@alephium/web3 0.13.0 → 0.14.1

package/dist/src/api/node-provider.d.ts

@@ -1,4 +1,4 @@
-import { ApiRequestArguments, ApiRequestHandler, FungibleTokenMetaData, NFTMetaData } from './types';
+import { ApiRequestArguments, ApiRequestHandler, FungibleTokenMetaData, NFTMetaData, NFTCollectionMetaData } from './types';
 import { Api as NodeApi } from './api-alephium';
 import { HexString } from '../contract';
 interface NodeProviderApis {
@@ -34,7 +34,9 @@ export declare class NodeProvider implements NodeProviderApis {
     static Remote(handler: ApiRequestHandler): NodeProvider;
     fetchFungibleTokenMetaData: (tokenId: HexString) => Promise<FungibleTokenMetaData>;
     fetchNFTMetaData: (tokenId: HexString) => Promise<NFTMetaData>;
+    fetchNFTCollectionMetaData: (contractId: HexString) => Promise<NFTCollectionMetaData>;
     guessStdInterfaceId: (tokenId: HexString) => Promise<HexString | undefined>;
+    guessFollowsNFTCollectionStd: (contractId: HexString) => Promise<boolean>;
     guessStdTokenType: (tokenId: HexString) => Promise<'fungible' | 'non-fungible' | undefined>;
 }
 export {};

package/dist/src/api/node-provider.js

@@ -65,6 +65,17 @@ class NodeProvider {
                 collectionAddress: (0, utils_2.addressFromContractId)(result.results[1].returns[0].value)
             };
         };
+        // Only use this when the contract follows the NFT collection interface, check `guessFollowsNFTCollectionStd` first
+        this.fetchNFTCollectionMetaData = async (contractId) => {
+            const address = (0, utils_2.addressFromContractId)(contractId);
+            const group = (0, utils_2.groupOfAddress)(address);
+            const calls = Array.from([0, 1], (index) => ({ methodIndex: index, group: group, address: address }));
+            const result = await this.contracts.postContractsMulticallContract({ calls });
+            return {
+                collectionUri: (0, utils_2.hexToString)(result.results[0].returns[0].value),
+                totalSupply: BigInt(result.results[1].returns[0].value)
+            };
+        };
         this.guessStdInterfaceId = async (tokenId) => {
             const address = (0, utils_2.addressFromTokenId)(tokenId);
             const group = (0, utils_2.groupOfAddress)(address);
@@ -78,12 +89,16 @@ class NodeProvider {
                 return undefined;
             }
         };
