@lombard.finance/sdk 3.7.4 → 4.1.0

package/dist/shared/actions/BaseAction.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Base Action Class
+ *
+ * Abstract base class for all action implementations.
+ * Provides:
+ * - Event emission capabilities
+ * - Status and error tracking (separated concerns)
+ * - Type-safe event handlers
+ * - Error handling utilities
+ *
+ * ## Error Design
+ *
+ * Status and error are orthogonal concerns:
+ * - `status` = "What step are you at?" (IDLE, PREPARING, READY, etc.)
+ * - `error` = "Did something go wrong?" (Error | null)
+ * - `isFailed` = Derived from `error !== null`
+ *
+ * When an error occurs:
+ * 1. Status stays at the step where error occurred (preserves context)
+ * 2. Error is stored and accessible via `error` property
+ * 3. `isFailed` returns true
+ * 4. Events are emitted for listeners
+ *
+ * This allows easy retry - just call the method again since status
+ * is already at the correct step.
+ *
+ * @module shared/actions/BaseAction
+ */
+import type { StrategyProgress } from '../../core/types';
+import type { Logger } from '../context/types';
+import { LombardError } from '../errors';
+import { type EventEmitter, type EventHandler } from '../monitoring/createEventEmitter';
+/**
+ * Log metadata for structured logging
+ */
+export interface LogMeta {
+    /** Action name (e.g., 'BtcStake', 'EvmUnstake') */
+    action?: string;
+    /** Current step (e.g., 'prepare', 'authorize', 'execute') */
+    step?: string;
+    /** Current status */
+    status?: string;
+    /** Operation duration in milliseconds */
+    duration?: number;
+    /** Error code if applicable */
+    errorCode?: string;
+    /** Chain identifier */
+    chain?: string;
+    /** Any additional context */
+    [key: string]: unknown;
+}
+/**
+ * Monitorable action interface
+ *
+ * All actions expose this interface for consistent progress tracking.
+ *
+ * ## Orthogonal Concerns
+ * - `status` - Which step in the flow (IDLE, NEEDS_AUTH, READY, etc.)
+ * - `isLoading` - Is an async operation in progress
+ * - `error` / `isFailed` - Did an error occur
+ */
+export interface MonitorableAction {
+    /** Current status of the action (step in the flow) */
+    readonly status: string;
+    /** Whether an async operation is in progress */
+    readonly isLoading: boolean;
+    /** Error that occurred (if any) - null means no error */
+    readonly error: LombardError | null;
+    /** Whether the action has failed (derived from error !== null) */
+    readonly isFailed: boolean;
+    /**
+     * Register an event handler
+     *
+     * @param event - Event to listen for
+     * @param handler - Handler function
+     * @returns Unsubscribe function
+     */
+    on<TEvent extends string>(event: TEvent, handler: (...args: unknown[]) => void): () => void;
+}
+/**
+ * Base action abstract class
+ *
+ * Provides event emission and error handling infrastructure for all actions.
+ *
+ * ## Error Handling Design
+ *
+ * Status and error are separate concerns:
+ * - On error, status stays at current step (so you know WHERE it failed)
+ * - Error is stored and `isFailed` returns true
+ * - Retry by calling the same method again
+ *
+ * @example
+ * ```typescript
+ * class MyAction extends BaseAction<MyEventMap, MyStatus> {
+ *   async execute() {
+ *     this.assertStatus('idle', 'execute');
+ *     return this.act(
+ *       async () => {
+ *         // ... do work ...
+ *         // isLoading is true during execution
+ *         this.emitCompleted();
+ *       },
+ *       'completed', // Success status
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseAction<TEventMap extends Record<string, EventHandler<unknown[]>>, TStatus extends string> implements MonitorableAction {
+    /** Event emitter for this action */
+    protected readonly eventEmitter: EventEmitter<TEventMap>;
+    /** Current status (step in the flow) */
+    private _status;
+    /** Tracked error - null means no error */
+    protected _error: LombardError | null;
+    /** Loading state - true when an async operation is in progress */
+    private _isLoading;
+    /** Optional logger for debugging and monitoring */
+    protected readonly logger?: Logger;
+    /** Operation timing for performance monitoring */
+    private _timing;
+    constructor(initialStatus: TStatus, logger?: Logger);
+    /**
+     * Log a message with context
+     *
+     * Automatically includes action name and current status.
+     * No-op if logger is not configured.
+     *
+     * Uses explicit switch to avoid dynamic property access (security best practice).
+     */
+    protected log(level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: LogMeta): void;
+    /**
+     * Get timing for an operation
+     */
+    getTiming(operation: string): number | undefined;
+    /**
+     * Get all operation timings
+     */
+    getAllTimings(): Record<string, number>;
+    /**
+     * Record timing for an operation
+     */
+    protected recordTiming(operation: string, duration: number): void;
+    /** Current action status (which step in the flow) */
+    get status(): TStatus;
+    /** Error that occurred (if any) - null means no error */
+    get error(): LombardError | null;
+    /** Whether the action has failed (derived from error !== null) */
+    get isFailed(): boolean;
+    /** Whether an async operation is in progress */
+    get isLoading(): boolean;
+    /**
+     * Update the action status and emit status-change event
+     */
+    protected updateStatus(status: TStatus): void;
+    /**
+     * Assert the action is in an expected status
+     *
+     * @param expected - Single status or array of allowed statuses
+     * @param action - Name of the action being performed (for error message)
+     * @throws LombardError if current status is not in expected list
+     */
+    protected assertStatus(expected: TStatus | TStatus[], action: string): void;
+    /**
+     * Clear any previous error
+     *
+     * Call this at the start of retry attempts to reset error state.
+     */
+    protected clearError(): void;
+    /**
+     * Handle action failure
+     *
+     * Stores error, emits events, and throws.
+     * Status is NOT changed - it stays at the step where the error occurred.
+     * This allows callers to know exactly where the failure happened.
+     *
+     * @param error - The error that occurred
+     * @throws The wrapped LombardError
+     */
+    protected handleFailure(error: unknown): never;
+    /**
+     * Set loading state and emit event
+     */
+    protected setLoading(loading: boolean): void;
+    /**
+     * Perform an async operation with automatic state management
+     *
+     * This is the primary method for wrapping async operations in actions.
+     * Handles loading state, errors, and status transitions automatically.
+     *
+     * ## Automatic Behaviors
+     *
+     * - **isLoading**: Set to true before operation, false after (success or failure)
+     * - **error**: Cleared on start, set on failure
+     * - **status**: Optionally transitions to `successStatus` on success
+     *
+     * ## Design Philosophy: Orthogonal Concerns
+     *
+     * Status, loading, and error are independent:
+     * - `status` = "What step are you at?" (IDLE, NEEDS_AUTH, READY, etc.)
+     * - `isLoading` = "Is an operation in progress?" (true/false)
+     * - `error` = "Did something go wrong?" (Error | null)
+     *
+     * No transitional statuses (PREPARING, AUTHORIZING, etc.) needed!
+     * The UI can derive the display state:
+     * - IDLE + isLoading → "Preparing..."
+     * - NEEDS_AUTH + isLoading → "Authorizing..."
+     * - READY + isLoading → "Generating..."
+     *
+     * @param fn - Async function to execute
+     * @param successStatus - Status to transition to on success (optional)
+     * @returns Result of the operation
+     *
+     * @example Simple operation (no status change)
+     * ```typescript
+     * async execute() {
+     *   return this.act(async () => {
+     *     return this.depositAddress;
+     *   });
+     * }
+     * ```
+     *
+     * @example Operation with status transition
+     * ```typescript
+     * async authorize(): Promise<void> {
+     *   this.assertStatus([Status.NEEDS_AUTH, Status.READY], 'authorize');
+     *   if (this.status === Status.READY) return;
+     *
+     *   return this.act(
+     *     async () => {
+     *       const result = await this.signTransaction();
+     *       this.authState.signature = result.signature;
+     *     },
+     *     Status.READY
+     *   );
+     * }
+     * ```
+     *
+     * @example Flow visualization
+     * ```
+     * Success flow:
+     *   status: NEEDS_AUTH          -> NEEDS_AUTH          -> READY
+     *   isLoading: false -> true                   -> false
+     *
+     * Failure flow:
+     *   status: NEEDS_AUTH          -> NEEDS_AUTH (unchanged!)
+     *   isLoading: false -> true    -> false
+     *   error: null                 -> "User rejected"
+     * ```
+     */
+    protected act<T>(fn: () => Promise<T>, successStatus?: TStatus): Promise<T>;
+    /**
+     * Register an event handler
+     *
+     * @param event - Event to listen for
+     * @param handler - Handler function
+     * @returns Unsubscribe function
+     */
+    on<TEvent extends keyof TEventMap>(event: TEvent, handler: TEventMap[TEvent]): () => void;
+    /** Emit a progress update */
+    protected emitProgress(progress: StrategyProgress<TStatus>): void;
+    /** Emit a status change */
+    protected emitStatusChange(status: TStatus): void;
+    /** Emit completion event */
+    protected emitCompleted(): void;
+    /** Emit failed event */
+    protected emitFailed(): void;
+    /** Emit error event */
+    protected emitError(error: LombardError): void;
+    /** Emit loading state change */
+    protected emitLoading(isLoading: boolean): void;
+    /** Clear all event listeners */
+    protected clearListeners(): void;
+}
+//# sourceMappingURL=BaseAction.d.ts.map

