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.
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 smartcontract and the blockchain platform itself, smart contracts start and work in Docker containers.
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.
A smart contract has an access to the node state for data exchange via gRPC and REST API interfaces.
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 with the Waves Enterprise technical support service. After approval of your request, your smart contract will be uploaded into the registry, you will be able to call the smart contract with the use of the platform client or 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 general chart of smart contract operation is provided below:
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 work in the Waves Enterprise Mainnet, it already has the pre-set parameters for installing of smart contracts 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.
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 permiossion;
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. This option is supported only by smart contracts that use the gRPC interface for data exchange.
Concept of parallel operation of smart contracts:
A smart contract developer enables the
async-factorparameter in the code of his smart contract. This parameter defines the maximum allowed number of simultaneous transactions within one smart contract.
Upon start, the smart contract transfers the
async-factorvalue to the node.
When operation of smart contracts begins, transactions for call of smart contracts are transferred from the UTX pool into the buffer for unprocessed smart contract transactions up to its filling.
Transaction in the buffer are divided into groups depending on smart contract IDs. Only one group of transactions can operate simultaneously, maximum number of transaction corresponds with the
When a next smart contract starts its operation, one cell in the transaction buffer becomes free. In the same time, a cell is blocked in case of transfer of transactions from the UTX pool. That means, operations of the buffer filling and processing of contract calls are performed simulteneously, that allows to avoid time gaps while transferring new transactions.
The value of the
async-factor parameter can be set in advance in the interval from 1 to 999, as well as to be calculated dynamically. You can set a fixed value of this parameter as a constant, but it is recommended to set a calculable value. For instance, a contract can request a number of free processor cores and pass this value as
async-factor. This number will be used for parallel processing of transactions with a definite smart contract.
async-factor parameter is not defined, all transactions with a smart contract will be processed in a consecutive way.
Parallel operation of smart contracts is illustrated with the chart below:
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¶
In order to exchange data with smart contracts and nodes, the platforn provides the gRPC and REST API methods. Usage of these methods allows to perform a wide range of operations with the blockchain.