@txnod/sdk 1.0.1

package/docs/examples/nextjs-route-handler.md

@@ -0,0 +1,206 @@
+---
+title: "Next.js 16 App Router — create invoice + verify webhook"
+description: "Two complete route handlers: POST /api/checkout to create an invoice, POST /api/txnod-webhook to verify and handle events."
+sdk_version: 1.0.0
+---
+
+# Next.js 16 App Router example
+
+Two files. Both run on the Node.js runtime (the SDK uses `node:crypto`). Do not set `runtime = 'edge'` on these routes.
+
+Assumed env vars (see [`../00-getting-started.md`](../00-getting-started.md)):
+
+```
+TXNOD_PROJECT_ID=01JXXXXXXXXXXXXXXXXXXXXXXX
+TXNOD_API_SECRET=...
+TXNOD_WEBHOOK_SECRET=... # same value as TXNOD_API_SECRET
+```
+
+## Shared client — `src/lib/txnod.ts`
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+export const txnod = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+```
+
+## Create invoice — `src/app/api/checkout/route.ts`
+
+```ts
+import { randomUUID } from 'node:crypto';
+import {
+  TxnodCoinNotEnabledError,
+  TxnodError,
+  TxnodExternalIdConflictError,
+  TxnodPoolExhaustedError,
+  TxnodRateLimitError,
+  TxnodValidationError,
+} from '@txnod/sdk';
+import { txnod } from '@/lib/txnod';
+
+export const runtime = 'nodejs';
+
+export async function POST(request: Request): Promise<Response> {
+  const body = (await request.json()) as {
+    order_id: string;
+    amount_usd: number;
+    coin: 'btc' | 'eth' | 'usdt_erc20' | 'usdc_erc20' | 'trx' | 'usdt_trc20' | 'ada' | 'pol' | 'usdt_polygon' | 'usdc_polygon' | 'bnb' | 'usdt_bep20' | 'usdc_bep20' | 'ton' | 'usdt_ton';
+  };
+
+  try {
+    const invoice = await txnod.createInvoice({
+      external_id: body.order_id ?? randomUUID(),
+      coin: body.coin,
+      amount_usd: body.amount_usd,
+      callback_url: new URL('/api/txnod-webhook', request.url).toString(),
+      metadata: { source: 'checkout' },
+    });
+
+    return Response.json({
+      invoice_id: invoice.id,
+      pay_to: invoice.address,
+      amount_crypto: invoice.amount_crypto,
+      amount_crypto_units: invoice.amount_crypto_units,
+      payment_uri: invoice.payment_uri,
+      expires_at_iso: invoice.expires_at_iso,
+    });
+  } catch (err) {
+    if (err instanceof TxnodExternalIdConflictError) {
+      // Idempotent: fetch the existing invoice and return it.
+      const page = await txnod.searchInvoices({
+        external_id: body.order_id,
+        limit: 1,
+      });
+      const existing = page.items[0];
+      if (existing !== undefined) {
+        return Response.json({
+          invoice_id: existing.id,
+          pay_to: existing.address,
+          amount_crypto: existing.amount_crypto,
+          amount_crypto_units: existing.amount_crypto_units,
+          payment_uri: existing.payment_uri,
+          expires_at_iso: existing.expires_at_iso,
+          reused: true,
+        });
+      }
+    }
+
+    if (err instanceof TxnodValidationError) {
+      return Response.json(
+        { error: 'validation_error', errors: err.raw.errors, request_id: err.request_id },
+        { status: 422 },
+      );
+    }
+
+    if (err instanceof TxnodCoinNotEnabledError) {
+      const rates = await txnod.getRates({});
+      return Response.json(
+        {
+          error: 'coin_not_enabled',
+          enabled_coins: Object.keys(rates.rates),
+          request_id: err.request_id,
+        },
+        { status: 422 },
+      );
+    }
+
+    if (err instanceof TxnodRateLimitError) {
+      return Response.json(
+        { error: 'rate_limited', retry_after_seconds: err.retry_after_seconds },
+        { status: 429 },
+      );
+    }
+
+    if (err instanceof TxnodPoolExhaustedError) {
+      return Response.json(
+        { error: 'pool_exhausted', retry_after_seconds: err.retry_after_seconds },
+        { status: 503 },
+      );
+    }
+
+    if (err instanceof TxnodError) {
+      return Response.json(
+        { error: err.error_code, request_id: err.request_id },
+        { status: err.status },
+      );
+    }
+    throw err;
+  }
+}
+```
+
+## Verify webhook — `src/app/api/txnod-webhook/route.ts`
+
+```ts
+import {
+  TxnodHmacError,
+  TxnodSignatureFormatError,
+  TxnodTimestampError,
+  verifyWebhookSignature,
+} from '@txnod/sdk';
+import { recordEventOnce, fulfilOrder, reverseOrder } from '@/lib/orders';
+
+export const runtime = 'nodejs';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text(); // exact bytes, do not pre-parse
+
+  let event;
+  try {
+    event = verifyWebhookSignature(
+      request.headers,
+      rawBody,
+      process.env.TXNOD_WEBHOOK_SECRET!,
+    );
+  } catch (err) {
+    if (err instanceof TxnodSignatureFormatError) return new Response('bad header', { status: 401 });
+    if (err instanceof TxnodHmacError) return new Response('bad sig', { status: 401 });
+    if (err instanceof TxnodTimestampError) {
+      console.warn('txnod webhook clock skew seconds:', err.skew_seconds);
+      return new Response('stale', { status: 401 });
+    }
+    throw err;
+  }
+
+  // Idempotency: insert-if-not-exists keyed on event_id.
+  const isFirstTime = await recordEventOnce(event.event_id, event.event_type);
+  if (!isFirstTime) return Response.json({ ok: true, duplicate: true });
+
+  switch (event.event_type) {
+    case 'invoice.paid':
+    case 'invoice.overpaid':
+      // event.data.invoice_id is `string` here — no cast needed.
+      await fulfilOrder(event.data.invoice_id);
+      break;
+    case 'invoice.reverted':
+      await reverseOrder(event.data.invoice_id);
+      break;
+    case 'invoice.expired':
+    case 'invoice.expired_paid_late':
+      // Handle per your business rules.
+      break;
+    case 'invoice.detected':
+    case 'invoice.partial':
+      // Optional UI signal — do not fulfil yet.
+      break;
+  }
+
+  return Response.json({ ok: true });
+}
+```
+
+## Notes
+
+- **Do not use the edge runtime** — the SDK relies on `node:crypto`.
+- **Do not wrap the webhook route in JSON parsing middleware** — HMAC verification requires the exact request bytes.
+- **Fulfilment policy.** The example fulfils on `invoice.paid`. If your policy demands finalization-depth confirmations before release, gate `fulfilOrder` on `event.data.confirmations` against your threshold (see [`../06-idempotency.md`](../06-idempotency.md)).
+- **Reversal policy.** `reverseOrder` must be safe to run even if the order had not been fulfilled — a `reverted` event can arrive before the paid event has been fully processed in edge cases.
+
+## Related
+
+- [`../00-getting-started.md`](../00-getting-started.md) — env var setup
+- [`../06-idempotency.md`](../06-idempotency.md) — why the `recordEventOnce` pattern
+- [`express-webhook-receiver.md`](./express-webhook-receiver.md) — equivalent for Express

package/docs/examples/sandbox-vitest-suite.md

@@ -0,0 +1,263 @@
+---
+title: "Sandbox: end-to-end Vitest suite"
+description: "Vitest fixture that exercises every sandbox simulate-* method and asserts the integrator's webhook handler updates state correctly."
+sdk_version: 1.0.0
+---
+
+# Sandbox: end-to-end Vitest suite
+
+This example walks every webhook event type the SDK can produce: `invoice.detected`, `invoice.paid`, `invoice.overpaid`, `invoice.partial`, `invoice.expired`, `invoice.expired_paid_late`, `invoice.reverted`. Drop it into your project as `tests/sandbox.test.ts`. The handler under test (`processWebhook`) is a plausible stand-in for your idempotent webhook receiver — replace its body with your real one.
+
+## How the harness wires up
+
+There is **no `signature_hex` / `payload_raw` field on `client.listWebhookEvents()`** — that endpoint is a forensic delivery-log only. Re-verifying a webhook means parsing the envelope your callback URL actually received: the dispatcher's HTTP request, with `X-Txnod-Signature` and the raw body bytes. The harness below stands up a tiny `node:http` capture-server bound to a free local port; the request handler reads the raw body off the request stream and runs `verifyWebhookSignature(req.headers, rawBody, secret)` to parse + verify the typed `WebhookEvent`. Each `simulate*` call is followed by a polling loop that drains the captured queue keyed by `invoiceId` until the expected event arrives.
+
+The order map is keyed by `invoice.id` (a real wire field on `WebhookEventData.invoice_id`) joined to a side-table that captures `external_id` at `createInvoice` time — `event.data.external_id` does **not** exist on the wire shape, and reading it would silently coerce to `undefined`.
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { createServer, type Server } from 'node:http';
+import {
+  TxnodClient,
+  verifyWebhookSignature,
+  type WebhookEvent,
+} from '@txnod/sdk';
+
+interface OrderState {
+  status: 'pending' | 'detected' | 'paid' | 'overpaid' | 'partial' | 'expired' | 'reverted';
+  events: WebhookEvent['event_type'][];
+}
+
+// invoice.id (wire field) -> external_id (partner-side, never on the wire).
+// Captured at createInvoice time; consulted in processWebhook to key the
+// order map by your business identifier.
+const invoiceToExternalId = new Map<string, string>();
+const orders = new Map<string, OrderState>();
+
+function processWebhook(event: WebhookEvent): void {
+  const externalId = invoiceToExternalId.get(event.data.invoice_id);
+  if (externalId === undefined) return; // unknown invoice (shouldn't happen in the suite below)
+  const state: OrderState = orders.get(externalId) ?? {
+    status: 'pending',
+    events: [],
+  };
+  if (state.events.includes(event.event_type)) return; // idempotent dedup on event_id is the wire contract; this is a coarser dedup for the example
+  state.events.push(event.event_type);
+  switch (event.event_type) {
+    case 'invoice.detected':
+      state.status = 'detected';
+      break;
+    case 'invoice.paid':
+      state.status = 'paid';
+      break;
+    case 'invoice.overpaid':
+      state.status = 'overpaid';
+      break;
+    case 'invoice.partial':
+      state.status = 'partial';
+      break;
+    case 'invoice.expired':
+    case 'invoice.expired_paid_late':
+      // Most integrations treat both terminal expiry events the same way; if
+      // you accept late payments and want to credit them as paid-late,
+      // branch on event_type before this switch.
+      state.status = 'expired';
+      break;
+    case 'invoice.reverted':
+      state.status = 'reverted';
+      break;
+  }
+  orders.set(externalId, state);
+}
+
+const SECRET = process.env.TXNOD_WEBHOOK_SECRET!;
+const PROJECT_ID = process.env.TXNOD_PROJECT_ID!;
+
+const client = new TxnodClient({
+  projectId: PROJECT_ID,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  environment: 'non-production',
+});
+
+// Per-invoice queue of typed events the local capture-server has verified.
+const capturedByInvoice = new Map<string, WebhookEvent[]>();
+
+let receiver: Server;
+let receiverUrl: string;
+
+beforeAll(async () => {
+  receiver = createServer((req, res) => {
+    if (req.method !== 'POST') {
+      res.statusCode = 405;
+      res.end();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+      const rawBody = Buffer.concat(chunks).toString('utf8');
+      try {
+        const event = verifyWebhookSignature(req.headers, rawBody, SECRET);
+        const queue = capturedByInvoice.get(event.data.invoice_id) ?? [];
+        queue.push(event);
+        capturedByInvoice.set(event.data.invoice_id, queue);
+        res.statusCode = 200;
+      } catch {
+        // HMAC mismatch — the dispatcher will retry; surface 401 so retries fire
+        // and the test can assert on captured-event counts.
+        res.statusCode = 401;
+      }
+      res.end();
+    });
+  });
+  await new Promise<void>((resolve) => receiver.listen(0, '127.0.0.1', resolve));
+  const addr = receiver.address();
+  if (addr === null || typeof addr === 'string') {
+    throw new Error('receiver bound to unexpected address');
+  }
+  receiverUrl = `http://127.0.0.1:${addr.port}/`;
+  await client.sandbox.reset(PROJECT_ID);
+});
+
+afterAll(async () => {
+  await client.sandbox.reset(PROJECT_ID);
+  await new Promise<void>((resolve, reject) =>
+    receiver.close((err) => (err === undefined ? resolve() : reject(err))),
+  );
+});
+
+// Per-test isolation runs in-memory only — clearing the captured-event queue,
+// the side-table, and the order map. We intentionally do NOT call
+// `client.sandbox.reset(PROJECT_ID)` between tests: the dispatcher worker is
+// async-decoupled from the simulate-* call, so a mid-test reset can race
+// late-arriving webhooks (and surface flakes via deliveries that key on a
+// now-orphaned invoice_id). The single `beforeAll`/`afterAll` reset bookends
+// the whole suite — that's the shape this example is meant to teach.
+beforeEach(() => {
+  capturedByInvoice.clear();
+  invoiceToExternalId.clear();
+  orders.clear();
+});
+
+async function createInvoice(args: {
+  externalId: string;
+  amountUsd: number;
+  coin: 'btc' | 'eth' | 'usdt_trc20';
+}): Promise<string> {
+  const invoice = await client.createInvoice({
+    amount_usd: args.amountUsd,
+    coin: args.coin,
+    external_id: args.externalId,
+    callback_url: receiverUrl,
+  });
+  invoiceToExternalId.set(invoice.id, args.externalId);
+  return invoice.id;
+}
+
+async function waitForEvents(
+  invoiceId: string,
+  expected: number,
+  timeoutMs = 5000,
+): Promise<WebhookEvent[]> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const queue = capturedByInvoice.get(invoiceId) ?? [];
+    if (queue.length >= expected) return [...queue];
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return capturedByInvoice.get(invoiceId) ?? [];
+}
+
+describe('Sandbox webhook coverage', () => {
+  it('detected → paid emits invoice.detected then invoice.paid with mode=sandbox', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-paid', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateDetect(invoiceId, { seed: 'paid-seed' });
+    await client.sandbox.simulatePaid(invoiceId);
+    const events = await waitForEvents(invoiceId, 2);
+    for (const e of events) processWebhook(e);
+    expect(orders.get('order-paid')?.status).toBe('paid');
+    expect(events.every((e) => e.mode === 'sandbox')).toBe(true);
+  });
+
+  it('detected → overpaid emits invoice.overpaid', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-overpaid', amountUsd: 5, coin: 'eth' });
+    await client.sandbox.simulateDetect(invoiceId);
+    await client.sandbox.simulateOverpaid(invoiceId, { multiplier: 1.5 });
+    const events = await waitForEvents(invoiceId, 2);
+    for (const e of events) processWebhook(e);
+    expect(orders.get('order-overpaid')?.status).toBe('overpaid');
+  });
+
+  it('detected → partial emits invoice.partial and invoice stays open', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-partial', amountUsd: 5, coin: 'usdt_trc20' });
+    await client.sandbox.simulateDetect(invoiceId);
+    await client.sandbox.simulatePartial(invoiceId, { fraction: 0.5 });
+    const events = await waitForEvents(invoiceId, 2);
+    for (const e of events) processWebhook(e);
+    expect(orders.get('order-partial')?.status).toBe('partial');
+  });
+
+  it('pending → expired emits invoice.expired', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-expired', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateExpire(invoiceId);
+    const events = await waitForEvents(invoiceId, 1);
+    for (const e of events) processWebhook(e);
+    expect(orders.get('order-expired')?.status).toBe('expired');
+  });
+
+  it('expired → expired_paid_late emits invoice.expired_paid_late', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-late', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateExpire(invoiceId);
+    await client.sandbox.simulateLatePayment(invoiceId);
+    const events = await waitForEvents(invoiceId, 2);
+    for (const e of events) processWebhook(e);
+    expect(orders.get('order-late')?.status).toBe('expired');
+  });
+
+  it('paid → reverted → paid (reorg + reconfirm) emits invoice.reverted then a fresh invoice.paid', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-reorg', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateDetect(invoiceId);
+    await client.sandbox.simulatePaid(invoiceId);
+    await client.sandbox.simulateReorg(invoiceId);
+    await client.sandbox.simulateReconfirm(invoiceId);
+    const events = await waitForEvents(invoiceId, 4);
+    for (const e of events) processWebhook(e);
+    const types = events.map((e) => e.event_type);
+    expect(types).toContain('invoice.reverted');
+    expect(types.filter((t) => t === 'invoice.paid').length).toBeGreaterThanOrEqual(2);
+    expect(orders.get('order-reorg')?.status).toBe('paid');
+  });
+
+  it('duplicate delivery re-fires the same event_id (idempotency exercise)', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-dup', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateDetect(invoiceId);
+    await client.sandbox.simulatePaid(invoiceId);
+    const before = await waitForEvents(invoiceId, 2);
+    await client.sandbox.simulateDuplicateDelivery(invoiceId);
+    const after = await waitForEvents(invoiceId, 3);
+    const beforeIds = new Set(before.map((e) => e.event_id));
+    const afterIds = new Set(after.map((e) => e.event_id));
+    // Same event_id reappeared — your idempotency dedup must absorb it.
+    expect([...afterIds].some((id) => beforeIds.has(id))).toBe(true);
+  });
+
+  it('clock_advance bumps confirmations and finalises detected invoices', async () => {
+    const invoiceId = await createInvoice({ externalId: 'order-clock', amountUsd: 5, coin: 'btc' });
+    await client.sandbox.simulateDetect(invoiceId);
+    const r = await client.sandbox.clockAdvance(PROJECT_ID, {
+      chain: 'btc',
+      blocks: 6,
+    });
+    expect(r.advanced).toBeGreaterThanOrEqual(1);
+  });
+});
+```
+
+## Reading the example
+
+- **Capture-server harness** — `node:http` server bound to a free local port; the dispatcher's `POST` arrives with the standard `X-Txnod-Signature` header, the raw body is read off the request stream, and `verifyWebhookSignature(req.headers, rawBody, SECRET)` parses + verifies in one call. The verified `WebhookEvent` is queued per-`invoice_id`. No SDK listing call is involved — that endpoint is a forensic-only surface and does not return signing material or raw bodies.
+- **Order map key** — the wire shape carries `event.data.invoice_id` (a real field on `WebhookEventData`); it does **not** carry your `external_id`. The harness records `invoice.id → external_id` at `createInvoice` time so `processWebhook` can look up your business identifier without a server round-trip.
+- **Per-event idempotency check** — the `processWebhook` stand-in dedups on `(externalId, event_type)` for clarity. **Your real handler must dedup on `event_id`** (same `event_id` arrives on every retry of the same delivery; manual `resendWebhookEvent` mints a fresh `event_id` with `original_event_id` for lineage).
+- **`event.mode === 'sandbox'`** — every webhook envelope carries the `mode` discriminator (`'production' | 'testnet' | 'sandbox'`). Your handler should assert this matches its runtime expectations (see [`05-sandbox.md`](../05-sandbox.md#recommended-ci-assertion)).
+- **`reset()` between runs** — `client.sandbox.reset(projectId)` soft-purges the project's data tail (invoices, transactions, outbox events, address pool) while preserving the project shell, xpubs, bindings, and api_keys. Use it as `beforeAll`/`afterAll`/`afterEach` so tests start from a clean slate.
+- **`simulateDuplicateDelivery`** — the most under-exercised correctness path in real integrations. The same `event_id` arrives twice; the integrator's idempotency layer is the device under test.

package/docs/index.md

@@ -0,0 +1,66 @@
+---
+title: "@txnod/sdk documentation"
+description: "Index and 30-second overview of the agent-targeted docs bundled inside @txnod/sdk."
+sdk_version: 1.0.0
+---
+
+# @txnod/sdk documentation
+
+Fully-typed REST client and webhook verifier for [TxNod](https://txnod.com) — a non-custodial crypto payment gateway for BTC, ETH (+ ERC-20 USDT/USDC), TRON (+ TRC-20 USDT), Cardano, Polygon PoS (+ POL and Polygon USDT/USDC), BNB Smart Chain (+ BNB and BEP-20 USDT/USDC), and TON (+ jetton USDT). Node ≥ 20, zero cryptocurrency runtime dependencies.
+
+## 30-second overview
+
+```ts
+import { TxnodClient, verifyWebhookSignature } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+// 1. Create an invoice
+const invoice = await client.createInvoice({
+  amount_usd: 9.99,
+  coin: 'usdt_trc20',
+  external_id: 'order-42',
+  callback_url: 'https://your-site.com/api/txnod-webhook',
+});
+
+// 2. Show `invoice.address`, `invoice.amount_crypto`, `invoice.payment_uri` to the user
+
+// 3. Verify inbound webhooks against TXNOD_WEBHOOK_SECRET (= TXNOD_API_SECRET)
+const event = verifyWebhookSignature(req.headers, rawBody, secret);
+if (event.event_type === 'invoice.paid') { /* ... */ }
+```
+
+## Table of contents
+
+### Guides (read in order on first integration)
+
+- [`00-getting-started.md`](./00-getting-started.md) — install, env vars, first invoice, first verified webhook
+- [`01-authentication.md`](./01-authentication.md) — HMAC scheme, headers, clock skew, key rotation
+- [`02-invoices.md`](./02-invoices.md) — create, fetch, search, cancel; status lifecycle
+- [`03-rates-and-quotes.md`](./03-rates-and-quotes.md) — `getRates` and `quoteAmount`, indicative vs binding
+- [`04-webhooks.md`](./04-webhooks.md) — event types, `verifyWebhookSignature`, retries, resend
+- [`05-errors.md`](./05-errors.md) — every typed error class and the correct branch to write
+- [`05-sandbox.md`](./05-sandbox.md) — `client.sandbox.*`, environment-detection guards, layered defenses, per-chain testnet truth table
+- [`06-idempotency.md`](./06-idempotency.md) — `external_id`, `event_id`, reorgs, reverts
+
+### Reference
+
+- [`reference/client.md`](./reference/client.md) — every `TxnodClient` method: signature, behaviour, example
+- [`reference/errors.md`](./reference/errors.md) — `error_code` → class table
+- [`reference/types.md`](./reference/types.md) — pointers to Zod schemas that define request/response shapes
+
+### Examples
+
+- [`examples/nextjs-route-handler.md`](./examples/nextjs-route-handler.md) — Next.js 16 App Router
+- [`examples/express-webhook-receiver.md`](./examples/express-webhook-receiver.md) — Express receiver with raw body
+- [`examples/sandbox-vitest-suite.md`](./examples/sandbox-vitest-suite.md) — end-to-end Vitest suite covering all 7 webhook event types via `client.sandbox.*`
+
+## Non-negotiable invariants
+
+1. **Non-custodial.** The SDK never handles private keys or mnemonics. `apiSecret` is an HMAC secret.
+2. **Verify webhooks before parsing.** Use [`verifyWebhookSignature`](./04-webhooks.md) — it HMACs, clock-checks, and parses for you.
+3. **Idempotency on four layers.** See [`06-idempotency.md`](./06-idempotency.md).
+4. **`paid` is not terminal until finalization.** Reorgs can revert it to `reverted`. Treat disbursal/fulfilment triggers accordingly.