@eco-incorp/sauce 0.99.6 → 0.99.7

package/skills/sauce-intents/examples/fund-by-transfer.sauce.ts

@@ -0,0 +1,54 @@
+// Opens an intent funded by transfer: the reward goes straight into the intent's vault, the
+// address the source Portal derives from the intent itself, and then the intent is published. One
+// cook on the Pot, so the vault can't be wrong and nothing is published unfunded. No approval is
+// involved, so a token like USDT needs nothing special.
+//
+// `destination`, `route` and `reward` are the arguments of the Portal's `publish`, the same
+// `publish` that `sauce intent publish … --from <address> --format json` prints for an intent file (which
+// already funds that way); `portal` is the source chain's Portal (its file in sauce-chains).
+//
+//   sauce run fund-by-transfer.sauce.ts --chain <chain> --config sauce.config.json \
+//     --keystore <keystore> --args <portal> <destination> <route> <reward>
+//
+//   portal: Address       the source chain's Portal
+//   destination: Uint256  the destination's chain id: 1 is Ethereum
+//   route: bytes          the encoded route, 0x hex, as the publish transaction carries it
+//   reward: { deadline: Uint256; creator: Address; prover: Address; nativeAmount: Uint256;
+//             tokens: { token: Address; amount: Uint256 }[] }
+//                         the reward, a JSON object: each token's amount in its smallest units,
+//                         {"deadline": <unix seconds>, "creator": "<address>", "prover": "<address>",
+//                         "nativeAmount": 0, "tokens": [{"token": "<token>", "amount": 1010000}]}
+//                         is 1.01 of a 6-decimal token such as USDC
+//
+// On Base, for an intent to Ethereum:
+//
+//   sauce run fund-by-transfer.sauce.ts --chain base --config sauce.config.json \
+//     --keystore <keystore> --args 0xEC000769A73b70e16f361a442292500b3BCf4A85 1 <route> <reward>
+function main(
+  portal: Address,
+  destination: Uint256,
+  route: bytes,
+  reward: {
+    deadline: Uint256;
+    creator: Address;
+    prover: Address;
+    nativeAmount: Uint256;
+    tokens: { token: Address; amount: Uint256 }[];
+  },
+): bytes {
+  // A native reward is sent to the vault with the cook's value; this program funds tokens only.
+  require(reward.nativeAmount == 0n, "a native reward is not funded here");
+  const intent = abi.encode(destination, route, reward);
+
+  // intentVaultAddress(uint64,bytes,(uint64,address,address,uint256,(address,uint256)[]))
+  const vaultOf = hex`0742ebe4`;
+  const vault = abi.decode(evm.static(portal, vaultOf.concat(intent)), ["Address"])[0];
+  for (const t of reward.tokens) {
+    Token(t.token).transfer(vault, t.amount);
+  }
+
+  // publish(uint64,bytes,(uint64,address,address,uint256,(address,uint256)[])): returns
+  // (intentHash, vault).
+  const publish = hex`645c890c`;
+  return evm.call(portal, 0n, publish.concat(intent));
+}

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

