@sequence0/sdk 1.0.0 → 1.0.2

package/dist/utils/fee.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Fee Manager
+ *
+ * Reads the FeeCollector contract on the Sequence0 chain to provide fee
+ * information and build unsigned fee-payment transactions. The actual fee
+ * payment (signing and sending the TX) is the app developer's responsibility
+ * -- they must have S0 native tokens on the Sequence0 chain (800801).
+ *
+ * Fully decentralized: reads directly from on-chain contracts, no backend.
+ *
+ * @example
+ * ```typescript
+ * const fee = new FeeManager({
+ *     rpcUrl: 'https://rpc.sequence0.network',
+ *     feeCollectorAddress: '0x24963595AdEbf6608Dd20DDBfcEf7D5931a595D9',
+ *     registryAddress: '0x84E44eD38E30FD1F0ec37D88AbAAE831A90C610E',
+ * });
+ *
+ * // Get the current per-signature fee
+ * const feeWei = await fee.getSignatureFee();
+ *
+ * // Build an unsigned fee TX for a wallet's committee
+ * const tx = await fee.buildCollectFeeTx('my-wallet', ['0xAgent1', '0xAgent2']);
+ * // => { to, data, value } -- sign and send with your own wallet
+ * ```
+ */
+export interface FeeManagerOptions {
+    /** Sequence0 chain RPC URL */
+    rpcUrl: string;
+    /** FeeCollector proxy contract address */
+    feeCollectorAddress: string;
+    /** AgentRegistry proxy contract address (for resolving peer IDs to payment addresses) */
+    registryAddress: string;
+    /** Fee cache TTL in ms (default: 300000 = 5 minutes) */
+    cacheTtl?: number;
+}
+/** Unsigned transaction object that the app developer signs and sends */
+export interface UnsignedFeeTx {
+    /** FeeCollector contract address */
+    to: string;
+    /** ABI-encoded calldata for collectFee(walletId, agents) */
+    data: string;
+    /** Fee amount in wei (hex string) */
+    value: string;
+}
+export declare class FeeManager {
+    private rpcUrl;
+    private feeCollectorAddress;
+    private registryAddress;
+    private cacheTtl;
+    private feeCache;
+    constructor(options: FeeManagerOptions);
+    /**
+     * Get the current per-signature fee from the FeeCollector contract.
+     * Result is cached for 5 minutes (configurable via cacheTtl).
+     *
+     * @returns Fee in wei as a bigint
+     */
+    getSignatureFee(): Promise<bigint>;
+    /**
+     * Build an unsigned collectFee transaction.
+     *
+     * The app developer must sign and send this transaction on the Sequence0
+     * chain (800801) using their own wallet/signer. They need S0 native tokens
+     * to cover the fee.
+     *
+     * @param walletId - The Sequence0 wallet ID being signed for
+     * @param agents - Array of agent Ethereum addresses (payment addresses)
+     * @returns Unsigned transaction { to, data, value }
+     */
+    buildCollectFeeTx(walletId: string, agents: string[]): Promise<UnsignedFeeTx>;
+    /**
+     * Resolve committee peer IDs to their Ethereum payment addresses
+     * by reading the AgentRegistry contract.
+     *
+     * @param peerIds - Array of libp2p peer IDs from a wallet's committee
+     * @returns Array of Ethereum payment addresses (same order; empty string if not found)
+     */
+    resolveAgentPaymentAddresses(peerIds: string[]): Promise<string[]>;
+    /**
+     * Invalidate the cached fee so the next call re-fetches from chain.
+     */
+    clearCache(): void;
+    /**
+     * Look up a single agent's payment address from the AgentRegistry.
+     * The `agents(string)` public mapping getter returns the Agent struct.
+     *
+     * Struct layout:
+     *   string multiaddr        (dynamic, offset at slot 0)
+     *   address paymentAddress   (slot 1)
+     *   uint256 registeredAt     (slot 2)
+     *   uint256 lastHeartbeat    (slot 3)
+     *   bool isActive            (slot 4)
+     *   uint64 heartbeatCount    (packed in slot 4)
+     *   uint64 signaturesParticipated (packed in slot 4)
+     */
+    private getAgentPaymentAddress;
+    /**
+     * ABI-encode calldata for collectFee(string walletId, address[] agents)
+     */
+    private encodeCollectFee;
+    /**
+     * Make an eth_call to the Sequence0 chain RPC.
+     */
+    private ethCall;
+}
+//# sourceMappingURL=fee.d.ts.map

