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 to 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
1.4	1.7.0

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 participants’ addresses from the node keystore and data stored in addresses.

``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 data stored at the address.

``GetAssetBalance`` – method for obtaining the current asset balance for a definite smart contract 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_contract_service.proto¶

A set of methods for work with smart contracts.

``Connect`` – method for connecting a smart contract to a node. The method query should contain the following parameters:

connection_id – the connection identifier of the smart contract (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).

``CommitExecutionSuccess`` – the method for obtaining the result of successful execution of a smart contract by its ID and transferring the result to the node.

``CommitExecutionError`` – the method to retrieve an error that occurred as a result of execution of a smart contract by its ID and transfer this error to a node.

``GetContractKeys`` – the method for obtaining the results of execution of a smart contract by its ID. The method query contains the following data:

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 response returns the Entries array containing the results of a smart contract operation.

``GetContractKey`` – the method for obtaining a definite result of a smart contract execution by its key. 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 a list of all the 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 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 for obtaining all the 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 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¶

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 designed to get information about groups for sharing confidential data and working 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 to obtain addresses of owners of a confidential data group by its 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 confidential data package by 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 metadata for a confidential data package by 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 – confidential data type (file);
info – file data array:
- filename – name of a file;
- size – file size;
- timestamp – the file placement Unix Timestamp (in milliseconds);
- author – file author;
- comment – optional comment to the file;
hash – confidential data identifying hash.

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 – the system time of the node PC;
ntp – network time.