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

package/dist/cjs/modules/vault.js

@@ -0,0 +1,427 @@
+"use strict";
+/**
+ * @module vault
+ * @description Encrypted memory vault — init, session management, inscribe,
+ * delegate access, nonce rotation, and close operations.
+ *
+ * Vaults provide encrypted, session-scoped memory storage for agents,
+ * with support for epoch-based pagination and hot-wallet delegation.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultModule = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const base_1 = require("./base");
+const pda_1 = require("../pda");
+const payments_1 = require("../constants/payments");
+const anchor_errors_1 = require("../utils/anchor-errors");
+/**
+ * @name VaultModule
+ * @description Manages encrypted memory vaults for the Synapse Agent Protocol.
+ *   Provides methods to initialise vaults, open/close sessions, inscribe
+ *   encrypted data, manage delegates (hot wallets), rotate nonces, and
+ *   fetch all related account types.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Initialize a vault
+ * await sap.vault.initVault([...nonce]);
+ * // Open a session and inscribe data
+ * await sap.vault.openSession([...sessionHash]);
+ * ```
+ */
+class VaultModule extends base_1.BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveVault
+     * @description Derive the `MemoryVault` PDA for a given agent.
+     * @param agentPda - The agent account PDA.
+     * @returns A tuple of `[PublicKey, bump]` for the vault PDA.
+     * @see {@link deriveVault} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveVault(agentPda) {
+        return (0, pda_1.deriveVault)(agentPda);
+    }
+    /**
+     * @name deriveSession
+     * @description Derive the `SessionLedger` PDA for a given vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - A unique session identifier (32 bytes).
+     * @returns A tuple of `[PublicKey, bump]` for the session PDA.
+     * @see {@link deriveSession} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveSession(vaultPda, sessionHash) {
+        return (0, pda_1.deriveSession)(vaultPda, sessionHash);
+    }
+    // ── Vault Lifecycle ──────────────────────────────────
+    /**
+     * @name initVault
+     * @description Initialize an encrypted memory vault for the caller's agent.
+     *   Creates the `MemoryVault` PDA and sets the initial encryption nonce.
+     * @param vaultNonce - The initial encryption nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async initVault(vaultNonce) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        const [globalPda] = (0, pda_1.deriveGlobalRegistry)();
+        return this.methods
+            .initVault(vaultNonce)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            vault: vaultPda,
+            globalRegistry: globalPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name openSession
+     * @description Open a new session within a vault. Creates a `SessionLedger`
+     *   PDA identified by the session hash.
+     * @param sessionHash - A unique session identifier (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async openSession(sessionHash) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        const [sessionPda] = (0, pda_1.deriveSession)(vaultPda, new Uint8Array(sessionHash));
+        return this.methods
+            .openSession(sessionHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name inscribe
+     * @description Inscribe encrypted data into the transaction log.
+     *   Account resolution is handled by Anchor via remaining accounts.
+     * @param args - Inscription parameters (sequence, encrypted data, nonce, content hash, fragments, compression, epoch).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribe(args) {
+        // Session PDA is passed via remaining accounts resolution by Anchor
+        // For now, we build accounts manually
+        return this.methods
+            .inscribeMemory(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .rpc();
+    }
+    /**
+     * @name inscribeWithAccounts
+     * @description Full inscribe with explicit session and epoch page PDAs.
+     *   Use this when you need manual control over account resolution.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA for the target epoch.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribeWithAccounts(sessionPda, epochPagePda, vaultPda, args) {
+        return this.methods
+            .inscribeMemory(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+            epochPage: epochPagePda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name compactInscribe
+     * @description Simplified inscription (4 args vs 8) for single-fragment writes.
+     * @param sessionPda - The session ledger PDA.
+     * @param vaultPda - The memory vault PDA.
+     * @param args - Compact inscription parameters (sequence, encrypted data, nonce, content hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async compactInscribe(sessionPda, vaultPda, args) {
+        return this.methods
+            .compactInscribe(args.sequence, args.encryptedData, args.nonce, args.contentHash)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeSession
+     * @description Close a session — no more inscriptions will be allowed.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeSession(vaultPda, sessionPda) {
+        return this.methods
+            .closeSession()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeVault
+     * @description Close the `MemoryVault` PDA and reclaim rent to the owner wallet.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeVault() {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        return this.methods
+            .closeVault()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            vault: vaultPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeSessionPda
+     * @description Close a `SessionLedger` PDA (session must be closed first).
+     *   Reclaims rent to the owner wallet.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA to close.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeSessionPda(vaultPda, sessionPda) {
+        return this.methods
+            .closeSessionPda()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            session: sessionPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeEpochPage
+     * @description Close an `EpochPage` PDA and reclaim rent.
+     * @param sessionPda - The session ledger PDA that owns this epoch page.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async closeEpochPage(sessionPda, epochIndex) {
+        const [epochPda] = (0, pda_1.deriveEpochPage)(sessionPda, epochIndex);
+        return this.methods
+            .closeEpochPage(epochIndex)
+            .accounts({
+            wallet: this.walletPubkey,
+            session: sessionPda,
+            epochPage: epochPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name rotateNonce
+     * @description Rotate the vault encryption nonce. All future inscriptions
+     *   will use the new nonce.
+     * @param newNonce - The replacement nonce (byte array).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async rotateNonce(newNonce) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        return this.methods
+            .rotateVaultNonce(newNonce)
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+        })
+            .rpc();
+    }
+    // ── Delegation ───────────────────────────────────────
+    /**
+     * @name addDelegate
+     * @description Authorize a delegate (hot wallet) for vault operations.
+     *   Creates a `VaultDelegate` PDA with the specified permissions and expiry.
+     * @param delegatePubkey - The public key of the delegate wallet to authorize.
+     * @param permissions - Bitmask of permitted operations.
+     * @param expiresAt - Unix timestamp when delegation expires.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async addDelegate(delegatePubkey, permissions, expiresAt) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        const [delegatePda] = (0, pda_1.deriveVaultDelegate)(vaultPda, delegatePubkey);
+        // v0.13.0 preflight — on-chain rejects expiry > now + MAX_DELEGATE_DURATION_SECS
+        // (365 days). Catch this client-side instead of burning the tx.
+        const exp = typeof expiresAt === "bigint" ? expiresAt : BigInt(expiresAt);
+        const nowSec = BigInt(Math.floor(Date.now() / 1000));
+        if (exp <= nowSec) {
+            (0, anchor_errors_1.throwPredicted)("DelegateExpired", `expiresAt ${exp} is in the past (now ${nowSec})`);
+        }
+        const maxExp = nowSec + BigInt(payments_1.MAX_DELEGATE_DURATION_SECS);
+        if (exp > maxExp) {
+            (0, anchor_errors_1.throwPredicted)("DelegateExpiryInvalid", `expiresAt ${exp} > now+MAX (${maxExp}); cap is ${payments_1.MAX_DELEGATE_DURATION_SECS}s (365 days)`);
+        }
+        if (permissions === 0) {
+            (0, anchor_errors_1.throwPredicted)("InvalidDelegate", "permissions bitmask cannot be 0");
+        }
+        await this.requireAccountAbsent("vaultDelegate", delegatePda, "Delegate already exists — revokeDelegate first or use a different delegate wallet");
+        return this.methods
+            .addVaultDelegate(permissions, this.bn(expiresAt))
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            delegate: delegatePda,
+            delegateWallet: delegatePubkey,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name revokeDelegate
+     * @description Revoke a delegate’s authorization, closing their `VaultDelegate` PDA.
+     * @param delegatePubkey - The public key of the delegate wallet to revoke.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async revokeDelegate(delegatePubkey) {
+        const [agentPda] = (0, pda_1.deriveAgent)(this.walletPubkey);
+        const [vaultPda] = (0, pda_1.deriveVault)(agentPda);
+        const [delegatePda] = (0, pda_1.deriveVaultDelegate)(vaultPda, delegatePubkey);
+        return this.methods
+            .revokeVaultDelegate()
+            .accounts({
+            wallet: this.walletPubkey,
+            vault: vaultPda,
+            delegate: delegatePda,
+        })
+            .rpc();
+    }
+    /**
+     * @name inscribeDelegated
+     * @description Inscribe data via an authorized delegate (hot wallet).
+     *   The transaction is signed by the delegate instead of the vault owner.
+     * @param delegateWallet - The delegate wallet public key.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochPagePda - The epoch page PDA.
+     * @param args - Inscription parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async inscribeDelegated(delegateWallet, vaultPda, sessionPda, epochPagePda, args) {
+        const [delegatePda] = (0, pda_1.deriveVaultDelegate)(vaultPda, delegateWallet);
+        return this.methods
+            .inscribeMemoryDelegated(args.sequence, args.encryptedData, args.nonce, args.contentHash, args.totalFragments, args.fragmentIndex, args.compression, args.epochIndex)
+            .accounts({
+            delegateWallet,
+            vault: vaultPda,
+            delegateAuth: delegatePda,
+            session: sessionPda,
+            epochPage: epochPagePda,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetchVault
+     * @description Fetch a deserialized `MemoryVault` account.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData>} The vault account data.
+     * @throws Will throw if the vault account does not exist.
+     * @since v0.1.0
+     */
+    async fetchVault(agentPda) {
+        const [pda] = (0, pda_1.deriveVault)(agentPda);
+        return this.fetchAccount("memoryVault", pda);
+    }
+    /**
+     * @name fetchVaultNullable
+     * @description Fetch a deserialized `MemoryVault` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<MemoryVaultData | null>} The vault data or `null`.
+     * @since v0.1.0
+     */
+    async fetchVaultNullable(agentPda) {
+        const [pda] = (0, pda_1.deriveVault)(agentPda);
+        return this.fetchAccountNullable("memoryVault", pda);
+    }
+    /**
+     * @name fetchSession
+     * @description Fetch a deserialized `SessionLedger` account by vault and session hash.
+     * @param vaultPda - The memory vault PDA.
+     * @param sessionHash - The session identifier used during creation.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    async fetchSession(vaultPda, sessionHash) {
+        const [pda] = (0, pda_1.deriveSession)(vaultPda, sessionHash);
+        return this.fetchAccount("sessionLedger", pda);
+    }
+    /**
+     * @name fetchSessionByPda
+     * @description Fetch a deserialized `SessionLedger` account by its PDA directly,
+     *   bypassing PDA derivation.
+     * @param sessionPda - The session ledger PDA.
+     * @returns {Promise<SessionLedgerData>} The session ledger data.
+     * @throws Will throw if the session does not exist.
+     * @since v0.1.0
+     */
+    async fetchSessionByPda(sessionPda) {
+        return this.fetchAccount("sessionLedger", sessionPda);
+    }
+    /**
+     * @name fetchEpochPage
+     * @description Fetch a deserialized `EpochPage` account.
+     * @param sessionPda - The session ledger PDA.
+     * @param epochIndex - The zero-based epoch index.
+     * @returns {Promise<EpochPageData>} The epoch page data.
+     * @throws Will throw if the epoch page does not exist.
+     * @since v0.1.0
+     */
+    async fetchEpochPage(sessionPda, epochIndex) {
+        const [pda] = (0, pda_1.deriveEpochPage)(sessionPda, epochIndex);
+        return this.fetchAccount("epochPage", pda);
+    }
+    /**
+     * @name fetchDelegate
+     * @description Fetch a deserialized `VaultDelegate` account.
+     * @param vaultPda - The memory vault PDA.
+     * @param delegatePubkey - The delegate wallet public key.
+     * @returns {Promise<VaultDelegateData>} The delegate account data.
+     * @throws Will throw if the delegate does not exist.
+     * @since v0.1.0
+     */
+    async fetchDelegate(vaultPda, delegatePubkey) {
+        const [pda] = (0, pda_1.deriveVaultDelegate)(vaultPda, delegatePubkey);
+        return this.fetchAccount("vaultDelegate", pda);
+    }
+}
+exports.VaultModule = VaultModule;
+//# sourceMappingURL=vault.js.map

