穩定幣支付對帳：如何把鏈上轉帳匹配到業務訂單

鏈上期初餘額
+ 符合條件的入帳轉帳
+ 未匹配的入帳轉帳
- 資金歸集
- 退款及其他出帳轉帳
= 鏈上期末餘額

商戶系統                         StableOps                         區塊鏈

invoice_10482  <------------->  merchant_order_id
業務訂單號                       payment_order_id  <------------> 歸一化事件
結算狀態                         event_id                          tx_hash + log_index
退款或人工入帳                   delivery_id                      鏈 + 代幣 + 金額

const order = await client.paymentOrders.create(
  {
    merchantOrderId: 'invoice_10482',
    amount: '249.00',
    acceptedAssets: [
      { chain: 'base', asset: 'USDC' },
      { chain: 'tron', asset: 'USDT' },
    ],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    metadata: {
      customerId: 'cus_781',
      invoiceNumber: 'INV-2026-10482',
      ledgerAccount: 'sales-software',
    },
  },
  { idempotencyKey: 'invoice_10482:create-payment-order' },
)

{
  "windowStart": "2026-07-27T00:00:00.000Z",
  "windowEnd": "2026-07-28T00:00:00.000Z",
  "orders": [
    {
      "merchantOrderId": "invoice_10482",
      "paymentOrderId": "po_01...",
      "requestedAmount": "249.00",
      "payableAmount": "249.000001",
      "settlementAsset": "USDC",
      "paymentApplied": true,
      "transfer": {
        "chain": "base",
        "asset": "USDC",
        "chainAmount": "249000001",
        "txHash": "0x...",
        "logIndex": 7
      }
    }
  ]
}

import { createHash } from 'node:crypto'
import { readFile } from 'node:fs/promises'

type TransferRef = {
  chain: string
  asset: string
  chainAmount: string
  txHash: string
  logIndex: number
}

type LocalOrder = {
  merchantOrderId: string
  paymentOrderId: string
  requestedAmount: string
  payableAmount: string
  settlementAsset: string | null
  paymentApplied: boolean
  transfer?: TransferRef
}

type ExportFile = {
  windowStart: string
  windowEnd: string
  orders: LocalOrder[]
}

type PlatformOrder = {
  id: string
  merchant_order_id: string
  amount: string
  requested_amount: string
  settlement_asset?: string
  status: string
  created_at: string
}

type Delivery = {
  id: string
  webhook_endpoint_id: string
  event_id: string
  payment_order_id: string | null
  event_type: string
  status: string
  created_at: string
  payload: Record<string, unknown>
}

type Page<T> = { items: T[]; has_more: boolean }
type TransferEvidence = TransferRef & {
  eventId: string
  paymentOrderId: string
  normalizedEventId: string
}

const apiKey = process.env.STABLEOPS_API_KEY
const baseUrl = process.env.STABLEOPS_API_URL ?? 'https://api.stableops.dev'
if (!apiKey) throw new Error('STABLEOPS_API_KEY is required')

function canonical(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(canonical)
  if (value && typeof value === 'object') {
    const record = value as Record<string, unknown>
    return Object.fromEntries(
      Object.keys(record)
        .sort()
        .map((key) => [key, canonical(record[key])]),
    )
  }
  return value
}

function fingerprint<T extends { id: string }>(items: T[]) {
  const sorted = [...items].sort((a, b) => a.id.localeCompare(b.id))
  return createHash('sha256')
    .update(JSON.stringify(canonical(sorted)))
    .digest('hex')
}

async function listOnce<T extends { id: string }>(
  path: string,
  query: Record<string, string> = {},
) {
  const items = new Map<string, T>()
  for (let offset = 0; ; offset += 200) {
    const search = new URLSearchParams({ ...query, limit: '200', offset: String(offset) })
    const response = await fetch(`${baseUrl}${path}?${search}`, {
      headers: { authorization: `Bearer ${apiKey}` },
    })
    if (!response.ok) throw new Error(`${path}: ${response.status} ${await response.text()}`)
    const page = (await response.json()) as Page<T>
    for (const item of page.items) {
      if (items.has(item.id)) throw new Error(`${path}: pagination changed during the scan`)
      items.set(item.id, item)
    }
    if (!page.has_more) return [...items.values()]
  }
}

