Aro Mail

​

The idea in one paragraph

​

Why it fits AroPay

• Extends confidential transfers into an offline delivery channel: all three money legs (escrow, release, refund) are cAROUSD confidentialTransfers with FHE-encrypted amounts.
• Reuses the sandbox’s custodial wallets, transaction ledger, receipts, and dashboard; every letter leg is a normal transaction row.
• Reaches recipients who have no wallet or no reliable internet at send time.
• Enterprise use cases: remittances, gifts, disaster relief, legal payments, unbanked payouts.

​

Scope boundary

​

aro-mail as a 7-layer stack

​

Layer boundary at claim

​

End-to-end flow

​

Status machine

• Every transition is guarded. Status changes are conditional updates keyed on the current status (and expiresAt for claims), so a second claimant, a concurrent void, and the expiry sweep cannot race each other into double-spending the escrow.
• Confirmed is not paid. ERC-7984 confidentialTransfer clamps an over-spend to an encrypted zero instead of reverting, so AroPay decrypts the ConfidentialTransfer event of every leg and compares it with the letter amount before moving the status. A clamped escrow becomes FAILED (400 insufficient_confidential_balance); a clamped release rolls the letter back to claimable (503 escrow_vault_underfunded).
• Refunds are tracked separately from status. refund on the letter points at the LETTER_REFUND transaction; a failed refund never un-expires or un-voids the letter and is retried by the sweep.
• Senders cannot claim their own letter (400 cannot_claim_own_letter), by account or by wallet address. Recovery is /void, so the audit trail always shows a void.
• Reads never move money. Listing letters or previewing a claim reconciles receipts and derives status, but refunds, releases and Lob calls only happen on owner detail reads, on the write endpoints, and in the sweep.

​

Escrow model and trust model

​

Claim code and claim URL

• Secret. 16 random bytes (128 bits) encoded in Crockford base32 (0123456789ABCDEFGHJKMNPQRSTVWXYZ, no I, L, O, U) plus two check symbols derived from the secret’s SHA-256, for 28 symbols displayed in groups of four: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX.
• Forgiving input. Codes are upper-cased, dashes and whitespace are stripped, and O→0, I→1, L→1 are corrected before the checksum is verified. Anything else is 400 invalid_claim_code.
• Storage. Only a SHA-256 hash is used for lookup; the code itself is encrypted at rest and returned to the owner in the create and detail responses while the letter is non-terminal. It never appears in list items, in the public preview, in URL paths or query strings, or in logs.
• Claim URL. https://<aropay-host>/claim#<code>: the code travels in the URL fragment, which browsers never send to the server. The claim page reads it, removes it from the address bar immediately, keeps it in session storage across sign-in, and never puts it in a redirect target. The QR encodes this URL. The origin is fixed when the letter is created (from the deployment’s AROPAY_PUBLIC_URL), so a reprint months later still points at the same place, and mailing requires an https: origin (400 claim_origin_not_public).
• Manual entry. The letter also prints the code under OR ENTER CODE for recipients whose camera cannot read the QR.

​

What the letter looks like

​

The API

​

Create a letter

POST /transfer/letter

{
  "walletId": "ckwlt0001abcd",
  "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
}

