Skip to content

SPEC.md

Latest commit

 

History

History
59 lines (47 loc) · 4.34 KB

SPEC.md

File metadata and controls

59 lines (47 loc) · 4.34 KB
Raw

Overview

  • This project is called bee-factory.
  • It is a CLI tool written in TypeScript/Node.js (requires Node.js ≥ 18), distributed as an npm package (npx @ethersphere/bee-factory).
  • Its purpose is to run a local stack of Bee nodes for Ethereum Swarm development.
  • A Bee node is the official Swarm client implementation.
  • The tool uses Docker to run Bee nodes and a local blockchain to simulate the Ethereum network.

CLI

  • bee-factory start — starts the local stack using the bundled Anvil snapshot for fast boot (contracts and funded wallets are restored; no redeployment).
  • bee-factory start --fresh — ignores the snapshot, redeploys all contracts from scratch, funds wallets, and saves a new snapshot for future fast starts.
  • bee-factory start --tag <ref> — builds Bee from a specific git ref (branch, tag, or commit; default: master). If the corresponding bee-factory/bee:<ref> image already exists locally, the build is skipped.
  • bee-factory stop — stops and removes all containers and the Docker network.
  • Every bee-factory start must begin by removing any existing bee-factory containers and the Docker network (clean slate).

Bee Nodes

  • The tool must always run exactly 5 Bee nodes, all running as full nodes (not ultra-light or light).
  • Bee nodes must be built from source with REACHABILITY_OVERRIDE_PUBLIC=true baked in at compile time (it is a Go linker flag passed to make binary, not a runtime env var). The tool clones the official https://github.com/ethersphere/bee.git repository to a temporary directory, builds via Dockerfile.dev with --build-arg REACHABILITY_OVERRIDE_PUBLIC=true, and tags the result as bee-factory/bee:<ref>. The build is skipped on subsequent starts if the image already exists locally.
  • Bee node keys must be fixed, pre-baked private keys.
  • The tool must generate an Ethereum V3 keystore file (swarm.key) for each node from its pre-baked private key, encrypt it with the fixed password bee-factory, store it under /tmp/bee-factory/keys/bee-{n}/, and mount that directory into the container.
  • The node at API port 1633 is the "queen" (main) node; the other four are worker nodes that connect to it to build topology.
Node API port P2P port
queen 1633 1634
worker 1 1635 1636
worker 2 1637 1638
worker 3 1639 1640
worker 4 1641 1642

Blockchain

  • The local blockchain must use Anvil (Foundry), exposed on port 8545, with chain ID 1337 and a 5-second block time.
  • A dedicated Docker bridge network must be created so containers can reach each other by hostname.

Smart Contracts

  • The required contracts are: BzzToken, PostageStamp, PriceOracle, StakeRegistry, Redistribution, SimpleSwapFactory, and SwapPriceOracle.
  • Smart contract artifacts (ABI + bytecode) must be bundled with the npm package.
  • A bundled Anvil state snapshot (contract deployments + funded wallets) must also be included in the npm package so that bee-factory start (without --fresh) can restore state instantly.
  • When deploying from scratch, contracts must be deployed programmatically, followed by role grants and initial configuration:
    • Grant PRICE_ORACLE_ROLE on PostageStamp to PriceOracle (so it can call setPrice).
    • Grant REDISTRIBUTOR_ROLE on PostageStamp to Redistribution.
    • Grant REDISTRIBUTOR_ROLE on StakeRegistry to Redistribution.
    • Grant PRICE_UPDATER_ROLE on PriceOracle to the deployer, then call setPrice with an initial non-zero value so Bee nodes can read a valid price immediately.
  • Each node must be funded with 1 ETH and 100 BZZ tokens. BZZ uses 16 decimals.

Startup Sequence

  1. Remove all existing bee-factory containers and the Docker network.
  2. Start Anvil; wait for its RPC to be ready.
  3. Restore contracts and funded wallets from the bundled snapshot (or deploy and fund from scratch if --fresh).
  4. Generate keystore files for all nodes.
  5. Start the queen node; wait for its API to respond.
  6. Fetch the queen's underlay address from its /addresses API endpoint.
  7. Start each worker node with --bootnode set to the queen's underlay address; wait for each API to respond.
  8. Wait for all nodes to report isWarmingUp: false via their /status endpoint before declaring the stack ready.