@usesigil/kit 0.8.1 → 0.11.0

package/README.md

@@ -1,8 +1,10 @@
 # @usesigil/kit
 
-Kit-native TypeScript SDK for Sigil — on-chain spending limits and permission policies for AI agent wallets on Solana.
+Kit-native TypeScript SDK for **Sigil** — on-chain spending limits, permission policies, and audit trails for AI-agent wallets on Solana.
 
-Sigil wraps arbitrary DeFi instructions with security guardrails. Your agents trade through Jupiter, Flash Trade, Drift, or any Solana protocol while vault policies enforce spending caps, permission bitmasks, and protocol allowlists.
+> **Sigil is a security wrapper, not a DeFi SDK.** Your agents keep using Jupiter, Flash Trade, Drift, or any Solana protocol. Sigil wraps the instructions they produce with a validate-and-authorize gate, enforces the policies the vault owner configured, and records the outcome — all without touching the underlying DeFi logic.
+
+---
 
 ## Install
 
@@ -12,243 +14,427 @@ npm install @usesigil/kit @solana/kit
 
 `@solana/kit ^6.2.0` is a peer dependency. Node >= 18.
 
+---
+
+## Mental model
+
+Sigil separates **authority** (owner) from **execution** (agents), enforced at the Solana transaction boundary rather than only in application code.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       OWNER (human or DAO)                       │
+│   - Creates vault, sets policy (caps / timelock / allowlist)     │
+│   - Registers agent signing keys                                 │
+│   - Withdraws funds, freezes vault, revokes agents               │
+│   - Cannot be impersonated by any agent                          │
+└──────────────────────────┬───────────────────────────────────────┘
+                           │ owner-signed transactions
+                           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    SIGIL ON-CHAIN PROGRAM                        │
+│   ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐    │
+│   │ AgentVault   │  │ PolicyConfig │  │ SpendTracker        │    │
+│   │  (funds)     │  │  (limits)    │  │  (rolling 24 h)     │    │
+│   └──────────────┘  └──────────────┘  └─────────────────────┘    │
+│                                                                  │
+│   Every spending tx is `[validate, <DeFi ix>, finalize]`.        │
+│   The sandwich cannot be decomposed — all succeed or all revert. │
+└──────────────────────────┬───────────────────────────────────────┘
+                           │ validated tx
+                           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│        DeFi protocols (Jupiter, Flash Trade, Drift, …)           │
+│        Sigil does not touch this layer — no protocol SDK needed. │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Nothing an agent does can bypass the on-chain gate. If the validate instruction rejects — cap exceeded, protocol not allowed, agent paused — the entire transaction reverts before any funds move.
+
+---
+
 ## Quickstart
 
-```typescript
+Provision a vault and execute your first agent-authorized swap:
+
+```ts
 import {
-  SigilClient,
   createAndSendVault,
-  ActionType,
-  toAgentError,
-  formatUsd,
-  USDC_MINT_DEVNET,
+  SigilClient,
+  SAFETY_PRESETS,
+  parseUsd,
+  createConsoleLogger,
 } from "@usesigil/kit";
-import { address, createSolanaRpc } from "@solana/kit";
 