{
  "ok": true,
  "data": {
    "letter": {
      "id": "cklet0001abcd",
      "status": "ESCROWED",
      "chainId": 11155111,
      "amount": "50.00",
      "token": "cAROUSD",
      "amountVisibility": "sealed",
      "memo": "Thanks for the referral",
      "recipient": {
        "name": "Jane Doe",
        "address": {
          "line1": "12 Adeola Odeku Street",
          "line2": "Victoria Island",
          "landmark": "Opposite Eko Hotel",
          "city": "Lagos",
          "region": "LA",
          "postal": null,
          "country": "NG",
          "countryName": "Nigeria"
        }
      },
      "isDomestic": false,
      "expiresAt": "2026-10-22T09:45:00.000Z",
      "sender": { "walletId": "ckwlt0001abcd", "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72" },
      "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
      "claimUrl": "https://dev.aropay.aro.media/claim#7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
      "pdfUrl": "https://dev.aropay.aro.media/api/v1/transfer/letter/cklet0001abcd/pdf",
      "escrow": {
        "transactionId": "cktxn0005abcd",
        "txHash": "0x4d1e…",
        "explorerUrl": "https://sepolia.etherscan.io/tx/0x4d1e…",
        "status": "CONFIRMED",
        "verified": true
      },
      "claim": null,
      "refund": null,
      "mail": null,
      "needsReview": false,
      "error": null,
      "createdAt": "2026-09-07T09:45:00.000Z",
      "updatedAt": "2026-09-07T09:45:31.000Z"
    }
  }
}

​

Print and mail on the sender’s behalf

POST /transfer/letter/{id}/mail

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

​

Preview and claim

POST /transfer/letter/claim/preview

{ "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y" }

{
  "ok": true,
  "data": {
    "preview": {
      "state": "claimable",
      "amount": null,
      "token": "cAROUSD",
      "amountVisibility": "sealed",
      "senderName": "Acme Payroll, Inc.",
      "memo": null,
      "expiresAt": "2026-10-22T09:45:00.000Z",
      "claimedAt": null,
      "chainId": 11155111
    }
  }
}

POST /transfer/letter/claim

{ "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y", "walletId": "ckwlt0004abcd" }

​

Void

POST /transfer/letter/{id}/void

{ "acknowledgeMailed": true }

​

Addresses, destinations and limits

​

Defaults

​

Error codes

​

Decisions made for the MVP

1. Escrow is the operator vault plus a Postgres ledger; there is no escrow contract. Every leg is a verified cAROUSD confidentialTransfer; the ledger row (SandboxLetter) is the source of truth for who owns what, and every status change is a guarded conditional update.
2. Lob is the only fulfilment provider. PostGrid, Letter Labs and courier delivery are not offered; the provider interface exists so they can be added, and deliveryMethod: "courier" returns 400 delivery_method_unavailable.
3. Postage is priced and applied by Lob. There are no Forever or Global Forever stamps; standard is USPS First Class, tracked adds Certified (US) or Registered (international).
4. The claim code is 28 characters, Crockford base32 with two check symbols, printed as seven groups of four. The eight-character 6H2K-QT4P sketch is gone.
5. The claim URL is https://<aropay-host>/claim#<code> on the AroPay host itself, with the code in the URL fragment. There is no claim.aropay.aro.media/{code} subdomain and the code never travels in a path or query string.
6. amount_visibility_invalid and the format field are gone. An invalid amountVisibility is an ordinary 400 validation_error; the PDF is the only format and is fetched from GET /transfer/letter/{id}/pdf.
7. Screening is a country allow/block hook only. No sanctions/PEP provider is wired in; 403 recipient_blocked is reserved for one.
8. No claim reservation. A code stays claimable until it is claimed, voided or expired; a recipient who scans before they have an account can come back later.
9. Letters are English-only. No label localisation in the MVP.
10. Nothing is printed on the envelope beyond the address Lob applies; the amount is never visible from outside, regardless of amountVisibility.
11. Void is allowed after mailing, with an explicit acknowledgeMailed: true (stop-payment semantics); the paper letter then fails with 409 letter_not_claimable.
12. Senders cannot claim their own letter, by account or by wallet address (400 cannot_claim_own_letter); they void instead.
13. No self-service sign-up. Recipients need an AroPay account provisioned by Aro Media; the claim page explains this and points to support@aro.media.

​

Availability

​

Not in the MVP

​

Related

• Send Aro Mail: the step-by-step guide.
• Confidential transfers: how the escrow, release and refund legs stay private.
• Transactions: the LETTER_* rows every leg writes.