@eco-incorp/sauce 0.99.6 → 0.99.7

package/docs/api/router.md

@@ -0,0 +1,238 @@
+# `@sauce/router`
+
+[Documentation](../README.md) · [SauceScript](../concepts/saucescript.md) · [Actions](../guides/actions.md)
+
+`@sauce/router` is a SauceScript library for swapping: one function per venue. Every function takes
+its pool, tokens and amount as **run-time arguments**, so a program can choose them while it runs —
+spend what an earlier call returned, read a balance, loop over a list of pools — and every function
+returns the amount of `tokenOut` the recipient received.
+
+```js
+import { curve, uniswapV2 } from "@sauce/router";
+import { balanceOf } from "@sauce/token";
+
+// Base: sell every WETH the Pot holds on Uniswap V2, then the USDC that returns for crvUSD in
+// Curve's 4pool, and keep it. The amounts are only known when this runs; MIN_OUT is a define.
+function main() {
+  const weth = 0x4200000000000000000000000000000000000006n;
+  const usdc = 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913n;
+  const crvusd = 0x417ac0e078398c154edfadd9ef675d30be60af93n;
+  const pair = 0x88a43bbdf9d098eec7bceda4e2494615dfd9bb9cn; // Uniswap V2 WETH/USDC
+  const fourPool = 0xf6c5f01c7f3148891ad0e19df78743d31e390d1fn; // USDC is coin 0, crvUSD 3
+
+  const sold = balanceOf(weth, ctx.self());
+  const received = uniswapV2(pair, weth, usdc, sold, 3000n, 0n, ctx.self());
+  curve(fourPool, usdc, crvusd, received, 0n, 3n, false, MIN_OUT, ctx.self());
+}
+```
+
+The SDK carries the library and serves it to every compile it makes — a route body, an intent, an
+[action program](../guides/actions.md) — so an import is all a program needs. [router-swap.ts](../examples/router-swap.ts)
+compiles this one.
+
+It is the one implementation of a swap at these venues: an action such as `uniswapV2Swap` is a
+call into it, so a JSON action program and a hand-written program trade a venue through the same
+code. It runs on EVM chains only.
+
+## Functions
+
+Every function takes its arguments in one order — the pool, the two tokens, the amount, then the
+venue's own facts, then the floor and the recipient — and returns the amount received:
+
+```text
+venue(pool, tokenIn, tokenOut, amountIn, ...facts, minOut, recipient): Uint256
+```
+
+| Function      | Arguments                                                                                                 | Reached through  |
+| ------------- | --------------------------------------------------------------------------------------------------------- | ---------------- |
+| `uniswapV2`   | `pair, tokenIn, tokenOut, amountIn, feePpm, minOut, recipient`                                            | the pair         |
+| `uniswapV3`   | `pool, tokenIn, tokenOut, amountIn, sqrtPriceLimitX96, minOut, recipient`                                 | the Pot's Router |
+| `uniswapV4`   | `poolManager, tokenIn, tokenOut, amountIn, fee, tickSpacing, hooks, sqrtPriceLimitX96, minOut, recipient` | the Pot's Router |
+| `curve`       | `pool, tokenIn, tokenOut, amountIn, i, j, uint256Indices, minOut, recipient`                              | the pool         |
+| `balancerV2`  | `vault, tokenIn, tokenOut, amountIn, poolId, minOut, recipient`                                           | the Vault        |
+| `dodoV2`      | `pool, tokenIn, tokenOut, amountIn, baseToken, quoteToken, minOut, recipient`                             | the pool         |
+| `traderJoeLB` | `pair, tokenIn, tokenOut, amountIn, tokenX, tokenY, minOut, recipient`                                    | the pair         |
+| `woofi`       | `pool, tokenIn, tokenOut, amountIn, minOut, recipient`                                                    | the WooPPV2      |
+| `maverickV2`  | `pool, tokenIn, tokenOut, amountIn, minOut, recipient`                                                    | the Pot's Router |
+
+and four `try` forms with the same arguments as the function they name: `tryUniswapV2`, `tryCurve`,
+`tryBalancerV2` and `tryTraderJoeLB` — see [what a swap may not do](#what-a-swap-may-not-do).
+
+Addresses are `Address`, amounts and the other numbers `Uint256`, and `uint256Indices` a `bool`.
+
+- **`amountIn`** is what the Pot pays. Every swap is **exact input**; nothing here expresses an
+  exact-output swap.
+- **`minOut`** is the least the swap may deliver; below it the whole program reverts. `0n` sets no
+  floor, except for `woofi`, which requires a positive one. Where the venue enforces a floor
+  itself — Curve's `min_dy`, the Balancer Vault's `limit`, WooPPV2's `minToAmount` — `minOut` is
+  that floor; otherwise the function checks it against the amount the venue reports.
+- **`recipient`** receives the output; `ctx.self()` keeps it in the Pot.
+- **The return value** is what the recipient received: the amount the pool or the Router reports,
+  or, for Curve, whose 3pool-era pools report nothing, the Pot's balance change.
+
+## How each venue is reached
+
+Uniswap V2 and its forks, Curve, Balancer V2, DODO V2, Trader Joe LB and WOOFi never call back:
+each function pays the pool and calls it directly, so it runs in any Pot. It either pushes the input
+first (V2, DODO, LB, WOOFi) or approves exactly the input for the pool to pull (Curve, the Vault),
+which leaves a zero allowance.
+
+Uniswap V3 and its forks, Uniswap V4 and Maverick V2 pools re-enter their caller mid-swap to be
+paid, which a program cannot answer. Those functions call the Pot's Router — `ctx.self()`, whose
+fallback delegatecalls it — and the Router answers the callback, paying from the Pot exactly what
+the pool asks for, up to `amountIn`. It also checks the pool's own tokens against `tokenIn` and
+`tokenOut`. Synthra V3 and UnitFlow V3 pools call back under their own names, which only a
+generation-3 Router answers: on an older one the swap reverts. A Pot runs the Router it was minted
+with until its owner moves it; see [the Pot's Router](../concepts/architecture.md#a-pots-router).
+
+Every token write is `@sauce/token`'s, with OpenZeppelin `SafeERC20` semantics: a token that
+returns nothing (USDT) works, one that returns `false` reverts the program, and a standing
+allowance is reset to zero before a new one is set.
+
+## Direction and orientation
+
+Each function works out which side it trades from its own arguments, while the program runs, and
+reverts rather than trade a side the arguments contradict:
+
+- a Uniswap V2 pair's direction is the sort order of `tokenIn` and `tokenOut` — its `token0` is the
+  lower address — and so is a Uniswap V4 pool's;
+- `dodoV2` takes the pool's `baseToken` and `quoteToken`, sells base when `tokenIn` is the base
+  token and quote when it is the quote token, and reverts unless the two tokens are those two. The
+  side cannot come from address order, and the wrong one does not revert at the pool: it prices the
+  side it was told to sell, sees none of it, and keeps the input;
+- `traderJoeLB` takes the pair's `tokenX` and `tokenY` the same way;
+- the Router checks a V3 or Maverick pool's tokens itself.
+
+The facts are the caller's, like the pool address: take them from the pool.
+
+## What a swap may not do
+
+**A swap consumes its whole input or reverts; nothing is refunded.** Each pay-first pool spends all
+it is paid or reverts — a V2 pair and a DODO V2 pool book their whole balance, an LB pair reverts
+`LBPair__OutOfLiquidity` rather than fill part of an input, WooPPV2 books exactly the amount pushed —
+and only an uncaught revert unwinds a push. So no function catches its pool's failure after paying
+it. (Through the Router, a price limit or a pool that runs out can leave part of `amountIn` unspent;
+it stays in the Pot.)
+
+The `try` forms are the one way to get a swap that may fail without reverting the program, and they
+lose nothing either: a `try` that cannot swap returns `0n` having moved nothing, and the program
+goes on. Each exists only where that can be guaranteed:
+
+- `tryUniswapV2` and `tryTraderJoeLB` check, before anything moves, that the pool fills the whole
+  input at the floor — the V2 reserves, LB's `getSwapOut` — and otherwise run uncaught, so a failure
+  the check did not foresee still reverts;
+- `tryCurve` and `tryBalancerV2` catch the pool's failure and reset the approval to zero.
+
+DODO V2 and WOOFi offer neither, so they have no `try` form. A swap that ran returns at least 1, so
+`0n` always means skipped.
+
+## Venues
+
+- **Uniswap V2** prices the output from the pair's reserves with the Sauce Router's own
+  constant-product math and takes exactly that, so the pair's K check holds for a correctly stated
+  fee and reverts for one stated too low. `feePpm` is the pair's LP fee in parts per million: 3000
+  (0.30%) for Uniswap V2 and its forks that charge it, which `0n` also means; 2500 for PancakeSwap
+  V2; 1,000,000 or more reverts. An input past the reserve's `uint112` width reverts at the pair.
+- **Uniswap V3** sends `amountIn` positive, the pool's exact-input sign. A non-zero
+  `sqrtPriceLimitX96` stops the swap at that price.
+- **Uniswap V4**'s pool key is `tokenIn` and `tokenOut` in sort order — native ETH is the zero
+  address, which sorts first and which the Pot pays from its own balance — with the pool's `fee`,
+  `tickSpacing` and `hooks`. V4 reads a negative amount as exact input, so the function passes
+  `-amountIn`: unary negation, never `0n - amountIn`, which reverts for any non-zero amount.
+- **Curve** calls the pool's 4-argument `exchange(i, j, dx, min_dy)`. `uint256Indices` picks the
+  CryptoSwap spelling over the StableSwap and NG one (`int128` indices). The pool pays the Pot, which
+  forwards the output when `recipient` is not the Pot.
+- **Balancer V2** swaps GIVEN_IN through the chain's Vault, `0xBA12222222228d8Ba445958a75a0704d566BF2C8`
+  where Balancer deployed it, with `poolId` the pool's 32-byte id and internal balances off.
+- **DODO V2** covers DVM, DPP and DSP pools. Legacy V1 pairs are the `dodoV1Swap` action's.
+- **Trader Joe LB** amounts are `uint128`.
+- **WOOFi** is the WooPPV2 itself, not its WooRouterV2. It prices from an oracle, so `minOut` is
+  required, and it reverts when its reserve, notional cap or oracle refuses the trade.
+- **Maverick V2** swaps over the pool's full tick range.
+
+## Choose the venue at run time
+
+Because every argument is a run-time value, one compiled program can serve every route over a set
+of venues: give it the legs as arguments, and let it pick each function as it goes.
+
+```js
+import { balancerV2, curve, uniswapV2, uniswapV3 } from "@sauce/router";
+
+// One compiled program for any route over four venues: each leg names its venue, pool and tokens,
+// and the program picks the function while it runs, spending what the previous leg returned.
+interface Leg {
+  venue: Uint256; // 0 Uniswap V2, 1 Uniswap V3, 3 Curve, 4 Balancer V2
+  pool: Address; // the pair, the pool, or the Balancer Vault
+  tokenIn: Address;
+  tokenOut: Address;
+  i: Uint256; // Curve's coin indices
+  j: Uint256;
+  poolId: Uint256; // Balancer's pool id
+}
+
+function main(legs: Leg[], amountIn: Uint256, minOut: Uint256): Uint256 {
+  let out = amountIn;
+  for (let k = 0; k < legs.length; k = k + 1) {
+    const leg = legs[k];
+    if (leg.venue == 0n) {
+      out = uniswapV2(leg.pool, leg.tokenIn, leg.tokenOut, out, 0n, 0n, ctx.self());
+    } else if (leg.venue == 1n) {
+      out = uniswapV3(leg.pool, leg.tokenIn, leg.tokenOut, out, 0n, 0n, ctx.self());
+    } else if (leg.venue == 3n) {
+      out = curve(leg.pool, leg.tokenIn, leg.tokenOut, out, leg.i, leg.j, false, 0n, ctx.self());
+    } else {
+      out = balancerV2(leg.pool, leg.tokenIn, leg.tokenOut, out, leg.poolId, 0n, ctx.self());
+    }
+  }
+  require(out >= minOut);
+  return out;
+}
+```
+
+[router-route.ts](../examples/router-route.ts) compiles it once and appends a route as its
+arguments. Nothing about the legs is known to the compiler, so the bytecode — and its hash — is the
+same for every route.
+
+## From JSON
+
+Each [action](../guides/actions.md#swaps) at these venues is a call into this library with the
+action's fields as its arguments. Inside an action program, a swap whose output a later action
+spends delivers to the Pot. Its tokens and contracts may be names (`"USDC"`, `"UniswapV3.Factory"`),
+which are the program globals of those names, and three may name their pool by key instead of
+`pool`: the program reads the pool from the factory and passes it to the function
+([pools by key](../guides/actions.md#pools-by-key)).
+
+| Action            | Function      | Facts it carries                                                                      |
+| ----------------- | ------------- | ------------------------------------------------------------------------------------- |
+| `uniswapV2Swap`   | `uniswapV2`   | `pool` or `factory`, optional `feePpm`                                                |
+| `uniswapV3Swap`   | `uniswapV3`   | `pool`, or `factory` + `fee` or `tickSpacing`; optional `sqrtPriceLimitX96`           |
+| `uniswapV4Swap`   | `uniswapV4`   | `poolManager`, `fee`, `tickSpacing`, optional `hooks` and `sqrtPriceLimitX96`         |
+| `curveSwap`       | `curve`       | `pool`, `i`, `j`, `indexType` (`"int128"` or `"uint256"`)                             |
+| `balancerV2Swap`  | `balancerV2`  | `vault`, `poolId`                                                                     |
+| `dodoV2Swap`      | `dodoV2`      | `pool`, `baseToken`, `quoteToken`                                                     |
+| `traderJoeLBSwap` | `traderJoeLB` | `pool` or `factory` + `binStep`; `tokenX`, `tokenY`, read from the pair when left out |
+| `woofiSwap`       | `woofi`       | `pool`                                                                                |
+| `maverickV2Swap`  | `maverickV2`  | `pool`                                                                                |
+
+## Compile it yourself
+
+`compileSauceRoute`, the chain helpers, `openRoute` and the actions package resolve `@sauce/router`
+with no option. A raw `compile()` resolves it through the SDK's own resolvers, which serve the
+library, the `@sauce/token` it imports and the pool ABIs it binds from memory:
+
+```ts
+import { compile, resolveSdkModule, resolveSdkPackage } from "@eco-incorp/sauce/compiler";
+
+export function compileWithRouter(source: string) {
+  const entry = new TextEncoder().encode(source);
+  return compile({
+    target: "evm",
+    resolve: (path) => (path === "main.js" ? entry : resolveSdkModule(path)),
+    resolvePackage: (specifier) => resolveSdkPackage(specifier),
+  });
+}
+```
+
+The package also ships the library's files under `sdk/dist/std/router/`, beside `@sauce/token`'s,
+for a toolchain that resolves packages off disk. There is no SVM arm: importing `@sauce/router` for
+the SVM fails at the import.

package/docs/api/routes.md

@@ -26,9 +26,9 @@ There is no `/routes` subpath. The public types are members of the namespace: `r
 
 Chain references accept canonical slugs, names/aliases supported by the registry, numeric chain IDs, and canonical chain records. `.chain` exposes the canonical record.
 
-`Base` and every other chain are **named exports of the package root**; importing the package installs nothing on `globalThis`. A root-imported accessor is the composed one, which also exposes host contract and venue accessors (`Base.Uniswap.UniversalRouter`, `Solana.RaydiumCpSwap`); `routes.chainAccessors.Base` is the bare route entry point without that tree. A host that wants the bare names at run time can call `installRouteGlobals()`; `uninstallRouteGlobals()` reverses it, and neither installs TypeScript declarations.
+`Base` and every other chain are **named exports of the package root**; importing the package installs nothing on `globalThis`. A root-imported accessor is the composed one, which also exposes host contract and venue accessors (`Base.Uniswap.UniversalRouter`, `Solana.RaydiumCpSwap`) and the chain's registry tokens (`Base.USDC`), described in the [contracts reference](contracts.md); `routes.chainAccessors.Base` is the bare route entry point without them. A host that wants the bare names at run time can call `installRouteGlobals()`; `uninstallRouteGlobals()` reverses it, and neither installs TypeScript declarations.
 
-`body` accepts a source string or a synchronous zero-argument callback. A string can contain a full `function main(...)` or a bare body. A callback supplies source text, with no JavaScript capture. See [callback semantics](../guides/intents.md#callbacks-are-compiled-source).
+`body` accepts a source string or a synchronous zero-argument callback. A string is a SauceScript file, compiled as written: a module declaring `function main(...)`, or a script whose top-level statements are the entry. A script cannot `return`, so a program that returns a value declares `main`. A callback supplies source text, with no JavaScript capture. See [callback semantics](../guides/intents.md#callbacks-are-compiled-source).
 
 ## Intent options
 
@@ -59,7 +59,7 @@ The compiler needs no source reward to compile a destination program. Use `compi
 import { routes } from "@eco-incorp/sauce";
 
 export function compileProgram(execution: routes.SauceEvmExecutionInput) {
-  return routes.compileSauceRoute("base", "return 7n;", execution);
+  return routes.compileSauceRoute("base", "function main() { return 7n; }", execution);
 }
 ```
 
@@ -69,11 +69,11 @@ export function compileProgram(execution: routes.SauceEvmExecutionInput) {
 | ---------- | --------------------------------------------------------------------- |
 | `calls`    | Destination call inputs, normally one call for one program            |
 | `compiled` | Route compatibility result with `bytecode: Uint8Array[]` and warnings |
-| `source`   | Source after wrapping and SDK token/protocol rewrites                 |
+| `source`   | Source after the SDK token/protocol rewrites                          |
 
 The route wrapper differs from the direct `/compiler` API, which returns one byte array plus compiler metadata and an optional SVM account manifest. Use the direct API when you need that metadata. The route target defaults to `"v12"` for EVM and `"svm"` for SVM; direct compiler targets are `"evm"` and `"svm"`.
 
-`SauceCompileOptions` supports `resolve` and `resolvePackage` for the program's own imports, scalar `defines`, token-address `tokens`, ABI `contracts`, `ambient` module names, and `accessors`. `resolve` has the [compiler's resolver contract](compiler.md#resolver-contract) and is asked for any path the program imports; the SDK itself serves `@sauce/token`, `./artifacts/IERC20.json`, `./artifacts/ISauceRouter.json` and every `./protocols/<slug>/<Export>.json`, so source from the SDK's builders needs neither option. Accessor rewriting defaults on; an options object can configure qualified-chain scope or other rewrite behavior. `openRoute` merges chain defaults and the default ambient token module. Direct `compileSauceRoute` performs token/protocol rewrites but does not automatically merge that ambient module.
+`SauceCompileOptions` supports `resolve` and `resolvePackage` for the program's own imports, scalar `defines`, token-address `tokens`, ABI `contracts`, `ambient` module names, and `accessors`. `resolve` has the [compiler's resolver contract](compiler.md#resolver-contract) and is asked for any path the program imports; the SDK itself serves `@sauce/token`, `./artifacts/IERC20.json`, `./artifacts/ISauceRouter.json` and every `./protocols/<slug>/<Export>.json`, so source from the SDK's builders needs neither option. Accessor rewriting defaults on; an options object can configure qualified-chain scope or other rewrite behavior. `openRoute` adds each chain's defaults — its token symbols, `chainId` and protocol addresses, taken separately for every chain an intent written in the program names — and the default ambient token module. A `defines` or `tokens` entry under one of those chain-scoped names belongs to the chain the program compiles for: an intent's body on another chain uses that chain's value instead ([names resolve per chain](../guides/intents.md#names-resolve-per-chain)). Direct `compileSauceRoute` performs token/protocol rewrites but does not automatically merge that ambient module.
 
 The route wrapper has no runtime argument-payload parameter. Use compile-time defines here, or direct compilation and a suitable execution API for parameterized entry points; see [compiler integration](compiler.md).
 
@@ -81,34 +81,43 @@ The route wrapper has no runtime argument-payload parameter. Use compile-time de
 
 `buildSauceEvmCall({ pot, engine, program, value? })` builds one Pot `cook` call; `program` is a hex string. `value` defaults to zero and must include the Kitchen fee. `buildSauceEvmCalls({ pot, engine, cooks, value? })` applies that value to **each** ordered cook. Multiple statements within one program need only one cook and fee.
 
+Both builders, and `sauceEvmDeployPotCall` below, return `{ to, target, data, value }`. `{ to, data, value }` is the request a wallet sends or `client.call` takes, the same shape as `destinationExecutionFee()` and the Portal transaction builders; `to` is the contract's checksummed 20-byte address. `target` names the same contract as a route's `calls` entry (the Portal's `Call` struct) records it, a 32-byte universal address for a cook, so the object goes into `RouteInput.calls` unchanged. `value` is a `bigint`.
+
 ## Deployment addresses
 
-`sauceEvmDeployPotCall({ owner, salt, kitchen })` encodes Pot deployment through the Kitchen you name; for a direct intent route the owner is the destination `Portal.executor()`. No route the SDK builds includes this call. To deploy an intent's shared Pot yourself before the solver does, pass `kitchen: v12GateKitchen()`, that Executor, and `SAUCE_INTENT_POT_SALT`.
+`sauceEvmDeployPotCall({ owner, salt, kitchen? })` encodes Pot deployment through a Kitchen, by default the released one (`v12KitchenAddress()`); for a direct intent route the owner is the destination `Portal.executor()`. No route the SDK builds includes this call. To deploy an intent's shared Pot yourself before the solver does, pass that Executor and `SAUCE_INTENT_POT_SALT`.
 
-Every address helper here returns a **recorded** address, never a verified one. `v12EngineAddress()` and `v12KitchenAddress()` give the released addresses directly and are the ones to prefer. `sauceEvmDeployPotCall`'s `chainId` form, `v12Deployment` and `requireV12Deployment` filter by a roster of chains where deployment previously succeeded, which is a different question from whether code is there now. `V12_EVM_CONTRACTS` and `v12SvmProgramId` name an earlier deployment generation. Check the chain before trusting any of them; [evm-execution.ts](../examples/evm-execution.ts) shows prediction, deployment and the owner/Kitchen checks.
+Every address helper here returns a **recorded** address, never a verified one. `v12EngineAddress()` and `v12KitchenAddress()` give the released addresses, the same on every chain; the SDK reads no chain, so it cannot say whether code is there. Check the chain before trusting any of them; [evm-execution.ts](../examples/evm-execution.ts) shows prediction, deployment and the owner/Kitchen checks.
 
 `buildSauceSvmCall` and the SVM route path emit an 8-byte engine instruction that the Solana engine does not accept, whatever code account or engine id you give them: they do not build the Kitchen call the engine requires. Build Solana execution with the Kitchen client instead — see [SVM destinations in Eco intents](../guides/solana.md#svm-destinations-in-eco-intents).
 
 ## Built intents
 
-| Member                                      | Behavior                                                            |
-| ------------------------------------------- | ------------------------------------------------------------------- |
-| `intent`, `root()`                          | Normalized head intent                                              |
-| `source`, `destination`                     | Canonical chain records                                             |
-| `compiled`                                  | Head destination program's compilation result                       |
-| `children`                                  | Direct nested children                                              |
-| `intents()`                                 | Root-first preorder traversal of all intents                        |
-| `hash()`                                    | Intent, route, and reward hashes                                    |
-| `encodeEVM()`, `encodeSVM()`                | Explicit codec serialization of route and reward                    |
-| `approvals()`                               | EVM approval requests for the head reward                           |
-| `publishCalldata()`                         | Source Portal publication request                                   |
-| `publishAndFundCalldata(allowPartial)`      | Publication and funding request                                     |
-| `fundCalldata(allowPartial)`                | Funding request                                                     |
-| `vaultCall()`, `hashCall()`, `fundedCall()` | Source Portal read request plus result decoder                      |
-| `predictVault(config)`                      | Offline CREATE2 prediction with caller-provided vault configuration |
+| Member                                        | Behavior                                                           |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `intent`, `root()`                            | Normalized head intent                                             |
+| `source`, `destination`                       | Canonical chain records                                            |
+| `compiled`                                    | Head destination program's compilation result                      |
+| `children`                                    | Direct nested children                                             |
+| `intents()`                                   | Root-first preorder traversal of all intents                       |
+| `hash()`                                      | Intent, route, and reward hashes                                   |
+| `encodeEVM()`, `encodeSVM()`                  | Explicit codec serialization of route and reward                   |
+| `sourceTxs({ fundVia, vault, allowPartial })` | The head reward's funding and publication, in order                |
+| `approvals()`                                 | EVM approval requests for the head reward                          |
+| `publishCalldata()`                           | Source Portal publication request                                  |
+| `publishAndFundCalldata(allowPartial)`        | Publication and funding request                                    |
+| `fundCalldata(allowPartial)`                  | Funding request                                                    |
+| `vaultCall()`, `hashCall()`, `fundedCall()`   | Source Portal read request plus result decoder                     |
+| `predictVault(config?)`                       | Offline CREATE2 prediction; eco-routes' derivation unless `config` |
 
 Submission and read helpers take an optional `{ portal }` override; without one they use `sourcePortal`, which itself defaults to the eco-routes Portal for the reward's source chain. They build EVM requests, require an EVM source, and perform no RPC — you send them. The codec represents an SVM destination fine; building that execution is the separate matter above. `encodeEVM()`/`encodeSVM()` force a codec for inspection; they do not change an intent's chain kinds.
 
+`sourceTxs()` funds by transfer by default: a `transfer` of each reward token to the intent's vault, a plain send of the native amount, then `publish`. Pass `vault` as `vaultCall()` read it; it must equal `predictVault()` or `IntentVaultMismatchError` is thrown. `fundVia: "publishAndFund"` (or `IntentOptions.fundVia`, which also selects it for the intents the route's own program opens) returns `approvals()` then `publishAndFundCalldata(allowPartial)`. The same choice is `intentSourceTxs(intent, { portal }, options)` for an `Intent` built some other way, over `vaultTransferTxs`, `rewardVaultLegs`, `predictIntentVault` and `assertIntentVault`; `ecoRoutesVaultConfig(portal)` is the vault configuration behind the prediction. [Intents](../guides/intents.md#submit-the-source-reward) covers the order and the checks.
+
+The destination side is a solver's, and two helpers build it from `built.intent`: `fulfillTx(intent, { claimant })` is `Portal.fulfill(intentHash, route, rewardHash, claimant)`, sent to the Portal the route records with `route.nativeAmount` as its value, and `fulfillApprovalTxs(intent)` the solver's approvals of that Portal for the route's tokens, which it pulls from the solver first (one per token, the entries summed). Both require an EVM destination. The route they carry is `evmRouteTuple(route)`, the value `routeHash` is taken over, so the Portal's hash check agrees with `hashIntent`. [`sauce intent fill`](../guides/cli.md#rehearsing-the-fill-sauce-intent-fill) rehearses them on the destination with no key, and with `--send` sends them.
+
+After the fill, the same module builds the rest of an intent's life, each as a request you send: `fulfillAndProveTx(intent, { claimant, prover, sourceDomain, data, fee })` (the fill and its proof in one, `route.nativeAmount + fee` as its value) and `proveTx(intents, { prover, sourceDomain, data, fee })` on the destination, with `hyperlaneProverData({ sourceProver })` the Hyperlane prover's `data` and `proverFeeCall(...)` its fee; `withdrawTx`, `batchWithdrawTx` and `refundTx` on the source, taking `{ portal }`; `cancelTx` and `cancelAndProveTx` on a destination Portal that has `cancel`, after the route's deadline. The reads that decide them are `rewardStatusCall` (one of `REWARD_STATUSES`), `fulfillmentCall` (what the destination recorded: a claimant, `CANCELLED_CLAIMANT_BYTES32`, or zero), `provenIntentCall` (the source prover's claimant and destination) and `proofTypeCall`. `intentFromPublished(log, sourceChainId)` rebuilds an intent from its `IntentPublished` log, checking its hash. [After the fill](../guides/intents.md#after-the-fill-prove-claim-refund-cancel) explains when each applies.
+
 ## Composition and lower-level encoding
 
 Call `.nest(childOrThunk, options?)` before `.reward(...)`. The fluent default is transfer funding after the parent program. [Nested intents](../guides/nested-intents.md) explains funding modes, deadlines, account custody, and execution ordering.

package/docs/concepts/architecture.md

@@ -56,7 +56,26 @@ A program runs through `Pot.cook(engine, program)`. A Pot has an owner; the engi
 cook, so a call needs **both** addresses. A direct `compileSauceRoute` takes them from you. An intent
 derives them: the released engine, and the Pot the recorded Portal's Executor owns under salt zero
 (`SAUCE_INTENT_POT_SALT`). That Pot must exist before the route runs; the solver deploys it. An
-engine accepts only Pots created by its own Kitchen.
+engine accepts only Pots created by its own Kitchen, with the Pot bytecode it was built for: a
+Kitchen release that changes the Pot's bytecode starts a new family of Pot addresses, and a Pot
+from an earlier family keeps running on the engine built for it.
+
+#### A Pot's Router
+
+A Pot's swaps run on **its own Router**. Router self-calls and the pools' mid-swap callbacks reach
+the Pot's fallback, which delegatecalls `pot.router()`: the Kitchen's Router when the Pot was
+minted, until the Pot's owner points it elsewhere with `setRouter`. The Kitchen's owner moves the
+Router that NEW Pots start on and nothing else — the Kitchen cannot move an existing Pot, and a
+Router change moves no Pot address. So after a Router rollout, `potRouterUpdate(client, pot)` from
+`@eco-incorp/sauce/evm/engine` reads both through your client and returns the `setRouter` call for
+the Pot's owner to sign, or nothing when the Pot is already current. Nothing sends it for you, and
+a call from anyone but the owner reverts with `NotOwner()`. It throws for a Pot of an earlier
+Kitchen release, which has no `setRouter` and keeps its Router for good.
+[pot-router.ts](../examples/pot-router.ts) shows the check.
+
+`v12PotAbi` and `v12KitchenAbi` from the same subpath are the released contracts' complete ABIs,
+including the Kitchen's owner-only administration (`initialize`, `setRouter`, `setExecutionFee`,
+ownership transfer and upgrade).
 
 Every cook must send the Kitchen's current `executionFee()` as native value, even for a program that
 moves only ERC-20s. Native the program itself spends is on top of that. A balance already sitting in
@@ -92,8 +111,12 @@ a cascade, not one call stack spanning chains. See [create an intent](../guides/
 
 ## Versions travel with artifacts
 
-A compiled program is paired with an engine that understands it. The compiler reports what it
-produced; it does not inspect an address to find out what is deployed there. Read the deployment
+A compiled program is paired with an engine that understands it, by exact package version in both
+directions: each compiler release names the engine releases its output runs on, and those engines
+run no other compiler's output. The compiler reports what it produced; it does not inspect an
+address to find out what is deployed there. The SDK pins one compiler, ships the engines of its row of
+`V12_RELEASE_SETS`, and refuses to build a cook for an engine another row names
+([which engine runs a program](../api/compiler.md#which-engine-runs-a-program)). Read the deployment
 helpers in `@eco-incorp/sauce/deployments` for released engine and Kitchen addresses, and confirm the
 code is live on the chain or cluster you are targeting.
 

package/docs/concepts/saucescript.md

@@ -32,8 +32,10 @@ target feature has nothing to point at.
 
 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.
+bytes, or records so their callers know the return shape. A file without a `main`
+is a script: its top-level statements are the entry, which runs as `main(): void`,
+so a script cannot `return`. The raw compiler and the route compiler both take one
+as written.
 Entry argument encoding does not determine return encoding. For ABI-decodable
 EVM output, [return `abi.encode(...)`](../guides/compiling.md#return-values-an-abi-decoder-can-read).
 
@@ -71,58 +73,29 @@ one program — one hash — covers every value. The SVM settle recipe folds its
 and token-program split in as defines instead, and is verified by recompiling with
 the same values. Neither is a drop-in for the other.
 
-## 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.
-
-A module-level scalar `const` is a compile-time value. A module-level `let` is
-re-initialised on every invocation — it is scratch space, not chain state. Reach
-for the target's storage builtins when something has to persist.
-
-## 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.
-
-Every example and boundary on this page is checked against the compiler this
-package ships.
+## The language
+
+The [SauceScript reference](../../skills/sauce-script/references/builtins.md) is the complete account of the language, and
+every example and quoted error in it is checked against the compiler this package ships: types,
+literals, operators, statements, functions and modules, every builtin on each target, and the
+limits. What most often surprises a TypeScript author:
+
+- Numbers are unsigned 256-bit integers, and arithmetic is checked: overflow, underflow and division
+  by zero revert. Write a negative amount as `-x`; `~x + 1n` reverts when `x` is zero. Prefer
+  `bigint` literals in host-authored route callbacks so the host keeps exact values.
+- `bool` is kept apart from numbers, and `bytes`/`string` are byte strings: `"text"` is its UTF-8
+  bytes and `` hex`a9059cbb` `` raw bytes. Every untagged template literal is rejected, with or
+  without `${}`.
+- Annotations are checked, and an unannotated parameter is a number, so a helper that takes or
+  returns an array, a record or bytes says so. `Account` roles (`Account<Writable, Signer>`) exist
+  on SVM only; on EVM an `Account` is an address and a role is a compile error.
+- Destructuring binds the fields of something that produces a record — a multi-output contract
+  call, `abi.decode`, `crypto.findPDA` — and not of an array.
+- Functions are top-level declarations; `switch`, `try`/`catch`, classes, closures other than the
+  EVM `.catch(() => { ... })` handler, spread and optional chaining are rejected.
+- A module-level `const` is a compile-time value. A module-level `let` is re-initialised on every
+  invocation — scratch space, not chain state. Reach for the target's storage builtins when
+  something has to persist.
 
 ## EVM and SVM operations
 
@@ -176,8 +149,15 @@ function main(token: Address, spender: Address, amount: Uint256): void {
 }
 ```
 
+`@sauce/token` also pulls tokens into a program, each pull a `safeTransferFrom`:
+`transferFrom` on an allowance, and `permit` (EIP-2612) or `permitTransferFrom`
+(Permit2) on the holder's signature. See
+[Pulling tokens in](../guides/protocols-and-tokens.md#pulling-tokens-in).
+
 A raw compile resolves `@sauce/token` by passing `resolveSdkPackage` and
-`resolveSdkModule` from `@eco-incorp/sauce/compiler`.
+`resolveSdkModule` from `@eco-incorp/sauce/compiler`. Swaps have a library of their
+own, [`@sauce/router`](../api/router.md): one function per venue, taking its pool and
+amount as run-time arguments, resolved the same way.
 
 The compiler's `ambient` option broadcasts a SauceScript module's exports without
 explicit imports. Its `defines` option injects scalar constants into every

package/docs/examples/README.md

@@ -5,18 +5,25 @@
 These run against the published package exports, and they run on every release — if one of them
 stops working, the release does. The construction examples are offline: they compile source and
 build transaction data without sending anything. Repeated-digit addresses and round fees are
-fixtures, not configuration. The RPC helper is typechecked here and reads chain state only when your
-application calls it.
-
-| Example                                                    | Shows                                                                                                                 |
-| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| [cross-chain-intent.sauce.ts](cross-chain-intent.sauce.ts) | A program that measures a balance and publishes a new intent carrying it — written in SauceScript                     |
-| [cross-chain-intent.ts](cross-chain-intent.ts)             | Compiling that program with `defines` and attaching it to a route                                                     |
-| [protocol-approval.ts](protocol-approval.ts)               | A typed `Base(() => ...)` body calling `USDC.approve(Uniswap.UniversalRouter, ...)`                                   |
-| [first-intent.ts](first-intent.ts)                         | Both sides of a transfer intent: Ethereum reward, Base delivery, Executor-to-Pot funding, source transaction requests |
-| [compile-program.ts](compile-program.ts)                   | Direct compilation, a compact entry schema, and argument encoding and decoding                                        |
-| [action-program.ts](action-program.ts)                     | A JSON action program: strict parsing, compilation with a runtime amount, and an intent on the program's chain        |
-| [evm-execution.ts](evm-execution.ts)                       | Reading a destination chain: Kitchen, Executor ownership, Pot prediction and deployment, execution fee                |
+fixtures, not configuration. The RPC helpers are typechecked here and read chain state only when your
+application calls them.
+
+| Example                                                        | Shows                                                                                                                                          |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [cross-chain-intent.sauce.ts](cross-chain-intent.sauce.ts)     | A program that measures a balance and publishes a new intent carrying it — written in SauceScript                                              |
+| [cross-chain-intent.ts](cross-chain-intent.ts)                 | Compiling that program with `defines` and attaching it to a route                                                                              |
+| [protocol-approval.ts](protocol-approval.ts)                   | A typed `Base(() => ...)` body calling `USDC.approve(Uniswap.UniversalRouter, ...)`                                                            |
+| [venue-where-deployed.sauce.ts](venue-where-deployed.sauce.ts) | One program for every chain, using PancakeSwap V3 only where `available(...)` finds it — written in SauceScript                                |
+| [registry-names.ts](registry-names.ts)                         | That program compiled for two chains, and the same registry names from TypeScript: `Base.USDC`, a typed call, `.read(client)`                  |
+| [first-intent.ts](first-intent.ts)                             | Both sides of a transfer intent: Ethereum reward, Base delivery, Executor-to-Pot funding, source transaction requests                          |
+| [compile-program.ts](compile-program.ts)                       | Direct compilation, a compact entry schema, and argument encoding and decoding                                                                 |
+| [action-program.ts](action-program.ts)                         | A chain-agnostic JSON action program — token symbols, a pool by key — compiled for two chains, with a runtime amount, and as an intent on Base |
+| [router-swap.sauce.ts](router-swap.sauce.ts)                   | Two swaps through `@sauce/router`, the second spending what the first returned — written in SauceScript                                        |
+| [router-swap.ts](router-swap.ts)                               | Compiling that program into a cook and an intent, with its floor as a define                                                                   |
+| [router-route.sauce.ts](router-route.sauce.ts)                 | One program for any route over four venues, picking each `@sauce/router` function while it runs                                                |
+| [router-route.ts](router-route.ts)                             | Compiling it once with the raw compiler and appending a route as its arguments                                                                 |
+| [evm-execution.ts](evm-execution.ts)                           | Reading a destination chain: Kitchen, Executor ownership, Pot prediction and deployment, execution fee                                         |
+| [pot-router.ts](pot-router.ts)                                 | Whether a Pot runs its Kitchen's current Router, and the owner's `setRouter` call when it does not                                             |
 
 ## Run an example in your project
 
@@ -34,9 +41,9 @@ pnpm exec tsc example.ts --target ES2022 --module NodeNext --moduleResolution No
 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.
+For `first-intent.ts`, `evm-execution.ts`, `pot-router.ts`, `router-route.ts` and `registry-names.ts`, also run `pnpm add viem`: they use Viem's address formatter and RPC interfaces.
 
 CI typechecks and runs each of them, and asserts the encoded output including a nonzero cook-fee
-budget. The RPC helper is not a live-chain integration test — it is the shape of the reads you make.
+budget. The RPC helpers are not live-chain integration tests — they are the shape of the reads you make.
 
 For actual EVM execution, read the destination Kitchen's `executionFee()` and use it instead of the fixture fee. The intent examples name no Pot or engine: the SDK derives both. The derived Pot is the shared one the solver deploys for each Portal, and it must exist before a route runs on it. To check that it does, or to use a Pot of your own, call `prepareDestinationPot` from `evm-execution.ts` with a destination client, Portal, and salt (zero for the shared Pot). If it returns `ready: false`, send its deployment request with your signer, wait for a successful receipt, and call it again. Pass a Pot of your own as `execution.pot`. 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.