@pafi-dev/issuer 0.5.28 → 0.5.30

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

@@ -2321,7 +2321,28 @@ function createIssuerService(config) {
 
 // src/userop-store/serialize.ts
 var import_core9 = require("@pafi-dev/core");
-function serializeEntryToJsonRpc(entry, signature) {
+function serializeEntryToJsonRpc(entry, signature, variant = "sponsored") {
+  if (variant === "fallback") {
+    if (!entry.fallback) {
+      throw new Error(
+        "serializeEntryToJsonRpc: variant=fallback requested but the stored entry has no `fallback` branch \u2014 caller should resubmit with variant='sponsored' or re-prepare with a fee configured."
+      );
+    }
+    return (0, import_core9.serializeUserOpToJsonRpc)(
+      {
+        sender: entry.sender,
+        nonce: BigInt(entry.nonce),
+        callData: entry.fallback.callData,
+        callGasLimit: BigInt(entry.fallback.callGasLimit),
+        verificationGasLimit: BigInt(entry.fallback.verificationGasLimit),
+        preVerificationGas: BigInt(entry.fallback.preVerificationGas),
+        maxFeePerGas: BigInt(entry.maxFeePerGas),
+        maxPriorityFeePerGas: BigInt(entry.maxPriorityFeePerGas)
+        // intentionally no paymaster — user pays ETH gas
+      },
+      signature
+    );
+  }
   return (0, import_core9.serializeUserOpToJsonRpc)(
     {
       sender: entry.sender,