Commit¶

In Numbers Protocol, "Commits" serve as a mechanism for tracking the evolution of a digital asset throughout its lifecycle. Similar to the design of Git, a widely-used version control system, Commits in Numbers Protocol allows developers to easily monitor changes made to Web3 assets and view their full history.

When a commit is created, it serves as a historical record of a specific alteration made to an asset, including information such as the updated assetTree file, the action performed, and the identity of the person who made the change. These changes may include modifications to the asset's metadata, the addition of new files, or any other type of update. By reviewing the commit messages, users can access important information about an asset, such as the date and time of the change, the user who made the change, and a detailed description of the change, allowing for full transparency and traceability.

Commit Contract¶

To ensure the interoperability and decentralization of the digital media indexing system, the Commit contract implemented on the Numbers blockchain, and on any network indexed by the Numbers engine should follow the reference design suggested by the EIP-7053 standard.

The Commit contract serves as a vital component in generating Commit Messages, which play a pivotal role in establishing the authenticity and provenance of digital media assets within the digital-media ecosystem.

Commit Message¶

In most cases, when Commit or Commits are mentioned in the documentation, it refers to "Commit Messages" which generated by the Commit contract. All Commit messages should include:

One immutable on-chain message and
An AssetTree pinned on IPFS

Creating a Commit message allows for the association of metadata with the asset and the ability to track the entire history of the asset.

It should be noted that the original asset, such as an image or video, is NOT stored on the blockchain, but is converted to a Nid and kept on IPFS. This allows for efficient storage and fast retrieval of the asset, while still maintaining a tamper-proof history of the asset on the blockchain.

The process of viewing this history is straightforward:

First, by querying the asset's Nid, which serves as a unique identity
By locating and viewing the associated Commits to see the changes made
Check AssetTree files linked to the Commits and finds changes of the assets over time.

By having a clear and transparent record of all modifications, changes, and other related activities, it is possible to understand the context of an asset and make informed decisions about its value and use.

Specification for Commit message:¶

Field Name	Description	Type	Optional
`assetCid`	The Nid of the asset file.	string	false
`assetTreeCid`	The Nid of the AssetTree file.	string	false
`assetTreeSha256`	The sha256sum of the AssetTree file.	string	false
`assetTreeSignature`	The EIP-191 signature signed by the asset's author.	signature	false
`abstract`	Commit message. This should describe the purpose of the commit and is different from the abstract in the AssetTree.	string	false
`author`	The wallet address of the person who writes the assetTree content.	string	false
`committer`	The wallet address which sends the transaction.	string	false
`action`	The Nid of the IPFS file which describes the action performed to the asset.	string	false
`actionName`	The name of the action in plain text. More details about `action` and `actionName` see the Action session below.	string	false
`actionResult`	The result URI of the performed action.	string	true
`provider`	The Cid/Nid of the IPFS file which describe the information of the service provider.	string	true
`attachment`	The Cid/Nid of the attachment file.	string	true

The DBDiagram describes the relationship between Commit and AssetTree tables. More tools to create and read commits can be found on the Developer pages. You may also refer to the nit open-source project for more examples of how to create AssetTree and Commit.

Note:

The goal of the Commit is to ensure the integrity of the raw asset and its derivatives, such as metadata, and possibly the major asset.
One asset can have multiple commits and all of those commits will be tracked here. It will include the details of the asset tree file and the metadata, who created and registered this asset

Actions¶

An action refers to a specific type of transaction that occurs on the Numbers network. It represents an instruction to the network to perform a specific task, such as initial registration, minting NFT, licensing the asset, showing the asset is composed of other assets, committing log messages or other custom actions.

These actions are verified and recorded on the blockchain, ensuring the immutability and integrity of the data. The following table shows the pre-defined actions in the Numbers Network:

actionName	action	actionResult	Description
action-initial-registration-jade	bafkreicptxn6f752c4pvb6gqwro7s7wb336idkzr6wmolkifj3aafhvwii	\	Initial registration of assets on Numbers Mainnet
action-initial-registration-avalanche	bafkreiavifzn7ntlb6p2lr55k3oezo6pofwvknecukc5auhng4miowcte4	\	Initial registration of assets on Avalanche C-Chain
action-initial-registration-iota	bafkreibnyl3ohbx76rzxmdzfyayvztjcqgjv745wh4t3z6a4ung43xd554	\	Initial registration of assets on IOTA
action-license-to	(Update Soon)	\	License asset to a wallet owner
action-composition	(Update Soon)	\	Showing other assets that are used to create the current asset
action-used-by	(Update Soon)	\	Showing how the current asset is used by other assets or referred by a website
action-mint-erc721-nft-jade	bafkreiakk6le5wgbl3zz3acybd2wfc2y32mpmxj4kbjjjskom7cy2akwly	\	Mint ERC721 NFT on Numbers Mainnet
action-mint-erc721-nft-ethereum	bafkreighzhmelvwlntigjq6ushun4mz36x6cq5nztkvcac47bdxz2ipeca	\	Mint ERC721 NFT on Ethereum network
action-mint-erc721-nft-avalanche	bafkreibro4v4vsibvr47uwhkj6gqpc5rfvvq5ykfzzz4jnzvm23zwoh2gq	\	Mint ERC721 NFT on Avalanche network
action-mint-erc721-nft-polygon	bafkreigdxfmwhhepusyhaoidyzy6bv7jzpc5liqohyc6numgvvbfwabn6a	\	Mint ERC721 NFT on Polygon network
action-mint-erc721-nft-thundercore	bafkreih7gzxeukcnosbotvpq7hw6htlxoi2dzzm2nnkskloazgw2sbh55i	\	Mint ERC721 NFT on ThunderCore network
action-commit	bafkreiceiqfe4w4g4j46rsi4h4tbqu35ivewfxm4q743tfmegscpg7d63m	\	General commit messages of the asset, also the default action if you use nit to commit.

You may also find the list of pre-defined actions on GitHub.

Action specification¶

{
  "networkActionName": <unique-name>,
  "blockchain": <name-of-blockchain-network>,
  "tokenAddress": <address-of-payment-token>,
  "provider": <nid-of-provider-description>,
  "abstract": <short-description-of-this-action>,
  "type": "new"
}

Create custom Action¶

A custom action allows developers to extend the functionality of the Numbers network and create solutions for their specific use cases. By creating a custom action, developers can add unique logic, automate processes, and interact with other smart contracts on the blockchain. This enables them to build more sophisticated applications and provide additional value to their users.

If you are interested in creating a custom action, here are the steps:

Create a JSON object following the action spec
Save it to a file and pin the file on IPFS
Get the action file Nid (you can also use this API to execute step 1, 2, 3 together)
Update action.ts and submit PR on GitHub

The nit repository maintainer will review your PR and proceed with the follow-up actions on GitHub.