@eco-incorp/sauce 0.99.6 → 0.99.7

package/skills/sauce-swaps/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: sauce-swaps
+description: Swapping inside a Sauce program with @sauce/router — one function per venue (uniswapV2, uniswapV3, uniswapV4, curve, balancerV2, dodoV2, traderJoeLB, woofi, maverickV2, and the try forms), every argument a run-time value, each returning what the recipient received and reverting below minOut; which venues are paid first and which call back through the Pot's Router, which pool families the Router's callbacks service (Uniswap V3 and forks, PancakeSwap V3, Algebra, Synthra, UnitFlow, Uniswap V4), exact input only, how a price limit produces a partial fill, the PancakeSwap Infinity entry points on the Router itself, and the guard that stops a leg from stranding input. Use when the user wants a swap, trade, price limit, sqrtPriceLimitX96, min-out or slippage bound, a partial fill, "swap then …", or asks which venues Sauce can swap on.
+---
+
+# Swaps with `@sauce/router`
+
+`@sauce/router` is the package's swap library: one SauceScript function per venue. A program
+imports the ones it uses, and the package serves the library to every compile, so the import is all
+it needs:
+
+```sauce chain=base,arbitrum
+import { uniswapV3 } from "@sauce/router";
+
+function main(amount: Uint256, sqrtPriceLimitX96: Uint256, minOut: Uint256) {
+  const pool = UniswapV3.Factory.getPool(WETH, USDC, 500n);
+  uniswapV3(pool, WETH, USDC, amount, sqrtPriceLimitX96, minOut, ctx.self());
+}
+```
+
+Every argument is a run-time value, so a program can choose the pool, the direction and the amount
+while it runs: spend what an earlier swap returned, read a balance, loop over a list of pools.
+
+A tokenized stock (`SPCXc` on Base, `TSLAon` on Ethereum) is swapped like any token; its symbol
+and what differs about it are in `sauce-globals`
+([Tokenized stocks](../sauce-globals/SKILL.md#tokenized-stocks)).
+
+## Functions
+
+Every function takes its arguments in one order — the pool, the two tokens, the amount, the venue's
+own facts, then the floor and the recipient — and returns the amount of `tokenOut` the recipient
+received:
+
+| 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 |
+
+- **`amountIn`** is what the Pot pays. **Every swap is exact input.**
+- **`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.
+- **`recipient`** receives the output; `ctx.self()` keeps it in the Pot.
+- `feePpm` is a V2 pair's LP fee in parts per million (3000, which `0n` also means, for Uniswap V2;
+  2500 for PancakeSwap V2). `uniswapV4` takes the pool key's `fee`, `tickSpacing` and `hooks`, and
+  builds the key from `tokenIn` and `tokenOut` in sort order. `uint256Indices` picks a Curve
+  CryptoSwap pool's `uint256` coin indices over a StableSwap pool's `int128` ones.
+
+`tryUniswapV2`, `tryCurve`, `tryBalancerV2` and `tryTraderJoeLB` take the same arguments as the
+function they name and return `0n`, having moved nothing, instead of reverting when the swap cannot
+be made. DODO V2 and WOOFi have no `try` form.
+
+## How each venue is reached
+
+**Paid first.** Uniswap V2 and its forks, Curve, Balancer V2, DODO V2, Trader Joe LB and WOOFi never
+call back: the function pushes the input to the pool, or approves exactly the input for the pool to
+pull, and calls it. Such a swap **consumes its whole input or reverts**; nothing is refunded.
+
+**Called back.** 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()`: the Pot's fallback delegatecalls the Router it is configured with (`router()` on the
+Pot), so the Router runs in the Pot's context, holds the Pot's balances, and answers the callback.
+It services these callbacks:
+
+- `uniswapV3SwapCallback`: Uniswap V3 and forks that keep the name, including Aerodrome Slipstream;
+- `pancakeV3SwapCallback`: PancakeSwap V3;
+- `algebraSwapCallback`: Algebra pools (Camelot V3, QuickSwap V3), whose `swap` has the same
+  selector as Uniswap V3's;
+- `synthraV3SwapCallback`, `unitFlowV3SwapCallback`: Synthra V3 and UnitFlow V3;
+- `unlockCallback`: Uniswap V4.
+
+So `uniswapV3` drives every one of those V3-style pools. Each callback is authenticated to the pool
+being swapped (`InvalidPool` for a pool that is not the requested pair), pays **once**, and pays only
+the input the pool asks for, never more than `amountIn` (`InputExceedsAuthorized`).
+
+Every token write is `@sauce/token`'s SafeERC20: a token that returns nothing (USDT) works, one that
+returns `false` reverts the program.
+
+**Direction is checked from the arguments.** A V2 pair's and a V4 pool's direction is the sort order
+of `tokenIn` and `tokenOut`; `dodoV2` takes the pool's base and quote tokens and `traderJoeLB` its X
+and Y tokens, and each reverts unless `tokenIn` and `tokenOut` are those two; the Router checks a V3
+pool's tokens itself. Take these facts from the pool, as you take the pool itself.
+
+## Price limits and partial fills
+
+`sqrtPriceLimitX96` is `floor(sqrt(token1Units / token0Units) * 2^96)`, with token0 the lower of
+the two addresses, so one number means the same price on every V3-style pool of the pair and on V4
+pools of the same two currencies. Selling token0 moves the price down, so the limit is a floor;
+selling token1 moves it up, so it is a ceiling. It must lie strictly between `4295128739` and
+`1461446703485210103287273052203988822378723970342` and on the far side of the pool's current
+price, or the pool reverts `SPL`. A limit of `0n` means none, which leaves `minOut` as the only
+bound: set a real limit.
+
+**Convert a price with `sauce price`**, which reads no network:
+`npx sauce price --chain base WETH USDC 2686.5`. The price is **quote per base**: the first token
+is the one priced, the second what it is priced in, so this is 2,686.5 USDC per WETH. Swapped,
+`USDC WETH 2686.5` would mean 2,686.5 WETH per USDC, a limit nowhere near any pool. It prints the
+pair's order on the chain (on Base WETH is token0, the lower address, and USDC token1) and two
+blocks:
+
+- **`sell`** (the base token in: WETH → USDC): its `sqrtPriceLimitX96` is a **floor**;
+- **`buy`** (the base token out: USDC → WETH): its `sqrtPriceLimitX96` is a **ceiling**.
+
+Each block also gives `minAvgPrice` for that direction. Take the limit from the block of the
+direction you trade.
+
+**Put the limit near the current price, on the far side of it.** A limit far beyond the price, such
+as the bound itself, is no limit at all: the pool fills down (or up) to it at any price. One on the
+wrong side fills nothing: a single swap reverts `SPL`, and a distributed swap skips every pool and
+refunds everything, which is not a success. In a real run never pass `minOut` as `0`.
+
+**Build the limit from the best price a taker gets among pools with liquidity**: drop the pools
+with no in-range liquidity (`liquidity()`, or less than the order needs), take the best price after
+each pool's fee, and move it by the slippage you accept. Never a pool's price alone: a pool with no
+liquidity at its price keeps a stale price that can be far from the market. Nor the deepest pool's
+mid price: a pool's mid sits up to its fee away from the cheap pools, so a 0.3% pool's price is a
+loose reference. `sauce-distributed-swap` works this through on Base.
+
+**It bounds the pool's price after the swap, not the price paid.** One number is the same pool price
+on every V3-style pool of the pair, but the fee comes on top, and it differs per pool: under one
+limit, the last unit a 1% pool fills costs about 1% more than the limit, a 0.05% pool's about
+0.05%. To bound the price paid, give each pool its own limit: `limit ÷ √(1 − fee)` selling token0,
+`limit × √(1 − fee)` selling token1 (`sauce-distributed-swap` computes it for each pool).
+
+A pool offered more than it can fill before its price reaches the limit **takes only what it
+can**: the Router pays exactly the pool's delta, and the rest of the input stays in the Pot. That
+is what a limit is for (the remainder can go to another venue or back to the user), and why a leg
+must never end with any of its input left in the Pot.
+
+A V4 pool priced in native ETH has `currency0` = `0x0`: it is a different pair from the WETH pools,
+and it needs native ETH in the Pot.
+
+## When a swap reverts
+
+A V3-style pool reverts with a short string, and the Router with a custom error:
+
+| Revert                                   | From       | Means                                                                                           |
+| ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `SPL`                                    | the pool   | the price limit is on the wrong side of the pool's current price, or at or past a bound (above) |
+| `AS`                                     | the pool   | the amount is zero                                                                              |
+| `LOK`                                    | the pool   | the pool is not initialized (or is mid-swap)                                                    |
+| `IIA`                                    | the pool   | its callback paid less input than it asked for                                                  |
+| `TF`                                     | the pool   | its transfer of the output token failed                                                         |
+| `InvalidPool()`, `0x2083cd40`            | the Router | the pool's `token0`/`token1` are not the pair passed                                            |
+| `InputExceedsAuthorized()`, `0x510db218` | the Router | the pool asked for more input than the exact input offered                                      |
+
+A revert inside the program (a `require`, the library's `minOut` check) is the program's own; the
+cook reverts as a whole either way.
+
+## PancakeSwap Infinity
+
+PancakeSwap Infinity pools are not in the library: the Router's own entry points swap them, called
+through the Pot with the Router ABI the package serves (`import { ISauceRouter } from
+"./artifacts/ISauceRouter.json"`, then `ISauceRouter.at(ctx.self())`). Their exact input is a
+negative amount (`-amount`), and they return the pool's signed deltas, not a received amount: the
+program measures the output and checks its own floor.
+
+| Entry point                                                                                              | Price bound         |
+| -------------------------------------------------------------------------------------------------------- | ------------------- |
+| `swapInfinityCL(vault, key, zeroForOne, amountSpecified, sqrtPriceLimitX96, payer, recipient, callback)` | `sqrtPriceLimitX96` |
+| `swapInfinityBin(vault, key, swapForY, amountSpecified, payer, recipient, callback)`                     | none                |
+
+## The guard (required on every leg)
+
+The library checks `minOut`; what is left is the input a price limit left unspent:
+
+1. Pass a `minOut` that is a `main` input, so a short fill reverts the whole transaction.
+2. Pay the output to its recipient (`recipient` does it), or keep it in the Pot for the next step.
+3. Send the rest of the input back to the user or a refund address: `amountIn` less what the
+   swap took (the input balance before minus after), not the Pot's whole balance of the token,
+   which on an owner's Pot may hold more of it for other uses. A full sweep is only for an intent
+   body on the shared intent Pot, which holds nothing of anyone's (`sauce-intents`).
+
+[examples/swap-leg.sauce.ts](examples/swap-leg.sauce.ts) is exactly this for one Uniswap V3 pool.
+Rehearse it, then run it, with the input in the Pot (or pulled in with `--fund`):
+
+```sh
+npx sauce simulate swap-leg.sauce.ts --chain base --owner <address> --config sauce.config.json \
+  --args <tokenIn> <tokenOut> 500 <amountIn> <sqrtPriceLimitX96> <minOut> <recipient>
+npx sauce run swap-leg.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+  --fund WETH:0.5 --args <tokenIn> <tokenOut> 500 <amountIn> <sqrtPriceLimitX96> <minOut> <recipient>
+```
+
+A swap is sent on a chain the initial release supports, Ethereum or Base here; on a preview chain
+the leg compiles and simulates, and `sauce tx` and `sauce run` refuse it with the chain-support
+request for that chain (`sauce-chains`).
+
+For several venues under one price limit, use `sauce-distributed-swap`.
+
+## Example
+
+[examples/swaps.mts](examples/swaps.mts) compiles the leg and pins the library's functions, the
+Router's entry points, their price parameters and the callbacks above against what the package
+serves.

package/skills/sauce-swaps/examples/swap-leg.sauce.ts

@@ -0,0 +1,50 @@
+// One guarded swap leg: sell `amountIn` of `tokenIn` on the chain's Uniswap V3 pool at `fee`, never
+// past `sqrtPriceLimitX96`. `uniswapV3` swaps through the Pot's Router, pays `recipient` and reverts
+// below `minOut`. The pool takes only what it can fill before the limit, so the rest of `amountIn`
+// goes back too. Only this trade's tokens move: what else the Pot holds stays there.
+//
+//   sauce run swap-leg.sauce.ts --chain <chain> --config sauce.config.json --keystore <keystore> \
+//     --args <tokenIn> <tokenOut> <fee> <amountIn> <sqrtPriceLimitX96> <minOut> <recipient>
+//
+//   tokenIn: Address            the token sold
+//   tokenOut: Address           the token bought
+//   fee: Uint256                the pool's fee tier, in millionths: 500 is 0.05%
+//   amountIn: Uint256           how much `tokenIn` to sell, in its smallest units:
+//                               100000000000000000 is 0.1 WETH (18 decimals)
+//   sqrtPriceLimitX96: Uint256  the pool price past which nothing more is sold, as the pool
+//                               states it (`sauce price` turns "2500 USDC per WETH" into it)
+//   minOut: Uint256             the least `tokenOut` to accept, in its smallest units:
+//                               249000000 is 249 USDC (6 decimals)
+//   recipient: Address          who receives `tokenOut` and the unsold `tokenIn`
+//
+// On Base, 0.1 WETH sold for USDC on the 0.05% pool, no lower than 2,500 USDC per WETH:
+//
+//   sauce run swap-leg.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+//     --args 0x4200000000000000000000000000000000000006 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
+//     500 100000000000000000 3961408125713216879677197 249000000 <recipient>
+import { uniswapV3 } from "@sauce/router";
+
+function main(
+  tokenIn: Address,
+  tokenOut: Address,
+  fee: Uint256,
+  amountIn: Uint256,
+  sqrtPriceLimitX96: Uint256,
+  minOut: Uint256,
+  recipient: Address,
+) {
+  const self = ctx.self();
+  const pool = UniswapV3.Factory.getPool(tokenIn, tokenOut, fee);
+  require(pool != 0n, "no pool at that fee tier");
+  const inBefore = Token(tokenIn).balanceOf(self);
+  require(inBefore >= amountIn, "amountIn is not in the Pot");
+
+  uniswapV3(pool, tokenIn, tokenOut, amountIn, sqrtPriceLimitX96, minOut, recipient);
+
+  // The rest of amountIn: what the pool did not take. Not the Pot's whole balance, which may hold
+  // more of the token for other uses.
+  const unspent = amountIn - (inBefore - Token(tokenIn).balanceOf(self));
+  if (unspent > 0n) {
+    Token(tokenIn).transfer(recipient, unspent);
+  }
+}

package/skills/sauce-swaps/examples/swaps.mts

@@ -0,0 +1,124 @@
+// Compiles swap-leg.sauce.ts for Base and Arbitrum the way `sauce compile` does, and pins the facts
+// the sauce-swaps skill states: the functions `@sauce/router` exports and their argument order, the
+// Router entry points that take a sqrt-price limit, which pool callbacks the Router services, and
+// what a callback is held to. Offline: nothing is sent.
+//
+//   node swaps.mts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import { routes } from "@eco-incorp/sauce";
+import { resolveSdkModule, resolveSdkPackage } from "@eco-incorp/sauce/compiler";
+
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`check failed: ${message}`);
+}
+
+const source = readFileSync(new URL("./swap-leg.sauce.ts", import.meta.url), "utf8");
+for (const slug of ["base", "arbitrum"]) {
+  const leg = routes.compileSauceProgram(slug, source);
+  check(
+    leg.entryParams.map((param) => `${param.name}: ${param.type}`).join(", ") ===
+      "tokenIn: Address, tokenOut: Address, fee: Uint256, amountIn: Uint256, " +
+        "sqrtPriceLimitX96: Uint256, minOut: Uint256, recipient: Address",
+    "main's inputs, as --args takes them",
+  );
+  check(/from "@sauce\/router"/.test(leg.source), "the leg swaps through @sauce/router");
+  console.log(`guarded V3 leg on ${slug}: ${leg.bytecode.length} bytes`);
+}
+
+// The library the package serves for `import ... from "@sauce/router"`: its EVM arm, and every
+// function the skill lists, with its arguments in the order the skill gives them.
+const entry = resolveSdkPackage("@sauce/router");
+if (entry === undefined) throw new Error("the SDK serves @sauce/router");
+const library = resolveSdkModule(entry.replace(/\.js$/, ".evm.js"));
+if (library === undefined) throw new Error("@sauce/router has an EVM arm");
+const text = new TextDecoder().decode(library);
+const params = (name: string) => {
+  const found = new RegExp(`export function ${name}\\(([^)]*)\\)`).exec(text);
+  return found?.[1]
+    ?.split(",")
+    .map((p) => p.trim().split(":")[0]!.trim())
+    .filter(Boolean)
+    .join(", ");
+};
+const LIBRARY = {
+  uniswapV2: "pair, tokenIn, tokenOut, amountIn, feePpm, minOut, recipient",
+  uniswapV3: "pool, tokenIn, tokenOut, amountIn, sqrtPriceLimitX96, minOut, recipient",
+  uniswapV4:
+    "poolManager, tokenIn, tokenOut, amountIn, fee, tickSpacing, hooks, sqrtPriceLimitX96, minOut, recipient",
+  curve: "pool, tokenIn, tokenOut, amountIn, i, j, uint256Indices, minOut, recipient",
+  balancerV2: "vault, tokenIn, tokenOut, amountIn, poolId, minOut, recipient",
+  dodoV2: "pool, tokenIn, tokenOut, amountIn, baseToken, quoteToken, minOut, recipient",
+  traderJoeLB: "pair, tokenIn, tokenOut, amountIn, tokenX, tokenY, minOut, recipient",
+  woofi: "pool, tokenIn, tokenOut, amountIn, minOut, recipient",
+  maverickV2: "pool, tokenIn, tokenOut, amountIn, minOut, recipient",
+};
+for (const [name, args] of Object.entries(LIBRARY)) {
+  check(params(name) === args, `@sauce/router's ${name}(${args})`);
+}
+for (const name of ["UniswapV2", "Curve", "BalancerV2", "TraderJoeLB"]) {
+  const base = name.charAt(0).toLowerCase() + name.slice(1);
+  check(params(`try${name}`) === params(base), `try${name} takes ${base}'s arguments`);
+}
+for (const name of ["DodoV2", "Woofi"]) {
+  check(params(`try${name}`) === undefined, `${name} has no try form`);
+}
+
+// The Router ABI the package serves, which `@sauce/router` calls for the venues that call back.
+interface AbiFunction {
+  type: string;
+  name: string;
+  inputs: { name: string }[];
+}
+const served = resolveSdkModule("./artifacts/ISauceRouter.json");
+if (served === undefined) throw new Error("the SDK serves ISauceRouter.json");
+const parsed = JSON.parse(new TextDecoder().decode(served)) as
+  AbiFunction[] | { abi: AbiFunction[] };
+const abi = (Array.isArray(parsed) ? parsed : parsed.abi).filter((f) => f.type === "function");
+const has = (name: string) => abi.some((f) => f.name === name);
+const inputs = (name: string) => abi.find((f) => f.name === name)?.inputs.map((i) => i.name) ?? [];
+
+check(inputs("swapV3").includes("sqrtPriceLimitX96"), "swapV3 takes a limit");
+check(inputs("swapV4").includes("sqrtPriceLimitX96"), "swapV4 takes a limit");
+check(
+  inputs("swapInfinityCL").join() ===
+    "vault,key,zeroForOne,amountSpecified,sqrtPriceLimitX96,payer,recipient,callback",
+  "PancakeSwap Infinity CL takes a limit",
+);
+check(
+  inputs("swapInfinityBin").join() ===
+    "vault,key,swapForY,amountSpecified,payer,recipient,callback",
+  "PancakeSwap Infinity Bin has no limit",
+);
+
+// The pool callbacks the Router services: which pool families `uniswapV3`/`uniswapV4` can drive.
+for (const callback of [
+  "uniswapV3SwapCallback",
+  "pancakeV3SwapCallback",
+  "algebraSwapCallback",
+  "synthraV3SwapCallback",
+  "unitFlowV3SwapCallback",
+  "unlockCallback",
+]) {
+  check(has(callback), `the Router implements ${callback}`);
+}
+
+// What a callback is held to: the pool must be the requested pair, and it is paid at most the
+// exact input. The deployed Router's full ABI ships beside the package's other artifacts.
+const routerAbi = (
+  JSON.parse(
+    readFileSync(
+      join(
+        dirname(createRequire(import.meta.url).resolve("@eco-incorp/sauce")),
+        "artifacts/Router.json",
+      ),
+      "utf8",
+    ),
+  ) as { abi: { type: string; name?: string }[] }
+).abi;
+const errors = routerAbi.filter((entry) => entry.type === "error").map((entry) => entry.name);
+check(errors.includes("InvalidPool"), "a pool that is not the requested pair is refused");
+check(errors.includes("InputExceedsAuthorized"), "a callback takes at most the exact input");
+console.log(`@sauce/router: ${Object.keys(LIBRARY).join(", ")}`);

