The Mirror Protocol — v1 draft

Status: draft for review. Audience: a bank's cryptography team, its data-protection officer, and its counsel. What this document is for: so those three people can decide whether Mirror is safe to join without taking a vendor's word for anything.

Everything below is implemented and test-enforced. Where something is not implemented, or is weaker than a reader might assume, it says so in the same sentence. There is no section of this document whose purpose is to sound impressive.

1. The problem, stated precisely#

The three legs of a trade live in three institutions. The exporter's bank sees the invoice. Customs sees the declared value. The importer's bank sees the payment. Trade-based money laundering is a mismatch between those legs — declare a 1,000-unit shipment at $300/unit when it is worth $100 and $200,000 has moved under cover of a legitimate-looking trade.

No party can see the mismatch, because no party holds more than one leg. Every incumbent AML system monitors one institution in isolation. The obvious fix — pool the data — is unlawful, commercially unacceptable, or both.

Mirror is the join, performed blind.

2. Roles and trust model#

The operator is not trusted, and does not need to be. It is structurally unable to read a value because a value is never in its input. That is a property of the wire format, not a policy, not a contractual promise, and not a configuration setting. §9 states exactly where the property ends.

2.1 Threat model — what must remain impossible#

Assume all of these adversaries at once, and the guarantee still holds. This table is the security product; if any row becomes false, that is a Sev-0, not a backlog item.

The claim we make to a CISO is not "we encrypt well". It is: full root on Mirror production yields membership, corridor ids, opaque 256-bit blobs, signed verdicts, and the shipment references those verdicts are grouped by — nothing else. If a debug flag, a tracing span, or an error message ever violates that sentence, the architecture has failed, not the configuration.

That sentence used to end at "signed verdicts — nothing else", which was not true: shipment_ref is in the clear on the wire and in the store (§5.0). A security audit found the contradiction between that claim and §5.0 and was right to treat it as disqualifying — a reader who catches a spec contradicting itself has no reason to believe the rows they cannot check. The clause is now in the sentence, and the exposure it creates has its own section rather than a footnote.

2.2 Designed inability, and its limits#

The operator's inability is enforced in four places, and it is worth being exact about how strong each one is:

1. The wire rejects raw data. Any payload carrying a value, unit count, band, corridor table, secret, salt, entity name, or counterparty name is refused at the door with 400 raw_leaked — on every route, and for the pKYC and flow surfaces with their own blocklists. Rejected, never stripped: silently discarding it would teach a caller that sending it is acceptable.
2. No filing decision can enter. A separate wall refuses any suspicious-activity field at any nesting depth (400 sar_wall). See §10.
3. A build gate on the operator's own source. A linter fails the build if operator-side code so much as names a value-shaped field. Encryption-at-rest of data you should not have is how you accidentally have it; the control is that the code cannot name it.
4. The commitment construction itself. A value is not encrypted on its way in — it is never sent. Only a salted hash of a band index travels.

The limit, stated plainly. Point 3 is a lint over source, which catches a named field, not obfuscation: it cannot stop leg["amo"+"unt"], a base64 blob, or data smuggled through a generic key. Its realistic threat is the well-meaning engineer adding a debug field, and against that it is effective. It is not a defence against a determined insider with commit access — nothing in this list is. What defends against that insider is point 4: even with commit access, the operator cannot recover a value it was never sent, because the salt lives with the members.

2.3 Cryptographic construction notes#

• Binding comes from the hash: after a member emits a commitment it cannot open it to a different band without a second preimage.
• Hiding from the operator lives entirely in the salt — 256 bits, derived per shipment via HMAC-SHA-256 from a secret the operator never holds. This is what makes the operator's brute force infeasible even though the band space is roughly 12–24 buckets.
• Not hiding from the counterparty. Stated in §9 and not treated as a defect.
• Domain separation. Distinct hash namespaces are tagged and length-prefixed so that fields cannot be spliced across them — a locator preimage is <len>:<field> concatenated under mirror.locator.v1, and each banded dimension commits under its own tag. The core band commitment concatenates a fixed-width 64-hex salt with the band, which is unambiguous for the same reason.
• Known gap, honestly. The verdict signature is ES256 (ECDSA P-256), which is not post-quantum. The commitments are hash-based and therefore already PQ-safe, but a verdict that must still verify in 2040 should carry a second, lattice-based signature. Mirror does not ship one today, and will not hand-roll one: it requires a vetted implementation, and shipping unreviewed post-quantum crypto would be worse than the gap it closes.

2.4 Residual exposure: what the wire still reveals#

This section exists because §2.1 used to claim "no shipment identifiers on the wire" while §5.0 said shipment_ref travels in the clear. Both could not be true. Rather than quietly delete the row, here is the exposure, stated at the same resolution as everything Mirror does mitigate.

What is exposed. Every leg submission carries shipment_ref in the clear, and the operator stores it. So the operator — and anyone who can observe its traffic or compel its logs — learns:

• that two named members reconciled the same trade reference, and when;
• how often a given pair of institutions reconciles, and the shape of that timing;
• the reference itself, which in documentary trade is frequently an LC number (§4) and is therefore a real-world identifier, not an opaque token.

What is still NOT exposed, even to a rooted operator: the value, the unit count, the band, the corridor's price table, the salt, and the counterparty's customer. Those remain absent, not encrypted. The exposure here is traffic analysis of correspondent pairs, not disclosure of trade terms.

