Technical description of the platform
Snapshooting¶
Snapshooting is an auxiliary mechanism of the blockchain platform which allows to save the data of the working blockchain for a subsequent change of network configuration and starting of the network with the saved data.
The snapshooting mechanism allows to change the blockchain configuration parameters without loss of its data. The process of changing of the network configuration parameters with the use of a snapshot is called migration.
A snapshot includes the following data:
states of network addresses: balances, permissions, keys;
states of smart contracts created in the network: data received as a result of smart contract calls and attached to them with the use of 105 transactions;
data of miners of the previous rounds;
information of confidential data access groups.
A snapshot does not include history of transactions, bans and network blocks.
In the process of migration, a snapshot becomes an initial state of the blockchain network with new parameters, and the network itself is restarted with generation of the new genesis block.
Snapshooting is enabled and configured in the section node.consensual-snapshot of the node configuration file.
Components of the snapshooting mechanism¶
SnapshotBroadcaster – the component for broadcasting of the SnapshotNotification messages, processing of requests for snapshot generation (SnapshotRequest) and subsequent transfer of a ready snapshot. As snapshots can have a large size, the SnapshotBroadcaster process not more than 2 requests simultaneously.
SnapshotLoader – the component that registrates incoming SnapshotNotification messages at a node, sends SnapshotRequest messages and loads snapshots. If a node receives the SnapshotNotification message, the sender address is added to the array of addresses that have the snapshot. After that, the notification is sent to other node peers.
The SnapshotLoader repeatedly checks the address array for presence of an address with a ready snapshot. If such address exists, as well as an open network channel with it, the node sends the SnapshotRequest message to this address for download of the snapshot. The response timeout for this message is 10 seconds. If a node with the snapshot does not respond within this timeout, it is excluded from the address array. In this case, the node picks a next address with a ready snapshot and sends a SnapshotRequest message to this address.
If the snapshot has been downloaded successfully, it is unpacked and verified with the node state. In case of a successful verification, the node which has received the snapshot sends the SnapshotNotification messages to its peers.
SnapshotApiRoute – the REST API interface for snapshot operations.
Generation and broadcasting of a snapshot in an operating blockchain¶
1. The node appointed for mining at the snapshot-height is also appointed for snapshot generation. Snapshot generation starts at the snapshot-height + 1, the generated snapshot is saved in the snapshot-directory. During the snapshot generation, entering of new transactions into the blockchain UTX pool is blocked. After successful generation of snapshot, the node creates an empty genesis block with the consensus algorithm of a new network (consensus-type) and saves it in the snapshot.
2. Upon achievement of the snapshot-height + wait-blocks-count, the node which has created the snapshot, archives it and sends the SnapshotNotification messages about readiness of the snapshot to its peers.
3. Upon receipt of the SnapshotNotification, the nodes initiate the SnapshotRequest messages to download a ready snapshot. In case of expiration of snapshot receiving timeout or an error while downloading it, the node picks another peer and requests a snapshot from it.
4. Each node that has received an archive with a snapshot, saves it in the snapshot-directory, unpacks it and checks its correctness: compares address balances and keys, checks smart contracts integrity, members and parameters of confidential data access groups, participants’ permissions. If the snapshot verification is successful, the node sends the messages about availability of the snapshot (SnapshotNotification) to its peers. After this, peers of the node can send it a request for snapshot download.
As a result, the snapshot is downloaded by each node of the network, and verification on the level of each node excludes a possibility of snapshot data spoofing.
After generating of the snapshot, you can start your node with changed configuration parameters and the generated snapshot. Learn more about this in the article Node start with a snapshot.
If you connect to the node with an empty state (new node) to the network started from the snapshot, the process of snapshot download will be performed automatically: node automatically connects with peers for snapshot downloading and validation of its own configuration file. See the Connection of a new node to blockchain network section for description of the connection process.
Snapshot REST API methods¶
GET /snapshot/status – returns an actual snapshot status at the current node:
Exists– the snapshot exists/has been downloaded;
NotExists– the snapshot does not exists/has not been downloaded yet;
Failed– failed to unpack or verify a snapshot;
Verified– the snapshot has been verified successfully.
GET /snapshot/genesis-config – returns a configuration of a new network genesis block;
POST /snapshot/swap-state – freezes operation of the mode and switches its state with the snapshot. The query contains a backupOldState parameter, that defines if the current state should be saved or removed:
true– save the current state in the``PreSnapshotBackup`` directory of the node;
false– remove the current state.
Network messages¶
SnapshotNotification(sender)– the message of a node about availability of a snapshot, is sent with a node public key;SnapshotRequest(sender)– request of a node for downloading of a snapshot, is also sent with a node public key.