feat(sdk): session state checks and tx verifier (#140)

Author: JackHamer09

README.md

@@ -19,7 +19,7 @@ simplifying user authentication, session management, and transaction processing.
 - 🔑 Passkey authentication (no seed phrases)
 - ⏰ Sessions w/ easy configuration and management
 - 💰 Integrated paymaster support
-- ❤️‍🩹 Account recovery _(Coming Soon)_
+- ❤️‍🩹 Account recovery
 - 💻 Simple SDKs : JavaScript, iOS/Android _(Coming Soon)_
 - 🤝 Open-source authentication server
 - 🎓 Examples to get started quickly
@@ -82,6 +82,15 @@ const ssoConnector = zksyncSsoConnector({
          }),
       ],
    },
+
+   // 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({

packages/sdk/README.md

@@ -17,7 +17,7 @@ simplifying user authentication, session management, and transaction processing.
 - 🔑 Passkey authentication (no seed phrases)
 - ⏰ Sessions w/ easy configuration and management
 - 💰 Integrated paymaster support
-- ❤️‍🩹 Account recovery _(Coming Soon)_
+- ❤️‍🩹 Account recovery
 - 💻 Simple SDKs : JavaScript, iOS/Android _(Coming Soon)_
 - 🤝 Open-source authentication server
 - 🎓 Examples to get started quickly
@@ -79,7 +79,16 @@ const ssoConnector = zksyncSsoConnector({
         ],
       }),
     ],
