@usesigil/kit 0.1.0

package/dist/seal.d.ts

@@ -0,0 +1,211 @@
+/**
+ * seal() — Protocol-agnostic DeFi instruction sealing.
+ *
+ * Takes arbitrary DeFi instructions (from Jupiter API, SAK, GOAT, MCP servers)
+ * and sandwiches them with Sigil security:
+ * [ComputeBudget, ValidateAndAuthorize, ...defiIxs, FinalizeSession]
+ *
+ * All succeed or all revert atomically.
+ *
+ * Devnet prerequisites:
+ * - Sigil program deployed at SIGIL_PROGRAM_ADDRESS
+ * - SIGIL_ALT_DEVNET updated in alt-config.ts (currently placeholder)
+ * - PROTOCOL_TREASURY token accounts initialized for USDC/USDT on devnet
+ * - Vault funded with tokens and ATAs created
+ */
+import type { Address, AddressesByLookupTableAddress, Instruction, Rpc, SolanaRpcApi, TransactionSigner } from "@solana/kit";
+import { compileTransaction } from "@solana/kit";
+import { ActionType } from "./generated/types/actionType.js";
+import { type ResolvedVaultState, type ResolvedVaultStateForOwner, type ResolvedBudget } from "./state-resolver.js";
+import { type Blockhash, type SendAndConfirmOptions } from "./rpc-helpers.js";
+import { type AgentError } from "./agent-errors.js";
+import { type VaultPnL, type TokenBalance } from "./balance-tracker.js";
+import { type CreateVaultOptions, type CreateVaultResult } from "./create-vault.js";
+export interface SealParams {
+    /** On-chain vault PDA address. */
+    vault: Address;
+    /** Agent signer — must be registered in the vault's agent list. */
+    agent: TransactionSigner;
+    /** DeFi instructions to seal. ComputeBudget and System instructions are stripped automatically. */
+    instructions: Instruction[];
+    /** RPC client for state resolution and blockhash fetching. */
+    rpc: Rpc<SolanaRpcApi>;
+    /** Network identifier. Accepts `"devnet"` or `"mainnet"` (normalized to `"mainnet-beta"` internally). */
+    network: "devnet" | "mainnet";
+    /**
+     * Token mint being spent FROM the vault.
+     *
+     * For swaps: the input mint (what leaves the vault).
+     * For transfers: the transferred token's mint.
+     *
+     * The SDK uses this to derive the vault's ATA and rewrite agent ATAs
+     * in the DeFi instructions to point at the vault's token account.
+     */
+    tokenMint: Address;
+    /**
+     * Amount in the token's native base units.
+     *
+     * - Stablecoin input (USDC/USDT): base units = USD with 6 decimals.
+     *   Example: $100 USDC = 100_000_000n (100 * 10^6).
+     *
+     * - Non-stablecoin input (SOL, BONK, etc.): raw token base units.
+     *   Example: 1 SOL = 1_000_000_000n (10^9 lamports).
+     *   Non-stablecoin amounts are NOT cap-checked (by design) —
+     *   finalize_session measures actual stablecoin balance delta instead.
+     *
+     * Must be > 0 for spending actions, 0 for non-spending actions.
+     */
+    amount: bigint;
+    /**
+     * DeFi action type. Determines permission check and spending classification.
+     * Default: `ActionType.Swap`.
+     *
+     * 9 spending: Swap, OpenPosition, IncreasePosition, Deposit, Transfer,
+     *   AddCollateral, PlaceLimitOrder, SwapAndOpenPosition, CreateEscrow.
+     * 12 non-spending: ClosePosition, DecreasePosition, Withdraw, RemoveCollateral,
+     *   PlaceTriggerOrder, EditTriggerOrder, CancelTriggerOrder, EditLimitOrder,
+     *   CancelLimitOrder, CloseAndSwapPosition, SettleEscrow, RefundEscrow.
+     */
+    actionType?: ActionType;
+    /** Protocol program address. Auto-detected from first DeFi instruction if omitted. */
+    targetProtocol?: Address;
+    /** Declared leverage in basis points (100 = 1x). Advisory — on-chain checks declared value. */
+    leverageBps?: number;
+    /** Override compute unit budget. Default: auto-estimated from action type. */
+    computeUnits?: number;
+    /** Priority fee in microLamports per CU. Default: 0 (no priority fee). */
+    priorityFeeMicroLamports?: number;
+    /** Output stablecoin ATA for non-stablecoin input swaps. Vault's canonical ATA derived if omitted. */
+    outputStablecoinAccount?: Address;
+    /** Pre-fetched blockhash. If omitted, fetched via RPC (cached 30s). */
+    blockhash?: Blockhash;
+    /**
+     * Protocol-specific ALT addresses to merge with the Sigil ALT for tx compression.
+     * Jupiter: extract `addressLookupTableAddresses` from the /swap-instructions response.
+     * These rotate per-route — always pass fresh values from the latest API response.
+     */
+    protocolAltAddresses?: Address[];
+    /** Pre-resolved ALT contents. If omitted, Sigil ALT resolved automatically. */
+    addressLookupTables?: AddressesByLookupTableAddress;
+    /** Pre-resolved vault state. Skips RPC fetch if fresh enough (see maxCacheAgeMs). */
+    cachedState?: ResolvedVaultState;
+    /** Max age in ms for cachedState before re-resolving. Default: 30_000 (30s). */
+    maxCacheAgeMs?: number;
+    /** Additional agent ATA → vault ATA replacements for multi-token DeFi routes. */
+    additionalAtaReplacements?: Map<Address, Address>;
+}
+export interface SealResult {
+    ok: true;
+    transaction: ReturnType<typeof compileTransaction>;
+    actionType: ActionType;
+    warnings: string[];
+    txSizeBytes: number;
+    /** Block height after which the blockhash expires. Sign and send before this. */
+    lastValidBlockHeight: bigint;
+    /** Vault context for downstream drain detection (eliminates double-resolve). */
+    vaultContext?: {
+        vaultAddress: Address;
+        vaultTokenAta: Address;
+        tokenBalance: bigint;
+        knownRecipients: Set<string>;
+    };
+}
+/** Replace agent ATAs with vault ATAs in DeFi instruction account lists. */
+export declare function replaceAgentAtas(instructions: Instruction[], replacements: Map<Address, Address>): Instruction[];
+/**
+ * Seal arbitrary DeFi instructions with Sigil security.
+ *
+ * Sandwiches the provided instructions between validate_and_authorize (before)
+ * and finalize_session (after) in an atomic Solana transaction.
+ *
+ * NOTE: Concurrent calls for the same vault+agent+tokenMint are NOT supported.
+ * The on-chain SessionAuthority PDA is deterministic — two concurrent seals
+ * produce colliding session PDAs and only one will succeed on-chain.
+ *
+ * @throws Error if vault is not active, agent lacks permission, protocol not allowed,
+ *   spending cap insufficient, or transaction exceeds 1232 byte limit.
+ */
+export declare function seal(params: SealParams): Promise<SealResult>;
+export interface SigilClientConfig {
+    rpc: Rpc<SolanaRpcApi>;
+    vault: Address;
+    agent: TransactionSigner;
+    network: "devnet" | "mainnet";
+    blockhashTtlMs?: number;
+    /** Callback invoked on any error during executeAndConfirm(). For telemetry/logging. Error is always rethrown. */
+    onError?: (error: AgentError, context: {
+        action: string;
+        tokenMint: Address;
+        amount: bigint;
+    }) => void;
+}
+/**
+ * Options for `client.seal()`.
+ *
+ * Note: `blockhash` is intentionally omitted — SigilClient manages its own
+ * BlockhashCache instance, which is what `invalidateCaches()` actually clears.
+ * Use the standalone `seal()` function if you need to supply a custom blockhash.
+ */
+export interface ClientSealOpts {
+    tokenMint: Address;
+    amount: bigint;
+    actionType?: ActionType;
+    targetProtocol?: Address;
+    leverageBps?: number;
+    computeUnits?: number;
+    priorityFeeMicroLamports?: number;
+    outputStablecoinAccount?: Address;
+    protocolAltAddresses?: Address[];
+    addressLookupTables?: AddressesByLookupTableAddress;
+    cachedState?: ResolvedVaultState;
+    maxCacheAgeMs?: number;
+    additionalAtaReplacements?: Map<Address, Address>;
+}
+export interface ExecuteResult {
+    signature: string;
+    sealResult: SealResult;
+}
+/**
+ * Primary SDK entry point — stateful client that owns context and caches.
+ *
+ * Recommended over standalone seal() for production use:
+ * - Holds vault, agent, network, and RPC — no state carrying between calls
+ * - Blockhash and ALT caches are isolated per client instance
+ * - invalidateCaches() clears instance caches that are actually used
+ * - Convenience methods delegate to existing stateless functions
+ */
+export declare class SigilClient {
+    private readonly blockhashCacheInstance;
+    private readonly altCacheInstance;
+    private readonly onErrorCallback?;
+    readonly rpc: Rpc<SolanaRpcApi>;
+    readonly vault: Address;
+    readonly agent: TransactionSigner;
+    readonly network: "devnet" | "mainnet";
+    constructor(config: SigilClientConfig);
+    /**
+     * Seal DeFi instructions with Sigil security.
+     *
+     * Pre-resolves blockhash and ALTs from instance caches, then delegates
+     * to the standalone seal() function. This ensures invalidateCaches()
+     * actually clears caches that are read (N-2 fix).
+     */
+    seal(instructions: Instruction[], opts: ClientSealOpts): Promise<SealResult>;
+    /**
+     * Seal + sign + send + confirm in one call.
+     *
+     * Uses the same signing pattern as TransactionExecutor.signSendConfirm()
+     * (transaction-executor.ts:236-265).
+     */
+    executeAndConfirm(instructions: Instruction[], opts: ClientSealOpts & {
+        confirmOptions?: SendAndConfirmOptions;
+    }): Promise<ExecuteResult>;
+    invalidateCaches(): void;
+    private get networkFull();
+    getVaultState(): Promise<ResolvedVaultStateForOwner>;
+    getAgentBudget(): Promise<ResolvedBudget>;
+    getPnL(): Promise<VaultPnL>;
+    getTokenBalances(): Promise<TokenBalance[]>;
+    static createVault(opts: CreateVaultOptions): Promise<CreateVaultResult>;
+}
+//# sourceMappingURL=seal.d.ts.map

package/dist/seal.d.ts.map

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