@rarify/js-sdk

Rarify JavaScript SDK

The Rarify JavaScript SDK is a JavaScript library for the Rarify API. It provides reusable commands that make it easier to communicate with the API from client-side and server-side JavaScript applications.

For more information about the Rarify API, see the Rarify API reference at https://docs.rarify.tech/.

For full documentation about this SDK, see https://rarifytech.gitlab.io/js-sdk.

Table of contents

• Installing the SDK
• Getting started
• Creating tokens
  • Step 1: Create a contract
  • Step 2: Create the metadata and design for the token
  • Step 3: Transfer (mint) the tokens on the target network
  • Step 4: Get the status of a transfer
• Development
  • Build bundles
  • Build documentation
• Changelog

Installing the SDK

To install the SDK into a Node.JS application, use npm or yarn to install the NPM package @rarify/js-sdk:

yarn add @rarify/js-sdk

To install the SDK into a client-side web application, use this unpkg link, replacing [version] with the version that you want to use:

<script type="text/javascript" src="https://unpkg.com/@rarify/js-sdk@[version]/lib/rarify.js-sdk.min.js"></script>

Getting started

To start using the SDK, you must import classes from the NPM package, give the API your token, and create instances of the classes. These classes and their methods represent the API endpoints.

To avoid having to create instances of these classes in every file, you can create a single file that sets up the Rarify API. Then you can import the instances in other JavaScript files.

For example, this rarifyAPI.js JavaScript file imports the classes, sets the authentication token, and initalizes instances of the API classes.

These classes provide access to the Rarify API endpoints. For example, the TokenCaller class provides methods that call endpoints that deal with creating token designs, such as POST /core/tokens.

import {
  JsonApiClient,
  NetworkCaller,
  ContractCaller,
  FileCaller,
  MetadataCaller,
  TokenCaller,
  TransferCaller
} from '@rarify/js-sdk';

// Initiate JsonApiCaller:
export const apiCaller = new JsonApiClient({ baseUrl: 'https://api.rarify.tech' });

// Set authorization token
apiCaller.setAuthToken('d6ef1960-6f6f-42ac-8ac1-d530652ca416');

// Initiate endpoint callers with JsonApiCaller
export const networkCaller = new NetworkCaller(apiCaller);
export const contractCaller = new ContractCaller(apiCaller);
export const fileCaller = new FileCaller(apiCaller);
export const metadataCaller = new MetadataCaller(apiCaller);
export const tokenCaller = new TokenCaller(apiCaller);
export const transferCaller = new TransferCaller(apiCaller);

// Export user's internal ID ("identity")
export const myIdentity = '233f2794-a8d7-4689-b84b-15a293eb6d1d';

To make sure that the SDK is working, try a straightforward command such as networkCaller.getNetworks() to get a list of the available networks. This method returns a promise that resolves to a JSON object that lists the available networks. This response is the same as the response to the GET /core/networks endpoint.

const { data } = await networkCaller.getNetworks();

On a Vue page, you can import the classes from the rarifyAPI.js file and use them to call the endpoints, as in this example:

<template>
  <p>is loading data :{{ isLoading }}</p>
  <pre>{{ result }}</pre>
</template>

<script>
import {
  networkCaller,
} from './rarifyAPI';

export default {
  name: "App",

  data: () => ({
    result: {},
    isLoading: false,
  }),

  async created() {
    this.isLoading = true;

    const { data } = await networkCaller.getNetworks();
    this.result = data;

    this.isLoading = false;
  },
};
</script>

Creating tokens

As with using the Rarify API directly, creating tokens with the SDK has these major steps:

• Create a contract for the token
• Create the metadata and design for the token
• Transfer (mint) the tokens on the target network
• Get the status of a transfer

Step 1: Create a contract

To create a contract, use the contractCaller.createContract() method, which calls the POST /core/contracts endpoint. Just like the endpoint, this method accepts the type of contract to create and the network to create it on.

For more information about creating a contract with Rarify, see Creating tokens in the Rarify API reference.

// Import callers and identity
import {
  networkCaller,
  contractCaller,
  myIdentity,
} from './rarifyAPI';

// Get a network that supports creating contracts
const { data: networks } = await networkCaller.getNetworks();
const contractNetwork = networks.find(contract => contract.tokens_minting);

// Create the contract
const { data: contractTransaction } = await contractCaller.createContract({
  name: 'My new ERC1155 contract',
  erc1155: {
    metadata: {
      royalties_fee_basic_points: 250,
      royalties_receiver: "0x1234567890",
      description: "My example contract that I use to create ERC1155 NFTs",
      external_url: "https://rarify.tech/",
      image_url: "https://s3.eu-west-1.amazonaws.com/rarify.tech/main-splash.png",
      name: "My example ERC1155 token collection",
    }
  },
  networkId: contractNetwork.id,
  ownerId: myIdentity,
});

