@anywalletkit/wallet-near 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -45,6 +45,7 @@ __export(src_exports, {
   WalletAccountReadOnlyNear: () => WalletAccountReadOnlyNear,
   WalletManagerNear: () => WalletManagerNear,
   YOCTO: () => YOCTO,
+  accessKeyPermissionTag: () => accessKeyPermissionTag,
   actionKey: () => actionKey,
   argsBytes: () => argsBytes,
   assertWellFormed: () => assertWellFormed,
@@ -361,17 +362,34 @@ function argsBytes(args) {
   if (!isPlainObject(args)) throw new TypeError("function-call args must be bytes, a string or a plain object");
   return utf8.encode(JSON.stringify(args));
 }
+var FUNCTION_CALL_PERMISSION_KEYS = /* @__PURE__ */ new Set(["allowance", "receiverId", "methodNames"]);
+function accessKeyPermissionTag(permission) {
+  const keys = isPlainObject(permission) ? Object.keys(permission) : [];
+  if (keys.length !== 1) throw new TypeError(`an access-key permission must have exactly one variant, fullAccess or functionCall (has: ${keys.join(", ") || "none"})`);
+  const variant = permission[keys[0]];
+  if (keys[0] === "fullAccess") {
+    if (!isPlainObject(variant)) throw new TypeError("fullAccess must be a plain object");
+    return 1;
+  }
+  if (keys[0] === "functionCall") {
+    if (!isPlainObject(variant) || Object.keys(variant).some((k) => !FUNCTION_CALL_PERMISSION_KEYS.has(k))) throw new TypeError("functionCall must be a plain { receiverId, methodNames, allowance? } object");
+    if (typeof variant.receiverId !== "string") throw new TypeError("functionCall.receiverId must be a string");
+    if (!Array.isArray(variant.methodNames) || !variant.methodNames.every((m) => typeof m === "string")) throw new TypeError("functionCall.methodNames must be an array of strings");
+    if (variant.allowance !== void 0 && typeof variant.allowance !== "bigint") throw new TypeError("functionCall.allowance must be a bigint or absent");
+    return 0;
+  }
+  throw new TypeError(`unknown access-key permission ${JSON.stringify(keys[0])}`);
+}
 function writeAccessKey(w, k) {
   w.u64(k.nonce);
-  if ("functionCall" in k.permission) {
+  const tag = accessKeyPermissionTag(k.permission);
+  w.u8(tag);
+  if (tag === 0) {
     const p = k.permission.functionCall;
-    w.u8(0);
     w.option(p.allowance, (a) => w.u128(a));
     w.string(p.receiverId);
     w.u32(p.methodNames.length);
     for (const m of p.methodNames) w.string(m);
-  } else {
-    w.u8(1);
   }
 }
 function readAccessKey(r) {
@@ -613,6 +631,13 @@ function httpTransport(url, headers, timeoutMs) {
   };
 }
 var isDefinitive = (e) => e instanceof NearRpcError && !/TIMEOUT|INTERNAL|UNAVAILABLE|NO_SYNCED/i.test(e.errorName ?? "");
+var isDefinitiveBroadcast = (e) => {
+  if (!(e instanceof NearRpcError)) return false;
+  const err = e.cause;
+  const name = typeof err?.name === "string" ? err.name : void 0;
+  const causeName = typeof err?.cause?.name === "string" ? err.cause.name : void 0;
+  return causeName === "INVALID_TRANSACTION" || causeName === "PARSE_ERROR" || name === "REQUEST_VALIDATION_ERROR";
+};
 var BROADCAST_METHODS = /* @__PURE__ */ new Set(["send_tx", "broadcast_tx_commit", "broadcast_tx_async"]);
 function createClient(config) {
   if (config.provider === void 0) return void 0;
@@ -699,7 +724,7 @@ var NearRpc = class {
   }
 };
 function failureOf(status) {
-  if (!status || !("Failure" in status)) return void 0;
+  if (!status || typeof status !== "object" || !("Failure" in status)) return void 0;
   const f = status.Failure;
   try {
     const json = JSON.stringify(f);
@@ -767,8 +792,15 @@ function describeTransaction(tx, ctx = {}) {
     if (DANGEROUS_ACTIONS.has(key)) {
       dangerous ??= KIND_OF_DANGEROUS[key];
       warnings.push({ code: "dangerous-action", message: `${key} changes the account, its keys or its code.` });
-      if (key === "addKey" && "fullAccess" in a.addKey.accessKey.permission) {
-        warnings.push({ code: "full-access-key", message: "Adds a FULL ACCESS key: whoever holds it owns the account." });
+      if (key === "addKey") {
+        let tag;
+        try {
+          tag = accessKeyPermissionTag(a.addKey?.accessKey?.permission);
+        } catch {
+          tag = void 0;
+        }
+        if (tag === 1) warnings.push({ code: "full-access-key", message: "Adds a FULL ACCESS key: whoever holds it owns the account." });
+        else if (tag === void 0) warnings.push({ code: "dangerous-action", message: "Malformed access-key permission: neither fullAccess nor functionCall. The wallet refuses to sign it." });
       }
       continue;
     }
@@ -1116,8 +1148,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) {
@@ -1138,8 +1169,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;
@@ -1166,6 +1199,15 @@ function assertShape(actions, depth = 0) {
       if (!(f.args instanceof Uint8Array) && typeof f.args !== "string" && !isPlainObject(f.args)) throw new UnsafeTransactionError("malformed-action", "Function-call args must be bytes, a string or a plain object.");
       if (f.gas !== void 0 && typeof f.gas !== "bigint" || f.deposit !== void 0 && typeof f.deposit !== "bigint") throw new UnsafeTransactionError("malformed-action", "Function-call gas and deposit must be bigints.");
     }
+    if ("addKey" in a) {
+      const k = a.addKey;
+      if (!isPlainObject(k) || !isPlainObject(k.accessKey)) throw new UnsafeTransactionError("malformed-action", "addKey must carry an accessKey object.");
+      try {
+        accessKeyPermissionTag(k.accessKey.permission);
+      } catch (e) {
+        throw new UnsafeTransactionError("malformed-action", `AddKey: ${e.message}.`);
+      }
+    }
     if ("signedDelegate" in a && depth === 0) assertShape(a.signedDelegate.delegateAction.actions, depth + 1);
   }
 }
@@ -1238,6 +1280,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 = (0, import_core4.requireCurve)(signer, "ed25519");
@@ -1282,15 +1333,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);
@@ -1306,18 +1386,24 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
     this.key();
     this.requireRpc("sign transactions");
     const { built } = await this.prepare(tx, (0, import_core4.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;
@@ -1326,20 +1412,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, (0, import_core4.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), (0, import_core4.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() {