midnightntwrk/midnight-expert/data-models

Midnight Data Models

Midnight supports two distinct token paradigms: UTXO-based ledger tokens and account-based contract tokens. Choose based on privacy requirements and use case complexity.

Quick Decision Guide

UTXO Model (Ledger Tokens)

UTXO = Unspent Transaction Output. Each token is a discrete digital coin that must be spent entirely.

Core Mechanics

Creation -> Existence -> Consumption -> Prevention of Reuse

1. Creation: UTXO born with a cryptographic commitment that hides the coin's value, type, and owner
2. Existence: Queryable in the commitment tree
3. Consumption: Entire UTXO spent in transaction (change returned as new UTXO)
4. Prevention: Nullifier added to global set, prevents double-spend

Nullifier Innovation

Unlike Bitcoin, which references prior outputs directly by txid+index (revealing which coin was spent), Midnight uses nullifiers:

Each coin carries a value, token type, and unique nonce. The nullifier is a hash derived from the coin data and the spending key.

Privacy benefit: The nullifier is computed from the raw coin data and the spending key, not from the commitment. This means the nullifier reveals nothing about which coin commitment was spent.

Shielded vs Unshielded

Each UTXO independently chooses privacy level:

• Shielded: Commitment hidden, value/owner private
• Unshielded: Value visible for regulatory compliance

Account Model (Contract Tokens)

Maintain address-to-balance mappings within Compact contracts, following patterns inspired by OpenZeppelin-style token standards adapted for Compact.

When to Use

• Complex DeFi state machines requiring intricate interactions
• Gaming systems with stateful game logic
• Governance tokens with delegation mechanics
• Social tokens tracking relationships

Trade-offs

Ledger Structure

Midnight's ledger has two components:

1. Zswap State

• Commitment tree — a Merkle tree of all coin commitments ever created
• First free index — pointer to the next available leaf position (append-only)
• Nullifier set — all spent-coin nullifiers, checked before accepting new spends
• Historic roots — recent Merkle roots kept for a time window so proofs can reference slightly older tree states

2. Contract Map

• Associates contract addresses with states
• Each contract state holds an Impact state value plus entry point operations (SNARK verifier keys)

Token Types

Token types are 256-bit collision-resistant hashes:

• Native token: The type identifier is the 256-bit zero value
• Custom tokens: derived by hashing a domain separator with the issuing contract's address

References

For detailed technical information:

• `references/utxo-mechanics.md` - Complete UTXO lifecycle, nullifier computation
• `references/ledger-structure.md` - Zswap state internals, Merkle tree details