Topos Playground

The Topos Playground installs and launches all the elements that compose a local test network. The first part of this section is optional and will let you test locally what you already experienced on the Testnet.

Component overview

Before you dive in, take a moment to understand the Playground at a high level. It makes use of the following components:

  • A local network, which utilizes Docker and Docker Compose, to test the essential (and some of the optional) components of the Topos Stack. The repository will spin up a local Docker network called local-erc20-messaging-infra-docker. This Docker network will consist of two subnets:
    • The Topos Subnet, which will simulate the actual Topos Subnet.
    • The Incal Subnet, a standard subnet, which will demonstrate the execution of cross-subnet messages.
  • A TCE network, which will consist of five TCE nodes in order to achieve a reliable broadcast of the certificates.
  • A dApp, to interact with the deployed network and trigger cross-subnet messages.
  • An executor service, which is an example implementation to execute cross-subnet calls on the receiving subnet.

You learned about the different components in the first chapter. If you need a refresher, review that chapter before you continue.


For the Playground to work, you should install:

  • Docker, which contains the following necessary components:
    • Docker, to run the container.
    • Docker Compose, to manage containers and networking.
  • Node.js, which will be used by the dApp.
  • MetaMask, which will also be used by the dApp.
  • Git, which is used to fetch different components that live in their respective repositories.

Minimum required versions:

  • Node.js -- version 16.0.0 or higher
  • Docker -- version 17.06.0 or higher

Install the Topos Playground


Once you have the necessary software on your machine, run:

$ npm install -g @topos-protocol/topos-playground@0.1.0 --save-dev --save-exact

After the installation is complete, check your installation:

$ npx topos-playground --help

Now you can start the Playground:

$ npx topos-playground start

It will first check your machine:

Starting Topos-Playground...
Verifying dependency installation...
✅ Docker -- Version: 24.0.5
✅ Git -- Version: 2.37.0
✅ Node.js -- Version: 19.6.0
✅ Dependency checks completed!

It will then clone the local network, dApp and executor service repositories and set up the environment parameters:

✅ Working directory exists
Cloning repositories...
✅ local-erc20-messaging-infra | v0.1.6 successfully cloned
✅ dapp-frontend-erc20-messaging | v0.1.4 successfully cloned
✅ executor-service | v0.2.0 successfully cloned
Copying .env files across repositories...
✅ .env.dapp-frontend copied
✅ .env.dapp-backend copied
✅ .env.executor-service copied
✅ .env.secrets copied

Eventually, it will start many components:

Running the ERC20 messaging infra...
✅ Subnets & TCE are running
Retrieving contract addresses...
✅ Contract addresses were retrieved and written to env files
Running the redis server...
✅ redis is running
Running the Executor Service...
✅ Deps are installed
✅ Web server is running
Running the dApp Frontend...
✅ Deps are installed
✅ Static files are built
✅ Web server is running

If everything works correctly, you should see:

🔥 Everything is done! 🔥
🚀 Start sending ERC20 tokens across subnet by accessing the dApp Frontend at http://localhost:3001
ℹ️ Ctrl/cmd-c will shut down the dApp Frontend and the Executor Service BUT will keep subnets and the TCE running (use the clean command to shut them down)
ℹ️ Logs were written to ~/.local/state/topos-playground/logs/log-5c63e885-129b-4941-b304-bdae3b780ac5.log

With everything running, you can start interacting with the frontend. You should be familiar with the frontend from the previous section. In addition, you can use the Topos Explorer to observe your local network. Just use your local endpoints instead of the Testnet.

Components in-depth

After playing with and testing the Topos Playground, you should now be motivated to dive into the details. The four key elements are:

  • The TCE network
  • The Topos Subnet
  • The Incal subnet
  • The ERC20 Messaging Frontend

This section will look at each of them.

The TCE network

The Playground first bootstraps a TCE node, and then runs four additional TCE nodes alongside it. All five TCE nodes will broadcast certificates – the first one generates keys for testing purposes. These TCE nodes are spawned with the help of the Topos CLI, which you will learn about and experiment with in the next section.

The Topos Subnet

You have already learned that the Topos Subnet is a special element of the zkEcosystem. The underlying Docker Compose file for it includes:

  • One container which generates the keys and subnet genesis block, and also sets the consensus to Istanbul Byzantine Fault Tolerant (IBFT) during initialization. This is done with the help of Polygon Edge.
  • Four Polygon Edge node containers, of which the first exposes the JSON-RPC API.
  • A sequencer container, which communicates with the TCE network. The sequencer container utilizes the Topos CLI in order to start a sequencer node.

The Incal Subnet

Because the Topos Playground is just a basic tool for demonstration and local testing, the network topology of the subnets it creates is similar. Incal consists of four node containers and one sequencer container. In addition, one container creates the keys and the genesis block. When the TCE network is up, the sequencer subscribes to it to receive relevant certificates and to broadcast its own certificates to it.

After the subnet is ready, the Playground starts a container for the contracts:

  • One container to prepare necessary artifacts in order to deploy the contracts.
  • One container for the Incal subnet to deploy its intended contracts.

This container also includes some scripts – for example, for contract deployments and subnet registrations. So, by default, the Incal subnet is registered on the Topos Subnet. The contract container runs once and exit after the deployment.

The ERC20 Messaging frontend

The ERC20 Messaging frontend for the Playground consists of a basic web server and the frontend you interacted with previously. The frontend utilizes the ethers.js library to call the respective contracts. The first action you tried, the registration of a token, invokes the deployToken function on the ERC20Messaging contract. Similarly, you can see that a token is sent by calling the sendToken function of the contract.

To be more precise, a cross-subnet token transfer is divided into the three steps that were displayed by the ERC20 Messaging frontend during your test. You can examine the code to better understand the process behind the steps.

One thing to mention specifically in relation to the Playground is the use of the executor service. What the service essentially does is:

  1. Wait for the expected certificate to be delivered.
  2. Submit the transaction payload and Merkle proof of inclusion.

Up next

You have now looked at the details of the playground components. In the next section you will learn how to run the topos-zkevm-demo, which allows you to run and use a zkevm in your local environment.

© 2024 All rights reserved zk FoundationBuild bd74f6332024-04-19T16:37:51.288Z