diff --git a/content/00.zksync-network/30.unique-features/30.zksync-sso/00.index.md b/content/00.zksync-network/30.unique-features/30.zksync-sso/00.index.md index a73a1d360..0e6188c5a 100644 --- a/content/00.zksync-network/30.unique-features/30.zksync-sso/00.index.md +++ b/content/00.zksync-network/30.unique-features/30.zksync-sso/00.index.md @@ -53,5 +53,5 @@ The [ZKsync SSO SDK](https://github.com/matter-labs/zksync-sso) is open-source and available on GitHub under the MIT License. Feel free to contribute, report issues, or suggest new features to help us improve the tool for everyone. -The [ZKsync SSO Smart Contracts](https://github.com/matter-labs/zksync-sso-clave-contracts) -is a fork of [Clave](https://github.com/getclave/clave-contracts) smart contracts, open-source and available on GitHub under the GNU License. +The [ZKsync SSO Smart Contracts](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts) +are open-source and available on GitHub under the MIT License. diff --git a/content/00.zksync-network/30.unique-features/30.zksync-sso/10.architecture.md b/content/00.zksync-network/30.unique-features/30.zksync-sso/10.architecture.md index 68d6ecaf2..71776022d 100644 --- a/content/00.zksync-network/30.unique-features/30.zksync-sso/10.architecture.md +++ b/content/00.zksync-network/30.unique-features/30.zksync-sso/10.architecture.md @@ -68,23 +68,67 @@ itself handles passkey creation and management. Each platform implements this th - Supports WebAuthn-compatible domain association - Enables cross-context passkey usage between app and browser +## ERC-4337 Account Abstraction + +ZKsync SSO leverages [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) to provide native account abstraction capabilities, +enabling gasless transactions, batched operations, and advanced account features without requiring protocol-level changes. + +### How It Works + +**EntryPoint Contract:** The system uses EntryPoint v0.8 deployed at `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108`. +This contract serves as the central hub for processing UserOperations (account abstraction transactions). + +**UserOperation Flow:** + +1. User initiates an action (e.g., transaction, passkey creation) +2. SDK packages the action as a UserOperation with gas estimates and paymaster data +3. UserOperation is sent to a bundler service (Pimlico/Alto compatible) +4. Bundler validates, simulates, and submits the UserOperation to the EntryPoint +5. EntryPoint executes the operation through the user's modular smart account +6. Transaction is confirmed on-chain + +**Bundler Integration:** The SDK works with ERC-4337 bundler services that collect and submit UserOperations. +For production use, you can use hosted bundler services like Pimlico or Alchemy. + +### Local Development Setup + +For local development and testing, you can run your own bundler and node: + +```bash +# Start local Anvil node (in terminal 1) +pnpm run anvil + +# Start bundler with proxy (in terminal 2) +pnpm run bundler:with-proxy +``` + +This sets up a complete local ERC-4337 environment with: + +- Local Ethereum node at `http://localhost:8545` +- Bundler API at `http://localhost:4337` +- EntryPoint v0.8 contract deployed + +After starting the local environment, deploy the SSO contracts from the `packages/erc-4337-contracts` directory. + ## Smart Contracts A set of smart contracts deployed on the ZKsync chain manage accounts, passkeys, and sessions. These contracts form the on-chain backbone of the ZKsync SSO system. -- [**SsoAccount.**](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/main/src/SsoAccount.sol) -Implements the ZKSync modular account standard, allowing for extensible smart account functionalities. -- [**AAFactory.**](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/main/src/AAFactory.sol) -A factory contract used to deploy new user accounts on the chain efficiently. -- [**SessionKeyValidator.**](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/main/src/validators/SessionKeyValidator.sol) +- [**ModularSmartAccount.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/ModularSmartAccount.sol) +Implements the ERC-4337 and ERC-7579 modular account standard, allowing for extensible smart account functionalities. +- [**MSAFactory.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/MSAFactory.sol) +A factory contract used to deploy new modular smart accounts on the chain efficiently. +- [**SessionKeyValidator.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/validators/SessionKeyValidator.sol) Manages session keys with specific spend limits, enhancing security by restricting their scope and usage. -- [**WebAuthnModule.**](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/main/src/validators/WebAuthValidator.sol) +- [**WebAuthnValidator.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/validators/WebAuthnValidator.sol) Handles authentication using WebAuthn standards, enabling passkey-based authentication methods. -- [**Account Proxies.**](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/main/src/AccountProxy.sol) -Each user account is an upgradable proxy contract for the ZKsync smart-sign-on implemention. +- [**EOAKeyValidator.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/validators/EOAKeyValidator.sol) +Enables account control via traditional ECDSA private keys for backwards compatibility and testing. +- [**GuardianExecutor.**](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/executors/GuardianExecutor.sol) +Handles guardian-based account recovery with timelock mechanisms. -The deployed contract addresses for ZKsync Sepolia testnet are available in the [ZKsync SSO repository](https://github.com/matter-labs/zksync-sso/blob/main/packages/auth-server/stores/era-sepolia.json). +The deployed contract addresses for ZKsync Sepolia testnet will be available soon (addresses TBD). ## Diagram diff --git a/content/00.zksync-network/30.unique-features/30.zksync-sso/27.accounts.md b/content/00.zksync-network/30.unique-features/30.zksync-sso/27.accounts.md index 56216cea6..084583c26 100644 --- a/content/00.zksync-network/30.unique-features/30.zksync-sso/27.accounts.md +++ b/content/00.zksync-network/30.unique-features/30.zksync-sso/27.accounts.md @@ -14,11 +14,11 @@ and installed by default for every new account deployment. Modules can be added or removed from the account, without having to migrate or upgrade the whole account. You can contribute to the smart account modules available to ZKsync SSO users by -submitting a PR to the [`zksync-sso-clave-contracts`](https://github.com/matter-labs/zksync-sso-clave-contracts) repository. +submitting a PR to the [`erc-4337-contracts`](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts) repository. Modules must implement the -[`IModuleValidator`](https://github.com/matter-labs/zksync-sso-clave-contracts/tree/main/src/interfaces/IModuleValidator.sol) interface. -The current implemented modules can be found in the [`validators` folder](https://github.com/matter-labs/zksync-sso-clave-contracts/tree/main/src/validators). +[`IERC7579Validator`](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/interfaces/IERC7579Validator.sol) interface. +The current implemented modules can be found in the [`validators` folder](https://github.com/matter-labs/zksync-sso/tree/main/packages/erc-4337-contracts/src/validators). Looking for inspiration? Take a look at the modules already created for [ERC-7579](https://erc7579.com/modules) diff --git a/content/00.zksync-network/30.unique-features/30.zksync-sso/28.account-recovery.md b/content/00.zksync-network/30.unique-features/30.zksync-sso/28.account-recovery.md index 9208aa760..ff8e8f5cd 100644 --- a/content/00.zksync-network/30.unique-features/30.zksync-sso/28.account-recovery.md +++ b/content/00.zksync-network/30.unique-features/30.zksync-sso/28.account-recovery.md @@ -146,8 +146,3 @@ These passkeys could be stored via FIDO device or a different online passkey pro Users can register a new device by adding a new passkey to their account. This typically involves verifying their identity on the new device, after which the new passkey is securely associated with their account. - -**Recovery via OAuth 2.0** - -OAuth Recovery ERC-7579 module enables users to set up an account recovery through OAuth tokens associated with their existing Web2 logins like -Gmail, Facebook, or X (formerly Twitter). This allows users to regain access by logging in with their familiar social media or email accounts. diff --git a/content/00.zksync-network/30.unique-features/30.zksync-sso/5.getting-started.md b/content/00.zksync-network/30.unique-features/30.zksync-sso/5.getting-started.md index bfe90f8dc..15a731b6a 100644 --- a/content/00.zksync-network/30.unique-features/30.zksync-sso/5.getting-started.md +++ b/content/00.zksync-network/30.unique-features/30.zksync-sso/5.getting-started.md @@ -19,35 +19,35 @@ Just 2 steps: ::code-group ```bash [npm] - npm i zksync-sso + npm i zksync-sso-4337 # optional peer dependencies - npm i @simplewebauthn/browser @simplewebauthn/server @wagmi/core + npm i @simplewebauthn/browser @simplewebauthn/server @wagmi/core viem ``` ```bash [yarn] - yarn add zksync-sso + yarn add zksync-sso-4337 # optional peer dependencies - yarn add @simplewebauthn/browser @simplewebauthn/server @wagmi/core + yarn add @simplewebauthn/browser @simplewebauthn/server @wagmi/core viem ``` ```bash [pnpm] - pnpm add zksync-sso + pnpm add zksync-sso-4337 # optional peer dependencies - pnpm add @simplewebauthn/browser @simplewebauthn/server @wagmi/core + pnpm add @simplewebauthn/browser @simplewebauthn/server @wagmi/core viem ``` ```bash [bun] - bun add zksync-sso + bun add zksync-sso-4337 # optional peer dependencies - bun add @simplewebauthn/browser @simplewebauthn/server @wagmi/core + bun add @simplewebauthn/browser @simplewebauthn/server @wagmi/core viem ``` :: ::callout{icon="i-heroicons-information-circle" color="blue"} Note on peer dependencies: - - `@wagmi/core` is required when using ZKsync SSO connector (`zksyncSsoConnector`) in your app. - - `@simplewebauthn/browser` and `@simplewebauthn/server` are required when SDK passkey functionality directly inside your app. + - `@wagmi/core` and `viem` are required when using ZKsync SSO connector (`zksyncSsoConnector`) in your app. + - `@simplewebauthn/browser` and `@simplewebauthn/server` are required when using SDK passkey functionality directly inside your app. :: 2. Add ZKsync SSO connector to your app. diff --git a/cspell-config/cspell-misc.txt b/cspell-config/cspell-misc.txt index 5c0a15fb7..aea21ac53 100644 --- a/cspell-config/cspell-misc.txt +++ b/cspell-config/cspell-misc.txt @@ -15,6 +15,7 @@ immediates Immunefi initializable Initializable +Pimlico Transak Lukka mathbb diff --git a/examples/sso/package.json b/examples/sso/package.json index 8f6e9beee..cf005a9f4 100644 --- a/examples/sso/package.json +++ b/examples/sso/package.json @@ -19,6 +19,6 @@ "@simplewebauthn/server": "^13.1.2", "viem": "^2.33.1", "wagmi": "^2.16.0", - "zksync-sso": "^0.3.3" + "zksync-sso-4337": "latest" } } diff --git a/examples/sso/src/deployModularAccount.ts b/examples/sso/src/deployModularAccount.ts index 5bf7493ac..7c4c31a3d 100644 --- a/examples/sso/src/deployModularAccount.ts +++ b/examples/sso/src/deployModularAccount.ts @@ -1,8 +1,8 @@ import { createWalletClient, http, type Address } from 'viem'; import { privateKeyToAccount } from 'viem/accounts'; import { zksyncSepoliaTestnet } from 'viem/zksync'; -import { deployModularAccount } from 'zksync-sso/client'; -import type { RegisterNewPasskeyReturnType } from 'zksync-sso/client/passkey'; +import { deployModularAccount } from 'zksync-sso-4337/client'; +import type { RegisterNewPasskeyReturnType } from 'zksync-sso-4337/client/passkey'; export async function deployAccountFromPasskey(publicPassKey: RegisterNewPasskeyReturnType) { const deployerKey = '0x_YOUR_PRIVATE_KEY'; // Replace with your deployer's private key diff --git a/examples/sso/src/ecdsa.ts b/examples/sso/src/ecdsa.ts index 4ceaa1611..3336a7466 100644 --- a/examples/sso/src/ecdsa.ts +++ b/examples/sso/src/ecdsa.ts @@ -2,7 +2,7 @@ import type { Address } from 'viem'; import { createWalletClient, http } from 'viem'; import { privateKeyToAccount } from 'viem/accounts'; import { zksyncSepoliaTestnet } from 'viem/chains'; -import { createZksyncEcdsaClient } from 'zksync-sso/client/ecdsa'; +import { createZksyncEcdsaClient } from 'zksync-sso-4337/client/ecdsa'; const privateKey = '0x_YOUR_PRIVATE_KEY'; // Replace with an owner account's private key diff --git a/examples/sso/src/registerPasskey.ts b/examples/sso/src/registerPasskey.ts index 7ef8c7979..c46b92b9b 100644 --- a/examples/sso/src/registerPasskey.ts +++ b/examples/sso/src/registerPasskey.ts @@ -1,4 +1,4 @@ -import { registerNewPasskey, type RegisterNewPasskeyReturnType } from 'zksync-sso/client/passkey'; +import { registerNewPasskey, type RegisterNewPasskeyReturnType } from 'zksync-sso-4337/client/passkey'; export async function registerPasskey() { const newPasskey: RegisterNewPasskeyReturnType = await registerNewPasskey({ diff --git a/examples/sso/src/reownAppkit.ts b/examples/sso/src/reownAppkit.ts index 10d12df47..371fbcea3 100644 --- a/examples/sso/src/reownAppkit.ts +++ b/examples/sso/src/reownAppkit.ts @@ -1,4 +1,4 @@ -import { zksyncSsoConnector, callPolicy } from 'zksync-sso/connector'; +import { zksyncSsoConnector, callPolicy } from 'zksync-sso-4337/connector'; import { zksyncSepoliaTestnet } from 'viem/chains'; import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'; import { erc20Abi, parseEther, parseUnits } from 'viem'; diff --git a/examples/sso/src/wagmi.ts b/examples/sso/src/wagmi.ts index 8bee5830f..4834e765c 100644 --- a/examples/sso/src/wagmi.ts +++ b/examples/sso/src/wagmi.ts @@ -1,4 +1,4 @@ -import { zksyncSsoConnector, callPolicy } from 'zksync-sso/connector'; +import { zksyncSsoConnector, callPolicy } from 'zksync-sso-4337/connector'; import { zksyncSepoliaTestnet } from 'viem/chains'; import { createConfig, connect, disconnect } from '@wagmi/core'; import { erc20Abi, http, parseEther, parseUnits } from 'viem';