ARC-89: ASA Metadata Registry

ARCs/arc-0089.md

@@ -0,0 +1,189 @@
+---
+arc: 89
+title: ASA Metadata Registry
+description: Singleton Application providing ASA metadata via Algod API
+author: Cosimo Bassi (@cusma)
+discussions-to: https://github.com/algorandfoundation/ARCs/issues/...
+status: Draft
+type: Standards Track
+category: Interface
+sub-category: Asa
+created: 2025-09-22
+requires: 3, 4, 56, 82
+---
+
+## Abstract
+
+This ARC defines the interface and the implementation of a singleton Application
+that provides Algorand Standard Assets metadata through the Algod API.
+
+## Motivation
+
+Algorand Standard Assets (ASA) lack a dedicated metadata field on the Algorand ledger
+for storing additional asset information.
+
+Although it's generally not advisable to use Algorand as a distributed storage system
+for data that could easily reside elsewhere, the absence of a native metadata store
+on the ledger has led the ecosystem to adopt less-than-ideal solutions for discovering
+and fetching off-chain asset data, involving the usage of an Indexer or external
+infrastructure (such as IPFS), or hacking on the ASA RBAC roles to get asset metadata
+mutability.
+
+While storing huge data, such as images, off-chain is a practical (and recommended)
+approach, smaller, more pertinent data should not incur the expenses, availability
+challenges, and latency typically associated with external infrastructure.
+
+This ARC establishes a standardized URI within the ASA URL field to solve this simple
+use case: _directly retrieving ASA metadata using the Algod API_.
+
+## Specification
+
+The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**",
+"**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**"
+in this document are to be interpreted as described in <a href="https://datatracker.ietf.org/doc/html/rfc2119">RFC 2119</a>.
+
+> Notes like this are non-normative.
+
+### ASA Metadata Registry
+
+The ASA Metadata Registry is an _immutable singleton Application_ that stores Asset
+Metadata.
+
+#### ASA Metadata Box
+
+The Asset Metadata are stored in a dedicated Box, called _Asset Metadata Box_.
+
+The Asset Metadata Box Name **MUST** be equal to the _Asset ID_ (`uint64`).
+
+The Asset Metadata **MUST** fit into a single Box.
+
+#### [ARC-56](./arc-0056.md) AppSpec
+
+- `arc89_upload_metadata(asset_id:	unit64, ...tbd)`
+- `arc89_delete_metadata(asset_id:	unit64, ...tbd)`
+- `...`
+
+##### Upload Metadata
+
+The authorization to upload (and update) the Asset Metadata **MUST** be restricted
+to the Asset Manager.
+
+The Asset URL (`au`) **MUST** conform to this specification (see the [Asset URL section](#asset-url)).
+
+The MBR for the Asset Metadata Box **MUST** be provided upon the Asset Metadata upload
+(and update).
+
+The Asset Metadata **MUST** be stored as the Asset Metadata Box Value.
+
+##### Delete Metadata
+
+The authorization to delete the Asset Metadata:
+
+- **MUST** be restricted to the Asset Manager if the ASA exists;
+
+- **MUST NOT** be restricted otherwise.
+
+The MBR of the Asset Metadata Box:
+
+- **MUST** be returned to the Asset Manager if the ASA exists;
+
+- **MUST** be split among the caller (10%) and the Fee Sink (90%) otherwise.
+
+The Asset Metadata Box **MUST** be deleted.
+
+### Asset URL
+
+The _Asset URL_ (`au`) field is used as a URI pointing to the Asset Metadata on the
+Algorand ledger.
+
+The _Asset URL_ (`au`) **MUST** be the (partial) [ARC-82](./arc-0082.md) URI:
+
+`algorand://app/<singleton_arc89_app_id>?box=`
+
+The clients **SHALL** interpret the (complete) [ARC-82](./arc-0082.md) URI with the
+`boxparam` filled with the Asset Metadata Box Name, equal to the _Asset ID_ (encoded
+as `base64url`).
+
+> The complete Asset Metadata [ARC-82](./arc-0082.md) URI for the ASA `12345` would
+> be interpreted as:
+>
+> `algorand://app/<singleton_arc89_app_id>?box=MDk=`
+
+### [ARC-3](./arc-0003.md) Compliance
+
+The compliance with [ARC-3](./arc-0003.md) is **OPTIONAL** but **RECOMMENDED**.
+
+If the ASA conforms to [ARC-3](./arc-0003.md), then:
+
+- The ASA **MUST** comply with the [_ARC-3 ASA Parameters Conventions_](./arc-0003.md#asa-parameters-conventions)
+for the _Asset Name_ (`an`) and the _Asset URL_ (`au`) fields.
+
+  - The **RECOMMENDED** _Asset URL_ (`au`) for an [ARC-3](./arc-0003.md) ASA is:
+  `algorand://app/<singleton_arc89_app_id>?box=#arc3`
+
+- The Asset Metadata **MUST** comply with the [_ARC-3 JSON Metadata File Schema_](./arc-0003.md#json-metadata-file-schema).
+
+- If the Asset Metadata are _immutable_, the ASA **MUST** comply with the [_ARC-3
+ASA Parameters Conventions_](./arc-0003.md#asa-parameters-conventions) for the _Asset
+Metadata Hash_ (`an`) field.
+
+## Rationale
+
+The singleton ASA Metadata Registry Application and the standard Asset Metadata [ARC-82](./arc-0082.md)
+URI are a simple and efficient way to provide the Asset Metadata to the clients directly
+through the <a href="https://dev.algorand.co/reference/rest-api/algod/">Algod API</a>,
+without the need of an additional infrastructure.
+
+The compliance with [ARC-3](./arc-0003.md) ensures interoperability with existing
+infrastructures, such as explorers and wallets, and other applications.
+
+The deletion of (abandoned) Asset Metadata related to destroyed ASAs is incentivized
+by returning a small fraction (10%) of the Asset Metadata Box MBR to the caller,
+while the remainder (90%) is donated to the Fee Sink.
+
+## Backwards Compatibility
+
+Backwards compatibility for existing ASA Metadata is not possible, since the _Asset
+URL_ (`au`) field is immutable.
+
+## Reference Implementation
+
+### Usage
+
+The clients use the Algod API endpoint to retrieve the Asset Metadata.
+
+> A minimal Python SDK example is provided with the [reference implementation]().
+
+#### Example: Get [ARC-3](./arc-0003.md) Asset Metadata
+
+> Given the ASA with the _Asset ID_ `12345`, the client:
+>
+> 1. Calls the Algod API <a href="https://dev.algorand.co/reference/rest-api/algod/#getassetbyid">GetAssetByID</a>
+> endpoint to get the _Asset URL_ field (`url`) from the response and drops the
+> `#arc3` suffix (if present), obtaining: `algorand://app/<singleton_arc89_app_id>?box=`;
+>
+> 1. Extracts the _Application ID_ (`<singleton_arc89_app_id>`) and encodes the _Asset
+> ID_ as Asset Metadata Box Name (`<asset_id>`);
+>
+> 1. Calls the Algod API <a href="https://dev.algorand.co/reference/rest-api/algod/#getapplicationboxbyname">GetApplicationBoxByName</a>
+> endpoint to get the content of the _Asset Metadata Box_ from the response:
+>
+> ```shell
+> curl -X GET http://localhost/v2/applications/<singleton_arc89_app_id>/box?name=<asset_id> \
+>  -H 'Accept: application/json' \
+>  -H 'X-Algo-API-Token: API_KEY'
+> ```
+>
+> The `value` field of the response contains the Asset [ARC-3](./arc-0003.md) JSON
+> Metadata.
+
+## Security Considerations
+
+The authorization over the Asset Metadata update and delete is granted to the Asset
+Manager to preserve the ASA trust model. The authorization is not granted to the
+Asset Creator, since this role could be performed programmatically by Applications
+and is not supposed to be the long-lasting maintainer of the ASA.
+
+## Copyright
+
+Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.