Crownridge Testing

Status honesty note. This test suite is a necessary condition for mainnet, not a sufficient one. Crownridge has not undergone an external security audit and is not deployed to mainnet. Spec §88 makes an independent smart-contract audit and an external economic/risk review non-negotiable pre-mainnet gates; nothing in this document substitutes for them.

Toolchain: Foundry (forge), Solidity 0.8.30 (pinned), via_ir + optimizer (200 runs), EVM cancun, OpenZeppelin Contracts v5 (pinned). Indexer tests: Vitest + PGlite.

1. Test inventory

All Solidity suites live in contracts/test/. Counts below are per test function, read from the source (each fuzz function additionally runs hundreds of sampled cases — see §3).

Total: 74 test functions + 8 invariant properties = 82 checks. Under the default profile each invariant property is additionally exercised across 16,384 handler calls per suite run (§4).

                    ┌────────────────────────────┐
                    │  fork/ForkRobinhood.t.sol  │  live mainnet: real USDG,
                    │  (3 tests, RH_RPC_URL)     │  real Uniswap v3 bytecode
                    ├────────────────────────────┤
                    │  invariant/Invariants      │  8 properties × 16,384
                    │  + Handler (stateful fuzz) │  randomized calls per run
                    ├────────────────────────────┤
                    │  Deploy.t.sol Timelock.t   │  wiring, hand-off, veto
                    ├────────────────────────────┤
                    │  unit + bounded fuzz       │  63 tests over the full
                    │  (Token/Treasury/Genesis/  │  stack, deployed exactly
                    │  Buyback/Founder/Mint/Acct)│  as production wires it
                    └────────────────────────────┘

Shared fixture

