@pafi-dev/issuer 0.5.27 → 0.5.29

package/README.md

@@ -15,7 +15,13 @@ ledger, policy engine, EIP-712 issuer signing, relay submission, and mint/burn e
 
 - Node.js >= 18
 - TypeScript >= 5.0
-- `viem` ^2.0.0 and `@pafi-dev/core` ^0.4.0 (peer dependencies)
+- `viem` ^2.0.0 and `@pafi-dev/core` ^0.5.16 (peer dependencies)
+
+> **Latest:** `0.5.28` — adds bundler-receipt fallback for status polling
+> and propagates Pimlico's re-estimated gas + bundler-required gas price
+> through `SponsorshipResponse`. Required to fix `AA34` paymaster-sig
+> errors and the "status stuck PENDING" indexer race. See
+> [Changelog](#changelog).
 
 ---
 
@@ -240,13 +246,91 @@ const sponsorship = await pafiClient.requestSponsorship({
   },
 });
 
+// Paymaster fields
 // sponsorship.paymaster
 // sponsorship.paymasterData
 // sponsorship.paymasterVerificationGasLimit
 // sponsorship.paymasterPostOpGasLimit
+// Pimlico's re-estimated values — MUST overwrite the userOp's matching
+// fields BEFORE computing the userOpHash, or both AA24 (sender sig) and
+// AA34 (paymaster sig) fire on the bundler. See "Critical: apply gas
+// overrides" below.
+// sponsorship.callGasLimit?
+// sponsorship.verificationGasLimit?
+// sponsorship.preVerificationGas?
+// sponsorship.maxFeePerGas?           // bundler-required floor
+// sponsorship.maxPriorityFeePerGas?
 // sponsorship.expiresAt
 ```
 
+### Critical: apply gas overrides before computing the userOpHash
+
+Pimlico's `pm_sponsorUserOperation` does two things the SDK didn't
+previously echo back:
+
+1. **Re-estimates** `callGasLimit` / `verificationGasLimit` /
+   `preVerificationGas`. The paymaster signature signs over these new
+   values.
+2. **Quotes the bundler-required gas price** — `eth_feeHistory` on Base
+   regularly underestimates the bundler floor by 10–15 %, producing
+   `maxFeePerGas must be at least …` rejections.
+
+Both sets of values are now returned on `SponsorshipResponse`. Apply
+them to the userOp **before** calling `computeUserOpHash`:
+
+```ts
+function applyOverrides<T extends Record<string, unknown>>(
+  userOp: T,
+  fields: Awaited<ReturnType<typeof pafiClient.requestSponsorship>> | undefined,
+): T {
+  if (!fields) return userOp;
+  const merged: Record<string, unknown> = { ...userOp };
+  for (const [k, v] of Object.entries(fields)) if (v !== undefined) merged[k] = v;
+  return merged as T;
+}
+
+const fields = await pafiClient.requestSponsorship({ /* ... */ });
+const final = applyOverrides(userOp, fields);
+const userOpHash = computeUserOpHash(final, chainId);  // matches what the bundler will hash
+```
+
+### Bundler receipt fallback for status polling
+
+`PointIndexer.deductBalance` matches `(user, token, amount, oldest
+PENDING)`. When several PENDING locks share the same amount, the
+indexer can resolve a *different* lock than the one the user is
+currently polling — symptom: `/claim/status` returns PENDING forever
+even though the on-chain mint succeeded.
+
+`PafiBackendClient.getUserOpReceipt(userOpHash)` proxies
+`eth_getUserOperationReceipt` through PAFI's authenticated `/bundler/receipt`
+endpoint, letting status handlers short-circuit the indexer:
+
+```ts
+import { PafiBackendClient } from "@pafi-dev/issuer";
+
+// Inside POST /claim/submit, persist the bundler-returned userOpHash on
+// the lock (add a `user_op_hash` column to your locked_mint_requests).
+await ledger.bindMintUserOpHash(lockId, result.userOpHash);
+
+// Inside GET /claim/status/:lockId
+const lock = await ledger.getMintLock(lockId);
+if (lock.status === "PENDING" && lock.userOpHash) {
+  const receipt = await pafiClient.getUserOpReceipt(lock.userOpHash);
+  if (receipt) {
+    const status = receipt.success ? "MINTED" : "FAILED";
+    await ledger.updateMintStatus(lock.id, status, receipt.txHash);
+    return { ...lock, status, txHash: receipt.txHash };
+  }
+}
+return lock;  // bundler hasn't seen it yet — keep polling
+```
+
+Returns `null` when the bundler hasn't confirmed yet (still in mempool /
+not bundled). The indexer continues to do off-chain accounting in the
+background; the receipt fallback only affects *user-visible status*,
+not balance correctness.
+
 ---
 
 ## Error handling
@@ -302,6 +386,77 @@ try {
 
 ## Changelog
 
+### 0.5.28
+
+`PafiBackendClient.getUserOpReceipt(userOpHash)` added.
+
+**Why.** When several PENDING mint/redeem locks share the same amount,
+`PointIndexer` / `BurnIndexer` resolve them by `(user, token, amount,
+oldest PENDING)` — the userOp's actual bundler hash isn't part of the
+match. A lock the user is *currently polling* can be left PENDING while
+a *sibling* lock gets the on-chain `tx_hash`, so `/claim/status`
+returns PENDING forever even though the mint succeeded.
+
+The new method calls PAFI's authenticated bundler-receipt proxy and
+returns `{ success, txHash, blockNumber } | null`. Status handlers can
+look up the user's specific userOpHash and bypass the indexer race
+entirely:
+
+```ts
+const receipt = await pafiClient.getUserOpReceipt(lock.userOpHash);
+if (receipt?.success) markMinted(lock.id, receipt.txHash);
+```
+
+Pair this with a `user_op_hash` column on your locks table that you set
+inside `/claim/submit` from the value returned by `relayUserOperation`.
+
+### 0.5.27
+
+`SponsorshipResponse` now carries Pimlico's re-estimated gas + bundler
+gas price.
+
+**Why this fixes AA34 / AA24.** `pm_sponsorUserOperation` re-estimates
+`callGasLimit` / `verificationGasLimit` / `preVerificationGas` AND
+quotes the bundler-required `maxFeePerGas` / `maxPriorityFeePerGas`. The
+paymaster signature is computed *over those new values*, not the values
+the SDK originally proposed. If the caller submits the userOp with the
+*original* gas fields:
+
+- The bundler hashes the on-chain UserOp with the original values
+- The paymaster signature recovers a different signer → `AA34
+  signature error`
+- The user signature, computed over a different `userOpHash`, also
+  fails → `AA24 signature error` (whichever fires first depends on the
+  validation order)
+
+The response now exposes:
+
+```ts
+interface SponsorshipResponse {
+  paymaster: Address;
+  paymasterData: Hex;
+  paymasterVerificationGasLimit: bigint;
+  paymasterPostOpGasLimit: bigint;
+  callGasLimit?: bigint;             // NEW — Pimlico re-estimate
+  verificationGasLimit?: bigint;     // NEW
+  preVerificationGas?: bigint;       // NEW
+  maxFeePerGas?: bigint;             // NEW — bundler-required floor
+  maxPriorityFeePerGas?: bigint;     // NEW
+  expiresAt: number;
+}
+```
+
+**Callers must merge these (skipping `undefined`) into the userOp
+before computing `userOpHash`** — see the
+"Critical: apply gas overrides" section above.
+
+### 0.5.26
+
+`@pafi-dev/core` peer dependency bumped to `0.5.16` to pull in the v0.8
+EIP-712 userOpHash + `buildUserOpTypedData()` helpers. This is what
+makes the EIP-7702 mobile flow validate cleanly on Pimlico's
+`Simple7702Account` (no AA24).
+
 ### 0.4.0
 - `PafiBackendClient` added — HTTP client for PAFI paymaster backend with retry logic and bigint serialization
 - `SponsorAuth` support — issuer signs EIP-712 authorization for FE to request paymaster sponsorship

package/dist/index.cjs

@@ -2069,6 +2069,51 @@ var PafiBackendClient = class {
     }
     throw lastError;
   }
+  /**
+   * Fetch ERC-4337 UserOp receipt via PAFI's authenticated bundler proxy.
+   * Returns `null` when the bundler hasn't seen the userOp yet — caller
+   * should keep polling. Used by status endpoints to short-circuit the
+   * on-chain indexer when several PENDING locks share the same amount.
+   */
+  async getUserOpReceipt(userOpHash) {
+    const fetchFn = this.config.fetchImpl ?? fetch;
+    const url = `${this.config.url}/bundler/receipt`;
+    let response;
+    try {
+      response = await fetchFn(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-Issuer-Id": this.config.issuerId
+        },
+        body: JSON.stringify({ userOpHash })
+      });
+    } catch (err) {
+      throw new PafiBackendError(
+        "NETWORK_ERROR",
+        `Network error: ${err instanceof Error ? err.message : String(err)}`,
+        0
+      );
+    }
+    const text = await response.text();
+    let json = {};
+    try {
+      json = JSON.parse(text);
+    } catch {
+    }
+    if (!response.ok) {
+      const code = json.code ?? "INTERNAL_ERROR";
+      const message = json.message ?? `HTTP ${response.status}`;
+      throw new PafiBackendError(code, message, response.status, json);
+    }
+    if (json.pending) return null;
+    return {
+      success: json.success,
+      txHash: json.txHash,
+      blockNumber: json.blockNumber
+    };
+  }
   async relayUserOperation(request) {
     const fetchFn = this.config.fetchImpl ?? fetch;
     const url = `${this.config.url}/bundler/relay`;