abstractionkit 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 0.3.3
+
+### New Features
+
+- **`TokenQuote` type** exported from the package root: `{ token: string; exchangeRate: bigint; tokenCost: bigint }`. Surfaces the exchange rate and maximum token cost the paymaster applied when paying gas with an ERC-20 token, so consumers can display the cost to users or log/meter it without a second RPC round-trip.
+- **`CandidePaymaster.createTokenPaymasterUserOperation` and `Erc7677Paymaster.createPaymasterUserOperation` now return `tokenQuote`** alongside the UserOperation. Populated on the token-payment flow; absent on sponsored flows and on Candide's `signingPhase: "finalize"` path (no gas estimation → no cost computation).
+- **`skipGasEstimation` flag on `createUserOperation` overrides** for `SafeAccount`, `Calibur7702Account`, and `Simple7702Account`. When set, the UserOperation is returned with a dummy signature and zero (or override-provided) gas limits, skipping the bundler's `eth_estimateUserOperationGas` roundtrip. Useful when gas estimation is run separately, for example by a paymaster sponsorship call that returns its own gas limits.
+- **`SponsorInfo` type** exported from the package root. Represents the raw `{ name, icon? }` shape returned by paymasters per ERC-7677; `CandidePaymaster` normalizes it into the public `SponsorMetadata` shape.
+
+### Breaking Changes
+
+- **Three paymaster methods changed return shape** from a raw UserOperation / tuple to a named-field object. All now return `{ userOperation, tokenQuote? | sponsorMetadata? }`:
+  - `CandidePaymaster.createTokenPaymasterUserOperation` — returns `{ userOperation, tokenQuote? }` (was `SameUserOp<T>`).
+  - `CandidePaymaster.createSponsorPaymasterUserOperation` — returns `{ userOperation, sponsorMetadata? }` (was `[SameUserOp<T>, SponsorMetadata | undefined]`).
+  - `Erc7677Paymaster.createPaymasterUserOperation` — returns `{ userOperation, tokenQuote? }` (was `SameUserOp<T>`).
+
+  Migration:
+  ```ts
+  // Before
+  const [sponsoredOp, sponsorMetadata] = await paymaster.createSponsorPaymasterUserOperation(...);
+  const tokenOp = await paymaster.createTokenPaymasterUserOperation(...);
+  const userOp = await erc7677.createPaymasterUserOperation(...);
+
+  // After
+  const { userOperation: sponsoredOp, sponsorMetadata } = await paymaster.createSponsorPaymasterUserOperation(...);
+  const { userOperation: tokenOp, tokenQuote } = await paymaster.createTokenPaymasterUserOperation(...);
+  const { userOperation, tokenQuote } = await erc7677.createPaymasterUserOperation(...);
+  ```
+- **`CandidePaymasterContext` moved back to a dedicated parameter** on `CandidePaymaster.createSponsorPaymasterUserOperation` and `createTokenPaymasterUserOperation`. The `context` field was removed from `GasPaymasterUserOperationOverrides`, and `context` is now the second-to-last argument (optional) on both methods, with `overrides` as the last argument. Migration:
+  ```ts
+  // Before (0.3.2): context nested inside overrides
+  await paymaster.createSponsorPaymasterUserOperation(
+    smartAccount, userOp, bundlerRpc, sponsorshipPolicyId,
+    { context: { signingPhase: "commit" }, maxFeePerGasMultiplier: 110n },
+  );
+  await paymaster.createTokenPaymasterUserOperation(
+    smartAccount, userOp, tokenAddress, bundlerRpc,
+    { context: { signingPhase: "commit" }, maxFeePerGasMultiplier: 110n },
+  );
+
+  // After (0.3.3): context is a dedicated argument
+  await paymaster.createSponsorPaymasterUserOperation(
+    smartAccount, userOp, bundlerRpc, sponsorshipPolicyId,
+    { signingPhase: "commit" },
+    { maxFeePerGasMultiplier: 110n },
+  );
+  // For createTokenPaymasterUserOperation, `context` is optional: the method
+  // always derives `context.token` from the `tokenAddress` argument, so pass
+  // `undefined` unless you need other context fields (e.g. `signingPhase`).
+  await paymaster.createTokenPaymasterUserOperation(
+    smartAccount, userOp, tokenAddress, bundlerRpc,
+    undefined,
+    { maxFeePerGasMultiplier: 110n },
+  );
+  ```
+
+### Bug Fixes
+
+- **`CandidePaymaster` now parses sponsor info per ERC-7677.** Paymasters return sponsor info under `sponsor: { name, icon? }` (singular `icon`); the previous code read a non-standard `sponsorMetadata` key and therefore always returned `undefined`. The raw response is now normalized into the public `SponsorMetadata` shape (`{ name, description, url, icons[] }`).
+
+## 0.3.2
+
+### New Features
+
+- **`signUserOperationWithSigner(s)` + `ExternalSigner` (capability-oriented signing API)**: new async method on every account class for integrating viem, ethers Signers, hardware wallets, HSMs, MPC, WebAuthn, or Uint8Array-only signers without passing raw private keys. Each account declares its accepted schemes via a static `ACCEPTED_SIGNING_SCHEMES: ReadonlyArray<"hash" | "typedData">`, and incompatible signers fail offline with an actionable error. The method naming mirrors the parameter arity:
+  - Safe accounts (multi-signer): `signUserOperationWithSigners(op, signers[], chainId)` — plural.
+  - Simple7702 / Calibur (single signer): `signUserOperationWithSigner(op, signer, chainId)` — singular.
+
+  Call-site is one line:
+  ```ts
+  import { fromViem } from "abstractionkit"
+  userOp.signature = await safe.signUserOperationWithSigners(
+      userOp, [fromViem(account)], chainId,
+  )
+  ```
+
+- **`ExternalSigner` interface**: `{ address, signHash?, signTypedData? }` discriminated union that enforces at least one of the two methods at compile time. Accepts any signer that matches the shape (viem local account, viem WalletClient, ethers Wallet, hardware wallet, MPC, WebAuthn, Uint8Array-held keys). The library has zero runtime dependency on viem or ethers for this surface.
+- **`fromPrivateKey(pk)` / `fromViem(account)` / `fromEthersWallet(wallet)` / `fromViemWalletClient(client)` adapters**: one-line factories returning an `ExternalSigner`. Structural types only. `fromViem` / `fromViemWalletClient` require viem ≥ 2.0; `fromEthersWallet` requires ethers ≥ 6.0.
+- **`SignHashFn` / `SignTypedDataFn` / `TypedData` / `SigningScheme` / `SignContext` / `MultiOpSignContext` types** exported from the package root for implementers of custom signers.
+- **`SignContext` forwarded to signers, narrowly typed per signing path**: signers receive a context as the second arg of `signHash` / `signTypedData` so custom validator implementations can inspect the userOp. `Signer<C>` is generic over context (default `C = SignContext` for single-op `{userOperation, chainId, entryPoint}`; opt into `ExternalSigner<MultiOpSignContext>` for `signUserOperationsWithSigners`'s `{userOperations[], entryPoint}`). Built-in adapters return `Signer<unknown>` and work everywhere. See `src/signer/types.ts`.
+- **`SafeMultiChainSigAccountV1.signUserOperationsWithSigners`**: new async multi-op variant that signs a Merkle-rooted bundle of UserOperations with a single signature across chains, using `ExternalSigner[]`.
+
+### Breaking Changes
+
+> **Note on versioning.** The callback-API removal below is a breaking change for callers of `signUserOperationWithSigner`'s prior callback shape on `Calibur7702Account`. Calibur is not yet in use in any production environment; we're communicating directly with the developers currently building against it to coordinate the migration.
+
+- **`SafeAccount.baseSignSingleUserOperation` is now `protected static`.** Previously `public static`, which leaked an internal helper into the package surface. All callers should use the version-specific subclass methods that wrap it (`SafeAccountV0_2_0#signUserOperation`, `SafeAccountV0_3_0#signUserOperation`, etc.) — they auto-inject the correct entrypoint and 4337 module addresses. Migration:
+  ```ts
+  // Before:
+  const sig = SafeAccount.baseSignSingleUserOperation(
+    op, [pk], chainId,
+    SafeAccountV0_3_0.DEFAULT_ENTRYPOINT_ADDRESS,
+    SafeAccountV0_3_0.DEFAULT_SAFE_4337_MODULE_ADDRESS,
+  );
+  // After:
+  const sig = safeV3.signUserOperation(op, [pk], chainId);
+  ```
+  `baseSignUserOperationWithSigners` (introduced earlier in this Unreleased window) is also `protected static` for the same reason; no migration needed since it was never on a released `latest` tag.
+- **`ViemLocalAccountLike` / `ViemWalletClientLike` / `EthersWalletLike` are no longer exported.** They're internal structural shapes the adapters match against; pass concrete viem / ethers instances directly to `fromViem` / `fromViemWalletClient` / `fromEthersWallet`. If you need to type a wrapper, use `Parameters<typeof fromViem>[0]` (etc.).
+- **Callback signing API removed.** `signUserOperationWithSigner(op, callback, chainId)` as introduced in the original signer PR is gone, along with the `SignerFunction`, `AddressedSignerFunction`, `SignerInput`, `SignerResult`, and `SignerTypedData` types. The callback method name is now reused for the new capability-oriented API on single-signer accounts (Simple7702, Calibur) with a different parameter shape. Migration:
+  ```ts
+  // Before:
+  const signer = async ({ userOpHash }) => ({
+    signature: wallet.signingKey.sign(userOpHash).serialized,
+  });
+  userOp.signature = await account.signUserOperationWithSigner(userOp, signer, chainId);
+
+  // After — Simple7702 / Calibur (single signer):
+  import { fromEthersWallet } from "abstractionkit";
+  userOp.signature = await account.signUserOperationWithSigner(
+    userOp, fromEthersWallet(wallet), chainId,
+  );
+
+  // After — Safe accounts (multi-signer, plural method name):
+  userOp.signature = await safe.signUserOperationWithSigners(
+    userOp, [fromEthersWallet(wallet)], chainId,
+  );
+  ```
+
+### Migration: Signing with a raw private key
+
+The existing sync `signUserOperation(op, pk[] | pk, chainId): string` method on every account **is untouched**. If your code passes a hex private-key string directly, no change needed. The new `signUserOperationWithSigner(s)` methods are Signers-only — they do NOT accept bare pk strings. To sign with a pk string via the new API, wrap explicitly:
+
+```ts
+import { fromPrivateKey } from "abstractionkit";
+userOp.signature = await safe.signUserOperationWithSigners(
+  userOp, [fromPrivateKey(pk)], chainId,
+);
+```
+
 ## 0.3.1
 
 ### New Features

package/README.md

@@ -38,10 +38,10 @@ npm install abstractionkit
 
 ### Upgrading to v0.3.0
 
-v0.3.0 is a major release. Two API changes are likely to break existing paymaster code:
+v0.3.0 is a major release. The following API changes are likely to break existing paymaster code:
 
-- `CandidePaymaster.createSponsorPaymasterUserOperation(...)` now takes `smartAccount` as the **first** argument: `(smartAccount, userOp, bundlerRpc, sponsorshipPolicyId?, overrides?)`.
-- `CandidePaymasterContext` is no longer a separate argument. Pass it via `overrides.context` on `GasPaymasterUserOperationOverrides`.
+- `CandidePaymaster.createSponsorPaymasterUserOperation(...)` now takes `smartAccount` as the **first** argument: `(smartAccount, userOp, bundlerRpc, sponsorshipPolicyId?, context?, overrides?)`.
+- `CandidePaymaster.createTokenPaymasterUserOperation(...)` adds a dedicated `context?` argument before `overrides?`: `(smartAccount, userOp, tokenAddress, bundlerRpc, context?, overrides?)`. Callers that previously passed `overrides` positionally at argument 5 must insert `undefined` (or an explicit context) so `overrides` shifts to argument 6.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full list of new features, renames, type export changes, and fixes.
 
@@ -143,12 +143,13 @@ const userOp = await smartAccount.createUserOperation(
 
 // Sponsor it. Sets paymaster fields and re-estimates gas.
 // Note: as of v0.3.0, smartAccount is the first argument.
-const [sponsoredOp] = await paymaster.createSponsorPaymasterUserOperation(
+const { userOperation: sponsoredOp, sponsorMetadata } = await paymaster.createSponsorPaymasterUserOperation(
   smartAccount,
   userOp,
   bundlerRpc,
   sponsorshipPolicyId,
-  // overrides (optional, includes context for parallel signing)
+  // context (optional — e.g. { signingPhase: "commit" } for EP v0.9 parallel signing)
+  // overrides (optional — gas limits and multipliers)
 );
 
 // Sign and send as usual
@@ -173,12 +174,14 @@ const userOp = await smartAccount.createUserOperation(
 // Automatically prepends token approval + sets paymaster fields.
 // For tokens like USDT that require resetting allowance to 0 first, pass
 // { resetApproval: true } in the overrides.
-const tokenOp = await paymaster.createTokenPaymasterUserOperation(
+// `tokenQuote` carries the exchange rate and max token cost used for the approval.
+const { userOperation: tokenOp, tokenQuote } = await paymaster.createTokenPaymasterUserOperation(
   smartAccount,
   userOp,
   gasTokenAddress,
   bundlerRpc,
-  // overrides (optional)
+  // context (optional)
+  // overrides (optional — gas limits, multipliers, resetApproval)
 );
 
 tokenOp.signature = smartAccount.signUserOperation(tokenOp, [ownerPrivateKey], chainId);
@@ -187,20 +190,20 @@ const response = await smartAccount.sendUserOperation(tokenOp, bundlerRpc);
 
 ### Pass paymaster context (sponsorship policy, parallel signing)
 
-As of v0.3.0, `CandidePaymasterContext` is passed via the `overrides.context` field on `GasPaymasterUserOperationOverrides`. Previously it was a separate top level argument.
+`CandidePaymasterContext` is passed as its own argument, separate from gas overrides.
 
 ```typescript
-const [sponsoredOp] = await paymaster.createSponsorPaymasterUserOperation(
+const { userOperation: sponsoredOp } = await paymaster.createSponsorPaymasterUserOperation(
   smartAccount,
   userOp,
   bundlerRpc,
   sponsorshipPolicyId,
   {
-    context: {
-      // For EntryPoint v0.9 parallel signing flows:
-      // signingPhase: "commit" | "finalize",
-    },
-    // gas overrides also live here:
+    // For EntryPoint v0.9 parallel signing flows:
+    // signingPhase: "commit" | "finalize",
+  },
+  {
+    // gas overrides:
     callGasLimitPercentageMultiplier: 110,
   },
 );