How to Use Chopsticks to Fork Your Appchain¶

Introduction¶

Chopsticks provides a developer-friendly method of locally forking existing Substrate-based chains. It allows for the replaying of blocks to easily examine how transactions affect the state, the forking of multiple Tanssi appchains for XCM testing, and more. This empowers developers to test and experiment with their custom blockchain configurations in a local development environment without deploying a live network.

Overall, Chopsticks aims to simplify the process of building blockchain applications on Substrate and make it accessible to a wider range of developers.

This article will cover using Chopsticks to fork and interact with the local copy of a Tanssi appchain.

Prerequisites¶

To follow along with this tutorial, you will need to clone the repository along with its submodules(Smoldot):

git clone --recurse-submodules https://github.com/AcalaNetwork/chopsticks.git

Then, get into the folder and install the dependencies using yarn:

 cd chopsticks && yarn

Finally, build the project:

yarn build-wasm

Now the development environment is ready to start testing and debugging Tanssi-deployed appchains.

Forking a Demo EVM Appchain with Chopsticks¶

To fork a Tanssi appchain using Chopsticks, execute the command with only the RPC endpoint as a parameter:

yarn start --endpoint wss://fraa-dancebox-3001-rpc.a.dancebox.tanssi.network

This command will start a local clone of the chain as it was in the latest block.

Typically, the configuration parameters are stored in a configuration file, as are the configurations in the repository's configs folder for the relay chains and parachains deployed in the Dotsama ecosystem. The following configuration file works for the demo EVM appchain, overriding the chain's sudo account with Alith's and additionally funding the account with tokens:

endpoint: wss://fraa-dancebox-3001-rpc.a.dancebox.tanssi.network
mock-signature-host: true
allow-unresolved-imports: true
db: ./tmp/db_ftrcon.sqlite

import-storage:
  System:
    Account:
      - - - "0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac" # Alith
        - providers: 1
          sufficients: 1
          consumers: 1
          data:
            free: "100000000000000000000000"
  Sudo:
    Key: "0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac"

The configuration file accepts all of the following parameters:

You can run the command yarn start to fork chains by specifying a local configuration file. Alternatively, the name or the GitHub URL can be used if the chain is listed in the repository's configs folder.

yarn start --config=configs/polkadot.yml

yarn start --config=polkadot

yarn start \
--config=https://github.com/AcalaNetwork/chopsticks.git/master/configs/polkadot.yml

All settings (except genesis and timestamp) can also be passed as flags to configure the environment completely in the command line. For example, the following command forks the demo EVM appchain at block 100.

yarn start --endpoint wss://fraa-dancebox-3001-rpc.a.dancebox.tanssi.network --block 100

Interacting with a Fork¶

When running a fork, by default, it will be accessible at:

ws://localhost:8000

You can interact with the parachain via libraries such as Polkadot.js and its user interface, Polkadot.js Apps.

You should now be able to interact with the forked chain as you would with the real one.

Replaying Blocks¶

If you would like to replay a block and retrieve its information to dissect the effects of an extrinsic, you can use the yarn start run-block command. Its following flags are:

For example, running the following command will re-run the demo EVM appchains's block 1000 and write the storage diff and other data in a chain-output.json file:

yarn start run-block  \
--endpoint wss://fraa-dancebox-3001-rpc.a.dancebox.tanssi.network  \
--output-path=./chain-output.json  \
--block 1000

WebSocket Commands¶

Chopstick's internal WebSocket server has special endpoints that allow the manipulation of the local Substrate chain.

These are the methods that can be invoked and their parameters:

import { WsProvider } from '@polkadot/api'
const ws = new WsProvider(`ws://localhost:8000`)
// Creates five new blocks
await ws.send('dev_newBlock', [{ count: 5 }])

import { WsProvider } from '@polkadot/api';
const ws = new WsProvider(`ws://localhost:8000`);
// Overwrites the sudo key
await ws.send('dev_setStorage', 
    [{"Sudo": { "Key": "0x6Be02d1d3665660d22FF9624b7BE0551ee1Ac91b" }}]
);

import { WsProvider } from '@polkadot/api';
const ws = new WsProvider(`ws://localhost:8000`);
// Sets the timestamp of the block to 15th August 2030
await ws.send('dev_timeTravel', ["2030-08-15T00:00:00"]);

import { WsProvider } from '@polkadot/api';
const ws = new WsProvider(`ws://localhost:8000`);
// Sets the head to block number 500
await ws.send('dev_setHead', [500]);