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

package/dist/esm/utils/network-normalizer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @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
+ */
+import { type SapNetworkId } from "../constants/network";
+/**
+ * @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"
+ * ```
+ */
+export declare function normalizeNetworkId(raw: string): SapNetworkId | string;
+/**
+ * @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
+ * ```
+ */
+export declare function isNetworkEquivalent(a: string, b: string): boolean;
+/**
+ * @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
+ */
+export declare function getNetworkGenesisHash(networkId: string): string;
+/**
+ * @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
+ */
+export declare function getNetworkClusterName(networkId: string): string;
+/**
+ * @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
+ */
+export declare function isKnownNetwork(networkId: string): boolean;
+//# sourceMappingURL=network-normalizer.d.ts.map

package/dist/esm/utils/network-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-normalizer.d.ts","sourceRoot":"","sources":["../../../src/utils/network-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAsDrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,CAcrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CA2BjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAIzD"}

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

@@ -0,0 +1,229 @@
+/**
+ * @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
+ */
+import { SapNetwork } from "../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", SapNetwork.SOLANA_MAINNET],
+    ["solana:mainnet", SapNetwork.SOLANA_MAINNET],
+    ["mainnet-beta", SapNetwork.SOLANA_MAINNET],
+    ["mainnet", SapNetwork.SOLANA_MAINNET],
+    ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
+    ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
+    // ── Devnet ────────────────────────────────
+    ["solana:devnet", SapNetwork.SOLANA_DEVNET_NAMED],
+    ["devnet", SapNetwork.SOLANA_DEVNET_NAMED],
+    ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
+    ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
+]);
+/**
+ * Mainnet equivalence set: all strings that refer to Solana mainnet-beta,
+ * regardless of format.
+ */
+const MAINNET_EQUIVALENTS = new Set([
+    SapNetwork.SOLANA_MAINNET,
+    SapNetwork.SOLANA_MAINNET_GENESIS,
+    "solana:mainnet",
+    "mainnet-beta",
+    "mainnet",
+    "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+]);
+/**
+ * Devnet equivalence set.
+ */
+const DEVNET_EQUIVALENTS = new Set([
+    SapNetwork.SOLANA_DEVNET,
+    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"
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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
+ */
+export function getNetworkGenesisHash(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_MAINNET_GENESIS;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return 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
+ */
+export function getNetworkClusterName(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_MAINNET;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return 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
+ */
+export 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/esm/utils/network-normalizer.js.map

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

package/dist/esm/utils/priority-fee.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @module utils/priority-fee
+ * @description Compute budget and priority fee utilities for SAP transactions.
+ *
+ * Solana transactions that include a priority fee (via the Compute Budget program)
+ * land faster because validators prefer higher-fee transactions. This module
+ * provides a clean, composable API for building priority-fee instructions
+ * that can be prepended to any Anchor method builder via `.preInstructions()`.
+ *
+ * Typical use: x402 settlement transactions where the receiving agent's RPC
+ * has a short confirmation window (e.g., 30 seconds).
+ *
+ * @category Utils
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * import { buildPriorityFeeIxs, DEFAULT_SETTLE_PRIORITY } from "@synapse-sap/sdk";
+ *
+ * // Append to any Anchor method builder:
+ * await program.methods
+ *   .settleCalls(calls, hash)
+ *   .accounts({ ... })
+ *   .preInstructions(buildPriorityFeeIxs({ priorityFeeMicroLamports: 5000 }))
+ *   .rpc({ skipPreflight: true });
+ * ```
+ */
+import { type TransactionInstruction } from "@solana/web3.js";
+/**
+ * Default priority fee for settlement transactions (in microlamports).
+ * 5000 µL ≈ 0.0005 SOL per 200k CU — fast enough for most agent RPCs.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_SETTLE_PRIORITY_FEE = 5000;
+/**
+ * Default compute unit limit for settlement transactions.
+ * `settle_calls` uses ~60k CU; 100k provides a safe margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_SETTLE_COMPUTE_UNITS = 100000;
+/**
+ * Default compute unit limit for batch settlement transactions.
+ * `settle_batch` with 10 entries uses ~200k CU; 300k provides margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_BATCH_SETTLE_COMPUTE_UNITS = 300000;
+/**
+ * @name computeBatchSettleCu
+ * @description Compute the CU limit needed by `settle_batch` for a
+ * given entry count. Returned value is safe to pass to
+ * `ComputeBudgetProgram.setComputeUnitLimit`.
+ *
+ * Formula: `60_000 + n * 25_000`, clamped to 1.2M.
+ *
+ * @param entryCount - Number of settlements in the batch (1..N).
+ * @returns CU limit suitable for `setComputeUnitLimit`.
+ *
+ * @example
+ * ```ts
+ * const cu = computeBatchSettleCu(20); // 560_000
+ * ```
+ *
+ * @category Utils
+ * @since v0.11.0
+ */
+export declare function computeBatchSettleCu(entryCount: number): number;
+/**
+ * @interface PriorityFeeConfig
+ * @description Configuration for building compute budget instructions.
+ * @category Utils
+ * @since v0.6.2
+ */
+export interface PriorityFeeConfig {
+    /**
+     * Priority fee in microlamports per compute unit.
+     * Higher values = faster confirmation.
+     *
+     * Common values:
+     * - `1000` — low priority (~0.0001 SOL)
+     * - `5000` — medium priority (~0.0005 SOL) ← recommended for settle
+     * - `50000` — high priority (~0.005 SOL)
+     * - `0` — no priority fee (default Solana behavior)
+     *
+     * @default 0
+     */
+    readonly priorityFeeMicroLamports?: number;
+    /**
+     * Maximum compute units the transaction may consume.
+     * Setting an explicit limit avoids overpaying for unused CU.
+     *
+     * @default 200_000 (Solana default)
+     */
+    readonly computeUnits?: number;
+}
+/**
+ * @interface SettleOptions
+ * @description Options for x402 settlement transactions.
+ * Controls priority fees, compute budget, and RPC behavior
+ * to optimize confirmation speed for time-sensitive settlements.
+ *
+ * @category Registries
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * // Fast settlement with priority fee
+ * const receipt = await x402.settle(depositor, 1, "data", {
+ *   priorityFeeMicroLamports: 5000,
+ *   computeUnits: 100_000,
+ *   skipPreflight: true,
+ * });
+ *
+ * // Use the convenience preset
+ * import { FAST_SETTLE_OPTIONS } from "@synapse-sap/sdk";
+ * const receipt = await x402.settle(depositor, 1, "data", FAST_SETTLE_OPTIONS);
+ * ```
+ */
+export interface SettleOptions extends PriorityFeeConfig {
+    /**
+     * Skip Solana simulation before submitting.
+     * Saves ~400ms but loses pre-flight error detection.
+     *
+     * Recommended for settlements where the escrow state
+     * has already been pre-fetched and validated.
+     *
+     * @default false
+     */
+    readonly skipPreflight?: boolean;
+    /**
+     * Transaction commitment level override.
+     * Uses the provider's default when omitted.
+     *
+     * - `"processed"` — fastest, least reliable
+     * - `"confirmed"` — balanced (recommended)
+     * - `"finalized"` — slowest, most reliable
+     */
+    readonly commitment?: "processed" | "confirmed" | "finalized";
+    /**
+     * Maximum number of RPC retry attempts.
+     * @default provider default (usually 3)
+     */
+    readonly maxRetries?: number;
+}
+/**
+ * Recommended preset for fast x402 settlements.
+ * Priority fee 5000 µL, 100k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * Recommended preset for fast batch settlements.
+ * Priority fee 5000 µL, 300k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_BATCH_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * @name buildPriorityFeeIxs
+ * @description Build compute budget instructions for priority fee transactions.
+ *
+ * Returns an array of 0–2 `TransactionInstruction`s:
+ * - `SetComputeUnitPrice` (if `priorityFeeMicroLamports > 0`)
+ * - `SetComputeUnitLimit` (if `computeUnits` provided)
+ *
+ * The returned array is designed to be passed directly to
+ * Anchor's `.preInstructions()` builder method.
+ *
+ * @param config - Priority fee configuration.
+ * @returns Array of compute budget instructions (may be empty).
+ *
+ * @category Utils
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * const ixs = buildPriorityFeeIxs({
+ *   priorityFeeMicroLamports: 5000,
+ *   computeUnits: 100_000,
+ * });
+ *
+ * await program.methods
+ *   .settleCalls(calls, hash)
+ *   .accounts({ ... })
+ *   .preInstructions(ixs)
+ *   .rpc({ skipPreflight: true });
+ * ```
+ */
+export declare function buildPriorityFeeIxs(config?: PriorityFeeConfig): TransactionInstruction[];
+/**
+ * @name buildRpcOptions
+ * @description Build Anchor `.rpc()` options from {@link SettleOptions}.
+ *
+ * @param opts - Settle options.
+ * @returns Options object suitable for Anchor `.rpc(opts)`.
+ *
+ * @category Utils
+ * @since v0.6.2
+ * @internal
+ */
+export declare function buildRpcOptions(opts?: SettleOptions): Record<string, unknown> | undefined;
+//# sourceMappingURL=priority-fee.d.ts.map

package/dist/esm/utils/priority-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-fee.d.ts","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AA8B1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,aAAa,CAKtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,aAAa,CAK5D,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,iBAAiB,GACzB,sBAAsB,EAAE,CAwB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBrC"}