Sponsor guide
Write a job, fund it on-chain, register it with the verifier, and read private reports.
A job is a Foundry workspace plus a JSON spec. The spec's hash is committed on-chain when you fund the job, so operators and the verifier work from exactly what you published.
1. Build the workspace#
- A Foundry project containing your hook source and its dependencies.
- A fixture contract (for example
ProbeCase) whosesetUpbuilds the snapshot: pool manager, tokens, the hook at a flag-valid address, and any positions. Pinblock_numberandblock_timestampinfoundry.toml. - Helper functions in the fixture for the actions you want tested, so cases stay short.
- A few seed cases, so operators without an AI agent can still run the job.
The verifier forces ffi off and removes file and network access whatever your config says.
2. Write the spec#
{
"slug": "scheduled-exit-fee-withdrawals",
"title": "Withdrawals around a scheduled exit-fee change",
"summary": "Replay full and partial liquidity withdrawals against a Uniswap v4 hook that charges an exit fee scheduled to change from the next block.",
"objective": "Show whether a liquidity provider can be charged an exit fee different from the fee the hook declares for the block they withdraw in.",
"inScope": [
"afterRemoveLiquidity on the job's pool, full and partial withdrawals",
"Exit-fee changes made through scheduleFee, in the same block or earlier blocks",
"The declared fee returned by feeForBlock"
],
"outOfScope": [
"The Uniswap v4 PoolManager and periphery contracts themselves",
"Owner key compromise",
"Gas griefing without a balance effect"
],
"acceptanceRules": [
"The case inherits the job fixture and reproduces on the pinned snapshot with no extra state.",
"The case asserts a concrete balance or fee outcome.",
"A case is a duplicate if its execution path through the hook matches an accepted case.",
"Cases that read wall-clock time, randomness, the network, files or environment variables fail verification.",
"Cases may not rewrite contract code or storage."
],
"network": { "id": "local", "name": "Local test chain" },
"hook": { "name": "ScheduledExitFeeHook", "callbacks": ["afterRemoveLiquidity"] },
"snapshot": {
"id": "exit-fee-snap-4812330",
"block": 4812330,
"note": "Foundry fixture pinned to block 4,812,330 and a fixed timestamp: a v4 PoolManager, two tokens, the hook at a flag-valid address, and one LP position."
},
"workspace": { "path": "jobs/scheduled-exit-fee" },
"fixture": { "base": "ProbeCase", "import": "../ProbeCase.sol" },
"targets": ["src/ScheduledExitFeeHook.sol"],
"allowedImports": ["forge-std/", "v4-core/", "solmate/"],
"seedCases": "seed-cases",
"rewardModel": "findings-and-coverage",
"reward": {
"headline": "Paid per accepted case",
"detail": "Each new execution path through the hook that reproduces and asserts an outcome is paid once."
},
"sponsor": "PROBE example sponsor"
}Fields that matter most#
- targets
- Source files whose line and branch coverage defines a case's execution path.
- fixture
- The base contract every case must inherit, and the import path cases use.
- acceptanceRules
- Shown to operators and the agent. Write them as checks someone else could apply.
- rewardModel
- findings, coverage, or findings-and-coverage. Coverage jobs require a branch no accepted case reached.
- reportKey
- Your X25519 public key. Added automatically by probe sponsor create if you ran probe sponsor keygen.
3. Fund and register#
Funding creates the job on-chain with its full budget, reward per accepted case, deadline and optional holding requirement. Registration sends the spec to the verifier, signed by the funding wallet; the verifier checks it against the on-chain hash before accepting it.
probe sponsor keygen
probe sponsor create --spec job.json --token <stablecoin> --reward 250 --budget 5000 --days 30You can also do this from the sponsor app with your wallet.
4. Read private reports#
Every accepted case and its full trace are sealed to your report key. Download and open them with probe sponsor reports <job>. Only your key can open them; keep it safe and backed up.
5. Close the job#
After the deadline, the funding wallet can close the job and reclaim the unallocated budget. Rewards operators already earned stay claimable.