Technical description of the platform

gRPC services used by Docker smart contracts¶

The contract gRPC services described in this section are designed to exchange data between a Docker smart contract and a node. These services are only available to Docker smart contracts. An external user cannot call the contract services and use their functions.

General instructions on gRPC usage for Docker smart contracts development are provided in the Example of a Docker smart contract with gRPC article.

Versions of Docker smart contract API¶

gRPC methods (including the methods used by Docker smart contracts) constitute API defined by protobuf files.

To clearly define new methods and make changes to existing ones, API versioning is provided. Thanks to the version number assigned, a node determines the appropriate set of methods to use when executing a Docker smart contract.

The current version of the gRPC API for the blockchain platform version is contained in the api_version.proto file. Docker smart contracts that require an API version higher than that of the mining node are ignored during mining.

To create and update Docker smart contracts, 103 CreateContract Transaction and 107 UpdateContract Transaction (version 4 and higher) provide apiVersion field. This field specifies the API version used by the Docker smart contract for the mining node.

The table below provides API versions corresponding with the versions of the blockchain platform:

API version	Platform version
1.0	1.6.0 and 1.6.1
1.1	1.6.2
1.4	1.7.0
1.6	1.11.0
1.7	1.12.0
1.8	1.12.1
1.9	1.12.2
1.10	1.12.3 and 1.13.0

Protobuf files of the methods¶

Docker smart contracts that use gRPC to exchange data with a node can use the services listed in the protobuf files with names starting with contract:

protobuf	Methods
contract_address_service.proto	GetAddresses GetAddressData GetAssetBalance
contract_block_service.proto	GetBlockHeader
contract_contract_service.proto	Connect CommitExecutionSuccess CommitExecutionError GetContractKeys GetContractKey GetContractBalances CalculateAssetId
contract_permission_service.proto	GetPermissions GetPermissionsForAddresses
contract_privacy_service.proto	GetPolicyRecipients GetPolicyOwners GetPolicyHashes
contract_transaction_service.proto	TransactionExists TransactionInfo
contract_util_service.proto	GetNodeTime

contract_address_service.proto¶

The AddressService methods are designed to retrieve participants’ addresses from the node keystore and to retrieve the data stored at the address.

GetAddresses – the method for obtaining all the addresses of participants, whose key pairs are stored in the node keystore. The method returns the addresses string array.

GetAddressData – the method for obtaining all the data stored at a definite address with the use of the transaction 12. The method query contains the following parameters:

address – the address containing the data to be obtained;
limit – the limit of number of data blocks to be obtained;
offset – number of data blocks to be missed in the method response.

The method returns the DataEntry array containing the address data.

GetAssetBalance – the method for obtaining the current asset balance for a definite user. The method request includes the following parameters:

address – the address the balance of which is to be displayed;
assetId – asset identifier. This parameter is left blank for WEST.

contract_block_service.proto¶

The BlockService methods enable contracts to request information about a block from a node.

GetBlockHeader – method to get the block header by its signature (block ID) or by its height.

One of the following parameters is entered in the method request:

signature – the signature of the requested block as a Base58-encoded string;
key – height of the requested block.

The method returns the following information about the block header:

version — block version;
height – block height;
block_signature — block signature (identifier) as a Base58-encoded string;
reference — the signature of the previous block, to which the current block is referring, as a Base58-encoded string;
miner_address — miner address, as a Base58-encoded string;
tx_count — the number of transactions in the block;
timestamp — block time.

If the block is not found, the method returns the BlockDoesNotExist error.

contract_contract_service.proto¶

The ContractService methods are designed to work with Docker smart contracts. These are service methods for contract execution, as well as methods for reading smart contract state information and for actions with assets.

Connect¶

Connect – the method for connecting a smart contract to a node.

The method query should contain the following parameters:

connection_id – the identifier of the Docker smart contract connection (see Authorization of smart contracts with gRPC);

async_factor – the maximum number of simultaneously processed transactions of the smart contract (see Parallel operation of smart contracts).

The method returns the following information about the transaction and the block:

transaction — contract call transaction;

auth_token — authorization token;

current_block_info — information on the current block:

height – current height;

timestamp — block time;

miner_address — miner address, as a Base58-encoded string;

reference — the signature (identifier) of the previous block, to which the current block is referring, as a Base58-encoded string.

CommitExecutionSuccess¶

