> ## Documentation Index
> Fetch the complete documentation index at: https://corridor.udokaam.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Corridor Reference

> One 32-byte identifier, carried in the native memo field of every chain a payment touches, that lets chain logs, partner webhooks and the ledger reconcile without an indexer.

Every Corridor movement carries the same 32-byte **Corridor Reference**: in Tempo's TIP-20 memo, in a Solana SPL Memo, in each Zcash output's encrypted memo, and in the partner's free-text field. Reconciliation is a join on this value.

<Frame caption="Fig. 04 · The 32-byte Corridor Reference of a real NGN → CNY payout, and the field that carries it on each venue.">
  <img className="block dark:hidden" src="https://mintcdn.com/corridorapp/YeOtjsXcStLLcZ_W/images/diagrams/corridor-reference-light.svg?fit=max&auto=format&n=YeOtjsXcStLLcZ_W&q=85&s=7710c4e6af55dfa9b8e53a29ddbbcbc4" alt="Corridor Reference byte layout and carriers" width="1200" height="520" data-path="images/diagrams/corridor-reference-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/corridorapp/YeOtjsXcStLLcZ_W/images/diagrams/corridor-reference-dark.svg?fit=max&auto=format&n=YeOtjsXcStLLcZ_W&q=85&s=8f43a5c463fc73c604899b846a20fc2a" alt="Corridor Reference byte layout and carriers" width="1200" height="520" data-path="images/diagrams/corridor-reference-dark.svg" />
</Frame>

## Byte layout (version 2)

| Bytes | Field | Notes |
| - | - | - |
| 0 | Version | `0x02` |
| 1 | Kind | payout `0x01` · batch `0x02` · batch item `0x03` · sweep `0x04` · deposit `0x05` · collection `0x06` |
| 2 | Funding currency | One-byte index from the [currency table](/architecture/core-model#currencies) |
| 3 | Beneficiary currency | Same table, so `GHS-HKD` needs no registry change |
| 4 | Flags | bit 0 = shielded |
| 5–20 | Payment id | UUIDv7 (16 bytes): time-ordered, globally unique |
| 21–27 | Customer tag | 7-byte keyed hash (HMAC) of the customer id: links payments to a customer without naming them on a public chain |
| 28–31 | Checksum | First 4 bytes of SHA-256 over bytes 0–27 |

## A real one, decoded

The payout that paid a Shenzhen supplier ¥7,140 on testnet carries this reference in its Tempo `TransferWithMemo` log ([transaction](https://explore.testnet.tempo.xyz/tx/0x671161f61c70a0b5b33c6c8de4221c938d86c310958725146ea9f21517957b5e)):

```text theme={"dark"}
0x 02 01 28 46 00 01a0eb3fe7e57ca994eb596e7f87c87f 33d74bd58688d8 53957c1f
   │  │  │  │  │  │                                │              └ checksum ✓
   │  │  │  │  │  │                                └ customer tag (keyed hash)
   │  │  │  │  │  └ payment id 01a0eb3f-e7e5-7ca9-94eb-596e7f87c87f (UUIDv7)
   │  │  │  │  └ flags: public lane
   │  │  │  └ to: 0x46 = 70 = CNY
   │  │  └ from: 0x28 = 40 = NGN
   │  └ kind: payout
   └ version 2
```

## Where it lives on each chain

| Venue | Field | Why it fits |
| - | - | - |
| Tempo | TIP-20 `transferWithMemo(to, amount, bytes32 memo)`. The memo is an **indexed topic** of the `TransferWithMemo` event | Reconciliation filters logs by reference directly through `eth_getLogs`, with no indexer |
| Solana | SPL Memo instruction `corridor:<hex>` in the same transaction as the USDC transfer | The native pattern ramp partners already read |
| Zcash | ZIP-302 text memo on each Ironwood output: `INV-… / corridor:<hex>` | Encrypted to the recipient; readable only by the recipient and viewing-key holders |
| Partners | Free-text fields (Paj `description` / `userExternalId`), echoed back on webhooks | Lets partner events join the same reconciliation |

## Codec

```ts theme={"dark"}
import { encodeRef, decodeRef, customerTag, RefKind, uuidv7 } from "@corridor/core";

const ref = encodeRef({
  kind: RefKind.Payout,
  corridor: "NGN-CNY",
  shielded: false,
  id: uuidv7(),
  customerTag: customerTag("adeola-imports", process.env.CORRIDOR_REF_SECRET!),
});

decodeRef(ref); // validates version, kind and checksum; throws on any mismatch
```

<Tip>
  The checksum makes a mistyped or truncated reference fail loudly at decode time rather than silently matching nothing in reconciliation.
</Tip>

## Design notes

* **Fixed 32 bytes** fits Tempo's `bytes32` memo exactly, so the hub carries it with no encoding overhead.
* **The currency pair is in the reference**, so any observer knows the corridor without a lookup.
* **No PII on-chain.** The customer tag is a keyed hash: anyone can see two payments share a tag, but only Corridor can say whose it is.
* **Versioned.** Version 2 encodes the currency pair directly rather than a corridor id, so any spoke is addressable without a registry change; decoders reject unknown versions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.