svm: Kitchen - Eco Docs

@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.

`derivePotPda`

Function · @eco-incorp/sauce/svm A Pot: ["pot", owner, salt]. The salt is what lets one owner hold many - it is raw bytes, not a counter, so a caller with a natural 32-byte id (a hash, say) passes it directly.

export declare function derivePotPda(kitchen: Address, owner: Address, salt: Uint8Array): Promise<KitchenPda>;

`deriveExecutionFeeConfigPda`

Function · @eco-incorp/sauce/svm The execution-fee config: ["execution_fee"], one per kitchen. It is both the fee’s source of truth and the treasury the fees accumulate in, so every cook takes it writable even when the configured fee is zero.

export declare function deriveExecutionFeeConfigPda(kitchen: Address): Promise<KitchenPda>;

`decodeExecutionFeeConfig`

Function · @eco-incorp/sauce/svm The fee in an ExecutionFeeConfig account’s data: 8 discriminator bytes, then the fee as a u64 LE - exactly 16 bytes, the length the engine requires too. Anything else throws: a lookalike account is not a fee of zero.

export declare function decodeExecutionFeeConfig(data: Uint8Array): bigint;

`fetchExecutionFee`

Function · @eco-incorp/sauce/svm The Kitchen’s execution fee in lamports, read from its ["execution_fee"] config - what a cook through the Kitchen and a direct engine cook both pay. Throws when the config is absent, is not owned by kitchen, or does not decode: every cook is refused on chain then, so there is no fee to report.

export declare function fetchExecutionFee(rpc: Rpc<GetAccountInfoApi>, kitchen: Address): Promise<bigint>;

`deriveProgramDataPda`

Function · @eco-incorp/sauce/svm A program’s ProgramData under the upgradeable loader: [program]. The fee instructions authorize against the authority recorded there rather than a stored admin key, so whoever can upgrade the kitchen is whoever can price it.

export declare function deriveProgramDataPda(program: Address): Promise<KitchenPda>;

`deriveCodeBufferPda`

Function · @eco-incorp/sauce/svm A code buffer’s metadata account: ["buffer", owner, nonce_le].

export declare function deriveCodeBufferPda(kitchen: Address, owner: Address, nonce: bigint): Promise<KitchenPda>;

`deriveCodePda`

Function · @eco-incorp/sauce/svm The bytes account for a buffer: ["code", code_buffer]. Seeded on the METADATA account’s address, so the pair is bound by derivation and neither needs to store a pointer to the other for the kitchen to validate.

export declare function deriveCodePda(kitchen: Address, codeBuffer: Address): Promise<KitchenPda>;

`buildCreatePotInstruction`

Function · @eco-incorp/sauce/svm

export declare function buildCreatePotInstruction({ kitchen, owner, engineProgram, pot, salt, space, }: CreatePotInput): Instruction;

`buildClosePotInstruction`

Function · @eco-incorp/sauce/svm

export declare function buildClosePotInstruction({ kitchen, owner, engineProgram, pot, salt, }: ClosePotInput): Instruction;

`buildCookInstruction`

Function · @eco-incorp/sauce/svm Builds a Kitchen cook with the program in the instruction data. Include buildHeapFramePrepend() exactly once; omitting it makes the cook fail with ProgramFailedToComplete. Pot and code-buffer lifecycle instructions do not require it. The Pot account must match the supplied salt, and any Pot the program writes must also appear in the unsigned tail.

export declare function buildCookInstruction({ kitchen, owner, engineProgram, potSalt, pot, feeConfig, bytecode, maxExecutionFee, feePayer, tail, }: CookInput): Instruction;

`buildCookFromAccountInstruction`

Function · @eco-incorp/sauce/svm cook_from_account - the staged transport: the bytecode is read from a finalized code account. Needs the same RequestHeapFrame as cook - see there.

export declare function buildCookFromAccountInstruction({ kitchen, owner, codeBuffer, code, engineProgram, potSalt, pot, feeConfig, pin, maxExecutionFee, feePayer, tail, }: CookFromAccountInput): Instruction;

`buildCreateCodeBufferInstruction`

Function · @eco-incorp/sauce/svm Creates the codeBuffer metadata account and its code data account, sized for capacity. capacity must be 1..=MAX_CODE_LEN; the kitchen rejects anything else with CapacityOutOfRange, and this throws first so the bound is visible without a simulation. A create allocates at most ONE GROWTH_STEP. The runtime caps how much an account can grow per instruction, so a capacity above that is only partly allocated here and needs Math.ceil(capacity / GROWTH_STEP) - 1 further buildGrowCodeBufferInstruction calls before the code account is the full size. The cap resets per instruction, so those repeats can share one transaction. Writing before the account is fully grown fails with WriteOutOfBounds.

export declare function buildCreateCodeBufferInstruction({ kitchen, owner, codeBuffer, code, nonce, capacity, }: CodeBufferAccounts & {
    nonce: bigint;
    capacity: number;
}): Instruction;

`buildGrowCodeBufferInstruction`

Function · @eco-incorp/sauce/svm One growth step. A CPI-created account cannot be allocated more than GROWTH_STEP at once, so a larger buffer repeats this - the runtime’s limit resets per instruction, so the repeats fit in one transaction.

