@jack-kernel/sdk 1.0.0 → 1.2.1

package/dist/types/yellow/channel-state-manager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Channel State Manager for Yellow Network Integration
+ *
+ * Tracks local channel state and provides on-chain query capabilities.
+ * Maintains a local cache of channel states from ClearNode messages and
+ * falls back to on-chain queries via viem PublicClient when the WebSocket
+ * is disconnected.
+ *
+ * Requirements: 7.1, 7.2, 7.3, 7.4
+ */
+import type { PublicClient } from 'viem';
+import type { ChannelState } from './types.js';
+/**
+ * Manages local channel state cache and provides on-chain query capabilities.
+ *
+ * The ChannelStateManager serves two purposes:
+ * 1. Maintains a local cache of channel states received from ClearNode messages,
+ *    enabling fast lookups without network calls.
+ * 2. Provides on-chain balance queries via viem PublicClient for when the
+ *    WebSocket connection is unavailable (Requirement 7.4) or when authoritative
+ *    on-chain data is needed (Requirement 7.2).
+ *
+ * Requirements: 7.1, 7.2, 7.3, 7.4
+ */
+export declare class ChannelStateManager {
+    private readonly publicClient;
+    private readonly custodyAddress;
+    private readonly channels;
+    /**
+     * @param publicClient - viem PublicClient for on-chain balance queries
+     * @param custodyAddress - Address of the custody contract holding channel collateral
+     */
+    constructor(publicClient: PublicClient, custodyAddress: `0x${string}`);
+    /**
+     * Update the local cache with a channel state from a ClearNode response.
+     *
+     * This is called when the YellowProvider receives channel state updates
+     * from ClearNode messages (create, resize, close, or get_ledger_balances).
+     *
+     * Requirement 7.1: Maintain local channel state from ClearNode responses.
+     *
+     * @param channelId - The channel identifier
+     * @param state - The channel state to cache
+     */
+    updateChannel(channelId: string, state: ChannelState): void;
+    /**
+     * Get a locally cached channel state by channel ID.
+     *
+     * Returns undefined if the channel is not in the local cache.
+     * For authoritative on-chain data, use queryOnChainBalances instead.
+     *
+     * Requirement 7.2: Query specific channel status by channel ID.
+     *
+     * @param channelId - The channel identifier
+     * @returns The cached channel state, or undefined if not found
+     */
+    getChannel(channelId: string): ChannelState | undefined;
+    /**
+     * Get all locally cached channel states.
+     *
+     * Returns a snapshot array of all channels currently in the cache.
+     * The returned array is a copy; modifications do not affect the cache.
+     *
+     * Requirement 7.1: Return list of channels with their statuses and allocations.
+     *
+     * @returns Array of all cached channel states
+     */
+    getAllChannels(): ChannelState[];
+    /**
+     * Query on-chain channel balances from the custody contract.
+     *
+     * Uses viem PublicClient.readContract to call the custody contract's
+     * getChannelBalances function. This provides authoritative on-chain data
+     * and is used as a fallback when the ClearNode WebSocket is disconnected.
+     *
+     * Requirement 7.2: Query on-chain custody contract for channel balances.
+     * Requirement 7.4: Fall back to on-chain queries when WebSocket is disconnected.
+     *
+     * @param channelId - The channel identifier (bytes32 hex string)
+     * @param tokens - Array of token addresses to query balances for
+     * @returns Array of token balances as bigint values, one per token
+     * @throws Error if the on-chain query fails
+     */
+    queryOnChainBalances(channelId: string, tokens: string[]): Promise<bigint[]>;
+    /**
+     * Find an open (ACTIVE) channel for a given token address.
+     *
+     * Searches the local cache for a channel with status 'ACTIVE' that
+     * matches the specified token address. Returns the first match found.
+     *
+     * This is used by the YellowProvider to reuse existing channels
+     * when executing intents, avoiding unnecessary channel creation.
+     *
+     * @param token - The token address to find an open channel for
+     * @returns The first matching ACTIVE channel, or undefined if none found
+     */
+    findOpenChannel(token: string): ChannelState | undefined;
+    /**
+     * Clear all cached channel states.
+     *
+     * This is typically called when the provider disconnects or when
+     * a full state refresh is needed.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=channel-state-manager.d.ts.map

package/dist/types/yellow/channel-state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-state-manager.d.ts","sourceRoot":"","sources":["../../../src/yellow/channel-state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA+B/C;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD;;;OAGG;gBACS,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,MAAM,EAAE;IAMrE;;;;;;;;;;OAUG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAI3D;;;;;;;;;;OAUG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIvD;;;;;;;;;OASG;IACH,cAAc,IAAI,YAAY,EAAE;IAIhC;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBlF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IASxD;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/yellow/clear-node-connection.d.ts

@@ -0,0 +1,202 @@
+/**
+ * ClearNode WebSocket Connection Manager
+ *
+ * Manages the WebSocket connection to Yellow Network's ClearNode relay server
+ * with reconnection logic, request-response correlation, and event emission.
+ *
+ * Key features:
+ * - Exponential backoff reconnection: delay = initialDelay * 2^(attempt-1)
+ * - Request-response correlation using method name matching
+ * - EventEmitter pattern for connected/disconnected events
+ * - Cleanup of all pending handlers on disconnect
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+/**
+ * Configuration options for the ClearNodeConnection.
+ */
+export interface ConnectionOptions {
+    /** Maximum number of reconnection attempts before giving up. Default: 5 */
+    maxReconnectAttempts?: number;
+    /** Initial reconnection delay in milliseconds. Default: 1000 */
+    reconnectDelay?: number;
+    /** Timeout for sendAndWait responses in milliseconds. Default: 30000 */
+    messageTimeout?: number;
+}
+/**
+ * Minimal WebSocket interface used internally.
+ *
+ * Compatible with both the Node.js global WebSocket (Node 22+) and the `ws` package.
+ * This abstraction avoids a hard dependency on `@types/ws` while remaining type-safe.
+ */
+interface IWebSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(): void;
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+/**
+ * Factory type for creating WebSocket instances.
+ * Defaults to the global WebSocket constructor.
+ * Can be overridden for testing.
+ */
+type WebSocketFactory = (url: string) => IWebSocket;
+/**
+ * Calculate the exponential backoff delay for a given reconnection attempt.
+ *
+ * Formula: delay = initialDelay * 2^(attempt - 1)
+ *
+ * This is exported as a pure function so it can be independently tested
+ * (including via property-based tests).
+ *
+ * @param initialDelay - The base delay in milliseconds
+ * @param attempt - The attempt number (1-based)
+ * @returns The delay in milliseconds before the given attempt
+ */
+export declare function calculateBackoffDelay(initialDelay: number, attempt: number): number;
+/**
+ * Manages a WebSocket connection to Yellow Network's ClearNode.
+ *
+ * Provides:
+ * - connect/disconnect lifecycle management
+ * - send (fire-and-forget) and sendAndWait (request-response correlation)
+ * - Automatic reconnection with exponential backoff
+ * - Event emission for 'connected' and 'disconnected' events
+ * - Cleanup of pending handlers on disconnect
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+export declare class ClearNodeConnection {
+    private readonly url;
+    private readonly maxReconnectAttempts;
+    private readonly reconnectDelay;
+    private readonly messageTimeout;
+    private readonly wsFactory;
+    private ws;
+    private emitter;
+    private pendingRequests;
+    private messageHandlers;
+    private _isConnected;
+    private _isDisposed;
+    private reconnectAttempt;
+    private reconnectTimer;
+    /**
+     * @param url - The ClearNode WebSocket URL
+     * @param options - Connection configuration options
+     * @param wsFactory - Optional WebSocket factory for testing. Defaults to global WebSocket.
+     */
+    constructor(url: string, options?: ConnectionOptions, wsFactory?: WebSocketFactory);
+    /**
+     * Establish a WebSocket connection to ClearNode.
+     *
+     * Resolves when the connection is open and ready.
+     * Rejects if the connection fails to establish.
+     *
+     * Requirement 10.1: Emit a connected event on successful connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the WebSocket connection and clean up all resources.
+     *
+     * Requirement 10.4: Clean up all pending message handlers on disconnect.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message and wait for a correlated response.
+     *
+     * The response is matched by method name: when a message is received
+     * that contains a matching method field, the promise resolves with that response.
+     *
+     * Requirement 10.5: Request-response correlation using method name matching.
+     *
+     * @param message - The message string to send
+     * @param method - The method name to correlate the response with
+     * @param timeout - Optional timeout in ms (defaults to messageTimeout)
+     * @returns The parsed response data
+     * @throws Error if the connection is not open, the request times out, or the connection drops
+     */
+    sendAndWait<T>(message: string, method: string, timeout?: number): Promise<T>;
+    /**
+     * Send a message without waiting for a response (fire-and-forget).
+     *
+     * @param message - The message string to send
+     * @throws Error if the connection is not open
+     */
+    send(message: string): void;
+    /**
+     * Register a handler for incoming messages.
+     *
+     * Handlers receive the parsed message data for all incoming messages
+     * (including those that match pending requests).
+     *
+     * @param handler - Callback invoked with the parsed message data
+     */
+    onMessage(handler: (data: unknown) => void): void;
+    /**
+     * Whether the WebSocket connection is currently open and ready.
+     */
+    get isConnected(): boolean;
+    /**
+     * Register an event listener for connection lifecycle events.
+     *
+     * Supported events: 'connected', 'disconnected'
+     */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Remove an event listener.
+     */
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Handle an incoming WebSocket message.
+     *
+     * Parses the message as JSON and checks for method-based correlation
+     * with pending requests. Also dispatches to all registered message handlers.
+     */
+    private handleMessage;
+    /**
+     * Extract the method name from a parsed message object.
+     *
+     * Supports common message formats:
+     * - { method: "..." }
+     * - { type: "..." }
+     * - Nested: { response: { method: "..." } }
+     */
+    private extractMethod;
+    /**
+     * Handle an unexpected WebSocket disconnection.
+     *
+     * Cleans up state and initiates reconnection with exponential backoff.
+     *
+     * Requirement 10.2: Exponential backoff reconnection.
+     * Requirement 10.3: Emit disconnected and mark unavailable when retries exhausted.
+     */
+    private handleDisconnect;
+    /**
+     * Attempt to reconnect with exponential backoff.
+     *
+     * Requirement 10.2: delay = initialDelay * 2^(attempt-1)
+     * Requirement 10.3: Mark provider unavailable when all retries exhausted.
+     */
+    private attemptReconnect;
+    /**
+     * Cancel any pending reconnection timer.
+     */
+    private cancelReconnect;
+    /**
+     * Reject all pending requests with the given error and clean up timers.
+     *
+     * Requirement 10.4: Clean up all pending message handlers on disconnect.
+     */
+    private cleanupPendingRequests;
+    /**
+     * Remove a specific pending request from the list.
+     */
+    private removePendingRequest;
+}
+export {};
+//# sourceMappingURL=clear-node-connection.d.ts.map