async function scanAuditData() {
  const [platform, deliveries] = await Promise.all([
    listOnce<PlatformOrder>('/v1/payment-orders'),
    listOnce<Delivery>('/v1/webhook-deliveries'),
  ])
  return { platform, deliveries }
}

async function stableAuditSnapshot() {
  let previous = await scanAuditData()
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const current = await scanAuditData()
    if (
      fingerprint(previous.platform) === fingerprint(current.platform) &&
      fingerprint(previous.deliveries) === fingerprint(current.deliveries)
    )
      return current
    previous = current
  }
  throw new Error('no stable audit snapshot; retry after the cutoff settles')
}

function decimalKey(value: string) {
  if (!/^\d+(?:\.\d+)?$/u.test(value)) throw new Error(`invalid decimal amount: ${value}`)
  const [whole, fraction = ''] = value.split('.')
  return `${BigInt(whole)}.${fraction.replace(/0+$/u, '')}`
}

function inWindow(value: string, start: number, end: number) {
  const time = Date.parse(value)
  return Number.isFinite(time) && time >= start && time < end
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
}

function detectedEvidence(delivery: Delivery): TransferEvidence | null {
  if (delivery.event_type !== 'payment.detected' || !isRecord(delivery.payload.data)) return null
  const data = delivery.payload.data
  if (
    !delivery.payment_order_id ||
    typeof data.normalized_event_id !== 'string' ||
    typeof data.chain !== 'string' ||
    typeof data.asset !== 'string' ||
    typeof data.chain_amount !== 'string' ||
    typeof data.tx_hash !== 'string' ||
    typeof data.log_index !== 'number'
  )
    return null
  return {
    eventId: delivery.event_id,
    paymentOrderId: delivery.payment_order_id,
    normalizedEventId: data.normalized_event_id,
    chain: data.chain,
    asset: data.asset,
    chainAmount: data.chain_amount,
    txHash: data.tx_hash,
    logIndex: data.log_index,
  }
}

function transferKey(value: TransferRef) {
  return [value.chain, value.asset, value.chainAmount, value.txHash, value.logIndex].join('|')
}

const file = process.argv[2]
if (!file) throw new Error('usage: npx tsx reconcile.ts business-export.json')

const input = JSON.parse(await readFile(file, 'utf8')) as ExportFile
const start = Date.parse(input.windowStart)
const end = Date.parse(input.windowEnd)
if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end)
  throw new Error('invalid reconciliation window')

const { platform, deliveries } = await stableAuditSnapshot()

const findings: string[] = []
const localByMerchantId = new Map<string, LocalOrder>()
const localByPaymentId = new Map<string, LocalOrder>()
for (const order of input.orders) {
  if (localByMerchantId.has(order.merchantOrderId))
    throw new Error(`duplicate merchantOrderId: ${order.merchantOrderId}`)
  if (localByPaymentId.has(order.paymentOrderId))
    throw new Error(`duplicate paymentOrderId: ${order.paymentOrderId}`)
  localByMerchantId.set(order.merchantOrderId, order)
  localByPaymentId.set(order.paymentOrderId, order)
}

const platformById = new Map(platform.map((order) => [order.id, order]))
const paymentIdsChangedInWindow = new Set(
  deliveries
    .filter((delivery) => delivery.payment_order_id && inWindow(delivery.created_at, start, end))
    .map((delivery) => delivery.payment_order_id as string),
)
const platformInWindow = platform.filter(
  (order) => inWindow(order.created_at, start, end) || paymentIdsChangedInWindow.has(order.id),
)
const relevantPaymentIds = new Set([
  ...localByPaymentId.keys(),
  ...platformInWindow.map((order) => order.id),
])

