Sandboxed mode

Sandboxed mode#

To run a ‘localhost-only’ instance of a Tezos network, we provide two helper scripts:

  • ./src/bin_node/octez-sandboxed-node.sh

  • ./src/bin_client/octez-init-sandboxed-client.sh

For the moment these scripts are expected to be run on the master branch (see Build from sources; in particular, use git checkout master instead of git checkout latest-release).

Run a sandboxed node#

For instance, if you want to run a local network with two nodes, in the first terminal, the following command will initialize a node listening for peers on port 19731 and listening for RPC on port 18731.

./src/bin_node/octez-sandboxed-node.sh 1 --connections 1

This node will store its data in a temporary directory /tmp/octez-node.xxxxxxxx which will be removed when the node is stopped.

The option --connections specifies the ideal number of peers the node tries to connect to. Lowering the number of expected connections removes the spurious “Too few connections” warnings. Set it to 1 for our two-nodes network (and you would set it to 0 for a single-node network).

More informations can be found in the api page of the octez node config : or by simply calling

./src/bin_node/octez-sandboxed-node.sh 1 --connections 1 --help

To launch the second node, run the following command in another terminal, and it will listen on port 19739 and 18739:

./src/bin_node/octez-sandboxed-node.sh 9

You might replace 1 or 9 by any number in between if you want to run more than two nodes.

Use the sandboxed client#

Once your node is running, open a new terminal and initialize the “sandboxed” client data in a temporary directory:

eval `./src/bin_client/octez-init-sandboxed-client.sh 1`

It will also define in the current shell session an alias octez-client preconfigured for communicating with the same-numbered node.

When you bootstrap a new network, the network is initialized with a dummy economic protocol, called genesis. If you want to run the whole implemented protocol, init-sandboxed-client also defines an alias octez-activate-alpha, that you need to execute once for activating the whole network. For instance:

$ octez-client rpc get /chains/main/blocks/head/metadata
  "next_protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"
$ octez-activate-alpha
  Injected BMV9KnSPE1yw
$ octez-client rpc get /chains/main/blocks/head/metadata
  "protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"

We now have the possibility to send transactions to the sandboxed network. As the genesis block used to initialize the sandboxed network differs from the one used in test networks, it is not possible to activate accounts obtained from the faucet. However, we can use the preconfigured accounts which can be listed with:

$ octez-client list known addresses

  activator: tz1TGu6TN5GSez2ndXXeDX6LgUDvLzPLqgYV (unencrypted sk known)
  bootstrap5: tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv (unencrypted sk known)
  bootstrap4: tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv (unencrypted sk known)
  bootstrap3: tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU (unencrypted sk known)
  bootstrap2: tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN (unencrypted sk known)
  bootstrap1: tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx (unencrypted sk known)

We can run the following command to transfer some Tez from one account to another:

$ octez-client transfer 42 from bootstrap1 to bootstrap2 &
...
Waiting for the operation to be included...

You will notice that this command doesn’t terminate (hence the &), as usual it is waiting for the network to include the transaction in a block. Given that we are in a sandbox we need to bake a block ourselves and we can do so with the following command:

$ octez-client bake for --minimal-timestamp

If the previous transaction is valid, the operation is included in the chain and the transfer terminates returning the usual receipt. Note that the bake for command of the client is exclusively for testing purposes, all baking should be done using the octez-baker binary.

Tune protocol Alpha parameters#

The octez-activate-alpha alias uses parameters from src/proto_alpha/parameters/sandbox-parameters.json to activate protocol Alpha. It can be useful to tune these parameters when you need to debug something, for example, change the number of blocks per cycle, the time between blocks, etc.

Preserve data#

If you want to preserve data and configuration files at the end of your run, you can use the DATA_DIR environment variable.

mkdir /tmp/tz-data
DATA_DIR='/tmp/tz-data' ./src/bin_node/octez-sandboxed-node.sh 1 --connections 1

You can even provide a custom identity.json and config.json to the sandboxed node by placing them in the data directory.

Baking multiple blocks#

To bake multiple blocks in a single command the -n <number_of_blocks> option can be used like

$ octez-client bake for --minimal-timestamp -n 1_000

Once the current timestamp is caught up, blocks are produced every second or every minimal_block_delay set in the parameters file. To speed up the process the protocol can be activated in the past with

$ octez-activate-alpha --timestamp "2024-01-01T00:00:00Z"

This increases the number of blocks needed to reach the current timestamp and speeds up the blocks production.

Contents