A gas-efficient, merkle-based vesting system using OpenZeppelin's VestingWallet contracts.
Instead of deploying all vesting contracts upfront (expensive for large allocations), this system:
- Setup: Store a merkle root of all vesting allocations + total tokens
- Claim: Users provide merkle proof to claim their allocation
- Deploy: Each claim deploys an OpenZeppelin
VestingWalletCliffvia CREATE2 - Vest: Users call
release()on their wallet to withdraw vested tokens
- Gas Efficient: Issuer pays constant cost regardless of recipient count
- Scalable: Supports unlimited recipients (limited only by merkle tree depth)
- Standard: Uses battle-tested OpenZeppelin contracts
- Predictable: CREATE2 enables pre-computing wallet addresses
- Flexible: Support for cliff + linear vesting schedules
| Package | Description |
|---|---|
packages/contracts |
Solidity smart contracts (Foundry) |
packages/indexer |
Ponder-based blockchain indexer |
packages/merkle-server |
Merkle tree API server with safety features |
- Node.js >= 18
- pnpm 9.x
- Foundry (for contracts)
# Install dependencies
pnpm install
# Install Foundry dependencies
cd packages/contracts && forge install# Build contracts
pnpm contracts:build
# Test contracts
pnpm contracts:test
# Start local Anvil node
pnpm anvil
# Seed local deployment
pnpm seed
# Seed a deployment that exercises the platform fee wrapper
pnpm seed:fee
# Run indexer (development)
pnpm indexer:devMerkleVestingFactory
└── creates MerkleVestingDeployer (one per vesting campaign)
└── deploys VestingWalletCliff (one per recipient on claim)
See docs/ for detailed documentation:
- Plans - Implementation plans and roadmaps
- Learnings - Development insights and logs
- Reference - Technical reference materials
- Platform Fee - Guidance on the optional fee wrapper
- Architecture - System design docs
- Decisions - Architecture decision records
- Double-claim prevention via claimed mapping
- Merkle proof validation using OpenZeppelin MerkleProof
- CREATE2 determinism with beneficiary in salt
- Claim deadline with sweep for unclaimed tokens
- Reentrancy protection
Dennison Bertram [email protected]
Built for Tally - Onchain Governance
MIT