ConceptsEscalations

Escalations

When a payment is above the wallet’s escalationThreshold, the wallet does not send it. It escalates: the payment is held onchain until enough approvers sign, someone rejects it, the owner cancels it, or it expires. No USDC moves while it waits, and it does not count against any limit.

In the hosted app, held payments appear in the restraint queue.

Setting up approvers

The owner chooses the approvers, how many approvals are needed, and how long a held payment stays open:

await ownerClient.writeContract({
  address: wallet,
  abi: GuardedWalletAbi,
  functionName: "configureEscalation",
  args: [[alice, bob, carol], 2, 3600], // 2 of 3, expires after one hour
})

What can happen to a held payment

StatusMeaning
PendingWaiting for approvals.
ExecutedEnough approvers signed and the payment was sent.
RejectedAn approver rejected it.
ExpiredTime ran out. An expired payment is never sent.
CancelledThe owner withdrew it.
DeniedIt was approved, but the payment now breaks a rule and was refused.
InvalidatedThe owner changed the approver set while it was waiting.

Two safety details

  • Approval is checked again. When the last approval arrives, the wallet re-checks the payment against the current policy, vendor list and spending. If the owner tightened a limit or blocked the vendor in the meantime, the payment is refused.
  • Changing approvers resets pending votes. Each approver set has a version number. A payment held under an old set cannot be released by it.

Approving

Approvers can sign in the hosted app at thearcanum.in, or call the EscalationManager directly with approve(escalationId) or reject(escalationId).

Agents can wait for the result:

const stop = arc.onEscalationResolved(escalationId, (event) => {
  console.log(event.status)
})