Technical description of the platform

gRPC services used by smart contracts¶

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

Versions of smart contract API¶

The gRPC methods used by smart contracts form the API defined by the 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 smart contract.

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

The apiVersion fields in the version 4 103 CreateContract Transaction and 107 UpdateContract Transaction transactions are provided for creating and updating smart contracts. These fields point the version of the API used by the 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 earlier
1.1	1.6.2

Protobuf files of the methods¶

Smart contracts that use the gRPC for data exchange with the node can use the services that are listed in the protobuf files with names starting with contract:

contract_address_service.proto¶

A set of methods for obtaining of participant addresses from the node keystore and data stored in addresses.

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

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

address - the address containing data to be obtained;
limit - a 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 data stored at the address.

``GetAssetBalance`` - method for obtaining a current asset balance for a definite smart contract user. The method request includes following parameters:

address - the address with the balance to be displayed;
assetId - asset identifier. This parameter is left blank for WEST.

contract_contract_service.proto¶

A set of methods for work with smart contracts.

``Connect`` - the method for connection of the smart contract to the node. The method query should contain following parameters:

connection_id - the connection identifier of the smart contract (see Authorization of smart contracts with gRPC);
async_factor - maximum number of simultaneously processed transaction of the smart contract (see Parallel operation of smart contracts).

``CommitExecutionSuccess`` - the method for obtaining of a result of a successful of a smart contract with a definite ID and transferring of this result to the node.

``CommitExecutionError`` - the method for obtaining of an error occured as a result of operation of a smart contract with a definite ID and transferring of this error to the node.

``GetContractKeys`` - the method for obtaining of results of operation of a smart contract with a definite ID. The method query contains the following data:

contract_id - smart contract identifier;
limit - a 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 sorting of keys.

The method response returns the Entries array containing the results of a smart contract operation.

``GetContractKey`` - the method for obtaining of a definite result of a smart contract operation according to the key of this result. The method query contains the following data:

contract_id - smart contract identifier;
key - the required key.

The method response returns the entry data array which contains the result of smart contract operation according to the required key.

contract_crypto_service.proto¶

A set of encryption and decryption methods. See details in the article gRPC: encryption and decryption methods.

contract_permission_service.proto¶

A set of methods for obtaining of information about permissions of participants.

``GetPermissions`` - the method for obtaining of a list of all address permissions valid at the moment of the query transfer. The method query contains the following data:

address - the required address;

timestamp - the Unix Timestamp (in milliseconds) for the required moment of time.

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

``GetPermissionsForAddresses`` - the method for obtaining of all permissions valid at the moment of the query transfer for multiple addresses. The method query contains the following data:

addresses - a string array containing required addresses;
timestamp - the Unix Timestamp (in milliseconds) for the required moment of time.

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

contract_pki_service.proto¶

A set of methods for generation and checking of electronic signatures. See details in the article gRPC: generation and checking of data electronic signatures (PKI).

contract_privacy_service.proto¶

A set of methods for obtaining of information about confidential data groups, as well as for work with confidential data.

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

``GetPolicyRecipients`` - the method for obtaining of addresses in a confidential data group with a definite policy_id. The method response returns a recipients string array which contains addresses of confidential data group participants.

``GetPolicyOwners`` - the method for obtaining of owners of a confidential data group with a definite policy_id. The response of the method returns the owners string array, which contains addresses of confidential data group owners.

``GetPolicyItemData`` - the method for obtaining of a confidential data package according to its identification hash. This method is available if the address of the method caller belongs to the confidential data group.

The method query contains a confidential group identifier policy_id and an identifying hash of required confidential data item_hash. The response of the method returns the data string containing a hash of a required confidential data package.

``GetPolicyItemInfo`` - the method for obtaining of information about a confidential data package according to its identification hash. This method is available if the address of the method caller belongs to the confidential data group.

The method query contains a confidential group identifier policy_id and an identifying hash of required confidential data item_hash. The method response returns the following data:

sender - an address of confidential data sender;
policy_id - a confidential data group identifier;
type - type of confidential data (file);
info - an array containing a file data: * filename - name of the file; * size - size of the file; * timestamp - a Unix Timestamp (in milliseconds) for uploading of the file to the network; * author - author of the file; * comment - an optional comment to the file;
hash - identifying hash of confidential data.

contract_transaction_service.proto¶

A set of methods for obtaining of information about transactions that have been sent to the blockchain. See details in the article gRPC: information about transaction according to their IDs.

contract_util_service.proto¶

This protobuf file contains the ``GetNodeTime`` method, which is used for obtaining of a node current time. The method returns the current node time in two formats:

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