package/dist/shared/actions/BaseAction.d.ts.map

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

package/dist/shared/actions/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared Actions
+ *
+ * Base classes and interfaces for action implementations.
+ *
+ * @module shared/actions
+ */
+export { BaseAction, type MonitorableAction } from './BaseAction';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/actions/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/shared/constants/statusConstants.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Status constants for all action types
+ *
+ * These constants replace magic strings throughout the codebase
+ * and provide type-safe status values.
+ *
+ * ## Error Design
+ *
+ * Note: There is NO 'failed' status. Error handling is separate from status:
+ * - `status` = "What step are you at?" (flow position)
+ * - `error` = "Did something go wrong?" (Error | null)
+ * - `isFailed` = Derived from `error !== null`
+ *
+ * When an error occurs, status stays at the step where it happened.
+ * This allows:
+ * 1. Knowing WHERE the error occurred (status tells you)
+ * 2. Easy retry - just call the method again
+ * 3. Simpler state machine - status only flows forward
+ */
+/**
+ * Unified BTC Action Status
+ *
+ * Single source of truth for all BTC action statuses.
+ * All BTC actions (Stake, Deposit, StakeAndDeploy, DepositAndDeploy) use this.
+ *
+ * Status represents "what step are you at" - no transitional statuses.
+ * Use `isLoading` for operation-in-progress state.
+ *
+ * ## Flow Examples
+ *
+ * **BtcStake/BtcDeposit (to Ethereum):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → ADDRESS_READY
+ *
+ * **BtcStake/BtcDeposit (to non-Ethereum):**
+ * IDLE → NEEDS_ADDRESS_CONFIRMATION → READY → ADDRESS_READY
+ *
+ * **BtcStakeAndDeploy/BtcDepositAndDeploy:**
+ * IDLE → NEEDS_DEPLOY_AUTHORIZATION → READY → ADDRESS_READY
+ */
+export declare const BtcActionStatus: {
+    /** Initial state - ready for prepare() */
+    readonly IDLE: "idle";
+    /** User needs to sign fee authorization (EVM stake/deposit to Ethereum) */
+    readonly NEEDS_FEE_AUTHORIZATION: "needs_fee_authorization";
+    /** User needs to confirm destination address (non-Ethereum destinations) */
+    readonly NEEDS_ADDRESS_CONFIRMATION: "needs_address_confirmation";
+    /** User needs to sign vault deploy authorization (stake-and-deploy, deposit-and-deploy) */
+    readonly NEEDS_DEPLOY_AUTHORIZATION: "needs_deploy_authorization";
+    /** Authorization complete - ready to generate address */
+    readonly READY: "ready";
+    /** Deposit address generated - awaiting BTC deposit */
+    readonly ADDRESS_READY: "address_ready";
+};
+export type BtcActionStatus = (typeof BtcActionStatus)[keyof typeof BtcActionStatus];
+/**
+ * EVM operation statuses (Deposit, Stake, Deploy, Unstake, Redeem)
+ *
+ * Simplified - use isLoading for operation-in-progress.
+ *
+ * ## Flow Examples
+ *
+ * **EVM Unstake (LBTC → BTC.b on Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ *
+ * **EVM Unstake (LBTC → BTC.b on Base/BSC - subsidized):**
+ * IDLE → READY → COMPLETED
+ *
+ * **EVM Redeem (BTC.b → BTC on Ethereum/Sepolia):**
+ * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
+ */
+export declare const EvmOperationStatus: {
+    readonly IDLE: "idle";
+    /** User needs to sign fee authorization (Ethereum/Sepolia only) */
+    readonly NEEDS_FEE_AUTHORIZATION: "needs_fee_authorization";
+    /** User needs to approve token spending */
+    readonly NEEDS_APPROVAL: "needs-approval";
+    readonly READY: "ready";
+    readonly CONFIRMING: "confirming";
+    readonly COMPLETED: "completed";
+};
+export type EvmOperationStatus = (typeof EvmOperationStatus)[keyof typeof EvmOperationStatus];
+/**
+ * Solana/Sui/Starknet Unstake operation statuses
+ */
+export declare const NonEvmUnstakeStatus: {
+    readonly IDLE: "idle";
+    readonly READY: "ready";
+    readonly CONFIRMING: "confirming";
+    readonly COMPLETED: "completed";
+};
+export type NonEvmUnstakeStatus = (typeof NonEvmUnstakeStatus)[keyof typeof NonEvmUnstakeStatus];
+//# sourceMappingURL=statusConstants.d.ts.map

