@shieldedtech/moth-wallet 0.2.0

package/dist/sync/sdk-dedup.js

@@ -0,0 +1,134 @@
+// Client-side workaround for an off-by-one in
+// @midnightntwrk/wallet-sdk-shielded and @midnightntwrk/wallet-sdk-dust-wallet.
+//
+// The SDKs' default applyUpdate looks roughly like:
+//
+//   const last = updates.at(-1);
+//   if (BigInt(last.id) <= state.progress.appliedIndex) return early-skip;
+//   replayEventsWithChanges(state, ..., updates.map(toEvent));
+//   appliedIndex = BigInt(last.id);
+//
+// The early-skip only fires when the LAST event in the batch is already
+// applied. When the indexer re-sends a boundary event (subscription
+// reconnect, keepalive race, etc.) and that event sits at the head of an
+// otherwise-fresh batch, the duplicate slips through to the WASM tree:
+//
+//   Error: values inserted non-linearly into zswap commitment tree;
+//          expected to insert index N+1, but received N.
+//
+// The fix is to filter the batch BEFORE replay, dropping any event with
+// id <= state.progress.appliedIndex. If everything filters out the
+// behavior matches the SDK's own skip path; if some events remain we
+// hand them to the original applyUpdate which advances appliedIndex
+// against the new tail.
+//
+// We wrap rather than fork — V1Builder.withSync is the documented
+// extension point.
+import { V1Builder as ShieldedV1Builder, Sync as ShieldedSync, CoreWallet as ShieldedCoreWallet, } from '@midnightntwrk/wallet-sdk/shielded/v1';
+import { V1Builder as DustV1Builder, SyncService as DustSyncService, CoreWallet as DustCoreWallet, } from '@midnightntwrk/wallet-sdk/dust/v1';
+/**
+ * Walk the updates array and split into "already applied" vs "still to
+ * apply" against the wallet's current appliedIndex. The boundary event
+ * — the one whose id equals appliedIndex — counts as already applied.
+ */
+function partitionByAppliedIndex(updates, appliedIndex) {
+    const fresh = [];
+    for (const u of updates) {
+        if (BigInt(u.id) > appliedIndex)
+            fresh.push(u);
+    }
+    return { fresh, droppedCount: updates.length - fresh.length };
+}
+function makeDedupingApplyUpdate(base, updateProgress) {
+    return (state, wrapped) => {
+        if (wrapped.updates.length === 0) {
+            return base.applyUpdate(state, wrapped);
+        }
+        const { fresh, droppedCount } = partitionByAppliedIndex(wrapped.updates, state.progress.appliedIndex);
+        if (droppedCount === 0) {
+            // No duplicates — fast path, defer entirely to the SDK.
+            return base.applyUpdate(state, wrapped);
+        }
+        if (fresh.length === 0) {
+            // Whole batch is already-applied. Mirror the SDK's own early-skip
+            // shape so downstream observers see the same "still-connected,
+            // bumped highest-relevant-index" signal.
+            const tail = wrapped.updates[wrapped.updates.length - 1];
+            const highestRelevantWalletIndex = BigInt(tail.maxId);
+            return [
+                updateProgress(state, { highestRelevantWalletIndex, isConnected: true }),
+                { changes: [], protocolVersion: Number(state.protocolVersion) },
+            ];
+        }
+        // Partial overlap — hand only the fresh suffix to the SDK so its
+        // own appliedIndex advancement still reflects the batch tail.
+        return base.applyUpdate(state, { ...wrapped, updates: fresh });
+    };
+}
+// The V1Builder generics evolve through each builder method (withSync
+// narrows the configuration intersection, withTransacting adds more, etc).
+// Annotating an exact return type is brittle and adds no value — callers
+// pass the result directly to CustomShieldedWallet / CustomDustWallet,
+// which already accept their own narrowed V1Builder type. Let TS infer.
+/**
+ * Build a V1Builder for the shielded wallet whose syncCapability filters
+ * already-applied events before handing them to the SDK's
+ * makeEventsSyncCapability. Pass to CustomShieldedWallet(cfg, builder).
+ */
+// The inferred narrow V1Builder type references internal SDK paths that
+// aren't part of the SDK's public type surface, which makes the `.d.ts`
+// non-portable. Callers always feed the result straight into
+// CustomShieldedWallet(cfg, builder) / CustomDustWallet(cfg, builder),
+// both of which accept their own builder generic — so the actual type
+// at the call site is recovered. We return `unknown` here as a
+// deliberate escape hatch, and the callers cast.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function dedupingShieldedBuilder() {
+    return new ShieldedV1Builder().withDefaults().withSync(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ShieldedSync.makeEventsSyncService, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((_config, _getContext) => {
+        const base = ShieldedSync.makeEventsSyncCapability();
+        return {
+            applyUpdate: makeDedupingApplyUpdate(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            base, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (state, patch) => ShieldedCoreWallet.updateProgress(state, patch)),
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }));
+}
+/**
+ * Build a V1Builder for the dust wallet whose syncCapability filters
+ * already-applied events before handing them to the SDK's
+ * makeDefaultSyncCapability. Pass to CustomDustWallet(cfg, builder).
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function dedupingDustBuilder() {
+    return new DustV1Builder().withDefaults().withSync(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    DustSyncService.makeDefaultSyncService, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((_config, _getContext) => {
+        // makeDefaultSyncCapability ignores its args at runtime even though
+        // V1Builder invokes the factory with (config, getContext).
+        const base = DustSyncService.makeDefaultSyncCapability();
+        return {
+            applyUpdate: makeDedupingApplyUpdate(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            base, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (state, patch) => DustCoreWallet.updateProgress(state, patch)),
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }));
+}
+// Exported for unit-testing the boundary-filter logic in isolation,
+// without needing a live SDK wallet instance.
+export const __TEST_ONLY__ = {
+    partitionByAppliedIndex,
+    makeDedupingApplyUpdate,
+};
+//# sourceMappingURL=sdk-dedup.js.map

package/dist/sync/sdk-dedup.js.map

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

package/dist/sync/sync-store.d.ts

@@ -0,0 +1,33 @@
+export interface SyncStateStore {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export type WalletPart = 'shielded' | 'unshielded' | 'dust' | 'history';
+export declare function syncStateKey(networkId: string, walletName: string, part: WalletPart): string;
+/** Reserved wallet name for the pre-seed reference wallet (see preseed.ts). */
+export declare const EMPTY_REF_WALLET = "__empty_ref__";
+/**
+ * Where the pre-seed reference wallet's state lives: its ordinary sync-cache
+ * location. It MUST match what `startWalletSync(…, EMPTY_REF_WALLET, …)`
+ * saves, because the pre-seed reads the reference state back from there.
+ */
+export declare function emptyRefStateKey(networkId: string, part: WalletPart): string;
+/**
+ * Chain height the reference wallet was synced to, recorded at build time.
+ *
+ * The snapshots' own `offset` is an event index, not a block height, so it
+ * cannot be compared against a wallet's `birthday` (which is a height). This
+ * records the height separately, because pre-seeding a wallet from a reference
+ * NEWER than its birthday would skip that wallet's own history.
+ */
+export declare function emptyRefHeightKey(networkId: string): string;
+export declare function emptyRefMnemonicKey(networkId: string): string;
+/** Volatile store — used as the default outside Node when none is provided. */
+export declare class InMemorySyncStateStore implements SyncStateStore {
+    private readonly entries;
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=sync-store.d.ts.map

package/dist/sync/sync-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-store.d.ts","sourceRoot":"","sources":["../../src/sync/sync-store.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;AAExE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAE5F;AAED,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,+EAA+E;AAC/E,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAE/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC"}

package/dist/sync/sync-store.js

@@ -0,0 +1,45 @@
+// Storage abstraction for serialized wallet sync state.
+// Keys are relative paths (e.g. "sync/devnet/alice/shielded.dat") so the
+// Node store can map them 1:1 onto the legacy ~/.moth file layout while
+// browser stores treat them as opaque strings.
+export function syncStateKey(networkId, walletName, part) {
+    return `sync/${networkId}/${walletName}/${part}.dat`;
+}
+/** Reserved wallet name for the pre-seed reference wallet (see preseed.ts). */
+export const EMPTY_REF_WALLET = '__empty_ref__';
+/**
+ * Where the pre-seed reference wallet's state lives: its ordinary sync-cache
+ * location. It MUST match what `startWalletSync(…, EMPTY_REF_WALLET, …)`
+ * saves, because the pre-seed reads the reference state back from there.
+ */
+export function emptyRefStateKey(networkId, part) {
+    return syncStateKey(networkId, EMPTY_REF_WALLET, part);
+}
+/**
+ * Chain height the reference wallet was synced to, recorded at build time.
+ *
+ * The snapshots' own `offset` is an event index, not a block height, so it
+ * cannot be compared against a wallet's `birthday` (which is a height). This
+ * records the height separately, because pre-seeding a wallet from a reference
+ * NEWER than its birthday would skip that wallet's own history.
+ */
+export function emptyRefHeightKey(networkId) {
+    return `empty-ref/${networkId}/height.txt`;
+}
+export function emptyRefMnemonicKey(networkId) {
+    return `empty-ref/${networkId}/mnemonic.txt`;
+}
+/** Volatile store — used as the default outside Node when none is provided. */
+export class InMemorySyncStateStore {
+    entries = new Map();
+    async get(key) {
+        return this.entries.get(key) ?? null;
+    }
+    async put(key, value) {
+        this.entries.set(key, value);
+    }
+    async delete(key) {
+        this.entries.delete(key);
+    }
+}
+//# sourceMappingURL=sync-store.js.map

package/dist/sync/sync-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-store.js","sourceRoot":"","sources":["../../src/sync/sync-store.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,wEAAwE;AACxE,+CAA+C;AAU/C,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,UAAkB,EAAE,IAAgB;IAClF,OAAO,QAAQ,SAAS,IAAI,UAAU,IAAI,IAAI,MAAM,CAAC;AACvD,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAC;AAEhD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,IAAgB;IAClE,OAAO,YAAY,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,aAAa,SAAS,aAAa,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,aAAa,SAAS,eAAe,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAC/E,MAAM,OAAO,sBAAsB;IAChB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/dist/sync/wallet-sync.d.ts

@@ -0,0 +1,153 @@
+import { WalletFacade } from '@midnightntwrk/wallet-sdk/facade';
+import { type NetworkConfig } from '../types/network.js';
+import { NIGHT_TOKEN_ID, formatNight } from '../types/tokens.js';
+import { type SyncStateStore } from './sync-store.js';
+import { type SubWallet } from './progress.js';
+import type { WalletKeys } from './operations.js';
+export { NIGHT_TOKEN_ID, formatNight };
+export interface DustGeneration {
+    balance: bigint;
+    designated: bigint;
+    ratePerDay: bigint;
+    limit: bigint;
+    fillTime: Date;
+    numUtxos: number;
+    registered: boolean;
+    /** NIGHT (raw STAR) actually registered for generation — the sum of the
+     *  registered UTXOs. Balance beyond this contributes no DUST capacity until
+     *  it, too, is registered. */
+    registeredNight: bigint;
+    /** Creation time of the newest registered NIGHT UTXO, or null when none.
+     *  Lets callers distinguish "generation records still settling" (recent)
+     *  from a stale local dust view (old UTXOs with no records). */
+    newestRegisteredAt: Date | null;
+}
+export interface SyncProgress {
+    /** 0.0 to 1.0 */
+    percentage: number;
+    /** Estimated seconds remaining, or null if unknown */
+    etaSeconds: number | null;
+    /** Which sub-wallets are synced */
+    shieldedSynced: boolean;
+    unshieldedSynced: boolean;
+    dustSynced: boolean;
+    /** Which sub-wallet the percentage came from; null once synced. */
+    slowest: SubWallet | null;
+}
+/** Per-sub-wallet sync progress as raw applied/total indices (mirrors midnight-wallet-cli). */
+export interface SubWalletSyncProgress {
+    applied: number;
+    total: number;
+}
+export interface ShieldedCoinInfo {
+    value: bigint;
+    type: string;
+}
+export interface UnshieldedCoinInfo {
+    value: bigint;
+    type: string;
+    registeredForDustGeneration: boolean;
+}
+export interface DustCoinInfo {
+    generatedNow: bigint;
+    maxCap: bigint;
+    maxCapReachedAt: Date;
+    /** Set when the underlying NIGHT UTXO has been deregistered. */
+    dtime: Date | null;
+}
+export interface WalletCoinDetails {
+    shielded: {
+        available: ShieldedCoinInfo[];
+        pending: ShieldedCoinInfo[];
+    };
+    unshielded: {
+        available: UnshieldedCoinInfo[];
+        pending: UnshieldedCoinInfo[];
+    };
+    dust: {
+        available: DustCoinInfo[];
+        pending: DustCoinInfo[];
+    };
+}
+export interface SubWalletProgress {
+    shielded: SubWalletSyncProgress;
+    unshielded: SubWalletSyncProgress;
+    dust: SubWalletSyncProgress;
+}
+export interface WalletBalances {
+    shielded: Record<string, bigint>;
+    unshielded: Record<string, bigint>;
+    dust: bigint;
+    dustGeneration: DustGeneration | null;
+    syncProgress: SyncProgress;
+    synced: boolean;
+    /** Per-coin breakdown (matches midnight-wallet-cli's WalletStateView). */
+    coins: WalletCoinDetails;
+    /** Per-sub-wallet sync progress as raw applied/total. */
+    subProgress: SubWalletProgress;
+}
+export declare const EMPTY_COINS: WalletCoinDetails;
+export declare const EMPTY_SUB_PROGRESS: SubWalletProgress;
+export interface SyncedWallet {
+    facade: WalletFacade;
+    balances: WalletBalances;
+    stop: () => Promise<void>;
+    refresh: () => Promise<WalletBalances>;
+    /** Subscribe to progressive balance updates. Returns unsubscribe function. */
+    subscribe: (cb: (balances: WalletBalances) => void) => () => void;
+}
+/**
+ * Resolve the sync-state store: explicit option → Node filesystem store
+ * (legacy ~/.moth layout, loaded lazily so browser bundles never pull in
+ * node:fs) → volatile in-memory store.
+ */
+export declare function resolveSyncStore(explicit?: SyncStateStore): Promise<SyncStateStore>;
+/** Tuning for how the SDK groups sync events into synchronous WASM applies. */
+export interface BatchUpdatesOptions {
+    /** Max events applied per batch. Bigger = faster sync, longer main-thread blocks. */
+    size?: number;
+    /** Max ms to wait for a full batch before emitting a partial one. */
+    timeout?: number;
+    /** Min ms between consecutive batches — lets the event loop breathe. */
+    spacing?: number;
+}
+export interface WalletSyncOptions {
+    /** Where serialized sync state is cached. Defaults to the filesystem store in Node, in-memory elsewhere. */
+    syncStore?: SyncStateStore;
+    /**
+     * Event-batching overrides. Defaults favour throughput (size 500), which is
+     * right for Node CLIs; UI hosts that share a thread with rendering should
+     * pass smaller batches so each synchronous WASM apply stays short.
+     */
+    batchUpdates?: BatchUpdatesOptions;
+}
+export declare function startWalletSync(keys: WalletKeys, network: NetworkConfig, onProgress?: (msg: string) => void, walletName?: string, isNewWallet?: boolean, 
+/** Chain tip index at wallet creation time. Skips scanning blocks before this index on first sync. */
+birthday?: number, options?: WalletSyncOptions): Promise<SyncedWallet>;
+/**
+ * Clear cached sync state for a wallet on a specific network.
+ * Useful after a devnet genesis reset or corrupted state.
+ */
+export declare function clearSyncCache(walletName: string, networkId: string, store?: SyncStateStore): Promise<void>;
+/**
+ * Remove every artifact a wallet leaves behind so re-creating a wallet under
+ * the same name never silently inherits stale state from a previous seed:
+ *   - the serialized sync state held in the SyncStateStore (the `.dat` entries;
+ *     IndexedDB in the extension, the fs-backed store under the daemon/CLI/TUI),
+ *     cleared via clearSyncCache so this works in the browser too; and
+ *   - on node only, the per-wallet `~/.moth/sync/<network>/<name>/` directory
+ *     and the matching daemon `.sock` file, which live outside the store.
+ *
+ * Best-effort: missing artifacts are ignored. The node-only fs work is behind a
+ * dynamic import so this module keeps its "no static node:* imports" invariant
+ * (see the file header) and stays browser-bundleable.
+ */
+export declare function removeWalletSyncArtifacts(walletName: string, networkId: string, store?: SyncStateStore): Promise<void>;
+/**
+ * Clear ONLY the dust sub-wallet's cached state, keeping the (much larger)
+ * shielded/unshielded caches. The next sync start rebuilds the dust view from
+ * the chain — the targeted repair for a dust view that stopped ingesting
+ * generation records for newer NIGHT UTXOs.
+ */
+export declare function clearDustSyncCache(walletName: string, networkId: string, store?: SyncStateStore): Promise<void>;
+//# sourceMappingURL=wallet-sync.d.ts.map

package/dist/sync/wallet-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-sync.d.ts","sourceRoot":"","sources":["../../src/sync/wallet-sync.ts"],"names":[],"mappings":"AAQA,OAAO,EAAuB,YAAY,EAAmB,MAAM,kCAAkC,CAAC;AActG,OAAO,EAAsB,KAAK,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAE5E,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAG/D,OAAO,EAAuC,KAAK,cAAc,EAAkB,MAAM,iBAAiB,CAAC;AAE3G,OAAO,EAAsB,KAAK,SAAS,EAAC,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iBAAiB,CAAC;AAIhD,OAAO,EAAC,cAAc,EAAE,WAAW,EAAC,CAAC;AAgKrC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,IAAI,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB;;kCAE8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB;;oEAEgE;IAChE,kBAAkB,EAAE,IAAI,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mCAAmC;IACnC,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,IAAI,CAAC;IACtB,gEAAgE;IAChE,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE;QAAC,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAAC,OAAO,EAAE,gBAAgB,EAAE,CAAA;KAAC,CAAC;IACvE,UAAU,EAAE;QAAC,SAAS,EAAE,kBAAkB,EAAE,CAAC;QAAC,OAAO,EAAE,kBAAkB,EAAE,CAAA;KAAC,CAAC;IAC7E,IAAI,EAAE;QAAC,SAAS,EAAE,YAAY,EAAE,CAAC;QAAC,OAAO,EAAE,YAAY,EAAE,CAAA;KAAC,CAAC;CAC5D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,UAAU,EAAE,qBAAqB,CAAC;IAClC,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,YAAY,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,KAAK,EAAE,iBAAiB,CAAC;IACzB,yDAAyD;IACzD,WAAW,EAAE,iBAAiB,CAAC;CAChC;AAED,eAAO,MAAM,WAAW,EAAE,iBAIzB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,iBAIhC,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IACvC,8EAA8E;IAC9E,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAQD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAezF;AAkDD,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,4GAA4G;IAC5G,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAeD,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,aAAa,EACtB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAClC,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,OAAO;AACrB,sGAAsG;AACtG,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAsWvB;AAiTD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf"}