package/dist/types/yellow/clear-node-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-node-connection.d.ts","sourceRoot":"","sources":["../../../src/yellow/clear-node-connection.ts"],"names":[],"mappings":"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"}

package/dist/types/yellow/event-mapper.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Yellow Network Event-to-Status Mapper
+ *
+ * Maps Yellow Network events, channel statuses, and state intents to JACK
+ * ExecutionStatus values. These are pure functions with no side effects,
+ * extracted from the dashboard's route.ts mapping tables into SDK-level
+ * reusable functions.
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+import { ExecutionStatus } from '../types.js';
+/**
+ * Represents a mapped Yellow Network event with its corresponding JACK
+ * execution status, step label, step status, and terminal flag.
+ */
+export interface MappedEvent {
+    executionStatus: ExecutionStatus;
+    stepLabel: string;
+    stepStatus: 'COMPLETED' | 'IN_PROGRESS' | 'PENDING' | 'FAILED';
+    isTerminal: boolean;
+}
+/**
+ * Map a Yellow Network event name to a JACK MappedEvent.
+ *
+ * Accepts event names in any casing; normalizes to lowercase with underscores.
+ * Returns undefined for unknown events.
+ *
+ * @param event - The Yellow Network event name (e.g., "quote_accepted", "settled")
+ * @returns The corresponding MappedEvent, or undefined if the event is unknown
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5
+ */
+export declare function mapYellowEvent(event: string): MappedEvent | undefined;
+/**
+ * Map a channel status to a JACK MappedEvent.
+ *
+ * Accepts channel statuses in any casing (e.g., "ACTIVE", "active", "Active").
+ * Returns undefined for unknown statuses.
+ *
+ * @param status - The ERC-7824 channel status (e.g., "VOID", "ACTIVE", "FINAL")
+ * @returns The corresponding MappedEvent, or undefined if the status is unknown
+ *
+ * Requirement: 9.6
+ */
+export declare function mapChannelStatus(status: string): MappedEvent | undefined;
+/**
+ * Map a state intent to a JACK MappedEvent.
+ *
+ * Accepts state intents in any casing (e.g., "FINALIZE", "finalize", "Finalize").
+ * Returns undefined for unknown intents.
+ *
+ * @param intent - The ERC-7824 state intent (e.g., "INITIALIZE", "OPERATE", "FINALIZE")
+ * @returns The corresponding MappedEvent, or undefined if the intent is unknown
+ *
+ * Requirement: 9.6
+ */
+export declare function mapStateIntent(intent: string): MappedEvent | undefined;
+/**
+ * Infer the best mapping from a notification payload.
+ *
+ * Checks fields in priority order: event → channelStatus → stateIntent.
+ * Returns the first successful mapping, or undefined if no field matches.
+ *
+ * @param notification - An object with optional event, channelStatus, and stateIntent fields
+ * @returns The best matching MappedEvent, or undefined if no mapping is found
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+export declare function inferMapping(notification: {
+    event?: string;
+    channelStatus?: string;
+    stateIntent?: string;
+}): MappedEvent | undefined;
+//# sourceMappingURL=event-mapper.d.ts.map

package/dist/types/yellow/event-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-mapper.d.ts","sourceRoot":"","sources":["../../../src/yellow/event-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,eAAe,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/D,UAAU,EAAE,OAAO,CAAC;CACrB;AA+KD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,WAAW,GAAG,SAAS,CAiB1B"}

package/dist/types/yellow/serialization.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Yellow Network Integration - BigInt Serialization Utilities
+ *
+ * Provides helpers to ensure all BigInt values from NitroliteClient responses
+ * are converted to string representations in public-facing types, making
+ * ChannelState and YellowQuote objects fully JSON-serializable via JSON.stringify.
+ *
+ * Requirements: 11.1, 11.2, 11.5
+ */
+import type { ChannelState, YellowQuote } from './types.js';
+/**
+ * Recursively converts any BigInt values in an object (or nested objects/arrays)
+ * to their string representation. All other value types are left unchanged.
+ *
+ * This is the foundational utility used by the type-specific helpers below.
+ * It handles the case where NitroliteClient responses may contain raw BigInt
+ * values that would cause JSON.stringify to throw.
+ *
+ * @param value - Any value that may contain BigInt values at any nesting level
+ * @returns A new value with all BigInt instances replaced by their string form
+ *
+ * Requirement 11.5: Convert BigInt values to string representation for JSON compatibility
+ */
+export declare function serializeBigIntToString<T>(value: T): T;
+/**
+ * Ensures a ChannelState object is fully JSON-serializable.
+ *
+ * Converts any BigInt values that may be present in the ChannelState
+ * (particularly in allocation amounts, challengePeriod, challengeExpiration,
+ * stateVersion, chainId, createdAt, updatedAt) to their appropriate
+ * JSON-compatible types (string for amounts, number for numeric fields).
+ *
+ * @param state - A ChannelState that may contain BigInt values from NitroliteClient
+ * @returns A new ChannelState with all values JSON-serializable
+ *
+ * Requirements: 11.1, 11.5
+ */
+export declare function toSerializableChannelState(state: ChannelState): ChannelState;
+/**
+ * Ensures a YellowQuote object is fully JSON-serializable.
+ *
+ * Converts any BigInt values that may be present in the YellowQuote
+ * (particularly amountIn and amountOut from solver responses) to their
+ * string representation.
+ *
+ * @param quote - A YellowQuote that may contain BigInt values from ClearNode
+ * @returns A new YellowQuote with all values JSON-serializable
+ *
+ * Requirement 11.2
+ */
+export declare function toSerializableYellowQuote(quote: YellowQuote): YellowQuote;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/types/yellow/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/yellow/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqB,WAAW,EAAE,MAAM,YAAY,CAAC;AAM/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAuBtD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAiB5E;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAazE"}

