@eco-incorp/sauce 0.99.0

package/sdk/dist/svm/client.d.ts

@@ -0,0 +1,116 @@
+import type { Address, AddressesByLookupTableAddress, Commitment, Instruction, Signature, TransactionSigner } from "@solana/kit";
+import type { AccountManifest } from "sauce-compiler";
+import type { ArgsLayout, ArgValue } from "./layout.js";
+import type { AccountResolution } from "./resolve.js";
+import type { SendExecuteResult, SimulateExecuteResult } from "./send.js";
+export interface SauceSvmClientConfig {
+    rpcUrl: string;
+    /** Defaults to rpcUrl with the protocol swapped to ws(s). */
+    wsUrl?: string;
+    /** The ENGINE. Named per call rather than compiled in, and still the interpreter that runs — but
+     *  it is no longer what a transaction talks to. */
+    programId: Address;
+    /**
+     * The KITCHEN every execution goes through.
+     *
+     * A released engine refuses any invocation that did not arrive through a kitchen cook, so this is
+     * not optional: without it there is no way to reach the interpreter at all.
+     */
+    kitchen: Address;
+    payer: TransactionSigner;
+    /** Which of the payer's Pots to run as. Defaults to the all-zero salt — the natural "primary". */
+    potSalt?: Uint8Array;
+    /**
+     * What the caller consents to pay per cook, in lamports. Defaults to zero, which succeeds only
+     * while the kitchen is priced at zero — a kitchen with a positive fee refuses, rather than
+     * silently spending the payer's SOL on a quote they never saw.
+     */
+    maxExecutionFee?: bigint;
+}
+export interface SimulateOpts {
+    prepends?: readonly Instruction[];
+    lookupTables?: AddressesByLookupTableAddress;
+    /**
+     * Append the fee payer as an in-list readonly signer when the manifest yields no
+     * signer meta. Needed ONLY for programs that read MSG_SENDER/TX_ORIGIN —
+     * NoSigner is lazy, so everything else runs (and simulates) signerless.
+     */
+    appendPayerSigner?: boolean;
+}
+export interface ExecuteOpts extends SimulateOpts {
+    /** 'auto' simulates first and applies recommendedComputeUnitLimit (x1.2, capped 1.4M). */
+    computeUnitLimit?: number | "auto";
+}
+/** A buffer staged by this client — carries the SDK-computed content hash (the execute pin). */
+export interface StagedBuffer {
+    address: Address;
+    /** The 32-byte PDA seed the buffer was derived + init'd under. */
+    seed: Uint8Array;
+    /** sha256 of the staged bytecode, computed SDK-side and verified on-chain at finalize. */
+    sha256: Uint8Array;
+    /** Staging transaction signatures in send order: init, writes…, finalize. */
+    signatures: Signature[];
+}
+/** Per-execution args for a staged program. The layout is CALLER-SUPPLIED: neither `CompileResult`
+ *  carries one — the compiler's is `{ bytecode, manifest? }`, the route seam's is
+ *  `{ bytecode: Uint8Array[], warnings }` — so `ArgsLayout` is the SDK's own type (`./layout.ts`)
+ *  describing where each value sits in the payload tail. */
+export interface StagedArgs {
+    layout: ArgsLayout;
+    values: readonly ArgValue[];
+}
+export interface SimulateStagedOpts extends SimulateOpts {
+    /**
+     * REJECTED, not enforced. Passing this THROWS.
+     *
+     * `execute_from_account` on the released engine takes no payload, so this was being forwarded
+     * and then dropped while documented as an applied pin. The enforceable content pin is the
+     * kitchen's, given to `buildFinalizeCodeBufferInstruction` when the buffer is finalized.
+     */
+    expectedSha256?: Uint8Array;
+}
+export interface ExecuteStagedOpts extends SimulateStagedOpts {
+    computeUnitLimit?: number | "auto";
+}
+/** An address lookup table this client created/extended, ready to compress a v0 transaction against. */
+export interface EnsuredLookupTable {
+    lookupTableAddress: Address;
+    /** The shape `executeStaged`/`simulate`'s `lookupTables` option consumes (table → its addresses). */
+    lookupTables: AddressesByLookupTableAddress;
+}
+export interface EnsureLookupTableOpts {
+    /**
+     * Reuse and EXTEND this table instead of creating a fresh one: the addresses
+     * already in it are diffed out and only the missing ones are appended (an
+     * all-present set sends nothing) — the idempotent per-universe reuse path.
+     */
+    existing?: Address;
+    commitment?: Commitment;
+}
+export interface SauceSvmClient {
+    /** Fee-payer / lookup-table authority public key — the ALT-address selection excludes it (signers cannot be looked up). */
+    readonly payerAddress: Address;
+    /**
+     * Creates (or, with `opts.existing`, extends) an address lookup table over
+     * `addresses`, waits for it to warm up, and returns it in the shape the
+     * execute/simulate `lookupTables` option consumes. Signers must NOT be in
+     * `addresses` — they have to stay static message accounts. Idempotent on the
+     * existing path: an already-covering table sends no transactions. A set that
+     * would take the table past LOOKUP_TABLE_MAX_ADDRESSES throws before any
+     * transaction is sent — a partially-extended table cannot be un-funded.
+     */
+    ensureLookupTable(addresses: readonly Address[], opts?: EnsureLookupTableOpts): Promise<EnsuredLookupTable>;
+    simulate(bytecode: Uint8Array, manifest: AccountManifest, resolution: AccountResolution, opts?: SimulateOpts): Promise<SimulateExecuteResult>;
+    execute(bytecode: Uint8Array, manifest: AccountManifest, resolution: AccountResolution, opts?: ExecuteOpts): Promise<SendExecuteResult>;
+    simulateStaged(buffer: Address | StagedBuffer, manifest: AccountManifest, resolution: AccountResolution, opts?: SimulateStagedOpts): Promise<SimulateExecuteResult>;
+    /**
+     * Executes a finalized buffer, hash-pinned, in ONE instruction. With `args`,
+     * the per-execution values are encoded into the instruction payload
+     * (encodePayloadArgs) after the flags byte and pin — the staged program
+     * reads them through its CALLDATA prologue, so one staged buffer serves
+     * every argument set without restaging.
+     */
+    executeStaged(buffer: Address | StagedBuffer, manifest: AccountManifest, resolution: AccountResolution, opts?: ExecuteStagedOpts): Promise<SendExecuteResult>;
+}
+export declare function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen, payer, potSalt, maxExecutionFee, }: SauceSvmClientConfig): Promise<SauceSvmClient>;
+//# sourceMappingURL=client.d.ts.map