package/dist/utils/fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/utils/fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAgBH,MAAM,WAAW,iBAAiB;IAC9B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC1B,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAmD;gBAEvD,OAAO,EAAE,iBAAiB;IAOtC;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAsBxC;;;;;;;;;;OAUG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBnF;;;;;;OAMG;IACG,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAYxE;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;;;;;;;;;OAYG;YACW,sBAAsB;IAsCpC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0CxB;;OAEG;YACW,OAAO;CAoBxB"}

package/dist/utils/fee.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Fee Manager
+ *
+ * Reads the FeeCollector contract on the Sequence0 chain to provide fee
+ * information and build unsigned fee-payment transactions. The actual fee
+ * payment (signing and sending the TX) is the app developer's responsibility
+ * -- they must have S0 native tokens on the Sequence0 chain (800801).
+ *
+ * Fully decentralized: reads directly from on-chain contracts, no backend.
+ *
+ * @example
+ * ```typescript
+ * const fee = new FeeManager({
+ *     rpcUrl: 'https://rpc.sequence0.network',
+ *     feeCollectorAddress: '0x24963595AdEbf6608Dd20DDBfcEf7D5931a595D9',
+ *     registryAddress: '0x84E44eD38E30FD1F0ec37D88AbAAE831A90C610E',
+ * });
+ *
+ * // Get the current per-signature fee
+ * const feeWei = await fee.getSignatureFee();
+ *
+ * // Build an unsigned fee TX for a wallet's committee
+ * const tx = await fee.buildCollectFeeTx('my-wallet', ['0xAgent1', '0xAgent2']);
+ * // => { to, data, value } -- sign and send with your own wallet
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeeManager = void 0;
+const errors_1 = require("./errors");
+/** FeeCollector contract: signatureFee() returns uint256 */
+const SIGNATURE_FEE_SELECTOR = '0x19b234f4';
+/** FeeCollector contract: collectFee(string walletId, address[] agents) */
+const COLLECT_FEE_SELECTOR = '0xddd9c849';
+/** AgentRegistry contract: agents(string peerId) returns Agent struct */
+const AGENTS_SELECTOR = '0xcf6ee0cb';
+/** Cache TTL for the signature fee (5 minutes) */
+const FEE_CACHE_TTL = 5 * 60 * 1000;
+class FeeManager {
+    constructor(options) {
+        this.feeCache = null;
+        this.rpcUrl = options.rpcUrl;
+        this.feeCollectorAddress = options.feeCollectorAddress;
+        this.registryAddress = options.registryAddress;
+        this.cacheTtl = options.cacheTtl ?? FEE_CACHE_TTL;
+    }
+    /**
+     * Get the current per-signature fee from the FeeCollector contract.
+     * Result is cached for 5 minutes (configurable via cacheTtl).
+     *
+     * @returns Fee in wei as a bigint
+     */
+    async getSignatureFee() {
+        if (this.feeCache && Date.now() - this.feeCache.timestamp < this.cacheTtl) {
+            return this.feeCache.fee;
+        }
+        const result = await this.ethCall(this.feeCollectorAddress, SIGNATURE_FEE_SELECTOR);
+        if (!result || result === '0x') {
+            throw new errors_1.NetworkError('Failed to read signatureFee from FeeCollector contract');
+        }
+        // Result is a single uint256
+        const hex = result.startsWith('0x') ? result.slice(2) : result;
+        const fee = BigInt('0x' + hex);
+        this.feeCache = { fee, timestamp: Date.now() };
+        return fee;
+    }
+    /**
+     * Build an unsigned collectFee transaction.
+     *
+     * The app developer must sign and send this transaction on the Sequence0
+     * chain (800801) using their own wallet/signer. They need S0 native tokens
+     * to cover the fee.
+     *
+     * @param walletId - The Sequence0 wallet ID being signed for
+     * @param agents - Array of agent Ethereum addresses (payment addresses)
+     * @returns Unsigned transaction { to, data, value }
+     */
+    async buildCollectFeeTx(walletId, agents) {
+        if (!walletId || typeof walletId !== 'string') {
+            throw new Error('walletId must be a non-empty string');
+        }
+        if (!agents || agents.length === 0) {
+            throw new Error('agents array must not be empty');
+        }
+        const fee = await this.getSignatureFee();
+        const data = this.encodeCollectFee(walletId, agents);
+        return {
+            to: this.feeCollectorAddress,
+            data,
+            value: '0x' + fee.toString(16),
+        };
+    }
+    /**
+     * Resolve committee peer IDs to their Ethereum payment addresses
+     * by reading the AgentRegistry contract.
+     *
+     * @param peerIds - Array of libp2p peer IDs from a wallet's committee
+     * @returns Array of Ethereum payment addresses (same order; empty string if not found)
+     */
+    async resolveAgentPaymentAddresses(peerIds) {
+        const addresses = [];
+        for (const peerId of peerIds) {
+            const address = await this.getAgentPaymentAddress(peerId);
+            addresses.push(address);
+        }
+        // Filter out empty/zero addresses
+        return addresses.filter((a) => a !== '' && a !== '0x0000000000000000000000000000000000000000');
+    }
+    /**
+     * Invalidate the cached fee so the next call re-fetches from chain.
+     */
+    clearCache() {
+        this.feeCache = null;
+    }
+    // ── Internals ──
+    /**
+     * Look up a single agent's payment address from the AgentRegistry.
+     * The `agents(string)` public mapping getter returns the Agent struct.
+     *
+     * Struct layout:
+     *   string multiaddr        (dynamic, offset at slot 0)
+     *   address paymentAddress   (slot 1)
+     *   uint256 registeredAt     (slot 2)
+     *   uint256 lastHeartbeat    (slot 3)
+     *   bool isActive            (slot 4)
+     *   uint64 heartbeatCount    (packed in slot 4)
+     *   uint64 signaturesParticipated (packed in slot 4)
+     */
+    async getAgentPaymentAddress(peerId) {
+        // ABI-encode: agents(string peerId)
+        // Function selector + offset to string data (0x20) + string length + string data
+        const peerIdHex = Buffer.from(peerId, 'utf8').toString('hex');
+        const peerIdLen = peerId.length.toString(16).padStart(64, '0');
+        const peerIdPadded = peerIdHex.padEnd(Math.ceil(peerIdHex.length / 64) * 64, '0');
+        const offset = '0000000000000000000000000000000000000000000000000000000000000020';
+        const calldata = AGENTS_SELECTOR + offset + peerIdLen + peerIdPadded;
+        try {
+            const result = await this.ethCall(this.registryAddress, calldata);
+            if (!result || result === '0x' || result.length < 130) {
+                return '';
+            }
+            // The return is an ABI-encoded struct. For a Solidity public mapping
+            // getter returning the struct, the encoding is:
+            //   word 0: offset to multiaddr string (dynamic)
+            //   word 1: paymentAddress (address, right-aligned in 32 bytes)
+            //   word 2: registeredAt (uint256)
+            //   word 3: lastHeartbeat (uint256)
+            //   word 4: isActive + heartbeatCount + signaturesParticipated (packed)
+            //   ... then the string data for multiaddr
+            const data = result.startsWith('0x') ? result.slice(2) : result;
+            // paymentAddress is at word index 1 (bytes 64..128)
+            const addressWord = data.slice(64, 128);
+            // Address is the last 40 hex chars (20 bytes)
+            const address = '0x' + addressWord.slice(24);
+            return address;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * ABI-encode calldata for collectFee(string walletId, address[] agents)
+     */
+    encodeCollectFee(walletId, agents) {
+        // collectFee has two dynamic params: string and address[]
+        // ABI encoding:
+        //   4 bytes: selector
+        //   word 0: offset to walletId string data
+        //   word 1: offset to agents array data
+        //   ... walletId string encoding (length + padded data)
+        //   ... agents array encoding (length + addresses)
+        const walletIdHex = Buffer.from(walletId, 'utf8').toString('hex');
+        const walletIdLen = walletId.length;
+        const walletIdPadded = walletIdHex.padEnd(Math.ceil(walletIdHex.length / 64) * 64, '0');
+        const walletIdWords = Math.max(1, Math.ceil(walletIdHex.length / 64));
+        // Offset to walletId data: 2 words (for the two offsets) = 0x40
+        const offsetWalletId = '0000000000000000000000000000000000000000000000000000000000000040';
+        // Offset to agents data: 0x40 + 0x20 (walletId length word) + walletIdWords * 0x20
+        const agentsOffset = 64 + 32 + walletIdWords * 32; // in bytes
+        const offsetAgents = agentsOffset.toString(16).padStart(64, '0');
+        // WalletId encoding: length (32 bytes) + padded string data
+        const walletIdLenHex = walletIdLen.toString(16).padStart(64, '0');
+        const walletIdEncoded = walletIdLenHex + walletIdPadded;
+        // Agents encoding: length (32 bytes) + each address padded to 32 bytes
+        const agentsLen = agents.length.toString(16).padStart(64, '0');
+        const agentsEncoded = agents.map((addr) => {
+            const clean = addr.startsWith('0x') ? addr.slice(2) : addr;
+            return clean.toLowerCase().padStart(64, '0');
+        }).join('');
+        return (COLLECT_FEE_SELECTOR +
+            offsetWalletId +
+            offsetAgents +
+            walletIdEncoded +
+            agentsLen +
+            agentsEncoded);
+    }
+    /**
+     * Make an eth_call to the Sequence0 chain RPC.
+     */
+    async ethCall(to, data) {
+        const callData = data.startsWith('0x') ? data : '0x' + data;
+        const res = await fetch(this.rpcUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'eth_call',
+                params: [{ to, data: callData }, 'latest'],
+                id: 1,
+            }),
+        });
+        const json = (await res.json());
+        if (json.error) {
+            throw new errors_1.NetworkError(`Contract call failed: ${json.error.message}`);
+        }
+        return json.result;
+    }
+}
+exports.FeeManager = FeeManager;
+//# sourceMappingURL=fee.js.map

package/dist/utils/fee.js.map

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

package/dist/utils/http.d.ts

@@ -1,8 +1,77 @@
 /**
  * Lightweight HTTP client for Sequence0 agent node REST API
  *
- * Uses native fetch — works in Node.js 18+ and all modern browsers.
+ * Uses native fetch -- works in Node.js 18+ and all modern browsers.
+ * Includes client-side rate limiting, automatic retries with exponential
+ * backoff, request/response debug logging, response validation, and
+ * a per-host circuit breaker to fail fast on unreachable agents.
  */
+import { Sequence0Error } from './errors';
+import { RateLimiterOptions } from './rate-limiter';
+import { Logger } from './logger';
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Thrown when a request is rejected because the circuit breaker is OPEN.
+ * The caller should select a different agent or wait for the cooldown.
+ */
+export declare class CircuitBreakerError extends Sequence0Error {
+    host: string;
+    timeUntilHalfOpen: number;
+    constructor(host: string, timeUntilHalfOpen: number);
+}
+export interface CircuitBreakerOptions {
+    /** Consecutive failures before tripping OPEN (default: 3) */
+    failureThreshold?: number;
+    /** Cooldown in ms before moving from OPEN to HALF_OPEN (default: 30000) */
+    cooldownMs?: number;
+}
+/**
+ * Per-host circuit breaker.
+ *
+ * States:
+ *   CLOSED   — normal operation, requests pass through
+ *   OPEN     — failing, requests are rejected immediately
+ *   HALF_OPEN — testing recovery, one request is allowed through
+ *
+ * Transitions:
+ *   CLOSED   → OPEN      after `failureThreshold` consecutive failures
+ *   OPEN     → HALF_OPEN after `cooldownMs` elapses
+ *   HALF_OPEN → CLOSED   on first success
+ *   HALF_OPEN → OPEN     on first failure
+ */
+export declare class CircuitBreaker {
+    private states;
+    private failureCounts;
+    private lastFailureTimes;
+    private failureThreshold;
+    private cooldownMs;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Check whether a request to the given host is allowed.
+     * Throws CircuitBreakerError if the circuit is OPEN and cooldown has not elapsed.
+     */
+    allowRequest(host: string): void;
+    /**
+     * Record a successful request. Resets the circuit to CLOSED.
+     */
+    recordSuccess(host: string): void;
+    /**
+     * Record a failed request. Increments failure count and may trip the circuit.
+     */
+    recordFailure(host: string): void;
+    /**
+     * Get the current state for a host (defaults to CLOSED).
+     */
+    getState(host: string): CircuitState;
+    /**
+     * Reset the circuit breaker for a specific host.
+     */
+    reset(host: string): void;
+    /**
+     * Reset all circuit breakers.
+     */
+    resetAll(): void;
+}
 export interface HttpOptions {
     /** Base URL of the agent node (e.g. http://3.140.248.117:8080) */
     baseUrl: string;
@@ -10,14 +79,41 @@ export interface HttpOptions {
     timeout?: number;
     /** Additional headers */
     headers?: Record<string, string>;
+    /** Max retry attempts on transient failures (default: 3) */
+    maxRetries?: number;
+    /** Client-side rate limiting options */
+    rateLimiter?: RateLimiterOptions | false;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom logger instance (overrides debug flag) */
+    logger?: Logger;
+    /** Circuit breaker instance (shared across HttpClient instances for per-host tracking) */
+    circuitBreaker?: CircuitBreaker;
+    /** Enable HTTP keep-alive for connection reuse (default: true) */
+    keepAlive?: boolean;
+    /** Keep-alive timeout in ms (default: 30000) */
+    keepAliveTimeout?: number;
 }
 export declare class HttpClient {
     private baseUrl;
+    private host;
     private timeout;
     private headers;
+    private maxRetries;
+    private rateLimiter;
+    private logger;
+    private circuitBreaker;
     constructor(options: HttpOptions);
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Destroy internal resources (rate limiter timers, etc.)
+     */
+    destroy(): void;
+    /**
+     * Request with circuit breaker check, automatic retries, and exponential backoff.
+     */
+    private requestWithRetry;
     private request;
 }
 //# sourceMappingURL=http.d.ts.map

package/dist/utils/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,WAAW;IACxB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,qBAAa,UAAU;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAyB;gBAE5B,OAAO,EAAE,WAAW;IAS1B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;YAIzC,OAAO;CAuCxB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAA8B,cAAc,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAe,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,MAAM,EAA2B,MAAM,UAAU,CAAC;AAI3D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IAExC,IAAI,EAAE,MAAM;IACZ,iBAAiB,EAAE,MAAM;gBADzB,IAAI,EAAE,MAAM,EACZ,iBAAiB,EAAE,MAAM;CAQvC;AAED,MAAM,WAAW,qBAAqB;IAClC,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,qBAA0B;IAK/C;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAmBhC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAoBjC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAIpC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMzB;;OAEG;IACH,QAAQ,IAAI,IAAI;CAKnB;AAOD,MAAM,WAAW,WAAW;IACxB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,WAAW,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;IACzC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,qBAAa,UAAU;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAwB;gBAElC,OAAO,EAAE,WAAW;IAiD1B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;OAEG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;YACW,gBAAgB;YAuDhB,OAAO;CA+ExB"}