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

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 Router to receive a receipt for an operation that was requested in regards for one of the Router’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 Router 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;
}

FinP2P

Asset Service

Asset Transfer Message

Response Message

Escrow Cancellation

Request Message

Response Message

Provide Transaction Signature

Request Message

Response Message

Accept Receipt

Request Message

Response Message

Stream Message (`OperationsResults`)

Balance

Request message

Response Message

GetReceipt

Request message

Response Message

Related content

Asset Service

Asset Transfer Message

Response Message

Escrow Cancellation

Request Message

Response Message

Provide Transaction Signature

Request Message

Response Message

Accept Receipt

Request Message

Response Message

Stream Message (OperationsResults)

Balance

Request message

Response Message

GetReceipt

Request message

Response Message

Related content

Stream Message (`OperationsResults`)