@anywalletkit/wallet-near 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -626,7 +626,13 @@ declare class WalletAccountReadOnlyNear implements IWalletAccountReadOnly {
     static hashOf(tx: NearBuiltTransaction): Uint8Array;
     static txHash(tx: NearBuiltTransaction): string;
 }
-declare function receiptOf(hash: string, o: RawFinalOutcome): NearReceipt;
+/**
+ * The receipt of a `tx` / `send_tx` outcome: status 0 when the transaction or any receipt failed,
+ * 1 when it executed (`SuccessValue` / `SuccessReceiptId`), `undefined` while it is not executed
+ * yet (no execution status, `NotStarted` / `Started`, or `final_execution_status` NONE / INCLUDED /
+ * INCLUDED_FINAL).
+ */
+declare function receiptOf(hash: string, o: RawFinalOutcome): NearReceipt | undefined;
 declare function parseSignature(signature: string): Uint8Array;
 /**
  * An object transaction has exactly the shape the encoder writes, before it is built or signed (also
@@ -660,6 +666,15 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     readonly signerKind: Signer['kind'];
     private _disposed;
     private _readOnly;
+    /**
+     * Highest nonce this account has broadcast (accepted, or maybe sent). The access key is read at
+     * `final`, which lags the block that holds our last transaction, so a second send right after
+     * the first would sign the same nonce and be refused. A filled-in nonce is never below it + 1;
+     * NEAR only needs nonces to increase, so a gap left by a transaction that never landed is harmless.
+     */
+    private _nonceFloor;
+    /** Tail of this account's send queue: prepare → sign → broadcast runs one send at a time. */
+    private _sendTail;
     constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string);
     /** Wrap a raw derived key (takes ownership; zeroized on dispose). */
     static fromPrivateKey(privateKey: Uint8Array, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string): WalletAccountNear;
@@ -679,7 +694,11 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     sign(message: string | Uint8Array): Promise<string>;
     /** NEP-413 off-chain message (what NEAR Intents and dApps ask wallets to sign). */
     signNep413(payload: Nep413Payload): Promise<Nep413Signed>;
-    /** Sign a fully built transaction. No checks — see `signTransaction`. */
+    /**
+     * Sign a fully built transaction. It gets the same hard checks as `signTransaction` (this
+     * account's signer and key, no dangerous action unless `allowDangerousActions`, gas limit) but
+     * no node round-trip: no preflight and no fee check.
+     */
     signBuilt(tx: NearBuiltTransaction): Promise<NearSignedTransaction>;
     /** Build → hard checks → preflight → fee cap. Shared by sign / send / transfer. */
     private prepare;

package/dist/index.d.ts

@@ -626,7 +626,13 @@ declare class WalletAccountReadOnlyNear implements IWalletAccountReadOnly {
     static hashOf(tx: NearBuiltTransaction): Uint8Array;
     static txHash(tx: NearBuiltTransaction): string;
 }
-declare function receiptOf(hash: string, o: RawFinalOutcome): NearReceipt;
+/**
+ * The receipt of a `tx` / `send_tx` outcome: status 0 when the transaction or any receipt failed,
+ * 1 when it executed (`SuccessValue` / `SuccessReceiptId`), `undefined` while it is not executed
+ * yet (no execution status, `NotStarted` / `Started`, or `final_execution_status` NONE / INCLUDED /
+ * INCLUDED_FINAL).
+ */
+declare function receiptOf(hash: string, o: RawFinalOutcome): NearReceipt | undefined;
 declare function parseSignature(signature: string): Uint8Array;
 /**
  * An object transaction has exactly the shape the encoder writes, before it is built or signed (also
@@ -660,6 +666,15 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     readonly signerKind: Signer['kind'];
     private _disposed;
     private _readOnly;
+    /**
+     * Highest nonce this account has broadcast (accepted, or maybe sent). The access key is read at
+     * `final`, which lags the block that holds our last transaction, so a second send right after
+     * the first would sign the same nonce and be refused. A filled-in nonce is never below it + 1;
+     * NEAR only needs nonces to increase, so a gap left by a transaction that never landed is harmless.
+     */
+    private _nonceFloor;
+    /** Tail of this account's send queue: prepare → sign → broadcast runs one send at a time. */
+    private _sendTail;
     constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string);
     /** Wrap a raw derived key (takes ownership; zeroized on dispose). */
     static fromPrivateKey(privateKey: Uint8Array, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string): WalletAccountNear;
