@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/protocol/EASHelper.js

@@ -2,18 +2,62 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EASHelper = void 0;
 const ethers_1 = require("ethers");
+const eas_sdk_1 = require("@ethereum-attestation-service/eas-sdk");
 const eip712_1 = require("../types/eip712");
-const EAS_ABI = [
-    'event Attested(address indexed attester, bytes32 indexed uid, bytes32 indexed schema)',
-    'function attest(tuple(bytes32 schema, tuple(address recipient, uint64 expirationTime, bool revocable, bytes32 refUID, bytes data) data) request) external returns (bytes32)',
-    'function revoke(tuple(bytes32 schema, bytes32 uid) request) external returns (bytes32)',
-    'function getAttestation(bytes32 uid) external view returns (tuple(bytes32 uid, bytes32 schema, address recipient, address attester, uint64 time, uint64 expirationTime, bool revocable, bytes32 refUID, bytes data, uint32 bump))'
-];
+const UsedAttestationTracker_1 = require("../utils/UsedAttestationTracker");
+/**
+ * EASHelper - utility wrapper for Ethereum Attestation Service interactions
+ */
 class EASHelper {
-    constructor(signer, config) {
+    /**
+     * Create EASHelper instance
+     *
+     * @param signer - Ethers signer for signing attestations
+     * @param config - EAS configuration
+     * @param attestationTracker - Optional tracker for replay attack prevention (C-1 fix)
+     *
+     * SECURITY FIX (NEW-M-2): Validates schema UID format in constructor
+     */
+    constructor(signer, config, attestationTracker) {
         this.config = config;
-        this.eas = new ethers_1.Contract(config.contractAddress, EAS_ABI, signer);
+        // SECURITY FIX (NEW-M-2): Validate schema UID format
+        if (!config.deliveryProofSchemaId || !/^0x[a-fA-F0-9]{64}$/.test(config.deliveryProofSchemaId)) {
+            throw new Error(`Invalid deliveryProofSchemaId: must be bytes32 hex string (0x...). ` +
+                `Got: ${config.deliveryProofSchemaId}`);
+        }
+        if (config.deliveryProofSchemaId === '0x0000000000000000000000000000000000000000000000000000000000000000') {
+            throw new Error('deliveryProofSchemaId cannot be zero bytes32');
+        }
+        // Use official EAS SDK wrapper to ensure ABI correctness across deployments
+        // (includes fields like revocationTime that are required for security checks).
+        this.eas = new eas_sdk_1.EAS(config.contractAddress);
+        this.eas.connect(signer);
+        // SECURITY FIX (C-1): Use provided tracker or create new in-memory one
+        if (!attestationTracker) {
+            // SECURITY WARNING (HIGH-5): In-memory tracker does not persist across restarts!
+            // For production use, provide a FileBasedUsedAttestationTracker with a stateDirectory:
+            //
+            //   import { FileBasedUsedAttestationTracker } from '../utils/UsedAttestationTracker';
+            //   const tracker = new FileBasedUsedAttestationTracker('/path/to/state');
+            //   const easHelper = new EASHelper(signer, config, tracker);
+            //
+            // Without persistence, attestation replay protection is lost on process restart,
+            // allowing potential double-spend attacks.
+            console.warn('[SECURITY WARNING] EASHelper: Using in-memory attestation tracker. ' +
+                'Replay protection will be lost on process restart. ' +
+                'For production, provide FileBasedUsedAttestationTracker for persistence.');
+        }
+        this.attestationTracker = attestationTracker || new UsedAttestationTracker_1.InMemoryUsedAttestationTracker();
     }
+    /**
+     * Get the attestation tracker for external use
+     */
+    getAttestationTracker() {
+        return this.attestationTracker;
+    }
+    /**
+     * Create an attestation for a delivery proof. Returns the attestation UID and transaction hash.
+     */
     async attestDeliveryProof(proof, recipient, options) {
         const { expirationTime = 0, revocable = true } = options || {};
         const proofData = (0, eip712_1.deliveryProofDataFromProof)(proof);
@@ -30,77 +74,226 @@ class EASHelper {
             schema: this.config.deliveryProofSchemaId,
             data: {
                 recipient,
-                expirationTime,
+                expirationTime: BigInt(expirationTime),
                 revocable,
                 refUID: proof.txId,
-                data: encodedData
-            }
-        });
-        const receipt = await tx.wait();
-        const attestedLog = receipt?.logs?.find((log) => {
-            try {
-                const parsed = this.eas.interface.parseLog(log);
-                return parsed?.name === 'Attested';
-            }
-            catch {
-                return false;
+                data: encodedData,
+                // For Base EAS, value is typically 0. Keep explicit to avoid ambiguity.
+                value: 0n
             }
         });
-        const uid = attestedLog
-            ? this.eas.interface.parseLog(attestedLog)?.args?.uid
-            : (0, ethers_1.zeroPadValue)('0x00', 32);
+        const uid = await tx.wait();
+        if (!uid || !/^0x[a-fA-F0-9]{64}$/.test(uid)) {
+            throw new Error(`Failed to obtain attestation UID from EAS transaction. Got: ${String(uid)}`);
+        }
+        if (uid === '0x0000000000000000000000000000000000000000000000000000000000000000') {
+            throw new Error('EAS returned zero UID for attestation (unexpected).');
+        }
         return {
             uid,
-            transactionHash: receipt.transactionHash
+            transactionHash: tx.tx.hash
         };
     }
+    /**
+     * Revoke a previously issued attestation by UID.
+     */
     async revokeAttestation(uid) {
+        if (!uid || !/^0x[a-fA-F0-9]{64}$/.test(uid)) {
+            throw new Error(`Invalid attestation UID format: ${uid}`);
+        }
         const tx = await this.eas.revoke({
             schema: this.config.deliveryProofSchemaId,
-            uid
+            data: { uid }
         });
-        const receipt = await tx.wait();
-        return receipt.transactionHash;
+        await tx.wait();
+        return tx.tx.hash;
     }
+    /**
+     * Fetch attestation data from the EAS contract.
+     */
     async getAttestation(uid) {
+        if (!uid || !/^0x[a-fA-F0-9]{64}$/.test(uid)) {
+            throw new Error(`Invalid attestation UID format: ${uid}`);
+        }
         return await this.eas.getAttestation(uid);
     }
+    /**
+     * Verify that a delivery attestation belongs to the specified transaction.
+     *
+     * SECURITY: ACTPKernel V1 accepts any bytes32 as attestationUID without validation.
+     * This means a malicious provider could submit attestation from Transaction A
+     * for Transaction B. This method provides SDK-side protection by verifying:
+     *
+     * 1. Attestation exists and is not revoked
+     * 2. Attestation uses the canonical delivery schema UID
+     * 3. Attestation's txId matches the expected transaction ID
+     * 4. Attestation has not expired
+     *
+     * @param txId - Expected transaction ID (bytes32)
+     * @param attestationUID - Attestation UID to verify (bytes32)
+     * @returns true if attestation is valid for this transaction, false otherwise
+     * @throws Error if attestation is revoked, expired, schema mismatch, or txId mismatch
+     */
     async verifyDeliveryAttestation(txId, attestationUID) {
+        if (!txId || !/^0x[a-fA-F0-9]{64}$/.test(txId)) {
+            throw new Error(`Invalid txId format (expected bytes32): ${txId}`);
+        }
+        if (!attestationUID || !/^0x[a-fA-F0-9]{64}$/.test(attestationUID)) {
+            throw new Error(`Invalid attestationUID format (expected bytes32): ${attestationUID}`);
+        }
+        // 1. Fetch attestation from EAS contract
         const attestation = await this.eas.getAttestation(attestationUID);
+        // 2. Check if attestation exists (uid should match)
         if (attestation.uid !== attestationUID) {
             throw new Error(`Attestation not found: ${attestationUID}`);
         }
+        // 3. Check schema UID matches canonical delivery schema (B2 blocker fix)
+        // This prevents accepting attestations from unrelated EAS schemas
         if (attestation.schema !== this.config.deliveryProofSchemaId) {
             throw new Error(`Schema UID mismatch: expected canonical delivery schema ${this.config.deliveryProofSchemaId}, ` +
                 `got ${attestation.schema}. Attestation may be from a different schema!`);
         }
-        const isRevoked = attestation.revocationTime > 0n;
+        // 4. Check revocation - EAS uses revocationTime field (not revoked boolean)
+        // revocationTime = 0 means not revoked
+        // revocationTime > 0 means revoked at that timestamp
+        const revocationTime = BigInt(attestation.revocationTime ?? 0);
+        const isRevoked = revocationTime > 0n;
         if (isRevoked) {
-            throw new Error(`Attestation has been revoked: ${attestationUID} (revoked at timestamp ${attestation.revocationTime})`);
+            throw new Error(`Attestation has been revoked: ${attestationUID} (revoked at timestamp ${revocationTime})`);
         }
-        if (attestation.expirationTime > 0n) {
+        // 5. Check expiration
+        // expirationTime = 0 means no expiration
+        // expirationTime > 0 means expires at that timestamp
+        const expirationTime = BigInt(attestation.expirationTime ?? 0);
+        if (expirationTime > 0n) {
             const now = Math.floor(Date.now() / 1000);
-            if (Number(attestation.expirationTime) < now) {
-                throw new Error(`Attestation has expired: ${attestationUID} (expired at ${attestation.expirationTime})`);
+            if (Number(expirationTime) < now) {
+                throw new Error(`Attestation has expired: ${attestationUID} (expired at ${expirationTime})`);
             }
         }
-        let attestedTxId;
+        // 6. Decode attestation data to extract txId
+        let attestedTxId = '';
         try {
             const abiCoder = ethers_1.AbiCoder.defaultAbiCoder();
-            const decoded = abiCoder.decode(['bytes32', 'bytes32', 'uint256', 'string', 'uint256', 'string'], attestation.data);
-            attestedTxId = decoded[0];
+            const rawData = attestation.data;
+            // Prefer AIP-6 decoding (current DX Playground schema)
+            // - Official AIP-6: bytes32 txId,string resultCID,bytes32 resultHash,uint256 deliveredAt
+            // - Test schema:    + uint256 testTimestamp
+            try {
+                const decoded = abiCoder.decode(['bytes32', 'string', 'bytes32', 'uint256', 'uint256'], rawData);
+                attestedTxId = decoded[0];
+                const resultCID = decoded[1];
+                const resultHash = decoded[2];
+                const deliveredAt = decoded[3];
+                if (!attestedTxId || !/^0x[a-fA-F0-9]{64}$/.test(attestedTxId)) {
+                    throw new Error(`Decoded txId is not valid bytes32: ${attestedTxId}`);
+                }
+                if (typeof resultCID !== 'string' || resultCID.length === 0 || resultCID.length > 2048) {
+                    throw new Error(`Decoded resultCID invalid length: ${resultCID?.length}`);
+                }
+                if (!resultHash || !/^0x[a-fA-F0-9]{64}$/.test(resultHash)) {
+                    throw new Error(`Decoded resultHash is not valid bytes32: ${resultHash}`);
+                }
+                const now = BigInt(Math.floor(Date.now() / 1000));
+                if (deliveredAt > now + 86400n) {
+                    throw new Error(`Decoded deliveredAt is in far future: ${deliveredAt.toString()}`);
+                }
+            }
+            catch (_e) {
+                // Fallback: official AIP-6 schema without testTimestamp
+                try {
+                    const decoded = abiCoder.decode(['bytes32', 'string', 'bytes32', 'uint256'], rawData);
+                    attestedTxId = decoded[0];
+                    const resultCID = decoded[1];
+                    const resultHash = decoded[2];
+                    const deliveredAt = decoded[3];
+                    if (!attestedTxId || !/^0x[a-fA-F0-9]{64}$/.test(attestedTxId)) {
+                        throw new Error(`Decoded txId is not valid bytes32: ${attestedTxId}`);
+                    }
+                    if (typeof resultCID !== 'string' || resultCID.length === 0 || resultCID.length > 2048) {
+                        throw new Error(`Decoded resultCID invalid length: ${resultCID?.length}`);
+                    }
+                    if (!resultHash || !/^0x[a-fA-F0-9]{64}$/.test(resultHash)) {
+                        throw new Error(`Decoded resultHash is not valid bytes32: ${resultHash}`);
+                    }
+                    const now = BigInt(Math.floor(Date.now() / 1000));
+                    if (deliveredAt > now + 86400n) {
+                        throw new Error(`Decoded deliveredAt is in far future: ${deliveredAt.toString()}`);
+                    }
+                }
+                catch (__e) {
+                    // Final fallback: legacy AIP-4 schema
+                    // Schema: bytes32 txId, bytes32 contentHash, uint256 timestamp, string deliveryUrl, uint256 size, string mimeType
+                    const decoded = abiCoder.decode(['bytes32', 'bytes32', 'uint256', 'string', 'uint256', 'string'], rawData);
+                    attestedTxId = decoded[0];
+                    const contentHash = decoded[1];
+                    const timestamp = decoded[2];
+                    const deliveryUrl = decoded[3];
+                    const size = decoded[4];
+                    const mimeType = decoded[5];
+                    if (!attestedTxId || !/^0x[a-fA-F0-9]{64}$/.test(attestedTxId)) {
+                        throw new Error(`Decoded txId is not valid bytes32: ${attestedTxId}`);
+                    }
+                    if (!contentHash || !/^0x[a-fA-F0-9]{64}$/.test(contentHash)) {
+                        throw new Error(`Decoded contentHash is not valid bytes32: ${contentHash}`);
+                    }
+                    const now = BigInt(Math.floor(Date.now() / 1000));
+                    if (timestamp > now + 86400n) {
+                        throw new Error(`Decoded timestamp is in far future: ${timestamp.toString()}`);
+                    }
+                    if (typeof deliveryUrl !== 'string' || deliveryUrl.length > 2048) {
+                        throw new Error('Decoded deliveryUrl too long');
+                    }
+                    if (size < 0n) {
+                        throw new Error(`Decoded size is negative: ${size}`);
+                    }
+                    if (typeof mimeType !== 'string' || mimeType.length > 256) {
+                        throw new Error('Decoded mimeType too long');
+                    }
+                }
+            }
         }
         catch (error) {
             throw new Error(`Attestation data format mismatch: cannot decode attestation ${attestationUID}. ` +
-                `Expected AIP-4 delivery proof schema format. ` +
+                `Expected AIP-6 (preferred) or AIP-4 (legacy) delivery proof schema format. ` +
                 `Original error: ${error.message}`);
         }
-        if (attestedTxId !== txId) {
+        // 7. Verify attestation txId matches expected transaction ID
+        if (attestedTxId.toLowerCase() !== txId.toLowerCase()) {
             throw new Error(`Attestation txId mismatch: expected ${txId}, got ${attestedTxId}. ` +
                 `Provider may be attempting to use attestation from different transaction!`);
         }
+        // SECURITY FIX (C-1): Check if attestation has been used for a different transaction
+        if (!this.attestationTracker.isValidForTransaction(attestationUID, txId)) {
+            const usedFor = this.attestationTracker.getUsageForAttestation(attestationUID);
+            throw new Error(`Attestation replay attack detected: attestation ${attestationUID} ` +
+                `was already used for transaction ${usedFor}. ` +
+                `Cannot reuse for transaction ${txId}.`);
+        }
+        // Record this attestation as used for this transaction
+        const recorded = await this.attestationTracker.recordUsage(attestationUID, txId);
+        if (!recorded) {
+            const usedFor = this.attestationTracker.getUsageForAttestation(attestationUID);
+            throw new Error(`Attestation replay attack detected: attestation ${attestationUID} ` +
+                `was already used for transaction ${usedFor}. Cannot reuse for ${txId}.`);
+        }
+        // All checks passed
         return true;
     }
+    /**
+     * Verify attestation for escrow release with mandatory replay protection
+     *
+     * SECURITY FIX (C-4): This method MUST be called before releaseEscrow()
+     * to prevent attestation replay attacks.
+     *
+     * @param txId - Expected transaction ID (bytes32)
+     * @param attestationUID - Attestation UID to verify (bytes32)
+     * @throws Error if verification fails or replay attack detected
+     */
+    async verifyAndRecordForRelease(txId, attestationUID) {
+        // Verify the attestation
+        await this.verifyDeliveryAttestation(txId, attestationUID);
+    }
 }
 exports.EASHelper = EASHelper;
 //# sourceMappingURL=EASHelper.js.map

package/dist/protocol/EASHelper.js.map

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

package/dist/protocol/EscrowVault.d.ts

@@ -1,23 +1,114 @@
-import { Signer } from 'ethers';
+import { Contract, Signer } from 'ethers';
 import { Escrow } from '../types';
+/**
+ * Gas options for transactions
+ */
 interface GasOptions {
     maxFeePerGas?: bigint;
     maxPriorityFeePerGas?: bigint;
 }
+/**
+ * EscrowVault - Escrow contract wrapper
+ *
+ * IMPORTANT:
+ * - Escrow creation happens atomically inside `ACTPKernel.linkEscrow()`.
+ * - Payout/refund functions are `onlyKernel` on-chain and MUST NOT be called by users.
+ *
+ * This module provides:
+ * - Helper methods for USDC approvals (requester → EscrowVault allowance)
+ * - Read-only access to escrow state (`escrows()` / `remaining()`)
+ *
+ * Workflow (per AIP-3):
+ * 1. Consumer approves USDC to EscrowVault address (use approveToken)
+ * 2. Consumer calls ACTPKernel.linkEscrow(txId, escrowVault, escrowId)
+ * 3. Kernel internally calls IEscrowValidator.createEscrow(escrowId, requester, provider, amount)
+ * 4. Escrow pulls USDC from requester
+ *
+ * Reference: AIP-3 §3.2 (Escrow Linking Workflow), lines 258-336
+ */
 export declare class EscrowVault {
     private readonly address;
     private readonly signer;
     private contract;
     private readonly gasSettings?;
     constructor(address: string, signer: Signer, gasSettings?: GasOptions);
+    /**
+     * Get gas buffer multiplier based on operation complexity
+     * V6 Security Enhancement: Operation-specific gas buffers
+     * Reference: SDK_SECURITY_ANALYSIS-Ultra-Think.md Lines 326-337
+     */
     private getGasBufferMultiplier;
+    /**
+     * Build transaction options with gas settings and estimated gas
+     * V6 Enhancement: Dynamic buffer based on operation type
+     *
+     * SECURITY FIX (NEW-C-1): Gas estimation manipulation attack protection
+     * - Enforces minimum gas floor regardless of estimate
+     * - Uses safe BigInt arithmetic with overflow detection
+     */
     private buildTxOptions;
+    /**
+     * Get escrow vault address
+     */
     getAddress(): string;
+    /**
+     * Get the underlying ethers Contract instance.
+     *
+     * SECURITY FIX (C-3): Provides public access to contract for EventMonitor
+     * instead of accessing private field via bracket notation.
+     *
+     * @returns ethers Contract instance
+     */
+    getContract(): Contract;
+    /**
+     * Approve USDC token for escrow creation
+     *
+     * IMPORTANT: Call this BEFORE ACTPKernel.linkEscrow()
+     * The consumer must approve EscrowVault to pull USDC when linkEscrow() is called
+     *
+     * @param tokenAddress - USDC contract address
+     * @param amount - Amount to approve (in USDC wei, 6 decimals)
+     * @throws {ValidationError} If inputs are invalid
+     * @throws {TransactionRevertedError} If approval fails
+     *
+     * @example
+     * ```typescript
+     * // Approve 100 USDC for escrow
+     * const amount = ethers.parseUnits('100', 6);
+     * await client.escrow.approveToken(BASE_SEPOLIA.contracts.usdc, amount);
+     *
+     * // Now call linkEscrow via Kernel
+     * const escrowId = ethers.id(`escrow-${Date.now()}`);
+     * await client.kernel.linkEscrow(txId, escrowVault, escrowId);
+     * ```
+     */
     approveToken(tokenAddress: string, amount: bigint): Promise<void>;
+    /**
+     * Get escrow details
+     */
     getEscrow(escrowId: string): Promise<Escrow>;
+    /**
+     * Get escrow remaining balance (amount - releasedAmount)
+     */
     getEscrowBalance(escrowId: string): Promise<bigint>;
-    releaseEscrow(escrowId: string, recipients: string[], amounts: bigint[]): Promise<void>;
+    /**
+     * @deprecated
+     *
+     * Payouts/refunds are executed by ACTPKernel (on-chain) as part of state transitions.
+     * EscrowVault disbursement methods are `onlyKernel` and cannot be called by EOAs.
+     *
+     * Use:
+     * - `BlockchainRuntime.releaseEscrow(txId, attestationUID?)` (recommended)
+     * - or `ACTPKernel.transitionState(txId, State.SETTLED, proof)` (advanced)
+     */
+    releaseEscrow(escrowId: string, _recipients: string[], _amounts: bigint[]): Promise<void>;
+    /**
+     * Check token balance
+     */
     getTokenBalance(tokenAddress: string, account: string): Promise<bigint>;
+    /**
+     * Check token allowance
+     */
     getTokenAllowance(tokenAddress: string, owner: string, spender: string): Promise<bigint>;
 }
 export {};

package/dist/protocol/EscrowVault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EscrowVault.d.ts","sourceRoot":"","sources":["../../src/protocol/EscrowVault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG1C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAWlC,UAAU,UAAU;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAiBD,qBAAa,WAAW;IAKpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAa;gBAGvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAC/B,WAAW,CAAC,EAAE,UAAU;IAW1B,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,cAAc;IAoBtB,UAAU,IAAI,MAAM;IA0Bd,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCjE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB5C,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASnD,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC;IAqCV,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQvE,iBAAiB,CACrB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;CAInB"}
+{"version":3,"file":"EscrowVault.d.ts","sourceRoot":"","sources":["../../src/protocol/EscrowVault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG1C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAQlC;;GAEG;AACH,UAAU,UAAU;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW;IAKpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAa;gBAGvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAC/B,WAAW,CAAC,EAAE,UAAU;IAM1B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAoCtB;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;OAOG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCvE;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAclD;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKzD;;;;;;;;;OASG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC;IAShB;;OAEG;IACG,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK7E;;OAEG;IACG,iBAAiB,CACrB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;CAInB"}