package/skills/sauce-typescript/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: sauce-typescript
+description: The TypeScript side of Sauce (@eco-incorp/sauce) — compiling a .sauce.ts program for a chain from application code exactly as the sauce command does, encoding its main(...) arguments and the Pot.cook transaction, deriving and deploying the owner's Pot, the raw compiler and compact arguments, JSON action programs, settlement verification, browser compilation with ready(), and the rule that the package embeds no RPC. Use when writing application or script code that compiles, encodes, verifies or submits Sauce programs, or when the user asks which import or subpath to use.
+---
+
+# Sauce from TypeScript
+
+Write the program in SauceScript first (`sauce-script`, `sauce-globals`), and run it with the
+`sauce` command (`sauce-cli`). Reach for TypeScript when an application builds the transactions
+itself: every command is a thin layer over the functions below. The package embeds no RPC endpoint
+and reads no environment variable: anything that touches a chain takes a client or an `rpcUrl` from
+you. Every address comes from the package (`/deployments`, the registries) or from the developer;
+never invent one. The shipped manual starts at `node_modules/@eco-incorp/sauce/docs/README.md`; the
+subpath list is `node_modules/@eco-incorp/sauce/docs/api/README.md`.
+
+## Supported chains
+
+For the initial release, Sauce supports transactions on Ethereum, Base and Solana. Every other
+chain the registry knows is a preview chain: its programs compile and simulate, and the `sauce`
+command and the MCP server build and send no transaction there. Application code follows the same
+rule: build and send a cook, a Pot's deployment or an intent's transactions only for a supported
+chain, and treat a preview chain as compile and simulate only. To ask for a preview chain, find its
+request among the
+[existing chain-support requests](https://github.com/eco-incorp/sauce/issues?q=is%3Aissue+label%3Achain-support)
+and add the use case, or
+[open one](https://github.com/eco-incorp/sauce/issues/new?template=chain-support.yml).
+
+## Compile a program for a chain, and cook it
+
+`routes.compileSauceProgram(chain, source, options)` is what `sauce compile` runs: the chain's
+names, its defines and `@sauce/token`, with `options.defines` for the program's own compile-time
+values and `options.intents` for the intents it opens. The result carries `main`'s declared
+parameters (`entryParams`); `routes.encodeEntryArguments` encodes values for them as `--args` does,
+and program plus arguments is the `program` of the owner's `Pot.cook(engine, program)`.
+
+```ts
+import { readFileSync } from "node:fs";
+import { destinationExecutionFee, routes, v12PredictPot } from "@eco-incorp/sauce";
+import { v12EngineAddress } from "@eco-incorp/sauce/deployments";
+import { v12Pot } from "@eco-incorp/sauce/evm/engine";
+import { bytesToHex, concatHex, getAddress, type PublicClient } from "viem";
+
+type Address = `0x${string}`;
+
+export async function cookTransactions(
+  client: PublicClient, // the chain's: the program is compiled for it and the fee read from it
+  file: string,
+  chain: string,
+  owner: Address,
+  args: readonly (bigint | string | boolean)[],
+) {
+  const salt = `0x${"00".repeat(32)}` as const;
+  const pot = v12PredictPot(owner, salt); // the owner's Pot, derived through the released Kitchen
+  const deploy = routes.sauceEvmDeployPotCall({ owner, salt }); // once, through the Kitchen
+  const program = routes.compileSauceProgram(chain, readFileSync(file, "utf8"));
+  const encoded = routes.encodeEntryArguments(program, args); // checked against main's types
+  const engine = getAddress(v12EngineAddress());
+  const payload = concatHex([bytesToHex(program.bytecode), bytesToHex(encoded)]);
+  // The cook's value is the Kitchen's executionFee(), read just before sending: a cook paying
+  // less reverts.
+  const fee = destinationExecutionFee();
+  const { data: answer } = await client.call({ to: fee.to, data: fee.data });
+  if (answer === undefined) throw new Error("the Kitchen did not answer executionFee()");
+  const cook = {
+    chainId: await client.getChainId(),
+    to: pot,
+    data: v12Pot.encodeCook(engine, payload),
+    value: fee.decode(answer),
+  };
+
+  return { deploy, cook }; // cook is what `sauce tx` prints: { chainId, to, data, value }
+}
+```
+
+- `destinationExecutionFee()` builds the fee read (`{ to, data, decode }`) for the chain's
+  Kitchen; the example sends it as an `eth_call` with the chain's client just before the cook.
+- `routes.sauceEvmDeployPotCall` and `routes.buildSauceEvmCall` return `{ to, data, value }` to send
+  as a transaction, plus `target`, the same contract as a route's `calls` entry names it.
+- `v12EngineAddress()` and `v12KitchenAddress()` are recorded release addresses, and the deploy
+  call goes to the Kitchen unless you pass `kitchen`: check the chain has code at them. Deploy the
+  Pot only where it has no code yet.
+- A Pot swaps through the Router its Kitchen handed it when it was minted. `potRouterUpdate(client,
+pot)` from `/evm/engine` reads both, and returns the `setRouter` call for the Pot's owner to send
+  when the Kitchen has a newer one.
+- A program that opens an intent also needs `options.intents`, `{ deadline, creator,
+executionFee }` (`sauce-intents`).
+
+## The raw compiler
+
+`compile({ target, entry, resolve, ... })` from `/compiler` compiles a program and resolves nothing
+for you: no registry names, no chain defines, no token syntax. Reach for it for full control of the
+source and resolver, and for compact arguments.
+
+- ABI-v1 arguments by default: `abi.encode` of `main`'s parameters, except that a tuple parameter
+  is always behind an offset word, even one whose fields are all fixed-size. `encodeAbiParameters`
+  inlines that tuple instead; `routes.encodeEntryArguments` writes the layout `main` reads.
+- `compactArgs: true` returns an `entrySchema` for
+  `encodeCompactArguments`/`decodeCompactArguments` (`scalarWidth` keeps offsets fixed).
+- `resolveSdkModule` and `resolveSdkPackage` serve `@sauce/token`, the package's artifact ABIs and
+  every `./protocols/<slug>/<Export>.json` to your resolver.
+- In a browser, `await ready()` once before the first compile; `/svm/engine-artifacts` is the one
+  Node-only subpath. See [examples/compiler.mts](examples/compiler.mts) and
+  `node_modules/@eco-incorp/sauce/docs/api/compiler.md`.
+
+## The protocol registry
+
+```ts
+import { contracts, getProtocol, getProtocolsByChain, listProtocolSlugs } from "@eco-incorp/sauce";
+import * as pancakeV3 from "@eco-incorp/sauce/protocols/pancakeswap-v3";
+
+export const onBase = getProtocolsByChain(8453).map((p) => p.slug); // catalogued on Base
+export const info = getProtocol("pancakeswap-v3"); // name, category, chains, website
+export const slugs = listProtocolSlugs();
+// Per-chain addresses by role, e.g. { factory, smartRouter, nonfungiblePositionManager }.
+export const pancakeOnBase = pancakeV3.deployments.find((d) => d.chainId === 8453)?.addresses;
+// Whether a namespace contract is deployed on a chain, and where.
+export const aave = contracts.on("base").AaveV3.Pool; // { available, address, abi, methods, … }
+export const pancake = contracts.on("optimism").PancakeswapV3.Factory.available; // false
+```
+
+Each protocol module (`@eco-incorp/sauce/protocols/<slug>`) exports `protocolInfo`, `deployments`,
+its ABIs (`…ABI`), and its SauceScript templates by name (`supply`, `swap`, `getPool`, …).
+`getProtocolSkill(slug)`, `getProtocolIndex()` and `listSkillSlugs()` from
+`@eco-incorp/sauce/skills` return the `sauce-protocols` documents. An address in `deployments` is
+a recorded address, not proof of live code on the chain.
+
+## Other host tools
+
+- **JSON action programs** (`/actions`): a document names tokens by registry symbol (`"USDC"`) and
+  contracts by namespace (`"UniswapV3.Factory"`), and a swap may give its pool by its factory's
+  key (`factory` and `fee`). `compileProgram(program, { chain })` compiles it for any chain that
+  has those names; a name the chain lacks throws `ProgramError`, whose `issues` and `chain` say
+  which. `argument` actions become runtime amounts. `programIntent(...)`, `quoteAction(...)` and
+  `compileSplitSwap(...)` resolve names on `chain` the same way. Reference:
+  `node_modules/@eco-incorp/sauce/docs/guides/actions.md`; see
+  [examples/actions.mts](examples/actions.mts), and `sauce-actions` for writing the documents.
+- **Settlement verification** (`/verify`, `/svm/verify`): `validateSettleProgram`,
+  `decodeSettleCall`, `extractEvmSettleFromIntent`, historical pins. It identifies the program and
+  its parameters; the Pot, engine and every other call stay yours to check (`sauce verify` runs
+  it). See [examples/verify.mts](examples/verify.mts).
+- **Solana execution** (`/svm`): the Kitchen client,
+  `createSauceSvmClient({ rpcUrl, payer, programId, kitchen, maxExecutionFee })`, with no default
+  endpoint; the SVM route helpers (`Solana(...)` routes, `buildSauceSvmCall`) do not produce an
+  instruction the engine accepts, so build execution with the Kitchen client. `USDC_MINT` is the
+  mainnet USDC mint. The token builder generates Token-2022 and `TransferChecked` programs:
+  `token.Token.transfer({ amount, svm: { ... } }).source("svm")`, with top-level
+  `tokenProgram: "token-2022"`. For a `@sauce/token` program's accounts,
+  `resolveSvmToken(load, mint)` reads a mint through an owned-account loader and returns its token
+  program (by the mint's owner), decimals and extensions, and why a checked transfer of it would be
+  refused; `svmTokenAccount(token, owner)` derives a holder's account under that program, and
+  `svmTokenReceived`/`svmTokenToSend` net a Token-2022 transfer fee exactly, either way. Venue adapters (`venue("raydium-cp-swap")`, also `Solana.RaydiumCpSwap`) build
+  pool configs, quote source and swap CPIs over an account loader you supply. For a local validator
+  or LiteSVM, `svmEnginePath()`, `svmKitchenPath()` and `svmKitchenIdlPath()` from
+  `@eco-incorp/sauce/svm/engine-artifacts` (Node only) locate the packaged programs; the program
+  ids are `v12SvmEngineProgramId()` and `v12SvmKitchenProgramId()` from `/deployments`. Writing the
+  programs is `sauce-solana`.
+- **Intents** (`sauce-intents`): `routes.hashIntent(intent)` gives the three hashes,
+  `routes.encodeRouteEvm(intent.route)` the route bytes (decode with `routes.EVM_ROUTE_PARAM` for
+  `fulfill`), `destinationPot(chain)` the shared Pot and
+  `routes.sauceEvmDeployPotCall({ owner: ecoRoutesExecutor(chain), salt: SAUCE_INTENT_POT_SALT })`
+  its deploy; the intents runner builds a rehearsal with them. For the source side,
+  `built.sourceTxs()` (`routes.intentSourceTxs` for an intent built some other way) is the
+  funding and publication in order: a transfer of each reward token to the vault, then `publish`
+  (`{ fundVia: "publishAndFund" }` for the approvals and `publishAndFund`). Pass `{ vault }` read with
+  `routes.intentVaultAddressCall`: it is checked against `routes.predictIntentVault`, the package's
+  own computation. `routes.publishTx`, `routes.publishAndFundTx`, `routes.approvalTxs` and
+  `routes.isIntentFundedCall` build the single calls (`{ to, data }`, with `decode` for a read).
+- **Cascades from TypeScript**: `routes.openRoute(chain, body, options).nest(child, { via })`
+  attaches a child intent to a route. By default (`via: "transfer"`) the parent's route funds the
+  child by a transfer into the child's vault, with no publication of its own;
+  `via: "publishAndFund"` publishes and funds it for public discovery instead.
+
+## Example
+
+[examples/cook.mts](examples/cook.mts) builds the Pot, its deploy call and a cook with arguments
+offline; [examples/compiler.mts](examples/compiler.mts),
+[examples/actions.mts](examples/actions.mts) and [examples/verify.mts](examples/verify.mts) run the
+raw compiler and argument codecs, the action-program pipeline, and settlement verification.

package/skills/sauce-typescript/examples/actions.mts

@@ -0,0 +1,100 @@
+// JSON action programs: validate at the edge, compile once for a chain with a runtime amount, and
+// build (not send) the quote that prices a swap action. Documents name tokens by registry symbol and
+// contracts by namespace, so one document compiles for every chain that has those names.
+import {
+  ProgramError,
+  compileProgram,
+  parseProgram,
+  quoteAction,
+  type ActionProgram,
+  type UniswapV4SwapAction,
+} from "@eco-incorp/sauce/actions";
+import { v12RouterAddress } from "@eco-incorp/sauce/deployments";
+import { toHex } from "viem";
+
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`check failed: ${message}`);
+}
+
+// The Sauce Router of the release, which quotes Uniswap V3 and V4 swap actions with the code that
+// swaps them. A Pot swaps through its own Router, the Kitchen's when it was minted.
+const ROUTER = toHex(BigInt(v12RouterAddress()), { size: 20 });
+
+// 1. Strict validation: every problem at once, each with a path. Amounts are base-10 STRINGS.
+try {
+  parseProgram({ version: 1, actions: [{ type: "approve", token: "USDT", amuont: 5 }] });
+  throw new Error("expected rejection");
+} catch (error) {
+  if (!(error instanceof ProgramError)) throw error;
+  check(error.issues.length >= 1, "issues carry paths");
+}
+
+// 2. One compiled program for every amount: `argument` becomes a runtime parameter of `main`. The
+//    names resolve on the chain given; token writes are SafeERC20 (approve is forceApprove), so USDT
+//    is fine here.
+const reusable: ActionProgram = parseProgram({
+  version: 1,
+  actions: [
+    { type: "argument", name: "amount" },
+    { type: "approve", token: "USDT", spender: "AaveV3.Pool" },
+  ],
+});
+const compiled = compileProgram(reusable, { chain: "ethereum" });
+const p1 = compiled.payload({ amount: 5n });
+const p2 = compiled.payload({ amount: "900000" });
+check(
+  p1.length === compiled.bytecode.length + 32 && p1.length === p2.length,
+  "ABI-v1: one word per argument",
+);
+check(compiled.argumentOffset("amount") === compiled.bytecode.length, "splice offset of `amount`");
+check(
+  !/IERC20\.at\([^)]*\)\.approve/.test(compiled.source),
+  "the approve is not a typed IERC20 call",
+);
+// The same document compiles for another chain with those names, to that chain's addresses: the
+// source names them, and the bytecode holds each chain's own.
+const onOptimism = compileProgram(reusable, { chain: "optimism" });
+check(onOptimism.source === compiled.source, "the source names the tokens and contracts");
+check(
+  toHex(onOptimism.bytecode) !== toHex(compiled.bytecode),
+  "the bytecode holds each chain's addresses",
+);
+
+// 3. A name the chain lacks throws ProgramError, with the issues and the chain: Base registers no
+//    USDT, so the same document does not compile there.
+try {
+  compileProgram(reusable, { chain: "base" });
+  throw new Error("expected rejection");
+} catch (error) {
+  if (!(error instanceof ProgramError)) throw error;
+  check(
+    error.chain?.slug === "base" && error.issues[0]?.path === "actions[1].token",
+    "the issue names the field and the chain",
+  );
+}
+
+// 4. A quote is an eth_call you send yourself; nothing here touches the network. A swap action is
+//    a call into @sauce/router, here its `uniswapV4`: a hookless USDC/USDT pool, named by its key.
+const swapAction: UniswapV4SwapAction = {
+  type: "uniswapV4Swap",
+  poolManager: "UniswapV4.PoolManager",
+  tokenIn: "USDC",
+  tokenOut: "USDT",
+  fee: 100,
+  tickSpacing: 1,
+  amount: "1000000",
+  amountOutMin: "990000",
+  recipient: "self",
+};
+const swapping = compileProgram(parseProgram({ version: 1, actions: [swapAction] }), {
+  chain: "ethereum",
+});
+check(/from "@sauce\/router"/.test(swapping.source), "a swap action calls @sauce/router");
+const quote = quoteAction(swapAction, { chain: "ethereum", router: ROUTER });
+check(
+  quote.data.startsWith("0x") && typeof quote.decode === "function",
+  "quote = { to, data, decode }",
+);
+
+console.log(`reusable approval: ${compiled.bytecode.length} bytes + 32-byte argument`);
+console.log(`quote: eth_call to ${quote.to}`);