Guide 1 : Make your Regular NFT Collection to be Data NFT-PH Compatible

Are you planning on minting a regular NFT collection for your project? If so, then consider making your NFT Collection Data NFT Compatible. This is possible thanks to a Data NFT type called Data NFT-PH (Plug-In Hybrid).

Data NFT-PH is for projects that want to launch their own fully controlled NFT collections independently via an NFT Launchpad, CandyMachine or via a regular mint, but would like to provide a "plug-in" interface for their regular NFTs also to be used as "hybrid Data NFTs", immediately making your NFT collection compatible with Itheum's vision for data ownership and also the Itheum's entire ecosystem of tools and community - and bringing a new dimension of utility for your original NFT and boosting community activation/engagement/loyalty that's built on the principals of "data ownership." Firstly, you should learn about all the benefits of Data NFT-PH collection in theData NFT-PH (Plug-In Hybrid) product section docs. Next, in this guide, we will walk you through the 3 step process of making your NFT collection Data NFT-PH compatible!

🏁 🏎️ Ready to start? Here are a few assumptions and pre-conditions

• You need @itheum/sdk-data-marshal-network v1.0.0 or above to follow this guide.

• This guide assumes that you can add a few "custom metadata attribute fields" on your NFT's JSON metadata files stored in IPFS, Arweave or any NFT metadata storage you use.

• This guide also assumes that your Data Stream (the data the Data NFT-PH will unlock) can provide some simple "access control" or "authentication" by using a MultiversX Native Auth Protected API as your Data Stream origin.

• The Data NFT-PH standard is available in Mainnet Beta mode, where it provides all the below-described functionality, but it currently does NOT support static Data Streams (i.e. static files that never change) and will require your Data Stream to be dynamic and served via a "server" or "service" where you can handle some simple "access control" or "authentication". The goal is to have future versions of Data NFT-PHs to support BOTH static and dynamic Data Streams.

To make the guide more practical, let's first detail the real-world user story that we will aim to achieve by following this guide.

Target User Story:

Step 1: Prepare and Launch your Public Data Stream

Data NFTs, in essence, are regular NFTs that are "connected" to a "Data Stream."

In the current version of Data NFT-PH, the Data Stream should be dynamic, showing data that is updating in real-time or during some schedule that triggers the data update (every hour, every day, every week, etc). The Data Stream can be fully open and public or have "MultiversX Native Auth authenticated" and should be served as an HTTPS URL. The complete requirements for a Data Stream URLs are detailed here: Data Stream URL Rules Let's assume the Data Stream URL is just a backend authenticated API, similar to this sample API: https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo (It's important to note that this sample API gives you a "Access Forbidden as this is a protected Data Stream. No credentials sent!" message. This is expected as the API is protected by MultiversX Native Auth and is missing an access token, more on this later) As in the user story above, we are minting a 10k NFT collection. So we can have 10k variations of the same Data Stream URL. e.g.

But as the Data Stream URL (once encrypted) will need to be inserted as an NFT Attribute on each token, as you can see, it's probably not the most optimized to have a Data Stream URL for each NFT as this will require a lot more processing to encrypt and store during the mint process but also as it's not easy to know information like final NFT IDs during a mint.

So, it's recommended that you have a single, smart Data Stream URL that is the same for all NFT tokens but implements a "MultiversX Native Auth wrapper." Native Auth is simply a "signature" based authentication system where you can validate the "caller" wallet address. By doing this, the Data Stream can unpack the Native Auth token, get the caller address "identity," and use it to personalize the Data Stream response.

The Data Stream also passes through the Data Marshal network, injecting additional metadata like NFT Token ID into your Data Stream URL. With both the metadata from the validated Native Auth token and the additional metadata from the Data Marshal, you will be able to have access to validated information like authenticated caller address, ownership validated Data NFT ID, chain ID, etc., and use this to "real-time" personalize each Data Stream URL for each NFT.

So, with this approach, you can have the same Data Stream URL for all your tokens :

At the end of this step, you should have a public, Native Auth-protected API that you can use as the Data Stream URL for all the NFT tokens in your collection. Your new API should be similar to https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo

Once you have this Data Stream URL, just one more step is required to make your new NFT collection, Data NFT-PH compatible.

Step 2: Include Custom Attributes in your NFT's Metadata File

Adding Data NFT compatibility to a regular NFT token is achieved by including some "custom metadata attribute fields" in your NFT's JSON Metadata file. It should be noted that these Attributes are "non-sensitive" (i.e. not sensitive data like keys or identity etc).

2.1) Get a Data Marshal Network-compatible encrypted Data Stream URL for the data_stream_url token Attribute:

You can do this via a simple node.js script and by using our Data Marshal Network SDK.

Install the SDK:

npm install --save @itheum/sdk-data-marshal-network

then write a simple node.js script (e.g. job.js) which has the following code and run it locally via node job.js

const { DataMarshal } = require("@itheum/sdk-data-marshal-network");

