APIbase Receipt Attest — a GenLayer Intelligent Contract
Validators attest that an APIbase paid-call receipt matches the USDC transfer on Base.
What it is. ApibaseReceiptAttest (contracts/apibase_receipt_attest.py) reads one public JSON
receipt published by APIbase for a paid tool call, asks a configured Base JSON-RPC node for the
transaction that receipt names, and records PASS, FAIL or NOT_FOUND. GenLayer's leader/validator
consensus replaces a single process's word with several independent fetches.
Beside it sit two dispute contracts, one per closed claim, both REFUND / RELEASE witnesses:
ApibaseReceiptDispute (contracts/apibase_receipt_dispute.py, claim upstream_failed_but_billed, reads
the receipt only) and ApibasePaymentDispute (contracts/apibase_payment_dispute.py, claim
paid_without_receipt, reads APIbase's index and Base). They are described in The refund policy and the
two claims; the rest of this file describes the attest unless it says otherwise.
What it is not. There is no LLM in it. It never makes a paid call and never spends anything. It
does not judge the tool's response, only that the payment the receipt claims is the payment on the
chain. It covers one rail and billed calls only (see v0 limits). It does not take part in Provek's
scoring and shares no code with src/.
The use case, in three sentences. An agent pays APIbase for a tool call and gets a receipt that
says who paid whom, how much, and in which Base transaction. Anyone — the agent, its operator, an
auditor — can ask the contract about that receipt id, with no account and no permission. The answer is
a consensus-backed record that the receipt and the chain agree, or that they do not.
Where this code lives. The source of record is integrations/genlayer-apibase-attest/ in
whiteknightonhorse/provek,
where Provek's gates check it (D-66, beside D-63 for the first contract). The same directory is published, with its
history, as whiteknightonhorse/apibase-genlayer-attest — a read-only mirror made with
git subtree split (the procedure is D-64's). The mirror is never edited directly: every change enters Provek and is
re-split (D-64, second mirror). The deployed contract is this directory's contracts/apibase_receipt_attest.py as committed at
11474b4 (D-67). Paths such as DECISIONS.md, docs/adr/ and evidence/* refer to the root of the Provek
repository.
APIbase Receipt Attest — live on Bradbury Phase 2
ApibaseReceiptAttest (integrations/genlayer-apibase-attest/) is deployed on the GenLayer test network, test GEN only. One real
APIbase receipt has been attested there; the record is readable by anyone with get_attestation.
| |
|---|
| Contract | 0x1bD4C0EBC9b365905d4EBC84b944d861499afe6E |
| Explorer | https://explorer-bradbury.genlayer.com/address/0x1bD4C0EBC9b365905d4EBC84b944d861499afe6E |
| Page | https://apibase.pro/attest/ (APIbase's page for this contract; APIbase moves it to this address when its promotion goes live) |
| Network | GenLayer testnet Bradbury Phase 2 (chain 4221), RPC https://rpc-bradbury.genlayer.com; deployed 2026-10-28 from commit 11474b4 after GenLayer reset the testnet on 2026-10-24 (the earlier deployment died with the reset; its entry is kept in deploy/deployment.json, previous_deployments) |
| Rail configured | set_chain("8453", ...): Base mainnet, https://mainnet.base.org, USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
Live records, as of 2026-10-28 (read back with list_by_receipt and get_attestation; every field and transaction in
deploy/deployment.json and evidence/MEASURED-019-*, the deploy and the write in evidence/MEASURED-017-*):
| result | receipt id | observation | attested at (UTC) |
|---|
| PASS | 9dbc77f9fd66bcb8714cd064f5681005 (myvariant.search, 1000 atomic USDC) | payment_matches | 2026-10-28T09:30:52Z |
Not measured: a live FAIL or NOT_FOUND record (none was requested), and a studionet integration run for this contract.
The deployment record is deploy/DEPLOYMENT.md.
Dispute contracts — live on Bradbury Phase 2
Deployed 2026-11-09 from commit 9055f93 (runner babwp, header # v0.3.0), policy 2026-11-04.3 pinned; test GEN only.
0 disputes as of 2026-11-09 (none submitted in the deployment session; list_recent not read).
Every field is in deploy/deployment.json (dispute_contract) and deploy/DEPLOYMENT.md; the transcripts are evidence/MEASURED-021-* and -022-*.
The receipt: apibase-receipt/1
The contract fetches {receipt_base_url}{receipt_id}.json. receipt_id is 32–64 lowercase hex
characters. The document, as the contract reads it (a concrete instance, with a real transaction hash, is
tests/fixtures/receipt_pass.json; the repository secret scan excludes that one fixtures directory
because a transaction hash has the shape of a raw key):
{
"schema": "apibase-receipt/1",
"rail": "x402-base",
"chain_id": 8453,
"payment_tx": "0x<64 hex characters>",
"payer": "0x688130810f0bede38742b66e7a443274c01d4213",
"payee": "0x781dfd3f2687f8e5656313b2179fdefdf99d339d",
"asset": "USDC",
"amount_atomic": "1000000",
"billed": true,
"tool": "example.tool",
"upstream_status": 200,
"response_sha256": "<64 hex characters>"
}
Validation is strict: schema must be exactly apibase-receipt/1; chain_id and upstream_status
integers; payment_tx 0x plus 64 hex; payer and payee 0x plus 40 hex (stored lowercased);
asset exactly USDC; amount_atomic a decimal string (USDC has six decimals, so 1000000 is 1 USDC);
billed a boolean; response_sha256 64 hex. The first key that fails is named in the revert.
Receipts publish payer, payee, amount, transaction and the SHA-256 of the response — never the response.
The judge
One function, _judge, is called by the leader, by every validator and by attest() after
consensus. transfers are the Transfer(address,address,uint256) logs emitted by the configured
chain's USDC contract inside the transaction; amounts are compared as integers.
| Observation | Outcome | Record result / observation |
|---|
| Receipt fetch failed, or HTTP status ≠ 200, or the RPC answered with an error | revert receipt <id> is not readable at APIbase (http=<n>) | none |
| Receipt malformed | revert … not attestable by this contract: malformed receipt: <key> | none |
rail ≠ x402-base | revert … unsupported rail <rail> | none |
billed is not true | revert … not billed | none |
chain_id not configured | revert … chain <id> not configured | none |
Node returns null for the transaction | recorded | NOT_FOUND / tx_not_found |
| Transaction status ≠ 1 | recorded | FAIL / tx_reverted |
A transfer equals [payer, payee, amount] | recorded | PASS / payment_matches |
| Transaction succeeded, no such transfer | recorded | FAIL / no_matching_transfer |
A validator agrees iff its own whole observation equals the leader's (receipt, receipt_sha256,
chain_found, tx_status, transfers): every input is immutable by design, and the record is built
from all of it. Verdict-only agreement was incomplete in the design (GL-00 ruling-2), not a build
defect; the Portal steward rejected it on 2026-10-23 (D-76). A validator whose own fetch raises
votes False and no verdict is made: nobody could check is not the same as the claim being false
(CLAUDE.md invariant 1, named in the contract's docstring). NOT_FOUND, FAIL and a revert are three
different things on purpose.
Interface
__init__(operator, receipt_base_url); the URL must be http(s) and end in /.set_chain(chain_id, rpc_url, usdc) — operator only; usdc is stored lowercased.attest(receipt_id) -> attest_id — permissionless (D-66). attest_id is
sha256(json([receipt_id, checked_at, sender])); the same sender asking in the same block time reverts as a duplicate.- Views:
get_attestation(attest_id), list_by_receipt(receipt_id) (JSON list, [] default),
get_chain(chain_id), get_config() (JSON: operator, receipt base URL, configured chain ids).
- The record (
Attestation) carries receipt_id, receipt_sha256, rail, chain_id, payment_tx,
payer, payee, amount_atomic, tool, upstream_status, billed, response_sha256, result,
observation, checked_at, requester.
The refund policy and the two claims
Two further contracts decide whether APIbase should refund a paid call. Each decides ONE claim, so that
each file stays small enough for D-67's 19 000 B rule (a single file for both claims measured 25 331 B;
D-80). Both pin the published refund policy in storage (set_policy(version, sha256), operator only; a
dispute while no policy is pinned reverts refund policy not published) and copy that pair into every
record, so a verdict names the policy text it was decided under. Validators recompute the claim from
published documents; there is no LLM and no judgement call.
A verdict never pays by itself. REFUND is an instruction to APIbase's refund worker, which recomputes the same rule, pays within the published window under its own caps, and publishes refunds/<dispute_id>.json; the refund is verifiable on Base from that document (on-chain confirmation, confirm_refund, is v1.1). Bradbury is a test network; the verdict moves real USDC only through that capped worker.
| claim | contract | recomputed from | REFUND when | RELEASE reasons (also in the record) | revert, nothing written |
|---|
upstream_failed_but_billed | ApibaseReceiptDispute.dispute_receipt(receipt_id) | the receipt {receipt_base_url}{receipt_id}.json | billed and upstream_status >= 500, and no earlier REFUND for the same payment_tx | not_billed; upstream_status_<n> (n < 500); refund_verdict_exists:<dispute_id> | receipt not readable, malformed (malformed receipt: <key>), unsupported rail |
paid_without_receipt | ApibasePaymentDispute.dispute_payment(chain_id, payment_tx) | the index {receipt_base_url}by-tx/<tx>.json, then the transaction on Base | the index lists no receipt and no refund, no earlier REFUND for the tx, the transaction succeeded and carries a USDC transfer to the chain's configured payee (the first such transfer fixes payer and amount_atomic) | already_refunded; receipt_exists:<id>; refund_verdict_exists:<dispute_id>; tx_not_found; tx_reverted; no_payment_to_apibase | index not readable (HTTP ≠ 200 or any shape but the published one), RPC failure, chain not configured |
An index that cannot be read is unmeasured, not "no receipt": the call reverts and writes nothing.
The sibling-URL contract. Receipts stay byte-immutable, so refund state lives at sibling URLs of the
receipt base, never inside a receipt and never in a verdict record:
by-tx/<tx>.json — always answers 200 for a well-formed transaction hash:
{"schema": "apibase-receipt-index/1", "payment_tx": "<tx, lowercase>", "receipt_ids": [...], "refund_tx": "0x…" | null}.
Any other status or shape is an unreadable index.refunds/<dispute_id>.json — written once by the refund worker, after it paid:
{"schema": "apibase-refund/1", "dispute_id", "refund_tx", "chain_id", "to", "amount_atomic"}.
Nothing in these contracts reads it yet.
refund_verdicts (payment_tx → dispute_id of the first REFUND) is kept per contract: a second REFUND
on the same payment_tx becomes RELEASE / refund_verdict_exists:<id>. A claim-1 REFUND and a claim-2
REFUND for one payment are excluded by the index (a payment with a receipt gets receipt_exists); the
residual case, a receipt published after a claim-2 REFUND and then disputed under claim 1, is stopped
by the refund worker's one-refund-per-payment_tx ledger.
Interface, both contracts: __init__(operator, receipt_base_url); set_policy(version, sha256)
(operator only); get_dispute(dispute_id), list_by_subject(receipt_id | payment_tx) (JSON list, []
default), list_recent() (JSON list of the last 200 dispute ids, newest last), get_config() (JSON:
operator, receipt base URL, policy version and sha-256; the payment contract adds the configured chain
ids). Receipt contract: dispute_receipt(receipt_id) -> dispute_id, permissionless;
dispute_id = sha256(json(["receipt", receipt_id, checked_at, sender])). Payment contract:
set_chain(chain_id, rpc_url, usdc, payee) (operator only; payee is APIbase's receiving wallet on that
chain, stored lowercased), get_chain(chain_id), dispute_payment(chain_id, payment_tx) -> dispute_id,
permissionless; dispute_id = sha256(json(["payment", chain_id, payment_tx, checked_at, sender])).
The record (Dispute, byte-identical in both files, immutable once written) carries dispute_id,
claim, receipt_id (empty for a payment claim), chain_id, payment_tx, payer, payee,
amount_atomic, policy_version, policy_sha256, verdict, reason, evidence_sha256 (the receipt's
or the index's SHA-256), checked_at, requester.
The validators of both contracts vote by whole-observation equality, as the attest does (D-76); a
validator whose own fetch fails votes False. test_dispute_shares_attest_helpers proves the helpers
(_validate_receipt, _error_observation, _rpc_request_body, _parse_transfers, _observe_rpc) are
verbatim copies of the attest's, because a GenVM contract is one file and cannot import another.
Not deployed yet: deployment from the merged commit's bytes is a later, separate step (D-67).
Commands
Run from this directory, with the isolated Python 3.12 toolchain of D-63 (the door uses ~/orchestra/glenv-babwp, with GENVM_VERSION=v0.6.0-rc10, GENVM_ALLOW_PRERELEASE=1):
The contract's version line # v0.3.0 must be line 1, with the # { "Depends": "py-genlayer:babwp9t3…" } line second (why): Bradbury Phase 2 runs the babwp runner as of 2026-10-28, and the documentation's 1jb45… id fails there (D-79).
python3 scripts/check_genvm_lint.py # genvm-lint check on all three contracts, with the named E014 warnings
python3 -m pytest tests/direct -v # direct-mode tests: mocks only, no network
gltest --network studionet tests/integration # live; skipped unless ATTEST_CONTRACT and APIBASE_RECEIPT_ID are set
genvm-lint check itself has no allowlist, so scripts/check_genvm_lint.py runs it with --json, once per
contract, and demands that the warning set be exactly the known false positives: the linter (0.11.1rc2) only
knows the v0.2 storage decorator name allow_storage, so it reports the classes decorated with the v0.3.0
gl.storage.allow as E014 - ChainConfig (line 40) and Attestation (line 50) in the attest, Dispute
(line 37) in apibase_receipt_dispute.py, ChainConfig (line 37) and Dispute (line 47) in
apibase_payment_dispute.py; its SDK-semantic validation, which builds the real schema, passes. Any other
shape is red.
tests/fixtures/rpc_receipt_real_base_usdc.json is a real eth_getTransactionReceipt answer from
https://mainnet.base.org (transaction 0xa7055e5e…bf58, block 52589696): two logs, one of them a USDC
transfer of 1 USDC; test_parse_transfers_golden_vector parses it.
v0 limits
- One rail:
x402-base. An MPP/Tempo receipt is refused (unsupported rail), not attested.
- Billed calls only:
billed: false is refused (not billed).
- One asset: USDC, at the address configured per chain.
- Receipts are fetched, not signed: the contract trusts neither the receipt nor the chain alone; it
checks that they agree. A receipt APIbase never published is
not readable.
- It attests payment, not service:
response_sha256 and upstream_status are copied into the
record for whoever holds the response; the contract does not see it.
- Disputes: the same one rail and one asset, and two closed claims only.
response_mismatch (the
response differs from what was promised) and double_billed are deliberately absent: they cannot be
recomputed from a published document, and a witness that guesses is not a witness. Verdict records are
immutable; refund confirmation on chain is a later contract (v1.1).
The RPC trust assumption
Every validator asks the same JSON-RPC URL, held in storage per chain id and replaceable by the
operator alone with set_chain. The contract therefore proves "the configured node says so". An
operator who points a chain at a node that lies can make it attest a transfer that did not happen.
The URL is public (get_chain), which makes the assumption auditable; letting each validator choose its
own node would remove it and is a different, later design. At deployment the Base endpoint is
https://mainnet.base.org. ApibaseReceiptDispute makes no such assumption: it asks no chain, only
APIbase's own receipt document; ApibasePaymentDispute makes it exactly as the attest does.
ApibaseReceiptAttest — contract reference
The contract file keeps short docstrings (gas, see the last paragraph of this section). The text below is the original
documentation from commit 774a184, verbatim.
Narrative
APIbase Receipt Attest — a GenLayer Intelligent Contract.
WHAT THIS IS. A consensus-backed check that an APIbase paid-call receipt tells the truth about the
money. APIbase publishes, for each paid tool call, a small JSON receipt (`apibase-receipt/1`, see
README.md) that names a payer, a payee, an amount of USDC and the Base transaction that moved it.
Anyone may ask this contract about a receipt id (`attest(receipt_id)`); the leader fetches the
receipt from `receipt_base_url`, asks the configured Base JSON-RPC for that transaction's receipt,
and reports whether the chain holds a USDC `Transfer(payer -> payee, amount)` inside it. Validators
repeat both fetches themselves and agree only if they saw the same thing. The verdict is written
to storage as an `Attestation` nobody can edit afterwards.
WHAT THIS IS NOT. There is no LLM anywhere in this contract. It never makes a paid call to APIbase
and never spends anything: it reads one static JSON document and asks a chain node for one
transaction receipt. It does not attest that the tool's response was good, only that the payment
the receipt claims is the payment on the chain; `response_sha256` is carried into the record so a
holder of the response can check it themselves, nothing more. v0 covers ONE rail (`x402-base`) and
BILLED calls only (`billed is true`); an MPP/Tempo receipt, or a call that was not billed, is
refused with a named reason rather than attested as something it is not.
TRUST ASSUMPTION, STATED. The chain is reached through ONE JSON-RPC URL per chain id, held in
storage and updatable by the operator alone (`set_chain`). Every validator asks that same URL, so
the contract proves "the configured node says so", not "the chain says so": an operator who points
`rpc_url` at a node that lies can make the contract attest a transfer that did not happen. The
URL is public (`get_chain`) so the assumption is auditable; removing it would mean validators each
choosing their own node, which is a different and later design.
WHY A CUSTOM VALIDATOR, NOT `strict_eq`. `strict_eq` compares the leader's whole output to the
validator's byte for byte. The receipt observation carries fields that can legitimately differ
between two honest nodes reading the same chain (a log list that includes unrelated contracts'
events, RPC extras) and, worse, it cannot distinguish "the validator saw something different" from
"the validator could not see anything". `_judge` below is the one deterministic function leader
and validator both call, so the verdict rule lives in exactly one place; the validator agrees iff
its whole observation equals the leader's, because the record is built from all of it (D-76).
CONSENSUS SEMANTICS, NAMED EXPLICITLY. Three different outcomes must not be confused
(CLAUDE.md invariant 1: a missing measurement is never a pass, and never silently a fail):
* `FAIL` means the instrument worked and the claim is false: the transaction exists but reverted
(`tx_reverted`), or it succeeded and holds no matching USDC transfer (`no_matching_transfer`).
* `NOT_FOUND` means the node answered and does not know the transaction (`tx_not_found`). It is
recorded, not hidden: a payment that the configured node cannot see is evidence of its own.
* A revert (no record) means there is nothing to attest: the receipt is not readable at APIbase,
or it is a shape this v0 contract refuses (`unsupported rail`, `not billed`, `chain not
configured`, `malformed receipt`). Nobody is told "the payment is false" about a receipt that was
never in scope.
Separately, a validator whose OWN fetch raises returns `False` without constructing any verdict:
"nobody could check" must not be turned into "the claim is false", and GenVM rotates the leader.
FIELD NAME NOTE. `genlayer.gl.nondet.web.Response` has `status`, not `status_code` (the same
finding as the witness contract next door; running its direct tests against the pinned SDK is
what showed it). This contract uses `response.status`.
Storage
See the module docstring. Storage: `operator` (fixed at construction), `receipt_base_url`
(receipts live at `{receipt_base_url}{receipt_id}.json`), `chains` (chain id -> `ChainConfig`,
operator-updatable), `records` (attest_id -> `Attestation`, append-only), `index`
(receipt_id -> JSON list of attest_ids; a list inside a `TreeMap` is kept as a JSON string, the
same workaround the witness contract uses).
set_chain
Operator-only: configure (or replace) the JSON-RPC endpoint and USDC address for a
chain id. `usdc` is stored lowercased.
attest
Request one consensus-backed attestation. PERMISSIONLESS: any sender may ask, and the
question has one answer per receipt, so who asks adds nothing. Reverts before consensus for
a malformed `receipt_id` or a duplicate `attest_id`; after consensus for the cases the
module docstring lists. Returns the `attest_id`.
get_attestation
The published record for `attest_id`; reverts for an unknown id — a missing record is a
caller error to surface, not an empty value to fabricate.
list_by_receipt
JSON list of every `attest_id` published for `receipt_id`, in request order, or `"[]"`.
get_chain
The configured endpoint and USDC address for `chain_id`; reverts for an unknown chain.
get_config
JSON: operator, receipt_base_url, configured chain ids (sorted).
Deployed code is the file
The deployed bytes are the committed file bytes at the deploy commit, verifiable with sha256sum integrations/genlayer-apibase-attest/contracts/apibase_receipt_attest.py at that commit against the code shown by the
explorer. The Bradbury per-transaction gas cap is 16 777 216 (measured 2026-10-20) and gas is about 778 per byte, so
every contract file in this repo is kept at or under 19 000 bytes and the deploy gate is eth_estimateGas <= 16 000 000
with the exact deploy arguments. tests/direct/test_apibase_receipt_attest.py holds the size ceiling, the docs-only AST
comparison against 774a184, and the docstring limits.
