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

package/dist/esm/modules/staking.js

@@ -0,0 +1,155 @@
+/**
+ * @module staking
+ * @description Agent staking lifecycle — init, deposit, request unstake,
+ * complete unstake, and fetch stake accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { SystemProgram, } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveStake } from "../pda";
+import { MIN_AGENT_STAKE_LAMPORTS, computeRequiredStakeLamports, } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
+/**
+ * @name StakingModule
+ * @description Manages agent stake accounts — init, deposit, unstake, and fetch.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class StakingModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    deriveStake(agentPda) {
+        return deriveStake(agentPda);
+    }
+    // ── Instructions ─────────────────────────────────────
+    async initStake(agentWallet, initialDeposit) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflights
+        const want = BigInt(this.bn(initialDeposit).toString());
+        if (want < MIN_AGENT_STAKE_LAMPORTS) {
+            throwPredicted("StakeBelowMinimum", `initial deposit ${want} < MIN_AGENT_STAKE_LAMPORTS ${MIN_AGENT_STAKE_LAMPORTS}`);
+        }
+        await this.requireAccountAbsent("agentStake", stakePda, "Stake already initialized — use depositStake to top up");
+        return this.methods
+            .initStake(this.bn(initialDeposit))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async deposit(agentWallet, amount) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — stake must already exist; amount > 0
+        if (BigInt(this.bn(amount).toString()) <= 0n) {
+            throwPredicted("InsufficientStake", "Deposit amount must be > 0");
+        }
+        await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "Call initStake first" });
+        return this.methods
+            .depositStake(this.bn(amount))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async requestUnstake(agentWallet, amount) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — enforce MIN_STAKE floor + no double-pending
+        const stake = await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "No stake account to unstake from" });
+        const want = BigInt(this.bn(amount).toString());
+        if (want <= 0n)
+            throwPredicted("InsufficientStake", "Unstake amount must be > 0");
+        const max = this.getMaxUnstakeLamports(stake);
+        if (want > max) {
+            throwPredicted("StakeBelowMinimum", `requested ${want} would drop stake below MIN_AGENT_STAKE_LAMPORTS (max unstake = ${max})`);
+        }
+        if (BigInt(stake.unstakeAmount.toString()) > 0n) {
+            throwPredicted("UnstakeAlreadyPending", "A pending unstake already exists — completeUnstake first or wait for cooldown");
+        }
+        return this.methods
+            .requestUnstake(this.bn(amount))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+        })
+            .rpc();
+    }
+    async completeUnstake(agentWallet) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [stakePda] = this.deriveStake(agentPda);
+        // v0.13.0 preflight — cooldown must have elapsed and an unstake must be pending
+        const stake = await this.requireAccountExists("agentStake", stakePda, { predicted: "NoStakeAccount", hint: "No stake account" });
+        const pending = BigInt(stake.unstakeAmount.toString());
+        if (pending === 0n) {
+            throwPredicted("NoUnstakePending", "Call requestUnstake first");
+        }
+        const availableAt = BigInt(stake.unstakeAvailableAt.toString());
+        const nowSec = BigInt(Math.floor(Date.now() / 1000));
+        if (nowSec < availableAt) {
+            throwPredicted("UnstakeCooldownNotMet", `available at unix ${availableAt}, now ${nowSec} (Δ ${availableAt - nowSec}s)`);
+        }
+        return this.methods
+            .completeUnstake()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            stake: stakePda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    async fetch(agentPda) {
+        const [pda] = this.deriveStake(agentPda);
+        return this.fetchAccount("agentStake", pda);
+    }
+    async fetchNullable(agentPda) {
+        const [pda] = this.deriveStake(agentPda);
+        return this.fetchAccountNullable("agentStake", pda);
+    }
+    async fetchByPda(stakePda) {
+        return this.fetchAccount("agentStake", stakePda);
+    }
+    // ── v0.11 helpers ────────────────────────────────────────────
+    /**
+     * Compute the maximum amount that can be requested via `requestUnstake`
+     * without breaching the on-chain {@link MIN_AGENT_STAKE_LAMPORTS} floor.
+     *
+     * Returns 0 if the agent is already at (or below) the floor.
+     *
+     * @since v0.11.0
+     */
+    getMaxUnstakeLamports(stake) {
+        const staked = BigInt(stake.stakedAmount.toString());
+        if (staked <= MIN_AGENT_STAKE_LAMPORTS)
+            return 0n;
+        return staked - MIN_AGENT_STAKE_LAMPORTS;
+    }
+    /**
+     * Returns the lamport delta the agent must `deposit` to satisfy the
+     * per-escrow stake-coverage requirement for `escrowLamports`. 0 if already
+     * sufficient. Useful for a UI "top up to open this escrow" button.
+     *
+     * Mirrors the on-chain check in `create_escrow_v2` (v0.11 H-1).
+     *
+     * @since v0.11.0
+     */
+    getRequiredTopUp(stake, escrowLamports) {
+        const required = computeRequiredStakeLamports(escrowLamports);
+        const have = BigInt(stake.stakedAmount.toString());
+        return have >= required ? 0n : required - have;
+    }
+}
+//# sourceMappingURL=staking.js.map

