- 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>
122 lines
4.4 KiB
TypeScript
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 };
|
|
}
|