diff --git a/CHIPs/chip-0060.md b/CHIPs/chip-0060.md new file mode 100644 index 00000000..c00882f0 --- /dev/null +++ b/CHIPs/chip-0060.md @@ -0,0 +1,307 @@ +CHIP Number | 0060 +:-------------|:---- +Title | Titled CAT Standard +Description | A standard binding a CAT at issuance to a singleton-anchored title that carries on-chain metadata, enforced supply commitments, an optional creator DID, and optional royalties. +Author | [Evan Winget](https://github.com/EvanWinget) +Editor | [Dan Perry](https://github.com/danieljperry) +Comments-URI | [CHIPs repo, PR #205](https://github.com/Chia-Network/chips/pull/205) +Status | Draft +Category | Standards Track +Sub-Category | Primitive +Created | 2026-05-22 +Requires | [CAT2](https://chialisp.com/cats/), [CHIP-40 (`everything_with_singleton` TAIL)](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0040.md), Singleton Standard, Offer Standard. Optional layers: [DID1 (CHIP-4)](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0004.md) (creator provenance), [CHIP-56 (Fee CATs)](https://github.com/Chia-Network/chips/pull/194) (royalties), [CHIP-38 (Revocable CATs)](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0038.md) (revocability) +Replaces | None +Superseded-By | None + + +## Abstract + +A **Titled CAT** is a Chia Asset Token (CAT) bound at issuance to a **title**: a singleton-anchored, on-chain record carrying the asset's metadata (name, ticker, content references), supply commitments, an optional creator DID, and optional royalty and revocation configuration. The binding is intrinsic, since a Unit's asset ID derives from the Title Singleton's launcher ID by construction, so identity and supply live in the coin with no registry. A CAT already has an opaque on-chain identity in its TAIL, but its name, ticker, image, and provenance live off-chain in indexers and registries. Titled CAT attaches that record to the CAT's own identity. + +Metadata is **mutable by default**, updated by the title owner through an on-chain, auditable action, with no field forced permanent by the standard. An issuer who wants a field frozen locks it explicitly (a locking inner puzzle, or retiring the Title Singleton). + +The standard is **additive and opt-in**, applies only to CATs newly minted under the CHIP-40 `everything_with_singleton` TAIL, and introduces no consensus or CLVM changes, only the **Title Singleton** inner puzzle. It is complementary to a registry such as CATalog, which indexes arbitrary existing CATs. A single **`precision`** field, the number of decimal places (`0` indivisible, `3` the current default), fixes display across the fungibility spectrum, from indivisible trading cards and tickets to divisible stablecoins and commodities. + + +## Definitions + +Throughout this document: + +- **Title**: The on-chain record carried by a Titled CAT's Title Singleton (name, ticker, precision, content references, optional creator DID, optional royalty and revocation configuration, and supply commitments). Metadata is mutable by default. The Unit-to-title binding, the Unit layer configuration, and the supply mechanism are fixed and are not metadata (see *Mutability and issuer-optional locking*). +- **Title Singleton**: The singleton whose inner puzzle holds the title and authorizes minting and melting via the associated TAIL. Its launcher ID is the asset's permanent identifier. Spent only at mint, melt, mint-close, metadata update, and ownership transfer, never on ordinary Unit transfers. +- **Title ID**: A bech32m encoding of the launcher ID, prefix `tcat`. +- **TAIL Asset ID**: The tree hash of the CHIP-40 `everything_with_singleton` TAIL curried to the Title Singleton, the CAT asset ID identifying the token's Units. +- **Unit**: The base indivisible unit, one mojo of the CAT. Units of a title are interchangeable, and all holdings and supply counters are denominated in Units. +- **precision**: The number of decimal places used to display the asset. `precision = 0` is indivisible, one Unit shown as one whole token. `precision = 3` is the current ecosystem default. Mutable by default. +- **Holder**: A wallet or coin controlling one or more Units. +- **Issuer**: The creator of a Titled CAT. Its DID, when set, is recorded on the title. +- **Title Owner**: The current controller of the Title Singleton (initially the Issuer), authorized to mint, melt, close the mint, update metadata, prepend URIs, and transfer the title. +- **Total Minted / Circulating Supply**: `total_minted` is the monotonic cumulative count of Units ever minted (never falls, even on melt). Circulating Supply is the count currently in existence, equal to `total_minted` minus Units melted and observable on-chain. +- **Must, required, shall / Must not, shall not / Should, recommended / Should not, not recommended / May**: as in CHIP-0005. + + +## Motivation + +A CAT is identified on-chain by its TAIL and the asset ID derived from it: permanent and verifiable, but opaque about what the token is called, what it represents, or who issued it. All of that lives off-chain. NFT1 (CHIP-5) shows the alternative, committing an NFT's name, creator DID, and content reference into its own coin. **The problem Titled CAT solves is that, for an issuer minting a new asset, a CAT has no on-chain home for its metadata, supply discipline, or royalties bound to the asset itself.** + +### The metadata gap + +Because a CAT's metadata comes entirely from outside the coin, every option has a cost: + +- **Impersonation.** Anyone can mint a CAT reusing a known name and ticker, so users rely on off-chain allowlists to tell genuine from counterfeit. +- **Dependence on third parties.** To show a name or logo, a wallet must consult and trust an off-chain indexer or registry. The token cannot point to its own record. +- **Registration friction.** Registries such as [CATalog (CHIP-55)](https://github.com/Yakuhito/chips/blob/xchandles/CHIPs/chip-0055.md) record metadata on-chain but require a registration step and a fee per asset. For an issuer with many distinct assets this is a real, repeated cost. +- **No bound supply or royalties.** A registry describes a token but does not enforce a supply cap, a mint lifecycle, or a resale royalty. + +The same record serves the whole fungibility spectrum, from stablecoins and tokenized commodities to indivisible trading cards, tickets, and editioned collectibles, with a single `precision` field. "Fungible within a class, distinct across classes" is well established elsewhere (notably Ethereum's ERC-1155), and Titled CAT brings it to Chia. It is an issuance shape for new assets that opt in at mint, complementary to a registry such as CATalog, which indexes arbitrary existing CATs and which a title can be indexed and curated on top of. + +### Technical feasibility + +Titled CAT needs no protocol changes. The non-royalty core uses only deployed pieces: CAT2, the CHIP-40 TAIL (Final, in production for Revocable CATs), the CHIP-38 revocation layer (Final), and the Singleton and Offer standards. The one new puzzle is the Title Singleton inner puzzle. The optional royalty path additionally relies on the CHIP-56 Fee Layer (open, PR #194). Composition is entirely at the puzzle-hash level, so no consensus or VM change is required. + + +## Backwards Compatibility + +Titled CAT introduces no breaking changes. It does not modify Chia's consensus, the CLVM, or any existing primitive, and neither replaces nor deprecates CAT2. A wallet that does not implement Titled CAT recognition sees a Unit as an ordinary CAT with a recognizable TAIL pattern, showing a generic CAT and never a misleading name, but it does not read `precision` and falls back to its own default, so a title whose `precision` differs can display a different quantity than an aware wallet. That divergence and its mitigation are covered under *Precision and display* and Security. + +### Applicability + +A Unit's asset ID is the tree hash of the `everything_with_singleton` TAIL curried to the Title Singleton's launcher ID, so the standard applies **only to CATs newly minted under that TAIL**. It cannot be applied retroactively: the common single-issuance TAIL (`genesis_by_coin_id`, currently the default) derives its asset ID from a one-time genesis coin with no standing on-chain object, and an issued CAT's TAIL is fixed for life. Single-issuance, `genesis_by_puzzle_hash`, `everything_with_signature`, and `delegated_tail` CATs are out of scope and remain best served by a registry such as CATalog, which maps any asset ID to metadata regardless of TAIL. This also shapes the supply guarantee: `everything_with_singleton` lets the Title Singleton mint up to the current `edition_cap`, so supply is permanently bounded only once `mint_closed` is set, enforced by the inner puzzle rather than by the TAIL. + + +## Rationale + +### Title Singleton plus a CAT + +The design splits along Chia's coin-set model. Metadata and supply discipline live once, in the Title Singleton. Fungible holdings (who holds how many Units, and how they transfer) are what CAT2 already represents. The CHIP-40 `everything_with_singleton` TAIL binds the two by committing the launcher ID, so a Unit's Asset ID derives from it and only the Title Singleton can authorize a Unit's existence. The record is intrinsic, with no registry entry and no canonical-holder ambiguity. Because the singleton participates only in mint and melt, a title with no royalty layer has the same per-transfer cost as a bare CAT2. + +### Mutability and issuer-optional locking + +Metadata is mutable by default, allowing the title owner to update `name`, `ticker`, `precision`, `creator_did`, `edition_cap`, and content references through an `update_metadata` action recorded on-chain, so a field's history is auditable and a consumer can pin to a state and detect later change. Authenticity is a curation concern (verified-issuer lists, verifier attestations such as CATalog's overlay), as it already is for NFT1 collections and registry entries, rather than a property of a self-declared field. An issuer who needs a field permanent locks it: a locking inner puzzle that rejects `update_metadata` for chosen fields, or retiring the Title Singleton to a burn address once setup is complete. + +Three values are fixed mechanism: + +- **The Unit-to-title binding.** The launcher ID, and so the Asset ID, is fixed by construction. +- **The Unit layer configuration** (royalty and revocation parameters), because every Unit's stack is bound to it at mint and must stay uniform across the title, or the title would hold Units with different stacks under one Asset ID, reintroducing the layer-stripping and confusion attacks of CHIP-38. +- **The supply mechanism.** `total_minted` only rises and `mint_closed` only flips to true. + +### DID-rooted provenance + +A creator DID recorded on the title names its issuer, so curation can target verified DIDs rather than individual assets, as NFT1 collections are authenticated today. Because the field is mutable, the claim is curation-backed rather than self-proving, and an issuer who wants it permanent will need to lock it. + +### A single `precision` field instead of separate standards + +`precision` is the number of decimal places, the quantity CAT2's 1000-mojo convention encodes implicitly as three. Because metadata and divisibility are orthogonal, one standard serves an indivisible card (`precision = 0`) and a milligram-divisible gold token (`precision = 3`). A decimal count rather than a units-per-token value is fewer bytes, makes the power-of-ten relationship structural, and matches CATalog's `precision`, so a wallet has one notion of precision across both. `precision = 0` is mechanically indivisible, since a coin cannot be smaller than one mojo. Because it is mutable, a residual temporal risk remains, addressed under Security and *Offer integration*. + +### Optional fee layer and revocation layer + +Royalties and revocability are wanted by some titles and not others, so both are optional layers rather than built in, keeping the common case as cheap as a bare CAT2. Royalties are oriented to the editioned, indivisible case. Divisible fungibles generally want identity without a per-trade fee, so the Specification recommends they omit the Fee Layer (see *Royalty configuration*). + +### Relationship to registries (CATalog) + +A title and a plain CAT2 registered in a registry such as CATalog reproduce much of the same outcome but differ in where the record lives, what it costs, and what it enforces: + +- **Intrinsic versus looked-up.** A title is the CAT's TAIL binding, read by walking the one Title Singleton it commits to, the trustless full-node operation NFT and DID wallets already perform. The registry keeps metadata in a separate entry a wallet trusts the registry to serve. +- **Per-asset cost.** A 1,000-card game is 1,000 registrations and fees under a registry. Under Titled CAT each title is a singleton the issuer launches to control issuance, a saving only for issuers who want singleton-governed issuance anyway. An issuer who would otherwise mint a fixed-supply single-issuance CAT takes on a singleton launch they would not otherwise need. +- **Bound supply and royalties.** A title enforces a supply cap and mint lifecycle and binds royalty enforcement into every Unit. A registry describes but does not enforce these. + +The two are complementary. A registry indexes arbitrary existing CATs, curates, and powers search and verified-issuer lists, none of which a title attempts. A title is a trustless issuance substrate a registry can index on top of. For a token that needs none of singleton-governed issuance, supply discipline, or royalties, a plain CAT2 plus a registry remains the right tool. + +### Relationship to NFT1 + +Titled CAT is singleton-anchored and DID-rooted, so it is fair to ask whether it subsumes NFT1. **It does not.** Even the 1-of-1 case is not a drop-in NFT, since making a fungible Unit behave like a single item takes extra machinery (a `p2_singleton`-style check that the coin carries the right TAIL, that the edition cap is one, and that the amount is exactly one). The deeper difference is granularity. A title puts one singleton around a whole *class* and holds balances as fungible Units, spent only at supply changes. NFT1 puts a singleton around every *item*, spent on every transfer, which is what lets each item carry distinct metadata and a DID-bound owner. Because any two Units merge into one coin, there is no per-Unit slot for distinct artwork, a serial number, or an owner, so a collection of unique artworks belongs in NFT1, while 100 identical copies of a card are one title and 100 interchangeable Units. The boundary is individuation: once copies must be distinguished, the asset is in NFT1's domain. + +### Why scope this to the primitive alone? + +This CHIP defines the primitive only. Two companions should be developed separately: a **Titled CAT Off-Chain Metadata Format** (a JSON schema for the `metadata_uri_list` document, analogous to CHIP-7), and **Titled CAT Collections** (conventions for grouping titles into a family). + + +## Specification + +### Title Singleton + +Each Titled CAT shall be anchored by a singleton conforming to the Chia Singleton Standard. Its launcher ID is the asset's permanent identifier, and the **Title ID** is a bech32m encoding of that launcher ID with prefix `tcat`. The inner puzzle holds the title's metadata, enforces the supply mechanism, and is curried with the Unit layer configuration. Metadata fields are mutable through `update_metadata` unless the issuer has locked them. The layer configuration and supply-mechanism rules are fixed for the life of the title. The reference inner puzzle published with this CHIP is the canonical implementation. + +#### Identity (mutable metadata) + +- **`name`**: UTF-8 string, max 256 bytes. The asset's full display name. +- **`ticker`**: UTF-8 string, max 32 bytes. The asset's short symbol, not protocol-enforced as unique (a curation concern). +- **`description`** *(optional)*: UTF-8 string, max 1024 bytes. A short human-readable description. Longer prose belongs in the off-chain metadata document. +- **`precision`**: Unsigned integer, the number of decimal places. `precision = 0` is the indivisible, integer-displayed case. `precision = 3` is the current default. A divisible title MAY carry precision-aware `name_p`/`ticker_p` variants (see *Precision and display*). +- **`name_p`** *(optional, divisible titles)*: UTF-8 string, max 256 bytes. The precision-aware display name an aware wallet prefers, read together with `precision`. Falls back to `name` if absent. +- **`ticker_p`** *(optional, divisible titles)*: UTF-8 string, max 32 bytes. The precision-aware ticker an aware wallet prefers, read together with `precision`. Falls back to `ticker` if absent. +- **`creator_did`** *(optional)*: 32-byte launcher ID of the issuer's DID singleton. If omitted, provenance traces only to the original Issuer's puzzle hash. + +#### Content references (mutable hash plus URI list pairs) + +Each reference is a hash paired with a URI list, the hash committing the current bytes and the list locating them. A URI list may be prepended via `add_uri` without touching the hash, and the hash and list may be replaced together via `update_metadata` when content genuinely changes. Every change is on-chain, so a consumer needing permanence pins to a state or requires the field locked. Wallets should verify fetched content against the current hash before rendering. + +- **`data_hash`** / **`data_uri_list`**: the asset's primary content (card image or token logo). +- **`metadata_hash`** / **`metadata_uri_list`**: the off-chain metadata document (richer fields per a companion CHIP, and the home for extensible attributes such as a future Colored CAT `color`, needing no puzzle change). +- **`license_hash`** / **`license_uri_list`**: licensing and legal terms. + +#### Royalty configuration (fixed at creation, present only with the fee layer) + +Curried into the CHIP-56 Fee Layer that wraps each Unit, so they are set at creation and fixed for life, not mutable metadata (see *Mint-time stack binding*). Any wallet can reconstruct the expected Unit puzzle hash from the Title Singleton alone. + +- **`royalty_puzzle_hash`**: 32-byte puzzle hash royalties are directed to. +- **`royalty_basis_points`**: Unsigned integer, basis points (1 bps = 0.01%). Zero means no proportional royalty. No protocol cap. +- **`royalty_min_fee`**: Unsigned integer, minimum royalty in mojos of the quote asset. Zero disables the floor. +- **`allow_zero_price`**: Boolean. When `false`, even direct sends must declare a trade price and pay at least `royalty_min_fee`. When `true`, free transfers (gifting) are permitted. + +The Fee Layer suits the indivisible, editioned case (`precision = 0`), where a resale royalty is expected. Divisible titles SHOULD set `royalty_basis_points = 0` and SHOULD NOT set `allow_zero_price: false`, since a per-trade royalty interferes with the price discovery and arbitrage fungibles depend on (notably AMMs) and a per-transfer floor makes a circulating fungible impractical. A divisible Titled CAT therefore typically omits the Fee Layer. + +#### Revocability (fixed at creation, present only with the revocation layer) + +Like the royalty configuration, curried into each Unit at mint and fixed for life, not mutable metadata. + +- **`revocable`**: Boolean. When `true`, every Unit is wrapped in a CHIP-38 revocation layer between the Fee Layer (or the CAT layer, if none) and the holder's `p2`, and any Fee Layer is curried with `has_hidden_revoke_layer: true` and `allow_revoke_fee_bypass: true`. +- **`hidden_puzzle_hash`** *(present only if `revocable`)*: the hidden puzzle hash used by the revocation layer. + +#### Supply commitments + +- **`edition_cap`** *(optional)*: maximum on `total_minted` checked by `mint_units`. A mutable declared target, so a holder needing a credible permanent cap relies on `mint_closed` (or on the issuer having locked `edition_cap`), not the value alone. If omitted, supply is uncapped subject to `mint_closed`. +- **`total_minted`**: cumulative count of Units ever minted, strictly monotonic, enforced by the inner puzzle. Melts reduce Circulating Supply but not `total_minted`. +- **`mint_closed`**: Boolean, flipped `false` to `true` by the Title Owner and never back. This one-way transition, not the surrounding metadata, is the binding supply guarantee. + +Wallets and explorers derive a plain-language supply state from `edition_cap` and `mint_closed`, with counts shown in Units scaled by `precision`. + +#### Title Singleton inner puzzle actions + +- **`mint_units(count, target_puzzle_hash)`**: Authorizes the TAIL to mint `count` Units to `target_puzzle_hash` in the canonical Unit stack. It derives the canonical Unit puzzle hash from the title's fixed layer configuration and constrains issuance to coins bearing exactly that hash, so it cannot authorize a non-canonical stack (see *Mint-time stack binding*). Requires `mint_closed == false` and, if set, `total_minted + count <= edition_cap`. Updates `total_minted`. +- **`melt_units(count)`**: Authorizes the TAIL to melt `count` Units presented in the same bundle. Melting requires both Title Singleton authorization and control of the Units, so neither Holder nor Issuer alone can destroy a Unit (suiting issuer-driven redemption, a ticket melted at scan, while preventing unilateral burning). Does not decrease `total_minted`. Titles forbidding melt omit this action. +- **`close_mint()`**: Sets `mint_closed` true, permanently disabling minting. +- **`update_metadata(fields)`**: Sets one or more mutable fields (`name`, `ticker`, `description`, `name_p`, `ticker_p`, `precision`, `creator_did`, `edition_cap`, content hash/URI pairs) in the recreated singleton. A locking inner puzzle MAY reject it for specific fields. Does not touch the layer configuration or supply mechanism. +- **`add_uri(key, uri)`**: Prepends a URI to a list (`key` in {`data`, `metadata`, `license`}) without modifying the paired hash. +- **`transfer_title(new_owner_p2_puzzle_hash, optional_new_did)`**: Transfers ownership. With a `creator_did`, follows NFT1's DID-aware transfer pattern. + +### Unit layer stack + +Each Unit is one mojo of a CAT2 coin whose TAIL is `everything_with_singleton` (CHIP-40), curried to the Title Singleton via the singleton module hash and struct (committing launcher ID `L`). CHIP-40's `NONCE` is fixed to zero, since each title has its own singleton and does not need the one-singleton-many-CATs case, so the Unit's Asset ID is a deterministic function of `L` alone. Optional Fee and revocation layers, when declared, nest inside: + +``` +├ CAT outer layer (cat_v2) +├── TAIL (everything_with_singleton, bound to Title Singleton L) +├──── Fee Layer (CHIP-56, present only if royalties) +├────── Revocation Layer (CHIP-38, present only if revocable) +├──────── p2 puzzle (holder's standard transaction puzzle) +``` + +Undeclared layers are omitted, so a minimal title is CAT/TAIL/p2. The layer configuration is fixed at creation, so the expected stack is uniform across every Unit, and from the Title ID a wallet derives the expected stack and Unit puzzle hash to check a candidate coin. + +**Mint-time stack binding.** A Unit's Asset ID is the hash of the TAIL alone, identical whether or not the optional layers are present, since they live beneath the CAT layer. Nothing at the CAT layer distinguishes a canonical Unit from one with a missing or altered layer. Only `mint_units` can, by recomputing the canonical puzzle hash `H` from the fixed layer configuration and authorizing only created coins whose puzzle hash equals `H`. Because the TAIL delegates all issuance to the Title Singleton, a coin minted with any other stack is never authorized. This is why the layer configuration is fixed: if it could change, a title could hold Units with different stacks under one Asset ID, the exact condition CHIP-38 identifies as enabling layer stripping (combining a layered and unlayered coin of the same Asset ID) and the associated confusion scam. Keeping every Unit on one canonical stack makes royalties and revocation unstrippable. This derive-and-constrain step is the most security-critical code in the standard. + +**Persistence across transfers.** The Fee Layer, when present, must re-wrap itself on every spend, including ordinary transfers, and reject any spend that drops it. A Fee Layer that let a transfer settle to a bare `p2` would let a holder strip it and produce a royalty-free coin sharing the title's Asset ID (see Security). + +### Precision and display + +- **Indivisible (`precision = 0`).** One Unit is one whole token, displayed as an integer count. +- **Divisible (`precision = d`, `d >= 1`).** The Unit balance is displayed divided by `10^d`, with `d` decimal places. + +**Legacy-safe display for divisible titles.** A non-aware wallet applies its own default (3) instead of reading `precision`, and since it does not read the title at all, it sources `name`/`ticker` from an indexer keyed by asset ID, the same way it names any CAT today. For a divisible title this is made safe by a dual-name convention from CATalog: `name`/`ticker` are chosen to read correctly at precision 3, and the title MAY carry precision-aware variants `name_p`/`ticker_p` an aware wallet prefers. The benefit therefore reaches a legacy wallet through an indexer mirroring the title's legacy-safe `name`, as CATalog's own convention does, not through the coin directly. For example, `name`/`ticker` = "Base warped milliETH" / "wmilliETH.b" (the legacy view, in the smaller unit) and `name_p`/`ticker_p` = "Base warped ETH" / "wETH.b" with `precision = 6` (the aware view). The legacy wallet then shows the correct value in a smaller denomination, not a wrong number. This does not help the indivisible case, where five tokens show as `0.005` in a precision-3 wallet. That is the cost of mechanical indivisibility, so indivisible titles are safe only in aware tooling that refuses to render an unresolved amount. + +### Wallet recognition and display + +A wallet recognizes a CAT coin as a Titled CAT Unit when: +1. The outer layer is `cat_v2` +2. The TAIL is `everything_with_singleton` committing some launcher ID `L` +3. `L` resolves to a Title Singleton with a valid inner puzzle +4. The Unit's inner stack matches the stack derived from the title's fixed layer configuration + +When recognized, the wallet shall display the holding using the title's current `name`, `ticker`, and `precision`, verify `data_hash` against fetched content before rendering imagery, surface `creator_did` when present, flag recent metadata changes, and show royalty and revocation configuration before any Offer is accepted. + +### Discovering a title from a Unit + +A wallet reads a coin's Asset ID cheaply from its parent's puzzle reveal, but not `L`. The TAIL reveal appears on-chain only at mint and melt, so recovering `L` from a transferred coin can otherwise require walking the lineage back to a mint. This is a performance problem, not a trust one: because the Asset ID is a deterministic hash of `L`, any candidate `L` is self-verifying (recompute and check), so a memo, index, or peer can supply it untrusted. Recognition is therefore **pull-based**, resolved from data on coins a wallet already holds, never from a standing subscription: + +- **Hint on mint and transfer.** `mint_units` SHOULD hint each created coin with `L`, and an aware wallet SHOULD carry the hint forward on sends, keeping aware-to-aware transfers a direct lookup. This is convention, not puzzle-enforced. +- **Resolve once, cache.** A wallet needs `L` for an Asset ID only once and caches it permanently, since the cached value re-verifies. One-time per title, not per transfer. +- **Fallback.** With no hint (a non-aware sender), a wallet recovers `L` by lineage walk or index, both trustless, then caches. If `L` is unresolvable, the Unit degrades to a generic CAT. + +A wallet MAY subscribe to a Title Singleton it already holds for live updates. Wallets SHOULD NOT blanket-subscribe to a shared TAIL or hint hash to detect titledness across unknown CATs, since a widely-subscribed hash is an attractive dusting target and the pull-based path makes it unnecessary. + +### Offer integration + +Offers involving Units with a Fee Layer follow the CHIP-56 pattern unchanged: the maker's wallet computes the per-price royalty, includes settlement payments, injects `SetCatTradeContext(trade_nonce, trade_prices)` into each lock-leg spend, and the taker must include the royalty payments to complete the Offer. Units without a Fee Layer trade as ordinary CATs, and per-Offer royalty cost is bounded per title regardless of Unit quantity. Because `precision` is mutable, offer tooling SHOULD record it at offer creation and warn or refuse to settle on a change, so a redenomination cannot silently alter how an in-flight offer's amounts display. + +### RPC calls + +Wallets may expose: + +- **`titled_cat_create`**: Create a title and optionally mint an initial batch. Returns `title_id`, `title_singleton_coin_id`, `tail_asset_id`. +- **`titled_cat_mint` / `_melt` / `_transfer`**: Mint, melt, or transfer Units. Melt requires both Title Singleton authorization and control of the Units. +- **`titled_cat_update_metadata`**: Update mutable fields, failing for any the issuer has locked. +- **`titled_cat_close_mint` / `_add_uri`**: Close the mint, or prepend a URI. +- **`titled_cat_get_info` / `_get_balances`**: Read a title's on-chain state (including update history), or holdings aggregated per title. +- **`titled_cat_revoke`** *(revocable titles only)*: Revoke specified Units. + + +## Test Cases + +Detailed test cases ship with the reference implementation in `assets/chip-/tests/`. At minimum they cover title creation across the precision range and option combinations, derived Unit puzzle hashes matching on-chain Units per stack variant, mint and melt rules (edition cap, `close_mint`, dual-authorization melt), the supply invariants (monotonic `total_minted`, one-way `mint_closed`), ordinary transfers matching bare CAT2 cost, display across `precision` including the legacy-safe convention, `update_metadata` succeeding for the owner and being rejected for non-owners and locked fields, royalty-enforced Offer settlement, title transfer and URI prepend, a non-canonical-stack mint failing, revocable behavior, and safe degradation in a non-aware wallet. + + +## Reference Implementation + +The reference implementation will be provided in: + +- `chia-wallet-sdk/crates/chia-sdk-puzzles/puzzles/titled_cat_inner_puzzle.rue` will contain the Title Singleton inner puzzle, written in [Rue](https://github.com/Rigidity/rue) and compiled to CLVM. Following the CHIP-56 Fee Layer convention (`fee_layer_v1.rue`), the `chia-sdk-puzzles` crate owns the Rue source alongside the embedded compiled bytes and serialized tree hash. +- `chia-wallet-sdk` will contain the typed Rust bindings and the driver layer for Title Singleton construction/spending and Unit parsing/construction. +- `chia-blockchain/chia/wallet/titled_cat/` will contain the wallet integration, RPC handlers, and indexing. + +The inner puzzle composes with the existing Singleton, CAT2, CHIP-40 TAIL, and CHIP-38 layer (Chialisp) and the CHIP-56 Fee Layer (Rue). Because each layer curries the hash of the layer it wraps, the source language is immaterial, the same mixed-language stack already in production for Revocable Fee CATs. + + +## Security + +### Duplicate names and mutable metadata + +Titled CAT does not make names unique or decide which issuer is legitimate, and because metadata is mutable, `name`, `ticker`, image, and `creator_did` can change after holders acquire Units. Neither is a protocol guarantee. Authenticity is a curation concern, as for NFT1 collections and registry entries: wallets should surface `creator_did`, make recent changes visible, and rely on reputation overlays (verified DIDs, verifier attestations, allow and deny lists). A consumer needing a field never to change should require it locked (or the singleton retired), and may pin to a state to detect change. + +### Precision display divergence + +Putting `precision` on the title removes the cross-wallet ambiguity of CAT2's wallet-default convention, since every aware wallet agrees on a balance's meaning. Two residual risks remain. First, a non-aware wallet falls back to its default, so a differing `precision` displays a different amount. The divisible legacy-safe convention (see *Precision and display*) makes this a smaller denomination rather than a wrong number, and the indivisible case is safe only in aware tooling. Second, because `precision` is mutable, an owner could change it between a taker reading an Offer and accepting it. Offers settle in Units, so the value is never wrong, but the displayed reading could be manipulated. Offer tooling SHOULD pin `precision` at offer creation and warn or refuse on a change, and an issuer of a token that should never be redenominated SHOULD lock `precision`. + +### Title Singleton key compromise or loss + +An attacker controlling the Title Singleton key (or its DID) can mint up to `edition_cap` (or without bound if uncapped), update mutable metadata, prepend URIs, transfer ownership, and close the mint. They cannot alter the layer configuration, change the supply invariants, or revoke a non-revocable title's Units. The primary exposure is minting, bounded by `edition_cap`, `close_mint`, and key custody (a vault, multisig, or hardware wallet separate from the revocation key). For a closed mint, supply is safe even under compromise, while metadata could still change, which is why authenticity rests on curation and an issuer needing permanence locks the field. + +Key loss freezes the title (no mint, melt, close, update, or transfer) while existing Units keep transferring, since ordinary transfers never touch the singleton. For a closed mint this is benign and equivalent to deliberately retiring the singleton. For an open title it is a permanent loss of control, a further reason to close the mint once issuance is complete. + +### Creator DID over time + +A `creator_did`, even when locked, names a DID singleton that is not itself frozen and can be transferred, abandoned, or compromised. The binding proves which DID the title names, not who controls it today, as for an NFT1 collection. A wallet should treat a change to `creator_did` as significant and the DID as a provenance anchor whose reputation is tracked over time, not a permanent endorsement. + + +## Additional Assets + +The following additional assets are anticipated as the reference implementation progresses: + +- `assets/chip-/titled_cat_inner_puzzle.rue`: canonical inner puzzle source (Rue), to be added during Draft. +- `assets/chip-/titled_cat_inner_puzzle.clsp.hex` and its tree hash: compiled CLVM bytes mirroring the source, following the CHIP-56 Fee Layer convention. + + +## Appendix: CATalog field mapping + +A title maps onto a [CATalog (CHIP-55)](https://github.com/Yakuhito/chips/blob/xchandles/CHIPs/chip-0055.md) entry with no translation beyond the notes below, so a registry can index a title directly. Title fields with no CATalog equivalent are title-only and are carried as extensions or dropped by an indexer. + +| Title field | CATalog key | +|:--|:--| +| `name` | `n` | +| `ticker` | `t` | +| `description` | `d` | +| `precision` | `p` | +| `name_p` | `pn` | +| `ticker_p` | `pt` | +| `data_hash` / `data_uri_list` | `h` / `u` | +| `metadata_hash` / `metadata_uri_list` | `mh` / `mu` | +| `license_hash` / `license_uri_list` | `lh` / `lu` | +| `hidden_puzzle_hash` | `hph` | +| `creator_did`, royalty config, supply commitments | (no equivalent, title-only) | + +Titled CAT keeps NFT1's `data_hash`/`data_uri_list` for the primary image, which map to CATalog's `image_hash` (`h`) and `image_uris` (`u`). The precision-aware `name_p`/`ticker_p` follow CATalog's `p`-prefixed convention (`pn`/`pt`). Keys reflect the CHIP-55 draft and should be reconciled against it at finalization. + + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).