@eco-incorp/sauce 0.99.3 → 0.99.5

package/README.md

@@ -1,35 +1,98 @@
 # Sauce
 
-Write programmable transactions and Eco intents with **`@eco-incorp/sauce`**. The SDK compiles
-SauceScript into bytecode for the Sauce EVM and Solana runtimes, resolves protocol contracts and
-tokens, and builds the calls that execute your program.
+**Sauce is a programmable-transaction runtime.** You write a program, it compiles to bytecode, and a
+Sauce engine executes it atomically inside one transaction on EVM or Solana. Either the whole
+program lands or none of it does.
+
+`@eco-incorp/sauce` is the developer package for that runtime: the compiler, the chain and protocol
+knowledge a program needs, and the builders that turn a program into a transaction.
+
+On top of the runtime sits a second layer — **routes**. A route packages a program as an Eco intent:
+an offer to have that program executed on another chain, with a reward escrowed here for whoever
+executes it there. Cross-chain execution is this layer, not the runtime.
 
 ```sh
 npm install @eco-incorp/sauce
 ```
 
-[Documentation](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/README.md) · [Quick start](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/quick-start.md) ·
-[Examples](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/examples/README.md) · [API reference](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/api/README.md)
+Node.js **24 or newer**, or a browser — [one `await ready()`](docs/api/compiler.md#in-a-browser) and the
+same code compiles the same bytes.
+
+[Documentation](docs/README.md) · [Quick start](docs/guides/quick-start.md) ·
+[Examples](docs/examples/README.md) · [API reference](docs/api/README.md)
+
+## A program that creates a cross-chain intent
+
+A program can spend an intent's funds, and it can also create the next intent. That is where the
+runtime and the routes layer meet. This program measures an amount nobody knew in advance and offers
+an intent carrying it onward.
+
+```js
+// 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 }] });
+}
+```
+
+That is the whole program. What you did not have to do:
+
+- **Write or deploy a contract.** It compiles to bytecode that a Sauce engine runs in the shared
+  Pot the solver deploys.
+- **Import anything.** `USDC`, `Arbitrum` and `ctx` need no import line.
+- **Encode the intent.** No Portal, prover, selector, approval or ABI encoding appears. The SDK
+  looks up the Portal and prover in its eco-routes deployment tables and emits the rest.
+- **Know the amount in advance.** `amount` is an ordinary variable, and the published intent
+  carries the value the program measured.
+- **Roll back by hand.** Below `MIN_AMOUNT` the `throw` reverts the whole fulfilment: nothing is
+  published, and no earlier call in the route survives.
 
-Use Node.js **24 or newer**. The links open the Markdown manual and examples included in this package version. After installation, you can also open `node_modules/@eco-incorp/sauce/docs/README.md` locally.
+Without Sauce, this hop is either a contract you write and deploy (read the balance, approve the
+Portal, encode the intent around the amount, call `publishAndFund`) or a second intent you publish
+yourself after the first lands and you have read what it produced.
 
-## Programs with protocol and token globals
+`USDC` is a registered token symbol, and inside the braces it means **Arbitrum's** USDC, because
+that is where those calls run. `RECIPIENT` and `MIN_AMOUNT` are compile-time `defines`: a program
+captures nothing from the JavaScript around it, so defines are how application values reach one.
 
-This complete example builds an intent offline. The repeated-digit addresses and fee are fixtures;
-no transaction is sent. Select a destination chain, then use its contracts and tokens in the program:
+You supply what the SDK cannot know once, on the enclosing intent, and every intent the program
+creates inherits it: a deadline, and the creator who may reclaim the reward if nobody earns it. The
+intent is an offer; a solver still decides to fill it.
+[docs/examples/cross-chain-intent.ts](docs/examples/cross-chain-intent.ts) is the caller, run on
+every release; [nested intents](docs/guides/nested-intents.md) covers cascades several hops deep.
+
+## A program that calls protocols and tokens by name
+
+Inside a route body the SDK resolves token symbols and protocol contracts against the destination
+chain, so a program reads like the operation it performs. This example builds a complete intent
+offline; the repeated-digit addresses and the fee are fixtures and nothing is sent.
 
 ```ts
-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.
-const executionFee = 1_000n;
+const executionFee = 1_000n; // Read the destination Kitchen's executionFee() before use.
 const options: routes.IntentOptions = {
-  execution: {
-    pot: "0x1111111111111111111111111111111111111111",
-    engine: "0x2222222222222222222222222222222222222222",
-    value: executionFee,
-  },
+  // No Pot or engine: both are derived. The Pot is the shared one the solver deploys per Portal.
+  execution: { value: executionFee },
   nativeAmount: executionFee,
   portal: "0x3333333333333333333333333333333333333333",
   deadline: 2_000_000_000n,
@@ -48,49 +111,28 @@ const built = Base(() => {
 console.log(built.hash().intentHash);
 ```
 
-The [quick start](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/quick-start.md) explains the setup, and the [examples](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/examples/README.md) are checked
-against the SDK. The callback is compiled as source. Token and protocol names resolve on Base;
-values from surrounding JavaScript must be supplied through compile-time `defines`.
-
-Use `USDC.transfer(...)`, `USDC.balanceOf(...)`, `Token(address).approve(...)`, and linked protocol
-methods in the same program. `Uniswap.UniversalRouter` is the family alias for
-`UniswapV4.UniversalRouter`; available contracts and methods come from the
-[accessor registry](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/api/coverage.md). The compiler checks chain availability and ABI fidelity.
-
-## From a program to an intent
-
-`Base(body, options).reward(reward)` compiles a destination program and constructs an Eco intent.
-The result exposes the intent, bytecode, hashes, and Portal transaction requests. Your application
-submits those requests. Direct Portal execution requires an Executor-owned Pot and native value for the Kitchen execution fee. Use `.nest(...)` to compose intents with separate executions and funding.
-
-Use the direct Kitchen client for Solana execution. The legacy SVM intent helper is incompatible
-with the released gated engine; the Solana guide below describes this boundary.
-
-- [Create and fund an intent](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/intents.md)
-- [Compose nested intents](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/nested-intents.md)
-- [Build programs with token, swap, deposit, and action helpers](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/builders-and-actions.md)
-- [Execute on Solana](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/solana.md)
-- [Verify settlement programs](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/verification.md)
-
-## Compiler and runtime
-
-The SDK includes **`@eco-incorp/sauce-compiler`**, the Rust/WebAssembly SauceScript compiler, and
-exposes it through `@eco-incorp/sauce/compiler`. Compile directly when you need entry arguments,
-custom module resolution, or SVM account manifests. See the [compiler guide](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/compiling.md)
-and [compiler API](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/api/compiler.md).
-
-SauceScript supports contract calls, arithmetic, control flow, and composition within the
-[compiler's language subset](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/concepts/saucescript.md). A program executes atomically in one
-transaction on its target chain. Cross-chain intents coordinate separate transactions.
-
-The root SDK and its compiler integration require Node.js **24 or newer**. The compiler dependency also has its
-own browser entry point. See [architecture](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/concepts/architecture.md) for how the SDK,
-compiler, and deployed runtime work together.
-
-Current release pins: compiler **2.3.0**, EVM engine **1.0.1**, SVM engine **1.1.0**, both Kitchens
-**1.0.0**. Release addresses do not establish on-chain deployment status.
-
-The EVM settle program compiles to **356 bytes** with a new verification hash. Recompile and
-invalidate cached programs when upgrading; to verify existing 362-byte payloads, pass their
-historical `{ hash, bytes: 362 }` pin to `validateSettleProgram` (see
-[verification](https://unpkg.com/@eco-incorp/sauce@0.99.3/docs/guides/verification.md)).
+Two kinds of name meet in that snippet. `Base` is a **named export**, one per chain; importing the
+package puts nothing on `globalThis`. `USDC` and `Uniswap` are **program syntax**: the SDK resolves
+them to Base's addresses and binds the ABI, so there is no address to look up and no JavaScript
+object to import. The callback is read as source text and never invoked, so it captures nothing;
+application values reach it through `defines`.
+
+`.reward(...)` completes the intent and returns its hashes, bytecode and the Portal transaction
+requests your application submits. [Quick start](docs/guides/quick-start.md) walks through it, and
+[protocols and tokens](docs/guides/protocols-and-tokens.md) covers the names available.
+
+## What else is in the package
+
+| You want to                                         | Start at                                        |
+| --------------------------------------------------- | ----------------------------------------------- |
+| Build, fund and submit an intent                    | [Create an intent](docs/guides/intents.md)      |
+| Chain intents together, statically or at run time   | [Nested intents](docs/guides/nested-intents.md) |
+| Generate programs from data instead of writing them | [Builders](docs/guides/builders-and-actions.md) |
+| Compile a standalone program with runtime arguments | [Compiling programs](docs/guides/compiling.md)  |
+| Execute on Solana                                   | [Solana](docs/guides/solana.md)                 |
+| Check what a settlement payload contains            | [Verification](docs/guides/verification.md)     |
+| Know which protocols, tokens and chains are wired   | [Coverage](docs/api/coverage.md)                |
+
+The SauceScript compiler ships inside this package; there is no separate install and no compiler
+checkout. [Architecture](docs/concepts/architecture.md) explains how the pieces fit,
+[SauceScript](docs/concepts/saucescript.md) the language itself.