Algorand MCP

--- arc: 69 title: ASA Parameters Conventions, Digital Media description: Alternatives conventions for ASAs containing digital media. author: Chris Antaki (@ChrisAntaki), AlgoKittens (@algokittens), TommyAlex79 (@TommyAlex79) discussions-to: https://github.com/algorandfoundation/ARCs/issues/64 status: Final type: Standards Track category: ARC sub-category: Asa created: 2021-08-07 --- # Community Algorand Standard Asset Parameters Conventions for Digital Media Tokens We introduce community conventions for the parameters of Algorand Standard Assets (ASAs) containing digital media. ## Abstract The goal of these conventions is to make it simpler to display the properties of a given ASA. This ARC differs from [ARC-3](./arc-0003.md) by focusing on optimization for fetching of digital media, as well as the use of onchain metadata. Furthermore, since asset configuration transactions are used to store the metadata, this ARC can be applied to existing ASAs. While mutability helps with backwards compatibility and other use cases, like leveling up an RPG character, some use cases call for immutability. In these cases, the ASA manager MAY remove the manager address, after which point the Algorand network won't allow anyone to send asset configuration transactions for the ASA. This effectively makes the latest valid [ARC-69](./arc-0069.md) metadata immutable. ## Specification The key words "**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://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>. An ARC-69 ASA has an associated JSON Metadata file, formatted as specified below, that is stored on-chain in the note field of the most recent asset configuration transaction (that contains a note field with a valid ARC-69 JSON metadata). ### ASA Parameters Conventions The ASA parameters should follow the following conventions: * *Unit Name* (`un`): no restriction. * *Asset Name* (`an`): no restriction. * *Asset URL* (`au`): a URI pointing to digital media file. This URI: * **SHOULD** be persistent. * **SHOULD** link to a file small enough to fetch quickly in a gallery view. * **MUST** follow <a href="https://www.ietf.org/rfc/rfc3986.txt">RFC-3986</a> and **MUST NOT** contain any whitespace character. * **SHOULD** specify media type with `#` fragment identifier at end of URL. This format **MUST** follow: `#i` for images, `#v` for videos, `#a` for audio, `#p` for PDF, or `#h` for HTML/interactive digital media. If unspecified, assume Image. * **SHOULD** use one of the following URI schemes (for compatibility and security): *https* and *ipfs*: * When the file is stored on IPFS, the `ipfs://...` URI **SHOULD** be used. IPFS Gateway URI (such as `https://ipfs.io/ipfs/...`) **SHOULD NOT** be used. * **SHOULD NOT** use the following URI scheme: *http* (due to security concerns). * *Asset Metadata Hash* (`am`): the SHA-256 digest of the full resolution media file as a 32-byte string (as defined in <a href="https://doi.org/10.6028/NIST.FIPS.180-4">NIST FIPS 180-4</a> ) * **OPTIONAL** * *Freeze Address* (`f`): * **SHOULD** be empty, unless needed for royalties or other use cases * *Clawback Address* (`c`): * **SHOULD** be empty, unless needed for royalties or other use cases There are no requirements regarding the manager account of the ASA, or the reserve account. However, if immutability is required the manager address **MUST** be removed. Furthermore, the manager address, if present, **SHOULD** be under the control of the ASA creator, as the manager address can unilaterally change the metadata. Some advanced use cases **MAY** use a logicsig as ASA manager, if the logicsig only allows to set the note fields by the ASA creator. ### JSON Metadata File Schema ```json { "title": "Token Metadata", "type": "object", "properties": { "standard": { "type": "string", "value": "arc69", "description": "(Required) Describes the standard used." }, "description": { "type": "string", "description": "Describes the asset to which this token represents." }, "external_url": { "type": "string", "description": "A URI pointing to an external website. Borrowed from Open Sea's metadata format (https://docs.opensea.io/docs/metadata-standards)." }, "media_url": { "type": "string", "description": "A URI pointing to a high resolution version of the asset's media." }, "properties": { "type": "object", "description": "Properties following the EIP-1155 'simple properties' format. (https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md#erc-1155-metadata-uri-json-schema)" }, "mime_type": { "type": "string", "description": "Describes the MIME type of the ASA's URL (`au` field)." }, "attributes": { "type": "array", "description": "(Deprecated. New NFTs should define attributes with the simple `properties` object. Marketplaces should support both the `properties` object and the `attributes` array). The `attributes` array follows Open Sea's format: https://docs.opensea.io/docs/metadata-standards#attributes" } }, "required":[ "standard" ] } ``` The `standard` field is **REQUIRED** and **MUST** equal `arc69`. All other fields are **OPTIONAL**. If provided, the other fields **MUST** match the description in the JSON schema. The URI field (`external_url`) is defined similarly to the Asset URL parameter `au`. However, contrary to the Asset URL, the `external_url` does not need to link to the digital media file. #### MIME Type In addition to specifying a data type in the ASA's URL (`au` field) with a URI fragment (ex: `#v` for video), the JSON Metadata schema also allows indication of the URL's MIME type (ex: `video/mp4`) via the `mime_type` field. #### Examples ##### Basic Example An example of an ARC-69 JSON Metadata file for a song follows. The properties array proposes some **SUGGESTED** formatting for token-specific display properties and metadata. ```json { "standard": "arc69", "description": "arc69 theme song", "external_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "mime_type": "video/mp4", "properties": { "Bass":"Groovy", "Vibes":"Funky", "Overall":"Good stuff" } } ``` An example of possible ASA parameters would be: * *Asset Name*: `ARC-69 theme song` for example. * *Unit Name*: `69TS` for example. * *Asset URL*: `ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT#v` * *Metadata Hash*: the 32 bytes of the SHA-256 digest of the high resolution media file. * *Total Number of Units*: 1 * *Number of Digits after the Decimal Point*: 0 #### Mutability ##### Rendering Clients **SHOULD** render an ASA's latest ARC-69 metadata. Clients **MAY** render an ASA's previous ARC-69 metadata for changelogs or other historical features. ##### Updating ARC-69 metadata If an ASA has a manager address, then the manager **MAY** update an ASA's ARC-69 metadata. To do so, the manager sends a new `acfg` transaction with the entire metadata represented as JSON in the transaction's `note` field. ##### Making ARC-69 metadata immutable Managers MAY make an ASA's ARC-69 immutable. To do so, they MUST remove the ASA's manager address with an `acfg` transaction. ##### ARC-69 attribute deprecation The initial version of ARC-69 followed the Open Sea attributes format https://docs.opensea.io/docs/metadata-standards#attributes. As illustrated below: ``` "attributes": { "type": "array", "description": "Attributes following Open Sea's attributes format (https://docs.opensea.io/docs/metadata-standards#attributes)." } ``` This format is now deprecated. New NFTs **SHOULD** use the simple `properties` format, since it significantly reduces the metadata size. To be fully compliant with the ARC-69 standard, both the `properties` object and the `attributes` array **SHOULD** be supported. ## Rationale These conventions take inspiration from <a href="https://docs.opensea.io/docs/metadata-standards">Open Sea's metadata standards</a> and <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md#erc-1155-metadata-uri-json-schema">EIP-1155</a> to facilitate interoperobility. The main differences are highlighted below: * Asset Name, Unit Name, and URL are specified in the ASA parameters. This allows applications to efficiently display meaningful information, even if they aren't aware of ARC-69 metadata. * MIME types help clients more effectively fetch and render media. * All asset metadata is stored onchain. * Metadata can be either mutable or immutable. ## Security Considerations None. ## Copyright Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.