Base.t.sol (CrownridgeBase) deploys and wires the entire stack — token, MintController (address-predicted so the token's immutable minter is exact), Treasury, Genesis, Buyback, LiquidityManager, FounderTreasuryController, Accounting lens — with the same roles and protocol-holder set the production Deploy.s.sol establishes. admin stands in for the TimelockController in logic tests; the timelock's own delay/cancel behavior is covered separately in Timelock.t.sol. Mocks:

• mocks/MockUSDG.sol — mintable 6-decimal ERC-20 standing in for USDG.
• mocks/MockUniV3.sol — MockUniV3Pool (settable tick, TWAP slope, cardinality, liquidity; implements slot0/observe) and MockSwapRouter (delivers CRWN at a settable price), so buyback tests are deterministic. Real Uniswap behavior is validated by the fork suite, not mocked away.

The fixture derives pool ticks via binary search over the real forward quote function (UniV3TwapLib.getQuoteAtTick), so unit tests exercise the true price derivation rather than a parallel reimplementation.

2. Unit tests

Every externally callable function has positive and negative (revert) coverage, asserting the exact custom error where one exists. Representative guarantees, each mapped to the core invariants (CLAUDE.md §3):

Decimal correctness (USDG 6 ↔ CRWN 18) is asserted throughout with explicit raw-unit expectations (e.g. a 10,000e6 USDG deposit at rate 1e18 and 50 bps fee must mint exactly 9_950e18 CRWN and produce navPerToken ≈ 1.005025e18).

3. Fuzz tests (bounded)

Two property-style fuzz tests run inside the standard suite; both bound their inputs to the reachable domain rather than rejecting samples:

• GenesisTest.testFuzz_depositBackingInvariant(uint256 amount) — amount bounded to [minDeposit, cap]. Asserts restated Invariant 2 after every deposit: circulatingSupply ≤ recognizedReserve × 1e12 × rate / 1e18, plus conservationHolds().
• BuybackTest.test_accretionAlwaysHolds_fuzz(uint256 marketUsd, uint256 spend) — market price bounded to [0.30, 0.90] USD/CRWN, spend to [100, 10_000] USDG. If executeBuyback succeeds it must be accretive (navPerToken never decreases); a revert (fail-closed) is always acceptable. This is the executable form of the accretion theorem in docs/ECONOMICS.md.

Configured in foundry.toml: 512 runs per fuzz test by default, 2,000 runs under the ci profile, max_test_rejects = 200000.

4. Invariant suite — 8 properties over a randomized handler

invariant/Handler.sol drives randomized sequences against the fully wired stack with three actor addresses and five actions: deposit (Genesis), founderWithdraw, burn, transfer (occasionally into a protocol holder, to jiggle circulating-supply math), and writeDown. Reverting actions are swallowed (fail_on_revert = false) — a rejected action is not a violation, so the fuzzer keeps exploring the reachable state space. The handler tracks two ghost totals, cumulativeGrossDeposited and totalBurned, that the properties check against.

Default profile: 256 runs × depth 64 = 16,384 randomized calls checked against every property per suite run. CI profile: 512 × 128 = 65,536.

5. Differential / accounting checks

The design rule is a single anchored accounting convention (CrownridgeMath, used identically by Treasury, Buyback, and the replaceable Accounting lens). The tests enforce that no two surfaces can disagree:

• AccountingLensTest.test_viewsMatchTreasury — every lens view (recognizedUSDG, recognizedAssets, usdGBalance, grossAssets, netAssetValue, circulatingSupply, navPerToken, navPerCRWN, liabilities, conservationHolds) equals the Treasury's own primitives, value for value.
• test_backingPerTokenEqualsNav, test_protocolHeldSupply — derived views tie back to primitives.
• GenesisTest.test_quoteMatchesDeposit — the off-chain-facing quote() equals the actual on-chain mint result.
• TokenTest.test_supplyEqualsIssued and invariant_supplyAccounting — the token, the MintController's ledger, and burn history reconcile exactly.
• Buyback accounting is checked by measured deltas, mirroring the contract's own logic: recognizedReserve drops by exactly the USDG spent, supply by exactly the CRWN burned, and navPerToken strictly increases (test_executesBelowThreshold_andBurns).

A TypeScript-vs-Solidity differential NAV recomputation is a planned P4 follow-up (CLAUDE.md §6); by design the SDK and website read navPerToken on-chain rather than recomputing it, so the on-chain convention is the only convention.

6. Fork suite — live Robinhood Chain mainnet

fork/ForkRobinhood.t.sol runs against live Robinhood Chain mainnet (chainId 4663) — real USDG bytecode, real Uniswap v3 deployments, no mocks (spec §133/§163/§164). It gates itself on RH_RPC_URL: when the variable is unset, setUp logs a skip notice and the three tests no-op, so the offline suite stays green.

• test_chainAndUsdgAreReal — block.chainid == 4663; USDG at 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 has bytecode and reports decimals() == 6; the Treasury queries the same.
• test_uniswapContractsAreReal — factory 0x1f7d…2EfA, SwapRouter02 0xCaf6…5cb2, QuoterV2 and NFPM 0x7399…E0D3 all have bytecode; getPool responds without reverting.
• test_realGenesisDepositWithRealUsdg — deploys the protocol on the fork, funds a user with real USDG via Foundry's deal storage cheat (no faucet or counterparty needed), executes a genuine genesis.deposit(10_000e6) through the canonical token, and asserts exact mint output (9_950e18), treasury balance, recognition, conservation, and navPerToken ≈ 1.005025e18.

This proves the verified addresses in CLAUDE.md §2 are real and that the deposit path works end-to-end against the canonical reserve asset — it does not constitute a mainnet deployment.

7. Deploy-path testing

Deploy.t.sol executes the production script/Deploy.s.sol end-to-end (env-driven, against a mock USDG), so the deployment procedure itself is under test, including the script's internal post-deploy assertions. It re-checks the headline guarantees independently: the CREATE-nonce address prediction held (crwn.minter() == mint), the deployer renounced Treasury admin, the timelock holds DEFAULT_ADMIN_ROLE, the security multisig holds the timelock's CANCELLER_ROLE, the buyback is disabled at launch, Genesis holds ISSUER_ROLE, and the founder controller is in CAPPED mode. script/VerifyDeployment.s.sol re-verifies a live deployment from its manifest.

8. Economic-attack coverage

Mapped to the economic attack review required by spec §88/§164:

The founder-withdrawal tests deserve emphasis: test_uncapped_withdrawsUpToReserve demonstrates — deliberately — that in UNCAPPED mode the founder can withdraw the entire recognized reserve, driving NAV to zero without touching CRWN supply. The suite verifies the mechanism behaves exactly as disclosed; it does not (and cannot) remove the trust assumption. See docs/RISK.md.

9. Running the tests

cd contracts

# Everything local: unit + fuzz + invariants (fork tests self-skip without RH_RPC_URL)
forge test

# One suite / one test
forge test --match-path test/Buyback.t.sol
forge test --match-test test_donationDoesNotBrickBuyback -vvv

# Fork suite against live Robinhood Chain mainnet (public RPC is rate-limited; prefer a
# dedicated provider endpoint)
RH_RPC_URL=https://rpc.mainnet.chain.robinhood.com forge test --match-path 'test/fork/*'

# Heavier runs: fuzz 2,000 runs; invariants 512 runs × depth 128 (profile in foundry.toml)
FOUNDRY_PROFILE=ci forge test

# Coverage (informational)
forge coverage

The repo-level runner executes the contract suite and the indexer tests as part of the full check: npm run verify (or npm run verify -- --part contracts).

10. Indexer tests (PGlite)

indexer/test/db.test.ts (5 tests, cd indexer && npm test → Vitest) validates src/db/schema.sql and the exact SQL the server issues against a real Postgres engine — PGlite, Postgres compiled to WASM — so real SQL semantics are exercised with no Docker dependency:

• schema applies idempotently (double-apply must not throw; all four tables exist),
• token amounts are stored as raw integer strings without precision loss (1e24 round-trips, beyond Number.MAX_SAFE_INTEGER — the same no-floats rule the contracts follow),
• event ingestion dedupes on (tx_hash, log_index) (ON CONFLICT DO NOTHING), making re-indexing safe,
• the summary aggregates the API serves compute correctly over NUMERIC amounts,
• alerts (e.g. conservation_breach) are recorded and readable.

Running the same suite against a full Postgres service instance is part of the CI phase (P18).

11. What formal / property verification would add (spec §89)

The invariant suite samples 16,384 execution paths per property per run; formal/property verification (e.g. Certora, Halmos, or SMTChecker) would turn the strongest of these from "unfalsified under fuzzing" into "proven for all inputs". Spec §89 identifies the candidates, most of which already exist here as executable properties:

Additional candidates from this codebase: the accretion theorem (executeBuyback succeeds ⟹ navPerToken non-decreasing) and monotonicity of writeDownRecognized. This work is planned, not done — it belongs alongside the external audit engagement (founder action list, CLAUDE.md §11, item 9).

12. Known gaps

Recorded so they are worked, not forgotten:

• No external audit; no testnet or mainnet deployment has occurred yet.
• TS-vs-Solidity differential NAV recomputation not yet implemented (planned, §5).
• Formal verification not yet performed (§11).
• CI wiring (contracts + indexer + Postgres service) lands in phase P18.
• Fork tests exercise deposits against live USDG; a fork-level buyback against a live CRWN/USDG pool requires a seeded pool and is part of the local anvil-fork stack (npm run stack:up) rather than the forge fork suite.