package/dist/cjs/modules/vault.js.map

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

package/dist/cjs/parser/client.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * @module parser/client
+ * @description Object-oriented wrapper for transaction parsing.
+ *
+ * Binds the Anchor `Program` reference so callers do not need to
+ * pass it on every call. Designed as a lazy singleton accessible
+ * from {@link SapClient.parser}.
+ *
+ * @category Parser
+ * @since v0.5.0
+ *
+ * @example
+ * ```ts
+ * const client = SapClient.from(provider);
+ *
+ * // Parse a full transaction
+ * const parsed = client.parser.parseTransaction(txResponse);
+ *
+ * // Quick instruction names
+ * const names = client.parser.instructionNames(txResponse);
+ *
+ * // From pre-built instructions
+ * const decoded = client.parser.fromInstructions(ixList);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionParser = void 0;
+const transaction_1 = require("./transaction");
+const instructions_1 = require("./instructions");
+const complete_1 = require("./complete");
+const inner_1 = require("./inner");
+/**
+ * Stateful transaction parser bound to a specific Anchor `Program`.
+ *
+ * Stores the program reference, instruction coder, and program ID
+ * internally so that repeated parse calls require only the
+ * transaction data as input.
+ *
+ * @name TransactionParser
+ * @category Parser
+ * @since v0.5.0
+ */
+class TransactionParser {
+    program;
+    coder;
+    programId;
+    /**
+     * Create a new TransactionParser.
+     *
+     * @param program - An Anchor `Program` built from the SAP IDL.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(program) {
+        this.program = program;
+        this.coder = program.coder.instruction;
+        this.programId = program.programId;
+    }
+    /**
+     * Full parse: instructions + inner calls + events.
+     *
+     * @param tx - Raw transaction response from `connection.getTransaction`.
+     * @param options - Optional filters for instructions, events, and inner calls.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Complete parsed transaction, or `null` if the input is nullish.
+     *
+     * @since v0.5.0
+     */
+    parseTransaction(tx, options, addressLookupTables) {
+        return (0, complete_1.parseSapTransactionComplete)(tx, this.program, this.programId, options, addressLookupTables);
+    }
+    /**
+     * Parse a batch of transactions.
+     *
+     * @param txs - Array of transaction responses (may contain `null` entries).
+     * @param options - Optional parse filters.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Non-null parsed transactions.
+     *
+     * @since v0.5.0
+     */
+    parseBatch(txs, options, addressLookupTables) {
+        return (0, complete_1.parseSapTransactionBatch)(txs, this.program, this.programId, options, addressLookupTables);
+    }
+    /**
+     * Decode top-level SAP instructions from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    instructionsFromTransaction(tx, addressLookupTables) {
+        return (0, transaction_1.parseSapInstructionsFromTransaction)(tx, this.coder, this.programId, addressLookupTables);
+    }
+    /**
+     * Extract only the instruction names from a transaction response.
+     *
+     * @param tx - Raw transaction response.
+     * @param addressLookupTables - Resolved lookup tables for v0 transactions.
+     * @returns Instruction name strings.
+     *
+     * @since v0.5.0
+     */
+    instructionNames(tx, addressLookupTables) {
+        return this.instructionsFromTransaction(tx, addressLookupTables).map((ix) => ix.name);
+    }
+    /**
+     * Decode SAP instructions from a pre-built instruction array.
+     *
+     * @param instructions - The instruction list to decode.
+     * @returns Decoded SAP instructions.
+     *
+     * @since v0.5.0
+     */
+    fromInstructions(instructions) {
+        return (0, instructions_1.parseSapInstructionsFromList)(instructions, this.coder, this.programId);
+    }
+    /**
+     * Check if any instruction in the list targets the SAP program.
+     *
+     * @param instructions - The instruction array to inspect.
+     * @returns `true` if at least one instruction targets SAP.
+     *
+     * @since v0.5.0
+     */
+    isSapTransaction(instructions) {
+        return (0, instructions_1.containsSapInstruction)(instructions, this.programId);
+    }
+    /**
+     * Decode inner (CPI) instructions from transaction metadata.
+     *
+     * @param innerGroups - The `tx.meta.innerInstructions` array.
+     * @param tx - The transaction response (for account key resolution).
+     * @returns Decoded inner instructions.
+     *
+     * @since v0.5.0
+     */
+    decodeInner(innerGroups, tx) {
+        const accountKeys = (0, inner_1.extractAccountKeys)(tx);
+        return (0, inner_1.decodeInnerInstructions)(innerGroups, accountKeys, this.coder, this.programId);
+    }
+}
+exports.TransactionParser = TransactionParser;
+//# sourceMappingURL=client.js.map

package/dist/cjs/parser/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/parser/client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAiBH,+CAAoE;AACpE,iDAAsF;AACtF,yCAAmF;AACnF,mCAIiB;AAEjB;;;;;;;;;;GAUG;AACH,MAAa,iBAAiB;IAUC;IATZ,KAAK,CAAsB;IAC3B,SAAS,CAAY;IAEtC;;;;OAIG;IACH,8DAA8D;IAC9D,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;QAChD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,WAA6C,CAAC;QACzE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;;;;;;;;OASG;IACH,gBAAgB,CACd,EAAyE,EACzE,OAA4B,EAC5B,mBAAiD;QAEjD,OAAO,IAAA,sCAA2B,EAChC,EAAE,EACF,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,SAAS,EACd,OAAO,EACP,mBAAmB,CACpB,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,UAAU,CACR,GAA8E,EAC9E,OAA4B,EAC5B,mBAAiD;QAEjD,OAAO,IAAA,mCAAwB,EAC7B,GAAG,EACH,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,SAAS,EACd,OAAO,EACP,mBAAmB,CACpB,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,2BAA2B,CACzB,EAAsD,EACtD,mBAAiD;QAEjD,OAAO,IAAA,iDAAmC,EACxC,EAAE,EACF,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,SAAS,EACd,mBAAmB,CACpB,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,gBAAgB,CACd,EAAsD,EACtD,mBAAiD;QAEjD,OAAO,IAAI,CAAC,2BAA2B,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC,GAAG,CAClE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAChB,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,gBAAgB,CACd,YAAsC;QAEtC,OAAO,IAAA,2CAA4B,EAAC,YAAY,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;OAOG;IACH,gBAAgB,CAAC,YAAsC;QACrD,OAAO,IAAA,qCAAsB,EAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CACT,WAAoC,EACpC,EAAsD;QAEtD,MAAM,WAAW,GAAG,IAAA,0BAAkB,EAAC,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAA,+BAAuB,EAC5B,WAAW,EACX,WAAW,EACX,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;CACF;AArJD,8CAqJC"}