@eco-incorp/sauce 0.99.0 → 0.99.2

package/docs/guides/compiling.md

@@ -0,0 +1,264 @@
+# Compiling programs
+
+[Documentation](../README.md) · [Compiler API](../api/compiler.md) · [SauceScript](../concepts/saucescript.md)
+
+Use the SDK route compiler when a program should become an Eco route call with
+chain-scoped token and protocol names. Use the raw compiler when you need a
+reusable parameterized program, an SVM account manifest, or explicit compiler
+options such as compact arguments.
+
+## Choose a compilation path
+
+| Entry point                                                         | Inputs you supply                                           | What the SDK supplies                                                                              |
+| ------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `Base(body, options)` / `routes.openRoute(...)`                     | Closure or source, intent options, execution addresses      | Chain defines, default ambient `@sauce/token`, registry rewrites, compilation, intent construction |
+| `routes.compileSauceRoute(destination, source, execution, options)` | Source, destination, execution settings                     | Registry rewrites, token defines, compilation, one encoded route call                              |
+| `compile({ target, resolve, ... })`                                 | Complete source/dependency resolution and compiler settings | The published compiler result, including entry metadata and SVM manifest                           |
+
+Bare `USDC`, `Token(address)`, and protocol-member calls are resolved by SDK route
+rewrites. Raw `compile()` expects compiler-native source, such as
+`ERC20.at(address).approve(...)` backed by an ABI import or registered binding.
+
+## Compile an EVM route
+
+This function constructs a call; the caller supplies the deployed Pot,
+compatible engine address, and the Kitchen's current execution fee. It submits
+no transaction.
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+import type { Address } from "viem";
+
+export function buildApprovalRoute(pot: Address, engine: Address, executionFee: bigint) {
+  return routes.compileSauceRoute("base", "USDC.approve(Uniswap.UniversalRouter, 1_000_000n);", {
+    pot,
+    engine,
+    value: executionFee,
+  });
+}
+```
+
+The destination determines registry addresses. The result contains one entry in
+`calls` and the compiled program in `compiled.bytecode[0]`. Inspect `source` to
+see the SDK's rewrites. This approval program spends no native token, so its call
+value is only the execution fee. A program spending native tokens also needs that
+amount in its call value. For Portal fulfillment, the Pot must be owned by the
+destination Portal's Executor, and `route.nativeAmount` must cover the call values.
+Use [the intent guide](intents.md) to read the fee, derive the correctly owned Pot,
+and add source-chain funding, a reward, and Portal publication calldata.
+
+`compileSauceRoute` accepts a bare body or a complete `function main(...)`
+program. Keep route source in the JavaScript syntax accepted by its rewrite
+passes; use raw `compile` for programs that require SauceScript type annotations.
+The raw compiler accepts typed source directly.
+
+## Compile a reusable program
+
+This Node example compiles a program that sums runtime inputs and checks a floor.
+All modules are in memory, so it needs no filesystem resolver.
+
+```ts
+import { compile } from "@eco-incorp/sauce/compiler";
+
+const source = `
+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;
+}
+`;
+
+const entry = new TextEncoder().encode(source);
+const artifact = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve: (path) => (path === "main.ts" ? entry : undefined),
+});
+
+console.log(artifact.isaRevision); // "stack-compact-v2"
+console.log(artifact.entryEncoding); // "abi-v1"
+```
+
+The amount list and minimum have not been supplied yet. Changing those execution
+values does not require recompilation.
+
+### ABI-v1 entry arguments
+
+Encode the `main` arguments in declaration order and append them to the compiled
+program. Entry arguments have no function selector.
+
+```ts
+import { encodeAbiParameters, hexToBytes, bytesToHex } from "viem";
+import { v12Pot } from "@eco-incorp/sauce/evm/engine";
+
+const args = hexToBytes(
+  encodeAbiParameters([{ type: "uint256[]" }, { type: "uint256" }], [[25n, 75n], 100n]),
+);
+
+const payload = new Uint8Array(artifact.bytecode.length + args.length);
+payload.set(artifact.bytecode);
+payload.set(args, artifact.bytecode.length);
+
+// Given a compatible engine address:
+// const data = v12Pot.encodeCook(engine, bytesToHex(payload));
+// Send `data` from the Pot owner with value = executionFee + programNativeValue.
+```
+
+The same byte payload is the `program` argument to `Pot.cook(engine, program)`;
+the outer cook call has its own ordinary contract ABI encoding. Supplying
+argument bytes to the compiler as `defines` would produce a different kind of
+program, specialized to those values.
+
+### Compact-v1 entry arguments
+
+Compile the same source with `compactArgs: true`, then use the returned schema.
+The schema and bytecode belong to the same artifact.
+
+```ts
+import {
+  compile,
+  encodeCompactArguments,
+  decodeCompactArguments,
+} from "@eco-incorp/sauce/compiler";
+
+const compact = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve: (path) => (path === "main.ts" ? entry : undefined),
+  compactArgs: true,
+});
+
+if (compact.entryEncoding !== "compact-v1" || !compact.entrySchema) {
+  throw new Error("Expected a compact argument schema");
+}
+
+const compactArgs = encodeCompactArguments(compact.entrySchema, [[25n, 75n], 100n]);
+const inspected = decodeCompactArguments(compact.entrySchema, compactArgs);
+// inspected: [[25n, 75n], 100n]
+
+const compactPayload = new Uint8Array(compact.bytecode.length + compactArgs.length);
+compactPayload.set(compact.bytecode);
+compactPayload.set(compactArgs, compact.bytecode.length);
+```
+
+A compact program requires an engine implementing its ISA revision. It does not
+accept an ABI-v1 tail, and an ABI-v1 program does not accept compact arguments.
+Compact encoding often reduces scalar and collection payload size, but runtime
+heap, compute, and transaction limits still apply. Its format does not change
+contract ABI calls performed inside the program.
+
+### Encode EVM return values
+
+`entryEncoding` and `compactArgs` describe inputs only. To return data for a host
+ABI decoder, encode it explicitly in SauceScript:
+
+```ts
+function main(): bytes {
+  return abi.encode([1n, 2n, 3n]);
+}
+```
+
+Decode that result as one `uint256[]` with Viem's `decodeAbiParameters`. It is
+160 bytes: an offset, an element count, and three values. The EVM Pot returns
+these bytes directly; do not decode another ABI `bytes` wrapper around them.
+This applies with both ABI-v1 and compact-v1 inputs. SVM has no `abi.encode`
+builtin.
+
+Compiler 2.3.0 changed raw EVM scalar-array literal returns: `return [1n, 2n, 3n]`
+now returns three packed 32-byte values without an ABI offset or count. Compiler
+2.2.1 returned heap descriptors for that source. Raw tuple returns still contain
+heap descriptors. Recompilation can therefore change observable return bytes;
+use explicit `abi.encode` when a caller relies on ABI output.
+
+## Resolve source modules and ABIs
+
+A resolver is synchronous and returns bytes. Missing target-arm candidates must
+return `undefined`; unreadable existing files should fail compilation.
+
+```ts
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { compile } from "@eco-incorp/sauce/compiler";
+
+const root = resolvePath("./programs");
+
+const artifact = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve(path) {
+    try {
+      return readFileSync(resolvePath(root, path));
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+      throw error;
+    }
+  },
+});
+```
+
+This resolver reads files; it is not an isolation boundary for untrusted source.
+Use an allowlisted virtual module map when applications accept user-supplied
+programs. Fetch any remote modules before the synchronous compile step.
+
+For an ABI already held in memory, use raw compiler
+`inlineContracts: [["ERC20", JSON.stringify(abi)]]`. The route API instead accepts
+`contracts: { ERC20: { abi } }` with a parsed ABI and adapts it internally.
+Do not pass the route shape to raw `compile()`.
+
+Raw compiler resolution does not automatically locate the SDK's `@sauce/token`
+copy. SDK route compilation resolves that package itself. With raw compilation,
+provide the package's source and neutral entry mapping through your resolver.
+
+## Compile for SVM
+
+Selecting `target: "svm"` produces an account manifest. For example:
+
+```ts
+import { compile } from "@eco-incorp/sauce/compiler";
+
+const source = new TextEncoder().encode(`
+  function main(vault: Account, amount: Uint256): Uint256 {
+    return amount;
+  }
+`);
+
+const artifact = compile({
+  target: "svm",
+  resolve: (path) => (path === "main.js" ? source : undefined),
+  compactArgs: true,
+});
+
+console.log(artifact.manifest?.accounts);
+// [{ kind: "slot", index: 0, name: "vault", requires: "readonly" }]
+```
+
+The compact root has one field, `amount`; `vault` is attached at account slot 0.
+Resolve and attach accounts in manifest order using the SVM helpers. The manifest
+does not discover an account's address, balance, owner, or liveness.
+
+For staged execution, stage the bytes through the Kitchen, finalize the code
+account, then use the Kitchen client or instruction builders. The SVM
+`routes.compileSauceRoute` path drops the manifest and emits a legacy instruction
+incompatible with the released engine. Use raw compilation for account plans
+and follow the [Solana execution guide](solana.md).
+
+## Keep compilation reproducible
+
+Record the compiler version, target, ISA revision, source/dependency bytes,
+contract ABIs, defines, ambient modules, optimization settings, and argument
+format with an artifact. Keep request arguments separate from the code cache;
+hash the final code-plus-arguments payload when committing to a particular
+execution.
+
+The compiler's function cache is enabled by default. It is an optimization of
+lowering, not an application-level bytecode cache or a dependency resolver.
+`cache: false` forces fresh lowering. If an application mutates cached resolver
+inputs, refresh those inputs and use the compiler package's cache controls as
+needed.
+
+For canonical settle programs, use the shipped recipe source and the pinned
+verification surface described in [settlement verification](verification.md).

package/docs/guides/intents.md

@@ -0,0 +1,158 @@
+# Create and fund an Eco intent
+
+[Documentation](../README.md) · [Routes API](../api/routes.md) · [Nested intents](nested-intents.md)
+
+`Base(body, options).reward(reward)` compiles a program for Base and packages it as an Eco intent. `Base.route(...)` has the same behavior. The destination chain selects the compiler target, token addresses, and protocol deployments.
+
+```ts
+import "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+export function buildApprovalIntent(routeOptions: routes.IntentOptions, reward: routes.RewardArg) {
+  return Base(() => {
+    USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+  }, routeOptions).reward(reward);
+}
+```
+
+The SDK constructs the intent and transaction requests. Your application supplies deployments, funds the source reward, submits transactions, and arranges fulfillment by a solver.
+
+## Source, destination, and funding
+
+An intent has two sides:
+
+| Field                                    | Meaning                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| `Base(...)`                              | Destination chain where the Sauce program executes                |
+| `options.portal`                         | Destination Portal recorded in the route                          |
+| `options.pot`, `options.engine`          | Destination Pot and interpreter used by `cook`                    |
+| `options.tokens`, `options.nativeAmount` | Destination assets delivered by the solver to the Portal Executor |
+| `reward.source`                          | Chain where the reward is funded                                  |
+| `options.sourcePortal`                   | Source Portal used by submission and read helpers                 |
+| `reward.tokens`, `reward.nativeAmount`   | Source assets offered as the reward                               |
+| `reward.creator`, `reward.prover`        | Creator and prover recorded in the reward                         |
+
+Destination route assets initially arrive in the **Executor**. The Sauce program executes in the **Pot**. For an ERC-20 program that spends solver-delivered assets, prepend a token transfer from the Executor to the Pot. Native value reaches the Pot through `execution.value`; declaring `nativeAmount` alone does not forward it into `cook`.
+
+Every EVM `cook` must receive the Kitchen's current `executionFee()` in native wei, including ERC-20-only programs. Set `execution.value` to **fee + native assets the program needs**, and budget `nativeAmount` for the route's calls. The Pot remits the fee before executing; its existing balance cannot replace this payment. Nested transfer programs add another cook and fee. Read the fee before building; an increase before fulfillment can make the route revert.
+
+Deadlines are absolute Unix timestamps in seconds. `route.deadline` limits destination fulfillment. `reward.deadline` allows source refunds when no valid proof exists; leave time for fulfillment and proof delivery before it.
+
+## Prepare the destination Pot
+
+For direct Portal routes, the Pot's owner must be the destination **`Portal.executor()`**. A user-owned or solver-owned Pot rejects the Executor's call with `NotOwner()`.
+
+Use [evm-execution.ts](../examples/evm-execution.ts) on the destination chain to read the Executor, resolve the current Kitchen and engine, predict the Pot, and quote the execution fee. If the Pot is absent, the helper returns a deployment request. Send it, wait for a successful receipt, and run the helper again. Only use a result with `ready: true`, which confirms code is present and checks the Pot's `owner()` and `kitchen()`.
+
+Deployment helpers return release addresses; the historical chain roster does not attest current release liveness.
+
+An Executor-owned Pot can be invoked by other valid Portal routes. Deliver assets, use them, and return leftovers **within the same fulfillment**; do not leave user funds or standing allowances in it. Source reward escrow belongs in the intent vault. These caller and custody rules follow [Eco Routes' Executor calls](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Executor.sol#L50-L74) and [destination fulfillment](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Inbox.sol#L225-L271).
+
+## Build a Base USDC transfer intent
+
+This function takes deployment and reward configuration as inputs. It delivers one USDC on Base to `recipient` and offers the configured source-token reward. It only constructs data.
+
+```ts
+import { token, type routes } from "@eco-incorp/sauce";
+
+interface TransferIntentConfig {
+  pot: routes.AddressInput;
+  engine: routes.AddressInput;
+  executionFee: bigint;
+  destinationPortal: routes.AddressInput;
+  baseUsdc: routes.AddressInput;
+  recipient: routes.AddressInput;
+  source: routes.ChainRef;
+  sourcePortal: routes.AddressInput;
+  rewardToken: routes.AddressInput;
+  rewardAmount: bigint;
+  creator: routes.AddressInput;
+  prover: routes.AddressInput;
+  routeDeadline: bigint;
+  rewardDeadline: bigint;
+}
+
+export function buildBaseTransfer(config: TransferIntentConfig) {
+  const amount = 1_000_000n;
+  const delivery = token.Token.transfer({
+    token: config.baseUsdc,
+    to: config.pot,
+    amount,
+  }).toCall();
+
+  return Base("USDC.transfer(RECIPIENT, AMOUNT);", {
+    execution: { pot: config.pot, engine: config.engine, value: config.executionFee },
+    nativeAmount: config.executionFee,
+    portal: config.destinationPortal,
+    sourcePortal: config.sourcePortal,
+    deadline: config.routeDeadline,
+    tokenDefines: { USDC: config.baseUsdc },
+    defines: { RECIPIENT: BigInt(config.recipient), AMOUNT: amount },
+    tokens: [{ token: config.baseUsdc, amount }],
+    precalls: [delivery],
+  }).reward({
+    source: config.source,
+    creator: config.creator,
+    prover: config.prover,
+    deadline: config.rewardDeadline,
+    tokens: [{ token: config.rewardToken, amount: config.rewardAmount }],
+  });
+}
+```
+
+Use an EVM source when using the Portal submission helpers below; they generate EVM calldata and reject an SVM source. The route model can represent SVM destinations, but the current SVM route emitter is incompatible with the released gated engine.
+
+`executionFee` is the destination Kitchen quote obtained above. The source reward must separately compensate the solver for delivery, fees, and gas; the SDK does not price it.
+
+The explicit `tokenDefines` ensures that the token transferred into the Pot matches the token used by the program. To use the SDK's default Base USDC, resolve it with `routes.registryTokenAddress(Base.chain, "USDC")` and check the result before building. That lookup returns a `bigint`; convert it to a 20-byte hex address with Viem's `toHex(value, { size: 20 })` for intent token fields, as in the [complete example](../examples/first-intent.ts).
+
+## Callbacks are compiled source
+
+A callback is read with `Function.prototype.toString()`, parsed, and compiled as SauceScript. It is never invoked as a JavaScript callback and captures no outer variables. An `amount` in surrounding JavaScript does not become a value inside the program.
+
+Use literals for self-contained callbacks, or source strings plus `defines` for application inputs, as above. Defines accept scalar `bigint`, `number`, or `boolean` values; use `bigint` for addresses and token quantities. `compile.defines` overrides `options.defines`, which overrides chain defaults. Local declarations in the program take precedence over ambient names.
+
+Callbacks must be synchronous and take no parameters. Bound/native functions, generators, and async functions are rejected. If a bundler transforms function source, ship an explicit SauceScript string or source asset. A TypeScript type declaration does not create a captured value.
+
+`Base(...)` adds the SDK's default ambient token module, enabling function forms such as `approve(tokenAddress, spender, amount)`. Direct `compileSauceRoute(...)` does not automatically add that ambient module. The token and protocol member syntax described in [protocols and tokens](protocols-and-tokens.md) is a separate rewrite.
+
+## Submit the source reward
+
+For a built intent, prepare the source-chain requests:
+
+```ts
+import type { routes } from "@eco-incorp/sauce";
+
+export function sourceTransactions(built: routes.BuiltIntent) {
+  return [...built.approvals(), built.publishAndFundCalldata(false)];
+}
+```
+
+Each request is `{ to, data, value }`. Send them from the intended funder on `built.source`, in order, waiting for successful approvals before funding. ERC-20 approvals authorize the **source Portal**, which pulls tokens into the intent vault. Native rewards are included as transaction `value`. `.approvals()` covers only the root reward, even when the intent has children.
+
+`false` selects full funding; use partial funding only when the application deliberately supports it. `publishCalldata()` publishes without funding, and `fundCalldata(allowPartial)` funds separately. These methods do no RPC and send no transactions.
+
+Set `sourcePortal` while building, or pass `{ portal: sourcePortal }` to each helper. The destination `portal` is never silently reused as the submission target.
+
+## Inspect hashes, vaults, and status
+
+`built.hash()` returns `intentHash`, `routeHash`, and `rewardHash`. `built.intent` or `.root()` returns the normalized intent. `.intents()` returns the root and descendants in preorder; it does not imply they execute atomically across chains.
+
+Read helpers return a request plus its decoder:
+
+```ts
+import type { routes } from "@eco-incorp/sauce";
+
+export async function readVault(
+  built: routes.BuiltIntent,
+  ethCall: (request: Pick<routes.PortalReadCall<routes.Hex>, "to" | "data">) => Promise<routes.Hex>,
+) {
+  const request = built.vaultCall();
+  const result = await ethCall({ to: request.to, data: request.data });
+  return request.decode(result);
+}
+```
+
+Execute this read on the source chain. `hashCall()` cross-checks hashes against the Portal; `fundedCall()` checks funding. `predictVault({ portal, vaultInitCodeHash })` provides an offline CREATE2 prediction when you have verified the deployed vault configuration.
+
+The current SVM route emitter produces an older direct-engine instruction and cannot target the released gated engine. Code staging alone does not make those routes executable. See the [Solana guide](solana.md) for supported Kitchen execution and route-helper limitations.

package/docs/guides/nested-intents.md

@@ -0,0 +1,79 @@
+# Nested intents
+
+[Documentation](../README.md) · [Create an intent](intents.md) · [Routes API](../api/routes.md)
+
+`.nest(...)` adds a child intent whose source is the parent's destination. When the parent fulfills, its route funds the child's reward. A solver can fulfill that child in a later transaction on the child's destination chain. Each leg is a separate intent; a failure on a later chain does not roll back a completed parent.
+
+Use the thunk form to receive the parent's destination as the child's source:
+
+```ts
+import "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+export function buildCascade(
+  parentOptions: routes.IntentOptions,
+  childOptions: routes.IntentOptions,
+  parentReward: routes.SauceRewardSpec,
+  childReward: Omit<routes.SauceRewardSpec, "source">,
+  executionFee: bigint,
+) {
+  return Base("return 1n;", parentOptions)
+    .nest(
+      (on) =>
+        Arbitrum("return 1n;", childOptions).reward({
+          ...childReward,
+          source: on,
+        }),
+      { requireCap: true, executionFee },
+    )
+    .reward(parentReward);
+}
+```
+
+The example isolates composition: replace the no-op bodies with your programs. Each options object supplies its destination execution, Portal, deadline, and body cook fee. `executionFee` is the Base Kitchen quote for the additional transfer cook; include it in `parentOptions.nativeAmount` alongside the parent body and any native reward forwarding. Configure `childOptions.sourcePortal` as the Portal on Base. Deliver or earn the child's reward assets in the parent fulfillment before the funding step; see [the Executor-to-Pot example](intents.md#build-a-base-usdc-transfer-intent).
+
+You can also pass an already built child. The SDK checks that its source matches the parent's destination. Both forms produce static children: reward amounts and other hashed fields are fixed before execution. A runtime balance can determine how much is transferred to a child's vault; it does not rewrite the child's reward or hash.
+
+## Default: transfer to the child vault
+
+The fluent API defaults to `via: "transfer"` and `position: "after"`. After the parent program, another Sauce program reads the Pot's balance and transfers assets to the child vault. By default each transfer is capped at the declared child reward amount. Deliver or earn those assets in the same parent fulfillment; do not leave user funds in the Executor-owned Pot between transactions.
+
+| Option                | Default     | Effect                                                                               |
+| --------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `clamp`               | `true`      | Transfer at most the declared child reward amount                                    |
+| `requireCap`          | `false`     | If enabled, revert the parent fulfillment when the Pot cannot cover the cap          |
+| `native`              | `"balance"` | Include the native leg; `"skip"` omits it                                            |
+| `fundNativeFromRoute` | `false`     | Forward the child's declared native reward from route value into the transfer `cook` |
+| `executionFee`        | `0n`        | Additional wei for the merged transfer cook's Kitchen fee                            |
+| `position`            | `"after"`   | Run after the parent body; `"before"` runs before it                                 |
+
+With default `requireCap: false`, a short Pot balance can leave the child underfunded while the parent succeeds. Select `requireCap: true` when full child funding must be a condition of parent fulfillment. With multiple children, transfers consume balances sequentially.
+
+Read the current Kitchen fee and supply `executionFee` for every transfer child. Children merged into one position share one fee and must specify the same value; separate `"before"` and `"after"` cooks each pay. The generated call adds this fee to any `fundNativeFromRoute` reward amounts, so the fee does not reduce the child's funding. Zero works only on a fee-free Kitchen. When a nonzero fee is supplied, the builder checks that `nativeAmount` covers the calls' combined value, excluding publication funding explicitly marked `fundedByBody`.
+
+The default vault resolution calls the Portal from the generated program. Alternatively, pass `vault` after verifying it with `child.vaultCall()`, or pass `vaultConfig` containing the verified `vaultInitCodeHash` for an offline prediction. Explicit `vault` takes precedence over `vaultConfig`.
+
+Transfer funding does not emit a child `IntentPublished` event. Share the built child with your solver or intent-distribution system; an indexer relying only on publication events cannot discover it from such an event.
+
+## Opt in to publication and Portal funding
+
+Use `{ via: "publishAndFund" }` to insert ERC-20 approvals followed by a Portal `publishAndFund` call in the parent route. This mode adds no Sauce cook or Kitchen fee. Those calls run as the Executor, so child reward assets must remain in the Executor or return there from the parent program before publication. `allowPartial` defaults to `false`. Budget the parent's `nativeAmount` for its cook fee, native program spending, and the child's native reward.
+
+The builder checks that declared parent route assets cover child rewards for this mode. Set `fundedByBody: true` only when the parent program actually earns or supplies those assets and makes them available to the Executor. That option skips a static coverage check; it does not move assets.
+
+`allowPartial` and `fundedByBody` belong to publication mode. `vault`, `vaultConfig`, `clamp`, `requireCap`, `native`, `fundNativeFromRoute`, `executionFee`, `pot`, `engine`, and `compile` belong to transfer mode. Mixing mode-specific options throws.
+
+## Ordering and constraints
+
+The current call order is:
+
+1. Parent `precalls`.
+2. Children positioned `"before"`.
+3. The parent's compiled program.
+4. Children positioned `"after"`.
+
+Within either position group, publication-mode calls precede the merged transfer program. Transfer children execute in their `.nest()` order inside that program. Do not depend on an interleaving of different funding modes. Transfer children merged into one position must use the same Pot, engine, and execution fee.
+
+The builder enforces an EVM parent destination, matching parent-destination/child-source chains, and child route and reward deadlines at least as late as the parent route deadline. The codec accepts SVM children, but the [built-in SVM Sauce route is incompatible with the released engine](solana.md#svm-destinations-in-eco-intents). Duplicate direct-child intent hashes are rejected; use distinct salts for otherwise identical children. The default salt is zero, so separate construction alone does not create a distinct intent.
+
+`.intents()` lists the root and descendants in preorder, while `.children` lists direct children. Store the whole cascade if your application must distribute every leg. The root's approval helpers fund only the root; child funding is part of parent fulfillment.

package/docs/guides/protocols-and-tokens.md

@@ -0,0 +1,116 @@
+# Protocols and tokens
+
+[Documentation](../README.md) · [Quick start](quick-start.md) · [Coverage](../api/coverage.md)
+
+Within an EVM route, token symbols and protocol names resolve against the destination chain:
+
+```js
+USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+```
+
+`USDC` resolves to the chain's registered token address. `Uniswap.UniversalRouter` resolves to the registered contract address when used as an argument, and exposes its ABI methods when used as a call target. Amounts are integers in the token's smallest units; the SDK does not infer decimal conversions.
+
+## Compile a global call
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+
+export function compileApproval(pot: routes.AddressInput, engine: routes.AddressInput) {
+  return routes.compileSauceRoute("base", "USDC.approve(Uniswap.UniversalRouter, 1_000_000n);", {
+    pot,
+    engine,
+  });
+}
+```
+
+The returned `calls` encode an EVM Pot `cook`; this function does not submit a transaction. The same body can be a callback to `Base(() => { ... }, options).reward(...)`; see [creating intents](intents.md).
+
+The supported Universal Router spelling is `UniswapV4.UniversalRouter`, or the unambiguous family alias `Uniswap.UniversalRouter`. `UniswapV3.UniversalRouter` is not registered. The router's `execute` method takes the arguments declared by its ABI; the namespace does not construct swap commands or select a route for you.
+
+## Which names exist?
+
+The protocol catalog, contract descriptors, token registry, and SVM venue registry provide different coverage. A catalog entry does not automatically provide a callable contract namespace. [Coverage](../api/coverage.md) lists what is registered.
+
+```ts
+import { contracts, getProtocol, routes } from "@eco-incorp/sauce";
+
+const protocol = getProtocol("uniswap-v4");
+const descriptors = contracts.listDescriptors();
+const router = contracts.on("base").UniswapV4.UniversalRouter;
+const baseTokens = routes.knownTokenSymbols(routes.chain("base").chain);
+
+console.log(protocol, descriptors.length, router.available, baseTokens);
+```
+
+Contract accessors expose `address`, `available`, `chains`, `abi`, `methods`, and `coverage`. A namespace's presence does not establish deployment on every chain. A call to a registered contract with no deployment on the selected chain fails during construction or compilation.
+
+Versioned names are explicit: `UniswapV2.Factory` and `UniswapV3.Factory` select different descriptors. A family alias only resolves a contract name when it identifies one descriptor; `Uniswap.Factory` is ambiguous and fails. A protocol with a single default contract also permits the shorter `Protocol.method(...)` form.
+
+## Token methods and balances
+
+These are SauceScript route-body fragments:
+
+```js
+USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
+let available = USDC.balanceOf(self);
+```
+
+For a token absent from the registry, use `Token(address)`:
+
+```js
+Token(0x1111111111111111111111111111111111111111n).approve(Uniswap.UniversalRouter, 1_000_000n);
+```
+
+Replace that illustrative address with your ERC-20. The wrapper accepts a literal, a local variable, or a compile-time define. The token member syntax supports `transfer`, `approve`, and `balanceOf`. Use an explicit ABI binding for additional ERC-20 methods. The shorthand `self.USDC` reads the executing contract's balance; `USDC.balanceOf(self)` makes the same intent explicit. `self` refers to the executing contract, which is the Pot in the EVM route path.
+
+Use `tokenDefines` on an intent to add or override symbols, or `tokens` on `compileSauceRoute`'s compile options. Overrides merge per symbol with the registry. These maps contain **addresses**; `IntentOptions.tokens` instead declares the **token amounts** a solver must deliver for the route.
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+
+export function compileCustomTokenApproval(
+  pot: routes.AddressInput,
+  engine: routes.AddressInput,
+  asset: routes.AddressInput,
+) {
+  return routes.compileSauceRoute(
+    "base",
+    "ASSET.approve(Uniswap.UniversalRouter, 100n);",
+    { pot, engine },
+    { tokens: { ASSET: asset } },
+  );
+}
+```
+
+Custom symbol names work in source strings. The package's generated TypeScript declarations cover registered names; applications authoring callbacks with additional names must supply their own declarations. A declaration provides a type, while the token map provides the address used by the compiler.
+
+## Route source and host JavaScript
+
+Importing the package installs real chain globals such as `Base` and `Solana`, plus the host `Token` builder. The package also supplies TypeScript declarations for bare route names such as `USDC` and `Uniswap`. Those bare names are **route syntax**: there is no host JavaScript `USDC` or `Uniswap` object to execute.
+
+Use a side-effect import, `import "@eco-incorp/sauce"`, when relying on installed globals. A type-only import does not install them, and TypeScript can erase a named import used only for types.
+
+Outside a route, `Base.UniswapV4.UniversalRouter` or `contracts.on("base").UniswapV4.UniversalRouter` is a real host accessor. Its methods return inert `ContractCall` objects. A call can provide encoded `data`, `.toCall()` for `{ target, data, value }`, or `.toSauceScript()` for source and import paths. Host accessor methods currently have the static type `unknown`; use an explicit signature when invoking one in TypeScript:
+
+```ts
+import { contracts } from "@eco-incorp/sauce";
+
+const router = contracts.on("base").UniswapV4.UniversalRouter;
+const execute = router.execute as (
+  commands: `0x${string}`,
+  inputs: readonly `0x${string}`[],
+  deadline: bigint,
+) => contracts.ContractCall;
+```
+
+That declaration does not build or send a swap. Supply valid Universal Router commands before calling it. For ordinary ERC-20 operations from host code, the typed `token.Token.transfer({ ... })` and `.approve({ ... })` builders are usually more convenient; see [builders and actions](builders-and-actions.md).
+
+## Chain selection and ABI bindings
+
+A bare protocol reference uses the enclosing destination. A qualified reference such as `Ethereum.UniswapV4.UniversalRouter` selects an address from Ethereum's registry. It does **not** move execution to Ethereum: the resulting call still executes on the enclosing route's chain. Use separate intents and [nesting](nested-intents.md) for cross-chain execution. Set `compile.accessors.chainScope` to restrict explicitly qualified chain names when needed.
+
+Route rewriting rejects missing methods, ambiguous aliases, missing deployments, and descriptors marked with widened ABI types. A widened ABI can produce a selector different from the deployed contract. Inspect `coverage` and use the exact ABI for that deployment; opting past the check does not repair the ABI.
+
+To call a contract outside the descriptor registry, supply an ABI binding through `compile.contracts` or a resolved ABI import, then call `Binding.at(address).method(...)` in source. See [compiler integration](../api/compiler.md). Host `.at(address)` rebinding and SauceScript ABI `.at(address)` are separate APIs; the global protocol rewrite does not provide arbitrary `.at(...)` chains.
+
+The token and EVM protocol rewrites apply to EVM routes. Solana uses account parameters and venue adapters, covered in the [Solana guide](solana.md).