@uswap/toolboxes 4.3.6

package/src/near/toolbox.ts

@@ -0,0 +1,421 @@
+import type { Account, Contract } from "@near-js/accounts";
+import type { SignedTransaction, Transaction } from "@near-js/transactions";
+import { AssetValue, Chain, getChainConfig, getRPCUrl, SwapKitError } from "@uswap/helpers";
+import { getBalance } from "../utils";
+import {
+  getFullAccessPublicKey,
+  getNearSignerFromPhrase,
+  getNearSignerFromPrivateKey,
+  getValidateNearAddress,
+} from "./helpers/core";
+import {
+  estimateBatchGas,
+  GAS_COSTS,
+  getContractMethodGas,
+  isAccountCreation,
+  isBatchTransaction,
+  isContractCall,
+  isContractDeployment,
+  isCustomEstimator,
+  isSimpleTransfer,
+} from "./helpers/gasEstimation";
+import { createNearContract } from "./helpers/nep141";
+import type {
+  NearCreateTransactionParams,
+  NearFunctionCallParams,
+  NearToolboxParams,
+  NearTransferParams,
+} from "./types";
+import type { NearContractInterface, NearGasEstimateParams } from "./types/contract";
+import type { NEP141StorageContract } from "./types/nep141";
+import type {
+  BatchTransaction,
+  ContractFunctionCallParams,
+  CreateActionParams,
+  GetSignerFromPhraseParams,
+} from "./types/toolbox";
+
+export async function getNearToolbox(toolboxParams?: NearToolboxParams) {
+  const { P, match } = await import("ts-pattern");
+  const { JsonRpcProvider } = await import("@near-js/providers");
+  const signer = await match(toolboxParams)
+    .with({ phrase: P.string }, async (params) => {
+      const signer = await getNearSignerFromPhrase(params);
+      return signer;
+    })
+    .with({ signer: P.any }, ({ signer }) => signer)
+    .otherwise(() => undefined);
+
+  const url = await getRPCUrl(Chain.Near);
+
+  const provider = new JsonRpcProvider({ url });
+
+  async function getAccount(address?: string) {
+    const { Account } = await import("@near-js/accounts");
+
+    const _address = address || (await getAddress());
+
+    const account = new Account(_address, provider, signer);
+
+    return account;
+  }
+
+  async function getAddress() {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+    const address = await signer.getAddress();
+    return address;
+  }
+
+  async function checkStorageBalance(params: { contractId: string; accountId: string }) {
+    const contract = await createContract<NEP141StorageContract>({
+      changeMethods: [],
+      contractId: params.contractId,
+      viewMethods: ["storage_balance_of"],
+    });
+
+    return contract.storage_balance_of({ account_id: params.accountId });
+  }
+
+  async function transferTokenWithStorageDeposit(params: {
+    recipient: string;
+    assetValue: AssetValue;
+    memo?: string;
+    contractId: string;
+  }) {
+    const storageDeposit = "1250000000000000000000"; // 0.00125 NEAR default
+
+    const actions = [
+      await createAction({
+        args: { account_id: params.recipient },
+        attachedDeposit: storageDeposit,
+        gas: "150000000000000", // 150 TGas for storage_deposit
+        methodName: "storage_deposit",
+      }),
+      await createAction({
+        args: {
+          amount: params.assetValue.getBaseValue("string"),
+          memo: params.memo || null,
+          receiver_id: params.recipient,
+        },
+        attachedDeposit: "1",
+        gas: "150000000000000", // 150 TGas for ft_transfer
+        methodName: "ft_transfer",
+      }),
+    ];
+
+    return executeBatchTransaction({ actions, receiverId: params.contractId });
+  }
+
+  async function transfer(params: NearTransferParams) {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+
+    const { assetValue, recipient, memo } = params;
+    const sender = await getAddress();
+
+    // Handle NEP-141 token transfers - check if recipient needs storage
+    if (!assetValue.isGasAsset && assetValue.address) {
+      const storageBalance = await checkStorageBalance({ accountId: recipient, contractId: assetValue.address });
+
+      if (!storageBalance) {
+        return transferTokenWithStorageDeposit({ assetValue, contractId: assetValue.address, memo, recipient });
+      }
+    }
+
+    // Standard transfer (native NEAR or token with registered storage)
+    const transaction = await createTransaction({ ...params, sender });
+    return signAndSendTransaction(transaction);
+  }
+
+  async function createTransaction(params: NearCreateTransactionParams) {
+    const { recipient, assetValue, memo, attachedDeposit, sender: signerId, functionCall } = params;
+    const validateNearAddress = await getValidateNearAddress();
+
+    if (!validateNearAddress(recipient)) {
+      throw new SwapKitError("toolbox_near_invalid_address", { recipient: recipient });
+    }
+
+    if (!validateNearAddress(signerId)) {
+      throw new SwapKitError("toolbox_near_invalid_address", { signerId: signerId });
+    }
+
+    if (functionCall) {
+      return createContractFunctionCall({ ...functionCall, sender: signerId });
+    }
+
+    if (!assetValue.isGasAsset) {
+      const contractId = assetValue.address;
+      if (!contractId) {
+        throw new SwapKitError("toolbox_near_missing_contract_address");
+      }
+
+      return createContractFunctionCall({
+        args: { amount: assetValue.getBaseValue("string"), memo: memo || null, receiver_id: recipient },
+        attachedDeposit: attachedDeposit || "1",
+        contractId,
+        gas: "250000000000000",
+        methodName: "ft_transfer",
+        sender: signerId,
+      });
+    }
+
+    const { publicKey, nonce } = await getFullAccessPublicKey(provider, signerId);
+    const baseAmount = assetValue.getBaseValue("bigint");
+
+    const { actionCreators, createTransaction } = await import("@near-js/transactions");
+    const { baseDecode } = await import("@near-js/utils");
+
+    const txActions = [actionCreators.transfer(baseAmount)];
+
+    if (memo && attachedDeposit) {
+      txActions.push(actionCreators.functionCall("memo", { memo }, BigInt("250000000000000"), BigInt(attachedDeposit)));
+    }
+
+    const block = await provider.block({ finality: "final" });
+    const blockHash = baseDecode(block.header.hash);
+
+    return createTransaction(signerId, publicKey, recipient, nonce + 1, txActions, blockHash);
+  }
+
+  function serializeTransaction(transaction: Transaction) {
+    const serializedTx = transaction.encode();
+    return Buffer.from(serializedTx).toString("base64");
+  }
+
+  async function createContractFunctionCall(params: ContractFunctionCallParams) {
+    const { sender: accountId } = params;
+
+    const { publicKey, nonce } = await getFullAccessPublicKey(provider, accountId);
+
+    const { createTransaction, actionCreators } = await import("@near-js/transactions");
+    const { baseDecode } = await import("@near-js/utils");
+    const block = await provider.block({ finality: "final" });
+    const blockHash = baseDecode(block.header.hash);
+
+    const actions = [
+      actionCreators.functionCall(
+        params.methodName,
+        Buffer.from(JSON.stringify(params.args)),
+        BigInt(params.gas),
+        BigInt(params.attachedDeposit),
+      ),
+    ];
+
+    const transaction = createTransaction(accountId, publicKey, params.contractId, nonce + 1, actions, blockHash);
+
+    return transaction;
+  }
+
+  async function createAction(params: CreateActionParams) {
+    const { actionCreators } = await import("@near-js/transactions");
+
+    const action = actionCreators.functionCall(
+      params.methodName,
+      Buffer.from(JSON.stringify(params.args)),
+      BigInt(params.gas),
+      BigInt(params.attachedDeposit),
+    );
+
+    return action;
+  }
+
+  async function signTransaction(transaction: Transaction): Promise<SignedTransaction> {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+
+    const [_hash, signedTx] = await signer.signTransaction(transaction);
+    return signedTx;
+  }
+
+  async function broadcastTransaction(signedTransaction: SignedTransaction) {
+    const result = await provider.sendTransaction(signedTransaction);
+    return result.transaction.hash;
+  }
+
+  async function signAndSendTransaction(transaction: Transaction) {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+
+    try {
+      const signedTx = await signTransaction(transaction);
+      const txHash = await broadcastTransaction(signedTx);
+      return txHash;
+    } catch {
+      return signer.signAndSendTransactions?.({ transactions: [transaction] });
+    }
+  }
+
+  async function estimateTransactionFee(params: NearTransferParams | NearGasEstimateParams) {
+    if ("assetValue" in params) {
+      const baseTransferCost = "115123062500";
+      const receiptCreationCost = "108059500000";
+
+      const totalGasUnits = BigInt(baseTransferCost) + BigInt(receiptCreationCost);
+
+      const gasPrice = await getCurrentGasPrice();
+
+      const totalCostYocto = totalGasUnits * BigInt(gasPrice.toString());
+      const { baseDecimal } = getChainConfig(Chain.Near);
+
+      return AssetValue.from({ chain: Chain.Near, fromBaseDecimal: baseDecimal, value: totalCostYocto.toString() });
+    }
+
+    const account = signer ? await getAccount() : undefined;
+    return estimateGas(params, account);
+  }
+
+  async function getCurrentGasPrice() {
+    try {
+      const result = await provider.query({
+        account_id: "system",
+        args_base64: "",
+        finality: "final",
+        method_name: "gas_price",
+        request_type: "call_function",
+      });
+
+      return result;
+    } catch {
+      return "100000000"; // 0.0001 NEAR per Tgas
+    }
+  }
+
+  async function createSubAccount(subAccountId: string, publicKey: string, initialBalance: string): Promise<string> {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+
+    const account = await getAccount();
+    const { formatNearAmount } = await import("@near-js/utils");
+    const { PublicKey } = await import("@near-js/crypto");
+
+    const balanceInYocto = formatNearAmount(initialBalance) || "0";
+
+    const result = await account.createAccount(subAccountId, PublicKey.fromString(publicKey), BigInt(balanceInYocto));
+
+    return result.transaction.hash;
+  }
+
+  async function callFunction(params: NearFunctionCallParams): Promise<string> {
+    try {
+      if (!signer) {
+        throw new SwapKitError("toolbox_near_no_signer");
+      }
+
+      const { actionCreators } = await import("@near-js/transactions");
+
+      const { contractId, methodName, args, deposit } = params;
+      const account = await getAccount();
+
+      const estimatedGas = await estimateGas({ args: args || {}, contractId, methodName });
+
+      const functionAction = actionCreators.functionCall(
+        methodName,
+        args || {},
+        estimatedGas.getBaseValue("bigint"),
+        BigInt(deposit || "1"),
+      );
+
+      const result = await account.signAndSendTransaction({ actions: [functionAction], receiverId: contractId });
+
+      return result.transaction_outcome.id;
+    } catch (error) {
+      throw new SwapKitError("toolbox_near_transfer_failed", { error });
+    }
+  }
+
+  // Create typed contract interface
+  async function createContract<T extends Contract = Contract>(contractInterface: NearContractInterface): Promise<T> {
+    const account = await getAccount();
+
+    return createNearContract<T>({
+      account,
+      changeMethods: contractInterface.changeMethods,
+      contractId: contractInterface.contractId,
+      viewMethods: contractInterface.viewMethods,
+    });
+  }
+
+  async function executeBatchTransaction(batch: BatchTransaction): Promise<string> {
+    if (!signer) {
+      throw new SwapKitError("toolbox_near_no_signer");
+    }
+
+    if (batch.actions.length === 0) {
+      throw new SwapKitError("toolbox_near_empty_batch");
+    }
+
+    const account = await getAccount();
+
+    // Use account.signAndSendTransaction for batch operations
+    const result = await account.signAndSendTransaction({ actions: batch.actions, receiverId: batch.receiverId });
+
+    return result.transaction.hash;
+  }
+
+  async function estimateGas(params: NearGasEstimateParams, account?: Account) {
+    const { baseDecimal } = getChainConfig(Chain.Near);
+
+    const gasInTGas = await match(params)
+      .when(isSimpleTransfer, () => GAS_COSTS.SIMPLE_TRANSFER)
+      .when(isContractCall, (p) => getContractMethodGas(p.methodName))
+      .when(isBatchTransaction, (p) => estimateBatchGas(p.actions))
+      .when(isAccountCreation, () => GAS_COSTS.ACCOUNT_CREATION)
+      .when(isContractDeployment, () => GAS_COSTS.CONTRACT_DEPLOYMENT)
+      .when(isCustomEstimator, (p) => {
+        if (!account) {
+          throw new SwapKitError("toolbox_near_no_account");
+        }
+        return p.customEstimator(account);
+      })
+      .otherwise(() => {
+        throw new SwapKitError("toolbox_near_invalid_gas_params");
+      });
+
+    const gasInUnits = BigInt(gasInTGas) * BigInt(10 ** 12);
+    const costInYoctoNear = gasInUnits;
+
+    return AssetValue.from({ chain: Chain.Near, fromBaseDecimal: baseDecimal, value: costInYoctoNear });
+  }
+
+  // Get current gas price from network
+  async function getGasPrice() {
+    try {
+      const result = await provider.gasPrice(null);
+      return result.gas_price || "100000000";
+    } catch {
+      // Fallback to default
+      return "100000000";
+    }
+  }
+
+  return {
+    broadcastTransaction,
+    callFunction,
+    createAction,
+    createContract,
+    createContractFunctionCall,
+    createSubAccount,
+    createTransaction,
+    estimateGas,
+    estimateTransactionFee,
+    executeBatchTransaction,
+    getAddress,
+    getBalance: getBalance(Chain.Near),
+    getGasPrice,
+    getPublicKey: async () => (signer ? (await signer.getPublicKey()).toString() : ""),
+    getSignerFromPhrase: (params: GetSignerFromPhraseParams) => getNearSignerFromPhrase(params),
+    getSignerFromPrivateKey: getNearSignerFromPrivateKey,
+    provider,
+    serializeTransaction,
+    signAndSendTransaction,
+    signTransaction,
+    transfer,
+    validateAddress: await getValidateNearAddress(),
+  };
+}

