Zellular Sequencer

Warning: Do not use in Production, testnet only.

A PoC implementation of the Zellular BFT Protocol in Python.

Table of Contents

• Requirements
• Documentation
• Joining EigenLayer Test Network
• Testing

Requirements

• Docker and Docker Compose
• Python 3.10+ (for development and testing)
• EigenLayer CLI (for key generation)

Documentation

Comprehensive documentation is available at docs.zellular.xyz, including:

• Architecture Overview - Learn about the system design
• Protocol Specification - Detailed explanation of the BFT protocol
• SDK Documentation - How to build applications with Zellular
• Example Applications - Sample implementations including:
  • Token Service
  • Orderbook
  • Downtime Monitoring

Joining EigenLayer Test Network

Recommended Node Specifications

For running a Zellular Sequencer node, the General Purpose - large with 2 vCPUs, 8 GB RAM, and 5 Mbps network bandwidth is sufficient.

Install Docker

Follow these instructions to install the latest version of Docker.

Generate Keys

Follow these instructions to install the eigenlayer CLI to generate the BLS and ECDSA key files for your node:

eigenlayer operator keys create --key-type ecdsa zellular
eigenlayer operator keys create --key-type bls zellular

Register the Operator

Follow the EigenLayer Operator Guide to fund your ECDSA wallet and register as an operator on EigenLayer core contracts.

Zellular Holesky testnet operators need at least 1 Lido Staked Ether (stETH) delegated to them:

1. Obtain Holesky testnet ethers from the available faucets
2. Use the Lido testnet staking dashboard to stake these ethers and receive Lido staking tokens
3. Restake these tokens on the EigenLayer Holesky dashboard and delegate them to your operator

Set Up Your Node

1. Create a directory for your node:

   mkdir zsequencer
   cd zsequencer

2. Download the docker-compose file:

   curl -o docker-compose.yml https://raw.githubusercontent.com/zellular-xyz/zsequencer/refs/heads/main/docker-compose-pull.yml

3. Download the environment file template:

   curl -o .env https://raw.githubusercontent.com/zellular-xyz/zsequencer/refs/heads/main/.env.example

4. Edit the .env file with your configuration:

   ZSEQUENCER_BLS_KEY_FILE=~/.eigenlayer/operator_keys/zellular.bls.key.json
   ZSEQUENCER_BLS_KEY_PASSWORD=[your password for bls key file]
   ZSEQUENCER_ECDSA_KEY_FILE=~/.eigenlayer/operator_keys/zellular.ecdsa.key.json
   ZSEQUENCER_ECDSA_KEY_PASSWORD=[your password for ecdsa key file]
   ZSEQUENCER_REGISTER_SOCKET=[htttp://server-ip:port]
   

   Note: The only required variables to set are:

   • Path to BLS & ECDSA key files and their passwords
   • Socket URL for registering the operator with Zellular AVS on EigenLayer

Run the Node

1. Create the Docker network (first time only):

   docker network create zsequencer_net

2. Start your node:

   docker compose up -d

Testing

End-to-End (E2E) Tests

The project includes end-to-end tests that simulate a network of nodes and allow you to test functionality in a controlled environment.

Prerequisites

• Docker and Docker Compose installed
• Python with uv package manager

Steps to Run E2E Tests

1. Build the Docker container:

   docker compose build

2. Run the network simulation:

   uv run -m tests.e2e.run start --config tests/e2e/sample_config.json

   This will start a network of nodes based on the configuration in sample_config.json.

3. In a separate terminal, run the client to interact with the network:

   uv run -m tests.e2e.client --config tests/e2e/sample_config.json

   The client will send example transactions to the nodes in the network.

4. To view logs from all containers:

   # Opens a terminal window for each container showing its logs
   uv run -m tests.e2e.run logs --terminal=gnome-terminal

   Supported terminals: gnome-terminal, xterm, konsole, terminator, tilix

   For individual container logs, use the docker logs command directly:

   docker logs -f zsequencer-node-0

5. When you're done testing, you can stop all the containers:

   uv run -m tests.e2e.run stop

   This will stop and remove all zsequencer node containers that were started.

Configuration Options

The sample configuration file (sample_config.json) lets you control:

• Number of nodes in the network
• Base port for the nodes
• Environment variables for all nodes
• Simulated network conditions, including outages and delays