caelum0x 06f3139325 feat(checkout): verify every network through the shared chain runtimes
- lib/evm.ts loads enabled EVM chains with the same loader as the API and
  worker; lib/zcash.ts adds the transparent Zcash runtime, quote locking,
  verification and a 60 s per-payTo address scan cache
- verify-payment is an exhaustive switch over every PaymentNetwork; a
  network without a runtime fails closed; bindings come from the session
  (payTo per network, notBefore = createdAt, payer, Tempo memo, ZEC quote)
- store claims a valid transfer still awaiting confirmations (or a late
  Zcash payment) as a pending payment and reports payment_pending /
  payment_under_review instead of a hard failure
- tx-hash re-exports @settlekit/chains; format gains registry-backed
  network + asset labels (USDC, USDG, USDC.e, pathUSD, ZEC) and badges

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:03:50 +03:00

122 lines
4.4 KiB
TypeScript

/**
* On-chain payment verification for the hosted checkout.
*
* When Arc settlement is configured (ARC_RPC_URL + ARC_USDC_ADDRESS present),
* a submitted transaction hash is verified against the chain with the REAL
* `@settlekit/arc` client: the transaction must have transferred at least the
* invoiced amount of USDC to the session's `payToAddress` and reached the
* configured minimum confirmations before the payment is accepted. This closes
* the trust gap where any well-formed hash would otherwise settle a session.
*
* FAIL CLOSED: when Arc is NOT configured (no ARC_RPC_URL / ARC_USDC_ADDRESS)
* verification returns a failed outcome — a transaction hash alone is never
* evidence of payment, so an unconfigured checkout cannot settle Arc sessions.
*/
import { createArcClient, type Hex } from "@settlekit/arc";
import type { Money } from "@settlekit/common";
/** Resolved Arc settlement configuration from the environment. */
interface ArcVerifyConfig {
rpcUrl: string;
usdcAddress: Hex;
chainId: number;
minConfirmations: number;
}
/** Read Arc settlement config from env, or `null` when it is not configured. */
function loadArcConfig(): ArcVerifyConfig | null {
const rpcUrl = process.env.ARC_RPC_URL?.trim();
const usdcAddress = process.env.ARC_USDC_ADDRESS?.trim();
if (!rpcUrl || !usdcAddress) return null;
const chainId = Number(process.env.ARC_CHAIN_ID ?? "1");
const minConfirmations = Number(process.env.ARC_MIN_CONFIRMATIONS ?? "3");
return {
rpcUrl,
usdcAddress: usdcAddress as Hex,
chainId: Number.isFinite(chainId) && chainId > 0 ? chainId : 1,
minConfirmations: Number.isInteger(minConfirmations) && minConfirmations > 0 ? minConfirmations : 3,
};
}
/** Whether the legacy Arc settings (ARC_RPC_URL + ARC_USDC_ADDRESS) are present. */
export function legacyArcConfigured(env: Readonly<Record<string, string | undefined>> = process.env): boolean {
return Boolean(env.ARC_RPC_URL?.trim() && env.ARC_USDC_ADDRESS?.trim());
}
/** Outcome of an on-chain verification attempt. */
export interface OnChainVerification {
ok: boolean;
/** Confirmations observed on-chain (0 when no matching transfer was found). */
confirmations: number;
/** Minimum confirmations required by configuration. */
minConfirmations: number;
/** Why verification failed, when `ok` is false. */
reason?: string;
/** Not final yet (unmined, too few confirmations, RPC/explorer down): retry later. */
pending?: boolean;
/**
* The transaction was found and pays this session; only depth is missing.
* The checkout may claim the tx hash so the worker can finish confirming.
*/
claimable?: boolean;
/** Paid after the locked quote expired (Zcash): hold for manual review. */
late?: boolean;
}
/** A well-formed Arc transaction hash (0x + 64 hex). */
const TX_HASH_RE = /^0x[0-9a-fA-F]{64}$/;
/**
* Verify a USDC transfer for a checkout payment and return the outcome with the
* real observed confirmation count. Unconfigured Arc is a failed outcome.
*/
export async function verifyOnChainPayment(input: {
txHash: string;
payTo: string;
amount: Money;
}): Promise<OnChainVerification> {
const config = loadArcConfig();
if (!config) {
return {
ok: false,
confirmations: 0,
minConfirmations: 0,
reason: "Arc payments are not configured on this checkout (ARC_RPC_URL / ARC_USDC_ADDRESS unset).",
};
}
if (!TX_HASH_RE.test(input.txHash)) {
return { ok: false, confirmations: 0, minConfirmations: config.minConfirmations, reason: "Malformed transaction hash" };
}
const arc = createArcClient({
rpcUrl: config.rpcUrl,
usdcAddress: config.usdcAddress,
chainId: config.chainId,
});
const result = await arc.verifyUsdcTransfer({
txHash: input.txHash as Hex,
to: input.payTo as Hex,
minAmount: input.amount,
});
if (!result.confirmed) {
return {
ok: false,
confirmations: result.confirmations,
minConfirmations: config.minConfirmations,
reason: "No matching USDC transfer found on-chain",
};
}
if (result.confirmations < config.minConfirmations) {
return {
ok: false,
confirmations: result.confirmations,
minConfirmations: config.minConfirmations,
reason: `Insufficient confirmations: ${result.confirmations} < ${config.minConfirmations}`,
};
}
return { ok: true, confirmations: result.confirmations, minConfirmations: config.minConfirmations };
}