@@ -0,0 +1,343 @@
+// Compiles the two intent files the way `sauce run` and `sauce compile` do
+// (`routes.compileSauceProgram` with the intent settings), and checks on which chain each name
+// resolves: the body and its delivery on the destination, the reward on the source. Each child's
+// Portal and prover come from the eco-routes registry; the deadline, the creator, the recipient and
+// each destination Kitchen's fee are the developer's. Then builds what rehearsing the swap-on-base
+// body on a fork of Base sends: the shared Pot's deploy, and the Portal's fulfill with the Kitchen
+// fee as its value. Pins the funding by transfer (fund-by-transfer.sauce.ts) and the Portal
+// reference (references/portal.md) to the registry's Portal ABI. Offline: nothing is sent.
+//
+//   node intents.mts --creator <address> --recipient <address> --ethereum-fee <wei> --base-fee <wei>
+//
+// Each fee is that chain's Kitchen executionFee(), read there just before sending with
+// destinationExecutionFee(); it is compiled into the child's cook.
+import { readFileSync } from "node:fs";
+
+import {
+  contracts,
+  destinationExecutionFee,
+  destinationPot,
+  routes,
+  SAUCE_INTENT_POT_SALT,
+  v12PredictPot,
+} from "@eco-incorp/sauce";
+import { v12KitchenAddress } from "@eco-incorp/sauce/deployments";
+import {
+  ecoRoutesExecutor,
+  ecoRoutesPortal,
+  ecoRoutesProver,
+  PortalABI,
+} from "@eco-incorp/sauce/protocols/eco-routes";
+import {
+  decodeAbiParameters,
+  decodeFunctionData,
+  encodeFunctionData,
+  getAddress,
+  toEventSelector,
+  toFunctionSelector,
+  type AbiEvent,
+  type Hex,
+} from "viem";
+
+function flag(name: string): string {
+  const i = process.argv.indexOf(`--${name}`);
+  const value = i === -1 ? undefined : process.argv[i + 1];
+  if (value === undefined) throw new Error(`pass --${name}`);
+  return value;
+}
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`check failed: ${message}`);
+}
+
+const creator = getAddress(flag("creator")); // may reclaim an unearned reward; never a Pot
+const recipient = BigInt(getAddress(flag("recipient")));
+const fee = { ethereum: BigInt(flag("ethereum-fee")), base: BigInt(flag("base-fee")) };
+const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // filled within the hour or not at all
+const feeRead = destinationExecutionFee(); // { to, data, decode }: eth_call it on each destination
+
+const compileFor = (
+  slug: string,
+  source: string,
+  defines: Record<string, bigint>,
+  executionFee?: bigint,
+) =>
+  routes.compileSauceProgram(slug, source, {
+    defines,
+    intents: { deadline, creator, ...(executionFee === undefined ? {} : { executionFee }) },
+  });
+const word = (value: bigint | string) => BigInt(value).toString(16).padStart(40, "0");
+const token = (slug: string, symbol: string) => {
+  const found = routes.registryTokenAddress(routes.chain(slug).chain, symbol);
+  if (found === undefined) throw new Error(`no ${symbol} on ${slug}`);
+  return found;
+};
+const contract = (slug: string, name: string) => {
+  const found = routes.chainDefines(routes.chain(slug).chain)[name];
+  if (typeof found !== "bigint") throw new Error(`no ${name} on ${slug}`);
+  return found;
+};
+/** The one intent a program opens: its route's tokens and calls, and its reward's tokens. */
+function intentOf(program: ReturnType<typeof compileFor>) {
+  check(program.intents.length === 1, "one intent");
+  const { route, reward } = program.intents[0]!.intent;
+  return {
+    delivered: route.tokens.map((t) => t.token.slice(-40)),
+    calls: route.calls.map((c) => `${c.target.slice(-40)}:${c.data.toLowerCase()}`).join(" "),
+    rewarded: reward.tokens.map((t) => t.token.slice(-40)),
+  };
+}
+
+// ---- cross-chain.sauce.ts: from Base, a program child on Ethereum.
+const forward = readFileSync(new URL("./cross-chain.sauce.ts", import.meta.url), "utf8");
+check(!/function main\b/.test(forward), "an intent file is top-level statements");
+let missingFee = "";
+try {
+  compileFor("base", forward, { BENEFICIARY: recipient });
+} catch (error) {
+  missingFee = (error as Error).message;
+}
+check(missingFee.includes("executionFee"), "a program child needs the destination's Kitchen fee");
+const forwarded = intentOf(compileFor("base", forward, { BENEFICIARY: recipient }, fee.ethereum));
+check(
+  forwarded.delivered.join() === word(token("ethereum", "USDC")),
+  "the solver delivers Ethereum's USDC",
+);
+check(forwarded.calls.includes(word(contract("ethereum", "AaveV3_Pool"))), "Ethereum's Aave pool");
+check(!forwarded.calls.includes(word(contract("base", "AaveV3_Pool"))), "and not Base's");
+check(forwarded.rewarded.join() === word(token("base", "USDC")), "the reward is Base's USDC");
+
+// ---- swap-on-base.sauce.ts: from Ethereum, the distributed swap as a program child on Base.
+const swap = readFileSync(new URL("./swap-on-base.sauce.ts", import.meta.url), "utf8");
+check(!/function main\b/.test(swap), "an intent file is top-level statements");
+const swapped = intentOf(
+  compileFor(
+    "ethereum",
+    swap,
+    {
+      AMOUNT_IN: 10n ** 18n,
+      REWARD: 10n ** 18n + 10n ** 15n,
+      SQRT_PRICE_LIMIT_X96: 3068493539683605256287027n, // 1,500 USDC per WETH on Base
+      MIN_OUT: 0n,
+      MIN_AVG_PRICE: 1_500_000_000n,
+      RECIPIENT: recipient,
+      REFUND_TO: recipient,
+    },
+    fee.base,
+  ),
+);
+check(swapped.delivered.join() === word(token("base", "WETH")), "the solver delivers Base's WETH");
+for (const [what, value] of [
+  ["Base's USDC", token("base", "USDC")],
+  ["Base's Uniswap V3 factory", contract("base", "UniswapV3_Factory")],
+  ["Base's Uniswap V4 PoolManager", contract("base", "UniswapV4_PoolManager")],
+  ["Base's Uniswap V4 StateView", contract("base", "UniswapV4_StateView")],
+] as const) {
+  check(swapped.calls.includes(word(value)), `the child uses ${what}`);
+}
+check(swapped.rewarded.join() === word(token("ethereum", "WETH")), "the reward is Ethereum's WETH");
+// The body swaps through @sauce/router and reads each V3 pool through the `UniswapV3.Pool`
+// namespace, whose ABI is the registry's: three view functions the pool dispatches, by these
+// selectors, which the child carries, and no raw selector of its own.
+for (const [signature, selector] of [
+  ["slot0()", "3850c7bd"],
+  ["liquidity()", "1a686502"],
+  ["fee()", "ddca3f43"],
+] as const) {
+  check(toFunctionSelector(signature) === `0x${selector}`, `${signature} is 0x${selector}`);
+  check(swapped.calls.includes(selector), `the child calls ${signature} on a pool`);
+}
+check(/UniswapV3\.Pool\(pool\)/.test(swap), "the body reads a pool through UniswapV3.Pool");
+check(!/hex`[0-9a-f]{8}`/.test(swap), "and calls no raw selector");
+check(
+  /import \{ uniswapV3, uniswapV4 \} from "@sauce\/router"/.test(swap),
+  "the body swaps through @sauce/router",
+);
+
+// ---- A token-only child is plain route calls for the destination's Executor: no Pot, no fee.
+// Inside the body, and in the delivery, a token symbol is the destination's: `USDC` here is
+// Ethereum's, while the one in `.reward(...)` is Base's, which the program escrows.
+const direct = intentOf(
+  compileFor(
+    "base",
+    "Ethereum(() => { USDC.transfer(RECIPIENT, AMOUNT); }).reward({ tokens: [{ token: USDC, amount: AMOUNT }] });",
+    { RECIPIENT: recipient, AMOUNT: 1_000_000n },
+  ),
+);
+check(direct.calls.startsWith(word(token("ethereum", "USDC"))), "Ethereum's USDC, called directly");
+check(!direct.calls.includes(" "), "and nothing else: no cook");
+check(direct.rewarded.join() === word(token("base", "USDC")), "the reward is Base's USDC");
+check(contracts.on("ethereum").AaveV3.Pool.available, "Ethereum has AaveV3.Pool");
+
+// ---- Inside a body, a decoded result is read by position or destructured, as anywhere else.
+const decodeIn = (statement: string) =>
+  `Base(() => { const d = hex\`3850c7bd\`; ${statement} require(x != 0n); }, { tokens: [{ token: 0x4200000000000000000000000000000000000006n, amount: 1n }] }).reward({ tokens: [{ token: WETH, amount: 1n }] });`;
+const refused = (source: string) => {
+  try {
+    compileFor("ethereum", source, { RECIPIENT: recipient }, fee.base);
+    return "";
+  } catch (error) {
+    return (error as Error).message;
+  }
+};
+check(
+  refused(decodeIn('const x = abi.decode(evm.static(RECIPIENT, d), ["Uint256"])[0n];')) === "",
+  "a body reads a decoded result by position",
+);
+check(
+  refused(decodeIn('const [x] = abi.decode(evm.static(RECIPIENT, d), ["Uint256"]);')) === "",
+  "and destructures one, as anywhere else",
+);
+
+// ---- Rehearsing the swap-on-base body on a fork of Base: what the solver sends there.
+const swapDefines = {
+  AMOUNT_IN: 10n ** 18n,
+  REWARD: 10n ** 18n + 10n ** 15n,
+  SQRT_PRICE_LIMIT_X96: 3068493539683605256287027n,
+  MIN_OUT: 0n,
+  MIN_AVG_PRICE: 1_500_000_000n,
+  RECIPIENT: recipient,
+  REFUND_TO: recipient,
+};
+const { intent } = compileFor("ethereum", swap, swapDefines, fee.base).intents[0]!;
+// The Kitchen fee is the route's native amount: the solver pays it, in Base's native coin, as the
+// value of fulfill. Nothing in the reward pays it back.
+check(intent.route.nativeAmount === fee.base, "route.nativeAmount is Base's Kitchen fee");
+// 1. The shared Pot: the Executor's at salt zero. Anyone may deploy it; no solver can fill first.
+const executor = ecoRoutesExecutor("base");
+const pot = destinationPot("base");
+check(pot === v12PredictPot(executor, SAUCE_INTENT_POT_SALT), "the shared Pot is the Executor's");
+const deployPot = routes.sauceEvmDeployPotCall({ owner: executor, salt: SAUCE_INTENT_POT_SALT });
+check(
+  getAddress(`0x${deployPot.target.slice(-40)}`) === getAddress(v12KitchenAddress()),
+  "the Pot's deploy is a call to the Kitchen",
+);
+// 2. The route's tokens: what the solver holds and approves to the Portal, which pulls them.
+check(
+  intent.route.tokens.length === 1 && intent.route.tokens[0]!.amount === 10n ** 18n,
+  "the route's tokens are the delivered WETH",
+);
+// 3. fulfill(intentHash, route, rewardHash, claimant), the hashes as the Portal computes them
+//    (its getIntentHash gives the same three).
+const { intentHash, rewardHash } = routes.hashIntent(intent);
+const [route] = decodeAbiParameters([routes.EVM_ROUTE_PARAM], routes.encodeRouteEvm(intent.route));
+const solver = creator; // offline, any address stands in for the solver's
+const claimant = `0x${"00".repeat(12)}${solver.slice(2)}` as Hex; // who the reward goes to
+const fulfill = {
+  to: ecoRoutesPortal("base"),
+  value: intent.route.nativeAmount,
+  data: encodeFunctionData({
+    abi: PortalABI,
+    functionName: "fulfill",
+    args: [intentHash, route, rewardHash, claimant],
+  }),
+};
+const decoded = decodeFunctionData({ abi: PortalABI, data: fulfill.data });
+check(decoded.functionName === "fulfill" && decoded.args[0] === intentHash, "fulfill's calldata");
+// The deadline and the fee are in the route, so either changes the intent and its hash: rebuild
+// every transaction (and any unsigned one printed earlier) after changing one.
+const rehashed = (deadlineShift: bigint, executionFee: bigint) =>
+  routes.hashIntent(
+    routes.compileSauceProgram("ethereum", swap, {
+      defines: swapDefines,
+      intents: { deadline: deadline + deadlineShift, creator, executionFee },
+    }).intents[0]!.intent,
+  ).intentHash;
+check(rehashed(0n, fee.base) === intentHash, "the same inputs give the same intent");
+check(rehashed(1n, fee.base) !== intentHash, "a new deadline is a new intent");
+check(rehashed(0n, fee.base + 1n) !== intentHash, "a new Kitchen fee is a new intent");
+
+// Funding by transfer: the program reads the vault and publishes by the registry's selectors,
+// with the same three arguments, and compiles for a source chain.
+const byHand = readFileSync(new URL("./fund-by-transfer.sauce.ts", import.meta.url), "utf8");
+// A function's or error's selector is the hash of its bare signature, `name(types)`.
+type Param = { type: string; components?: readonly Param[] };
+type Entry = { name: string; inputs: readonly Param[] };
+const typeOf = (param: Param): string =>
+  param.type.startsWith("tuple")
+    ? `(${(param.components ?? []).map(typeOf).join(",")})${param.type.slice(5)}`
+    : param.type;
+const signature = (item: Entry) => `${item.name}(${item.inputs.map(typeOf).join(",")})`;
+const portalFunction = (name: string): Entry =>
+  PortalABI.find((item) => item.type === "function" && item.name === name) as Entry;
+for (const name of ["intentVaultAddress", "publish"]) {
+  const selector = toFunctionSelector(signature(portalFunction(name)));
+  check(
+    byHand.includes(`hex\`${selector.slice(2)}\``),
+    `fund-by-transfer calls ${name}, ${selector}`,
+  );
+}
+check(
+  JSON.stringify(portalFunction("publish").inputs) ===
+    JSON.stringify(portalFunction("intentVaultAddress").inputs),
+  "publish and intentVaultAddress take the same (destination, route, reward)",
+);
+check(
+  JSON.stringify(portalFunction("publishAndFund").inputs.slice(0, 3)) ===
+    JSON.stringify(portalFunction("publish").inputs),
+  "publish's arguments are publishAndFund's first three",
+);
+const byHandProgram = routes.compileSauceProgram("base", byHand);
+check(
+  byHandProgram.entryParams.map((param) => param.name).join() === "portal,destination,route,reward",
+  "fund-by-transfer takes the intent as publish's arguments",
+);
+
+// The Portal reference: every selector and topic it gives for something the registry declares is
+// the registry's.
+const reference = readFileSync(new URL("../references/portal.md", import.meta.url), "utf8");
+let pinned = 0;
+for (const item of PortalABI) {
+  if (item.type !== "function" && item.type !== "event" && item.type !== "error") continue;
+  // Each entry naming it, to the next list item, table row or paragraph; the one that gives a
+  // selector or topic must give the registry's.
+  const entries: string[] = [];
+  for (let at = reference.indexOf(`\`${item.name}(`); at !== -1;) {
+    const ends = ["\n- ", "\n|", "\n\n"]
+      .map((end) => reference.indexOf(end, at + 1))
+      .filter((i) => i > 0);
+    entries.push(reference.slice(at, Math.min(...ends)));
+    at = reference.indexOf(`\`${item.name}(`, at + 1);
+  }
+  const given = entries.filter((entry) => /`0x[0-9a-f]{8}(?:[0-9a-f]{56})?`/.test(entry));
+  if (given.length === 0) continue;
+  const expected =
+    item.type === "event"
+      ? toEventSelector(item as AbiEvent)
+      : toFunctionSelector(signature(item as Entry));
+  check(
+    given.every((entry) => entry.includes(expected)),
+    `references/portal.md gives ${item.name} as ${expected}`,
+  );
+  pinned++;
+}
+check(pinned >= 15, `the reference pins ${pinned} of the Portal's selectors and topics`);
+
+// The one-pool swap body compiles as an intent to Base, with the delivery the solver brings.
+const skill = readFileSync(new URL("../SKILL.md", import.meta.url), "utf8");
+const onePool =
+  /```sauce chain=ethereum define=AMOUNT_IN,REWARD,SQRT_PRICE_LIMIT_X96,MIN_OUT,RECIPIENT,REFUND_TO\n([\s\S]*?)```/.exec(
+    skill,
+  );
+check(onePool !== null, "the skill gives the one-pool body");
+const onePoolIntent = routes.compileSauceProgram("ethereum", onePool[1]!, {
+  defines: { ...swapDefines, MIN_OUT: 1n },
+  intents: { deadline, creator, executionFee: fee.base },
+}).intents[0]!.intent;
+check(
+  onePoolIntent.route.nativeAmount === fee.base && onePoolIntent.route.tokens.length === 1,
+  "the one-pool body is a program body: the Kitchen fee as nativeAmount, WETH delivered",
+);
+
+console.log(
+  `rehearsal on a fork of Base: deploy the Pot ${pot} if it has no code, approve the Portal for ` +
+    `the WETH, then fulfill ${intentHash.slice(0, 10)}… with value ${fulfill.value}`,
+);
+console.log(
+  `cross-chain.sauce.ts on Base -> Ethereum Portal ${ecoRoutesPortal("ethereum")}, ` +
+    `prover ${ecoRoutesProver("base", "ethereum")}`,
+);
+console.log(
+  `swap-on-base.sauce.ts on Ethereum -> Base Portal ${ecoRoutesPortal("base")}, ` +
+    `prover ${ecoRoutesProver("ethereum", "base")}`,
+);
+console.log(`each destination fee is read at ${feeRead.to}`);

