AssetTree¶

What is AssetTree¶

AssetTree files describe an asset's properties, including its creator, creation time, license, and other relevant details. These AssetTree files contain a comprehensive collection of metadata that are important to authenticating digital assets on the blockchain.

When changes are made to an asset, a new Commit is created on the blockchain. This process also leads to the generation of a new AssetTree file, reflecting the updated state of the asset. Each of these commits includes the Nid of the relevant AssetTree within its metadata, linking every asset state to a particular point in the blockchain.

An important part of this process is the merging of AssetTree files. This must be done according to the Commit specifications, which then allows users to trace the complete history of an asset. Users may also use API or nit module to merge AssetTree files. By merging the AssetTree files, one can see the complete lifecycle of the asset from its creation to its alterations, to the current state.

For example, consider a digital art piece that has undergone multiple iterations. Each AssetTree file would document properties such as the artist's name, the dates of revisions, the licenses under which the art is distributed, any relevant keywords, and other pertinent information about the art at each point of its evolution. These historical snapshots can be used to verify the authenticity of the art piece at each stage, ensuring it hasn't been tampered with and can always be traced back to its original creator.

Overall, AssetTree provides a comprehensive view of the properties of the asset and ensures transparency and accountability, making it an essential part of the assetization process.

AssetTree Specification¶

AssetTree is a JSON file on IPFS containing the following information:

Field	Type	Required	Description
`assetCid`	string	Yes	The Nid of the asset file
`assetCreator`	string	Yes	Name of the asset creator. The length should not exceed 15 characters.
`encodingFormat`	string	Yes	The asset's type expressed using a MIME format
`abstract`	string	Yes	An abstract is a short description that summarizes the asset, the length should not exceed 500 characters. More details see the definition on the schema.org
`assetTimestampCreated`	Unix timestamp	Yes	Creation time of the asset file, the time when the digital media content was converted to a Web3 asset (i.e. with the first blockchain recognition).
`headline`	string	No	Headline or the title of the content file, the length should not exceed 25 characters. More details see the definition on the schema.org
`digitalSourceType`	string	No	Specify the type of the source. More details see digitalSourceType.
`assetLocationCreated`	string	No	Precise or broad location where the asset was created.
`assetSha256`	string	No	SHA-256 hash of the asset file
`assetSourceType`	string	No	This field specifies where the asset comes from
`creatorWallet`	string	No	The wallet address of the asset creator
`creatorProfile`	string	No	The Nid of the creator profile
`parentAssetCid`	string	No	The Nid of the parent asset
`license.name`	string	No	License of the asset file
`license.document`	string	No	URL of the license file
`miningPreference.allowed`	array	No	Provide options of the allowed mining preferences for data mining or AI/ML training workflow. More details see miningPreference.
`miningPreference.notAllowed`	array	No	Provide options of the NOT allowed mining preferences for data mining or AI/ML training workflow. More details see miningPreference.
`miningPreference.constrained`	array	No	Provide options of the allowed mining preferences with constraints for data mining or AI/ML training workflow. More details see miningPreference. If the mining option is shown in the constrained array, the users should follow the license to use the asset properly.
`generatedBy`	string	No	The AI model used to generate the content.
`generatedThrough`	string	No	URL of the software application or a downloadable link which generates the digital content.
`usedBy`	string	No	URL of the website that uses the asset
`integrityCid`	string	No	The Cid/Nid of the additional proof metadata on IPFS. More details see integrityCid.
`nftRecord`	string	No	IPFS Cid where you can find all the NFT records. More details see nftRecord.
`displaySocial`	boolean	No	Set this to `True` if you want to display the asset on Asset Profile with the social media link instead of the IPFS file URL.
`socialLink`	string	No	Social link to the URL. If `displaySocial` is true, this URL will be used to display the asset on Asset Profile.
`custom`	JSON	No	Custom metadata

