Futureverse Asset Register Core SDK

Installation

NPM:

    npm install @futureverse/asset-register --save

Yarn:

    yarn add @futureverse/asset-register

Usage

Create Schema

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
import { AssetRegister } from '@futureverse/asset-register';
import { Namespace } from '@futureverse/asset-register/types';

const domain = '<domain for the authentication>';
const origin = '<origin for the authentication>';
const chainId = 5;
// Get the wallet instant from futurepass
const wallet = privateKeyToAccount(generatePrivateKey());
const walletAddress = wallet.address;

const assetRegisterSdk = new AssetRegister({
  url: 'https://ar.futureverse.app/graphql',
  auth: {
    sign: async (message) => {
      return await wallet.signMessage({ message });
    },
    storage: {
      set: (key: string, value: string) => localStorage.setItem(key, value),
      get: (key: string) => localStorage.getItem(key),
    },
    domain,
    origin,
    chainId,
    walletAddress,
  },
});

// CreateSchema
assetRegisterSdk.createSchema({
  namespace: 'fv.test' as Namespace,
  schema: '',
  version: 0.1,
});

Asset Linking

import { AssetRegister, AssetTransactionMessage, ChainAddress, Signature, TransactionHash } from '@futureverse/asset-register';
import { ARTM, STATEMENTS } from '@futureverse/artm';
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';

const GQL_API_URL = 'http://localhost:8080/graphql';
const domain = '<domain for the authentication>';
const origin = '<origin for the authentication>';
const chainId = 5;
// get the wallet instant from futurepass
const wallet = privateKeyToAccount(generatePrivateKey());
const walletAddress = wallet.address;

const boxerDid = 'did:fv-asset:5:evm:0x5085cc0236ae108812571eadf24beee4fe8e0c50:4132';
const asmGenTwoBrainDid = 'did:fv-asset:5:evm:0x51cea47135c93eee33a6c15c22ea3532aec0540a:375';

let nonce = 0;

// Define the asset register instance
const assetRegisterSdk = new AssetRegister({
  url: GQL_API_URL,
  auth: {
    sign: async (message) => {
      return await wallet.signMessage({ message });
    },
    storage: {
      set: (key: string, value: string) => localStorage.setItem(key, value),
      get: (key: string) => localStorage.getItem(key),
    },
    domain,
    origin,
    chainId,
    walletAddress: walletAddress,
  },
});

//STEP 1: get nonce
nonce = await assetRegisterSdk.nonceForChainAddress(walletAddress as ChainAddress);

//STEP 2: Create a message
const artmMessage = new ARTM({
  address: walletAddress,
  statement: STATEMENTS.OWNERSHIP,
  nonce: nonce,
});

const operation = 'create';

artmMessage.operations = [
  {
    type: 'asset-link',
    action: operation,
    args: ['equipWith_asmBrain', boxerDid, asmGenTwoBrainDid],
  },
];

const signature = await wallet.signMessage({
  message: artmMessage.getMessageToSign(),
});

const input = {
  signature: signature as Signature,
  transaction: artmMessage.message as AssetTransactionMessage,
};

// STEP 3: Send the message to the server
const response = await assetRegisterSdk.submitTransaction(input);

// STEP 4:  Check the transaction status
const transactionStatus = await assetRegisterSdk.transaction({
  transactionHash: response.transactionHash as TransactionHash,
});

Create off-chain Asset

import { AssetRegister } from '@futureverse/asset-register';
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
import { v4 as uuidv4 } from 'uuid';

const GQL_API_URL = 'http://localhost:8080/graphql';
const domain = '<domain for the authentication>';
const origin = '<origin for the authentication>';
const chainId = 5;
// get the wallet instant from futurepass
const wallet = privateKeyToAccount(generatePrivateKey());
const walletAddress = wallet.address;

const CREATOR_ID = '72fe2ff1-5f69-40e3-90b3-5335c7126552';

/* 
Define the asset registry instance
Only url is required. Other params are auth related which are not required if you don't call methods need authentication.
You can set them afterward by assetRegisterSdk.setAuthorizationParameters(). 
*/

const assetRegisterSdk = new AssetRegister({
  url: GQL_API_URL,
  auth: {
    sign: async (message) => {
      return await wallet.signMessage({ message });
    },
    storage: {
      set: (key: string, value: string) => localStorage.setItem(key, value),
      get: (key: string) => localStorage.getItem(key),
    },
    domain,
    origin,
    chainId,
    walletAddress: walletAddress,
  },
});

// Register an off chain sft when collection is created without a token id
const creatorCollectionId = uuidv4();
const sftInput = {
  creatorCollectionId: creatorCollectionId,
  creatorId: CREATOR_ID,
};
const response = await assetRegisterSdk.registerOffChainAsset(sftInput);

// register an off chain nft when collection is created with a token id
const tokenId = uuidv4();
const creatorCollectionId2 = uuidv4();
const nftInput = {
  creatorCollectionId: creatorCollectionId2,
  creatorId: CREATOR_ID,
  tokenId: tokenId,
};