@@ -679,7 +694,11 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     sign(message: string | Uint8Array): Promise<string>;
     /** NEP-413 off-chain message (what NEAR Intents and dApps ask wallets to sign). */
     signNep413(payload: Nep413Payload): Promise<Nep413Signed>;
-    /** Sign a fully built transaction. No checks — see `signTransaction`. */
+    /**
+     * Sign a fully built transaction. It gets the same hard checks as `signTransaction` (this
+     * account's signer and key, no dangerous action unless `allowDangerousActions`, gas limit) but
+     * no node round-trip: no preflight and no fee check.
+     */
     signBuilt(tx: NearBuiltTransaction): Promise<NearSignedTransaction>;
     /** Build → hard checks → preflight → fee cap. Shared by sign / send / transfer. */
     private prepare;

package/dist/index.js

@@ -22,7 +22,7 @@ import {
   encodeCursor,
   failureOf,
   fromBase64,
-  isDefinitive,
+  isDefinitiveBroadcast,
   mapNearblocksGroup,
   mapNearblocksTxn,
   mapRpcTxStatus,
@@ -30,7 +30,7 @@ import {
   outcomeFailed,
   parseJsonPreservingBigInts,
   toBase64
-} from "./chunk-ZWMEZA5A.js";
+} from "./chunk-5UHDSFWA.js";
 
 // src/address.ts
 import { base58 } from "@scure/base";