Why it is like this. The operator has to group the legs of one trade to compare them, and grouping needs a join key. shipment_ref is the join key that requires no additional coordination between members, which is why the protocol shipped with it.

The specified mitigation, and its status. §4 defines a locator commitment: an opaque, length-prefixed value both members derive from the corridor secret. Grouping by that instead of by shipment_ref gives the operator a 256-bit blob with no external meaning, and padded fixed-interval batches remove the timing signal. That construction is specified but not the default, and until it is, this row of the threat table is false and is marked false.

Do not read the mitigation as shipped. A control that exists in a document and not on the wire is a plan, and this specification does not get to describe plans in the present tense.

3. The corridor#

A corridor is a party-agreed, versioned reference table of price bands for one product class.

• Mirror invents no prices. Corridor edges are supplied by the members. There is no default price curve anywhere in the implementation, and shipping one would make Mirror a data vendor competing with the sources members already license.

• A corridor is identified by its content, so two parties who used the same table get the same id without coordinating a label:

  corridor_id = "c:" + sha256(sorted_edges.join(","))

• Corridors are append-only and versioned. Superseding a table creates a new version; the old one is retained forever, so a verdict signed last year can be re-checked against the exact table it was judged under. A commitment cites its table version, and mixing two versions can never reconcile — it is undetermined.

• A corridor becomes usable only when a quorum of distinct members ratifies it. Quorum counts distinct members, never distinct signatures, and is never less than 2.

• A table's outer bands are open. Band 0 runs from zero to the first edge and the top band from the last edge to infinity, so two legs that both land in either one agree at any ratio. A corridor MAY be ratified closed (closed: true, §5): the table is then the half-open range (first edge, last edge], and a value outside it can never clear. Only on a closed table can a match ceiling (max_ratio, §7.1) be met, because only there is every clear's window bounded.

• The shape a new corridor must have. An operator admits a new corridor.propose (and a ratification of one still pending) only if it is closed, carries a max_ratio above 1 and at most 1.5, has at least two edges, and its widest band at tolerance 0 — with its ratified edge_margin — fits under that ceiling. Anything else is refused at /registry/event with corridor_not_closed, ceiling_required, ceiling_too_wide, corridor_no_interior or ceiling_below_table; a citation corridor (§7.3), which cannot be closed yet, with corridor_shape. The rule is applied at the door only: replayed history is never re-judged. The cap is a released constant (CORRIDOR_RATIO_CAP in the kernel), never an operator setting.

3.2 Federation — a verdict co-signed by independent operators#

A corridor MAY name a federation: { k, operators: [{ kid, org, jwk }] }, ratified with the table.

• Shape. k is a whole number, at least 2 and at most the number of operators. The operators are 2 to 16. A kid is DERIVED from the operator's public key ("mir-" + sha256(canonical({crv, kty, x, y})).slice(0, 16)) and must equal the one given. Two operators may not share a key, and may not share an organisation name, compared case-insensitively with whitespace collapsed. A private key (d) is refused. The federation's id is "fd:" + sha256(canonical(federation)), with the operators sorted by kid.
• Co-signing. A verdict is co-signed when k distinct listed operators each return a record that verifies under their own listed key, names their own key in the proof, and is for the requested shipment, and the identical canonical record is what they signed. One operator counts once, however many answers it gives. Two different records for the same shipment are DISSENT: nothing is co-signed, even where k operators agree. An operator that does not answer is not a vote against.
• Governance agreement. Operators that answer and show a different federation for the corridor, or no corridor, disagree and block the co-sign. At least k must have answered with the federation.
• Offline check. A co-signed verdict is verified from the artifact and the federation alone: each co-signature verifies over the record, each is a listed key, and at least k distinct keys signed.
• What is not changed. The record is an ordinary verdict, so every operator still learns only the commitments. The federation does not lift the independence gate: two parties alone are undetermined on every operator.

Co-signing is replication with quorum. It is not threshold ECDSA and not secure multi-party computation.

3.1 Ratio corridors — a table nobody negotiates#

A corridor MAY band the ratio of each price to a public reference instead of the price itself. The table is then dimensionless and published once for every corridor, and the only corridor-specific choice is which public figures make the reference — a citation, not a price.