The DBDiagram describes the relationship between Commit and AssetTree tables. Here is an example of the AssetTree file. You may also refer to the nit open-source project for more examples of how to create AssetTree and Commit.

Note:

This specification follows the EIP-191 verification method for input: data, signature and output: signer's wallet address.

digitalSourceType¶

digitalSourceType is a controlled vocabulary that indicates from which source a digital media was created. The vocabulary is maintained by the International Press Telecommunications Council (IPTC), a non-profit organization that develops and maintains standards for the exchange of news and multimedia content.

The digitalSourceType in AssetTree is defined the same way as in the C2PA spec whose value shall be one of the terms defined by the IPTC or a C2PA specific value. Some useful guidlines to choose the digitalSourceType:

For AI-generated images or videos, the value should be trainedAlgorithmicMedia.
If the content is generated by AI but the format is not digital media, use trainedAlgorithmicData
digitalCapture should be used for original digital capture sampled from real life.
digitalArt can be used for media created by a human using digital tools.
If the media file was created purely by an algorithm NOT based on any sampled training data, e.g. an image created by software using a mathematical formula, use algorithmicMedia
For content which does not have a clear source type, the field should be empty or use digitalUpload. digitalUpload means the content file was uploaded without specifying any reliable digitalSourceType.

integrityCid¶

The integrityCid is a unique identifier representing the IPFS address of a file containing the integrity proof of the content collected and signed by a device.

The integrity proof serves as a digital fingerprint that verifies the authenticity and integrity of the content file, ensuring that it has not been tampered with or altered in any way since its creation. The integrity proof should include metadata about the content file, such as its MIME type, timestamp, device information, geolocation data, and a proof hash. This metadata provides crucial context and attests to the content's provenance. The integrityCid provides a secure and reliable method to store and retrieve the content's integrity proof, guaranteeing its trustworthiness and facilitating validation of the content's origin throughout its lifecycle.

Integrity Proof Specification¶

Here's the spec for the integrity proof in plain text with bullet points:

asset_mime_type: (string) The content's type expressed using a MIME format
caption: (string) A caption or description of the content file
created_at: (timestamp) Creation time of the content file
device_name: (string) The name of the device used to create the content file
information: (JSON) Available fields see the table below
location_latitude: (number) The latitude of the content's location
location_longitude: (number) The longitude of the content's location
proof_hash: (string) The proof hash for the content
recorder: (string) The name of the recorder used to create the content
spec_version: (string) The version of the specification

Information¶

The "information" section in the integrity proof contains details about the device and its environment at the time of content creation. This includes data about the app used to capture or create the content, such as the app's name, identifier, version, and build number. Additionally, it provides information about the device itself, including the device name, manufacturer, platform, operating system, and unique identifier.

The section also covers the device's battery level, charging status, memory usage, and available disk space depending on the permission granted by the register. Finally, geolocation information, such as latitude and longitude, is included to specify the location of the content when it was created. This comprehensive set of data helps to ensure the integrity of the content and provides a detailed context for its origin.

Field	Type	Description
device.app_build	string	The app build number
device.app_id	string	The app identifier
device.app_name	string	The name of the app
device.app_version	string	The app version
device.battery_level	number	The device's battery level at the time of content creation
device.device_name	string	The name of the device
device.disk_free	number	The available disk space on the device
device.disk_total	number	The total disk space on the device
device.is_charging	boolean	Whether the device is charging or not
device.is_virtual	boolean	Whether the device is virtual or physical
device.manufacturer	string	The device manufacturer
device.mem_used	number	The memory used on the device
device.operating_system	string	The operating system of the device
device.os_version	string	The operating system version
device.platform	string	The platform of the device
device.user_device_name	string	The user-defined device name
device.uuid	string	The unique device identifier
geolocation.geolocation_latitude	number	The latitude of the content's location
geolocation.geolocation_longitude	number	The longitude of the content's location

Example of Proof Metadata¶

