nft-auth-js v1.0.4

👾 NFT Auth JS

This repository contains the library for implementing NFT auth in javascript applications.

Table of contents

1. 🔨 Installation
2. 📚 Methods
3. 🚀 Use cases

🔨 Installation

The package is freely available on npm, so you just need to install it using your package manager:

npm install nft-auth-js
yarn add nft-auth-js

📚 Methods

These are the methods supported by the library.

constructor(options: NFTAuthOptions, contracts: NFTAuthContract[])

Creates a new instance of NFTAuth in your project; the package comes both as a ES6 and CommonJS module, ready to be used in both React and NodeJS applications.

/* ES6 module */
import { NFTAuth } from 'nft-auth-js';

/* CommonJS module */
const { NFTAuth } = require('nft-auth-js');

// initialize with provider
const nftAuth = new NFTAuth({ provider: 'https://YOUR_PROVIDER_HERE' });
// initialize with web3 instance
const nftAuth = new NFTAuth({ web3: new Web3('https://YOUR_PROVIDER_HERE') });
// initialize with contracts too
const nftAuth = new NFTAuth({ web3: new Web3('https://YOUR_PROVIDER_HERE') }, [{ address: '0x0...', abi: { } }]);

This method fails if no provider or web3 is provided during initialization.

addContract(address, abi)

Adds the contract with the given address and abi to the NFTAuth instance.

// some code here with NFTAuth initialization

nftAuth.addContract('0x0....', CONTRACT_ABI);

This method fails if no address or ABI are provided.

getERC721Owned(address: string, contractAddress: string, options: ERC721OwnershipOptions)

Returns a list of tokenId owned by the wallet with the given address in the ERC721 contract provided.

// some code here with NFTAuth initialization with contracts

const ids = await nftAuth.getERC721Owned('0x0...', '0x0...');
console.log(ids);
// [0, 1, 2, ...]

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options described below are wrong.

You can also pass a third parameter (optional if you are using the standard ERC721 interface) containing an object of options with the following schema:

interface ERC721OwnershipOptions {
    transferEvent?: string; // ERC721 transfer event name (default: 'Transfer')
    toParam?: string; // ERC721 transfer to parameter (default: 'to')
    tokenIdParam?: string; // ERC721 transfer tokenId parameter (default: 'tokenId')
    balanceOfFunc?: string; // ERC721 balanceOf function name (default: 'balanceOf')
    fromBlock?: number | string; // events retrieval start block (default: 0)
    toBlock?: number | string; // events retrieval end block (default: 'latest')
}

This options allows for custom-made ERC721 contracts to be supported by this library and are the same for all the ERC721 methods.

getERC1155Owned(address: string, contractAddress: string, options: ERC1155OwnershipOptions)

Returns a list of tokenId owned by the wallet with the given address in the ERC1155 contract provided.

// some code here with NFTAuth initialization with contracts

const ids = await nftAuth.getERC1155Owned('0x0...', '0x0...');
console.log(ids);
// [0, 1, 2, ...]

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options described below are wrong.

You can also pass a third parameter (optional if you are using the standard ERC1155 interface) containing an object of options with the following schema:

interface ERC1155OwnershipOptions {
    transferSingleEvent?: string; // ERC1155 transfer single event name (default: 'TransferSingle')
    transferBatchEvent?: string; // ERC1155 transfer batch event name (default: 'TransferBatch')
    toParam?: string; // ERC1155 to parameter (default: 'to')
    tokenIdParam?: string; // ERC1155 transfer single token id param (default: 'id')
    tokenIdsParam?: string; // ERC1155 transfer batch token ids param (default: 'ids')
    balanceOfFunc?: string; // ERC1155 single balance function name (default: 'balanceOf')
    balanceOfBatchFunc?: string; // ERC1155 batch balance function name (default: 'balanceOfBatch')
    fromBlock?: number | string; // events retrieval start block (default: 0)
    toBlock?: number | string; // events retrieval end block (default: 'latest')
}

This options allows for custom made ERC1155 contracts to be supported by this library and are the same for all the ERC1155 methods.

verifyERC721Ownership(address: string, contractAddress: string, options: ERC721OwnershipOptions)

Returns true if the given address owns at least 1 ERC721 token from the contract provided.

// some code here with NFTAuth initialization with contracts

const isERC721Owner = await nftAuth.verifyERC721Ownership('0x0...', '0x0...');
console.log(isERC721Owner);
// true/false

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options are wrong.

verifyERC721OwnershipWithSig(signedMessage: string, message: string, contractAddress: string, options: ERC721OwnershipOptions)

Returns true if the address recovered from the given signedMessage owns at least 1 ERC721 token from the contract provided. This method under the hood calls the verifyERC721Ownership one, so all the above applies to this method too.

// some code here with NFTAuth initialization with contracts

const isERC721Owner = await nftAuth.verifyERC721OwnershipWithSig('0x0...', 'Hello world!');
console.log(isERC721Owner);
// true/false

verifyERC1155Ownership(address: string, contractAddress: string, options: ERC1155OwnershipOptions)

Returns true if the given address owns at least 1 ERC1155 NFT token (balance === 1) from the contract provided.

// some code here with NFTAuth initialization with contracts

const isERC1155Owner = await nftAuth.verifyERC1155Ownership('0x0...', '0x0...');
console.log(isERC1155Owner);
// true/false

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options are wrong.

verifyERC1155OwnershipWithSig(signedMessage: string, message: string, contractAddress: string, options: ERC1155OwnershipOptions)

Returns true if the address recovered from the given signedMessage owns at least 1 ERC1155 NFT token (balance === 1) from the contract provided. This method under the hood calls the verifyERC1155Ownership one, so all the above applies to this method too.

// some code here with NFTAuth initialization with contracts

const isERC1155Owner = await nftAuth.verifyERC1155OwnershipWithSig('0x0...', 'Hello world!');
console.log(isERC1155Owner);
// true/false

countERC721Owned(address: string, contractAddress: string, options: ERC721OwnershipOptions)

Returns the number of ERC721 tokens owned by the given address. This method under the hood calls getERC721Owned.

// some code here with NFTAuth initialization with contracts

const erc721Count = await nftAuth.countERC721Owned('0x0...', '0x0...');
console.log(erc721Count);
// 2

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options are wrong.

countERC1155Owned(address: string, contractAddress: string, options: ERC1155OwnershipOptions)

Returns the number of ERC1155 NFT tokens (balance === 1) owned by the given address. This method under the hood calls getERC1155Owned.

// some code here with NFTAuth initialization with contracts

const erc1155Count = await nftAuth.countERC1155Owned('0x0...', '0x0...');
console.log(erc1155Count);
// 2

This method fails if the contractAddress is referring to a contract not added during initialization or via the addContract method or if some parameters provided in the options are wrong.

🚀 Use cases

This is a short and not exaustive list of when the usage of this library comes in handy.

Restricted access

By using this library you can authorize a given address to perform certain operations in your business logic by just writing literally 2 lines of code. These are some examples for you:

• Authorize the wallet if it owns at least 1 ERC721 token (verifyERC721Ownership method);
• Authorize the wallet if it has at least 10 ERC721 tokens (countERC721Owned method);
• Authorize the wallet if it owns specific ERC721 token ids (getERC721Owned method).

NFT retrieval

If you need to retrieve in your project all the tokenIds of a contract that a given address owns you can simply use the getERC721Owned or getERC1155Owned instead of always duping the same logic everytime: it does really saves you time.