feat: add txHashResolver support for AA wallets in StoryClient

Support optional txHashResolver in StoryClient and all factory methods to resolve userOp hashes before waiting for transaction receipts. Add unit/integration coverage for resolver wiring and raw userOp wallet behavior (including value/fee forwarding), and stabilize oov3 error-path unit test stubbing.

Author: yingyangxu2026

docs/v1.4.4-release.md

@@ -0,0 +1,123 @@
+# v1.4.4 Release Notes
+
+## New Features
+
+### Account Abstraction (AA) Wallet Support — `txHashResolver`
+
+Added support for Account Abstraction wallets (e.g. **ZeroDev**, **Dynamic Global Wallet**) via a new optional `txHashResolver` configuration parameter.
+
+#### Problem
+
+When using AA wallets, `writeContract` returns a **UserOperation hash** instead of a standard **transaction hash**. The SDK's `waitForTransactionReceipt` only works with regular transaction hashes, causing AA wallet transactions to fail silently or hang.
+
+#### Solution
+
+A new `txHashResolver` option can be passed when creating a `StoryClient`. This function resolves UserOperation hashes into on-chain transaction hashes before the SDK waits for receipts. The resolver is applied transparently — **all existing SDK methods work without any changes**.
+
+#### Usage
+
+**Normal wallets** — no changes needed:
+
+```typescript
+const client = StoryClient.newClient({
+  transport: http("https://aeneid.storyrpc.io"),
+  account: privateKeyToAccount("0x..."),
+});
+```
+
+**ZeroDev AA wallet — Using Kernel Client directly (recommended)**:
+
+ZeroDev's `createKernelAccountClient` returns a viem smart account client whose `writeContract` internally sends the UserOperation, waits for the bundler to include it on-chain, and returns the **real tx hash**. Therefore **`txHashResolver` is NOT needed** — simply pass the kernel client as the wallet:
+
+```typescript
+import { createKernelAccountClient } from "@zerodev/sdk";
+
+const kernelClient = await createKernelAccountClient({ /* ... */ });
+
+const client = StoryClient.newClientUseWallet({
+  transport: http("https://aeneid.storyrpc.io"),
+  wallet: kernelClient,
+  // No txHashResolver needed — kernel client handles it internally
+});
+
+// All SDK methods work as usual
+const result = await client.ipAsset.mintAndRegisterIpAssetWithPilTerms({
+  spgNftContract: "0x...",
+  terms: [],
+});
+```
+
+**Raw UserOp wallet + txHashResolver (for AA wallets that return userOpHash)**:
+
+Some AA wallet integrations return the **UserOperation hash** directly from `writeContract` without internally waiting for the bundler receipt. For these wallets, configure `txHashResolver` to convert the userOpHash into the real on-chain tx hash:
+
+```typescript
+const client = StoryClient.newClientUseWallet({
+  transport: http("https://aeneid.storyrpc.io"),
+  wallet: rawAAWallet, // writeContract returns userOpHash
+  txHashResolver: async (userOpHash) => {
+    const receipt = await bundlerClient.waitForUserOperationReceipt({
+      hash: userOpHash,
+    });
+    return receipt.receipt.transactionHash;
+  },
+});
+```
+
+> **How to tell?** If the hash returned by the AA wallet's `writeContract` cannot be found as a transaction on a block explorer, it is a userOpHash and you need `txHashResolver`. If it can be found on-chain directly, the wallet already handles resolution internally and no resolver is needed.
+
+**Dynamic Global Wallet**:
+
+```typescript
+const client = StoryClient.newClientUseWallet({
+  transport: http("https://aeneid.storyrpc.io"),
+  wallet: dynamicWalletClient,
+  txHashResolver: async (userOpHash) => {
+    // Use Dynamic's bundler client to resolve the hash
+    const receipt = await dynamicBundlerClient.waitForUserOperationReceipt({
+      hash: userOpHash,
+    });
+    return receipt.receipt.transactionHash;
+  },
+});
+```
+
+#### Supported Factory Methods
+
+`txHashResolver` is supported by all three client creation methods:
+
+- `StoryClient.newClient({ ..., txHashResolver })`
+- `StoryClient.newClientUseWallet({ ..., txHashResolver })`
+- `StoryClient.newClientUseAccount({ ..., txHashResolver })`
+
+#### API Reference
+
+```typescript
+/**
+ * A function that resolves a hash returned by writeContract into an actual
+ * transaction hash that can be used with waitForTransactionReceipt.
+ *
+ * @param hash - The hash returned by writeContract (could be a userOpHash or txHash)
+ * @returns The resolved on-chain transaction hash
+ */
+type TxHashResolver = (hash: Hash) => Promise<Hash>;
+```
+
+## Changed Files
+
+| File | Change |
+|------|--------|
+| `packages/core-sdk/src/types/config.ts` | Added `TxHashResolver` type; added `txHashResolver` to `StoryConfig`, `UseWalletStoryConfig`, `UseAccountStoryConfig` |
+| `packages/core-sdk/src/client.ts` | Added `applyTxHashResolver()` method; patched `rpcClient.waitForTransactionReceipt` when resolver is provided; forwarded resolver in factory methods |
+| `packages/core-sdk/test/unit/client.test.ts` | Added unit tests that verify resolver wiring, hash transformation, and constructor-time patching |
+| `packages/core-sdk/test/integration/txHashResolver.test.ts` | ZeroDev E2E integration tests (6 passing), covering both AA wallet modes |
+| `packages/core-sdk/package.json` | Added `@zerodev/sdk`, `@zerodev/ecdsa-validator` as devDependencies |
+
+## Test Coverage Notes
+
+- **Unit tests**: Validate that `txHashResolver` is invoked before receipt polling and that the resolved hash is used for receipt lookup.
+- **Integration tests — Pass-through & Simulated**: Cover normal wallet pass-through and simulated AA hash mapping behavior.
+- **Integration tests — ZeroDev E2E (2 scenarios)**:
+  - **Kernel client as wallet**: Verifies that `writeContract` returns a real txHash and the SDK works correctly without a resolver.
+  - **Raw userOp wallet + txHashResolver**: Uses a custom wallet wrapper (whose `writeContract` returns a userOpHash) to verify end-to-end that the resolver converts the userOpHash into a real on-chain txHash.
+- ZeroDev E2E tests require `BUNDLER_RPC_URL` and `WALLET_PRIVATE_KEY` in `.env`. Tests are automatically skipped when these are not configured.

