Technical description of the platform

gRPC services used by smart contracts¶

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

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

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:

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	GetPolicyRecipientss GetPolicyOwners
contract_transaction_service.proto	TransactionExists TransactionInfo
contract_util_service.proto	GetNodeTime

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 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¶

A set of methods that allow contracts to query a node for information about a block.

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¶

A set of methods designed to work with smart contracts: service methods for contract execution as well as methods for reading smart contract status information and for actions with assets.

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 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 – the method for transferring the result of successful execution of a smart contract 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 – the method for sending a smart contract execution error to the node.

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 smart contract state.

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

The following data is passed in the method request:

contract_id – smart contract identifier;

key – the required key.

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

GetContractBalances – the method for obtaining the smart contract balance(s) (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 – the method to calculate assetId when a new token is issued by a smart contract based on the passed parameter:

nonce — a one-time byte type code that is not equal to 0; the range of acceptable values is from -128 to 127. Also, several assets with the same nonce cannot be released within the same contract call.

contract_permission_service.proto¶

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

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 method query should contain the following parameters:

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¶

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 the addresses of owners of a confidential data group by its policy_id. The method returns the owners string array in the response, which contains addresses of confidential data group owners.

contract_transaction_service.proto¶

A set of methods for obtaining 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 article.

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¶

This protobuf file contains the GetNodeTime method, which is used for obtaining 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.