Registry Canister API Reference
Canister ID: enh6y-7qaaa-aaaab-afaha-cai
The Registry canister manages on-chain creation and deployment of ICRC-1 ledger canisters and spot market canisters. It stores WASM modules, collects ICP creation fees via ICRC-2, orchestrates multi-step canister creation workflows, and maintains a registry of all deployed markets.
For complete method signatures and type definitions, refer to the Candid interface file (
registry.did).
Public Endpoints
Queries
get_control
Returns the full registry configuration state. No authentication required.
get_creation_fees
Returns current ICP creation fees (in e8s). No authentication required.
Default fees:
| Type | Fee |
|---|---|
| Ledger | 5 ICP (500,000,000 e8s) |
| Spot market | 20 ICP (2,000,000,000 e8s) |
get_spot_market
Look up a registered spot market by its base and quote ledger principals. No authentication required. Returns null if no market exists for the pair.
get_all_markets
Returns all registered spot markets. No authentication required.
get_creations
Returns creation history (ledger + spot) for the caller. Authenticated (uses caller principal). Returns entries showing creation progress, phase, and outcome.
Update Calls
create_spot_market
Create a new spot market canister for a token pair.
Prerequisites:
- Caller must have an ICRC-2 allowance granted to the Registry on the ICP ledger for at least the spot creation fee.
- Both base and quote tokens must implement ICRC-2 (
icrc2_approve/icrc2_transfer_from). - Quote token must be one of: ICP, ckUSDT, or ckUSDC.
- Base token cannot be a quote token (unless caller is admin).
- Market must not already exist for this pair.
Error codes:
| Code | Meaning |
|---|---|
IDENTICAL_TOKENS | Base and quote are the same principal |
INVALID_QUOTE | Quote token is not ICP, ckUSDT, or ckUSDC |
INVALID_BASE | Base token is a quote token (non-admin caller) |
DUPLICATE_MARKET | Market already exists for this pair |
NOT_CONFIGURED | Treasury or indexer not configured |
PAYMENT_FAILED | ICRC-2 transfer_from failed (insufficient allowance or balance) |
ICRC2_REQUIRED | One of the tokens does not support ICRC-2 |
EXTERNAL_SERVICE_ERROR | Treasury or WASM install failure |
create_ledger
Create a new ICRC-1 ledger canister.
Prerequisites:
- Caller must have an ICRC-2 allowance granted to the Registry on the ICP ledger for at least the ledger creation fee.
Validation rules for LedgerInitArgs:
| Field | Constraint |
|---|---|
token_name | 1-20 characters; letters, digits, spaces; no leading/trailing spaces |
token_symbol | 2-8 characters; uppercase letters and digits only |
decimals | Must be 8 (if provided) |
transfer_fee | Max Nat128 |
initial_balances | Max 1,000 entries; each amount max Nat128; sum max Nat128 |
metadata | Max 10 entries |
icrc1:logo | Must be PNG data URL (data:image/png;base64,...); max 140KB |
controllers | Max 10 |
Error codes:
| Code | Meaning |
|---|---|
INVALID_TOKEN_NAME | Name violates length or character rules |
INVALID_TOKEN_SYMBOL | Symbol violates length or character rules |
INVALID_DECIMALS | Decimals is not 8 |
INVALID_TRANSFER_FEE | Fee exceeds Nat128 max |
TOO_MANY_BALANCES | More than 1,000 initial balance entries |
INVALID_BALANCE | Individual balance exceeds Nat128 |
INVALID_TOTAL_SUPPLY | Sum of initial balances exceeds Nat128 |
TOO_MANY_METADATA | More than 10 metadata entries |
LOGO_TOO_LARGE | Logo data URL exceeds 140KB |
LOGO_NOT_PNG | Logo is not a PNG data URL |
LOGO_INVALID | Logo metadata value is not Text |
TOO_MANY_CONTROLLERS | More than 10 controllers |
PAYMENT_FAILED | ICRC-2 transfer_from failed |
NOT_CONFIGURED | Treasury not configured |
EXTERNAL_SERVICE_ERROR | Treasury or WASM install failure |
claim_refund
Claim an owed ICP refund from a previously failed canister creation. Returns the net amount transferred (gross minus ICP ledger fee), or 0 if the owed amount was dust (less than or equal to the transfer fee). Returns an error if no refund is owed.
Error codes: REFUND_FAILED -- no refund owed or transfer failed.
release_rate_limit
Pay to release a rate-limited principal. Costs 11x the ICP transfer fee (10x penalty + 1x ICRC transfer fee), pulled from the caller's wallet via ICRC-2.
Constraints:
- Caller must not be blocked themselves.
- Caller cannot release themselves (
SELF_RELEASE). - Target must have violations (
NOT_BLOCKED).
Canister Creation Flow
Both create_spot_market and create_ledger follow a multi-step workflow. If any step after payment fails, the creation fee is refunded (or recorded as owed if the refund transfer itself fails).
Spot Market Creation
1. Validate token pair
- Reject identical tokens
- Quote must be ICP, ckUSDT, or ckUSDC
- Base must not be a quote token (unless admin)
- Market must not already exist
2. Resolve local state (fail-fast, no cleanup needed)
- Load active spot WASM module
- Verify treasury and indexer are configured
3. Lock pair (prevents TOCTOU races across await boundaries)
4. Collect ICP payment via ICRC-2 transfer_from
└─ On failure: unlock pair, return error
5. Query ICRC-1 metadata for both tokens
- icrc1_name, icrc1_symbol, icrc1_decimals, icrc1_fee
- Enforces size limits (name ≤256, symbol ≤32, decimals ≤18)
└─ On failure: unlock pair, refund ICP
6. Validate ICRC-2 compliance on both tokens
└─ On failure: unlock pair, refund ICP
7. Create canister shell via Treasury
- Treasury allocates cycles and creates the canister
└─ On failure: unlock pair, refund ICP
8. Install spot WASM with token init args
9. Register market metadata in Registry state
10. Unlock pair
11. Notify Indexer (best-effort)
- Failure is logged but does not fail the creation
Ledger Creation
1. Validate all init args (name, symbol, decimals, fees, balances, metadata, logo, controllers)
2. Resolve local state
- Load active ledger WASM module
- Verify treasury is configured
3. Collect ICP payment via ICRC-2 transfer_from
4. Create canister shell via Treasury (marked as #unmanaged)
5. Install ledger WASM with LedgerArg (#Init variant)
6. Register ledger metadata in Registry state
Payment and Refunds
- Collection: ICP is pulled from the caller via ICRC-2
transfer_from. The caller must first callicrc2_approveon the ICP ledger (ryjl3-tyaaa-aaaaa-aaaba-cai) granting the Registry canister an allowance of at least the creation fee. - Refunds on failure: If creation fails after payment, the Registry pushes the full fee amount back to the caller. If the refund transfer itself fails, the amount is recorded as owed and can be claimed later via
claim_refund. - Fee forwarding: The Registry's hourly heartbeat pushes accumulated fees to the Treasury via
collect_protocol_fees(ICRC-2 pull by Treasury).