@near-js/client initial approach

[andy-haynes]

The upcoming client library seeks to provide a new set of functions for building client applications with Near. This new functionality is meant to be clear and easy-to-use, while addressing longstanding friction points in the current implementation. Our immediate goal is to encapsulate mid-to-high level functionality in individual, purpose-built functions which are tree-shakable.

Below are some common use cases with the current implementation and potential implementations presented. The potential implementations are by no means locked in, but instead should express the design philosophy of clarity and ease of use mentioned above. These implementations written to use IoC for complex dependencies like signers and RPC providers; the intention here is to strictly manage dependencies to make tree shaking maximally effective and cohesive without strong coupling.

View function

View functions require an RPC provider to make readonly requests. near-api-js exposes a viewFunction method (used in the code snippet below) on the Account class, which is more or less the most straightforward way of making view calls currently.

The proposed implementation reduces the amount of initialization overhead and would provide a dedicated function with clear parameters. A separate function initializes the RPC provider with minimal arguments, which the view function takes as an argument to make the request.

Current implementation

import { Account, Connection, providers } from 'near-api-js';

(async function () {
  const account = new Account(Connection.fromConfig({
    networkId: 'testnet',
    provider: new providers.JsonRpcProvider({ url: 'https://rpc.testnet.near.org' }),
    signer: {}, // signer not needed here but an object must be passed
  }), 'dontcare'); // required but not used; most string values should work here

  const app = await account.viewFunction({
    contractId: 'v1.chain-hosted-ui.testnet',
    methodName: 'get_application',
    args: { application: 'react-vite-example', account_id: 'tuster.testnet' },
  });

  console.log(app);
}());

Potential implementations

import { getRpcProvider, view } from './client';

(async function () {
  // positional parameters for intrinsic args, last argument for dependencies
  const app = await view(
    'v1.chain-hosted-ui.testnet',
    'get_application',
    { application: 'react-vite-example', account_id: 'tuster.testnet' },
    { provider: getRpcProvider('testnet') }
  );

  /* alternatively, object parameters with specified dependencies
  const app = await view({
    contract: 'v1.chain-hosted-ui.testnet',
    method: 'get_application',
    args: {
    application: 'react-vite-example', account_id: 'tuster.testnet' },
    deps: { provider: getRpcProvider('testnet') }
  });
 */

  console.log(app);
}());

Call function

Call functions add a signing component, which requires initialization of an underlying key store. It still relies on the Account class, with the represented account being the transaction signer. The method currently takes several parameters that are only applicable in very specific use cases, making it awkward for general use.

The proposed implementation exposes a dedicated method with simple arguments. Initialization of the signer is much more clear by way of a simple initialization method which can trivially be extended to accommodate other signers.

Current implementation

import {
  Account,
  Connection,
  InMemorySigner,
  keyStores,
  KeyPair,
  providers,
} from 'near-api-js';
import { SIGNER, SIGNER_KEY } from './constants';

(async function () {
  const keyStore = new keyStores.InMemoryKeyStore();
  await keyStore.setKey(
    'testnet',
    SIGNER,
    KeyPair.fromString(SIGNER_KEY)
  );

  const account = new Account(Connection.fromConfig({
    networkId: 'testnet',
    provider: new providers.JsonRpcProvider({ url: 'https://rpc.testnet.near.org' }),
    signer: new InMemorySigner(keyStore),
  }), SIGNER);

  const outcome = await account.functionCall({
    contractId: 'v1.chain-hosted-ui.testnet',
    methodName: 'get_application',
    args: { application: 'react-vite-example', account_id: 'tuster.testnet' },
    gas: 300000000000000n,
  });

  console.log(providers.getTransactionLastResult(outcome));
}());

Potential implementations

import { call, getRpcProvider, getSignerFromPrivateKey } from './client';
import { SIGNER, SIGNER_KEY } from './constants';

(async function () {
  const signer = await getSignerFromPrivateKey(SIGNER, 'testnet', SIGNER_KEY);
  const provider = getRpcProvider('testnet');

  // positional parameters for intrinsic args, last argument for dependencies
  const result = await call(
    'v1.chain-hosted-ui.testnet',
    'get_application',
    { application: 'react-vite-example', account_id: 'tuster.testnet' },
    { sender: SIGNER, signer, provider },
  );

  /* alternatively, object parameters with specified dependencies
  const result = await call({
    contract: 'v1.chain-hosted-ui.testnet',
    method: 'get_application',
    args: { application: 'react-vite-example', account_id: 'tuster.testnet' },
    deps: { sender: SIGNER, signer, provider },
  );
 */

  console.log(result);
}());

Create account

Current implementation

import {
  Account,
  Connection,
  InMemorySigner,
  KeyPair,
  keyStores,
  providers,
  utils,
} from 'near-api-js';
import { SIGNER, SIGNER_KEY } from './constants';

(async function () {
  const keyStore = new keyStores.InMemoryKeyStore();
  await keyStore.setKey(
    'testnet',
    SIGNER,
    KeyPair.fromString(SIGNER_KEY)
  );

  const keyPair = utils.KeyPairEd25519.fromRandom();
  const publicKey = keyPair.publicKey.toString();

  const config = Connection.fromConfig({
    networkId: 'testnet',
    provider: new providers.JsonRpcProvider({ url: 'https://rpc.testnet.near.org' }),
    signer: new InMemorySigner(keyStore),
  });
  const creatorAccount = new Account(config, SIGNER);

  const newAccountId = `new-account-${Date.now().valueOf()}.testnet`;
  await creatorAccount.functionCall({
    contractId: 'testnet',
    methodName: 'create_account',
    args: {
      new_account_id: newAccountId,
      new_public_key: publicKey,
    },
    gas: 300000000000000n,
    attachedDeposit: 100n,
  });

  console.log(await (new Account(config, newAccountId).state()));
}());

Potential implementations

import { KeyPairEd25519 } from '@near-js/crypto';

import { createAccount, getRpcProvider, getSignerFromPrivateKey, viewAccount } from './client';
import { SIGNER, SIGNER_KEY } from './constants';

(async function () {
  const provider = getRpcProvider('testnet');
  const signer = await getSignerFromPrivateKey(SIGNER, 'testnet', SIGNER_KEY);

  const keyPair = KeyPairEd25519.fromRandom();
  const publicKey = keyPair.publicKey;

  const newAccountId = `new-account-${Date.now().valueOf()}.testnet`;

  // positional parameters for intrinsic args, last argument for dependencies
  const result = await createAccount(newAccountId, publicKey, 'testnet', {
    provider,
    signer,
    sender: SIGNER,
    attachedDeposit: 100n,
  });

  /* alternatively, object parameters with specified dependencies
  const result = await createAccount({ newAccountId, publicKey, creatingAccountId: 'testnet', deps: {
    provider,
    signer,
    sender: SIGNER,
    attachedDeposit: 100n,
  }});
 */

  console.log(await viewAccount(newAccountId, { provider }));
}());