export declare function buildGrowCodeBufferInstruction({ kitchen, owner, codeBuffer, code, }: CodeBufferAccounts): Instruction;

`buildWriteCodeBufferInstruction`

Function · @eco-incorp/sauce/svm

export declare function buildWriteCodeBufferInstruction({ kitchen, owner, codeBuffer, code, offset, chunk, }: CodeBufferAccounts & {
    offset: number;
    chunk: Uint8Array;
}): Instruction;

`buildFinalizeCodeBufferInstruction`

Function · @eco-incorp/sauce/svm Seals the buffer at len and pins its digest. The kitchen shrinks the code account to exactly len here, which is the security property: the engine executes the account’s whole data slice and bounds jumps only by that slice’s length, so any byte past len would be jump-reachable but outside the hash.

export declare function buildFinalizeCodeBufferInstruction({ kitchen, owner, codeBuffer, code, len, expectedSha256, }: CodeBufferAccounts & {
    len: number;
    expectedSha256: Uint8Array;
}): Instruction;

`buildCloseCodeBufferInstruction`

Function · @eco-incorp/sauce/svm Closes both accounts and refunds their rent. expectedSha256 gates the close on the staged bytes.

export declare function buildCloseCodeBufferInstruction({ kitchen, owner, codeBuffer, code, expectedSha256, }: CodeBufferAccounts & {
    expectedSha256?: Uint8Array;
}): Instruction;

`buildInitializeExecutionFeeInstruction`

Function · @eco-incorp/sauce/svm initialize_execution_fee - creates the config PDA. The initial fee must be greater than zero; a kitchen is unusable until it is priced, and a later set may take it back to zero.

export declare function buildInitializeExecutionFeeInstruction({ kitchen, authority, programData, feeConfig, payer, initialFee, }: ExecutionFeeAdminInput & {
    payer?: Address;
    initialFee: bigint;
}): Instruction;

`buildSetExecutionFeeInstruction`

Function · @eco-incorp/sauce/svm set_execution_fee - repricing, including back to zero.

export declare function buildSetExecutionFeeInstruction({ kitchen, authority, programData, feeConfig, fee, }: ExecutionFeeAdminInput & {
    fee: bigint;
}): Instruction;

`buildWithdrawExecutionFeesInstruction`

Function · @eco-incorp/sauce/svm withdraw_execution_fees - collect what the config PDA holds. amount omitted sweeps everything ABOVE the account’s rent-exempt minimum, which the withdrawal never spends: that same account is the config every cook reads, and a zero balance would have the runtime reap it. The recipient must already be rent-exempt, or the runtime refuses the transaction for leaving it rent-paying.

export declare function buildWithdrawExecutionFeesInstruction({ kitchen, authority, programData, feeConfig, recipient, amount, }: ExecutionFeeAdminInput & {
    recipient: Address;
    amount?: bigint;
}): Instruction;

`TailAccount`

Type · @eco-incorp/sauce/svm One entry of a program’s own account tail, in the shape a kit Instruction carries.

export type TailAccount = AccountLookupMeta | AccountMeta;

`KITCHEN_DISCRIMINATORS`

Variable · @eco-incorp/sauce/svm Each Kitchen instruction’s discriminator, by name: what tells an instruction read back what it is.

KITCHEN_DISCRIMINATORS: Readonly<Record<keyof typeof DISCRIMINATOR, Uint8Array>>

`CODE_BUFFER_SEED`

Variable · @eco-incorp/sauce/svm The kitchen’s own #[constant]s, from the same IDL.

CODE_BUFFER_SEED = "buffer"

`CODE_SEED`

Variable · @eco-incorp/sauce/svm

CODE_SEED = "code"

`POT_SEED`

Variable · @eco-incorp/sauce/svm

POT_SEED = "pot"

`EXECUTION_FEE_SEED`

Variable · @eco-incorp/sauce/svm

EXECUTION_FEE_SEED = "execution_fee"

`GROWTH_STEP`

Variable · @eco-incorp/sauce/svm One grow_code_buffer step: MAX_PERMITTED_DATA_INCREASE, the most a CPI-created account can grow in a single instruction.

GROWTH_STEP = 10240

`MAX_CODE_LEN`

Variable · @eco-incorp/sauce/svm

MAX_CODE_LEN = 1048576

`MAX_POT_LEN`

Variable · @eco-incorp/sauce/svm

MAX_POT_LEN = 10240

`svmRentExempt`

Variable · @eco-incorp/sauce/svm Rent-exempt lamports for an account of bytes of data, at mainnet’s rent: 3,480 lamports per byte-year, two years, over the data and the 128 bytes every account carries.

svmRentExempt: (bytes: number) => bigint

`SALT_BYTES`

Variable · @eco-incorp/sauce/svm A Pot’s salt and a code buffer’s expected_sha256 are both exactly 32 bytes.

SALT_BYTES = 32

`BPF_LOADER_UPGRADEABLE`

Variable · @eco-incorp/sauce/svm The loader that owns every upgradeable program’s ProgramData, which is where the fee instructions read the kitchen’s live upgrade authority from.

BPF_LOADER_UPGRADEABLE: Address