FungibleToken API

This module provides the full FungibleToken module API.

For an overview of the module, read the FungibleToken guide.

`FungibleToken`

import "./node_modules/@openzeppelin/compact-contracts/token/FungibleToken";

Ledger

_balances: Map<Either<Bytes<32>, ContractAddress>, Uint<128>>

ledger

Mapping from account addresses to their token balances.

_allowances: Map<Either<Bytes<32>, ContractAddress>, Map<Either<Bytes<32>, ContractAddress>, Uint<128>>>

ledger

Mapping from owner accounts to spender accounts to their allowances.

_totalSupply: Uint<128>

ledger

The total token supply.

_name: Opaque<"string">

sealed ledger

The immutable token name.

_symbol: Opaque<"string">

sealed ledger

The immutable token symbol.

_decimals: Uint<8>

sealed ledger

The immutable token decimals.

Witnesses

wit_FungibleTokenSK() → Bytes<32>

witness

Returns the caller's secret key used in deriving the account identifier.

The same key produces the same account identifier across all contracts. Users who desire cross-contract unlinkability should use different keys per contract.

Circuits

ZERO() → Either<Bytes<32>, ContractAddress>

pure

Returns a canonical zero Either value for Bytes<32> and ContractAddress. Returns the left variant (Bytes<32>) to avoid misleading contract-to-contract error messages.

initialize(
  name_: Opaque<"string">,
  symbol_: Opaque<"string">,
  decimals_: Uint<8>
) → []

circuit

Initializes the contract by setting the name, symbol, and decimals.

This MUST be called in the implementing contract's constructor. Failure to do so can lead to an irreparable contract.

Requirements:

Contract is not initialized.

k=10, rows=71

name() → Opaque<"string">

circuit

Returns the token name.

Requirements:

Contract is initialized.

k=6, rows=28

symbol() → Opaque<"string">

circuit

Returns the symbol of the token.

Requirements:

Contract is initialized.

k=6, rows=28

decimals() → Uint<8>

circuit

Returns the number of decimals used to get its user representation.

Requirements:

Contract is initialized.

k=6, rows=28

totalSupply() → Uint<128>

circuit

Returns the value of tokens in existence.

Requirements:

Contract is initialized.

k=6, rows=28

balanceOf(account: Either<Bytes<32>, ContractAddress>) → Uint<128>

circuit

Returns the value of tokens owned by account.

Requirements:

Contract is initialized.

k=10, rows=673