package/skills/sauce-intents/examples/swap-on-base.sauce.ts

@@ -0,0 +1,135 @@
+// Sells WETH for USDC on Base, paying the solver in WETH on the chain this runs on: one intent
+// whose body is a distributed swap. A solver delivers AMOUNT_IN of WETH on Base; the body goes once
+// over every Uniswap V3 pool and hookless Uniswap V4 pool of the pair, and sells to each with
+// liquidity the WETH still unsold, up to its own limit (the price paid, fee included, never below
+// SQRT_PRICE_LIMIT_X96), then pays the USDC to RECIPIENT and returns the unsold WETH to REFUND_TO
+// on Base. The solver earns REWARD of WETH. The whole file is the intent: top-level statements, no
+// main, and every value a define. Nothing is measured on chain, so it can also be published from a
+// wallet (sauce intent publish).
+//
+// `--chain` is the source chain: `WETH` in `.reward(...)` is its WETH. Inside the braces, and in
+// the delivery argument after them, the body runs on Base: `WETH`, `USDC`, `UniswapV3.Factory`,
+// `UniswapV3.Pool`, `UniswapV4.StateView` and `UniswapV4.PoolManager` there are Base's.
+//
+//   sauce run swap-on-base.sauce.ts --chain <chain> --config sauce.config.json \
+//     --keystore <keystore> --define AMOUNT_IN=<amount> --define REWARD=<amount> \
+//     --define SQRT_PRICE_LIMIT_X96=<sqrtPriceX96> --define MIN_OUT=<amount> \
+//     --define MIN_AVG_PRICE=<price> --define RECIPIENT=<address> --define REFUND_TO=<address> \
+//     --intent-deadline <unix seconds> --intent-creator <address> \
+//     --intent-execution-fee <Base Kitchen fee in wei>
+//
+//   AMOUNT_IN: Uint256             Base WETH the solver delivers and the body sells, in its
+//                                  smallest units (18 decimals): 1000000000000000000 is 1 WETH
+//   REWARD: Uint256                the source chain's WETH the solver earns, in its smallest units:
+//                                  above AMOUNT_IN by the solver's margin
+//   SQRT_PRICE_LIMIT_X96: Uint256  Base's WETH/USDC pool price below which no pool sells (`sauce
+//                                  price --chain base 2500 USDC per WETH` gives it)
+//   MIN_OUT: Uint256               the least USDC out, in its smallest units (6 decimals):
+//                                  2490000000 is 2,490 USDC
+//   MIN_AVG_PRICE: Uint256         the least USDC per WETH sold, as USDC units per WETH unit times
+//                                  1e18: 2490000000 is 2,490 USDC per WETH
+//   RECIPIENT: Address             who receives the USDC on Base
+//   REFUND_TO: Address             who receives the unsold WETH on Base
+//   --intent-execution-fee: wei    Base's Kitchen fee for the body's cook; `auto` reads it through
+//                                  --config
+//
+// From Ethereum, selling 1 WETH on Base no lower than 2,500 USDC per WETH, for 1.002 WETH:
+//
+//   sauce run swap-on-base.sauce.ts --chain ethereum --config sauce.config.json \
+//     --keystore <keystore> --define AMOUNT_IN=1000000000000000000 \
+//     --define REWARD=1002000000000000000 --define SQRT_PRICE_LIMIT_X96=3961408125713216879677197 \
+//     --define MIN_OUT=2490000000 --define MIN_AVG_PRICE=2490000000 \
+//     --define RECIPIENT=<address> --define REFUND_TO=<address> \
+//     --intent-deadline <unix seconds> --intent-creator <address> --intent-execution-fee auto
+import { uniswapV3, uniswapV4 } from "@sauce/router";
+
+// A pool's own limit: the caller's sqrt price limit moved by sqrt(1 - fee), so that what the pool
+// pays, fee included, never passes the caller's. Selling token0 pushes the price down: then the
+// limit is a floor, and higher is better.
+function ownLimit(limit: Uint256, fee: Uint256, sellsToken0: bool): Uint256 {
+  const root = Math.sqrt((1000000n - fee) * 10n ** 30n); // sqrt(1 - fee), times 1e18
+  if (sellsToken0) {
+    return Math.mulDiv(limit, 10n ** 18n, root);
+  }
+  return Math.mulDiv(limit, root, 10n ** 18n);
+}
+
+Base(
+  () => {
+    require(SQRT_PRICE_LIMIT_X96 != 0n && RECIPIENT != 0n && REFUND_TO != 0n, "set the defines");
+    const self = ctx.self();
+    const sellsToken0 = WETH < USDC;
+    const wethBefore = WETH.balanceOf(self);
+    const usdcBefore = USDC.balanceOf(self);
+
+    // One pass over the pools: each is offered all the WETH still unsold, up to its own limit, and
+    // skipped when it is missing, has no liquidity, or is already past that limit. A pool fills
+    // what it can and leaves the rest for the next.
+    // Uniswap V3, by fee tier, each pool read through the `UniswapV3.Pool` namespace.
+    for (const tier of [100n, 500n, 3000n, 10000n]) {
+      const pool = UniswapV3.Factory.getPool(WETH, USDC, tier);
+      if (pool != 0n) {
+        if (UniswapV3.Pool(pool).liquidity() > 0n) {
+          const limit = ownLimit(SQRT_PRICE_LIMIT_X96, UniswapV3.Pool(pool).fee(), sellsToken0);
+          const price = UniswapV3.Pool(pool).slot0().sqrtPriceX96;
+          const unsold = WETH.balanceOf(self);
+          if (unsold > 0n && (sellsToken0 ? price > limit : price < limit)) {
+            uniswapV3(pool, WETH, USDC, unsold, limit, 0n, self);
+          }
+        }
+      }
+    }
+    // Uniswap V4's four standard hookless keys, read from the StateView. Its protocol fee for
+    // this direction is taken first (selling token0's in the low 12 bits, token1's in the next 12),
+    // and the LP fee from the rest.
+    const currency0 = sellsToken0 ? WETH : USDC;
+    const currency1 = sellsToken0 ? USDC : WETH;
+    const v4Fees = [100n, 500n, 3000n, 10000n];
+    const v4TickSpacings = [1n, 10n, 60n, 200n];
+    for (let k = 0n; k < 4n; k++) {
+      const id = crypto.keccak256(
+        abi.encode(currency0, currency1, v4Fees[k], v4TickSpacings[k], 0n),
+      );
+      if (UniswapV4.StateView.getLiquidity(id) > 0n) {
+        const slot0 = UniswapV4.StateView.getSlot0(id);
+        let protocolFee = slot0.protocolFee & 0xfffn;
+        if (!sellsToken0) {
+          protocolFee = (slot0.protocolFee >> 12n) & 0xfffn;
+        }
+        const fee = protocolFee + slot0.lpFee - (protocolFee * slot0.lpFee) / 1000000n;
+        const limit = ownLimit(SQRT_PRICE_LIMIT_X96, fee, sellsToken0);
+        const unsold = WETH.balanceOf(self);
+        if (
+          unsold > 0n &&
+          (sellsToken0 ? slot0.sqrtPriceX96 > limit : slot0.sqrtPriceX96 < limit)
+        ) {
+          uniswapV4(
+            UniswapV4.PoolManager,
+            WETH,
+            USDC,
+            unsold,
+            v4Fees[k],
+            v4TickSpacings[k],
+            0n,
+            limit,
+            0n,
+            self,
+          );
+        }
+      }
+    }
+
+    // Settle on Base: the checks, the USDC out, and the WETH back. This body runs on the shared
+    // intent Pot, which holds nothing of anyone's between intents, so it returns all the WETH there.
+    const unsold = WETH.balanceOf(self);
+    const spent = wethBefore - unsold;
+    const out = USDC.balanceOf(self) - usdcBefore;
+    require(out >= MIN_OUT, "output below MIN_OUT");
+    require(out * 10n ** 18n >= MIN_AVG_PRICE * spent, "average price below MIN_AVG_PRICE");
+    USDC.transfer(RECIPIENT, out);
+    if (unsold > 0n) {
+      WETH.transfer(REFUND_TO, unsold);
+    }
+  },
+  { tokens: [{ token: WETH, amount: AMOUNT_IN }] },
+).reward({ tokens: [{ token: WETH, amount: REWARD }] });

