MIP-xxxx: Token Standards

[hbulgarini]

Preliminary discussion to scope a coherent token-standards effort across the token types Midnight supports. The four base quadrants are:

• Shielded Native tokens
• Unshielded Native tokens
• Shielded contract tokens
• Unshielded contract tokens

Plus two hybrid types that sit between the ledger and contract worlds:

• Unshielded hybrid tokens (unshielded native tokens fully managed by a Compact contract)
• Shielded hybrid tokens (shielded native tokens fully managed by a Compact contract)

Each likely deserves its own standard, or at least its own section. The shielded vs unshielded split alone changes what is even expressible (balanceOf and totalSupply only make sense on the unshielded side; contract tokens add another dimension of public vs private state).

This thread is intended as an umbrella discussion, not a replacement for the more focused proposals already in flight. Where existing MIPs cover a topic, they should remain the canonical place to debate it; the goal here is to make sure all four quadrants are addressed coherently and that nothing falls through the cracks.

Native tokens

The protocol pins the on-chain shape: CoinInfo, commitments, nullifiers, and the offer / balance structure are fixed. What remains open lives off-chain or at the wallet layer:

• address encoding and payment URIs
• HD derivation paths
• the output ciphertext payload (encrypted to the recipient, carries (nonce, type, value) plus optional memo)
• transfer receipts
• optional view-key conventions for compliance
• metadata

Wallets are landing now, so divergence here is the most time-sensitive risk.

Contract tokens

Logic is fully customizable in Compact, which makes the surface look ERC-20-shaped, but Kachina's separation of public on-chain state from private witness state changes how "balance" and "transfer" are actually expressed. There is also a real architectural choice between balance-in-Map (account model) and balance-held-as-contract-coin (UTXO held by the contract). The standard should pick one or define both, and decide whether private-state shape is part of the standard or implementation-defined.

Hybrid tokens

Hybrid tokens aim for the best of both worlds: a coin that lives in the Zswap ledger layer (native efficiency, and privacy in the shielded case) while its full lifecycle is governed by a Compact contract (mint policy, transfer rules, compliance hooks).

The blocker today is spend bypass. A Zswap coin's nullifier is derived from either the owner's secret key or a contract address. When a contract holds the UTXO, spending requires the contract's authorization, so contract logic is enforced. But when the user is the UTXO owner, they can construct a spend with their own key and operate Zswap directly, bypassing the managing contract entirely. So a contract-managed ledger token only holds as long as the contract custodies the coin, which defeats the point of a user-held hybrid token.

There is a potential fix, tentatively called custom spend logic, which would let a coin carry spend conditions that must be satisfied regardless of who owns the UTXO. That mechanism is out of scope for this thread and is expected to be discussed in its own MPS/MIP. This thread should note the dependency but not try to design it here.

Related proposals already under discussion

• Fungible Token Standard with UTXO (PR #75). Contract-token side, with four conversion circuits (shield, toUtxo, unshield, fromUtxo) that bridge a Map-based balance into either shielded or unshielded UTXOs while preserving supply invariants. Flags the Uint<64> mint limit and UTXO fragmentation as open.
• P2P Atomic Swaps (PR #47). Application-layer offer-exchange protocol on top of native Zswap transaction merging. Defines a JSON offer schema, optional BIP-340 Schnorr authentication, and a reference indexer REST API. Fee splitting and privacy of the indexer are explicitly deferred.
• Off-Chain Token Metadata Registry (PR #104). Covers all four quadrants. Defines a metadata schema (identity plus quadrant-specific fields), Ed25519-attested entries with sequence numbers, mandatory color-derivation verification for contract tokens, and a CIP-26-inspired off-chain registry with privacy-preserving query patterns. Open questions: NFT metadata, multi-contract tokens, governance, view keys.

Together those cover metadata, contract-token UTXO interop, and atomic-swap RFQ.

Aspects not yet addressed by an open proposal:

• address encoding and payment URIs
• HD derivation
• the ciphertext-payload memo format
• issuance attestations
• transfer receipts
• view keys for compliance

Open questions for this thread

Intentionally broad. Topic-specific questions should stay in the MIPs above.

1. Is the four-quadrant-plus-two-hybrid taxonomy the right cut for the standards effort, or do we collapse some?
2. Should contract-token standards specify private-state shape, or only the public interface?
3. Should contract tokens be required to track total minted / burnt as on-chain state, or is that left to the implementation?
4. For ledger tokens, who is the trust anchor for metadata: a federated registry, the issuer's DID, or both? (Picked up in PR MPS-xxx: Token Registry #104 but worth aligning here.)
5. What is the standard substitute for ERC-20 Transfer events on a chain with no native event log?
6. Prioritization: is the ledger-side wallet-interop work (addresses, HD, URIs, memo) more time-sensitive than contract-token interfaces? It launches first and is harder to change later.
7. Hybrid tokens depend on custom spend logic landing first. Do we scope the hybrid standards now in anticipation, or hold them until that mechanism is specified?

Looking for thoughts on scope, sequencing, and which precedents (Cardano CIPs, Zcash ZIPs, EIPs) are the closest analogues per quadrant.

[hbulgarini]

This topic has been extensively discussed during the Wallets and Dapps Working group call held on Jun 10th 2026. Meeting notes attached below:

https://docs.google.com/document/d/1TBN0lypSkffWY4DsX5o9HT1NSbv7oZt06QSN-FESLqw/edit?tab=t.ii1p7orc0s2v

[hbulgarini]

Updated "Ledger" token types as "Native" token types as @0xisk recommendation.

[kapke]

Should contract-token standards specify private-state shape, or only the public interface?

Only the public interface. The underlying state shape might differ greatly between different tokens depending on the exact functionality they implement.

What is the standard substitute for ERC-20 Transfer events on a chain with no native event log?

Native events are coming; See https://github.com/midnightntwrk/midnight-improvement-proposals/blob/main/mips/mip-0002-public-contract-log-emission.md

For ledger tokens, who is the trust anchor for metadata: a federated registry, the issuer's DID, or both?

It does not need apply to ledger tokens only really. DID avenue is interesting on the very basis of being decentralized in the idea, but who would issue the authorizing DID in the first place?

[kapke]

Is the four-quadrant-plus-two-hybrid taxonomy the right cut for the standards effort, or do we collapse some?

I think it is the right cut. Each kind has its own challenges and gaps on Midnight, so collapsing them would make it harder to remember about particular case or ignore some privacy-led requirements.

[AndrewWestberg]

In order to have good contract composability and a generally good user experience, we need to minimize the number of addresses a wallet needs to know about and maintain. If every single contract is doing its own custom domain-specific hash in order to create an "accountId" for the user, that is the same as adding a new address the wallet needs to track.

For public programmable tokens, what we need is the ability to verify ownership of UserAddress inside compact. This can allow for public programmable tokens to be sent from one user to another by just knowning the receiver's unshielded address (UserAddress). If both parties have to first transact with the contract before value can be sent, this is a user experience dead-end.