Bountiful is an on-chain bug bounty platform for the Fe programming language. It deploys Fe smart contracts that should uphold certain invariants. If a bounty hunter can break those invariants — by exploiting a bug in the Fe compiler or the contract logic — they can claim ETH prize money permissionlessly, directly from the contract.

Four different implementations of the 15 puzzle game, each initialized to an unsolvable board state. Each variant exercises different Fe language features:

All game contracts implement the ISolvable interface (isSolved() -> bool).

Unlike typical production smart contracts, Bountiful's challenges are intentionally not optimized for efficiency or gas usage. Instead, they are designed to:

1. Maximize attack surface: Use a wide variety of Fe language features (enums, nested arrays, bitpacking, storage maps, etc.) to expose potential compiler bugs.
2. Increase complexity: Implement logic in ways that exercise different parts of the Fe type system and code generation (e.g., searching for the empty cell on every move instead of storing its index).
3. Encourage exploration: Provide multiple paths (arithmetic, storage, control flow) for hunters to find exploits.

The goal is to provide a "stress test" for the Fe compiler across various idiomatic and non-idiomatic coding patterns.

• Contracts: Fe (primary) + Solidity (interfaces, deployment, tests)
• Build & test: make + Fe compiler + Foundry (forge)
• Network: Ethereum mainnet
• Website: Zola static site generator

contracts/           Fe workspace (3 ingots)
  ingots/registry/   BountyRegistry contract
  ingots/games/      Four 15-puzzle implementations
  ingots/shared/     Shared types, errors, constants
src/                 Solidity interfaces + FeDeployer helper
test/                Foundry test suite
script/              Foundry deployment script
web/                 Zola-based website with interactive puzzle
Makefile             Central build process

git clone https://github.com/cburgdorf/bountiful.git
cd bountiful

make build

make test        # runs Fe tests + Forge tests (builds Fe first)
make test-fe     # Fe tests only
make test-forge  # Forge tests only (builds Fe first)

export DEPLOYER_PRIVATE_KEY=0x...
export MAINNET_RPC_URL=https://...
export LOCK_DEPOSIT=10000000000000000  # optional, defaults to 0.01 ETH
forge script script/Deploy.s.sol --rpc-url $MAINNET_RPC_URL --broadcast

make docs              # generate API docs (docs.json, fe-web.js, index.html)
cd web && zola serve

Ethereum is a dark forest — any profitable transaction can be front-run by MEV bots. Bountiful uses a per-challenge locking mechanism to prevent this:

1. Find an exploit locally — attack the contracts on your own machine first.
2. Acquire a lock — call registry.lock(challengeAddress) and pay the lock deposit. This gives you exclusive access to that challenge for 100 blocks.
3. Wait a few blocks — let your lock settle to be safe.
4. Solve the challenge — replay your exploit on-chain. No one else can interact with the locked challenge.
5. Claim the prize — call registry.claim(challengeAddress). The registry verifies the challenge is solved and transfers the prize money.

When a challenge is not locked, the admin can withdraw funds. This is used to migrate to newer versions of the system.

# Via the registry contract's withdraw() function

The admin can register new challenge contracts or remove existing ones (when unlocked) through the BountyRegistry contract.

• Bounty Hunting Guide — Step-by-step walkthrough for finding exploits and claiming prizes
• AGENTS.md — Structured reference for AI agents hunting bounties