This EIP proposes the establishment of a new metadata standard for Historical Asset Tokens (HATs) on the Ethereum
platform. HATs are tokens that represent a specific historical asset, such as a collectible or a rare item, and provide
comprehensive context and provenance needed to establish historical significance and value.
HAT is the metadata standard and smart contract for historical NFTs. While existing NFT standards offer the mechanism to
ensure immutability and decentralised ownership of assets on the blockchain, we believe a rich metadata standard (that
includes data for the underlying asset from its moment of creation to its moment of conversion) will imbue historical
NFTs with the comprehensive context and provenance needed to establish historical significance and value. Additionally,
the standard will enhance the discoverability, connectivity, and collectability of all HATs.
Motivation
In recent years, the market for collectible and rare items has experienced significant growth, with many people looking
to buy, sell, and trade these assets in an efficient and secure manner. However, the current market for historical
assets is often plagued by issues such as fraud, counterfeiting, and lack of transparency.
The creation of a standard for HATs on the Ethereum platform has the potential to address these issues and provide a
secure and transparent marketplace for historical assets. By representing historical assets as tokens on the blockchain,
it becomes possible to create a permanent, tamper-proof record of ownership and transfer of these assets, while also
providing a level of transparency and security that is not currently available in traditional markets.
The standard is proposed as the number and variety of NFT projects increases. The current ERC-721 has a
modest metadata
extension, optionally allowing for the inclusion of “name” and “symbol” functions to identify NFT
collections, and for "name", "descriptions", and “image” attributes to represent assets. Metadata plays a big role in
facilitating the search and discovery of NFTs on marketplaces. As the number and variety of NFT projects increases,
disconnected and limited metadata structures makes it difficult for collectors to navigate through the ocean of NFT
assets on major marketplaces and make sense of their value.
The provenance and history of artworks, artifacts and historical IP can take different forms and be created by
different issuers. While there is no consolidated archive, a standardised metadata structure provides connectivity
across NFTs associated with historical and cultural assets, regardless of the medium and issuer. For example, a video
clip issued by a local filmmaker about the 1997 handover of Hong Kong can be connected to the news coverage by South
China Morning Post (SCMP) of the Sino-British Joint Declaration via the HAT metadata. While well-informed collectors may
not need this programmed connectivity, a standardised metadata for HATs will make these connections easily accessible
for all collectors, scholars, and interested parties.
Provenance and context are extremely important for historical assets. The archival and research of significant artworks,
objects, and collections are ongoing; it is a collaborative effort between creators, artist estates, galleries, auction
houses, scholars and institutions. The consolidation of information and knowledge is not only crucial to the
understanding of our cultural heritage; the richer the context, the more valuable the asset is to collectors. A shared
and standardised metadata structure enriches the context of an NFT. With the establishment of HATs, it is our hope that
this standardised structure will contribute to the evolution of cultural heritage, and fully capture the context of
culturally and historically significant assets, thereby ensuring relevant and fair value for all historically
significant NFTs.
Specification
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
This EIP extends ERC-721 and ERC-1155 with 48 additional properties to capture the
historical significance of the underlying asset.
Compatible contracts, besides implementing the relevant metadata schemas ("Metadata JSON Schema" for
ERC-721 contracts or "Metadata URI JSON Schema" for ERC-1155 contracts), must implement
the following metadata interface.
The following TypeScript interface defines the mandatory and optional properties compatible tokens must conform to:
interfaceHistoricalAssetMetadata{name:string;// Name of the HATdescription:string,// Full description of the HAT to provide the historical contextimage:string;// A URI pointing to a resource with mime type image/* to serve as the cover image of the HATproperties:{id:string;// An unambiguous identifier of the HATsummary:string;// Short description of the HAT, no more than 200 charactersassetType:// The type of the underlying asset"newspaper_cover"|"magazine_a1_cover"|"newspaper_article"|"magazine_article"|"photo"|"graphic"|"video"|"audio"|"3d_object"|"others";issuers:string[];// Organizations or individuals who created the HATissueTimestamp:string;// The date and time the HAT was issued in ISO 8601 formatedition:number;// Unique serial number of the HATeditionCount:number;// Total number of editions available for this HATfileURI:string;// Link to the digital file representing the HATfileSize:number;// Size of the digital file of the HAT in bytesfileFormat:string;// MIME type of the digital file of the HATseriesName?:string;// The name of the series this HAT is a part ofassetFullText?:string;// The full text in the underlying asset of the HATassetCreators?:string[];// Organizations or individuals who created the underlying assetearliestPossibleCreationDate?:string;// Earliest possible creation date of the underlying asset in ISO 8601 date formatlatestPossibleCreationDate:string;// Latest possible creation date of the underlying asset in ISO 8601 date formatassetCreationGeos?:string;// Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivisionassetCreationLocations?:string[];// Specific cities and named locations where the underlying asset was createdassetCreationCoordinates?:string[];// Coordinates of the location where the underlying asset was createdrelevantDates?:string[];// Dates, in ISO 8601 date format, that are referenced and important to the significance of the HATrelevantGeos?:string[];// Country, subdivision, and city that are referenced and important to the significance of the HAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivisionrelevantLocations?:string[];// Specific cities and named locations that are referenced and important to the significance of the HATrelevantPeople?:string[];// Individuals that are referenced and important to the significance of the HATrelevantEntities?:string[];// Entities that are referenced and important to the significance of the HATassetLanguages?:string[];// Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage namesassetHeight?:string;// Height of the underlying assetassetWidth?:string;// Width of the underlying assetassetDepth?:string;// Depth of the underlying assetassetFileURI?:string;// Link to a high quality file of the underlying assetassetFileSize?:number;// Size of the digital file of the underlying asset in bytesassetCopyrightHolder?:string;// Copyright holder of the underlying assetassetCopyrightDocumentURI?:string;// Link to the legal contract that outlines the copyright of the underlying assetassetProvenanceRecordURI?:string;// Link to the existing provenance record documents of the underlying assetisPhysicalAsset?:boolean;// Flags whether the asset is tied to a physical assetassetMedium?:string;// The material used to create the physical underlying assetassetFormFormat?:string;// The physical form or the digital format of the underlying asset. For digital format, a MIME type should be specified.issuerNotes?:string;// Issuer's notes regarding the HAT and its underlying assettokenReplaced?:string;// Token identifier of the token this HAT replacedtokenReferenced?:string;// Token identifier of the token this HAT referenced, or is a derivative ofisOwnerTokenCopyrightRightHolder?:boolean;// Flags whether the HAT token holder is the copyright owner of the HAT. Does not include the copyright to the underlying assettokenCopyrightRightDocumentURI?:string;// Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the HATisOwnerAssetCopyrightRightHolder?:boolean;// Flags whether the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying assetassetCopyrightRightDocumentURI?:string;// Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying assetisOwnerTokenReprintRightHolder?:boolean;// Flags whether the token owner has non-exclusive reprint/second serial rights to the HAT. Does not include the rights to the underlying assettokenReprintRightDocumentURI?:string;// Link to legal document outlining the token owner’s reprint/second serial rights of the HATisOwnerAssetReprintRightHolder?:boolean;// Flags whether the token owner has non-exclusive reprint/second serial rights to the underlying asset. Does not include the rights to the underlying assetassetReprintRightDocumentURI?:string;// Link to legal document outlining the token owner’s reprint/second serial rights of the underlying assetisEligibleForRelatedTokenAirdrops?:boolean;// Flags whether the token holder is eligible for related HAT airdropsisEligibleForMetaverseAccess?:boolean;// Flags whether the token holder can gain access to the HAT metaverse}}
Historical Asset Metadata JSON Schema
The following JSON Schema enforces the constraints set out in the above interface definition. Tokens adopting the
Historical Asset Metadata JSON Schema extension should be validated against the JSON schema prior to minting:
{"title":"Historical Asset Metadata","type":"object","properties":{"name":{"type":"string","description":"Name of the HAT"},"description":{"type":"string","description":"Full description of the HAT to provide the historical context"},"image":{"type":"string","description":"A URI pointing to a resource with mime type image/* to serve as the cover image of the HAT","format":"uri"},"properties":{"type":"object","description":"Historical asset attributes","properties":{"id":{"type":"string","description":"An unambiguous identifier of the HAT"},"summary":{"type":"string","description":"Short description of the HAT, no more than 200 characters"},"assetType":{"type":"string","enum":["newspaper_cover","magazine_a1_cover","newspaper_article","magazine_article","photo","graphic","video","audio","3d_object","others"],"description":"The type of the underlying asset"},"issuers":{"type":"array","items":{"type":"string"},"description":"Organizations or individuals who created the HAT"},"issueTimestamp":{"type":"string","description":"The date and time the HAT was issued in ISO 8601 format","format":"date-time"},"edition":{"type":"integer","description":"Unique serial number of the HAT"},"editionCount":{"type":"integer","description":"Total number of editions available for this HAT"},"fileURI":{"type":"string","description":"Link to the digital file representing the HAT","format":"uri"},"fileSize":{"type":"integer","description":"Size of the digital file of the HAT in bytes"},"fileFormat":{"type":"string","description":"MIME type of the digital file of the HAT"},"seriesName":{"type":"string","description":"The name of the series this HAT is a part of"},"assetFullText":{"type":"string","description":"The full text in the underlying asset of the HAT"},"assetCreators":{"type":"array","items":{"type":"string"},"description":"Organizations or individuals who created the underlying asset"},"earliestPossibleCreationDate":{"type":"string","description":"Earliest possible creation date of the underlying asset in ISO 8601 date format","format":"date"},"latestPossibleCreationDate":{"type":"string","format":"date","description":"Latest possible creation date of the underlying asset in ISO 8601 date format"},"assetCreationGeos":{"type":"array","items":{"type":"string"},"description":"Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision"},"assetCreationLocations":{"type":"array","items":{"type":"string"},"description":"Specific cities and named locations where the underlying asset was created"},"assetCreationCoordinates":{"type":"array","items":{"type":"string"},"description":"Coordinates of the location where the underlying asset was created"},"relevantDates":{"type":"array","items":{"type":"string","description":"Dates, in ISO 8601 date format, that are referenced and important to the significance of the HAT","format":"date"}},"relevantGeos":{"type":"array","items":{"type":"string"},"description":"Country, subdivision, and city that are referenced and important to the significance of the HAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision"},"relevantLocations":{"type":"array","items":{"type":"string"},"description":"Specific cities and named locations that are referenced and important to the significance of the HAT"},"relevantPeople":{"type":"array","items":{"type":"string"},"description":"Individuals that are referenced and important to the significance of the HAT"},"relevantEntities":{"type":"string","description":"Entities that are referenced and important to the significance of the HAT"},"assetLanguages":{"type":"array","items":{"type":"string"},"description":"Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage names"},"assetHeight":{"type":"string","description":"Height of the underlying asset"},"assetWidth":{"type":"string","description":"Width of the underlying asset"},"assetDepth":{"type":"string","description":"Depth of the underlying asset"},"assetFileURI":{"type":"string","description":"Link to a high quality file of the underlying asset","format":"uri"},"assetFileSize":{"type":"integer","description":"Size of the digital file of the underlying asset in bytes"},"assetCopyrightHolder":{"type":"string","description":"Copyright holder of the underlying asset"},"assetCopyrightDocumentURI":{"type":"string","description":"Link to the legal contract that outlines the copyright of the underlying asset","format":"uri"},"assetProvenanceRecordURI":{"type":"string","description":"Link to the existing provenance record documents of the underlying asset","format":"uri"},"isPhysicalAsset":{"type":"boolean","description":"Flags whether the asset is tied to a physical asset"},"assetMedium":{"type":"string","description":"The material used to create the physical underlying asset"},"assetFormFormat":{"type":"string","description":"The physical form or the digital format of the underlying asset"},"issuerNotes":{"type":"string","description":"Issuer's notes regarding the HAT and its underlying asset"},"tokenReplaced":{"type":"string","description":"Token identifier of the token this HAT replaced"},"tokenReferenced":{"type":"string","description":"Token identifier of the token this HAT referenced, or is a derivative of"},"isOwnerTokenCopyrightRightHolder":{"type":"boolean","description":"Flags whether or not the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying asset"},"tokenCopyrightRightDocumentURI":{"type":"string","description":"Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the HAT","format":"uri"},"isOwnerAssetCopyrightRightHolder":{"type":"boolean","description":"Flags whether or not the HAT token holder is the copyright owner of the underlying asset. Does not include the copyright to the underlying asset"},"assetCopyrightRightDocumentURI":{"type":"string","description":"Link to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying asset","format":"uri"},"isOwnerTokenReprintRightHolder":{"type":"boolean","description":"Flags whether or not the HAT token owner has non-exclusive reprint/second serial rights to the HAT. Does not include the rights to the underlying asset"},"tokenReprintRightDocumentURI":{"type":"string","description":"Link to legal document outlining the token owner’s reprint/second serial rights of the HAT","format":"uri"},"isOwnerAssetReprintRightHolder":{"type":"boolean","description":"Flags whether or not the HAT token owner has non-exclusive reprint/second serial rights to the underlying asset. Does not include the rights to the underlying asset"},"assetReprintRightDocumentURI":{"type":"string","description":"Link to legal document outlining the token owner’s reprint/second serial rights of the underlying asset","format":"uri"},"isEligibleForRelatedTokenAirdrops":{"type":"boolean","description":"Flags whether or not the HAT token holder is eligible for related HAT airdrops"},"isEligibleForMetaverseAccess":{"type":"boolean","description":"Flags whether or not the HAT token holder can gain access to the HAT metaverse"}},"required":["assetType","id","issuers","summary","issueTimestamp","edition","editionCount","fileURI","fileSize","fileFormat","latestPossibleCreationDate"]}},"required":["name","description","image","properties"]}
Rationale
Choosing to Extend Off-Chain Metadata JSON Schema over On-Chain Interface
Both the ERC-721 and ERC-1155 provides natural extension point in the metadata JSON
file associated with NFTs to provide enriched dataset about the underlying assets.
Providing enriched dataset through off-chain metadata JSON files allow already-deployed NFT contracts to adopt the
metadata structure in this EIP without upgrade or migration. The off-chain design allows for flexible and progressive
enhancement of any NFT collections to adopt standard such as this EIP, and to progressively enhance and enrich the
collection over time.
By avoiding the need to newly create or adapt smart contracts, NFT collections can be deployed using audited and battle
tested smart contract code, thus reducing the risk of adopting and implementing a new standard.
Capturing Attributes Extensions in properties property
The ERC-1155 standard has a properties property in its JSON Metadata Schema to define an arbitrary
set of additional metadata or properties to describe an underlying asset. Defining the metadata fields in this EIP over
this properties preserve the overall shape of the metadata schema of the ERC-1155, minimizing the
change needed to list and process the proposed properties.
For tokens minted against the ERC-721 standard, only one additional property needs to be added to the
metadata JSON object to take advantage of the standardized fields, simplifying the adoption of this standard.
Backwards Compatibility
This EIP is fully backward compatible with ERC-721 and ERC-1155.
Security Considerations
NFT platforms and systems working with Historical Asset Metadata JSON files are recommended to treat the files as client
supplied data and follow the appropriate best practices for processing such data.
When processing the URI fields, backend systems should take care to prevent a malicious issuer exploiting these fields
to perform Server-Side Request Forgery (SSRF).
Frontend or client-side systems are recommended to escape all control characters that may be exploited to perform
Cross-Site Scripting (XSS).
Processing systems are also recommended to take care with resource allocation to mitigate against buffer overflow due to
improper processing of variable data such as strings, arrays, and JSON objects. This is to prevent the systems from
becoming susceptible to Denial of Service (DOS) attack or circumventing security protection through arbitrary code
exception.
The metadata JSON files and the digital resources representing both the token and underlying assets should be stored in
a decentralized storage network to preserve integrity and to ensure available of data for long term preservation.
Establishing the authenticity of the claims made in the Metadata JSON file is beyond the scope of this EIP, and is left
to future EIPs to propose an appropriate protocol.