@usesigil/kit 0.1.0

package/dist/transaction-executor.js

@@ -0,0 +1,165 @@
+/**
+ * TransactionExecutor — Kit-native transaction pipeline.
+ *
+ * Steps:
+ *   9. Compose versioned transaction (blockhash + compile)
+ *  10. Simulate (fail-closed)
+ *  11. Sign
+ *  12. Send + confirm, parse events
+ */
+import { getBase64EncodedWireTransaction } from "@solana/kit";
+import { composeSigilTransaction, measureTransactionSize, MAX_TX_SIZE, } from "./composer.js";
+import { AltCache } from "./alt-loader.js";
+import { simulateBeforeSend, adjustCU, RISK_FLAG_FULL_DRAIN, } from "./simulation.js";
+import { parseSigilEvents } from "./events.js";
+import { BlockhashCache, signAndEncode, sendAndConfirmTransaction, } from "./rpc-helpers.js";
+import { estimateComposedCU } from "./priority-fees.js";
+// ─── TransactionExecutor ────────────────────────────────────────────────────
+export class TransactionExecutor {
+    rpc;
+    agent;
+    blockhashCache;
+    confirmOptions;
+    _skipSimulation;
+    _drainThresholds;
+    altCache;
+    constructor(rpc, agent, options) {
+        this.rpc = rpc;
+        this.agent = agent;
+        this.blockhashCache = new BlockhashCache(options?.blockhashCacheTtlMs);
+        this.confirmOptions = options?.confirmOptions ?? {};
+        this._skipSimulation = options?.skipSimulation ?? false;
+        this._drainThresholds = options?.drainThresholds;
+    }
+    /**
+     * Resolve ALT addresses via cached RPC fetch.
+     * Returns a map of ALT address → resolved addresses.
+     */
+    async resolveAlts(rpc, altAddresses) {
+        if (!this.altCache)
+            this.altCache = new AltCache();
+        return this.altCache.resolve(rpc, altAddresses);
+    }
+    /**
+     * Step 9: Compose a versioned transaction from instructions + cached blockhash.
+     */
+    async composeTransaction(params) {
+        const blockhash = await this.blockhashCache.get(this.rpc);
+        const computeUnits = params.computeUnits ?? estimateComposedCU(params.defiInstructions);
+        const compiledTx = composeSigilTransaction({
+            feePayer: params.feePayer,
+            validateIx: params.validateIx,
+            defiInstructions: params.defiInstructions,
+            finalizeIx: params.finalizeIx,
+            blockhash,
+            computeUnits,
+            priorityFeeMicroLamports: params.priorityFeeMicroLamports,
+            addressLookupTables: params.addressLookupTables,
+        });
+        // Check wire size after compose (with or without ALTs)
+        const { byteLength, withinLimit } = measureTransactionSize(compiledTx);
+        if (!withinLimit) {
+            const altsApplied = params.addressLookupTables != null &&
+                Object.keys(params.addressLookupTables).length > 0;
+            const err = Object.assign(new Error(altsApplied
+                ? `Transaction ${byteLength}B exceeds ${MAX_TX_SIZE}B limit even with ALTs applied. Simplify the DeFi route.`
+                : `Transaction ${byteLength}B exceeds ${MAX_TX_SIZE}B limit. ALT fetch may have failed — retry, or simplify the route.`), {
+                code: 7033,
+                context: { byteLength, limit: MAX_TX_SIZE, altsApplied },
+            });
+            throw err;
+        }
+        return { compiledTx, computeUnits, blockhash };
+    }
+    /**
+     * Step 10: Simulate the transaction. Fail-closed — failure blocks sending.
+     * If CU consumed differs >20% from estimate, re-composes.
+     */
+    async simulate(params, compiledTx, estimatedCU, blockhash) {
+        const wireBase64 = getBase64EncodedWireTransaction(compiledTx);
+        // Build simulation options from vault monitoring context + drain thresholds
+        const simOptions = params.vaultMonitoring ? {
+            monitorAccounts: params.vaultMonitoring.monitorAccounts,
+            preBalances: params.vaultMonitoring.preBalances,
+            vaultAddress: params.vaultMonitoring.vaultAddress,
+            totalVaultBalance: params.vaultMonitoring.totalVaultBalance,
+            knownRecipients: params.vaultMonitoring.knownRecipients,
+            drainThresholds: this._drainThresholds,
+        } : undefined;
+        const simulation = await simulateBeforeSend(this.rpc, wireBase64, simOptions);
+        if (!simulation.success) {
+            return { simulation, finalCU: estimatedCU };
+        }
+        // Check if CU adjustment is needed
+        const adjustedCU = adjustCU(estimatedCU, simulation.unitsConsumed);
+        if (adjustedCU !== estimatedCU) {
+            // Re-compose with adjusted CU — reuse blockhash from initial compose
+            const recomposedTx = composeSigilTransaction({
+                feePayer: params.feePayer,
+                validateIx: params.validateIx,
+                defiInstructions: params.defiInstructions,
+                finalizeIx: params.finalizeIx,
+                blockhash,
+                computeUnits: adjustedCU,
+                priorityFeeMicroLamports: params.priorityFeeMicroLamports,
+                addressLookupTables: params.addressLookupTables,
+            });
+            return { simulation, recomposedTx, finalCU: adjustedCU };
+        }
+        return { simulation, finalCU: estimatedCU };
+    }
+    /**
+     * Steps 11+12: Sign, send, and confirm the transaction.
+     */
+    async signSendConfirm(compiledTx) {
+        const wireBase64 = await signAndEncode(this.agent, compiledTx);
+        const signature = await sendAndConfirmTransaction(this.rpc, wireBase64, this.confirmOptions);
+        return { signature };
+    }
+    /**
+     * Full pipeline: compose → simulate → sign → send → parse events.
+     * Steps 9-12 in one call.
+     */
+    async executeTransaction(params) {
+        // Step 9: Compose
+        const { compiledTx, computeUnits, blockhash } = await this.composeTransaction(params);
+        // Step 10: Simulate (unless skipped)
+        let txToSign = compiledTx;
+        let simLogs;
+        let unitsConsumed;
+        const riskWarnings = [];
+        if (!this._skipSimulation) {
+            const { simulation, recomposedTx } = await this.simulate(params, compiledTx, computeUnits, blockhash);
+            if (!simulation.success) {
+                const errMsg = simulation.error?.suggestion ??
+                    simulation.error?.message ??
+                    "Simulation failed";
+                throw new Error(`Simulation failed: ${errMsg}`);
+            }
+            // Drain detection: FULL_DRAIN blocks TX, others are warnings
+            if (simulation.riskFlags.length > 0) {
+                if (simulation.riskFlags.includes(RISK_FLAG_FULL_DRAIN)) {
+                    throw new Error(`Transaction blocked: drain detection triggered (${simulation.riskFlags.join(", ")})`);
+                }
+                riskWarnings.push(...simulation.riskFlags);
+            }
+            simLogs = simulation.logs;
+            unitsConsumed = simulation.unitsConsumed;
+            if (recomposedTx) {
+                txToSign = recomposedTx;
+            }
+        }
+        // Steps 11+12: Sign, send, confirm
+        const { signature } = await this.signSendConfirm(txToSign);
+        // Parse events from simulation logs (best-effort)
+        const events = simLogs ? parseSigilEvents(simLogs) : [];
+        return {
+            signature,
+            unitsConsumed,
+            logs: simLogs,
+            events,
+            warnings: riskWarnings.length > 0 ? riskWarnings : undefined,
+        };
+    }
+}
+//# sourceMappingURL=transaction-executor.js.map

