diff --git a/ARCs/arc-0040.md b/ARCs/arc-0040.md new file mode 100644 index 000000000..27ef75ab1 --- /dev/null +++ b/ARCs/arc-0040.md @@ -0,0 +1,399 @@ +--- +arc: 40 +title: Mutable Asset Set Schema & Validation +description: A Standardized Metadata Schema and Decentralized Verification Workflow for Mutable Sets of Assets (including NFT Collections) +author: Mark Crae (@dolphinkitty) +discussions-to: https://github.com/algorandfoundation/ARCs/issues/280 +status: Draft +type: Standards Track +category: ARC +created: 2024-02-20 +--- + + +## Abstract + +This ARC introduces a standardized schema and decentralized (platform-agnostic) workflows for defining, configuring, and validating metadata for sets of associated assets ("Asset Sets"), such as NFT Collections. The proposal provides a modular framework enabling bidirectional linkage between the metadata of a parent Asset Set ASA, Child Assets, and Contributors (e.g. Creators), for trustless proof of control and attribution. Asset Set ASAs provide a verifiable source of truth for any Asset Set. + +By fully leveraging Algorand's capabilities, such as the mutability of [ARC-19](./arc-0019.md) and the asset opt-in process, the proposal ensures the integrity of Asset Set metadata, thereby enhancing trust, consistency, and interoperability across the Algorand ecosystem. + +The proposal includes the following components: +1. Standardized JSON schema for Asset Set metadata +1. Workflows for encoding bidirectional linkage between: + - Asset Sets and Child Assets + - Asset Sets and Contributor entities (Addresses or Assets) +1. Validation rule sets conditional on Asset Set type + +## Specification + +The specification's schema, configuration workflows, and validation rules are designed to enable modular implementation, allowing different projects to adopt subsets of the framework according to their needs. The ARC supports the following use cases: + +- Verified NFT Collections +- Verified and unverified asset groups + +### 1: Standardized Asset Set Metadata Schema + +#### Key Terminology + +- **Asset Set** : A group of associated entities such as: NFTs, Tokens, other Asset Sets +- **Asset Set Metadata** : JSON file defining properties of an Asset Set +- **Asset Set ASA** : A mutable (ARC-19) asset, linked to Asset Set metadata on IPFS +- **Child Assets** : Constituent assets within a parent Asset Set +- **Contributor** : An entity that contributes to an Asset Set (e.g. Creator, Contributor, Artist) +- **Contributor Asset** : An asset (ARC-19 or [ARC-3](./arc-0003.md)) linked to an Asset Set, that is distributed to Contributor Addresses to verify proof of contribution + +#### Core Schema Parameter + +`asset_type` : Identifies the type of Asset Set, e.g.: + +- `asset_type: "collection"` : A verified NFT Collection +- `asset_type: "group"` : An unverified group of assets + +#### Full Asset Set Metadata Schema + +| Field | Schema | Description | Required | +| ---- | ---- | ---- | ----| +| `asset_type` | string | Type of the asset, e.g. "collection", "group" | Yes | +| `schema_version` | string | Version of the metadata schema | Yes | +| `version_history` | array | History of schema changes | Yes | +| `timestamp` | array | Timestamp of each version | Yes | +| `version` | string | Version number at the timestamp | Yes | +| `set_name` | string | Name of the Asset set | Yes | +| `set_description` | string | Description of the Asset set | No | +| `set_image` | string | URL to an image representing the Asset Set | No | +| `set_properties` | array | Properties of the Asset Set (key-value pairs) | No | +| `set_links` | array | URLs related to the Asset Set | No | +| `license` | string | Legal terms of the Asset Set | No | +| `royalties` | integer | Royalty % (0-100) requested from sales | No | +| `assets` | array | Array of Child Asset IDs | Yes | +| `contributors` | array | Array of objects linked to a contributor | No | +| `contributor_address` | string | Wallet address of a contributor | No | +| `contributor_name` | string | Name of a contributor | No | +| `contributor_role` | string | Contributor's role e.g. "creator", "artist" | No | +| `contributor_link` | string | Contributor's website URL | No | +| `contributor_assets` | array | Array of Contributor Asset IDs | No | + +#### Child Asset and Contributor Asset Metadata + +The `asset_set` parameter is included within Child Asset and Contributor Asset metadata JSONs to associate these entities with a parent Asset Set + +| Field | Schema | Description | Required | +| ---- | ---- | ---- | ----| +| `asset_set` | string | Parent Asset Set ASA ID | Conditional | + +"Required" is conditional on Child Asset / Contributor Asset properties +See section 3: Verification Conditions for Asset Set Information + +#### Asset Set Schema Instance + +```json +{ + "asset_type": "collection", + "schema_version": "n.n.n", + "version_history": [ + { + "timestamp": "YYYY-MM-DDTHH:MM:SSZ", + "version": "n.n.n" + }, + { + "timestamp": "YYYY-MM-DDTHH:MM:SSZ", + "version": "n.n.n" + } + ], + + "set_name": "Collection name", + "set_description": "Description of the collection", + "set_image": "placeholder_url", + "set_properties": { + "key1": "value1", + "key2": "value2" + }, + "set_links": [ + "link1", + "link2" +], + + "license": "License / IP details", + "royalties": 15, + + "assets": [ + "123...", + "456..." +], + + "contributors": [ + { + "contributor_address": "XZ45......", + "contributor_name": "Contributor's name", + "contributor_role": "Creator", + "contributor_link": "placeholder_url" + }, + { + "contributor_address": "XZ45......", + "contributor_name": "Contributor's name", + "contributor_role": "Creator", + "contributor_link": "placeholder_url" + } + ], + + "contributor_assets": [ + "asset_id_1", + "asset_id_2" + ], +} +``` + +### 2: Configuration Workflows for Asset Set Metadata + +#### Bidirectional Metadata Linkage +A core feature of this ARC are workflows designed to establish a bidirectional link connecting the metadata of an Asset Set with any associated entities (e.g. Child Assets, Contributor Addresses, and Contributor Assets), allowing them to reciprocally reference each other. Linkage is established during the minting / configuration process, providing verifiable proof of control or association between entities – independently validating the integrity of the Asset Set without the need for trusted intermediaries. + +#### Configuration Workflows + +Below are the 3 workflows required to bidirectionally link Asset Set related entities. + +Asset Set to Child Asset Linkage + +1. Create a placeholder metadata JSON file and upload to IPFS. +2. Mint a mutable ARC-19 asset representing the Asset Set (the "Asset Set ASA"), storing the IPFS hash (from step 1) in the Reserve Address field. +3. Mint the Child Assets, encoding the ID of the parent Asset Set ASA in each Child Asset's metadata. +4. Create a new Asset Set metadata JSON file and add the IDs of each Child Asset. +5. Upload the new JSON file to IPFS. +6. Reconfigure the mutable Asset Set ASA with an updated Reserve Address containing the new IPFS hash (from step 5). + +Asset Set to Contributor Asset Linkage + +1. Create a placeholder metadata JSON file and upload to IPFS. +2. Mint a mutable ARC-19 asset representing the Asset Set (the "Asset Set ASA"), storing the IPFS hash (from step 1) in the Reserve Address field. +3. Mint any Contributor Assets, encoding the ID of the parent Asset Set ASA in each Contributor Asset's metadata. +4. Create a new Asset Set metadata JSON file and add the IDs of each Contributor Asset. +5. Upload the new JSON file to IPFS. +6. Reconfigure the mutable Asset Set ASA with an updated Reserve Address containing the new IPFS hash (from step 5). +7. Transfer the Contributor Assets to the Contributor Addresses. + - Contributor Addresses must opt-in to the Contributor Asset prior to transfer. + +Asset Set to Contributor Address Linkage + +1. Create the Asset Set metadata JSON file and add any Contributor Addresses. +2. Upload the JSON file to IPFS. +3. Mint a mutable ARC-19 asset representing the Asset Set (the "Asset Set ASA"), storing the IPFS hash (from step 2) in the Reserve Address field. +4. All Contributor Addresses must opt-in to the Asset Set ASA to confirm their association. + +### 3: Verification Conditions for Asset Set Information + +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 RFC-2119. + +Due to the potential for arbitrary Contributor Addresses or asset IDs (including assets not controlled by the Asset Set creator) being added to an Asset Set, its metadata cannot be trusted until verification checks are performed. The required verification conditions depend on the Asset Set type ("asset_type" : parameter). By structuring verifications conditional on Asset Set type, provides clear, standardized validation rule sets tailored to the needs of each use case. + +#### Asset Set to Child Asset Validation + +Validation conditions for verified NFT Collections: + +- Asset Set metadata JSON **MUST** include the parameter/value: `"asset_type" : "collection"` +- IF a Child Asset is ARC-19, minted BEFORE or AFTER the Asset Set ASA: + - Asset Set metadata JSON **MUST** include a Child Asset ID in the `assets` array + - Child Asset metadata JSON **MUST** include the parameter/value: `"asset_set" : "asset_id_string"` +- IF a Child Asset is ARC-3, minted AFTER the Asset Set ASA: + - Same validation as above +- IF a Child Asset is ARC-3, minted BEFORE the Asset Set ASA: + - Asset set ASA and the Child Asset **MUST** have the same Creator address + - (Metadata cannot be bidirectionally linked) + +Validation conditions for unverified Asset Groups: + +- Asset Set metadata JSON **MUST** include the parameter/value: `"asset_type" : "group"` +- IF a Child Asset is ARC-3 or ARC-19, minted BEFORE or AFTER the Asset Set ASA: + - No validation is required + +#### Asset Set to Contributor Validation + +Validation conditions for verified NFT Collections: +- Asset Set metadata JSON **MUST** include the parameter/value: `"asset_type" : "collection"` +- IF the Asset Set is linked to Contributor Address: + - Asset Set metadata JSON **MUST** include the Contributor Address + - Contributor Address **MUST** be opted into the Asset Set ASA +- IF the Asset Set is linked to a Contributor Asset + - Asset Set metadata JSON **MUST** include the Contributor Asset ID + - Contributor Address **MUST** hold the Contributor Asset + +Validation conditions for unverified Asset Groups: + +- Asset Set metadata JSON **MUST** include the parameter/value: `"asset_type" : "group"` + - No validation is required + +## Rationale + +### Existing Solutions and Challenges + +Sets of assets, such as NFT Collections, play a fundamental role within blockchain applications and use cases. Ensuring a standardized, decentralized, and interoperable system for defining and validating these Asset Sets is essential. However, currently no NFT Collections standards exist within the Algorand network. The resulting uncertainty surrounding an asset's association with a collection or contributor, can create confusion potentially leading to pricing inaccuracies and decreased trust. + +Previous proposals such as `ARC-30` and `ARC-53` have attempted to tackle metadata standards for NFT Collections. However, their proposed validation solutions lacked sufficient decentralization, while also potentially introducing UX friction and market distortions. Despite recognizing the potential drawbacks of platform-specific solutions, such approaches are still considered due to the absence of alternative platform-agnostic solution. In response, this current ARC proposal focuses on facilitating a fully decentralized validation solution. + +### Key Features + +#### Standardized Metadata Schema + +The proposed metadata schema combined with a modular implementation framework enables extensibility across a range of Asset Set types and use cases, including: + +- NFT Collections: Sets of NFTs with verified association +- Asset Groups: Verified and unverified sets of assets, such as: + - Gaming assets: Sets of in-game items or characters that function together. + - Galleries: Curated sets used to organize and present a body of related artistic work. + - Favorite lists: Adhoc sets of assets, grouped to an individual's liking. + - Dynamic sets: Mutable sets that can evolve over time, with assets manually or programmatically added or removed. + - Collabs: Collaborative sets that include assets created by multiple creators. + - Derivatives: Sets of assets derived from other creator's prior work. + +#### Verification Workflows + +The proposal incorporates verification workflows directly within the ARC-19 minting process, creating interconnected structures to enable decentralized and platform-agnostic validation. + +Verification workflows support a range of conditions: + +1. Asset Set to Child Asset association, via bidirectional linkage + - For both ARC-3 and ARC-19 Child Assets +1. Asset Set to Contributor address association, via unidirectional linkage plus opt-in +1. Asset Set to Contributor Asset association, via bidirectional linkage +1. Support for both verified NFT Collections and unverified Groups of assets + +The modular framework maximizes the scope and flexibility of the ARC, but also introduces increased complexity. Alternatively, validation can be limited to a subset of conditions, for example, only those utilizing bidirectional linkage – this would increase simplicity and robustness. + +For a more explicit specification of verification requirements, a dedicated `verification` parameter could be included within the schema. + +#### Modular Framework + +Both newly minted and pre-existing Asset Sets can selectively implement metadata parameters and validation rules that align with their specific requirements. Pre-existing Asset Sets can choose to migrate to the new standard as needed, enabling the retroactive adoption of the standard across the Algorand ecosystem. + +To enable verification of pre-existing ARC-3 Child Assets, the framework requires that the Creator addresses of Asset Sets and Child Assets match each other. This requirement can be excluded if the scope of the ARC is limited to just newly minted collections. + +#### Contributor attribution + +The ARC provides these contributor verification mechanisms: + +1. Asset Set ASA opt-in by Contributor Addresses +2. Bidirectional linkage between Asset Set and Contributor Asset metadata +3. Transfer of Contributor Assets to Contributor Addresses + +While each method provides implicit proof of association, bidirectional linkage offers enhanced validation strength and transparency by requiring explicit approval from both Asset Set Creator and Contributor. + +Utilizing Contributor Assets within the verification process introduce a new concept in the NFT space, that provides multiple benefits: + +- Validation strength is enhanced through the required additional verification steps by both Contributor and Asset Set creator. +- Verification can be determined by less technical users. +- Contributor Assets can specify customized roles (e.g., Creator, Contributor, Artist). +- Contributor Assets are modeled on POAPs, both are intended to record participation. +- Contributors can display owned Contributor Assets within a public gallery for more transparent proof of association. +- This robust approach is potentially unique to Algorand, making the network more attractive to NFT Creators. + +In addition to the core validation goals facilitated by Contributor Assets, they can also facilitate proper attribution and compensation for contributors, promoting a fairer and more equitable ecosystem. + +#### IP Rights and Royalties Distribution + +Current approaches to royalty payments are either unenforced or platform-specific. By including schema parameters for `license`, `royalties`, `contributor_address`, validated Asset Set metadata can become the primary source of truth for royalties distribution. The ARC provides the necessary components to facilitate decentralized royalty payments, while the actual distribution requires a separate technical implementation. + +The inclusion of the `license` parameter within sovereign Asset Set ASAs enable a flexible approach to ownership and governance. Intellectual property rights can evolve, ownership can be transferred, Asset Set ASAs could even be fractionalized. These new capabilities allow NFT projects to implement innovative funding models, opening up new monetization opportunities for creators and deeper engagement for communities. Asset Set ASAs transform rigid NFT Collections into adaptable entities with customizable management frameworks to meet the changing needs of creators, communities, and investors. + +#### Version Control + +The framework utilizes ARC-19 mutability to enable iterative adjustments to metadata, ensuring that the Asset Set can respond to changes in contributors, content, tokenomics, etc, for long-term sustainability. + +Asset Set metadata includes two version control parameters designed to facilitate tracking and management of metadata: + +- `schema_version`: Records the version of the metadata schema adhered to by the JSON; ensuring compatibility and consistency across applications. +- `version_history`: Maintains an array of each version update, enabling the identification of prior iterations and the ability to track Asset Set evolution. + +#### Minting on Demand + +The mutability of ARC-19 Asset Sets, together with the `version_history` parameter, help support minting on demand use cases such as POAP Collection minting. This is achieved by applying updates to Asset Set metadata after a specific number of POAPs are minted. + +#### Enhanced Discoverability + +The intrinsic linkage between Asset set metadata and its constituent assets facilitates navigation from one entity to the other, in both directions. This interconnectedness enhances transparency and discovery. Interlinked metadata enables sophisticated NFT platform experiences. + +#### Naming Standards + +Alternate names for "Asset Set" were considered: + +- "Collection Asset", "Group Asset" : Too restrictive to Collections or Groups, limiting other use cases. +- "Reference Asset", "Index Asset" : Less intuitive when referring to NFT Collections or Groups. + +**"Asset Set" was chosen for the following advantages:** + +- Clearly conveys a relationship between a group and its constituents. +- More intuitive and inclusive when referring to broader use cases. +- Flexible enough to support emerging use cases like: documents, indexes, directories, etc. + +**Alternate names for "Contributor Assets" were considered:** + +- "Contributor POAPs" +- "Contributor Coins" + +**Instance naming standards** +By specifying a suffix to be appended to each Asset Type instance, the ASA can more obviously self identify its purpose. + +Potential Asset Set instance naming options:** + +- Asset Set name [collection] +- Asset Set name [group] +- Asset Set name [set] + +Potential Contributor Asset instance naming options:** + +- Contributor Asset Name [contributor] +- Contributor Asset Name [poap] + +#### Indexing Efficiency + +- Indexers can efficiently validate metadata by verifying it against entities linked to an Asset Set. +- The `asset_type` parameter standardizes classification, facilitating consistent search queries. +- Storing Child Asset IDs within Asset Set metadata can potentially reduce fetching requests within NFT platforms. +- Including Collection `set_properties` values within Asset Set metadata can streamline filtering. +- Standardized metadata enables improved interoperability and ecosystem analytics. + +## Backwards Compatibility + +### Unchanged Consensus Protocol + +This ARC does not modify the consensus protocol. It only leverages existing Algorand transaction types and JSON metadata formats. Therefore, no new backward compatibility issues are introduced. + +### Support for Legacy Validation + +The ARC's standardized framework avoids the interoperability issues of current platform-specific validation solutions, while also allowing adoption by both new Asset Sets and legacy Collections. This approach enables the new standard to coexist with legacy validation solutions, as long as issuing platforms maintain support for both. However, migrating platforms and legacy collections to the new standard would benefit ecosystem cohesion. + +### Schema fragmentation +The inclusion of the `schema_version` parameter helps future-proof the standard. However, significant schema changes over time could break compatibility. Maintaining the validity of key parameters across versions is important to minimize this risk. + +### Standardized Technical Implementation + +To maximize interoperability across the ecosystem and ease `schema_version` transitions, a standardized technical implementation of verification workflows through shared code would be optimal. Applications could then easily implement the standardized validation logic locally. Development of an open-source repo would align well with the goals of the xGov program. + +## Security Considerations + +While this ARC does not introduce protocol security risks, the potential for fraudulent usage of the standard should be addressed. + +### Key Concerns + +Users could manipulate Asset Set metadata to artificially inflate asset values by: + +- Including unauthorized Asset IDs or Contributor Addresses. +- Creating deceptive Asset Sets combining high-value unowned and low-value owned assets. +- Building fake influencer personas around contributor addresses. + +Users may also bypass critical validation checks such as: + +- Cross-verifying Asset Set and Child Asset creator address matches. +- Confirming metadata linkage. +- Validating Contributor Address opt-in status. + +#### Mitigating Risks + +Platforms and users should take the following steps to avoid risks: + +- Strictly adhere to the verification workflows. +- Develop an open-source implementation of verification processes to increase reliability across platforms. +- Build trust by displaying `verified` badges for Asset Sets that pass validation checks. +- Asset buyers and ecosystem stakeholders should remain vigilant to the risks and educated on manual validation steps. + +## Copyright + +Copyright and related rights waived via CCO.