Chain Backup and Restoration

MOP: Toto Chain Backup and Restoration

1.0 Introduction

This Method of Procedure (MOP) provides standardized instructions for creating a true backup of a Toto Chain node. This is the correct and standard procedure for disaster recovery, migrating a node to new hardware, or any scenario where you need to restore a node that can continue syncing with the original network.

The primary method involves using the export-blocks and import-blocks commands, which save and restore the chain's actual history.

At the end of this document, there is a supplementary guide on an alternative technique, export-state, which is used for creating new development chains, not for backups.

2.0 Procedure: Backup and Restore

2.1 Prerequisites

• A fully synced node of the chain you wish to back up.

• The peerplays node executable.

• The original genesis file of the chain (e.g., toto-network.genesis.json).

• Sufficient disk space for the exported blocks file, which can be large.

2.1.1 What if I don't have the original genesis file?

The genesis file is essential for restoration. While it's not stored as a simple .json file in a running node's database, you can regenerate it using the peerplays executable itself. The node's binary contains the necessary information to build the chain specification.

To regenerate the genesis file, use the build-spec command. You will need to know the name of the chain spec you want to build (e.g., testnet, mainnet).

• To generate a raw genesis file (required for starting a network that can connect to other nodes):

  ./peerplays build-spec --chain <chain-spec> --raw > genesis.json
  

• To generate a human-readable chain spec file (useful for inspection and understanding the configuration):

  ./peerplays build-spec --chain <chain-spec> > chainSpec.json
  

For the purpose of this MOP, you will need the raw version.

2.2 Backup (Exporting Blocks)

Step 2.2.1: Stop the Node

1. For a clean and consistent backup, stop the running node by pressing Ctrl + C in its terminal.

Step 2.2.2: Execute the export-blocks Command

1. In your terminal, execute the export-blocks command, specifying the node's data directory (--base-path).

2. Redirect the output to a binary file. For clarity, it's good practice to name this file something descriptive like blocks.bin.

   • Syntax:

     ./peerplays export-blocks --base-path <path_to_data> > blocks.bin
     

   • Note: You can use flags like --from <block_number> to export a partial history if needed. For a full backup of the entire chain history, omit these flags.

Step 2.2.3: Secure the Backup

1. Confirm that the blocks.bin file has been created and is not empty.

2. Copy this blocks.bin file and the original genesis.json file to a secure, separate backup location (e.g., a different server, cloud storage). Both files are required for a successful restoration.

2.3 Restoration (Importing Blocks)

Step 2.3.1: Prepare the New Environment

1. On the new machine or in a new location, create a new, empty directory that will serve as the base path for the restored node.

   • Example: mkdir ./restored-node-data

2. Place your blocks.bin backup file and the original genesis.json file in a location accessible to the peerplays executable.

Step 2.3.2: Execute the import-blocks Command

1. Execute the import-blocks command, specifying the new base path, the original chain spec (your genesis file), and the path to your blocks file.

   • Syntax:

     ./peerplays import-blocks --base-path <path_to_new_data_dir> --chain <original_genesis.json> <path_to_blocks.bin>
     

   • Example:

     ./peerplays import-blocks --base-path ./restored-node-data --chain toto-network.genesis.json ./blocks.bin
     

2. The node will now begin replaying all the blocks from the backup file into its new database. This process can take a significant amount of time, depending on the size of the backup.

Step 2.3.3: Start and Verify the Restored Node

1. Once the import process is complete, start the node normally, pointing to the newly populated data directory.

   • Example: ./peerplays --base-path ./restored-node-data --chain toto-network.genesis.json

2. The node will initialize using the restored data and then immediately attempt to connect to the p2p network to sync any new blocks that were produced since the backup was taken.

3. Verify in the logs that the node is successfully connecting to peers and finalizing new blocks. Your node is now fully restored and in sync with the original network.

Appendix: Creating a New Chain from a State Snapshot (Advanced)

This is a developer-focused technique and is not a backup method. It is used to create a new, separate chain that starts at block #0 but contains the full state of another chain at a specific point in time. A node started this way cannot connect back to the original network.

• Use Case: Creating a lightweight test environment with realistic data without the large database of a full node.

Exporting the State

1. Stop a synced node of the source chain (Chain A).

2. Execute the export-state command, using the same --base-path and --chain parameters as the running node.

   ./peerplays export-state --base-path . --chain toto-network.genesis.json > new_genesis_from_state.json
   

Starting the New Chain (Chain B)

1. Create a new, empty data directory (e.g., mkdir ./new-chain-b-data).

2. Start a new node, pointing to the new data directory and using the exported state file as its genesis.

   ./peerplays --base-path ./new-chain-b-data --chain new_genesis_from_state.json
   

3. This node (Chain B) will now be running as a completely separate network.

Important Note: This newly created chain will not produce blocks because it does not have validator keys in its keystore. It is a snapshot of a previous state, ideal for querying, testing, and analysis.