@anywalletkit/wallet-near 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { IWalletAccountReadOnly, TransferResult, IWalletAccount, Signer, WalletManager, FeeRates } from '@anywalletkit/core';
+import { IWalletAccountReadOnly, TransferResult, IWalletAccount, Signer, WriteOptions, WalletManager, FeeRates } from '@anywalletkit/core';
 export { HistoryFetch, HistoryUnavailableError, NearChainTx, NearHistoryCursor, NearHistoryOptions, NearHistoryPage, NearHistoryRaw, NearHistorySource, NearblocksFtRow, NearblocksReceiptRow, NearblocksTxn, RpcTxStatus, createNearHistory, decodeFunctionCallArgs, decodeCursor as decodeHistoryCursor, encodeCursor as encodeHistoryCursor, mapNearblocksGroup, mapNearblocksTxn, mapRpcTxStatus, nearExplorerTxUrl, parseJsonPreservingBigInts } from './history.cjs';
 
 /** JSON-RPC transport: `method` + `params`, returns the `result` (throws on `error`). */
@@ -16,6 +16,8 @@ interface NearConfig {
     retries?: number;
     /** Optional headers for every request (e.g. an API key). */
     headers?: Record<string, string>;
+    /** Per-request timeout for url providers, in ms (default 15 000): a node that never answers fails over (reads) or ends as "maybe sent" (`send_tx`). */
+    timeoutMs?: number;
     /** "mainnet" (default) | "testnet" | any CAIP-2 suffix. */
     network?: 'mainnet' | 'testnet' | string;
     /** Max fee (yoctoNEAR) for `transfer`. */
@@ -291,6 +293,18 @@ declare class NearRpcError extends Error {
         code?: number;
     });
 }
+/**
+ * The signed transaction was handed to the RPC but no definitive answer came back (no response, or
+ * a node timeout): it MAY be on chain. Do not sign it again (a new nonce would pay twice) — watch
+ * `hash`, computed locally.
+ */
+declare class BroadcastUnknownError extends Error {
+    /** Always true: the transaction may be on its way. */
+    readonly maybeSent = true;
+    /** Base58 hash of the signed transaction. */
+    readonly hash: string;
+    constructor(hash: string, cause: unknown);
+}
 
 /** True for a valid NEAR account id: 2–64 characters of the allowed alphabet, implicit or named. */
 declare function isValidAccountId(id: string): boolean;
