@eco-incorp/sauce 0.99.6 → 0.99.7

package/docs/examples/action-program.ts

@@ -6,16 +6,21 @@ import {
   serializeProgram,
 } from "@eco-incorp/sauce/actions";
 
-// A program as it would arrive from another service: JSON text. Base USDC; the spender is a fixture.
+// A program as it would arrive from another service: JSON text. It has no chainId: its tokens are
+// registry symbols and its pool is found by key, through Uniswap V3's factory, so it compiles for
+// any chain where those names exist. The amount is a runtime argument.
 const json = `{
   "version": 1,
-  "chainId": 8453,
   "actions": [
-    { "type": "balanceOf", "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+    { "type": "argument", "name": "amount" },
     {
-      "type": "approve",
-      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-      "spender": "0x1111111111111111111111111111111111111111"
+      "type": "uniswapV3Swap",
+      "factory": "UniswapV3.Factory",
+      "fee": 500,
+      "tokenIn": "USDC",
+      "tokenOut": "WETH",
+      "amountOutMin": "1",
+      "recipient": "self"
     }
   ]
 }`;
@@ -26,43 +31,54 @@ if (serializeProgram(program) !== JSON.stringify(JSON.parse(json))) {
 
 // Every problem is reported at once, each with its path.
 try {
-  parseProgram({ ...program, actions: [{ type: "approve", amount: 5 }] });
+  parseProgram({ ...program, actions: [{ type: "approve", amount: 5, token: "usdc" }] });
   throw new Error("Expected the program to be rejected");
 } catch (error) {
   if (!(error instanceof ProgramError) || error.issues.length !== 3) throw error;
 }
 
-// Standalone: the approval spends whatever USDC the Pot holds when it runs.
-const { bytecode } = compileProgram(program);
+// One document, two chains: the same SauceScript, each chain's own tokens and factory.
+const onBase = compileProgram(program, { chain: "base" });
+const onEthereum = compileProgram(program, { chain: "ethereum" });
+if (onBase.source !== onEthereum.source) throw new Error("Expected one source for both chains");
+if (onBase.source.indexOf("UniswapV3.Factory.getPool(USDC, WETH, 500n)") < 0) {
+  throw new Error("Expected the pool to be read from the factory while the program runs");
+}
+const same = onBase.bytecode.every((byte, i) => byte === onEthereum.bytecode[i]);
+if (same && onBase.bytecode.length === onEthereum.bytecode.length) {
+  throw new Error("Expected each chain's addresses in its bytecode");
+}
 
-// One compiled program, many amounts: an `argument` is appended to the bytecode at run time.
-const reusable = compileProgram({
-  version: 1,
-  chainId: 8453,
-  actions: [
-    { type: "argument", name: "amount" },
-    {
-      type: "approve",
-      token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-      spender: "0x1111111111111111111111111111111111111111",
-    },
-  ],
-});
-const payload = reusable.payload({ amount: 1_000_000n });
-if (payload.length !== reusable.bytecode.length + 32) throw new Error("Expected one ABI word");
+// One compiled program, many amounts: the `argument` is appended to the bytecode at run time.
+const payload = onBase.payload({ amount: 1_000_000_000n });
+if (payload.length !== onBase.bytecode.length + 32) throw new Error("Expected one ABI word");
 
-// As an intent: the route runs on the program's chain, Base. Offline fixtures throughout.
+// A chain that lacks a name refuses the program, naming the chain, the name and its path.
+try {
+  compileProgram(program, { chain: "avalanche" });
+  throw new Error("Expected Avalanche, which registers no token symbols, to refuse the names");
+} catch (error) {
+  if (!(error instanceof ProgramError) || error.chain?.slug !== "avalanche") throw error;
+  if (!error.issues.some((issue) => issue.path === "actions[1].tokenIn")) throw error;
+}
+
+// As an intent on Base. A route takes no runtime arguments, so the swap spends the Pot's USDC
+// balance, read when it runs, instead of the argument. Offline fixtures throughout.
 const executionFee = 1_000n;
-const built = programIntent(program, {
-  execution: {
-    pot: "0x2222222222222222222222222222222222222222",
-    engine: "0x3333333333333333333333333333333333333333",
-    value: executionFee,
+const built = programIntent(
+  { version: 1, actions: [{ type: "balanceOf", token: "USDC" }, program.actions[1]!] },
+  {
+    chain: "base",
+    execution: {
+      pot: "0x2222222222222222222222222222222222222222",
+      engine: "0x3333333333333333333333333333333333333333",
+      value: executionFee,
+    },
+    nativeAmount: executionFee,
+    portal: "0x4444444444444444444444444444444444444444",
+    deadline: 2_000_000_000n,
   },
-  nativeAmount: executionFee,
-  portal: "0x4444444444444444444444444444444444444444",
-  deadline: 2_000_000_000n,
-}).reward({
+).reward({
   source: "ethereum",
   creator: "0x5555555555555555555555555555555555555555",
   prover: "0x6666666666666666666666666666666666666666",
@@ -71,5 +87,5 @@ const built = programIntent(program, {
 });
 if (built.destination.slug !== "base") throw new Error("Expected a Base route");
 
-console.log("Program bytes:", bytecode.length, "with an argument:", payload.length);
+console.log("Program bytes on Base:", onBase.bytecode.length, "with an argument:", payload.length);
 console.log("Action intent:", built.hash().intentHash);

package/docs/examples/cross-chain-cascade.sauce.ts

@@ -7,6 +7,10 @@
 //
 // The middle body is more than token writes, so it compiles to a program and runs on Arbitrum's
 // Pot; its second argument names what a solver must deliver for it to have something to measure.
+//
+// Every `USDC` is the USDC of the chain where that part runs. Each body's is its destination's. Each
+// reward is escrowed by the program offering it, so the Arbitrum hop's reward is the first chain's
+// USDC and the Optimism hop's is Arbitrum's.
 function main() {
   const amount = USDC.balanceOf(ctx.self());
   Arbitrum(

package/docs/examples/cross-chain-intent.sauce.ts

@@ -10,7 +10,8 @@
 // the encoded intent, and fills in the Portal, the prover, the approval and the encoding.
 //
 // RECIPIENT is a compile-time `define` the caller supplies. `USDC` is a registered symbol, and
-// inside the braces it means Arbitrum's USDC, because that is the chain those calls run on.
+// inside the braces it means Arbitrum's USDC, because that is the chain those calls run on. In
+// `.reward(...)` it means the USDC of the chain this program runs on, which escrows the reward.
 function main() {
   const amount = USDC.balanceOf(ctx.self());
   if (amount < MIN_AMOUNT) {

package/docs/examples/evm-execution.ts

@@ -4,8 +4,6 @@ import { v12Kitchen, v12Pot } from "@eco-incorp/sauce/evm/engine";
 import { getAddress, parseAbi, type Address, type Hex, type PublicClient } from "viem";
 
 const portalAbi = parseAbi(["function executor() view returns (address)"]);
-const feeAbi = parseAbi(["function executionFee() view returns (uint256)"]);
-const potKitchenAbi = parseAbi(["function kitchen() view returns (address)"]);
 
 // Call with a client for the destination chain. Importing this example performs no RPC.
 export async function prepareDestinationPot(client: PublicClient, portal: Address, salt: Hex) {
@@ -32,7 +30,7 @@ export async function prepareDestinationPot(client: PublicClient, portal: Addres
   });
   const executionFee = await client.readContract({
     address: kitchen,
-    abi: feeAbi,
+    abi: v12Kitchen.abi,
     functionName: "executionFee",
   });
   const context = { kitchen, engine, executor, pot, executionFee };
@@ -50,7 +48,7 @@ export async function prepareDestinationPot(client: PublicClient, portal: Addres
 
   const [owner, actualKitchen] = await Promise.all([
     client.readContract({ address: pot, abi: v12Pot.abi, functionName: "owner" }),
-    client.readContract({ address: pot, abi: potKitchenAbi, functionName: "kitchen" }),
+    client.readContract({ address: pot, abi: v12Pot.abi, functionName: "kitchen" }),
   ]);
   if (getAddress(owner) !== getAddress(executor) || getAddress(actualKitchen) !== kitchen) {
     throw new Error("Pot must belong to this Portal Executor and the current Kitchen");

package/docs/examples/first-intent.ts

@@ -39,9 +39,14 @@ const built = Base(
   tokens: [{ token: sourceUsdc, amount }],
 });
 
-const sourceRequests = [...built.approvals(), built.publishAndFundCalldata(false)];
+// The reward paid into the intent's vault, then `publish`. Pass `{ vault }` as `built.vaultCall()`
+// reads it from the source chain to have it checked against this offline derivation.
+const sourceRequests = built.sourceTxs();
 if (built.intent.route.calls.length !== 2 || sourceRequests.length !== 2) {
-  throw new Error("Expected destination delivery + cook and source approval + funding");
+  throw new Error("Expected destination delivery + cook and source transfer + publish");
+}
+if (sourceRequests[0]?.to.toLowerCase() !== sourceUsdc.toLowerCase()) {
+  throw new Error("The reward is transferred in the source chain's USDC");
 }
 if (
   built.intent.route.calls[1]?.value !== executionFee ||

package/docs/examples/pot-router.ts

@@ -0,0 +1,19 @@
+import { v12RouterGeneration } from "@eco-incorp/sauce/deployments";
+import { potRouterUpdate } from "@eco-incorp/sauce/evm/engine";
+import type { Address, PublicClient } from "viem";
+
+// Call with a client for the Pot's chain. Importing this example performs no RPC.
+export async function potRouter(client: PublicClient, pot: Address) {
+  // Reads pot.router() and its Kitchen's router(). Throws for a Pot of an earlier Kitchen release,
+  // which has no setRouter and keeps its Router for good.
+  const update = await potRouterUpdate(client, pot);
+  if (update === undefined) {
+    // The Pot runs its Kitchen's current Router. Its generation decides which pools' callbacks it
+    // answers: Synthra V3 and UnitFlow V3 swaps need generation 3.
+    return { current: true as const, routerGeneration: v12RouterGeneration() };
+  }
+
+  // Only the Pot's owner can send this; anyone else reverts with NotOwner(). Send it with the
+  // owner's signer, wait for a successful receipt, then call potRouter again.
+  return { current: false as const, update: { ...update, value: 0n } };
+}

package/docs/examples/registry-names.ts

@@ -0,0 +1,52 @@
+// The registry's names in both languages: venue-where-deployed.sauce.ts compiled for two chains,
+// and the same contracts and tokens from host TypeScript.
+//
+// Everything that runs here is offline: the Pot and engine are fixtures and nothing is sent. The
+// read helper at the bottom is typechecked, and reads chain state only when your application calls
+// it with a client.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Base, Optimism, routes } from "@eco-incorp/sauce";
+import type { PublicClient } from "viem";
+
+const program = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "venue-where-deployed.sauce.ts"),
+  "utf8",
+);
+const execution = {
+  pot: "0x1111111111111111111111111111111111111111",
+  engine: "0x2222222222222222222222222222222222222222",
+} as const;
+
+// Base has PancakeSwap V3; Optimism does not, so there the program asks Uniswap V3.
+const onBase = routes.compileSauceRoute("base", program, execution);
+const onOptimism = routes.compileSauceRoute("optimism", program, execution);
+const calls = (bytecode: Uint8Array, factory: string | undefined) =>
+  factory !== undefined &&
+  Array.from(bytecode, (byte) => byte.toString(16).padStart(2, "0"))
+    .join("")
+    .includes(factory.slice(2).toLowerCase());
+if (!calls(onBase.compiled.bytecode[0]!, Base.PancakeswapV3.Factory.address)) {
+  throw new Error("Expected Base to call PancakeSwap V3's factory");
+}
+if (
+  Optimism.PancakeswapV3.Factory.available ||
+  !calls(onOptimism.compiled.bytecode[0]!, Optimism.UniswapV3.Factory.address)
+) {
+  throw new Error("Expected Optimism to fall back to Uniswap V3's factory");
+}
+
+// The same names on the host: a token is its registry row, a contract call is typed from its ABI.
+const usdc = Base.USDC; // { address, decimals, symbol, chain }
+const getPool = Base.PancakeswapV3.Factory.getPool(usdc.address, Base.WETH.address, 500);
+if (usdc.decimals !== 6 || !getPool.data.startsWith("0x1698ee82")) {
+  throw new Error("Expected Base's USDC row and an encoded getPool call");
+}
+console.log("Base pool lookup:", getPool.toCall());
+
+// Call with a client for Base. Importing this example performs no RPC.
+export async function readBasePool(client: PublicClient): Promise<`0x${string}`> {
+  return Base.PancakeswapV3.Factory.getPool(Base.USDC.address, Base.WETH.address, 500).read(client);
+}

package/docs/examples/router-route.sauce.ts

@@ -0,0 +1,31 @@
+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;
+}

package/docs/examples/router-route.ts

@@ -0,0 +1,72 @@
+// Compiles router-route.sauce.ts once, then gives it a route as runtime arguments: the program a Pot
+// cooks is the bytecode followed by the ABI-encoded legs, so one compile serves every route over its
+// venues. Offline: the route is Ethereum's, but nothing is sent.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile, resolveSdkModule, resolveSdkPackage } from "@eco-incorp/sauce/compiler";
+import { concatHex, encodeAbiParameters, toHex } from "viem";
+
+const source = new TextEncoder().encode(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "router-route.sauce.ts"), "utf8"),
+);
+
+// A raw compile names the SDK's own modules: resolveSdkPackage maps `@sauce/router` (and the
+// `@sauce/token` it imports) to the copies the SDK carries, and resolveSdkModule serves their files.
+const { bytecode, entryEncoding } = compile({
+  target: "evm",
+  resolve: (path) => (path === "main.js" ? source : resolveSdkModule(path)),
+  resolvePackage: (specifier) => resolveSdkPackage(specifier),
+});
+if (entryEncoding !== "abi-v1") throw new Error("Expected ABI-encoded arguments");
+
+const WETH = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";
+const USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+const USDT = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
+const none = { i: 0n, j: 0n, poolId: 0n };
+
+// 1 WETH to USDC in Uniswap V3's 0.05% pool, then USDC to USDT in Curve's 3pool.
+const legs = [
+  {
+    venue: 1n,
+    pool: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
+    tokenIn: WETH,
+    tokenOut: USDC,
+    ...none,
+  },
+  {
+    venue: 3n,
+    pool: "0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7",
+    tokenIn: USDC,
+    tokenOut: USDT,
+    i: 1n,
+    j: 2n,
+    poolId: 0n,
+  },
+] as const;
+
+const args = encodeAbiParameters(
+  [
+    {
+      type: "tuple[]",
+      components: [
+        { name: "venue", type: "uint256" },
+        { name: "pool", type: "address" },
+        { name: "tokenIn", type: "address" },
+        { name: "tokenOut", type: "address" },
+        { name: "i", type: "uint256" },
+        { name: "j", type: "uint256" },
+        { name: "poolId", type: "uint256" },
+      ],
+    },
+    { type: "uint256" },
+    { type: "uint256" },
+  ],
+  [legs, 10n ** 18n, 3_000_000_000n],
+);
+
+// The `program` argument of Pot.cook: the reusable bytecode, then this route.
+const program = concatHex([toHex(bytecode), args]);
+console.log(`route program: ${bytecode.length} bytes, plus ${(args.length - 2) / 2} of arguments`);
+console.log(program.slice(0, 18));

package/docs/examples/router-swap.sauce.ts

@@ -0,0 +1,16 @@
+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());
+}

package/docs/examples/router-swap.ts

@@ -0,0 +1,47 @@
+// Compiles router-swap.sauce.ts — a program that swaps through @sauce/router, choosing its amounts
+// as it runs — into the call a Pot cooks, and into an Eco intent of its own.
+//
+// The SauceScript is its own file so it is the same text the router reference shows. Everything
+// here is offline: the Pot, the engine and the fee are fixtures, and nothing is sent.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Base, routes } from "@eco-incorp/sauce";
+
+const program = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "router-swap.sauce.ts"),
+  "utf8",
+);
+
+// The SDK serves @sauce/router — and the @sauce/token and pool ABIs it imports — from memory, so
+// compiling needs no resolver option. MIN_OUT is the floor on the crvUSD the program keeps.
+const defines = { MIN_OUT: 2_500n * 10n ** 18n };
+const compiled = routes.compileSauceRoute(
+  "base",
+  program,
+  {
+    pot: "0x2222222222222222222222222222222222222222",
+    engine: "0x3333333333333333333333333333333333333333",
+  },
+  { defines },
+);
+if (compiled.calls.length !== 1) throw new Error("Expected one cook");
+
+// The same program as an intent body: a solver runs it on Base for a reward on Ethereum.
+const executionFee = 1_000n;
+const built = Base(program, {
+  execution: { value: executionFee },
+  nativeAmount: executionFee,
+  deadline: 2_000_000_000n,
+  defines,
+}).reward({
+  source: "ethereum",
+  creator: "0x4444444444444444444444444444444444444444",
+  prover: "0x5555555555555555555555555555555555555555",
+  deadline: 2_000_003_600n,
+  nativeAmount: executionFee,
+});
+
+console.log(`@sauce/router swap: ${compiled.compiled.bytecode[0]!.length} bytes`);
+console.log(built.hash().intentHash);

package/docs/examples/venue-where-deployed.sauce.ts

@@ -0,0 +1,14 @@
+// One program for every chain: the USDC/WETH 0.05% pool from PancakeSwap V3 where the chain has it,
+// from Uniswap V3 where it does not, and nothing where it has neither.
+//
+// `available(...)` is decided when the program is compiled, for the chain it is compiled for, and
+// the branches it rules out are removed before anything in them is resolved.
+function main() {
+  let pool = 0n;
+  if (available(PancakeswapV3.Factory)) {
+    pool = PancakeswapV3.Factory.getPool(USDC, WETH, 500n);
+  } else if (available(UniswapV3.Factory)) {
+    pool = UniswapV3.Factory.getPool(USDC, WETH, 500n);
+  }
+  return pool;
+}