@eco-incorp/sauce 0.99.5 → 0.99.7

package/sdk/dist/std/token/token.svm.js

@@ -1,65 +1,137 @@
-// @sauce/token — SVM arm (SPL Token).
+// @sauce/token — SVM arm (SPL Token and Token-2022).
 // Selected by the compiler for `--target svm`. Reads are a byte-range `svm.sload` into the SPL
-// account layout; writes are a `svm.call` CPI into the SPL Token program, which each write requires
-// by identity. Accounts are passed as
-// `Account` slots; the token's own identity (`token`) is a plain address value (the mint pubkey).
+// account layout; writes are a `svm.call` CPI into a token program, which each write requires by
+// identity. Accounts are passed as `Account` slots; the token's own identity (`token`) is a plain
+// address value (the mint pubkey).
 //
-// Pinning `.owner` to legacy SPL Token (`Tokenkeg…`) means a **Token-2022** (`TokenzQd…`) account is
-// now refused by every function here, where the reads used to accept one — its first 165 bytes carry
-// the same layout. Deliberate: the writes already pin their callee to `Tokenkeg…`, so accepting
-// Token-2022 on the read path would let one program's accounts be read and never written.
+// TWO TOKEN PROGRAMS. A mint, and every token account of it, is owned by the legacy SPL Token program
+// (`Tokenkeg…`) or by Token-2022 (`TokenzQd…`). Token-2022 keeps the legacy layouts as its base and
+// appends extensions after them, so one set of offsets reads both:
+//   - every read (`balanceOf`, `ownerOf`, `allowance`, `totalSupply`, `decimals`) takes an account
+//     owned by either program;
+//   - the checked writes (`transferChecked`, `approveChecked`) CPI into whichever of the two owns the
+//     accounts — the `TransferChecked`/`ApproveChecked` instructions, which carry the mint and its
+//     decimals and which both programs implement. Token-2022 refuses the plain `Transfer` for a mint
+//     whose extensions need the mint to move it (a transfer fee, a transfer hook, a pause), so a
+//     program that moves Token-2022 tokens uses these;
+//   - the plain writes (`transfer`, `transferFrom`, `approve`) are unchanged: they CPI the legacy
+//     `Transfer`/`Approve` into legacy SPL Token only, and refuse a Token-2022 callee or account.
 //
-// Every function requires `<account>.owner` to be the SPL Token program before it reads an SPL layout
-// out of an account. The layout checks below say what the bytes claim to be; the owner says who was
+// Every function requires `<account>.owner` to be a token program before it reads an SPL layout out
+// of an account. The layout checks below say what the bytes claim to be; the owner says who was
 // allowed to write them, and only the owning program may. Without it a hand-assembled account with the
 // right bytes at the right offsets reads exactly like a genuine one.
 //
-// SPL token-account layout (`spl_token::state::Account`, `LEN` = 165): mint@0 (pubkey), amount@64
-// (u64 LE), delegate COption tag@72 (u32 LE: 0 = None, 1 = Some), delegate@76 (pubkey),
-// delegated_amount@121 (u64 LE).
+// Each check reverts with a reason, so a refused account is named rather than failing in silence:
+// "not a token account" (an owner that is no token program, or a Token-2022 account that is not a
+// token account), "wrong mint", "not a mint", "uninitialized mint", "not the token program" (the CPI
+// callee), "amount over u64" and "transfer hook" (a Token-2022 mint whose transfer hook names a
+// program, below). They are short on purpose: a reason is compiled into the program byte for byte,
+// and on Solana the program rides in a transaction of at most 1,232 bytes (`transfer`'s four add 65).
+//
+// SPL token-account layout (`spl_token::state::Account`, `LEN` = 165): mint@0 (pubkey), owner@32
+// (pubkey: whose balance it is, a wallet or a PDA such as a Pot), amount@64 (u64 LE), delegate
+// COption tag@72 (u32 LE: 0 = None, 1 = Some), delegate@76 (pubkey), state@108 (u8), is_native
+// COption@109, delegated_amount@121 (u64 LE), close_authority COption@129.
 // SPL mint layout (`spl_token::state::Mint`, `LEN` = 82): supply@36 (u64 LE), decimals@44 (u8), initialized@45 (bool).