transfer(to: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → Boolean

circuit

Moves a value amount of tokens from the caller's account to to.

Transfers to contract addresses are currently disallowed until contract-to-contract interactions are supported in Compact. This restriction prevents assets from being inadvertently locked in contracts that cannot currently handle token receipt.

Requirements:

Contract is initialized.
to is not a ContractAddress.
to is not the zero address.
The caller has a balance of at least value.

k=13, rows=3985

_unsafeTransfer(to: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → Boolean

circuit

Unsafe variant of transfer which allows transfers to contract addresses.

Transfers to contract addresses are considered unsafe because contract-to-contract calls are not currently supported. Tokens sent to a contract address may become irretrievable. Once contract-to-contract calls are supported, this circuit may be deprecated.

Requirements:

Contract is initialized.
to is not the zero address.
The caller has a balance of at least value.

k=13, rows=3982

allowance(
  owner: Either<Bytes<32>, ContractAddress>,
  spender: Either<Bytes<32>, ContractAddress>
) → Uint<128>

circuit

Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom. This value changes when approve or transferFrom are called.

Requirements:

Contract is initialized.

k=11, rows=1346

approve(spender: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → Boolean

circuit

Sets a value amount of tokens as allowance of spender over the caller's tokens.

Requirements:

Contract is initialized.
spender is not the zero address.

k=13, rows=3072

transferFrom(
  fromAddress: Either<Bytes<32>, ContractAddress>,
  to: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → Boolean

circuit

Moves value tokens from fromAddress to to using the allowance mechanism. value is then deducted from the caller's allowance.

Requirements:

Contract is initialized.
fromAddress is not the zero address.
fromAddress must have a balance of at least value.
to is not the zero address.
to is not a ContractAddress.
The caller has an allowance of fromAddress's tokens of at least value.

k=13, rows=4960

_unsafeTransferFrom(
  fromAddress: Either<Bytes<32>, ContractAddress>,
  to: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → Boolean

circuit

Unsafe variant of transferFrom which allows transfers to contract addresses.

Requirements:

Contract is initialized.
fromAddress is not the zero address.
fromAddress must have a balance of at least value.
to is not the zero address.
The caller has an allowance of fromAddress's tokens of at least value.

k=13, rows=4957

_transfer(
  fromAddress: Either<Bytes<32>, ContractAddress>,
  to: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → []

circuit

Moves a value amount of tokens from fromAddress to to. This circuit is equivalent to transfer, and can be used to e.g. implement automatic token fees, slashing mechanisms, etc.

Requirements:

Contract is initialized.
fromAddress is not the zero address.
fromAddress must have at least a balance of value.
to must not be the zero address.
to must not be a ContractAddress.

k=12, rows=2345

_unsafeUncheckedTransfer(
  fromAddress: Either<Bytes<32>, ContractAddress>,
  to: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → []

circuit

Unsafe variant of _transfer which allows transfers to contract addresses.

Requirements:

Contract is initialized.
fromAddress is not the zero address.
to is not the zero address.

k=12, rows=2342

_update(
  fromAddress: Either<Bytes<32>, ContractAddress>,
  to: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → []

internal

Transfers a value amount of tokens from fromAddress to to, or alternatively mints (or burns) if fromAddress (or to) is the zero address.

Requirements:

Contract is initialized.

k=11, rows=1305

_mint(account: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → []

circuit

Creates a value amount of tokens and assigns them to account, by transferring it from the zero address. Relies on the _update mechanism.

Requirements:

Contract is initialized.
account is not a ContractAddress.
account is not the zero address.

k=11, rows=1437

_unsafeMint(account: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → []

circuit

Unsafe variant of _mint which allows transfers to contract addresses.

Requirements:

Contract is initialized.
account is not the zero address.

k=11, rows=1434

_burn(account: Either<Bytes<32>, ContractAddress>, value: Uint<128>) → []

circuit

Destroys a value amount of tokens from account, lowering the total supply. Relies on the _update mechanism.

Requirements:

Contract is initialized.
account is not the zero address.
account must have at least a balance of value.

k=11, rows=1377

_approve(
  owner: Either<Bytes<32>, ContractAddress>,
  spender: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → []

circuit

Sets value as the allowance of spender over the owner's tokens. This circuit is equivalent to approve, and can be used to e.g. set automatic allowances for certain subsystems, etc.

Requirements:

Contract is initialized.
owner is not the zero address.
spender is not the zero address.

k=11, rows=1406

_spendAllowance(
  owner: Either<Bytes<32>, ContractAddress>,
  spender: Either<Bytes<32>, ContractAddress>,
  value: Uint<128>
) → []

circuit

Updates owner's allowance for spender based on spent value. Does not update the allowance value in case of infinite allowance.

Requirements:

Contract is initialized.
spender must have at least an allowance of value from owner.

k=11, rows=1729

_computeAccountId() → Bytes<32>

internal

Computes the caller's account identifier from the wit_FungibleTokenSK witness.

ID Derivation: accountId = persistentHash(secretKey)

The result is a 32-byte commitment that uniquely identifies the caller.

computeAccountId(secretKey: Bytes<32>) → Bytes<32>

pure

Computes an account identifier without on-chain state, allowing a user to derive their identity commitment before submitting a token operation. This is the off-chain counterpart to the internal _computeAccountId and produces an identical result given the same inputs.

ID Derivation: accountId = persistentHash(secretKey)

The secretKey parameter is a sensitive secret. Mishandling it can permanently compromise the security of this system. Never log or persist the key in plaintext. Use cryptographically secure randomness to generate keys. Treat key loss as identity loss. A lost key cannot be recovered.

_isTargetZero(target: Either<Bytes<32>, ContractAddress>) → Boolean

internal

Returns true if target's active branch (as indicated by is_left) holds the zero value.

FungibleToken API

FungibleToken

Ledger

Witnesses

Circuits

On this page

`FungibleToken`