{"id":19730446,"url":"https://github.com/zellular-xyz/zsequencer","last_synced_at":"2025-10-03T12:10:05.426Z","repository":{"id":250277332,"uuid":"775957204","full_name":"zellular-xyz/zsequencer","owner":"zellular-xyz","description":"PoC implementation of the Zellular sequencing protocol","archived":false,"fork":false,"pushed_at":"2025-08-10T07:42:16.000Z","size":1124,"stargazers_count":2,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T09:22:37.636Z","etag":null,"topics":["bft-protocols","consensus-protocol"],"latest_commit_sha":null,"homepage":"https://zellular.xyz","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zellular-xyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-22T11:42:48.000Z","updated_at":"2025-07-14T07:02:07.000Z","dependencies_parsed_at":"2024-07-26T09:05:58.272Z","dependency_job_id":"998edec1-f470-4af6-a6ba-da968e3ebc0c","html_url":"https://github.com/zellular-xyz/zsequencer","commit_stats":null,"previous_names":["zellular-xyz/zsequencer"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/zellular-xyz/zsequencer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellular-xyz%2Fzsequencer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellular-xyz%2Fzsequencer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellular-xyz%2Fzsequencer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellular-xyz%2Fzsequencer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zellular-xyz","download_url":"https://codeload.github.com/zellular-xyz/zsequencer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellular-xyz%2Fzsequencer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278158278,"owners_count":25939781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bft-protocols","consensus-protocol"],"created_at":"2024-11-12T00:16:26.172Z","updated_at":"2025-10-03T12:10:05.381Z","avatar_url":"https://github.com/zellular-xyz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zellular Sequencer\n\n\u003e **Warning:** Do not use in Production, testnet only.\n\nA PoC implementation of the [Zellular BFT Protocol](https://docs.zellular.xyz/protocol.html) in Python.\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Documentation](#documentation)\n- [Joining EigenLayer Test Network](#joining-eigenlayer-test-network)\n- [Testing](#testing)\n\n## Requirements\n\n- Docker and Docker Compose\n- Python 3.10+ (for development and testing)\n- EigenLayer CLI (for key generation)\n\n## Documentation\n\nComprehensive documentation is available at [docs.zellular.xyz](https://docs.zellular.xyz/), including:\n\n- [Architecture Overview](https://docs.zellular.xyz/architecture.html) - Learn about the system design\n- [Protocol Specification](https://docs.zellular.xyz/protocol.html) - Detailed explanation of the BFT protocol\n- [SDK Documentation](https://docs.zellular.xyz/sdk.html) - How to build applications with Zellular\n- Example Applications - Sample implementations including:\n  - [Token Service](https://docs.zellular.xyz/examples/token.html)\n  - [Orderbook](https://docs.zellular.xyz/examples/orderbook.html)\n  - [Downtime Monitoring](https://docs.zellular.xyz/examples/downtime_monitoring.html)\n\n## Joining EigenLayer Test Network\n\n### Recommended Node Specifications\n\nFor running a Zellular Sequencer node, the [General Purpose - large](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/eigenlayer-node-classes#general-purpose-eigenlayer-node-classes) with 2 vCPUs, 8 GB RAM, and 5 Mbps network bandwidth is sufficient.\n\n### Install Docker\n\nFollow [these instructions](https://docs.docker.com/engine/install/#server) to install the latest version of Docker.\n\n### Generate Keys\n\nFollow [these instructions](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/operator-installation#install-cli-using-binary) to install the `eigenlayer` CLI to generate the `BLS` and `ECDSA` key files for your node:\n\n```bash\neigenlayer operator keys create --key-type ecdsa zellular\neigenlayer operator keys create --key-type bls zellular\n```\n\n### Register the Operator\n\nFollow the [EigenLayer Operator Guide](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/operator-installation#fund-ecdsa-wallet) to fund your ECDSA wallet and register as an operator on EigenLayer core contracts.\n\nZellular Holesky testnet operators need at least 1 Lido Staked Ether (stETH) delegated to them:\n\n1. Obtain Holesky testnet ethers from the [available faucets](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/testnet/obtaining-testnet-eth-and-liquid-staking-tokens-lsts#obtain-holesky-eth-aka-holeth-via-a-faucet)\n2. Use the [Lido testnet staking dashboard](https://stake-holesky.testnet.fi/) to stake these ethers and receive Lido staking tokens\n3. Restake these tokens on the [EigenLayer Holesky dashboard](https://holesky.eigenlayer.xyz/restake/stETH) and delegate them to your operator\n\n### Set Up Your Node\n\n1. Create a directory for your node:\n   ```bash\n   mkdir zsequencer\n   cd zsequencer\n   ```\n\n2. Download the docker-compose file:\n   ```bash\n   curl -o docker-compose.yml https://raw.githubusercontent.com/zellular-xyz/zsequencer/refs/heads/main/docker-compose-pull.yml\n   ```\n\n3. Download the environment file template:\n   ```bash\n   curl -o .env https://raw.githubusercontent.com/zellular-xyz/zsequencer/refs/heads/main/.env.example\n   ```\n\n4. Edit the `.env` file with your configuration:\n   ```\n   ZSEQUENCER_BLS_KEY_FILE=~/.eigenlayer/operator_keys/zellular.bls.key.json\n   ZSEQUENCER_BLS_KEY_PASSWORD=[your password for bls key file]\n   ZSEQUENCER_ECDSA_KEY_FILE=~/.eigenlayer/operator_keys/zellular.ecdsa.key.json\n   ZSEQUENCER_ECDSA_KEY_PASSWORD=[your password for ecdsa key file]\n   ZSEQUENCER_REGISTER_SOCKET=[htttp://server-ip:port]\n   ```\n\n   \u003e **Note**: The only required variables to set are:\n   \u003e - Path to BLS \u0026 ECDSA key files and their passwords\n   \u003e - Socket URL for registering the operator with Zellular AVS on EigenLayer\n\n### Run the Node\n\n1. Create the Docker network (first time only):\n   ```bash\n   docker network create zsequencer_net\n   ```\n\n2. Start your node:\n   ```bash\n   docker compose up -d\n   ```\n\n## Testing\n\n### End-to-End (E2E) Tests\n\nThe project includes end-to-end tests that simulate a network of nodes and allow you to test functionality in a controlled environment.\n\n#### Prerequisites\n\n- Docker and Docker Compose installed\n- Python with `uv` package manager\n\n#### Steps to Run E2E Tests\n\n1. Build the Docker container:\n   ```bash\n   docker compose build\n   ```\n\n2. Run the network simulation:\n   ```bash\n   uv run -m tests.e2e.run start --config tests/e2e/sample_config.json\n   ```\n   This will start a network of nodes based on the configuration in `sample_config.json`.\n\n3. In a separate terminal, run the client to interact with the network:\n   ```bash\n   uv run -m tests.e2e.client --config tests/e2e/sample_config.json\n   ```\n   The client will send example transactions to the nodes in the network.\n\n4. To view logs from all containers:\n   ```bash\n   # Opens a terminal window for each container showing its logs\n   uv run -m tests.e2e.run logs --terminal=gnome-terminal\n   ```\n   Supported terminals: gnome-terminal, xterm, konsole, terminator, tilix\n\n   For individual container logs, use the docker logs command directly:\n   ```bash\n   docker logs -f zsequencer-node-0\n   ```\n\n5. When you're done testing, you can stop all the containers:\n   ```bash\n   uv run -m tests.e2e.run stop\n   ```\n   This will stop and remove all zsequencer node containers that were started.\n\n#### Configuration Options\n\nThe sample configuration file (`sample_config.json`) lets you control:\n- Number of nodes in the network\n- Base port for the nodes\n- Environment variables for all nodes\n- Simulated network conditions, including outages and delays\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzellular-xyz%2Fzsequencer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzellular-xyz%2Fzsequencer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzellular-xyz%2Fzsequencer/lists"}