const response2 = await assetRegisterSdk.registerOffChainAsset(nftInput);

Get Asset Tree

import { AssetRegister } from '@futureverse/asset-register'

import {
  CollectionId,
} from '@futureverse/asset-register/types'

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'

const GQL_API_URL = 'http://localhost:8080/graphql'
const domain = '<domain for the authentication>'
const origin = '<origin for the authentication>'
const chainId = 5
// get the wallet instant from futurepass
const wallet = privateKeyToAccount(generatePrivateKey())
const walletAddress = wallet.address

const boxerDid =
  'did:fv-asset:5:evm:0x5085cc0236ae108812571eadf24beee4fe8e0c50:4132'

const [_did, _fvAsset, chainId, chainType, contractAddress, tokenId] = boxerDid.split(':')

// Define the asset register instance
const assetRegisterSdk = new AssetRegister({
  url: GQL_API_URL,
  auth: {
    sign: async (message) => {
      return await wallet.signMessage({ message })
    },
    storage: {
      set: (key: string, value: string) => localStorage.setItem(key, value),
      get: (key: string) => localStorage.getItem(key),
    },
    domain,
    origin,
    chainId,
    walletAddress: walletAddress,
  }
})

const collectionId = `${chainId}:${chainType}:${contractAddress}` as CollectionId

const assetTree = await ar.getAssetTree({
  tokenId
  collectionId
})

// List the paths to the relative assetTree,
// The paths should looks like below
// const paths = [
//        'http://schema.futureverse.com#equippedWith_accessoryClothing',
//        'http://schema.futureverse.com#equippedWith_accessoryEyewear',
//        'http://schema.futureverse.com#equippedWith_accessoryHead',
//        'http://schema.futureverse.com#equippedWith_accessoryMouth',
//        'http://schema.futureverse.com#equippedWith_accessoryNose',
//        'http://schema.futureverse.com/fvp#sft_link_owner_0x225b5333c2d8ec41f40d6463d44141786c2c4463',
//      ];
const paths = assetTree?.paths
// To fetch the relative assetTee, just use the `getPath` method.
const clothingAssetTreePath = await assetTree.getPath('http://schema.futureverse.com#equippedWith_accessoryClothing')
const clothingAssetTree = await clothingAssetTreePath.getAssetTree()

Migration guide from @futureverse/asset-registry package

The new package name for this library is now @futureverse/asset-register. Hence, there are some files and codes that have been renamed in the new version. Here are the migration guides:

• ./src/lib/AssetRegistry.ts file is now ./src/lib/AssetRegister.ts
• AssetRegistry class is now AssetRegister
• For types:
  • AssetRegistryError is now AssetRegisterError
  • AssetRegistryErrorExtensions is now AssetRegisterErrorExtensions

New Core SDK APIs

The original Core SDK API had limitations:

• Cumbersome Pagination: It lacked user-friendly features for navigating through large datasets.
• Limited Batching: It couldn't process multiple data requests (queries or mutations) in a single call.
• Inefficient Relationship Handling: It wasn't optimized for retrieving related data elements effectively.

To address these shortcomings, we've introduced a redesigned Core SDK API.

All the new APIs are located under the @futureverse/asset-register/v2 path of the npm package.

Initialize the client

const auth: AuthorizationParameters = {
	...
}

const client = new new AssetRegister({
    url: 'http://localhost:8080/graphql',
		auth // optional
}

Authentication

interface AuthorizationParameters {
  /** A function for signing requests to the API. */
  sign: SignFunction
  /** An object for storing data locally. */
  storage: Storage
  /** The domain of the client application. */
  domain: string
  /** The origin of the client application. */
  origin: string
  /** The ID of the blockchain network. */
  chainId: number
  /** The address of the wallet being used. */
  walletAddress: string
}

client.setAuthorizationParameters(auth: AuthorizationParameters)

Query

const [namespaces] = await client.namespaces().execute();
const [domains] = await client.domains().execute();

Multiple queries in one request

const [namespace, assets1, assets2] = await client
  .namespaces()
  .asset({
    tokenId: '<tokenId 1>',
    collectionId: '<collectionId 1>' as CollectionId,
  })
  .asset({
    tokenId: '<tokenId 2>',
    collectionId: '<collectionId 2>' as CollectionId,
  })
  .execute();

Pagination

// pagination
if (namespaces.hasNextPage()) {
  const namespaces_on_next_page = await namespaces.nextPage();
}

Access the items in the list by map method

const [namespaces] = await client.namespaces().execute();
namespaces.map((namespace) => {
  //Do something for the namespace
});

Access sub-items directly

const [asset] = client
  .asset({
    tokenID: 'token id',
    collectionID: 'collection id',
  })
  .execute();

const schema = asset.schema;
const assetTree = asset.assetTree;