for (const order of input.orders) {
  const remote = platformById.get(order.paymentOrderId)
  if (!remote) {
    findings.push(`${order.merchantOrderId}: payment order ${order.paymentOrderId} is missing`)
    continue
  }
  if (remote.merchant_order_id !== order.merchantOrderId)
    findings.push(`${order.paymentOrderId}: merchantOrderId mapping differs`)
  if (decimalKey(order.requestedAmount) !== decimalKey(remote.requested_amount))
    findings.push(`${order.merchantOrderId}: requested amount differs`)
  if (decimalKey(order.payableAmount) !== decimalKey(remote.amount))
    findings.push(`${order.merchantOrderId}: payable amount differs`)
  if (order.settlementAsset !== (remote.settlement_asset ?? null))
    findings.push(`${order.merchantOrderId}: settlement asset differs`)
  if (order.paymentApplied && remote.status !== 'finalized')
    findings.push(
      `${order.merchantOrderId}: merchant applied payment but StableOps is ${remote.status}`,
    )
  if (!order.paymentApplied && remote.status === 'finalized')
    findings.push(`${order.merchantOrderId}: finalized but merchant is not settled`)
}

for (const remote of platformInWindow) {
  if (!localByMerchantId.has(remote.merchant_order_id))
    findings.push(`${remote.id}: StableOps order has no business order in this window`)
}

const deliveryGroups = new Map<string, Delivery[]>()
for (const delivery of deliveries) {
  if (!delivery.payment_order_id || !relevantPaymentIds.has(delivery.payment_order_id)) continue
  const key = `${delivery.webhook_endpoint_id}:${delivery.event_id}`
  deliveryGroups.set(key, [...(deliveryGroups.get(key) ?? []), delivery])
}
for (const group of deliveryGroups.values()) {
  if (group.some((delivery) => delivery.status === 'succeeded')) continue
  const sample = group[0]
  if (group.some((delivery) => delivery.status === 'dead_letter'))
    findings.push(`${sample.payment_order_id}: ${sample.event_type} remains dead-lettered`)
  else if (group.some((delivery) => delivery.status === 'failed'))
    findings.push(`${sample.payment_order_id}: ${sample.event_type} delivery is still failing`)
}

const evidenceByEvent = new Map<string, TransferEvidence>()
for (const delivery of deliveries) {
  if (!delivery.payment_order_id || !relevantPaymentIds.has(delivery.payment_order_id)) continue
  const evidence = detectedEvidence(delivery)
  if (!evidence) {
    if (delivery.event_type === 'payment.detected')
      findings.push(`${delivery.id}: malformed payment.detected evidence`)
    continue
  }
  const existing = evidenceByEvent.get(evidence.eventId)
  if (existing && transferKey(existing) !== transferKey(evidence))
    findings.push(`${evidence.eventId}: inconsistent replay payload`)
  else evidenceByEvent.set(evidence.eventId, evidence)
}

const evidenceByPaymentId = new Map<string, TransferEvidence[]>()
for (const evidence of evidenceByEvent.values()) {
  evidenceByPaymentId.set(evidence.paymentOrderId, [
    ...(evidenceByPaymentId.get(evidence.paymentOrderId) ?? []),
    evidence,
  ])
}
for (const order of input.orders) {
  const evidence = evidenceByPaymentId.get(order.paymentOrderId) ?? []
  const remote = platformById.get(order.paymentOrderId)
  if (evidence.length > 1)
    findings.push(`${order.merchantOrderId}: multiple detected transfers are associated`)
  if (remote?.status === 'finalized' && evidence.length === 0)
    findings.push(`${order.merchantOrderId}: finalized without retained transfer evidence`)
  if (order.transfer && evidence[0] && transferKey(order.transfer) !== transferKey(evidence[0]))
    findings.push(`${order.merchantOrderId}: merchant and StableOps transfer references differ`)
  if (!order.transfer && evidence[0])
    findings.push(`${order.merchantOrderId}: merchant ledger is missing the transfer reference`)
}

console.log(
  JSON.stringify(
    {
      window: { start: input.windowStart, end: input.windowEnd },
      checkedLocalOrders: input.orders.length,
      checkedPlatformOrders: platformInWindow.length,
      transfers: [...evidenceByEvent.values()],
      findings,
    },
    null,
    2,
  ),
)
process.exitCode = findings.length === 0 ? 0 : 1