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.

Important

The following ContractService methods can be used as both contract and public methods:

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.

Important

The following ContractService methods can be used as both contract and public methods:

  • GetContractKeys,

  • GetContractKey,

  • GetContractBalances,

  • CalculateAssetId.

Connect

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

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.

Important

The GetContractKeys method of the ContractService can be used as both a contract method and a public method.

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.

Important

The GetContractKey method of the ContractService can be used as both a contract method and a public method.

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).

Important

The GetContractBalances method of the ContractService can be used as both a contract method and a public method.

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.

Important

The CalculateAssetId method of the ContractService can be used as both a contract method and a public method.

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.

See also