near-api-ts 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,5 @@
 ## NEAR API TS
-Typescript library for interactions with Near Protocol in the browser or Node.js
+TypeScript library for interactions with Near Protocol in the browser or Node.js
 
 [GitHub Repository](https://github.com/eclipseeer/near-api-ts/tree/main)
 
@@ -15,19 +15,20 @@ import {
   createTestnetClient,
   createMemoryKeyService,
   createMemorySigner,
-  testnet,
   transfer,
+  near,
+  isNatError,
 } from 'near-api-ts';
 
-// Create a near testnet client
+// Read some data from the chain
 const client = await createTestnetClient();
 
-
-// Read some data from the chain
-await client.getAccountState({
+const { accountInfo } = await client.getAccountInfo({
   accountId: 'testnet',
   atMomentOf: 'LatestFinalBlock',
 })
+console.log(accountInfo.balance.total.near)
+console.log(accountInfo.balance.total.yoctoNear)
 
 // Send some transaction
 const keyService = await createMemoryKeyService({
@@ -41,9 +42,31 @@ const signer = await createMemorySigner({
 });
 
 await signer.executeTransaction({
-  action: transfer({ amount: { yoctoNear: '1' } }),
-  receiverAccountId: 'some-receiver.testnet',
+  intent: {
+    action: transfer({ amount: { yoctoNear: '1' } }),
+    receiverAccountId: 'some-receiver.testnet',
+  }
+});
+
+// Handle transaction errors
+try {
+  const txResult = await signer.executeTransaction({
+    intent: {
+      action: transfer({ amount: near('10000000000') }),
+      receiverAccountId: 'some-receiver.testnet',
+    },
+  });
+} catch (e) {
+  if (isNatError(e, 'MemorySigner.ExecuteTransaction.Rpc.Transaction.Signer.Balance.TooLow')) {
+    console.log(e.context.transactionCost)
+  }
+}
+
+// Use library functions in 'safe' mode
+const maybeBlock = await client.safeGetBlock({
+  blockReference: { blockHeight: 10000000000000 },
 });
+console.log(maybeBlock); // { ok: false, error: NatError: <{ kind: 'Client.GetBlock.Rpc.Block.NotFound', context: null }> }
 ```
 
 You may found more examples in the [examples/nodejs/ts-esm](https://github.com/eclipseeer/near-api-ts/tree/main/examples/nodejs/ts-esm)

package/dist/index.d.cts

@@ -775,7 +775,9 @@ type BaseDeserializeResult = ({ rawResult, }: {
     rawResult: RawCallResult;
 }) => unknown;
 type MaybeBaseDeserializeResult = BaseDeserializeResult | undefined;
-type BaseSerializeArgs<A> = (args: {
+type BaseSerializeArgs<A> = [A] extends [undefined] ? (args?: {
+    functionArgs: A;
+}) => Uint8Array : (args: {
     functionArgs: A;
 }) => Uint8Array;
 type BaseFnCallArgs = {

package/dist/index.d.ts

@@ -775,7 +775,9 @@ type BaseDeserializeResult = ({ rawResult, }: {
     rawResult: RawCallResult;
 }) => unknown;
 type MaybeBaseDeserializeResult = BaseDeserializeResult | undefined;
-type BaseSerializeArgs<A> = (args: {
+type BaseSerializeArgs<A> = [A] extends [undefined] ? (args?: {
+    functionArgs: A;
+}) => Uint8Array : (args: {
     functionArgs: A;
 }) => Uint8Array;
 type BaseFnCallArgs = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-api-ts",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Typescript library for interactions with Near Protocol in the browser or Node.js",
   "type": "module",
   "exports": {
@@ -34,13 +34,12 @@
     "test:all": "vitest run"
   },
   "dependencies": {
-    "@near-js/jsonrpc-types": "^1.4.0",
+    "@near-js/jsonrpc-types": "^1.5.0",
     "@noble/curves": "^1.9.4",
     "@noble/hashes": "^1.8.0",
     "@scure/base": "^1.2.6",
     "borsh": "^2.0.0",
     "lodash-es": "^4.17.21",
-    "valibot": "^1.1.0",
-    "zod": "^4.0.11"
+    "zod": "^4.1.13"
   }
 }

package/src/_common/configs/constants.ts

@@ -1,23 +1,16 @@
-export const BinaryCryptoKeyLengths = {
+export const BinaryLengths = {
   Ed25519: {
-    // SecretKey + PublicKey
-    PrivateKey: 64,
+    PrivateKey: 64, // SecretKey + PublicKey
     SecretKey: 32,
     PublicKey: 32,
+    Signature: 64,
   },
   Secp256k1: {
-    // SecretKey + PublicKey
-    PrivateKey: 96,
+    PrivateKey: 96, // SecretKey + PublicKey
     SecretKey: 32,
     PublicKey: 64,
+    Signature: 65,
   },
 } as const;
 
-export const BinaryCryptoHashLength = 32;
 export const NearDecimals = 24;
-
-// Fetch block every 1000 blocks * 600ms best block time = >10 minutes
-export const RefetchBlockHashInterval = 600_000;
-
-// 1 minute
-export const SignerTaskTtlMs = 60_000 as const

package/src/_common/natError.ts

@@ -0,0 +1,50 @@
+import type {
+  NatErrorKind,
+  CreateNatErrorArgs,
+  ContextFor,
+} from 'nat-types/natError';
+
+export const NatErrorBrand = Symbol('NatError');
+
+export class NatError<K extends NatErrorKind> extends Error {
+  public readonly [NatErrorBrand] = true;
+  public readonly kind: K;
+  public readonly context: ContextFor<K>;
+
+  constructor(args: CreateNatErrorArgs<K>) {
+    super(`<${args.kind}>`);
+    this.name = 'NatError';
+    this.kind = args.kind;
+    this.context = args.context;
+  }
+}
+
+export const createNatError = <K extends NatErrorKind>(
+  args: CreateNatErrorArgs<K>,
+): NatError<K> => new NatError(args);
+
+export const isNatError = <K extends NatErrorKind>(
+  error: unknown,
+  kind?: K,
+): error is NatError<K> => {
+  const isNatErr =
+    typeof error === 'object' && error !== null && NatErrorBrand in error;
+
+  if (kind === undefined) return isNatErr;
+  return isNatErr && (error as NatError<K>)?.kind === kind;
+};
+
+type NatErrorUnion<K extends readonly NatErrorKind[]> = {
+  [I in keyof K]: NatError<K[I]>;
+}[number];
+
+export const isNatErrorOf = <const K extends readonly NatErrorKind[]>(
+  error: unknown,
+  kinds: K,
+): error is NatErrorUnion<K> => {
+  const isNatErr =
+    typeof error === 'object' && error !== null && NatErrorBrand in error;
+
+  if (!isNatErr) return false;
+  return kinds.includes((error as NatError<any>).kind);
+};

package/src/_common/schemas/borsh/index.ts

@@ -1,3 +1,2 @@
 export * from './transaction';
-export * from './signedTransaction';
 export * from './delegateAction';

package/src/_common/schemas/borsh/transaction.ts

@@ -11,6 +11,7 @@ import { stakeActionBorshSchema } from './actions/stake';
 import { deleteKeyActionBorshSchema } from './actions/deleteKey';
 import { deleteAccountActionBorshSchema } from './actions/deleteAccount';
 import { signedDelegateActionBorshSchema } from './actions/signedDelegate';
+import { signatureBorshSchema } from '@common/schemas/borsh/signature';
 
 // Actions order in this enum is important and must match nearcore
 const actionBorshSchema: Schema = {
@@ -40,3 +41,10 @@ export const transactionBorshSchema: Schema = {
     actions: { array: { type: actionBorshSchema } },
   },
 };
+
+export const signedTransactionBorshSchema: Schema = {
+  struct: {
+    transaction: transactionBorshSchema,
+    signature: signatureBorshSchema,
+  },
+};

package/src/_common/schemas/zod/client.ts

@@ -0,0 +1,34 @@
+import * as z from 'zod/mini';
+import { PartialTransportPolicySchema } from '../../../client/transport/transportPolicy';
+import {
+  BlockHashSchema,
+  BlockHeightSchema,
+} from '@common/schemas/zod/common/common';
+
+export const PoliciesSchema = z.optional(
+  z.object({
+    transport: PartialTransportPolicySchema,
+  }),
+);
+
+export const BaseOptionsSchema = z.optional(
+  z.object({
+    signal: z.optional(z.instanceof(AbortSignal)),
+  }),
+);
+
+export const BlockReferenceSchema = z.union([
+  z.literal('LatestOptimisticBlock'),
+  z.literal('LatestNearFinalBlock'),
+  z.literal('LatestFinalBlock'),
+  z.literal('EarliestAvailableBlock'),
+  z.literal('GenesisBlock'),
+  z.object({
+    blockHash: BlockHashSchema,
+    blockHeight: z.optional(z.never()),
+  }),
+  z.object({
+    blockHash: z.optional(z.never()),
+    blockHeight: BlockHeightSchema,
+  }),
+]);

package/src/_common/schemas/zod/common/accountId.ts

@@ -0,0 +1,11 @@
+import * as z from 'zod/mini';
+import { oneLine } from '@common/utils/common';
+
+export const AccountIdSchema = z.string().check(
+  z.minLength(2),
+  z.maxLength(64),
+  z.regex(/^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/, {
+    error: oneLine(`Account ID may contain only lowercase letters (a–z), 
+    digits (0–9), and separators (., -, _).`),
+  }),
+);

package/src/_common/schemas/zod/common/common.ts

@@ -0,0 +1,16 @@
+import * as z from 'zod/mini';
+import { CryptoHashSchema } from '@common/schemas/zod/common/cryptoHash';
+
+export const BlockHashSchema = CryptoHashSchema;
+export const BlockHeightSchema = z.number().check(z.nonnegative());
+export const BlockIdSchema = z.union([BlockHeightSchema, BlockHashSchema]);
+
+export const NonceSchema = z.number().check(z.int(), z.nonnegative());
+
+export const ContractFunctionNameSchema = z
+  .string()
+  .check(z.minLength(1), z.maxLength(256));
+
+// TODO Zod doesn't allow to pass objects with undefined fields
+//  like { a: 1, b: undefined }. But our types allow it. Need to fix zod schema.
+export const JsonSchema = z.json();

package/src/_common/schemas/zod/common/cryptoHash.ts

@@ -0,0 +1,25 @@
+import * as z from 'zod/mini';
+import { base58 } from '@scure/base';
+import { oneLine } from '@common/utils/common';
+
+const Base58StringSchema = z.string().check(
+  z.regex(
+    /^[1-9A-HJ-NP-Za-km-z]+$/,
+    oneLine(`Base58 string contains invalid characters. Allowed characters:
+    123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`),
+  ),
+);
+
+export const CryptoHashSchema = z
+  .pipe(
+    Base58StringSchema,
+    z.transform((cryptoHash) => {
+      const u8CryptoHash = base58.decode(cryptoHash);
+      return { cryptoHash, u8CryptoHash };
+    }),
+  )
+  .check(
+    z.refine(({ u8CryptoHash }) => u8CryptoHash.length === 32, {
+      error: 'Crypto hash length should be 32 bytes',
+    }),
+  );

package/src/_common/schemas/zod/common/curveString.ts

@@ -0,0 +1,22 @@
+import * as z from 'zod/mini';
+import { oneLine } from '@common/utils/common';
+import type { Curve, CurveString } from 'nat-types/_common/curveString';
+import { base58 } from '@scure/base';
+
+export const CurveStringSchema = z.pipe(
+  z.string().check(
+    z.regex(
+      /^(ed25519|secp256k1):[1-9A-HJ-NP-Za-km-z]+$/,
+      oneLine(`Curve strings should use the 
+      ed25519:<base58String> or secp256k1:<base58String> format.`),
+    ),
+  ),
+  z.transform((curveString: CurveString) => {
+    const [curve, base58String] = curveString.split(':');
+    return {
+      curveString,
+      curve: curve as Curve,
+      u8Data: base58.decode(base58String),
+    };
+  }),
+);

package/src/_common/schemas/zod/common/nearGas.ts

@@ -0,0 +1,33 @@
+import * as z from 'zod/mini';
+
+export const GasInputSchema = z.union([
+  z.bigint(),
+  z.pipe(
+    z.number().check(z.int()),
+    z.transform((v) => BigInt(v)),
+  ),
+]);
+
+const createTeraGasInputSchema = (decimals: number) =>
+  z.string().check(
+    z.refine(
+      (val) => {
+        const decimalPattern = new RegExp(`^\\d+(?:\\.\\d{1,${decimals}})?$`);
+        return decimalPattern.test(val);
+      },
+      {
+        message: `Must be a valid number with up to ${decimals} decimal places`,
+      },
+    ),
+  );
+
+export const TeraGasInputSchema = createTeraGasInputSchema(12);
+
+export const NearGasArgsSchema = z.union([
+  z.object({
+    gas: GasInputSchema,
+  }),
+  z.object({
+    teraGas: TeraGasInputSchema,
+  }),
+]);

package/src/_common/schemas/zod/common/nearToken.ts

@@ -0,0 +1,54 @@
+import * as z from 'zod/mini';
+
+/**
+ * Validate a positive decimal string with an optional fractional part
+ * whose length is limited by `decimals`:
+ *
+ * Pattern: ^\d+(?:\.\d{1,decimals})?$
+ * - ^                  : anchor at start — match the whole string only
+ * - \d+                : integer part — one or more digits (requires a digit before the dot)
+ * - (?: ... )          : non-capturing group for the optional fractional part
+ * - \.                 : literal dot
+ * - \d{1,decimals}     : 1 to decimals digits after the dot
+ * - ?                  : make the fractional group optional (allow integers)
+ * - $                  : anchor at end — no extra chars allowed
+ *
+ * Notes:
+ * - Disallows ".5" (no integer part) and "5." (no fractional digits).
+ * - Disallows signs, spaces, commas, exponent notation, etc.
+ * - Allows leading zeros in the integer part (e.g., "0001", "0.05").
+ *
+ * Examples (decimals = 2):
+ *   ✓ "0", "12", "3.4", "10.00"
+ *   ✗ ".5", "5.", "1.234", "-1", "1e3", " 1"
+ */
+const createTokensInputSchema = (decimals: number) =>
+  z.string().check(
+    z.refine(
+      (val) => {
+        const decimalPattern = new RegExp(`^\\d+(?:\\.\\d{1,${decimals}})?$`);
+        return decimalPattern.test(val);
+      },
+      {
+        message: `Must be a valid number with up to ${decimals} decimal places`,
+      },
+    ),
+  );
+
+export const NearInputSchema = createTokensInputSchema(24);
+
+const BigintStringSchema = z.pipe(
+  z.string().check(z.regex(/^\d+$/, 'Must contain only digits')),
+  z.transform((v) => BigInt(v)),
+);
+
+export const YoctoNearInputSchema = z.union([z.bigint(), BigintStringSchema]);
+
+export const NearTokenArgsSchema = z.union([
+  z.object({
+    near: NearInputSchema,
+  }),
+  z.object({
+    yoctoNear: YoctoNearInputSchema,
+  }),
+]);

package/src/_common/schemas/zod/common/privateKey.ts

@@ -0,0 +1,26 @@
+import * as z from 'zod/mini';
+import { BinaryLengths } from '@common/configs/constants';
+import { CurveStringSchema } from '@common/schemas/zod/common/curveString';
+
+const { Ed25519, Secp256k1 } = BinaryLengths;
+
+export const PrivateKeySchema = z
+  .pipe(
+    CurveStringSchema,
+    z.transform((val) => ({
+      privateKey: val.curveString,
+      u8PrivateKey: val.u8Data,
+      curve: val.curve,
+    })),
+  )
+  .check(
+    z.refine(
+      ({ curve, u8PrivateKey }) =>
+        curve === 'ed25519'
+          ? u8PrivateKey.length === Ed25519.PrivateKey
+          : u8PrivateKey.length === Secp256k1.PrivateKey,
+      { error: 'Invalid private key length' },
+    ),
+  );
+
+export type InnerPrivateKey = z.infer<typeof PrivateKeySchema>;

package/src/_common/schemas/zod/common/publicKey.ts

@@ -0,0 +1,26 @@
+import * as z from 'zod/mini';
+import { BinaryLengths } from '@common/configs/constants';
+import { CurveStringSchema } from '@common/schemas/zod/common/curveString';
+
+const { Ed25519, Secp256k1 } = BinaryLengths;
+
+export const PublicKeySchema = z
+  .pipe(
+    CurveStringSchema,
+    z.transform((val) => ({
+      publicKey: val.curveString,
+      u8PublicKey: val.u8Data,
+      curve: val.curve,
+    })),
+  )
+  .check(
+    z.refine(
+      ({ curve, u8PublicKey }) =>
+        curve === 'ed25519'
+          ? u8PublicKey.length === Ed25519.PublicKey
+          : u8PublicKey.length === Secp256k1.PublicKey,
+      { error: 'Invalid public key length' },
+    ),
+  );
+
+export type InnerPublicKey = z.infer<typeof PublicKeySchema>;

package/src/_common/schemas/zod/common/signature.ts

@@ -0,0 +1,26 @@
+import * as z from 'zod/mini';
+import { BinaryLengths } from '@common/configs/constants';
+import { CurveStringSchema } from '@common/schemas/zod/common/curveString';
+
+const { Ed25519, Secp256k1 } = BinaryLengths;
+
+export const SignatureSchema = z
+  .pipe(
+    CurveStringSchema,
+    z.transform((val) => ({
+      signature: val.curveString,
+      u8Signature: val.u8Data,
+      curve: val.curve,
+    })),
+  )
+  .check(
+    z.refine(
+      ({ curve, u8Signature }) =>
+        curve === 'ed25519'
+          ? u8Signature.length === Ed25519.Signature
+          : u8Signature.length === Secp256k1.Signature,
+      { error: 'Invalid signature length' },
+    ),
+  );
+
+export type InnerSignature = z.infer<typeof SignatureSchema>;

package/src/_common/schemas/zod/rpc.ts

@@ -1,9 +1,62 @@
 import * as z from 'zod/mini';
-import { RpcErrorSchema } from '@near-js/jsonrpc-types';
 
-export const RpcResponseSchema = z.object({
+const BaseRpcResponseSchema = z.object({
   jsonrpc: z.literal('2.0'),
-  id: z.unknown(),
-  result: z.optional(z.unknown()),
-  error: z.optional(RpcErrorSchema()),
+  id: z.number(),
 });
+
+const BaseRpcErrorSchema = z.object({
+  code: z.number(),
+  message: z.string(),
+  data: z.optional(z.unknown()),
+});
+
+const RpcErrorSchema = z.discriminatedUnion('name', [
+  z.object({
+    ...BaseRpcErrorSchema.shape,
+    name: z.literal('REQUEST_VALIDATION_ERROR'),
+    cause: z.discriminatedUnion('name', [
+      z.object({
+        name: z.literal('METHOD_NOT_FOUND'),
+        info: z.object({ methodName: z.string() }),
+      }),
+      z.object({
+        name: z.literal('PARSE_ERROR'),
+        info: z.object({ errorMessage: z.string() }),
+      }),
+    ]),
+  }),
+  z.object({
+    ...BaseRpcErrorSchema.shape,
+    name: z.literal('HANDLER_ERROR'),
+    cause: z.object({
+      info: z.unknown(),
+      name: z.string(),
+    }),
+  }),
+  z.object({
+    ...BaseRpcErrorSchema.shape,
+    name: z.literal('INTERNAL_ERROR'),
+    cause: z.object({
+      name: z.literal('INTERNAL_ERROR'),
+      info: z.object({ errorMessage: z.string() }),
+    }),
+  }),
+]);
+
+export type RpcError = z.infer<typeof RpcErrorSchema>;
+
+export const RpcResponseSchema = z.union([
+  z.object({
+    ...BaseRpcResponseSchema.shape,
+    result: z.unknown(),
+    error: z.optional(z.never()),
+  }),
+  z.object({
+    ...BaseRpcResponseSchema.shape,
+    result: z.optional(z.never()),
+    error: RpcErrorSchema,
+  }),
+]);
+
+export type RpcResponse = z.infer<typeof RpcResponseSchema>;

package/src/_common/schemas/zod/transaction/actions/addKey.ts

@@ -0,0 +1,29 @@
+import * as z from 'zod/mini';
+import { PublicKeySchema } from '@common/schemas/zod/common/publicKey';
+import { AccountIdSchema } from '@common/schemas/zod/common/accountId';
+import { ContractFunctionNameSchema } from '@common/schemas/zod/common/common';
+import { NearTokenArgsSchema } from '@common/schemas/zod/common/nearToken';
+
+const AddFullAccessKeyActionSchema = z.object({
+  actionType: z.literal('AddKey'),
+  accessType: z.literal('FullAccess'),
+  publicKey: PublicKeySchema,
+});
+
+const AddFunctionCallKeyActionSchema = z.object({
+  actionType: z.literal('AddKey'),
+  accessType: z.literal('FunctionCall'),
+  publicKey: PublicKeySchema,
+  contractAccountId: AccountIdSchema,
+  gasBudget: z.optional(NearTokenArgsSchema),
+  allowedFunctions: z.optional(
+    z.array(ContractFunctionNameSchema).check(z.minLength(1)),
+  ),
+});
+
+export const AddKeyActionSchema = z.union([
+  AddFullAccessKeyActionSchema,
+  AddFunctionCallKeyActionSchema,
+]);
+
+export type InnerAddKeyAction = z.infer<typeof AddKeyActionSchema>;

package/src/_common/schemas/zod/transaction/actions/createAccount.ts

@@ -0,0 +1,5 @@
+import * as z from 'zod/mini';
+
+export const CreateAccountActionSchema = z.object({
+  actionType: z.literal('CreateAccount'),
+});

package/src/_common/schemas/zod/transaction/actions/deleteAccount.ts

@@ -0,0 +1,11 @@
+import * as z from 'zod/mini';
+import { AccountIdSchema } from '@common/schemas/zod/common/accountId';
+
+export const DeleteAccountActionSchema = z.object({
+  actionType: z.literal('DeleteAccount'),
+  beneficiaryAccountId: AccountIdSchema,
+});
+
+export type InnerDeleteAccountAction = z.infer<
+  typeof DeleteAccountActionSchema
+>;

package/src/_common/schemas/zod/transaction/actions/deleteKey.ts

@@ -0,0 +1,9 @@
+import * as z from 'zod/mini';
+import { PublicKeySchema } from '@common/schemas/zod/common/publicKey';
+
+export const DeleteKeyActionSchema = z.object({
+  actionType: z.literal('DeleteKey'),
+  publicKey: PublicKeySchema,
+});
+
+export type InnerDeleteKeyAction = z.infer<typeof DeleteKeyActionSchema>;

package/src/_common/schemas/zod/transaction/actions/deployContract.ts

@@ -0,0 +1,10 @@
+import * as z from 'zod/mini';
+
+export const DeployContractActionSchema = z.object({
+  actionType: z.literal('DeployContract'),
+  wasmBytes: z.instanceof(Uint8Array),
+});
+
+export type InnerDeployContractAction = z.infer<
+  typeof DeployContractActionSchema
+>;

package/src/_common/schemas/zod/transaction/actions/functionCall.ts

@@ -0,0 +1,14 @@
+import * as z from 'zod/mini';
+import { NearTokenArgsSchema } from '@common/schemas/zod/common/nearToken';
+import { NearGasArgsSchema } from '@common/schemas/zod/common/nearGas';
+import { ContractFunctionNameSchema } from '@common/schemas/zod/common/common';
+
+export const FunctionCallActionSchema = z.object({
+  actionType: z.literal('FunctionCall'),
+  functionName: ContractFunctionNameSchema,
+  functionArgs: z.instanceof(Uint8Array),
+  gasLimit: NearGasArgsSchema,
+  attachedDeposit: z.optional(NearTokenArgsSchema),
+});
+
+export type InnerFunctionCallAction = z.infer<typeof FunctionCallActionSchema>;

package/src/_common/schemas/zod/transaction/actions/transfer.ts

@@ -0,0 +1,9 @@
+import * as z from 'zod/mini';
+import { NearTokenArgsSchema } from '@common/schemas/zod/common/nearToken';
+
+export const TransferActionSchema = z.object({
+  actionType: z.literal('Transfer'),
+  amount: NearTokenArgsSchema,
+});
+
+export type InnerTransferAction = z.infer<typeof TransferActionSchema>;