Watch-only architecture and merchant API

2. Deterministic D1 lease allocator

Because public watch-only manifests do not deploy per-invoice smart contracts (avoiding sweep gas), CCRails disambiguates concurrent sessions through atomic SQLite/D1 address_leases locks:

• EVM, Solana, and Tron: locks (project_id, chain, asset, address, amount_atomic) across 5 shards and 0..19 micro-cent offsets. Exact +$0.00 amounts allocate across all 5 shards before +0.01 is ever used.
• TON: single project V4R2 address paired with an opaque 12-character HMAC tag (computeOpaqueTonMemo) carrying no shared prefix or project slug on-chain.
• Bitcoin: dedicated per-lease Native SegWit (bc1q) address from the project's watch-only pool.

3. Exchange fee tolerance and cross-EVM rescue

Real buyers withdraw from centralized exchanges that deduct flat withdrawal fees from the outbound principal or broadcast on a sibling L2 network.

• Withdrawal fee absorption: sessions auto-settle as paid whenever shortfall_usd <= min($1.50, amount_usd * 7%), recording fee_absorbed in operator telemetry without opening percentage loopholes on high-ticket orders.
• Cross-asset and cross-EVM rescue: if a buyer sends USDT instead of USDC, or broadcasts on Arbitrum instead of Base to the same 0x shard, engine/rescue.ts values the transfer at live spot USD and settles when value meets threshold.
• Cumulative top-ups: underpaid sessions outside tolerance transition to partially_paid and sum multiple claimed transactions until complete.

4. HMAC-SHA256 signing and double-lock settlement

Every merchant API call and outbound webhook uses constant-time HMAC-SHA256 over ${tsSec}.${btoa(rawJsonBody)} with a strict 300-second anti-replay window (x-ccrails-ts). Storefronts enforce a two-step settlement lock before fulfilling orders:

// Step A: verify HMAC-SHA256 signature + 300s timestamp window
const verified = await verifyMerchantWebhook({
  request,
  rawBody,
  apiKey: env.CCRAILS_API_KEY,
});
if (!verified.ok) return new Response("Invalid signature", { status: 401 });

// Step B: authoritative pull cross-check against payment node
const info = await fetchMerchantPaymentInfo({
  pspOrigin: env.CCRAILS_PSP_ORIGIN,
  projectId: "my-storefront",
  apiKey: env.CCRAILS_API_KEY,
  token: String(verified.payload.token),
});
if (info.ok && info.session?.status === "paid") {
  await fulfillOrder(String(info.session.order_id));
}

5. Transport modes: redirect vs first-party stealth proxy

Each merchant chooses between direct checkout redirect (https://pay.ccrails.dev/:token) or server-to-server first-party proxying via the zero-dependency proxy_adapter.ts helper:

• Direct checkout redirect (psp_redirect): storefront creates a signed session via POST /api/v1/payment and redirects the buyer 302 to pay.ccrails.dev/:token.
• First-party stealth proxy (first_party_proxy): forwardFirstPartyCheckout() intercepts /pay/:token and /api/v1/payform/:token/* inside your storefront Worker (x-ccrails-proxy: 1), keeping buyers on <merchant-domain>/pay/:token.

6. Verified 20-route asset and network table

All routes below are verified against public RPC endpoints with confirmation floors calibrated per chain finality.