abstractionkit 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.3.4
+
+### New Features
+
+- **`SafeAccount.isDeployed(accountAddress, nodeRpcUrl)`**: static method that checks whether a Safe account is already deployed on-chain. Returns `true` when `accountAddress` has non-empty bytecode, `false` otherwise. Useful for branching between `new SafeAccountV0_3_0(address)` (existing account) and `SafeAccountV0_3_0.initializeNewAccount([owners])` (counterfactual) without inspecting `eth_getCode` manually.
+
+## 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

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,
   },
 );
@@ -239,6 +242,18 @@ const newAccount = SafeAccountV0_3_0.initializeNewAccount(["0xOwnerAddress"]);
 // First UserOp will deploy it automatically
 ```
 
+When you have a stored Safe address and need to pick between the two paths at runtime, use `isDeployed` to avoid emitting redundant factory data (and the `AA10 sender already constructed` error) on subsequent UserOps:
+
+```typescript
+import { SafeAccountV0_3_0 } from "abstractionkit";
+
+const smartAccount = (await SafeAccountV0_3_0.isDeployed(safeAddress, nodeRpc))
+  ? new SafeAccountV0_3_0(safeAddress)
+  : SafeAccountV0_3_0.initializeNewAccount(owners);
+```
+
+`isDeployed` only checks for bytecode at the address. It does not verify that the deployed code is a Safe or that its on-chain owners match a given set. If your owners may have changed, compare `createAccountAddress(owners)` against the stored address yourself before calling `initializeNewAccount`.
+
 ### Calibur 7702: delegate an EOA and send a transfer
 
 `Calibur7702Account` is Uniswap's EIP-7702 smart account. It upgrades a regular EOA in place so the same address becomes a programmable smart account on EntryPoint v0.8.