package/sdk/dist/svm/client.d.ts.map

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

package/sdk/dist/svm/client.js

@@ -0,0 +1,161 @@
+import { createSolanaRpc, createSolanaRpcSubscriptions, sendAndConfirmTransactionFactory, } from "@solana/kit";
+import { LOOKUP_TABLE_MAX_ADDRESSES, createAltWithAddresses, extendAlt, fetchAlt, waitForAltActive, } from "./alt.js";
+import { assertNoExecutePin } from "./instructions.js";
+import { buildComputeBudgetPrepend, buildHeapFramePrepend } from "./prepends.js";
+import { resolveAccounts } from "./resolve.js";
+import { buildCookFromAccountInstruction, buildCookInstruction, deriveCodePda, deriveExecutionFeeConfigPda, derivePotPda, } from "./kitchen.js";
+import { recommendedComputeUnitLimit, sendExecute, simulateExecute } from "./send.js";
+import { buildExecuteTransaction } from "./transaction.js";
+export async function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen, payer, potSalt = new Uint8Array(32), maxExecutionFee = 0n, }) {
+    const rpc = createSolanaRpc(rpcUrl);
+    const rpcSubscriptions = createSolanaRpcSubscriptions(wsUrl ?? rpcUrl.replace(/^http/, "ws"));
+    // Derived once: both are pure functions of the kitchen and the payer, and a cook names them on
+    // every call.
+    const { address: pot } = await derivePotPda(kitchen, payer.address, potSalt);
+    const { address: feeConfig } = await deriveExecutionFeeConfigPda(kitchen);
+    /**
+     * Signs an execute transaction: RequestHeapFrame(262144) FIRST (required on
+     * every execute/simulate; add-once — caller prepends must not carry their
+     * own), then the prepends, then the execute instruction.
+     */
+    async function signExecuteTransaction(executeInstruction, prepends, lookupTables) {
+        const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+        return buildExecuteTransaction({
+            payer,
+            instructions: [buildHeapFramePrepend(), ...prepends, executeInstruction],
+            latestBlockhash,
+            lookupTables,
+        });
+    }
+    async function buildTransaction(bytecode, manifest, resolution, prepends, opts) {
+        const accounts = resolveAccounts(manifest, resolution, payer.address, {
+            appendPayerSigner: opts.appendPayerSigner,
+        });
+        const executeInstruction = buildCookInstruction({
+            kitchen,
+            owner: payer.address,
+            engineProgram: programId,
+            potSalt,
+            pot,
+            feeConfig,
+            bytecode,
+            maxExecutionFee,
+            tail: accounts,
+        });
+        return signExecuteTransaction(executeInstruction, prepends, opts.lookupTables);
+    }
+    async function simulate(bytecode, manifest, resolution, opts = {}) {
+        const transaction = await buildTransaction(bytecode, manifest, resolution, opts.prepends ?? [], opts);
+        return simulateExecute(rpc, transaction);
+    }
+    async function buildStagedTransaction(buffer, manifest, resolution, prepends, opts) {
+        const address = typeof buffer === "string" ? buffer : buffer.address;
+        const accounts = resolveAccounts(manifest, resolution, payer.address, {
+            appendPayerSigner: opts.appendPayerSigner,
+        });
+        assertNoExecutePin(opts.expectedSha256);
+        const { address: code } = await deriveCodePda(kitchen, address);
+        const executeInstruction = buildCookFromAccountInstruction({
+            kitchen,
+            owner: payer.address,
+            codeBuffer: address,
+            code,
+            engineProgram: programId,
+            potSalt,
+            pot,
+            feeConfig,
+            maxExecutionFee,
+            tail: accounts,
+        });
+        return signExecuteTransaction(executeInstruction, prepends, opts.lookupTables);
+    }
+    async function simulateStaged(buffer, manifest, resolution, opts = {}) {
+        const transaction = await buildStagedTransaction(buffer, manifest, resolution, opts.prepends ?? [], opts);
+        return simulateExecute(rpc, transaction);
+    }
+    async function autoComputeUnitPrepends(simulateRun, opts) {
+        let unitLimit;
+        if (opts.computeUnitLimit === "auto") {
+            const sim = await simulateRun();
+            if (!sim.ok || sim.unitsConsumed === undefined) {
+                throw new Error(`compute unit auto-limit simulation failed: ${JSON.stringify(sim.err) ?? "no units consumed"}`);
+            }
+            unitLimit = recommendedComputeUnitLimit(sim.unitsConsumed);
+        }
+        else {
+            unitLimit = opts.computeUnitLimit;
+        }
+        return [
+            ...(unitLimit !== undefined ? buildComputeBudgetPrepend({ unitLimit }) : []),
+            ...(opts.prepends ?? []),
+        ];
+    }
+    const sendAndConfirmAlt = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
+    async function ensureLookupTable(addresses, opts = {}) {
+        if (addresses.length === 0) {
+            throw new Error("ensureLookupTable needs at least one address (a lookup table cannot be empty)");
+        }
+        const commitment = opts.commitment ?? "confirmed";
+        const deduped = [...new Set(addresses)];
+        if (opts.existing !== undefined) {
+            const current = (await fetchAlt(rpc, opts.existing))[opts.existing] ?? [];
+            const have = new Set(current);
+            const missing = deduped.filter((address) => !have.has(address));
+            if (current.length + missing.length > LOOKUP_TABLE_MAX_ADDRESSES) {
+                throw new Error(`lookup table ${opts.existing} holds ${current.length} addresses and cannot take ${missing.length} more: one table holds at most ${LOOKUP_TABLE_MAX_ADDRESSES}`);
+            }
+            if (missing.length > 0) {
+                const { lastExtendedSlot } = await extendAlt({
+                    rpc,
+                    payer,
+                    authority: payer,
+                    lookupTableAddress: opts.existing,
+                    addresses: missing,
+                    sendAndConfirm: sendAndConfirmAlt,
+                    commitment,
+                });
+                await waitForAltActive(rpc, lastExtendedSlot);
+            }
+            return {
+                lookupTableAddress: opts.existing,
+                lookupTables: await fetchAlt(rpc, opts.existing),
+            };
+        }
+        const { lookupTableAddress, lastExtendedSlot } = await createAltWithAddresses({
+            rpc,
+            payer,
+            authority: payer,
+            addresses: deduped,
+            sendAndConfirm: sendAndConfirmAlt,
+            commitment,
+        });
+        await waitForAltActive(rpc, lastExtendedSlot);
+        return { lookupTableAddress, lookupTables: await fetchAlt(rpc, lookupTableAddress) };
+    }
+    return {
+        payerAddress: payer.address,
+        ensureLookupTable,
+        simulate,
+        async execute(bytecode, manifest, resolution, opts = {}) {
+            const prepends = await autoComputeUnitPrepends(() => simulate(bytecode, manifest, resolution, {
+                prepends: opts.prepends,
+                lookupTables: opts.lookupTables,
+                appendPayerSigner: opts.appendPayerSigner,
+            }), opts);
+            const transaction = await buildTransaction(bytecode, manifest, resolution, prepends, opts);
+            return sendExecute({ rpc, rpcSubscriptions, transaction });
+        },
+        simulateStaged,
+        async executeStaged(buffer, manifest, resolution, opts = {}) {
+            const prepends = await autoComputeUnitPrepends(() => simulateStaged(buffer, manifest, resolution, {
+                prepends: opts.prepends,
+                lookupTables: opts.lookupTables,
+                appendPayerSigner: opts.appendPayerSigner,
+                expectedSha256: opts.expectedSha256,
+            }), opts);
+            const transaction = await buildStagedTransaction(buffer, manifest, resolution, prepends, opts);
+            return sendExecute({ rpc, rpcSubscriptions, transaction });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/sdk/dist/svm/client.js.map

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

package/sdk/dist/svm/clusters.d.ts

@@ -0,0 +1,12 @@
+import type { Address } from "@solana/kit";
+/** Solana cluster definition (parallel to the EVM `Chain` registry in chains/). */
+export interface SolanaCluster {
+    cluster: "mainnet-beta" | "devnet" | "localnet";
+    /** Synthetic chain id reported by the engine's CHAIN_ID opcode on this cluster. */
+    engineChainId: bigint;
+    rpcUrl?: string;
+    /** No engine deployment exists yet — callers supply the program id, matching the repo convention. */
+    engineProgramId?: Address;
+}
+export declare const SOLANA_CLUSTERS: Record<SolanaCluster["cluster"], SolanaCluster>;
+//# sourceMappingURL=clusters.d.ts.map

package/sdk/dist/svm/clusters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusters.d.ts","sourceRoot":"","sources":["../../src/svm/clusters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,GAAG,QAAQ,GAAG,UAAU,CAAC;IAChD,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,aAAa,CAe3E,CAAC"}

package/sdk/dist/svm/clusters.js

@@ -0,0 +1,18 @@
+import { ENGINE_CHAIN_IDS } from "./engine.js";
+export const SOLANA_CLUSTERS = {
+    "mainnet-beta": {
+        cluster: "mainnet-beta",
+        engineChainId: ENGINE_CHAIN_IDS.mainnet,
+        rpcUrl: "https://api.mainnet-beta.solana.com",
+    },
+    devnet: {
+        cluster: "devnet",
+        engineChainId: ENGINE_CHAIN_IDS.devnet,
+        rpcUrl: "https://api.devnet.solana.com",
+    },
+    localnet: {
+        cluster: "localnet",
+        engineChainId: ENGINE_CHAIN_IDS.devnet,
+    },
+};
+//# sourceMappingURL=clusters.js.map

package/sdk/dist/svm/clusters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusters.js","sourceRoot":"","sources":["../../src/svm/clusters.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAY/C,MAAM,CAAC,MAAM,eAAe,GAAoD;IAC9E,cAAc,EAAE;QACd,OAAO,EAAE,cAAc;QACvB,aAAa,EAAE,gBAAgB,CAAC,OAAO;QACvC,MAAM,EAAE,qCAAqC;KAC9C;IACD,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ;QACjB,aAAa,EAAE,gBAAgB,CAAC,MAAM;QACtC,MAAM,EAAE,+BAA+B;KACxC;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,UAAU;QACnB,aAAa,EAAE,gBAAgB,CAAC,MAAM;KACvC;CACF,CAAC"}

package/sdk/dist/svm/cpi-probe.d.ts

@@ -0,0 +1,84 @@
+import type { Address, GetAccountInfoApi, Instruction, Rpc, SimulateTransactionApi, TransactionSigner } from "@solana/kit";
+/** The instructions sysvar — its presence in a swap's account list = introspection. */
+export declare const INSTRUCTIONS_SYSVAR: Address;
+/** Prop-AMM integrability tier (see the module doc + docs/svm-venues.md). */
+export type CpiTier = "P-A" | "P-B" | "P-C";
+/** One account of a venue swap, for the static screen (address + signer flag). */
+export interface ScreenAccount {
+    address?: Address;
+    signer?: boolean;
+}
+export interface StaticScreenInput {
+    /** The venue swap's ordered accounts. */
+    accounts: readonly ScreenAccount[];
+    /** The user's own signer (owner) — the ONLY permitted signer; others are gating candidates. */
+    userSigner?: Address;
+}
+export interface StaticScreen {
+    /** The Instructions sysvar rides the account list ⇒ the swap introspects. */
+    introspects: boolean;
+    /** Signer accounts that are NOT the user (maker seats / oracle writers). */
+    foreignSigners: Address[];
+    /** P-C when introspecting or foreign-signed; else P-A candidate (needs the sim to confirm). */
+    candidateTier: "P-A" | "P-C";
+    /** Human-readable reasons feeding the ledger. */
+    reasons: string[];
+}
+/**
+ * The free static screen over a swap's account list. `introspects` /
+ * foreign-signer ⇒ hard P-C candidate; otherwise the pool is a P-A candidate
+ * that the unrecognized-caller simulation confirms.
+ */
+export declare function staticCpiScreen(input: StaticScreenInput): StaticScreen;
+/** ACCEPT / REJECT / DEGRADE / UNKNOWN — the simulation verdict. */
+export type CpiVerdict = "accept" | "reject" | "degrade" | "unknown";
+export interface AcceptanceProbeInput {
+    rpc: Rpc<SimulateTransactionApi & GetAccountInfoApi>;
+    /** The venue swap ix, built as an UNRECOGNIZED caller would send it (tiny input, minOut=1). */
+    swapIx: Instruction;
+    /** Fee payer / signer (signature not verified — sigVerify:false). */
+    payer: TransactionSigner;
+    /** The scratch out-ATA the swap credits — the probe reads its delta. */
+    outAta: Address;
+    /**
+     * The venue's own off-chain quote for the probe size (e.g. referenceQuote).
+     * When given, a realized delta materially below it is DEGRADE (adverse fill
+     * for unrecognized flow).
+     */
+    expectedOut?: bigint;
+    /** DEGRADE threshold in bps: delta < expectedOut·(1 − bps/1e4) ⇒ degrade. Default 500 (5%). */
+    degradeBps?: number;
+}
+export interface AcceptanceProbe {
+    verdict: CpiVerdict;
+    /** The out-ATA balance delta from the simulation (0 on reject). */
+    delta: bigint;
+    /** CU consumed by the simulated CPI (feeds the budgeter). */
+    cu?: bigint;
+    /** Error / log evidence. */
+    detail?: string;
+}
+/**
+ * Runs the unrecognized-caller simulation and classifies the venue. Never
+ * lands a swap; on any simulation error it returns `reject` with the error
+ * detail (a gated program refuses the arbitrary caller). ACCEPT/DEGRADE split
+ * on `expectedOut` when supplied.
+ */
+export declare function probeCpiAcceptance(input: AcceptanceProbeInput): Promise<AcceptanceProbe>;
+export interface VenueClassification {
+    tier: CpiTier;
+    reasons: string[];
+    /** True iff a P-C venue may still be quoted through the off-chain simulation best-scan lane. */
+    externalScanEligible: boolean;
+}
+/**
+ * Combine the static screen with an optional simulation verdict into the final
+ * tier. Introspection is decisive P-C. Otherwise ACCEPT ⇒ P-A (public/readable
+ * oracle) or P-B (proprietary internal oracle located empirically — the caller
+ * distinguishes via `internalOracle`); REJECT/DEGRADE ⇒ P-C. Without a sim
+ * verdict the static candidate stands (a P-A candidate stays provisional).
+ */
+export declare function classifyVenue(screen: StaticScreen, probe?: AcceptanceProbe, opts?: {
+    internalOracle?: boolean;
+}): VenueClassification;
+//# sourceMappingURL=cpi-probe.d.ts.map

package/sdk/dist/svm/cpi-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpi-probe.d.ts","sourceRoot":"","sources":["../../src/svm/cpi-probe.ts"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EACV,OAAO,EAEP,iBAAiB,EACjB,WAAW,EACX,GAAG,EACH,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAGrB,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAoD,OAAO,CAAC;AAE5F,6EAA6E;AAC7E,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5C,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,+FAA+F;IAC/F,aAAa,EAAE,KAAK,GAAG,KAAK,CAAC;IAC7B,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAoBtE;AAED,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,GAAG,CAAC,sBAAsB,GAAG,iBAAiB,CAAC,CAAC;IACrD,+FAA+F;IAC/F,MAAM,EAAE,WAAW,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,iBAAiB,CAAC;IACzB,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,UAAU,CAAC;IACpB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CA2D9F;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gGAAgG;IAChG,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,eAAe,EACvB,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,mBAAmB,CA+BrB"}

package/sdk/dist/svm/cpi-probe.js

@@ -0,0 +1,175 @@
+/**
+ * CPI-acceptance probe — a prepare-time classifier that sorts a venue into the
+ * prop-AMM tiers P-A / P-B / P-C BEFORE any adapter effort or admission (the
+ * SVM analog of the EVM Metric/Tessera probing discipline). It never lands a
+ * swap.
+ *
+ * The problem: every Solana prop-AMM integrates with aggregators via a
+ * PERMISSIONED off-chain quote SDK, which says NOTHING about whether the swap
+ * program accepts a CPI from an arbitrary caller (the engine's `CALL`). Two
+ * signals answer that:
+ *
+ *  1. STATIC SCREEN (free, from the swap's account list): the presence of the
+ *     Instructions sysvar (`Sysvar1nstructions…`) means the program
+ *     introspects the enclosing transaction (router-path / anti-sandwich /
+ *     caller gating) ⇒ CPI-hostile (candidate P-C). A signer other than the
+ *     user (a maker seat, an oracle writer) is likewise a gating candidate.
+ *     NEITHER verdict is definitive — step 2 decides. `PRESENT` is a P-C
+ *     *candidate*, not a hard signal: a program can read the sysvar to price a
+ *     caller **fee tier** rather than to reject, in which case an unrecognized
+ *     caller's CPI succeeds and merely pays the worst tier (measured on ZeroFi
+ *     — see docs/svm-venues.md). `absent` is likewise
+ *     necessary-but-not-sufficient.
+ *
+ *  2. UNRECOGNIZED-CALLER SIMULATION (the definitive test): build the venue
+ *     swap ix from an address the venue has never seen (wrapped in a non-router
+ *     caller — here, `simulateTransaction` with `sigVerify:false` +
+ *     `replaceRecentBlockhash`, the same lane as quoteSim.ts), a tiny input,
+ *     `minOut=1`, funded scratch out-ATA. Classify by the out-ATA delta:
+ *       ACCEPT  — success, delta > 0                         → P-A/P-B
+ *       REJECT  — custom error / caller/owner/missing-acct   → P-C
+ *       DEGRADE — success but delta materially below the     → P-C-with-penalty
+ *                 venue's own quote for the size (adverse       (external lane only)
+ *                 fill for "unrecognized" flow)
+ *
+ * The terminal realized-delta `minOut` on the out-ATA backstops ALL tiers
+ * regardless of the verdict — the probe only decides ADMISSION (does a slot
+ * enter the in-VM split, or stay an off-chain best-scan candidate, or drop).
+ * See docs/svm-venues.md for the ranked ledger and per-venue evidence.
+ */
+import { appendTransactionMessageInstructions, createTransactionMessage, getBase64EncodedWireTransaction, getBase64Encoder, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from "@solana/kit";
+import { readUintLE } from "./venues/math.js";
+/** The instructions sysvar — its presence in a swap's account list = introspection. */
+export const INSTRUCTIONS_SYSVAR = "Sysvar1nstructions1111111111111111111111111";
+/**
+ * The free static screen over a swap's account list. `introspects` /
+ * foreign-signer ⇒ hard P-C candidate; otherwise the pool is a P-A candidate
+ * that the unrecognized-caller simulation confirms.
+ */
+export function staticCpiScreen(input) {
+    const reasons = [];
+    let introspects = false;
+    const foreignSigners = [];
+    for (const account of input.accounts) {
+        if (account.address === INSTRUCTIONS_SYSVAR) {
+            introspects = true;
+            reasons.push("carries the Instructions sysvar (transaction introspection)");
+        }
+        if (account.signer && account.address !== undefined && account.address !== input.userSigner) {
+            foreignSigners.push(account.address);
+            reasons.push(`requires a non-user signer ${account.address} (maker seat / oracle writer)`);
+        }
+    }
+    const candidateTier = introspects || foreignSigners.length > 0 ? "P-C" : "P-A";
+    if (candidateTier === "P-A")
+        reasons.push("no introspection, no foreign signer — P-A candidate (confirm with the simulation probe)");
+    return { introspects, foreignSigners, candidateTier, reasons };
+}
+const TOKEN_AMOUNT_OFFSET = 64;
+const TOKEN_ACCOUNT_MIN_LENGTH = TOKEN_AMOUNT_OFFSET + 8;
+const PLACEHOLDER_BLOCKHASH = {
+    blockhash: "11111111111111111111111111111111",
+    lastValidBlockHeight: 0n,
+};
+function decodeBase64(data) {
+    return new Uint8Array(getBase64Encoder().encode(data));
+}
+function tokenAmount(data) {
+    if (data.length < TOKEN_ACCOUNT_MIN_LENGTH)
+        return null;
+    return readUintLE(data, TOKEN_AMOUNT_OFFSET, 8);
+}
+/**
+ * Runs the unrecognized-caller simulation and classifies the venue. Never
+ * lands a swap; on any simulation error it returns `reject` with the error
+ * detail (a gated program refuses the arbitrary caller). ACCEPT/DEGRADE split
+ * on `expectedOut` when supplied.
+ */
+export async function probeCpiAcceptance(input) {
+    const { value: preAccount } = await input.rpc
+        .getAccountInfo(input.outAta, { encoding: "base64" })
+        .send();
+    const preAmount = preAccount === null ? 0n : (tokenAmount(decodeBase64(preAccount.data[0])) ?? 0n);
+    const message = pipe(createTransactionMessage({ version: 0 }), (m) => setTransactionMessageFeePayerSigner(input.payer, m), (m) => appendTransactionMessageInstructions([input.swapIx], m), (m) => setTransactionMessageLifetimeUsingBlockhash(PLACEHOLDER_BLOCKHASH, m));
+    const transaction = await signTransactionMessageWithSigners(message);
+    const { value } = await input.rpc
+        .simulateTransaction(getBase64EncodedWireTransaction(transaction), {
+        encoding: "base64",
+        replaceRecentBlockhash: true,
+        accounts: { encoding: "base64", addresses: [input.outAta] },
+    })
+        .send();
+    const cu = value.unitsConsumed === undefined || value.unitsConsumed === null
+        ? undefined
+        : BigInt(value.unitsConsumed);
+    if (value.err !== null) {
+        // A rejecting program surfaces a custom error / a caller/owner/missing-acct
+        // failure — the definitive P-C signal.
+        return {
+            verdict: "reject",
+            delta: 0n,
+            cu,
+            detail: `${JSON.stringify(value.err)}${value.logs ? `\n${value.logs.join("\n")}` : ""}`,
+        };
+    }
+    const postAccount = value.accounts?.[0];
+    const postAmount = postAccount === null || postAccount === undefined
+        ? preAmount
+        : (tokenAmount(decodeBase64(postAccount.data[0])) ?? preAmount);
+    const delta = postAmount - preAmount;
+    if (delta <= 0n)
+        return { verdict: "reject", delta, cu, detail: "swap simulated but credited no output" };
+    if (input.expectedOut !== undefined && input.expectedOut > 0n) {
+        const bps = BigInt(input.degradeBps ?? 500);
+        const floor = input.expectedOut - (input.expectedOut * bps) / 10000n;
+        if (delta < floor) {
+            return {
+                verdict: "degrade",
+                delta,
+                cu,
+                detail: `delta ${delta} < expected ${input.expectedOut} − ${bps}bps (adverse fill for unrecognized flow)`,
+            };
+        }
+    }
+    return { verdict: "accept", delta, cu };
+}
+/**
+ * Combine the static screen with an optional simulation verdict into the final
+ * tier. Introspection is decisive P-C. Otherwise ACCEPT ⇒ P-A (public/readable
+ * oracle) or P-B (proprietary internal oracle located empirically — the caller
+ * distinguishes via `internalOracle`); REJECT/DEGRADE ⇒ P-C. Without a sim
+ * verdict the static candidate stands (a P-A candidate stays provisional).
+ */
+export function classifyVenue(screen, probe, opts = {}) {
+    if (screen.candidateTier === "P-C") {
+        return {
+            tier: "P-C",
+            reasons: screen.reasons,
+            externalScanEligible: probe?.verdict === "accept",
+        };
+    }
+    if (probe === undefined) {
+        return {
+            tier: opts.internalOracle ? "P-B" : "P-A",
+            reasons: [...screen.reasons, "no simulation verdict — provisional"],
+            externalScanEligible: true,
+        };
+    }
+    if (probe.verdict === "accept") {
+        const tier = opts.internalOracle ? "P-B" : "P-A";
+        return {
+            tier,
+            reasons: [
+                ...screen.reasons,
+                `simulation ACCEPT (delta ${probe.delta}${probe.cu ? `, ${probe.cu} CU` : ""})`,
+            ],
+            externalScanEligible: true,
+        };
+    }
+    const reasons = [
+        ...screen.reasons,
+        `simulation ${probe.verdict.toUpperCase()}${probe.detail ? `: ${probe.detail}` : ""}`,
+    ];
+    return { tier: "P-C", reasons, externalScanEligible: probe.verdict === "degrade" };
+}
+//# sourceMappingURL=cpi-probe.js.map

package/sdk/dist/svm/cpi-probe.js.map

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

package/sdk/dist/svm/engine-artifacts.d.ts

@@ -0,0 +1,17 @@
+export type EngineCluster = "devnet" | "mainnet";
+/** Directory holding the packaged SVM binaries, resolved relative to this compiled module. */
+export declare const SVM_ARTIFACTS_DIR: string;
+/** Absolute path to the packaged engine `.so` for a cluster (default `devnet`). Throws if absent. */
+export declare function svmEnginePath(cluster?: EngineCluster): string;
+/** Absolute path to the packaged kitchen program `.so`. Throws if absent. */
+export declare function svmKitchenPath(): string;
+/** Absolute path to the packaged kitchen Anchor IDL JSON. Throws if absent. */
+export declare function svmKitchenIdlPath(): string;
+/** The full packaged set a local LiteSVM harness needs to run a kitchen-gated cook. Throws if any
+ *  piece is absent, so a caller gets one clear error rather than a partial set. */
+export declare function svmEngineArtifacts(cluster?: EngineCluster): {
+    engineSo: string;
+    kitchenSo: string;
+    kitchenIdlJson: string;
+};
+//# sourceMappingURL=engine-artifacts.d.ts.map

package/sdk/dist/svm/engine-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-artifacts.d.ts","sourceRoot":"","sources":["../../src/svm/engine-artifacts.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAK7B,CAAC;AAcF,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,OAAO,GAAE,aAAwB,GAAG,MAAM,CAOvE;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;mFACmF;AACnF,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,aAAwB,GAAG;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB,CAMA"}