svm: Settle verification

@eco-incorp/sauce/svm is the Solana side: the client (createSauceSvmClient), clusters, PDAs, account resolution against the compiler’s account manifest, Kitchen and engine instructions, transactions and sending, token accounts, and compute planning for @sauce/router’s Solana venues. @eco-incorp/sauce/svm/engine exports the engine’s wire format and instruction builders, @eco-incorp/sauce/svm/verify verifies settle programs and engine CPI data, and @eco-incorp/sauce/svm/engine-artifacts (Node only) returns file paths to the packaged engine and Kitchen binaries.

import { createSauceSvmClient, SOLANA_CLUSTERS } from "@eco-incorp/sauce/svm";

Generated from the type declarations of @eco-incorp/sauce.

`verifySvmSettleProgram`

Function · @eco-incorp/sauce/svm/verify Verifies a compiled SVM settle program is genuine AND enforces expected - the SVM analogue of the EVM check, done by recompile. It:

takes the escrow count N (or infers it from the manifest’s 3N + 3 slots),
recompiles svmSettleSource(N) with expected as defines, and
byte-compares the result, and asserts the manifest’s slot names equal svmSettleRefs(N).

A genuine result means the bytecode IS the reusable settle logic for N escrows, compiled for exactly this floor and this split - all three are the same bytes, so one comparison pins them all. The resolved account identities (from the executed instruction) remain the caller’s own check. Never throws for a non-genuine program; returns { genuine: false, mismatch }.

export declare function verifySvmSettleProgram(bytecode: Uint8Array, manifest: SettleManifestLike, expected: SvmSettleExpectation): SvmSettleVerification;

`decodeSvmSettleExecution`

Function · @eco-incorp/sauce/svm/verify Decode the released engine’s 65-byte gate header and full CPI account list. This inspects bytes and positions; it authenticates neither execution nor account roles. A Kitchen instruction has a different layout and must be decoded separately.

export declare function decodeSvmSettleExecution(input: SvmSettleExecutionInput): DecodedSvmSettleExecution;

`verifySvmSettleExecution`

Function · @eco-incorp/sauce/svm/verify Compare inline bytes, or caller-supplied staged bytes/pin, with a canonical recompile. This does not check the callee, gate derivation/signature, account roles, or transaction success. Engine calldata has no staged content pin; the caller must connect its pin to the code account.

export declare function verifySvmSettleExecution(input: SvmSettleExecutionVerifyInput): SvmSettleExecutionVerification;

`SvmSettleExpectation`

Interface · @eco-incorp/sauce/svm/verify The values a settle program was compiled with. Both are folded into the bytecode, so they are what a recompile pins: naming them is how a caller says “prove the program enforces THIS floor and THIS split”, rather than reading them back out of an execution and trusting them.

export interface SvmSettleExpectation {
    minOut: bigint;
    splCount: bigint;
}

`SettleManifestLike`

Interface · @eco-incorp/sauce/svm/verify Just enough of an account manifest to count and name its slots.

export interface SettleManifestLike {
    accounts: readonly {
        kind: string;
        name?: string;
    }[];
}

`SvmSettleVerification`

Interface · @eco-incorp/sauce/svm/verify

export interface SvmSettleVerification {
    genuine: boolean;
    escrowCount: number | null;
    refs: string[];
    mismatch?: string;
}

`SvmExecutionWireFormat`

Type · @eco-incorp/sauce/svm/verify Released engine CPI wire, or an explicitly selected pre-gate inspection format.

export type SvmExecutionWireFormat = "gated-v1" | "legacy-ungated";

`SvmSettleAccountLike`

Type · @eco-incorp/sauce/svm/verify

export type SvmSettleAccountLike = string | {
    address?: string;
    pubkey?: string;
    ref?: string;
};

`SvmSettleExecutionInput`

Interface · @eco-incorp/sauce/svm/verify

export interface SvmSettleExecutionInput {
    instructionData: Uint8Array;
    accounts: readonly SvmSettleAccountLike[];
    wireFormat?: SvmExecutionWireFormat;
}

`SvmExecutionGate`

Interface · @eco-incorp/sauce/svm/verify Parsed derivation material only; this does not validate the Pot PDA or its signature.

export interface SvmExecutionGate {
    owner: Address;
    salt: Uint8Array;
    bump: number;
    pot: Address;
}

`DecodedSvmSettleExecution`

Interface · @eco-incorp/sauce/svm/verify

export interface DecodedSvmSettleExecution {
    instruction: "execute" | "execute_from_account";
    wireFormat: SvmExecutionWireFormat;
    gate?: SvmExecutionGate;
    codeAccount?: Address;
    escrowCount: number;
    refs: string[];
    accounts: Record<string, Address>;
    hadBufferAccount: boolean;
    labeledRefsConsistent: boolean | null;
}