package/dist/shared/constants/statusConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusConstants.d.ts","sourceRoot":"","sources":["../../../src/shared/constants/statusConstants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe;IAC1B,0CAA0C;;IAI1C,2EAA2E;;IAE3E,4EAA4E;;IAE5E,2FAA2F;;IAG3F,yDAAyD;;IAGzD,uDAAuD;;CAE/C,CAAC;AAEX,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB;;IAE7B,mEAAmE;;IAEnE,2CAA2C;;;;;CAKnC,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/shared/context/ContextBuilder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Context Builder
+ *
+ * Builds lightweight action contexts from LombardConfig.
+ * Contexts are passed to actions instead of the full SDK instance,
+ * improving testability and reducing coupling.
+ *
+ * NOTE: All context creation now works from config only.
+ * The SDK class should pass this.config when creating actions.
+ *
+ * @module shared/context/ContextBuilder
+ */
+import type { LombardConfig } from '../../config/types';
+import type { BtcCoreContext, EvmCoreContext } from './types';
+/**
+ * Create BTC core context from config
+ *
+ * Used by BtcActions and BTC factory functions.
+ *
+ * @example
+ * ```typescript
+ * // In BtcActions
+ * constructor(config: LombardConfig) {
+ *   this.ctx = createBtcCoreContext(config);
+ * }
+ *
+ * // Or directly for factory functions
+ * const stake = btcStake(config, params);
+ * ```
+ */
+export declare function createBtcCoreContext(config: LombardConfig): BtcCoreContext;
+/**
+ * Create EVM core context from config
+ *
+ * Used by EvmActions and EVM factory functions.
+ */
+export declare function createEvmCoreContext(config: LombardConfig): EvmCoreContext;
+/**
+ * @deprecated Use createBtcCoreContext(config) instead
+ */
+export declare const createBtcCoreContextFromConfig: typeof createBtcCoreContext;
+/**
+ * @deprecated Use createEvmCoreContext(config) instead
+ */
+export declare const createEvmCoreContextFromConfig: typeof createEvmCoreContext;
+//# sourceMappingURL=ContextBuilder.d.ts.map

