Getting Started

Integrating ZKsync SSO into your app requires minimal amount of changes.

Quick Start

Web

Just 2 steps:

1. Install the ZKsync SSO SDK package.
   npmyarnpnpmbun

   npm i zksync-sso
   

2. Add ZKsync SSO connector to your app.
   wagmiweb3modal

   import { zksyncSsoConnector, callPolicy } from "zksync-sso/connector";
   import { zksyncSepoliaTestnet } from "viem/chains";
   import { createConfig, connect } from "@wagmi/core";
   import { erc20Abi } from "viem";
   
   const ssoConnector = zksyncSsoConnector({
     // Optional session configuration, if omitted user will have to sign every transaction via Auth Server
     session: {
       expiry: "1 day",
   
       // Allow up to 0.1 ETH to be spend in gas fees
       feeLimit: parseEther("0.1"),
   
       transfers: [
         // Allow ETH transfers of up to 0.1 ETH to specific address
         {
           to: "0x188bd99cd7D4d78d4E605Aeea12C17B32CC3135A",
           valueLimit: parseEther("0.1"),
         },
       ],
   
       // Allow calling specific smart contracts (e.g. ERC20 transfer):
       contractCalls: [
         callPolicy({
           address: "0xa1cf087DB965Ab02Fb3CFaCe1f5c63935815f044",
           abi: erc20Abi,
           functionName: "transfer",
           constraints: [
             // Only allow transfers to this address. Or any address if omitted
             {
               index: 0, // First argument of erc20 transfer function, recipient address
               value: "0x6cC8cf7f6b488C58AA909B77E6e65c631c204784",
             },
   
             // Allow transfering up to 0.2 tokens per hour
             // until the session expires
             {
               index: 1,
               limit: {
                 limit: parseUnits("0.2", TOKEN.decimals),
                 period: "1 hour",
               },
             },
           ],
         }),
       ],
     },
     // Optional: Receive notifications about session state changes
     onSessionStateChange: ({ state, address, chainId }) => {
       console.log(`Session state for address ${address} changed: ${state.type} - ${state.message}`);
   
       // Use this to notify users and restart the session if needed
       // - Session expired: state.type === 'session_expired'
       // - Session inactive (e.g. was revoked): state.type === 'session_inactive'
     },
   });
   
   const wagmiConfig = createConfig({
     connectors: [ssoConnector],
     ..., // your wagmi config https://wagmi.sh/core/api/createConfig
   });
   
   const connectWithSSO = () => {
     connect(wagmiConfig, {
       connector: ssoConnector,
       chainId: zksyncSepoliaTestnet.id, // or another chain id that has SSO support
     });
   };
   

React Native

1. Install the ZKsync SSO SDK package.
   npmyarn

   npm i react-native-zksync-sso
   

2. Configure platform-specific settings:
   Make sure your application is set up to create passkeys by following the platform-specific guidelines:
   • iOS: Refer to Apple's documentation for setting up passkey support in your iOS app.
   • Android: Refer to Google's documentation for implementing passkey support in your Android app.
3. Set up the SDK and register an account

   import sdk from 'react-native-zksync-sso';
   
   const config = {
     contracts: {
       accountFactory: "0x...",
       passkey: "0x...",
       session: "0x...",
       accountPaymaster: "0x..."
     },
     nodeUrl: "https://...",
     deployWallet: {
       privateKeyHex: "0x..."
     }
   };
   
   const accountInfo = {
     name: "Jane Doe",
     userID: "jdoe@example.com"
   };
   
   const rpId = sdk.utils.createRpId(
     "example.com",
     "android:apk-key-hash:your-app-key-hash"
   );
   
   const challenge = sdk.utils.generateRandomChallenge();
   
   const deployedAccount = await sdk.register.registerAccountWithUniqueId(
     {
       name: accountInfo.name,
       userID: accountInfo.userID,
       rp: {
         name: "example.com",
         id: rpId
       }
     },
     challenge,
     config
   );
   

4. Send a transaction

   import sdk from 'react-native-zksync-sso';
   import { AccountClient } from 'react-native-zksync-sso';
   
   const accountClient = new AccountClient(
     {
       address: deployedAccount.address,
       uniqueAccountId: deployedAccount.uniqueAccountId
     },
     rpId,
     config
   );
   
   const transaction = {
     to: "0x...", // Recipient address
     value: 1000, // Amount in wei
     from: deployedAccount.address,
     input: undefined // Optional: contract call data
   };
   
   const receipt = await accountClient.sendTransaction(tx);
   

Interfaces

You can find the full list of options and their descriptions in the Interfaces section.

Examples

We provide several example apps to help you get started quickly. Find them on our GitHub repository.