packages/core-sdk/package.json

@@ -50,6 +50,8 @@
     "@types/mocha": "^10.0.2",
     "@types/node": "^20.8.2",
     "@types/sinon": "^10.0.18",
+    "@zerodev/ecdsa-validator": "^5.4.9",
+    "@zerodev/sdk": "^5.5.7",
     "c8": "^8.0.1",
     "chai": "^4.3.10",
     "chai-as-promised": "^7.1.1",

packages/core-sdk/src/client.ts

@@ -11,7 +11,13 @@ import { NftClient } from "./resources/nftClient";
 import { PermissionClient } from "./resources/permission";
 import { RoyaltyClient } from "./resources/royalty";
 import { WipClient } from "./resources/wip";
-import { ChainIds, StoryConfig, UseAccountStoryConfig, UseWalletStoryConfig } from "./types/config";
+import {
+  ChainIds,
+  StoryConfig,
+  TxHashResolver,
+  UseAccountStoryConfig,
+  UseWalletStoryConfig,
+} from "./types/config";
 import { chain, chainStringToViemChain, validateAddress } from "./utils/utils";
 
 if (typeof process !== "undefined") {
@@ -52,6 +58,12 @@ export class StoryClient {
 
     this.rpcClient = createPublicClient(clientConfig);
 
+    // If a txHashResolver is provided (e.g. for AA wallets like ZeroDev/Dynamic),
+    // patch waitForTransactionReceipt to resolve the hash first.
+    if (config.txHashResolver) {
+      this.applyTxHashResolver(config.txHashResolver);
+    }
+
     if (this.config.wallet) {
       this.wallet = this.config.wallet;
     } else if (this.config.account) {
@@ -66,6 +78,23 @@ export class StoryClient {
     }
   }
 
+  /**
+   * Patches rpcClient.waitForTransactionReceipt to first resolve the hash
+   * through the provided resolver. This transparently supports AA wallets
+   * where writeContract returns a UserOperation hash instead of a tx hash.
+   */
+  private applyTxHashResolver(resolver: TxHashResolver): void {
+    const originalWaitForReceipt = this.rpcClient.waitForTransactionReceipt.bind(
+      this.rpcClient,
+    );
+    this.rpcClient.waitForTransactionReceipt = async (
+      args,
+    ): ReturnType<PublicClient["waitForTransactionReceipt"]> => {
+      const resolvedHash = await resolver(args.hash);
+      return originalWaitForReceipt({ ...args, hash: resolvedHash });
+    };
+  }
+
   private get chainId(): ChainIds {
     return this.config.chainId as ChainIds;
   }
@@ -86,6 +115,7 @@ export class StoryClient {
       chainId: config.chainId,
       transport: config.transport,
       wallet: config.wallet,
+      txHashResolver: config.txHashResolver,
     });
   }
 
