Use Docker and Flextesa to Run an Independent Tezos Sandbox

Running ephemeral and isolated sandboxes can be useful to experiment with faster networks or to automate reproducible tests.

Here we use Flextesa to run one or more Tezos nodes, bakers, and endorsers contained in a sandbox environment. The default sandbox is configured to be compatible with the tezos-client installed in the “Client-setup” section.

Dependencies

This example requires Docker, available for Linux, Mac or Windows at https://www.docker.com.

Starting and Using a Sandbox

Start the sandbox in the background (will run with baking enabled):

docker run --rm --name my-sandbox --detach -p 20000:20000 \
       tqtezos/flextesa:20200925 carthagebox start

After a few seconds this should succeed:

tezos-client config reset        # Cleans-up left-over configuration.
tezos-client -A localhost -P 20000 bootstrapped

Configure the client to communicate with the sandbox:

tezos-client -A localhost -P 20000 config update

Then, instead of using a public faucet one can just use ꜩ by importing accounts already existing in the sandbox. They are visible with:

 $ docker run --rm tqtezos/flextesa:20200925 carthagebox info

Usable accounts:

- alice
  * edpkvGfYw3LyB1UcCahKQk4rF2tvbMUk8GFiTuMjL75uGXrpvKXhjn
  * tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb
  * unencrypted:edsk3QoqBuvdamxouPhin7swCvkQNgq4jP5KZPbwWNnwdZpSpJiEbq
- bob
  * edpkurPsQ8eUApnLUJ9ZPDvu98E8VNj4KtJa1aZr16Cr5ow5VHKnz4
  * tz1aSkwEot3L2kmUvcoxzjMomb9mvBNuzFK6
  * unencrypted:edsk3RFfvaFaxbHx8BMtEW1rKQcPtDML3LXjNqMNLCzC3wLC1bWbAt

Root path (logs, chain data, etc.): /tmp/mini-box (inside container).

You may then just import them:

tezos-client import secret key alice unencrypted:edsk3QoqBuvdamxouPhin7swCvkQNgq4jP5KZPbwWNnwdZpSpJiEbq --force
tezos-client import secret key bob unencrypted:edsk3RFfvaFaxbHx8BMtEW1rKQcPtDML3LXjNqMNLCzC3wLC1bWbAt --force

Check their balances:

tezos-client get balance for alice

Using The Sandbox

See also the Tezos Client section or the Wallet-usage tutorial of the Tezos manual.

For instance, one can originate the most minimalistic contract:

# Download the contract:
wget https://gitlab.com/tezos/tezos/raw/mainnet/src/bin_client/test/contracts/attic/id.tz
# Run origination:
tezos-client originate contract hello-id transferring 0 from bob running id.tz --init "\"hello world\"" --burn-cap 1 --force

Shutting Down The Sandbox

When you're done playing, just destroy the container:

docker kill my-sandbox

Advanced Usage

Tweak Protocol Constants

One can see the configuration of the protocol running in the sandbox with:

tezos-client rpc get /chains/main/blocks/head/context/constants

One important field is "time_between_blocks": [ "5" ], which means that blocks are baked every 5 seconds (as opposed to 60 seconds on Mainnet).

This constant can be configured with the block_time environment variable, see example below:

docker run --rm --name my-sandbox -e block_time=2 --detach -p 20000:20000 \
       tqtezos/flextesa:20200925 carthagebox start

The above command runs a full sandbox with the Carthage protocol and a faster time-between-blocks of 2 seconds.

Many other parameters are set by the carthagebox script. All the configuration options available can be seen with the command:

docker run --rm -it tqtezos/flextesa:20200925 flextesarl mini-net --help

Try The Delphi Protocol

The Docker image also contains a delphibox script:

docker run --rm --name my-sandbox --detach -p 20000:20000 \
       tqtezos/flextesa:20200925 delphibox start

On can then check that the protocol hash is PsDELPH1Kxsxt8f9eWbxQeRxkjfbxoqM52jvs5Y5fBxWWh4ifpo:

 $ tezos-client rpc get /chains/main/blocks/head/metadata | grep protocol
{ "protocol": "PsDELPH1Kxsxt8f9eWbxQeRxkjfbxoqM52jvs5Y5fBxWWh4ifpo",
  "next_protocol": "PsDELPH1Kxsxt8f9eWbxQeRxkjfbxoqM52jvs5Y5fBxWWh4ifpo",

or that the storage burn cost has been reduced to 250 μꜩ:

 $ tezos-client rpc get /chains/main/blocks/head/context/constants | grep cost_per_byte
  "endorsement_reward": [ "1250000", "833333" ], "cost_per_byte": "250",

Further Reading

For more issues or questions, see the Flextesa repository, and for even more advanced usage, see the documentation.

For the differences between Carthage and Delphi see the changelog.

← Tezos ClientIntroduction →