-   },
+  },
+
+  // 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): eve.state.type === 'session_inactive'
+  },
 });
 
 const wagmiConfig = createConfig({

packages/sdk/src/client-auth-server/Signer.ts

@@ -4,6 +4,7 @@ import type { TransactionRequestEIP712 } from "viem/chains";
 import { createZksyncSessionClient, type ZksyncSsoSessionClient } from "../client/index.js";
 import type { Communicator } from "../communicator/index.js";
 import { type CustomPaymasterHandler, getTransactionWithPaymasterData } from "../paymaster/index.js";
+import type { SessionStateEvent } from "../utils/session.js";
 import { StorageItem } from "../utils/storage.js";
 import type { AppMetadata, RequestArguments } from "./interface.js";
 import type { AuthServerRpcSchema, ExtractParams, ExtractReturnType, Method, RPCRequestMessage, RPCResponseMessage, RpcSchema } from "./rpc.js";
@@ -41,6 +42,7 @@ type SignerConstructorParams = {
   transports?: Record<number, Transport>;
   session?: () => SessionPreferences | Promise<SessionPreferences>;
   paymasterHandler?: CustomPaymasterHandler;
+  onSessionStateChange?: (event: { address: Address; chainId: number; state: SessionStateEvent }) => void;
 };
 
 type ChainsInfo = ExtractReturnType<"eth_requestAccounts", AuthServerRpcSchema>["chainsInfo"];
@@ -53,12 +55,13 @@ export class Signer implements SignerInterface {
   private readonly transports: Record<number, Transport> = {};
   private readonly sessionParameters?: () => (SessionPreferences | Promise<SessionPreferences>);
   private readonly paymasterHandler?: CustomPaymasterHandler;
+  private readonly onSessionStateChange?: SignerConstructorParams["onSessionStateChange"];
 
   private _account: StorageItem<Account | null>;
   private _chainsInfo = new StorageItem<ChainsInfo>(StorageItem.scopedStorageKey("chainsInfo"), []);
   private client: { instance: ZksyncSsoSessionClient; type: "session" } | { instance: WalletClient; type: "auth-server" } | undefined;
 
-  constructor({ metadata, communicator, updateListener, session, chains, transports, paymasterHandler }: SignerConstructorParams) {
+  constructor({ metadata, communicator, updateListener, session, chains, transports, paymasterHandler, onSessionStateChange }: SignerConstructorParams) {
     if (!chains.length) throw new Error("At least one chain must be included in the config");
 
     this.getMetadata = metadata;
@@ -68,6 +71,7 @@ export class Signer implements SignerInterface {
     this.chains = chains;
     this.transports = transports || {};
     this.paymasterHandler = paymasterHandler;
+    this.onSessionStateChange = onSessionStateChange;
 
     this._account = new StorageItem<Account | null>(StorageItem.scopedStorageKey("account"), null, {
       onChange: (newValue) => {
@@ -142,6 +146,14 @@ export class Signer implements SignerInterface {
           chain,
           transport: this.transports[chain.id] || http(),
           paymasterHandler: this.paymasterHandler,
+          onSessionStateChange: (event: SessionStateEvent) => {
+            if (!this.onSessionStateChange) return;
+            this.onSessionStateChange({
+              state: event,
+              address: this.account!.address,
+              chainId: chain.id,
+            });
+          },
         }),
       };
     } else {

packages/sdk/src/client-auth-server/WalletProvider.ts

@@ -6,6 +6,7 @@ import { PopupCommunicator } from "../communicator/PopupCommunicator.js";
 import { serializeError, standardErrors } from "../errors/index.js";
 import type { CustomPaymasterHandler } from "../paymaster/index.js";
 import { getFavicon, getWebsiteName } from "../utils/helpers.js";
+import type { SessionStateEvent } from "../utils/session.js";
 import type {
   AppMetadata,
   ProviderInterface,
@@ -24,13 +25,14 @@ export type WalletProviderConstructorOptions = {
   session?: SessionPreferences | (() => SessionPreferences | Promise<SessionPreferences>);
   authServerUrl?: string;
   paymasterHandler?: CustomPaymasterHandler;
+  onSessionStateChange?: (state: { address: Address; chainId: number; state: SessionStateEvent }) => void;
 };
 
 export class WalletProvider extends EventEmitter implements ProviderInterface {
   readonly isZksyncSso = true;
   private signer: Signer;
 
-  constructor({ metadata, chains, transports, session, authServerUrl, paymasterHandler }: WalletProviderConstructorOptions) {
+  constructor({ metadata, chains, transports, session, authServerUrl, paymasterHandler, onSessionStateChange }: WalletProviderConstructorOptions) {
     super();
     const communicator = new PopupCommunicator(authServerUrl || DEFAULT_AUTH_SERVER_URL);
     this.signer = new Signer({
@@ -45,6 +47,7 @@ export class WalletProvider extends EventEmitter implements ProviderInterface {
       transports,
       session: typeof session === "object" ? () => session : session,
       paymasterHandler,
+      onSessionStateChange,
     });
   }
 

packages/sdk/src/client/session/actions/session.ts

@@ -1,11 +1,12 @@
 import { type Account, type Address, type Chain, type Client, encodeFunctionData, type Hash, type Hex, type Prettify, type TransactionReceipt, type Transport } from "viem";
-import { waitForTransactionReceipt } from "viem/actions";
+import { readContract, waitForTransactionReceipt } from "viem/actions";
 import { getGeneralPaymasterInput, sendTransaction } from "viem/zksync";
 
 import { SessionKeyValidatorAbi } from "../../../abi/SessionKeyValidator.js";
 import { type CustomPaymasterHandler, getTransactionWithPaymasterData } from "../../../paymaster/index.js";
 import { noThrow } from "../../../utils/helpers.js";
-import type { SessionConfig } from "../../../utils/session.js";
+import type { SessionConfig, SessionState, SessionStateEventCallback } from "../../../utils/session.js";
+import { SessionEventType, SessionStatus } from "../../../utils/session.js";
 
 export type CreateSessionArgs = {
   sessionConfig: SessionConfig;
@@ -119,3 +120,85 @@ export const revokeSession = async <
     transactionReceipt,
   };
 };
+
+export type GetSessionStateArgs = {
+  account: Address;
+  sessionConfig: SessionConfig;
+  contracts: {
+    session: Address; // session module
+  };
+};
+export type GetSessionStateReturnType = {
+  sessionState: SessionState;
+};
+export const getSessionState = async <
+  transport extends Transport,
+  chain extends Chain,
+>(client: Client<transport, chain>, args: Prettify<GetSessionStateArgs>): Promise<Prettify<GetSessionStateReturnType>> => {
+  const sessionState = await readContract(client, {
+    address: args.contracts.session,
+    abi: SessionKeyValidatorAbi,
+    functionName: "sessionState",
+    args: [args.account, args.sessionConfig],
+  });
+
+  return {
+    sessionState: sessionState as SessionState,
+  };
+};
+
+export type CheckSessionStateArgs = {
+  sessionConfig: SessionConfig;
+  sessionState: SessionState;
+  onSessionStateChange: SessionStateEventCallback;
+  sessionNotifyTimeout?: NodeJS.Timeout;
+};
+export type CheckSessionStateReturnType = {
+  newTimeout?: NodeJS.Timeout;
+};
+
+/**
+ * Checks the current session state and sets up expiry notification.
+ * This function will trigger the callback with the session state.
+ */
+export const sessionStateNotify = (args: Prettify<CheckSessionStateArgs>): CheckSessionStateReturnType => {
+  // Generate a session ID for tracking timeouts
+  const { sessionState } = args;
+  const now = BigInt(Math.floor(Date.now() / 1000));
+
+  // Check session status
+  if (sessionState.status === SessionStatus.NotInitialized) { // Not initialized
+    args.onSessionStateChange({
+      type: SessionEventType.Inactive,
+      message: "Session is not initialized",
+    });
+  } else if (sessionState.status === SessionStatus.Closed) { // Closed/Revoked
+    args.onSessionStateChange({
+      type: SessionEventType.Revoked,
+      message: "Session has been revoked",
+    });
+  } else if (args.sessionConfig.expiresAt <= now) {
+    // Session has expired
+    args.onSessionStateChange({
+      type: SessionEventType.Expired,
+      message: "Session has expired",
+    });
+  } else {
+    // Session is active, set up expiry notification
+    const timeToExpiry = Number(args.sessionConfig.expiresAt - now) * 1000;
+    if (args.sessionNotifyTimeout) {
+      clearTimeout(args.sessionNotifyTimeout);
+    }
+    const newTimeout = setTimeout(() => {
+      args.onSessionStateChange({
+        type: SessionEventType.Expired,
+        message: "Session has expired",
+      });
+    }, timeToExpiry);
+    return {
+      newTimeout,
+    };
+  }
+
+  return {};
+};

packages/sdk/src/client/session/client.ts

@@ -4,8 +4,9 @@ import { zksyncInMemoryNode } from "viem/chains";
 
 import type { CustomPaymasterHandler } from "../../paymaster/index.js";
 import { encodeSessionTx } from "../../utils/encoding.js";
-import type { SessionConfig } from "../../utils/session.js";
+import type { SessionConfig, SessionStateEventCallback } from "../../utils/session.js";
 import { toSessionAccount } from "./account.js";
+import { getSessionState, sessionStateNotify } from "./actions/session.js";
 import { publicActionsRewrite } from "./decorators/publicActionsRewrite.js";
 import { type ZksyncSsoWalletActions, zksyncSsoWalletActions } from "./decorators/wallet.js";
 
@@ -90,10 +91,31 @@ export function createZksyncSessionClient<
       sessionConfig: parameters.sessionConfig,
       contracts: parameters.contracts,
       paymasterHandler: parameters.paymasterHandler,
+      onSessionStateChange: parameters.onSessionStateChange,
+      _sessionNotifyTimeout: undefined as NodeJS.Timeout | undefined,
     }))
     .extend(publicActions)
     .extend(publicActionsRewrite)
     .extend(zksyncSsoWalletActions);
+
+  // Check session state on initialization if callback is provided
+  if (client.onSessionStateChange) {
+    getSessionState(client, {
+      account: client.account.address,
+      sessionConfig: client.sessionConfig,
+      contracts: client.contracts,
+    }).then(({ sessionState }) => {
+      sessionStateNotify({
+        sessionConfig: client.sessionConfig,
+        sessionState,
+        onSessionStateChange: client.onSessionStateChange!,
+        sessionNotifyTimeout: client._sessionNotifyTimeout,
+      });
+    }).catch((error) => {
+      console.error("Failed to get session state on initialization:", error);
+    });
+  }
+
   return client;
 }
 
@@ -105,6 +127,8 @@ type ZksyncSsoSessionData = {
   sessionConfig: SessionConfig;
   contracts: SessionRequiredContracts;
   paymasterHandler?: CustomPaymasterHandler;
+  onSessionStateChange?: SessionStateEventCallback;
+  _sessionNotifyTimeout?: NodeJS.Timeout;
 };
 
 export type ClientWithZksyncSsoSessionData<
@@ -143,4 +167,5 @@ export interface ZksyncSsoSessionClientConfig<
   key?: string;
   name?: string;
   paymasterHandler?: CustomPaymasterHandler;
+  onSessionStateChange?: SessionStateEventCallback;
 }

packages/sdk/src/client/session/decorators/wallet.ts

@@ -4,20 +4,51 @@ import {
   type Transport, type WalletActions } from "viem";
 import {
   deployContract, getAddresses, getCallsStatus, getCapabilities, getChainId, prepareAuthorization, sendCalls, sendRawTransaction,
-  showCallsStatus,
-  signAuthorization,
-  signMessage, signTypedData, waitForCallsStatus, writeContract,
+  showCallsStatus, signAuthorization, signMessage, signTypedData, waitForCallsStatus, writeContract,
 } from "viem/actions";
 import { signTransaction, type TransactionRequestEIP712, type ZksyncEip712Meta } from "viem/zksync";
 
 import { getTransactionWithPaymasterData } from "../../../paymaster/index.js";
+import { SessionErrorType, SessionEventType, type SessionState, validateSessionTransaction } from "../../../utils/session.js";
 import { sendEip712Transaction } from "../actions/sendEip712Transaction.js";
+import { getSessionState, sessionStateNotify } from "../actions/session.js";
 import type { ClientWithZksyncSsoSessionData } from "../client.js";
 
 export type ZksyncSsoWalletActions<chain extends Chain, account extends Account> = Omit<
   WalletActions<chain, account>, "addChain" | "getPermissions" | "requestAddresses" | "requestPermissions" | "switchChain" | "watchAsset" | "prepareTransactionRequest"
 >;
 
+const sessionErrorToSessionEventType = {
+  [SessionErrorType.SessionInactive]: SessionEventType.Inactive,
+  [SessionErrorType.SessionExpired]: SessionEventType.Expired,
+};
+
+/**
+ * Helper function to check session state and notify via callback
+ */
+async function getSessionStateAndNotify<
+  transport extends Transport,
+  chain extends Chain,
+  account extends Account,
+>(client: ClientWithZksyncSsoSessionData<transport, chain, account>): Promise<SessionState> {
+  const { sessionState } = await getSessionState(client, {
+    account: client.account.address,
+    sessionConfig: client.sessionConfig,
+    contracts: client.contracts,
+  });
+
+  if (client.onSessionStateChange) {
+    sessionStateNotify({
+      sessionConfig: client.sessionConfig,
+      sessionState,
+      onSessionStateChange: client.onSessionStateChange,
+      sessionNotifyTimeout: client._sessionNotifyTimeout,
+    });
+  }
+
+  return sessionState;
+}
+
 export function zksyncSsoWalletActions<
   transport extends Transport,
   chain extends Chain,
@@ -29,6 +60,29 @@ export function zksyncSsoWalletActions<
     getChainId: () => getChainId(client),
     sendRawTransaction: (args) => sendRawTransaction(client, args),
     sendTransaction: async (args) => {
+      // Get current session state and trigger callback if needed
+      const sessionState = await getSessionStateAndNotify(client);
+
+      // Validate transaction against session constraints
+      const validationResult = validateSessionTransaction({
+        sessionState,
+        sessionConfig: client.sessionConfig,
+        transaction: args as any,
+      });
+
+      // Throw error if validation fails
+      if (validationResult.error) {
+        // If validation fails due to session issues, notify via callback
+        if (client.onSessionStateChange && Object.keys(sessionErrorToSessionEventType).includes(validationResult.error.type)) {
+          client.onSessionStateChange({
+            type: sessionErrorToSessionEventType[validationResult.error.type as keyof typeof sessionErrorToSessionEventType],
+            message: validationResult.error.message,
+          });
+        }
+        throw new Error(`Session validation failed: ${validationResult.error.message} (${validationResult.error.type})`);
+      }
+
+      // Process transaction if it's valid
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const unformattedTx: any = Object.assign({}, args);
 

packages/sdk/src/utils/helpers.ts

@@ -41,3 +41,12 @@ export function noThrow<T>(fn: () => T): T | null {
     return null;
   }
 }
+
+export function findSmallestBigInt(arr: bigint[]): bigint {
+  if (arr.length === 0) throw new Error("Array must not be empty");
+  let smallest = arr[0];
+  for (const num of arr) {
+    if (num < smallest) smallest = num;
+  }
+  return smallest;
+}