Validator Bonds
Solana monorepo for Validator Bonds — an on-chain protocol where validators post bonds as collateral
for Marinade stake. Settlements distribute SOL to stakers affected by protected events (PSR) or
validator bidding.
Key data flow: snapshot → bid-distribution CLI → settlement JSON → merkle trees → on-chain
settlements → claims.
Installation
Requires: Rust toolchain 1.88.0 (see rust-toolchain.toml), Node ≥ 20.18.0, pnpm.
pnpm install # TypeScript deps
cargo build # Rust workspace (debug)
Usage
# Public-facing CLI
pnpm cli --help
# Institutional CLI
pnpm cli:institutional --help
# Settlement sanity check
pnpm cli:check --help
# Collect on-chain bond data to YAML
cargo build --release
./target/release/bonds-collector collect-bonds -u "$RPC_URL" > bonds.yaml
# Store bonds YAML to Postgres
./target/release/validator-bonds-api-cli \
store-bonds --postgres-url "$POSTGRES_URL" --input-file bonds.yaml
# Run the bonds API server (port 8000)
./target/release/api \
--postgres-url "$POSTGRES_URL" \
--postgres-ssl-root-cert "$POSTGRES_SSL_ROOT_CERT"
Build & Test
pnpm build # anchor:build + all TS packages
pnpm check # lint (cargo + TS)
pnpm fix # auto-fix formatting + clippy
cargo test --features no-entrypoint -- --nocapture # Rust unit tests
pnpm test:unit # TS unit tests
pnpm test:bankrun # bankrun integration tests
FILE=path/to/test.spec.ts pnpm test:bankrun # single bankrun file
pnpm test:validator # anchor test (full, slow)
# After on-chain program changes — sync IDL to SDK and resources
pnpm copy:idl
Simulation & Regression
# Regression test against production GCS data
./scripts/regression-test-settlements.sh \
--start-epoch 918 --end-epoch 918 --data-dir ./regression-data
# Fee simulation across tiers — writes YAML report
bun scripts/simulate-fee.ts [-r] [-v] [-c] [-d DIR] <epoch|start-end> [-m <min_fee>] [<max_fee>]...
Scripts in scripts/ use #!/usr/bin/env bun.
Epoch Pipeline
Automated via .buildkite/ pipelines, staged in GCS
marinade-validator-bonds-mainnet/<epoch>/:
scheduler-bidding → prepare-bid-distribution → init-settlements
→ fund-settlements → claim-settlements → close-settlements
Contract Audits
Agent skills
Protocol context skills live in plugins/validator-bonds/.
See the plugin README for full install instructions.
Claude Code (add marketplace once, then install):
claude plugin marketplace add marinade-finance/validator-bonds
claude plugin install validator-bonds@marinade-finance
Codex:
codex plugin add marinade-finance/validator-bonds
From this repo, no install needed — Codex auto-loads .agents/skills.
Further Reading
