How it works

How it works

Arcanum has two layers. The contracts on Arc decide whether money moves. The services (indexer, API, dashboard and SDKs) make that state easy to read and operate. If every service went offline, the contracts would keep enforcing the same rules.

The contracts

ContractWhat it does
GuardedWalletOne per agent. Holds the USDC and runs every payment through the policy.
PolicyEngineDecides allow, escalate, deny or freeze for a payment.
EscalationManagerHolds payments that need approval and counts the approvals.
VendorRegistryEach wallet’s approved and blocked recipients, with categories and caps.
AnomalyOracleAccepts signed risk scores and can freeze a wallet whose score is too high.
WalletFactoryCreates new wallets. Anyone can use it.

Addresses for every network are on the Deployments page.

The services

ServiceWhat it does
IndexerReads contract events from Arc into a database.
APIServes that data to the dashboard, explorer and SDKs. It never signs transactions.
DashboardThe hosted app at thearcanum.in for owners and approvers.
SDKsTypeScript and Python clients for agents. They talk to Arc directly.

Who can do what

RoleCanCannot
Wallet ownerChange the policy, signers, approvers and vendors; freeze and unfreeze; withdraw; replace modules; hand the wallet to a new ownerSkip the policy when an agent pays
Agent signerRequest payments with executeUSDCChange any rule, withdraw, or unfreeze
ApproverApprove or reject a held paymentRelease a payment that now breaks a limit
Risk oracleFreeze a wallet that uses it (on by default), using a fresh signed scoreMove funds or unfreeze
ArcanumRun the hosted services; set defaults for new wallets; rotate the risk oracle’s signing keyMove funds from any wallet or change an existing wallet’s rules

The last row is explained in full on Admin and governance.

Guarantees the tests check

These properties are checked by the Foundry test suite in packages/contracts/test. Invariant tests run random sequences of actions and check the property after every step.

GuaranteeTest
No payment goes out while a wallet is frozeninvariant_NoTransferExecutesWhileFrozen
Daily spending never exceeds the current daily capinvariant_DailySpendNeverExceedsCurrentPolicyCap
A held payment is paid at most onceinvariant_EscalationsExecuteAtMostOnceAndReconcile
Approvals only count for the approver set the payment was held underinvariant_ExecutedEscalationsUseTheirHeldCouncilVersion
Every USDC that leaves a wallet is accounted forinvariant_WalletBalanceReconcilesAllOutflows
Approval cannot override the daily captest_attack_quorumCannotOverrideDailyCap
Changing approvers cancels payments held under the old settest_attack_councilRotationInvalidatesPendingEscalation
Only the oracle can trigger a risk freezetest_attack_nonOracleCannotFreeze
The token sweep can never take USDCtest_attack_sweepCannotTakeUsdc
Changing factory defaults cannot rewrite existing walletstest_attack_defaultRotationCannotRewriteExistingWallets
A previous owner loses all power after a handovertest_attack_previousOwnerLosesPowerAfterHandover

Run them yourself:

cd packages/contracts
forge test