@near-js/client

This package provides a simple interface for interacting with the Near blockchain. As a modern, tree-shakeable package, it is intended to replace usage of near-api-js.

Installation

# npm
npm i -s @near-js/client

# pnpm
pnpm add @near-js/client

Usage

Dependency Initialization

This package uses a common interface for specifying dependencies for RPC providers and cryptographic signing, allowing a more flexible approach to composing functionality.

RPC provider

RPC providers are required for any blockchain interaction, e.g. block queries, transaction publishing.

This interface makes use of the FallbackRpcProvider, making it configurable with multiple RPC endpoint URLs which can be cycled through when the current URL returns an error.

Specifying by URL endpoints:

import { getProviderByEndpoints } from '@near-js/client';

const rpcProvider = getProviderByEndpoints('https://rpc.tld', 'https://fallback-rpc.tld');

Specifying by network (uses default RPC endpoints specified in code):

import { getProviderByNetwork } from '@near-js/client';

const rpcProvider = getProviderByNetwork('testnet');

Shortcut methods:

import { getTestnetRpcProvider } from '@near-js/client';

// equivalent to getProviderByNetwork('testnet');
const rpcProvider = getTestnetRpcProvider();

Message Signer

Implementers of the MessageSigner interface can be initialized from the existing KeyStore classes or using private keys.

Using an existing keystore:

import { getSignerFromKeystore } from '@near-js/client';
import { BrowserLocalStorageKeyStore } from '@near-js/keystores-browser';

const keystore = new BrowserLocalStorageKeyStore();
const signer = getSignerFromKeystore('account.near', 'mainnet', keystore);

Using a private key string:

import { getSignerFromKeystore } from '@near-js/client';
import { BrowserLocalStorageKeyStore } from '@near-js/keystores-browser';

const signer = getSignerFromPrivateKey('ed25519:...');

An access key-based signer is also available. Initialized using a MessageSigner implementer, this signer caches the access key record and maintains a local, auto-incremented value for its nonce:

import { getAccessKeySigner, getMainnetRpcProvider, getSignerFromPrivateKey } from '@near-js/client';
import { BrowserLocalStorageKeyStore } from '@near-js/keystores-browser';

const keystore = new BrowserLocalStorageKeyStore();
const signer = getSignerFromKeystore('account.near', 'mainnet', keystore);
const accessKeySigner = getAccessKeySigner({
  accout: 'account.near',
  deps: {
    signer,
    rpcProvider: getMainnetRpcProvider(),
  },
});

View Methods

Several functions are provided for working with builtin account methods and smart contract view methods.

Executing a view method on a smart contract and return the entire response:

import { callViewMethod, getTestnetRpcProvider } from '@near-js/client';

const response = await callViewMethod({
  account: 'guest-book.testnet',
  method: 'getMessages',
  deps: { rpcProvider: getTestnetRpcProvider() },
});

Shorthand function to call the method and return only the parsed value:

import { getTestnetRpcProvider, view } from '@near-js/client';

interface GuestBookMessage {
  premium: boolean;
  sender: string;
  text: string;
}

// parse the returned buffer and parse as JSON
const data = await view<GuestBookMessage[]>({
  account: 'guest-book.testnet',
  method: 'getMessages',
  deps: { rpcProvider: getTestnetRpcProvider() },
});

Client method for requesting access keys:

import { getAccessKeys, getTestnetRpcProvider } from '@near-js/client';

const { fullAccessKeys, functionCallAccessKeys } = await getAccessKeys({
  account: 'account.testnet',
  deps: { rpcProvider: getTestnetRpcProvider() },
});

Transactions

New *Composer classes facilitate transaction building and signing:

import {
  getSignerFromKeystore,
  getTestnetRpcProvider,
  SignedTransactionComposer,
} from '@near-js/client';
import { KeyPairEd25519 } from '@near-js/crypto';
import { BrowserLocalStorageKeyStore } from '@near-js/keystores-browser';

const keystore = new BrowserLocalStorageKeyStore();
const signer = getSignerFromKeystore('account.testnet', 'testnet', keystore);

const oldPublicKey = await signer.getPublicKey();
const newKeyPair = KeyPairEd25519.fromRandom();

const composer = SignedTransactionComposer.init({
  sender: 'account.testnet',
  receiver: 'receiver.testnet',
  deps: {
    signer,
    rpcProvider: getMainnetRpcProvider(),
  }
});

// add new key and remove old key in single transaction
await composer
  .addFullAccessKey(newKeyPair.publicKey)
  .deleteKey(oldPublicKey.toString())
  .signAndSend();

keystore.setKey('testnet', 'account.testnet', newKeyPair);

For convenience, there are also functions wrapping individual actions, e.g. transfer:

import {
  getSignerFromKeystore,
  getTestnetRpcProvider,
  transfer,
} from '@near-js/client';
import { KeyPairEd25519 } from '@near-js/crypto';
import { BrowserLocalStorageKeyStore } from '@near-js/keystores-browser';

const keystore = new BrowserLocalStorageKeyStore();
const signer = getSignerFromKeystore('account.testnet', 'testnet', keystore);

await transfer({
  sender: 'account.testnet',
  receiver: 'receiver.testnet',
  amount: 1000n, // in yoctoNear
  deps: {
    rpcProvider: getTestnetRpcProvider(),
    signer,
  }
});

License

This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE and LICENSE-APACHE for details.