Skip to content

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) whose setUp builds the snapshot: pool manager, tokens, the hook at a flag-valid address, and any positions. Pin block_number and block_timestamp in foundry.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#

jsonjobs/scheduled-exit-fee/job.json
{
  "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.

shellWith PROBE_SPONSOR_KEY and RPC_URL set
probe sponsor keygen
probe sponsor create --spec job.json --token <stablecoin> --reward 250 --budget 5000 --days 30

You 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.