The Hedera NFT SDK for JavaScript is a set of tools and resources developers can use to build NFT-related software or perform NFT-related actions. The goal of the Hedera NFT SDK is to make it easier for builders and artists to implement standard NFT features, such as calculating risk and rarity, or perform NFT tasks, such as verifying NFT metadata against a schema specification like HIP412.
By providing several helpful NFT utilities, we want to support the Hedera NFT community in building faster, more, and better NFT projects. Instead of building your own NFT tooling, you can make use of the building blocks provided by the Hedera NFT SDK.
The project aims to evolve the Hedera NFT SDK based on community feedback to make it an excellent tool for NFT creators on the Hedera network.
In this blog post, you'll learn:
This package offers a comprehensive set of tools for the Hedera NFT ecosystem, with some features available exclusively in Node.js. Below is an overview of the primary functionalities:
Because the package is created with JavaScript, you can use NPM or Yarn package managers to install the SDK.
npm i -s @hashgraph/hedera-nft-sdk
Next, you can import the functionality you need. Let's look at each functionality individually to see what you can do and how it works.
The SDK offers multiple consensus node functions. Let's look at the main function you can use to validate metadata against the HIP412 standard.1. "Validator()"
const { Validator, defaultSchemaVersion } = require('@hashgraph/hedera-nft-sdk'); // Valid metadata instance const metadataInstance = { "creator": "HANGRY BARBOONS", "description": "HANGRY BARBOONS are 4,444 unique citizens from the United Hashgraph of Planet Earth. Designed and illustrated by President HANGRY.", "format": "none", "name": "HANGRY BARBOON #2343", "image": "ipfs://QmaHVnnp7qAmGADa3tQfWVNxxZDRmTL5r6jKrAo16mSd5y/2343.png", "type": "image/png", "properties": { "edition": 2343 }, "attributes": [ { "trait_type": "Background", "value": "Yellow" }, { "trait_type": "Fur", "value": "Gold" }, { "trait_type": "Clothing", "value": "Floral Jacket" }, { "trait_type": "Mouth", "value": "Tongue" }, { "trait_type": "Sing", "value": "None" } ] } const validator = new Validator(); const results = validator.validate(metadataInstance); // by default: verifies metadata against [email protected] console.log(results); /* Output: { errors: [], warnings: [] } */
The Validator() function accepts stringified metadata and a version number. The version number refers to a specific version of HIP412 you want to verify your metadata against. Currently, you can import the "defaultVersion" parameter, which refers to the latest version of the HIP412 specification (HIP412 v2.0.0).
The Validator() function outputs both errors and warnings. Errors refer to mistakes against the HIP412 standard, while warnings are related to additional properties on the JSON object not specified by the HIP412 metadata standard. According to the standard, any additional properties should be included in the "properties" object to keep the JSON object tidy and easy to interpret.
The risk score calculation functions allow you to calculate the risk score for a token based on the token information by looking at the keys that are set for the token. The presence of each key has an associated risk. For instance, the presence of an admin key is one of the highest risks for a token holder. The admin key can update the properties of the token or delete the token. To calculate the risk score, each key or property receives a "weight". By adding all weights, you get a final risk score for a token. Here's the overview of all the weights.
const defaultWeights = { keys: { admin_key: 200, metadata_key: 200, wipe_key: 200, freeze_key: 50, supply_key: 20, kyc_key: 50, pause_key: 50, fee_schedule_key: 40 }, properties: { supply_type_infinite: 20 } }
First, let's look at the different keys and why they received their respective weight.
Next, let's look at property-specific weights:
To determine the risk level, there are four categories each with an attached score. If the score is lower than or equal to a risk level, it will get that risk level. For the "HIGH" risk level, everything from 200 and above is considered a high risk NFT collection.
const defaultRiskLevels = { NORISK: 0, LOW: 40, MEDIUM: 199, HIGH: 200 };
There are two functions you can use to calculate the risk score. You can either input the token data yourself or provide a token ID. When you provide a token ID, the function will look up the token metadata on the mainnet and calculate the risk score and level.
const { calculateRiskScoreFromData, calculateRiskScoreFromTokenId } = require('@hashgraph/hedera-nft-sdk'); const results = await calculateRiskScoreFromTokenId("0.0.1270555"); console.log(results); /* Output: { riskScore: 20, riskLevel: 'LOW' } */
The "calculateRarity" function allows you to calculate the rarity of a folder on your machine containing JSON metadata files for an NFT collection. The function looks at the traits listed in the "attributes" property and their respective values to calculate the rarity score for each NFT (metadata file). This package uses the trait normalization rarity scoring model because it's the fairest model to calculate rarity. The model works by dividing the number one by the division of the number of NFTs with a specific trait value and the number of NFTs with the most common trait value for that trait. Here's the formula:
1 / (# of NFTs with trait value / # of NFTs with most common trait value)
Import the function and pass it an absolute path to the folder containing JSON metadata files.
const { calculateRarity } = require('@hashgraph/hedera-nft-sdk'); const myFilesPath = "./files"; const results = calculateRarity(myFilesPath); console.log(results);
The function will output the rarity for each file. The output looks like this.
[ { rarity: '5.50', NFT: 1, filename: 'nft1.json' }, { rarity: '6.00', NFT: 2, filename: 'nft2.json' }, { rarity: '5.50', NFT: 3, filename: 'nft3.json' }, { rarity: '5.50', NFT: 4, filename: 'nft4.json' }, { rarity: '11.50', NFT: 5, filename: 'nft5.json' } ]
If you have feature requests or want to submit feedback, please open an issue on the GitHub repository for the project.