dom-token API

ICRC-1/2 compliant DOM token ledger with policy-based burning for deflationary tokenomics.

Candid file: dom-token/src/dom_token.didStandard: ICRC-1, ICRC-2

Types

Account

Standard ICRC-1 account:

type Account = record {
  owner: principal;
  subaccount: opt blob;
};

TransferArgs

type TransferArgs = record {
  from_subaccount: opt blob;
  to: Account;
  amount: nat;
  fee: opt nat;
  memo: opt blob;
  created_at_time: opt nat64;
};

TransferError

type TransferError = variant {
  BadFee: record { expected_fee: nat };
  BadBurn: record { min_burn_amount: nat };
  InsufficientFunds: record { balance: nat };
  TooOld;
  CreatedInFuture: record { ledger_time: nat64 };
  Duplicate: record { duplicate_of: nat };
  TemporarilyUnavailable;
  GenericError: record { error_code: nat; message: text };
};

BurnPolicy

Available burn policies:

type BurnPolicy = variant {
  GeneralDonation;      // 1:1 burn rate
  EcologicalDonation;   // 5:1 amplified burn
  MarketplaceUnder50k;  // 5% burn
  MarketplaceOver50k;   // 7% burn
  InGamePurchase;       // 5% burn
};

BurnResult

type BurnResult = record {
  transaction_index: nat;
  tokens_burned: nat;
  effective_burn_rate: float64;
};

ICRC-1 Standard Methods

Metadata

icrc1_name (query)

"icrc1_name": () -> (text) query;

Returns: "DOM Token"

icrc1_symbol (query)

"icrc1_symbol": () -> (text) query;

Returns: "DOM"

icrc1_decimals (query)

"icrc1_decimals": () -> (nat8) query;

Returns: 8

icrc1_fee (query)

"icrc1_fee": () -> (nat) query;

Returns transfer fee amount.

icrc1_total_supply (query)

"icrc1_total_supply": () -> (nat) query;

Total tokens in existence (decreases with burns).

icrc1_balance_of (query)

"icrc1_balance_of": (Account) -> (nat) query;

Transfer

icrc1_transfer

Transfer tokens between accounts.

"icrc1_transfer": (TransferArgs) -> (variant { Ok: nat; Err: TransferError });

TypeScript Example:

const result = await domTokenActor.icrc1_transfer({
  from_subaccount: [],
  to: {
    owner: Principal.fromText(recipientPrincipal),
    subaccount: [],
  },
  amount: 1000_00000000n, // 1000 DOM with 8 decimals
  fee: [],
  memo: [],
  created_at_time: [],
});

Burn

icrc1_burn

Simple burn without policy.

"icrc1_burn": (amount: nat) -> (variant { Ok: nat; Err: TransferError });

Burn Policy System

burn_with_policy

Burn tokens with a specific policy multiplier.

"burn_with_policy": (BurnWithPolicyArgs) -> (variant { Ok: BurnResult; Err: TransferError });

type BurnWithPolicyArgs = record {
  amount: nat;
  policy: BurnPolicy;
  memo: opt blob;
};

Policy Rates:

Policy	Burn Rate	Use Case
GeneralDonation	1:1	Standard donations
EcologicalDonation	5:1	Environmental causes
MarketplaceUnder50k	5%	Small purchases
MarketplaceOver50k	7%	Large purchases
InGamePurchase	5%	Otter Camp games

TypeScript Example:

const result = await domTokenActor.burn_with_policy({
  amount: 100_00000000n, // 100 DOM
  policy: { EcologicalDonation: null },
  memo: [],
});

if ('Ok' in result) {
  console.log('Burned:', result.Ok.tokens_burned);
  console.log('Effective rate:', result.Ok.effective_burn_rate);
}

Policy Management (Admin Only)

enable_policy

"enable_policy": (policy_name: text) -> (variant { Ok; Err: text });

disable_policy

"disable_policy": (policy_name: text) -> (variant { Ok; Err: text });

get_policy_states (query)

"get_policy_states": () -> (vec record { text; bool }) query;

Analytics

total_burned (query)

Total tokens burned across all time.

"total_burned": () -> (nat) query;

circulating_supply (query)

Current circulating supply (total - burned - treasury).

"circulating_supply": () -> (nat) query;

burn_history (query)

Get burn event history.

"burn_history": (start_time: opt nat64, end_time: opt nat64) -> (vec BurnEvent) query;

type BurnEvent = record {
  timestamp: nat64;
  policy: text;
  amount: nat;
  caller: principal;
  transaction_index: nat;
};

Token Distribution (Admin Only)

mint_tokens

Mint new tokens (genesis distribution only).

"mint_tokens": (Account, amount: nat) -> (variant { Ok: nat; Err: text });

batch_distribute

Distribute tokens to multiple accounts.

"batch_distribute": (vec record { Account; nat }) -> (variant { Ok: nat64; Err: text });

Returns distribution ID.

Authorization

authorize_burner

Authorize a canister to burn tokens.

"authorize_burner": (principal) -> (variant { Ok; Err: TransferError });

revoke_burner

Revoke burn authorization.

"revoke_burner": (principal) -> (variant { Ok; Err: TransferError });

get_burners (query)

List authorized burners.

"get_burners": () -> (vec principal) query;

Error Messages

Error	Cause	Resolution
InsufficientFunds	Balance too low	Check balance first
BadBurn	Amount below minimum	Increase burn amount
BadFee	Fee mismatch	Use correct fee
TooOld	Transaction too old	Use current timestamp
Policy disabled	Burn policy not active	Use different policy