@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.1

package/dist/cjs/utils/merchant-validator.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * @module utils/merchant-validator
+ * @description Standard Synapse merchant middleware for x402 settlement.
+ *
+ * Reads `X-Payment-*` headers from incoming HTTP requests, validates
+ * the escrow on-chain, auto-generates the correct `AccountMeta[]`,
+ * and throws explicit errors (e.g. {@link MissingEscrowAtaError})
+ * instead of letting the program return a generic crash.
+ *
+ * Designed for agents like Syra/Invoica that receive x402 payments.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapMerchantValidator = void 0;
+exports.parseX402Headers = parseX402Headers;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+const escrow_validation_1 = require("./escrow-validation");
+const index_1 = require("../errors/index");
+// ═══════════════════════════════════════════════════════════════════
+//  Header parsing
+// ═══════════════════════════════════════════════════════════════════
+/** Required x402 headers. */
+const REQUIRED_HEADERS = [
+    "X-Payment-Protocol",
+    "X-Payment-Escrow",
+    "X-Payment-Agent",
+    "X-Payment-Depositor",
+    "X-Payment-MaxCalls",
+    "X-Payment-PricePerCall",
+    "X-Payment-Program",
+    "X-Payment-Network",
+];
+/**
+ * @name parseX402Headers
+ * @description Parse and validate x402 headers from an HTTP request.
+ *
+ * @param headers - HTTP headers object (case-insensitive key lookup).
+ * @returns Parsed x402 headers.
+ * @throws {SapValidationError} If required headers are missing or malformed.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+function parseX402Headers(headers) {
+    // Normalize to case-insensitive
+    const normalized = new Map();
+    for (const [key, value] of Object.entries(headers)) {
+        const val = Array.isArray(value) ? value[0] : value;
+        if (val !== undefined) {
+            normalized.set(key.toLowerCase(), val);
+        }
+    }
+    // Validate required headers present
+    const missing = [];
+    for (const h of REQUIRED_HEADERS) {
+        if (!normalized.has(h.toLowerCase())) {
+            missing.push(h);
+        }
+    }
+    if (missing.length > 0) {
+        throw new index_1.SapValidationError(`Missing required x402 headers: ${missing.join(", ")}`, "x402-headers");
+    }
+    const get = (key) => normalized.get(key.toLowerCase());
+    // Validate protocol
+    const protocol = get("X-Payment-Protocol");
+    if (protocol !== "SAP-x402") {
+        throw new index_1.SapValidationError(`Invalid X-Payment-Protocol: "${protocol}" (expected "SAP-x402")`, "X-Payment-Protocol");
+    }
+    // Parse PublicKeys
+    let escrowPda;
+    let agentPda;
+    let depositorWallet;
+    let programId;
+    try {
+        escrowPda = new web3_js_1.PublicKey(get("X-Payment-Escrow"));
+        agentPda = new web3_js_1.PublicKey(get("X-Payment-Agent"));
+        depositorWallet = new web3_js_1.PublicKey(get("X-Payment-Depositor"));
+        programId = new web3_js_1.PublicKey(get("X-Payment-Program"));
+    }
+    catch {
+        throw new index_1.SapValidationError("Malformed public key in x402 headers", "x402-headers");
+    }
+    // Parse numeric values
+    const maxCallsStr = get("X-Payment-MaxCalls");
+    const pricePerCallStr = get("X-Payment-PricePerCall");
+    let maxCalls;
+    let pricePerCall;
+    try {
+        maxCalls = new anchor_1.BN(maxCallsStr);
+        pricePerCall = new anchor_1.BN(pricePerCallStr);
+    }
+    catch {
+        throw new index_1.SapValidationError("Invalid numeric value in X-Payment-MaxCalls or X-Payment-PricePerCall", "x402-headers");
+    }
+    return {
+        protocol,
+        escrowPda,
+        agentPda,
+        depositorWallet,
+        maxCalls,
+        pricePerCall,
+        programId,
+        network: get("X-Payment-Network"),
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Merchant Validator
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapMerchantValidator
+ * @description Standard Synapse merchant middleware for x402 payment validation.
+ *
+ * Reads `X-Payment-*` headers, validates escrow state on-chain, generates
+ * correct `AccountMeta[]` for SPL token escrows, and throws explicit errors
+ * (e.g. {@link MissingEscrowAtaError}) when ATA accounts are missing.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const validator = new SapMerchantValidator(connection, fetchEscrow);
+ *
+ * // Express.js integration
+ * app.post("/api/v1/chat", async (req, res) => {
+ *   try {
+ *     const validation = await validator.validateRequest(req.headers, {
+ *       callsToSettle: 1,
+ *     });
+ *
+ *     if (!validation.valid) {
+ *       return res.status(402).json({ errors: validation.errors });
+ *     }
+ *
+ *     // Process request...
+ *
+ *     // Settle payment using pre-built account metas
+ *     await client.escrow.settle(
+ *       validation.headers.depositorWallet,
+ *       1,
+ *       serviceHash,
+ *       validation.accountMetas,
+ *     );
+ *
+ *     res.json({ result: "..." });
+ *   } catch (err) {
+ *     if (err instanceof MissingEscrowAtaError) {
+ *       return res.status(402).json({
+ *         error: err.message,
+ *         side: err.side,
+ *         ata: err.ataAddress,
+ *       });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+class SapMerchantValidator {
+    connection;
+    fetchEscrow;
+    /**
+     * @param connection  - Solana RPC connection.
+     * @param fetchEscrow - Callback to fetch escrow account data by PDA.
+     *   Typically `(pda) => client.escrow.fetchByPda(pda).catch(() => null)`.
+     */
+    constructor(connection, fetchEscrow) {
+        this.connection = connection;
+        this.fetchEscrow = fetchEscrow;
+    }
+    /**
+     * @name validateRequest
+     * @description Full validation pipeline for an incoming x402 request.
+     *
+     * Steps:
+     * 1. Parse `X-Payment-*` headers
+     * 2. Fetch escrow on-chain
+     * 3. Validate escrow state (balance, expiry, max calls)
+     * 4. If SPL escrow: validate ATAs exist and mint matches
+     * 5. Build `AccountMeta[]` for settlement TX
+     *
+     * @param headers - HTTP headers from the incoming request.
+     * @param opts
+     * @param opts.callsToSettle     - Number of calls to validate affordability for (default: 1).
+     * @param opts.throwOnMissingAta - Throw {@link MissingEscrowAtaError} instead of returning errors (default: true).
+     *
+     * @returns A complete {@link MerchantValidationResult}.
+     *
+     * @throws {SapValidationError} If headers are missing or malformed.
+     * @throws {MissingEscrowAtaError} If SPL ATAs are missing and `throwOnMissingAta` is true.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    async validateRequest(headers, opts) {
+        // 1. Parse headers
+        const parsed = parseX402Headers(headers);
+        // 2. Validate escrow state
+        const escrowValidation = await (0, escrow_validation_1.validateEscrowState)(this.connection, parsed.agentPda, // agentWallet derived inside validate
+        parsed.depositorWallet, this.fetchEscrow, { callsToSettle: opts?.callsToSettle ?? 1 });
+        // 3. Check for ATA errors and optionally throw
+        const throwOnMissingAta = opts?.throwOnMissingAta !== false;
+        if (throwOnMissingAta && escrowValidation.isSplEscrow) {
+            for (const error of escrowValidation.errors) {
+                if (error.includes("Depositor ATA does not exist")) {
+                    const ataAddr = error.split(": ")[1] ?? "unknown";
+                    throw new escrow_validation_1.MissingEscrowAtaError(ataAddr, "depositor");
+                }
+                if (error.includes("Escrow ATA does not exist")) {
+                    const ataAddr = error.split(": ")[1] ?? "unknown";
+                    throw new escrow_validation_1.MissingEscrowAtaError(ataAddr, "escrow");
+                }
+            }
+        }
+        // 4. Build account metas
+        const accountMetas = (0, escrow_validation_1.toAccountMetas)(escrowValidation.splAccounts);
+        return {
+            valid: escrowValidation.valid,
+            headers: parsed,
+            escrowValidation,
+            accountMetas,
+            errors: escrowValidation.errors,
+        };
+    }
+    /**
+     * @name validateEscrow
+     * @description Validate escrow from pre-parsed headers (convenience method).
+     * Call this when you've already parsed the headers yourself.
+     *
+     * @param headers - Pre-parsed x402 headers.
+     * @param opts
+     * @returns The escrow validation result with pre-built account metas.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    async validateEscrow(headers, opts) {
+        return (0, escrow_validation_1.validateEscrowState)(this.connection, headers.agentPda, headers.depositorWallet, this.fetchEscrow, opts);
+    }
+}
+exports.SapMerchantValidator = SapMerchantValidator;
+//# sourceMappingURL=merchant-validator.js.map

package/dist/cjs/utils/merchant-validator.js.map

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

package/dist/cjs/utils/network-normalizer.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * @module utils/network-normalizer
+ * @description Network identifier normalization for x402 payment headers.
+ *
+ * Solves the canonical-string mismatch between SAP clients and servers:
+ * some providers accept `solana:mainnet-beta` while others require
+ * the genesis-hash form `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`.
+ *
+ * This module provides a single source of truth for normalizing
+ * network identifiers so that both clients and agents canonicalize
+ * before comparing. Catches the Kamiyo "sap network mismatch" error
+ * at the SDK level.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeNetworkId = normalizeNetworkId;
+exports.isNetworkEquivalent = isNetworkEquivalent;
+exports.getNetworkGenesisHash = getNetworkGenesisHash;
+exports.getNetworkClusterName = getNetworkClusterName;
+exports.isKnownNetwork = isKnownNetwork;
+const network_1 = require("../constants/network");
+// ═══════════════════════════════════════════════════════════════════
+//  Canonical Mapping
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Bidirectional alias map: for every known network string, stores the
+ * canonical SapNetworkId it resolves to, plus all known aliases.
+ */
+const NETWORK_ALIASES = new Map([
+    // ── Mainnet ───────────────────────────────
+    // Canonical: genesis-hash form
+    ["solana:mainnet-beta", network_1.SapNetwork.SOLANA_MAINNET],
+    ["solana:mainnet", network_1.SapNetwork.SOLANA_MAINNET],
+    ["mainnet-beta", network_1.SapNetwork.SOLANA_MAINNET],
+    ["mainnet", network_1.SapNetwork.SOLANA_MAINNET],
+    ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", network_1.SapNetwork.SOLANA_MAINNET_GENESIS],
+    ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", network_1.SapNetwork.SOLANA_MAINNET_GENESIS],
+    // ── Devnet ────────────────────────────────
+    ["solana:devnet", network_1.SapNetwork.SOLANA_DEVNET_NAMED],
+    ["devnet", network_1.SapNetwork.SOLANA_DEVNET_NAMED],
+    ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", network_1.SapNetwork.SOLANA_DEVNET],
+    ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", network_1.SapNetwork.SOLANA_DEVNET],
+]);
+/**
+ * Mainnet equivalence set: all strings that refer to Solana mainnet-beta,
+ * regardless of format.
+ */
+const MAINNET_EQUIVALENTS = new Set([
+    network_1.SapNetwork.SOLANA_MAINNET,
+    network_1.SapNetwork.SOLANA_MAINNET_GENESIS,
+    "solana:mainnet",
+    "mainnet-beta",
+    "mainnet",
+    "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+]);
+/**
+ * Devnet equivalence set.
+ */
+const DEVNET_EQUIVALENTS = new Set([
+    network_1.SapNetwork.SOLANA_DEVNET,
+    network_1.SapNetwork.SOLANA_DEVNET_NAMED,
+    "devnet",
+    "EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+]);
+// ═══════════════════════════════════════════════════════════════════
+//  Public API
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name normalizeNetworkId
+ * @description Normalize a raw network identifier string to its canonical
+ * {@link SapNetworkId} form.
+ *
+ * Handles:
+ *   - Case-insensitive matching
+ *   - Stripping whitespace
+ *   - Resolving genesis-hash vs. cluster-name aliases
+ *   - Unknown strings are returned as-is (passthrough)
+ *
+ * @param raw - Raw network identifier string from headers, env vars, or config.
+ * @returns The canonical {@link SapNetworkId}, or the trimmed input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { normalizeNetworkId } from "@synapse-sap/sdk";
+ *
+ * normalizeNetworkId("solana:mainnet-beta");
+ * // → "solana:mainnet-beta"
+ *
+ * normalizeNetworkId("5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+ *
+ * normalizeNetworkId("  MAINNET  ");
+ * // → "solana:mainnet-beta"
+ * ```
+ */
+function normalizeNetworkId(raw) {
+    const trimmed = raw.trim();
+    // Exact match first
+    const exact = NETWORK_ALIASES.get(trimmed);
+    if (exact)
+        return exact;
+    // Case-insensitive lookup
+    const lower = trimmed.toLowerCase();
+    for (const [alias, canonical] of NETWORK_ALIASES) {
+        if (alias.toLowerCase() === lower)
+            return canonical;
+    }
+    // Passthrough for unknown networks (custom chains, etc.)
+    return trimmed;
+}
+/**
+ * @name isNetworkEquivalent
+ * @description Check if two network identifier strings refer to the same network,
+ * even if they use different formats (cluster-name vs. genesis-hash).
+ *
+ * This is the key function that prevents the Kamiyo "sap network mismatch"
+ * error — instead of comparing strings literally, we compare their
+ * canonical equivalence class.
+ *
+ * @param a - First network identifier.
+ * @param b - Second network identifier.
+ * @returns `true` if both identifiers refer to the same Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { isNetworkEquivalent } from "@synapse-sap/sdk";
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:devnet", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:devnet");
+ * // → false
+ * ```
+ */
+function isNetworkEquivalent(a, b) {
+    const normA = a.trim();
+    const normB = b.trim();
+    // Fast path: identical strings
+    if (normA === normB)
+        return true;
+    // Check if both are in the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(normA) && MAINNET_EQUIVALENTS.has(normB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(normA) && DEVNET_EQUIVALENTS.has(normB))
+        return true;
+    // Case-insensitive match
+    const lowerA = normA.toLowerCase();
+    const lowerB = normB.toLowerCase();
+    if (lowerA === lowerB)
+        return true;
+    // Resolve both to canonical and compare
+    const canonA = normalizeNetworkId(normA);
+    const canonB = normalizeNetworkId(normB);
+    if (canonA === canonB)
+        return true;
+    // Final check: both resolve to the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(canonA) && MAINNET_EQUIVALENTS.has(canonB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(canonA) && DEVNET_EQUIVALENTS.has(canonB))
+        return true;
+    return false;
+}
+/**
+ * @name getNetworkGenesisHash
+ * @description Get the genesis-hash form of a network identifier.
+ * Returns the genesis-hash variant for known networks, or the input as-is.
+ *
+ * Useful for agents that require the genesis-hash form (Kamiyo, Helius x402).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The genesis-hash form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function getNetworkGenesisHash(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_MAINNET_GENESIS;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_DEVNET;
+    }
+    return norm;
+}
+/**
+ * @name getNetworkClusterName
+ * @description Get the cluster-name form of a network identifier.
+ * Returns the human-readable cluster name for known networks.
+ *
+ * Useful for providers that accept cluster names (Coinbase, Phantom).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The cluster-name form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function getNetworkClusterName(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_MAINNET;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_DEVNET_NAMED;
+    }
+    return norm;
+}
+/**
+ * @name isKnownNetwork
+ * @description Check if a network identifier is recognized by the SDK.
+ *
+ * @param networkId - The network identifier to check.
+ * @returns `true` if the identifier maps to a known Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function isKnownNetwork(networkId) {
+    const trimmed = networkId.trim();
+    return MAINNET_EQUIVALENTS.has(trimmed) || DEVNET_EQUIVALENTS.has(trimmed) ||
+        NETWORK_ALIASES.has(trimmed);
+}
+//# sourceMappingURL=network-normalizer.js.map

package/dist/cjs/utils/network-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-normalizer.js","sourceRoot":"","sources":["../../../src/utils/network-normalizer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAuFH,gDAcC;AAgCD,kDA2BC;AAeD,sDASC;AAeD,sDASC;AAYD,wCAIC;AA9ND,kDAAqE;AAErE,sEAAsE;AACtE,qBAAqB;AACrB,sEAAsE;AAEtE;;;GAGG;AACH,MAAM,eAAe,GAAsC,IAAI,GAAG,CAAC;IACjE,6CAA6C;IAC7C,+BAA+B;IAC/B,CAAC,qBAAqB,EAAE,oBAAU,CAAC,cAAc,CAAC;IAClD,CAAC,gBAAgB,EAAE,oBAAU,CAAC,cAAc,CAAC;IAC7C,CAAC,cAAc,EAAE,oBAAU,CAAC,cAAc,CAAC;IAC3C,CAAC,SAAS,EAAE,oBAAU,CAAC,cAAc,CAAC;IACtC,CAAC,yCAAyC,EAAE,oBAAU,CAAC,sBAAsB,CAAC;IAC9E,CAAC,kCAAkC,EAAE,oBAAU,CAAC,sBAAsB,CAAC;IAEvE,6CAA6C;IAC7C,CAAC,eAAe,EAAE,oBAAU,CAAC,mBAAmB,CAAC;IACjD,CAAC,QAAQ,EAAE,oBAAU,CAAC,mBAAmB,CAAC;IAC1C,CAAC,yCAAyC,EAAE,oBAAU,CAAC,aAAa,CAAC;IACrE,CAAC,kCAAkC,EAAE,oBAAU,CAAC,aAAa,CAAC;CAC/D,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAS;IAC1C,oBAAU,CAAC,cAAc;IACzB,oBAAU,CAAC,sBAAsB;IACjC,gBAAgB;IAChB,cAAc;IACd,SAAS;IACT,kCAAkC;CACnC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACzC,oBAAU,CAAC,aAAa;IACxB,oBAAU,CAAC,mBAAmB;IAC9B,QAAQ;IACR,kCAAkC;CACnC,CAAC,CAAC;AAEH,sEAAsE;AACtE,cAAc;AACd,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,oBAAoB;IACpB,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,0BAA0B;IAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,eAAe,EAAE,CAAC;QACjD,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK;YAAE,OAAO,SAAS,CAAC;IACtD,CAAC;IAED,yDAAyD;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,mBAAmB,CAAC,CAAS,EAAE,CAAS;IACtD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEvB,+BAA+B;IAC/B,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAEjC,gDAAgD;IAChD,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClF,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhF,yBAAyB;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAEnC,wCAAwC;IACxC,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEzC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAEnC,wDAAwD;IACxD,IAAI,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACpF,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAElF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,qBAAqB,CAAC,SAAiB;IACrD,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,oBAAU,CAAC,sBAAsB,CAAC;IAC3C,CAAC;IACD,IAAI,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,oBAAU,CAAC,aAAa,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,qBAAqB,CAAC,SAAiB;IACrD,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,oBAAU,CAAC,cAAc,CAAC;IACnC,CAAC;IACD,IAAI,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,oBAAU,CAAC,mBAAmB,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,SAAiB;IAC9C,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC;QACxE,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}