Crate pallet_scarcity 

Scarcity Pallet

pallet-scarcity defines NFT collections and item definitions, then mints instances using a coinage-style ownership model: each purse key can hold at most one NFT. The pallet knows ownership, supply, metadata, and deposits; it knows nothing about what an item means. Item semantics and access-control policy can live in a higher-level runtime pallet or collection contract. At this storage layer the collection owner has full control over its definitions, metadata, and live instances, including force-transfer and force-burn. A runtime must separately expose Scarcity calls to its chosen contract environment; this crate does not provide a contract adapter.

Purse keys are coinage-style receiving addresses, not identities: the pallet applies no destination consent. Any collection owner can mint into — or force-transfer an instance to — any empty purse key, and because each key holds at most one NFT, an unsolicited instance blocks that key from receiving anything else until its holder burns it or transfers it away. Holders should treat purse keys as disposable, minting to fresh keys they control, and runtimes or contracts that need receive-consent or long-lived well-known destinations must enforce that policy above this storage layer.

The current collection owner backs all collection state with one aggregate consideration ticket. To transfer that responsibility safely, the owner first nominates a successor and the successor claims the collection. Claiming atomically creates an equivalent ticket for the successor, drops the former owner’s ticket, and transfers collection authority. This lets the successor reject an unwanted or unaffordable collection while allowing the runtime to choose how storage consideration is implemented.

Footprints count logical records and their encoded payloads rather than exact trie keys and hash prefixes. A runtime can account for backend overhead in its per-record base price and calibrate its byte price to the desired storage policy.

Cleanup proceeds from leaves to roots so every call remains bounded. The collection owner force-burns live instances (or holders burn their own), removes item metadata, deletes empty item definitions, removes collection metadata, and finally deletes the empty collection. Instance metadata is bounded and removed automatically on burn. Allocated identifiers are never reused.

Collection metadata supplies defaults inherited by every item definition, and item metadata supplies defaults shared by every instance minted from that definition. A minted instance may override either scope without affecting other instances. Pallet::instance_metadata_of resolves one key in instance, item, then collection order. Pallet::item_metadata_of resolves the item and collection scopes, while Pallet::collection_metadata_of reads only the collection scope.

Keys and values are bounded raw bytes. Numeric metadata is a convention rather than a pallet type: games should use SCALE-encoded u128 values when they need a shared numeric convention, and must decode and validate those bytes themselves.

Transfers are feeless when authorized through the AsScarcity transaction extension. Their transaction priority is the time since the NFT last moved, capped by the runtime. Moving an NFT consumes it from the old purse key and places it at the new one. Each authorization names the permanent instance and its current state nonce. The state nonce invalidates an authorization whenever that instance moves, including collection-owner force-transfers away from and back to the same purse. Following Coinage’s purse model, AsScarcity replaces the signed origin before ordinary account checks, so an NFT-only purse does not need a System account. Failed dispatch restores the NFT and temporarily locks the purse key; after the lock expires, the same signed transaction may be submitted again if its NFT state is still current. Callers must sign mortal transactions with an era shorter than Config::LockPeriod so that retrying is always a fresh signing decision; see the replay and mortality rules.

Re-exports

pub use pallet::*;

Modules

extension

Scarcity transaction extension.

pallet

The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

weights

Autogenerated weights for pallet_scarcity

Traits

MintWithoutDeposit

Runtime-only integration for minting an NFT without instance-scoped storage deposits.