@eco-incorp/sauce 0.99.0

package/sdk/dist/svm/intent.js

@@ -0,0 +1,213 @@
+// @eco-incorp/sauce/svm/verify — extract settle params from an Eco intent's SVM calls.
+//
+// The EVM twin (`@eco-incorp/sauce/verify`'s `extractEvmSettleFromIntent`) reads the settle program
+// straight out of a `Pot.cook(bytes[])` call, because an EVM intent's `route.calls[].data` is plain ABI
+// calldata. An SVM intent is one wrapper deeper: each `route.calls[].data` is the Eco **Portal**
+// program's `CalldataWithAccounts` Borsh envelope — `{ calldata: { data, account_count }, accounts:
+// [{ pubkey, is_signer, is_writable }] }` — where `calldata.data` is the Sauce engine's
+// `execute_from_account` instruction data (`[disc][flags][pin?][slice?][args]`) and `accounts` is that
+// instruction's account list. This module decodes that envelope and hands the two halves to
+// `decodeSvmSettleExecution` / `verifySvmSettleExecution`, so an external partner goes from a published
+// intent to the staged-execute header + resolved account identities with ONLY this package. `minOut`
+// and `splCount` are NOT decodable -- they are defines folded into the bytecode -- so a partner who
+// needs them states them as an expectation and `verifySvmSettleExecution` establishes them by
+// recompiling and byte-comparing. See `verify.ts`'s note on `DecodedSvmSettleExecution`.
+//
+// WHY THIS LIVES IN THE SDK (not in a solver adapter): this surface is for partners CONSUMING Eco
+// intents, who have neither the solver's internals nor its `decodeRouteCall`. So the Portal envelope
+// layout is mirrored here — it is a small, stable on-chain Anchor struct (Portal program IDL), decoded
+// with `@solana/kit` codecs (no new dependency). `test/svm/intent.test.ts` pins the byte layout against
+// a hand-built fixture so a Portal IDL change can't drift it silently.
+//
+// GENUINENESS WITHOUT PARTNER BYTECODE. A staged settle carries no structural signature (unlike an
+// EVM settle, whose whole program is a constant that hashes to a pinned value — see
+// `@eco-incorp/sauce/verify`'s `validateSettleProgram`), so "right shape" is NOT "is a settle" —
+// a non-settle staged execute, or an adversarial
+// decoy, has the same shape. The extraction here therefore does not trust shape: it recompiles the
+// canonical `svmSettleSource(N)` ITSELF and requires the calldata pin to equal `sha256(canonical settle)`
+// (or, if the caller passes the staged `bytecode` from `fulfillmentMetadata.svm.sauceStage`, a full
+// byte-match). A partner needs no bytecode to get a genuine verdict; a decoy is REJECTED, not returned.
+import { addDecoderSizePrefix, addEncoderSizePrefix, address, getArrayDecoder, getArrayEncoder, getAddressDecoder, getAddressEncoder, getBooleanDecoder, getBooleanEncoder, getBytesDecoder, getBytesEncoder, getStructDecoder, getStructEncoder, getU8Decoder, getU8Encoder, getU32Decoder, getU32Encoder, } from "@solana/kit";
+import { verifySvmSettleExecution, } from "./verify.js";
+// Borsh (Anchor): `bytes` = u32 LE length prefix + bytes; `Vec<T>` = u32 LE length + elements;
+// `bool` = 1 byte; `pubkey` = 32 bytes; `u8` = 1 byte. Field order is the IDL struct order.
+const calldataDecoder = getStructDecoder([
+    ["data", addDecoderSizePrefix(getBytesDecoder(), getU32Decoder())],
+    ["accountCount", getU8Decoder()],
+]);
+const accountMetaDecoder = getStructDecoder([
+    ["pubkey", getAddressDecoder()],
+    ["isSigner", getBooleanDecoder()],
+    ["isWritable", getBooleanDecoder()],
+]);
+const calldataWithAccountsDecoder = getStructDecoder([
+    ["calldata", calldataDecoder],
+    ["accounts", getArrayDecoder(accountMetaDecoder, { size: getU32Decoder() })],
+]);
+function toBytes(input, label) {
+    if (input instanceof Uint8Array)
+        return input;
+    if (typeof input !== "string")
+        throw new Error(`${label} must be a Uint8Array or string, got ${typeof input}`);
+    if (input.startsWith("0x") || input.startsWith("0X")) {
+        const hex = input.slice(2);
+        if (hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex))
+            throw new Error(`${label} is not valid 0x-hex`);
+        const out = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < out.length; i++)
+            out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+        return out;
+    }
+    // Not 0x-prefixed → base64 (Buffer is available; this module is node-side like the rest of svm/verify).
+    return new Uint8Array(Buffer.from(input, "base64"));
+}
+/** Resolves any `UniversalAddressInput` to the base58 `Address` form the rest of a settle verdict reports
+ *  accounts in, so it compares directly against a program id. Throws on input that is not a 32-byte
+ *  universal address; `resolveSettleTarget` is what makes that non-fatal for a scan. */
+function toTargetAddress(input) {
+    if (typeof input === "string" && !input.startsWith("0x") && !input.startsWith("0X"))
+        return address(input);
+    const bytes = toBytes(input, "target");
+    if (bytes.length !== 32)
+        throw new Error(`target is ${bytes.length} bytes — an SVM universal address is 32`);
+    return getAddressDecoder().decode(bytes);
+}
+/**
+ * Decodes a Portal `CalldataWithAccounts` envelope (the form of every SVM `route.calls[].data`) into the
+ * wrapped instruction data and its account list. Accepts the envelope as raw bytes, `0x`-hex (the viem
+ * `Hex` a call carries), or base64. Throws on a truncated / malformed envelope.
+ */
+export function decodePortalCalldataWithAccounts(data) {
+    const bytes = toBytes(data, "portal calldata");
+    const decoded = calldataWithAccountsDecoder.decode(bytes);
+    // Both `account_count` (the Calldata field) and the attached `accounts` vec length are decoded and
+    // surfaced; they are NOT asserted equal here. eco-solver's own `decodeRouteCall` does not enforce it
+    // either, and the exact `account_count` semantics for the settle envelope (whether it counts the
+    // leading buffer account) are not something to hard-fail a partner's decode on — a caller that wants
+    // the check can compare `accountCount` against `accounts.length` itself.
+    return {
+        // @solana/kit's bytes decoder yields a ReadonlyUint8Array — copy to a plain Uint8Array so the
+        // downstream payload parser (subarray / DataView) has a mutable, standard view.
+        instructionData: new Uint8Array(decoded.calldata.data),
+        accountCount: decoded.calldata.accountCount,
+        accounts: decoded.accounts.map((a) => ({
+            pubkey: a.pubkey,
+            isSigner: a.isSigner,
+            isWritable: a.isWritable,
+        })),
+    };
+}
+// Encoder side of the exact same envelope — kept beside the decoder above so the Portal
+// `CalldataWithAccounts` Borsh layout has exactly one source of truth (field order, u32-length
+// prefixes, u8 account_count, u32-length-prefixed accounts vec).
+const calldataEncoder = getStructEncoder([
+    ["data", addEncoderSizePrefix(getBytesEncoder(), getU32Encoder())],
+    ["accountCount", getU8Encoder()],
+]);
+const accountMetaEncoder = getStructEncoder([
+    ["pubkey", getAddressEncoder()],
+    ["isSigner", getBooleanEncoder()],
+    ["isWritable", getBooleanEncoder()],
+]);
+const calldataWithAccountsEncoder = getStructEncoder([
+    ["calldata", calldataEncoder],
+    ["accounts", getArrayEncoder(accountMetaEncoder, { size: getU32Encoder() })],
+]);
+/**
+ * Encodes a Portal `CalldataWithAccounts` envelope — the exact inverse of
+ * {@link decodePortalCalldataWithAccounts}, sharing its codec byte-for-byte (both are built from the
+ * same field list above), so encoder and decoder cannot drift apart. This is what a route `Call.data`
+ * for a staged SVM Sauce execution looks like on the wire.
+ */
+export function encodePortalCalldataWithAccounts(input) {
+    const accountCount = input.accountCount ?? input.accounts.length;
+    const encoded = calldataWithAccountsEncoder.encode({
+        calldata: { data: input.instructionData, accountCount },
+        accounts: input.accounts.map((a) => ({
+            pubkey: a.pubkey,
+            isSigner: a.isSigner,
+            isWritable: a.isWritable,
+        })),
+    });
+    return `0x${Buffer.from(Uint8Array.from(encoded)).toString("hex")}`;
+}
+/** Total, so the `… | null` scan around it stays total: a `target` this cannot resolve becomes
+ *  `unreadable` rather than an exception thrown out of a function no caller of that type would guard. */
+function resolveSettleTarget(input) {
+    if (input === undefined)
+        return { kind: "absent" };
+    try {
+        return { kind: "program", address: toTargetAddress(input) };
+    }
+    catch (error) {
+        return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Scans SVM intent calls and returns the first call that is a GENUINE settle execution — the SVM twin of
+ * `extractEvmSettleFromCalls`. Each call is a Portal envelope; the settle is found by VERIFYING it
+ * (`verifySvmSettleExecution`), not by shape: the calldata pin must equal `sha256` of the SDK's own
+ * recompiled canonical settle (or the supplied `bytecode` must byte-match it). A shape-only lookalike or
+ * an adversarial decoy is REJECTED — the scan keeps going and never returns a non-genuine call — so this
+ * cannot be tricked into reporting attacker-chosen params: `minOut`/`splCount` are what the CALLER
+ * expects, and a genuine verdict is itself the proof the program enforces them. Returns `null` if no
+ * call is a genuine settle.
+ *
+ * (To inspect a call's raw structural params without a genuineness proof — e.g. a decoy's claimed values —
+ * decode the envelope with `decodePortalCalldataWithAccounts` and call `decodeSvmSettleExecution` directly.)
+ *
+ * AND IT MUST VALIDATE `target`. Matching is on the envelope's instruction data ONLY — nothing here looks
+ * at the callee. The pin is not self-enforcing, and not engine-enforced either: the released engine's
+ * `execute_from_account` has no payload to check one against, so a pin is an assertion by whoever
+ * supplied it — and on this path that is the untrusted call object itself. It says nothing about an
+ * arbitrary program that merely accepts the same discriminator. For `[{ target: attackerProgram, data: <envelope pinned to the canonical settle> }]` this returns
+ * a `genuine` verdict while the attacker's program runs whatever it likes. `target` is carried through on
+ * the result for exactly this check — require `{ kind: 'program' }` and compare its `address` against the
+ * Sauce engine program id you trust (`v12SvmProgramId`). `absent` (the call named no callee) and
+ * `unreadable` (it named something that is not a 32-byte universal address) are NOT interchangeable, and
+ * neither clears the call. Unvalidated, a genuine verdict describes bytes handed to an unknown program.
+ */
+export function extractSvmSettleFromCalls(calls, options) {
+    const bytecode = options.bytecode !== undefined ? toBytes(options.bytecode, "bytecode") : undefined;
+    for (let i = 0; i < calls.length; i++) {
+        let envelope;
+        try {
+            envelope = decodePortalCalldataWithAccounts(calls[i].data);
+        }
+        catch {
+            continue; // not a decodable Portal envelope — skip
+        }
+        let verified;
+        try {
+            verified = verifySvmSettleExecution({
+                pin: calls[i].pin !== undefined ? toBytes(calls[i].pin, "pin") : undefined,
+                instructionData: envelope.instructionData,
+                accounts: envelope.accounts,
+                bytecode,
+                minOut: options.minOut,
+                splCount: options.splCount,
+            });
+        }
+        catch {
+            continue; // a decodable envelope, but its instruction is not even settle-SHAPED — skip
+        }
+        if (verified.genuine)
+            return { ...verified, callIndex: i, target: resolveSettleTarget(calls[i].target) };
+        // shape-matched but NOT a genuine settle (decoy / wrong program / wrong escrow count) — keep scanning,
+        // so a genuine settle later in the batch is never masked by an earlier lookalike.
+    }
+    return null;
+}
+/**
+ * Extracts the GENUINE SVM settle params + resolved account identities from an intent object — the thin
+ * intent-level wrapper over `extractSvmSettleFromCalls`, and the SVM twin of `extractEvmSettleFromIntent`.
+ * Duck-typed on `{ route: { calls } }`, so it takes an eco-solver `Intent` (runtime or persisted) as-is.
+ * Genuineness is proven from the intent alone (recompile + pin); pass `options.bytecode` (from the
+ * intent's `fulfillmentMetadata.svm.sauceStage`) for the additional full byte-match. `null` if the intent
+ * carries no genuine settle execution. The `target` duty documented on `extractSvmSettleFromCalls` applies
+ * here unchanged.
+ */
+export function extractSvmSettleFromIntent(intent, options) {
+    return extractSvmSettleFromCalls(intent.route.calls, options);
+}
+//# sourceMappingURL=intent.js.map

package/sdk/dist/svm/intent.js.map

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

package/sdk/dist/svm/kitchen.d.ts

@@ -0,0 +1,205 @@
+import type { AccountLookupMeta, AccountMeta, Address, Instruction } from "@solana/kit";
+/** One entry of a program's own account tail, in the shape a kit `Instruction` carries. */
+export type TailAccount = AccountLookupMeta | AccountMeta;
+/** The kitchen's own `#[constant]`s, from the same IDL. */
+export declare const CODE_BUFFER_SEED = "buffer";
+export declare const CODE_SEED = "code";
+export declare const POT_SEED = "pot";
+export declare const EXECUTION_FEE_SEED = "execution_fee";
+/** One `grow_code_buffer` step: `MAX_PERMITTED_DATA_INCREASE`, the most a CPI-created account can
+ *  grow in a single instruction. IDL-guarded by `engine-wire-drift.test.ts`. */
+export declare const GROWTH_STEP = 10240;
+export declare const MAX_CODE_LEN = 1048576;
+export declare const MAX_POT_LEN = 10240;
+/** A Pot's salt and a code buffer's `expected_sha256` are both exactly 32 bytes. */
+export declare const SALT_BYTES = 32;
+/** The loader that owns every upgradeable program's `ProgramData`, which is where the fee
+ *  instructions read the kitchen's live upgrade authority from. */
+export declare const BPF_LOADER_UPGRADEABLE: Address;
+export interface KitchenPda {
+    address: Address;
+    bump: number;
+}
+/**
+ * A Pot: `["pot", owner, salt]`. The salt is what lets one owner hold many — it is raw bytes, not a
+ * counter, so a caller with a natural 32-byte id (an intent hash, say) passes it directly.
+ */
+export declare function derivePotPda(kitchen: Address, owner: Address, salt: Uint8Array): Promise<KitchenPda>;
+/**
+ * The execution-fee config: `["execution_fee"]`, one per kitchen.
+ *
+ * It is both the fee's source of truth and the treasury the fees accumulate in, so every cook takes
+ * it writable even when the configured fee is zero.
+ */
+export declare function deriveExecutionFeeConfigPda(kitchen: Address): Promise<KitchenPda>;
+/**
+ * A program's `ProgramData` under the upgradeable loader: `[program]`.
+ *
+ * The fee instructions authorize against the authority recorded there rather than a stored admin
+ * key, so whoever can upgrade the kitchen is whoever can price it.
+ */
+export declare function deriveProgramDataPda(program: Address): Promise<KitchenPda>;
+/** A code buffer's metadata account: `["buffer", owner, nonce_le]`. */
+export declare function deriveCodeBufferPda(kitchen: Address, owner: Address, nonce: bigint): Promise<KitchenPda>;
+/**
+ * The bytes account for a buffer: `["code", code_buffer]`.
+ *
+ * Seeded on the METADATA account's address, so the pair is bound by derivation and neither needs to
+ * store a pointer to the other for the kitchen to validate.
+ */
+export declare function deriveCodePda(kitchen: Address, codeBuffer: Address): Promise<KitchenPda>;
+export interface CreatePotInput {
+    kitchen: Address;
+    owner: Address;
+    /** Not validated by the kitchen — see this module's header. */
+    engineProgram: Address;
+    pot: Address;
+    salt: Uint8Array;
+    /** Bounded by `MAX_POT_LEN`; the kitchen rejects anything larger before allocating. */
+    space: number;
+}
+export declare function buildCreatePotInstruction({ kitchen, owner, engineProgram, pot, salt, space, }: CreatePotInput): Instruction;
+export interface ClosePotInput {
+    kitchen: Address;
+    owner: Address;
+    engineProgram: Address;
+    pot: Address;
+    salt: Uint8Array;
+}
+export declare function buildClosePotInstruction({ kitchen, owner, engineProgram, pot, salt, }: ClosePotInput): Instruction;
+export interface CookInput {
+    kitchen: Address;
+    owner: Address;
+    engineProgram: Address;
+    /** Identifies the Pot to sign for. A program that writes Pot storage attaches it again in `tail`,
+     *  writable and unsigned. */
+    potSalt: Uint8Array;
+    /** `derivePotPda(kitchen, owner, potSalt)`. Passed rather than derived so this stays synchronous,
+     *  as `cook_from_account` already does for its buffer accounts. */
+    pot: Address;
+    /** `deriveExecutionFeeConfigPda(kitchen)`. */
+    feeConfig: Address;
+    bytecode: Uint8Array;
+    /** What the caller consents to pay. The cook is refused if the live fee exceeds it, so a quote
+     *  that went stale upward fails closed rather than overcharging. */
+    maxExecutionFee: bigint;
+    /** Who pays it. Defaults to `owner`; a sponsor here does not change `MSG_SENDER`. */
+    feePayer?: Address;
+    /** The program's own accounts, at their natural indices after the kitchen's named ones. */
+    tail?: readonly TailAccount[];
+}
+/**
+ * `cook` — stage-free execution: the bytecode travels in the instruction data.
+ *
+ * **The transaction MUST carry a RequestHeapFrame(`HEAP_FRAME_BYTES`).** The kitchen CPIs into the
+ * engine, whose interpreter memory lives in the transaction's heap frame and not in accounts, so
+ * without it the ENGINE access-violates before any opcode runs — surfacing from the kitchen as an
+ * opaque `ProgramFailedToComplete`. Use `buildHeapFramePrepend()` (`./prepends.js`). Pot and
+ * code-buffer lifecycle instructions need no such thing; only the two cooks execute.
+ *
+ * Note there is no `pot` account here. The kitchen derives it from `pot_salt` and `owner` and signs
+ * for it, so a Pot the program touches belongs in `tail` **unsigned**.
+ */
+export declare function buildCookInstruction({ kitchen, owner, engineProgram, potSalt, pot, feeConfig, bytecode, maxExecutionFee, feePayer, tail, }: CookInput): Instruction;
+export interface CookFromAccountInput {
+    kitchen: Address;
+    owner: Address;
+    codeBuffer: Address;
+    code: Address;
+    engineProgram: Address;
+    potSalt: Uint8Array;
+    pot: Address;
+    feeConfig: Address;
+    /** When given, the kitchen refuses unless the staged bytes hash to it. */
+    pin?: Uint8Array;
+    maxExecutionFee: bigint;
+    feePayer?: Address;
+    tail?: readonly TailAccount[];
+}
+/**
+ * `cook_from_account` — the staged transport: the bytecode is read from a finalized code account.
+ *
+ * Needs the same RequestHeapFrame as `cook` — see there.
+ */
+export declare function buildCookFromAccountInstruction({ kitchen, owner, codeBuffer, code, engineProgram, potSalt, pot, feeConfig, pin, maxExecutionFee, feePayer, tail, }: CookFromAccountInput): Instruction;
+export interface CodeBufferAccounts {
+    kitchen: Address;
+    owner: Address;
+    codeBuffer: Address;
+    code: Address;
+}
+/**
+ * Creates the `codeBuffer` metadata account and its `code` data account, sized for `capacity`.
+ *
+ * `capacity` must be 1..=`MAX_CODE_LEN`; the kitchen rejects anything else with
+ * `CapacityOutOfRange`, and this throws first so the bound is visible without a simulation.
+ *
+ * **A create allocates at most ONE `GROWTH_STEP`.** The runtime caps how much an account can grow
+ * per instruction, so a `capacity` above that is only partly allocated here and needs
+ * `Math.ceil(capacity / GROWTH_STEP) - 1` further `buildGrowCodeBufferInstruction` calls before the
+ * `code` account is the full size. The cap resets per instruction, so those repeats can share one
+ * transaction. Writing before the account is fully grown fails with `WriteOutOfBounds`.
+ */
+export declare function buildCreateCodeBufferInstruction({ kitchen, owner, codeBuffer, code, nonce, capacity, }: CodeBufferAccounts & {
+    nonce: bigint;
+    capacity: number;
+}): Instruction;
+/**
+ * One growth step. A CPI-created account cannot be allocated more than `GROWTH_STEP` at once, so a
+ * larger buffer repeats this — the runtime's limit resets per instruction, so the repeats fit in one
+ * transaction.
+ */
+export declare function buildGrowCodeBufferInstruction({ kitchen, owner, codeBuffer, code, }: CodeBufferAccounts): Instruction;
+export declare function buildWriteCodeBufferInstruction({ kitchen, owner, codeBuffer, code, offset, chunk, }: CodeBufferAccounts & {
+    offset: number;
+    chunk: Uint8Array;
+}): Instruction;
+/**
+ * Seals the buffer at `len` and pins its digest.
+ *
+ * The kitchen shrinks the code account to exactly `len` here, which is the security property: the
+ * engine executes the account's whole data slice and bounds jumps only by that slice's length, so
+ * any byte past `len` would be jump-reachable but outside the hash.
+ */
+export declare function buildFinalizeCodeBufferInstruction({ kitchen, owner, codeBuffer, code, len, expectedSha256, }: CodeBufferAccounts & {
+    len: number;
+    expectedSha256: Uint8Array;
+}): Instruction;
+/** Closes both accounts and refunds their rent. `expectedSha256` gates the close on the staged bytes. */
+export declare function buildCloseCodeBufferInstruction({ kitchen, owner, codeBuffer, code, expectedSha256, }: CodeBufferAccounts & {
+    expectedSha256?: Uint8Array;
+}): Instruction;
+/**
+ * The three fee instructions authorize against the kitchen's LIVE upgrade authority, read from its
+ * `ProgramData` — so the party that can replace the code is the party that can price it, and an
+ * immutable kitchen has a frozen fee and an uncollectable balance. Each therefore takes the kitchen
+ * program and its `ProgramData` as accounts; the constraint links the two, so a foreign program's
+ * `ProgramData` cannot be substituted.
+ */
+export interface ExecutionFeeAdminInput {
+    kitchen: Address;
+    authority: Address;
+    /** `deriveProgramDataPda(kitchen)`. */
+    programData: Address;
+    /** `deriveExecutionFeeConfigPda(kitchen)`. */
+    feeConfig: Address;
+}
+/** `initialize_execution_fee` — creates the config PDA. The initial fee must be greater than zero;
+ *  a kitchen is unusable until it is priced, and a later `set` may take it back to zero. */
+export declare function buildInitializeExecutionFeeInstruction({ kitchen, authority, programData, feeConfig, payer, initialFee, }: ExecutionFeeAdminInput & {
+    payer?: Address;
+    initialFee: bigint;
+}): Instruction;
+/** `set_execution_fee` — repricing, including back to zero. */
+export declare function buildSetExecutionFeeInstruction({ kitchen, authority, programData, feeConfig, fee, }: ExecutionFeeAdminInput & {
+    fee: bigint;
+}): Instruction;
+/** `withdraw_execution_fees` — collect what the config PDA holds. `amount` omitted sweeps everything
+ *  ABOVE the account's rent-exempt minimum, which the withdrawal never spends: that same account is
+ *  the config every cook reads, and a zero balance would have the runtime reap it. The recipient
+ *  must already be rent-exempt, or the runtime refuses the transaction for leaving it rent-paying. */
+export declare function buildWithdrawExecutionFeesInstruction({ kitchen, authority, programData, feeConfig, recipient, amount, }: ExecutionFeeAdminInput & {
+    recipient: Address;
+    amount?: bigint;
+}): Instruction;
+//# sourceMappingURL=kitchen.d.ts.map

package/sdk/dist/svm/kitchen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kitchen.d.ts","sourceRoot":"","sources":["../../src/svm/kitchen.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAExF,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAkB1D,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,WAAW,CAAC;AACzC,eAAO,MAAM,SAAS,SAAS,CAAC;AAChC,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAClD;gFACgF;AAChF,eAAO,MAAM,WAAW,QAAS,CAAC;AAClC,eAAO,MAAM,YAAY,UAAY,CAAC;AACtC,eAAO,MAAM,WAAW,QAAS,CAAC;AAElC,oFAAoF;AACpF,eAAO,MAAM,UAAU,KAAK,CAAC;AAG7B;mEACmE;AACnE,eAAO,MAAM,sBAAsB,EAAoD,OAAO,CAAC;AAE/F,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAoED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAQrB;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAOvF;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAOhF;AAED,uEAAuE;AACvE,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,CAOrB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAO9F;AAID,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAC;IACvB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,KAAK,EACL,aAAa,EACb,GAAG,EACH,IAAI,EACJ,KAAK,GACN,EAAE,cAAc,GAAG,WAAW,CAa9B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,KAAK,EACL,aAAa,EACb,GAAG,EACH,IAAI,GACL,EAAE,aAAa,GAAG,WAAW,CAY7B;AAaD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB;iCAC6B;IAC7B,OAAO,EAAE,UAAU,CAAC;IACpB;uEACmE;IACnE,GAAG,EAAE,OAAO,CAAC;IACb,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,CAAC;IACrB;wEACoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,KAAK,EACL,aAAa,EACb,OAAO,EACP,GAAG,EACH,SAAS,EACT,QAAQ,EACR,eAAe,EACf,QAAgB,EAChB,IAAS,GACV,EAAE,SAAS,GAAG,WAAW,CAczB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,UAAU,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,EACJ,aAAa,EACb,OAAO,EACP,GAAG,EACH,SAAS,EACT,GAAG,EACH,eAAe,EACf,QAAgB,EAChB,IAAS,GACV,EAAE,oBAAoB,GAAG,WAAW,CAgBpC;AAID,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAAC,EAC/C,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,EACJ,KAAK,EACL,QAAQ,GACT,EAAE,kBAAkB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAiBxE;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,EAC7C,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,GACL,EAAE,kBAAkB,GAAG,WAAW,CAWlC;AAED,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,EACJ,MAAM,EACN,KAAK,GACN,EAAE,kBAAkB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG,WAAW,CAU1E;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,EACjD,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,EACJ,GAAG,EACH,cAAc,GACf,EAAE,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,UAAU,CAAA;CAAE,GAAG,WAAW,CAYhF;AAED,yGAAyG;AACzG,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,KAAK,EACL,UAAU,EACV,IAAI,EACJ,cAAc,GACf,EAAE,kBAAkB,GAAG;IAAE,cAAc,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,WAAW,CAUpE;AAID;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;4FAC4F;AAC5F,wBAAgB,sCAAsC,CAAC,EACrD,OAAO,EACP,SAAS,EACT,WAAW,EACX,SAAS,EACT,KAAiB,EACjB,UAAU,GACX,EAAE,sBAAsB,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAahF;AAED,+DAA+D;AAC/D,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,SAAS,EACT,WAAW,EACX,SAAS,EACT,GAAG,GACJ,EAAE,sBAAsB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAWxD;AAED;;;sGAGsG;AACtG,wBAAgB,qCAAqC,CAAC,EACpD,OAAO,EACP,SAAS,EACT,WAAW,EACX,SAAS,EACT,SAAS,EACT,MAAM,GACP,EAAE,sBAAsB,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAYhF"}