by Unity Nodes
near-api-jsStable

near-api-js 7.0.0

v7.0.0github.com

#1691 f8666a0 Thanks @r-near! - Update parseNearAmount to only accept either a numeric string, or actual number, and not undefined, as well as throw error rather than silently return null; #1691 f8666a0 Thanks @r-near!…

Open on GitHub (opens in a new tab)

Major Changes

  • #1691 f8666a0 Thanks @r-near! - Update parseNearAmount to only accept either a numeric string, or actual number, and not undefined, as well as throw error rather than silently return null

  • #1691 f8666a0 Thanks @r-near! - Rename stable viewValidatorsV2 function back to viewValidators

  • #1809 eee87c2 Thanks @gagdiez! - Consolidate functionality of the @near-js/* packages into a single, tree-shakeable near-api-js package

  • #1805 9356419 Thanks @denbite! - Remove no longer needed error utils like getErrorTypeFromErrorMessage, parseRpcError, parseResultError, etc from the package as errors are now handled internally thanks to strongly typed RPC errors and end users can simply catch them in their application using specific error classes imported from rpc-errors sub-path

  • #1781 1caddf4 Thanks @denbite! - Replace TypedError class with a few specific errors created from fully type-safe RPC interfaces

  • #1808 bf7c148 Thanks @denbite! - Rename TypedContract back to Contract

  • #1669 683e1db Thanks @denbite! - Remove no longer maintained packages @near-js/iframe-rpc, @near-js/biometric-ed25519 and @near-js/client with @near-js/cookbook examples

  • #1670 54e4d48 Thanks @denbite! - Remove no longer maintained packages @near-js/keystores, @near-js/keystores-node and @near-js/keystores-browser

  • #1673 5d86344 Thanks @denbite! - Consolidate @near-js/* packages into a single near-api-js codebase

  • #1795 b96c604 Thanks @denbite! - Renovate Provider.query by removing the deprecated inline-argument overload and fully aligning the method with the nearcore RPC API spec.

    Previously supported (no longer works):

    provider.query("view_account", JSON.stringify({ ... }));

    New required usage (fully typed):

    provider.query({
  request_type: "view_account",
  ...
});

    Once request_type is specified, remaining parameters are inferred automatically by the IDE.

  • #1668 20672fb Thanks @denbite! - Remove deprecated functionality

  • #1813 858783c Thanks @gagdiez! - Renamed actionCreator helper object to simply "actions", and separated the helper addKey into addFullAccessKey and addFunctionCallKey

  • #1589 5cfdab8 Thanks @AlexKushnir1! - Refactor the abstract class Signer to implement every method, except for getPublicKey and signBytes, which are intended for users

Minor Changes

  • #1790 2f7a30d Thanks @denbite! - Introduce many specific errors based on generated response types from OpenAPI spec and which are thrown when calling Provider.sendJsonRpc method

  • #1798 a52592b Thanks @gagdiez! - Added a new multi-key signer which handles multiples keys and transparently rotates them as users ask to sign transactions

  • #1751 85f279e Thanks @denbite! - Add nep413 module that implements signMessage and verifyMessage functions

  • #1748 917ccea Thanks @denbite! - Make Account to take KeyPairString as third parameter

  • #1761 9d8799b Thanks @denbite! - Introduce teraToGas and gigaToGas helper functions to convert Gas amounts conviniently

  • #1761 fcbb1fe Thanks @denbite! - Introduce yoctoToNear and nearToYocto helper functions

  • #1796 c2601e2 Thanks @denbite! - Add a new Provider.viewGlobalContractCode method for retrieving global contract code using either a codeHash, or an accountId identifier.

    Example usage:

    provider.viewGlobalContractCode({
  identifier: { accountId: "global_contract.near" },
});
provider.viewGlobalContractCode({
  identifier: { codeHash: "J1arLz48fgXcGyCPVckFwLnewNH6j1uw79thsvwqGYTY" },
});

  • #1799 a7c3cd9 Thanks @denbite! - Add parseSeedPhrase method, exported via the seed-phrase sub-path, which converts a string seed phrase into a KeyPair.

    For example:

    import { parseSeedPhrase } from "near-api-js/seed-phrase";

const keyPair = parseSeedPhrase("tag interest match ...");