@@ -393,7 +407,11 @@ declare function decodeAnyTransaction(bytes: Uint8Array): {
 /** Base64 helpers that work in Node, browsers and Hermes (no Buffer). */
 declare function toBase64(bytes: Uint8Array): string;
 declare function fromBase64(s: string): Uint8Array;
-/** One transport, or a failover transport over the list. */
+/**
+ * One transport, or a failover transport over the list. Reads fail over on anything but a
+ * definitive node answer; a broadcast is sent once — the account turns an unanswered one into
+ * `BroadcastUnknownError`.
+ */
 declare function createClient(config: NearConfig): NearFetch | undefined;
 interface RawAccountView {
     amount: string;
@@ -631,15 +649,15 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     /** Build → hard checks → preflight → fee cap. Shared by sign / send / transfer. */
     private prepare;
     /** Build, check, preflight and sign; returns the signed transaction as base64 borsh (what `send_tx` takes). */
-    signTransaction(tx: NearTransaction | string): Promise<string>;
+    signTransaction(tx: NearTransaction | string, options?: WriteOptions): Promise<string>;
     private broadcast;
     /**
      * Sign and broadcast. Accepts a transaction, or base64 borsh of an unsigned /
      * already-signed transaction (a signed one is checked, not re-signed).
      */
-    sendTransaction(tx: NearTransaction | string): Promise<NearTransferResult>;
+    sendTransaction(tx: NearTransaction | string, options?: WriteOptions): Promise<NearTransferResult>;
     /** Native NEAR (no `token`) or NEP-141 `ft_transfer` (with `storage_deposit` when the recipient needs it). */
-    transfer(o: NearTransferOptions): Promise<NearTransferResult>;
+    transfer(o: NearTransferOptions, writeOptions?: WriteOptions): Promise<NearTransferResult>;
     /** The same account as a {@link WalletAccountReadOnlyNear}. */
     toReadOnlyAccount(): IWalletAccountReadOnly;
     /** Dispose the signer (zeroizes a local key). Idempotent. */
@@ -674,4 +692,4 @@ declare class WalletManagerNear extends WalletManager<WalletAccountNear, NearCon
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { ACTION_TAG, BorshReader, BorshWriter, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };
+export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IWalletAccountReadOnly, TransferResult, IWalletAccount, Signer, WalletManager, FeeRates } from '@anywalletkit/core';
+import { IWalletAccountReadOnly, TransferResult, IWalletAccount, Signer, WriteOptions, WalletManager, FeeRates } from '@anywalletkit/core';
 export { HistoryFetch, HistoryUnavailableError, NearChainTx, NearHistoryCursor, NearHistoryOptions, NearHistoryPage, NearHistoryRaw, NearHistorySource, NearblocksFtRow, NearblocksReceiptRow, NearblocksTxn, RpcTxStatus, createNearHistory, decodeFunctionCallArgs, decodeCursor as decodeHistoryCursor, encodeCursor as encodeHistoryCursor, mapNearblocksGroup, mapNearblocksTxn, mapRpcTxStatus, nearExplorerTxUrl, parseJsonPreservingBigInts } from './history.js';
 
 /** JSON-RPC transport: `method` + `params`, returns the `result` (throws on `error`). */
@@ -16,6 +16,8 @@ interface NearConfig {
     retries?: number;
     /** Optional headers for every request (e.g. an API key). */
     headers?: Record<string, string>;
+    /** Per-request timeout for url providers, in ms (default 15 000): a node that never answers fails over (reads) or ends as "maybe sent" (`send_tx`). */
+    timeoutMs?: number;
     /** "mainnet" (default) | "testnet" | any CAIP-2 suffix. */
     network?: 'mainnet' | 'testnet' | string;
     /** Max fee (yoctoNEAR) for `transfer`. */
@@ -291,6 +293,18 @@ declare class NearRpcError extends Error {
         code?: number;
     });
 }
+/**
+ * The signed transaction was handed to the RPC but no definitive answer came back (no response, or
+ * a node timeout): it MAY be on chain. Do not sign it again (a new nonce would pay twice) — watch
+ * `hash`, computed locally.
+ */
+declare class BroadcastUnknownError extends Error {
+    /** Always true: the transaction may be on its way. */
+    readonly maybeSent = true;
+    /** Base58 hash of the signed transaction. */
+    readonly hash: string;
+    constructor(hash: string, cause: unknown);
+}
 
 /** True for a valid NEAR account id: 2–64 characters of the allowed alphabet, implicit or named. */
 declare function isValidAccountId(id: string): boolean;
