A contract kit for two A2A agents with nobody in the middle (looking for the first pair)

[ogasurfproject-jpg]

A contract between two A2A agents that nobody in the middle has to hold: the two operators sign the terms, the contractor signs what it did, OpenTimestamps puts that record into Bitcoin, and anyone recomputes the verdict (within_grant, or a named deviation) from the bytes and public block headers. No server, account or ledger of ours is involved, and no money moves.

The kit is two Python files, peer_kit.py and anchor_direct.py, MIT. It has been reviewed in public: an independent approver role (settle v1.10) was built against vectors written by @babyblueviper1, and the PyPI build was reproduced byte for byte on Ubuntu and Windows by @pipavlo82 (horizon-shield Issue #29).

What it has not had yet is the only test that matters for a protocol: a contract with no party from my project in it. The count in the README is 0. I am looking for two A2A operators willing to make one contract with each other. Pairing, the steps and what counts are here:

ogasurfproject-jpg/horizon-shield#31

About ten minutes each plus a few hours for Bitcoin. If any step needs something from me, that is a defect in the kit, and I would like to hear about it.

[ogasurfproject-jpg]

An update on the pair this post was looking for: it happened.

agent-passport.org (principal) and kuangmi-bit.github.io (contractor) met in horizon-shield#31, signed the terms with their own keys, and the contractor signed one execution record, anchored in Bitcoin block 970480. They published everything in kuangmi-bit/musubi-peer-contract, including the settlement: within_grant, final, no deviations. Neither party is this project, and the settlement recomputes byte for byte from their files.

Since then the settlement function itself has been written down for a second implementation, so it no longer exists only as one program: SETTLE_CORE_v0.md with 76 test vectors; most of the real ones are built on that pair's contract, record and header view. Writing it down found defects in the earlier settle versions (the worst: an unsigned record could turn a verdict into a deviation and forfeit a bond); they are fixed in the version the text describes.

If you maintain an A2A agent or a verifier and want to try a clean-room implementation from the text and the vectors alone, the call is horizon-shield#49. Disagreements are the most useful result.

[ogasurfproject-jpg]

The same text is now an IETF Internet-Draft, so it can be cited without this thread or the repository: draft-oga-musubi-settlement-00 (Informational, individual submission, so no IETF endorsement is implied). Reviews and clean-room implementations are still collected in ogasurfproject-jpg/horizon-shield#49.

[kaspermuutra-dotcom]

Interesting. With nobody in the middle, each side has to trust the other’s card is accurate before committing. Have you thought about a pre-contract check where each agent’s declared skills and auth are verified first? We build exactly that kind of check (Suncly) and would be glad to run it on whichever pair you find, so the first contract starts from verified cards.

[ogasurfproject-jpg]

@kaspermuutra-dotcom Yes, and the kit already has the slot for it. A contract pins each party's agent card by sha256 at signing (parties[].agent_card_sha256), and the party that pinned it serves those exact bytes by that sha. That rule came from the second contract: live cards moved within days, so a pin that points at a live URL resolves to nothing.

So a signed pre-contract record of yours that names the same card sha256, made before the terms are signed, sits next to the contract, and anyone can check the join from the bytes: the same sha, and your record dated before the terms. The settlement does not read it (the settle core decides within_grant from the terms, the records and the block headers only), so it adds evidence without adding a party in the middle that anyone has to trust.

Two things would make it checkable by a stranger:

• the record is signed with a key published on your own domain, and
• it says what it checked (which declared skills answered, whether the auth scheme behaves as declared) and what it does not establish.

The first pair (agent-passport.org and kuangmi-bit.github.io) has already settled, so the next pair is the one to start from verified cards. New pairs are matched in ogasurfproject-jpg/horizon-shield#31. If you want a target before then, our own cards are fair game: run it on https://mcp.horizonshield.dev or https://gate.horizonshield.dev and post the record, and I will check the join against the sha we would pin.

[kaspermuutra-dotcom]

That’s the right anchor. Pinning the card by sha256 means a verification bound to the same hash slots straight in: “the card both parties signed against was checked to behave as declared.” That’s what our reports are keyed to, so a pre-signing check would reference the exact parties[].agent_card hash.

On finding the first pair: @xMaxos runs a public A2A 1.0 agent (Hidden AI Society, #2354) and is actively asking for interop counterparts. Might be a natural first party. Happy to verify both cards against their declared behaviour before signing, free, so the first contract starts from checked cards. No role in the contract itself, so it stays “no party from your project”.

[ogasurfproject-jpg]

@kaspermuutra-dotcom Agreed on keeping Suncly outside the contract. A signed check that names the pinned sha is evidence beside the terms, not a party.

On the first party: a contract needs two operators who are not this project, a principal and a contractor, so one agent is half a pair. @xMaxos, in case it is useful: Hidden AI Society would fit either side. The principal grants a bounded task, the contractor signs one execution record of what it did, and anyone recomputes the settlement (within_grant, or a named deviation) from those bytes and Bitcoin block headers. Nothing goes through our servers, and the traffic between the two agents stays whatever A2A binding you already serve. Your card has moved often (0.4.0 to 0.4.9 across #2354), which is the case the pin rule is for: whoever pins a card keeps those exact bytes and serves them by sha, so a later reader can still resolve the pin. If you want to try, matching and the steps are in ogasurfproject-jpg/horizon-shield#31. No obligation, and any step that needs something from me counts as a defect in the kit.

When a pair forms, the order I would suggest: both cards fixed by sha256, then Suncly's signed check naming those two shas, then the terms. Anyone can then see from the hashes and the anchor heights that the check came first and was of the same cards the parties signed against.

[kaspermuutra-dotcom]

Agreed on the order: cards pinned by sha256, then the signed check naming both shas, then terms. The check sits beside the contract as evidence and is never a party, so “no party from this project” holds for both of us.

For the next pairs matched in #31, we’ll do that pre-terms check free, so the kit gets a few runs with verified cards on record. If a short “optional: independent card check before terms” step in the kit’s README would help, I’m happy to draft it as a PR for you to accept or ignore.

[ogasurfproject-jpg]

@kaspermuutra-dotcom Yes, please. The place is the "peer_kit and anchor_direct" section of workers/hs-ledger/nenrin/musubi-v0/README.md, and the pairing steps people actually follow are in ogasurfproject-jpg/horizon-shield#31, so a one-line pointer there would help too.

Four things the step should say, so it stays true to what the kit does:

1. It is optional, and nothing in the kit reads it: peer_kit.py and the settle core decide within_grant from the terms, the records and the block headers only.
2. The check names both parties[].agent_card_sha256 values and is made before the terms are signed. For a stranger to see "before", the check needs a time nobody can move afterwards: an OpenTimestamps stamp of its sha256 (anchor_direct.py in the kit does exactly that) gives one.
3. It is signed with a key served on the checker's own domain.
4. It carries establishes and does_not_establish, as in Looking for a second and third independent witness for A2A agent conduct records (reciprocal, free, no account) #2272.

I will review it like any other change, and if a check in the repository flags something, I will point at the exact line.

[kaspermuutra-dotcom]

Great, thanks for the exact spec. I’ll open the PR against the “peer_kit and anchor_direct” section of workers/hs-ledger/nenrin/musubi-v0/README.md with all four points (optional and unread by the kit, names both agent_card_sha256 values before signing with an OpenTimestamps stamp via anchor_direct.py, signed with a key on the checker’s own domain, carries establishes / does_not_establish), plus a one-line pointer in #31.

I’ll send it after our first walk records are filed, so the step can link to a real signed example rather than describe a hypothetical one. Aiming for later this week.

[babyblueviper1]

@ogasurfproject-jpg taking up your offer on your own cards: a signed pre-terms record for gate.horizonshield.dev, made before any terms. It is in examples/pre-terms-card-check-horizonshield-gate.

• Card sha256 ada419468d732bdc0fbc13b692a0b36f9ee2a9560001f2375f0410fbd98dc88f. The exact bytes are in the folder, so you can check the join against the sha you would pin.
• Order: criteria committed with an RFC 3161 token, then one A2A message/send per declared skill and a tokenless POST /sweep, all recorded in observation.json, then the record. It is signed with the checker key published at api.babyblueviper.com/.well-known/invinoveritas-checker-keys.json.
• Auth behaves as declared. Every A2A probe answered without a credential, and /sweep without x-sweep-token answered 403 {"error": "forbidden"}.
• Provider and compensation disclosure are present (paid_by: buyer).
• The verdict is fail on one criterion: over A2A, verify, conditions and lookup answered with the register reading or a "send an MCP endpoint URL" prompt, not the function their skill descriptions state. Several of those descriptions point to POST /check or MCP tools, so this may be the A2A interface not routing by skill rather than a broken skill. Either way it is what a counterparty would see before signing.

One thing for anyone else running this step: Cloudflare in front of the gate refuses the default Python client with error 1010. A probe that reads that 403 as the gate's auth gets the auth finding wrong, so the step should record which client made each probe.

It is free for the next pair matched in horizon-shield#31, on both cards.

[ogasurfproject-jpg]

@babyblueviper1 thank you for running this on our card; the record and the fail are right, and the cause is on our side. The gate's A2A endpoint does not route by skill: a witness request gets a witness answer, a text part with an https URL gets the register reading, and anything else gets the usage prompt, while the card lists verify, conditions and lookup as A2A skills whose functions exist only over MCP and HTTP (verify_verdict, GET /spec, lookup_server). The 1010 is Cloudflare's edge refusing the default Python-urllib User-Agent before the request reaches the gate. We have changed the card to say what A2A actually does for these skills, added the User-Agent note, and re-signed it; the new card sha256 is f76d542cfccf56ed3a9b73e8a9a56a5147a72b5b433647061e81eadeb194c5f2.

[kaspermuutra-dotcom]

@ogasurfproject-jpg nice turnaround on the re-sign, and @babyblueviper1 good catch on the Cloudflare 1010. That's exactly the kind of thing that turns into a wrong auth finding if the probe doesn't record its client.

Since a second independent run is part of the point of this kit, we'll check the re-signed card (sha256 f76d542c…94c5f2) against the same criteria, record which client made each probe, and post the result here as a second record for the same card. Two checkers agreeing, or not, on one pinned card is a useful data point for anyone pairing.

I also still owe you the signing key and the two walk records from earlier. They'll be in the same post.

Kasper