@jack-kernel/sdk 1.0.0 → 1.1.0

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"}

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

@@ -0,0 +1,177 @@
+/**
+ * Yellow Network Integration - Shared Type Definitions
+ *
+ * This module defines all shared types for the Yellow Network integration layer.
+ * All BigInt-representable fields (allocations, challenge duration) use string type
+ * for JSON compatibility (Requirements 11.1, 11.2, 11.5).
+ *
+ * Requirements: 7.3, 11.1, 11.2, 11.5
+ */
+/**
+ * Connection status of the YellowProvider to ClearNode.
+ */
+export type YellowProviderStatus = 'connected' | 'disconnected' | 'connecting' | 'error';
+/**
+ * Reason codes for Yellow Network operation failures.
+ * Used in YellowFallback to indicate why an operation failed.
+ */
+export type YellowReasonCode = 'MISSING_PARAMS' | 'UNSUPPORTED_CHAIN' | 'INSUFFICIENT_BALANCE' | 'INSUFFICIENT_CHANNEL_BALANCE' | 'NO_SOLVER_QUOTES' | 'YELLOW_UNAVAILABLE' | 'YELLOW_TX_FAILED' | 'YELLOW_AUTH_FAILED' | 'YELLOW_TIMEOUT' | 'YELLOW_CHANNEL_DISPUTE' | 'YELLOW_WS_ERROR';
+/**
+ * Fallback information returned when a Yellow Network operation cannot be completed.
+ * The `enabled: true` flag indicates that fallback to an alternative provider is recommended.
+ */
+export interface YellowFallback {
+    enabled: true;
+    reasonCode: YellowReasonCode;
+    message: string;
+}
+/**
+ * Normalized representation of a state channel's current status, allocations, and metadata.
+ * Requirement 7.3: includes channelId, status, allocations per participant, token address, and chainId.
+ */
+export interface ChannelState {
+    channelId: string;
+    status: 'VOID' | 'INITIAL' | 'ACTIVE' | 'DISPUTE' | 'FINAL';
+    chainId: number;
+    token: string;
+    allocations: ChannelAllocation[];
+    stateVersion: number;
+    stateIntent: string;
+    stateHash?: string;
+    adjudicator: string;
+    challengePeriod: number;
+    challengeExpiration?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * A single allocation within a state channel, mapping a participant to a token amount.
+ * The `amount` field is a string representation of a BigInt for JSON compatibility (Requirement 11.5).
+ */
+export interface ChannelAllocation {
+    destination: string;
+    token: string;
+    amount: string;
+}
+/**
+ * A normalized solver quote received via ClearNode.
+ * All amount fields use string type for JSON compatibility.
+ */
+export interface YellowQuote {
+    solverId: string;
+    channelId: string;
+    amountIn: string;
+    amountOut: string;
+    estimatedTime: number;
+    timestamp: number;
+}
+/**
+ * The outcome of an offchain clearing operation.
+ * Contains matched orders and net settlement amounts.
+ */
+export interface ClearingResult {
+    channelId: string;
+    matchedAmountIn: string;
+    matchedAmountOut: string;
+    netSettlement: string;
+    settlementProof?: SettlementProof;
+    timestamp: number;
+}
+/**
+ * On-chain evidence of a completed settlement.
+ * Includes the final state hash, participant signatures, and optional transaction hash.
+ */
+export interface SettlementProof {
+    stateHash: string;
+    signatures: string[];
+    txHash?: string;
+    finalAllocations: ChannelAllocation[];
+}
+/**
+ * Result of a ClearNode connection and authentication attempt.
+ */
+export interface YellowConnectionResult {
+    connected: boolean;
+    sessionAddress?: string;
+    fallback?: YellowFallback;
+}
+/**
+ * Result of a channel lifecycle operation (create, resize, close, or query).
+ */
+export interface YellowChannelResult {
+    channelId?: string;
+    state?: ChannelState;
+    txHash?: string;
+    fallback?: YellowFallback;
+}
+/**
+ * Result of an offchain transfer operation.
+ */
+export interface YellowTransferResult {
+    success: boolean;
+    updatedAllocations?: ChannelAllocation[];
+    fallback?: YellowFallback;
+}
+/**
+ * Result of executing an intent via Yellow Network clearing.
+ * The `provider` field indicates whether Yellow or a fallback provider handled the intent.
+ */
+export interface YellowExecutionResult {
+    provider: 'yellow' | 'fallback';
+    intentId?: string;
+    quote?: YellowQuote;
+    clearing?: ClearingResult;
+    channelId?: string;
+    timestamp: number;
+    fallback?: YellowFallback;
+}
+/**
+ * Result of querying the list of channels and their balances.
+ */
+export interface YellowChannelsResult {
+    channels: ChannelState[];
+    fallback?: YellowFallback;
+}
+/**
+ * Events emitted by the YellowProvider during its lifecycle.
+ */
+export type YellowEvent = 'connected' | 'disconnected' | 'channel_created' | 'channel_resized' | 'channel_closed' | 'transfer_completed' | 'quote_received' | 'clearing_completed' | 'error';
+/**
+ * Handler function for YellowProvider events.
+ */
+export type YellowEventHandler = (data: unknown) => void;
+/**
+ * Parameters for creating a new state channel.
+ */
+export interface CreateChannelParams {
+    chainId: number;
+    token: string;
+}
+/**
+ * Parameters for resizing a channel's allocations.
+ * The `allocateAmount` field is a string representation of a BigInt for JSON compatibility.
+ */
+export interface ResizeChannelParams {
+    channelId: string;
+    allocateAmount: string;
+    fundsDestination?: string;
+}
+/**
+ * Parameters for closing a state channel.
+ */
+export interface CloseChannelParams {
+    channelId: string;
+    withdraw?: boolean;
+}
+/**
+ * Parameters for sending an offchain transfer through a state channel.
+ * Allocation amounts are string representations of BigInt for JSON compatibility.
+ */
+export interface TransferParams {
+    destination: string;
+    allocations: Array<{
+        asset: string;
+        amount: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/types/yellow/yellow-provider.d.ts

@@ -0,0 +1,303 @@
+/**
+ * YellowProvider - Main entry point for Yellow Network operations
+ *
+ * Orchestrates session management, channel lifecycle, clearing, and event mapping.
+ * Follows the same standalone-class pattern as LifiProvider.
+ *
+ * Key design decisions:
+ * - Constructor MAY throw if NitroliteClient initialization fails
+ * - All other public methods return result objects (never throw)
+ * - WebSocket connection management is encapsulated in ClearNodeConnection
+ * - Session key management is handled internally via SessionKeyManager
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.8, 10.1
+ */
+import type { WalletClient, PublicClient } from 'viem';
+import type { IntentParams } from '../types.js';
+import type { YellowConnectionResult, YellowChannelResult, YellowTransferResult, YellowExecutionResult, YellowChannelsResult, YellowEvent, YellowEventHandler, YellowProviderStatus, YellowReasonCode, CreateChannelParams, ResizeChannelParams, CloseChannelParams, TransferParams } from './types.js';
+/**
+ * Centralized error-to-reason-code mapping for all YellowProvider methods.
+ *
+ * Classifies an unknown error into the appropriate YellowReasonCode based on
+ * the error message content. This ensures consistent error classification
+ * across all provider methods.
+ *
+ * Mapping rules (Requirements 13.1, 13.2, 13.3, 13.4, 13.5):
+ * - WebSocket errors → YELLOW_UNAVAILABLE
+ * - On-chain transaction reverts → YELLOW_TX_FAILED
+ * - Authentication failures → YELLOW_AUTH_FAILED
+ * - Message timeouts → YELLOW_TIMEOUT
+ * - ClearNode unavailable / all reconnection attempts exhausted → YELLOW_UNAVAILABLE
+ *
+ * @param error - The error to classify (may be Error, string, or unknown)
+ * @returns The appropriate YellowReasonCode for the error
+ */
+export declare function mapErrorToReasonCode(error: unknown): YellowReasonCode;
+/**
+ * Extract a revert reason from an on-chain transaction error, if available.
+ *
+ * Attempts to parse the revert reason from common error formats produced by
+ * viem and other Ethereum libraries.
+ *
+ * @param error - The error to extract the revert reason from
+ * @returns The revert reason string, or undefined if not found
+ */
+export declare function extractRevertReason(error: unknown): string | undefined;
+/**
+ * Local stub interface for @erc7824/nitrolite NitroliteClient.
+ *
+ * This captures the expected API surface of the NitroliteClient from the
+ * @erc7824/nitrolite package. The real package is NOT installed; this stub
+ * allows the code to be structurally correct and ready to swap in the real
+ * package later.
+ */
+export interface NitroliteClientConfig {
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    custodyAddress: `0x${string}`;
+    adjudicatorAddress: `0x${string}`;
+    challengeDuration: bigint;
+}
+/**
+ * Stub NitroliteClient class.
+ *
+ * Provides the constructor interface expected by the real @erc7824/nitrolite package.
+ * Channel lifecycle methods (createChannel, resizeChannel, closeChannel) are stubs
+ * that will be replaced when the real package is installed.
+ */
+export declare class NitroliteClient {
+    readonly config: NitroliteClientConfig;
+    constructor(config: NitroliteClientConfig);
+}
+/**
+ * Configuration object for initializing the YellowProvider.
+ *
+ * Requirement 1.8: Accepts fields for ClearNode WebSocket URL, custody contract address,
+ * adjudicator contract address, chain ID, challenge duration, RPC URL, and session expiry.
+ */
+export interface YellowConfig {
+    /** ClearNode WebSocket URL. Default: "wss://clearnet-sandbox.yellow.com/ws" */
+    clearNodeUrl?: string;
+    /** Custody contract address (required) */
+    custodyAddress: `0x${string}`;
+    /** Adjudicator contract address (required) */
+    adjudicatorAddress: `0x${string}`;
+    /** Chain ID for on-chain operations (required) */
+    chainId: number;
+    /** RPC URL for the chain (optional, used to create a PublicClient if needed) */
+    rpcUrl?: string;
+    /** Challenge period in seconds. Default: 3600 */
+    challengeDuration?: number;
+    /** Session key expiry in seconds. Default: 3600 */
+    sessionExpiry?: number;
+    /** WebSocket message timeout in ms. Default: 30000 */
+    messageTimeout?: number;
+    /** Max WebSocket reconnection attempts. Default: 5 */
+    maxReconnectAttempts?: number;
+    /** Initial reconnection delay in ms. Default: 1000 */
+    reconnectDelay?: number;
+}
+/**
+ * Main provider class for Yellow Network operations.
+ *
+ * Orchestrates session management, channel lifecycle, clearing, and event mapping.
+ * The constructor initializes the NitroliteClient with viem clients and contract addresses.
+ * The connect() method establishes the WebSocket and completes the auth handshake.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.8, 10.1
+ */
+export declare class YellowProvider {
+    private readonly nitroliteClient;
+    private readonly walletClient;
+    private readonly publicClient;
+    private readonly config;
+    private connection;
+    private sessionManager;
+    private channelStateManager;
+    private readonly eventHandlers;
+    private _status;
+    /**
+     * Creates a new YellowProvider instance.
+     *
+     * Requirement 1.1: Initialize NitroliteClient with custody/adjudicator addresses and viem clients.
+     * Requirement 1.2: Default clearNodeUrl to "wss://clearnet-sandbox.yellow.com/ws".
+     * Requirement 1.3: Convert challengeDuration to BigInt when passing to NitroliteClient.
+     * Requirement 1.4: Default challengeDuration to 3600 seconds.
+     * Requirement 1.5: Throw descriptive error if NitroliteClient initialization fails.
+     * Requirement 1.8: Accept all YellowConfig fields.
+     *
+     * @param config - Yellow Network configuration
+     * @param walletClient - viem WalletClient for signing transactions and EIP-712 messages
+     * @throws Error if NitroliteClient initialization fails
+     */
+    constructor(config: YellowConfig, walletClient: WalletClient);
+    /**
+     * Connect to ClearNode and authenticate.
+     *
+     * Establishes a WebSocket connection via ClearNodeConnection, then authenticates
+     * using SessionKeyManager with the configured session expiry.
+     *
+     * Requirement 10.1: Establish WebSocket connection and emit connected event.
+     *
+     * @returns Connection result with session address on success, or fallback on failure
+     */
+    connect(): Promise<YellowConnectionResult>;
+    /**
+     * Disconnect from ClearNode and clean up all resources.
+     *
+     * Closes the WebSocket connection, invalidates the session, clears channel state,
+     * and removes all event handlers from internal components.
+     *
+     * Requirement 10.4: Close WebSocket and clean up all pending message handlers.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if the provider is connected and authenticated.
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the current provider status.
+     */
+    get status(): YellowProviderStatus;
+    /**
+     * Register an event listener for YellowProvider events.
+     *
+     * @param event - The event type to listen for
+     * @param handler - The handler function to call when the event fires
+     */
+    on(event: YellowEvent, handler: YellowEventHandler): void;
+    /**
+     * Remove an event listener.
+     *
+     * @param event - The event type to stop listening for
+     * @param handler - The handler function to remove
+     */
+    off(event: YellowEvent, handler: YellowEventHandler): void;
+    /**
+     * Create a new state channel.
+     *
+     * Two-phase operation:
+     * 1. Send create_channel message to ClearNode via sendAndWait
+     * 2. Submit channel creation on-chain via NitroliteClient (simulated)
+     *
+     * After success, updates the ChannelStateManager cache and emits channel_created.
+     *
+     * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5
+     *
+     * @param params - Channel creation parameters (chainId, token)
+     * @returns YellowChannelResult with channelId, state, and txHash on success; fallback on failure
+     */
+    createChannel(params: CreateChannelParams): Promise<YellowChannelResult>;
+    /**
+     * Resize a channel's allocations.
+     *
+     * Two-phase operation:
+     * 1. Send resize_channel message to ClearNode via sendAndWait
+     * 2. Submit resize on-chain via NitroliteClient (simulated)
+     *
+     * After success, updates the ChannelStateManager cache and emits channel_resized.
+     *
+     * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5
+     *
+     * @param params - Resize parameters (channelId, allocateAmount, optional fundsDestination)
+     * @returns YellowChannelResult with updated state on success; fallback on failure
+     */
+    resizeChannel(params: ResizeChannelParams): Promise<YellowChannelResult>;
+    /**
+     * Close a channel and optionally withdraw funds.
+     *
+     * Two-phase operation:
+     * 1. Send close_channel message to ClearNode via sendAndWait
+     * 2. Submit close on-chain via NitroliteClient (simulated)
+     * 3. Optionally call custody withdrawal for the channel's tokens
+     *
+     * After success, updates the ChannelStateManager cache and emits channel_closed.
+     *
+     * Requirements: 5.1, 5.2, 5.3, 5.4, 5.5
+     *
+     * @param params - Close parameters (channelId, optional withdraw flag defaulting to true)
+     * @returns YellowChannelResult with FINAL status on success; fallback on failure
+     */
+    closeChannel(params: CloseChannelParams): Promise<YellowChannelResult>;
+    /**
+     * Send an offchain transfer through an open state channel.
+     *
+     * Validates the transfer amount against the sender's channel allocation,
+     * sends a signed transfer message to ClearNode, and returns the updated allocations.
+     *
+     * Requirements: 6.1, 6.2, 6.3, 6.4
+     *
+     * @param params - Transfer parameters (destination, allocations with asset/amount)
+     * @returns YellowTransferResult with success and updated allocations, or fallback on failure
+     */
+    transfer(params: TransferParams): Promise<YellowTransferResult>;
+    /**
+     * Execute an intent via Yellow Network clearing.
+     *
+     * Validates the intent parameters, finds or creates a state channel for the
+     * intent's token/chain, submits the intent for solver matching via ClearNode,
+     * normalizes the solver quote into a YellowQuote, and returns a YellowExecutionResult
+     * with the clearing result on success.
+     *
+     * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
+     *
+     * @param params - Intent parameters (sourceChain, destinationChain, tokenIn, tokenOut, amountIn required)
+     * @returns YellowExecutionResult with clearing result on success; fallback on failure
+     */
+    executeIntent(params: IntentParams): Promise<YellowExecutionResult>;
+    /**
+     * Query channel list and balances.
+     *
+     * When connected to ClearNode, sends a get_ledger_balances message and parses
+     * the response into ChannelState objects, updating the local cache.
+     * When disconnected, falls back to the ChannelStateManager's cached data.
+     *
+     * Requirements: 7.1, 7.4
+     *
+     * @returns YellowChannelsResult with the list of channels
+     */
+    getChannels(): Promise<YellowChannelsResult>;
+    /**
+     * Query a specific channel's on-chain state.
+     *
+     * Queries the on-chain custody contract via ChannelStateManager.queryOnChainBalances
+     * for authoritative balance data, and also checks the local cache for additional
+     * channel metadata.
+     *
+     * Requirements: 7.2, 7.3
+     *
+     * @param channelId - The channel identifier to query
+     * @returns YellowChannelResult with the channel state
+     */
+    getChannelState(channelId: string): Promise<YellowChannelResult>;
+    /**
+     * Emit an event to all registered handlers.
+     *
+     * @param event - The event type to emit
+     * @param data - The data to pass to handlers
+     */
+    private emit;
+    /**
+     * Simulate an on-chain transaction via NitroliteClient.
+     *
+     * Since NitroliteClient is a stub, this generates a deterministic transaction hash
+     * based on the operation and channel ID. In production, this would call the actual
+     * NitroliteClient methods (createChannel, resizeChannel, closeChannel, withdraw).
+     *
+     * @param operation - The on-chain operation name
+     * @param channelId - The channel identifier
+     * @returns A simulated transaction hash
+     */
+    private simulateOnChainTransaction;
+    /**
+     * Get the internal NitroliteClient instance.
+     * Exposed for testing and advanced use cases.
+     */
+    getNitroliteClient(): NitroliteClient;
+    /**
+     * Get the resolved configuration with defaults applied.
+     * Exposed for testing.
+     */
+    getResolvedConfig(): Readonly<typeof this.config>;
+}
+//# sourceMappingURL=yellow-provider.d.ts.map

package/dist/types/yellow/yellow-provider.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jack-kernel/sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TypeScript SDK for JACK cross-chain execution kernel",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",