package/src/near/types/contract.ts

@@ -0,0 +1,32 @@
+import type { Account } from "@near-js/accounts";
+import type { Action } from "@near-js/transactions";
+
+// Custom interface for contract metadata (not in SDK)
+export interface NearContractInterface {
+  contractId: string;
+  viewMethods: string[];
+  changeMethods: string[];
+  metadata?: {
+    version: string;
+    standards: string[]; // e.g., ["nep141", "nep171"]
+  };
+}
+
+// Enhanced call parameters
+export interface NearCallParams {
+  contractId: string;
+  methodName: string;
+  args?: Record<string, any>;
+  gas?: string | bigint;
+  attachedDeposit?: string | bigint;
+  isView?: boolean;
+}
+
+// Gas estimation using discriminated unions for type inference
+export type NearGasEstimateParams =
+  | { recipient: string; amount: string }
+  | { contractId: string; methodName: string; args?: Record<string, any>; attachedDeposit?: string }
+  | { actions: Action[] }
+  | { newAccountId: string; publicKey?: string }
+  | { contractCode: Uint8Array }
+  | { customEstimator: (account: Account) => Promise<string> };

package/src/near/types/nep141.ts

@@ -0,0 +1,34 @@
+import type { Contract } from "@near-js/accounts";
+
+// NEP-141 Fungible Token Standard Types
+
+export interface FungibleTokenMetadata {
+  spec: string; // e.g., "ft-1.0.0"
+  name: string; // e.g., "Wrapped NEAR"
+  symbol: string; // e.g., "wNEAR"
+  icon?: string; // Data URL or IPFS link
+  reference?: string; // URL to additional metadata
+  reference_hash?: string; // Base64-encoded hash of reference content
+  decimals: number; // e.g., 24 for NEAR
+}
+
+export interface StorageBalance {
+  total: string;
+  available: string;
+}
+
+export interface StorageBalanceBounds {
+  min: string;
+  max?: string;
+}
+
+export interface NEP141StorageContract extends Contract {
+  storage_balance_of: (args: { account_id: string }) => Promise<StorageBalance | null>;
+}
+
+// Token transfer parameters
+export interface TokenTransferParams {
+  recipient: string;
+  amount: string;
+  memo?: string;
+}