• Published ratio tables (closed by construction, constants of the protocol): ratio-5 = [0.85, 0.9, 0.95, 1, 1.05, 1.1, 1.15], ratio-10 = [0.85, 0.95, 1.05, 1.15], ratio-20 = [0.7, 0.9, 1.1, 1.3].
• The reference set (ratified with the corridor, public): { table, sources, quorum, max_spread, rule }. sources is 1–8 citations, each exactly { source, instrument, publication, basis, currency, unit } — text only, no figure — all quoting the same currency, unit and basis, none listed twice. quorum is a whole number from 1 to the number of sources; max_spread a decimal in (0, 0.2]; rule one of the FX date rules (on_board_date, invoice_date, payment_value_date, fixed_date). Its id is "rs:" + sha256(canonical(set)), with max_spread as its shortest decimal string.
• The reference R is derived party-side from the bank's own figures file { set_id, date, figures: [{ source, value, file_sha256 }] }: one figure per source, each a plain positive decimal with the SHA-256 of the publisher's file it came from. At least quorum distinct sources must report. With the counted figures sorted, hi ≤ lo · (1 + max_spread) must hold exactly, or there is no reference and nothing is banded. R is the median: the middle figure, or for an even count the exact mean of the middle two, written as its shortest decimal string.
• The pin { set_id, date, rule, figures: [{ source, file_sha256 }] } (sorted by source; never a value) rides inside the committed pricing basis as ref (§7.4), so two legs divided by different files read basis_mismatch and can never clear.
• The leg is an ordinary commitLeg (§5) with unit_qty' = unit_qty × R computed exactly, the ratio table as corridor_edges and closed: true. A product that cannot be represented exactly makes the leg unbandable. Commitments are therefore byte-compatible with every implementation of §5.
• Admission. A corridor.propose carrying reference must carry exactly that table's edges and closed: true; otherwise the registry refuses it and the operator refuses it at /registry/event with corridor_reference. The shape rule of §3 (a ceiling of at most 1.5) still applies.
• Joining. One member authors a corridor (corridor.propose); others join by accepting it (corridor.ratify), never by co-authoring it.

What it does not change. The operator still sees commitments only: it never learns R, a figure, a price or a band. What it adds is a new attack surface, stated plainly: an adversary may attack the reference instead of the trade. The quorum median and the spread refusal blunt that; they do not close it. Goods with no credible public reference — services, bespoke goods — have no ratio corridor and keep a negotiated closed table.

4. The locator — how two parties agree they mean the same shipment#

This is the part most easily got wrong, and the part a DPO will ask about first.

Two banks must agree they are discussing one shipment without either sending a customer-identifying reference to the operator. An invoice or bill-of-lading number is commercially sensitive and often identifying, so it never travels in the clear.

LP(fields)  = concat over fields of  <byte-length> ":" <field>      (no separator)
inner       = sha256(LP("mirror.locator.v1",        corridor_key, locator_type, parts...))
commitment  = "l:" + sha256(LP("mirror.locator.v1.outer", corridor_key, inner))

Length-prefixing is load-bearing, not decoration. A bare "|" join makes the parse ambiguous: type "A|B" with value "C" would hash identically to type "A" with value "B|C", letting a party walk a locator from one shipment onto another's mapping. Every field is length-prefixed so (type, parts) has exactly one parse.

The corridor key is printable ASCII with no spaces (0x21–0x7E), trimmed, 32 to 512 characters. A key outside that is refused, never truncated. The length is a floor, not an entropy measure.

Normalisation. Two families, and the difference is the point:

• Free-form references (lc, bl, and the reference parts of inv, wr, po): remove all whitespace, then upper-case. Punctuation is content — LC-2026/0412 and LC20260412 are different references, and Mirror does not decide otherwise.
• Structured identifiers (awb, the container number in ctr, the IMO number in imo, and every UN/LOCODE): remove whitespace, -, / and ., then upper-case. This is safe only because each standard defines a fixed alphanumeric form, so no two identifiers can differ by a separator alone.
• Dates have whitespace removed but keep their hyphens: strict YYYY-MM-DD, years 1900–2999, and they must be real calendar dates (2026-02-30 is refused, not rolled into March).

A numeric input is accepted only when finite; a lost leading zero is not restored.

Recognised locator types, because real documentary trade is messy. parts are hashed in the order listed, after normalisation:

Composites (inv, wr, po, ctr, imo) are objects; a bare string for a composite type is refused. Every composite refuses if any part is missing — a partial composite collides across different shipments.

Check digits, exactly:

• ISO 6346 container number. Digits have their face value. Letters run from A = 10 upward, skipping every multiple of 11 (A=10, B=12 … K=21, L=23 … U=32, V=34 … Z=38). Take the first ten characters, multiply the value at position i (0-based) by 2^i, sum, take mod 11, then mod 10. The result must equal the eleventh character. CSQU3054383 is valid.
• IMO number. Weight the first six digits 7, 6, 5, 4, 3, 2, sum, and take the last digit of the sum. It must equal the seventh digit. 9074729 is valid.
• Air waybill. The digits in positions 4–10 (1-based), read as one number, mod 7, must equal the eleventh digit. 020-12345675 is valid.
• UN/LOCODE. Shape only: [A-Z]{2}[A-Z2-9]{3}. Whether the code is on the published list is not checked.

The cargo keys are full-load only. ctr and imo exist so two lenders holding different documents for the same cargo — a bill of lading at one bank, a warehouse receipt at another, with no shared reference to alias — can still meet. A consolidated (LCL) container or a part cargo carries several consignments, so a container- or vessel-level key would join unrelated ones; those commit their own bill of lading instead. The full-load flag is refused on anything but boolean true — a string, 1 and an omitted flag are all refused. Container and IMO numbers are public and low-entropy, so a cargo key blinds the operator and outsiders, not anyone else who holds the key.

The hard case is handled explicitly. One side holds an LC number, the other a BL number, for the same shipment. A member-held alias table maps a locator to the equivalent locators that member knows about, so a party emits commitments for all of its aliases and matching is set intersection. The alias table lives inside the institution and never travels. Three conditions fail closed — the resolution is refused and counted, never guessed:

