@swapkit/toolboxes 1.0.0-beta.9 → 4.0.0-beta.35

package/src/near/__tests__/core.test.ts

@@ -0,0 +1,80 @@
+import { beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { AssetValue, Chain, SKConfig } from "@swapkit/helpers";
+import { providers } from "near-api-js";
+import { getFullAccessPublicKey } from "../helpers/core";
+import { getNearToolbox } from "../toolbox";
+
+const accountId = "ea03292d08136cca439513a33c76af083e5204eceb4ce720320fff84071a447f";
+
+const context: {
+  provider: providers.JsonRpcProvider;
+  toolbox: Awaited<ReturnType<typeof getNearToolbox>>;
+} = {} as any;
+
+beforeAll(() => {
+  context.provider = new providers.JsonRpcProvider({
+    url: SKConfig.get("rpcUrls")[Chain.Near],
+  });
+});
+
+beforeEach(async () => {
+  context.toolbox = await getNearToolbox();
+});
+
+describe("NEAR createTransaction", () => {
+  test("should retrieve full access public key for valid account", async () => {
+    const toolbox = context.toolbox;
+
+    const transaction = await toolbox.createTransaction({
+      recipient: accountId, // Self transfer
+      assetValue: AssetValue.from({
+        chain: Chain.Near,
+        value: "0.001", // Small amount
+      }),
+      sender: accountId,
+      feeRate: 300000000000000, // 300 TGas
+    });
+
+    expect(transaction).toBeDefined();
+    expect(transaction.publicKey).toBeDefined();
+    expect(transaction.serialized).toBeDefined();
+  }, 30000);
+
+  test("should throw error for invalid account", async () => {
+    const provider = context.provider;
+    const invalidAccountId = "non-existent-account-12345.testnet";
+
+    await expect(async () => {
+      await getFullAccessPublicKey(provider, invalidAccountId);
+    }).toThrow();
+  }, 10000);
+
+  test("should handle network errors gracefully", async () => {
+    const invalidProvider = new providers.JsonRpcProvider({ url: "https://invalid-rpc-url.test" });
+
+    await expect(async () => {
+      await getFullAccessPublicKey(invalidProvider, "any-account.testnet");
+    }).toThrow();
+  }, 10000);
+
+  test("should work with contract function call transaction", async () => {
+    const toolbox = context.toolbox;
+    const provider = context.provider;
+
+    const contractTransaction = await toolbox.createContractFunctionCall({
+      sender: accountId,
+      contractId: "wrap.testnet", // Known testnet contract
+      methodName: "storage_deposit",
+      args: { account_id: accountId },
+      gas: "300000000000000", // 300 TGas
+      attachedDeposit: "1250000000000000000000", // 0.00125 NEAR for storage
+    });
+
+    expect(contractTransaction).toBeDefined();
+    expect(contractTransaction.publicKey).toBeDefined();
+
+    // Verify the public key can be retrieved directly
+    const { publicKey } = await getFullAccessPublicKey(provider, accountId);
+    expect(publicKey.toString()).toBe(contractTransaction.publicKey);
+  }, 30000);
+});

package/src/near/helpers/contractFactory.ts

@@ -0,0 +1,22 @@
+import type { Account, Contract } from "near-api-js";
+
+// Create a Near contract instance
+export async function createNearContract<T extends Contract>({
+  account,
+  contractId,
+  viewMethods,
+  changeMethods,
+}: {
+  account: Account;
+  contractId: string;
+  viewMethods: string[];
+  changeMethods: string[];
+}): Promise<T> {
+  const { Contract } = await import("near-api-js");
+
+  return new Contract(account, contractId, {
+    viewMethods,
+    changeMethods,
+    useLocalViewExecution: true, // Enable local view execution for efficiency
+  }) as T;
+}

package/src/near/helpers/core.ts

@@ -0,0 +1,89 @@
+import type { Provider } from "@near-js/providers";
+import { type DerivationPathArray, SwapKitError, derivationPathToString } from "@swapkit/helpers";
+import { type KeyPair, KeyPairSigner } from "near-api-js";
+import type { NearSigner } from "../types";
+
+export async function validateNearAddress(address: string) {
+  // Use the official NEAR SDK validation function if available
+  try {
+    const { validateAccountId } = await import("near-sdk-js");
+    return validateAccountId(address);
+  } catch {
+    const ACCOUNT_ID_REGEX = /^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/;
+
+    return address.length >= 2 && address.length <= 64 && ACCOUNT_ID_REGEX.test(address);
+  }
+}
+
+export async function getNearSignerFromPhrase(params: {
+  phrase: string;
+  derivationPath?: DerivationPathArray;
+  index?: number;
+}) {
+  const { parseSeedPhrase } = await import("near-seed-phrase");
+  const { KeyPair } = await import("near-api-js");
+
+  // Handle derivation path logic here
+  // NEAR uses a 3-level derivation path: m/44'/397'/index'
+  const index = params.index || 0;
+  const derivationPath = params.derivationPath
+    ? derivationPathToString(params.derivationPath.slice(0, 3) as [number, number, number])
+    : `m/44'/397'/${index}'`;
+
+  const { secretKey } = parseSeedPhrase(params.phrase, derivationPath);
+  const keyPair = KeyPair.fromString(secretKey as any);
+
+  return createNearSignerFromKeyPair(keyPair);
+}
+
+export async function getNearSignerFromPrivateKey(privateKey: string) {
+  const { KeyPair } = await import("near-api-js/lib/utils");
+  const keyPair = KeyPair.fromString(privateKey as any);
+  return createNearSignerFromKeyPair(keyPair);
+}
+
+class SKKeyPairSigner extends KeyPairSigner {
+  #keyPair: KeyPair;
+
+  constructor(keyPair: KeyPair) {
+    super(keyPair);
+    this.#keyPair = keyPair;
+  }
+
+  getAddress(): Promise<string> {
+    // For implicit accounts, derive account ID from public key
+    // NEAR implicit accounts use hex representation of the public key
+    const publicKey = this.#keyPair.getPublicKey();
+    const hexAddress = Buffer.from(publicKey.data).toString("hex");
+    return Promise.resolve(hexAddress);
+  }
+}
+
+function createNearSignerFromKeyPair(keyPair: KeyPair): NearSigner {
+  const keyPairSigner = new SKKeyPairSigner(keyPair);
+
+  return keyPairSigner;
+}
+
+export async function getFullAccessPublicKey(provider: Provider, accountId: string) {
+  // Get the first full access key for the account
+  const response = await provider.query({
+    request_type: "view_access_key_list",
+    finality: "final",
+    account_id: accountId,
+  });
+
+  const fullAccessKey = (response as any).keys.find(
+    (key: any) => key.access_key.permission === "FullAccess",
+  );
+
+  if (!fullAccessKey) {
+    throw new SwapKitError("toolbox_near_invalid_address");
+  }
+
+  const { utils } = await import("near-api-js");
+  const publicKey = utils.PublicKey.fromString(fullAccessKey.public_key);
+  const nonce = (fullAccessKey.access_key.nonce as number) || 0;
+
+  return { publicKey, nonce };
+}

package/src/near/helpers/gasEstimation.ts

@@ -0,0 +1,110 @@
+import type { Account } from "near-api-js";
+import type { NearGasEstimateParams } from "../types/contract";
+
+// Gas constants (in TGas - 10^12 gas units)
+export const GAS_COSTS = {
+  SIMPLE_TRANSFER: "1", // 1 TGas
+  TOKEN_TRANSFER: "100", // 100 TGas
+  CONTRACT_CALL: "100", // 100 TGas base
+  ACCOUNT_CREATION: "30", // 30 TGas
+  CONTRACT_DEPLOYMENT: "200", // 200 TGas
+  ACCESS_KEY_ADDITION: "5", // 5 TGas
+  ACCESS_KEY_DELETION: "5", // 5 TGas
+  STAKE: "10", // 10 TGas
+  STORAGE_DEPOSIT: "100", // 100 TGas
+} as const;
+
+// Type guards for discriminated union
+export function isSimpleTransfer(
+  params: NearGasEstimateParams,
+): params is { recipient: string; amount: string } {
+  return "recipient" in params && "amount" in params && !("contractId" in params);
+}
+
+export function isContractCall(params: NearGasEstimateParams): params is {
+  contractId: string;
+  methodName: string;
+  args?: Record<string, any>;
+  attachedDeposit?: string;
+} {
+  return "contractId" in params && "methodName" in params;
+}
+
+export function isBatchTransaction(params: NearGasEstimateParams): params is { actions: any[] } {
+  return "actions" in params;
+}
+
+export function isAccountCreation(params: NearGasEstimateParams): params is {
+  newAccountId: string;
+  publicKey?: string;
+} {
+  return "newAccountId" in params;
+}
+
+export function isContractDeployment(
+  params: NearGasEstimateParams,
+): params is { contractCode: Uint8Array } {
+  return "contractCode" in params;
+}
+
+export function isCustomEstimator(params: NearGasEstimateParams): params is {
+  customEstimator: (account: Account) => Promise<string>;
+} {
+  return "customEstimator" in params;
+}
+
+// Helper function to estimate gas for batch actions
+export function estimateBatchGas(actions: any[]) {
+  let totalGas = 0;
+
+  for (const action of actions) {
+    switch (action.enum) {
+      case "transfer":
+        totalGas += Number(GAS_COSTS.SIMPLE_TRANSFER);
+        break;
+      case "functionCall":
+        totalGas += Number(GAS_COSTS.CONTRACT_CALL);
+        break;
+      case "createAccount":
+        totalGas += Number(GAS_COSTS.ACCOUNT_CREATION);
+        break;
+      case "deployContract":
+        totalGas += Number(GAS_COSTS.CONTRACT_DEPLOYMENT);
+        break;
+      case "addKey":
+        totalGas += Number(GAS_COSTS.ACCESS_KEY_ADDITION);
+        break;
+      case "deleteKey":
+        totalGas += Number(GAS_COSTS.ACCESS_KEY_DELETION);
+        break;
+      case "stake":
+        totalGas += Number(GAS_COSTS.STAKE);
+        break;
+      default:
+        totalGas += Number(GAS_COSTS.CONTRACT_CALL);
+    }
+  }
+
+  return totalGas.toString();
+}
+
+// Helper function to get gas cost for contract methods
+export function getContractMethodGas(methodName: string) {
+  if (methodName === "ft_transfer" || methodName === "ft_transfer_call") {
+    return GAS_COSTS.TOKEN_TRANSFER;
+  }
+  if (methodName === "storage_deposit") {
+    return GAS_COSTS.STORAGE_DEPOSIT;
+  }
+  return GAS_COSTS.CONTRACT_CALL;
+}
+
+// Convert TGas string to gas units
+export function tgasToGas(tgas: string): string {
+  return (BigInt(tgas) * BigInt(10 ** 12)).toString();
+}
+
+// Convert gas units to TGas
+export function gasToTGas(gas: string): string {
+  return (BigInt(gas) / BigInt(10 ** 12)).toString();
+}

package/src/near/helpers/index.ts

@@ -0,0 +1,5 @@
+export * from "./core";
+
+export { createNearContract } from "./contractFactory";
+export * from "./gasEstimation";
+export { createNEP141Token } from "./nep141";

package/src/near/helpers/nep141.ts

@@ -0,0 +1,110 @@
+import type { Account, Contract } from "near-api-js";
+import { createNearContract } from "./contractFactory";
+
+const DEFAULT_STORAGE_DEPOSIT = "1250000000000000000000"; // 0.00125 NEAR
+
+// Define NEP-141 contract interface
+interface NEP141Contract extends Contract {
+  // View methods
+  ft_balance_of(args: { account_id: string }): Promise<string>;
+  ft_total_supply(): Promise<string>;
+  ft_metadata(): Promise<any>;
+  storage_balance_of(args: { account_id: string }): Promise<any>;
+  storage_balance_bounds(): Promise<any>;
+
+  // Change methods
+  ft_transfer(args: any, gas: any, deposit: any): Promise<any>;
+  ft_transfer_call(args: any, gas: any, deposit: any): Promise<any>;
+  storage_deposit(args: any, gas: any, deposit: any): Promise<any>;
+  storage_withdraw(args: any, gas: any, deposit: any): Promise<any>;
+  storage_unregister(force?: boolean, gas?: any): Promise<any>;
+}
+
+export async function createNEP141Token({
+  contractId,
+  account,
+}: {
+  contractId: string;
+  account: Account;
+}) {
+  const BN = (await import("bn.js")).default;
+
+  const contract = await createNearContract<NEP141Contract>({
+    account,
+    contractId,
+    viewMethods: [
+      "ft_balance_of",
+      "ft_total_supply",
+      "ft_metadata",
+      "storage_balance_of",
+      "storage_balance_bounds",
+    ],
+    changeMethods: [
+      "ft_transfer",
+      "ft_transfer_call",
+      "storage_deposit",
+      "storage_withdraw",
+      "storage_unregister",
+    ],
+  });
+
+  // Helper to ensure storage before transfers
+  const ensureStorageFor = async (accountId: string) => {
+    const balance = await contract.storage_balance_of({ account_id: accountId });
+    if (!balance) {
+      // Get minimum storage requirement
+      const bounds = await contract.storage_balance_bounds();
+      const deposit = bounds?.min || DEFAULT_STORAGE_DEPOSIT;
+
+      await contract.storage_deposit(
+        { account_id: accountId },
+        new BN("100000000000000"), // 100 TGas
+        new BN(deposit),
+      );
+    }
+  };
+
+  return {
+    transfer: async (receiverId: string, amount: string, memo?: string) => {
+      // Ensure recipient has storage before transfer
+      await ensureStorageFor(receiverId);
+
+      return contract.ft_transfer(
+        { receiver_id: receiverId, amount, memo },
+        new BN("100000000000000"), // 100 TGas
+        new BN("1"), // 1 yoctoNEAR for security
+      );
+    },
+
+    transferCall: async (receiverId: string, amount: string, msg: string, memo?: string) => {
+      // Ensure recipient has storage before transfer
+      await ensureStorageFor(receiverId);
+
+      return contract.ft_transfer_call(
+        { receiver_id: receiverId, amount, memo, msg },
+        new BN("100000000000000"), // 100 TGas
+        new BN("1"), // 1 yoctoNEAR for security
+      );
+    },
+
+    balanceOf: (accountId: string) => contract.ft_balance_of({ account_id: accountId }),
+
+    totalSupply: () => contract.ft_total_supply(),
+
+    metadata: () => contract.ft_metadata(),
+
+    storageBalanceOf: (accountId: string) => contract.storage_balance_of({ account_id: accountId }),
+
+    storageDeposit: (accountId?: string, amount?: string) =>
+      contract.storage_deposit(
+        { account_id: accountId },
+        new BN("100000000000000"),
+        new BN(amount || DEFAULT_STORAGE_DEPOSIT),
+      ),
+
+    ensureStorage: ensureStorageFor,
+
+    // Raw contract access for advanced use cases
+    contract,
+  };
+}

package/src/near/index.ts

@@ -0,0 +1,24 @@
+export * from "./toolbox";
+export * from "./types";
+export * from "./helpers";
+
+import type { getNearToolbox } from "./toolbox";
+
+export type NearWallet = Awaited<ReturnType<typeof getNearToolbox>>;
+
+export type {
+  NearContractInterface,
+  NearCallParams,
+  NearGasEstimateParams,
+} from "./types/contract";
+export type {
+  FungibleTokenMetadata,
+  StorageBalance,
+  StorageBalanceBounds,
+  NEP141Contract,
+  TokenTransferParams,
+} from "./types/nep141";
+
+export { createNEP141Token } from "./helpers/nep141";
+export { tgasToGas, gasToTGas } from "./helpers/gasEstimation";
+export { createNearContract } from "./helpers/contractFactory";