`SvmSettleExecutionVerifyInput`

Interface · @eco-incorp/sauce/svm/verify

export interface SvmSettleExecutionVerifyInput extends SvmSettleExecutionInput, SvmSettleExpectation {
    bytecode?: Uint8Array;
    pin?: Uint8Array;
}

`SvmSettleVerifiedBy`

Type · @eco-incorp/sauce/svm/verify

export type SvmSettleVerifiedBy = "inline-bytecode" | "bytecode" | "caller-asserted-pin" | "none";

`SvmSettleExecutionVerification`

Interface · @eco-incorp/sauce/svm/verify

export interface SvmSettleExecutionVerification extends DecodedSvmSettleExecution {
    genuine: boolean;
    verifiedBy: SvmSettleVerifiedBy;
    pinMatchesCanonical: boolean | null;
    pinMatchesBytecode: boolean | null;
    bytecodeMatchesCanonical: boolean | null;
    mismatch?: string;
}

`decodePortalCalldataWithAccounts`

Function · @eco-incorp/sauce/svm/verify Decodes a Solana call envelope (CalldataWithAccounts): instruction data with its account metas. Takes raw bytes, 0x hex or base64. Throws on a truncated or malformed envelope.

export declare function decodePortalCalldataWithAccounts(data: BytesInput): PortalCalldataWithAccounts;

`encodePortalCalldataWithAccounts`

Function · @eco-incorp/sauce/svm/verify Encodes a Solana call envelope (CalldataWithAccounts): the exact inverse of decodePortalCalldataWithAccounts, built from the same field list. Returns 0x hex.

export declare function encodePortalCalldataWithAccounts(input: PortalCalldataWithAccountsInput): `0x${string}`;

`extractSvmSettleFromCalls`

Function · @eco-incorp/sauce/svm/verify Reads the settle program out of a batch of Solana call envelopes: returns the first call that carries a recognized engine settle execution, as the verifySvmSettleExecution verdict against options plus the call’s index and callee, or null. A staged program’s identity rests on each call’s own trusted pin. The caller must also require a readable callee equal to v12SvmEngineProgramId(), validate the gate and the account roles, and inspect every other call. Kitchen cook envelopes are not handled.

export declare function extractSvmSettleFromCalls(calls: readonly SvmCallLike[], options: ExtractSvmSettleOptions): ExtractedSvmSettle | null;

`PortalAccountMeta`

Interface · @eco-incorp/sauce/svm/verify One account meta of a Solana call envelope: the public key, and whether the account signs and is writable.

export interface PortalAccountMeta {
    pubkey: Address;
    isSigner: boolean;
    isWritable: boolean;
}

`PortalCalldataWithAccounts`

Interface · @eco-incorp/sauce/svm/verify A decoded Solana call envelope: the wrapped instruction data, the account count and the account metas.

export interface PortalCalldataWithAccounts {
    instructionData: Uint8Array;
    accountCount: number;
    accounts: PortalAccountMeta[];
}

`PortalCalldataWithAccountsInput`

Interface · @eco-incorp/sauce/svm/verify The input of encodePortalCalldataWithAccounts: the instruction data and account metas, with an optional account count.

export interface PortalCalldataWithAccountsInput {
    instructionData: Uint8Array;
    accounts: readonly PortalAccountMeta[];
    accountCount?: number;
}

`BytesInput`

Type · @eco-incorp/sauce/svm/verify An opaque byte payload: Uint8Array as-is; a 0x-prefixed hex string (the viem Hex form a call’s data takes); or a base64 string (the Solana convention) for anything not 0x-prefixed. A BARE STRING IS BASE64 HERE. For an address, use UniversalAddressInput - same three carriage forms, but a bare string there is base58, and the two must never be handed to the same reader.

export type BytesInput = Uint8Array | string;

`UniversalAddressInput`

Type · @eco-incorp/sauce/svm/verify A 32-byte universal address, in the forms one arrives in: raw bytes, 0x-hex (what buildSauceSvmCall emits as a call’s target), or the base58 program id itself. Deliberately NOT BytesInput, whose bare-string form is base64 - only a branded Address may be spent as the base58 form, so an unvalidated string does not typecheck and the two encodings cannot be confused at a call site.

export type UniversalAddressInput = Uint8Array | `0x${string}` | Address;

`SvmCallLike`

Interface · @eco-incorp/sauce/svm/verify One Solana call. data, the envelope, is required; target, the callee program, and pin, a staged program’s trusted pin, are used when present.