1. an ambiguous alias: one locator mapped to two different shipments;
2. a contaminated class: any locator in the shipment's class also claimed by another shipment;
3. a physical contradiction: the same container or IMO number bound to two different (port, date) legs inside one shipment's class. One box or one full cargo loads once per leg. Reusing a box on a later voyage for a different shipment is not a contradiction — each leg is its own key.

Any unreadable row or entry in the table fails the whole resolution closed.

5. The commitment#

Everything the operator receives about a value is derived as follows, entirely inside the institution:

salt        = HMAC-SHA256(shared_secret, "mirror:" + shipment_ref)      (hex)
band        = count of corridor edges strictly below (value / unit_qty)
commitment  = sha256(salt + ":" + band)                                 for each band in [band-t, band+t]
corridor_commitment = sha256(salt + "|c|" + corridor_id)

• t is the tolerance, capped at 6. A party emits a commitment for its own band and for the neighbouring bands it would still accept as consistent.

• edge_margin (optional, the near-edge fix). A value a rounding error from a band edge is fragile: two honest banks can land in different bands and produce a false divergent. Widening t fixes it but enlarges the in-band blind spot everywhere. edge_margin is the surgical alternative, agreed in the corridor table as a relative fraction m (e.g. 0.005 = 0.5%), out of range (m <= 0, m > 0.1, or non-numeric) meaning off — never a wide default. When on, the set of core bands is expanded before the tolerance window is applied:

  core = { band }
  if band < len(edges)  and  value/unit >= edges[band]   * (1 - m):   core += { band + 1 }   # near the upper edge from below
  if band >= 1          and  value/unit <= edges[band-1] * (1 + m):   core += { band - 1 }   # near the lower edge from above
  commitments = sorted, de-duplicated { sha256(salt + ":" + b) : b in [c-t, c+t] for c in core, b >= 0 }

  The (1 - m) / (1 + m) comparisons are exact decimal (cross-multiplied as integers, never a float). A value in the middle of a band is untouched, so the blind spot is widened only at the edges where the wobble is real. With edge_margin absent or off the set is exactly [band-t, band+t], so no existing commitment changes. Two honest banks straddling one edge now share a commitment and reconcile; a genuine multi-band divergence still shares nothing and stays divergent.

  edge_margin is ratified in the corridor table, not sent on the wire. It is a property of the agreed table (alongside the edges and the optional max_ratio ceiling), so the operator reads it from its own ratified registry via the verdict's corridor_ref — never from a leg. The leg is unchanged: a near-edge hit simply adds one neighbouring commitment, so a leg carries 2t+1 commitments in the middle of a band and 2t+2 next to an edge. The operator uses the ratified m to read the match window honestly: it knows a near-edge margin adds at most one band, so it subtracts that one band before inferring the tolerance (both counts read as t), and it widens the widest reported price ratio by exactly (1 + m) / (1 - m) — because a value can reach a band from edges[k-1]·(1 - m) to edges[k]·(1 + m). Rounded up: this number states the corridor's blind spot on a signed record and must never understate it. Without a ratified m the window is computed exactly as before.

• closed (optional, ratified with the table like edge_margin). A boolean or absent; any other value is an ambiguous table and the leg is unbandable (no commitments). When true, the open outer bands are not part of the table: after the near-edge expansion, bands 0 and len(edges) are removed from core. If no core band is left — the value is at or below the first edge, or above the last, and not within the margin of the edge it is beyond — the leg commits out-of-range markers instead:

  commitments = [ sha256(salt + ":out:" + role + ":" + k)  for k = 0 .. 2t ]      # role lowercased, in k order

  Otherwise it commits core widened by t exactly as above. So a value inside the table commits what it commits on the open table, byte for byte, except that a near-edge value next to the table's boundary no longer also commits the open band beyond it. A marker can match no band commitment and no other role's marker, so an out-of-range leg can only read divergent — which routes it to review. Two legs agreeing far outside the agreed table (a 250/unit invoice and a 25,000/unit declaration both in the top band) cannot clear. A marker set has 2t+1 members, the count of a mid-band leg, so the operator's tolerance inference (and the commitment-count rule of the boundary register) is unchanged, and the operator cannot tell an out-of-range leg from any other divergence. The corridor_id is the edges' own: closure, like the margin, is a table property read from the ratified registry.

  The closed window. On a closed table every clear is between two interior bands at most 2t apart, so reaches_open_band is false, the record carries closed: true, and the widest bounded ratio is the maximum, over interior bands b, of edges[min(b + 2t, len(edges) - 1)] / edges[b - 1] (times (1 + m)/(1 - m) under a margin). It gates the ceiling, so it is computed exactly — integer arithmetic over the decimal mantissas — and rounded up to two decimals: 110/100 is 1.1, never the 1.11 a float ceiling prints, and 1.504 is 1.51, never 1.5. A closed table with one edge has no interior band: nothing clears under it. An open table's window is unchanged.

• The corridor_commitment is salted, so the operator can tell that two legs were banded against the same agreed table without learning which table it is. The counterparty, who holds the salt and the table, can open it at audit time.

• The raw value, the unit count, and the band itself never leave the institution.

5.0 The shared secret — a security parameter, not a configuration detail#

shipment_ref travels to the operator in the clear: the operator has to group the legs of one trade, and it has nothing else to group them by. The band space is also small — a corridor table has a handful of edges, so band ranges over roughly 5 to 30 values.

