npm: @futureverse/asset-register-reactnpmLoading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Asset Register is where you manage assets across applications in the open metaverse.
The Asset Register is a new ledger system and tool suite that enables developers to establish data parameters for their assets. It is a metadata repository that defines what an asset is, what an asset can do, and the various environments in which an asset can be applied.
Assets in web3 are currently restricted by their linear data composition. Each asset typically only has one corresponding metadata file and there is no way to create connections between assets in disparate ecosystems. Current systems tend to rely on specific chains, hindering asset relationships across different networks. Moreover, they primarily cater to on-chain assets, overlooking off-chain ones. Achieving interoperability for both types of assets across various applications is challenging.
The Asset Register addresses these challenges, and supports interesting use cases:
Equipping accessories to assets across chains
Linking user metadata to a collectible to show its provenance
Managing which collections are compatible with which accessories
Informing applications about what an object does and what engines it is compatible with
The Asset Register has three components: the Asset Register Core Ledger, the Asset Register API, and the Schema Management System, which sits on top for validation and is the main enabler of interoperability.
A good understanding of blockchain technology will help you comprehend how it works.
The Asset Register Core is similar to layer 2 DLTs and built specifically for asset relationship management. The Asset Register Core facilitates the data relationships between assets and ultimately enables us to create rich, interoperable applications while still adhering to Web3 design principles such as:
Consistency
Data transparency
Good question!
Users need to make decisions that are authenticated by their identity
Actions must be changed together in a logical order to ensure the changes to the state are consistent
Data needs to be readily available and accessible so that many applications can have the same source of truth
These are the same reasons blockchains are so good at what they do; every single state change is chained together consistently. We aren't reinventing the wheel. On the identity front, we leverage a user's FuturePass or other existing wallet for authentication. Delegated signing is also something we have scoped for.
Unlike a regular consensus blockchain that allows you to create assets with corresponding values, the Asset Register is lighter weight. It does not manipulate ownership of assets, relying instead on on-chain activities for this. Since there is no direct value attached to the links created by the Asset Register, the requirement for high trust does not exist in the same way. We realize, however, that applications may ascribe value in the asset links, so the roadmap includes both decentralized data storage and validation of data oracles. This is being done to maximize decentralization and trust while ensuring user experience, cost, and performance are optimized.
The Asset Register API is used to interact with the Asset Register Core and the Schema Management System.
Schemas merely describe data. We aren't doing anything special here. There is also no requirement to use our Schema Management service, you can host your schemas anywhere you like for increased decentralisation.
Our Schema Management System is built to facilitate a seamless onboarding experience for asset creators. It is built using TTL (pronounced 'turtle') files and utilizes the SHACL shape schema to describe assets and their relationships.
The system handles the hosting of schemas on a domain under the relevant namespaces. Asset creators can create schemas to describe the assets and the Schema Management System will stitch together multiple schemas on the same namespace. This will be used by people and machines to validate data outputted by systems.
Emit events based on changes on the Asset Register
Applications can subscribe to changes on the Asset Register (WIP)
The Core provides a blockchain-like transaction experience without the need for network consensus, resulting in improved performance and cost-effectiveness. A user can build relationships between assets using which are explicitly created and deleted via a signed Asset Register Transaction. Transactions can succeed or fail and will emit events accordingly. We have built infrastructure to query transactions; a block explorer could effectively be built on top of this data.
The API is used for submitting transactions to the Asset Register Core, querying transaction results, and, most importantly, viewing the . Schema creation and registration also occur via this service, making it the platform for admin-level interactions by asset creators.
Create between assets that are either s or s
Generate an describing the links
Schemas play a pivotal role in the Asset Register ecosystem. They exist within a specific namespace and provide a comprehensive description of an asset. The goal is to define the capabilities of an asset for linking, ensuring that any applications interacting with these assets can interpret and represent them correctly. These descriptions are crucial for seamless integration between various assets.
To achieve this, the Asset Register utilizes schemas. These schemas are registered both on-chain and off-chain through the Asset Register API. This process ensures that information about an asset's properties and compatibility with other assets (i.e. asset links) are globally accessible and permanently stored.
The Asset Schema is a detailed specification outlining the properties of an asset and its compatibility with other assets through asset links. These schemas should be stored in a globally accessible and permanent location. Moreover, they need to be registered against specific assets. The Asset Register facilitates the registration of these schemas, allowing Futureverse teams to store them on a dedicated namespace.
In the Asset Register, a namespace is a container for organizing and presenting schemas. It serves as a centralized mechanism to group related schemas together. This organizational approach is crucial for efficient management, preventing naming conflicts, and improving overall code organization. In the context of Futureverse, namespaces play a vital role in grouping schemas for internal use.
Asset linking is a fundamental activity within the Asset Register and is executed through transactions. This process is crucial for establishing relationships between different assets. Oracles actively monitor these transactions to ensure that asset links are consistent with the on-chain ownership of assets. This validation guarantees the integrity and accuracy of the linked assets.
Ensuring accurate ownership information within the Asset Register is paramount. The ownership status of assets correlates directly with user access. This correlation is vital for maintaining the security and integrity of the asset ecosystem. Ownership resolution mechanisms are in place to guarantee that asset ownership aligns with the specified user access.
Transactions are how actions are committed to the Asset Register. Assets are linked via transactions that are executed in an authenticated and unrepeatable manner. Every action, including those involving oracles, must be explicit. This ensures the security and transparency of the Asset Register, preventing unauthorized or duplicate actions.
Schemas need to be created to describe asset relationships. Asset Register service provides a Schema Management system to get you going.
Learning how to use the Assets API
The Asset Register is a GraphQL API that can be interacted with through existing SDKs on JavaScript environments.
React SDK
The React SDK offers a convenient way to query assets within React-based applications. It leverages React's provider and hook-based approach, simplifying asset retrieval and integration within React projects.
Core SDK
The Core SDK is designed for Node.js environments but can also be utilized in frameworks other than React. It provides a versatile means of interacting with the Assets API, offering comprehensive asset querying and manipulation functionality.
For developers seeking more customized functionality or specific use cases, direct interaction with the GraphQL API is also supported. The API is fully Relay specification compliant.
Using the API directly allows for fine-grained control over asset queries and enables the execution of custom calls.
Root and Ethereum Mainnet
Porcini and Goerli
The Asset Register documentation introduces new terminology to describe its usage. A brief review of this document before exploring guides will help you understand them better.
Assets that are created by a third party with the existence attested on a blockchain network supported by the Asset Register. The Asset Register can only interact with these assets through the interface provided by the smart contract or runtime module on the blockchain where the asset is located. Therefore, it is imperative that asset collections deployed on the respective networks adhere to the NFT specifications.
Assets that are created by a third party and attested by the third party’s system. Therefore, the third party is the creator and has superuser access over all their off-chain assets. Each asset must be registered on the Asset Register and registered against a schema to be a valid off-chain asset.
A link between two assets (parent and child) based on a relationship path e.g. equippedWith_gloves. The Asset Register uses these relationships to build the asset trees that describe an asset.
Describes the properties of an asset and its compatibility with other assets through asset links. Schemas should be stored in a globally accessible and permanent location and be registered against an asset. The Asset Register will provide internal Futureverse teams with the ability to store schemas on a Futureverse namespace.
Turtle syntax is used to create the schemas.
Describes all the nested asset links for a given asset.
There are two different types of authentication required based on the functionality you are trying to access. This guide will explain to you what they are and show you how to use them.
Sign In with Ethereum (SIWE) is used to create access tokens to communicate with the authenticated endpoints on the Asset Register API (🔒).
You can generate these tokens using this helper tool. The contents generated in the Authorization box, after you sign, should be used as the Authorization header when making API calls.
Any updates made to the asset register through a transaction (i.e. asset links) will need to be signed by a wallet, similar to any other blockchain transaction (🔑).
This guide will take you through registering schemas that are compliant with the Asset Register.
These schemas and shapes help ensure that data about assets, NFTs, and other entities adhere to the required structure and constraints.
This example defines the core classes and their hierarchies within the Futureverse framework. These definitions create a hierarchy where fv:Asset is the root, and the more specific classes like fv:NFT and fv:SFT inherit from it. Each of these asset types can be further categorized into on-chain or off-chain, depending on where the asset data is stored.
This example defines a specific instance of an OnChainNFT, called Boxer, using SHACL (Shapes Constraint Language).
sh:property:
The sh:property construct defines constraints on a particular property of a node. Inside each sh:property block, you specify details about the property, such as its path, type, cardinality, and more.
sh:maxCount and sh:minCount:
sh:maxCount 1: This specifies that the property can have at most one value. It's used to enforce uniqueness or singularity of a particular property in a node.
sh:minCount 0: This means that the property is optional (it can have zero values). If this were set to 1, the property would be required.
Together, these constraints define a property that is optional but can only occur once if present.
sh:class asm:Brain:
The sh:class property is used to enforce that the value of the property must be of a specific RDF class, in this case, asm:Brain. This ensures that the value of asm:equippedWith_brain must be an instance of the asm:Brain class.
Targeting Multiple Classes with sh:class:
You can target multiple classes by listing them in a comma-separated list within the sh:class property. For example:
This specifies that the property can be an instance of either fv:Gloves or fv:Mittens.
sh:path Property:
The sh:path statement indicates the exact RDF property within your data model that is subject to the constraints defined in the SHACL shape.
In this case, asm:equippedWith_brain is the RDF property that the shape is describing. This property might represent a relationship where a Boxer is equipped with a Brain.
This example defines Brain as a specialized type of OnChainNFT, inheriting properties and constraints from its parent classes.
the Asset Link Operations guide explains how you can sign Asset Register transactions.
Creating schemas is a two-step process. First, you must create the namespace which a schema will live under. A namespace contains a set of schemas that describe something in the same domain. For example the http://schema.futureverse.com/tnl the namespace will contain the Boxer, Gloves, HairStyle and HairDye schemas for The Next Legends.
We are creating a front-end experience to make this a lot easier instead of going through and making API calls.
A namespace can only be created if the namespace owner has been whitelisted under a domain.
This functionality is in development. In the meantime, please contact the Customer Success team via customersuccess@futureverse.com to access a namespace.
A valid SIWE token with a signature must be set as the Authorisation Header.
When you create a new schema under a pre-existing schema entity it will create a new version.
To create a schema it is the same as above. Ensure that the version is incremented by 1 otherwise, it will fail.
This guide will go into detail about querying the asset tree.
Where,
tokenId - The token ID of the NFT you want the asset tree for
collection.chainType - Either evm or root to specify where the asset lives on The Root Network we have both EVM (evm) and native substrate (root) storage, so this specifies where to look
collection.location - The location of the NFT, this is either a contract address if the chainType is evm or a collection ID (number) if the chainType is root
collection.chainId - The Chain ID of the blockchain the asset lives on
An asset must be registered to a schema in order to generate the Asset Tree.
Currently, anyone can make the call to register a collection with a schema. Eventually, this will be locked down to the owner of the on-chain collection based on the owner of the NFT contract.
Only the off-chain asset creator can register a schema to the asset.
Same as Registering an on-chain asset with a schema.
Asset links can only be executed through a transaction. This guide will specifically focus on creating these operations using the SDKs.
The user must own both assets to create links unless it is an off-chain asset, where only the creator of the child asset can create a link. Linking between assets owned on a FuturePass account and FuturePass account owner EOA is allowed. As long as the ownership resolution is satisfied links can be created across chains as well.
The first argument corresponds to the path or the subject of the link.
The second argument is the parent asset. An asset can have 0 to many links as a parent.
The third argument is the child asset. An asset can have 0 or 1 link as a child.
The user must own the parent asset to delete links.
You may have noticed that all the arguments look the same. This is because we have to be explicit with exactly which link we are deleting.
Using the above operations you can create an ARTM as follows:
In the above transaction, we are creating and then deleting the link in the same transaction. This is completely fine to do so but there is no reason to perform it other than for demonstration purposes!
Note that any invalid operation will result in the failure of the entire transaction.
Example of Assets with Schemas
Transactions are made to the Asset Register using a messaging standard designed to be human readable and familiar to blockchain users using the Ethereum message standard.
Like a traditional blockchain, the Asset Register uses nonces to prevent replay attacks. The nonce for a chain address can be queried using the Asset Register API as follows:
goes into detail about how to create and submit transactions, whereas, this guide will focus on the asset link operations in particular to help you build an asset tree.
In the following sections, we will focus on using the to create and manipulate an ARTM and its operations.
To make changes to the asset register you must make transactions using signed Ethereum messages. An Asset Register Transaction Message (ARTM) can be generated using the and looks like this:
The artm object is defined in . Therefore, signing can be done manually and then sent to the Asset Register API using the , or it can be used with the hook directly.
Under the hood, the React library uses the . This library is specifically built to enable the creation, signing, and validation of ARTMs. Creating an ARTM message is described in detail on the .
Code
Description
Scenario
FAIL_ARTM_VALIDATION (1)
Failed to verify the signature of the Asset Rights Token Metadata (ARTM).
This error occurs when the signature on the ARTM message is invalid or cannot be verified. This could happen if the ARTM message is tampered with, the signing key is incorrect, or there's an issue with the signature verification process.
INVALID_NONCE (2)
The provided nonce (a unique value used to prevent replay attacks) is invalid.
This error occurs when the provided nonce value is invalid. It could be because the nonce has already been used in a previous transaction (replay attack), the nonce value is not formatted correctly, or it's missing entirely.
FAIL_NEPTUNE_TRANSACTION (3)
An error occurred while processing the transaction on the Neptune network.
This error indicates a problem with processing the transaction on the underlying Neptune network. This could be due to network issues, errors on the Neptune side, or invalid transaction data sent to the network.
FAIL_NONCE_UPDATE (4)
Failed to update the nonce value.
This error occurs when there's an issue updating the system's internal nonce value after a successful transaction. This is typically an internal system error and might require further investigation.
INVALID_ARTM (5)
The ARTM message could not be parsed correctly.
This error occurs when the system cannot understand the format of the ARTM message. This could happen if the message is corrupted, missing required fields, or contains invalid data.
INVALID_ASSET_OWNER (6)
The ownership of the asset could not be validated.
This error occurs when the system cannot verify that the sender of the transaction is the rightful owner of the asset involved. This could be due to missing ownership information, invalid ownership claims, or conflicting ownership records.
INVALID_OPERATION (7)
The attempted operation is not allowed for this type of transaction.
This error occurs when the user tries to perform an action that's not allowed for the specific transaction type.
INVALID_ASSET_PARENT (8)
An asset cannot have multiple node parents.
This error occurs when a transaction tries to assign an asset multiple parent nodes, which is not allowed in the system.
INVALID_SIGNATURE (9)
The provided signature is invalid.
This error occurs when the signature on the transaction is invalid or cannot be verified. This could be similar to FAIL_ARTM_VALIDATION but might apply to signatures on other parts of the transaction data.
INVALID_ASSET_TYPE (10)
The type of asset is not allowed in this context.
This error occurs when the transaction involves an asset type that's not allowed for the specific operation. For example, trying to assign an SFT as a parent asset.
MAX_BALANCE_ALLOCATED (11)
The maximum balance has already been allocated for the Security Fungible Token (SFT).
This error occurs specifically for SFTs (Semi-Fungible Tokens) and indicates that the transaction would exceed the maximum allowed balance for that particular SFT.
PARENT_PATH_IN_USE (12)
The chosen path is already in use on the parent asset.
This error occurs when a transaction tries to assign a path to an asset that's already in use by another child asset under the same parent. This ensures a hierarchical structure with unique paths for child assets.
FAIL_LINK_VALIDATION (13)
The information provided for linking assets failed validation.
This error occurs when the information provided for linking assets (like target asset or link type) is invalid or doesn't meet the system's requirements.
ASSET_ALREADY_LINKED (14)
The asset is already linked.
This error occurs when a transaction tries to link an asset that's already linked to another asset. Linking can only be done once for an asset.
Like a blockchain, Asset Register is event driven and therefore subscribers must be given real time feedback on what is happening so they can react to them.
When you subscribe to an event you will receive the full transaction that includes the event you are interested in.
Like any other webhook subscription, the Asset Register Subscription Service will forward the events via a POST request with the API_KEY set in the headers, ensuring the origination of the request.
If an event delivery to a webhook endpoint is attempted and an error occurs, the following takes place:
Events associated with error codes 409, 429, and 5xx are retried.
Events associated with error codes 1xx, 2xx, 3xx, and 4xx (excluding 429) are not retried.
We read the standard HTTP response header Retry-After to determine how long to wait before making a follow-up request. We then choose the more conservative value between the defined retry policy and the Retry-After header. If Retry-After value is negative, the event will not be retried.
You must send a valid SIWE token for the following interactions. Please see Admin Authentication.
The following mutations demonstrate the main use cases. However, additional mutations for managing endpoints are available. To explore the complete set of mutations, refer to the GraphQL playground by navigating to the GraphQL URL in your browser.
Before you can create a subscription, a webhook endpoint must be created. This will point all the subscriptions to the correct URL and will set you up with an API Key for request authentication.
The retries property determines the number of times the webhook endpoint will be retried before stopping. The maximum allowable number of retries is set at 20.
The webhookId from the response should be used whenCreating a subscription.
You can use the following queries to get subscription resources created by the requester:
webhookEndpoint
webhookEndpoints
webhookSubscription
webhookSubscriptions
Off-chain assets, as the name implies, lives on an off-chain database and ownership is managed by the creator.
Off-chain assets need to be globally unique and identifiable just like on-chain assets. To achieve this for Futureverse assets, we have built an off-chain ownership repository to register any off-chain assets against the Asset Register.
Creator ID
Randomly generated UUID for the creator. This will be provided to you and only you will be able access it.
40877d72-9957-4de7-af77-1ee9f54a529e
Creator Collection ID
A creator’s collection ID. This should be unique for each creator. It can be any string.
12 | pb_1232124| bedde205-5af2-423b-9092-088c8951a2ea
Token ID (optional)
The token ID is for uniquely identifying NFT assets in a collection. It will be empty if it is SFT (ERC1155 equivalent). This can be any string (like a UUID), however, it is best practice to stick to a number.
4637 | 61d21cf3-6e0d-4b9d-a2c8-55583eb81a84
Asset ID
This is the combination of creatorAddress,creatorCollectionId & tokenId. SFT assets will not have a Token ID.
40877d72-9957-4de7-af77-1ee9f54a529e:12:4637
Since ownership resolution needs to be globally unique we can use the did:fv-asset DID method directly with the already globally unique Asset ID.
did:fv-asset:off-chain:40877d72-9957-4de7-af77-1ee9f54a529e:12:4637
Just like on-chain assets which are classified as ERC721 (NFT) and ERC1155 (equivalent to an SFT), off-chain assets can be defined in the same way.
A unique asset just like ERC721.
off-chain:{creatorId}:{creatorCollectionId}:{tokenId}
For example: off-chain:40877d72-9957-4de7-af77-1ee9f54a529e:12:4637
A collection that can store an infinite amount of assets defined by the same asset ID.
off-chain:{creatorId}:{creatorCollectionId}
For example: off-chain:40877d72-9957-4de7-af77-1ee9f54a529e:12
Unlike creating assets on the chain, off-chain assets must be registered with the Asset Register before they can then be registered with the schema.
Assuming the schema for the off-chain asset is already created, the following illustrates the process of fully registering a new off-chain asset with the Asset Register to generate an asset tree.