package/src/near/types/toolbox.ts

@@ -0,0 +1,55 @@
+import type { Account, Contract } from "@near-js/accounts";
+import type { JsonRpcProvider } from "@near-js/providers";
+import type { Action, SignedTransaction, Transaction } from "@near-js/transactions";
+import type { AssetValue, DerivationPathArray } from "@uswap/helpers";
+import type { NEP141Token } from "../helpers/nep141";
+import type { NearCreateTransactionParams, NearFunctionCallParams, NearSigner, NearTransferParams } from "../types";
+import type { NearContractInterface, NearGasEstimateParams } from "../types/contract";
+
+export interface BatchTransaction {
+  receiverId: string;
+  actions: Action[];
+}
+
+export interface ContractFunctionCallParams {
+  sender: string;
+  contractId: string;
+  methodName: string;
+  args: Record<string, any>;
+  gas: string;
+  attachedDeposit: string;
+}
+
+export type CreateActionParams = Pick<ContractFunctionCallParams, "methodName" | "args" | "gas" | "attachedDeposit">;
+
+export interface GetSignerFromPhraseParams {
+  phrase: string;
+  derivationPath?: DerivationPathArray;
+  index?: number;
+}
+
+export interface NearToolbox {
+  getAddress: () => Promise<string>;
+  getPublicKey: () => Promise<string>;
+  provider: typeof JsonRpcProvider;
+  transfer: (params: NearTransferParams) => Promise<string>;
+  createAction: (params: CreateActionParams) => Promise<Action>;
+  createTransaction: (params: NearCreateTransactionParams) => Promise<Transaction>;
+  createContractFunctionCall: (params: ContractFunctionCallParams) => Promise<Transaction>;
+  estimateTransactionFee: (params: NearTransferParams | NearGasEstimateParams) => Promise<AssetValue>;
+  broadcastTransaction: (signedTransaction: SignedTransaction) => Promise<string>;
+  signTransaction: (transaction: Transaction) => Promise<SignedTransaction>;
+  getBalance: (address: string) => Promise<AssetValue[]>;
+  validateAddress: (address: string) => boolean;
+  getSignerFromPhrase: (params: GetSignerFromPhraseParams) => Promise<NearSigner>;
+  getSignerFromPrivateKey: (privateKey: string) => Promise<NearSigner>;
+  callFunction: (params: NearFunctionCallParams) => Promise<string>;
+  createSubAccount: (subAccountId: string, publicKey: string, initialBalance: string) => Promise<string>;
+  createContract: <T extends Contract = Contract>(contractInterface: NearContractInterface) => Promise<T>;
+  executeBatchTransaction: (batch: BatchTransaction) => Promise<string>;
+  nep141: (contractId: string) => Promise<NEP141Token>;
+  getGasPrice: () => Promise<string>;
+  estimateGas: (params: NearGasEstimateParams, account?: Account) => Promise<AssetValue>;
+  serializeTransaction: (params: Transaction) => Promise<string>;
+  signAndSendTransaction: (params: Transaction) => Promise<string>;
+}

