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
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:
- 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 @email@example.com --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
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
- 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:
- Wait for the expected certificate to be delivered.
- Submit the transaction payload and Merkle proof of inclusion.
You have now looked at the details of the playground components, one of them being the Topos CLI. In the next section, you will look at the CLI in more depth.