Installing the VWBL SDK & a Basic Overview

A quick step-by-step overview of installing the VWBL SDK and usage basics

1. Install the ​VWBL SDK

// Install via yarn
yarn add vwbl-sdk vwbl-core

// Install via npm
npm install vwbl-sdk vwbl-core

2. Import the VWBL SDK

Import the VWBL class and type definition.

import { VWBL } from "vwbl-sdk";
import {
  ManageKeyType,
  UploadContentType,
  UploadMetadataType,
} = ("vwbl-core");

3. Create Web3 or Ethers instance

The popular libraries that interact with evm smart contract are web3.js and ethers.js. VWBL SDK supports both libraries.

Using web3.js in Browser env:

// ※There are some ways to connect with MetaMask. In this time, use @metamask/detect-provider as one example.

import detectEthereumProvider from "@metamask/detect-provider";
import Web3 from "web3";

const provider = await detectEthereumProvider();
const web3 = new Web3(provider);

const Web3 = require("web3");
const Provider = require("@truffle/hdwallet-provider");
const privateKey = "walletPrivateKeyString"
const blockchainRPCURL = "https://polygon-rpc.com"
const provider = new Provider(privateKey, blockchainRPCURL);
const web3 = new Web3(provider);

Using Ethers.js in Browser/NodeJs env:

// ※Web3 modal enables connect various wallet such as metamask, coinbase wallet.

import Web3Modal from "web3modal";
import { ethers } from "ethers";

const web3Modal = new Web3Modal({ cacheProvider: true });
const provider = await web3Modal.connect();
const ethProvider = new ethers.providers.Web3Provider(provider);
const ethSigner = ethProvider.getSigner();

import { ethers } from "ethers";

const privateKey = "walletPrivateKeyString"
const ethProvider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com');
const ethSigner = new ethers.Wallet(privateKey, ethProvider);

4. Instantiate the VWBL SDK

VWBL SDK provides VWBL class for web3.js / ethers.js

Using web3.js in Browser env:

import { VWBL } from 'vwbl-sdk';
import {
  ManageKeyType,
  UploadContentType,
  UploadMetadataType
} from "vwbl-core";

const vwbl = new VWBL({
    web3,  // web3 instance
    contractAddress: "0x...",              // VWBL nft's contract address
    manageKeyType: ManageKeyType.VWBL_NETWORK_SERVER, // how to manage key
    uploadContentType: UploadCotentType.S3, // where to upload content
    uploadMetadataType: UploadMetadataType.S3, // where to upload metadata
    awsConfig: {
        region: "ap-northeast-1",
        idPoolId: "ap-northeast-1:...",
        cloudFrontUrl: "https://xxx.cloudfront.net",
        bucketName: {
          metadata: "vwbl-metadata",
          content: "vwbl-content",
        }
     }
 });

import {
    ManageKeyType,
    UploadContentType,
    UploadMetadataType,
    VWBL
} from 'vwbl-sdk';

const vwbl = new VWBL({
    web3,  // web3 instance
    contractAddress: "0x...",              // VWBL nft's contract address
    manageKeyType: ManageKeyType.VWBL_NETWORK_SERVER, // how to manage key
    uploadContentType: UploadContentType.IPFS, // where to upload content
    uploadMetadataType: UploadMetadataType.IPFS, // where to upload metadata
    ipfsConfig: {
        apiKey: "yourPinataApiKey", // pinata API Key
        apiSecret: "yourPinataSecretApiKey", // pinata SecretAPI Key
    }
});

Using ethers.js in Broswer/NodeJs env:

import { VWBL } from 'vwbl-sdk';
import {
    ManageKeyType,
    UploadContentType,
    UploadMetadataType,
} from "vwbl-core";

const vwbl = new VWBL({
    ethersProvider: ethProvider, // ethers.js provider instance
    ethersSigner: ethSigner, // ethers.js signer instance
    contractAddress: "0x...",              // VWBL nft's contract address
    manageKeyType: ManageKeyType.VWBL_NETWORK_SERVER, // how to manage key
    uploadContentType: UploadCotentType.S3, // where to upload content
    uploadMetadataType: UploadMetadataType.S3, // where to upload metadata
    awsConfig: {
        region: "ap-northeast-1",
        idPoolId: "ap-northeast-1:...",
        cloudFrontUrl: "https://xxx.cloudfront.net",
        bucketName: {
          metadata: "vwbl-metadata",
          content: "vwbl-content",
        }
     }
 });

