@csir-dlt/afriverse NPM

Afriverse-Library

This library interfaces with Blockchain (afriverse backend), NFT storage, HD wallet and exposes an API that integrate wallet and the virtual enviroment.

Configuration

We rely on the NFT storage service to store off-chain NFT metadata. This service requires an API key. You can freely create one by visiting https://nft.storage/.

After you have obtained the key, create an .env file on the project root directory and set the following variable:

NFT_STORE_API_KEY = [Your - API - Key];

Wallet Integration

The server has an afriverse instance that enables interaction with the afriverse backend. It also has a server instance which integrates the wallet and the virtual enviroment. With the server instance you can open an HTTP connection where the virtual enviroment can send the HTTP requests then the server will process the request. E.g. the enviroment can send a request to mint NFTs then the server will handle the request by utilizing the afriverse instance encapsulated within it.

Start a server

import { server } from "@csir-dlt/afriverse";

// initialize handlers that will process the request
server.initServices();

// start the server
server.start();

Since the server interacts with the afriverse backend via the afriverse instance, we need to know the user's keys to sign transactions.. Therefore we need to set the keys to the server:

const keypairMap: Map<string, Keypair>;
server.setKeypairs(keypairMap);

The keypairMap is of type Map, where the key is a public key that maps to a corresponding Keypair.

The server now has a list of all user's keypair, it now needs to know the exact keypair that can be used to sign the transactions. Since the afriverse instance is the one responsible for interacting with the Blockchain, we need to specify that keypair in it:

const signingKeypair: Keypair;
server.afriverse.setKeypair(signingKeypair);

If we support multiple addresses on the wallet and the user clicks the specific address for signing transaction, we also need to update the keypair that will sign transactions:

server.afriverse.setKeypair(updateKeypair);

Complete Code:

import { server } from "@csir-dlt/afriverse";

const keypairMap: Map<string, Keypair>;
const signingKeypair: Keypair;

server.setKeypairs(keypairMap);
server.afriverse.setActiveKeypair(signingKeypair);

server.initServices();
server.start();

If you have your keypairs as a list i.e. Keypair[]. You will need to convert it to Map<string, Keypair> type, where the map key is a public key of a keypair. Here's is the helper function for that:

keypairListToMap(keypairs: web3.Keypair[]): Map<string, web3.Keypair> {
      const map: Map<string, web3.Keypair> = new Map();
      if(keypairs.length > 0){
        for(let i = 0; i < keypairs.length; i++){
          map.set(keypairs[i].publicKey.toBase58(), keypairs[i])
        }
      }
      return map;
   }

This function is also available via the identity instance:

import {identity} from "@csir-dlt/afriverse";
identity.keypairListToMap(Keypair[]);

The server enales the enviroment to interact with the Blockchain, but for the wallet to interact directly with the Blockchain (afriverse) backend it can utilize the AfriverseInterface.

interface AfriverseInterface {
  cluster: any;
  storage: Storage;
  wallet: Wallet;
  program: Program<AfriVerse>;
  provider: AnchorProvider;
  createRoom(roomOwner: web3.Keypair, numberOfNFTs: number): Promise<string[]>;
  leftNFTs(ownerID: string, roomID: string): Promise<number>;
  hasAccess(roomID: string, userAddress?: string): Promise<boolean>;
  buyNFT(
    ownerKeypair: web3.Keypair,
    buyerKeypair: web3.Keypair,
    nftOwner: string,
    roomID: string
  ): Promise<boolean>;
  getNFTMetadataByMint(mint: string): Promise<any>;
  getAllNFTMetadata(owner: string): Promise<any>;
  mintAsset(
    creatorKeypair: web3.Keypair,
    name: string,
    symbol: string,
    description: string,
    imagePath: string,
    externalURL: string,
    attributes: NFTProperties[],
    animationURL: string,
    royaltyPercentage: number,
    adminAddress: string,
    mintingPriceSOL: number
  ): Promise<string>;
  transferSOL(
    keypair: web3.Keypair,
    to: string,
    amountInSOL: number
  ): Promise<boolean>;
  transferNFT(
    ownerKeypair: web3.Keypair,
    nftAddress: string,
    to: string
  ): Promise<boolean>;
}

Example: To retrieve all the user's NFTs you can:

import { afriverse } from "@csir-dlt/afriverse";

// make sure the signing key is set to the afriverse instance when interacting with the Blockchain,
// even though it is not required in this case since we are not make a transaction
afriverse.setActiveKeypair(signingKeypair);
afriverse.getAllNFTMetadata([user - public - key]);

HTTPS Requests

Once the server is running the enviroment can interact with it. The server runs on port 1212 by default. The following code snippet shows how we can send the HTTP request using the axios library:

import axios from "axios";

// HTTP requests
const createRoomRequest = async (mints: number): Promise<string[]> => {
  const response = await axios.get(
    `http://localhost:1212/createRoom?nfts=${mints}`
  );
  return response.data;
};

const hasAccessRequest = async (roomID: string): Promise<boolean> => {
  let response = await axios.get(
    `http://localhost:1212/access?roomID=${roomID}`
  );
  return response.data;
};

const buyNFTRequest = async (
  roomID: string,
  roomOwner: string
): Promise<boolean> => {
  let response = await axios.get(
    `http://localhost:1212/buyNFT?roomID=${roomID}&ownerID=${roomOwner}`
  );
  return response.data;
};

createRoomRequest() accepts initial number of nfts to be minted as an argument
- returns list with room ID, room owner ID
http://localhost:1212/access?roomID=[room ID]
- returns true if the user has access to the room
http://localhost:1212/buyNFT?roomID=[room ID]&ownerID=roomOwner
- returns true if NFT was bought successfully

NFT Storage

interface NFTStorageInterface {
  storageURL: string;
  storeNFTImage(name: string, description: string, fullPath: string): any;
  uploadNFTMetadata(
    name: string,
    symbol: string,
    description: string,
    externalURL: string,
    imageURL: string,
    attributes: NFTProperties[],
    animationURL: string
  ): any;
  uploadCollectionMetadata(
    name: string,
    symbol: string,
    description: string,
    external_url: string,
    imageURL: string
  ): any;
  replaceProtocol?(url: string): void;
}

The storage interface expose functionalities that deal with off-chain metadata. It relies on the NFT Storage service which uses IPFS behind the scene. The NFT Storage services requires the API key to utilize it. You can get one from: https://nft.storage/. You will then need to create a .env file and store your API key as:

NFT_STORE_API_KEY = [Your - API - Key];

You can then utilize this interface or create an instance of the NFTStorageInterface

import { Storage } from "@csir-dlt/afriverse";

const storage = new Storage("https://ipfs.io/ipfs/"); // or https://cloudflare-ipfs.com/ipfs/

const storeMetadata = async () => {
  const metadataURL = await storage.uploadCollectionMetadata(
    "name",
    "symbol",
    "description",
    "external_url",
    "https://upload.wikimedia.org/wikipedia/commons/2/24/NFT_Icon.png?20191215204608"
  );
  console.log(metadataURL);
};

HD Wallet

interface IdentityInterface {
  activeIdentity: number;
  seed: any;
  mnemonic: any;
  keypairs: Keypair[];
  selectedKeypair: web3.Keypair | any;
  addKeypair(keyPair: web3.Keypair): Keypair[];
  generateMnemonicAndSeed(): Keypair[];
  generateNewKeypair(): Keypair;
  createKeypairFromFile(fullPath: string): Promise<Keypair>;
}