MultiToken API

This module provides the full MultiToken module API.

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

`MultiToken`

import "./node_modules/@openzeppelin/token/src/MultiToken";

Ledger

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

ledger

Mapping from token ID to account balances.

_operatorApprovals: Map<Either<Bytes<32>, ContractAddress>, Map<Either<Bytes<32>, ContractAddress>, Boolean>>

ledger

Mapping from account to operator approvals.

_uri: Opaque<"string">

ledger

Base URI for computing token URIs.

Witnesses

wit_MultiTokenSK() → 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 (left variant with zero Bytes<32>). Used as the zero value for mint/burn operations in _update, where a zero fromAddress signals a mint and a zero to signals a burn.

initialize(uri_: Opaque<"string">) → []

circuit

Initializes the contract by setting the base URI for all tokens.

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=6, rows=33

uri(id: Uint<128>) → Opaque<"string">

circuit

This implementation returns the same URI for all token types. It relies on the token type ID substitution mechanism defined in the EIP: ERC1155-Metadata. Clients calling this function must replace the \{id\} substring with the actual token type ID.

Requirements:

Contract is initialized.

k=8, rows=176

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

circuit

Returns the amount of id tokens owned by account.

Requirements:

Contract is initialized.

k=10, rows=875

setApprovalForAll(
  operator: Either<Bytes<32>, ContractAddress>,
  approved: Boolean
) → []

circuit

Enables or disables approval for operator to manage all of the caller's assets. The caller's identity is derived from the wit_MultiTokenSK witness as persistentHash(secretKey).

Requirements:

Contract is initialized.
operator is not zero.

k=13, rows=2944

isApprovedForAll(
  account: Either<Bytes<32>, ContractAddress>,
  operator: Either<Bytes<32>, ContractAddress>
) → Boolean

circuit

Queries if operator is an authorized operator for account.

Requirements:

Contract is initialized.

k=11, rows=1343

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

circuit

Transfers ownership of value amount of id tokens from fromAddress to to. The caller must be fromAddress or approved to transfer on their behalf. The caller's identity is derived from the wit_MultiTokenSK witness as persistentHash(secretKey).

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 zero.
fromAddress is not zero.
Caller must be fromAddress or approved via setApprovalForAll.
fromAddress must have an id balance of at least value.

k=13, rows=4926

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

circuit

Transfers ownership of value amount of id tokens from fromAddress to to. Does not impose restrictions on the caller, making it suitable for composition in higher-level contract logic.

Requirements:

Contract is initialized.
to is not a ContractAddress.
to is not zero.
fromAddress is not zero.
fromAddress must have an id balance of at least value.

k=12, rows=2450

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

internal

Transfers a value amount of tokens of type id from fromAddress to to. This circuit will mint (or burn) if fromAddress (or to) is zero.

Requirements:

Contract is initialized.
If fromAddress is not zero, the balance of id of fromAddress must be >= value.

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

circuit

Unsafe variant of transferFrom which allows transfers to contract addresses. The caller must be fromAddress or approved to transfer on their behalf. The caller's identity is derived from the wit_MultiTokenSK witness as persistentHash(secretKey).

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 zero.
fromAddress is not zero.
Caller must be fromAddress or approved via setApprovalForAll.
fromAddress must have an id balance of at least value.

k=13, rows=4925

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

circuit

Unsafe variant of _transfer which allows transfers to contract addresses. Does not impose restrictions on the caller, making it suitable as a low-level building block for advanced contract logic.

Requirements:

Contract is initialized.
fromAddress is not zero.
to is not zero.
fromAddress must have an id balance of at least value.

k=12, rows=2449

_setURI(newURI: Opaque<"string">) → []

circuit

Sets a new URI for all token types, by relying on the token type ID substitution mechanism defined in the MultiToken standard. See https://eips.ethereum.org/EIPS/eip-1155#metadata.

By this mechanism, any occurrence of the \{id\} substring in either the URI or any of the values in the JSON file at said URI will be replaced by clients with the token type ID.

For example, the https://token-cdn-domain/\{id\}.json URI would be interpreted by clients as https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json for token type ID 0x4cce0.

Requirements:

Contract is initialized.

k=6, rows=28

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

circuit

Creates a value amount of tokens of type id, and assigns them to to.

Requirements:

Contract is initialized.
to is not zero.
to is not a ContractAddress.

k=11, rows=1531

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

circuit

Unsafe variant of _mint which allows transfers to contract addresses.

Requirements:

Contract is initialized.
to is not zero.

k=11, rows=1530

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

circuit

Destroys a value amount of tokens of type id from fromAddress.

Requirements:

Contract is initialized.
fromAddress is not zero.
fromAddress must have an id balance of at least value.

k=11, rows=1222

_setApprovalForAll(
  owner: Either<Bytes<32>, ContractAddress>,
  operator: Either<Bytes<32>, ContractAddress>,
  approved: Boolean
) → []

circuit

Enables or disables approval for operator to manage all of owner's assets. This circuit does not check for access permissions but can be useful as a building block for more complex contract logic.

Requirements:

Contract is initialized.
owner is not zero.
operator is not zero.

k=11, rows=1279

_computeAccountId() → Bytes<32>

internal

Computes the caller's account identifier from the wit_MultiTokenSK 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 it in 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.

MultiToken API

MultiToken

Ledger

Witnesses

Circuits

On this page

`MultiToken`