keyPair.getPublicKey().toString(); // ed25519:9uMmkWHW...
keyPair.toString(); // ed25519:3N6TYZVRrkQxh...

  • #1747 493d9e5 Thanks @denbite! - Add sub-path exports for "tokens", "tokens/mainnet" and "tokens/testnet" to improve tree-shaking

  • #1794 7b6ff4f Thanks @denbite! - Extend the Account constructor to accept an RPC URL string in addition to a Provider, making account instantiation simpler and more ergonomic.

    New supported usage:

    new Account("user.near", "https://rpc.testnet.near.org");

    Previously, users had to always manually create a provider:

    const provider = new JsonRpcProvider({ url: "https://rpc.testnet.near.org" });
new Account("user.near", provider);

  • #1803 9f3e14d Thanks @denbite! - Export strongly typed RPC error classes behind the rpc-errors sub-path, for end users to reliably handle specific RPC failures.

    For example, end users can now catch action-level errors (e.g. when a transaction fails because the recipient account does not exist):

    import { AccountDoesNotExistActionError } from "near-api-js/rpc-errors";

try {
  await account.transfer({
    amount: nearToYocto(0.01),
    receiverId: "unexisted_account_111.testnet",
  });
} catch (error) {
  if (error instanceof AccountDoesNotExistActionError) {
    console.error(
      `Transaction ${error.txHash} failed because recipient ${error.accountId} does not exist!`
    );
  }
}

    Or, RPC request validation and parsing errors can also be handled explicitly (e.g. when an invalid account ID format is included in a transaction):

    import { RpcRequestParseError } from "near-api-js/rpc-errors";

try {
  await account.transfer({
    amount: nearToYocto(0.001),
    receiverId: "account_name_that_fail_validation%.testnet",
  });
} catch (error) {
  if (error instanceof RpcRequestParseError) {
    // Failed parsing args: the value could not be decoded from borsh due to:
    // invalid value: "account_name_that_fail_validation%.testnet",
    // the Account ID contains an invalid character '%' at index 33
    console.error(error.message);
  }
}

    Or, some requests may reference data that is no longer available or cannot be resolved by the node (e.g. querying a block that cannot be found):

    import { UnknownBlockError } from "near-api-js/rpc-errors";

const unexistedBlockHeight = 1_000_000_000_000_000;

try {
  await provider.viewBlock({ blockId: unexistedBlockHeight });
} catch (error) {
  if (error instanceof UnknownBlockError) {
    console.error(
      `Block at height ${unexistedBlockHeight} could not be found on the node!`
    );
  }
}

    All exported errors ultimately extend the RpcError base class, so applications can also catch and handle any RPC-related error in a single place when fine-grained handling is not required:

    import { RpcError } from "near-api-js/rpc-errors";

try {
  await provider.viewAccessKey({
    accountId: "user.testnet",
    publicKey: "ed25519:EaQnZxCMwh9yhkqW2XE2umd21iNmXep1BkM6Wtw2Qr1b",
  });
} catch (error) {
  if (error instanceof RpcError) {
    // Access key ed25519:EaQnZx... does not exist at block height ...
    console.error(error.message);
  }
}

try {
  await provider.viewAccessKey({
    accountId: "user.testnet",
    publicKey: "ed25519:EaQnZxCMwh9yhkqW2XE2umd21iNmXep1BkM6Wtw2Qr1bxxxx", // invalid key here
  });
} catch (error) {
  if (error instanceof RpcError) {
    // Failed parsing args: invalid key length: expected the input of 32 bytes, but 33 was given
    console.error(error.message);
  }
}

  • #1754 b3b2947 Thanks @gagdiez! - Added optional signer argument to signing functions on account class

  • #1793 ddceeab Thanks @denbite! - Add concurrent transactions support by introducing nonce caching and automatic retries on InvalidNonceError.

    The following example that previously failed due to nonce collisions, now works reliably:

    await Promise.all([
  account.transfer({
    amount: nearToYocto(1),
    receiverId: "user1.testnet",
  }),
  account.transfer({
    amount: nearToYocto(2),
    receiverId: "user2.testnet",
  }),
  account.transfer({
    amount: nearToYocto(3),
    receiverId: "user3.testnet",
  }),
]);

Patch Changes

All near-api-js releases