-// Instruction tags: Transfer=3, Approve=4.
-// The SPL Token program (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA) is an `Account` the caller
-// attaches, like every other: `svm.call`'s callee is named by the slot it occupies, so it rides in as
-// `tokenProgram` and reaches the manifest under that name. Which account arrives there is the
-// caller's choice, so each write `require`s that it is the SPL Token program — the same shape as the
-// mint check beside it, and the reason `Account` compares for identity.
+// Instruction tags: Transfer=3, Approve=4, TransferChecked=12, ApproveChecked=13.
+//
+// Token-2022 (`spl_token_2022::extension`): an account with no extensions is exactly the legacy size,
+// 82 bytes for a mint and 165 for a token account. An account WITH extensions is longer than 165: a
+// mint's 82 bytes are padded to 165, and either way byte 165 is the account type (1 = Mint,
+// 2 = Account), followed by the extensions as TLV entries (a u16 type, a u16 length, the value).
+// Token-2022 refuses to read a 355-byte account as either, because that is the size of its multisig,
+// whose byte 165 falls inside a signer key; so do these checks.
+//
+// The token program is an `Account` the caller attaches, like every other: `svm.call`'s callee is
+// named by the slot it occupies, so it rides in as `tokenProgram` and reaches the manifest under that
+// name. Which account arrives there is the caller's choice, so each write `require`s that it is a
+// token program — the same shape as the mint check beside it, and the reason `Account` compares for
+// identity.
 
 const SPL_TOKEN_PROGRAM = 0x06ddf6e1d765a193d9cbe146ceeb79ac1cb485ed5f5b37913a8cf5857eff00a9;
+const TOKEN_2022_PROGRAM = 0x06ddf6e1ee758fde18425dbce46ccddab61afc4d83b90d27febdf928d8a18bfc;
 
 // `spl_token::state::Mint::LEN` — the legacy SPL mint's exact size. Exact, not a floor: the legacy
 // program's `Pack` refuses any other length for a mint, so every account it ever initialized as one
 // is this size and nothing genuine is turned away by requiring it. A floor (`>= 82`) would admit the
 // 165-byte token account this exists to reject, since a token account is longer than a mint, not
-// shorter.
+// shorter. A Token-2022 mint is this size too until it carries an extension.
 const SPL_MINT_LEN = 82;
 
+// `spl_token::state::Account::LEN`, and the offset of a Token-2022 account's type byte.
+const SPL_ACCOUNT_LEN = 165;
+
+// `spl_token_2022::state::Multisig::LEN`, the one length above 165 that is no extended account.
+const SPL_MULTISIG_LEN = 355;
+
+// A token account of `token`, owned by either token program. A legacy SPL Token account is taken on
+// its owner, as it always was. A Token-2022 one is 165 bytes, or longer with its type byte (165) set
+// to Account (2), and never the multisig's 355; that keeps out a Token-2022 mint, whose first 32
+// bytes are its mint authority. Then its mint@0 must be `token`.
+//
+// The reads share it rather than each repeating it: a function is emitted once however many calls
+// reach it, so a program that reads an account twice over (`ownerOf`, then `balanceOf`) carries one
+// copy of the checks and their reasons, at the price of a call for a program that reads once.
+function requireTokenAccount(token: Address, account: Account): void {
+  if (account.owner != SPL_TOKEN_PROGRAM) {
+    const size = account.dataLen;
+    require(account.owner == TOKEN_2022_PROGRAM &&
+      (size == SPL_ACCOUNT_LEN ||
+        (size > SPL_ACCOUNT_LEN &&
+          size != SPL_MULTISIG_LEN &&
+          svm.sload(account, SPL_ACCOUNT_LEN, 1).toLe() == 2)), "not a token account");
+  }
+  require(svm.sload(account, 0, 32).toBe() == token, "wrong mint");
+}
+
+// An initialized mint, owned by either token program: 82 bytes, or a Token-2022 mint longer than 165
+// with its type byte set to Mint (1). Owner must be checked before size, and size before the type
+// byte, which only an extended account has: each program owns both mints and token accounts, and a
+// legacy mint is exactly 82 bytes. Size alone also admits permissionlessly allocated but
+// uninitialized accounts, so require the mint's initialization byte before reading its fields.
+function requireMint(token: Account): void {
+  const size = token.dataLen;
+  if (token.owner == TOKEN_2022_PROGRAM) {
+    require(size == SPL_MINT_LEN ||
+      (size > SPL_ACCOUNT_LEN &&
+        size != SPL_MULTISIG_LEN &&
+        svm.sload(token, SPL_ACCOUNT_LEN, 1).toLe() == 1), "not a mint");
+  } else {
+    require(token.owner == SPL_TOKEN_PROGRAM && size == SPL_MINT_LEN, "not a mint");
+  }
+  require(svm.sload(token, 45, 1).toLe() == 1, "uninitialized mint");
+}
+
 export function balanceOf(token: Address, account: Account): Uint256 {
-  require(account.owner == SPL_TOKEN_PROGRAM);
-  require(svm.sload(account, 0, 32).toBe() == token);
+  requireTokenAccount(token, account);
   return svm.sload(account, 64, 8).toLe();
 }
 