Those two facts together mean an operator holding a single leg can run this, with no cryptanalysis at all:

for each candidate shared_secret S:
    salt = HMAC-SHA256(S, "mirror:" + shipment_ref)
    for band b in 0 .. B:
        if sha256(salt + ":" + b) is among the leg's commitments:  the band is b

Cost is (candidate secrets) × (B + 1) hashes. The band loop is a rounding error. The entire distance between "the operator cannot read a band" and "the operator reads every band before lunch" is the guess cost of shared_secret.

Therefore, normatively:

1. shared_secret MUST carry at least 128 bits of entropy. An implementation MUST refuse to band below that floor rather than warn. The reference bander refuses.
2. shared_secret MUST be produced by a cryptographically secure random generator. It MUST NOT be derived from, or equal to, any business artifact — letter-of-credit number, UETR, invoice reference, booking reference, or any concatenation of them with a corridor name or year. Those pass every statistical entropy test and represent a search space of a few million to anyone who knows the format, which every counterparty and every operator does.
3. An implementation SHOULD generate the secret itself and record its provenance, because requirement 2 is not checkable by measurement. Measurement is the backstop; generation is the control.
4. The secret MUST NOT reach the operator by any route. An operator holding a per-shipment secret does not need to search at all — it derives the salt and opens every commitment directly. There is deliberately no operator-side endpoint anywhere in this protocol that accepts, assesses, escrows, or recovers a shared secret.

5.0.1 Establishing the secret — the channel is part of the threat model#

The whole operator-blindness property rests on the two counterparties, and only them, holding the shared secret. If that secret is intercepted in transit, the scheme is defeated before a commitment is ever computed — so how the secret reaches the counterparty is in scope, not an implementation detail.

For v1, the establishment channel is out of band and pre-existing: the two institutions already run a trusted channel to agree a corridor at all (the same channel that ratifies the corridor table and exchanges member key fingerprints at onboarding), and the generated secret is delivered over that channel. The reference bander's new-secret command writes it to an owner-only file for exactly this hand-off; it is never printed to a shared terminal and never emailed in the clear.

A stated limitation, and the intended v2: the secret is currently a symmetric value delivered over a trusted side channel, not derived. A later version SHOULD establish it by authenticated key agreement between the institutions' already-registered long-term keys — an X25519 ECDH with the shared value run through HKDF-SHA256 and bound to the corridor and a per-shipment identifier — so that no secret value ever transits any channel and compromise of one shipment's material does not touch another's. That is deliberately not claimed as built: shipping an unaudited key-agreement path would be a worse trade than stating plainly that today the channel is trusted and out of band.

5.1 Two dimensions, not one#

Banding price-per-unit alone conflates two independent frauds. A party that inflates quantity and deflates unit price by matching factors produces a price-per-unit band that matches perfectly while the trade is a structure; and quantity short-shipment is invisible to a price band entirely.

So quantity and unit price are banded and compared separately, each under its own domain-separated reference ("mirror-dim:<dimension>:<locator>") so each dimension gets its own salt and a band-2 quantity commitment can never collide with a band-2 price commitment.

The combination rule that makes it worth building: a dimension that agrees never masks one that disagrees. Any diverging dimension makes the whole reading divergent. The reading also judges the union of the policy's dimensions and the dimensions actually present, so a party cannot hide a divergence by simply not banding that dimension.

6. Time — matching windows#

The legs of a trade are not same-day. Without a time model, "undetermined" is meaningless and a clear is indefensible, because nothing establishes that the legs belong to one trade.

A window is [anchor + min_days, anchor + max_days], closed at both ends, running forward. Party-supplied per corridor; the defaults below are conventions, not law:

Everything ambiguous is undetermined, never a pass: a leg out of window, an undated leg, a stale corridor table, legs banded against different table versions, or a leg dated after the supplied clock.

One distinction matters operationally more than any other in this section: a window that is still open with a leg missing is pending — the trade is in flight. A window that has closed with a leg missing is a finding. Conflating them either floods the queue with in-flight trades or silently drops the structure.

Nonsense window policy falls to the stricter default, never the looser one, and every substitution is recorded on the face of the record.

7. The verdict — three states, and no fourth#

reconciled  | divergent | undetermined

• There is no score. There is no 0.73 likely laundering. A probability would make Mirror an accusation engine, and would put a number in front of an examiner that no one can defend.
• cleared is true only for reconciled.
• Fail-closed runs the opposite way to a permissions system. Here the dangerous act is clearing a trade that should have been looked at, so ambiguity must never clear. A missing leg, an unbandable value, an unreadable commitment, or legs banded against two different corridors all yield undetermined. You reach a clear only on positive evidence that the legs agree.

Every verdict — including a clear — is signed and canonical. The clear is the product: an examiner asks "why did you not escalate this?" and the answer is a portable file they can check themselves.

7.1 What a clear asserts — exactly#

A reconciled verdict asserts that the parties' committed band labels agree. It does not assert that each label is the band of its submitter's true value: that link is checked at opening (§8), and, where a leg is bound to an origination document (§7.4), against the bank's own signed document. Every record MUST carry an asserts block stating this, with label_equals_value_band: "not_proven_here". A verifier MUST reject a record whose asserts block does not restate the record's own fields.

