@gala-chain/launchpad-sdk 5.0.3 → 5.0.4-beta.1

package/dist/src/utils/address-formatter.d.ts

@@ -0,0 +1,317 @@
+/**
+ * AddressFormatter - Consolidated address format conversion utilities
+ *
+ * Consolidates address formatting logic scattered across multiple files:
+ * - validation.ts: `toBackendAddressFormat()`, `fromBackendAddressFormat()`, `normalizeAddressInput()`
+ * - validation-helpers.ts: `formatAddressForBackend()`, `isValidAddress()`, `assertValidWalletAddress()`
+ * - Multiple services: Duplicate address parsing and normalization
+ *
+ * ## Problem Solved
+ *
+ * Address formatting was duplicated with inconsistent patterns:
+ * - Ethereum format: "0x1234..."
+ * - Backend format: "eth|1234..."
+ * - Client format: "client|abc123"
+ * - Different validation patterns in different files
+ * - Inconsistent error messages
+ *
+ * This utility provides a cohesive, well-documented interface for all address operations.
+ *
+ * @category Utilities
+ * @since 6.5.0
+ */
+import { AddressFormat } from '../types/common';
+import { stripHexPrefix as bridgeStripHexPrefix } from '../bridge/utils/address-formatter';
+/**
+ * Address format types
+ */
+export type AddressFormatType = 'ethereum' | 'backend' | 'client';
+/**
+ * AddressFormatter - Unified address format operations
+ *
+ * Provides consistent, well-documented address formatting and validation
+ * across all services that work with wallet addresses.
+ *
+ * ## Supported Formats
+ *
+ * - **Ethereum**: `0x1234567890abcdef...` (40 hex chars with 0x prefix)
+ * - **Backend**: `eth|1234567890abcdef...` (40 hex chars without 0x)
+ * - **Client**: `client|identifier` (arbitrary client identifiers)
+ *
+ * ## Usage Examples
+ *
+ * ### Format conversion
+ * ```typescript
+ * const formatter = new AddressFormatter();
+ *
+ * // Ethereum to backend
+ * formatter.toBackendFormat('0x1234...abc');
+ * // Returns: 'eth|1234...abc'
+ *
+ * // Backend to Ethereum
+ * formatter.toEthereumFormat('eth|1234...abc');
+ * // Returns: '0x1234...abc'
+ *
+ * // Auto-detect and convert
+ * const format = formatter.normalizeInput('0x1234...abc');
+ * // Returns: 'eth|1234...abc' (backend format)
+ * ```
+ *
+ * ### Validation
+ * ```typescript
+ * const formatter = new AddressFormatter();
+ *
+ * // Check validity (no throw)
+ * if (formatter.isValid('0x1234...abc')) {
+ *   // Process address
+ * }
+ *
+ * // Validate with throw
+ * formatter.assertValid(address, 'userAddress');
+ * // Safe to use
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare class AddressFormatter {
+    /**
+     * Convert Ethereum address to backend format
+     *
+     * Accepts Ethereum format (with or without 0x prefix) and returns backend format.
+     *
+     * @param address Ethereum address (0x... or plain 40 hex)
+     * @returns Backend format address (eth|...)
+     * @throws ValidationError if address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.toBackendFormat('0x1234567890abcdef...abcdef');
+     * // Returns: 'eth|1234567890abcdef...abcdef'
+     *
+     * formatter.toBackendFormat('1234567890abcdef...abcdef');
+     * // Returns: 'eth|1234567890abcdef...abcdef'
+     * ```
+     */
+    toBackendFormat(address: string): string;
+    /**
+     * Convert backend address format to Ethereum format
+     *
+     * Converts backend format (eth|...) to standard Ethereum format (0x...).
+     * Preserves the original case of the address portion (including EIP-55 checksummed addresses).
+     *
+     * @param address Backend format address (eth|...)
+     * @returns Ethereum format address (0x...)
+     * @throws ValidationError if address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.toEthereumFormat('eth|1234567890abcdef...abcdef');
+     * // Returns: '0x1234567890abcdef...abcdef'
+     *
+     * formatter.toEthereumFormat('eth|5aAeb6053f3E94C9b9A09f33669435E7Ef1BeAed');
+     * // Returns: '0x5aAeb6053f3E94C9b9A09f33669435E7Ef1BeAed' (preserves checksum case)
+     * ```
+     */
+    toEthereumFormat(address: string): string;
+    /**
+     * Smart address parser - accepts both Ethereum and backend formats
+     *
+     * Automatically detects format and converts to backend format required by SDK.
+     * Handles both "0x..." and "eth|..." formats seamlessly.
+     *
+     * @param address Address in either Ethereum or backend format
+     * @returns Backend format address (eth|...)
+     * @throws ValidationError if address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * // Ethereum format input
+     * formatter.normalizeInput('0x1234...abc');
+     * // Returns: 'eth|1234...abc'
+     *
+     * // Backend format input
+     * formatter.normalizeInput('eth|1234...abc');
+     * // Returns: 'eth|1234...abc' (unchanged)
+     *
+     * // Plain hex (with or without 0x)
+     * formatter.normalizeInput('1234...abc');
+     * // Returns: 'eth|1234...abc'
+     * ```
+     */
+    normalizeInput(address: string | undefined): AddressFormat | undefined;
+    /**
+     * Check if an address is valid (without throwing)
+     *
+     * Returns true if address is in valid Ethereum or backend format.
+     *
+     * @param address Address to check
+     * @returns true if valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * if (formatter.isValid('0x1234...abc')) {
+     *   // Process address
+     * }
+     * ```
+     */
+    isValid(address: string | undefined | null): address is string;
+    /**
+     * Validate address format, throwing on invalid
+     *
+     * @param address Address to validate
+     * @param fieldName Field name for error messages (default: 'address')
+     * @throws ValidationError if address is invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.assertValid(userAddress, 'userAddress');
+     * // Safe to use userAddress
+     * ```
+     */
+    assertValid(address: string | undefined, fieldName?: string): void;
+    /**
+     * Detect the format of an address string
+     *
+     * @param address Address string to check
+     * @returns Format type ('ethereum', 'backend', 'client') or null if invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.detectFormat('0x1234...abc');     // 'ethereum'
+     * formatter.detectFormat('eth|1234...abc');   // 'backend'
+     * formatter.detectFormat('client|xyz');       // 'client'
+     * formatter.detectFormat('invalid');          // null
+     * ```
+     */
+    detectFormat(address: string | undefined): AddressFormatType | null;
+    /**
+     * Normalize address casing (lowercase for consistency)
+     *
+     * Ethereum addresses can be checksummed, but we normalize to lowercase
+     * for consistency in comparisons and storage.
+     *
+     * @param address Address to normalize
+     * @returns Lowercase address
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.normalize('0xABCD...DCBA');
+     * // Returns: '0xabcd...dcba'
+     *
+     * formatter.normalize('ETH|ABCD...DCBA');
+     * // Returns: 'eth|abcd...dcba'
+     * ```
+     */
+    normalize(address: string | undefined): string | undefined;
+    /**
+     * Extract hex address from either format
+     *
+     * Returns just the 40-character hex portion without any prefix.
+     *
+     * @param address Ethereum or backend format address
+     * @returns 40-character hex string (lowercase)
+     * @throws ValidationError if address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const formatter = new AddressFormatter();
+     *
+     * formatter.extractHex('0x1234...abc');
+     * // Returns: '1234...abc'
+     *
+     * formatter.extractHex('eth|1234...abc');
+     * // Returns: '1234...abc'
+     * ```
+     */
+    extractHex(address: string): string;
+}
+export declare const stripHexPrefix: typeof bridgeStripHexPrefix;
+/**
+ * Convert Ethereum address to backend format (function style)
+ *
+ * @param address Ethereum address
+ * @returns Backend format
+ * @throws ValidationError if invalid
+ */
+export declare function toBackendAddressFormat(address: string): string;
+/**
+ * Convert backend address to Ethereum format (function style)
+ *
+ * @param address Backend format address
+ * @returns Ethereum format
+ * @throws ValidationError if invalid
+ */
+export declare function fromBackendAddressFormat(address: string): string;
+/**
+ * Smart address parser (function style)
+ *
+ * @param address Address to normalize
+ * @returns Backend format or undefined
+ */
+export declare function normalizeAddressInput(address: string | undefined): AddressFormat | undefined;
+/**
+ * Check if address is valid (function style)
+ *
+ * @param address Address to check
+ * @returns true if valid
+ */
+export declare function isValidAddress(address: string | undefined): address is string;
+/**
+ * Validate address and throw (function style)
+ *
+ * @param address Address to validate
+ * @param fieldName Field name for errors
+ * @throws ValidationError if invalid
+ */
+export declare function assertValidWalletAddress(address: string | undefined, fieldName?: string): void;
+/**
+ * Convert Ethereum address object (from ethers Wallet) to backend format
+ *
+ * Provides a convenient one-step conversion from ethers Wallet addresses to backend format.
+ * Handles both Wallet objects and plain addresses.
+ *
+ * @param ethAddress Ethereum address with or without 0x prefix, or ethers Wallet object
+ * @returns Backend format address (eth|...)
+ * @throws ValidationError if address format is invalid
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from 'ethers';
+ * import { toBackendAddressFromEthers } from '@/utils/address-formatter';
+ *
+ * const wallet = new Wallet(privateKey);
+ * const backendAddr = toBackendAddressFromEthers(wallet.address);
+ * // Returns: 'eth|1234567890abcdef...abcdef'
+ *
+ * // Also works with plain addresses
+ * const result = toBackendAddressFromEthers('0x1234...abc');
+ * // Returns: 'eth|1234...abc'
+ * ```
+ *
+ * @since 6.6.0
+ */
+export declare function toBackendAddressFromEthers(ethAddress: string | {
+    address: string;
+}): string;
+/**
+ * Detect the format of an address string (function style)
+ *
+ * @param address Address to check
+ * @returns Format type ('ethereum', 'backend', 'client') or null if invalid
+ */
+export declare function detectFormat(address: string | undefined): AddressFormatType | null;
+//# sourceMappingURL=address-formatter.d.ts.map