console.log(contractTransaction.id);

The response includes the ID of the transaction that the Rarify API is using to create the contract on the network. Creating a contract on a network is an asynchronous action, so you can use the transaction ID to check the progress of the action or to accept a callback when the contract is created. For more information about these asynchronous events and setting up callbacks for them, see Using callbacks in the API reference.

Step 2: Create the metadata and token design

Rarify allows you to set up tokens and their metadata payload on its API before you mint tokens on the target network. This way, you can plan and test tokens before you incur costs.

To create a token design before you actually mint the token, create the token metadata payload with the metadataCaller.setMetadata() command and then create the token design with the tokenCaller.createToken() command. These commands call the PUT /core/metadata and POST /code/tokens endpoints.

This example uploads a file to include in the metadata, creates the metadata, and creates a token design that includes the metadata:

import {
  networkCaller,
  contractCaller,
  fileCaller,
  myIdentity,
} from './rarifyAPI';

// Get a network that supports metadata storage to store the token metadata
const metadataStorageNetwork = networks.find(item => item.metadata_storage);

// Upload image
const { data: image } = await fileCaller.uploadFile(
  file, // Not shown in this example; get the file from a browser event
  myIdentity,
);

// Set token metadata
const { data: metadata } = await metadataCaller.setMetadata({
  name: 'My token',
  description: 'A token design I created with the SDK',
  imageUrl: image.url,
  externalUrl: 'https://rarify.tech/',
  networkId: metadataStorageNetwork.id,
  ownerId: myIdentity,
});

// Create the token design based on the metadata and a contract
const { data: tokenDesign } = tokenCaller.createToken(
  contractId, // Not shown in this example
  metadata.id
);

console.log(tokenDesign.id);

Step 3: Mint a token

The transferCaller.transferTokens() command mints tokens based on a token design and metadata. Minting the token creates one or more specific instances of the token on the target network and incurs network costs, so be sure to specify the correct recipient and other information.

This example mints one instance of the token and sends it to a target account:

const { data: transfer } = await transferCaller.transferTokens({
  tokenId: tokenId, // Not shown in this example
  amount: 1,
  isMinting: true,
  receiver: receivingAccountAddress, // Not shown in this example
});

Minting tokens on a network is an asynchronous action, so you can use the transaction ID to check the progress of the action or to accept a callback when the transaction is complete. Now that you have minted the token the target network, you can use it like any other token on the network or use the Rarify API to transfer it between accounts with the transferCaller.transferTokens() command. The request is similar, but instead of setting is_minting to true, set it to false and specify the new owner of the token.

Step 4: Get the status of a transaction

To get the status of a transaction, such as the transaction that is minting your token, use the transactionCaller.getTransactions() command. This command calls the GET /transactions endpoint. Like the endpoint, you must include your internal ID to filter the transactions.

This example gets the status of the transfer from step 3:

const { data: transactions } = await transactionCaller.getTransactions({
  'filter[owner]': myIdentity,
});
const transaction = transactions.find(t => t.id === transfer.tx.id);
console.log(transaction.state);

The response includes the status and ID of the transaction. If the transaction succeeded, the state field is set to applied and the hash field provides the hex ID that you can use to look up your new token on the network.

Development

These instructions are for developing and building the SDK locally.

For the development environment we use:

• Eslint plus Prettier for the linting and formatting code.
• Jest for unit tests.

Build bundles

@rarify/js-sdk compiles into the es-modules and also there is distributive for "in-script-tag" usage that compiles into the ./lib/rarify.js-sdk.min.js output file, which will accessible in the Window object with property name .rarifySdk

Before developing or building library distributive you'll need to install node_modules, use npm install or yarn install.

To build library distributives you can execute yarn build that will compile the type definitions, es-module bundle and browser bundle, or you can do each step manually:

Remove all compiled distributions from ./lib directory:

yarn clean

Build type definitions with TypeScript compiler:

yarn build:types

This command emits all type definitions from library without JavaScript compiling, also we use tsc-alias tool to replace all alias-ed type definitions paths to the relative one.

Compile and minify library into the es-modules with Babel.js:

yarn build:js

It will remove all comments, whitespaces, transpile and minify output JavaScript code.

Build browser compatible bundle with esbuild:

yarn build:browser

There are some npm scripts that will help during development:

Run tests:

yarn test

Serve tests during development or fixing:

yarn test:watch

Check types with TypeScript compiler:

yarn type-check

Lint source code:

yarn lint

Check out CHANGELOG.md and package.json files for release version changes:

yarn rsc %release-version%

Example: yarn rsc 1.0.0-rc.0

Built and tested on node v14.18.1.

Building the documentation

We use the Typedoc tool to compile docs from the source code, you can build it for the local usage by running this command:

yarn docs

The ouput appears in the docs folder.

Changelog

All notable changes to this project will be documented in the change log. This project adheres to semantic versioning.