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
message SignedEscrowCancellationRequest {
EscrowCancellationRequest request = 1;
common.Signature signature = 2;
}
message EscrowCancellationRequest {
common.Envelope envelope = 1;
EscrowCancellationPayload payload = 2;
}
message EscrowCancellationPayload {
string escrowid = 1;
enum Reason {
TIMEOUT = 0;
BUYER = 1;
SELLER = 2;
}
Reason reason = 2;
}
Response Message
message SignedEscrowCancellationResponse {
EscrowCancellationResponse response = 1;
common.Signature signature = 2;
}
message EscrowCancellationResponse {
common.Envelope envelope = 1;
common.Status status = 2;
}
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
message SignedProvideSignatureRequest {
ProvideSignatureRequest request = 1;
common.Signature signature = 2;
}
message ProvideSignatureRequest {
common.Envelope envelope = 1;
signature.SignatureTemplate template = 2;
common.ResourceID signer = 3; // User for whom the signature request is addressed to
common.ResourceID intentId = 4;
}
Response Message
message SignedProvideSignatureResponse {
ProvideSignatureResponse response = 1;
common.Signature signature = 2;
}
message ProvideSignatureResponse {
common.Envelope envelope = 1;
common.Status status = 2;
oneof payload {
Acknowledgement ack = 10;
ProvideSignatureResponsePayload signatureResponse = 11;
}
}
message ProvideSignatureResponsePayload {
bytes signature = 2;
}
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
message SignedAcceptReceiptRequest {
AcceptReceiptRequest request = 1;
common.Signature signature = 2;
}
message AcceptReceiptRequest {
common.Envelope envelope = 1;
Receipt receipt = 2;
}
Response Message
message SignedAcceptReceiptResponse {
AcceptReceiptResponse response = 1;
common.Signature signature = 2;
}
message AcceptReceiptResponse {
common.Envelope envelope = 1;
common.Status status = 2;
}
Stream Message (OperationsResults)
bi-directional stream to provide results for asynchronous operations (e.g. Transfer, ProvideTransactionSignature) messages will contain the relevant request correlation id.
message SignedStreamMessage {
StreamMessage message = 1;
common.Signature signature = 2;
}
message StreamMessage {
common.Envelope envelope = 1;
common.Status status = 2;
string cid = 3; // correlation id
oneof payload {
TransferResponsePayload transferResponse = 10;
ProvideSignatureResponsePayload signatureResponse = 11;
}
}
Balance
In the balance request is broadcast to the members of the cluster.
Request message
message SignedBalanceRequest {
BalanceRequest request = 1;
common.Signature signature = 2;
}
message BalanceRequest {
common.Envelope envelope = 1; // To fields is set to clusterID
BalanceRequestPayload payload = 2;
}
message BalanceRequestPayload {
common.FinID finid = 1; // owner of the account
common.ResourceID asset = 2;
}
Response Message
The response payload includes the user’s account and asset from the request and adds the balance quantity.
message SignedBalanceResponse {
BalanceResponse response = 1;
common.Signature signature = 2;
}
message BalanceResponse {
common.Envelope envelope = 1;
common.Status status = 2;
BalanceResponsePayload payload = 3;
}
message BalanceResponsePayload {
common.FinID finID = 1; // Account Owner
common.ResourceID asset = 2; // the requested asset
uint64 amount = 3; // Balance
}
GetReceipt
Provides a node with an ability to request a receipt for a specific transaction.
Request message
message SignedGetReceiptRequest {
GetReceiptRequest request = 1;
common.Signature signature = 2;
}
message GetReceiptRequest {
common.Envelope envelope = 1;
string transactionId = 2;
}
message SignedGetReceiptResponse {
GetReceiptResponse response = 1;
common.Signature signature = 2;
}
Response Message
The response payload includes the receipt with information regarding the specific transaction.
message GetReceiptResponse {
common.Envelope envelope = 1;
common.Status status = 2;
Receipt receipt = 3;
}