The governed match ceiling. A clear is only as strong as the window its legs agreed within. When the named corridor ratified a max_ratio, a comparison that agreed stays reconciled only if the match window is bounded (a closed table, §5) and its widest ratio is at most the ceiling. Otherwise — the window reaches an open band, exceeds the ceiling, or cannot be read at all (a corridor the operator holds no edges for) — the verdict is undetermined with undetermined_reason: "match_ceiling" and the ratified max_ratio on the record. A ceiling is never skipped into a clear. Like the independence gate (§7.2), the hold moves reconciled to undetermined only, so an offline verifier that recomputes the join and finds it reconciled MUST accept a record held for match_ceiling, and MUST NOT accept the reverse.

7.2 The independence gate#

A comparison that comes out reconciled stays reconciled only if at least one anchor agreed. An anchor is evidence from a party with no stake in the price:

• a leg signed by a witness key the members ratified by quorum under an independent class (customs, terminal, port, weighbridge, carrier, warehouse, inspectorate, surveyor, assayer, certifier), whose organisation is not a stakeholder's; or
• evidence such a key signed: a terminal's commitment-bulletin entry proven by inclusion (§7.5), or a signed measurement.

The anchor MUST be competent on an axis the reading judged, and that axis MUST have agreed. A class lives on the ratified key, never on what a leg says about itself. A relayed document (a stakeholder's segregated desk, class relay) anchors only on a corridor that ratified anchor.accept_relayed. Otherwise the verdict is undetermined, with undetermined_reason: "insufficient_independence". The gate moves reconciled to undetermined only. It never mints a clear, never softens a divergence and never produces a fourth state.

7.3 Nested resolution#

Legs MAY also commit at fine resolution under the same salt: sha256(salt ":fine:" band) against a fine table that contains every coarse edge. Coarse agreement with fine disagreement is divergent on axis resolution. Once any leg commits finely, every leg MUST, under one agreed (or ratified) fine window; otherwise the reading is undetermined. Every ratified table has a signed geometry certificate stating the widest mispricing that still reconciles, as a ratio (public) and an amount per unit (members). A corridor MAY be ratified as a citation of a published figure, with a closed field set and no price. Each bank derives the nested table party-side.

7.4 Label integrity#

A corridor MAY ratify its bander builds (a leg from any other build is undetermined) and MAY require every label to be bound to an origination document. That is a commitment to the document's figures, signed at booking by a key of class origin held by the bank's trade system and never by the bander. A leg MAY commit its pricing basis (currency, unit, Incoterm, place); a basis mismatch is undetermined. The leg signature MUST cover every block it carries: fine commitments, physical, dimensions, origin, basis, bander pin.

7.5 Physical witnesses, paths and services#

A terminal publishes an RFC 6962 commitment bulletin of H(locator, mass commitment, table commitment) entries, salted by a receipt secret that travels with the cargo's papers, and signs the head with its ratified witness key. The operator verifies inclusion and compares the terminal's mass commitment with each stakeholder's declared-mass set; it sees no kilogram and no container number. A path certificate counts one cargo's hops by opaque locator (states, declared free-zone hops, hops without an independent or customs-class anchor, and drift from mirror-chain), proves each hop into the verdict log, and is released to a member only when k institutions other than the requester stand behind it. Services use an obligation key derived from the signed statement of work, band hours and rate as two dimensions, and are witnessed only by a ratified certifier.

7.6 A cited benchmark#

A corridor MAY require a leg with the role benchmark: a public market figure (a settlement price, a published assessment) that one party cites, obtains itself and commits under the shipment's own salt and the corridor's table exactly as any leg, with unit quantity 1 and a tolerance equal to the market window the parties agreed (2w+1 commitments, w at most 6). It is compared pairwise with every other required role like any leg, so requiring it can only add a divergent pair; it can never remove one. Three rules keep it from changing what a clear asserts about the trade legs:

• The operator MUST NOT count a benchmark leg when it infers the tolerance for the match window (§5): the window describes the trade legs. A record whose required roles include benchmark states the benchmark's own window in its reason.
• A benchmark leg takes no part in nested resolution (§7.3). It is compared at the corridor's resolution only, by the operator and by every verifier that recomputes the join.
• It is outside a corridor's origination requirement (§7.4): it cites a public document, not a booking. A pricing basis it commits MUST match the trade legs', or the reading is undetermined.

A benchmark is not a witness and never satisfies the independence gate (§7.2). Mirror supplies, fetches and chooses no figure: the citation and the figure stay with the party that committed the leg, and are checked at opening against the public document.

8. Signing and the Clear File#

• ES256 (ECDSA P-256) over the record as canonical JSON: recursively sorted keys.

• The signature covers canonical text, never an object. Handing an object to a signer stringifies it as "[object Object]" — a constant — so every record would carry the same signature and any signature would verify. The implementation canonicalises internally so a caller cannot make that mistake.

• A record must contain no undefined-valued keys. canonical() signs them as null while JSON.stringify drops them, so a genuine record would fail its own signature after one wire round trip. This is test-enforced on every emitted record.

• Key id, derived from the public half only, so signer and verifier reach the same id independently:

  kid = "mir-" + sha256(canonical({crv, kty, x, y})).slice(0, 16)

• Verification selects the key by proof.kid, never keys[0] — a JWKS carries several keys through rotation.

8.1 Input attestation — signing the legs, not only the verdict#

An operator signature proves one thing: that this operator computed this verdict. It says nothing about whether the inputs were real. Without input attestation, a compromised operator can copy the invoice bank's commitments into the customs slot, obtain a mathematically perfect agreement, and sign a clear that is cryptographically flawless and factually invented — and every offline verifier in the world would accept it.

So each member signs its own leg, with the same ratified member key the registry already publishes and member login already uses. No second key hierarchy and no second directory.

leg_envelope = { v: 1, type: "mirror.leg-commitment/v1",
                 shipment_ref, role, commitments (sorted), corridor_commitment, kid }
attest       = { alg: "ES256", kid, sig = ES256(canonical(leg_envelope)) }

Every binding in that envelope is load-bearing: shipment_ref stops a leg being replayed onto another trade, role stops it being pasted into another slot, commitments stops any alteration, corridor_commitment stops re-judging under a different table, and kid puts the author inside the signed bytes. The type tag is domain separation — a leg attestation can never be replayed as a governance vote, a login assertion, or a cosignature.

The operator verifies each attestation against the active ratified member directory, re-checking membership on every request, and embeds the attestations in the verdict. A supervisor holding the verdict and the published keys then re-checks every input offline, trusting the operator for nothing.

Normatively:

• A leg whose signature does not verify, whose kid is unknown, or whose kid is not an active ratified member MUST make the shipment undetermined. Unverifiable is treated as bad, never as absent — otherwise corrupting a leg would be a way to delete it.
• Equivocation — one member signing two different commitment sets for the same role on the same shipment — MUST make the shipment undetermined and MUST be attributed to that member.
• A leg carrying no attestation MAY still reconcile, so a rail can migrate without breaking, but the verdict MUST state that its inputs were unauthenticated. An implementation MUST offer a strict mode in which unsigned legs are undetermined, and the verdict MUST record which regime it was judged under.
• Offline verification returns exactly three outcomes: AUTHENTIC, TAMPERED, or UNAUTHENTICATED_INPUTS. "Probably fine" is not one of them.

What this does not fix: signatures defeat forgery, not censorship. An operator can still withhold a leg and report it missing, and no signature scheme can compel delivery. The member's own signed copy of that leg is the counter-evidence — the verdict says the leg was absent, the member holds a signed leg for that exact shipment and role, and both cannot be true. That is a dispute with proof rather than an argument, and §11's dispute mechanism is where it goes.

The Clear File is the artifact an examiner receives: a self-contained HTML file that re-verifies every signature in the browser, with the network unplugged, plus the canonical JSON for the archive. It has no external references of any kind, and is served under a Content-Security-Policy that forbids it from making any network request at all — so "it cannot call home" is enforced by the browser, not promised by us.

8.2 Canonical forms and derivations (normative)#

Everything an independent implementation must reproduce byte for byte. Each rule is pinned by named vectors in /conformance-vectors.json, and conformance/reference-impl.js reproduces them from this text without importing the kernels. Where this text and a vector disagree, that is a defect to report.

Text and canonical JSON

• canon(v):
  • an array is [ + its elements' canon, comma-joined, in order + ];
  • an object is { + JSON(key):canon(value), comma-joined, keys sorted by UTF-16 code unit + };
  • anything else is JSON(v), where undefined becomes null.
  • JSON is ECMAScript JSON.stringify: shortest round-trip numbers, standard string escapes, no whitespace.
• Signed string values are ASCII. A record carrying another character is a defect of the emitter, not a variant to accept.
• lp(x) = the decimal length of x in UTF-16 code units, then ":", then x. Every multi-part hash below length-prefixes its parts, so no two part-lists collide.
• H(x) = lowercase hex SHA-256 of the UTF-8 bytes of x.

Exact decimal banding

• A decimal is its mantissa and base-10 scale, read from its shortest string. Exponent notation, non-finite and non-positive values do not band.
• value / unit_qty > edge iff v·10^(s_e+s_q) > e·q·10^(s_v), in integers.
• band = the number of ascending edges passed, stopping at the first that fails.
• There is no floating-point division anywhere on the path.

Commitments

Physical witness (§7.5)

• cargo_key = the ISO 6346 container number (check digit verified) + "|" + the UN/LOCODE + "|" + the load date YYYY-MM-DD.
• derive(label) = H(lp(receipt_secret) + lp("mirror:bulletin:" + label + ":v1") + lp(cargo_key)).
• locator = "cl:" + derive("locator"); salt = "ps:" + derive("salt").
• mass commitment = H(lp(salt) + lp("mirror:bulletin:mass") + lp(band_kg)), where band_kg = bandOf(kg, 1, kg_edges). A declared set covers the tolerance window and is listed sorted as strings.
• quality commitment = the same with "mirror:bulletin:quality".
• table commitment = H(lp(salt) + lp("mirror:bulletin:table") + lp(corridor_id(edges))).

Keys and signatures

• kid = "mir-" + H(canon({crv, kty, x, y})).slice(0, 16).
• An ES256 signature is r‖s, base64url, with low-S (s ≤ n/2). A high-S twin is the same signing, never a second record.

Webhooks

• subscription id = "wh_" + H("mirror:webhook-subscription:v1|" + canon({kid, url, events})).slice(0, 24).
• delivery id = "whd_" + H("mirror:webhook-delivery:v1|" + subscription_id + "|" + H(canon(judgement(record)))).slice(0, 32).
• judgement(record) = the record with every property named sig or signature removed, at any depth. A failover resubmission re-signs the same commitments, so it is the same judgement: one delivery, and one verdict in every count.

Field names at the wall

A key is compared after this normalisation:

1. NFKC;
2. invisible characters removed;
3. listed confusables folded;
4. camelCase split to snake_case;
5. lowercased;
6. runs of non-alphanumerics collapsed to one underscore;
7. edge underscores trimmed.

Unit Price, unitPrice and unit_price are one field.

9. What each party can learn — stated exactly#

This section is the one a DPO should read twice. It is deliberately unflattering.

The operator learns: that two legs did or did not land in the same band; that they were banded against the same corridor (not which); opaque locator, entity and node commitments; counts; timestamps. It cannot invert a commitment: it lacks the salt, which is derived from a secret it never holds.

A counterparty learns more than the operator, and this is the real boundary. The two parties on a trade share the per-shipment secret. A price band is low-cardinality — typically 12–24 buckets per product — so a counterparty can brute-force the other's band by hashing every candidate. That is not a flaw to be patched; it follows from the threat model. Mirror's threat model is "do not pool raw trade data at a central operator, and do not expose it to unrelated members" — not "hide the two legs from each other." The two banks on a trade are, by construction, already jointly examining one shipment.

This is not zero-knowledge, not secure multi-party computation, and not homomorphic encryption. Anyone claiming those without building them would be lying. Where the counterparty-visibility gap actually matters to a member, Mirror ships real private set intersection (Diffie–Hellman PSI on P-256) as a separate, party-to-party step which closes exactly that brute-force — and which is honest-but-curious secure only, and is documented as such including the reflection attack it cannot detect.

Graph topology leaks. Flow edges and chain hops reveal structure to the operator even though the nodes are opaque. The mitigation is a k-anonymity release gate that withholds an edge until k distinct members have contributed to its window — which delays detection, a real cost, stated rather than hidden.

What Mirror can never do: compare either party to the physical world. Two colluding parties who agree a consistent lie reconcile perfectly. Mirror compares parties to each other.

10. Attribution, legal basis, and the SAR wall#

• A trigger may name the member that raised it, and that name counts only if a signature proves it. Otherwise any holder of the pilot token could post the same entity twice under two member names and manufacture "corroborated by two institutions" out of one bank's hunch. Unsigned triggers are still accepted and still score; they simply stay unattributed and can never become a second source.
• A cross-institution signal is shared under a named legal basis (FinCEN 314(b), UK ECCTA ss.188–189, EU AMLA, or explicit consent) or not at all. The basis is bound into the signature, so a member is cryptographically on record for the basis it asserted and cannot later disclaim it.
• The SAR wall. The rail is structurally incapable of holding a suspicious-activity filing decision. Any field naming one is refused at the door on every endpoint, at any nesting depth. Two reasons, both load-bearing: disclosing that a SAR was filed is a tipping-off offence in most jurisdictions; and if a Mirror record could hold a filing decision, the archive becomes a different legal object and members would rationally stop submitting the awkward trades. The joint-SAR conversation happens off-rail, referring to a Clear File id.

11. Supervision without disclosure#

Verdicts are appended to an RFC 6962-shaped transparency log. A supervisor holds signed tree heads and demands consistency proofs, which prove a newer head append-only-extends an older one: nothing inserted, reordered, or removed. It never sees a value.

If the operator ever signs two different roots at the same tree size, it has signed two contradictory histories — and because both are signed, that is non-repudiable proof of operator misbehaviour. This is why multiple independent supervisors comparing heads is what makes the guarantee real.

A supervisor shown nothing reports undetermined, never "consistent". A supervisor that says "all good" because it was shown no evidence is worse than no supervisor at all.

12. What this protocol does not do#

• It does not prove a trade is legitimate. A clear is a defensible record of why a trade was not escalated, never a guarantee of innocence.
• It does not prove a divergence is laundering. A divergence is a reason to look.
• It does not prove, at reconciliation, that a committed label is the band of its submitter's true value. That is checked at opening, against the bank's own origination document where one is bound (§7.4). A proof of it at reconciliation would need a zero-knowledge circuit, and none is part of this protocol.
• It does not prove that parties who all have a stake in the price told the truth. That is why a clear needs an independent anchor (§7.2), and why an anchor confirms only the axis it is competent on.
• It does not prove completeness of participation. A trade never submitted to the rail is invisible to it. The completeness digest proves a member disclosed the whole set it committed to — not that it committed everything it did.
• It does not verify that corridor tables are correct. Garbage corridors give garbage bands, and no part of the mechanism can tell a wrong price table from a right one.
• It does not measure detection rate or false-positive rate. No such measurement is performed here and none is implied.

13. Conformance#

An independent implementation earns a signed conformance certificate by reproducing generated test vectors byte-for-byte. There is no partial pass. The challenge is stateless — the seed re-derives the reference — so the operator keeps no memory of what it issued.

This exists so the commitment format can become something the industry emits even when it is not anyone's customer, and so a member can verify a vendor's claim to speak the protocol rather than trusting a logo.

Mirror is a working name, after central-bank mirror statistics — the practice of comparing what one country says it exported against what its partner says it imported.