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_pki_service.proto

Verify

Some methods are only available in the corporate version of the platform and cannot be used in the opensource platform version:

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.

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

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.

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

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

  • 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 balance(s) (system token or other tokens) of a smart contract. The method query should contain the following parameters:

  • contract_id – smart contract identifier;

  • assets_ids – assets identifier.

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

CalculateAssetId – the method to calculate assetId by the passed parameter:

  • nonce — number that can only be used once.

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

The contract_pki_service.proto protobuf file describes the Verify contract method intended to verify the disconnected electronic signature for transmitted data in networks using GOST cryptography.

Important

The Verify method is not available when PKI is used, that is, when the node configuration file parameter node.crypto.pki.mode is set to ON. The method can be used in PKI test mode (node.crypto.pki.mode = TEST) or with PKI disabled (node.crypto.pki.mode = OFF).

Note

The Verify gRPC method cannot be used in the opensource version of the platform.

The field data types for the request and response are specified in the protobuf file.

The Verify method requires following parameters:

  • input_data – data signed by a DS (as an array of bytes in base64 encoding);

  • signature – the signature of the requested block as a Base58-encoded string;

  • sig_type – DS format. Supported values:

    • 1 – CAdES-BES;

    • 2 – CAdES-X Long Type 1;

    • 3 – CAdES-T.

  • extended_key_usage_list – the list of object identifiers (OIDs) of cryptographic algorithms that are used in DS generation; optional field.

Verify method response contains a status field with boolean data type:

  • true – the signature is valid,

  • false – the signature is compromised.

Verifying an advanced qualified digital signature

The Verify method provides the ability to verify an advanced qualified digital signature. To verify the AQDS correctly, install the root AQDS certificate of the certification authority (CA) on your node, which will be used to validate the signature.

Use the keytool utility to install the root certificate into the cacerts certificate storage of the Java virtual machine (JVM) you are using:

sudo keytool -import -alias certificate_alias -keystore path_to_your_JVM/lib/security/cacerts -file path_to_the_certificate/cert.cer

After the -alias flag, specify your preferred certificate name in the repository.

The cacerts certificate storage is located in the /lib/security/ subdirectory of your Java virtual machine. To find out the path to the virtual machine on Linux, use the following command:

readlink -f /usr/bin/java | sed "s:bin/java::"

Then add /lib/security/cacerts to the resulting path and paste the resulting absolute path to cacerts after the -keystore flag.

After the -file flag, specify the absolute or relative path to the received EDS certificate of the Certification Authority.

The default password for cacerts is changeit. If necessary, you can change it using the keytool utility:

sudo keytool -keystore cacerts -storepasswd

contract_privacy_service.proto

A set of methods designed to get information about groups for sharing confidential data and working with confidential data.

Important

The methods for obtaining information about groups for exchanging confidential data and working with confidential data are not available when using PKI, that is, when the node.crypto.pki.mode parameter parameter is set to ON. The methods can be used in PKI test mode (node.crypto.pki.mode = TEST) or when PKI is disabled (node.crypto.pki.mode = OFF).

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.