The quitanza format

Format version 1, issued by Quitanza API v0.3. This page is the normative specification: fields, canonicalization, the verification algorithm, and a worked example with real bytes you can verify without any Quitanza code.

A quitanza is a signed JSON document proving how an escrow closed: who paid whom, how much, against which terms, with what outcome, and the exact head of the evidence trail at the moment of issuance. Anyone holding the document and the issuer's public key can verify it offline.

Fields

A quitanza born of a dispute carries disputeId; one born of a clean settlement carries verdictId and deliveryHash. A refund quitanza proves the matter closed in the payer's favor. Proof is symmetric.

Canonicalization

Hashing and signing always operate on canonical JSON:

1. Object keys sorted lexicographically (code-unit order), at every nesting level.
2. No whitespace anywhere.
3. Keys whose value is undefined are omitted; null is kept.
4. Arrays keep their order; their elements are canonicalized recursively.
5. The result is UTF-8 encoded for hashing and signing.

Equivalent objects therefore produce identical bytes, so verification is byte-exact and implementation-independent.

Verification algorithm

Given a quitanza document and the issuer's public key:

1. Remove the signature field; the remainder is the signed body.
2. Compute the canonical JSON of the body (rules above).
3. Check signature.signer equals the issuer public key you trust.
4. Verify signature.signature as an Ed25519 signature over the UTF-8 bytes of step 2, using that key.

To additionally bind the proof to history, fetch the evidence trail (GET /v1/escrows/{escrowId}/trail) and check: every entry's hash equals SHA-256 of the canonical JSON of {index, prevHash, at, event, body}, each prevHash matches the previous entry's hash (64 zeros for the genesis entry), and the entry at index trailLength - 1 has hash trailHead.

Worked example: real bytes

The document below was issued by a real engine run; every byte verifies.

{
  "id": "qtz_3cd1d5ba17904e2eb1437a1011afb02c",
  "escrowId": "esc_77a341165e084c0daadcae6be877c6ca",
  "outcome": "released",
  "payer": "145acbb3f6e695d4313e4f373630c5226154d2561162cf028e5b5926877bca93",
  "payee": "e0bf901f8fb87ae3f5890afc34e80e5e65eab05df47a2855363516d838bd12b2",
  "amount": "25.00",
  "asset": "USDC",
  "termsHash": "07c1aef495dd22528506ca3a7baf3122f8d5a730c867a26ede7a20901ce0c0db",
  "trailHead": "247ea9423f4c9bb4489ce19b2ce50c6beff6f811df5d97542cc9d715cfb52071",
  "trailLength": 4,
  "issuedAt": "2026-06-10T12:00:13.000Z",
  "deliveryHash": "9f45517c2cf50d8e72bb6f8f173e25f54dc0d5daf3b196b785ea4e22f4626ea2",
  "verdictId": "vrd_664601e9f96b4777bd48313c05057ec3",
  "signature": {
    "signer": "f327d5d6dcffe11a9c81f832a525a8b3936b7a5299f82e306c4cded8e1ea7b16",
    "signature": "d86329a4c26da2545c2b874c0e02ac44191fcefcca5a931d3a8b1d615eeafc9db86c4431a0e58fb2d2e7b019476fcdaef9f4fde88f85caf47b9bcc015ca3130f"
  }
}

The issuer's public key is f327d5d6dcffe11a9c81f832a525a8b3936b7a5299f82e306c4cded8e1ea7b16. The canonical JSON of the signed body, step 2 of the algorithm (one line, keys sorted, no whitespace), is:

{"amount":"25.00","asset":"USDC","deliveryHash":"9f45517c2cf50d8e72bb6f8f173e25f54dc0d5daf3b196b785ea4e22f4626ea2","escrowId":"esc_77a341165e084c0daadcae6be877c6ca","id":"qtz_3cd1d5ba17904e2eb1437a1011afb02c","issuedAt":"2026-06-10T12:00:13.000Z","outcome":"released","payee":"e0bf901f8fb87ae3f5890afc34e80e5e65eab05df47a2855363516d838bd12b2","payer":"145acbb3f6e695d4313e4f373630c5226154d2561162cf028e5b5926877bca93","termsHash":"07c1aef495dd22528506ca3a7baf3122f8d5a730c867a26ede7a20901ce0c0db","trailHead":"247ea9423f4c9bb4489ce19b2ce50c6beff6f811df5d97542cc9d715cfb52071","trailLength":4,"verdictId":"vrd_664601e9f96b4777bd48313c05057ec3"}

Verify it with nothing but Node's standard library, no Quitanza code:

import { createPublicKey, verify } from "node:crypto";

const sortKeys = (v) =>
  Array.isArray(v) ? v.map(sortKeys)
  : v !== null && typeof v === "object"
    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]))
    : v;

const quitanza = JSON.parse(/* the document above */);
const { signature, ...body } = quitanza;
const canonical = JSON.stringify(sortKeys(body));

// Raw 32-byte Ed25519 key → DER SPKI by prefixing the fixed header.
const spki = Buffer.concat([
  Buffer.from("302a300506032b6570032100", "hex"),
  Buffer.from(signature.signer, "hex")
]);
const key = createPublicKey({ key: spki, format: "der", type: "spki" });