export interface SvmCallLike {
    data: BytesInput;
    target?: UniversalAddressInput;
    pin?: BytesInput;
}

`ExtractSvmSettleOptions`

Interface · @eco-incorp/sauce/svm/verify The values the settle program must have been compiled with (SvmSettleExpectation), plus an optional wireFormat and bytecode.

export interface ExtractSvmSettleOptions extends SvmSettleExpectation {
    wireFormat?: SvmExecutionWireFormat;
    bytecode?: BytesInput;
}

`ExtractedSvmSettle`

Type · @eco-incorp/sauce/svm/verify The extracted settle for a call: the full verifySvmSettleExecution verdict (resolved accounts and the genuine / verifiedBy genuineness fields), extended with the call’s index and callee.

export type ExtractedSvmSettle = SvmSettleExecutionVerification & {
    callIndex: number;
    target: SvmSettleTarget;
};

`SvmSettleTarget`

Type · @eco-incorp/sauce/svm/verify The callee of an extracted settle - three states a caller must keep apart. program: the call’s target, resolved to a program id to compare against the engine you trust. absent: the call carried no target at all. unreadable: it carried one that is not a 32-byte universal address, so there is nothing to compare it to. Collapsing unreadable into absent is the bypass this shape exists to prevent. A caller may legitimately skip the callee check for a call that named no callee; skipping it because the callee it named was garbage accepts a settle whose callee is unknown. Only program is ever safe to clear.

export type SvmSettleTarget = {
    readonly kind: "program";
    readonly address: Address;
} | {
    readonly kind: "absent";
} | {
    readonly kind: "unreadable";
    readonly reason: string;
};

Start here

Integration guides

Language reference

SauceScript libraries

Runtime and security

Troubleshooting and production

Chains and protocols

@eco-incorp/sauce

@eco-incorp/sauce-compiler

svm: Settle verification

`verifySvmSettleProgram`

`decodeSvmSettleExecution`

`verifySvmSettleExecution`

`SvmSettleExpectation`

`SettleManifestLike`

`SvmSettleVerification`

`SvmExecutionWireFormat`

`SvmSettleAccountLike`

`SvmSettleExecutionInput`

`SvmExecutionGate`

`DecodedSvmSettleExecution`

`SvmSettleExecutionVerifyInput`

`SvmSettleVerifiedBy`

`SvmSettleExecutionVerification`

`decodePortalCalldataWithAccounts`

`encodePortalCalldataWithAccounts`

`extractSvmSettleFromCalls`

`PortalAccountMeta`

`PortalCalldataWithAccounts`

`PortalCalldataWithAccountsInput`

`BytesInput`

`UniversalAddressInput`

`SvmCallLike`

`ExtractSvmSettleOptions`

`ExtractedSvmSettle`

`SvmSettleTarget`

​verifySvmSettleProgram

​decodeSvmSettleExecution

​verifySvmSettleExecution

​SvmSettleExpectation

​SettleManifestLike

​SvmSettleVerification

​SvmExecutionWireFormat

​SvmSettleAccountLike

​SvmSettleExecutionInput

​SvmExecutionGate

​DecodedSvmSettleExecution

​SvmSettleExecutionVerifyInput

​SvmSettleVerifiedBy

​SvmSettleExecutionVerification

​decodePortalCalldataWithAccounts

​encodePortalCalldataWithAccounts

​extractSvmSettleFromCalls

​PortalAccountMeta

​PortalCalldataWithAccounts

​PortalCalldataWithAccountsInput

​BytesInput

​UniversalAddressInput

​SvmCallLike

​ExtractSvmSettleOptions

​ExtractedSvmSettle

​SvmSettleTarget

`verifySvmSettleProgram`

`decodeSvmSettleExecution`

`verifySvmSettleExecution`

`SvmSettleExpectation`

`SettleManifestLike`

`SvmSettleVerification`

`SvmExecutionWireFormat`

`SvmSettleAccountLike`

`SvmSettleExecutionInput`

`SvmExecutionGate`

`DecodedSvmSettleExecution`

`SvmSettleExecutionVerifyInput`

`SvmSettleVerifiedBy`

`SvmSettleExecutionVerification`

`decodePortalCalldataWithAccounts`

`encodePortalCalldataWithAccounts`

`extractSvmSettleFromCalls`

`PortalAccountMeta`

`PortalCalldataWithAccounts`

`PortalCalldataWithAccountsInput`

`BytesInput`

`UniversalAddressInput`

`SvmCallLike`

`ExtractSvmSettleOptions`

`ExtractedSvmSettle`

`SvmSettleTarget`