@@ -97,6 +127,7 @@ export class StoryClient {
       account: config.account,
       chainId: config.chainId,
       transport: config.transport,
+      txHashResolver: config.txHashResolver,
     });
   }
 

packages/core-sdk/src/types/config.ts

@@ -1,4 +1,4 @@
-import { Account, Address, Transport } from "viem";
+import { Account, Address, Hash, Transport } from "viem";
 
 import { SimpleWalletClient } from "../abi/generated";
 
@@ -9,6 +9,34 @@ import { SimpleWalletClient } from "../abi/generated";
  */
 export type SupportedChainIds = "aeneid" | "mainnet" | ChainIds;
 
+/**
+ * A function that resolves a hash returned by `writeContract` into an actual
+ * transaction hash that can be used with `waitForTransactionReceipt`.
+ *
+ * This is required when using Account Abstraction wallets (e.g. ZeroDev, Dynamic)
+ * because `writeContract` returns a UserOperation hash instead of a regular
+ * transaction hash. The resolver should wait for the UserOperation to be bundled
+ * and return the resulting on-chain transaction hash.
+ *
+ * @example ZeroDev
+ * ```typescript
+ * const client = StoryClient.newClientUseWallet({
+ *   transport: http("https://..."),
+ *   wallet: kernelClient,
+ *   txHashResolver: async (userOpHash) => {
+ *     const receipt = await bundlerClient.waitForUserOperationReceipt({
+ *       hash: userOpHash,
+ *     });
+ *     return receipt.receipt.transactionHash;
+ *   },
+ * });
+ * ```
+ *
+ * @param hash - The hash returned by `writeContract` (could be a userOpHash or txHash)
+ * @returns The resolved on-chain transaction hash
+ */
+export type TxHashResolver = (hash: Hash) => Promise<Hash>;
+
 /**
  * Configuration for the SDK Client.
  *
@@ -23,6 +51,11 @@ export type UseAccountStoryConfig = {
    */
   readonly chainId?: SupportedChainIds;
   readonly transport: Transport;
+  /**
+   * Optional resolver for Account Abstraction wallets.
+   * @see TxHashResolver
+   */
+  readonly txHashResolver?: TxHashResolver;
 };
 
 export type UseWalletStoryConfig = {
@@ -34,6 +67,11 @@ export type UseWalletStoryConfig = {
   readonly chainId?: SupportedChainIds;
   readonly transport: Transport;
   readonly wallet: SimpleWalletClient;
+  /**
+   * Optional resolver for Account Abstraction wallets.
+   * @see TxHashResolver
+   */
+  readonly txHashResolver?: TxHashResolver;
 };
 
 export type StoryConfig = {
@@ -46,6 +84,16 @@ export type StoryConfig = {
   readonly chainId?: SupportedChainIds;
   readonly wallet?: SimpleWalletClient;
   readonly account?: Account | Address;
+  /**
+   * Optional resolver for Account Abstraction wallets (e.g. ZeroDev, Dynamic).
+   *
+   * When provided, the SDK will call this function to resolve the hash returned
+   * by `writeContract` into the actual on-chain transaction hash before waiting
+   * for the transaction receipt.
+   *
+   * @see TxHashResolver
+   */
+  readonly txHashResolver?: TxHashResolver;
 };
 
 export type ContractAddress = { [key in SupportedChainIds]: Record<string, string> };