Asset Service

The Asset Service is defines an asset transaction service and a balance request.

 

Transfer transactions are delivered P2P and queries, like Balance, are Broadcasted to the Routers 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 Router 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 Router 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 Router to receive a receipt for an operation that was requested in regards for one of the Router’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 Router 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.

Â