@eco-incorp/sauce 0.99.1 → 0.99.3

package/docs/guides/quick-start.md

@@ -0,0 +1,64 @@
+# Quick start
+
+[Documentation](../README.md) · [Protocols and tokens](protocols-and-tokens.md) · [Intents](intents.md)
+
+Use Node.js 24 or newer and install the single public package:
+
+```sh
+pnpm add @eco-incorp/sauce
+```
+
+The Sauce compiler is a dependency of that package. You do not need a compiler checkout or a separate compiler install.
+
+## Compile your first intent
+
+This complete TypeScript example builds an approval intent offline. Addresses and the fee are fixtures; the zero reward demonstrates construction only. Before submission, [read the current Kitchen fee and prepare an Executor-owned Pot](intents.md#prepare-the-destination-pot).
+
+```ts
+import "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+const executionFee = 1_000n; // Fixture: read the destination Kitchen's executionFee() before use.
+const options: routes.IntentOptions = {
+  execution: {
+    pot: "0x1111111111111111111111111111111111111111",
+    engine: "0x2222222222222222222222222222222222222222",
+    value: executionFee,
+  },
+  nativeAmount: executionFee,
+  portal: "0x3333333333333333333333333333333333333333",
+  deadline: 2_000_000_000n,
+};
+
+const built = Base(() => {
+  USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+}, options).reward({
+  source: "ethereum",
+  creator: "0x4444444444444444444444444444444444444444",
+  prover: "0x5555555555555555555555555555555555555555",
+  deadline: 2_000_003_600n,
+  nativeAmount: 0n,
+});
+
+console.log(built.hash().intentHash);
+```
+
+Importing the root package installs `Base` and the other chain globals. Inside the callback, the SDK resolves `USDC` and `Uniswap.UniversalRouter` for Base, compiles the body with Sauce, and encodes a Pot `cook(engine, program)` call. `.reward(...)` completes the Eco intent. Nothing is submitted to a chain.
+
+For execution, deploy the Pot with the destination `Portal.executor()` as owner and pay the current Kitchen fee on every cook. [Intent setup](intents.md#prepare-the-destination-pot) shows the reads and deployment call. Fund and empty that shared Pot within the fulfillment.
+
+`USDC` and protocol names have generated TypeScript declarations but are source syntax, not JavaScript clients. The router is registered as `UniswapV4.UniversalRouter`, with `Uniswap.UniversalRouter` as a family alias. `UniswapV3.UniversalRouter` is not a registered name. See [coverage](../api/coverage.md) for which protocols expose these namespaces.
+
+The callback captures no outer variables. Pass dynamic scalars through `defines`, or use explicit source strings; see the complete [transfer example](../examples/first-intent.ts). Callbacks must remain recognizable synchronous source after your build tooling transforms them.
+
+## Deliver assets and fund the reward
+
+In a transfer intent, the destination assets and source reward are separate. Destination `tokens` reach the Portal Executor. Add a transfer precall to deliver tokens into the Pot before Sauce spends them. Source reward tokens are approved to the source Portal and escrowed through its funding call.
+
+The [first-intent.ts example](../examples/first-intent.ts) constructs both sides and returns source transaction requests. Read [creating intents](intents.md) before submitting those requests, and [nested intents](nested-intents.md) to compose subsequent routes.
+
+## Compile a standalone program
+
+Use `@eco-incorp/sauce/compiler` when you need raw bytecode, entry schemas, or an SVM account manifest. It exposes the published Rust/Wasm compiler through `compile(options)`; it does not install SDK protocol namespaces into arbitrary compiler input.
+
+The [compiler example](../examples/compile-program.ts) compiles a typed SauceScript entry point and appends compact arguments. [Compiling](compiling.md) explains module resolution and the distinction between raw compiler output and the route wrapper.

package/docs/guides/solana.md

@@ -0,0 +1,199 @@
+# Solana programs and execution
+
+[Documentation](../README.md) · [Compiler](../api/compiler.md) · [Coverage](../api/coverage.md)
+
+Solana programs use the `svm` compiler target, explicit account parameters, and a Kitchen that invokes the engine. EVM token/protocol member rewrites such as `USDC.transfer(...)` do not apply to SVM routes.
+
+Use `@eco-incorp/sauce/compiler` to retain the compiler's account manifest. `routes.compileSauceRoute()` returns execution calls and a `compiled.bytecode` segment list, but does not expose that manifest; applications resolving account slots should use the direct compiler result.
+
+## Compile an SPL transfer
+
+The universal token builder emits account parameters and an SPL `TransferChecked` CPI. Its source needs no imports, so a single-module resolver is sufficient:
+
+```ts
+import { token } from "@eco-incorp/sauce";
+import { compile } from "@eco-incorp/sauce/compiler";
+
+export function compileSplTransfer(amount: bigint) {
+  const source = token.Token.transfer({
+    amount,
+    svm: {
+      source: "sourceAta",
+      mint: "mint",
+      dest: "destinationAta",
+      owner: "owner",
+      tokenProgram: "tokenProgram",
+    },
+  }).source("svm");
+
+  return compile({
+    target: "svm",
+    entry: "main.ts",
+    resolve: (id) => (id === "main.ts" ? new TextEncoder().encode(source) : null),
+  });
+}
+```
+
+The account references are names, not addresses. `manifest.accounts` records their order and required roles. Resolve them to the mint, source token account, destination token account, authority, and token program before execution. Amounts are smallest-unit integers. The builder reads mint decimals for the checked instruction and defaults to the classic SPL Token program. Set the builder's top-level `tokenProgram: "token-2022"` for a supported Token-2022 operation; `svm.tokenProgram` names the account reference and must resolve to that token program.
+
+## Execute through the Kitchen
+
+`createSauceSvmClient` requires an RPC URL, engine program ID, Kitchen program ID, and a Kit transaction signer. Its inline execution path constructs a Kitchen `cook`, includes the required heap-frame instruction, resolves accounts, and builds/signs transactions.
+
+Use `v12SvmEngineProgramId()` and `v12SvmKitchenProgramId()` from
+`@eco-incorp/sauce/deployments` for the released program identities, and confirm
+they are deployed on your cluster. The older `v12SvmProgramId` constant identifies
+a legacy engine. The client derives a Pot owned by its `payer` signer; select it
+with `potSalt` when configuring the client.
+
+```ts
+import {
+  createSauceSvmClient,
+  type AccountResolution,
+  type SauceSvmClientConfig,
+} from "@eco-incorp/sauce/svm";
+import type { CompileResult } from "@eco-incorp/sauce/compiler";
+
+export async function simulateProgram(
+  config: SauceSvmClientConfig,
+  compiled: CompileResult,
+  accounts: AccountResolution,
+) {
+  if (!compiled.manifest) throw new Error("Expected an SVM account manifest");
+  const client = await createSauceSvmClient(config);
+  return client.simulate(compiled.bytecode, compiled.manifest, accounts);
+}
+```
+
+For the transfer above, the resolution keys are `sourceAta`, `mint`, `destinationAta`, `owner`, and `tokenProgram`. A non-payer transaction authority should be supplied as `{ address, signer: transactionSigner }`; an address alone cannot provide its signature. A Pot PDA that the Kitchen signs for must be attached with `signer: false` in the transaction resolution. That override represents a signature supplied during invocation, not permission to bypass the program's authority requirement.
+
+After successful simulation, `client.execute(bytecode, manifest, resolution, { computeUnitLimit: "auto" })` simulates for compute budgeting and sends the transaction. `maxExecutionFee` in client configuration is the lamport fee ceiling accepted for each cook; its default is zero and fails when the Kitchen charges a positive fee. Lookup-table helpers can create or extend an address lookup table and wait until it is usable.
+
+### Select the released programs and quote the fee
+
+The pinned SVM engine **1.1.0** is `7MetdnWSaEsowvUmVyvwrbAeUW9xXFpVWXUXw4MxZ5CG`;
+Kitchen **1.0.0** is `SauceYLdWyabKFwtevSAgsSDoMjCoTKtx1HTb63eJot`.
+These are release addresses; confirm deployment on your cluster before use.
+Engine 1.1.0 adds direct paid calls. The SDK clients use Kitchen-mediated cooks;
+builders for the direct paid instructions are not yet exposed.
+Use the deployment helpers and read the Kitchen's fee configuration on the selected
+cluster. This example checks a caller-selected lamport budget before signing:
+
+```ts
+import { createHash } from "node:crypto";
+import {
+  address,
+  assertAccountExists,
+  createSolanaRpc,
+  fetchEncodedAccount,
+  type TransactionSigner,
+} from "@solana/kit";
+import { v12SvmEngineProgramId, v12SvmKitchenProgramId } from "@eco-incorp/sauce/deployments";
+import { createSauceSvmClient, deriveExecutionFeeConfigPda } from "@eco-incorp/sauce/svm";
+
+export async function createReleasedClient(
+  rpcUrl: string,
+  payer: TransactionSigner,
+  feeBudgetLamports: bigint,
+) {
+  const kitchen = address(v12SvmKitchenProgramId());
+  const { address: feeConfig } = await deriveExecutionFeeConfigPda(kitchen);
+  const account = await fetchEncodedAccount(createSolanaRpc(rpcUrl), feeConfig);
+  assertAccountExists(account);
+  const discriminator = createHash("sha256")
+    .update("account:ExecutionFeeConfig")
+    .digest()
+    .subarray(0, 8);
+  if (
+    account.programAddress !== kitchen ||
+    account.data.length !== 16 ||
+    !discriminator.every((value, index) => account.data[index] === value)
+  )
+    throw new Error("Unexpected Kitchen fee account");
+  const fee = new DataView(
+    account.data.buffer,
+    account.data.byteOffset,
+    account.data.byteLength,
+  ).getBigUint64(8, true);
+  if (fee > feeBudgetLamports) throw new Error("Kitchen fee exceeds the approved budget");
+  return createSauceSvmClient({
+    rpcUrl,
+    payer,
+    kitchen,
+    programId: address(v12SvmEngineProgramId()),
+    maxExecutionFee: fee,
+  });
+}
+```
+
+The payer needs SOL for this per-cook fee, transaction fees, and any rent or program
+spending. The Kitchen charges its current fee up to the signed cap; a fee increase
+above the quoted amount makes the cook fail. Requote before signing a retry.
+
+`resolveAccounts` preserves manifest order. The reserved `payer` reference resolves to the fee payer. A manifest ending with `remaining` leaves the final account tail to the caller; do not insert accounts that shift that tail's indices.
+
+## Stage a larger program
+
+Staging belongs to the Kitchen. There is no `client.stageBuffer()` convenience method. Build and submit Kitchen instructions in this order:
+
+1. Derive metadata and code addresses with `deriveCodeBufferPda(kitchen, owner, nonce)` and `deriveCodePda(kitchen, codeBuffer)`.
+2. Allocate with `buildCreateCodeBufferInstruction`. Capacities above `GROWTH_STEP` require additional `buildGrowCodeBufferInstruction` calls.
+3. Write the bytecode in appropriately sized chunks using `buildWriteCodeBufferInstruction`.
+4. Finalize with `buildFinalizeCodeBufferInstruction`, supplying the byte length and its SHA-256 digest. Finalization verifies the digest and shrinks the code account to that length.
+5. Execute with a Kitchen `buildCookFromAccountInstruction`, or the client's `simulateStaged`/`executeStaged` methods.
+
+The low-level instruction builders return instructions; the application groups, signs, submits, and confirms them. The two Kitchen cook paths require `buildHeapFramePrepend()` when assembling transactions yourself. A staged client's first argument is the **code-buffer metadata address**; it derives the associated code account.
+
+`buildCookFromAccountInstruction` supports a `pin` that the Kitchen checks at execution. The client's `expectedSha256` option is currently rejected; it is not a supported substitute for that low-level `pin`. A finalized buffer's digest and an execution-time caller-selected digest are different guarantees.
+
+## SVM destinations in Eco intents
+
+**The SDK's SVM route helpers are incompatible with the released gated engine.**
+For an SVM destination, `Solana(body, { execution, ... }).reward(...)`,
+`routes.compileSauceRoute()`, `buildSauceSvmCall()`, and `buildSauceSvmCalls()` emit
+a legacy `execute_from_account` instruction containing only its 8-byte
+discriminator. Engine 1.1.0 still requires another 65 bytes of Pot derivation material
+and a trailing Pot signer supplied by the Kitchen.
+
+The [SVM Portal fulfillment implementation](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
+forwards the route's instruction bytes to its target unchanged. It signs for its
+Executor PDA; it does not construct a Kitchen call or sign for a Sauce Pot.
+Changing only the helper's engine program ID therefore does not make these routes
+executable. Do not distribute them as executable intents against the pinned release.
+
+A Kitchen-targeted Portal integration needs separately constructed cook data and
+accounts, including the owner signature, Pot, fee configuration and payer, engine,
+and staged metadata/code where applicable. The SDK does not currently build or
+validate that complete integration. For standalone execution, use the client or
+Kitchen instruction builders described above.
+
+The legacy route's `execution.code` means the finalized **code account**, not its
+metadata address. The helper neither stages nor checks that code against its newly
+compiled bytes, and it drops the compiler account manifest. Keep the direct
+compilation result when inspecting historical routes. EVM-source Portal helpers
+can encode an SVM destination; they do not provide Solana-origin submission.
+
+## Venue accessors
+
+The `Solana` global includes the venues registered for runtime access. A venue accessor exposes a program ID, pool configuration loading, quote-source generation, swap CPI construction, and a TypeScript reference quote:
+
+```ts
+import { venue } from "@eco-incorp/sauce/svm";
+import type { AccountLoader, SwapUser } from "@eco-incorp/sauce/svm";
+import type { Address } from "@solana/kit";
+
+export async function buildRaydiumSwap(
+  load: AccountLoader,
+  pool: Address,
+  user: SwapUser,
+  amount: bigint,
+) {
+  const raydium = venue("raydium-cp-swap");
+  const config = await raydium.poolConfig(load, pool);
+  return raydium.swap(config, user, amount);
+}
+```
+
+`Solana.RaydiumCpSwap` exposes the same accessor when globals are installed. `poolConfig` uses the account loader you supply; it does not create an RPC client or discover pools. `quoteSource` returns SauceScript source, and `.swap` returns CPI data plus account references, not a transaction.
+
+Venue swap builders use a venue-level minimum output of one; the composed program must enforce the user's actual minimum with a post-swap output balance delta. Runtime accessors cover the registered venue set. Other adapters exported from `/svm` do not automatically appear as `Solana.<Venue>`; consult [coverage](../api/coverage.md).

package/docs/guides/verification.md

@@ -0,0 +1,253 @@
+# Verifying settlement programs
+
+[Documentation](../README.md) · [Intents](intents.md) · [Compiler API](../api/compiler.md)
+
+The SDK verifies its canonical settlement programs on EVM and SVM. These helpers
+answer which settlement logic and parameters a payload contains. Applications
+still check the destination, execution target, account identities, and remaining
+intent calls against the operation they intend to authorize.
+
+| Surface                        | Mechanism                                                                                          | Environment                                                            |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `@eco-incorp/sauce/verify`     | Validate the EVM program hash and decode its canonical runtime argument tail                       | Node, browsers, and edge runtimes; depends on `viem`, not the compiler |
+| `@eco-incorp/sauce/svm/verify` | Recompile SVM settlement with expected parameters, compare bytecode, and inspect attached accounts | Node; loads the compiler                                               |
+
+## Settlement behavior
+
+The EVM recipe sweeps the Pot's entire current balance of every listed token to
+one recipient. It checks `minOut` against the balance of `tokens[0]` before the
+first transfer; `minOut: 0n` disables that floor. Existing or donated balances
+count toward the floor and are swept as well. The floor is a balance check, not a
+measurement of the amount produced by an earlier swap.
+
+The SVM recipe applies the same pattern to escrow token accounts. It takes an
+escrow count and compile-time `minOut`/`splCount`, then attaches token programs,
+escrows, mints, destination token accounts, and the owner. `splCount` selects how
+the escrows are split between the two token-program slots.
+
+## EVM: validate a complete payload
+
+For EVM, a payload is the reusable compiled program followed by ABI-v1 runtime
+arguments. The compiler never sees the argument values.
+
+```ts
+import {
+  SETTLE_PROGRAM,
+  encodeSettleProgram,
+  validateSettleProgram,
+} from "@eco-incorp/sauce/verify";
+
+const payload = encodeSettleProgram(
+  ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"], // Base USDC
+  1_000_000n,
+  "0x1111111111111111111111111111111111111111", // Example recipient
+  SETTLE_PROGRAM,
+);
+
+const settlement = validateSettleProgram(payload);
+console.log(settlement.tokens, settlement.minOut, settlement.recipient);
+console.log(settlement.floorToken, settlement.programHash);
+```
+
+`validateSettleProgram()` checks the full program hash and the argument encoding.
+The current `SETTLE_WIRE` pin records compiler **2.3.0** and a **356-byte** program.
+Payloads produced before that recompile are 362 bytes under a different hash; verify them by
+passing their historical `{ hash, bytes: 362 }` pin to `validateSettleProgram`.
+Import `SETTLE_WIRE` when code needs those values; avoid copying them into a
+second constant table.
+
+The tail contains three 32-byte head words—token-array offset, minimum output,
+recipient—followed by the token count and token addresses in source order. The
+verifier requires the canonical offset, a nonempty token list, a nonzero
+recipient, clean address words, and no trailing data. Some alternate encodings
+execute on an engine but are deliberately rejected here, so a successful decode
+has a unique byte representation.
+
+This surface verifies the pinned **ABI-v1** settlement artifact. Recompiling the
+recipe with `compactArgs: true` changes that contract and is not accepted by the
+existing settlement decoder.
+
+### Inspection levels
+
+| Helper                                                    | Result                                                                                    |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `validateSettleProgram(payload, accepted?)`               | Hash-pinned program identity and strict argument decode; preferred for validation         |
+| `decodeSettleProgram(payload)`                            | Strict argument shape at the expected program length; does not authenticate program bytes |
+| `parseSettleProgram(payload)`                             | A non-throwing structural report, including a `fatal` failure when present                |
+| `bestEffortDecode(parse)`                                 | Best-effort inspection or `null` when reporting values would be misleading                |
+| `encodeSettleProgram(tokens, minOut, recipient, program)` | Canonical payload construction                                                            |
+
+An arbitrary prefix of the expected length can pass structural decoding. Only a
+hash-pinned validation establishes that it contains the recognized settlement
+program. Validation failures use `SettleDecodeError.code`, including
+`PROGRAM_HASH`, `TOKENS_OFFSET`, `DIRTY_ADDRESS_WORD`, and `ARGS_OVERLONG`.
+
+### Extract a settlement from an intent
+
+The intent helpers unwrap `cook` calldata and validate the program they find.
+This reusable check expects exactly one current Pot settlement call:
+
+```ts
+import { extractEvmSettleFromIntent, type IntentLike } from "@eco-incorp/sauce/verify";
+import type { Address } from "viem";
+
+export function inspectSingleSettle(
+  intent: IntentLike,
+  trustedPot: Address,
+  trustedEngine: Address,
+) {
+  const result = extractEvmSettleFromIntent(intent);
+  if (!result) throw new Error("No recognized settlement");
+  if (intent.route.calls.length !== 1 || result.callIndex !== 0) {
+    throw new Error("Expected exactly one settlement call");
+  }
+  if (result.ingredientCount !== 1) throw new Error("Unexpected extra program");
+  if (result.target?.toLowerCase() !== trustedPot.toLowerCase()) {
+    throw new Error("Unexpected Pot");
+  }
+  if (result.engine?.toLowerCase() !== trustedEngine.toLowerCase()) {
+    throw new Error("Unexpected engine");
+  }
+  return result; // Compare tokens, minOut, and recipient to application expectations.
+}
+```
+
+For a swap-plus-settle intent, use the expected call count and positions for that
+application and validate every other call. `extractEvmSettleFromIntent()` returns
+the first recognized settlement; it does not approve the whole batch or check
+the intent's destination chain.
+
+`decodeSettleCall(data)` examines one cook, and
+`extractEvmSettleFromCalls(calls)` operates without the intent wrapper. The
+decoder also recognizes the historical `cook(bytes[])` wrapper: only its first
+ingredient is inspected. A legacy router executes every ingredient, so check
+`ingredientCount` and interpret an absent `engine` according to that contract.
+Current `Pot.cook(address,bytes)` carries exactly one program and reports the
+engine it names.
+
+### Compiler upgrades and historical pins
+
+`validateSettleProgram` accepts an explicit list of program hashes or
+`{ hash, bytes }` `ProgramPin` records. Use the full record for a historical
+program with a different length. Passing an empty list accepts no program; it
+does not fall back to the default pin.
+
+Compiler upgrades can change program bytes. When upgrading the SDK or compiler,
+check which program versions your application produces and accepts. Import the
+SDK's settlement pins rather than copying their values. Keep historical pins only
+for program versions your application explicitly accepts.
+
+The source is available through `settleSource()` from
+`@eco-incorp/sauce/recipes`, and as the
+`@eco-incorp/sauce/recipes/settle.sauce.ts` asset. `SAUCE_BASE_DIRS` locates its ABI
+dependencies for a reproducing resolver. The verifier itself does not load that
+source or recompile it.
+
+## SVM: verify program and accounts
+
+SVM settle parameters are compiled into the program, and account identities live
+outside it. State the expected floor and token-program split, then verify both
+parts.
+
+```ts
+import { compile } from "@eco-incorp/sauce/compiler";
+import { svmSettleSource } from "@eco-incorp/sauce/svm";
+import { verifySvmSettleProgram } from "@eco-incorp/sauce/svm/verify";
+
+const expected = { minOut: 1_000_000n, splCount: 1n };
+const source = new TextEncoder().encode(svmSettleSource(1));
+const artifact = compile({
+  target: "svm",
+  resolve: (path) => (path === "main.js" ? source : undefined),
+  defines: [
+    ["SETTLE_MIN_OUT", expected.minOut.toString()],
+    ["SETTLE_SPL_COUNT", expected.splCount.toString()],
+  ],
+});
+if (!artifact.manifest) throw new Error("Expected SVM accounts");
+
+const result = verifySvmSettleProgram(artifact.bytecode, artifact.manifest, expected);
+if (!result.genuine) throw new Error(result.mismatch);
+console.log(result.escrowCount, result.refs);
+```
+
+This example demonstrates reproduction. To verify received data, pass the
+received bytecode and manifest instead. The helper infers the escrow count from
+the `3N + 3` account shape, checks canonical slot names, and recompiles the shipped
+source with the expected values. Supported settle generators accept 1–16 escrows.
+The result does not establish that the account addresses attached to an actual
+instruction are the ones the application expects.
+
+### Execution verification
+
+`decodeSvmSettleExecution({ instructionData, accounts })` resolves accounts
+positionally against the canonical settlement refs. The default `wireFormat: "gated-v1"` accepts raw **engine CPI instructions** produced by Kitchen 1.0.0 for
+engine 1.1.0:
+
+| Instruction            | Data                                                               | Full CPI account list                  |
+| ---------------------- | ------------------------------------------------------------------ | -------------------------------------- |
+| `execute`              | discriminator (8 bytes), owner (32), salt (32), bump (1), bytecode | settlement accounts, Pot               |
+| `execute_from_account` | discriminator (8 bytes), owner (32), salt (32), bump (1)           | code account, settlement accounts, Pot |
+
+The decoder removes the code account and trailing Pot before resolving the
+`3N + 3` settlement slots. It returns parsed `gate` metadata and the staged
+`codeAccount` when present. It rejects truncated headers, extra staged data,
+invalid account addresses, and incompatible account counts. Labels are diagnostic;
+account positions determine identities. Structural decoding alone cannot identify
+settlement: unrelated programs can use the same account count.
+
+Historical 8-byte headers require explicit `wireFormat: "legacy-ungated"`.
+That inspection mode accepts the user account tail or its code-prefixed form;
+it does not make legacy instructions executable on the released engine.
+Kitchen `cook` and `cook_from_account` have different data and account layouts
+and must not be passed directly to this decoder.
+
+`verifySvmSettleExecution()` adds `minOut`, `splCount`, and optional `bytecode`
+and `pin` inputs. Check both its `genuine` and `verifiedBy` fields:
+
+| `verifiedBy`          | What was compared                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `inline-bytecode`     | The program inside an `execute` instruction matches the canonical program; supplied bytecode, if any, must match it too |
+| `bytecode`            | Supplied staged bytecode matches the canonical program and the supplied pin hashes those bytes                          |
+| `caller-asserted-pin` | A caller-supplied pin equals the hash of the canonical program; no staged bytes were supplied                           |
+| `none`                | No basis to authenticate the staged program                                                                             |
+
+For staged execution, the pin comes from the **caller**, not from the released
+engine's `execute_from_account` calldata. That instruction has no content-pin
+field. A `bytecode` or `caller-asserted-pin` result therefore depends on the
+caller's evidence connecting that pin to the code account that will execute,
+such as the relevant Kitchen `cook_from_account` instruction and staged account
+contents. The helper does not fetch that evidence. Supplying canonical bytes
+without a pin cannot authenticate a staged execution.
+
+Also check the engine program ID and the account identities, roles, mints,
+owners, and destinations required by the application. Parsed gate metadata is
+not proof of a valid Pot derivation or signature. The verifier does not validate
+the Kitchen invocation, account roles, on-chain state, or execution success;
+`genuine` describes the recognized program under the stated pin assumptions.
+
+### Eco Portal envelopes
+
+`decodePortalCalldataWithAccounts()` unwraps the SVM Portal's instruction data
+and ordered account metas. It requires the declared account count to match the
+full account list, canonical Borsh flags, and no trailing bytes. Envelope decoding
+alone does not validate the target, program identity, or settlement.
+`extractSvmSettleFromIntent()` and
+`extractSvmSettleFromCalls()` combine envelope extraction with execution
+verification and report the call target. They expect the raw engine format
+above, default to `gated-v1`, and do **not** decode Kitchen cook envelopes. Supply
+expected `minOut`, `splCount`, optional `wireFormat`, and optional `bytecode`
+through their options. When verifying staged code, attach
+the independently obtained `pin` to the relevant input call; pins are per call,
+not shared across the batch.
+
+A working Kitchen-targeted route needs separate Kitchen decoding before its
+program and account plan can be checked. For an already executed transaction,
+inspect the recorded inner engine instruction instead. The SDK's legacy SVM
+route builder cannot produce that Kitchen integration; see the
+[Solana guide](solana.md#svm-destinations-in-eco-intents).
+
+As on EVM, finding a genuine settlement does not validate adjacent calls or an
+arbitrary callee that accepts the same instruction discriminator. Match the
+reported target and account plan to the deployment and intent your application
+expects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eco-incorp/sauce",
-  "version": "0.99.1",
+  "version": "0.99.3",
   "description": "Sauce protocol tooling: SDK, action primitives, and a local dev environment.",
   "type": "module",
   "repository": {
@@ -8,6 +8,7 @@
     "url": "git+https://github.com/eco-incorp/sauce.git"
   },
   "homepage": "https://sauce.eco.com",
+  "license": "SEE LICENSE IN LICENSE.md",
   "bugs": "https://github.com/eco-incorp/sauce/issues",
   "publishConfig": {
     "access": "public",
@@ -79,6 +80,7 @@
     "sauce-dev-tools": "./dev-tools/scripts/init.js"
   },
   "files": [
+    "LICENSE.md",
     "sdk/dist",
     "actions/dist",
     "sdk/src/skills",
@@ -88,7 +90,9 @@
     "dev-tools/sauce",
     "dev-tools/artifacts",
     "dev-tools/hardhat.config.cjs",
-    "dev-tools/README.md"
+    "dev-tools/README.md",
+    "docs/**/*.md",
+    "docs/examples/*.ts"
   ],
   "dependencies": {
     "@solana-program/address-lookup-table": "^0.12.1",
@@ -98,7 +102,7 @@
     "@solana/kit": "^6.10.0",
     "acorn": "^8.15.0",
     "dotenv": "^17.3.1",
-    "sauce-compiler": "npm:@eco-incorp/sauce-compiler@^2.2.1",
+    "sauce-compiler": "npm:@eco-incorp/sauce-compiler@2.3.0",
     "typescript": "^5.7.0",
     "viem": "^2.45.3"
   },
@@ -112,9 +116,10 @@
     "typescript-eslint": "8.70.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "scripts": {
+    "docs:check": "node docs/scripts/check-docs.mjs",
     "build": "pnpm -r --filter './sdk' --filter './actions' build",
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test",

package/sdk/dist/artifacts/V12Deployments.json

@@ -1,16 +1,34 @@
 {
   "version": "1.0.0",
   "commit": "f2f6dfbe38809304d83ca755eb7975c19d35ceab",
+  "releases": {
+    "v12-evm": {
+      "version": "1.0.1",
+      "commit": "9281c2eeb0e14557e6565a3a689ae31380740fa7"
+    },
+    "kitchen-evm": {
+      "version": "1.0.0",
+      "commit": "f2f6dfbe38809304d83ca755eb7975c19d35ceab"
+    },
+    "v12-svm": {
+      "version": "1.1.0",
+      "commit": "5c809b3d001583c0fad81f23271eadb5265cd747"
+    },
+    "kitchen-svm": {
+      "version": "1.0.0",
+      "commit": "f2f6dfbe38809304d83ca755eb7975c19d35ceab"
+    }
+  },
   "evm": {
     "chainIndependent": true,
     "factory": "0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed",
     "deployer": "0x6Ab56944462222A2405ffb87d01A29e37890abC3",
     "contracts": {
       "engine": {
-        "address": "0x7d6FB016aa99425b6b490aDB520839b3A2342d3F",
+        "address": "0x9745fdfaB1be84a0003f0472A842A0b91E5A323c",
         "saltName": "Engine",
-        "rawSalt": "0x6ab56944462222a2405ffb87d01a29e37890abc300456e67696e650000010000",
-        "guardedSalt": "0x8a75428505a2ae0e25db2ef82c8dcb5a062b943f30ffc18525c6721d970f8fab",
+        "rawSalt": "0x6ab56944462222a2405ffb87d01a29e37890abc300456e67696e650000010001",
+        "guardedSalt": "0xbfaa08f51a17021008df6c83a6de420a69d30bb65908e3b1d31b5bcf7b0c20f4",
         "derivation": "CREATE(CREATE2(factory, guardedSalt, keccak256(CreateX proxy initcode)), 1)"
       },
       "router": {
@@ -49,8 +67,8 @@
     "clusterIndependent": true,
     "programs": {
       "engine": {
-        "programId": "DnR2g6w9gVhqcR68QEpuw7Wm7MuoKxRVEtKZDXGes3Nj",
-        "label": "engine@1.0.0",
+        "programId": "7MetdnWSaEsowvUmVyvwrbAeUW9xXFpVWXUXw4MxZ5CG",
+        "label": "engine@1.1.0",
         "derivation": "ed25519 keypair from sha256(SOLANA_PROGRAM_KEY_SEED, label)",
         "upgradeAuthority": "none — deployed --final, so this program can never be upgraded or closed"
       },