Running a local sandbox

You can run a local sandbox to test Etherlink transactions and smart contracts locally. The sandbox consists of an EVM node in a special mode that includes the functionality of the sequencer and does not need any other nodes. The local sandbox is intended for local testing and debugging.

The sandbox begins by replicating an existing network, so you can use it to work with contracts on Mainnet, Testnet, or Shadownet.

Follow these steps to start the local sandbox:

1. Get the latest release of the octez-evm-node binary as described in Running an Etherlink EVM node.

2. Initialize the data directory for the EVM node, as this example, which uses the placeholder <EVM_DATA_DIR> to represent the local folder for the data directory and <NETWORK> for the network to replicate (mainnet, testnet, or shadownet):

   octez-evm-node init config \
     --network <NETWORK> \
     --data-dir <EVM_DATA_DIR> \
     --dont-track-rollup-node

   For example, for Etherlink Shadownet, the command might like look like this:

   octez-evm-node init config \
     --network shadownet \
     --data-dir ~/sandbox-shadownet \
     --dont-track-rollup-node

   After you use the node in sandbox mode with a certain data directory, you cannot re-use that data directory for running an EVM node on the network itself. Consider using a different data directory for the sandbox than you use for other EVM nodes.

3. (Optional) Enable WebSockets on the node as described in Getting updates with WebSockets.

4. Start the node in sandbox mode from a snapshot:

   octez-evm-node run sandbox \
     --network <NETWORK> \
     --data-dir <EVM_DATA_DIR> \
     --init-from-snapshot \
     --fund 0x45Ff91b4bF16aC9907CF4A11436f9Ce61BE0650d

   The --fund arguments in these commands send 10,000 XTZ to one or more bootstrap addresses that you can use in the sandbox.

   To replicate an environment with high traffic, pass the RPC URL of an EVM node on the same network to the --replicate argument, as in --replicate https://node.shadownet.etherlink.com. Your sandbox node uses the blocks from that EVM node in real time to simulate a real environment with real transactions. Using this mode allows you to run tests on contracts already deployed on a live network, with a real context, but without having to deploy changes to Testnet or paying transaction fees.

   The sandbox node runs in rolling:1 history mode.

   The node takes time to download the snapshot and start the sandbox. The node is ready when the log shows new block numbers, as in this example:

   Mar 14 11:04:04.155 NOTICE │ head is now 7523759, applied in 11.422ms

5. Verify that the sandbox node is running. For example, you can call an RPC endpoint with a curl command to verify the amount of XTZ in the bootstrap accounts, as in this example:

curl -X POST -H 'Content-Type: application/json' \
  --data '{"jsonrpc": "2.0","method": "eth_getBalance","params":["0x45Ff91b4bF16aC9907CF4A11436f9Ce61BE0650d"],"id": 1}' \
  http://localhost:8545

Now you can use the sandbox environment like a private test network.