@usesigil/kit 0.1.0

package/dist/state-resolver.js

@@ -0,0 +1,660 @@
+/**
+ * StateResolver — L0 foundation for resolving vault state with pre-computed budgets.
+ *
+ * One batched RPC call resolves all vault accounts (AgentVault, PolicyConfig,
+ * SpendTracker, AgentSpendOverlay, InstructionConstraints) and computes
+ * boundary-corrected rolling 24h budgets that exactly mirror the on-chain math.
+ *
+ * Pure functions (getRolling24hUsd, getAgentRolling24hUsd, getProtocolSpend)
+ * are exported independently for unit testing and reuse.
+ */
+import { fetchEncodedAccounts, getAddressDecoder, getAddressEncoder, getU64Decoder, } from "@solana/kit";
+import { decodeAgentSpendOverlay, } from "./generated/accounts/agentSpendOverlay.js";
+import { decodeAgentVault, } from "./generated/accounts/agentVault.js";
+import { decodeInstructionConstraints, } from "./generated/accounts/instructionConstraints.js";
+import { decodePolicyConfig, } from "./generated/accounts/policyConfig.js";
+import { decodeSpendTracker, } from "./generated/accounts/spendTracker.js";
+import { getEscrowDepositDecoder, } from "./generated/accounts/escrowDeposit.js";
+import { getSessionAuthorityDecoder, } from "./generated/accounts/sessionAuthority.js";
+import { fetchMaybePendingPolicyUpdate, } from "./generated/accounts/pendingPolicyUpdate.js";
+import { fetchMaybePendingConstraintsUpdate, } from "./generated/accounts/pendingConstraintsUpdate.js";
+import { getVaultPDA, getPolicyPDA, getTrackerPDA, getAgentOverlayPDA, getConstraintsPDA, getPendingPolicyPDA, getPendingConstraintsPDA, } from "./resolve-accounts.js";
+import { EPOCH_DURATION, NUM_EPOCHS, OVERLAY_EPOCH_DURATION, OVERLAY_NUM_EPOCHS, SIGIL_PROGRAM_ADDRESS, ROLLING_WINDOW_SECONDS, U64_MAX, USDC_MINT_DEVNET, USDC_MINT_MAINNET, USDT_MINT_DEVNET, USDT_MINT_MAINNET, } from "./types.js";
+import { deriveAta } from "./x402/transfer-builder.js";
+import { formatUsd } from "./formatting.js";
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+const addressEncoder = getAddressEncoder();
+const addressDecoder = getAddressDecoder();
+function bytesMatchAddress(bytes, addr) {
+    const encoded = addressEncoder.encode(addr);
+    if (bytes.length !== encoded.length)
+        return false;
+    for (let i = 0; i < 32; i++) {
+        if (bytes[i] !== encoded[i])
+            return false;
+    }
+    return true;
+}
+// ─── Pure Functions ──────────────────────────────────────────────────────────
+/**
+ * Convert a 32-byte ReadonlyUint8Array to a Kit Address.
+ * Uses the same Codama address codec as resolve-accounts.ts.
+ */
+export function bytesToAddress(bytes) {
+    return addressDecoder.decode(bytes);
+}
+/**
+ * Mirror of SpendTracker::get_rolling_24h_usd() from tracker.rs:103-151.
+ *
+ * Iterates all 144 buckets, summing those within the 24h window.
+ * Boundary bucket is proportionally scaled. BigInt division truncates
+ * like Rust integer division.
+ */
+export function getRolling24hUsd(tracker, nowUnix) {
+    if (nowUnix <= 0n)
+        return 0n;
+    const epochDuration = BigInt(EPOCH_DURATION);
+    const numEpochs = BigInt(NUM_EPOCHS);
+    const currentEpoch = nowUnix / epochDuration;
+    // Early exit: if no writes in 144+ epochs, all data is expired
+    if (currentEpoch - tracker.lastWriteEpoch > numEpochs)
+        return 0n;
+    // G-2: Saturating subtraction — avoid negative windowStart when nowUnix < 86400
+    const windowStart = nowUnix > BigInt(ROLLING_WINDOW_SECONDS)
+        ? nowUnix - BigInt(ROLLING_WINDOW_SECONDS)
+        : 0n;
+    let total = 0n;
+    for (const bucket of tracker.buckets) {
+        if (bucket.usdAmount === 0n)
+            continue;
+        const bucketStart = bucket.epochId * epochDuration;
+        const bucketEnd = bucketStart + epochDuration;
+        // Skip if entirely outside window
+        if (bucketEnd <= windowStart || bucket.epochId > currentEpoch)
+            continue;
+        if (bucketStart >= windowStart) {
+            // Fully inside window
+            total += bucket.usdAmount;
+        }
+        else {
+            // Boundary bucket — proportional scaling
+            const overlap = bucketEnd - windowStart;
+            total += (bucket.usdAmount * overlap) / epochDuration;
+        }
+    }
+    // G-1: Clamp to u64::MAX to match on-chain Rust math
+    return total > U64_MAX ? U64_MAX : total;
+}
+/**
+ * Mirror of AgentSpendOverlay::get_agent_rolling_24h_usd() from
+ * agent_spend_overlay.rs:136-199.
+ *
+ * Iterates backward from lastWriteEpoch, summing contributions within
+ * the 24h window. Uses proportional scaling for boundary buckets.
+ */
+export function getAgentRolling24hUsd(entry, nowUnix) {
+    if (nowUnix <= 0n)
+        return 0n;
+    const epochDuration = BigInt(OVERLAY_EPOCH_DURATION);
+    const numEpochs = BigInt(OVERLAY_NUM_EPOCHS);
+    const currentEpoch = nowUnix / epochDuration;
+    // Early exit: if last write was more than 24 epochs ago, all expired
+    if (currentEpoch - entry.lastWriteEpoch > numEpochs)
+        return 0n;
+    // G-2: Saturating subtraction — avoid negative windowStart when nowUnix < 86400
+    const windowStart = nowUnix > BigInt(ROLLING_WINDOW_SECONDS)
+        ? nowUnix - BigInt(ROLLING_WINDOW_SECONDS)
+        : 0n;
+    let total = 0n;
+    // Iterate backward from lastWriteEpoch (most recent data)
+    for (let k = 0; k < OVERLAY_NUM_EPOCHS; k++) {
+        const epochForK = entry.lastWriteEpoch - BigInt(k);
+        if (epochForK < 0n)
+            break;
+        const bucketStart = epochForK * epochDuration;
+        const bucketEnd = bucketStart + epochDuration;
+        // If this bucket ends before the window start, we're done (going backward)
+        if (bucketEnd <= windowStart)
+            break;
+        // If this bucket is in the future, skip it
+        if (epochForK > currentEpoch)
+            continue;
+        const bucketIdx = Number(epochForK % numEpochs);
+        const contribution = entry.contributions[bucketIdx];
+        if (contribution === 0n)
+            continue;
+        if (bucketStart >= windowStart) {
+            // Fully within window
+            total += contribution;
+        }
+        else {
+            // Boundary bucket — proportional scaling
+            const overlap = bucketEnd - windowStart;
+            total += (contribution * overlap) / epochDuration;
+        }
+    }
+    // G-1: Clamp to u64::MAX to match on-chain Rust math
+    return total > U64_MAX ? U64_MAX : total;
+}
+/**
+ * Mirror of SpendTracker::get_protocol_spend() from tracker.rs:155-172.
+ *
+ * Simple 24h window check (NOT rolling boundary-corrected).
+ * Returns the windowSpend if the counter exists and hasn't expired.
+ */
+export function getProtocolSpend(tracker, protocolAddress, nowUnix) {
+    if (nowUnix <= 0n)
+        return 0n;
+    const epochDuration = BigInt(EPOCH_DURATION);
+    const numEpochs = BigInt(NUM_EPOCHS);
+    const currentEpoch = nowUnix / epochDuration;
+    for (const counter of tracker.protocolCounters) {
+        if (bytesMatchAddress(counter.protocol, protocolAddress)) {
+            // Check if window is still valid (< 144 epochs = 24h)
+            if (currentEpoch - counter.windowStart < numEpochs) {
+                return counter.windowSpend;
+            }
+            return 0n; // Window expired
+        }
+    }
+    return 0n; // No counter found
+}
+/**
+ * Convert SpendTracker epoch buckets into a chronologically sorted time-series
+ * for dashboard charts (Recharts area charts, tooltips).
+ *
+ * Mirrors getRolling24hUsd() iteration but outputs individual data points
+ * instead of a sum. Zero-amount epochs are skipped (sparse-friendly).
+ * No proportional boundary scaling — raw epoch amounts for chart display.
+ *
+ * @param tracker - SpendTracker account data (null for vaults with no tracker PDA)
+ * @param nowUnix - Current unix timestamp in seconds
+ * @returns Chronologically sorted SpendingEpoch[] (ascending by timestamp)
+ */
+export function getSpendingHistory(tracker, nowUnix) {
+    if (!tracker || nowUnix <= 0n)
+        return [];
+    const epochDuration = BigInt(EPOCH_DURATION);
+    const numEpochs = BigInt(NUM_EPOCHS);
+    const currentEpoch = nowUnix / epochDuration;
+    // Early exit: if no writes in 144+ epochs, all data is expired
+    if (currentEpoch - tracker.lastWriteEpoch > numEpochs)
+        return [];
+    const windowStartEpoch = currentEpoch - numEpochs;
+    const result = [];
+    for (const bucket of tracker.buckets) {
+        if (bucket.usdAmount === 0n)
+            continue;
+        if (bucket.epochId < windowStartEpoch)
+            continue;
+        if (bucket.epochId > currentEpoch)
+            continue;
+        result.push({
+            epochId: Number(bucket.epochId),
+            timestamp: Number(bucket.epochId * epochDuration),
+            usdAmount: bucket.usdAmount,
+            usdAmountFormatted: formatUsd(bucket.usdAmount),
+        });
+    }
+    // Sort chronologically (circular buffer order ≠ time order)
+    result.sort((a, b) => a.timestamp - b.timestamp);
+    return result;
+}
+// ─── resolveVaultState ───────────────────────────────────────────────────────
+/**
+ * Resolve complete vault state from a single batched RPC call.
+ *
+ * Derives 4 PDAs + 2 stablecoin ATAs, fetches all 7 accounts in one
+ * getMultipleAccounts, decodes, and pre-computes global/agent/protocol
+ * budgets with boundary-corrected rolling 24h math.
+ *
+ * @param network - Optional network for stablecoin mint resolution (defaults to "mainnet-beta")
+ */
+export async function resolveVaultState(rpc, vault, agent, nowUnix, network) {
+    const net = network ?? "mainnet-beta";
+    const usdcMint = net === "devnet" ? USDC_MINT_DEVNET : USDC_MINT_MAINNET;
+    const usdtMint = net === "devnet" ? USDT_MINT_DEVNET : USDT_MINT_MAINNET;
+    // 1. Derive PDAs + stablecoin ATAs in parallel
+    const [[policyPda], [trackerPda], [overlayPda], [constraintsPda], vaultUsdcAta, vaultUsdtAta,] = await Promise.all([
+        getPolicyPDA(vault),
+        getTrackerPDA(vault),
+        getAgentOverlayPDA(vault, 0),
+        getConstraintsPDA(vault),
+        deriveAta(vault, usdcMint),
+        deriveAta(vault, usdtMint),
+    ]);
+    // 2. Single batch fetch (one RPC round-trip — 7 accounts)
+    const encoded = await fetchEncodedAccounts(rpc, [
+        vault,
+        policyPda,
+        trackerPda,
+        overlayPda,
+        constraintsPda,
+        vaultUsdcAta,
+        vaultUsdtAta,
+    ]);
+    // 3. Decode — vault and policy are required, others are optional
+    const decodedVault = decodeAgentVault(encoded[0]);
+    if (!decodedVault.exists) {
+        throw new Error(`Vault account ${vault} does not exist`);
+    }
+    const decodedPolicy = decodePolicyConfig(encoded[1]);
+    if (!decodedPolicy.exists) {
+        throw new Error(`PolicyConfig for vault ${vault} does not exist`);
+    }
+    const decodedTracker = decodeSpendTracker(encoded[2]);
+    const tracker = decodedTracker.exists
+        ? decodedTracker.data
+        : null;
+    const decodedOverlay = decodeAgentSpendOverlay(encoded[3]);
+    const overlay = decodedOverlay.exists
+        ? decodedOverlay.data
+        : null;
+    const decodedConstraints = decodeInstructionConstraints(encoded[4]);
+    const constraints = decodedConstraints.exists
+        ? decodedConstraints.data
+        : null;
+    // 4. Timestamp
+    const timestamp = nowUnix ?? BigInt(Math.floor(Date.now() / 1000));
+    // 5. Global budget
+    const globalSpent = tracker ? getRolling24hUsd(tracker, timestamp) : 0n;
+    const globalCap = decodedPolicy.data.dailySpendingCapUsd;
+    const globalRemaining = globalCap > globalSpent ? globalCap - globalSpent : 0n;
+    const globalBudget = {
+        spent24h: globalSpent,
+        cap: globalCap,
+        remaining: globalRemaining,
+    };
+    // 6. Agent budgets — single pass builds both agentBudget and allAgentBudgets
+    let agentBudget = null;
+    const allAgentBudgets = new Map();
+    for (const entry of decodedVault.data.agents) {
+        if (entry.spendingLimitUsd <= 0n)
+            continue;
+        const entryAddr = entry.pubkey;
+        const cap = entry.spendingLimitUsd;
+        let budget;
+        if (overlay) {
+            const overlayEntry = overlay.entries.find((e) => bytesMatchAddress(e.agent, entryAddr));
+            if (overlayEntry) {
+                const spent = getAgentRolling24hUsd(overlayEntry, timestamp);
+                budget = { spent24h: spent, cap, remaining: cap > spent ? cap - spent : 0n };
+            }
+            else {
+                budget = { spent24h: 0n, cap, remaining: cap };
+            }
+        }
+        else {
+            budget = { spent24h: 0n, cap, remaining: cap };
+        }
+        allAgentBudgets.set(entryAddr, budget);
+        // Kit Address is a branded string — === is correct (always normalized base58)
+        if (entryAddr === agent) {
+            agentBudget = budget;
+        }
+    }
+    // 7. Protocol budgets
+    const protocolBudgets = [];
+    if (decodedPolicy.data.hasProtocolCaps && tracker) {
+        const protocols = decodedPolicy.data.protocols;
+        const caps = decodedPolicy.data.protocolCaps;
+        for (let i = 0; i < protocols.length; i++) {
+            const protocolCap = caps[i];
+            if (protocolCap === undefined || protocolCap === 0n)
+                continue;
+            const protocol = protocols[i];
+            const spent = getProtocolSpend(tracker, protocol, timestamp);
+            protocolBudgets.push({
+                protocol,
+                spent24h: spent,
+                cap: protocolCap,
+                remaining: protocolCap > spent ? protocolCap - spent : 0n,
+            });
+        }
+    }
+    // 8. Parse stablecoin ATA balances (fail-open: 0n if ATA doesn't exist)
+    let usdcBalance = 0n;
+    let usdtBalance = 0n;
+    try {
+        const usdcEncoded = encoded[5];
+        if (usdcEncoded.exists) {
+            const usdcData = usdcEncoded.data;
+            if (usdcData && usdcData.length >= 72) {
+                // SPL Token amount at offset 64 (u64 LE)
+                for (let i = 0; i < 8; i++) {
+                    usdcBalance |= BigInt(usdcData[64 + i]) << BigInt(i * 8);
+                }
+            }
+        }
+    }
+    catch {
+        // Fail-open: ATA may not exist
+    }
+    try {
+        const usdtEncoded = encoded[6];
+        if (usdtEncoded.exists) {
+            const usdtData = usdtEncoded.data;
+            if (usdtData && usdtData.length >= 72) {
+                for (let i = 0; i < 8; i++) {
+                    usdtBalance |= BigInt(usdtData[64 + i]) << BigInt(i * 8);
+                }
+            }
+        }
+    }
+    catch {
+        // Fail-open: ATA may not exist
+    }
+    return {
+        vault: decodedVault.data,
+        policy: decodedPolicy.data,
+        tracker,
+        overlay,
+        constraints,
+        globalBudget,
+        agentBudget,
+        allAgentBudgets,
+        protocolBudgets,
+        maxTransactionUsd: decodedPolicy.data.maxTransactionSizeUsd,
+        stablecoinBalances: { usdc: usdcBalance, usdt: usdtBalance },
+        resolvedAtTimestamp: timestamp,
+    };
+}
+/**
+ * Resolve complete vault state for an owner — returns all agents' budgets
+ * without requiring a specific agent address.
+ *
+ * Delegates to resolveVaultState internally. Agents with spendingLimitUsd = 0
+ * are excluded from allAgentBudgets (matching on-chain behavior where
+ * zero-limit agents have no budget to track).
+ *
+ * @param rpc - Kit RPC client
+ * @param vault - Vault PDA address
+ * @param nowUnix - Optional timestamp override (defaults to Date.now())
+ * @param network - Optional network for stablecoin mint resolution
+ */
+export async function resolveVaultStateForOwner(rpc, vault, nowUnix, network) {
+    // System program address — guaranteed not a vault agent (can't sign),
+    // so agentBudget is always null in the delegated result.
+    const state = await resolveVaultState(rpc, vault, "11111111111111111111111111111111", nowUnix, network);
+    const { agentBudget: _, ...rest } = state;
+    return rest;
+}
+/**
+ * Resolve only global + agent budgets with minimal RPC overhead.
+ *
+ * Fetches 4 accounts (vault, policy, tracker, overlay) instead of 7,
+ * skipping constraints and 2 stablecoin ATAs. Skips protocol budget
+ * computation and constraints decoding (8.3KB zero-copy).
+ * ~40% cheaper than resolveVaultState() for budget-only queries.
+ */
+export async function resolveVaultBudget(rpc, vault, agent, nowUnix) {
+    const [[policyPda], [trackerPda], [overlayPda],] = await Promise.all([
+        getPolicyPDA(vault),
+        getTrackerPDA(vault),
+        getAgentOverlayPDA(vault, 0),
+    ]);
+    const encoded = await fetchEncodedAccounts(rpc, [
+        vault,
+        policyPda,
+        trackerPda,
+        overlayPda,
+    ]);
+    const decodedVault = decodeAgentVault(encoded[0]);
+    if (!decodedVault.exists) {
+        throw new Error(`Vault account ${vault} does not exist`);
+    }
+    const decodedPolicy = decodePolicyConfig(encoded[1]);
+    if (!decodedPolicy.exists) {
+        throw new Error(`PolicyConfig for vault ${vault} does not exist`);
+    }
+    const decodedTracker = decodeSpendTracker(encoded[2]);
+    const tracker = decodedTracker.exists
+        ? decodedTracker.data
+        : null;
+    const decodedOverlay = decodeAgentSpendOverlay(encoded[3]);
+    const overlay = decodedOverlay.exists
+        ? decodedOverlay.data
+        : null;
+    const timestamp = nowUnix ?? BigInt(Math.floor(Date.now() / 1000));
+    // Global budget
+    const globalSpent = tracker ? getRolling24hUsd(tracker, timestamp) : 0n;
+    const globalCap = decodedPolicy.data.dailySpendingCapUsd;
+    const globalRemaining = globalCap > globalSpent ? globalCap - globalSpent : 0n;
+    const globalBudget = {
+        spent24h: globalSpent,
+        cap: globalCap,
+        remaining: globalRemaining,
+    };
+    // Agent budget
+    let agentBudget = null;
+    const agentEntry = decodedVault.data.agents.find((a) => a.pubkey === agent);
+    if (agentEntry && agentEntry.spendingLimitUsd > 0n) {
+        const cap = agentEntry.spendingLimitUsd;
+        if (overlay) {
+            const overlayEntry = overlay.entries.find((e) => bytesMatchAddress(e.agent, agent));
+            if (overlayEntry) {
+                const spent = getAgentRolling24hUsd(overlayEntry, timestamp);
+                agentBudget = { spent24h: spent, cap, remaining: cap > spent ? cap - spent : 0n };
+            }
+            else {
+                agentBudget = { spent24h: 0n, cap, remaining: cap };
+            }
+        }
+        else {
+            agentBudget = { spent24h: 0n, cap, remaining: cap };
+        }
+    }
+    return { globalBudget, agentBudget };
+}
+/** AgentVault account size (bytes) — used for dataSize filter. */
+const AGENT_VAULT_SIZE = 634;
+/** Byte offset of the `vault_id` field in AgentVault (after 8 disc + 32 owner). */
+const VAULT_ID_OFFSET = 40;
+const u64Decoder = getU64Decoder();
+/**
+ * Find all vaults owned by a wallet address.
+ *
+ * Strategy A: getProgramAccounts with memcmp filter (fast, requires RPC support).
+ * Strategy B: Sequential PDA probing fallback (works everywhere, slower).
+ *
+ * @param rpc - Kit RPC client
+ * @param owner - Owner wallet address
+ * @param maxProbe - Maximum vault IDs to probe in fallback (default: 20)
+ * @returns Array of discovered vaults
+ */
+/**
+ * Errors that indicate the RPC doesn't support getProgramAccounts (fall back to probing).
+ *
+ * JSON-RPC error codes (per Solana spec + major RPC providers):
+ * - -32601: Method not found (standard JSON-RPC)
+ * - -32010: Program excluded from account secondary indexes (Solana-specific)
+ * - HTTP 410: Method disabled at proxy level (public RPCs)
+ *
+ * Rate limits (-32005, HTTP 429) and network errors are NOT matched —
+ * they should propagate so callers can retry or surface the issue.
+ */
+function isGpaUnsupportedError(err) {
+    if (!(err instanceof Error))
+        return false;
+    // Check for JSON-RPC error codes (SolanaJSONRPCError or similar)
+    const code = err.code;
+    if (code === -32601 || code === -32010)
+        return true;
+    // Fallback: message-based matching for RPCs that don't set error codes
+    const msg = err.message.toLowerCase();
+    return (msg.includes("method not found") ||
+        msg.includes("not available") ||
+        msg.includes("not supported") ||
+        msg.includes("disabled") ||
+        msg.includes("410"));
+}
+/** Platform-agnostic base64 encode for Uint8Array (no Buffer dependency). */
+function uint8ToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/** Platform-agnostic base64 decode to Uint8Array (no Buffer dependency). */
+function base64ToUint8(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+export async function findVaultsByOwner(rpc, owner, maxProbe = 20) {
+    // Cap maxProbe to prevent excessive PDA derivation (V-3: DoS mitigation)
+    const cappedProbe = Math.min(Math.max(0, maxProbe), 100);
+    const ownerBase64 = uint8ToBase64(addressEncoder.encode(owner));
+    // Strategy A: getProgramAccounts with memcmp filter
+    try {
+        const accounts = await rpc
+            .getProgramAccounts(SIGIL_PROGRAM_ADDRESS, {
+            dataSlice: { offset: VAULT_ID_OFFSET, length: 8 },
+            filters: [
+                { dataSize: BigInt(AGENT_VAULT_SIZE) },
+                { memcmp: { offset: BigInt(8), bytes: ownerBase64, encoding: "base64" } },
+            ],
+            encoding: "base64",
+        })
+            .send();
+        const parsed = accounts.map((entry) => {
+            const raw = base64ToUint8(entry.account.data[0]);
+            const vaultId = u64Decoder.decode(raw);
+            return { vaultAddress: entry.pubkey, vaultId };
+        });
+        // V-1 fix: Re-derive PDAs to verify RPC-returned pubkeys are legitimate vault addresses.
+        // A malicious RPC could return fabricated pubkeys that don't correspond to real vault PDAs.
+        const verified = [];
+        for (const entry of parsed) {
+            const [expectedPda] = await getVaultPDA(owner, entry.vaultId);
+            if (expectedPda === entry.vaultAddress) {
+                verified.push(entry);
+            }
+        }
+        // Sort by vaultId for consistent ordering regardless of RPC response order
+        return verified.sort((a, b) => (a.vaultId < b.vaultId ? -1 : a.vaultId > b.vaultId ? 1 : 0));
+    }
+    catch (err) {
+        // Rate limits must propagate — never fall back to slow probing under rate limit
+        const code = err.code;
+        if (code === -32005 || (err instanceof Error && err.message.includes("429"))) {
+            throw err;
+        }
+        // Only fall back to probing if the RPC doesn't support getProgramAccounts.
+        // Network errors, auth errors should propagate.
+        if (!isGpaUnsupportedError(err)) {
+            throw err;
+        }
+    }
+    // Strategy B: PDA probing fallback — derive all candidate PDAs in parallel
+    const pdas = await Promise.all(Array.from({ length: cappedProbe }, async (_, i) => {
+        const [pda] = await getVaultPDA(owner, BigInt(i));
+        return { address: pda, vaultId: BigInt(i) };
+    }));
+    // Batch fetch via getMultipleAccounts (maxProbe <= 20, well under 100-account limit)
+    const addresses = pdas.map((p) => p.address);
+    const result = await rpc
+        .getMultipleAccounts(addresses, { encoding: "base64" })
+        .send();
+    const discovered = [];
+    for (let i = 0; i < result.value.length; i++) {
+        if (result.value[i] !== null) {
+            discovered.push({
+                vaultAddress: pdas[i].address,
+                vaultId: pdas[i].vaultId,
+            });
+        }
+    }
+    // Already sorted by vaultId (probed sequentially 0..maxProbe)
+    return discovered;
+}
+// ─── Escrow Discovery ──────────────────────────────────────────────────────
+/** Escrow account size (bytes) — used for dataSize filter. */
+const ESCROW_DEPOSIT_SIZE = 170;
+/**
+ * Find all escrow deposits where this vault is the source.
+ * Uses getProgramAccounts with memcmp on source_vault field (offset 8).
+ */
+export async function findEscrowsByVault(rpc, sourceVault) {
+    const vaultBase64 = uint8ToBase64(addressEncoder.encode(sourceVault));
+    try {
+        const accounts = await rpc
+            .getProgramAccounts(SIGIL_PROGRAM_ADDRESS, {
+            filters: [
+                { dataSize: BigInt(ESCROW_DEPOSIT_SIZE) },
+                { memcmp: { offset: BigInt(8), bytes: vaultBase64, encoding: "base64" } },
+            ],
+            encoding: "base64",
+        })
+            .send();
+        // Decode directly from GPA response (avoids double RPC)
+        const decoder = getEscrowDepositDecoder();
+        return accounts.map((entry) => {
+            const raw = base64ToUint8(entry.account.data[0]);
+            const data = decoder.decode(raw);
+            return { ...data, address: entry.pubkey };
+        });
+    }
+    catch (err) {
+        if (!isGpaUnsupportedError(err))
+            throw err;
+        return []; // GPA not supported — return empty
+    }
+}
+// ─── Session Discovery ─────────────────────────────────────────────────────
+/** SessionAuthority account size (bytes). */
+const SESSION_AUTHORITY_SIZE = 244;
+/**
+ * Find all active sessions for a vault.
+ * Uses getProgramAccounts with memcmp on vault field (offset 8).
+ */
+export async function findSessionsByVault(rpc, vault) {
+    const vaultBase64 = uint8ToBase64(addressEncoder.encode(vault));
+    try {
+        const accounts = await rpc
+            .getProgramAccounts(SIGIL_PROGRAM_ADDRESS, {
+            filters: [
+                { dataSize: BigInt(SESSION_AUTHORITY_SIZE) },
+                { memcmp: { offset: BigInt(8), bytes: vaultBase64, encoding: "base64" } },
+            ],
+            encoding: "base64",
+        })
+            .send();
+        // Decode directly from GPA response (avoids double RPC)
+        const decoder = getSessionAuthorityDecoder();
+        return accounts.map((entry) => {
+            const raw = base64ToUint8(entry.account.data[0]);
+            const data = decoder.decode(raw);
+            return { ...data, address: entry.pubkey };
+        });
+    }
+    catch (err) {
+        if (!isGpaUnsupportedError(err))
+            throw err;
+        return []; // GPA not supported — return empty
+    }
+}
+// ─── Pending Update Convenience Wrappers ───────────────────────────────────
+/**
+ * Fetch the pending policy update for a vault, if any.
+ * Returns null if no pending update exists.
+ */
+export async function getPendingPolicyForVault(rpc, vault) {
+    const [pda] = await getPendingPolicyPDA(vault);
+    const result = await fetchMaybePendingPolicyUpdate(rpc, pda);
+    return result.exists ? result.data : null;
+}
+/**
+ * Fetch the pending constraints update for a vault, if any.
+ * Returns null if no pending update exists.
+ */
+export async function getPendingConstraintsForVault(rpc, vault) {
+    const [pda] = await getPendingConstraintsPDA(vault);
+    const result = await fetchMaybePendingConstraintsUpdate(rpc, pda);
+    return result.exists ? result.data : null;
+}
+//# sourceMappingURL=state-resolver.js.map