Corridor Reference

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.

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
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):

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

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

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

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.

System

Engines

Operations

Corridor Reference

Byte layout (version 2)

A real one, decoded

Where it lives on each chain

Codec

Design notes

​Byte layout (version 2)

​A real one, decoded

​Where it lives on each chain

​Codec

​Design notes

Byte layout (version 2)

A real one, decoded

Where it lives on each chain

Codec

Design notes