abstractionkit 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,113 +1,219 @@
 # Changelog
 
-## 0.3.0
+## 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
 
-#### Build & Runtime
+> **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
 
-- **Node.js >= 18 required** — native `fetch` is now used; `isomorphic-unfetch` has been removed as a dependency.
-- **Build system switched from microbundle to tsdown** — dist output paths have changed:
-  - `dist/index.js` → `dist/index.cjs`
-  - `dist/index.m.js` → `dist/index.mjs`
-  - `dist/index.umd.js` → `dist/index.iife.js`
-  - `dist/index.d.ts` → `dist/index.d.cts`
-  - Proper `exports` map added to `package.json` for ESM/CJS resolution.
+### New Features
 
-#### API Changes
+- **`Erc7677Paymaster`**: provider-agnostic [ERC-7677](https://eips.ethereum.org/EIPS/eip-7677) paymaster client. Works with any compliant provider (Candide, Pimlico, Alchemy, ...). Auto-detects Candide/Pimlico from the URL and runs the full stub, estimate, and final pipeline in one call. Passing `{ token }` in context triggers the ERC-20 gas flow automatically.
+- `Bundler.estimateUserOperationGas` now forwards `paymasterVerificationGasLimit` and `paymasterPostOpGasLimit` when returned by the bundler.
 
-- **`signUserOperation` now only accepts a private key.** Use the new `signUserOperationWithSigner` method for external/custom signers.
-- **`createPaymasterUserOperation` removed.** Use `CandidePaymaster` methods directly.
-- **CandidePaymaster migrated to `pm_getPaymasterData` RPC** — paymaster types have been unified and restructured.
-- **`PaymasterInitValues` renamed to `ParallelPaymasterInitValues`.**
+### Breaking Changes
 
-#### Renames
+- **`SafeMultiChainSigAccountV1.formatSignaturesToUseroperationsSignatures`**: the third `overrides` argument has been removed. Overrides are now per-operation via a new optional `overrides` field on each `UserOperationToSignWithOverrides` element of the first argument. Migration: `ops.map(op => ({ ...op, overrides: {...} }))` and drop the third argument.
 
-| Before | After |
-|--------|-------|
-| `ExperimentalSafeMultiChainSigAccount` | `SafeMultiChainSigAccountV1` |
-| `ExperimentalAllowAllPaymaster` | `ExperimentalAllowAllParallelPaymaster` |
-| `EIP712_MULTI_SAFE_OPERATIONS_TYPE` | `EIP712_MULTI_CHAIN_OPERATIONS_TYPE` |
-| `listKeys` (Calibur) | `getKeys` |
+### Other
+
+- Minor type tightening across Calibur, Simple7702, and Tenderly helpers.
+
+## 0.3.0
+
+**This is a major release. The canonical upgrade path is from 0.2.30 (previous stable) to 0.3.0 (current stable).** Versions 0.2.31 through 0.2.41 were experimental pre-releases and are not on the `latest` dist-tag.
+
+### Breaking Changes
 
-#### TypeScript Export Changes
+#### Build & Runtime
+
+- **Node.js >= 18 required.** Native `fetch` is now used; `isomorphic-unfetch` has been removed as a dependency.
+- **Build system switched from microbundle to tsdown.** Dist output paths have changed. If you import from a subpath, update your references:
+  - `dist/index.js` -> `dist/index.cjs`
+  - `dist/index.m.js` -> `dist/index.mjs`
+  - `dist/index.umd.js` -> `dist/index.iife.js`
+  - `dist/index.d.ts` -> `dist/index.d.cts`
+  - A proper `exports` map has been added to `package.json` for ESM/CJS resolution, so normal `import { X } from "abstractionkit"` consumers are unaffected.
+
+#### Paymaster API
+
+- **`CandidePaymaster.createSponsorPaymasterUserOperation(...)` signature changed.** The method now takes `smartAccount` as the **first** argument. Migration:
+  ```ts
+  // Before (0.2.30):
+  await paymaster.createSponsorPaymasterUserOperation(userOp, bundlerRpc, sponsorshipPolicyId, overrides);
+
+  // After (0.3.0):
+  await paymaster.createSponsorPaymasterUserOperation(smartAccount, userOp, bundlerRpc, sponsorshipPolicyId, overrides);
+  ```
+  The `overrides` parameter type is also richer: it now accepts a `context?: CandidePaymasterContext` field for passing `sponsorshipPolicyId` and the new parallel-signing `signingPhase` option through overrides.
+- **`createPaymasterUserOperation` has been removed.** Use `createSponsorPaymasterUserOperation` or `createTokenPaymasterUserOperation` directly.
+- **CandidePaymaster now uses the `pm_getPaymasterData` JSON-RPC method** internally. Paymaster types have been unified and restructured.
+- **`PaymasterInitValues` renamed to `ParallelPaymasterInitValues`.**
 
-Several interfaces and types are now exported as `export type` instead of `export` for `isolatedModules` compatibility. This is only breaking if you re-export them with `export { X } from "abstractionkit"` — change to `export type { X }`:
+#### TypeScript Export Changes (`isolatedModules` compatibility)
+
+Many interfaces and types are now exported with `export type` instead of `export`. This is only breaking if you re-export them yourself with `export { X } from "abstractionkit"`, in which case change to `export type { X }`. Affected identifiers include:
 
 - `RecoveryRequest`, `RecoverySignaturePair`, `RecoveryRequestTypedDataDomain`, `RecoveryRequestTypedMessageValue`
 - `Allowance`
 - `DepositInfo`
 - `Authorization7702Hex`, `Authorization7702`
 - `CandidePaymasterContext`, `PrependTokenPaymasterApproveAccount`
-- `UserOperationV6`, `UserOperationV7`, `UserOperationV8`, `AbiInputValue`, `JsonRpcParam`, `JsonRpcResponse`, `MetaTransaction`, `StateOverrideSet`, etc.
+- `UserOperationV6`, `UserOperationV7`, `UserOperationV8`, `UserOperationV9`, `AbiInputValue`, `JsonRpcParam`, `JsonRpcResponse`, `MetaTransaction`, `StateOverrideSet`, and other non-runtime types from `./types`
+- `CreateUserOperationV6Overrides`, `CreateUserOperationV7Overrides`, `CreateUserOperationV9Overrides`, `ECDSAPublicAddress`, `InitCodeOverrides`, `SafeUserOperationTypedDataDomain`, `WebauthnPublicKey`, `WebauthnSignatureData`, `SignerSignaturePair`, `Signer`
 - `SafeMessageTypedDataDomain`, `SafeMessageTypedMessageValue`
-- `SafeUserOperationTypedDataDomain`, `WebauthnPublicKey`, `WebauthnSignatureData`, `SignerSignaturePair`, `Signer`, etc.
 
-The wildcard re-export `export * from "./account/Safe/safeMessage"` has been replaced with explicit named exports.
+The wildcard re-export `export * from "./account/Safe/safeMessage"` has been replaced with explicit named exports (`SAFE_MESSAGE_PRIMARY_TYPE`, `SAFE_MESSAGE_MODULE_TYPE`, `getSafeMessageEip712Data`).
 
 ### New Features
 
-#### EIP-7702 Support
+#### New Account Classes
+
+- **`Calibur7702Account`**: full-featured EIP-7702 smart account for EntryPoint v0.8, ported from Uniswap's Calibur. Supports secp256k1, P256, and WebAuthn P256 keys with per-key permissions and expirations. Includes key management (register, revoke, update settings via self-calls), automatic EIP-7702 delegation authoring and checking, and delegation revocation. Also exports `CaliburKeyType` and the `CaliburKey`, `CaliburKeySettings`, `CaliburKeySettingsResult`, `WebAuthnSignatureData`, `CaliburCreateUserOperationOverrides`, `CaliburSignatureOverrides`, and `SignerFunction` types.
+- **`Simple7702AccountV09`**: minimal EIP-7702 account targeting EntryPoint v0.9, with parallel paymaster signing support.
+- **`SafeMultiChainSigAccountV1`**: audited multi-chain signature account. Sign once, replay across chains via a merkle-proof structure. Promoted from experimental.
+- **`SafeAccountV1_5_0_M_0_3_0`**: Safe contract v1.5.0 support with EIP-7951 and the Daimo P256 verifier for WebAuthn.
+
+#### EntryPoint v0.8 and v0.9 Support
 
-- **`Simple7702Account`** — EIP-7702 account for EntryPoint v0.8.
-- **`Simple7702AccountV09`** — EIP-7702 account for EntryPoint v0.9, with parallel paymaster support.
-- **`Calibur7702Account`** — full-featured EIP-7702 account with WebAuthn/passkey support, key management, delegation auto-checking, and delegation revocation.
-- **`getDelegatedAddress`** utility for checking EIP-7702 delegation status.
-- **EIP-7702 delegation helpers** on `BaseSimple7702Account` (create, sign, and revoke delegation authorizations).
-- **Tenderly simulation support** for EntryPoint v0.9.
+- `UserOperationV9` type and `CreateUserOperationV9Overrides` added.
+- `ENTRYPOINT_V6`, `ENTRYPOINT_V7`, `ENTRYPOINT_V8`, `ENTRYPOINT_V9` address constants exported.
+- Bundler, CandidePaymaster, and Tenderly simulation helpers updated to handle all four EntryPoint versions.
+- Entrypoint version resolution has been centralized in `CandidePaymaster`: a new private `resolveEntrypoint` helper reads the target entrypoint from the smart account instance at the top of each public method, replacing the per-method `UserOperation vX.YZ is not supported` checks from 0.2.30. The guard itself is not new, but unsupported-version errors are now surfaced earlier and more consistently.
+
+#### Parallel Paymaster Signing (EntryPoint v0.9)
+
+- **`ExperimentalAllowAllParallelPaymaster`**: an experimental paymaster for the parallel-signing flow.
+- **`signingPhase`** added to `CandidePaymasterContext`, with values `"commit"` and `"finalize"`. Enables parallel-signing flows where owner signing and the paymaster's final signature can happen independently, via the `PAYMASTER_SIG_MAGIC` convention on `paymasterData`. Works with EntryPoint v0.9 only.
+- `CandidePaymaster` supports both v0.9 parallel flows and the existing sequential flow.
 
 #### Safe Accounts
 
-- **`SafeAccountV1_5_0_M_0_3_0`** — Safe contract v1.5.0 support with EIP-7951 and Daimo P256 verifier for WebAuthn.
-- **`SafeMultiChainSigAccountV1`** — multi-chain signature account (audited, promoted from experimental).
-- `createChangeThresholdMetaTransaction`, `createApproveHashMetaTransaction`, and `getThreshold` methods.
-- Auto-prepend `approve(0)` for ERC-20 tokens that require allowance reset before setting a new approval.
+- **`createChangeThresholdMetaTransaction`**, **`createApproveHashMetaTransaction`**, and **`getThreshold`** added to `SafeAccount`. Makes multi-sig threshold management and offchain approval flows first-class.
+- **Auto-prepend `approve(0)`** before setting a new ERC-20 allowance for tokens like USDT that disallow changing a non-zero allowance directly. Opt in via `{ resetApproval: true }` on the token paymaster overrides.
+- **`MerkleTree`** helper utilities added for multi-chain operations.
+
+#### AllowanceModule v1.0.0
+
+- Allowance module updated to v1.0.0. The legacy address is exported as **`ALLOWANCE_MODULE_V0_1_0_ADDRESS`** for migration purposes.
+
+#### Calibur Singleton Addresses
 
-#### EntryPoint v0.9
+- **`CALIBUR_UNISWAP_V1_0_0_SINGLETON_ADDRESS`** and **`CALIBUR_CANDIDE_V0_1_0_SINGLETON_ADDRESS`** exported as constants.
 
-- `UserOperationV9` type added.
-- Version-entrypoint compatibility guard — mismatched UserOperation versions are now caught early.
-- Entrypoint version is now resolved from the account instance.
+#### EIP-7702 Delegation Helpers
 
-#### Paymaster
+- **`getDelegatedAddress(eoaAddress, nodeRpc)`** utility for checking the current EIP-7702 delegation target of an EOA.
+- **Calibur delegation and key revocation**: `Calibur7702Account.createRevokeKeyMetaTransaction` and `createRevokeAllKeysMetaTransactions` for revoking individual or all registered keys, plus `createRevokeDelegationRawTransaction` for revoking the EIP-7702 delegation itself. Complements automatic delegation checking during UserOperation creation.
 
-- **`CandidePaymaster` now supports EntryPoint v0.9 and parallel signing flows.**
-- **`ExperimentalAllowAllParallelPaymaster`** for parallel paymaster data flows.
-- **Signing phases** added to the context object, with support in paymaster flows.
-- Parallel paymaster support for `Simple7702AccountV09`.
+#### Utilities and Constants
 
-#### Utilities
+- **EIP-2098** compact signature support in `parseRawSignature`.
+- **`EIP712_SAFE_OPERATION_PRIMARY_TYPE`** and **`EIP712_MULTI_CHAIN_OPERATIONS_PRIMARY_TYPE`** constants added alongside the existing EIP-712 type constants.
+- **`EIP712_MULTI_CHAIN_OPERATIONS_TYPE`** (previously `EIP712_MULTI_SAFE_OPERATIONS_TYPE`, renamed).
+- New paymaster-type exports: **`AnyUserOperation`**, **`SameUserOp`**.
 
-- `MerkleTree` helper functions for multi-chain operations.
-- EIP-2098 compact signature support in `parseRawSignature`.
-- `EIP712_SAFE_OPERATION_PRIMARY_TYPE` and `EIP712_MULTI_CHAIN_OPERATIONS_PRIMARY_TYPE` constants.
-- Entrypoint address constants: `ENTRYPOINT_V6`, `ENTRYPOINT_V7`, `ENTRYPOINT_V8`, `ENTRYPOINT_V9`.
-- `CALIBUR_UNISWAP_V1_0_0_SINGLETON_ADDRESS` and `CALIBUR_CANDIDE_V0_1_0_SINGLETON_ADDRESS` constants.
-- Legacy `ALLOWANCE_MODULE_V0_1_0_ADDRESS` constant for migration.
+#### Tenderly
+
+- Tenderly simulation helpers updated to support EntryPoint v0.9 and `IAccountExecute.executeUserOp` callData rewriting.
+
+### Renames
+
+| Before | After |
+|--------|-------|
+| `ExperimentalSafeMultiChainSigAccount` | `SafeMultiChainSigAccountV1` |
+| `ExperimentalAllowAllPaymaster` | `ExperimentalAllowAllParallelPaymaster` |
+| `EIP712_MULTI_SAFE_OPERATIONS_TYPE` | `EIP712_MULTI_CHAIN_OPERATIONS_TYPE` |
+| `PaymasterInitValues` | `ParallelPaymasterInitValues` |
+| `listKeys` (Calibur) | `getKeys` |
+
+These renames only apply to code built on intermediate experimental versions (0.2.31 through 0.2.41). Code on 0.2.30 does not reference these identifiers.
 
 ### Bug Fixes
 
-- Fix object mutation via aliasing in `SafeAccountV1_5_0_M_0_3_0` and `CandidePaymaster`.
-- Fix object mutation, infinite recursion, and missing module address in multi-chain leaf hashes.
-- Fix BigInt gas scaling, merkle proof forwarding, entrypoint dispatch, and missing override fields.
-- Fix `CHAIN_ID` BigInt crash.
-- Fix gas overrides calculations.
-- Fix `formatSignaturesToUseroperationsSignatures` overrides and single-op case handling.
-- Fix `paymasterAndData` packing and signing when `PAYMASTER_SIG_MAGIC` is appended (v0.9).
-- Fix fractional percentage multipliers in `applyMultiplier`.
-- Fix normalize `paymasterMetadata` hex fields in `fetchSupportedERC20TokensAndPaymasterMetadata`.
-- Fix multi-chain sig account singleton forwarding, hash overrides, and type safety.
-- Fix constructor forwarding, timeout tracking, and unhandled promises.
-- Fix reverse proof order to match onchain verification order.
-- Fix WebAuthn passkeys v0.2.1 compatibility for custom contract addresses.
-- Fix token approval prepended before existing calls in SafeAccount multisend.
-- Fix `IAccountExecute.executeUserOp` callData rewriting for Tenderly simulation.
-- Fix multi-chain defaults in `formatSignaturesToUseroperationsSignatures`.
+Fixes listed here apply to APIs that already existed at 0.2.30. Bugs that were fixed within new-in-0.3.0 features during their pre-release development are not listed separately; those features are shipped in their final form as part of the "New Features" section.
+
+- **Gas estimation**: fixed gas overrides calculations, BigInt gas scaling, and handling of fractional percentage multipliers in `applyMultiplier`.
+- **SafeAccount multisend**: fixed a bug where token paymaster approvals were prepended after existing calls instead of before them.
+- **WebAuthn passkeys**: fixed compatibility with the v0.2.1 shared-signer contracts when using custom contract addresses.
+- **EIP-7702 utilities**: fixed `CHAIN_ID` BigInt crash in signing helpers and exposed `DEFAULT_DELEGATEE_ADDRESS` as a static property.
+- **Safe v0.3.0 account**: fixed `safeAccountSingleton` forwarding and added missing `webAuthnSignerProxyCreationCode` handling.
+- **CandidePaymaster**: fixed `paymasterMetadata` hex-field normalization in `fetchSupportedERC20TokensAndPaymasterMetadata`; fixed several instances of in-place mutation via aliasing on the user-passed UserOperation.
+- **Constructor forwarding and lifecycle**: fixed unhandled promises, timeout tracking, and constructor argument forwarding across pre-existing classes.
+- **Miscellaneous**: typo fixes in error messages, removal of unused imports and dead guards, unused `safeV06PrevModuleAddress` removed, chainId validation tightened in pre-existing helpers.
 
 ### Internal
 
-- Build system migrated from microbundle to tsdown.
-- Removed `isomorphic-unfetch` and `rimraf` dependencies.
+- Build system migrated from microbundle to tsdown. Output paths updated (see Breaking Changes).
+- `Simple7702Account` refactored into a `BaseSimple7702Account` pattern to enable the new `Simple7702AccountV09` subclass. No user-facing API changes on `Simple7702Account` itself.
+- Removed `isomorphic-unfetch` and `rimraf` dependencies; `rimraf` replaced with a cross-platform inline Node script.
 - Added CI workflow (`.github/workflows/ci.yml`) using yarn.
 - Added `SECURITY.md` with vulnerability reporting policy.
 - Added `prepare` script for GitHub-based installs.
+- Extensive JSDoc coverage added across public methods and types.

package/README.md

@@ -16,101 +16,64 @@ AbstractionKit is agnostic of:
 
 
 ## Features
-### Safe Accounts
-- Built on ERC-4337 account abstraction
-- Passkeys Authentication for secure, passwordless access
-- Social Recovery to regain access easily
-- Multisig Support
-- Allowance Management for controlled spending limits
 
-### Gas Abstraction with Paymasters
-- Full Gas Sponsorship for a seamless user experience
-- Support for ERC-20 Tokens as gas payment options
-
-### Bundler Support
-- Compatibility with standard ERC-4337 Bundler Methods
-
-### UserOperation Utilities
-- A complete toolkit to construct, sign, and send UserOperations, enabling smooth integration
+- **Safe Accounts** with passkey authentication, social recovery, multisig, and allowance management
+- **EIP-7702** support via `Calibur7702Account` and `Simple7702Account`
+- **Gas abstraction** with sponsored UserOperations and ERC-20 gas payment via `CandidePaymaster`
+- **Multichain signatures** via `SafeMultiChainSigAccountV1` (sign once, replay across chains)
+- **Bundler client** compatible with standard ERC-4337 methods
+- **EntryPoint v0.6, v0.7, v0.8, and v0.9** support with a version-safe account/UserOp mapping
 
 ## Docs
 
-For full detailed documentation visit our [docs page](https://docs.candide.dev/wallet/abstractionkit/introduction). 
+For full detailed documentation visit our [docs page](https://docs.candide.dev/wallet/abstractionkit/introduction).
 
 ## Installation
 
+Requires Node.js 18 or later.
+
 ```bash
 npm install abstractionkit
 ```
 
-## Quickstart
-
-### Which version to use?
-
-| Class | EntryPoint | When to use |
-|---|---|---|
-| `SafeAccountV0_3_0` | v0.7 | Recommended for new projects |
-| `SafeAccountV0_2_0` | v0.6 | Legacy support |
-
-### Safe Account
-
-AbstractionKit features the Safe Account. It uses the original Safe Singleton and adds ERC-4337 functionality using a fallback handler module. The contracts have been developed by the Safe Team. It has been audited by Ackee Blockchain. To learn more about the contracts and audits, visit [safe-global/safe-modules](https://github.com/safe-global/safe-modules/tree/main/modules/4337).
-
+### Upgrading to v0.3.0
 
-```typescript
-import { SafeAccountV0_3_0 as SafeAccount } from "abstractionkit";
+v0.3.0 is a major release. Two API changes are likely to break existing paymaster code:
 
-const ownerPublicAddress = "0xBdbc5FBC9cA8C3F514D073eC3de840Ac84FC6D31";
-const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]);
+- `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`.
 
-```
-Then you can consume account methods:
-```typescript
-const safeAddress = smartAccount.accountAddress;
-```
+See [CHANGELOG.md](./CHANGELOG.md) for the full list of new features, renames, type export changes, and fixes.
 
-### Bundler
+## Quickstart
 
-Initialize a Bundler with a bundler RPC url. Get an API key from the [dashboard](https://dashboard.candide.dev), or use the public endpoint (no key required).
-```typescript
-import { Bundler } from "abstractionkit";
+### Which account class to use?
 
-// Authenticated (get YOUR_API_KEY from https://dashboard.candide.dev)
-const bundlerRpc = "https://api.candide.dev/api/v3/11155111/YOUR_API_KEY";
+| Class | EntryPoint | Account Type | When to use |
+|---|---|---|---|
+| `SafeAccountV0_3_0` | EP v0.7 | Safe (counterfactual) | Recommended for most new projects |
+| `SafeAccountV1_5_0_M_0_3_0` | EP v0.7 | Safe v1.5.0 (counterfactual) | Safe v1.5.0 with EIP-7951 / Daimo P256 verifier for WebAuthn |
+| `SafeAccountV0_2_0` | EP v0.6 | Safe (counterfactual) | Legacy support for EntryPoint v0.6 |
+| `SafeMultiChainSigAccountV1` | EP v0.9 | Safe multichain | Sign once, replay across chains. |
+| `Calibur7702Account` | EP v0.8 | EIP-7702 (Uniswap Calibur) | Upgrade an EOA in place. Supports EOA, P256, and WebAuthn keys |
+| `Simple7702Account` | EP v0.8 | EIP-7702 (minimal) | Minimal reference EIP-7702 account |
+| `Simple7702AccountV09` | EP v0.9 | EIP-7702 (minimal, parallel paymaster) | EntryPoint v0.9 with parallel paymaster signing |
 
-// Or public (no key required)
-// const bundlerRpc = "https://api.candide.dev/public/v3/11155111";
+### Endpoints
 
-const bundler = new Bundler(bundlerRpc);
-```
-Then you can consume Bundler methods:
+Candide hosts both bundler and paymaster under the same base URL. Get an API key from the [dashboard](https://dashboard.candide.dev), or use the public endpoint (rate-limited, no key required).
 
 ```typescript
-const entrypointAddresses = await bundler.supportedEntryPoints();
-```
-
-### Paymaster
-Initialize a Candide Paymaster with your RPC url. Get an API key from the [dashboard](https://dashboard.candide.dev).
-```typescript
-import { CandidePaymaster } from "abstractionkit";
-
 // Authenticated
-const paymasterRpc = "https://api.candide.dev/api/v3/11155111/YOUR_API_KEY";
+const rpc = "https://api.candide.dev/api/v3/11155111/YOUR_API_KEY";
 
 // Or public (no key required)
-// const paymasterRpc = "https://api.candide.dev/public/v3/11155111";
-
-const paymaster = new CandidePaymaster(paymasterRpc);
-```
-Then you can consume Paymaster methods:
-
-```typescript
-const supportedERC20TokensAndPaymasterMetadata = await paymaster.fetchSupportedERC20TokensAndPaymasterMetadata();
+// const rpc = "https://api.candide.dev/public/v3/11155111";
 ```
 
 ## Recipes
 
-Copy-paste patterns for common tasks. Examples use `SafeAccountV0_3_0` (EntryPoint v0.7). For EntryPoint v0.6, replace with `SafeAccountV0_2_0`.
+Copy paste patterns for common tasks. Examples use `SafeAccountV0_3_0` (EntryPoint v0.7). For EntryPoint v0.6, replace with `SafeAccountV0_2_0`.
 
 ### Send ETH from a new Safe account
 
@@ -120,7 +83,7 @@ import { SafeAccountV0_3_0 } from "abstractionkit";
 const ownerPublicAddress = "0xOwner";
 const ownerPrivateKey = "0xPrivateKey";
 const nodeRpc = "https://rpc.example.com";
-const bundlerRpc = "https://bundler.example.com";
+const bundlerRpc = "https://api.candide.dev/api/v3/11155111/YOUR_API_KEY";
 const chainId = 11155111n; // Sepolia
 
 // Initialize new account (deploys on first UserOp)
@@ -169,7 +132,7 @@ const userOp = await smartAccount.createUserOperation(
 ```typescript
 import { SafeAccountV0_3_0, CandidePaymaster } from "abstractionkit";
 
-const paymaster = new CandidePaymaster("https://paymaster.example.com/rpc");
+const paymaster = new CandidePaymaster("https://api.candide.dev/api/v3/11155111/YOUR_API_KEY");
 
 // Create the UserOp first (without paymaster)
 const userOp = await smartAccount.createUserOperation(
@@ -178,10 +141,14 @@ const userOp = await smartAccount.createUserOperation(
   bundlerRpc,
 );
 
-// Sponsor it — sets paymaster fields and re-estimates gas
+// 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(
+  smartAccount,
   userOp,
   bundlerRpc,
+  sponsorshipPolicyId,
+  // overrides (optional, includes context for parallel signing)
 );
 
 // Sign and send as usual
@@ -194,7 +161,7 @@ const response = await smartAccount.sendUserOperation(sponsoredOp, bundlerRpc);
 ```typescript
 import { SafeAccountV0_3_0, CandidePaymaster } from "abstractionkit";
 
-const paymaster = new CandidePaymaster("https://paymaster.example.com/rpc");
+const paymaster = new CandidePaymaster("https://api.candide.dev/api/v3/11155111/YOUR_API_KEY");
 const gasTokenAddress = "0xERC20TokenAddress"; // must be supported by paymaster
 
 const userOp = await smartAccount.createUserOperation(
@@ -203,24 +170,48 @@ const userOp = await smartAccount.createUserOperation(
   bundlerRpc,
 );
 
-// Automatically prepends token approval + sets paymaster fields
+// 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(
   smartAccount,
   userOp,
   gasTokenAddress,
   bundlerRpc,
+  // overrides (optional)
 );
 
 tokenOp.signature = smartAccount.signUserOperation(tokenOp, [ownerPrivateKey], chainId);
 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.
+
+```typescript
+const [sponsoredOp] = await paymaster.createSponsorPaymasterUserOperation(
+  smartAccount,
+  userOp,
+  bundlerRpc,
+  sponsorshipPolicyId,
+  {
+    context: {
+      // For EntryPoint v0.9 parallel signing flows:
+      // signingPhase: "commit" | "finalize",
+    },
+    // gas overrides also live here:
+    callGasLimitPercentageMultiplier: 110,
+  },
+);
+```
+
 ### Batch multiple transactions
 
 ```typescript
 import { SafeAccountV0_3_0, MetaTransaction } from "abstractionkit";
 
-// Pass an array of MetaTransactions — automatically encoded via MultiSend
+// Pass an array of MetaTransactions. Automatically encoded via MultiSend.
 const transactions: MetaTransaction[] = [
   { to: "0xRecipientA", value: 1000000000000000n, data: "0x" },
   { to: "0xRecipientB", value: 2000000000000000n, data: "0x" },
@@ -248,6 +239,98 @@ const newAccount = SafeAccountV0_3_0.initializeNewAccount(["0xOwnerAddress"]);
 // First UserOp will deploy it automatically
 ```
 
+### 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.
+
+```typescript
+import {
+  Calibur7702Account,
+  createAndSignEip7702DelegationAuthorization,
+} from "abstractionkit";
+
+const eoaAddress = "0xYourEOA";
+const privateKey = "0xYourPrivateKey";
+const nodeRpc = "https://rpc.example.com";
+const bundlerRpc = "https://api.candide.dev/api/v3/11155111/YOUR_API_KEY";
+const chainId = 11155111n;
+
+// The EOA address becomes the smart account address after delegation.
+const account = new Calibur7702Account(eoaAddress);
+
+// Create UserOp with EIP-7702 delegation (only required the first time).
+const userOp = await account.createUserOperation(
+  [{ to: "0xRecipient", value: 1000000000000000n, data: "0x" }],
+  nodeRpc,
+  bundlerRpc,
+  { eip7702Auth: { chainId } },
+);
+
+// Sign the delegation authorization.
+userOp.eip7702Auth = createAndSignEip7702DelegationAuthorization(
+  BigInt(userOp.eip7702Auth.chainId),
+  userOp.eip7702Auth.address,
+  BigInt(userOp.eip7702Auth.nonce),
+  privateKey,
+);
+
+// Sign and send.
+userOp.signature = account.signUserOperation(userOp, privateKey, chainId);
+const response = await account.sendUserOperation(userOp, bundlerRpc);
+const receipt = await response.included();
+```
+
+After the first UserOp deploys the delegation, subsequent UserOps no longer need `eip7702Auth`. Use `getDelegatedAddress(eoaAddress, nodeRpc)` to check delegation status.
+
+### Calibur 7702: register a WebAuthn passkey
+
+```typescript
+import { Calibur7702Account } from "abstractionkit";
+
+// Build a P256 key from the WebAuthn public key coordinates.
+const webAuthnKey = Calibur7702Account.createWebAuthnP256Key(pubKeyX, pubKeyY);
+const keyHash = Calibur7702Account.getKeyHash(webAuthnKey);
+
+// Register with a 1-year expiration.
+const registerTxs = Calibur7702Account.createRegisterKeyMetaTransactions(
+  webAuthnKey,
+  { expiration: Math.floor(Date.now() / 1000) + 86400 * 365 },
+);
+
+const userOp = await account.createUserOperation(registerTxs, nodeRpc, bundlerRpc);
+userOp.signature = account.signUserOperation(userOp, privateKey, chainId);
+const response = await account.sendUserOperation(userOp, bundlerRpc);
+```
+
+### Calibur 7702: sign a UserOp with a registered passkey
+
+```typescript
+import { Calibur7702Account, createUserOperationHash } from "abstractionkit";
+
+// Use a WebAuthn dummy signature for accurate gas estimation.
+const dummySig = Calibur7702Account.createDummyWebAuthnSignature(keyHash);
+
+const userOp = await account.createUserOperation(
+  [{ to: "0xRecipient", value: 0n, data: "0x" }],
+  nodeRpc,
+  bundlerRpc,
+  { dummySignature: dummySig },
+);
+
+// Compute the hash, sign with the passkey off-chain, then format the signature.
+const userOpHash = createUserOperationHash(userOp, entryPointAddress, chainId);
+userOp.signature = account.formatWebAuthnSignature(keyHash, {
+  authenticatorData,
+  clientDataJSON,
+  challengeIndex,
+  typeIndex,
+  r,
+  s, // P256 signature components
+});
+
+const response = await account.sendUserOperation(userOp, bundlerRpc);
+```
+
 ### Common error codes and solutions
 
 | Error Code | Meaning | Fix |
@@ -286,3 +369,5 @@ MIT
 
 * <a href='https://eips.ethereum.org/EIPS/eip-4337'>EIP-4337: Account Abstraction via Entry Point Contract specification </a>
 * <a href='https://safe.global/'>Safe Accounts, Modules, and SGP</a>
+* <a href='https://github.com/Uniswap/calibur'>Uniswap Calibur Account</a>
+