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
| Contract | What it does |
|---|---|
| GuardedWallet | One per agent. Holds the USDC and runs every payment through the policy. |
| PolicyEngine | Decides allow, escalate, deny or freeze for a payment. |
| EscalationManager | Holds payments that need approval and counts the approvals. |
| VendorRegistry | Each wallet’s approved and blocked recipients, with categories and caps. |
| AnomalyOracle | Accepts signed risk scores and can freeze a wallet whose score is too high. |
| WalletFactory | Creates new wallets. Anyone can use it. |
Addresses for every network are on the Deployments page.
The services
| Service | What it does |
|---|---|
| Indexer | Reads contract events from Arc into a database. |
| API | Serves that data to the dashboard, explorer and SDKs. It never signs transactions. |
| Dashboard | The hosted app at thearcanum.in for owners and approvers. |
| SDKs | TypeScript and Python clients for agents. They talk to Arc directly. |
Who can do what
| Role | Can | Cannot |
|---|---|---|
| Wallet owner | Change the policy, signers, approvers and vendors; freeze and unfreeze; withdraw; replace modules; hand the wallet to a new owner | Skip the policy when an agent pays |
| Agent signer | Request payments with executeUSDC | Change any rule, withdraw, or unfreeze |
| Approver | Approve or reject a held payment | Release a payment that now breaks a limit |
| Risk oracle | Freeze a wallet that uses it (on by default), using a fresh signed score | Move funds or unfreeze |
| Arcanum | Run the hosted services; set defaults for new wallets; rotate the risk oracle’s signing key | Move 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.
| Guarantee | Test |
|---|---|
| No payment goes out while a wallet is frozen | invariant_NoTransferExecutesWhileFrozen |
| Daily spending never exceeds the current daily cap | invariant_DailySpendNeverExceedsCurrentPolicyCap |
| A held payment is paid at most once | invariant_EscalationsExecuteAtMostOnceAndReconcile |
| Approvals only count for the approver set the payment was held under | invariant_ExecutedEscalationsUseTheirHeldCouncilVersion |
| Every USDC that leaves a wallet is accounted for | invariant_WalletBalanceReconcilesAllOutflows |
| Approval cannot override the daily cap | test_attack_quorumCannotOverrideDailyCap |
| Changing approvers cancels payments held under the old set | test_attack_councilRotationInvalidatesPendingEscalation |
| Only the oracle can trigger a risk freeze | test_attack_nonOracleCannotFreeze |
| The token sweep can never take USDC | test_attack_sweepCannotTakeUsdc |
| Changing factory defaults cannot rewrite existing wallets | test_attack_defaultRotationCannotRewriteExistingWallets |
| A previous owner loses all power after a handover | test_attack_previousOwnerLosesPowerAfterHandover |
Run them yourself:
cd packages/contracts
forge test