@@ -862,8 +862,7 @@ var WalletAccountReadOnlyNear = class _WalletAccountReadOnlyNear {
   /** Status of one of this account's transactions (the `tx` RPC needs the sender). */
   async getTransactionReceipt(hash) {
     const o = await this.requireRpc("fetch transaction receipts").txStatus(hash, this.address);
-    if (!o) return void 0;
-    return receiptOf(hash, o);
+    return o ? receiptOf(hash, o) : void 0;
   }
   /** Verify an `ed25519:<base58>` (or bare base58 / hex) signature produced by `sign`. */
   async verify(message, signature) {
@@ -884,8 +883,10 @@ var WalletAccountReadOnlyNear = class _WalletAccountReadOnlyNear {
 };
 function receiptOf(hash, o) {
   const failure = outcomeFailed(o);
-  const pending = o.final_execution_status !== void 0 && /NONE|INCLUDED$/.test(o.final_execution_status) && !failureOf(o.status) && o.status === void 0;
-  return { hash, status: failure ? 0 : 1, ...failure ? { failure } : {}, raw: { ...o, ...pending ? { pending: true } : {} } };
+  if (failure) return { hash, status: 0, failure, raw: { ...o } };
+  if (o.final_execution_status !== void 0 && /^(?:NONE|INCLUDED|INCLUDED_FINAL)$/.test(o.final_execution_status)) return void 0;
+  const executed = typeof o.status === "object" && o.status !== null && ("SuccessValue" in o.status || "SuccessReceiptId" in o.status);
+  return executed ? { hash, status: 1, raw: { ...o } } : void 0;
 }
 function parseSignature(signature) {
   const s = signature.startsWith("ed25519:") ? signature.slice("ed25519:".length) : signature;
@@ -993,6 +994,15 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
   signerKind;
   _disposed = false;
   _readOnly;
+  /**
+   * Highest nonce this account has broadcast (accepted, or maybe sent). The access key is read at
+   * `final`, which lags the block that holds our last transaction, so a second send right after
+   * the first would sign the same nonce and be refused. A filled-in nonce is never below it + 1;
+   * NEAR only needs nonces to increase, so a gap left by a transaction that never landed is harmless.
+   */
+  _nonceFloor;
+  /** Tail of this account's send queue: prepare → sign → broadcast runs one send at a time. */
+  _sendTail = Promise.resolve();
   constructor(signer, publicKey, path, config = {}, accountId) {
     super(accountId ?? implicitAccountId(publicKey), config, ed25519Key(publicKey));
     this.#signer = requireCurve(signer, "ed25519");
@@ -1037,15 +1047,44 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
     const sig = await this.#signBytes(nep413Hash(payload), "near-nep413");
     return { signature: toBase64(sig), publicKey: publicKeyToString(this.publicKey), accountId: this.address };
   }
-  /** Sign a fully built transaction. No checks — see `signTransaction`. */
+  /**
+   * Sign a fully built transaction. It gets the same hard checks as `signTransaction` (this
+   * account's signer and key, no dangerous action unless `allowDangerousActions`, gas limit) but
+   * no node round-trip: no preflight and no fee check.
+   */
   async signBuilt(tx) {
+    const own = this.#ownCopy(tx);
+    this.assertSafe(own);
+    return this.#signChecked(own);
+  }
+  /**
+   * A plain copy of `tx`, decoded from its borsh bytes: the object the checks read is the one that
+   * gets hashed and signed, whatever the caller does with its own object (a getter, or an array
+   * changed while a node call is awaited).
+   */
+  #ownCopy(tx) {
+    let copy;
+    try {
+      copy = decodeTransaction(encodeTransaction(tx));
+    } catch (e) {
+      this.assertSafe(tx);
+      throw new UnsafeTransactionError("non-canonical", `Not an encodable NEAR transaction: ${e.message}`);
+    }
+    return copy;
+  }
+  /** Sign a transaction that has already been through `assertSafe`. */
+  async #signChecked(tx) {
     assertWellFormed(tx);
     const sig = await this.#signBytes(WalletAccountReadOnlyNear.hashOf(tx), "near-tx");
     return { transaction: tx, signature: { keyType: "ed25519", data: sig } };
   }
   /** Build → hard checks → preflight → fee cap. Shared by sign / send / transfer. */
   async prepare(tx, maxFee, op) {
-    const built = await this.buildTransaction(tx);
+    let built = await this.buildTransaction(tx);
+    if (typeof tx !== "string" && tx.nonce === void 0 && this._nonceFloor !== void 0 && built.nonce <= this._nonceFloor) {
+      built = { ...built, nonce: this._nonceFloor + 1n };
+    }
+    built = this.#ownCopy(built);
     this.assertSafe(built);
     const estimate = await this.estimate(built);
     this.assertSafe(built, estimate.fee);
@@ -1061,18 +1100,24 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
     this.key();
     this.requireRpc("sign transactions");
     const { built } = await this.prepare(tx, feeLimit(this._config.transactionMaxFee, options), "transaction");
-    return toBase64(encodeSignedTransaction(await this.signBuilt(built)));
+    return toBase64(encodeSignedTransaction(await this.#signChecked(built)));
   }
   async broadcast(signed) {
     const hash = WalletAccountReadOnlyNear.txHash(signed.transaction);
     const rpc = this.requireRpc("broadcast");
+    const used = () => {
+      const n = signed.transaction.nonce;
+      if (this._nonceFloor === void 0 || n > this._nonceFloor) this._nonceFloor = n;
+    };
     let outcome;
     try {
       outcome = await rpc.sendTx(toBase64(encodeSignedTransaction(signed)));
     } catch (e) {
-      if (isDefinitive(e)) throw e;
+      if (isDefinitiveBroadcast(e)) throw e;
+      used();
       throw new BroadcastUnknownError(hash, e);
     }
+    used();
     const failure = outcomeFailed(outcome);
     if (failure) throw new Error(`Transaction ${hash} failed on chain: ${failure}`);
     return outcome.transaction?.hash ?? hash;
@@ -1081,20 +1126,35 @@ 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, options = {}) {
+  sendTransaction(tx, options = {}) {
+    return this.#serial(() => this.#sendTransactionNow(tx, options));
+  }
+  async #sendTransactionNow(tx, options) {
     this.key();
     this.requireRpc("send transactions");
     const presigned = typeof tx === "string" ? decodeSigned(tx) : void 0;
     const { built, estimate } = await this.prepare(tx, feeLimit(this._config.transactionMaxFee, options), "transaction");
-    const signed = presigned ?? await this.signBuilt(built);
+    const signed = presigned ?? await this.#signChecked(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, writeOptions = {}) {
+  transfer(o, writeOptions = {}) {
+    return this.#serial(() => this.#transferNow(o, writeOptions));
+  }
+  async #transferNow(o, writeOptions) {
     this.key();
     this.requireRpc("transfer tokens");
     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 };
+    return { hash: await this.broadcast(await this.#signChecked(built)), fee: estimate.fee, estimate };
+  }
+  /**
+   * One send at a time per account: two sends started together would read the same access-key
+   * nonce before either is broadcast. A failed send does not block the next.
+   */
+  #serial(run) {
+    const next = this._sendTail.then(run);
+    this._sendTail = next.then(() => void 0, () => void 0);
+    return next;
   }
   /** The same account as a {@link WalletAccountReadOnlyNear}. */
   toReadOnlyAccount() {