CommitExecutionSuccess – the method for transferring the result of a Docker smart contract successful execution to the node. With this method a smart contract can send a sequence of operations on assets.

The following data is passed in the method request:

tx_id — the identifier of the contract call transaction to which the smart contract sends the result;

results — an array of key-value values that the smart contract will write to its state as the execution result. If a key is returned that is already present in the state, its value is overwritten;

asset_operations — an array of actions a smart contract performs on assets available to it, including issuing new asset, reissuing an asset, burning an asset or transferring an asset available to the contract to another user (issue, reissue, burn, transfer).

The method response is not provided.

CommitExecutionError¶

CommitExecutionError – the method for sending a smart contract execution error to the node.

GetContractKeys¶

GetContractKeys – the method for requesting values from the smart contract state by the key filter.

The following data is passed in the method request:

contract_id – smart contract identifier;

limit – the limit of number of data blocks to be obtained;

offset – number of data blocks to be missed in the method response;

matches – an optional parameter for a regular expression for keys sorting.

The method returns a DataEntry array containing the requested keys with values from the current Docker smart contract state.

GetContractKey¶

GetContractKey – the method to get the value of a certain key from the Docker smart contract state.

The following data is passed in the method request:

contract_id – Docker smart contract identifier;

key – the required key.

The method returns DataEntry which matches the passed key from the Docker smart contract current state.

GetContractBalances¶

GetContractBalances – the method for obtaining the Docker smart contract balance(s) (in system token or other tokens).

The list of asset identifiers is passed in the request (assets_ids); to get the balance of the WEST system token, an empty string should be passed in the list.

The method response displays the list of the balances for each of the requested assets.

CalculateAssetId¶

CalculateAssetId – the method to calculate assetId when a new token is issued by a smart contract based on the passed parameter:

nonce — a one-time code that can only be used once; also, several assets with the same nonce cannot be released within the same contract call.

contract_permission_service.proto¶

The PermissionService methods are designed to retrieve information about participants` roles (permissions).

GetPermissions – the method returns a list of all the permissions of the participant whose address was specified, valid at the moment specified. The method query should contain the following parameters:

address – the participant’s address;
timestamp – the Unix Timestamp (in milliseconds) for the moment of time when the active permissions were requested.

The response of the method returns the roles array containing permissions for the required address and the entered timestamp.

GetPermissionsForAddresses – the method returns a list of all the permissions of multiple participants whose addresses were specified, valid at the moment specified.

The following data is passed in the method request:

addresses – a string array containing required addresses;
timestamp – the Unix Timestamp (in milliseconds) for the moment of time when the active permissions were requested.

The method response returns an address_to_roles array containing permissions for each required address, as well as the entered timestamp.

contract_pki_service.proto¶

contract_privacy_service.proto¶

The PrivacyService methods are designed to obtain information about confidential data access groups and to work with confidential data.

Learn more about confidential data exchange and access groups in the article Confidential data exchange.

GetPolicyRecipients – the method for obtaining addresses of the confidential data group participants by the group policy_id. The method response returns a recipients string array which contains addresses of confidential data group participants.

GetPolicyOwners – the method for obtaining the addresses of the owners of a confidential data access group; the group identifier is passed in the method request as policy_id. The method returns the owners string array in the response, which contains addresses of confidential data access group owners.

GetPolicyHashes – the method for obtaining confidential data hashes from a confidential data access group; the group identifier is passed in the method request as policy_id. The method response outputs an array of hashes strings containing hashes from the access group.

contract_transaction_service.proto¶

The TransactionService methods are designed to retrieve information about transactions that have been sent to the blockchain.

Similar gRPC methods available to an external user are described in the gRPC: handling transactions section.

Unlike the TransactionExists and TransactionInfo methods available for external integration, contract methods return information not only about the transactions that have already been written to the block, but also about the transactions that are just getting ready to be packed into the block.

TransactionExists – the method for verifying if the transaction with the specified ID exists. The method returns true if a transaction with the specified ID exists, or false if it does not.

TransactionInfo – the method for obtaining the data on the transaction with the specified identifier: transaction name, transaction version, the blockchain height on which this transaction was made, other data about the transaction, depending on the type of this transaction.

contract_util_service.proto¶

The GetNodeTime method of the UtilService is designed to get the current node time.

The method returns the current node time in two formats:

system – the system time of the node PC;
ntp – network time.