package/skills/sauce-intents/references/portal.md

@@ -0,0 +1,77 @@
+# The eco-routes Portal
+
+One Portal contract per chain is both sides of an intent: the source side escrows rewards, the
+destination side fills routes. Its address on each chain is in that chain's file in `sauce-chains`.
+`Reward` is `(uint64 deadline, address creator, address prover, uint256 nativeAmount, (address token, uint256 amount)[] tokens)`
+and `Route` is
+`(bytes32 salt, uint64 deadline, address portal, uint256 nativeAmount, (address token, uint256 amount)[] tokens, (address target, bytes data, uint256 value)[] calls)`;
+`route` as `bytes` is `abi.encode(Route)`.
+
+## Source side: escrow, publication, claim and refund
+
+- `publish(uint64 destination, bytes route, Reward reward)`, `0x645c890c`: records the intent and
+  emits `IntentPublished`. Needs no funding, anyone may send it, and sending it again re-emits the
+  event. Returns `(bytes32 intentHash, address vault)`.
+- `publishAndFund(uint64 destination, bytes route, Reward reward, bool allowPartial)`,
+  `0xdf00f8fa`, payable: `publish`, then pulls the reward from the sender into the vault, through
+  an allowance to the **Portal**, and the native reward from the value. With `allowPartial` false it
+  reverts `InsufficientFunds` unless the whole reward is covered. Emits `IntentPublished` and
+  `IntentFunded`, and sets the status to Funded.
+- `fund(uint64 destination, bytes32 routeHash, Reward reward, bool allowPartial)`, `0x9f24b4dd`,
+  payable: the funding half alone. Emits `IntentFunded`, never `IntentPublished`.
+- `intentVaultAddress(uint64 destination, bytes route, Reward reward)`, `0x0742ebe4`, view: the
+  intent's vault, an address derived from the intent hash (CREATE2 by the Portal). It holds what is
+  sent to it before any contract is deployed there.
+- `isIntentFunded(uint64 destination, bytes route, Reward reward)`, `0x0fa76b79`, view: true when
+  the status is Funded or the vault holds the whole reward, native and every token.
+- `getIntentHash(uint64 destination, bytes route, Reward reward)`, `0x6063cd5b`, pure:
+  `(intentHash, routeHash, rewardHash)`.
+- `getRewardStatus(bytes32 intentHash)`, `0x1299d617`, view: 0 Initial, 1 Funded, 2 Withdrawn,
+  3 Refunded. A vault funded by a transfer stays Initial.
+- `withdraw(uint64 destination, bytes32 routeHash, Reward reward)`, `0xf987b9bc`: once the reward's
+  prover has recorded the fill, pays the reward to the claimant the fill named. Anyone may send it.
+- `refund(uint64 destination, bytes32 routeHash, Reward reward)`, `0x308adade`: after the reward's
+  deadline, with no fill proven, returns the vault's reward tokens and native balance to the
+  creator. Anyone may send it; before the deadline it reverts `InvalidStatusForRefund`. A proven
+  but unclaimed intent cannot be refunded.
+- `refundTo(uint64 destination, bytes32 routeHash, Reward reward, address refundee)`, `0x572ac041`:
+  the same, sent by the creator, to a recipient the creator names.
+
+## Destination side: the fill
+
+- `fulfill(bytes32 intentHash, Route route, bytes32 rewardHash, bytes32 claimant)`, `0x52a8339e`,
+  payable: checks the route's deadline (`IntentExpired`), that `route.portal` is this Portal
+  (`InvalidPortal`), that the hash matches (`InvalidHash`), that it was not filled
+  (`IntentAlreadyFulfilled`) and that the value covers `route.nativeAmount`
+  (`InsufficientNativeAmount(sent, required)`); pulls each of the route's tokens from the sender,
+  through an allowance to this Portal, into its Executor; and has the Executor run the calls,
+  forwarding `route.nativeAmount`.
+- `executor()`, `0xc34c08e5`, view: the Executor, which owns the chain's shared intent Pot. It
+  reverts `CallToEOA(target)` (`0x2db59289`) for a call with data to an address with no code, and
+  `CallFailed(call, result)` (`0x12988136`) when a call reverts, with the call's own revert data in
+  `result`. It checks nothing else: a token transfer that returns `false` passes.
+
+## Events
+
+| Event                                                                                                                                                                                                                | Topic                                                                |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `IntentPublished(bytes32 indexed intentHash, uint64 destination, bytes route, address indexed creator, address indexed prover, uint64 rewardDeadline, uint256 rewardNativeAmount, (address,uint256)[] rewardTokens)` | `0x43974895be1bcec7344337863fa7de24a0d1c315c0a994f663fe0ee220ddc8e4` |
+| `IntentFunded(bytes32 intentHash, address funder, bool complete)`                                                                                                                                                    | `0xc1ed05721d27ad6b2555d61388ac393b120f5cc0e6009e53230e02c68e60064a` |
+| `IntentFulfilled(bytes32 indexed intentHash, bytes32 indexed claimant)`, on the destination                                                                                                                          | `0xc471de166a60c0b81727dfa2f57d4fc3ad1b45b057c1f034b7058365613bde8d` |
+| `IntentProven(bytes32 indexed intentHash, bytes32 indexed claimant)`                                                                                                                                                 | `0xe6d8040a8a6bc519f4e5a42fb2677067c929ddbf2cca9287a44b23fb617a6f00` |
+| `IntentWithdrawn(bytes32 intentHash, address indexed claimant)`                                                                                                                                                      | `0xbb062c23e818de8ea9c157514eb098052cf36904bbe431cd50d4ec92264ca3ac` |
+| `IntentRefunded(bytes32 intentHash, address indexed refundee)`                                                                                                                                                       | `0x8d53c2b04800cf061b987a07179bb6c9730c05536b2f6a3a091fe62303682eb6` |
+
+## Errors
+
+| Error                                                                         | Selector     | When                                                     |
+| ----------------------------------------------------------------------------- | ------------ | -------------------------------------------------------- |
+| `InsufficientNativeAmount(uint256 sent, uint256 required)`                    | `0x172f1184` | `fulfill` with less value than `route.nativeAmount`      |
+| `InvalidStatusForRefund(uint8 status, uint256 currentTime, uint256 deadline)` | `0xc6a2514b` | `refund` before the reward's deadline                    |
+| `InsufficientFunds(bytes32 intentHash)`                                       | `0x07b90620` | `publishAndFund`/`fund` that cannot cover the reward     |
+| `IntentExpired()`                                                             | `0x408b2234` | `fulfill` after the route's deadline                     |
+| `InvalidHash(bytes32 expectedHash)`                                           | `0x44d659bf` | `fulfill` whose route and reward hash differently        |
+| `InvalidPortal(address portal)`                                               | `0xd16be752` | `fulfill` on a Portal the route does not name            |
+| `IntentAlreadyFulfilled(bytes32 intentHash)`                                  | `0x373d2079` | a second `fulfill`                                       |
+| `CallToEOA(address target)` (the Executor)                                    | `0x2db59289` | a route call with data to an address with no code        |
+| `CallFailed((address,bytes,uint256) call, bytes result)` (the Executor)       | `0x12988136` | a route call that reverted (`result` is its revert data) |