Why three primitives

Every agent-commerce protocol we have studied collapses three separate concerns into one: the user’s permission to act, the safe-holding of funds during the transaction, and the after-the-fact record of what happened. When those are bundled, bugs multiply: a cancelled booking leaks funds, an expired consent still authorises a charge, a disputed payment has no signed evidence. GeraNexus separates them. Each primitive has its own wire format, its own verification path, and its own failure mode.

Consent tokens: narrowly scoped, short-lived, verifiable

A consent token is a JWS (RFC 7515) signed by a key the user controls — either the user’s personal key on-device or a consent-custodian key held by the user’s identity provider (e.g. Gera Auth, Apple, Google, a hardware key). The token payload is deliberately small:

{
  "iss": "user:[email protected]",
  "aud": "marketplace:geraclinic.com",
  "negotiation_id": "neg_01HWKC...",
  "action": "book+pay",
  "max_amount": { "currency": "GBP", "value": 8000 },
  "scope": ["read:provider_profile", "write:booking"],
  "exp": 1745259600,
  "nbf": 1745259000
}

The marketplace cannot replay the token against a different negotiation, cannot upgrade the action, cannot increase the cap, and cannot use it past exp. The agent must re-prompt the user for a new token for every new transaction. There is no such thing as a long-lived blanket consent in the protocol — providers that ask for one are misusing it.

Why not OAuth refresh tokens?

OAuth is built for the standing-authorisation use case: the user granted GitHub access to Vercel, and that grant stays good until revoked. Agent commerce is the opposite shape — every transaction is a discrete event with a discrete monetary and policy cost, and the user’s mental model is approve-per-transaction. A long-lived refresh token for “book things on my behalf” is a phishing target waiting to be stolen.

Escrow as a protocol state, not a payment-provider trick

Escrow in GeraNexus is a first-class booking state that sits between paid and settled. When the agent calls pay with escrow: true, the payment rail (GeraCash, Stripe, or a third-party gateway) transfers funds into a ring- fenced account tagged with the booking_id. The marketplace sees the booking as paid-in-escrow and can perform the work, but cannot withdraw until one of three release conditions triggers:

The agent (on behalf of the user) posts a signedcompletion_ack message carrying the completion receipt issued by the marketplace.
The auto-release SLA expires (typically 72 hours after the marketplace-issued completion_ts) and no dispute is open.
An arbitration outcome explicitly releases the funds.

The key property: the money does not leave the escrow until the protocol says so, not until the payment provider says so. This removes a whole class of refund-clawback races when a card transaction has already cleared but the service was never rendered.

Partial completion and ladder refunds

Real transactions are messier than happy paths. A dentist appointment that runs for 20 minutes instead of the booked 45 should trigger a 50% refund, not 0% and not 100%. GeraNexus supports a completion_ratio field on the completion receipt (0.0 to 1.0) which the escrow release logic maps through a refund ladder declared in the marketplace policy. The user’s agent verifies the ladder at negotiation time and rejects marketplaces whose ladders violate the user’s global preferences.

Receipts: signed, canonicalised, third-party verifiable

Every stage emits a receipt:

Negotiation receipt — quote + expiry, signed by the marketplace.
Booking receipt — slot reservation, signed by the marketplace.
Payment receipt — escrow deposit, signed by the payment rail.
Completion receipt — service rendered, signed by the marketplace with a timestamped attestation.
Release receipt — escrow funds moved to the marketplace, signed by the escrow agent.

Receipts are canonicalised using JCS (RFC 8785) before signing — no field-ordering ambiguity between clients and servers. Signatures are Ed25519 (RFC 8032). Public keys are published at/.well-known/gera-nexus.json alongside the protocol descriptor, with rotation supported via a keys[]array and kid headers on each signature.

Why you cannot replay or forge a receipt

Each receipt binds to the previous stage’s receipt hash (prev_receipt_hash) so the chain is continuous. A marketplace cannot emit a completion receipt without a matching booking receipt. A payment rail cannot emit a release without a matchingcompletion. An arbitrator’s evidence bundle is always a complete chain plus the consent token. Anyone with the public keys can verify the whole sequence without calling back to Gera — this is the third-party-verifiable property that makes interoperable dispute resolution possible.

The failure modes we built for

The three primitives exist because we enumerated the ways agent commerce goes wrong and made each a named state with a named recovery:

Agent overreach — the consent token stops it. No token, no booking.
Service not rendered — escrow holds the funds. User raises dispute, arbitration panel decides.
Receipt forgery — the Ed25519 chain makes it detectable after the fact, even by parties not involved in the original transaction.
Marketplace insolvency mid-transaction — the escrow is at the payment rail, not the marketplace; funds return to the user via the standard refund path.

What this unlocks downstream

Once receipts are third-party verifiable, you can compose them. A GeraClinic booking receipt becomes an insurance-claim evidence payload against GeraSure. A GeraCash payment receipt is a tax-return input. A GeraJobs contract-work completion receipt is a reputation signal on the worker’s public profile. The protocol does not build these features — but it makes them buildable without proprietary glue.

Where this is in the draft

The v0.1 draft spec covers consent tokens and receipts in full, with normative examples. Escrow is v0.2 — we are still converging on partial-completion semantics and cross-currency settlement. Open questions are catalogued on the open questions post. Comments via GitHub issues on the spec repo are open.