npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@magnify-cash/nft-lists

v0.0.1

Published

📫 The NFT Lists specification

Downloads

31

Readme

@magnify-cash/nft-lists

This package includes a JSON schema for NFT lists, and TypeScript utilities for working with NFT lists.

The JSON schema represents the technical specification for an NFT list which can be used in a dApp interface, such as the Magnify Cash Interface.

This work stands on the shoulders of Uniswap Labs and their work for an ERC20 token specification in Token Lists

What are nft lists?

Magnify Cash NFT Lists is is a specification for lists of NFT metadata (e.g. address, decimals, ...) that can be used by any dApp interfaces that needs one or more lists of NFTs.

Specifically an instance of a NFT list is a JSON blob that contains a list of ERC721 or ERC1155 NFT metadata for use in dApp user interfaces.

NFT list JSON must validate against the JSON schema in order to be used in the Magnify Cash Interface. NFTs on NFT lists, and NFT lists themselves, are tagged so that users can easily find NFTs.

JSON Schema $id

The JSON schema ID is http://magnify-cash.io/tokenlist.schema.json

Validating NFT lists

This package does not include code for NFT list validation. You can easily do this by including a library such as ajv to perform the validation against the JSON schema. The schema is exported from the package for ease of use.


import { schema } from '@magnify-cash/nft-lists'
import Ajv from 'ajv'
import addFormats from 'ajv-formats'
import fetch from 'node-fetch'

const ARBITRUM_LIST = "TODO"

async function validate() {
  const ajv = new Ajv({ allErrors: true, verbose: true })
  addFormats(ajv)
  const validator = ajv.compile(schema);
  const response = await fetch(ARBITRUM_LIST)
  const data = await response.json()
  const valid = validator(data)
  if (valid) {
  return valid
  }
  if (validator.errors) {
  throw validator.errors.map(error => {
    delete error.data
    return error
  })
  }
}

validate()
  .then(console.log("Valid List."))
  .catch(console.error)

Authoring NFT lists

Manual

The best way to manually author NFT lists is to use an editor that supports JSON schema validation. Most popular code editors do, such as IntelliJ or VSCode. Other editors can be found here.

The schema is registered in the SchemaStore, and any file that matches the pattern *.nftlist.json should automatically utilize the JSON schema for the supported text editors.

In order for your NFT list to be able to be used, it must pass all JSON schema validation.

Automated

If you want to automate NFT listing, e.g. by pulling from a smart contract, or other sources, you can use this npm package to take advantage of the JSON schema for validation and the TypeScript types. Otherwise, you are simply working with JSON. All the usual tools apply, e.g.:

import { NFTList, schema } from '@magnify-cash/nft-lists'

// generate your nft list however you like.
const myList: NFTList = generateMyNFTList();

// use a tool like `ajv` to validate your generated nft list
validateMyNFTList(myList, schema);

// print the resulting JSON to stdout
process.stdout.write(JSON.stringify(myList));

Semantic versioning

Lists include a version field, which follows semantic versioning.

List versions must follow the rules:

  • Increment major version when NFTs are removed
  • Increment minor version when NFTs are added
  • Increment patch version when NFTs already on the list have minor details changed (name, symbol, logo URL, decimals)

Changing a NFT address or chain ID is considered both a remove and an add, and should be a major version update.

Note that list versioning is used to improve the user experience, but not for security, i.e. list versions are not meant to provide protection against malicious updates to a NFT list; i.e. the list semver is used as a lossy compression of the diff of list updates. List updates may still be diffed in the client dApp.

Deploying your list

Once you have authored the list, you can make it available at any URI. Prefer pinning your list to IPFS (e.g. via pinata.cloud) and referencing the list by an ENS name that resolves to the contenthash.

If hosted on HTTPS, make sure the endpoint is configured to send an access-control-allow-origin header to avoid CORS errors.

Linking an ENS name to the list

An ENS name can be assigned to an IPFS hash via the contenthash text record. This is the preferred way of referencing your list.

Examples

You can find a simple example of a nft list in test/schema/example.nftlist.json.

A snapshot of the Magnify Cash default list encoded as a nft list is found in test/schema/bigexample.nftlist.json.