nota-mail (proposal)

This page is an internal proposal for the engineering team. Nothing here ships until scoped and approved. Endpoints and screens shown below are illustrative.

The idea in one paragraph

nota-mail turns a private cAROUSD transfer into a physical letter. The sender prints (or has AroPay print and mail) a letter carrying a QR code and short claim code. The recipient scans the QR, lands on a claim page, signs in or creates a wallet, and the escrowed cAROUSD moves into their wallet. From there they can hold cAROUSD, transfer it privately, or redeem it for USDC or USDT. AroPay delivers the digital dollars; local fiat conversion is the recipient’s responsibility.

Why it fits AroPay

Extends confidential transfers into an offline delivery channel while preserving the same encrypted-amount guarantees.
Reuses .nota files as the identity artifact and visual language.
Reaches recipients without existing wallets or reliable internet at send time.
Enterprise use cases: remittances, gifts, disaster relief, legal payments, unbanked payouts.

Scope boundary

AroPay owns

Escrow, print, mail, claim, delivery of cAROUSD to the recipient’s wallet, and redeem to USDC/USDT.

AroPay does not own

Local fiat conversion (NGN, INR, PHP, etc.), bank payouts, or off-ramp partnerships. The recipient handles cash-out.

nota-mail as a 7-layer stack

The OSI model is a useful frame here because nota-mail is a protocol: it takes value at one end, encodes it through several independent layers (crypto, escrow, print, postage, scan, claim), and reconstructs it at the other end. Each layer has one job and a clean handoff to the next. If a layer fails (letter lost, QR damaged, wallet not set up), only that layer needs recovery, not the whole system.

L1 \u00b7 Physical: the paper letter

The actual sheet of paper carrying ink. AroPay owns the layout template; the postal carrier owns the transit.Responsibilities: paper stock, print quality, QR contrast, tamper-evident fold. Failure mode: letter lost, damaged, or destroyed in transit. Recovery: expiry sweep at L5, then void at L4.

L2 \u00b7 Data link: envelope, stamp, provider handoff

The framing layer that gets a letter from AroPay onto the postal network. POST /transfer/letter/{id}/mail selects a provider (Lob, PostGrid, Letter Labs) and a deliveryMethod (standard, tracked, courier). Postage is Forever stamps domestic, Global Forever international.Responsibilities: provider API, postage math, tracking IDs, courier fallback. Failure mode: 402 postage_unavailable, provider outage. Recovery: retry with alternate provider; escalate to courier for high-value letters.

L3 \u00b7 Network: addressing and routing

Global address resolution. Flexible schema so recipient addresses in Nigeria, India, or the Philippines route as cleanly as US ones. Uses ISO 3166 country and 3166-2 region codes; postal optional; landmark supported.Responsibilities: address validation, country-aware rules, sanctions/PEP screening on names and addresses. Failure mode: 400 invalid_postal_address, sanctions hit. Recovery: sender fixes address at L7 and reissues; sanctions hits are hard-fail.

L4 \u00b7 Transport: escrow of encrypted value

The reliable-delivery layer. POST /transfer/letter moves cAROUSD from the sender’s custodial wallet into an escrow state, encrypted under FHE. Value cannot be lost or duplicated regardless of what happens at L1\u2013L3.Responsibilities: debit sender, hold ciphertext, honor void, honor expiry sweep. Failure mode: 400 validation_error (insufficient balance), 502 transfer_failed. Recovery: transaction row carries the error; sender retries.

L5 \u00b7 Session: claim lifecycle

The one-time session that binds a physical letter to a single successful claim. 128-bit claim secret, base32 encoded with checksum, embedded in the QR and printed as 6H2K-QT4P. Status machine: ESCROWED \u2192 MAILED \u2192 CLAIMED | EXPIRED | VOIDED.Responsibilities: atomic status flip, single-use enforcement, expiry timers, void authorization. Failure mode: 409 already_claimed, 410 letter_expired. Recovery: expired letters auto-refund the sender; already-claimed letters are terminal.

L6 \u00b7 Presentation: how the letter looks

Rendering of the escrowed transfer into something a human can read and a phone camera can decode. PDF layout, QR encoding, sealed vs. visible amount, sender/recipient blocks, expiry, and .nota-style branding.Responsibilities: PDF generation, QR contrast, amountVisibility: sealed | visible, localization of labels. Failure mode: 400 amount_visibility_invalid, unreadable QR. Recovery: regenerate PDF from the same letter id at L5; the escrowed value at L4 does not change.

L7 \u00b7 Application: sender and recipient intent

What a human is actually trying to do. Sender: “pay Jane $50 privately, she has no wallet yet.” Recipient: “claim the letter I received.”Responsibilities: sender UX for creating the letter, recipient UX at claim.aropay.aro.media/{code}, optional redeem to USDC/USDT after claim. Failure mode: recipient scans but abandons wallet setup. Recovery: hold claim reservation for N minutes (open question), then release the code for retry.

Layer boundary at claim

When the recipient scans, the layers unwind in reverse: L1 delivers paper, L6 decodes the QR, L5 validates the session, L4 releases escrow into the recipient’s wallet. L7 then decides what to do next: hold, transfer, or redeem.

