compact-core-compact-tokens

name: compact-core:compact-tokens description: This skill should be used when the user asks about Midnight tokens, token types (NIGHT, DUST, shielded, unshielded), minting and burning tokens, token transfers, token colors and domain separators, the zswap protocol, ShieldedCoinInfo, QualifiedShieldedCoinInfo, Kernel mint operations, contract token patterns (FungibleToken, NonFungibleToken, MultiToken), the account model vs UTXO model for tokens, sendShielded, receiveShielded, sendUnshielded, mintShieldedToken, mintUnshieldedToken, unshieldedBalance, OpenZeppelin Compact token contracts, or choosing between shielded and unshielded token approaches. version: 0.1.0

Compact Tokens

This skill covers tokens on Midnight: choosing between shielded and unshielded approaches, using the standard library mint/send/receive functions, understanding token colors and domain separators, and the NIGHT/DUST token model. It does not cover ledger ADT types or state design -- those belong in compact-ledger. It does not cover overall contract anatomy or circuit/witness design -- those belong in compact-structure.

Token Decision Tree

Token Types Quick Reference

Shielded Token Operations

Key types:

Key functions:

export circuit mint(amount: Uint<64>): ShieldedCoinInfo {
  counter.increment(1);
  const newNonce = evolveNonce(counter.read() as Uint<128>, nonce);
  nonce = newNonce;
  return mintShieldedToken(
    domain, disclose(amount), nonce,
    left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey())
  );
}

export circuit send(coin: ShieldedCoinInfo, to: ZswapCoinPublicKey, amount: Uint<128>): ShieldedSendResult {
  receiveShielded(disclose(coin));
  return sendImmediateShielded(disclose(coin), left<ZswapCoinPublicKey, ContractAddress>(disclose(to)), disclose(amount));
}

Unshielded Token Operations

Caveat: unshieldedBalance() returns the balance at transaction construction time, not at application time. If the balance changes between construction and application, the transaction fails. Prefer the comparison functions (unshieldedBalanceLt, unshieldedBalanceGte, etc.) unless you specifically need an exact-match constraint.

export circuit mintToSelf(domainSep: Bytes<32>, amount: Uint<64>): Bytes<32> {
  const color = mintUnshieldedToken(
    disclose(domainSep), disclose(amount),
    left<ContractAddress, UserAddress>(kernel.self())
  );
  receiveUnshielded(color, disclose(amount) as Uint<128>);
  return color;
}

Token Colors & Identification

A token color (type) is a Bytes<32> value derived from the contract address and a domain separator:

Colors are deterministic: the same (domainSep, contractAddress) pair always yields the same color. A contract can issue multiple token types by using different domain separators. The color field in ShieldedCoinInfo identifies which token a coin represents.

NIGHT & DUST

NIGHT is Midnight's native utility token. It exists as UTXOs on the ledger with the zero token color (nativeToken()). NIGHT is used for staking, governance, and generating DUST.

DUST is a shielded network resource, not a token. It is generated from NIGHT over time when NIGHT UTXOs are registered for dust generation. Key properties:

• Non-transferable: cannot be sent to other users
• Used exclusively for transaction fees
• Proportional to NIGHT balance; decays when disconnected from NIGHT
• Provides operational predictability: no volatile gas prices

On testnet, these are called tNIGHT and tDUST. Contracts cannot mint, send, or manipulate NIGHT or DUST directly through standard library functions.

Common Mistakes

Reference Routing