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.

Prerequisites

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.

Install the Topos Playground

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

$ npx topos-playground --help

$ npx topos-playground start

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!

✅ 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

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

🔥 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.