-// 1. Create a vault (owner operation — run once)
-const rpc = createSolanaRpc("https://api.devnet.solana.com");
-const vault = await createAndSendVault({
-  rpc,
+// 1. Owner provisions the vault on devnet.
+const { vaultAddress } = await createAndSendVault({
+  rpc, // Rpc<SolanaRpcApi> from @solana/kit
   network: "devnet",
-  owner,              // TransactionSigner (vault authority)
-  agent,              // TransactionSigner (AI agent key)
-  dailySpendingCapUsd: 500_000_000n,  // $500 in USDC base units
+  owner: ownerSigner, // TransactionSigner
+  agent: agentSigner, // TransactionSigner — separate key from owner
+  // Required safety posture (v0.9.0 — no silent defaults):
+  ...SAFETY_PRESETS.development,
 });
-console.log(`Vault created: ${vault.vaultAddress}`);
 
-// 2. Wrap a Jupiter swap (agent operation — per trade)
-const client = new SigilClient({
+// 2. Agent opens an async client with genesis-hash verification.
+const client = await SigilClient.create({
   rpc,
-  vault: vault.vaultAddress,
-  agent,
+  vault: vaultAddress,
+  agent: agentSigner,
   network: "devnet",
+  logger: createConsoleLogger(), // opt in to structured warnings
 });
 
-const jupiterInstructions = /* from Jupiter /swap-instructions API */;
+// 3. Wrap arbitrary DeFi instructions from Jupiter, SAK, MCP, etc.
+const jupiterInstructions = await buildJupiterSwap(/* your call */);
 const { signature } = await client.executeAndConfirm(jupiterInstructions, {
   tokenMint: USDC_MINT_DEVNET,
-  amount: 100_000_000n,           // $100 USDC
-  actionType: ActionType.Swap,
-  protocolAltAddresses: jupiterResponse.addressLookupTableAddresses,
+  amount: parseUsd("$10"), // strict parser → 10_000_000n base units
 });
-
-// 3. Check P&L
-const pnl = await client.getPnL();
-console.log(`P&L: ${formatUsd(pnl.pnl)}`);
 ```
 
-See [`examples/jupiter-swap.ts`](./examples/jupiter-swap.ts) for a complete, runnable example with Jupiter API calls, instruction parsing, ALT extraction, and error handling.
+The agent's signing key is never enough on its own — Sigil's validate instruction in the same transaction has to authorize the spend, and the finalize instruction has to record it. A leaked agent key cannot exceed the owner-configured daily cap or transfer to a non-allowed destination.
 
-## Architecture
+---
 
+## Sigil Facade (v0.11.0)
+
+The six-step quickstart above is fine, but v0.11.0 ships a single-call facade that wraps it. `Sigil.quickstart()` provisions the vault + returns a handle; `Sigil.fromVault()` binds a handle to an existing vault:
+
+```ts
+import {
+  Sigil,
+  SAFETY_PRESETS,
+  parseUsd,
+  USDC_MINT_DEVNET,
+} from "@usesigil/kit";
+
+// Provision + get a handle in one call.
+const { vault, funded, signatures } = await Sigil.quickstart({
+  rpc,
+  network: "devnet",
+  owner: ownerSigner,
+  agent: agentSigner,
+  ...SAFETY_PRESETS.development,
+  initialFundingUsd: parseUsd("$100"), // optional — zero or omit to skip
+  fundingMint: USDC_MINT_DEVNET, // defaults to USDC on target network
+});
+
+if (!funded.funded) {
+  console.warn("Vault live but not funded:", funded.reason, funded.error);
+}
+
+// Use the handle directly — no separate SigilClient / OwnerClient to wire.
+const result = await vault.execute(jupiterInstructions, {
+  tokenMint: USDC_MINT_DEVNET,
+  amount: parseUsd("$10"),
+});
+
+const overview = await vault.overview(); // owner-only — throws OWNER_REQUIRED without owner
+const budget = await vault.budget(); // cheapest read — agent-only works
 ```
-Transaction = [validate_and_authorize, ...defiInstructions, finalize_session]
+
+Bind a handle to an existing vault:
+
+```ts
+const vault = await Sigil.fromVault({
+  rpc,
+  network: "devnet",
+  address: existingVaultAddress,
+  agent: agentSigner,
+  owner: ownerSigner, // optional — required by vault.freeze() / vault.fund() / vault.overview()
+});
 ```
 
-Sigil wraps arbitrary DeFi instructions from any source (Jupiter API, Solana Agent Kit, MCP servers) and sandwiches them with on-chain security checks. All instructions succeed or all revert atomically. The SDK handles instruction composition, ATA rewriting, ALT compression, and pre-flight validation.
+Enumerate an owner's vaults:
 
-## API Overview
+```ts
+const vaults = await Sigil.discoverVaults(rpc, ownerAddress, "devnet");
+```
 
-### Core — Create vaults, wrap instructions, execute
+Presets are reachable through the same namespace:
 
-| Export                    | Description                                                                              |
-| ------------------------- | ---------------------------------------------------------------------------------------- |
-| `SigilClient`             | Stateful client — holds vault/agent/network, manages caches. Recommended for production. |
-| `wrap()`                  | Stateless wrapping function — takes DeFi instructions, returns a composed transaction.   |
-| `createVault()`           | Build vault creation instructions (caller signs and sends).                              |
-| `createAndSendVault()`    | One-call vault creation — build, sign, send, confirm.                                    |
-| `buildOwnerTransaction()` | Compose owner-only transactions (policy updates, agent management).                      |
-| `withVault()`             | Policy-guided vault creation — policies in, wrapped client out.                          |
+```ts
+Sigil.presets.safety.development; // { timelockDuration: 1800, ... }
+Sigil.presets.safety.production; // null caps — caller supplies
+Sigil.presets.vault["perps-trader"]; // VAULT_PRESETS entry
+Sigil.presets.applySafetyPreset("production", {
+  spendingLimitUsd,
+  dailySpendingCapUsd,
+});
+```
 
-### State — Query vaults, budgets, spending
+`Sigil` is a frozen namespace object — no instance state, no `new Sigil()`, tree-shakeable.
+
+---
+
+## Lifecycle hooks (v0.11.0)
+
+`SealHooks` observe the transaction lifecycle. Pass hooks at client-config level (fire on every call) or per-call (compose on top of client-level hooks):
+
+```ts
+import type { SealHooks } from "@usesigil/kit";
+
+const hooks: SealHooks = {
+  onBeforeBuild(ctx, params) {
+    // Runs before any RPC. Return { skipSeal: true, reason } to abort cleanly.
+    if (isDryRunMode()) return { skipSeal: true, reason: "dry-run" };
+  },
+  onBeforeSign(ctx, tx) {
+    // Observational — fires after build + size check, before signing.
+  },
+  onAfterSend(ctx, signature) {
+    // Fires as soon as the signature is obtained — good for starting traces.
+    startTrace(ctx.correlationId, signature);
+  },
+  onFinalize(ctx, result) {
+    // Fires on the success path after confirmation.
+    closeTrace(ctx.correlationId, result.signature);
+  },
+  onError(ctx, err) {
+    // Fires in every failure path. Error is always rethrown after the hook.
+  },
+};
+
+// Register at client level — fire on every vault.execute()
+const vault = await Sigil.fromVault({ ..., hooks });
+
+// Or per-call — composes with client-level hooks (client runs first, then per-call)
+await vault.execute(instructions, { ..., hooks: perCallHooks });
+```
 
-| Export                        | Description                                                                   |
-| ----------------------------- | ----------------------------------------------------------------------------- |
-| `resolveVaultState()`         | Fetch complete vault state (accounts, policy, tracker, overlay, constraints). |
-| `resolveVaultBudget()`        | Per-agent budget: rolling 24h spend, cap, remaining headroom.                 |
-| `getSpendingHistory()`        | 144-epoch circular buffer to chart-ready time series.                         |
-| `findVaultsByOwner()`         | Enumerate all vaults owned by an address.                                     |
-| `resolveVaultStateForOwner()` | Vault state with pending policy/constraint updates for dashboards.            |
+**Semantics:**
 
-### Analytics — Security checks, agent metrics, portfolio
+- **Observe-only by default.** A hook that throws is caught, logged via the injected logger, and swallowed. Hook exceptions never corrupt `seal()`'s atomic-transaction guarantee.
+- **`onBeforeBuild` is the only hook that may abort.** Returning `{ skipSeal: true, reason }` throws `SigilSdkDomainError(SIGIL_ERROR__SDK__HOOK_ABORTED)` before any RPC round-trip. Use for consent flows, feature flags, or dry-run mode.
+- **`ctx.correlationId`** is stable across every hook for a single seal invocation — use it to correlate `onBeforeBuild` → `onAfterSend` → `onFinalize` in distributed traces.
 
-| Export                   | Description                                                         |
-| ------------------------ | ------------------------------------------------------------------- |
-| `getSecurityPosture()`   | 13-point security assessment with pass/fail, severity, remediation. |
-| `getVaultHealth()`       | Risk score, liquidity, utilization.                                 |
-| `getAgentProfile()`      | Single agent stats — spend, tx count, errors.                       |
-| `getAgentLeaderboard()`  | Top agents by spend or profit.                                      |
-| `getPortfolioOverview()` | Cross-vault summary for multi-vault operators.                      |
-| `getAuditTrail()`        | Chronological audit log filtered by category, actor, or time range. |
-| `getSpendingVelocity()`  | Rate of spend over configurable time windows.                       |
+---
 
-7 analytics modules with 42 functions total — see source for the full list.
+## Policy plugins (v0.11.0)
 
-### Safety — Pre-flight checks, error handling
+`SigilPolicyPlugin` is the rejection surface — distinct from `SealHooks` which observe. Plugins run after state resolution; the first rejection short-circuits `seal()` with `SigilSdkDomainError(SIGIL_ERROR__SDK__PLUGIN_REJECTED)`:
 
-| Export                 | Description                                                                                       |
-| ---------------------- | ------------------------------------------------------------------------------------------------- |
-| `shield()`             | Client-side policy gate — evaluate instructions before signing.                                   |
-| `simulateBeforeSend()` | RPC simulation with error extraction.                                                             |
-| `detectDrainAttempt()` | Heuristic drain detection from balance deltas.                                                    |
-| `toAgentError()`       | Convert any error to structured `AgentError` with category, retryable flag, and recovery actions. |
+```ts
+import type { SigilPolicyPlugin } from "@usesigil/kit";
 
-### Formatting — Display helpers (11 functions)
+const maxAmountPlugin: SigilPolicyPlugin = {
+  name: "max-amount-plugin",
+  check(ctx) {
+    if (ctx.amount > 1_000_000_000n) {
+      return {
+        allow: false,
+        reason: "Amount exceeds $1,000 safety threshold",
+      };
+    }
+    return { allow: true };
+  },
+};
 
-| Export                | Description                     |
-| --------------------- | ------------------------------- |
-| `formatUsd()`         | `$1,234.56` with full precision |
-| `formatUsdCompact()`  | `$1.2M`, `$500K`                |
-| `formatPercent()`     | `12.34%`                        |
-| `formatDuration()`    | `1d 2h 3m`                      |
-| `formatAddress()`     | `4ZeV...wrHL`                   |
-| `formatTokenAmount()` | `1,000.000000 USDC`             |
+const vault = await Sigil.fromVault({ ..., plugins: [maxAmountPlugin] });
+// Calls to vault.execute() with amount > $1,000 throw PLUGIN_REJECTED.
+```
 
-Plus: `formatUsdSigned`, `formatPercentSigned`, `formatRelativeTime`, `formatTimeUntil`, `formatTokenAmountCompact`.
+Plugin semantics:
 
-### Presets — Vault templates
+- **Enforce, not observe.** First `{ allow: false }` short-circuits the chain — downstream plugins don't run.
+- **Async `check()` allowed** — plugins can call feature-flag servers or compliance APIs. A plugin that takes >1 second logs a warning (target is sub-second).
+- **Plugin throws become hard rejects.** The runner catches them and treats the message as the rejection reason.
+- **Plugin names must be unique per client.** Config validation at handle construction rejects duplicates.
 
-4 pre-configured vault templates for common use cases:
+---
 
-| Preset              | Permissions      | Daily Cap | Slippage |
-| ------------------- | ---------------- | --------- | -------- |
-| `jupiter-swap-bot`  | Swap only        | $500      | 2%       |
-| `perps-trader`      | Perps + Swap     | $5,000    | 5%       |
-| `lending-optimizer` | Deposit/Withdraw | $2,000    | 1%       |
-| `full-access`       | All 21 actions   | $10,000   | 5%       |
+## React hooks (v0.11.0, optional subpath)
 
-```typescript
-import { getPreset, presetToCreateVaultFields } from "@usesigil/kit";
+Install React + TanStack Query as optional peer dependencies, then import from `@usesigil/kit/react`:
 
-const preset = getPreset("jupiter-swap-bot");
-const fields = presetToCreateVaultFields(preset);
+```bash
+npm install react @tanstack/react-query
 ```
 
-### HTTP 402 Payments (x402)
+```tsx
+import { useVaultBudget, useOverview, useExecute } from "@usesigil/kit/react";
+
+function VaultDashboard({ vault }: { vault: SigilVault }) {
+  const budget = useVaultBudget(vault); // { data, isLoading, error }
+  const overview = useOverview(vault); // owner-only
+  const execute = useExecute(vault); // { mutate, mutateAsync, isPending }
+
+  if (budget.isLoading) return <div>Loading...</div>;
+  return (
+    <button
+      onClick={() =>
+        execute.mutate({
+          instructions: myJupiterInstructions,
+          opts: { tokenMint: USDC_MINT_DEVNET, amount: parseUsd("$10") },
+        })
+      }
+      disabled={execute.isPending}
+    >
+      Swap $10
+    </button>
+  );
+}
+```
 
-Sigil supports the [x402 standard](https://www.x402.org/) for automatic HTTP 402 payment negotiation on Solana. Use `shieldedFetch()` to handle payment-required responses transparently — spending limits and vault policies are enforced on every payment.
+Query keys are namespaced under `"sigil"` so they never collide with the consumer app's TanStack cache. Cache invalidation is the consumer's responsibility — wrap `useExecute` with a custom `onSuccess` that invalidates the specific vault keys you want refetched.
 
-```typescript
-import { shieldedFetch, createShieldedFetch } from "@usesigil/kit/x402";
+Consumers who don't use React never install the peer deps and never see a warning.
 
-// One-shot: fetch a paywalled URL, auto-negotiate payment
-const response = await shieldedFetch(url, {
-  vault,
-  agent,
-  rpc,
-  network: "devnet",
-  maxPaymentUsd: 1_000_000n, // $1 max per request
-});
+---
 
-if (response.x402?.paid) {
-  console.log(`Paid ${response.x402.amount} to ${response.x402.payTo}`);
-}
+## Security boundary
 
-// Reusable: create a pre-configured fetch function
-const fetch402 = createShieldedFetch({ vault, agent, rpc, network: "devnet" });
-const res = await fetch402("https://api.example.com/premium-data");
-```
+**What the on-chain program enforces:**
 
-The x402 subpath exports codec functions (header parsing), payment selectors, nonce tracking, amount validation, and 5 typed error classes (`X402ParseError`, `X402PaymentError`, `X402UnsupportedError`, `X402DestinationBlockedError`, `X402ReplayError`). See [INSTRUCTIONS.md](../docs/INSTRUCTIONS.md) for the full 12-step `shieldedFetch()` flow.
+- Daily and per-transaction spending caps (`dailySpendingCapUsd`, `maxTransactionSizeUsd`)
+- Per-agent spending limits (`spendingLimitUsd`)
+- Protocol allowlist / denylist (`protocols`, `protocolMode`)
+- Slippage tolerance on Jupiter swaps (`maxSlippageBps`)
+- Session expiry, position counters, leverage limits
+- Owner timelock on policy changes (`timelockDuration`)
 
-## Branded Types
+**What the SDK enforces pre-submission:**
 
-All USD amounts, capability tiers, and slot numbers are branded bigint types that prevent accidental misuse at compile time:
+- Agent capability check (2-bit enum: Disabled / Observer / Operator)
+- Genesis-hash assertion on `SigilClient.create()` — prevents cluster mismatch
+- Strict USD parsing (`parseUsd`) — no `parseFloat` rounding
+- Aggregate cap guard — sum of per-agent caps ≤ vault cap
+- SPL token-operation detection — blocks non-whitelisted transfer patterns
 
-```typescript
-import {
-  usd,
-  capability,
-  slot,
-  type UsdBaseUnits,
-  type CapabilityTier,
-} from "@usesigil/kit";
+**What the SDK does NOT attempt:**
 
-const cap: UsdBaseUnits = usd(500_000_000n); // $500
-const tier: CapabilityTier = capability(2n); // Operator
+- Key custody — bring your own `TransactionSigner` (Turnkey, Crossmint, Privy, or a local keypair)
+- Transaction simulation outcome trust — simulation is a hint, not a guarantee; on-chain enforcement is the source of truth
+- Replay prevention outside a session — agents must start a new session per transaction
 
-// TypeScript ERROR — these types are not interchangeable:
-// addAgent(agent, cap, tier);  // cap and tier swapped → compile error
-addAgent(agent, tier, cap); // correct order → compiles
-```
+If a piece of SDK logic is wrong, the worst a consumer loses is some UX clarity — the on-chain program still rejects the bad transaction. The boundary is deliberate.
 
-Zero runtime cost — the brand is a phantom type that TypeScript erases at compile time.
+---
 
-## MCP Round-Trip (fromJSON)
+## Configuration presets
 
-When AI agents consume Sigil via MCP, they receive JSON from tool responses and pass data back to subsequent calls. The `fromJSON` functions rehydrate bigints, typed addresses, and `toJSON()` methods:
+### Use-case presets (`VAULT_PRESETS`)
 
-```typescript
-import { overviewDataFromJSON } from "@usesigil/kit/dashboard";
+Starting templates for specific agent roles. Each sets capability, allowlist, slippage, and caps appropriate for the use case:
 
-// MCP tool response → JSON → rehydrated live types
-const overview = overviewDataFromJSON(toolResponse.data);
-console.log(overview.spending.global.today); // bigint, not string
-```
+- `jupiter-swap-bot` — Jupiter only, conservative caps ($500/day, $100/tx)
+- `perps-trader` — Jupiter + Flash Trade, 10× leverage, $5,000/day
+- `lending-optimizer` — Jupiter Lend + Kamino, 1% slippage, $2,000/day
+- `full-access` — every protocol allowed, $10,000/day, 20× leverage
 
-10 fromJSON functions cover all dashboard types. Available from `@usesigil/kit/dashboard`.
+### Safety presets (`SAFETY_PRESETS`) — v0.9.0
 
-## Error Handling
+Orthogonal to the use-case presets. Picks safe defaults for timelock and caps without prescribing a use case:
 
-All errors from `wrap()` and `executeAndConfirm()` convert to structured `AgentError`:
+- `development` — 30-min timelock, $100/agent, $500/day. Safe for devnet / CI.
+- `production` — 24-hour timelock, caps explicitly `null`. You must supply real values via `applySafetyPreset("production", { ... })` — the SDK will throw if you try to use an unfilled production preset with `createVault`.
 
-```typescript
-import { toAgentError } from "@usesigil/kit";
+Compose them:
 
-try {
-  await client.executeAndConfirm(instructions, opts);
-} catch (err) {
-  const e = toAgentError(err);
-  console.log(e.category); // "PERMISSION" | "SPENDING_CAP" | "INPUT_VALIDATION" | ...
-  console.log(e.retryable); // boolean
-  console.log(e.recovery_actions); // [{ action, description, tool? }]
-}
+```ts
+import { createVault, VAULT_PRESETS, applySafetyPreset } from "@usesigil/kit";
+
+const presetFields = VAULT_PRESETS["jupiter-swap-bot"];
+const safety = applySafetyPreset("production", {
+  spendingLimitUsd: 1_000_000_000n, // $1,000 per agent
+  dailySpendingCapUsd: 10_000_000_000n, // $10,000 vault-wide
+});
+await createVault({
+  rpc,
+  network: "mainnet",
+  owner,
+  agent,
+  ...presetFields,
+  ...safety,
+});
 ```
 
-10 error categories with recovery guidance. 71 on-chain error codes (6000-6070) mapped.
+---
 
-## Testing
+## Jupiter integration
 
-```typescript
-// Browser-safe mocks (no node:fs, no @solana/web3.js)
-import { createMockRpc, createMockVaultState } from "@usesigil/kit/testing";
+`@usesigil/kit` does not wrap Jupiter. Use the official [`@jup-ag/api`](https://www.npmjs.com/package/@jup-ag/api) client to build swap instructions, then pipe the `Instruction[]` through `seal()`:
 
-// Real devnet helpers (Node-only)
-import { provisionVault, createDevnetRpc } from "@usesigil/kit/testing/devnet";
+```ts
+import { createJupiterApiClient } from "@jup-ag/api";
+import { seal } from "@usesigil/kit";
+
+const jupiter = createJupiterApiClient();
+const { swapTransaction, addressLookupTableAddresses } = await jupiter.swapPost(
+  { quoteResponse, userPublicKey: vault },
+);
+
+// Extract instructions from the serialized swapTransaction (helper omitted
+// for brevity — decode with @solana/kit's `getCompiledTransactionMessageDecoder`
+// then convert each CompiledInstruction to the Kit Instruction shape).
+const jupiterIxs: Instruction[] = decodeSwapInstructions(swapTransaction);
+
+const sealed = await seal({
+  rpc,
+  network: "devnet",
+  vault,
+  agent: agentSigner,
+  instructions: jupiterIxs,
+  tokenMint: USDC_MINT_DEVNET,
+  amount: 10_000_000n, // $10 in base units
+  protocolAltAddresses: addressLookupTableAddresses, // rotate per-route
+});
 ```
 
-`@usesigil/kit/testing` provides mock factories for unit tests. `@usesigil/kit/testing/devnet` provides real devnet helpers (vault provisioning, funded agents, USDC airdrops). The devnet subpath imports `node:fs` and `@solana/web3.js` — keep it out of browser bundles.
+Any Jupiter-supported protocol flows through the same path; Sigil treats the instructions opaquely and enforces policy on the account touches Jupiter actually makes.
+
+---
+
+## Subpath imports
+
+| Import                         | Use for                                                              |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `@usesigil/kit`                | Main API: `seal`, `SigilClient`, `createVault`, analytics, presets   |
+| `@usesigil/kit/errors`         | The 52 `SIGIL_ERROR__*` code constants for `catch`-block narrowing   |
+| `@usesigil/kit/dashboard`      | `OwnerClient` for vault management (reads + owner mutations)         |
+| `@usesigil/kit/x402`           | HTTP 402 Payment Required helpers (`shieldedFetch`, payment parsing) |
+| `@usesigil/kit/react`          | TanStack Query hooks (v0.11.0) — optional React peer deps            |
+| `@usesigil/kit/testing`        | Mock RPCs and fixtures for unit tests                                |
+| `@usesigil/kit/testing/devnet` | Devnet test harness (browser-incompatible — Node only)               |
+
+---
+
+## v0.10 → v0.11 migration
+
+v0.11.0 is additive. Existing v0.10.0 consumers do not need to change code to upgrade — `Sigil` facade, `SigilVault`, hooks, plugins, and the `/react` subpath all sit on top of the existing `createSigilClient` / `createOwnerClient` / `seal()` primitives.
+
+Recommended migration path:
+
+1. Replace bespoke `createAndSendVault` + `SigilClient.create` + `createOwnerClient` plumbing with `Sigil.quickstart()` / `Sigil.fromVault()` for new call sites.
+2. Add lifecycle hooks to your existing `SigilClientConfig` or `SigilVault.execute()` options for telemetry.
+3. Move React consumers off ad-hoc `useEffect` loops onto `@usesigil/kit/react` hooks.
+
+v0.11.0 also added three new error codes to `/errors` (for a total of 52):
+
+- `SIGIL_ERROR__SDK__HOOK_ABORTED` — onBeforeBuild returned `{ skipSeal: true }`
+- `SIGIL_ERROR__SDK__PLUGIN_REJECTED` — a plugin returned `{ allow: false }`
+- `SIGIL_ERROR__SDK__OWNER_REQUIRED` — an owner-only SigilVault method was called on an agent-only handle
+
+---
+
+## v0.8 → v0.9 migration
 
-## Examples
+v0.9.0 is a breaking release. The headline changes:
 
-- [`examples/jupiter-swap.ts`](./examples/jupiter-swap.ts) — Complete Jupiter V6 swap via Sigil with error handling and P&L tracking
+1. **`createVault` now requires three fields** that previously had silent defaults: `spendingLimitUsd`, `dailySpendingCapUsd`, `timelockDuration`. Set them explicitly or spread `SAFETY_PRESETS.development` / `applySafetyPreset("production", {...})`.
+2. **`SigilClient.create(config)` is the new preferred entry point** — it asserts the RPC's genesis hash matches the configured network. `new SigilClient(config)` is deprecated (removal in Sprint 2) and logs a warning.
+3. **49 `SIGIL_ERROR__*` constants moved from the root barrel** to the `./errors` subpath. Update imports:
+   ```diff
+   - import { SIGIL_ERROR__SDK__CAP_EXCEEDED } from "@usesigil/kit";
+   + import { SIGIL_ERROR__SDK__CAP_EXCEEDED } from "@usesigil/kit/errors";
+   ```
+4. **Root barrel lost ~325 exports** (Codama instruction builders, event/struct types, hex error constants). Consumers who imported generated internals should migrate to `seal()` / `createVault()` / `OwnerClient`. Account decoders stay at root.
+5. **Structured logger replaces `console.warn`** inside the SDK. Pass `logger: createConsoleLogger()` to `SigilClient.create()` (or your preferred logger matching the `SigilLogger` interface) to receive diagnostic output.
 
-## Links
+See `CHANGELOG.md` and the upgrade checklist for every grep you need to run.
 
-- [GitHub](https://github.com/Sigil-Trade/sigil)
-- [npm](https://www.npmjs.com/package/@usesigil/kit)
-- [Issues](https://github.com/Sigil-Trade/sigil/issues)
+---
 
 ## License
 
-Apache-2.0
+Apache-2.0. Copyright 2024-2026 Kaleb Rupe.

package/dist/alt-config.d.ts

@@ -29,10 +29,12 @@ export declare const EXPECTED_ALT_CONTENTS_DEVNET: Address[];
 /**
  * Expected contents of the mainnet Sigil ALT.
  * Uses mainnet mints; treasury is the same across networks.
- * TODO: Add TREASURY_USDC_ATA_MAINNET and TREASURY_USDT_ATA_MAINNET
- * after deploying and extending the mainnet ALT. Derive from:
+ *
+ * Pre-mainnet task: extend this array with TREASURY_USDC_ATA_MAINNET and
+ * TREASURY_USDT_ATA_MAINNET after deploying the mainnet ALT. Derive via:
  *   getAssociatedTokenAddress(USDC_MINT_MAINNET, PROTOCOL_TREASURY, true)
  *   getAssociatedTokenAddress(USDT_MINT_MAINNET, PROTOCOL_TREASURY, true)
+ * Tracked alongside mainnet deployment checklist (D3 — upgrade authority transfer).
  */
 export declare const EXPECTED_ALT_CONTENTS_MAINNET: Address[];
 /**

package/dist/alt-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alt-config.d.ts","sourceRoot":"","sources":["../src/alt-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAW1C,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,EACuB,OAAO,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,EAAyC,OAAO,CAAC;AAU/E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ5D;AAYD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,OAAO,EAQjD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,OAAO,EAMlD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAIlE"}
+{"version":3,"file":"alt-config.d.ts","sourceRoot":"","sources":["../src/alt-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAW1C,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,EACuB,OAAO,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,EAAyC,OAAO,CAAC;AAU/E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ5D;AAYD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,OAAO,EAQjD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,EAAE,OAAO,EAMlD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAIlE"}

package/dist/alt-config.js

@@ -54,10 +54,12 @@ export const EXPECTED_ALT_CONTENTS_DEVNET = [
 /**
  * Expected contents of the mainnet Sigil ALT.
  * Uses mainnet mints; treasury is the same across networks.
- * TODO: Add TREASURY_USDC_ATA_MAINNET and TREASURY_USDT_ATA_MAINNET
- * after deploying and extending the mainnet ALT. Derive from:
+ *
+ * Pre-mainnet task: extend this array with TREASURY_USDC_ATA_MAINNET and
+ * TREASURY_USDT_ATA_MAINNET after deploying the mainnet ALT. Derive via:
  *   getAssociatedTokenAddress(USDC_MINT_MAINNET, PROTOCOL_TREASURY, true)
  *   getAssociatedTokenAddress(USDT_MINT_MAINNET, PROTOCOL_TREASURY, true)
+ * Tracked alongside mainnet deployment checklist (D3 — upgrade authority transfer).
  */
 export const EXPECTED_ALT_CONTENTS_MAINNET = [
     USDC_MINT_MAINNET,