Frontend Wallet Integration (Starknet)
Relevant source files
The following files were used as context for generating this wiki page:
The OnChain Sage frontend integrates with the Starknet blockchain to enable decentralized features, such as managing STRK token transactions for premium access and gas fees. This integration allows users to connect their Starknet wallets (e.g., Argent, Braavos) directly within the application, providing a seamless bridge between the user's assets and the platform's on-chain functionalities.
The core of this system is a React Context-based provider that manages the wallet's connection state, account details, and provider interface. This state is then consumed by various UI components to display connection status, user address, and to trigger on-chain transactions.
Sources: README.md, ARCHITECTURE.md
Core Components and Dependencies
The wallet integration is built using several key libraries and a modular component structure.
Key Dependencies
The functionality relies on the following npm packages defined in the frontend application.
| Package | Version | Description |
|---|---|---|
@starknet-react/core | ^3.7.2 | A library of React hooks for Starknet, though it is not directly used in the provided context files. |
get-starknet | ^3.3.3 | A library to facilitate connecting to Starknet wallet browser extensions, handling the connection modal. |
starknet | ^6.23.1 | The primary JavaScript/TypeScript SDK for interacting with the Starknet network, providing core types. |
Sources: apps/frontend/package.json:15-25
Component Architecture
The integration is structured around a central context provider that wraps the application and UI components that consume the context.
This diagram illustrates the component hierarchy for the Starknet integration.
Starknet Context Provider
The StarknetProvider is the central piece of the wallet integration. It is a React component that uses the Context API to manage and distribute the Starknet connection state across the entire application.
Sources: apps/frontend/context/StarknetContext.tsx
State and Interface
The provider manages a state object defined by the StarknetContextType interface.
interface StarknetContextType {
account: AccountInterface | null;
provider: ProviderInterface | null;
address: string | null;
isConnected: boolean;
connectWallet: () => Promise<void>;
disconnectWallet: () => Promise<void>;
isLoading: boolean;
}
Sources: apps/frontend/context/StarknetContext.tsx:5-13
The following table details the properties and methods exposed by the useStarknet hook, which consumes this context.
| Property/Method | Type | Description |
|---|---|---|
account | AccountInterface | null | The connected wallet account object from the starknet library. |
provider | ProviderInterface | null | The provider object for interacting with the Starknet network. |
address | string | null | The address of the connected wallet. |
isConnected | boolean | A flag indicating if a wallet is currently connected. |
isLoading | boolean | A flag indicating if a connection or disconnection action is in progress. |
connectWallet | () => Promise<void> | Function to initiate the wallet connection process. |
disconnectWallet | () => Promise<void> | Function to disconnect the current wallet. |
Sources: apps/frontend/context/StarknetContext.tsx:5-13
Root Layout Integration
The StarknetProvider is implemented in the root layout (layout.tsx) to ensure the wallet connection state is available to all pages and components within the application.
// apps/frontend/app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body className={inter.className}>
<StarknetProvider>
<div className="min-h-screen">
{children}
</div>
</StarknetProvider>
</body>
</html>
);
}
Sources: apps/frontend/app/layout.tsx:17-27
Connection Flow
The connectWallet function handles the user-facing connection process using the get-starknet library. It displays a modal for the user to select their wallet.
This sequence diagram shows the steps involved when a user connects their wallet.
Session Persistence (Silent Reconnect)
The provider uses localStorage to persist the connection status across sessions. On application load, a useEffect hook checks for the starknetWalletConnected flag. If present, it attempts a "silent" reconnect without prompting the user.
UI Component: WalletConnect
The WalletConnect component is a UI card that provides a visual interface for the wallet connection status. It is currently a mock implementation that uses local state and does not interact with the StarknetContext.
Sources: apps/frontend/components/wallet-connect.tsx
Logic and State
The component's logic is based on a single local state variable, isConnected.
| Element | Type | Description |
|---|---|---|
isConnected | boolean | Local state flag to toggle the display between connected and disconnected. |
handleConnect | () => void | Sets isConnected to true. Does not call the context. |
handleDisconnect | () => void | Sets isConnected to false. Does not call the context. |
Sources: apps/frontend/components/wallet-connect.tsx:7, 10-15
The component renders different content based on the isConnected state. When connected, it displays a hardcoded address (0x71C...F3E2) and balance (125.5 STRK).
This flowchart shows the rendering logic of the WalletConnect component.
Summary
The frontend wallet integration for Starknet is architected around a centralized StarknetProvider that manages connection state via React Context. This provider handles the logic for connecting, disconnecting, and persisting the session using the get-starknet library and localStorage. While UI components like WalletConnect exist to provide a user interface for these actions, the current implementation of WalletConnect is a visual mock-up. The core, reusable logic resides entirely within StarknetContext.tsx, making it the foundation for all Starknet-related interactions in the OnChain Sage frontend.
Sources: apps/frontend/context/StarknetContext.tsx, apps/frontend/components/wallet-connect.tsx