-// Legacy SPL Token owns both 82-byte mints and 165-byte token accounts. Owner must be checked
-// before size to reject Token-2022. Size alone also admits permissionlessly allocated but
-// uninitialized accounts, so require the mint's initialization byte before reading its fields.
+// Whose token account this is: its owner@32, a wallet or a PDA such as a Pot. Not `account.owner`,
+// which is the program that owns the account's data (a token program, checked first as everywhere
+// here), and not the `authority` a write is signed by: SPL accepts the account's delegate there too,
+// so a `transfer(…, authority)` that succeeds proves `authority` may spend from `source`, not that
+// `source` is `authority`'s. A program measuring its own balance requires
+// `ownerOf(token, account) == authority` first. There is no EVM counterpart: an ERC-20 balance has no
+// account apart from its holder, so the holder is already the address a program passes.
+export function ownerOf(token: Address, account: Account): Address {
+  requireTokenAccount(token, account);
+  return svm.sload(account, 32, 32).toBe();
+}
+
 export function totalSupply(token: Account): Uint256 {
-  require(token.owner == SPL_TOKEN_PROGRAM);
-  require(token.dataLen == SPL_MINT_LEN);
-  require(svm.sload(token, 45, 1).toLe() == 1);
+  requireMint(token);
   return svm.sload(token, 36, 8).toLe();
 }
 
 export function decimals(token: Account): Uint256 {
-  require(token.owner == SPL_TOKEN_PROGRAM);
-  require(token.dataLen == SPL_MINT_LEN);
-  require(svm.sload(token, 45, 1).toLe() == 1);
+  requireMint(token);
   return svm.sload(token, 44, 1).toLe();
 }
 
 export function allowance(token: Address, account: Account, spender: Address): Uint256 {
-  require(account.owner == SPL_TOKEN_PROGRAM);
-  require(svm.sload(account, 0, 32).toBe() == token);
+  requireTokenAccount(token, account);
   // The delegate is a `COption<Pubkey>`: read `delegated_amount` only when the tag is `Some` (1)
   // *and* the delegate matches `spender`. spl-token leaves the delegate bytes stale after `Revoke`,
   // so the tag must gate the pubkey compare — else a revoked delegate would still match.
@@ -84,10 +156,10 @@ export function transfer(
   authority: Account,
   amount: Uint256,
 ): void {
-  require(tokenProgram == SPL_TOKEN_PROGRAM);
-  require(source.owner == SPL_TOKEN_PROGRAM);
-  require(svm.sload(source, 0, 32).toBe() == token);
-  require(amount <= 0xffffffffffffffff);
+  require(tokenProgram == SPL_TOKEN_PROGRAM, "not the token program");
+  require(source.owner == SPL_TOKEN_PROGRAM, "not a token account");
+  require(svm.sload(source, 0, 32).toBe() == token, "wrong mint");
+  require(amount <= 0xffffffffffffffff, "amount over u64");
   let data = hex`03`;
   svm.call(tokenProgram, [source, dest, authority], data.concat(amount.toBytesLe(8)));
 }
@@ -119,10 +191,91 @@ export function approve(
   authority: Account,
   amount: Uint256,
 ): void {
-  require(tokenProgram == SPL_TOKEN_PROGRAM);
-  require(source.owner == SPL_TOKEN_PROGRAM);
-  require(svm.sload(source, 0, 32).toBe() == token);
-  require(amount <= 0xffffffffffffffff);
+  require(tokenProgram == SPL_TOKEN_PROGRAM, "not the token program");
+  require(source.owner == SPL_TOKEN_PROGRAM, "not a token account");
+  require(svm.sload(source, 0, 32).toBe() == token, "wrong mint");
+  require(amount <= 0xffffffffffffffff, "amount over u64");
   let data = hex`04`;
   svm.call(tokenProgram, [source, delegate, authority], data.concat(amount.toBytesLe(8)));
 }
+
+// The checked writes, for either token program: `TransferChecked` (12) and `ApproveChecked` (13) name
+// the mint as an account and carry its decimals. The callee must be one of the two token programs,
+// and the program that owns `source`, `dest` and `mint` — a Token-2022 account is moved by Token-2022
+// and a legacy one by legacy SPL Token, never across. `mint` must be `token`; the token program then
+// refuses a `source` or `dest` of any other mint, so the asset is pinned without reading either.
+// `decimals` must be the mint's own: the token program refuses a mismatch too, but the instruction
+// carries one byte, so a value past 255 would wrap onto the mint's and pass, where this refuses it.
+//
+// What Token-2022's extensions do to a checked write is the token program's, not this library's: a
+// transfer fee is withheld from what `dest` receives (a program measures the balance it got, not the
+// amount it sent), a paused mint and a frozen account refuse the CPI with the token program's own
+// error, and amounts are always raw base units (a scaled UI amount is a display multiplier no program
+// sees). The one extension refused here is a transfer hook that names a program: Token-2022 then
+// calls that program with the accounts its hook lists, which a fixed list of four cannot carry, so
+// the transfer is refused as "transfer hook" before it is attempted. A hook extension with no program
+// set is no hook, and transfers as any other mint.
+export function transferChecked(
+  token: Address,
+  tokenProgram: Account,
+  source: Account,
+  mint: Account,
+  dest: Account,
+  authority: Account,
+  amount: Uint256,
+  decimals: Uint256,
+): void {
+  require(tokenProgram == SPL_TOKEN_PROGRAM ||
+    tokenProgram == TOKEN_2022_PROGRAM, "not the token program");
+  const program = tokenProgram.address;
+  require(source.owner == program && dest.owner == program, "not a token account");
+  require(mint.owner == program, "not a mint");
+  require(mint == token, "wrong mint");
+  require(decimals == svm.sload(mint, 44, 1).toLe(), "wrong decimals");
+  require(amount <= 0xffffffffffffffff, "amount over u64");
+  // A mint's extensions follow its type byte, each a u16 type, a u16 length and the value.
+  // TransferHook (type 14) is its authority, then its program: all zeros is no program. A legacy mint,
+  // and a Token-2022 mint with no extensions, are 82 bytes, so the walk never starts. Token-2022 stops
+  // at an Uninitialized (0) entry and writes nothing after one; walking on reads only zeros.
+  let at = SPL_ACCOUNT_LEN + 1;
+  while (at + 4 <= mint.dataLen) {
+    const kind = svm.sload(mint, at, 2).toLe();
+    require(kind != 14 || svm.sload(mint, at + 36, 32).toBe() == 0, "transfer hook");
+    at = at + 4 + svm.sload(mint, at + 2, 2).toLe();
+  }
+  let data = hex`0c`;
+  svm.call(
+    tokenProgram,
+    [source, mint, dest, authority],
+    data.concat(amount.toBytesLe(8)).concat(decimals.toBytesLe(1)),
+  );
+}
+
+// `ApproveChecked` sets the single delegate on `source`, as `approve` does, for either token program.
+// The delegate is any key, not a token account, so only `source` and `mint` are checked. A transfer
+// hook runs on transfers only, so an approval needs no walk.
+export function approveChecked(
+  token: Address,
+  tokenProgram: Account,
+  source: Account,
+  mint: Account,
+  delegate: Account,
+  authority: Account,
+  amount: Uint256,
+  decimals: Uint256,
+): void {
+  require(tokenProgram == SPL_TOKEN_PROGRAM ||
+    tokenProgram == TOKEN_2022_PROGRAM, "not the token program");
+  const program = tokenProgram.address;
+  require(source.owner == program, "not a token account");
+  require(mint.owner == program, "not a mint");
+  require(mint == token, "wrong mint");
+  require(decimals == svm.sload(mint, 44, 1).toLe(), "wrong decimals");
+  require(amount <= 0xffffffffffffffff, "amount over u64");
+  let data = hex`0d`;
+  svm.call(
+    tokenProgram,
+    [source, mint, delegate, authority],
+    data.concat(amount.toBytesLe(8)).concat(decimals.toBytesLe(1)),
+  );
+}

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

@@ -3,30 +3,50 @@ 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";
+import type { SignedExecuteTransaction } from "./transaction.js";
+/**
+ * How a cook reaches the engine.
+ *
+ * - `"kitchen"`: the Kitchen's `cook` (or `cook_from_account`), which CPIs the engine and signs the
+ *   owner's Pot. The program can act as its Pot — hold assets in it, write its storage — and the
+ *   Kitchen charges the execution fee first. The engine runs one level down the invoke stack.
+ * - `"engine"`: the engine's own `cookAndPay` (or the staged, pinned `cookAndPayFromAccountPinned`).
+ *   The engine charges the same fee, into the same treasury, then runs the program as the top-level
+ *   instruction: no Pot, nothing signed for one — the program acts with the transaction's own
+ *   signatures, such as the wallet's — and one more level of CPI depth for what it calls.
+ */
+export type CookVia = "kitchen" | "engine";
 export interface SauceSvmClientConfig {
     /** Your cluster's JSON-RPC URL. Required: the SDK ships no RPC endpoints and has no default. */
     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. */
+    /** The ENGINE. Named per call rather than compiled in: the interpreter that runs, which a
+     *  Kitchen cook CPIs and a direct cook (`via: "engine"`) calls itself. */
     programId: Address;
     /**
-     * The KITCHEN every execution goes through.
+     * The KITCHEN, required either way.
      *
-     * 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.
+     * A Kitchen cook goes through it: the engine's legacy instructions refuse any invocation that did
+     * not arrive through one. A direct cook does not, but pays the fee its `["execution_fee"]` config
+     * sets, into that config — the engine re-derives the account against the Kitchen it bakes in.
      */
     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.
+     * What the caller consents to pay per cook, in lamports: every cook signs it as its
+     * `max_execution_fee`, and the Kitchen (or, `via: "engine"`, the engine) charges the configured
+     * fee only while it is at most this — a higher one refuses the cook before anything runs.
+     * 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.
+     * Quote it with `executionFee()`; a cook's own `maxExecutionFee` option overrides this one.
      */
     maxExecutionFee?: bigint;
+    /** How every cook reaches the engine: through the Kitchen (the default) or directly. See
+     *  {@link CookVia}. `potSalt` means nothing to a direct cook, which runs as no Pot. */
+    via?: CookVia;
 }
 export interface SimulateOpts {
     prepends?: readonly Instruction[];
@@ -37,6 +57,14 @@ export interface SimulateOpts {
      * NoSigner is lazy, so everything else runs (and simulates) signerless.
      */
     appendPayerSigner?: boolean;
+    /** This cook's `max_execution_fee`, in place of the client's `maxExecutionFee`. */
+    maxExecutionFee?: bigint;
+    /**
+     * Accounts whose state after the transaction `simulate`/`simulateStaged` report, in order, as
+     * `SimulateExecuteResult.accounts` — what a cook moved, read back without sending it. The
+     * execute paths ignore it.
+     */
+    accounts?: readonly Address[];
 }
 export interface ExecuteOpts extends SimulateOpts {
     /** 'auto' simulates first and applies recommendedComputeUnitLimit (x1.2, capped 1.4M). */
@@ -62,11 +90,15 @@ export interface StagedArgs {
 }
 export interface SimulateStagedOpts extends SimulateOpts {
     /**
-     * REJECTED, not enforced. Passing this THROWS.
+     * Through the Kitchen: 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.
+     *
+     * `via: "engine"`: the pin the engine enforces. A direct staged cook is always
+     * `cookAndPayFromAccountPinned`, and this is its digest — required unless the buffer is a
+     * `StagedBuffer`, whose `sha256` is used (the two must agree when both are given).
      */
     expectedSha256?: Uint8Array;
 }
@@ -91,6 +123,14 @@ export interface EnsureLookupTableOpts {
 export interface SauceSvmClient {
     /** Fee-payer / lookup-table authority public key — the ALT-address selection excludes it (signers cannot be looked up). */
     readonly payerAddress: Address;
+    /** How this client's cooks reach the engine. */
+    readonly via: CookVia;
+    /**
+     * The Kitchen's execution fee now, in lamports, from its fee config — what a cook pays either
+     * way. Compare it with what you will pay, and give it as `maxExecutionFee`, so a cook pays what
+     * was quoted or, if the fee rises before it lands, fails.
+     */
+    executionFee(): Promise<bigint>;
     /**
      * 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
@@ -103,15 +143,22 @@ export interface SauceSvmClient {
     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>;
+    /**
+     * The signed cook transaction `execute` sends, built the same way, without sending it: for a
+     * caller that sends it by its own route (polled confirmation, a relayer) or hands its wire bytes
+     * on. With `computeUnitLimit: "auto"` it simulates first, exactly as `execute` does.
+     */
+    cookTransaction(bytecode: Uint8Array, manifest: AccountManifest, resolution: AccountResolution, opts?: ExecuteOpts): Promise<SignedExecuteTransaction>;
     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.
+     * Executes a finalized code buffer in ONE instruction: the Kitchen's `cook_from_account`, or
+     * (`via: "engine"`) the engine's `cookAndPayFromAccountPinned`, pinned to the staged digest. The
+     * buffer is the code buffer's metadata address (or the `StagedBuffer`); its code account is
+     * derived from it. A staged program's arguments are part of the staged bytes.
      */
     executeStaged(buffer: Address | StagedBuffer, manifest: AccountManifest, resolution: AccountResolution, opts?: ExecuteStagedOpts): Promise<SendExecuteResult>;
+    /** The signed `cook_from_account` transaction `executeStaged` sends, without sending it. */
+    stagedCookTransaction(buffer: Address | StagedBuffer, manifest: AccountManifest, resolution: AccountResolution, opts?: ExecuteStagedOpts): Promise<SignedExecuteTransaction>;
 }
-export declare function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen, payer, potSalt, maxExecutionFee, }: SauceSvmClientConfig): Promise<SauceSvmClient>;
+export declare function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen, payer, potSalt, maxExecutionFee, via, }: SauceSvmClientConfig): Promise<SauceSvmClient>;
 //# sourceMappingURL=client.d.ts.map

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

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

