Technical description of the platform
Smart contract is a separate application which saves its entry data in the blockchain, as well as the output results of its algorithm. The Waves Enterprise blockchain platform supports development and usage of Turing complete smart contracts for creation of high-level business applications.
When a smart contract starts in a blockchain network, nobody can change, spoof it or restrict its operation without interference with the entire network. This aspect allows to provide security of business applications.
Smart contracts can be developed in any programming language and do not have any restrictions for their internal logic. In order to split startup and performance of a smart contract and the blockchain platform itself, smart contracts start and work in Docker containers.
Smart contracts use gRPC API interface to access the node state for data exchange.
Each network participant can create and call smart contracts. If you need to restrict access to a smart contract, create a confidential smart contract. Only the nodes you list when creating the contract will be able to call it and receive its result. You will be able to modify this list of nodes in the future. Learn more about confidential smart contracts:
A developed smart contract is packed in a Docker image which is stored in the open Waves Enterprise registry. This repository is based on the Docker Registry technology, every smart contract developer has an access to it. In order to upload your smart contract into the registry, contact the Waves Enterprise technical support service. After the approval of your request, your smart contract will be uploaded into the registry, and you will be able to call the smart contract in the platform Client or using a REST API query to your node.
If you are going to use smart contracts in your own private blockchain network, you have to create your own registry for smart contract uploading and calling.
The node implements MVCC (Multiversion concurrency control) mechanism – control of concurrent access to smart contracts state through multiversion. This allows the node to execute multiple transactions of any smart contracts in parallel. Data consistency is guaranteed.
Smart contract operation chart¶
The general chart of smart contract operation is provided below:
Handling tokens from a smart contract¶
As of version 1.12, after the 1120 feature activation, Waves Enterprise blockchain platform smart contracts have their own balance, which can store WEST system tokens as well as other tokens. For the smart contracts created on the previous versions, the balance of the WEST system tokens is set to zero.
Also, smart contracts can now perform basic operations with tokens:
burn the tokens on the smart contract balance,
transfer tokens from the smart contract balance to a user’s (users’) balance by the user’s (users’) address.
These functions are implemented by the CommitExecutionSuccess gRPC API method.
With this functionality, smart contracts can change the states of assets and users (their balances). Users can also send tokens to a smart contract balance.
Development and installation of smart contracts¶
Practical instructions on development of smart contracts, as well as an example of a smart contract in Python are listed in the article Development and usage of smart contracts.
A participant developing smart contracts should have the contract_developer permission in the network. This permission allows a participant to upload and call smart contracts, as well as to restrict operation of his own smart contracts and change their code.
Development of a smart contract starts with preparation of a Docker image which contains a ready smart contract code, its Dockerfile and, in case of usage of a smart contract with the gRPC interface for data exchange with the node, all required protobuf files.
The prepared image is built with the use of the build utility of the Docker package, and after this is upload into the registry.
In order to install and work with smart contracts, you have to set up the
docker-engine section of the node configuration file. If your node works in the Waves Enterprise Mainnet, it already has the pre-set parameters for smart contracts installation from the open repository, as well as the recommended parameters for optimal operation of smart contracts.
Installation of smart contracts in the blockchain is performed with the use of the 103 CreateContract Transaction. This transaction should contain a link to the image of the smart contract in the registry. It is recommended to send the last versions of transactions while working with smart contracts.
In private networks, the 103 transaction allows to install Docker images of smart contracts not only from repositories stated in the
docker-engine section of the node configuration file. If you need to install a smart contract from a registry not included in the list of the configuration file, type the full address of a smart contract in the registry you have created in the
name field of the 103 transaction. An example of 103 transaction fields is provided in its description.
Upon receiving the 103 transaction, the node downloads the smart contract image specified in the
image field. After that, the downloaded image is verified by the node and started in the Docker container.
Calling a smart contract and saving the results of its operation¶
A smart contract is called for operation by a network participant using the 104 CallContract Transaction.
This transaction transfers the smart contract Docker container id, as well as its input and output parameters in the form of key-value pairs.
The container is started if it has not been started before.
The smart contract is executed and sends the result via the gRPC API interface to the node that initiated the start of the smart contract. The node, in turn, generates a 105 ExecutedContract Transaction with the result of the smart-contract execution. This way the result of the smart contract execution is fixed in its state using the 105 ExecutedContract transaction.
Validator nodes verify that everyone who executed that smart contract with that data got the same result. If the verification is successful, the miner node places the transactions into the block, and the result of the smart contract execution goes into the blockchain.
Restriction of smart contract calls¶
In order to disable calls of a definite smart contract in the blockchain, send the 106 DisableContract Transaction with the ID of the smart contract Docker container. This transaction can be sent only by the developer of this smart contract with the non-expired contract_developer permission.
When disabled, a smart contract becomes unavailable for further calls. The data of disabled smart contracts is stored in the blockchain and can be obtained with the use of gRPC and REST API methods.
Updating of smart contracts¶
If you have changed the code of your smart contract, update it. To do this, upload your smart contract into the Waves Enterprise registry by sending a request for updating of your smart contract to the Waves Enterprise technical support service.
Then send the 107 UpdateContract Transaction to your node. The contract to be updated should not be disabled with a 106 transaction.
After updating of the smart contract, mining nodes of the blockchain download it and check correctness of its operation. After that, information about update of the smart contract is included into its state with the use of the 105 transaction containing data of the corresponding 107 transaction.
A certain smart contract can be updated only by a participant who has sent a 103 transaction for this smart contract and has the contract_developer permission.
Validation of smart contracts¶
The WE blockchain platform supports three smart contract validation policies to provide its additional integrity control. This opportunity is available under following conditions:
The 162 soft fork is activated in the network;
The network includes one or more participants with the contract_validator permission;
The validation policy is configured with the use of the
validationPolicy.type field of corresponding transaction.
Available validation policies:
any- the general validation policy is kept in the network: to mine the updated smart contract, the miner signs the corresponding 105 transaction. Also, this parameter is set if there are no registered validators in the network.
majority- a transaction is considered valid if it is confirmed by the majority of validators: 2/3 of the total number of registered addresses with the contract_validator permission.
majorityWithOneOf(List[Address])- the transaction is considered valid if the majority of validators is collected, among which there is at least one of the addresses included in the parameter list. The addresses included in the list must have a valid contract_validator permission.
If the validation policy
majorityWithOneOf(List[Address]) is selected, the address list must contain at least one address; passing an empty list is not allowed.
Parallel operation of smart contracts¶
The Waves Enterprise platform allows to run multiple smart contracts simultaneously. For this purpose, the node implements the MVCC (Multiversion concurrency control) mechanism – parallel access control through multiversion. The mechanism allows multiple transactions of containerized smart contracts to run in parallel and maintain data consistency.
All transactions are divided into two groups:
executable transactions – transactions of all containerized smart contracts.
Transactions of the first group are always executed sequentially (the level of parallelism is 1). For the second group of transactions, the execution parallelism is determined by the value of the
node.docker-engine.contracts-parallelism parameter in the node configuration:
node.docker-engine.contracts-parallelism = 8
The default value is
8. In this way, all smart contracts are executed in parallel, independently of the Docker image.
There is competition between the two groups of transactions: if heterogeneous transactions accumulate in the UTX pool, concurrency may decrease. This behavior can be smoothed by increasing the pulling buffer size, but it cannot be completely eliminated.
The code logic of a smart contract, as well as its programming language, should take into account the peculiarities of parallel operation of smart contracts. For instance, if a smart contract containing a function of increment of a variable upon every smart contract call transaction operates simultaneously, its result will be incorrect, because a common authorization key is used for each smart contract call.
API methods available for smart contracts¶
The platform provides the gRPC API methods to exchange data between a smart contract and a node. Use these methods to perform a wide range of operations with the blockchain.