Multi-chain Payouts with WaaP Squid Mode

npm install -g @human.tech/waap-cli@2.2.0
waap-cli signup
waap-cli policy set --daily-spend-limit 100
waap-cli squid init
waap-cli squid addresses

[
  {
    "id": "leg-evm-001",
    "label": "EVM leg — Base",
    "recipient": "0xb53fcf2c4a1b315bb4508db16dc1769f761a2b02",
    "chain": "evm:8453",
    "amount": "0.000002"
  },
  {
    "id": "leg-sui-001",
    "label": "Sui leg",
    "recipient": "0xe999e9b1faaab2660777549e408d378034adfc38c22ad3d6296800d8e17ac607",
    "chain": "sui:mainnet",
    "amount": "0.001"
  }
]

// multichain-payouts/agent.ts
import * as fs from 'fs'
import * as path from 'path'
import { classifySendFailure, squidAddresses, squidSendTx, type Chain } from '../lib/squid'
 
const TAG = '[multichain-payouts]'
const LEDGER = path.resolve(process.env.PAYOUT_LEDGER ?? './data/payout-ledger.json')
const CONFIG = path.resolve(process.env.PAYOUT_CONFIG ?? './payouts.json')
const DRY_RUN = process.env.DRY_RUN === '1'
 
const log = (level: string, event: string, data?: Record<string, unknown>) =>
  console.log(JSON.stringify({ ts: new Date().toISOString(), level, agent: TAG, event, ...data }))
 
interface Payout {
  id: string          // stable, caller-supplied. The idempotency key.
  label: string
  recipient: string
  chain: Chain        // the chain THEY asked to be paid on
  amount: string      // whole units
  intervalMs?: number // omit for one-shot
  enabled?: boolean
}
 
type Phase = 'intent' | 'settled' | 'failed'
interface Entry {
  id: string; phase: Phase; chain: Chain; recipient: string; amount: string
  txHash?: string; error?: string; intentAt: string; settledAt?: string
}
interface Ledger { entries: Record<string, Entry>; lastPaidAt: Record<string, string> }
 
function loadLedger(): Ledger {
  try { return JSON.parse(fs.readFileSync(LEDGER, 'utf8')) as Ledger }
  catch { return { entries: {}, lastPaidAt: {} } }
}
 
/** Synchronous and flushed. An async write here reintroduces the exact race this exists to close. */
function saveLedger(l: Ledger): void {
  fs.mkdirSync(path.dirname(LEDGER), { recursive: true })
  const tmp = `${LEDGER}.tmp`
  const fd = fs.openSync(tmp, 'w')
  fs.writeSync(fd, JSON.stringify(l, null, 2))
  fs.fsyncSync(fd)           // durable before we broadcast, or the ledger is theatre
  fs.closeSync(fd)
  fs.renameSync(tmp, LEDGER) // atomic swap
}
 
/**
 * Startup reconciliation. An entry still at `intent` means we crashed mid-flight and cannot
 * know whether the transaction landed. It is left for a human rather than silently re-sent:
 * double-paying is worse than pausing.
 */
function reconcile(l: Ledger): string[] {
  const stuck = Object.values(l.entries).filter((e) => e.phase === 'intent').map((e) => e.id)
  if (stuck.length) log('warn', 'reconcile_needed', { stuck, note: 'verify on-chain before re-running these' })
  return stuck
}
 
function isDue(p: Payout, l: Ledger): boolean {
  if (p.enabled === false) return false
  const last = l.lastPaidAt[p.id]
  if (!last) return true
  if (!p.intervalMs) return false          // one-shot, already paid
  return Date.now() - new Date(last).getTime() >= p.intervalMs
}
 
async function main() {
  const addrs = await squidAddresses()
  log('info', 'agent_start', { evm: addrs.evm, sui: addrs.sui, sol: addrs.sol, dryRun: DRY_RUN })
 
  const ledger = loadLedger()
  const stuck = new Set(reconcile(ledger))
 
  const payouts: Payout[] = JSON.parse(fs.readFileSync(CONFIG, 'utf8'))
  for (const p of payouts) {
    if (stuck.has(p.id)) { log('warn', 'skipped_unreconciled', { id: p.id }); continue }
    if (!isDue(p, ledger)) continue
 
    // A dry run must never touch the ledger. Writing intent first and returning here leaves
    // permanent `intent` rows, which reconciliation then reads as a mid-flight crash and
    // refuses to pay — a rehearsal that locks out the real run. Bail before the write.
    if (DRY_RUN) { log('info', 'dry_run', { id: p.id, chain: p.chain }); continue }
 
    // 1 — INTENT, durable before anything is broadcast.
    ledger.entries[p.id] = {
      id: p.id, phase: 'intent', chain: p.chain, recipient: p.recipient,
      amount: p.amount, intentAt: new Date().toISOString(),
    }
    saveLedger(ledger)
 
    try {
      // 2 — broadcast. One account, whichever chain they asked for.
      const r = await squidSendTx({ to: p.recipient, chain: p.chain, value: p.amount, wait: true })
      // 3 — SETTLED.
      ledger.entries[p.id] = { ...ledger.entries[p.id], phase: 'settled', txHash: r.txHash, settledAt: new Date().toISOString() }
      ledger.lastPaidAt[p.id] = new Date().toISOString()
      saveLedger(ledger)
      log('info', 'paid', { id: p.id, chain: p.chain, txHash: r.txHash })
    } catch (err) {
      const e = err as Error & { code?: string }
      const side = classifySendFailure(e)
 
      // `failed` means "nothing moved, retry is safe", so only a failure BEFORE broadcast earns
      // it. A confirm or status failure means the send may already be on-chain — that is the
      // ambiguous case, and it stays at `intent` so reconciliation refuses to pay again until a
      // human checks. Recording it as `failed` is how a payout system pays twice.
      const phase: Phase = side === 'pre-broadcast' ? 'failed' : 'intent'
 
      ledger.entries[p.id] = { ...ledger.entries[p.id], phase, error: e.message }
      saveLedger(ledger)
      log('error', 'payout_failed', { id: p.id, chain: p.chain, code: e.code, side, phase, message: e.message })
    }
  }
  log('info', 'agent_stop', { processed: payouts.length })
}
 
main().catch((e) => { log('error', 'fatal', { message: (e as Error).message }); process.exit(1) })

send  →  (crash here)  →  saveHistory()