package/sdk/dist/svm/client.js

@@ -1,12 +1,38 @@
 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 { assertNoExecutePin, buildCookAndPayFromAccountPinnedInstruction, buildCookAndPayInstruction, } from "./instructions.js";
 import { buildComputeBudgetPrepend, buildHeapFramePrepend } from "./prepends.js";
 import { resolveAccounts } from "./resolve.js";
-import { buildCookFromAccountInstruction, buildCookInstruction, deriveCodePda, deriveExecutionFeeConfigPda, derivePotPda, } from "./kitchen.js";
+import { buildCookFromAccountInstruction, buildCookInstruction, deriveCodePda, deriveExecutionFeeConfigPda, derivePotPda, fetchExecutionFee, } 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, }) {
+/**
+ * The digest a direct staged cook pins: the caller's `expectedSha256`, else the `StagedBuffer`'s
+ * own. A direct cook runs the code account with the transaction's signatures and the engine checks
+ * nothing else about that account, so the client makes no unpinned direct cook —
+ * `buildCookAndPayFromAccountInstruction` is the raw builder for a caller who wants one.
+ */
+function directPin(buffer, expectedSha256) {
+    const staged = typeof buffer === "string" ? undefined : buffer.sha256;
+    if (expectedSha256 !== undefined &&
+        staged !== undefined &&
+        (expectedSha256.length !== staged.length || expectedSha256.some((b, i) => b !== staged[i]))) {
+        throw new Error("expectedSha256 disagrees with the StagedBuffer's sha256: the pin must be the staged bytes' digest");
+    }
+    const pin = expectedSha256 ?? staged;
+    if (pin === undefined) {
+        throw new Error('a staged cook via "engine" is pinned: the engine runs the code account with the ' +
+            "transaction's signatures and checks nothing else about it. Pass the StagedBuffer staging " +
+            "returned, or the staged bytes' sha256 as expectedSha256.");
+    }
+    if (pin.length !== 32)
+        throw new Error("expectedSha256 must be exactly 32 bytes");
+    return pin;
+}
+export async function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen, payer, potSalt = new Uint8Array(32), maxExecutionFee = 0n, via = "kitchen", }) {
+    if (via !== "kitchen" && via !== "engine") {
+        throw new Error(`createSauceSvmClient: via must be "kitchen" or "engine", got ${String(via)}`);
+    }
     // The type already requires it; this is for callers the type does not reach (plain JS, a config
     // object built at runtime), who would otherwise get an opaque failure from inside the RPC client.
     if (typeof rpcUrl !== "string" || rpcUrl.trim() === "") {
@@ -37,47 +63,70 @@ export async function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen,
         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,
-        });
+        const cap = opts.maxExecutionFee ?? maxExecutionFee;
+        const executeInstruction = via === "engine"
+            ? buildCookAndPayInstruction({
+                engineProgram: programId,
+                feeConfig,
+                feePayer: payer.address,
+                maxExecutionFee: cap,
+                bytecode,
+                tail: accounts,
+            })
+            : buildCookInstruction({
+                kitchen,
+                owner: payer.address,
+                engineProgram: programId,
+                potSalt,
+                pot,
+                feeConfig,
+                bytecode,
+                maxExecutionFee: cap,
+                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);
+        return simulateExecute(rpc, transaction, opts.accounts === undefined ? {} : { accounts: opts.accounts });
     }
     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 cap = opts.maxExecutionFee ?? maxExecutionFee;