import { VWBL } from 'vwbl-sdk';
import {
    ManageKeyType,
    UploadContentType,
    UploadMetadataType,
} from "vwbl-core";

const vwbl = new VWBL({
    ethersProvider: ethProvider, // ethers.js provider instance
    ethersSigner: ethSigner, // ethers.js signer instance
    contractAddress: "0x...",              // VWBL nft's contract address
    manageKeyType: ManageKeyType.VWBL_NETWORK_SERVER, // how to manage key
    uploadContentType: UploadCotentType.IPFS, // where to upload content
    uploadMetadataType: UploadMetadataType.IPFS, // where to upload metadata
    ipfsConfig: {
        apiKey: "yourPinataApiKey," // pinata API Key
        apiSecret: "yourPinataSecretApiKey", // pinata SecretAPI Key
    }
});

5. Encryption and Distributing digital contents

When minting a VWBL NFT, managedCreateToken will need to be executed. When this method is executed, the following happens: An NFT is minted, key pairs are generated, encryption and uploading of the encrypted data, uploading metadata, and the sending the key to the VWBL Network. VWBL support type of preview image is File and digital content is File / File[]. Also, it is necessary to set the decryption key to the VWBL Network in minting a VWBL NFT. Since the signature is required when communicating with the VWBL Network, be sure to execute the sign function before executing the managedCreateToken function.

// make sure to sign before creating tokens
await vwbl.sign()

// create token, which metadata is stored on AWS.
const tokenId = await vwbl.managedCreateToken(
    "vwblNFT",                      // The NFT name
    "NFT owner can view content", // The NFT description
    file,                         // The data that only NFT owner can view
    thumbnail,                    // The NFT preview image
    royaltiesPercentage,          // The percentage of nft royalty percentage
);

// make sure to sign before creating tokens
await vwbl.sign()

const tokenId = await vwbl.managedCreateTokenForIPFS(
    "vwblNFT",                      // The NFT name
    "NFT owner can view content", // The NFT description
    file,                         // The data that only NFT owner can view
    thumbnail,                    // The NFT preview image
    royaltiesPercentage,          // The percentage of nft royalty percentage
);

6. Decryption encrypted content

This method can executed only by the NFT owner or minter. When this method is executed, the following happens: Downloading of the metadata & encrypted content, retrieval of the key, and decryption of encrypted content. Also, it is necessary to get the decryption key from the VWBL Network in extracting VWBL NFT's metadata. Since the signature is required when communicating with the VWBL Network, be sure to execute the sign function before executing the extractMetadata function.

// make sure to sign before creating tokens
await vwbl.sign();
// This method can execute by only nft owner
const {
  id, // tokenId
  name, // metadata name
  description, // metadata description
  image, // metadata image
  mimeType, // metadata mime type
  fileName, // file name
  ownData, // decrypted content
} = await vwbl.extractMetadata(tokenId);

If you are using VWBL SDK (v0.1.6 or later), it is possible to extract token's metadata from multiple contracts by setting data-collector address to constructor props and adding specific contract address in params of extractMetadata.

const vwbl = new VWBL({
  web3, // web3 instance
  contractAddress: "0x...", // VWBL nft's contract address
  manageKeyType: ManageKeyType.VWBL_NETWORK_SERVER, // how to manage key
  uploadContentType: UploadContentType.IPFS, // where to upload content
  uploadMetadataType: UploadMetadataType.IPFS, // where to upload metadata
  ipfsConfig: {
    apiKey: "yourPinataApiKey", // pinata API Key
    apiSecret: "yourPinataSecretApiKey", // pinata SecretAPI Key
  },
  dataCollectorAddress: "0x...", // check "Endpoint for VWBL"​
});

// make sure to sign before creating tokens
await vwbl.sign();
// This method can execute by only nft owner
const {
  id, // tokenId
  name, // metadata name
  description, // metadata description
  image, // metadata image
  mimeType, // metadata mime type
  fileName, // file name
  ownData, // decrypted content
} = await vwbl.extractMetadata(tokenId, contractAddress);