Swapboard

Trustless OTC bulletin board for ERC20 token swaps on Ethereum.

No admin. No fees. No upgrades. No keys. No backend.

Architecture

contracts/     Solidity smart contract (Foundry)
subgraph/      The Graph indexer
frontend/      Static HTML/CSS/JS
e2e/           Full stack integration tests
docs/          API documentation

Quick Start

Prerequisites

• Foundry
• Node.js v20+
• pnpm
• Docker (required for subgraph and e2e tests)

Build

# Contracts
cd contracts && forge build

# Subgraph
cd subgraph && pnpm install && pnpm build

# Frontend
cd frontend && pnpm install

# E2E (optional)
cd e2e && pnpm install

Test

# Default: contract + subgraph + frontend tests
./test.sh

# Fast: contract tests only (no Docker)
./test.sh --fast

# Full E2E: includes Docker stack with Graph Node
./test.sh --e2e

# All tests including full E2E
./test.sh --all

# Individual test suites
cd contracts && forge test -vvv           # 84 tests
cd subgraph && pnpm test                  # 22 tests (Docker)
cd frontend && node test.js               # 25 tests
cd e2e && npm run e2e                     # Full stack (Docker)

E2E Test Stack

The full E2E tests spin up:

• Anvil (local Ethereum node)
• PostgreSQL (Graph Node storage)
• IPFS (subgraph deployment)
• Graph Node (indexer)

Then execute real transactions, wait for indexing, and verify the frontend displays correct data from the subgraph.

# Manual control
cd e2e
./setup.sh    # Start stack, deploy contract + subgraph
node e2e.test.js  # Run tests
./teardown.sh # Stop stack

Deploy

Automated deployment script handles contract, subgraph, and frontend:

# 1. Configure environment
cp .env.example .env
# Edit .env with your private key, RPC URLs, and Graph auth token

# 2. Deploy everything to Sepolia (testnet)
./deploy.sh sepolia

# Or deploy to mainnet
./deploy.sh mainnet

The script will:

1. Deploy the contract and verify on Etherscan
2. Update subgraph config with contract address and start block
3. Build and deploy subgraph to The Graph Studio
4. Update frontend config with contract address and subgraph URL
5. Upload frontend to IPFS (if ipfs CLI available)
6. Print summary with all addresses and URLs

Partial deployments:

# Skip steps if already done
SKIP_CONTRACT=true ./deploy.sh sepolia    # Reuse existing contract
SKIP_SUBGRAPH=true ./deploy.sh sepolia    # Skip subgraph deploy
SKIP_FRONTEND=true ./deploy.sh sepolia    # Skip IPFS upload

Manual deployment:

See deploy.sh for the individual commands if you prefer manual control.

ENS contenthash (optional):

After IPFS deployment, update ENS contenthash via the ENS manager UI to ipfs://<CID>.

Contract

The Swapboard contract allows:

• createOrder: Deposit tokenA, specify tokenB amount wanted
• fillOrder: Pay tokenB, receive tokenA
• cancelOrder: Maker reclaims tokenA

All operations are atomic. No partial fills. No admin functions.

Security

• Reentrancy protection via OpenZeppelin
• Fee-on-transfer token detection for tokenA
• SafeERC20 for all transfers
• No proxy, no upgrades, no owner

Author

Built by Zak Cole at Number Group for the Ethereum Community Foundation.

License

AGPL-3.0-only