2 Server APIs

Communication between SDK Client and server done over gRPC service, using two sides TLS encryption.

Server expose 2 sets of APIs to SDK

• Query service - service Query {...} in following listing
• Transaction submit service - service Transaction {...}

Query service provied several types of queries for different purposes.

• For transaction execution Get().
• For provenance and data integrity, methods to get historical data - GetHistory() and methods to check data integrity - GetProof() and GetMerkleRoot() provided.
  • To understand how proofs generated and validated, see Transaction Poofs
• Ledger data access GetTx() and GetBlock().
• DB users query GetUsers().

All query method messages start with message QueryHeader{}, that contains user, dbname and query signature.

Transaction method only expose SubmitTransaction() method.

• There is no more specific methods for user management, they are part of transaction RWSets, see Client SDK APIs, TxContext section.

service Query {
    // Executed by 
    rpc Get(DataQuery) returns (Value)
    rpc GetHistory(HistoryQuery) returns (stream HistoryDataSet)
    rpc GetProof(ProofQuery) returns (Proof)
    rpc GetMerkleRoot(MerkleRootQuery) returns (Digest)
    rpc GetTx(TxQuery) returns (Envelope)
    rpc GetBlock(BlockQuery) returns (Block)
    rpc GetUsers(UserQuery) returns(UserSet)
    rpc GetBlockHeight() returns(BlockNumber)
}

service Transaction {
    rpc SubmitTransaction(stream Envelope) returns (stream Response)
}

message QueryHeader {
    User   user      = 1,
    bytes  signature = 2,
    string dbName    = 3,
}

message DataQuery {
    QueryHeader header = 1,
    string key         = 2,
}

message Value {
    bytes   value   = 1,
    Version version = 2,
}

message Version {
    uint64 block_num = 1,
    uint64 tx_num    = 2,
}

message HistoryQuery {
    QueryHeader header   = 1,
    string    key        = 2,
    Timestamp start_time = 3,
    Timestamp end_time   = 4,
    string    user_id    = 5,
    uint64    page_size  = 6,
}

message HistoryDataSet{
    repeated HistoricalData historydata = 2;
}

message HistoricalData {
    // DB key
    string key = 1,
    // Historical value
    bytes value = 2,
    // Client time for client who submitted transaction
    Timestamp txTime = 3,
    // Sequencer time when block was created
    Timestamp blocktime = 4,
    // Transaction that did the change
    bytes txId = 5,
    // Block number that holds changing tx
    uint64 blocknumber = 6,
    // Client who submitted changing tx
    bytes clientId = 7,
    // Is this tx deleted this key
    bool isDelete = 8
}

message MerkleRootQuery {
    QueryHeader header = 1,
}

message ProofQuery {
    QueryHeader header = 1,
    string txID        = 2,
}

message Proof {
    // Path to tx inside blocks merkle tree
    repeated bytes blockpath = 1,
    // Path to block inside dynamic ledger merkle tree
    repeated bytes ledgerpath = 2,
    // Transaction signatures
    repeated bytes txsignatures = 3,
    // Block signatures
    repeated bytes blocksignatures = 4
}

message Digest {
    // Ledger merkle tree root
    bytes root_hash = 1,
    // Ledger height
    uint64 height = 2
}

message TxQuery {
    QueryHeader header = 1,
    string txID        = 2,
}

message BlockQuery {
    QueryHeader header  = 1,
    uint64 block_number = 2,
}

message Block {
    BlockHeader header = 1,
    repeated Envelope envelopes = 2,
    TxMerkleTree tx_merkle_tree = 3
}

message Envelope {
}

message Response {
}

message UserQuery {
    QueryHeader header = 1,
    repeated string user_ids = 2,
    string role = 3,
}

message User {
    bytes userID = 1,
    bytes user_cetificate = 2,
    repeated string roles = 3
}

message UserSet {
    repeated User users = 1
}

Tx Response API

Each client SDK can register to tx responses for each transaction on multiple server nodes, not only on node SubmitTransaction() invoked. This API can be used to request responses for old transactions async, in parallel to GetTx() sync method.

message Response {
    bytes txid = 1,
    bool status = 2,
    bytes signature = 3
}
service TxResponse {
    rpc GetTxResponse(TxQuery) returns (stream Response)
}