Wallet
Architecture Overview
City Protocol's wallet layer is the identity and account-access foundation of every product built on the platform. It is designed to authenticate users, provision or connect wallets, and verify wallet-linked sessions across client and server boundaries using Privy and the City SDK.
This module handles the full lifecycle from login to backend-verified identity, ensuring that every downstream product feature, including vault interactions, access-gated flows, and on-chain operations, are anchored to a cryptographically verified wallet session.
Wallet integration uses Privy for client-side authentication and embedded wallet provisioning, and @cityprotocol/core for server-side identity verification. The architecture is stateless on the backend and framework-agnostic on the client.
Key Components
Privy Provider
Wraps the React application tree and manages authentication state, login methods, and embedded wallet creation policy.
Identity Token
A signed token issued by Privy after authentication. It encodes the user's session and linked wallet, and is the sole credential your backend should trust.
City SDK Verifier
A server-side utility (verifyPrivyWallet) exposed by @cityprotocol/core that validates the identity token, extracts the user profile, and returns the associated wallet address.
Wallet Gate
A client-side component pattern that conditionally renders UI based on authentication state, and attaches the identity token to outbound API calls.
Last updated