# SolMachina Intelligence Receipt (SIR) — open specification v1

**Status:** draft/open · **Version:** 1.0 · **License:** CC0 (public domain — adopt freely)

A **SIR** is a small, signed, self-verifying proof that a specific paid answer was delivered by a
specific provider. It turns an x402 payment (which proves *money moved*) into **proof of what was
delivered** — verifiable **offline**, by anyone, with public-key math and no trust in the provider.

> Others give your agent an answer. A SIR proves *which* answer you paid for.

Reference implementation: SolMachina serves it on every paid `/v1/*` response and ships an offline
verifier (`npx solmachina-verify`). Any x402 provider may emit SIRs; the format is provider-neutral.

## 1. Transport
On a successful paid response, the provider returns the header:
```
X-SolMachina-Receipt: <base64(JSON)>
```
(Providers adopting the standard generically MAY use `X-Intelligence-Receipt`.) The body is unchanged,
so `responseSha256` is the hash of exactly the bytes the client received.

## 2. Receipt object
```jsonc
{
  "schema": "solmachina.intelligence-receipt.v1",
  "service": "solmachina",
  "resource": "/v1/pretrade?mint=…",   // the exact resource + query served
  "endpoint": "/v1/pretrade",
  "priceUsd": "$0.10",
  "priceUsdcUnits": 100000,
  "network": "solana:mainnet | eip155:8453",
  "serviceVersion": "0.1.9",
  "requestSha256": "…",                 // sha256("GET <originalUrl>")
  "responseSha256": "…",                // sha256(exact response body bytes)
  "responseBytes": 1234,
  "ledgerChainHead": "…",               // SHA-256 chain head at issue time (links to the log)
  "generatedAtUtc": "2026-09-03T…Z",
  "signature": {
    "scheme": "ed25519-detached(utf8(canonicalReceipt))",
    "signatureBase58": "…",
    "signedBy": "<base58 ed25519 pubkey>",  // == the x402 facilitator/payTo identity, public in every 402
    "verify": "https://api.solmachina.com/trust/verify"
  }
}
```

## 3. Signing & verification (deterministic)
1. `canonicalReceipt` = `JSON.stringify(receipt)` where `receipt` is the object **without** the
   `signature` field, keys in insertion order (i.e. the object exactly as built before the signature
   was appended last).
2. Sign: `ed25519.sign.detached(utf8(canonicalReceipt), signerSecretKey)` → base58.
3. Verify: `ed25519.detached.verify(utf8(canonicalReceipt), base58decode(signatureBase58), base58decode(signedBy)) === true`.
4. Trust: check `signedBy` equals the provider's published key (`/trust/pubkey`) — for SolMachina it is
   the same public identity that settles the x402 payment (visible in every 402 challenge), so no extra
   key distribution is needed.
5. Delivery (optional): `sha256(savedResponseBytes) === responseSha256` proves the stored answer is
   exactly the one paid for.

## 4. Transparency log & inclusion proofs
Each paid call is also a leaf (`wal_entry_sha256`) in a SHA-256 hash-chain **and** a Merkle tree.
- `GET /trust/log` → `{ entries, merkleRootSha256, chainHeadSha256 }`.
- `GET /trust/proof?index=N` → `{ index, leaf, proof:[{hash, side}], merkleRootSha256 }`.
- Verify inclusion: fold `cur=leaf`; for each step `cur = side==="left" ? sha256(step.hash+cur) : sha256(cur+step.hash)`; result must equal `merkleRootSha256`. Leaves are hashes only — no query content, caller identity, or IP is exposed.

## 5. Versioning
`schema` carries the format version; `serviceVersion`/methodology versions travel in the receipt so a
result stays reproducible. Backward-incompatible changes bump `…-receipt.v2`.

## 6. Why it matters
- **No vendor lock-in / no trust required:** verify offline; if the provider vanishes, the proof stands.
- **Disputes & reputation:** a buyer can prove "I paid X for this exact answer at this time."
- **Agent-to-agent commerce:** a portable, checkable delivery proof across providers.

Adopt it, verify it, extend it. PRs and other implementations welcome.