Technical description of the platform

Confidential smart contracts¶

In some business cases there is a requirement to restrict the use of a certain smart contract and make it available only to some nodes.

For example, an organization collaborates with multiple counterparties. The business logic of this cooperation is implemented as transactions within a single smart contract. However, some details of the smart contract call and its execution result should only be available to the organization and the selected counter-agents. That is, the data transmitted by such a smart contract should be available only to some participants of the network. Confidential smart contracts (CSCs) satisfy this requirement.

When you create a confidential smart contract, you define a group of nodes (policy) that will be able to call the smart contract and receive its results. All the rest network participants will not be able to call the contract and receive its results. The policy administrator can change the list of its members.

When included in an existing policy, a node synchronizes its state with other participants and receives preceding contract performance results. If a node is excluded from the policy, it stops receiving contract performance results.

Note

A node can be a member of any number of policies.

The creation and use of confidential smart contracts is possible starting with release 1.13 after the 1130 feature activation.

Note

The same smart contract can be executed either confidentially or publicly. The confidentiality of the call is determined by the method by which the contract call transaction was sent – signAndBroadcast (for public smart contracts) or POST /confidential-contracts/call or ConfidentialCall (for confidential smart contracts).

Important

In addition to confidential smart contracts, the Waves Enterprise platform implements another confidential data exchange technology: transaction-level access to confidential data. When using this technology, only users who are members of a certain data access group can access data for certain transactions. Members of the same group can exchange data among themselves by sending it to the network via gRPC or REST APIs; the data will not be disclosed to the rest of the blockchain.

Confidential smart contract data¶

Confidential smart contracts receive and transmit the following data that require protection:

ConfidentialInput – an object that describes the confidential input data to run the contract, as well as the key to generate the commitment. ConfidentialInput includes the following fields:

txId – identifier of the version 6 104. CallContract transaction to which the input data refers;

commitmentKey – the key to form commitment;

param – input data of the confidential smart contract, represented as an array of objects; entered using the following fields:

key – the parameter key;

type – the parameter data type;

value– the parameter value.

ConfidentialOutput – object describing confidential contract execution results. ConfidentialOutput includes the following fields:

txId – identifier of the executable transaction to which the output data refers;

entries – output data of the confidential smart contract, represented as an array of objects, each of which includes the following fields:

key – the key;

type – data type;

value– the entry value.

Policy participants exchange confidential data that is recorded in transactions in encrypted form.

Storage of confidential smart contract data¶

Confidential smart contract data is stored off-blockchain in a separate database. Only the logic and еру key names are available in the smart contract itself.

Control of confidential smart contract data integrity and its protection¶

During confidential data exchange, files have arbitrary size, and their hash will always be unique. This ensures data integrity and security when exchanged in confidential mode.

But when you work with smart contracts, there are two categories of data that are not arbitrary – input and output data. Often they include integer values whose hash can be easily calculated.

To ensure the integrity and protection of the confidential smart contracts input and output data, an additional security mechanism – cryptographic commitment, or commitment scheme – is implemented. This mechanism includes hidden data transmission and data disclosure phases, and guarantees data consistency.

In addition, there is another mechanism to protect confidential smart contracts data – non-disclosure to the miners. The node that mines in the current round creates a new block and, accordingly, learns about all the new data, including smart contract transactions, before others do. In order for a block containing a smart contract transaction to enter the blockchain, a quorum for that transaction must be assembled. In case of a confidential smart contract, the validation of such transactions takes place within the policy. For this purpose, the policy must have at least three nodes with the contract-validator role. Due to this requirement, the miner can make sure that the quorum for the transaction has been collected and the consensus is reached, but the data itself remains hidden from the miner.

Creation of a confidential smart contract¶

To register a confidential smart contract in the blockchain, version 6 of the 103. CreateContract transaction is used.

When registering a confidential smart contract, you need to set its key parameters:

set the isConfidential field to true, thus marking the new contract as confidential;
define the policy, that is, the set of node addresses that will have access to sensitive data, in the groupParticipants field;
define the policy administrators, that is, the set of node addresses that can modify the lists of participants and policy administrators (groupParticipants and groupOwners), in the groupOwners field.

When creating a confidential smart contract, the following conditions must be met:

To create a confidential smart contract (isConfidential is set to true), you must specify three or more nodes with the contract-validator role in the groupParticipants field.
A confidential smart contract (isConfidential is set to true) cannot work with native tokens, so the payments field cannot be used when creating such a contract.
You cannot pass parameters in the params field for a confidential smart contract (isConfidential is set to true).
If the groupParticipants or groupOwners field contains any nodes, the contract is confidential and the isConfidential field must be set to true.
The size of the groupParticipants and groupOwners lists must not exceed 1024 participants.

Once the JSON representation of a CreateContract version 6 transaction has been generated, it must be signed and published in the same way as for a regular (public) smart contract, using one of the following methods:

POST /transactions/sign and POST /transactions/broadcast, or

POST /transactions/signAndBroadcast.

Confidential smart contract call¶

After a confidential smart contract is created and registered on the blockchain using transaction 103. CreateContract as described above, the member of the corresponding policy (node whose address is specified in the CreateContract transaction groupParticipants field) can call this smart contract using the 104. Call Contact transaction and one of the following methods:

POST /confidential-contracts/call REST method
ConfidentialCall gRPC method

Updating confidential smart contracts¶

Use version 5 of the 107. UpdateContract transaction to update confidential smart contracts.

When updating a confidential smart contract, a node whose address is specified in the groupOwners field can override the policy as follows:

change the list of node addresses that will have access to confidential data in the groupParticipants field; after the list is updated, the groupParticipants field must contain at least three participants with the contract-validator role.
change the list of policy administrators, that is, the nodes that will be able to modify the lists of participants and policy administrators (groupParticipants and groupOwners), in the groupOwners field.

Obtaining confidential smart contract result¶

You can get information about the confidential smart contract creation or update transaction by the transaction identifier {id} using the GET /transactions/info/{id} method. The transaction identifier is specified in the response of the POST /transactions/sign or POST /transactions/signAndBroadcast methods.

A policy member can retrieve the result of a confidential smart contract execution using the GET /confidential-contracts/tx/{executable-tx-id} method.

Note

If a user who is not a member of the policy, tries to get contract data after a confidential smart contract call transaction is mined using the /contracts/executed-tx-for/$txId method, the method response will be missing results. Thus, the result of a confidential smart contract execution is hidden from nodes that are not included in the policy.