Core concepts

You do not need to memorize these. Skim them once so the words stop feeling like jargon, and come back when one of them trips you up. Each is here because you will meet it in a real command.

The wallet (its program name is canonicalwalletd) is the background program that holds your keys, checks your rules, signs, and keeps the history. When these docs say "the wallet decides," this is what decides.

The command line (canonicalwallet) is what you type at the terminal to talk to the wallet. It holds nothing and decides nothing — think of it as a remote control.

The agent adapter is the same wallet, reachable by AI tools over a standard called MCP. It is how Claude or Cursor plugs in. It adds no powers of its own; an agent is just another thing asking the wallet, with its own limited access.

A token is the secret string that proves who is asking — like a password for one specific tool. Setup gives you two: a full-access one for you, and a read-only one meant for agents. You can make more, each scoped to one job.

A principal is the identity behind a token — you, a teammate, a bot. The token is just that identity's current password; swapping the token does not change who you are. History and approvals stick to the principal, not the token.

A principal kind is what sort of thing it is: a person (human_operator), the command line (cli_client), an AI agent (mcp_client), or automation (service_account). This matters in one important way — some rules require a human, and only a human_operator counts.

A capability is one permission bit: can read status, can draft a transaction, can approve one, and so on. Give a token only the capabilities its job needs. A read-only token has none of the "move money" ones, so those requests bounce immediately.

Keep this distinction in your head, because it explains most confusion: a capability lets you try something. Whether it actually goes through is a separate question, answered by your rules below.

A proposal is a transaction (or other risky action) that has been drafted but not yet done. This is the heart of Canonical. Instead of "sign and send" in one irreversible step, a proposal sits there — reviewed, waiting for approvals — until it has everything it needs. The whole next page is about it.

Your policy is the rule for how many people must approve, and whether one of them must be human. Out of the box it is "two approvals, at least one human" for anything that moves money. That is not a setting you switched on — it is the default.

The quorum is just the running score: how many approvals are in, how many to go, and whether a human is still needed.

If several people share a wallet, the workflow tools let them stay out of each other's way: claim a proposal so others know you have got it, hand it off, leave a review note. These only organize work. Claiming a transfer does not approve it — approving is separate, and deliberately so.

Your inbox is the wallet's answer to "what needs me right now?" — it filters everything down to the proposals you can actually act on.

The review is the plain-English breakdown of a transaction: what it does, what it will likely change, how risky it looks. The wallet builds it by decoding and simulating the transaction before anyone approves.

The frozen review. When you approve, you are approving that exact reviewed version. The wallet takes a fingerprint of the review and binds your approval to it. If the transaction changes even slightly afterward, the fingerprint no longer matches and your approval is void. Nobody can get you to approve one thing and execute another.

Drift is the wallet checking, one more time right before it signs, that the world has not changed since you approved. If the contract or its effects moved, it stops. Yesterday's approval does not authorize today's changed transaction.

Three views of the same history, for three needs:

• Activity — a readable timeline, for humans catching up.
• Events — a precise, resumable feed, for automation that polls.
• The audit log — the tamper-proof record underneath both. Each entry is chained to the one before it, so history cannot be quietly rewritten.