test-actions-bump-substrate-client

SDK npm

Be aware, this is ALPHA version, package is under construction.

Table of Contents

• @unique-nft/substrate-client
• Installation
• Initialize
• Design
  • Modules
  • Mutation and Query method

unique-nft/substrate-client

Substrate Client is a JavaScript/TypeScript library that helps to interact with UniqueNetwork using simple methods instead of low-level API. With SDK you can mint collections and tokens, manage account balance, etc. At the moment, the library is a pre-alpha version. We will be grateful for the feedback and ideas for improvement.

Installation

npm

npm install @unique-nft/substrate-client

yarn

yarn add @unique-nft/substrate-client

git

git clone https://github.com/UniqueNetwork/unique-sdk
cd unique-sdk
npm install
npm run build:substrate-client

---

Initialize SDK

import { createSigner } from '@unique-nft/substrate-client/sign';
import { Client } from '@unique-nft/substrate-client';
import fetch from 'node-fetch';

(async () => {
  const client = await Client.create({
    chainWsUrl: 'wss://quartz.unique.network',
    signer: await createSigner({
      seed: '//Alice', // Signer seed phrase if you want to sign extrinsics
    }),
    erc721: { // enable this option to parse ERC721 tokens
      fetch: async (url: string) => {
          const response = await fetch(url);
          if (!response.ok) throw new Error(response.statusText);
          try {
              return await response.json();
          } catch (e) {
              return true;
          }
      },
      ipfsGateways: ['https://ipfs.io', 'https://gateway.ipfs.io'],
    },
  });
})();

---

Design

Unique SDK was developed as an add-on of Polkadot{.js} ApiPromise, extending it with simple methods to work with the Unique Network blockchains (Opal, Quartz, Unique). However, Unique SDK can be used with any network based on the Substrate framework - main modules (extrinsics, balance, query, sign, etc.) will work with them.

---

Modules

By default, the SDK implements only a connection to the blockchain network, and modules expand its capabilities. Modules are implemented as secondary endpoints of npm package, this allows you to flexibly manage dependencies, not include unnecessary modules into the application bundle assembly and expand the SDK with your own modules.

import { Client } from '@unique-nft/substrate-client';

// ...

import '@unique-nft/substrate-client/extrinsics'; // Augment SDK with the `extrinsic` property

// ...

import { addFeature } from '@unique-nft/substrate-client';

class MyOwnSdkModule {
  constructor(private client: Client) {}

  public hello() {
    return 'world!';
  }
}

declare module '@unique-nft/substrate-client' {
  export interface Client {
    myOwnFeature: MyOwnSdkModule;
  }
}

addFeature('myOwnFeature', MyOwnSdkModule);

console.log(client.myOwnFeature.hello());

Currently, the SDK includes 5 modules

• Extrinsics - for building, signing, and submitting extrinsics
• State Queries - blockchain queries storage
• Sign - account management: sign, addresses
• Balance - get and transfers native substrate token
• Tokens - operations with NFT of Unique Network blockchains (Opal, Unique, Quartz)

Modules can be dependent on each other. For example, the Balance Module depends on the Extrinsic Module because it generates transfer extrinsic and submits them to the blockchain.

---

Mutation and Query methods

We have classified all SDK methods into two types

1. Query methods for reading blockchain storage (e.g. balance, or token properties)

import '@unique-nft/substrate-client/tokens';

const collectionId = 1;
const tokenId = 3456;
const token = await client.tokens.get({ collectionId, tokenId });

1. Mutation methods for updating the state of the blockchain

const transferArgs = {
  tokenId,
  collectionId,
  from: addressFrom,
  to: addressTo,
};
const unsignedExtrinsic = await client.tokens.transfer(transferArgs);

---

Query methods

Queries to blockchain storage that return data in a human-readable format

const address = 'unjKJQJrRd238pkUZZvzDQrfKuM39zBSnQ5zjAGAGcdRhaJTx';
/**
 * returns
 * {
 *  "raw": "0",
 *  "amount": 0,
 *  "amountWithUnit": "0",
 *  "formatted": "0",
 *  "unit": "UNQ"
 * }
 */
const { raw, amount, amountWithUnit, formatted, unit } = await client.balance.get({
  address,
});

---

Mutation methods

By default, they return an unsigned extrinsic. To apply this change in the blockchain state, you must sign it

import { createSigner } from '@unique-nft/substrate-client/sign';
const signer: ClientSigner = await createSigner(signerOptions);
const unsignedExtrinsic = await client.tokens.transfer(transferArgs);
const { signature, signatureType } = await signer.sign(unsignedExtrinsic);

And send the extrinsic and the signature in the blockchain

const hash = await client.extrinsics.submit({
  signature,
  signerPayloadJSON: unsignedExtrinsic.signerPayloadJSON,
});

For more convenience, we have implemented a complex method: if you initialize the SDK with a signer, you can sign and send extrinsics seamlessly, without separate actions

import { CreateCollectionArguments } from '@unique-nft/substrate-client/types';
import { createSigner } from '@unique-nft/substrate-client/sign';
import { Client } from '@unique-nft/substrate-client';
import '@unique-nft/substrate-client/tokens';

const client = await Client.create({
  chainWsUrl: 'wss://quartz.unique.network',
  signer: await createSigner({
    seed: '//Alice', // Signer seed phrase
  }),
});

const myCollection: CreateCollectionArguments = {
  address: 'unjKJQJrRd238pkUZZvzDQrfKuM39zBSnQ5zjAGAGcdRhaJTx',
  description: 'Just sample collection',
  name: 'Sample',
  tokenPrefix: 'SMPL',
  properties: {},
};

/**
 * returns unsigned extrinsic
 */
const unsignedExtrinsic = await client.collections.creation.build(myCollection);

/**
 * return signed extrinsic (unsigned extrinsic + signature + signature type)
 */
const signedExtrinsic = await client.collections.creation.sign(myCollection);

/**
 * submitting extrinsic and returns extrinsic hash
 */
const { hash } = await client.collections.creation.submit(myCollection);

/**
 * submitting extrinsic and returns Observable of extrinsic progress
 */
const newCollection$ = client.collections.creation.submitWatch(myCollection);

newCollection$.subscribe({
  next: (next) =>
    console.log(next.parsed?.collectionId || next.submittableResult.status),
});

/**
 * submitting extrinsic, returns final extrinsic result (status, events, other human info) and parsed data
 */
const result = await client.collections.creation.submitWaitResult(myCollection);

console.log(`Created collection with id ${result.parsed.collectionId}`);

/**
 * Signer may be provided as option
 */

const signer = new SeedSigner({ seed: '//Bob' });
await client.collections.creation.submitWaitResult(myCollection, { signer });