@eco-incorp/sauce 0.99.1 → 0.99.2

package/docs/concepts/architecture.md

@@ -0,0 +1,134 @@
+# SDK, compiler, and runtime
+
+[Documentation](../README.md) · [Quick start](../guides/quick-start.md)
+
+Sauce turns a program into an atomic on-chain execution. The SDK supplies chain and
+protocol knowledge, the compiler translates SauceScript into bytecode, and a
+compatible on-chain engine executes that bytecode. An Eco intent describes the
+destination execution and the reward for fulfilling it.
+
+## The three layers
+
+| Layer    | Published surface                                                                  | Responsibility                                                                                                                             |
+| -------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| SDK      | `@eco-incorp/sauce` and its subpaths                                               | Protocol and token registries, route syntax, builders, intent encoding, account planning, transaction helpers, and settlement verification |
+| Compiler | `@eco-incorp/sauce-compiler`; exposed in Node through `@eco-incorp/sauce/compiler` | Parse and check SauceScript, resolve modules and ABIs, apply compile-time parameters, and emit EVM or SVM bytecode                         |
+| Runtime  | Deployed Sauce EVM/SVM engines and Kitchen/Pot contracts or programs               | Execute compatible bytecode against the chain's accounts and contracts                                                                     |
+
+The compiler is included when you install `@eco-incorp/sauce`. Import
+`@eco-incorp/sauce/compiler` to compile standalone programs, or use the SDK
+route builders to resolve protocol and token names automatically.
+
+```mermaid
+flowchart TD
+    A[Route closure or source string] --> B[SDK: destination, tokens, protocols, defines]
+    B --> C[Rewritten SauceScript and ABI bindings]
+    C --> D[Published Sauce compiler]
+    E[Standalone SauceScript and resolver] --> D
+    D --> F[EVM bytecode]
+    D --> G[SVM bytecode and account manifest]
+    F --> H[Pot.cook: engine and program]
+    G --> I[Account plan and Kitchen cook instruction]
+    H --> J[Direct transaction or Eco route call]
+    I --> K[Solana transaction]
+```
+
+Both compiler targets use Sauce bytecode. EVM output is not a Solidity contract's
+deployment bytecode, and SVM output is not a Solana ELF program. The selected
+Sauce engine interprets it.
+
+## From global names to contract calls
+
+Inside an EVM route, the SDK lets you write:
+
+```js
+USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+```
+
+The destination chain selects `USDC` and the router deployment. Before invoking
+the compiler, the SDK rewrites token and protocol access into contract bindings,
+supplies the matching ABIs, and injects scalar addresses. The compiler then sees
+the equivalent `IERC20.at(...).approve(...)` call.
+
+These names are SDK syntax, not builtins of the standalone compiler. A direct
+`compile()` call needs explicit ABI imports/bindings and any addresses or defines
+the program uses. See [protocols and tokens](../guides/protocols-and-tokens.md) and
+[the compiler API](../api/compiler.md).
+
+There are also separate host JavaScript and SauceScript environments. Importing
+the SDK installs chain helpers such as `Base` in the host. A route callback is
+read as source and compiled; it is never invoked as a JavaScript callback and
+does not capture its surrounding variables. Generated TypeScript declarations
+help you author route bodies, but compilation still resolves each name against
+the selected destination's actual registry.
+
+## From bytecode to execution
+
+### EVM
+
+`V12Pot.cook(address engine, bytes program)` runs one program. A Pot has an owner;
+the engine is supplied on each cook. Constructing a call therefore needs both a
+**Pot address** and an **engine address**. The SDK does not infer them from the
+protocol namespace. The released engine accepts only canonical Pots deployed through
+its configured Kitchen. Each cook must send the Kitchen's current `executionFee()`
+in `msg.value`; the Pot remits it before running the program. Add native program
+funding on top of that fee. An existing Pot balance does not replace this payment.
+
+A multi-statement route body compiles to one program and one cook. To run separate
+programs, construct separate calls and use an authorized execution mechanism that
+propagates failures if the entire operation must be atomic. The caller must have
+authority to invoke the Pot. For direct Eco route calls, the caller and required
+Pot owner is the destination `Portal.executor()`. Keep funds in that shared Pot
+only during the fulfillment; [intent setup](../guides/intents.md#prepare-the-destination-pot)
+shows deployment, custody, and fee handling.
+
+### SVM
+
+The compiler returns an account manifest as well as bytecode. `Account` parameters
+name attached slots; their `Writable` and `Signer` modifiers describe required
+roles. Account identities and instruction data travel through separate channels.
+
+The SVM SDK resolves account plans, builds instructions and transactions, and
+supports Kitchen-managed code staging. Staged Kitchen execution uses finalized
+metadata and code accounts. The built-in SVM route helper emits a legacy engine
+instruction and is incompatible with the released engine; use the direct Kitchen
+client described in the [Solana guide](../guides/solana.md).
+
+The released engine's `execute_from_account` instruction names a code account;
+its instruction data does not carry a content hash. A program hash checked during
+Kitchen staging or cooking and the identity of the account later executed are
+distinct evidence. See [settlement verification](../guides/verification.md#svm-verify-program-and-accounts).
+
+## Intents connect executions across chains
+
+`Base(() => { ... }, options).reward(reward)` creates an Eco intent whose route
+executes on Base. The source chain and funding information come from the intent
+options and reward. The SDK compiles the destination program, constructs the
+route, and provides Portal calldata and hashes.
+
+Building an intent does not publish, fund, or fulfill it. Those are transactions
+submitted by the application and fulfillment actors. Nested intents are separate
+executions composed with `.nest(...)`; they do not form one synchronous call
+stack across chains. See [creating intents](../guides/intents.md).
+
+## Compiler and engine compatibility
+
+Compiler 2.3.0 identifies its output as `isaRevision: "stack-compact-v2"` and
+reports the selected entry-argument format. These fields describe the artifact;
+they do not inspect an address or negotiate runtime support.
+
+Use `v12EngineAddress()`, `v12KitchenAddress()`, `v12SvmEngineProgramId()`, and
+`v12SvmKitchenProgramId()` from `@eco-incorp/sauce/deployments` to obtain released
+engine and Kitchen addresses. The legacy chain roster records an older
+deployment and does not attest liveness of the pinned release. Check deployed
+code, cluster, and instruction support on the target chain. Pair programs with the engine
+release intended for them, and retain the compiler version, ISA revision, target,
+and argument format with cached or staged artifacts.
+
+Changing the compiler can change bytecode without changing the source-level API.
+Settlement hash pins, compiled-program caches, and staged programs therefore
+belong in a compiler upgrade's validation. The [verification guide](../guides/verification.md)
+explains the SDK's current settlement pins.
+
+Start with [SauceScript concepts](saucescript.md) for the language boundary, or
+[compiling programs](../guides/compiling.md) for direct compiler integration.

package/docs/concepts/saucescript.md

@@ -0,0 +1,172 @@
+# Writing SauceScript
+
+[Documentation](../README.md) · [Architecture](architecture.md) · [Compiling](../guides/compiling.md)
+
+SauceScript is a checked subset of TypeScript for programs that run inside the
+Sauce engine. It has familiar variables, functions, conditions, loops, arrays,
+and records, but it does not execute in a JavaScript VM. A host application builds
+and submits programs; SauceScript performs their on-chain computation.
+
+## Programs and route bodies
+
+A standalone program can declare an entry function:
+
+```ts
+function main(amounts: Uint256[], minimum: Uint256): Uint256 {
+  let total = 0n;
+  for (let i = 0; i < amounts.length; i = i + 1) {
+    total = total + amounts[i];
+  }
+  require(total >= minimum);
+  return total;
+}
+```
+
+This is SauceScript source, not a host TypeScript module. `Uint256` and `require`
+are interpreted by the Sauce compiler. Source diagnostics identify the relevant
+location and span; option, resolver, and target-capability errors may have no span.
+
+A function declared `: void` can finish without returning a value. Other
+functions must return on every path. Annotate helper functions returning arrays,
+bytes, or records so their callers know the return shape. The raw compiler also
+accepts an entry script without an explicit `main` and synthesizes its entry.
+Entry argument encoding does not determine return encoding. For ABI-decodable
+EVM output, [return `abi.encode(...)`](../guides/compiling.md#encode-evm-return-values).
+
+The SDK provides a second authoring form: a route body passed to a chain helper.
+
+```js
+() => {
+  USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+};
+```
+
+Pass this body to `Base(body, options)` or another chain helper as shown in the
+[intent guide](../guides/intents.md). The SDK extracts its text, wraps it in
+`main`, resolves SDK global names, and compiles it. For a body that falls through,
+the compilation adapter adds a `void` entry annotation.
+
+The callback must be synchronous, take no parameters, and retain source text the
+SDK can parse. It captures **no host variables**. A host `const amount = ...`
+does not make `amount` available to the compiler; pass it through
+`options.compile.defines`, write it into generated source, or use a standalone
+program with runtime entry arguments. If bundling/minification rewrites callback
+names or bodies, use explicit source strings or source assets.
+
+## Three ways values enter a program
+
+| Channel                             | When resolved                          | Effect on the compiled program                                                      |
+| ----------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
+| Literals and compile-time `defines` | During compilation                     | Values can be folded into bytecode; changing them can change the program hash       |
+| `main` parameters                   | During execution                       | Values are encoded after the reusable program; their values are not compiler inputs |
+| SVM `Account` parameters            | When instruction accounts are attached | Identities occupy manifest slots, separate from encoded scalar/collection arguments |
+
+The EVM settle recipe takes its token list, floor, and recipient as runtime
+parameters, so one program hash covers all values. The SVM settle recipe compiles
+its floor and token-program split through defines and verifies them by
+recompilation. Those are deliberate API choices, not interchangeable encodings.
+
+## Values and types
+
+SauceScript uses 256-bit scalar words and heap-backed bytes, arrays, and tuples.
+There is no JavaScript floating-point arithmetic. Prefer `bigint` literals in
+host-authored route callbacks so the host preserves exact integer values.
+
+| Type or syntax                            | Meaning                                                      |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `Uint256`, `number`, `bigint`             | A scalar integer word                                        |
+| `Address`                                 | An address-valued scalar                                     |
+| `bool`, `boolean`                         | A boolean type checked separately from integer values        |
+| `bytes`, `string`                         | Byte strings                                                 |
+| `T[]`                                     | An array whose element type is `T`                           |
+| `{ amount: Uint256, recipient: Address }` | A tuple/record shape                                         |
+| A top-level `interface`                   | A named record type                                          |
+| `Account`, `Account<Writable, Signer>`    | An SVM account slot and required role; address-valued on EVM |
+| `void`                                    | A function with no return value                              |
+
+Annotations are checked. Arbitrary TypeScript types are not accepted, and `as`
+casts cannot be used to bypass a type error. Ordinary arithmetic is checked by
+the compiler/runtime rather than following JavaScript number semantics.
+
+Module-level scalar `const` values are compile-time values. Module-level `let`
+state is initialized for each invocation; it is not persistent chain state. Use
+the target-specific storage builtins when persistent storage is required.
+
+## Language support
+
+The current compiler supports function declarations, recursion, `if`/`else`,
+`while`, C-style `for`, array `for...of`, short-circuit logical operators,
+conditional expressions, array/record values, indexing, mutation, and supported
+byte operations. Modules can import other SauceScript modules, JSON ABIs, and
+JSON data. Constant expressions and compile-time branches can be folded.
+
+Useful boundaries when adapting application code:
+
+- `async`/`await`, promises, classes, arbitrary JavaScript libraries, and host APIs
+  such as `fetch` or `console` are not on-chain operations.
+- Functions are declarations, not first-class values. The outer route callback
+  is an SDK wrapper; it does not add general arrow-function support to the
+  language. The special EVM external-call `.catch(() => { ... })` handler is a
+  supported exception.
+- `switch`, `for...in`, rest/spread, default parameters, and general object
+  destructuring are unsupported. Tuple destructuring in function bodies is
+  supported.
+- Type aliases, enums, generic application types, unions, `as`, and `satisfies`
+  are outside the subset. Use the supported annotations and named interfaces.
+- A template literal with interpolation is unsupported. The `hex` tagged literal
+  produces literal bytes.
+
+These examples and boundaries are validated with Sauce compiler 2.3.0. Additional
+language and builtin references are available at [sauce.eco.com](https://sauce.eco.com).
+
+## EVM and SVM operations
+
+The compiler shares a frontend across targets and rejects unavailable operations
+for the target selected at compile time.
+
+| Capability                                           | EVM                                      | SVM                                               |
+| ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------------- |
+| Arithmetic, functions, arrays, records, control flow | Supported                                | Supported                                         |
+| ABI-bound `Contract.at(address).method(...)`         | Supported                                | Use CPI/account APIs                              |
+| `evm.call`, `evm.static`, `evm.delegate`             | Supported                                | Unavailable                                       |
+| `svm.call` with attached account slots               | Unavailable                              | Supported                                         |
+| `abi.encode` / `abi.decode` builtins                 | Supported                                | Unavailable                                       |
+| Persistent storage                                   | `evm.sload` / `evm.sstore`               | `svm.sload` / `svm.sstore` byte ranges            |
+| Transient storage and external-call catch handlers   | EVM-specific                             | Unavailable                                       |
+| SDK `USDC.approve(...)` and protocol-member rewrites | Supported for registered EVM deployments | Use SVM account-aware builders                    |
+| Runtime entry arguments                              | ABI-v1 or compact-v1                     | ABI-v1 or compact-v1, plus separate Account slots |
+
+The absence of SVM `abi.encode`/`abi.decode` builtins does not remove runtime
+entry parameters: entry decoding is its own compiler feature. Context values
+also have target semantics: an EVM address and a Solana public key have different
+widths, and `ctx.blockNumber()` refers to the target's block/slot model.
+
+## Modules, ABI bindings, and global names
+
+A direct compiler program can bind an EVM ABI explicitly:
+
+```ts
+import ERC20 from "./erc20.abi.json";
+
+function main(token: Address, spender: Address, amount: Uint256): void {
+  ERC20.at(token).approve(spender, amount);
+}
+```
+
+A bare JSON import binds a contract ABI. A JSON data import uses
+`with { type: "json" }`. The host resolver must return the named file's bytes in
+either case.
+
+The compiler's `ambient` option broadcasts a SauceScript module's exports without
+explicit imports. Its `defines` option injects scalar constants into every
+module. Their precedence differs: ambient exports yield to declarations;
+defines replace same-named module `const` values. Pick specific define names
+because that replacement also reaches imported dependencies.
+
+The SDK adds chain selection, token symbols, and protocol member access around
+that compiler API. `openRoute` and chain helpers supply chain defines and the
+default `@sauce/token` ambient module. Direct `compileSauceRoute()` accepts an
+explicit `ambient` list and does not add that default list. Raw `compile()` adds
+neither the SDK registry nor its filesystem resolver. See the
+[compilation guide](../guides/compiling.md#choose-a-compilation-path) for the exact
+boundary.

package/docs/examples/README.md

@@ -0,0 +1,34 @@
+# Executable examples
+
+[Documentation](../README.md) · [Quick start](../guides/quick-start.md)
+
+These examples use the published package exports. The construction examples run offline: they compile source and construct transaction data without sending transactions. Repeated-digit addresses and illustrative fees are fixtures, not deployment configuration. The RPC setup helper is typechecked but only makes chain reads when your application calls it.
+
+| Example                                      | Demonstrates                                                                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [protocol-approval.ts](protocol-approval.ts) | A typed `Base(() => ...)` callback with `USDC.approve(Uniswap.UniversalRouter, ...)`                                           |
+| [first-intent.ts](first-intent.ts)           | Ethereum reward, Base USDC delivery, Executor-to-Pot funding, explicit callback defines, source transaction requests           |
+| [compile-program.ts](compile-program.ts)     | The compiler dependency, compact entry schema, argument encoding and decoding                                                  |
+| [evm-execution.ts](evm-execution.ts)         | Destination RPC setup helper: current Kitchen, Portal Executor ownership, Pot prediction/deployment request, and execution fee |
+
+## Run an example in your project
+
+Use Node.js 24 or newer. Install the SDK and TypeScript in your application:
+
+```sh
+pnpm add @eco-incorp/sauce
+pnpm add -D typescript
+```
+
+Set `"type": "module"` in your project's `package.json`. Copy an example to `example.ts`, then compile and run it:
+
+```sh
+pnpm exec tsc example.ts --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --skipLibCheck --outDir dist
+node dist/example.js
+```
+
+For `first-intent.ts` and `evm-execution.ts`, also run `pnpm add viem`: they use Viem's address formatter and RPC interfaces.
+
+The examples are typechecked and loaded automatically in the SDK's CI. Construction examples assert their encoded output, including nonzero cook-fee budgeting; the RPC helper is not a live-chain integration test.
+
+For actual EVM execution, first call `prepareDestinationPot` from `evm-execution.ts` with a destination client, Portal, and salt. If it returns `ready: false`, send its deployment request with your signer, wait for a successful receipt, and call it again. When `ready: true`, use its Pot, engine, and observed execution fee instead of the offline fixtures. Supply valid deadlines, source funding, and solver fulfillment. Read [intents](../guides/intents.md) for atomic asset handling and fee budgets, and [Solana](../guides/solana.md) for the separate supported execution paths.

package/docs/examples/compile-program.ts

@@ -0,0 +1,20 @@
+import {
+  compile,
+  decodeCompactArguments,
+  encodeCompactArguments,
+} from "@eco-incorp/sauce/compiler";
+
+const source = "function main(amount: Uint256): Uint256 { return amount + 1; }";
+const artifact = compile({
+  target: "evm",
+  compactArgs: true,
+  resolve: () => new TextEncoder().encode(source),
+});
+if (artifact.entryEncoding !== "compact-v1" || artifact.entrySchema === undefined) {
+  throw new Error("Expected a compact entry schema");
+}
+const args = encodeCompactArguments(artifact.entrySchema, [42n]);
+const program = new Uint8Array([...artifact.bytecode, ...args]);
+const decoded = decodeCompactArguments(artifact.entrySchema, args);
+if (!Array.isArray(decoded) || decoded[0] !== 42n) throw new Error("Argument round trip failed");
+console.log("ISA:", artifact.isaRevision, "program bytes:", program.length);

package/docs/examples/evm-execution.ts

@@ -0,0 +1,59 @@
+import { routes } from "@eco-incorp/sauce";
+import { v12EngineAddress, v12KitchenAddress } from "@eco-incorp/sauce/deployments";
+import { v12Kitchen, v12Pot } from "@eco-incorp/sauce/evm/engine";
+import { getAddress, parseAbi, type Address, type Hex, type PublicClient } from "viem";
+
+const portalAbi = parseAbi(["function executor() view returns (address)"]);
+const feeAbi = parseAbi(["function executionFee() view returns (uint256)"]);
+const potKitchenAbi = parseAbi(["function kitchen() view returns (address)"]);
+
+// Call with a client for the destination chain. Importing this example performs no RPC.
+export async function prepareDestinationPot(client: PublicClient, portal: Address, salt: Hex) {
+  const kitchen = getAddress(v12KitchenAddress());
+  const engine = getAddress(v12EngineAddress());
+  const [kitchenCode, engineCode] = await Promise.all([
+    client.getCode({ address: kitchen }),
+    client.getCode({ address: engine }),
+  ]);
+  if (!kitchenCode || kitchenCode === "0x" || !engineCode || engineCode === "0x") {
+    throw new Error("Current Kitchen and engine must be deployed on the destination chain");
+  }
+
+  const executor = await client.readContract({
+    address: portal,
+    abi: portalAbi,
+    functionName: "executor",
+  });
+  const pot = await client.readContract({
+    address: kitchen,
+    abi: v12Kitchen.abi,
+    functionName: "predictPot",
+    args: [executor, salt],
+  });
+  const executionFee = await client.readContract({
+    address: kitchen,
+    abi: feeAbi,
+    functionName: "executionFee",
+  });
+  const context = { kitchen, engine, executor, pot, executionFee };
+  const code = await client.getCode({ address: pot });
+  if (!code || code === "0x") {
+    const deploy = routes.sauceEvmDeployPotCall({ kitchen, owner: executor, salt });
+    // Send this destination-chain request with your signer, wait for a successful receipt,
+    // then call prepareDestinationPot again. Do not build a route until ready is true.
+    return {
+      ...context,
+      ready: false as const,
+      deployment: { to: kitchen, data: deploy.data, value: 0n },
+    };
+  }
+
+  const [owner, actualKitchen] = await Promise.all([
+    client.readContract({ address: pot, abi: v12Pot.abi, functionName: "owner" }),
+    client.readContract({ address: pot, abi: potKitchenAbi, functionName: "kitchen" }),
+  ]);
+  if (getAddress(owner) !== getAddress(executor) || getAddress(actualKitchen) !== kitchen) {
+    throw new Error("Pot must belong to this Portal Executor and the current Kitchen");
+  }
+  return { ...context, ready: true as const };
+}

package/docs/examples/first-intent.ts

@@ -0,0 +1,56 @@
+import { routes, token } from "@eco-incorp/sauce";
+import { toHex } from "viem";
+
+// Offline fixtures. Use prepareDestinationPot from evm-execution.ts before submission
+// to verify the Executor-owned Pot and read the current Kitchen fee.
+const pot = "0x1111111111111111111111111111111111111111";
+const executionFee = 1_000n;
+const baseUsdcValue = routes.registryTokenAddress(Base.chain, "USDC");
+const sourceUsdcValue = routes.registryTokenAddress(Ethereum.chain, "USDC");
+if (baseUsdcValue === undefined || sourceUsdcValue === undefined)
+  throw new Error("Missing USDC registry");
+const baseUsdc = toHex(baseUsdcValue, { size: 20 });
+const sourceUsdc = toHex(sourceUsdcValue, { size: 20 });
+const recipient = 0x2222222222222222222222222222222222222222n;
+const amount = 1_000_000n;
+
+const built = Base(
+  () => {
+    USDC.transfer(recipient, amount);
+  },
+  {
+    execution: {
+      pot,
+      engine: "0x3333333333333333333333333333333333333333",
+      value: executionFee,
+    },
+    nativeAmount: executionFee,
+    portal: "0x4444444444444444444444444444444444444444",
+    sourcePortal: "0x5555555555555555555555555555555555555555",
+    deadline: 2_000_000_000n,
+    // Callbacks capture nothing: explicitly supply every external scalar.
+    defines: { recipient, amount },
+    tokens: [{ token: baseUsdc, amount }],
+    // Route assets arrive at the Executor; the Sauce program spends from the Pot.
+    precalls: [token.Token.transfer({ token: baseUsdc, to: pot, amount }).toCall()],
+  },
+).reward({
+  source: Ethereum.chain,
+  creator: "0x6666666666666666666666666666666666666666",
+  prover: "0x7777777777777777777777777777777777777777",
+  deadline: 2_000_003_600n,
+  tokens: [{ token: sourceUsdc, amount }],
+});
+
+const sourceRequests = [...built.approvals(), built.publishAndFundCalldata(false)];
+if (built.intent.route.calls.length !== 2 || sourceRequests.length !== 2) {
+  throw new Error("Expected destination delivery + cook and source approval + funding");
+}
+if (
+  built.intent.route.calls[1]?.value !== executionFee ||
+  built.intent.route.nativeAmount !== executionFee
+) {
+  throw new Error("Destination funding must include the cook fee");
+}
+console.log("Ethereum → Base intent:", built.hash().intentHash);
+console.log("Prepared source transactions:", sourceRequests.length);

package/docs/examples/protocol-approval.ts

@@ -0,0 +1,33 @@
+import "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+// Offline fixtures. Read the destination Kitchen fee and use an Executor-owned Pot before use.
+const executionFee = 1_000n;
+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,
+});
+
+if (!built.compiled.bytecode[0]?.length || built.intent.route.calls.length !== 1) {
+  throw new Error("Expected a compiled approval and one Pot call");
+}
+if (built.intent.route.calls[0]!.value !== executionFee) {
+  throw new Error("Expected the destination cook to receive its fee");
+}
+console.log("Base approval intent:", built.hash().intentHash);

package/docs/guides/builders-and-actions.md

@@ -0,0 +1,108 @@
+# Builders and actions
+
+[Documentation](../README.md) · [Protocol calls](protocols-and-tokens.md) · [Compiler](../api/compiler.md)
+
+The SDK provides host-language builders for applications that construct programs from data. Token, swap, and deposit builders produce SauceScript source. The actions package accepts a sequence of routing actions and can produce either source or compiled EVM bytecode. None of these builders selects a market route or submits a transaction.
+
+## Token operations
+
+`token.Token` is a host builder. It takes spec objects, while `Token(address).transfer(...)` is syntax inside a compiled EVM route.
+
+```ts
+import { routes, token } from "@eco-incorp/sauce";
+
+export function compileTokenTransfer(
+  asset: token.AddressInput,
+  recipient: token.AddressInput,
+  amount: bigint,
+  execution: routes.SauceEvmExecutionInput,
+) {
+  const operation = token.Token.transfer({ token: asset, to: recipient, amount });
+  const program = operation.toSauceScript("evm");
+  return routes.compileSauceRoute("base", program.source, execution, {
+    baseDirs: [...program.baseDirs],
+  });
+}
+```
+
+`TokenCall.toCall()` instead returns `{ target, data, value }` for a fixed EVM call. Values that require runtime state, such as `amount: "balance"` or balance owner `"self"`, must be compiled. `.statement(target)` emits a transfer/approval statement; `.expression(target)` emits a balance read. `Token.program(specs, { target })` combines several operations into one program.
+
+Use `Token.approve({ token, spender, amount })` for approvals and `Token.balanceOf({ token, owner })` for reads. SVM specs name account references instead of ERC-20 addresses; see [Solana](solana.md).
+
+## Swaps
+
+`swap.swapSource(spec)` generates a program calling the Sauce Router's unified swap entry point. `swap.swapSource([legA, legB])` emits multiple swaps in one program. `swap.toSwapParams(spec)` exposes the normalized parameters, and `swap.swapCallStatement(spec)` produces a statement for composition.
+
+```ts
+import { routes, swap } from "@eco-incorp/sauce";
+
+export function compileSwap(spec: swap.SwapSourceSpec, execution: routes.SauceEvmExecutionInput) {
+  return routes.compileSauceRoute("base", swap.swapSource(spec), execution, {
+    baseDirs: [...swap.SWAP_BASE_DIRS],
+  });
+}
+```
+
+Supply the correct pool, tokens, amount, and pool-specific parameters. The generated program self-calls the Sauce Router path supported by the Pot; the execution deployment must support it. The unified builder supports `UniV2`, `UniV3`, `UniV4`, `Curve`, `BalancerV2`, `DODOV2`, `TraderJoeLB`, `MaverickV2`, and `WOOFi`. The separate Pancake Infinity CL/Bin entry points are not supported by this builder.
+
+The builder normalizes each pool type's amount-sign convention. It does not recover and expose a general `amountOut` value from the swap return. Enforce the intended output with an explicit balance/delta check or a settlement program. A program compiling successfully does not demonstrate correct execution against a specific live pool.
+
+## Deposits, withdrawals, staking, and wrapping
+
+`deposit.depositSource(spec)` emits the protocol call and its required approval. Discover supported pairs with `deposit.listDepositTemplates()`; template coverage is separate from the protocol catalog. Templates include Aave/Spark supply and withdrawal, Compound V3 supply, ERC-4626/Euler deposits, Lido operations, and WETH wrapping/unwrapping.
+
+```ts
+import { deposit, routes } from "@eco-incorp/sauce";
+
+export function compileSupply(
+  pool: deposit.AddressInput,
+  asset: deposit.AddressInput,
+  amount: bigint,
+  execution: routes.SauceEvmExecutionInput,
+) {
+  const source = deposit.depositSource({
+    protocol: "aave-v3",
+    action: "supply",
+    target: pool,
+    token: asset,
+    amount,
+  });
+  return routes.compileSauceRoute("base", source, execution, {
+    baseDirs: [...deposit.DEPOSIT_BASE_DIRS],
+  });
+}
+```
+
+The default approval policy is `"exact"`; `"none"` assumes an existing allowance, and `"max"` grants the maximum allowance. The default beneficiary is the executing contract where the protocol supports it. Native-funded templates require value in the executing Pot and use a call carrying native value.
+
+`amount: "balance"` reads the executing Pot's balance: native ETH for native-funded templates, the WETH `target` for unwrapping, or the supplied `token` for other templates. `deposit.swapThenDepositSource(...)` composes swaps and deposits and also supports `amount: "delta"` for the increase in that balance across the swap block. Standalone deposit source cannot use `"delta"` because it lacks the pre-swap snapshot. Use `deposit.COMPOSED_BASE_DIRS` when compiling composed source.
+
+For Aave/Spark withdrawals, use a fixed underlying-asset amount or `amount: "max"` to withdraw the full position. `"balance"` and `"delta"` read the underlying token held by the Pot, not its supplied position, and should not size a withdrawal.
+
+## Routing actions
+
+Import actions from the published package's `/actions` subpath:
+
+```ts
+import { actionsToSauce, actionsToSauceSource } from "@eco-incorp/sauce/actions";
+import type { RoutingAction } from "@eco-incorp/sauce/actions";
+
+export function buildRoutingProgram(actions: readonly RoutingAction[]) {
+  return {
+    source: actionsToSauceSource(actions),
+    bytecode: actionsToSauce(actions),
+  };
+}
+```
+
+Action variants cover protocol swaps, bridges, wrapping, staking, lending, transfers, and approvals. Each discriminated action specifies concrete addresses and protocol parameters. Keep all actions in a program compatible with the chain where it executes; a `chainId` field does not turn a program into cross-chain execution.
+
+Amount resolution uses this precedence:
+
+1. An explicit amount on the action.
+2. `amountRef`, naming a previously saved output.
+3. The immediately preceding action's output, for implicit chaining.
+
+Set `saveOutputAs` on an action to name its output for later reuse. Saving an output or implicitly chaining the next action can direct the output to the executing Pot and capture it once. Independent actions retain their configured recipients. Quote helpers such as `actionToQuote` construct protocol quote calls; the application performs and interprets the RPC simulation.
+
+`actionsToSauce` returns a single `Uint8Array`. To put already compiled EVM bytecode into a route, convert it to hex (for example, with Viem's `bytesToHex`) and use `routes.buildSauceEvmCall({ pot, engine, program })`; see the [Routes API](../api/routes.md). To produce an Eco cross-chain intent, build the destination program and use the [intent builder](intents.md).