CHIP-0055: CATalog

CHIPs/chip-0055.md

@@ -0,0 +1,91 @@
+CHIP Number   | 0055
+:-------------|:----
+Title         | CATalog - A shared on-chain CAT database
+Description   | A decentralized application that allows anyone to add permanent entries that resolve to an NFT to an append-only database.
+Author        | [yakuhito](https://github.com/yakuhito)
+Editor        | [Dan Perry](https://github.com/danieljperry)
+Comments-URI  | [CHIPs repo, PR #192](https://github.com/Chia-Network/chips/pull/192)
+Status        | Draft
+Category      | Informational
+Sub-Category  | Rue
+Created       | 2026-02-23
+Requires      | [CHIP-0050: Action Layer and Slots](https://github.com/Chia-Network/chips/pull/165); [CHIP-0005: NFT1 Standard](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0005.md)
+
+## Abstract
+This CHIP proposes an on-chain registry that works as a shared database for CAT details. CAT issuers can create entries by proving they are the first to know about the CAT’s existence and paying a small anti-spam fee. In return, an NFT is minted that can be used to control attributes such as name, image, and precision. Interface owners can verify that the CAT details can be used on their application through datastores. By putting all data on-chain, these interactions are publicly available and auditable.
+
+## Motivation
+The Chia ecosystem is currently incredibly fragmented when it comes to CAT details. Some wallets come with a small set of hardcoded asset id/name pairs that rarely changes. Users wanting to add more tokens have to manually add the details to these wallets. Other wallets, as well as most websites, fetch live CAT details from external APIs. Issuers often have to register the same details on multiple sites, each requiring different (and sometimes no) ways to prove CAT ownership. APIs have inconsistent response formats, and some frequently undergo breaking changes. Updates - such as name or image changes - are often challenging for issuers as well, as they have to coordinate with API operators. CATalog aims to solve this issue by providing a central, shared database that CAT issuers, verifiers, and data consumers can reference, uniting a currently fragmented but essential part of the Chia ecosystem.
+
+## Backwards Compatibility
+This proposal includes a new set of puzzles that collectively make up a dApp. CATalog is **not** compatible with previous CAT details APIs. However, effort will be made to migrate all existing data to CATalog during launch, as well as to give current CAT issuers control over their data.
+
+
+## Rationale
+The idea of a CAT registry was first introduced [here](https://medium.com/@fizpawiz/decentralized-names-on-the-chia-public-blockchain-823adb6cc2af). There are six main changes from the initial idea.
+
+First, uniqueness is no longer enforced via a Merkle tree. Instead, slots and a doubly-linked list are used, as explained in [this post](https://blog.fireacademy.io/p/solving-the-problem-of-uniqueness). The new approach scales extremely well, allowing registration in a registry with millions of entries cost the same as registration in a freshly-minted registry.
+
+Second, the CATalog registry only enforces the uniqueness of asset ids (TAIL hashes), which is the information used to create an entry. Registering by proving a user is the first to know about the TAIL allows the registry to support arbitrary TAILs (including multi-issuance ones), unlike the original design. Other details (e.g., name/image) are part of a special NFT representing the CAT’s editable entry, which is owned by the issuer. Validating these details is delegated to verifiers as explained below.
+
+Third, it’s expected that different interfaces, such as wallets, DEXes, and marketplaces, will have different listing criteria for CATs. Moreover, while names/tickers should be unique, they are a product of community consensus, not puzzle enforcement. Verifiers constitute an active, dynamic layer on top of CATalog - they curate CATs as the ecosystem evolves. This process is done on-chain, where other data consumers such as wallets with no associated validators can observe it and act accordingly.
+
+Fourth, special NFTs contain all the data related to the CAT except the asset id (which cannot be updated using the NFT - a new registration would be needed in that case). These NFTs store CAT information in metadata as described below. They also have a new owner-can-update-anything metadata updater, allowing issuers to add or remove fields should a new metadata schema be developed. An NFT describing a CAT may have the following fields:
+
+| Field | Description |
+| :--- | :--- |
+| ticker ('t') | The CAT’s ticker (e.g., “SBX”) |
+| name ('n') | The CAT’s (full) name (e.g., SpaceBucks) |
+| description ('d') | A description for the CAT (e.g., “Galactic money for a galactic galaxy.”) |
+| precision ('p') | The number of decimals this CAT has (default 3, corresponding to the current ecosystem ‘standard’ of 10^3 = 1000 mojos making up one CAT unit). |
+| hidden_puzzle_hash ('hph') | The hidden puzzle hash of the CAT’s revocation layer. The default value is none, signaling the CAT does *not* have a revocation layer. |
+| image_uris ('u') | List of URIs for the CAT’s display image. (see CHIP-0005 for more details) |
+| image_hash ('h') | Hash of the CAT’s display image. (see CHIP-0005 for more details) |
+| metadata_uris ('mu') | List of URIs pointing to a ‘fallback’ metadata JSON. The JSON may follow the NFT specification for compatibility reasons. If ticker/name/description are not specified on-chain, the values of the respective fields in the root of the metadata JSON may be used. (see CHIP-0005 for more details) |
+| metadata_hash ('mh') | The hash of the metadata JSON string. (see CHIP-0005 for more details) |
+| license_uris ('lu') | List of URIs pointing to a license connected to the CAT, either terms of use, display image licensing, or other legal information. (see CHIP-0005 for more details) |
+| license_hash ('lh') | Hash of the document returned by the license URIs. (see CHIP-0005 for more details) |
+
+Additionally, a wallet or website supporting custom precision may first look for the field with the key ‘p’ + non_precision_key. For example, a wallet may first check for ‘pt’ to resolve the ticker of an asset with a precision other than 3, and fall back to ‘t’ if such item is not provided. This helps issuers specify special display details for tokens that have custom precisions. A particular example is ‘Base warped milliETH/wmilliETH.b’, which may set the name and ticker to ‘Base warped ETH/wETH.b’ for wallets that support custom precisions.
+
+Fifth, CATalog fees will be taken in wUSDC.b instead of XCH. As the original article pointed out, registration fees are a necessary addition on top of network fees in order to deter spam. However, given the volatility of XCH price and its loose correlation with block rewards, wUSDC.b - the main stablecoin currently in use on Chia - will be used instead. The initial price for registering a new CAT will be 5 wUSDC.b. Verifiers may also ask for additional fees for issuing verifications, enabling a second layer of defense that allows the main registry fee to be low while the overall CATalog system is still able to deter spam. The price for a registration, as well as the payment CAT, may be updated by a 6-of-10 multisig controlled by [warp.green validators](https://docs.warp.green/#who-are-the-validators). This choice was made to allow some flexibility for future situations, such as an eventual Chia-native stablecoin. The multisig setup does not add any trust assumptions, as a 6-of-10 supermajority is also trusted by the warp.green protocol to relay messages, which is the functionality that keeps wUSDC.b’s peg.
+
+Sixth, verifiers may coordinate through DataLayer stores, specifically CHIP-0035 ones with oracle functionality enabled. Generally, the datastore items are `(key . value)`, with two possible items:
+ * **Verified CATs** with a `key` of `‘v’` and a value of ‘(asset_id mh . overrides)’. These entries are sorted by `asset_id` in the tree, allowing applications to also prove a certain asset id was not approved by a verifier. `overrides` is an optional (i.e., may be empty) list of `(attribute . new_value)`, where `attribute` is the NFT metadata attribute key that the verifier wishes to override with `new_value`, while `mh` represents the metadata hash (with ‘u/mu/lu’ keys removed) that the verifier approves of.
+ * **Trusted sub-verifiers** with a `key` of `’t’` and a value equaling the singleton launcher id of the trusted sub-verifier. A sub-verifier may verify additional CATs, but the main verifier’s overrides are always used over any of the sub-verifiers’.
+
+Note that, unlike XCHandles, CATalog registrations are permanent. This is because the unique keys - asset ids instead of handles - are not a rare commodity. Moreover, CATs may still be relevant long after issuers stop their activity (and thus are able to pay renewal fees).
+
+
+## Specification
+
+The XCHandles registry uses the [action layer and slots](https://github.com/Chia-Network/chips/pull/165) framework. The possible actions are defined in [this repository](https://github.com/Yakuhito/slot-machine/tree/master) and allow users interacting with the registry to:
+ - **Register** a new CAT
+ - **Refund** an invalid registration attempt
+
+An additional action is used to allow the multisig mentioned above to change the registration price and payment CAT. More information about the problem of uniqueness can be found [here](https://blog.fireacademy.io/p/uniqueness-on-chain), [here](https://blog.fireacademy.io/p/solving-the-problem-of-uniqueness), and [here](https://blog.fireacademy.io/p/announcing-catalog-and-xchandles). More technical details on CATalog’s inner workings can be found in the official documentation, available on [this site](https://docs.catalog.cat/). 
+
+The premine - CATs that will be pre-registered before launch, with control given to their issuers - will be provided at least one week before launch.
+
+## Test Cases
+
+A series of tests verifying the behavior of the dApp and its components can be found in chia-wallet-sdk. Each action and refund case is tested at least once.
+
+## Reference Implementation
+The Rue and equivalent Chialisp code, along with a CLI that can be used to interact with the CATalog registry through Coinset and Sage, can be found [here](https://github.com/Yakuhito/slot-machine). Drivers and tests have already been integrated into chia-wallet-sdk under the ‘action-layer’ feature.
+
+## Security
+The main risk of this standard is the puzzle risk. Multiple members of the Chia community have reviewed the puzzles powering CATalog. 
+
+Multisig and frontrunning related concerns are mentioned in CHIP-0054.
+
+Another concern is that CAT issuers may not register a CAT with CATalog before issuing it. A malicious attacker may then register the asset id with CATalog to get ownership of the issuer’s entry. In this scenario, the issuer would have to contact verifiers and coordinate overrides of the CAT’s attributes to ensure it is properly displayed.
+
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+
+## Acknowledgements
+
+Special thanks to Rigidity, stl, and Andreas for providing feedback on early designs of the dApp. The idea for a format that allows precision-compatible wallets to display assets differently originated in a private Chia Network, Inc. meeting. Many thanks to BramV for reviewing the second to last, as well as the final version of the dApps in Chialisp or/and Rue. Lastly, thanks to Ken for initially introducing the idea that a handle-like registry could be used to create a shared database of CAT details.