Skip to main content

token/Fungible

Reference for mo:core/token/Fungible in the core library.

Import​

mo:core/token/Fungible

Status​

  • Runtime token module
  • Uses contracts to preserve token identity and balances

Purpose​

token/Fungible defines a fungible token value with identity metadata and mutable balance. Token identity includes the token module hash, ticker, decimals, minting module hash, and issuer. Operations preserve identity while updating balances.

This module is useful for digital-asset examples and modules that need a verified token value rather than a custom balance record.

Public API​

Types​

  • Token - A token value with ticker, decimals, mintModuleHash, issuer, and mutable amount.
  • Id - Stable token identity: tokenModuleHash, ticker, decimals, mintModuleHash, and issuer.

Pure Helpers​

  • validTicker(symbol : Text) : Bool - Checks ticker length is between 3 and 8 characters.
  • unit(decimals : Nat) : Nat - Returns 10 ** decimals.
  • unitOfId(id : Id) : Nat - Returns the unit for an id.
  • unitOf(t : Token) : Nat - Returns the unit for a token.
  • id(symbol : Text, decimals : Nat, mintModuleHash : Blob, issuer : Principal) : Id - Builds an id for the current token module hash.
  • idOf(t : Token) : Id - Reads a token's id.
  • balance(t : Token) : Nat - Reads a token's balance.
  • model(t : Token) : (Id, Nat) - Returns the token identity and balance as a spec-friendly pair.

Runtime Functions​

  • empty(id : Id) : Token - Creates a zero-balance token for an id owned by the current token module.
  • emptyLike(t : Token) : Token - Creates a distinct zero-balance token with the same id.
  • create(symbol : Text, decimals : Nat) : Token - Creates a zero-balance token whose mint module is the local caller module. Traps if there is no local module caller or the ticker is invalid.
  • mint(t : Token, n : Nat) : () - Increases balance by n. Traps unless the local caller module hash matches t.mintModuleHash.
  • transfer(from : Token, to : Token, n : Nat) : () - Moves n between distinct tokens with the same id, requiring enough balance.
  • transferAll(from : Token, to : Token) : Nat - Moves the entire balance between distinct tokens with the same id and returns the moved amount.
  • transferAllChecked(from : Token, to : Token) : Nat - Like transferAll, but traps on id mismatch instead of requiring equality.
  • burn(t : Token, n : Nat) : () - Reduces balance by n, requiring enough balance.
  • burnAll(t : Token) : Nat - Burns the full balance and returns the burned amount.

Nested Modules​

  • TokenShared - Shared-boundary helpers used by the token implementation. toShared moves the token balance into a private shareable record and sets the source balance to 0; fromShared reconstructs a token from that record. See module hash and token identity for the public-module and helper-shape rules.

Important Contracts​

  • Token identity is stable across mint, transfer, and burn operations.
  • create and mint use Runtime.callingModuleId() to tie mint authority to the caller module hash.
  • empty requires id.tokenModuleHash == Runtime.moduleHash().
  • validTicker only checks length. It does not enforce uppercase letters or an allowed-character policy.

Summary​

  • Use idOf and balance in contracts instead of reaching into token fields directly.
  • Use transfer when the caller can prove id equality; use transferAllChecked when runtime trapping on mismatch is the desired behavior.
  • Mint authority is module-hash based, not caller-principal based.