Technical description of the platform
Smart contracts¶
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 smart contract has its own balance, which can hold WEST system tokens as well as other tokens. For more details about managing tokens from a smart contract see below.
Each network participant can create and call 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.
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:
issue tokens,
reissue 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 of a 103 transaction, the node downloads the image of a smart contract stated in the image
field. After that, the downloaded image is checked and started in the Docker container.
Call of a smart contract and saving of results of its operation¶
A smart contract is called for operation by a network participant with the use of the 104 CallContract Transaction. This transaction transfers the ID of the Docker container of the smart contract, as well as its input and output parameters in ‘key-value’ pairs. The container starts if it has not been started before.
Results of a smart contract operation are stored in its state with the use of the 105 ExecutedContract Transaction.
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.
Hint
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 version 4 103 and 107 transactions are used to create and update smart contracts.
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.
Warning
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:
non-executable transactions – atomic containers and all the classic transactions: transfer transaction, data transaction, etc.;
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.
Note
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 and REST 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.
Note
As of version 1.12, support for REST-based smart contracts is discontinued after the 1120 feature activation.
Learn more: