API Service

API Service is a general purpose proving service that is fast and effective. It provides a set of APIs to manipulate trie structures and generate blockchain proofs for any digital assets. A trie is a dictionary of key-values that can be built incrementally, whose root hash at any given time can be also dervied efficiently. Once the root hash is proven to a blockchain, every key-value is also proven, so as the digital asset stored in that key-value

Protobuf definition: api/api.proto

Table of Contents

APIService

Method NameRequest TypeResponse TypeDescription
GetTriesgoogle.protobuf.EmptyTrie streamGetTries gets all tries. Admin privilege is required
GetTrieTrieRequestTrieGetTrie gets a trie
ImportTrieDataChunk streamTrieImportTrie creates a new trie from existing trie data. If the trie ID is not provided in the metadata, a new one will be generated
ExportTrieTrieRequestDataChunk streamExportTrie exports a trie's data
CreateTriegoogle.protobuf.EmptyTrieCreateTrie creates an empty trie
DeleteTrieTrieRequestTrieDeleteTrie deletes a trie. This destroys everything of a trie
GetTrieKeyValuesTrieKeyValuesRequestKeyValue streamGetTrieKeyValues gets key-values of a trie. The returned KeyValues are ordered by the keys lexicographically
GetTrieKeyValueTrieKeyValueRequestKeyValueGetTrieKeyValue gets a key-value of a trie
SetTrieKeyValuesKeyValue streamTrieSetTrieKeyValues sets key-values of a trie. Set an empty value for a key to remove that key. Modifications to a trie will change its root hash
GetTrieRootsTrieRootsRequestTrieRoot streamGetTrieRoots gets roots of a trie. This is a series of roots showing the modification history of a trie
SetTrieRootSetTrieRootRequestTrieSetTrieRoot sets the root of a trie to the given one. This will add an entry in the root history
GetTrieProofsTrieProofsRequestTrieProof streamGetTrieProofs gets proofs of a trie
GetTrieProofTrieProofRequestTrieProofGetTrieProof gets a proof of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned
SubscribeTrieProofTrieProofRequestTrieProof streamSubscribeTrieProof subscribes to proof changes of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned
CreateTrieProofCreateTrieProofRequestTrieProofCreateTrieProof creates a proof for a trie root
DeleteTrieProofDeleteTrieProofRequestTrieProofDeleteTrieProof deletes a proof for a trie root
VerifyTrieProofVerifyTrieProofRequestVerifyProofReplyChunk streamVerifyTrieProof verifies a proof for a trie root
CreateKeyValuesProofCreateKeyValuesProofRequestDataChunk streamCreateKeyValuesProof creates a proof for the provided key-values out of a trie proof. The new proof is self-contained and can be verified independently
VerifyKeyValuesProofDataChunk streamVerifyProofReplyChunk streamVerifyKeyValuesProof verifies a key-values proof

CreateKeyValuesProofRequest

CreateKeyValuesProofRequest represents a create key-values proof request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
proof_idstringProofId is the trie proof id
requestCreateTrieProofRequestRequest is the request to create a new trie proof that is going to prove the key-values
filterKeyValuesFilterFilter is the key-values filter (optional). When zero, all key-values will be included in the proof

CreateTrieProofRequest

CreateTrieProofRequest represents a create trie proof request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
rootstringRoot is the root hash (optional). When zero, the current root hash of the trie will be used to create the TrieProof, and the request will be blocked until all ongoing updates are finished
anchor_typeanchor.Anchor.TypeAnchorType is the anchor type the trie proof should be submitted to. Default to ETH

DataChunk

DataChunk represents a chunk of data transmitted in a gRPC stream

FieldTypeLabelDescription
databytesData is the data within the DataChunk
trie_requestTrieRequestTrieRequest is the trie request
verify_key_values_proof_requestVerifyKeyValuesProofRequestVerifyKeyValuesProofRequest is the request to verify a key-values proof

DeleteTrieProofRequest

DeleteTrieProofRequest represents a delete trie proof request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
proof_idstringProofId is the trie proof ID

Key

Key represents a key of a key-value pair

FieldTypeLabelDescription
keybytesKey is the key of the key-value
key_sepuint32repeatedKeySep is the key separators for chained tries

KeyValue

KeyValue represents a key-value

FieldTypeLabelDescription
keybytesKey is the key of the key-value
key_sepuint32repeatedKeySep is the key separators for chained tries
valuebytesValue is the value of the key-value
trie_key_values_requestTrieKeyValuesRequestTrieKeyValuesRequest is the request to set or get key-values

KeyValuesFilter

KeyValuesFilter represents a key-value filter

FieldTypeLabelDescription
keysKeyrepeatedKeys are the keys of key-values that should be included in a key-value proof. Only those trie nodes are on the merkle paths of the given keys will be included in the proof

RootFilter

RootFilter represents a root filter to query a proof