console.log(
  verify(null, Buffer.from(canonical), key, Buffer.from(signature.signature, "hex"))
); // true

Change any field and verification fails: the amount, the outcome, the trail head.

What the trail head commits to

trailHead is the hash of the last entry in the escrow's evidence trail when the quitanza was issued, and trailLength is the entry count at that moment. Because each trail entry hashes its predecessor, the head transitively commits to every recorded event: creation, funding, the delivery's content hash, each verification check's result, every piece of dispute evidence, any timeout. The quitanza is small; what it pins down is not.

Verifying against a live API

GET /v1/quitanzas/{id}/verify
→ { "signatureValid": true, "trailIntact": true, "trailHeadMatches": true, "issuer": "…" }

Or offline with @quitanza/core: verifyQuitanza(quitanza).

Verifying against a domain

A deployment publishes its issuer keys at /.well-known/quitanza-issuer.json. verifyQuitanzaAgainstDomain(quitanza, "quitanza.com") in @quitanza/sdk fetches that document, requires the quitanza's signing key to be among the published keys, and verifies the signature offline. The CLI form is quitanza verify <id> --domain quitanza.com.

Addendum: the anchor block

When custody is chain-backed, the settlement moves funds in a contract and the quitanza carries an optional anchor object inside the signed body. Sandbox settlements omit it entirely, so every version 1 document above remains valid and the verification algorithm is unchanged: the anchor, when present, is just another signed field.

Custody is local-only in this release: no public network, no real funds. The anchor proves which transaction the issuer observed when it signed; on a development chain that transaction exists only on the node that produced it. The signature verifies offline either way.

Worked example with an anchor: real bytes

Issued by a real engine run settling through QuitanzaEscrow on a local anvil node. The same verification code as above accepts it unchanged.

{
  "id": "qtz_23c712d99c8c4b6f9ce545cf45adaba7",
  "escrowId": "esc_5e39926e46904f2cb113b0675690a96b",
  "outcome": "released",
  "payer": "9f9c3a9ff4fbd30d8cd926d01c86e49756640a8680914e28f52689b29ecbea84",
  "payee": "44ad3dd06c8fd11768d9e025bf2bed0cf8769a6a37968d1ff444837b49d9c102",
  "amount": "25.00",
  "asset": "USDC",
  "termsHash": "1653b0e2c0441523d3afa70f7092433f22854004cc114967a1942ae3a67fe3e4",
  "trailHead": "be823b4b95836e18020aea0469e5472601dfbd39424a15ef7a075107bbe24124",
  "trailLength": 4,
  "issuedAt": "2026-06-10T22:30:13.000Z",
  "anchor": {
    "chain": "eip155:31337",
    "contract": "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
    "escrowRef": "0x65c439bbdaab7fd6a50bba3be38e967a052c84a7bb059b525bc8e54d76229093",
    "txHash": "0x41ac0aa8893430112747b820d407d188c94a36d6862f85dcc4f696ffec070d33"
  },
  "deliveryHash": "3e68fb7b3c76277df0f62e842db9b3cef3c634caac234a9aeaf2d0aaa334688d",
  "verdictId": "vrd_fbe7431240014a1194210e4ea73a2fa6",
  "signature": {
    "signer": "85c3b227bd273d42bc375c62708f3d5bc759525d4f38a1be03d0eaa0b179b424",
    "signature": "a68ad13b2c98f5254e553adf31c261d49fabe5f815bb90fa150bd4f049ac3605c82064b06ad5043acd1a88666c12bb931eeadf85f0d6aabf10657af062d3400e"
  }
}

The canonical signed body, with the anchor in place (keys sorted, one line, no whitespace):

{"amount":"25.00","anchor":{"chain":"eip155:31337","contract":"0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512","escrowRef":"0x65c439bbdaab7fd6a50bba3be38e967a052c84a7bb059b525bc8e54d76229093","txHash":"0x41ac0aa8893430112747b820d407d188c94a36d6862f85dcc4f696ffec070d33"},"asset":"USDC","deliveryHash":"3e68fb7b3c76277df0f62e842db9b3cef3c634caac234a9aeaf2d0aaa334688d","escrowId":"esc_5e39926e46904f2cb113b0675690a96b","id":"qtz_23c712d99c8c4b6f9ce545cf45adaba7","issuedAt":"2026-06-10T22:30:13.000Z","outcome":"released","payee":"44ad3dd06c8fd11768d9e025bf2bed0cf8769a6a37968d1ff444837b49d9c102","payer":"9f9c3a9ff4fbd30d8cd926d01c86e49756640a8680914e28f52689b29ecbea84","termsHash":"1653b0e2c0441523d3afa70f7092433f22854004cc114967a1942ae3a67fe3e4","trailHead":"be823b4b95836e18020aea0469e5472601dfbd39424a15ef7a075107bbe24124","trailLength":4,"verdictId":"vrd_fbe7431240014a1194210e4ea73a2fa6"}

Etymology, briefly

A quitanza was the document a medieval creditor handed a debtor on payment: formal proof the obligation was discharged. First attested 1289, kin to English acquit and quittance. This format is that instrument, as cryptography.