package/src/near/types.ts

@@ -0,0 +1,44 @@
+import type { Signer } from "@near-js/signers";
+import type { SignedTransaction, Transaction } from "@near-js/transactions";
+import type {
+  ChainSigner,
+  DerivationPathArray,
+  GenericCreateTransactionParams,
+  GenericTransferParams,
+} from "@uswap/helpers";
+
+export interface NearSigner extends Signer, Omit<ChainSigner<Transaction, SignedTransaction>, "signTransaction"> {
+  signAndSendTransactions?(params: { transactions: Transaction[] }): Promise<string>;
+}
+
+export type NearToolboxParams =
+  | { signer?: NearSigner; accountId?: string }
+  | { phrase?: string; index?: number; derivationPath?: DerivationPathArray };
+
+export interface NearTransferParams extends GenericTransferParams {}
+
+export interface NearConfig {
+  networkId: "mainnet" | "testnet" | "betanet";
+  nodeUrl: string;
+  walletUrl?: string;
+  helperUrl?: string;
+  keyStore?: any;
+}
+
+export interface NearFunctionCallParams {
+  contractId: string;
+  methodName: string;
+  args: Uint8Array | Record<string, any>;
+  deposit?: bigint | string | number;
+  gas?: bigint | string | number;
+}
+
+export interface NearCreateTransactionParams extends Omit<GenericCreateTransactionParams, "feeRate"> {
+  attachedDeposit?: string;
+  functionCall?: { methodName: string; args: object; attachedDeposit: string; gas: string; contractId: string };
+}
+
+export * from "./toolbox";
+export * from "./types/contract";
+export * from "./types/nep141";
+export * from "./types/toolbox";