Tokens — Canton Token Standard on LocalNet

canton-devkit ships first-class tooling for the Canton Token Standard so you can create an instrument, mint/transfer/burn holdings, fund parties, and reconcile balances against a live LocalNet — from the CLI or the Web UI, by readable party alias, without surfacing raw JWTs, ports, or full contract IDs in every command.

Scope: both token-standard generations, routed per instrument. Reads and transfers work against CIP-0056 (Final) instruments — what existing assets such as Canton Coin implement on stable Splice releases. Creating a new instrument uses the Token Standard V2 (CIP-0112, released in Splice 0.6.11) surface. Splice 0.6.11 and newer include the V2 APIs and test-token DARs on the normal stable release channel.

Prerequisites — bring up a current LocalNet

Use Splice 0.6.11 or newer; no alpha protocol or extra profile is required:

# list curated versions
canton-devkit localnet versions

# bring up a stable V2-capable instance
canton-devkit localnet up --name v2 --version 0.6.12

# confirm the instance is healthy
canton-devkit localnet status --name v2

All token subcommands take --instance <name>. For on-ledger actions, --endpoint <participant host:port> is optional: when omitted the command resolves the acting role’s captured participant ledger gRPC port from the instance (the same port localnet status --name v2 prints). An explicit --endpoint always wins. Where a --token flag exists it can stay empty — a per-role dev JWT is auto-issued (mint/create/demo always auto-issue); --role defaults to app-provider (the provider participant that mints/creates).

The workspace model

On LocalNet there is no trust boundary between parties — you own all of them (the dev secret signs for every role). So the token tool is a single operator workspace over the instance, not a wallet-per-party:

Party aliases — token party new bob allocates a party and lets you say --to bob everywhere instead of pasting its id.
Balance matrix — token balances shows every party’s balance of every instrument in one scan.
Activity feed — token activity reconstructs an instrument’s mint/transfer/burn history from the ledger.
Faucet — token faucet bob 100 --instrument Amulet funds a party in one auto-accepted step.

Every command lands identically on the CLI and the Web UI Tokens screen (CLI ↔ UI parity).

Workflow

INST=v2
EP=localhost:63340   # participant ledger port from `localnet status`

# 1. Name a couple of parties (allocates + grants rights, records alias)
canton-devkit localnet token party new alice --instance $INST --endpoint $EP --role app-provider
canton-devkit localnet token party new bob   --instance $INST --endpoint $EP --role app-user
canton-devkit localnet token party ls        --instance $INST --endpoint $EP

# 2. Create your own native V2 instrument (auto-uploads and vets the test-token DARs on every participant)
canton-devkit localnet token create --instance $INST --endpoint $EP --non-interactive \
  --name "Retail Token" --symbol RTK --decimals 6 --initial-supply 1000000 --issuer alice

# 3. Mint supply to a party
canton-devkit localnet token mint --instance $INST --endpoint $EP \
  --instrument RTK --to bob --amount 1000

# 4. See everyone's balances at a glance
canton-devkit localnet token balances --instance $INST --endpoint $EP

# 5. Transfer (--auto-accept settles in one step on LocalNet)
canton-devkit localnet token transfer --instance $INST --endpoint $EP \
  --instrument RTK --from bob --to alice --amount 250 --auto-accept

# 6. Inspect one instrument
canton-devkit localnet token summary  --instance $INST --endpoint $EP --instrument RTK
canton-devkit localnet token activity --instance $INST --endpoint $EP --instrument RTK

# 7. Burn supply (archives the holder's holdings; returns change)
canton-devkit localnet token burn --instance $INST --endpoint $EP \
  --instrument RTK --from bob --amount 100

Add --format json to any read command (balance, balances, summary, activity, party ls) for machine-readable output.

Command reference

Command	What it does
`token create`	Create an on-ledger V2 instrument (TokenRules) for an issuer. Auto-uploads and vets the bundled `splice-test-token-v2` DARs on every LocalNet participant (`sv`, `app-provider`, `app-user`) if not already vetted. `--non-interactive` for CI; otherwise a wizard.
`token demo`	One-command demo: allocate an issuer, create a V2 instrument on-ledger, mint the initial supply, and fund a holder so the token is transferable immediately (`--symbol DEMO`, `--supply 1000000` defaults). Same orchestration as the UI’s Launch-demo-token button.
`token mint`	Mint new supply to a party (`TokenRules_OfferMint`, controller = issuer). Native CIP-0112 v2 instruments only.
`token transfer`	Sender-initiated transfer. `--auto-accept` chains the receiver-side accept (LocalNet default convenience); `--no-wait` returns the instruction id to hand off.
`token transfer accept`	Receiver accepts a pending `TransferInstruction` by id.
`token burn`	Burn supply. The example token has no protocol burn, so this archives the holder’s `Holding` contracts directly (signatory = account parties + admin, all operator-controlled on LocalNet) and returns change.
`token faucet <party> <amount>`	Fund a party from a well-known source, auto-accepted. `--source` overrides the default funded party.
`token balance`	One party’s balances.
`token balances`	Party × instrument balance matrix (cross-party reconciliation).
`token summary`	Supply / holder count / holding-contract count + holder distribution for one instrument.
`token activity`	Mint/transfer/burn history for one instrument, reconstructed from the ledger.
`token party new\|ls\|rm`	Manage the party alias registry.

V2 release compatibility

Token Standard V2 was released in Splice 0.6.11. For normal development:

Use Splice 0.6.11 or newer. These stable releases include the V2 API packages and splice-test-token-v2 DAR used by DevKit’s create flow.
No V2 profile is needed. The legacy token-standard-v2 catalogue entry and --profile tokens-v2 overlay exist only to reproduce the pre-release alpha environment.
Loopback-only dev auth. Per-role JWTs are signed with a literal unsafe dev secret. They are valid only against your local stack — never reuse them against DevNet/TestNet/MainNet.

Amulet vs. your own token

Amulet (Canton Coin) is dual-implemented (V1 + V2). The workspace observes it — balances, matrix, activity — and can transfer it via the off-ledger scan registry, but it has no mint or burn surface (those are governance operations). The UI gates Mint/Burn accordingly.
Your own splice-test-token-v2 instrument is fully operable: create → mint → transfer → burn, all on-ledger, no scan registry dependency (its TokenRules is the registry).

See also: Getting started · FAQ · troubleshooting · versions.