The following is an example of the proof metadata you may find following the integrityCid:

{
    "asset_mime_type": "image/png",
    "caption": "Beautiful sunset",
    "created_at": 1693309348713,
    "device_name": "iPhone13,3",
    "information": {
        "device.app_build": "850",
        "device.app_id": "io.numbersprotocol.capturepro",
        "device.app_name": "CapturePro",
        "device.app_version": "1.25.3",
        "device.battery_level": 0.599999993827392,
        "device.device_name": "iPhone13,3",
        "device.disk_free": 219000034311,
        "device.disk_total": 511762931712,
        "device.is_charging": true,
        "device.is_virtual": false,
        "device.manufacturer": "Apple",
        "device.mem_used": 58761233,
        "device.operating_system": "iOS",
        "device.os_version": "16.1",
        "device.platform": "iOS",
        "device.user_device_name": "iPhone",
        "device.uuid": "1A2B3C4D-56EF-78AB-90CD-1234E5F6A7B8",
        "geolocation.geolocation_latitude": 34.052235,
        "geolocation.geolocation_longitude": -118.243683
    },
    "location_latitude": 34.052235,
    "location_longitude": -118.243683,
    "proof_hash": "5c1234ef67g8h901i2j3k4l56m7890nop1q2r3s4t5u6v7w8x9y0zab1c2d3e4f5",
    "recorder": "CapturePro",
    "spec_version": "2.1.0"
}

miningPreference¶

miningPreference designates the selection made by the asset creators or licensed owners to decide if the asset is suitable for inclusion in a data mining or AI/ML training workflow:

dataMining : Allow text or data content to be extracted from the asset for purposes of determining "patterns, trends and correlations".
aiInference : Allow the asset to be used as input to a trained AI/ML model for the purposes of inferring a result.
aiGenerativeTraining : Authorize the work can be used as AI training data freely to an AI/ML model that could produce derivative assets.
aiGenerativeTrainingWithAuthorship : Authorize the work can be used as AI training data freely to an AI/ML model that could produce derivative assets as long as my authorship is disclosed.
aiTraining: Authorize the work can be used as AI training data freely to generative and non-generative AI/ML models, such as those used for classification, object detection, etc.
aiTrainingWithAuthorship: Authorize the work can be used as AI training data freely to generative and non-generative AI/ML models, such as those used for classification, object detection, etc, as long as my authorship is disclosed.

For more details please refer to the C2PA specification.

nftRecord¶

The nftRecord in the AssetTree is an essential component to allow for the traceability of NFT tokens minted for the asset. One should follow the definition of NFTs to issue tokens in order to build robust ownership systems. This is particularly important in the creator economy, as creators need to have a way to prove ownership and provenance of their creations.

nftRecord is a file on IPFS decentralized web containing a list of NFT records. As discussed in the Key Difference From NFT page, it is common that one asset is minted as multiple NFTs. In order to make sure the records can be found, a commit can be created after minting and put the NFT/NFTs info "of that mint" to be included in the nftRecord. The nftRecord is structured as an array, allowing multiple NFTs to be included in a single commit. This setup supports cases where multiple NFTs are minted in one action. The NFT records are stored as JSON files on IPFS to make them accessible.

The use of IPFS to store the nftRecord adds an additional layer of decentralization, as the information is stored on a distributed network rather than a single centralized server. This ensures that the records are tamper-proof and can be easily accessed by anyone.

If you want to view the full NFT history of an asset, you can use the Read Asset History feature, which retrieves the on-chain data directly.

nftRecord Specification¶

Every nft record in the nftRecord file is a JSON object containing the following information:

network: chain ID of the NFT blockchain
contractAddress: NFT contract address
tokenID: token ID of the NFT

Here is an example of the nftRecord file:

[
  {
    "network": 108,
    "contractAddress": "0x59d6fe14e7bfaf7c89c297be301195b96335df0e",
    "tokenId": "37262"
  }
]