async function runJob() {
  // Initialization
  const dataMarshal = new DataMarshal("devnet"); // or "mainnet" based on where you are minting

  /* Get your encrypted Data Stream URL:
  Param 1: is your clear text, Data Stream URL that will be encrypted by the Data Marshal network
  
  Param 2: This can be thought of as the "creator" or "owner" of the  Data Stream URL. In this case, it is "erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7". Note that this needs to be a valid MultiversX Wallet or the method will fail with an error similar to 'Error: Issue with data marshal generating payload'. 
  
  IMPORTANT!!! you need to make sure that you use this EXACT SAME Param 2 value, (i.e. "creator" or "owner" of the Data Stream URL) as the "itheum_creator" NFT attribute in the NFT metadata file, or else the Data Marshal network will not allow for the Data Stream to be viewed.
  */
  const encryptPayload = await dataMarshal.encryptDataStream(
    "https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo",
      "erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7"
    );

  console.log(encryptPayload);

  /*
  console logged value:
  {
    messageHash: '9ae257fd4014bc84b35692832ac49a30d140712d2b0d4c53726d7847bf3d1378',
    dataStreamEncrypted: 'eyJBIjoiOWFlMjU3ZmQ0MDE0YmM4NGIzNTY5MjgzN2JiMmE3MjEzODhkZTkxMGEzMGYyZTcwIiwiQiI6IjllZDM1NTFjMmRkZmYwOTFhNWRlOWI4YTUyMTIyNTkzYTQ3NzViZDkwZTg3ZDNiMjE0NDU0N2VhNzMxOGRiOGMiLCJDIjoiMDZiNWRkYjlhNjA1NzcyNWQ5NzdkMDdhOGUwZTFmZmJmMTUwYjdmNTY3ZGNiOWZiMmE0OThlZDc5OTQzNGMwZCIsIkQiOiJkMWY2NTJhMWZkZGRkOTY4MzdmODEzNjU5YzlmM2EwNGRiMDE3Nzc3ZDkxMDA1YWU2ODI2ZjdkMzZhNGE0YmRmYjM3NzA1MTZiZTg2YzQ3YjkxOWUwODFlNjU2YjY2MGQ0MWViZDJjOGRhOGZlZTcwN2QyZDkyMzY2NTkzMzUyYTM0ODhmMmU3NTRjYjk5NzYwMDgxMmNkZjI5NTZhMjRlZmU1NzdiOWUxODkxMzY3MmNhZGE4Mjc3N2M3NWMwZTg4YmIyMjA4NjQwNDcwNjczYTRmNjA4YzNhMGFmYzExNGUxNDA5YzQ0N2FjZDUxYTkyZjcxZjgxZDFlNDY3Zjc1MmEzNGZkM2U4ZTdkNzQ2NDFjZTQzY2YwMTg3OTA4YzY5YzU1NmZjODA4YjUxNzkwMzU0MDc4YWMyZDZjZTcxMjdjZGUxNDY0YjljM2Q1NDgxNjA3YjI1MjVlYzhjOThiZWY2ZmMwNTUxNjVmMzExYmU3MGVjNGI1NThhOTA4MDQ2MDU5ZGU1M2FhOTEzZGIwZDgwMzFlYTBhMTFlYWFiZjBjZmViOWJmYzgwMDhjNzc4YzIyNzY4ZGU1ZmFkYzBlIiwiRSI6Ijc1MWY4NjgzMjYxN2U0MGMwZmJlYTM3MDFmMzM3NGVlMDM5MmEzN2Y0MzA2ODU4NThiNjIzMDVlOTA1MWI5YTE1ODg0ZDFmNTRiMDNlYTk5MTM2NTc3YWRjYzgyYWQ3N2FiOTczZjZjNGFiMGRhMWZmNDNmNDI2NTE1NWRiZDBmIn0='
  }
  
  - messageHash is a unique hash you can use to identify your Data Stream URL (you can use this as a "provenance" ID of sorts if needed)
  - dataStreamEncrypted is the value you need to use for the "itheum_data_stream_url" NFT Attribute
  */
}

runJob();

... now that you have an encrypted "itheum_data_stream_url" value, we can proceed with the next steps.

2.2) Adding the Custom Attributes to your NFT's JSON Metadata File

As you will know, all NFT collections use a JSON Metadata file to store data about Traits, etc. On MultiversX you can view this JSON file by visiting any collection on Explorer (as an example...)

You need to add the Custom NFT Attributes described in the table above to this file. You MUST add the Mandatory fields "itheum_data_stream_url" (should be encrypted as described above), "itheum_creator" (should be the same value used in the encryption process of itheum_data_stream_url as described above), and "itheum_data_marshal_url" (use latest devnet or mainnet values as per Data Marshal Node Gateway Endpoints).

The remaining "itheum_[*]" fields are optional but recommended.

Once you add the custom fields, your JSON Metadata file should look EXACTLY like this:

Note that the custom fields MUST be on the "top-level" - e.g. on the same level as "name", "description", "attributes" etc. If they are NOT on the "top-level" it will NOT work.

Step 3: Enable Basic "NFT Collection Token ID Verification" in your Origin Data Stream Service

The final step is to include some basic NFT Collection Token ID verification in your MultiversX Native Auth Protected API Data Stream origin, this is only needed as we are in a Mainnet Beta mode and aims to provide some extra authentication layer to ensure that only your Data NFT-PH collection holders can open and view your data stream. The logic is fairly simple, and is shown in this code example (in red box)

This code is from the open-source MultiversX Native Auth Protected API template we provide, you can check out the code here