Asset Service
The Asset Service defines an asset transaction service and a balance request.
Transfer transactions are delivered P2P and queries, like Balance, are Broadcasted to the nodes of a cluster.
service AssetService {
// asynchronous transfer operation, server should replay with Acknowledgement message that contains a correlation id of the request,
// results of the operation will be provided on the OperationResults stream
// the operation is expected to be idempotent based on the sha3 256 hash of the message.
// in case of multiple execution from the client, the server should respond with Acknowledgement (with same correlation id) in case the operation has not yet completed
// in case the operation completed, the server should respond with the operation result.
rpc Transfer (SignedTransferRequest) returns (SignedTransferResponse) {
}
rpc EscrowCancellation(SignedEscrowCancellationRequest) returns (SignedEscrowCancellationResponse) {
}
rpc AcceptReceipt (SignedAcceptReceiptRequest) returns (SignedAcceptReceiptResponse) {
}
// provide user signature for proposed transfer operation, server should respond with Acknowledgement message containing
// correlation id for the expected operation result on the OperationResults stream.
rpc ProvideTransactionSignature (SignedProvideSignatureRequest) returns (SignedProvideSignatureResponse) {
}
// bi-directional stream to provide results for asynchronous operations (e.g. Transfer, ProvideTransactionSignature)
// messages will contain the relevant request correlation id.
rpc OperationsResults (stream SignedStreamMessage) returns (stream SignedStreamMessage) {
}
rpc Balance (SignedBalanceRequest) returns (SignedBalanceResponse) {
}
rpc GetReceipt (SignedGetReceiptRequest) returns (SignedGetReceiptResponse) {
}
}Asset Transfer Message
The Transfer message defines the transfer transaction and includes the senders signature. In order to sign a message that can be verified by the destination Ledger, an Asset Transaction Signature Template (ATST)is defined for each Asset. This template defines the cryptographic algorithms and the structure of the message to sign. The ATST is defined per Asset and is included when retrieving asset’s resource information.
message SignedTransferRequest {
TransferRequest request = 1;
common.Signature signature = 2;
}
message TransferRequest {
common.Envelope envelope = 1;
enum Operation {
UNKNOWN = 0;
ISSUE = 1;
TRANSFER = 2;
REDEEM = 3;
}
Operation operation = 2;
TransferRequestPayload payload = 3;
oneof settlement {
EscrowPayload escrow = 10;
}
}
message Investor {
common.ResourceID resource = 1;
}
message AssetOrder {
Term term = 1;
Instruction instruction = 2;
}
message Term {
accounts.Asset asset = 1;
uint64 amount = 2;
}
message Instruction {
accounts.Account sourceAccount = 1;
accounts.Account destinationAccount = 2;
}
message TransferRequestPayload {
bytes nonce = 1;
Investor buyer = 2;
Investor seller = 3;
AssetOrder asset = 4;
AssetOrder settlement = 5;
TransactionData data = 6;
signature.Signature signature = 7;
common.ResourceID intentId = 8;
}
message TransactionData {
bytes data = 1;
}
message EscrowPayload {
uint32 expiry = 1; // time boundary for the escrow to hold the funds for the transaction
}
message SignedEscrowPayload {
EscrowPayload payload = 1;
common.Signature signature = 2;
}
Response Message
An asset transaction may have multiple messages. We will define a set of messages that can be received from the Primary Node running the transaction
message SignedTransferResponse {
TransferResponse response = 1;
common.Signature signature = 2;
}
message TransferResponse {
common.Envelope envelope = 1;
common.Status status = 2;
TransferResponsePayload payload = 3;
}
message TransferResponsePayload {
oneof payload {
Acknowledgement ack = 10;
TransferOperationResults transferResponse = 11;
}
}
message Acknowledgement {
string cid = 1; // correlation id for the response stream
}
message TransferOperationResults {
bytes nonce = 1;
string txid = 2; // the transaction id
uint32 code = 3; // represents the outcome of the Tx
string message = 4; // Printable status message
bytes chainpoint = 5; // If the Tx was succesful, this field holds the ChainPoint where the transaction was recorded
Receipt receipt = 6;
}
message Receipt {
string transactionId = 1;
string assetId = 2;
string recipientPublicKey = 3;
string sourcePublicKey = 4;
string quantity = 5;
string settlementRef = 6;
TransactionDetails transactionDetails = 7;
int64 timestamp = 8;
string intentId = 9;
}
message TransactionDetails {
message Inputs {
string transactionId = 1;
string quantity = 2;
uint32 index = 3;
}
message Outputs {
string quantity = 1;
string publicKey = 2;
uint32 index = 3;
}
repeated Inputs inputs = 1;
repeated Outputs outputs = 2;
}
Escrow Cancellation
Allows an Escrow service to notify a node of a transaction in escrow being cancelled.
Request Message
Response Message
Provide Transaction Signature
Provide user signature for proposed transfer operation, server should respond with Acknowledgement message containing correlation id for the expected operation result on the OperationResults stream.
Request Message
Response Message
Accept Receipt
Endpoint for a node to receive a receipt for an operation that was requested in regards for one of the node’s users.
Request Message
Response Message
Stream Message (OperationsResults)
bi-directional stream to provide results for asynchronous operations (e.g. Transfer, ProvideTransactionSignature) messages will contain the relevant request correlation id.
Balance
In the balance request is broadcast to the members of the cluster.
Request message
Response Message
The response payload includes the user’s account and asset from the request and adds the balance quantity.
GetReceipt
Provides a node with an ability to request a receipt for a specific transaction.
Request message
Response Message
The response payload includes the receipt with information regarding the specific transaction.