@usesigil/kit 0.15.0 → 0.17.0

package/dist/preview-create-vault.js

@@ -0,0 +1,498 @@
+/**
+ * `@usesigil/kit/previewCreateVault`.
+ *
+ * Builds a `CreateVaultPreview` that the dashboard split-screen `/onboard`
+ * page renders BEFORE the user signs. Wraps the existing `createVault()`
+ * + `buildOwnerTransaction()` primitives — does not reinvent PDA derivation,
+ * compute-budget construction, or transaction compilation.
+ *
+ * ## Algorithm
+ *
+ * 1. **Validate** the config at the API edge. Negative bigints throw
+ *    `RangeError`; on-chain hard limits (`MIN_TIMELOCK_DURATION`,
+ *    `MAX_DEVELOPER_FEE_RATE`, `MAX_ALLOWED_PROTOCOLS`,
+ *    `MAX_ALLOWED_DESTINATIONS`) are mirrored as early throws so the FE
+ *    surfaces "your config will be rejected" before signing.
+ *    `validateNetwork()` propagates as-is.
+ * 2. **Derive 4 PDAs.** `vault` first (it's the seed for the others),
+ *    then `policy` / `tracker` / `agent_spend_overlay` in parallel.
+ * 3. **Fetch rent** for each PDA size in parallel via
+ *    `getMinimumBalanceForRentExemption(size)`. The 4 sizes are pinned to
+ *    the on-chain `<account>::SIZE` constants — drift between Rust and TS
+ *    is regression-tested.
+ * 4. **Build instructions** via `createVault()` (which validates
+ *    aggregate caps and rejects owner==agent).
+ * 5. **Compile transaction** via `buildOwnerTransaction()` with
+ *    `CU_VAULT_CREATION` (400_000) and the caller's optional priority fee.
+ * 6. **Compute totalCostUsd** via BigInt-safe math with explicit
+ *    mul-before-divide:
+ *    `(rentLamports + feeLamports) * solPriceUsd / 1_000_000_000n`.
+ *    Units: lamports × (6-decimal-USD per SOL) ÷ (lamports per SOL)
+ *      = 6-decimal USD.
+ * 7. **Build warnings** for soft-signal issues (cap=0, cap>$1M, allowlist
+ *    with no protocols, max-tx > daily-cap). Sorted by `code` ascending so
+ *    React keys don't thrash on re-type.
+ * 8. **Freeze + return.** The returned object is `Object.freeze`d; the
+ *    `pdaList` and `warnings` arrays are also frozen.
+ *
+ * ## What this does NOT do
+ *
+ *  - **Submit any transaction.** Preview is read-only RPC: rent + blockhash
+ *    + ALT lookup. No `sendTransaction`, no `simulateTransaction`.
+ *  - **Sign.** Internally constructs `createNoopSigner(address)` instances
+ *    so `buildOwnerTransaction` can compile a fee-payer-bound message.
+ *    Wallet adapter signs the returned `unsignedTxBytes` later.
+ *  - **Fetch SOL price.** Kit has no oracle. Caller passes
+ *    `solPriceUsd: bigint` (6-decimal USD per SOL). Without it, the kit
+ *    would have to either pin a default (silent lie) or take an RPC
+ *    dependency on a price feed (scope creep).
+ */
+import { createNoopSigner } from "./kit-adapter.js";
+import { getVaultPDA, getPolicyPDA, getTrackerPDA, getAgentOverlayPDA, } from "./resolve-accounts.js";
+import { createVault } from "./create-vault.js";
+import { buildOwnerTransaction } from "./owner-transaction.js";
+import { CU_VAULT_CREATION } from "./priority-fees.js";
+import { validateNetwork, SYSTEM_PROGRAM_ADDRESS, MAX_DEVELOPER_FEE_RATE, MAX_ALLOWED_PROTOCOLS, U64_MAX, } from "./types.js";
+import { SigilSdkDomainError } from "./errors/sdk.js";
+import { SIGIL_ERROR__SDK__INVALID_PARAMS } from "./errors/codes.js";
+// ─── On-chain account sizes (verified against programs/sigil/src/state/*.rs) ─
+/**
+ * `AgentVault::SIZE` from `programs/sigil/src/state/vault.rs:135-152`.
+ * Layout: 8 disc + 32 owner + 8 vault_id + 4 vec_prefix + (49 * 10) agents
+ *       + 32 fee_destination + 1 status + 1 bump + 8 created_at
+ *       + 8 total_transactions + 8 total_volume
+ *       + 8 total_fees_collected + 8 total_deposited_usd + 8 total_withdrawn_usd
+ *       + 8 total_failed_transactions + 1 active_sessions
+ *       + 1 observe_only [Phase 2 TA-19] + 8 frozen_at_timestamp + 1 freeze_reason
+ *       + 1 owner_type [F-Q6] + 32 vault_authority [Phase 8 LBL-01] = 676.
+ *   (Was 634 — stale: it predated the Phase-8 fields frozen_at_timestamp +
+ *    freeze_reason + vault_authority (+41) and F-Q6 owner_type (+1); corrected
+ *    to the rent-exact 676 here.)
+ */
+const AGENT_VAULT_SIZE = 676;
+/**
+ * `PolicyConfig::SIZE` from `programs/sigil/src/state/policy.rs:323-350`.
+ * Layout: 8 disc + 32 vault + 8 daily_cap + 8 max_tx + 1 protocol_mode
+ *       + (4 + 32*10) protocols + 2 dev_fee + 2 max_slippage_bps
+ *       + 8 session_window + (4 + 32*10) allowed_destinations
+ *       + 1 has_pending_policy + 1 has_protocol_caps [M1-04 removed has_constraints]
+ *       + (4 + 8*10) protocol_caps + 8 session_expiry + 1 bump
+ *       + 8 policy_version + 1 has_post_assertions + 1 destination_mode
+ *       + 32 policy_preview_digest [TA-19 Phase 2]
+ *       + 8 created_at_slot [PEN-CROSS-2]
+ *       + 4 operating_hours [TA-05 Phase 3]
+ *       + (4 + 40*10) destination_graylist [TA-07 Phase 3]
+ *       + 1 auto_promote_grays [TA-07] + 1 auto_revoke_threshold [TA-17]
+ *       + 8 stable_balance_floor [TA-12 Phase 5]
+ *       + 8 per_recipient_daily_cap_usd [TA-14 Phase 5]
+ *       + 1 cosign_required [G6 audit 2026-05-18]
+ *       + 32 cosign_session_pubkey [D-5 audit 2026-05-19, F-RP3-1]
+ *       + 8 operator_grant_delay_seconds [F-Q6 2026-06-02] = 1,329.
+ *   (Was 1,322 pre-F-Q6 — that value double-counted the M1-04-removed
+ *    has_constraints byte; corrected to the rent-exact 1,329 here.)
+ */
+const POLICY_CONFIG_SIZE = 1_329;
+/**
+ * `SpendTracker::SIZE` from `programs/sigil/src/state/tracker.rs:200-214`.
+ * Layout: 8 disc + 32 vault + (16 * 144) buckets + (48 * 10) protocol_counters
+ *       + 8 last_write_epoch + 1 bump + 7 padding
+ *       + (48 * 10) per_recipient [TA-14 Phase 5]
+ *       + 1 per_recipient_count + 7 _padding_recipient = 3,328.
+ */
+const SPEND_TRACKER_SIZE = 3_328;
+/**
+ * `AgentSpendOverlay::SIZE` from `programs/sigil/src/state/agent_spend_overlay.rs:114-123`.
+ * Layout: 8 disc + 32 vault + (232 * 10) entries + 1 bump + 7 padding
+ *       + (8 * 10) lifetime_spend + (8 * 10) lifetime_tx_count
+ *       + (8 * 10) cooldown_seconds [TA-06 Phase 3]
+ *       + (8 * 10) last_action_unix [TA-06 Phase 3] = 2,688.
+ */
+const AGENT_SPEND_OVERLAY_SIZE = 2_688;
+/** Default priority fee when caller doesn't supply one. Conservative. */
+const DEFAULT_PRIORITY_FEE_MICRO_LAMPORTS = 10_000;
+/** `1_000_000_000` lamports per SOL. */
+const LAMPORTS_PER_SOL = 1000000000n;
+/** Microlamports per lamport. */
+const MICRO_LAMPORTS_PER_LAMPORT = 1000000n;
+/** Heuristic: dailyCapUsd above $1,000,000 (6-decimal base units) → warn. */
+const DAILY_CAP_HIGH_THRESHOLD = 1000000000000n;
+/**
+ * Upper bound for any 6-decimal USD bigint at the public API edge.
+ * Re-exported from `types.U64_MAX` (`18_446_744_073_709_551_615n`). The
+ * on-chain program stores these as `u64`; values above overflow there. We
+ * reject at the kit edge rather than ship a tx the program will reject.
+ */
+const MAX_USD_BASE_UNITS = U64_MAX;
+/** Mirror of `MIN_TIMELOCK_DURATION` (1800) from `state/mod.rs`. */
+const MIN_TIMELOCK_DURATION_SECONDS = 1800n;
+/** Mirror of `MAX_ALLOWED_DESTINATIONS` (10) from `state/mod.rs`. */
+const MAX_ALLOWED_DESTINATIONS_COUNT = 10;
+// ─── Implementation ──────────────────────────────────────────────────────────
+/**
+ * Generate a `CreateVaultPreview` for the dashboard split-screen `/onboard`
+ * flow. See module JSDoc for the algorithm and design rationale.
+ *
+ * @throws {RangeError} If any bigint config field is negative or any count
+ *   exceeds its on-chain maximum, or if `timelockDuration < 1800n`,
+ *   or if `developerFeeRate > 500`.
+ * @throws {SigilSdkDomainError} If `validateNetwork(config.network)` fails,
+ *   if `getMinimumBalanceForRentExemption` returns 0n / undefined,
+ *   or if `createVault()` rejects the config (e.g., owner == agent,
+ *   spendingLimit > dailyCap aggregate).
+ */
+export async function previewCreateVault(config) {
+    // 1. Validate config at the API edge (fail fast, descriptive errors).
+    validateConfig(config);
+    // Normalize "mainnet-beta" → "mainnet" for createVault / buildOwnerTransaction
+    // (which use the short literal type) while still accepting either form.
+    const buildNetwork = toBuildNetwork(config.network);
+    // 2 + 3. Derive PDAs and fetch rent concurrently.
+    //
+    // Rent depends on size only, not address — fire all 4 rent RPC fetches
+    // in parallel with PDA derivation. PDA derivation is pure CPU (sha256
+    // in a 0..255 bump search loop) so overlapping it with network latency
+    // removes the serial CPU step from the wall-clock path on hot
+    // dashboard re-types.
+    //
+    // `vault` is the seed for the other three PDAs, so we wrap the
+    // dependent chain (`getVaultPDA` → policy/tracker/overlay) in a single
+    // async IIFE and `Promise.all` it alongside the rent fetches. Wrapping
+    // (rather than `await`-ing the vault PDA up front) keeps the rent
+    // promises in a Promise.all from the moment they're created, so a
+    // rejecting RPC never produces a transient
+    // `PromiseRejectionHandledWarning`.
+    const vaultChain = (async () => {
+        const [vAddr, vBump] = await getVaultPDA(config.owner, config.vaultId);
+        const [policy, tracker, overlay] = await Promise.all([
+            getPolicyPDA(vAddr),
+            getTrackerPDA(vAddr),
+            getAgentOverlayPDA(vAddr, 0),
+        ]);
+        return { vAddr, vBump, policy, tracker, overlay };
+    })();
+    const [{ vAddr, vBump, policy, tracker, overlay }, vaultRent, policyRent, trackerRent, overlayRent,] = await Promise.all([
+        vaultChain,
+        fetchRentForSize(config.rpc, AGENT_VAULT_SIZE, "AgentVault"),
+        fetchRentForSize(config.rpc, POLICY_CONFIG_SIZE, "PolicyConfig"),
+        fetchRentForSize(config.rpc, SPEND_TRACKER_SIZE, "SpendTracker"),
+        fetchRentForSize(config.rpc, AGENT_SPEND_OVERLAY_SIZE, "AgentSpendOverlay"),
+    ]);
+    const vaultAddress = vAddr;
+    const vaultBump = vBump;
+    const [policyAddress, policyBump] = policy;
+    const [trackerAddress, trackerBump] = tracker;
+    const [overlayAddress, overlayBump] = overlay;
+    // 4. Build the pdaList tuple in deterministic on-chain `init` order.
+    const pdaList = Object.freeze([
+        makePdaInfo("AgentVault", vaultAddress, vaultBump, AGENT_VAULT_SIZE, vaultRent),
+        makePdaInfo("PolicyConfig", policyAddress, policyBump, POLICY_CONFIG_SIZE, policyRent),
+        makePdaInfo("SpendTracker", trackerAddress, trackerBump, SPEND_TRACKER_SIZE, trackerRent),
+        makePdaInfo("AgentSpendOverlay", overlayAddress, overlayBump, AGENT_SPEND_OVERLAY_SIZE, overlayRent),
+    ]);
+    const rentLamports = vaultRent + policyRent + trackerRent + overlayRent;
+    // 5. Build the create-vault instructions. `createVault` validates aggregate
+    //    caps and owner≠agent for us; we propagate its throws.
+    const ownerSigner = createNoopSigner(config.owner);
+    const agentSigner = createNoopSigner(config.agentAddress);
+    const createResult = await createVault({
+        rpc: config.rpc,
+        network: buildNetwork,
+        owner: ownerSigner,
+        agent: agentSigner,
+        permissions: config.capabilityTier !== undefined
+            ? config.capabilityTier
+            : undefined,
+        spendingLimitUsd: config.spendingLimitUsd,
+        dailySpendingCapUsd: config.dailyCapUsd,
+        maxTransactionSizeUsd: config.maxTxSizeUsd,
+        feeDestination: config.feeDestination,
+        developerFeeRate: config.developerFeeRate,
+        protocols: [...config.protocols],
+        protocolMode: config.protocolMode,
+        maxSlippageBps: config.maxSlippageBps,
+        timelockDuration: Number(config.timelockDuration),
+        allowedDestinations: [...config.allowedDestinations],
+        vaultId: config.vaultId,
+        protocolCaps: config.protocolCaps.length > 0 ? [...config.protocolCaps] : undefined,
+    });
+    // 6. Compile the unsigned transaction.
+    const computeUnits = config.computeUnits ?? CU_VAULT_CREATION;
+    const priorityFeeMicroLamports = config.priorityFeeMicroLamports ?? DEFAULT_PRIORITY_FEE_MICRO_LAMPORTS;
+    const ownerTx = await buildOwnerTransaction({
+        rpc: config.rpc,
+        owner: ownerSigner,
+        instructions: [
+            createResult.initializeVaultIx,
+            createResult.registerAgentIx,
+        ],
+        network: buildNetwork,
+        computeUnits,
+        priorityFeeMicroLamports,
+        ...(config.blockhash !== undefined ? { blockhash: config.blockhash } : {}),
+        ...(config.addressLookupTables !== undefined
+            ? { addressLookupTables: config.addressLookupTables }
+            : {}),
+    });
+    // 7. feeLamports: microLamports per CU * CU / 1_000_000. Mul-before-divide
+    //    in BigInt to avoid number/bigint mixing.
+    const feeLamports = (BigInt(priorityFeeMicroLamports) * BigInt(computeUnits)) /
+        MICRO_LAMPORTS_PER_LAMPORT;
+    // 8. totalCostUsd: mul-before-divide preserves precision down to 1 unit of
+    //    6-decimal USD.
+    const totalCostUsd = ((rentLamports + feeLamports) * config.solPriceUsd) / LAMPORTS_PER_SOL;
+    const unsignedTxBytes = base64ToUint8Array(ownerTx.wireBase64);
+    // 9. lastValidBlockHeight is sourced from the same blockhash baked into the
+    //    wire bytes — never re-read the cache (TTL refresh would race the bytes
+    //    the user is about to sign).
+    const blockhash = ownerTx.blockhash;
+    // 10. Warnings (sorted by code) → undefined when empty so the FE skips
+    //     rendering the panel.
+    const warningsRaw = buildWarnings(config);
+    const warnings = warningsRaw.length > 0
+        ? Object.freeze(warningsRaw)
+        : undefined;
+    const preview = {
+        pdaList,
+        rentLamports,
+        computeUnits,
+        feeLamports,
+        totalCostUsd,
+        vaultAddress,
+        unsignedTxBytes,
+        txSizeBytes: ownerTx.txSizeBytes,
+        lastValidBlockHeight: blockhash.lastValidBlockHeight,
+        ...(warnings !== undefined ? { warnings } : {}),
+    };
+    return Object.freeze(preview);
+}
+// ─── Private helpers ─────────────────────────────────────────────────────────
+/**
+ * Build one frozen `VaultPdaInfo` entry for `pdaList`. The literal `name`
+ * type is preserved so each tuple slot narrows to its specific account class
+ * (e.g. `pdaList[0].name === "AgentVault"`).
+ */
+function makePdaInfo(name, address, bump, sizeBytes, rentLamports) {
+    return Object.freeze({
+        name,
+        address,
+        bump,
+        sizeBytes,
+        rentLamports,
+    });
+}
+/**
+ * Validate config at the API edge. Throws `RangeError` for value-out-of-range
+ * (matches the `composeAgentBootstrap` convention) and lets `validateNetwork`
+ * propagate its `SigilSdkDomainError`.
+ */
+function validateConfig(config) {
+    // Network — propagates SigilSdkDomainError if invalid.
+    validateNetwork(config.network);
+    // Negative bigints. `solPriceUsd` rejects 0n too — kit has no oracle, and
+    // a price of 0 silently produces `totalCostUsd === 0n` which the FE
+    // would render as "Free". Fail loud.
+    if (config.vaultId < 0n) {
+        throw new RangeError(`vaultId must be >= 0; received ${config.vaultId}`);
+    }
+    if (config.dailyCapUsd < 0n) {
+        throw new RangeError(`dailyCapUsd must be >= 0; received ${config.dailyCapUsd}`);
+    }
+    if (config.maxTxSizeUsd < 0n) {
+        throw new RangeError(`maxTxSizeUsd must be >= 0; received ${config.maxTxSizeUsd}`);
+    }
+    if (config.spendingLimitUsd < 0n) {
+        throw new RangeError(`spendingLimitUsd must be >= 0; received ${config.spendingLimitUsd}`);
+    }
+    if (config.solPriceUsd <= 0n) {
+        throw new RangeError(`solPriceUsd must be > 0n; received ${config.solPriceUsd}. ` +
+            `The kit has no oracle — caller must supply a fresh, positive price.`);
+    }
+    if (config.timelockDuration < 0n) {
+        throw new RangeError(`timelockDuration must be >= 0; received ${config.timelockDuration}`);
+    }
+    // Upper bounds — `u64::MAX` overflow guards. The on-chain program stores
+    // these as `u64`; values above `(1 << 64) - 1` overflow there. Reject at
+    // the kit edge.
+    if (config.dailyCapUsd > MAX_USD_BASE_UNITS) {
+        throw new RangeError(`dailyCapUsd must be <= u64::MAX (${MAX_USD_BASE_UNITS}); received ${config.dailyCapUsd}`);
+    }
+    if (config.maxTxSizeUsd > MAX_USD_BASE_UNITS) {
+        throw new RangeError(`maxTxSizeUsd must be <= u64::MAX; received ${config.maxTxSizeUsd}`);
+    }
+    if (config.spendingLimitUsd > MAX_USD_BASE_UNITS) {
+        throw new RangeError(`spendingLimitUsd must be <= u64::MAX; received ${config.spendingLimitUsd}`);
+    }
+    if (config.solPriceUsd > MAX_USD_BASE_UNITS) {
+        throw new RangeError(`solPriceUsd must be <= u64::MAX; received ${config.solPriceUsd}`);
+    }
+    // `timelockDuration` is a bigint at the API but createVault takes a
+    // number. Number can lose precision above 2^53. Reject silently-lossy
+    // values rather than ship a tx with a different timelock than the user
+    // typed.
+    if (config.timelockDuration > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError(`timelockDuration must be <= Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER}); ` +
+            `received ${config.timelockDuration}. Larger values lose precision in the bigint→number cast.`);
+    }
+    // On-chain hard limits — mirror as early throws.
+    if (config.timelockDuration < MIN_TIMELOCK_DURATION_SECONDS) {
+        throw new RangeError(`timelockDuration must be >= ${MIN_TIMELOCK_DURATION_SECONDS}n (MIN_TIMELOCK_DURATION); ` +
+            `the on-chain program rejects shorter timelocks. Received ${config.timelockDuration}.`);
+    }
+    if (!Number.isInteger(config.developerFeeRate) ||
+        config.developerFeeRate < 0) {
+        throw new RangeError(`developerFeeRate must be a non-negative integer; received ${config.developerFeeRate}`);
+    }
+    if (config.developerFeeRate > MAX_DEVELOPER_FEE_RATE) {
+        throw new RangeError(`developerFeeRate must be <= ${MAX_DEVELOPER_FEE_RATE} BPS (MAX_DEVELOPER_FEE_RATE); ` +
+            `received ${config.developerFeeRate}`);
+    }
+    if (!Number.isInteger(config.maxSlippageBps) || config.maxSlippageBps < 0) {
+        throw new RangeError(`maxSlippageBps must be a non-negative integer; received ${config.maxSlippageBps}`);
+    }
+    if (config.protocols.length > MAX_ALLOWED_PROTOCOLS) {
+        throw new RangeError(`protocols.length must be <= ${MAX_ALLOWED_PROTOCOLS} (MAX_ALLOWED_PROTOCOLS); ` +
+            `received ${config.protocols.length}`);
+    }
+    if (config.allowedDestinations.length > MAX_ALLOWED_DESTINATIONS_COUNT) {
+        throw new RangeError(`allowedDestinations.length must be <= ${MAX_ALLOWED_DESTINATIONS_COUNT} (MAX_ALLOWED_DESTINATIONS); ` +
+            `received ${config.allowedDestinations.length}`);
+    }
+    // protocol_caps when non-empty must align with allowlist mode and length.
+    if (config.protocolCaps.length > 0) {
+        if (config.protocolMode !== 1) {
+            throw new RangeError(`protocolCaps requires protocolMode === 1 (ALLOWLIST); received ${config.protocolMode}`);
+        }
+        if (config.protocolCaps.length !== config.protocols.length) {
+            throw new RangeError(`protocolCaps.length (${config.protocolCaps.length}) must equal protocols.length (${config.protocols.length})`);
+        }
+        for (const cap of config.protocolCaps) {
+            if (cap < 0n) {
+                throw new RangeError(`each protocolCaps entry must be >= 0; received ${cap}`);
+            }
+            if (cap > MAX_USD_BASE_UNITS) {
+                throw new RangeError(`each protocolCaps entry must be <= u64::MAX; received ${cap}`);
+            }
+        }
+    }
+    // `feeDestination` cannot be the system program (Pubkey::default = all-1s
+    // base58); the on-chain program rejects it at line 91-93 of
+    // initialize_vault.rs with `InvalidFeeDestination`.
+    if (config.feeDestination === SYSTEM_PROGRAM_ADDRESS) {
+        throw new RangeError(`feeDestination must not be the system program ` +
+            `(${SYSTEM_PROGRAM_ADDRESS}); the on-chain program rejects it as ` +
+            `InvalidFeeDestination`);
+    }
+    // Optional numeric overrides — must be non-negative integers. Negatives
+    // and NaN both produce silent drift (negative fee in preview but skipped
+    // on-chain; non-integer throws deep in BigInt(...)).
+    if (config.priorityFeeMicroLamports !== undefined) {
+        if (!Number.isInteger(config.priorityFeeMicroLamports) ||
+            config.priorityFeeMicroLamports < 0) {
+            throw new RangeError(`priorityFeeMicroLamports must be a non-negative integer; received ${config.priorityFeeMicroLamports}`);
+        }
+    }
+    if (config.computeUnits !== undefined) {
+        if (!Number.isInteger(config.computeUnits) || config.computeUnits <= 0) {
+            throw new RangeError(`computeUnits must be a positive integer; received ${config.computeUnits}`);
+        }
+    }
+}
+/**
+ * Resolve a `NetworkInput` to the `"devnet" | "mainnet"` shape that
+ * `createVault` and `buildOwnerTransaction` accept. `validateNetwork` has
+ * already gated the input by the time this runs.
+ */
+function toBuildNetwork(network) {
+    // After validateNetwork, network is one of "devnet", "mainnet", "mainnet-beta".
+    // createVault accepts only the short literal; "mainnet-beta" → "mainnet".
+    return network === "devnet" ? "devnet" : "mainnet";
+}
+/**
+ * Wrap `getMinimumBalanceForRentExemption` with explicit defensive checks.
+ * If the RPC returns `0n` or anything non-bigint, we surface a typed
+ * `SigilSdkDomainError` instead of producing a preview that lies about
+ * cost. Caller errors propagate with cause attached.
+ */
+async function fetchRentForSize(rpc, size, pdaName) {
+    const rent = await rpc.getMinimumBalanceForRentExemption(BigInt(size)).send();
+    if (typeof rent !== "bigint") {
+        throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_PARAMS, `getMinimumBalanceForRentExemption returned non-bigint for ${pdaName} (size=${size})`, { context: { field: pdaName, received: typeof rent } });
+    }
+    // Reject 0n AND negatives. Rent must always be positive — a "free" PDA
+    // doesn't exist on Solana, and a negative rent is non-physical and would
+    // produce a negative `totalCostUsd` (FE displays "you'll be paid to
+    // create this vault"). Both indicate a misbehaving RPC; surface as a
+    // typed throw so the caller can retry / switch RPC.
+    if (rent <= 0n) {
+        throw new SigilSdkDomainError(SIGIL_ERROR__SDK__INVALID_PARAMS, `getMinimumBalanceForRentExemption returned ${rent} for ${pdaName} (size=${size}); ` +
+            `expected a positive lamport value. RPC may be misconfigured or returning stale data.`, { context: { field: pdaName, received: rent } });
+    }
+    return rent;
+}
+/**
+ * Build the warnings array. Sorted by `code` ascending so the FE's React
+ * keys are stable across re-types (no banner flicker). Returns an empty
+ * array when nothing fires; the caller converts to `undefined` for the
+ * preview shape.
+ */
+function buildWarnings(config) {
+    const warnings = [];
+    if (config.dailyCapUsd === 0n) {
+        warnings.push({
+            code: "daily_cap_zero",
+            severity: "info",
+            message: "Daily spending cap is 0. The vault will accept deposits but the " +
+                "agent cannot execute any spending action until the cap is raised.",
+            field: "dailyCapUsd",
+        });
+    }
+    if (config.dailyCapUsd > DAILY_CAP_HIGH_THRESHOLD) {
+        warnings.push({
+            code: "daily_cap_unusually_high",
+            severity: "warning",
+            message: "Daily spending cap exceeds $1,000,000 — confirm this matches the " +
+                "intended risk tolerance.",
+            field: "dailyCapUsd",
+            suggestedValue: DAILY_CAP_HIGH_THRESHOLD,
+        });
+    }
+    if (config.protocolMode === 1 && config.protocols.length === 0) {
+        warnings.push({
+            code: "no_protocols_approved",
+            severity: "warning",
+            message: "Protocol mode is ALLOWLIST but no protocols are listed; the agent " +
+                "cannot reach any DeFi protocol with this policy.",
+            field: "protocols",
+        });
+    }
+    if (config.maxTxSizeUsd > config.dailyCapUsd) {
+        warnings.push({
+            code: "max_tx_exceeds_daily_cap",
+            severity: "warning",
+            message: "Max transaction size exceeds daily cap; a single transaction can " +
+                "consume the entire 24h budget.",
+            field: "maxTxSizeUsd",
+            suggestedValue: config.dailyCapUsd,
+        });
+    }
+    // Sort by code ascending so the FE's React keys stay stable.
+    warnings.sort((a, b) => (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+    // Freeze each warning so callers can't mutate after return. The cast
+    // preserves the discriminated-union type Object.freeze would erase to
+    // `Readonly<PreviewWarning>`.
+    return warnings.map((w) => Object.freeze(w));
+}
+/**
+ * Decode a base64 string to `Uint8Array`. Uses `atob` (built-in in browser
+ * and Node ≥ 16) so the kit stays Node-only-free. Validates input shape
+ * defensively — `atob` will throw `InvalidCharacterError` on non-base64.
+ */
+function base64ToUint8Array(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+//# sourceMappingURL=preview-create-vault.js.map

package/dist/preview-create-vault.js.map

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

package/dist/resolve-accounts.d.ts

@@ -5,35 +5,100 @@
  * seed encoding. All 9 PDA types are derivable.
  */
 import type { Address } from "./kit-adapter.js";
-export declare function getVaultPDA(owner: Address, vaultId: bigint, programAddress?: Address): Promise<[Address, number]>;
+/**
+ * Minimal shape consumed by {@link getVaultPdaFromState}. The full on-chain
+ * `AgentVault` account (see `state/vault.rs`) carries many fields; only the
+ * two seed inputs are required to rebuild the PDA, so callers may pass any
+ * object that exposes them (typically the result of `fetchAgentVault().data`
+ * or a `ResolvedVaultState`).
+ */
+export interface VaultPdaSeedSource {
+    /**
+     * Phase 8 LBL-01 — the IMMUTABLE seed-key written exactly once in
+     * `initialize_vault`. Survives ownership transfer; reads cleanly from
+     * on-chain `AgentVault.vault_authority`.
+     */
+    vaultAuthority: Address;
+    /** The same `vault_id` (u64) supplied to `initialize_vault`. */
+    vaultId: bigint;
+}
+/**
+ * Derive the AgentVault PDA from its on-chain seeds.
+ *
+ * **Important — post Phase 8 LBL-01:** the on-chain seed is
+ * `vault.vault_authority`, not the current `vault.owner`. The two are
+ * IDENTICAL at `initialize_vault` time (the handler writes
+ * `vault.vault_authority = owner.key()`), so at vault creation a caller
+ * may legitimately pass the initial owner here. After an
+ * `accept_ownership_transfer` the two diverge: `vault.owner` becomes the
+ * new owner while `vault.vault_authority` stays pinned to the original
+ * owner — and the on-chain PDA address is unchanged.
+ *
+ * If you are deriving a PDA for a vault that has (or might have) been
+ * ownership-transferred, prefer {@link getVaultPdaFromState} which reads
+ * `vault_authority` directly from on-chain state. Passing the current
+ * `owner` here for a transferred vault produces the WRONG address and
+ * silently returns a PDA that does not exist on-chain.
+ *
+ * @param vaultAuthority — the immutable seed-key. At `initialize_vault`
+ *   time this is the same as `owner`; thereafter callers must read it
+ *   from `AgentVault.vault_authority`.
+ * @param vaultId — the same `u64` passed to `initialize_vault`.
+ * @param programAddress — defaults to the canonical Sigil program id.
+ *
+ * @deprecated NH-4 close (Bucket 2 re-audit 2026-05-21): the parameter
+ *   was renamed `owner → vaultAuthority` in 0.16.0 to make the LBL-01
+ *   contract explicit at the type level. Direct callers that historically
+ *   passed `vault.owner` will now silently derive the WRONG PDA for any
+ *   ownership-transferred vault. Use {@link getVaultPdaFromState} which
+ *   takes a `{ vaultAuthority, vaultId }` shape — the field name forces
+ *   the caller to read the immutable seed from on-chain state rather
+ *   than assume `owner == vault_authority`. This function stays for
+ *   pre-LBL-01 backward compatibility (init-time call sites where the
+ *   two are equal by construction) and will be removed in v0.18.
+ */
+export declare function getVaultPDA(vaultAuthority: Address, vaultId: bigint, programAddress?: Address): Promise<[Address, number]>;
+/**
+ * Derive the AgentVault PDA from on-chain state.
+ *
+ * **Use this AFTER an ownership transfer.** Reads `vault.vault_authority`
+ * (the immutable Phase 8 LBL-01 seed-key) instead of the current
+ * `vault.owner`, which would resolve to the wrong PDA once
+ * `accept_ownership_transfer` has run.
+ *
+ * Equivalent to calling `getVaultPDA(vault.vaultAuthority, vault.vaultId)`,
+ * but the dedicated name documents the intent at the call site.
+ */
+export declare function getVaultPdaFromState(vault: VaultPdaSeedSource, programAddress?: Address): Promise<[Address, number]>;
 export declare function getPolicyPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
 export declare function getTrackerPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
 export declare function getSessionPDA(vault: Address, agent: Address, tokenMint: Address, programAddress?: Address): Promise<[Address, number]>;
 export declare function getPendingPolicyPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
-export declare function getEscrowPDA(sourceVault: Address, destinationVault: Address, escrowId: bigint, programAddress?: Address): Promise<[Address, number]>;
 export declare function getAgentOverlayPDA(vault: Address, shardIndex?: number, programAddress?: Address): Promise<[Address, number]>;
-export declare function getConstraintsPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
-export declare function getPendingConstraintsPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
 /**
- * Derive PDA for pending CLOSE constraints (queue_close_constraints).
- * Seed: "pending_close_constraints" — NOT the same as "pending_constraints" (which is for updates).
- * See close_vault.rs:127.
+ * Phase 7 — derive PDA for `AuditLogSuccess` at `[b"audit_success", vault]`.
+ * Allocated at vault creation, written by every mutating instruction that
+ * lands on the success path. Closed at `close_vault`.
+ */
+export declare function getAuditLogSuccessPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
+/**
+ * Phase 7 — derive PDA for `AuditLogRejected` at `[b"audit_rejected", vault]`.
+ * Audit #2 F-19 split: keeps rejected-finalize bursts out of the success
+ * buffer's blast radius.
  */
-export declare function getPendingCloseConstraintsPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
+export declare function getAuditLogRejectedPDA(vault: Address, programAddress?: Address): Promise<[Address, number]>;
 export interface ResolveAccountsInput {
     vault: Address;
     agent: Address;
     tokenMint: Address;
     outputMint?: Address;
     feeDestination?: Address;
-    hasConstraints?: boolean;
 }
 export interface ResolvedAccounts {
     vault: Address;
     policyPda: Address;
     trackerPda: Address;
     sessionPda: Address;
-    constraintsPda?: Address;
     agentOverlayPda?: Address;
 }
 /**

package/dist/resolve-accounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-accounts.d.ts","sourceRoot":"","sources":["../src/resolve-accounts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAsB,MAAM,kBAAkB,CAAC;AA8BpE,wBAAsB,WAAW,CAC/B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,EAClB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAW5B;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,YAAY,CAChC,WAAW,EAAE,OAAO,EACpB,gBAAgB,EAAE,OAAO,EACzB,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAW5B;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,MAAU,EACtB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAID,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CA0B3B"}
+{"version":3,"file":"resolve-accounts.d.ts","sourceRoot":"","sources":["../src/resolve-accounts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAsB,MAAM,kBAAkB,CAAC;AAIpE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,WAAW,CAC/B,cAAc,EAAE,OAAO,EACvB,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAU5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,kBAAkB,EACzB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAE5B;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,EAClB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAW5B;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAID,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,MAAU,EACtB,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,OAAO,EACd,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAM5B;AAID,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,GAAE,OAA+B,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CAkB3B"}