package/dist/types/yellow/session-key-manager.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Session Key Manager for Yellow Network ClearNode Authentication
+ *
+ * Handles session key generation, EIP-712 authentication flow, and session lifecycle.
+ *
+ * Authentication flow:
+ * 1. Generate session keypair via viem's generatePrivateKey + privateKeyToAccount
+ * 2. Send auth_request message with session key address, allowances, expiry, scope
+ * 3. Receive auth_challenge from ClearNode
+ * 4. Sign challenge with main wallet via EIP-712 typed data
+ * 5. Send auth_verify with signed challenge
+ * 6. Receive confirmation and store session state
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
+ */
+import type { WalletClient, Hex } from 'viem';
+import type { ClearNodeConnection } from './clear-node-connection.js';
+/**
+ * Signer function type used for signing messages.
+ * Compatible with @erc7824/nitrolite's MessageSigner type.
+ */
+export type MessageSigner = (payload: Uint8Array) => Promise<Hex>;
+/**
+ * Parameters for creating an auth request message.
+ */
+interface AuthRequestParams {
+    wallet: string;
+    participant: string;
+    allowances: Array<{
+        asset: string;
+        amount: string;
+    }>;
+    expire: number;
+    scope: string;
+}
+/**
+ * Parameters for authenticating with ClearNode.
+ */
+export interface AuthParams {
+    /** Token allowances for the session */
+    allowances: Array<{
+        asset: string;
+        amount: string;
+    }>;
+    /** Unix timestamp when the session expires. Default: now + 3600 seconds */
+    expiresAt?: number;
+    /** Application scope identifier. Default: "jack-kernel" */
+    scope?: string;
+}
+/**
+ * Information about the current authenticated session.
+ */
+export interface SessionInfo {
+    /** The session key's Ethereum address */
+    sessionAddress: string;
+    /** Unix timestamp when the session expires */
+    expiresAt: number;
+    /** Whether the session is currently authenticated */
+    authenticated: boolean;
+}
+/**
+ * Create an auth_request message for ClearNode.
+ *
+ * This is a local implementation matching the @erc7824/nitrolite
+ * createAuthRequestMessage API. It constructs a JSON-RPC style message
+ * with the session key details and allowances.
+ *
+ * @param params - Auth request parameters
+ * @returns JSON string of the auth_request message
+ */
+export declare function createAuthRequestMessage(params: AuthRequestParams): string;
+/**
+ * Create an EIP-712 auth message signer using the provided wallet client.
+ *
+ * This is a local implementation matching the @erc7824/nitrolite
+ * createEIP712AuthMessageSigner API. It returns a function that signs
+ * a challenge string using EIP-712 typed data via the wallet client.
+ *
+ * The EIP-712 domain and types follow the Yellow Network auth protocol:
+ * - Domain: { name: "Yellow ClearNode", version: "1" }
+ * - Types: { Auth: [{ name: "challenge", type: "string" }] }
+ *
+ * @param walletClient - The viem WalletClient to sign with
+ * @returns A function that takes a challenge string and returns the EIP-712 signature
+ */
+export declare function createEIP712AuthMessageSigner(walletClient: WalletClient): (challenge: string) => Promise<Hex>;
+/**
+ * Manages session key generation, ClearNode authentication, and session lifecycle.
+ *
+ * The SessionKeyManager generates ephemeral session keypairs for signing offchain
+ * messages, authenticates them with ClearNode via EIP-712, and tracks session expiry
+ * to support automatic re-authentication when the session expires.
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
+ */
+export declare class SessionKeyManager {
+    private readonly walletClient;
+    private readonly connection;
+    private sessionAccount;
+    private sessionPrivateKey;
+    private _sessionInfo;
+    private lastAuthParams;
+    /**
+     * @param walletClient - The main wallet's viem WalletClient for EIP-712 signing
+     * @param connection - The ClearNodeConnection for sending/receiving auth messages
+     */
+    constructor(walletClient: WalletClient, connection: ClearNodeConnection);
+    /**
+     * Generate a session keypair and authenticate with ClearNode.
+     *
+     * Flow:
+     * 1. Generate session keypair (Requirement 2.1)
+     * 2. Send auth_request with session address, allowances, expiry, scope (Requirement 2.2)
+     * 3. Receive auth_challenge from ClearNode
+     * 4. Sign challenge with main wallet via EIP-712 (Requirement 2.3)
+     * 5. Send auth_verify with signed challenge
+     * 6. Receive confirmation and store session state (Requirement 2.4)
+     *
+     * @param params - Authentication parameters including allowances and optional expiry/scope
+     * @returns Session information including address, expiry, and authentication status
+     * @throws Error if authentication fails or times out (Requirement 2.5)
+     */
+    authenticate(params: AuthParams): Promise<SessionInfo>;
+    /**
+     * Check if the current session is valid and not expired.
+     *
+     * Returns false if:
+     * - No session has been established
+     * - The session has been invalidated
+     * - The session has expired (Requirement 2.6)
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Get the session signer function for signing offchain messages.
+     *
+     * The returned function signs arbitrary payloads using the session private key.
+     * This is used for signing state channel messages without exposing the main wallet.
+     *
+     * @throws Error if no authenticated session exists
+     */
+    get sessionSigner(): MessageSigner;
+    /**
+     * Get the session key's Ethereum address.
+     *
+     * @throws Error if no session key has been generated
+     */
+    get sessionAddress(): string;
+    /**
+     * Invalidate the current session.
+     *
+     * Clears all session state including the keypair and authentication status.
+     * After invalidation, a new authenticate() call is required.
+     */
+    invalidate(): void;
+    /**
+     * Re-authenticate using the last authentication parameters.
+     *
+     * This is called internally when a session has expired and a new operation
+     * requires an active session (Requirement 2.6).
+     *
+     * @returns Session information from the new authentication
+     * @throws Error if no previous auth params exist or re-authentication fails
+     */
+    reauthenticate(): Promise<SessionInfo>;
+    /**
+     * Ensure the session is authenticated, re-authenticating if expired.
+     *
+     * This is a convenience method for use by other components that need
+     * to ensure an active session before performing operations.
+     *
+     * Requirement 2.6: Auto-reauthentication on next operation when expired.
+     *
+     * @returns The current or newly created session info
+     * @throws Error if authentication fails
+     */
+    ensureAuthenticated(): Promise<SessionInfo>;
+}
+export {};
+//# sourceMappingURL=session-key-manager.d.ts.map

package/dist/types/yellow/session-key-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key-manager.d.ts","sourceRoot":"","sources":["../../../src/yellow/session-key-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAgB,MAAM,MAAM,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAQtE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAElE;;GAEG;AACH,UAAU,iBAAiB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AA+BD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,UAAU,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;CACxB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAW1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,YAAY,GACzB,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAwBrC;AAeD;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IAEjD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,cAAc,CAA2B;IAEjD;;;OAGG;gBACS,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,mBAAmB;IAKvE;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAmG5D;;;;;;;OAOG;IACH,IAAI,eAAe,IAAI,OAAO,CAc7B;IAED;;;;;;;OAOG;IACH,IAAI,aAAa,IAAI,aAAa,CAYjC;IAED;;;;OAIG;IACH,IAAI,cAAc,IAAI,MAAM,CAK3B;IAED;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAW5C;;;;;;;;;;OAUG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,CAAC;CAQlD"}