package/dist/esm/modules/staking.js.map

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

package/dist/esm/modules/subscription.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module subscription
+ * @description Agent subscription lifecycle — create, fund, cancel,
+ * close, and fetch subscription accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import type { SubscriptionData, CreateSubscriptionArgs } from "../types";
+/**
+ * @name SubscriptionModule
+ * @description Manages recurring subscriptions between subscribers and agents.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export declare class SubscriptionModule extends BaseModule {
+    private toNum;
+    deriveSubscription(agentPda: PublicKey, subscriber?: PublicKey, subId?: BN | number | bigint): readonly [PublicKey, number];
+    create(agentWallet: PublicKey, args: CreateSubscriptionArgs): Promise<TransactionSignature>;
+    fund(agentWallet: PublicKey, subId: BN | number | bigint, amount: BN | number | bigint): Promise<TransactionSignature>;
+    cancel(agentWallet: PublicKey, subId?: BN | number | bigint): Promise<TransactionSignature>;
+    close(agentWallet: PublicKey, subId?: BN | number | bigint): Promise<TransactionSignature>;
+    fetch(agentPda: PublicKey, subscriber?: PublicKey, subId?: BN | number | bigint): Promise<SubscriptionData>;
+    fetchNullable(agentPda: PublicKey, subscriber?: PublicKey, subId?: BN | number | bigint): Promise<SubscriptionData | null>;
+    fetchByPda(subPda: PublicKey): Promise<SubscriptionData>;
+}
+//# sourceMappingURL=subscription.d.ts.map

package/dist/esm/modules/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/modules/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEzE;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAGhD,OAAO,CAAC,KAAK;IAIb,kBAAkB,CAChB,QAAQ,EAAE,SAAS,EACnB,UAAU,CAAC,EAAE,SAAS,EACtB,KAAK,GAAE,EAAE,GAAG,MAAM,GAAG,MAAU,GAC9B,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAUzB,MAAM,CACV,WAAW,EAAE,SAAS,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAoB1B,IAAI,CACR,WAAW,EAAE,SAAS,EACtB,KAAK,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,EAC3B,MAAM,EAAE,EAAE,GAAG,MAAM,GAAG,MAAM,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAc1B,MAAM,CACV,WAAW,EAAE,SAAS,EACtB,KAAK,GAAE,EAAE,GAAG,MAAM,GAAG,MAAU,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAc1B,KAAK,CACT,WAAW,EAAE,SAAS,EACtB,KAAK,GAAE,EAAE,GAAG,MAAM,GAAG,MAAU,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAe1B,KAAK,CACT,QAAQ,EAAE,SAAS,EACnB,UAAU,CAAC,EAAE,SAAS,EACtB,KAAK,GAAE,EAAE,GAAG,MAAM,GAAG,MAAU,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IAKtB,aAAa,CACjB,QAAQ,EAAE,SAAS,EACnB,UAAU,CAAC,EAAE,SAAS,EACtB,KAAK,GAAE,EAAE,GAAG,MAAM,GAAG,MAAU,GAC9B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAK7B,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG/D"}

package/dist/esm/modules/subscription.js

@@ -0,0 +1,92 @@
+/**
+ * @module subscription
+ * @description Agent subscription lifecycle — create, fund, cancel,
+ * close, and fetch subscription accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { SystemProgram, } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveSubscription } from "../pda";
+/**
+ * @name SubscriptionModule
+ * @description Manages recurring subscriptions between subscribers and agents.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class SubscriptionModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    toNum(v) {
+        return BN.isBN(v) ? v.toNumber() : Number(v);
+    }
+    deriveSubscription(agentPda, subscriber, subId = 0) {
+        return deriveSubscription(agentPda, subscriber ?? this.walletPubkey, this.toNum(subId));
+    }
+    // ── Instructions ─────────────────────────────────────
+    async create(agentWallet, args) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, args.subId);
+        return this.methods
+            .createSubscription(this.bn(args.subId), this.bn(args.pricePerInterval), args.billingInterval, this.bn(args.initialFund))
+            .accounts({
+            subscriber: this.walletPubkey,
+            agent: agentPda,
+            subscription: subPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async fund(agentWallet, subId, amount) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .fundSubscription(this.bn(amount))
+            .accounts({
+            subscriber: this.walletPubkey,
+            subscription: subPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async cancel(agentWallet, subId = 0) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .cancelSubscription()
+            .accounts({
+            subscriber: this.walletPubkey,
+            agentWallet,
+            subscription: subPda,
+        })
+            .rpc();
+    }
+    async close(agentWallet, subId = 0) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+        return this.methods
+            .closeSubscription()
+            .accounts({
+            subscriber: this.walletPubkey,
+            subscription: subPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    async fetch(agentPda, subscriber, subId = 0) {
+        const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+        return this.fetchAccount("subscriptionAccount", pda);
+    }
+    async fetchNullable(agentPda, subscriber, subId = 0) {
+        const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+        return this.fetchAccountNullable("subscriptionAccount", pda);
+    }
+    async fetchByPda(subPda) {
+        return this.fetchAccount("subscriptionAccount", subPda);
+    }
+}
+//# sourceMappingURL=subscription.js.map

package/dist/esm/modules/subscription.js.map

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

package/dist/esm/modules/tools.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @module tools
+ * @description Tool schema registry and session checkpoints for the
+ * Synapse Agent Protocol.
+ *
+ * Covers: publish, inscribe schema, update, deactivate/reactivate,
+ * close, report invocations, and session checkpoint management.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import type { ToolDescriptorData, SessionCheckpointData, PublishToolArgs, UpdateToolArgs, InscribeToolSchemaArgs } from "../types";
+/**
+ * @name ToolsModule
+ * @description Manages tool descriptors and session checkpoints for the
+ *   Synapse Agent Protocol. Provides methods to publish, update, deactivate,
+ *   reactivate, close, and fetch tool descriptors, as well as inscribe
+ *   JSON schemas into TX logs and manage session checkpoints.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Publish a tool by name (auto-hashes)
+ * const sig = await sap.tools.publishByName(
+ *   "getWeather", "mcp-v1", "Fetch weather",
+ *   '{"type":"object"}', '{"type":"object"}',
+ *   0, 1, 2, 1, false,
+ * );
+ * ```
+ */
+export declare class ToolsModule extends BaseModule {
+    /**
+     * @name deriveTool
+     * @description Derive the `ToolDescriptor` PDA for a given agent and tool name.
+     *   The tool name is SHA-256 hashed internally.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns A tuple of `[PublicKey, bump]` for the tool PDA.
+     * @see {@link deriveTool} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveTool(agentPda: PublicKey, toolName: string): readonly [PublicKey, number];
+    /**
+     * @name publish
+     * @description Publish a new tool descriptor for an agent using pre-computed
+     *   hashes. For auto-hashing, prefer {@link publishByName}.
+     * @param args - Tool publication parameters (name, hashes, HTTP method, category, params, etc.).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    publish(args: PublishToolArgs): Promise<TransactionSignature>;
+    /**
+     * @name publishByName
+     * @description Convenience method to publish a tool using string names.
+     *   All string arguments are automatically SHA-256 hashed.
+     * @param toolName - Human-readable tool name.
+     * @param protocolId - Protocol identifier (e.g. `"mcp-v1"`).
+     * @param description - Tool description text.
+     * @param inputSchema - JSON schema string for input validation.
+     * @param outputSchema - JSON schema string for output validation.
+     * @param httpMethod - Numeric HTTP method enum value.
+     * @param category - Numeric tool category enum value.
+     * @param paramsCount - Total number of parameters.
+     * @param requiredParams - Number of required parameters.
+     * @param isCompound - Whether the tool is a compound (multi-step) tool.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    publishByName(toolName: string, protocolId: string, description: string, inputSchema: string, outputSchema: string, httpMethod: number, category: number, paramsCount: number, requiredParams: number, isCompound: boolean): Promise<TransactionSignature>;
+    /**
+     * @name inscribeSchema
+     * @description Inscribe a full JSON schema into the transaction log (zero rent).
+     *   The schema is stored as TX log data, not as PDA account data.
+     * @param toolName - The human-readable tool name.
+     * @param args - Schema inscription parameters (type, data, hash, compression).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    inscribeSchema(toolName: string, args: InscribeToolSchemaArgs): Promise<TransactionSignature>;
+    /**
+     * @name update
+     * @description Update a tool’s schema hashes and bump its version.
+     *   All fields are optional — only non-null values are written.
+     * @param toolName - The human-readable tool name.
+     * @param args - Partial update parameters (hashes, method, category, params).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    update(toolName: string, args: UpdateToolArgs): Promise<TransactionSignature>;
+    /**
+     * @name deactivate
+     * @description Deactivate a tool. The tool remains discoverable but is
+     *   marked as unavailable.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    deactivate(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name reactivate
+     * @description Reactivate a previously deactivated tool.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    reactivate(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name close
+     * @description Close a tool PDA and reclaim rent to the owner wallet.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    close(toolName: string): Promise<TransactionSignature>;
+    /**
+     * @name reportInvocations
+     * @description Report tool invocation count. Updates the on-chain counter
+     *   for analytics and discovery ranking.
+     * @param toolName - The human-readable tool name.
+     * @param invocations - The number of invocations to report.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    reportInvocations(toolName: string, invocations: number | bigint): Promise<TransactionSignature>;
+    /**
+     * @name createCheckpoint
+     * @description Create a checkpoint snapshot of the current session state.
+     *   Checkpoints are indexed by session PDA and checkpoint index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    createCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<TransactionSignature>;
+    /**
+     * @name closeCheckpoint
+     * @description Close a checkpoint PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    closeCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<TransactionSignature>;
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `ToolDescriptor` account.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData>} The tool descriptor data.
+     * @throws Will throw if the tool descriptor does not exist.
+     * @since v0.1.0
+     */
+    fetch(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData>;
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `ToolDescriptor` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param toolName - The human-readable tool name.
+     * @returns {Promise<ToolDescriptorData | null>} The tool data or `null`.
+     * @since v0.1.0
+     */
+    fetchNullable(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData | null>;
+    /**
+     * @name fetchCheckpoint
+     * @description Fetch a deserialized `SessionCheckpoint` account by session PDA and index.
+     * @param sessionPda - The session ledger PDA.
+     * @param checkpointIndex - The zero-based checkpoint index.
+     * @returns {Promise<SessionCheckpointData>} The checkpoint data.
+     * @throws Will throw if the checkpoint does not exist.
+     * @since v0.1.0
+     */
+    fetchCheckpoint(sessionPda: PublicKey, checkpointIndex: number): Promise<SessionCheckpointData>;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/esm/modules/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/modules/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAOpC,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,sBAAsB,EACvB,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,WAAY,SAAQ,UAAU;IAGzC;;;;;;;;;OASG;IACH,UAAU,CACR,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,MAAM,GACf,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAM/B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyDnE;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,oBAAoB,CAAC;IA8BhC;;;;;;;;OAQG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAmBhC;;;;;;;;OAQG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAsBhC;;;;;;;OAOG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcjE;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcjE;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgB5D;;;;;;;;OAQG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IAgBhC;;;;;;;;OAQG;IACG,gBAAgB,CACpB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;OAOG;IACG,eAAe,CACnB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAehC;;;;;;;;OAQG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAK/E;;;;;;;;OAQG;IACG,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAK9F;;;;;;;;OAQG;IACG,eAAe,CACnB,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,qBAAqB,CAAC;CAIlC"}