Phantom Types

A type parameter is phantom if it is not used in any field (or used only as another phantom argument).

20.1 What is a phantom type parameter?

A type parameter is phantom if it is not used in any field (or used only as another phantom argument). Phantom parameters do not affect the struct's abilities.

Coin<USDC> and Coin<SUI> have the same layout but are different types — you cannot add them together.

public struct Coin<phantom T> has key, store {
    id: UID,
    balance: Balance<T>,
}

public struct Balance<phantom T> has store { value: u64 }

20.2 Why phantom matters

Without phantom, Coin<T> would only have store if T had store. Coin type markers are usually declared like public struct USDC has drop {} (no store), so the marker would poison the abilities. phantom tells the compiler the parameter is only a tag.

20.3 Type-tagged patterns

Coin<phantom T>, Balance<phantom T>, Aptos Coin<phantom CoinType> Permission<phantom Role> Unit of measure Amount<phantom Unit> Pool<phantom X, phantom Y>

public struct Vault<phantom Asset> has key { id: UID, balance: Balance<Asset> }

public struct Permission<phantom Role> has key, store { id: UID }
public struct Admin has drop {}
public struct Minter has drop {}

// Only holders of Permission<Minter> can call this
public fun mint(_: &Permission<Minter>, /* ... */) { }