+        this.guessFollowsNFTCollectionStd = async (contractId) => {
+            const interfaceId = await this.guessStdInterfaceId(contractId);
+            return interfaceId === types_1.StdInterfaceIds.NFTCollection;
+        };
         this.guessStdTokenType = async (tokenId) => {
             const interfaceId = await this.guessStdInterfaceId(tokenId);
             switch (interfaceId) {
-                case '0001':
+                case types_1.StdInterfaceIds.FungibleToken:
                     return 'fungible';
-                case '0003':
+                case types_1.StdInterfaceIds.NFT:
                     return 'non-fungible';
                 default:
                     return undefined;

package/dist/src/api/types.d.ts

@@ -30,6 +30,11 @@ export interface ApiRequestArguments {
 export type ApiRequestHandler = (args: ApiRequestArguments) => Promise<any>;
 export declare function forwardRequests(api: Record<string, any>, handler: ApiRequestHandler): void;
 export declare function request(provider: Record<string, any>, args: ApiRequestArguments): Promise<any>;
+export declare enum StdInterfaceIds {
+    FungibleToken = "0001",
+    NFTCollection = "0002",
+    NFT = "0003"
+}
 export interface FungibleTokenMetaData {
     name: string;
     symbol: string;
@@ -40,3 +45,7 @@ export interface NFTMetaData {
     collectionAddress: string;
     tokenUri: string;
 }
+export interface NFTCollectionMetaData {
+    collectionUri: string;
+    totalSupply: Number256;
+}

package/dist/src/api/types.js

@@ -17,7 +17,7 @@ You should have received a copy of the GNU Lesser General Public License
 along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.request = exports.forwardRequests = exports.typeLength = exports.fromApiVal = exports.fromApiArray = exports.fromApiVals = exports.toApiVal = exports.toApiArray = exports.toApiAddress = exports.toApiByteVec = exports.fromApiNumber256 = exports.toApiNumber256Optional = exports.toApiNumber256 = exports.toApiBoolean = exports.fromApiTokens = exports.fromApiToken = exports.toApiTokens = exports.toApiToken = void 0;
+exports.StdInterfaceIds = exports.request = exports.forwardRequests = exports.typeLength = exports.fromApiVal = exports.fromApiArray = exports.fromApiVals = exports.toApiVal = exports.toApiArray = exports.toApiAddress = exports.toApiByteVec = exports.fromApiNumber256 = exports.toApiNumber256Optional = exports.toApiNumber256 = exports.toApiBoolean = exports.fromApiTokens = exports.fromApiToken = exports.toApiTokens = exports.toApiToken = void 0;
 const utils_1 = require("../utils");
 utils_1.assertType;
 function toApiToken(token) {
@@ -257,3 +257,9 @@ async function request(provider, args) {
     return call(...args.params);
 }
 exports.request = request;
+var StdInterfaceIds;
+(function (StdInterfaceIds) {
+    StdInterfaceIds["FungibleToken"] = "0001";
+    StdInterfaceIds["NFTCollection"] = "0002";
+    StdInterfaceIds["NFT"] = "0003";
+})(StdInterfaceIds = exports.StdInterfaceIds || (exports.StdInterfaceIds = {}));

package/dist/src/api/utils.d.ts

@@ -1,5 +1,6 @@
 import 'cross-fetch/polyfill';
 export declare function convertHttpResponse<T>(response: {
+    status: number;
     data: T;
     error?: {
         detail: string;

package/dist/src/api/utils.js

@@ -23,7 +23,8 @@ const utils_1 = require("../utils");
 const async_sema_1 = require("async-sema");
 function convertHttpResponse(response) {
     if (response.error) {
-        throw new Error(`[API Error] - ${response.error.detail}`);
+        const errorMessage = response.error.detail ?? `status code: ${response.status}`;
+        throw new Error(`[API Error] - ${errorMessage}`);
     }
     else {
         return response.data;

package/dist/src/token/nft.d.ts

@@ -1,10 +1,24 @@
+import 'cross-fetch/polyfill';
 export interface NFTMetadata {
     name: string;
-    description: string;
+    description?: string;
     image: string;
+    attributes?: [
+        {
+            trait_type: string;
+            value: string | number | boolean;
+        }
+    ];
 }
 export interface NFTCollectionMetadata {
     name: string;
     description: string;
     image: string;
 }
+export declare const validNFTMetadataFields: string[];
+export declare const validNFTMetadataAttributesFields: string[];
+export declare const validNFTMetadataAttributeTypes: string[];
+export declare const validNFTCollectionMetadataFields: string[];
+export declare function validateNFTMetadata(metadata: any): NFTMetadata;
+export declare function validateNFTCollectionMetadata(metadata: any): NFTCollectionMetadata;
+export declare function validateEnumerableNFTBaseUri(nftBaseUri: string, maxSupply: number): Promise<NFTMetadata[]>;

package/dist/src/token/nft.js

@@ -17,3 +17,103 @@ You should have received a copy of the GNU Lesser General Public License
 along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnumerableNFTBaseUri = exports.validateNFTCollectionMetadata = exports.validateNFTMetadata = exports.validNFTCollectionMetadataFields = exports.validNFTMetadataAttributeTypes = exports.validNFTMetadataAttributesFields = exports.validNFTMetadataFields = void 0;
+// JSON Schema for the NFT metadata, which is pointed to by the value
+// returned from the `getTokenUri` method of the NFT contract
+require("cross-fetch/polyfill");
+exports.validNFTMetadataFields = ['name', 'description', 'image', 'attributes'];
+exports.validNFTMetadataAttributesFields = ['trait_type', 'value'];
+exports.validNFTMetadataAttributeTypes = ['string', 'number', 'boolean'];
+exports.validNFTCollectionMetadataFields = ['name', 'description', 'image'];
+function validateNFTMetadata(metadata) {
+    Object.keys(metadata).forEach((key) => {
+        if (!exports.validNFTMetadataFields.includes(key)) {
+            throw new Error(`Invalid field ${key}, only ${exports.validNFTMetadataFields} are allowed`);
+        }
+    });
+    const name = validateNonEmptyString(metadata, 'name');
+    const description = validateNonEmptyStringIfExists(metadata, 'description');
+    const image = validateNonEmptyString(metadata, 'image');
+    const attributes = validateNFTMetadataAttributes(metadata['attributes']);
+    return { name, description, image, attributes };
+}
+exports.validateNFTMetadata = validateNFTMetadata;
+function validateNFTCollectionMetadata(metadata) {
+    Object.keys(metadata).forEach((key) => {
+        if (!exports.validNFTCollectionMetadataFields.includes(key)) {
+            throw new Error(`Invalid field ${key}, only ${exports.validNFTCollectionMetadataFields} are allowed`);
+        }
+    });
+    const name = validateNonEmptyString(metadata, 'name');
+    const description = validateNonEmptyString(metadata, 'description');
+    const image = validateNonEmptyString(metadata, 'image');
+    return { name, description, image };
+}
+exports.validateNFTCollectionMetadata = validateNFTCollectionMetadata;
+async function validateEnumerableNFTBaseUri(nftBaseUri, maxSupply) {
+    if (isInteger(maxSupply) && maxSupply > 0) {
+        const nftMetadataz = [];
+        for (let i = 0; i < maxSupply; i++) {
+            const nftMetadata = await fetchNFTMetadata(nftBaseUri, i);
+            const validatedNFTMetadata = validateNFTMetadata(nftMetadata);
+            nftMetadataz.push(validatedNFTMetadata);
+        }
+        return nftMetadataz;
+    }
+    else {
+        throw new Error('maxSupply should be a positive integer');
+    }
+}
+exports.validateEnumerableNFTBaseUri = validateEnumerableNFTBaseUri;
+function validateNFTMetadataAttributes(attributes) {
+    if (!!attributes) {
+        if (!Array.isArray(attributes)) {
+            throw new Error(`Field 'attributes' should be an array`);
+        }
+        attributes.forEach((item) => {
+            if (typeof item !== 'object') {
+                throw new Error(`Field 'attributes' should be an array of objects`);
+            }
+            Object.keys(item).forEach((key) => {
+                if (!exports.validNFTMetadataAttributesFields.includes(key)) {
+                    throw new Error(`Invalid field ${key} for attributes, only ${exports.validNFTMetadataAttributesFields} are allowed`);
+                }
+            });
+            validateNonEmptyString(item, 'trait_type');
+            validateNonEmptyAttributeValue(item, 'value');
+        });
+    }
+    return attributes;
+}
+function validateNonEmptyString(obj, field) {
+    const value = obj[`${field}`];
+    if (!(typeof value === 'string' && value !== '')) {
+        throw new Error(`JSON field '${field}' is not a non empty string`);
+    }
+    return value;
+}
+function validateNonEmptyStringIfExists(obj, field) {
+    const value = obj[`${field}`];
+    if (value !== undefined && !(typeof value === 'string' && value !== '')) {
+        throw new Error(`JSON field '${field}' is not a non empty string`);
+    }
+    return value;
+}
+function validateNonEmptyAttributeValue(obj, field) {
+    const value = obj[`${field}`];
+    if (!((typeof value === 'string' && value !== '') || typeof value === 'number' || typeof value === 'boolean')) {
+        throw new Error(`Attribute value should be a non empty string, number or boolean`);
+    }
+    return value;
+}
+async function fetchNFTMetadata(nftBaseUri, index) {
+    try {
+        return await (await fetch(`${nftBaseUri}${index}`)).json();
+    }
+    catch (e) {
+        throw new Error(`Error fetching NFT metadata from ${nftBaseUri}${index}: ${e}`);
+    }
+}
+function isInteger(num) {
+    return num === parseInt(num.toString(), 10);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alephium/web3",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "A JS/TS library to interact with the Alephium platform",
   "license": "GPL",
   "main": "dist/src/index.js",

package/src/api/node-provider.ts

@@ -22,7 +22,9 @@ import {
   forwardRequests,
   request,
   FungibleTokenMetaData,
-  NFTMetaData
+  NFTMetaData,
+  NFTCollectionMetaData,
+  StdInterfaceIds
 } from './types'
 import { Api as NodeApi } from './api-alephium'
 import { DEFAULT_THROTTLE_FETCH } from './utils'
@@ -137,6 +139,18 @@ export class NodeProvider implements NodeProviderApis {
     }
   }
 
+  // Only use this when the contract follows the NFT collection interface, check `guessFollowsNFTCollectionStd` first
+  fetchNFTCollectionMetaData = async (contractId: HexString): Promise<NFTCollectionMetaData> => {
+    const address = addressFromContractId(contractId)
+    const group = groupOfAddress(address)
+    const calls = Array.from([0, 1], (index) => ({ methodIndex: index, group: group, address: address }))
+    const result = await this.contracts.postContractsMulticallContract({ calls })
+    return {
+      collectionUri: hexToString(result.results[0].returns[0].value as any as string),
+      totalSupply: BigInt(result.results[1].returns[0].value as any as string)
+    }
+  }
+
   guessStdInterfaceId = async (tokenId: HexString): Promise<HexString | undefined> => {
     const address = addressFromTokenId(tokenId)
     const group = groupOfAddress(address)
@@ -150,12 +164,17 @@ export class NodeProvider implements NodeProviderApis {
     }
   }
 
+  guessFollowsNFTCollectionStd = async (contractId: HexString): Promise<boolean> => {
+    const interfaceId = await this.guessStdInterfaceId(contractId)
+    return interfaceId === StdInterfaceIds.NFTCollection
+  }
+
   guessStdTokenType = async (tokenId: HexString): Promise<'fungible' | 'non-fungible' | undefined> => {
     const interfaceId = await this.guessStdInterfaceId(tokenId)
     switch (interfaceId) {
-      case '0001':
+      case StdInterfaceIds.FungibleToken:
         return 'fungible'
-      case '0003':
+      case StdInterfaceIds.NFT:
         return 'non-fungible'
       default:
         return undefined

package/src/api/types.ts

@@ -264,6 +264,12 @@ export async function request(provider: Record<string, any>, args: ApiRequestArg
   return call(...args.params)
 }
 
+export enum StdInterfaceIds {
+  FungibleToken = '0001',
+  NFTCollection = '0002',
+  NFT = '0003'
+}
+
 export interface FungibleTokenMetaData {
   name: string
   symbol: string
@@ -275,3 +281,8 @@ export interface NFTMetaData {
   collectionAddress: string
   tokenUri: string
 }
+
+export interface NFTCollectionMetaData {
+  collectionUri: string
+  totalSupply: Number256
+}

package/src/api/utils.ts

@@ -20,9 +20,10 @@ import 'cross-fetch/polyfill'
 import { sleep } from '../utils'
 import { RateLimit } from 'async-sema'
 
-export function convertHttpResponse<T>(response: { data: T; error?: { detail: string } }): T {
+export function convertHttpResponse<T>(response: { status: number; data: T; error?: { detail: string } }): T {
   if (response.error) {
-    throw new Error(`[API Error] - ${response.error.detail}`)
+    const errorMessage = response.error.detail ?? `status code: ${response.status}`
+    throw new Error(`[API Error] - ${errorMessage}`)
   } else {
     return response.data
   }

package/src/token/nft.ts

@@ -18,10 +18,19 @@ along with the library. If not, see <http://www.gnu.org/licenses/>.
 
 // JSON Schema for the NFT metadata, which is pointed to by the value
 // returned from the `getTokenUri` method of the NFT contract
+
+import 'cross-fetch/polyfill'
+
 export interface NFTMetadata {
   name: string
-  description: string
+  description?: string
   image: string
+  attributes?: [
+    {
+      trait_type: string
+      value: string | number | boolean
+    }
+  ]
 }
 
 // JSON Schema for the NFT Collection metadata, which is pointed to by
@@ -32,3 +41,117 @@ export interface NFTCollectionMetadata {
   description: string
   image: string
 }
+
+export const validNFTMetadataFields = ['name', 'description', 'image', 'attributes']
+export const validNFTMetadataAttributesFields = ['trait_type', 'value']
+export const validNFTMetadataAttributeTypes = ['string', 'number', 'boolean']
+export const validNFTCollectionMetadataFields = ['name', 'description', 'image']
+
+export function validateNFTMetadata(metadata: any): NFTMetadata {
+  Object.keys(metadata).forEach((key) => {
+    if (!validNFTMetadataFields.includes(key)) {
+      throw new Error(`Invalid field ${key}, only ${validNFTMetadataFields} are allowed`)
+    }
+  })
+
+  const name = validateNonEmptyString(metadata, 'name')
+  const description = validateNonEmptyStringIfExists(metadata, 'description')
+  const image = validateNonEmptyString(metadata, 'image')
+  const attributes = validateNFTMetadataAttributes(metadata['attributes'])
+
+  return { name, description, image, attributes }
+}
+
+export function validateNFTCollectionMetadata(metadata: any): NFTCollectionMetadata {
+  Object.keys(metadata).forEach((key) => {
+    if (!validNFTCollectionMetadataFields.includes(key)) {
+      throw new Error(`Invalid field ${key}, only ${validNFTCollectionMetadataFields} are allowed`)
+    }
+  })
+
+  const name = validateNonEmptyString(metadata, 'name')
+  const description = validateNonEmptyString(metadata, 'description')
+  const image = validateNonEmptyString(metadata, 'image')
+
+  return { name, description, image }
+}
+
+export async function validateEnumerableNFTBaseUri(nftBaseUri: string, maxSupply: number): Promise<NFTMetadata[]> {
+  if (isInteger(maxSupply) && maxSupply > 0) {
+    const nftMetadataz: NFTMetadata[] = []
+
+    for (let i = 0; i < maxSupply; i++) {
+      const nftMetadata = await fetchNFTMetadata(nftBaseUri, i)
+      const validatedNFTMetadata = validateNFTMetadata(nftMetadata)
+      nftMetadataz.push(validatedNFTMetadata)
+    }
+
+    return nftMetadataz
+  } else {
+    throw new Error('maxSupply should be a positive integer')
+  }
+}
+
+function validateNFTMetadataAttributes(attributes: any): NFTMetadata['attributes'] {
+  if (!!attributes) {
+    if (!Array.isArray(attributes)) {
+      throw new Error(`Field 'attributes' should be an array`)
+    }
+
+    attributes.forEach((item) => {
+      if (typeof item !== 'object') {
+        throw new Error(`Field 'attributes' should be an array of objects`)
+      }
+
+      Object.keys(item).forEach((key) => {
+        if (!validNFTMetadataAttributesFields.includes(key)) {
+          throw new Error(`Invalid field ${key} for attributes, only ${validNFTMetadataAttributesFields} are allowed`)
+        }
+      })
+
+      validateNonEmptyString(item, 'trait_type')
+      validateNonEmptyAttributeValue(item, 'value')
+    })
+  }
+
+  return attributes as NFTMetadata['attributes']
+}
+
+function validateNonEmptyString(obj: object, field: string): string {
+  const value = obj[`${field}`]
+  if (!(typeof value === 'string' && value !== '')) {
+    throw new Error(`JSON field '${field}' is not a non empty string`)
+  }
+
+  return value
+}
+
+function validateNonEmptyStringIfExists(obj: object, field: string): string {
+  const value = obj[`${field}`]
+  if (value !== undefined && !(typeof value === 'string' && value !== '')) {
+    throw new Error(`JSON field '${field}' is not a non empty string`)
+  }
+
+  return value
+}
+
+function validateNonEmptyAttributeValue(obj: object, field: string): string | number | boolean {
+  const value = obj[`${field}`]
+  if (!((typeof value === 'string' && value !== '') || typeof value === 'number' || typeof value === 'boolean')) {
+    throw new Error(`Attribute value should be a non empty string, number or boolean`)
+  }
+
+  return value
+}
+
+async function fetchNFTMetadata(nftBaseUri: string, index: number) {
+  try {
+    return await (await fetch(`${nftBaseUri}${index}`)).json()
+  } catch (e) {
+    throw new Error(`Error fetching NFT metadata from ${nftBaseUri}${index}: ${e}`)
+  }
+}
+
+function isInteger(num: number) {
+  return num === parseInt(num.toString(), 10)
+}