End-to-end flow

Status machine

DRAFT → ESCROWED → MAILED (optional) → CLAIMED | EXPIRED | VOIDED

What the letter looks like

Rendered mockup of a sandbox letter. Real letters use the recipient’s postal address and a signed QR payload.

AroPay · nota-mail

Confidential Letter of Value

LETTER ID

cklet0001a2b3

From

Acme Payroll, Inc.
Wallet 0x8Ba1…BA72

Jane Doe
12 Adeola Odeku Street
Victoria Island, Lagos LA
Nigeria

Sealed amount

••••••• cAROUSD

Revealed to recipient on claim

Claim at

claim.aropay.aro.media/6H2K-QT4P

Or enter code

6H2K-QT4P

Expires 2026-11-13One-time claim · Do not photograph

Illustrative API

Final shape lives in the OpenAPI spec once scoped. This is the shape the flow assumes.

Create a letter

POST /transfer/letter

{
  "walletId": "ckwlt0001...",
  "amount": "50",
  "recipient": {
    "name": "Jane Doe",
    "address": {
      "line1": "12 Adeola Odeku Street",
      "line2": "Victoria Island",
      "landmark": "opposite Eko Hotel",
      "city": "Lagos",
      "region": "LA",
      "country": "NG"
    }
  },
  "memo": "Thanks for the referral",
  "amountVisibility": "sealed",
  "expiresInDays": 45,
  "format": "pdf"
}

{
  "ok": true,
  "data": {
    "letter": {
      "id": "cklet0001a2b3",
      "status": "ESCROWED",
      "claimUrl": "https://claim.aropay.aro.media/6H2K-QT4P",
      "claimCode": "6H2K-QT4P",
      "pdfUrl": "https://.../letters/cklet0001a2b3/letter.pdf",
      "expiresAt": "2026-09-29T00:00:00.000Z",
      "amount": { "encrypted": true, "handle": "0x8f2c..." }
    }
  }
}

Print and mail on the sender’s behalf

POST /transfer/letter/{id}/mail

{ "deliveryMethod": "tracked", "provider": "lob" }

Claim

POST /transfer/letter/claim

{ "claimCode": "6H2K-QT4P", "walletId": "ckwlt0004..." }

Moves cAROUSD from escrow into the claiming wallet. Idempotent, single-use.

Void

POST /transfer/letter/{id}/void

Returns funds to the sender while status === "ESCROWED".

Design constraints for the team

Claim secret. 128-bit random, base32 with checksum, embedded in QR and printed code.
Single-use claim. Atomic status flip; second scan returns 409 already_claimed.
Sealed vs visible amount. sealed (default for international) hides amount on the printed letter; visible prints it.
Expiry sweep. Background job refunds sender after expiresAt. Default 90 days domestic, 45 days international.
Address flexibility. Do not require postal. Accept landmark. Use ISO 3166-2 regions.
Fulfillment abstraction. Thin provider interface: Lob, PostGrid, Letter Labs. Postage via Global Forever for international.
Sanctions/PEP screening. Runs on POST /transfer/letter before escrow, on recipient name and address.
Velocity limits. Per-country cap on unclaimed letters in flight.
New failure modes. 400 invalid_postal_address, 400 amount_visibility_invalid, 402 postage_unavailable, 404 letter_not_found, 409 already_claimed, 410 letter_expired.

Open questions

Escrow: new contract or a locked-balance pattern on cAROUSD?
Fulfillment provider of record for MVP: Lob, PostGrid, or Letter Labs?
Print amount on the envelope for postal insurance, or fully sealed until claim?
Recovery flow if the recipient scans but never completes wallet setup: how long do we hold the reservation?
Country rollout: US-only pilot, or open international from day one with a per-country flag?

Docs impact when it ships

New guide Send a nota-mail letter under Guides, sibling to Send transfers.
Update the mint/redeem diagram on Confidential transfers to include the escrow → mail → claim path.
Add letter endpoints to the API reference.
Add an Availability matrix (supported countries, delivery methods, transit times).

Get started

Core concepts

Guides

Security & access

Support

nota-mail (proposal)

The idea in one paragraph

Why it fits AroPay

Scope boundary

AroPay owns

AroPay does not own

nota-mail as a 7-layer stack

Layer boundary at claim

End-to-end flow

Status machine

What the letter looks like

Illustrative API

Create a letter

Print and mail on the sender’s behalf

Claim

Void

Design constraints for the team

Open questions

Docs impact when it ships

​The idea in one paragraph

​Why it fits AroPay

​Scope boundary

AroPay owns

AroPay does not own

​nota-mail as a 7-layer stack

​Layer boundary at claim

​End-to-end flow

​Status machine

​What the letter looks like

​Illustrative API

​Create a letter

​Print and mail on the sender’s behalf

​Claim

​Void

​Design constraints for the team

​Open questions

​Docs impact when it ships

The idea in one paragraph

Why it fits AroPay

Scope boundary

nota-mail as a 7-layer stack

Layer boundary at claim

End-to-end flow

Status machine

What the letter looks like

Illustrative API

Create a letter

Print and mail on the sender’s behalf

Claim

Void

Design constraints for the team

Open questions

Docs impact when it ships