@eco-incorp/sauce 0.99.4 → 0.99.6

package/docs/concepts/saucescript.md

@@ -2,10 +2,13 @@
 
 [Documentation](../README.md) · [Architecture](architecture.md) · [Compiling](../guides/compiling.md)
 
-SauceScript is a checked subset of TypeScript for programs that run inside the
-Sauce engine. It has familiar variables, functions, conditions, loops, arrays,
-and records, but it does not execute in a JavaScript VM. A host application builds
-and submits programs; SauceScript performs their on-chain computation.
+SauceScript is a checked subset of TypeScript. It has the familiar things —
+variables, functions, conditions, loops, arrays, records — but it does not run in
+a JavaScript engine. Your application builds and submits a program; SauceScript is
+what the chain then executes, atomically, inside that one transaction.
+
+Most of what follows is about the boundary: which TypeScript the compiler accepts,
+and how values get from your application into a program that captures nothing.
 
 ## Programs and route bodies
 
@@ -22,16 +25,17 @@ function main(amounts: Uint256[], minimum: Uint256): Uint256 {
 }
 ```
 
-This is SauceScript source, not a host TypeScript module. `Uint256` and `require`
-are interpreted by the Sauce compiler. Source diagnostics identify the relevant
-location and span; option, resolver, and target-capability errors may have no span.
+This is SauceScript source, not a host TypeScript module: `Uint256` and `require`
+mean something to the Sauce compiler and nothing to `tsc`. A source error points at
+a location and span; an error about an option, a resolver or an unavailable
+target feature has nothing to point at.
 
 A function declared `: void` can finish without returning a value. Other
 functions must return on every path. Annotate helper functions returning arrays,
 bytes, or records so their callers know the return shape. The raw compiler also
 accepts an entry script without an explicit `main` and synthesizes its entry.
 Entry argument encoding does not determine return encoding. For ABI-decodable
-EVM output, [return `abi.encode(...)`](../guides/compiling.md#encode-evm-return-values).
+EVM output, [return `abi.encode(...)`](../guides/compiling.md#return-values-an-abi-decoder-can-read).
 
 The SDK provides a second authoring form: a route body passed to a chain helper.
 
@@ -61,10 +65,11 @@ names or bodies, use explicit source strings or source assets.
 | `main` parameters                   | During execution                       | Values are encoded after the reusable program; their values are not compiler inputs |
 | SVM `Account` parameters            | When instruction accounts are attached | Identities occupy manifest slots, separate from encoded scalar/collection arguments |
 
-The EVM settle recipe takes its token list, floor, and recipient as runtime
-parameters, so one program hash covers all values. The SVM settle recipe compiles
-its floor and token-program split through defines and verifies them by
-recompilation. Those are deliberate API choices, not interchangeable encodings.
+The choice between the first two is a design decision with consequences. The EVM
+settle recipe takes its token list, floor and recipient as runtime parameters, so
+one program — one hash — covers every value. The SVM settle recipe folds its floor
+and token-program split in as defines instead, and is verified by recompiling with
+the same values. Neither is a drop-in for the other.
 
 ## Values and types
 
@@ -88,9 +93,9 @@ Annotations are checked. Arbitrary TypeScript types are not accepted, and `as`
 casts cannot be used to bypass a type error. Ordinary arithmetic is checked by
 the compiler/runtime rather than following JavaScript number semantics.
 
-Module-level scalar `const` values are compile-time values. Module-level `let`
-state is initialized for each invocation; it is not persistent chain state. Use
-the target-specific storage builtins when persistent storage is required.
+A module-level scalar `const` is a compile-time value. A module-level `let` is
+re-initialised on every invocation — it is scratch space, not chain state. Reach
+for the target's storage builtins when something has to persist.
 
 ## Language support
 
@@ -116,8 +121,8 @@ Useful boundaries when adapting application code:
 - A template literal with interpolation is unsupported. The `hex` tagged literal
   produces literal bytes.
 
-These examples and boundaries are validated with Sauce compiler 2.3.0. Additional
-language and builtin references are available at [sauce.eco.com](https://sauce.eco.com).
+Every example and boundary on this page is checked against the compiler this
+package ships.
 
 ## EVM and SVM operations
 
@@ -136,10 +141,10 @@ for the target selected at compile time.
 | SDK `USDC.approve(...)` and protocol-member rewrites | Supported for registered EVM deployments | Use SVM account-aware builders                    |
 | Runtime entry arguments                              | ABI-v1 or compact-v1                     | ABI-v1 or compact-v1, plus separate Account slots |
 
-The absence of SVM `abi.encode`/`abi.decode` builtins does not remove runtime
-entry parameters: entry decoding is its own compiler feature. Context values
-also have target semantics: an EVM address and a Solana public key have different
-widths, and `ctx.blockNumber()` refers to the target's block/slot model.
+Losing `abi.encode`/`abi.decode` on Solana does not cost you runtime entry
+parameters — those are decoded by a separate mechanism and work on both targets.
+Context reads differ where the chains differ: an EVM address and a Solana public
+key are not the same width, and `ctx.blockNumber()` means a slot on Solana.
 
 ## Modules, ABI bindings, and global names
 
@@ -148,8 +153,8 @@ A direct compiler program can bind an EVM ABI explicitly:
 ```ts
 import ERC20 from "./erc20.abi.json";
 
