near-api-ts 0.2.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "near-api-ts",
+  "version": "0.2.0",
+  "description": "Typescript library for interactions with Near Protocol in the browser or Node.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "types",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "run": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.4",
+    "@noble/hashes": "^1.8.0",
+    "@scure/base": "^1.2.6",
+    "borsh": "^2.0.0",
+    "valibot": "^1.1.0",
+    "zod": "^4.0.11"
+  },
+  "devDependencies": {
+    "@near-js/jsonrpc-types": "^1.3.4"
+  }
+}

package/src/_common/configs/constants.ts

@@ -0,0 +1,23 @@
+export const BinaryCryptoKeyLengths = {
+  Ed25519: {
+    // SecretKey + PublicKey
+    PrivateKey: 64,
+    SecretKey: 32,
+    PublicKey: 32,
+  },
+  Secp256k1: {
+    // SecretKey + PublicKey
+    PrivateKey: 96,
+    SecretKey: 32,
+    PublicKey: 64,
+  },
+} 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/schemas/borsh/actions/addKey.ts

@@ -0,0 +1,44 @@
+import { publicKeyBorshSchema } from '../publicKey';
+
+const fullAccessPermissionBorshSchema = {
+  struct: {
+    fullAccess: {
+      struct: {},
+    },
+  },
+};
+
+const functionCallPermissionBorshSchema = {
+  struct: {
+    functionCall: {
+      struct: {
+        allowance: { option: 'u128' },
+        receiverId: 'string',
+        methodNames: { array: { type: 'string' } },
+      },
+    },
+  },
+};
+
+const accessKeyBorshSchema = {
+  struct: {
+    nonce: 'u64',
+    permission: {
+      enum: [
+        functionCallPermissionBorshSchema,
+        fullAccessPermissionBorshSchema,
+      ],
+    },
+  },
+};
+
+export const addKeyActionBorshSchema = {
+  struct: {
+    addKey: {
+      struct: {
+        publicKey: publicKeyBorshSchema,
+        accessKey: accessKeyBorshSchema,
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/createAccount.ts

@@ -0,0 +1,7 @@
+export const createAccountActionBorshSchema = {
+  struct: {
+    createAccount: {
+      struct: {},
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/deleteAccount.ts

@@ -0,0 +1,9 @@
+export const deleteAccountActionBorshSchema = {
+  struct: {
+    deleteAccount: {
+      struct: {
+        beneficiaryId: 'string',
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/deleteKey.ts

@@ -0,0 +1,11 @@
+import { publicKeyBorshSchema } from '../publicKey';
+
+export const deleteKeyActionBorshSchema = {
+  struct: {
+    deleteKey: {
+      struct: {
+        publicKey: publicKeyBorshSchema,
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/deployContract.ts

@@ -0,0 +1,9 @@
+export const deployContractActionBorshSchema = {
+  struct: {
+    deployContract: {
+      struct: {
+        code: { array: { type: 'u8' } },
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/deployGlobalContract.ts

@@ -0,0 +1,24 @@
+const codeHashModeBorshSchema = {
+  struct: {
+    CodeHash: { struct: {} },
+  },
+};
+
+const accountIdModeBorshSchema = {
+  struct: {
+    AccountId: { struct: {} },
+  },
+};
+
+export const deployGlobalContractActionBorshSchema = {
+  struct: {
+    deployGlobalContract: {
+      struct: {
+        code: { array: { type: 'u8' } },
+        deployMode: {
+          enum: [codeHashModeBorshSchema, accountIdModeBorshSchema],
+        },
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/functionCall.ts

@@ -0,0 +1,12 @@
+export const functionCallActionBorshSchema = {
+  struct: {
+    functionCall: {
+      struct: {
+        methodName: 'string',
+        args: { array: { type: 'u8' } },
+        gas: 'u64',
+        deposit: 'u128',
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/signedDelegate.ts

@@ -0,0 +1,13 @@
+import { delegateActionBorshSchema } from '../delegateAction';
+import { signatureBorshSchema } from '../signature';
+
+export const signedDelegateActionBorshSchema = {
+  struct: {
+    signedDelegate: {
+      struct: {
+        delegateAction: delegateActionBorshSchema,
+        signature: signatureBorshSchema,
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/stake.ts

@@ -0,0 +1,12 @@
+import { publicKeyBorshSchema } from '../publicKey';
+
+export const stakeActionBorshSchema = {
+  struct: {
+    stake: {
+      struct: {
+        stake: 'u128',
+        publicKey: publicKeyBorshSchema,
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/transfer.ts

@@ -0,0 +1,9 @@
+export const transferActionBorshSchema = {
+  struct: {
+    transfer: {
+      struct: {
+        deposit: 'u128',
+      },
+    },
+  },
+};

package/src/_common/schemas/borsh/actions/useGlobalContract.ts

@@ -0,0 +1,23 @@
+const codeHashIdentifierBorshSchema = {
+  struct: {
+    CodeHash: { array: { type: 'u8', len: 32 } },
+  },
+};
+
+const accountIdIdentifierBorshSchema = {
+  struct: {
+    AccountId: 'string',
+  },
+};
+
+export const useGlobalContractActionBorshSchema = {
+  struct: {
+    useGlobalContract: {
+      struct: {
+        contractIdentifier: {
+          enum: [codeHashIdentifierBorshSchema, accountIdIdentifierBorshSchema],
+        },
+      },
+    },
+  },
+};

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

@@ -0,0 +1,41 @@
+import type { Schema } from 'borsh';
+import { publicKeyBorshSchema } from './publicKey';
+import { createAccountActionBorshSchema } from './actions/createAccount';
+import { transferActionBorshSchema } from './actions/transfer';
+import { addKeyActionBorshSchema } from './actions/addKey';
+import { deployContractActionBorshSchema } from './actions/deployContract';
+import { functionCallActionBorshSchema } from './actions/functionCall';
+import { stakeActionBorshSchema } from './actions/stake';
+import { deleteKeyActionBorshSchema } from './actions/deleteKey';
+import { deleteAccountActionBorshSchema } from './actions/deleteAccount';
+import { deployGlobalContractActionBorshSchema } from './actions/deployGlobalContract';
+import { useGlobalContractActionBorshSchema } from './actions/useGlobalContract';
+
+const allowedActionBorshSchema: Schema = {
+  enum: [
+    createAccountActionBorshSchema,
+    deployContractActionBorshSchema,
+    functionCallActionBorshSchema,
+    transferActionBorshSchema,
+    stakeActionBorshSchema,
+    addKeyActionBorshSchema,
+    deleteKeyActionBorshSchema,
+    deleteAccountActionBorshSchema,
+    { struct: { signedDelegate: 'string' } }, // TODO is it possible to rid this placeholder and keep enum order?
+    deployGlobalContractActionBorshSchema,
+    useGlobalContractActionBorshSchema,
+  ],
+};
+
+export const delegateActionBorshSchema: Schema = {
+  struct: {
+    senderId: 'string',
+    publicKey: publicKeyBorshSchema,
+    actions: { array: { type: allowedActionBorshSchema } },
+    receiverId: 'string',
+    nonce: 'u64',
+    maxBlockHeight: 'u64',
+  },
+};
+
+// TODO add DelegateActionPrefix

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

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

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

@@ -0,0 +1,25 @@
+import type { Schema } from 'borsh';
+
+const Ed25519PublicKeyBorshSchema = {
+  struct: {
+    ed25519Key: {
+      struct: {
+        data: { array: { type: 'u8', len: 32 } },
+      },
+    },
+  },
+};
+
+const Secp256k1PublicKeyBorshSchema = {
+  struct: {
+    secp256k1Key: {
+      struct: {
+        data: { array: { type: 'u8', len: 64 } },
+      },
+    },
+  },
+};
+
+export const publicKeyBorshSchema: Schema = {
+  enum: [Ed25519PublicKeyBorshSchema, Secp256k1PublicKeyBorshSchema],
+};

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

@@ -0,0 +1,25 @@
+import type { Schema } from 'borsh';
+
+const Ed25519SignatureBorshSchema = {
+  struct: {
+    ed25519Signature: {
+      struct: {
+        data: { array: { type: 'u8', len: 64 } },
+      },
+    },
+  },
+};
+
+const Secp256k1SignatureBorshSchema = {
+  struct: {
+    secp256k1Signature: {
+      struct: {
+        data: { array: { type: 'u8', len: 65 } },
+      },
+    },
+  },
+};
+
+export const signatureBorshSchema: Schema = {
+  enum: [Ed25519SignatureBorshSchema, Secp256k1SignatureBorshSchema],
+};

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

@@ -0,0 +1,10 @@
+import type { Schema } from 'borsh';
+import { transactionBorshSchema } from './transaction';
+import { signatureBorshSchema } from './signature';
+
+export const signedTransactionBorshSchema: Schema = {
+  struct: {
+    transaction: transactionBorshSchema,
+    signature: signatureBorshSchema,
+  },
+};

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

@@ -0,0 +1,42 @@
+import type { Schema } from 'borsh';
+import { publicKeyBorshSchema } from './publicKey';
+import { createAccountActionBorshSchema } from './actions/createAccount';
+import { transferActionBorshSchema } from './actions/transfer';
+import { addKeyActionBorshSchema } from './actions/addKey';
+import { deployContractActionBorshSchema } from './actions/deployContract';
+import { deployGlobalContractActionBorshSchema } from './actions/deployGlobalContract';
+import { useGlobalContractActionBorshSchema } from './actions/useGlobalContract';
+import { functionCallActionBorshSchema } from './actions/functionCall';
+import { stakeActionBorshSchema } from './actions/stake';
+import { deleteKeyActionBorshSchema } from './actions/deleteKey';
+import { deleteAccountActionBorshSchema } from './actions/deleteAccount';
+import { signedDelegateActionBorshSchema } from './actions/signedDelegate';
+
+// Actions order in this enum is important and must match nearcore
+const actionBorshSchema: Schema = {
+  enum: [
+    createAccountActionBorshSchema,
+    deployContractActionBorshSchema,
+    functionCallActionBorshSchema,
+    transferActionBorshSchema,
+    stakeActionBorshSchema,
+    addKeyActionBorshSchema,
+    deleteKeyActionBorshSchema,
+    deleteAccountActionBorshSchema,
+    signedDelegateActionBorshSchema,
+    deployGlobalContractActionBorshSchema,
+    useGlobalContractActionBorshSchema,
+  ],
+};
+
+// Fields order is important and must follow the nearcore
+export const transactionBorshSchema: Schema = {
+  struct: {
+    signerId: 'string',
+    publicKey: publicKeyBorshSchema,
+    nonce: 'u64',
+    receiverId: 'string',
+    blockHash: { array: { type: 'u8', len: 32 } },
+    actions: { array: { type: actionBorshSchema } },
+  },
+};

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

@@ -0,0 +1,12 @@
+import * as v from 'valibot';
+
+export const Base58StringSchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^[1-9A-HJ-NP-Za-km-z]+$/,
+    `Base58 string contains invalid characters. Allowed characters:\
+     123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`,
+  ),
+);
+
+

package/src/_common/schemas/valibot/cryptoHash.ts

@@ -0,0 +1,12 @@
+import * as v from 'valibot';
+import { base58 } from '@scure/base';
+import { Base58StringSchema } from './common';
+import { BinaryCryptoHashLength } from '../../configs/constants';
+
+export const Base58CryptoHashSchema = v.pipe(
+  Base58StringSchema,
+  v.check((value) => {
+    const u8Value = base58.decode(value);
+    return u8Value.length === BinaryCryptoHashLength;
+  }, `Binary Crypto Hash length should be exactly ${BinaryCryptoHashLength} bytes`),
+);

package/src/_common/schemas/valibot/curveString.ts

@@ -0,0 +1,23 @@
+import * as v from 'valibot';
+import type { Curve, CurveString } from 'nat-types/crypto';
+import { base58 } from '@scure/base';
+
+export const CurveStringSchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^(ed25519|secp256k1):[1-9A-HJ-NP-Za-km-z]+$/,
+    'Invalid elliptic curve string format, expected <curve>:<base58>',
+  ),
+  v.transform((value) => value as CurveString),
+);
+
+export const CurveStringTransformSchema = v.pipe(
+  CurveStringSchema,
+  v.transform((value) => {
+    const [curve, base58String] = value.split(':');
+    return {
+      curve: curve as Curve,
+      u8Data: base58.decode(base58String),
+    };
+  }),
+);

package/src/_common/schemas/valibot/privateKey.ts

@@ -0,0 +1,38 @@
+import { BinaryCryptoKeyLengths } from '../../configs/constants';
+import * as v from 'valibot';
+
+const { Ed25519, Secp256k1 } = BinaryCryptoKeyLengths;
+
+export const BinarySecp256k1PrivateKeySchema = v.pipe(
+  v.instance(Uint8Array),
+  v.length(
+    Secp256k1.PrivateKey,
+    `Length of binary secp256k1 private key should be ${Secp256k1.PrivateKey}`,
+  ),
+);
+
+export const BinaryEd25519PrivateKeySchema = v.pipe(
+  v.instance(Uint8Array),
+  v.length(
+    Ed25519.PrivateKey,
+    `Length of binary ed25519 private key should be ${Ed25519.PrivateKey}`,
+  ),
+);
+
+// import { getRandomSecp256k1PrivateKey } from '../../crypto/getRandomPrivateKey';
+
+// new Array(100).fill(0).forEach((_, i) => {
+//   const { publicKey, privateKey } = getRandomSecp256k1PrivateKey();
+//   console.log(
+//     `Public key: ${publicKey}, privateKey: ${privateKey}`,
+//     `Public key: ${publicKey.length}, privateKey: ${privateKey.length}`,
+//   );
+// });
+
+// console.log(
+//   v.parse(
+//     PublicKeySchema,
+//     'secp256k1:2k5acvmedoDyDm28qDknzd7R7gY7ndYwtTAbmn8P2bVuiXDCdFEi7KbbYxuXQArpTp9SveYYRgBP1LG9Jxwf1NGn2ad',
+//     { abortEarly: true}
+//   ),
+// );

package/src/_common/schemas/valibot/publicKey.ts

@@ -0,0 +1,33 @@
+import * as v from 'valibot';
+import type { Ed25519PublicKey, Secp256k1PublicKey } from 'nat-types/crypto';
+
+const Ed25519PublicKeySchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^ed25519:[1-9A-HJ-NP-Za-km-z]+$/,
+    'Invalid public key format, expected ed25519:<base58>',
+  ),
+  v.check(
+    (value) => value.length === 51 || value.length === 52,
+    'Ed25519 public key string must be 51 or 52 characters long',
+  ),
+  v.transform((value) => value as Ed25519PublicKey),
+);
+
+const Secp256k1PublicKeySchema = v.pipe(
+  v.string(),
+  v.regex(
+    /^secp256k1:[1-9A-HJ-NP-Za-km-z]+$/,
+    'Invalid public key format, expected secp256k1:<base58>',
+  ),
+  v.check(
+    (value) => value.length === 97 || value.length === 98,
+    'Secp256k1 public key string must be 97 or 98 characters long',
+  ),
+  v.transform((value) => value as Secp256k1PublicKey),
+);
+
+export const PublicKeySchema = v.union(
+  [Ed25519PublicKeySchema, Secp256k1PublicKeySchema],
+  'Invalid public key',
+);

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

@@ -0,0 +1,42 @@
+import * as v from 'valibot';
+import { PublicKeySchema } from './publicKey';
+import { Base58CryptoHashSchema } from './cryptoHash';
+
+// Near Account
+const AccountIdSchema = v.pipe(v.string(), v.brand('AccountId'));
+
+type AccountId = v.InferOutput<typeof AccountIdSchema>;
+
+const NonceSchema = v.number('uint64');
+
+const TransferActionSchema = v.object({
+  type: v.literal('Transfer'),
+  params: v.object({
+    amount: v.object({
+      yoctoNear: v.bigint(),
+    }),
+  }),
+});
+
+const CreateAccountActionSchema = v.object({
+  type: v.literal('CreateAccount'),
+});
+
+const ActionSchema = v.variant('type', [
+  TransferActionSchema,
+  CreateAccountActionSchema,
+]);
+
+export const TransactionSchema = v.object({
+  signerAccountId: AccountIdSchema,
+  signerPublicKey: PublicKeySchema,
+  receiverAccountId: AccountIdSchema,
+  // action: v.optional(ActionSchema),
+  nonce: NonceSchema,
+  blockHash: Base58CryptoHashSchema,
+});
+
+
+type Transaction = v.InferOutput<typeof TransactionSchema>;
+
+// const a: Transaction = {}

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

@@ -0,0 +1,29 @@
+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`),
+  ),
+);
+
+const CryptoHashSchema = Base58StringSchema.check(
+  z.refine(
+    (val) => {
+      try {
+        const bytes = base58.decode(val);
+        return bytes.length === 32;
+      } catch {
+        return false;
+      }
+    },
+    { error: 'CryptoHash string must decode to 32 bytes' },
+  ),
+);
+
+export const BlockHashSchema = CryptoHashSchema;
+export const BlockHeightSchema = z.uint64();
+export const BlockIdSchema = z.union([BlockHeightSchema, BlockHashSchema]);

package/src/_common/transformers/contract.ts

@@ -0,0 +1,11 @@
+import type { FnArgs } from 'nat-types/contract';
+import type { MaybeJsonLikeValue } from 'nat-types/common';
+import { toJsonBytes } from '@common/utils/common';
+
+export const toContractFnArgsBytes = <AJ extends MaybeJsonLikeValue>(
+  args: FnArgs<AJ>,
+): Uint8Array => {
+  if (args.fnArgsBytes) return args.fnArgsBytes;
+  if (args.fnArgsJson) return toJsonBytes(args.fnArgsJson);
+  return new Uint8Array();
+};

package/src/_common/transformers/curveString.ts

@@ -0,0 +1,27 @@
+import { base58 } from '@scure/base';
+import type {
+  Curve,
+  CurveString,
+  Ed25519CurveString,
+  Secp256k1CurveString,
+} from 'nat-types/crypto';
+
+export const toEd25519CurveString = (u8Data: Uint8Array): Ed25519CurveString =>
+  `ed25519:${base58.encode(u8Data)}`;
+
+export const toSecp256k1CurveString = (
+  u8Data: Uint8Array,
+): Secp256k1CurveString => `secp256k1:${base58.encode(u8Data)}`;
+
+export const fromCurveString = (
+  value: CurveString,
+): {
+  curve: Curve;
+  u8Data: Uint8Array;
+} => {
+  const [curve, base58String] = value.split(':');
+  return {
+    curve: curve as Curve,
+    u8Data: base58.decode(base58String),
+  };
+};

package/src/_common/transformers/toBorshBytes/signedTransaction.ts

@@ -0,0 +1,20 @@
+import type {
+  NativeSignedTransaction,
+  SignedTransaction,
+} from 'nat-types/signedTransaction';
+import type { BorshBytes } from 'nat-types/common';
+import { serialize } from 'borsh';
+import { signedTransactionBorshSchema } from '@common/schemas/borsh';
+import { toNativeSignedTransaction } from '@common/transformers/toNative/signedTransaction';
+
+export const serializeNativeSignedTransaction = (
+  nativeSignedTransaction: NativeSignedTransaction,
+): BorshBytes =>
+  serialize(signedTransactionBorshSchema, nativeSignedTransaction);
+
+export const serializeSignedTransaction = (
+  signedTransaction: SignedTransaction,
+): BorshBytes =>
+  serializeNativeSignedTransaction(
+    toNativeSignedTransaction(signedTransaction),
+  );