package/dist/src/utils/address-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-formatter.d.ts","sourceRoot":"","sources":["../../../src/utils/address-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE3F;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAwBlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAyBxC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IA+BzC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS;IAsBtE;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,IAAI,MAAM;IA4B9D;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI;IAU7E;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,GAAG,IAAI;IAwBnE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAQ1D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAoBpC;AAQD,eAAO,MAAM,cAAc,6BAAuB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,IAAI,MAAM,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAEzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG3F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,GAAG,IAAI,CAElF"}

package/dist/src/utils/agent-config.d.ts.map

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

package/dist/src/utils/amount-validator.d.ts

@@ -0,0 +1,268 @@
+/**
+ * AmountValidator - Comprehensive token amount validation utility
+ *
+ * Consolidates amount validation logic scattered across multiple services:
+ * - validateNumericString() from validation.ts
+ * - Amount range validation patterns
+ * - Decimal precision validation
+ * - Safe amount parsing and conversion
+ *
+ * ## Problem Solved
+ *
+ * Amount validation was duplicated across services:
+ * - validation.ts: `validateNumericString()` with inline error messages
+ * - GSwapService, BondingCurveService: Duplicate amount range checks
+ * - Multiple services: Inconsistent error messages for amount validation
+ *
+ * This utility provides a cohesive, reusable validation interface.
+ *
+ * @category Utilities
+ * @since 6.5.0
+ */
+import BigNumber from 'bignumber.js';
+/**
+ * Amount validation configuration
+ */
+export interface AmountValidationOptions {
+    /**
+     * Whether zero amounts are allowed (default: true)
+     */
+    allowZero?: boolean;
+    /**
+     * Minimum allowed amount (default: 0)
+     */
+    minimum?: string | number;
+    /**
+     * Maximum allowed amount (optional)
+     */
+    maximum?: string | number;
+    /**
+     * Maximum decimal places (default: 18)
+     */
+    maxDecimals?: number;
+    /**
+     * Custom field name for error messages (default: 'amount')
+     */
+    fieldName?: string;
+}
+/**
+ * AmountValidator - Comprehensive token amount validation
+ *
+ * Provides consistent, well-documented amount validation across all trading operations.
+ *
+ * ## Usage Examples
+ *
+ * ### Basic validation
+ * ```typescript
+ * const validator = new AmountValidator();
+ *
+ * // Validate with defaults (positive number)
+ * validator.validate('100');      // OK
+ * validator.validate('100.50');   // OK
+ * validator.validate('0');        // OK (zero allowed by default)
+ * validator.validate('abc');      // Throws - not numeric
+ * validator.validate('-100');     // Throws - negative
+ * ```
+ *
+ * ### With custom options
+ * ```typescript
+ * const validator = new AmountValidator();
+ *
+ * // No zero amounts allowed
+ * validator.validate('0', { allowZero: false });
+ * // Throws: "amount must be greater than zero"
+ *
+ * // Range validation
+ * validator.validate('50', {
+ *   minimum: '100',
+ *   maximum: '1000',
+ *   fieldName: 'trade amount'
+ * });
+ * // Throws: "trade amount must be at least 100"
+ * ```
+ *
+ * ### Decimal precision validation
+ * ```typescript
+ * const validator = new AmountValidator();
+ *
+ * // Strict decimal precision for USDC (2 decimals)
+ * validator.validate('123.456', { maxDecimals: 2, fieldName: 'USDC amount' });
+ * // Throws: "USDC amount cannot exceed 2 decimal places"
+ * ```
+ *
+ * ### Safe parsing
+ * ```typescript
+ * const validator = new AmountValidator();
+ *
+ * // Parse string amount to BigNumber
+ * const amount = validator.parseAmount('123.456');
+ * // Returns: BigNumber('123.456')
+ *
+ * // Parse with default fallback
+ * const amount = validator.parseAmount(undefined, '0');
+ * // Returns: BigNumber('0')
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare class AmountValidator {
+    /**
+     * Maximum allowed decimal places for amounts (18 = standard wei precision)
+     */
+    static readonly MAX_DECIMAL_PLACES = 18;
+    /**
+     * Minimum positive amount
+     */
+    static readonly MIN_POSITIVE = "0.00000000000000001";
+    /**
+     * Validate a numeric string amount
+     *
+     * Performs comprehensive validation to ensure the string represents a valid,
+     * non-negative (or positive) decimal number without edge cases that could
+     * cause calculation errors.
+     *
+     * Rejects:
+     * - Empty strings or whitespace-only strings
+     * - Non-numeric values (NaN, Infinity, -Infinity)
+     * - Scientific notation (e.g., '1e10')
+     * - Negative numbers (unless explicitly allowed)
+     * - Numbers exceeding maximum decimal places
+     * - Numbers outside specified min/max range
+     * - Invalid number formats
+     *
+     * @param amount The string amount to validate
+     * @param options Validation options (optional)
+     * @throws ValidationError if validation fails
+     *
+     * @example Basic validation
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * validator.validate('100.50', { fieldName: 'amount' }); // OK
+     * validator.validate('0', { fieldName: 'amount' }); // OK (zero allowed)
+     * validator.validate('   ', { fieldName: 'amount' }); // Throws: whitespace-only
+     * validator.validate('1e10', { fieldName: 'amount' }); // Throws: scientific notation
+     * validator.validate('-50', { fieldName: 'amount' }); // Throws: negative
+     * ```
+     *
+     * @example With range validation
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * validator.validate('500', {
+     *   fieldName: 'stake amount',
+     *   minimum: '100',
+     *   maximum: '1000'
+     * }); // OK
+     *
+     * validator.validate('50', {
+     *   fieldName: 'stake amount',
+     *   minimum: '100'
+     * }); // Throws: below minimum
+     * ```
+     *
+     * @example Token-specific precision
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * // GALA has 8 decimals
+     * validator.validate('123.12345678', {
+     *   fieldName: 'GALA amount',
+     *   maxDecimals: 8
+     * }); // OK
+     *
+     * // USDC has 6 decimals
+     * validator.validate('123.1234567', {
+     *   fieldName: 'USDC amount',
+     *   maxDecimals: 6
+     * }); // Throws: exceeds precision
+     * ```
+     */
+    validate(amount: string, options?: AmountValidationOptions): void;
+    /**
+     * Parse a string amount to BigNumber with fallback
+     *
+     * Safe parsing that applies a fallback value if input is null/undefined/invalid.
+     * Delegates to toBigNumber from bignumber-helpers for consistency.
+     *
+     * @param amount Amount string to parse
+     * @param fallback Fallback value if amount is invalid (default: '0')
+     * @returns BigNumber instance
+     *
+     * @example
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * const amount1 = validator.parseAmount('123.45');    // BigNumber('123.45')
+     * const amount2 = validator.parseAmount(undefined);    // BigNumber('0')
+     * const amount3 = validator.parseAmount(null, '100');  // BigNumber('100')
+     * ```
+     */
+    parseAmount(amount: string | undefined | null, fallback?: string | number): BigNumber;
+    /**
+     * Check if amount is valid without throwing
+     *
+     * @param amount Amount string to check
+     * @param options Validation options (optional)
+     * @returns true if valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * if (validator.isValid('100.50')) {
+     *   // Process amount
+     * } else {
+     *   // Show error to user
+     * }
+     * ```
+     */
+    isValid(amount: string | undefined | null, options?: AmountValidationOptions): boolean;
+    /**
+     * Format amount as string with specific decimal places
+     *
+     * Removes trailing zeros and unnecessary decimal point.
+     * Delegates to toBigNumberFixed from bignumber-helpers for consistency.
+     *
+     * @param amount Amount string or BigNumber
+     * @param decimals Number of decimal places (default: auto)
+     * @returns Formatted string
+     *
+     * @example
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * validator.formatAmount('100.5000');        // "100.5"
+     * validator.formatAmount('100', 2);          // "100"
+     * validator.formatAmount('100.123456', 2);   // "100.12"
+     * ```
+     */
+    formatAmount(amount: string | BigNumber, decimals?: number): string;
+    /**
+     * Ensure amount is within valid range
+     *
+     * Clamps amount between minimum and maximum (if specified).
+     * Uses toBigNumber from bignumber-helpers for consistent parsing.
+     *
+     * @param amount Amount to clamp
+     * @param minimum Minimum value
+     * @param maximum Maximum value
+     * @returns Clamped amount as string
+     *
+     * @example
+     * ```typescript
+     * const validator = new AmountValidator();
+     *
+     * const clamped = validator.clampAmount('500', '100', '1000');
+     * // Returns: "500"
+     *
+     * const clamped2 = validator.clampAmount('50', '100', '1000');
+     * // Returns: "100" (below minimum, clamped)
+     *
+     * const clamped3 = validator.clampAmount('2000', '100', '1000');
+     * // Returns: "1000" (above maximum, clamped)
+     * ```
+     */
+    clampAmount(amount: string | number, minimum: string | number, maximum: string | number): string;
+}
+//# sourceMappingURL=amount-validator.d.ts.map

package/dist/src/utils/amount-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/amount-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,SAAS,MAAM,cAAc,CAAC;AAYrC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,kBAAkB,MAAM;IAExC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,YAAY,yBAAyB;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,IAAI;IAoGrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,QAAQ,GAAE,MAAM,GAAG,MAAY,GAAG,SAAS;IAK1F;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO;IAY1F;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAKnE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAcjG"}