-function main(token: Address, spender: Address, amount: Uint256): void {
-  ERC20.at(token).approve(spender, amount);
+function main(token: Address, owner: Address): Uint256 {
+  return ERC20.at(token).balanceOf(owner);
 }
 ```
 
@@ -157,6 +162,23 @@ A bare JSON import binds a contract ABI. A JSON data import uses
 `with { type: "json" }`. The host resolver must return the named file's bytes in
 either case.
 
+An ABI-bound call decodes what the ABI declares it returns. For an ERC-20 write
+that is a `bool`, so `ERC20.at(token).approve(...)` reverts on a token that
+returns nothing, such as USDT, and accepts one that returns `false`. Write token
+transfers and approvals with `@sauce/token` instead, which follows OpenZeppelin
+`SafeERC20`:
+
+```ts
+import { approve } from "@sauce/token";
+
+function main(token: Address, spender: Address, amount: Uint256): void {
+  approve(token, spender, amount);
+}
+```
+
+A raw compile resolves `@sauce/token` by passing `resolveSdkPackage` and
+`resolveSdkModule` from `@eco-incorp/sauce/compiler`.
+
 The compiler's `ambient` option broadcasts a SauceScript module's exports without
 explicit imports. Its `defines` option injects scalar constants into every
 module. Their precedence differs: ambient exports yield to declarations;
@@ -168,5 +190,4 @@ that compiler API. `openRoute` and chain helpers supply chain defines and the
 default `@sauce/token` ambient module. Direct `compileSauceRoute()` accepts an
 explicit `ambient` list and does not add that default list. Raw `compile()` adds
 neither the SDK registry nor its filesystem resolver. See the
-[compilation guide](../guides/compiling.md#choose-a-compilation-path) for the exact
-boundary.
+[compilation guide](../guides/compiling.md) for the exact boundary.

package/docs/examples/README.md

@@ -2,14 +2,21 @@
 
 [Documentation](../README.md) · [Quick start](../guides/quick-start.md)
 
-These examples use the published package exports. The construction examples run offline: they compile source and construct transaction data without sending transactions. Repeated-digit addresses and illustrative fees are fixtures, not deployment configuration. The RPC setup helper is typechecked but only makes chain reads when your application calls it.
-
-| Example                                      | Demonstrates                                                                                                                   |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| [protocol-approval.ts](protocol-approval.ts) | A typed `Base(() => ...)` callback with `USDC.approve(Uniswap.UniversalRouter, ...)`                                           |
-| [first-intent.ts](first-intent.ts)           | Ethereum reward, Base USDC delivery, Executor-to-Pot funding, explicit callback defines, source transaction requests           |
-| [compile-program.ts](compile-program.ts)     | The compiler dependency, compact entry schema, argument encoding and decoding                                                  |
-| [evm-execution.ts](evm-execution.ts)         | Destination RPC setup helper: current Kitchen, Portal Executor ownership, Pot prediction/deployment request, and execution fee |
+These run against the published package exports, and they run on every release — if one of them
+stops working, the release does. The construction examples are offline: they compile source and
+build transaction data without sending anything. Repeated-digit addresses and round fees are
+fixtures, not configuration. The RPC helper is typechecked here and reads chain state only when your
+application calls it.
+
+| Example                                                    | Shows                                                                                                                 |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [cross-chain-intent.sauce.ts](cross-chain-intent.sauce.ts) | A program that measures a balance and publishes a new intent carrying it — written in SauceScript                     |
+| [cross-chain-intent.ts](cross-chain-intent.ts)             | Compiling that program with `defines` and attaching it to a route                                                     |
+| [protocol-approval.ts](protocol-approval.ts)               | A typed `Base(() => ...)` body calling `USDC.approve(Uniswap.UniversalRouter, ...)`                                   |
+| [first-intent.ts](first-intent.ts)                         | Both sides of a transfer intent: Ethereum reward, Base delivery, Executor-to-Pot funding, source transaction requests |
+| [compile-program.ts](compile-program.ts)                   | Direct compilation, a compact entry schema, and argument encoding and decoding                                        |
+| [action-program.ts](action-program.ts)                     | A JSON action program: strict parsing, compilation with a runtime amount, and an intent on the program's chain        |
+| [evm-execution.ts](evm-execution.ts)                       | Reading a destination chain: Kitchen, Executor ownership, Pot prediction and deployment, execution fee                |
 
 ## Run an example in your project
 
@@ -29,6 +36,7 @@ node dist/example.js
 
 For `first-intent.ts` and `evm-execution.ts`, also run `pnpm add viem`: they use Viem's address formatter and RPC interfaces.
 
-The examples are typechecked and loaded automatically in the SDK's CI. Construction examples assert their encoded output, including nonzero cook-fee budgeting; the RPC helper is not a live-chain integration test.
+CI typechecks and runs each of them, and asserts the encoded output including a nonzero cook-fee
+budget. The RPC helper is not a live-chain integration test — it is the shape of the reads you make.
 
-For actual EVM execution, first call `prepareDestinationPot` from `evm-execution.ts` with a destination client, Portal, and salt. If it returns `ready: false`, send its deployment request with your signer, wait for a successful receipt, and call it again. When `ready: true`, use its Pot, engine, and observed execution fee instead of the offline fixtures. Supply valid deadlines, source funding, and solver fulfillment. Read [intents](../guides/intents.md) for atomic asset handling and fee budgets, and [Solana](../guides/solana.md) for the separate supported execution paths.
+For actual EVM execution, read the destination Kitchen's `executionFee()` and use it instead of the fixture fee. The intent examples name no Pot or engine: the SDK derives both. The derived Pot is the shared one the solver deploys for each Portal, and it must exist before a route runs on it. To check that it does, or to use a Pot of your own, call `prepareDestinationPot` from `evm-execution.ts` with a destination client, Portal, and salt (zero for the shared Pot). If it returns `ready: false`, send its deployment request with your signer, wait for a successful receipt, and call it again. Pass a Pot of your own as `execution.pot`. Supply valid deadlines, source funding, and solver fulfillment. Read [intents](../guides/intents.md) for atomic asset handling and fee budgets, and [Solana](../guides/solana.md) for the separate supported execution paths.

package/docs/examples/action-program.ts

@@ -0,0 +1,75 @@
+import {
+  compileProgram,
+  parseProgram,
+  programIntent,
+  ProgramError,
+  serializeProgram,
+} from "@eco-incorp/sauce/actions";
+
+// A program as it would arrive from another service: JSON text. Base USDC; the spender is a fixture.
+const json = `{
+  "version": 1,
+  "chainId": 8453,
+  "actions": [
+    { "type": "balanceOf", "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+    {
+      "type": "approve",
+      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "spender": "0x1111111111111111111111111111111111111111"
+    }
+  ]
+}`;
+const program = parseProgram(json);
+if (serializeProgram(program) !== JSON.stringify(JSON.parse(json))) {
+  throw new Error("Expected the canonical text to be the input's");
+}
+
+// Every problem is reported at once, each with its path.
+try {
+  parseProgram({ ...program, actions: [{ type: "approve", amount: 5 }] });
+  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 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");
+
+// As an intent: the route runs on the program's chain, Base. Offline fixtures throughout.
+const executionFee = 1_000n;
+const built = programIntent(program, {
+  execution: {
+    pot: "0x2222222222222222222222222222222222222222",
+    engine: "0x3333333333333333333333333333333333333333",
+    value: executionFee,
+  },
+  nativeAmount: executionFee,
+  portal: "0x4444444444444444444444444444444444444444",
+  deadline: 2_000_000_000n,
+}).reward({
+  source: "ethereum",
+  creator: "0x5555555555555555555555555555555555555555",
+  prover: "0x6666666666666666666666666666666666666666",
+  deadline: 2_000_003_600n,
+  nativeAmount: executionFee,
+});
+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("Action intent:", built.hash().intentHash);

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

@@ -0,0 +1,21 @@
+// Three hops, written as three intents opening one another.
+//
+// No amount below the first exists when this is signed. `amount` is measured here. `swapped` is
+// measured on Arbitrum while that hop is being fulfilled, by the program the middle braces compiled
+// to, and it is the reward of the third hop. Each level's numbers are filled in by the level above
+// it, at that level's own execution time.
+//
+// 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.
+function main() {
+  const amount = USDC.balanceOf(ctx.self());
+  Arbitrum(
+    () => {
+      const swapped = USDC.balanceOf(ctx.self());
+      Optimism(() => {
+        USDC.transfer(RECIPIENT, swapped);
+      }).reward({ tokens: [{ token: USDC, amount: swapped }] });
+    },
+    { tokens: [{ token: USDC, amount }] },
+  ).reward({ tokens: [{ token: USDC, amount }] });
+}

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

@@ -0,0 +1,43 @@
+// Compiles cross-chain-cascade.sauce.ts — three hops whose amounts are each measured on arrival.
+//
+// Offline: the addresses and the fee are fixtures and nothing is sent. The Portals, the provers and
+// the destination Pots come from the SDK's own tables; the execution fee does not, because it is
+// mutable on-chain and lives on the destination — read it with `destinationExecutionFee()`.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Base, destinationExecutionFee } from "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+const program = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "cross-chain-cascade.sauce.ts"),
+  "utf8",
+);
+
+const creator = "0x4444444444444444444444444444444444444444";
+const executionFee = 1_000n; // Fixture: `destinationExecutionFee()` builds the read for the real one.
+
+const options: routes.IntentOptions = {
+  execution: { value: executionFee },
+  nativeAmount: executionFee,
+  deadline: 2_000_000_000n,
+  creator,
+  prover: "0x5555555555555555555555555555555555555555",
+  source: "ethereum",
+  defines: { RECIPIENT: BigInt("0x6666666666666666666666666666666666666666") },
+  // A program body cooks, so its hop needs the destination Kitchen's fee. Everything else the
+  // intents inherit from this one.
+  compile: { intents: { executionFee } },
+};
+
+const built = Base(program, options).reward({
+  creator,
+  prover: "0x5555555555555555555555555555555555555555",
+  deadline: 2_000_003_600n,
+  nativeAmount: 0n,
+});
+
+console.log(`Cascade program: ${built.compiled.bytecode[0]!.length} bytes`);
+console.log(`Fee is read from ${destinationExecutionFee().to}`);
+console.log(built.hash().intentHash);

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

@@ -0,0 +1,23 @@
+// Create a cross-chain intent from inside a Sauce program.
+//
+// This runs on one chain as part of an intent's route, measures what the calls before it left in
+// the Pot, and offers a NEW intent that carries that amount onward to another chain. The amount is
+// never known in advance — it is whatever the swap, bridge or transfer just before it produced —
+// which is the reason to build the intent here rather than off-chain.
+//
+// `Arbitrum(() => { ... }).reward({ ... })` is the whole of it. `amount` is an ordinary variable of
+// this program, and using it inside the intent is enough: the SDK splices its run-time value into
+// 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.
+function main() {
+  const amount = USDC.balanceOf(ctx.self());
+  if (amount < MIN_AMOUNT) {
+    throw "cross-chain-intent: nothing to forward";
+  }
+
+  Arbitrum(() => {
+    USDC.transfer(RECIPIENT, amount);
+  }).reward({ tokens: [{ token: USDC, amount }] });
+}

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

@@ -0,0 +1,49 @@
+// Compiles cross-chain-intent.sauce.ts — the program that creates an intent from inside another
+// intent — and packages it as an Eco intent of its own.
+//
+// The SauceScript is its own file rather than a template literal so it is the same text the README
+// shows and the same text you can compile yourself. Everything here is offline: the addresses 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 } from "@eco-incorp/sauce";
+import type { routes } from "@eco-incorp/sauce";
+
+const program = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "cross-chain-intent.sauce.ts"),
+  "utf8",
+);
+
+// Offline fixtures. Read the destination Kitchen fee before use. The Pot and engine are derived.
+const executionFee = 1_000n;
+const creator = "0x4444444444444444444444444444444444444444";
+
+const options: routes.IntentOptions = {
+  execution: { value: executionFee },
+  nativeAmount: executionFee,
+  // No `portal`: the SDK carries the eco-routes deployments, and this intent runs on Base.
+  deadline: 2_000_000_000n,
+  creator,
+  prover: "0x5555555555555555555555555555555555555555",
+  source: "ethereum",
+  // The names the program reads. A define is one 256-bit word folded into the bytecode, which is
+  // how a program is parameterised — it captures nothing from the JavaScript around it.
+  defines: {
+    RECIPIENT: BigInt("0x6666666666666666666666666666666666666666"),
+    MIN_AMOUNT: 1n,
+  },
+};
+
+// The intent the program creates inherits this one's deadline, creator and eco-routes deployment,
+// so there is nothing extra to configure for it.
+const built = Base(program, options).reward({
+  creator,
+  prover: "0x5555555555555555555555555555555555555555",
+  deadline: 2_000_003_600n,
+  nativeAmount: 0n,
+});
+
+console.log(`Cross-chain intent program: ${built.compiled.bytecode[0]!.length} bytes`);
+console.log(built.hash().intentHash);

package/docs/examples/first-intent.ts

@@ -1,9 +1,10 @@
-import { routes, token } from "@eco-incorp/sauce";
+import { Base, destinationPot, Ethereum, routes, token } from "@eco-incorp/sauce";
 import { toHex } from "viem";
 
-// Offline fixtures. Use prepareDestinationPot from evm-execution.ts before submission
-// to verify the Executor-owned Pot and read the current Kitchen fee.
-const pot = "0x1111111111111111111111111111111111111111";
+// Offline fixtures. Read the current Kitchen fee before submission.
+const portal = "0x4444444444444444444444444444444444444444";
+// The Pot the route cooks on: the shared one owned by that Portal's Executor. It must already exist.
+const pot = destinationPot(Base.chain, { portal });
 const executionFee = 1_000n;
 const baseUsdcValue = routes.registryTokenAddress(Base.chain, "USDC");
 const sourceUsdcValue = routes.registryTokenAddress(Ethereum.chain, "USDC");
@@ -19,13 +20,9 @@ const built = Base(
     USDC.transfer(recipient, amount);
   },
   {
-    execution: {
-      pot,
-      engine: "0x3333333333333333333333333333333333333333",
-      value: executionFee,
-    },
+    execution: { value: executionFee },
     nativeAmount: executionFee,
-    portal: "0x4444444444444444444444444444444444444444",
+    portal,
     sourcePortal: "0x5555555555555555555555555555555555555555",
     deadline: 2_000_000_000n,
     // Callbacks capture nothing: explicitly supply every external scalar.

package/docs/examples/protocol-approval.ts

@@ -1,14 +1,10 @@
-import "@eco-incorp/sauce";
+import { Base } from "@eco-incorp/sauce";
 import type { routes } from "@eco-incorp/sauce";
 
-// Offline fixtures. Read the destination Kitchen fee and use an Executor-owned Pot before use.
+// Offline fixtures. Read the destination Kitchen fee before use. The Pot and engine are derived.
 const executionFee = 1_000n;
 const options: routes.IntentOptions = {
-  execution: {
-    pot: "0x1111111111111111111111111111111111111111",
-    engine: "0x2222222222222222222222222222222222222222",
-    value: executionFee,
-  },
+  execution: { value: executionFee },
   nativeAmount: executionFee,
   portal: "0x3333333333333333333333333333333333333333",
   deadline: 2_000_000_000n,