package/dist/transaction-executor.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Kit-native type constants + permission helpers for Sigil.
+ *
+ * All types use Kit's `Address` (branded string) instead of web3.js `PublicKey`,
+ * and `bigint` instead of `BN`.
+ */
+import type { Address, Instruction } from "@solana/kit";
+export { SIGIL_PROGRAM_ADDRESS } from "./generated/programs/sigil.js";
+export type { ActionType } from "./generated/types/actionType.js";
+export type { VaultStatus } from "./generated/types/vaultStatus.js";
+export type { EscrowStatus } from "./generated/types/escrowStatus.js";
+export type { AgentEntry } from "./generated/types/agentEntry.js";
+export type { EpochBucket } from "./generated/types/epochBucket.js";
+export type { ConstraintEntry } from "./generated/types/constraintEntry.js";
+export type { DataConstraint } from "./generated/types/dataConstraint.js";
+export type { AccountConstraint } from "./generated/types/accountConstraint.js";
+export type { ConstraintOperator } from "./generated/types/constraintOperator.js";
+export declare const FEE_RATE_DENOMINATOR = 1000000;
+export declare const PROTOCOL_FEE_RATE = 200;
+export declare const MAX_DEVELOPER_FEE_RATE = 500;
+export declare const PROTOCOL_TREASURY: Address;
+export declare const USD_DECIMALS = 6;
+/** Scaling factor for stablecoin-to-USD conversion.
+ *  USDC/USDT both use 6 decimals: amount / STABLECOIN_USD_FACTOR = USD.
+ *  This assumption is load-bearing — if a stablecoin with different decimals
+ *  is added to isStablecoinMint(), this factor must be updated. */
+export declare const STABLECOIN_USD_FACTOR: bigint;
+export declare const MAX_AGENTS_PER_VAULT = 10;
+/** Permission bitmask with all 21 bits set (18 base + 3 escrow ActionType variants) */
+export declare const FULL_PERMISSIONS: bigint;
+export declare const SWAP_ONLY: bigint;
+export declare const PERPS_ONLY: bigint;
+export declare const TRANSFER_ONLY: bigint;
+export declare const ESCROW_ONLY: bigint;
+/** Full perps permission set: open, close, increase, decrease, deposit, withdraw, add/remove collateral, triggers, limits */
+export declare const PERPS_FULL: bigint;
+export declare const MAX_ESCROW_DURATION = 2592000;
+/** Maximum u64 value — used for BigInt clamping to match on-chain Rust math. */
+export declare const U64_MAX: bigint;
+export declare const MAX_SLIPPAGE_BPS = 5000;
+export declare const EPOCH_DURATION = 600;
+export declare const NUM_EPOCHS = 144;
+export declare const OVERLAY_EPOCH_DURATION = 3600;
+export declare const OVERLAY_NUM_EPOCHS = 24;
+export declare const ROLLING_WINDOW_SECONDS = 86400;
+export declare const PROTOCOL_MODE_ALL = 0;
+export declare const PROTOCOL_MODE_ALLOWLIST = 1;
+export declare const PROTOCOL_MODE_DENYLIST = 2;
+export declare const USDC_MINT_DEVNET: Address;
+export declare const USDC_MINT_MAINNET: Address;
+export declare const USDT_MINT_DEVNET: Address;
+export declare const USDT_MINT_MAINNET: Address;
+export declare const JUPITER_PROGRAM_ADDRESS: Address;
+/** The 5 recognized DeFi programs for instruction count enforcement.
+ *  Must stay in sync with on-chain validate_and_authorize.rs:325-329. */
+export declare const RECOGNIZED_DEFI_PROGRAMS: ReadonlySet<string>;
+export type Network = "devnet" | "mainnet-beta";
+/** Validate that a string is a recognized Network value. */
+export declare function validateNetwork(network: string): asserts network is Network;
+/** Short-form network accepted by public APIs. Normalized internally. */
+export type NetworkInput = "devnet" | "mainnet" | "mainnet-beta";
+/** Convert short-form network to canonical Network type.
+ *  "mainnet" → "mainnet-beta", all others pass through. */
+export declare function normalizeNetwork(network: NetworkInput): Network;
+/** Type-safe instruction conversion from Codama builders. */
+export declare function toInstruction(ix: {
+    programAddress: Address;
+    accounts?: readonly unknown[];
+    data?: unknown;
+}): Instruction;
+/** Check if a mint address is a recognized stablecoin (network-aware). */
+export declare function isStablecoinMint(mint: Address, network: Network): boolean;
+/** Permission bit mapping for each ActionType variant (21 total) */
+export declare const ACTION_PERMISSION_MAP: Record<string, bigint>;
+/** Check if a permission bitmask includes the permission for a given action type */
+export declare function hasPermission(permissions: bigint, actionType: string): boolean;
+/** Convert a permission bitmask to an array of action type strings */
+export declare function permissionsToStrings(permissions: bigint): string[];
+/**
+ * Convert an array of action type strings to a permission bitmask.
+ * Inverse of permissionsToStrings().
+ *
+ * @throws Error if any string is not a recognized action type.
+ * @example stringsToPermissions(["swap", "deposit"]) // => 33n (bit 0 + bit 5)
+ */
+export declare function stringsToPermissions(strings: string[]): bigint;
+/**
+ * Parse an action type to its string key.
+ * Accepts either a numeric ActionType enum value or an Anchor-style { Swap: {} } object.
+ */
+export declare function parseActionType(actionType: number | Record<string, unknown>): string | undefined;
+/** Builder for constructing permission bitmasks */
+export declare class PermissionBuilder {
+    private permissions;
+    add(actionType: string): this;
+    remove(actionType: string): this;
+    build(): bigint;
+}
+export type PositionEffect = "increment" | "decrement" | "none";
+export declare function isSpendingAction(actionType: string): boolean;
+export declare function getPositionEffect(actionType: string): PositionEffect;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,216 @@
+/**
+ * Kit-native type constants + permission helpers for Sigil.
+ *
+ * All types use Kit's `Address` (branded string) instead of web3.js `PublicKey`,
+ * and `bigint` instead of `BN`.
+ */
+// Re-export the program address from generated code
+export { SIGIL_PROGRAM_ADDRESS } from "./generated/programs/sigil.js";
+// ─── Fee Constants ────────────────────────────────────────────────────────────
+export const FEE_RATE_DENOMINATOR = 1_000_000;
+export const PROTOCOL_FEE_RATE = 200; // 2 BPS
+export const MAX_DEVELOPER_FEE_RATE = 500; // 5 BPS
+export const PROTOCOL_TREASURY = "ASHie1dFTnDSnrHMPGmniJhMgfJVGPm3rAaEPnrtWDiT";
+// ─── USD Constants ────────────────────────────────────────────────────────────
+export const USD_DECIMALS = 6;
+/** Scaling factor for stablecoin-to-USD conversion.
+ *  USDC/USDT both use 6 decimals: amount / STABLECOIN_USD_FACTOR = USD.
+ *  This assumption is load-bearing — if a stablecoin with different decimals
+ *  is added to isStablecoinMint(), this factor must be updated. */
+export const STABLECOIN_USD_FACTOR = 10n ** BigInt(USD_DECIMALS);
+// ─── Multi-agent Constants ────────────────────────────────────────────────────
+export const MAX_AGENTS_PER_VAULT = 10;
+/** Permission bitmask with all 21 bits set (18 base + 3 escrow ActionType variants) */
+export const FULL_PERMISSIONS = (1n << 21n) - 1n;
+export const SWAP_ONLY = 1n << 0n;
+export const PERPS_ONLY = (1n << 1n) | (1n << 2n) | (1n << 3n) | (1n << 4n);
+export const TRANSFER_ONLY = 1n << 7n;
+export const ESCROW_ONLY = (1n << 18n) | (1n << 19n) | (1n << 20n);
+/** Full perps permission set: open, close, increase, decrease, deposit, withdraw, add/remove collateral, triggers, limits */
+export const PERPS_FULL = PERPS_ONLY |
+    (1n << 5n) |
+    (1n << 6n) |
+    (1n << 8n) |
+    (1n << 9n) |
+    (1n << 10n) |
+    (1n << 11n) |
+    (1n << 12n) |
+    (1n << 13n) |
+    (1n << 14n) |
+    (1n << 15n) |
+    (1n << 16n) |
+    (1n << 17n);
+// ─── Escrow Constants ─────────────────────────────────────────────────────────
+export const MAX_ESCROW_DURATION = 2_592_000; // 30 days in seconds
+// ─── u64 Boundary ────────────────────────────────────────────────────────────
+/** Maximum u64 value — used for BigInt clamping to match on-chain Rust math. */
+export const U64_MAX = BigInt("18446744073709551615");
+// ─── Slippage Constants ───────────────────────────────────────────────────────
+export const MAX_SLIPPAGE_BPS = 5_000; // 50%
+// ─── SpendTracker Constants ───────────────────────────────────────────────────
+export const EPOCH_DURATION = 600; // 10 minutes in seconds
+export const NUM_EPOCHS = 144; // 144 × 10 min = 24h
+// ─── AgentSpendOverlay Constants ─────────────────────────────────────────────
+export const OVERLAY_EPOCH_DURATION = 3600; // 1 hour in seconds
+export const OVERLAY_NUM_EPOCHS = 24; // 24 × 1h = 24h
+export const ROLLING_WINDOW_SECONDS = 86_400; // 24 hours in seconds
+// ─── Protocol Mode ────────────────────────────────────────────────────────────
+export const PROTOCOL_MODE_ALL = 0;
+export const PROTOCOL_MODE_ALLOWLIST = 1;
+export const PROTOCOL_MODE_DENYLIST = 2;
+// ─── Stablecoin Mints ─────────────────────────────────────────────────────────
+// Devnet mints: test-controlled keypairs matching on-chain state/mod.rs
+// (we own the mint authority for devnet testing)
+export const USDC_MINT_DEVNET = "DMFEQFCRsvGrYzoL2gfwTEd9J8eVBQEjg7HjbJHd6oGH";
+export const USDC_MINT_MAINNET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export const USDT_MINT_DEVNET = "43cd9ma7P968BssTtAKNs5qu6zgsErupwxwdjkiuMHze";
+export const USDT_MINT_MAINNET = "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+export const JUPITER_PROGRAM_ADDRESS = "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4";
+/** The 5 recognized DeFi programs for instruction count enforcement.
+ *  Must stay in sync with on-chain validate_and_authorize.rs:325-329. */
+export const RECOGNIZED_DEFI_PROGRAMS = new Set([
+    "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", // Jupiter V6
+    "FLASH6Lo6h3iasJKWDs2F8TkW2UKf3s15C8PMGuVfgBn", // Flash Trade
+    "JLend2fEim9xUFcaHsyGePEoBzFLvkjMi3MnPcSuCdu", // Jupiter Lend
+    "jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9", // Jupiter Earn
+    "jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi", // Jupiter Borrow
+]);
+/** Validate that a string is a recognized Network value. */
+export function validateNetwork(network) {
+    const normalized = network === "mainnet" ? "mainnet-beta" : network;
+    if (normalized !== "devnet" && normalized !== "mainnet-beta") {
+        throw new Error(`Invalid network: "${network}". Must be "devnet", "mainnet", or "mainnet-beta".`);
+    }
+}
+/** Convert short-form network to canonical Network type.
+ *  "mainnet" → "mainnet-beta", all others pass through. */
+export function normalizeNetwork(network) {
+    return network === "mainnet" ? "mainnet-beta" : network;
+}
+/** Type-safe instruction conversion from Codama builders. */
+export function toInstruction(ix) {
+    return ix;
+}
+/** Check if a mint address is a recognized stablecoin (network-aware). */
+export function isStablecoinMint(mint, network) {
+    if (network === "devnet") {
+        return mint === USDC_MINT_DEVNET || mint === USDT_MINT_DEVNET;
+    }
+    return mint === USDC_MINT_MAINNET || mint === USDT_MINT_MAINNET;
+}
+// ─── Permission System ────────────────────────────────────────────────────────
+/** Permission bit mapping for each ActionType variant (21 total) */
+export const ACTION_PERMISSION_MAP = {
+    swap: 1n << 0n,
+    openPosition: 1n << 1n,
+    closePosition: 1n << 2n,
+    increasePosition: 1n << 3n,
+    decreasePosition: 1n << 4n,
+    deposit: 1n << 5n,
+    withdraw: 1n << 6n,
+    transfer: 1n << 7n,
+    addCollateral: 1n << 8n,
+    removeCollateral: 1n << 9n,
+    placeTriggerOrder: 1n << 10n,
+    editTriggerOrder: 1n << 11n,
+    cancelTriggerOrder: 1n << 12n,
+    placeLimitOrder: 1n << 13n,
+    editLimitOrder: 1n << 14n,
+    cancelLimitOrder: 1n << 15n,
+    swapAndOpenPosition: 1n << 16n,
+    closeAndSwapPosition: 1n << 17n,
+    createEscrow: 1n << 18n,
+    settleEscrow: 1n << 19n,
+    refundEscrow: 1n << 20n,
+};
+/** Check if a permission bitmask includes the permission for a given action type */
+export function hasPermission(permissions, actionType) {
+    const bit = ACTION_PERMISSION_MAP[actionType];
+    if (bit === undefined)
+        return false;
+    return (permissions & bit) !== 0n;
+}
+/** Convert a permission bitmask to an array of action type strings */
+export function permissionsToStrings(permissions) {
+    const result = [];
+    for (const [name, bit] of Object.entries(ACTION_PERMISSION_MAP)) {
+        if ((permissions & bit) !== 0n) {
+            result.push(name);
+        }
+    }
+    return result;
+}
+/**
+ * Convert an array of action type strings to a permission bitmask.
+ * Inverse of permissionsToStrings().
+ *
+ * @throws Error if any string is not a recognized action type.
+ * @example stringsToPermissions(["swap", "deposit"]) // => 33n (bit 0 + bit 5)
+ */
+export function stringsToPermissions(strings) {
+    let result = 0n;
+    for (const s of strings) {
+        const bit = ACTION_PERMISSION_MAP[s];
+        if (bit === undefined) {
+            const valid = Object.keys(ACTION_PERMISSION_MAP).join(", ");
+            throw new Error(`Unknown action type: "${s}". Valid types: ${valid}`);
+        }
+        result |= bit;
+    }
+    return result;
+}
+/**
+ * Parse an action type to its string key.
+ * Accepts either a numeric ActionType enum value or an Anchor-style { Swap: {} } object.
+ */
+export function parseActionType(actionType) {
+    if (typeof actionType === "number") {
+        const entries = Object.entries(ACTION_PERMISSION_MAP);
+        return entries[actionType]?.[0];
+    }
+    return Object.keys(actionType)[0];
+}
+/** Builder for constructing permission bitmasks */
+export class PermissionBuilder {
+    permissions = 0n;
+    add(actionType) {
+        const bit = ACTION_PERMISSION_MAP[actionType];
+        if (bit !== undefined) {
+            this.permissions |= bit;
+        }
+        return this;
+    }
+    remove(actionType) {
+        const bit = ACTION_PERMISSION_MAP[actionType];
+        if (bit !== undefined) {
+            this.permissions &= ~bit;
+        }
+        return this;
+    }
+    build() {
+        return this.permissions;
+    }
+}
+export function isSpendingAction(actionType) {
+    return [
+        "swap",
+        "openPosition",
+        "increasePosition",
+        "deposit",
+        "transfer",
+        "addCollateral",
+        "placeLimitOrder",
+        "swapAndOpenPosition",
+        "createEscrow",
+    ].includes(actionType);
+}
+export function getPositionEffect(actionType) {
+    if (["openPosition", "swapAndOpenPosition", "placeLimitOrder"].includes(actionType)) {
+        return "increment";
+    }
+    if (["closePosition", "closeAndSwapPosition", "cancelLimitOrder"].includes(actionType)) {
+        return "decrement";
+    }
+    return "none";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/vault-analytics.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Vault analytics — health assessment and one-call summary.
+ *
+ * getVaultHealth(): Pure function (no RPC) — derives health, cap metrics,
+ * security checks from already-resolved vault state.
+ *
+ * getVaultSummary(): Async function — parallel RPC calls for state, P&L,
+ * balances, pending policy. Returns everything a vault detail page needs.
+ */
+import type { Address, Rpc, SolanaRpcApi } from "@solana/kit";
+import type { ResolvedVaultState, ResolvedVaultStateForOwner } from "./state-resolver.js";
+import { type VaultPnL, type TokenBalance } from "./balance-tracker.js";
+import { type Network } from "./types.js";
+export interface VaultSecurityCheck {
+    id: string;
+    label: string;
+    passed: boolean;
+    severity: "critical" | "warning" | "info";
+}
+export interface VaultHealth {
+    status: "Active" | "Frozen" | "Closed";
+    /** Active + has agents + not approaching caps */
+    isHealthy: boolean;
+    agentCount: number;
+    pausedAgentCount: number;
+    openPositions: number;
+    activeEscrowCount: number;
+    /** 0-100 percentage of daily cap used */
+    capUtilization: number;
+    /** USD base units remaining in 24h window */
+    capRemaining: bigint;
+    /** Seconds until the oldest epoch rolls off and frees cap space. */
+    capResetsIn: number;
+    /** Seconds until cap would be hit at current rate. null = safe. */
+    timeToCapAtCurrentRate: number | null;
+    hasConstraints: boolean;
+    hasTimelock: boolean;
+    timelockDuration: number;
+    hasPendingPolicyChange: boolean;
+    /** Unix timestamp of most recent tracker activity. 0 if none. */
+    lastActivityTimestamp: number;
+    securityChecks: VaultSecurityCheck[];
+}
+export interface VaultStats {
+    totalTransactions: bigint;
+    totalVolume: bigint;
+    totalFeesCollected: bigint;
+    totalDeposited: bigint;
+    totalWithdrawn: bigint;
+    createdAt: bigint;
+    /** Days since vault creation (min 1) */
+    ageInDays: number;
+    /** totalVolume / ageInDays (0 if vault < 1 day old) */
+    avgDailyVolume: bigint;
+    /** totalVolume / totalTransactions (0 if no transactions) */
+    avgTransactionSize: bigint;
+    /** totalFeesCollected as BPS of totalVolume */
+    feeRate: number;
+}
+export interface VaultSummary {
+    address: Address;
+    owner: Address;
+    vaultId: bigint;
+    health: VaultHealth;
+    pnl: VaultPnL;
+    tokenBalances: TokenBalance[];
+    totalValueUsd: bigint;
+    state: ResolvedVaultStateForOwner;
+    stats: VaultStats;
+}
+/**
+ * Single-call vault health assessment. Pure function — no RPC.
+ *
+ * Derives isHealthy, capUtilization, capResetsIn, security checks from
+ * already-resolved vault state. The dashboard vault card renders this directly.
+ */
+export declare function getVaultHealth(state: ResolvedVaultState | ResolvedVaultStateForOwner, nowUnix: bigint): VaultHealth;
+/**
+ * Complete vault summary in one call. Parallel RPC for state, P&L, balances,
+ * pending policy. Returns everything the vault detail page header needs.
+ */
+export declare function getVaultSummary(rpc: Rpc<SolanaRpcApi>, vault: Address, network?: Network): Promise<VaultSummary>;
+//# sourceMappingURL=vault-analytics.d.ts.map

package/dist/vault-analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-analytics.d.ts","sourceRoot":"","sources":["../src/vault-analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAM1F,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvC,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,OAAO,CAAC;IAChC,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,kBAAkB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,QAAQ,CAAC;IACd,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,0BAA0B,CAAC;IAClC,KAAK,EAAE,UAAU,CAAC;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,0BAA0B,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAyHnH;AAID;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,EACtB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,OAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CAgDvB"}