package/dist/shared/context/ContextBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextBuilder.d.ts","sourceRoot":"","sources":["../../../src/shared/context/ContextBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EACV,cAAc,EAEd,cAAc,EAEf,MAAM,SAAS,CAAC;AAwDjB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAc1E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAW1E;AAMD;;GAEG;AACH,eAAO,MAAM,8BAA8B,6BAAuB,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,8BAA8B,6BAAuB,CAAC"}

package/dist/shared/context/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strategy Context System
+ *
+ * Exports context types and builder functions for dependency injection.
+ */
+export * from './ContextBuilder';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/context/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,SAAS,CAAC"}

package/dist/shared/context/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Strategy Context Types
+ *
+ * Defines the lightweight context objects passed to strategies instead of the full SDK.
+ * This improves testability, reduces coupling, and makes dependencies explicit.
+ *
+ * Architecture:
+ * - CoreContext = What ALL strategies of a source chain need (env, partner, chain service)
+ * - Destination = What strategies need for their destination chain (injected by namespace)
+ */
+import type { ApiService, BtcService, Env, EvmService, SolanaService, StarknetService, SuiService } from '@lombard.finance/sdk-common';
+import type { EIP1193Provider } from 'viem';
+import type { PartnerConfiguration } from '../../client/PartnerConfiguration';
+import type { CapabilityRegistry } from '../../modules/CapabilityRegistry';
+/**
+ * Logger interface for strategy operations
+ */
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Provider key for chain-specific wallet providers
+ */
+export type ProviderKey = 'bitcoin' | 'evm' | 'solana' | 'sui' | 'starknet';
+/**
+ * Provider resolver function
+ * Lazily resolves chain-specific wallet providers
+ */
+export type ProviderResolver = (key: ProviderKey) => Promise<EIP1193Provider | unknown>;
+/**
+ * Base Core Context
+ *
+ * Minimal context shared by ALL strategies, regardless of chain.
+ * Contains only environment, partner config, and provider resolution.
+ *
+ * TODO (v4.1): Add `catalog: AssetCatalog` field for remote catalog support.
+ * See: docs/ADDRESS_SYSTEM_UNIFICATION.md
+ */
+export interface CoreContext {
+    readonly env: Env;
+    readonly partner: PartnerConfiguration;
+    readonly getProvider: ProviderResolver;
+    readonly logger?: Logger;
+}
+/**
+ * BTC Core Context
+ *
+ * What ALL Bitcoin strategies need (source chain operations).
+ * Includes BTC service, API service, and capabilities registry.
+ *
+ * Note: Chain-specific destination services (EVM, Solana, etc.) are accessed
+ * via capabilities.require('evm') when needed by chain configs.
+ */
+export interface BtcCoreContext extends CoreContext {
+    readonly btc: BtcService;
+    readonly api: ApiService;
+    readonly capabilities: CapabilityRegistry;
+}
+/**
+ * EVM Core Context
+ *
+ * What ALL EVM strategies need (source chain operations).
+ */
+export interface EvmCoreContext extends CoreContext {
+    readonly evm: EvmService;
+}
+/**
+ * Solana Core Context
+ *
+ * What ALL Solana strategies need (source chain operations).
+ */
+export interface SolanaCoreContext extends CoreContext {
+    readonly solana: SolanaService;
+}
+/**
+ * Sui Core Context
+ *
+ * What ALL Sui strategies need (source chain operations).
+ */
+export interface SuiCoreContext extends CoreContext {
+    readonly sui: SuiService;
+}
+/**
+ * Starknet Core Context
+ *
+ * What ALL Starknet strategies need (source chain operations).
+ */
+export interface StarknetCoreContext extends CoreContext {
+    readonly starknet: StarknetService;
+}
+/**
+ * EVM as destination chain
+ * Injected into strategies that mint/send to EVM chains
+ */
+export interface EvmDestination {
+    readonly evm: EvmService;
+}
+/**
+ * Solana as destination chain
+ * Injected into strategies that mint/send to Solana
+ */
+export interface SolanaDestination {
+    readonly solana: SolanaService;
+}
+/**
+ * Sui as destination chain
+ * Injected into strategies that mint/send to Sui
+ */
+export interface SuiDestination {
+    readonly sui: SuiService;
+}
+/**
+ * Starknet as destination chain
+ * Injected into strategies that mint/send to Starknet
+ */
+export interface StarknetDestination {
+    readonly starknet: StarknetService;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/context/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shared/context/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,GAAG,EACH,UAAU,EACV,aAAa,EACb,eAAe,EACf,UAAU,EACX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAID;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAE5E;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,eAAe,GAAG,OAAO,CAAC,CAAC;AAIxC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAE1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAID;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC"}