FieldTypeLabelDescription
rootstringRoot is the root hash. When zero, the current root hash of the trie will be used to retrieve the TrieProof, and the request will be blocked until all ongoing updates are finished
not_beforegoogle.protobuf.TimestampNotBefore is the not before timestamp. When nil, this constraint is not used; when zero, the latest TrieProof for the root hash will be returned

SetTrieRootRequest

SetTrieRootRequest represents a set trie root request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
rootstringRoot is the root hash to set to

Trie

Trie represents a dictionary of key-values that can be built incrementally, whose root hash at any given time can be also dervied efficiently. Once the root hash is proven to a blockchain, every key-value is also proven

FieldTypeLabelDescription
idstringId is the trie ID
rootstringRoot is the root hash of the trie

TrieKeyValueRequest

TrieKeyValueRequest represents a trie key-value request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
rootstringRoot is the root hash (optional). When zero, the current root hash of the trie will be used to retrieve the TrieKeyValues, and the request will be blocked until all ongoing updates are finished
keyKeyKey is the key of the key-value

TrieKeyValuesRequest

TrieKeyValuesRequest represents a trie key-values request. The returned KeyValues are ordered by the keys lexicographically

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
rootstringRoot is the root hash (optional). When zero, the current root hash of the trie will be used to retrieve the TrieKeyValues, and the request will be blocked until all ongoing updates are finished

TrieProof

TrieProof represents a proof for a trie at a certain root, which can be viewed as a snapshot of all the key-values contained in the trie

FieldTypeLabelDescription
idstringId is the ID of the trie proof
trie_idstringTrieId is the trie ID
rootstringRoot is the root hash of the trie proven by this proof
created_atgoogle.protobuf.TimestampCreatedAt is the created at timestamp. The timestamp when the proof is created
statusanchor.Batch.StatusStatus is the anchor batch status of the trie proof
errorstringError is the error message when status is ERROR
anchor_typeanchor.Anchor.TypeAnchorType is the anchor type the trie proof has been submitted to
txn_idstringTxnId is the blockchain transaction ID
txn_uristringTxnUri is the explorer URI for the blockchain transaction
block_timeuint64BlockTime is the blockchain's block consensus timestamp in seconds
block_time_nanouint64BlockTimeNano is the Blockcahin's block consensus timestamp's nano part. For most traditional blockchains, this will be zero. For Hedera, this will be the nano part of the transaction's consensus timestamp
block_numberuint64BlockNumber is the blockchain's block number. For Hedera, this will be zero as there is no block concept and each transaction has its own consensus timestamp which defines the transaction order
proof_rootstringProofRoot is the root hash of the trie proof, which is the anchor batch's root hash the proof belongs to

TrieProofRequest

TrieProofRequest represents a trie proof request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
proof_idstringProofId is the trie proof ID
root_filterRootFilterRootFilter is the root filter. A nil filter equals a zero filter

TrieProofsRequest

TrieProofsRequest represents a trie proofs request. The returned TrieProofs are ordered by root lexicographically then by created at timestamp chronologically

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
root_filterRootFilterRootFilter is the root filter (optional). When nil, all TrieProofs will be returned

TrieRequest

TrieRequest represents a trie request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID

TrieRoot

TrieRoot represents a root of a trie. Each modification made to the trie will lead to a new trie root

FieldTypeLabelDescription
rootstringRoot is the root hash of the trie
created_atgoogle.protobuf.TimestampCreatedAt is the created at timestamp. The timestamp when the root is created

TrieRootsRequest

TrieRootsRequest represents a trie roots request. The returned TrieRoots are in chronological order

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
root_filterRootFilterRootFilter is the root filter (optional). When nil, all TrieRoots will be returned

VerifyKeyValuesProofRequest

VerifyKeyValuesProofRequest represents a verify key-values proof request

FieldTypeLabelDescription
output_key_valuesboolOutputKeyValues indicates whether to output key-values contained in the trie
output_dot_graphboolOutputDotGraph indicates whether to output a Graphviz dot graph to visualize the trie

VerifyProofReply

VerifyProofReply represents a verify proof reply

FieldTypeLabelDescription
verifiedboolVerified indicates whether the proof is verified
errorstringError is the error message when the proof is falsified

VerifyProofReplyChunk

VerifyProofReplyChunk represents a chunk of data in the verify proof reply stream

FieldTypeLabelDescription
key_valueKeyValueKeyValue is one of the key-values contained in the trie when the OutputKeyValues is true
dot_graph_chunkDataChunkDotGraphChunk is a chunk of the Graphviz dot graph for the trie when the OutputDotGraph is true
replyVerifyProofReplyVerifyProofReply is the verify proof reply, which should be the data in the last VerifyProofReplyChunk

VerifyTrieProofRequest

VerifyTrieProofRequest represents a verify trie proof request

FieldTypeLabelDescription
trie_idstringTrieId is the trie ID
proof_idstringProofId is the trie proof ID
output_key_valuesboolOutputKeyValues indicates whether to output key-values contained in the trie
output_dot_graphboolOutputDotGraph indicates whether to output a Graphviz dot graph to visualize the trie

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)