@@ -393,7 +407,11 @@ declare function decodeAnyTransaction(bytes: Uint8Array): {
 /** Base64 helpers that work in Node, browsers and Hermes (no Buffer). */
 declare function toBase64(bytes: Uint8Array): string;
 declare function fromBase64(s: string): Uint8Array;
-/** One transport, or a failover transport over the list. */
+/**
+ * One transport, or a failover transport over the list. Reads fail over on anything but a
+ * definitive node answer; a broadcast is sent once — the account turns an unanswered one into
+ * `BroadcastUnknownError`.
+ */
 declare function createClient(config: NearConfig): NearFetch | undefined;
 interface RawAccountView {
     amount: string;
@@ -631,15 +649,15 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     /** Build → hard checks → preflight → fee cap. Shared by sign / send / transfer. */
     private prepare;
     /** Build, check, preflight and sign; returns the signed transaction as base64 borsh (what `send_tx` takes). */
-    signTransaction(tx: NearTransaction | string): Promise<string>;
+    signTransaction(tx: NearTransaction | string, options?: WriteOptions): Promise<string>;
     private broadcast;
     /**
      * Sign and broadcast. Accepts a transaction, or base64 borsh of an unsigned /
      * already-signed transaction (a signed one is checked, not re-signed).
      */
-    sendTransaction(tx: NearTransaction | string): Promise<NearTransferResult>;
+    sendTransaction(tx: NearTransaction | string, options?: WriteOptions): Promise<NearTransferResult>;
     /** Native NEAR (no `token`) or NEP-141 `ft_transfer` (with `storage_deposit` when the recipient needs it). */
-    transfer(o: NearTransferOptions): Promise<NearTransferResult>;
+    transfer(o: NearTransferOptions, writeOptions?: WriteOptions): Promise<NearTransferResult>;
     /** The same account as a {@link WalletAccountReadOnlyNear}. */
     toReadOnlyAccount(): IWalletAccountReadOnly;
     /** Dispose the signer (zeroizes a local key). Idempotent. */
@@ -674,4 +692,4 @@ declare class WalletManagerNear extends WalletManager<WalletAccountNear, NearCon
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { ACTION_TAG, BorshReader, BorshWriter, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };
+export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  BroadcastUnknownError,
   CAIP2,
   FT_TRANSFER_GAS,
   HistoryUnavailableError,
@@ -20,6 +21,7 @@ import {
   encodeCursor,
   failureOf,
   fromBase64,
+  isDefinitive,
   mapNearblocksGroup,
   mapNearblocksTxn,
   mapRpcTxStatus,
@@ -27,7 +29,7 @@ import {
   outcomeFailed,
   parseJsonPreservingBigInts,
   toBase64
-} from "./chunk-2GH6U3LB.js";
+} from "./chunk-6YJS2IMU.js";
 
 // src/address.ts
 import { base58 } from "@scure/base";
@@ -856,7 +858,7 @@ function equalBytes(a, b) {
 }
 
 // src/account.ts
-import { LocalSigner, SignerError, requireCurve } from "@anywalletkit/core";
+import { LocalSigner, SignerError, feeLimit, requireCurve } from "@anywalletkit/core";
 var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNear {
   /** nonce / block hash come from the node, so building needs the network. */
   needsNetwork = true;
@@ -920,15 +922,22 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
     return { built, estimate };
   }
   /** Build, check, preflight and sign; returns the signed transaction as base64 borsh (what `send_tx` takes). */
-  async signTransaction(tx) {
+  async signTransaction(tx, options = {}) {
     this.key();
     this.requireRpc("sign transactions");
-    const { built } = await this.prepare(tx, this._config.transactionMaxFee, "transaction");
+    const { built } = await this.prepare(tx, feeLimit(this._config.transactionMaxFee, options), "transaction");
     return toBase64(encodeSignedTransaction(await this.signBuilt(built)));
   }
   async broadcast(signed) {
     const hash = WalletAccountReadOnlyNear.txHash(signed.transaction);
-    const outcome = await this.requireRpc("broadcast").sendTx(toBase64(encodeSignedTransaction(signed)));
+    const rpc = this.requireRpc("broadcast");
+    let outcome;
+    try {
+      outcome = await rpc.sendTx(toBase64(encodeSignedTransaction(signed)));
+    } catch (e) {
+      if (isDefinitive(e)) throw e;
+      throw new BroadcastUnknownError(hash, e);
+    }
     const failure = outcomeFailed(outcome);
     if (failure) throw new Error(`Transaction ${hash} failed on chain: ${failure}`);
     return outcome.transaction?.hash ?? hash;
@@ -937,19 +946,19 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
    * Sign and broadcast. Accepts a transaction, or base64 borsh of an unsigned /
    * already-signed transaction (a signed one is checked, not re-signed).
    */
-  async sendTransaction(tx) {
+  async sendTransaction(tx, options = {}) {
     this.key();
     this.requireRpc("send transactions");
     const presigned = typeof tx === "string" ? decodeSigned(tx) : void 0;
-    const { built, estimate } = await this.prepare(tx, this._config.transactionMaxFee, "transaction");
+    const { built, estimate } = await this.prepare(tx, feeLimit(this._config.transactionMaxFee, options), "transaction");
     const signed = presigned ?? await this.signBuilt(built);
     return { hash: await this.broadcast(signed), fee: estimate.fee, estimate };
   }
   /** Native NEAR (no `token`) or NEP-141 `ft_transfer` (with `storage_deposit` when the recipient needs it). */
-  async transfer(o) {
+  async transfer(o, writeOptions = {}) {
     this.key();
     this.requireRpc("transfer tokens");
-    const { built, estimate } = await this.prepare(await this.transferActions(o), this._config.transferMaxFee, "transfer");
+    const { built, estimate } = await this.prepare(await this.transferActions(o), feeLimit(this._config.transferMaxFee, writeOptions), "transfer");
     return { hash: await this.broadcast(await this.signBuilt(built)), fee: estimate.fee, estimate };
   }
   /** The same account as a {@link WalletAccountReadOnlyNear}. */
@@ -985,10 +994,10 @@ var WalletManagerNear = class extends WalletManager {
     if (cached) return cached;
     const external = this.externalSigner();
     if (external) return this.fromSigner(external, full);
-    const signer = LocalSigner2.leafFromSeed(this.seedBytes(), "ed25519", full);
-    const account = new WalletAccountNear(signer, signer.publicKey, full, this._config);
-    this._accounts.set(full, account);
-    return account;
+    return this.cachedAccount(full, () => {
+      const signer = LocalSigner2.leafFromSeed(this.seedBytes(), "ed25519", full);
+      return new WalletAccountNear(signer, signer.publicKey, full, this._config);
+    });
   }
   /** The key of account `index`, bound to a named account that lists it as a full-access key. */
   async getNamedAccount(accountId, index = 0) {
@@ -997,22 +1006,18 @@ var WalletManagerNear = class extends WalletManager {
   /** Resolve `path` against an injected signer: the signer itself, or a child when it can derive there. */
   async fromSigner(signer, path) {
     this.requireSigner("ed25519");
-    let leaf = signer;
+    let rel;
     let key = "external";
     if (isSeedSigner(signer)) {
       if (path === signer.path) key = path;
       else if (path.startsWith(`${signer.path}/`)) {
-        leaf = await (signer.deriveLeaf ?? signer.derive).call(signer, path.slice(signer.path.length + 1));
+        rel = path.slice(signer.path.length + 1);
         key = path;
       } else throw new SignerError2(`The injected signer sits at ${signer.path}; it cannot provide ${path}.`);
     } else if (path !== `${NEAR_BASE_PATH}/0'` && path !== "external") {
       throw new SignerError2(`An external signer has one account; ${path} is not derivable from it.`);
     }
-    const cached = this._accounts.get(key);
-    if (cached) return cached;
-    const account = new WalletAccountNear(leaf, await leaf.getPublicKey(), key, this._config);
-    this._accounts.set(key, account);
-    return account;
+    return this.signerAccount(key, signer, rel, (leaf, publicKey) => new WalletAccountNear(leaf, publicKey, key, this._config));
   }
   /** A read-only account for any account id, with this manager's config. */
   getReadOnlyAccount(accountId, publicKey) {
@@ -1030,6 +1035,7 @@ export {
   ACTION_TAG,
   BorshReader,
   BorshWriter,
+  BroadcastUnknownError,
   CAIP2,
   DANGEROUS_ACTIONS,
   FT_TRANSFER_GAS,