For coding agents, and for people, changing this repository. These are the rules that are easy to break
and expensive to get wrong. How to run everything is in TESTING.md; why things are
shaped this way is in DECISION.md.
- The contract is the only thing that holds money, and the owner cannot move it. Do not add an
owner method that touches a balance.
t16_owner_cannot_move_fundscalls every owner method and checks that balances are unchanged. - Each service key is a function-call key limited to its own methods, listed in
scripts/lib/service-keys.ts: the workeraccept_engagementandsubmit_receipt, the arbiterresolve_claim, the keeperexecute_payoutandregister_signer. A new method a service needs is added there, deliberately. - Never re-serialise model bytes. The request is serialised once, then sent and hashed; the response is kept byte for byte. A receipt's hashes are over those exact bytes, and re-serialising breaks every signature check.
- Recorded fixtures must replay byte for byte. That is why the engagement id is not put in the request bytes. A fixture changes where bytes come from, never whether they are verified.
- Mainnet refuses fixtures and sabotage. Keep that check wherever a new mode or adapter is added.
- One test per threat. Adversarial tests are named
tNN_…to matchTHREAT_MODEL.md, and the judge reads them by that pattern. A new threat gets a row there and a test here. - Amounts are strings in the token's smallest unit, everywhere outside Rust, so JSON never rounds them.
- Rebuilding the contract changes its hash.
contracts/recourse/res/recourse.wasmis pinned byrecourse.wasm.sha256, and judge check 2 fails if they disagree. Rebuild withpnpm build:contract(reproducible) and commit both files. - Every command the README names must exist in
package.json. Judge check 13 enforces it. - The NEAR sandbox runs only on Linux x86_64 and macOS arm64 (
scripts/lib/sandbox.ts). On Windows, usedocker-compose.judge.yml. Graviton and other arm64 Linux hosts cannot run the hosted stack. - One indexer per database. The indexer's SQLite file wants a single writer; never run two against the same store, and never put it on a network file system.
NEXT_PUBLIC_API_URLis inlined when the site is built, not read at runtime. Set it beforenext build, or every visitor's browser calls its own localhost.- Never commit a
.envor a key..env.examplelists every variable with no values, and gitleaks scans the full history in CI.
| To change | Look in |
|---|---|
| Bonds, engagements, claims, slashing, payouts | contracts/recourse/src (bonds.rs, engagements.rs, claims.rs, slashing.rs, payouts.rs) |
| The on-chain receipt check | contracts/recourse/src/tee.rs |
| Sealed-bid underwriting and pricing | contracts/recourse/src/underwriting.rs, pricing.rs; the bidding agents in services/underwriters |
| Contract events | contracts/recourse/src/events.rs (NEP-297, standard recourse) |
| NEAR AI Cloud calls, attestation, receipts | packages/receipts |
| 1Click quotes and status | packages/intents |
| Network IDs, USDC and Sputnik addresses, defaults | packages/config |
| The worker, the arbiter and its rubric | services/worker-agent, services/arbiter |
| Payout execution and refunds | services/keeper |
| The REST API | services/indexer/src/api.ts, documented in docs/api.md |
| The site | apps/web |
| The seven scenarios and the judge | demo/run-demo.ts, scripts/judge.ts |
| Hosting | docker-compose.yml, scripts/hosted-sandbox.ts, infra/aws |
Before calling a change done, run npm run judge (or the clean-room version) and read the table.