+        if (via === "kitchen")
+            assertNoExecutePin(opts.expectedSha256);
+        const pin = via === "engine" ? directPin(buffer, opts.expectedSha256) : undefined;
         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,
-        });
+        const executeInstruction = pin !== undefined
+            ? buildCookAndPayFromAccountPinnedInstruction({
+                engineProgram: programId,
+                code,
+                expectedSha256: pin,
+                feeConfig,
+                feePayer: payer.address,
+                maxExecutionFee: cap,
+                tail: accounts,
+            })
+            : buildCookFromAccountInstruction({
+                kitchen,
+                owner: payer.address,
+                codeBuffer: address,
+                code,
+                engineProgram: programId,
+                potSalt,
+                pot,
+                feeConfig,
+                maxExecutionFee: cap,
+                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);
+        return simulateExecute(rpc, transaction, opts.accounts === undefined ? {} : { accounts: opts.accounts });
     }
     async function autoComputeUnitPrepends(simulateRun, opts) {
         let unitLimit;
@@ -138,28 +187,40 @@ export async function createSauceSvmClient({ rpcUrl, wsUrl, programId, kitchen,
         await waitForAltActive(rpc, lastExtendedSlot);
         return { lookupTableAddress, lookupTables: await fetchAlt(rpc, lookupTableAddress) };
     }
+    async function cookTransaction(bytecode, manifest, resolution, opts = {}) {
+        const prepends = await autoComputeUnitPrepends(() => simulate(bytecode, manifest, resolution, {
+            prepends: opts.prepends,
+            lookupTables: opts.lookupTables,
+            appendPayerSigner: opts.appendPayerSigner,
+            maxExecutionFee: opts.maxExecutionFee,
+        }), opts);
+        return buildTransaction(bytecode, manifest, resolution, prepends, opts);
+    }
+    async function stagedCookTransaction(buffer, manifest, resolution, opts = {}) {
+        const prepends = await autoComputeUnitPrepends(() => simulateStaged(buffer, manifest, resolution, {
+            prepends: opts.prepends,
+            lookupTables: opts.lookupTables,
+            appendPayerSigner: opts.appendPayerSigner,
+            expectedSha256: opts.expectedSha256,
+            maxExecutionFee: opts.maxExecutionFee,
+        }), opts);
+        return buildStagedTransaction(buffer, manifest, resolution, prepends, opts);
+    }
     return {
         payerAddress: payer.address,
+        via,
+        executionFee: () => fetchExecutionFee(rpc, kitchen),
         ensureLookupTable,
         simulate,
+        cookTransaction,
         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);
+            const transaction = await cookTransaction(bytecode, manifest, resolution, opts);
             return sendExecute({ rpc, rpcSubscriptions, transaction });
         },
         simulateStaged,
+        stagedCookTransaction,
         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);
+            const transaction = await stagedCookTransaction(buffer, manifest, resolution, opts);
             return sendExecute({ rpc, rpcSubscriptions, transaction });
         },
     };