@eco-incorp/sauce 0.99.4 → 0.99.5

package/docs/guides/compiling.md

@@ -2,29 +2,28 @@
 
 [Documentation](../README.md) · [Compiler API](../api/compiler.md) · [SauceScript](../concepts/saucescript.md)
 
-Use the SDK route compiler when a program should become an Eco route call with
-chain-scoped token and protocol names. Use the raw compiler when you need a
-reusable parameterized program, an SVM account manifest, or explicit compiler
-options such as compact arguments.
+There are two ways to compile, and the choice is about who resolves names. Either way the compiler
+is already in this package, and the output is a program a Sauce engine runs, not a contract you
+deploy.
 
-## Choose a compilation path
+Use the **route path** when the program is part of an Eco intent and should say `USDC` and
+`Uniswap.UniversalRouter`: the SDK resolves those against the destination chain and hands you a
+ready-made call. Use the **raw compiler** when you want a reusable program that takes values at
+execution time, a Solana account manifest, or full control over module resolution.
 
-| Entry point                                                         | Inputs you supply                                           | What the SDK supplies                                                                              |
+| Entry point                                                         | You supply                                                  | The SDK supplies                                                                                   |
 | ------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `Base(body, options)` / `routes.openRoute(...)`                     | Closure or source, intent options, execution addresses      | Chain defines, default ambient `@sauce/token`, registry rewrites, compilation, intent construction |
-| `routes.compileSauceRoute(destination, source, execution, options)` | Source, destination, execution settings                     | Registry rewrites, token defines, compilation, one encoded route call                              |
-| `compile({ target, resolve, ... })`                                 | Complete source/dependency resolution and compiler settings | The published compiler result, including entry metadata and SVM manifest                           |
+| `Base(body, options)` / `routes.openRoute(...)`                     | Body and intent options                                     | Chain defines, the ambient token module, registry rewrites, the EVM Pot and engine, a built intent |
+| `routes.compileSauceRoute(destination, source, execution, options)` | Source, destination, execution settings                     | Registry rewrites, token defines, one encoded route call                                           |
+| `compile({ target, resolve, ... })`                                 | All source and dependency resolution, and compiler settings | Nothing — you get the compiler's own result                                                        |
 
-Bare `USDC`, `Token(address)`, and protocol-member calls are resolved by SDK route
-rewrites. Raw `compile()` expects compiler-native source, such as
-`ERC20.at(address).approve(...)` backed by an ABI import or registered binding.
+Bare `USDC`, `Token(address)` and protocol members only exist on the route path. There,
+`USDC.approve(Uniswap.UniversalRouter, 1_000_000n)` becomes an ERC-20 ABI import and
+`IERC20.at(USDC).approve(<the router's Base address>, 1_000_000n)`, with `USDC` defined as Base's
+USDC. Raw `compile()` expects you to write that yourself.
 
 ## Compile an EVM route
 
-This function constructs a call; the caller supplies the deployed Pot,
-compatible engine address, and the Kitchen's current execution fee. It submits
-no transaction.
-
 ```ts
 import { routes } from "@eco-incorp/sauce";
 import type { Address } from "viem";
@@ -38,24 +37,22 @@ export function buildApprovalRoute(pot: Address, engine: Address, executionFee:
 }
 ```
 
-The destination determines registry addresses. The result contains one entry in
-`calls` and the compiled program in `compiled.bytecode[0]`. Inspect `source` to
-see the SDK's rewrites. This approval program spends no native token, so its call
-value is only the execution fee. A program spending native tokens also needs that
-amount in its call value. For Portal fulfillment, the Pot must be owned by the
-destination Portal's Executor, and `route.nativeAmount` must cover the call values.
-Use [the intent guide](intents.md) to read the fee, derive the correctly owned Pot,
-and add source-chain funding, a reward, and Portal publication calldata.
+The destination selects the registry addresses. The result has one entry in `calls` and the program
+in `compiled.bytecode[0]`; read `source` to see exactly what the rewrites produced.
+
+The call's `value` is the Kitchen fee plus whatever native the program itself spends — this approval
+spends none. For Portal fulfillment the Pot must be owned by the destination Portal's Executor and
+`route.nativeAmount` must cover every call value. [Create an intent](intents.md) covers reading the
+fee, deriving that Pot, and adding the reward and Portal calldata.
 
-`compileSauceRoute` accepts a bare body or a complete `function main(...)`
-program. Keep route source in the JavaScript syntax accepted by its rewrite
-passes; use raw `compile` for programs that require SauceScript type annotations.
-The raw compiler accepts typed source directly.
+`compileSauceRoute` takes a bare body or a complete `function main(...)`. Its rewrite passes parse
+the body as JavaScript, so a body carrying SauceScript type annotations belongs in raw `compile`,
+which accepts typed source directly.
 
 ## Compile a reusable program
 
-This Node example compiles a program that sums runtime inputs and checks a floor.
-All modules are in memory, so it needs no filesystem resolver.
+A program compiled this way has no values baked into it. Change the amounts and you do not
+recompile — which is what makes one program hash cover every execution.
 
 ```ts
 import { compile } from "@eco-incorp/sauce/compiler";
@@ -78,17 +75,13 @@ const artifact = compile({
   resolve: (path) => (path === "main.ts" ? entry : undefined),
 });
 
-console.log(artifact.isaRevision); // "stack-compact-v2"
 console.log(artifact.entryEncoding); // "abi-v1"
 ```
 
-The amount list and minimum have not been supplied yet. Changing those execution
-values does not require recompilation.
-
-### ABI-v1 entry arguments
+### Pass arguments with ABI-v1
 
-Encode the `main` arguments in declaration order and append them to the compiled
-program. Entry arguments have no function selector.
+Encode `main`'s arguments in declaration order and append them to the program. There is no function
+selector: entry arguments are not a contract call.
 
 ```ts
 import { encodeAbiParameters, hexToBytes, bytesToHex } from "viem";
@@ -104,18 +97,17 @@ payload.set(args, artifact.bytecode.length);
 
 // Given a compatible engine address:
 // const data = v12Pot.encodeCook(engine, bytesToHex(payload));
-// Send `data` from the Pot owner with value = executionFee + programNativeValue.
+// Send it from the Pot owner with value = executionFee + native the program spends.
 ```
 
-The same byte payload is the `program` argument to `Pot.cook(engine, program)`;
-the outer cook call has its own ordinary contract ABI encoding. Supplying
-argument bytes to the compiler as `defines` would produce a different kind of
-program, specialized to those values.
+That whole payload is the `program` argument to `Pot.cook(engine, program)`; the cook call itself is
+an ordinary contract call with its own ABI encoding. Passing those same values as `defines` instead
+would produce a _different_ program — one specialised to them.
 
-### Compact-v1 entry arguments
+### Pass arguments with compact-v1
 
-Compile the same source with `compactArgs: true`, then use the returned schema.
-The schema and bytecode belong to the same artifact.
+Compile with `compactArgs: true` and use the schema that comes back with it. The schema and the
+bytecode belong to the same artifact; do not pair one with another.
 
 ```ts
 import {
@@ -144,16 +136,14 @@ compactPayload.set(compact.bytecode);
 compactPayload.set(compactArgs, compact.bytecode.length);
 ```
 
-A compact program requires an engine implementing its ISA revision. It does not
-accept an ABI-v1 tail, and an ABI-v1 program does not accept compact arguments.
-Compact encoding often reduces scalar and collection payload size, but runtime
-heap, compute, and transaction limits still apply. Its format does not change
-contract ABI calls performed inside the program.
+Compact encoding is usually smaller for scalars and collections. The two formats are not
+interchangeable: a compact program does not accept an ABI-v1 tail, and the reverse is equally true.
+Either way, contract calls the program _makes_ still use their own contract ABIs — this is about
+getting values into `main`, nothing else.
 
-### Encode EVM return values
+### Return values an ABI decoder can read
 
-`entryEncoding` and `compactArgs` describe inputs only. To return data for a host
-ABI decoder, encode it explicitly in SauceScript:
+`entryEncoding` describes inputs. Outputs are yours to encode:
 
 ```ts
 function main(): bytes {
@@ -161,22 +151,17 @@ function main(): bytes {
 }
 ```
 
-Decode that result as one `uint256[]` with Viem's `decodeAbiParameters`. It is
-160 bytes: an offset, an element count, and three values. The EVM Pot returns
-these bytes directly; do not decode another ABI `bytes` wrapper around them.
-This applies with both ABI-v1 and compact-v1 inputs. SVM has no `abi.encode`
-builtin.
-
-Compiler 2.3.0 changed raw EVM scalar-array literal returns: `return [1n, 2n, 3n]`
-now returns three packed 32-byte values without an ABI offset or count. Compiler
-2.2.1 returned heap descriptors for that source. Raw tuple returns still contain
-heap descriptors. Recompilation can therefore change observable return bytes;
-use explicit `abi.encode` when a caller relies on ABI output.
+Decode that as a single `uint256[]` with viem's `decodeAbiParameters`. It is 160 bytes — an offset, a
+count, three values. The Pot returns those bytes directly; there is no extra ABI `bytes` wrapper
+around them. Returning a raw array instead gives you packed words with no offset or count, which a
+generic decoder will not read, so encode explicitly whenever a caller depends on the shape. Solana
+has no `abi.encode`.
 
 ## Resolve source modules and ABIs
 
-A resolver is synchronous and returns bytes. Missing target-arm candidates must
-return `undefined`; unreadable existing files should fail compilation.
+A resolver is synchronous and returns bytes. Return `undefined` for a candidate that does not exist —
+that is how the compiler probes a target-specific arm before falling back. Throw when a file that
+_does_ exist cannot be read, so the failure is not mistaken for absence.
 
 ```ts
 import { readFileSync } from "node:fs";
@@ -200,22 +185,42 @@ const artifact = compile({
 });
 ```
 
-This resolver reads files; it is not an isolation boundary for untrusted source.
-Use an allowlisted virtual module map when applications accept user-supplied
-programs. Fetch any remote modules before the synchronous compile step.
+This resolver reads the filesystem; it is not a sandbox. If your application compiles programs
+somebody else wrote, serve them from an allowlisted in-memory map instead. Fetch anything remote
+_before_ compiling — the resolver cannot await.
+
+For an ABI you already hold, raw compilation takes
+`inlineContracts: [["ERC20", JSON.stringify(abi)]]`. The route API takes the parsed form,
+`contracts: { ERC20: { abi } }`, and adapts it. The two shapes are not interchangeable.
+
+Raw compilation serves nothing you do not. The route path serves the SDK's own files itself: the
+`@sauce/token` library, the ERC-20 and Sauce Router ABIs and every protocol ABI twin. For a raw
+compile that needs them, fall back to `resolveSdkModule` and `resolveSdkPackage` from
+`@eco-incorp/sauce/compiler` — the [compiler reference](../api/compiler.md#the-sdks-own-modules)
+shows how.
 
-For an ABI already held in memory, use raw compiler
-`inlineContracts: [["ERC20", JSON.stringify(abi)]]`. The route API instead accepts
-`contracts: { ERC20: { abi } }` with a parsed ABI and adapts it internally.
-Do not pass the route shape to raw `compile()`.
+The filesystem resolver above is the one Node-only part of this page. In a browser, serve modules
+from memory.
+
+## Compile in a browser
+
+Everything on this page runs in a browser and compiles the same bytes as Node. The compiler's
+WebAssembly loads asynchronously there, so call `ready()` once before the first compile:
+
+```ts
+import { ready } from "@eco-incorp/sauce";
+
+await ready();
+```
 
-Raw compiler resolution does not automatically locate the SDK's `@sauce/token`
-copy. SDK route compilation resolves that package itself. With raw compilation,
-provide the package's source and neutral entry mapping through your resolver.
+With no argument it fetches the wasm from beside the compiler's module, which is where a bundler
+that handles `new URL(…, import.meta.url)` puts it. Otherwise pass the wasm's URL or bytes. The
+[compiler reference](../api/compiler.md#in-a-browser) covers both, and the one subpath that stays
+Node-only.
 
-## Compile for SVM
+## Compile for Solana
 
-Selecting `target: "svm"` produces an account manifest. For example:
+`target: "svm"` returns an account manifest alongside the bytecode:
 
 ```ts
 import { compile } from "@eco-incorp/sauce/compiler";
@@ -236,29 +241,23 @@ console.log(artifact.manifest?.accounts);
 // [{ kind: "slot", index: 0, name: "vault", requires: "readonly" }]
 ```
 
-The compact root has one field, `amount`; `vault` is attached at account slot 0.
-Resolve and attach accounts in manifest order using the SVM helpers. The manifest
-does not discover an account's address, balance, owner, or liveness.
+`amount` is the one compact field; `vault` is attached at account slot 0. Resolve and attach accounts
+in manifest order with the SVM helpers. The manifest records what the _author_ declared — it does not
+discover an account's address, balance, owner or existence.
 
-For staged execution, stage the bytes through the Kitchen, finalize the code
-account, then use the Kitchen client or instruction builders. The SVM
-`routes.compileSauceRoute` path drops the manifest and emits a legacy instruction
-incompatible with the released engine. Use raw compilation for account plans
-and follow the [Solana execution guide](solana.md).
+To run a larger program, stage its bytes through the Kitchen, finalize the code account, then execute.
+Keep the raw compilation result: the route path drops the manifest. The
+[Solana guide](solana.md) has the full flow.
 
 ## Keep compilation reproducible
 
-Record the compiler version, target, ISA revision, source/dependency bytes,
-contract ABIs, defines, ambient modules, optimization settings, and argument
-format with an artifact. Keep request arguments separate from the code cache;
-hash the final code-plus-arguments payload when committing to a particular
-execution.
+Store the compiler version, target, source and dependency bytes, ABIs, defines, ambient modules,
+optimization setting and argument format alongside any artifact you keep. Keep request arguments out
+of the code cache, and hash the final code-plus-arguments payload when you commit to one execution.
 
-The compiler's function cache is enabled by default. It is an optimization of
-lowering, not an application-level bytecode cache or a dependency resolver.
-`cache: false` forces fresh lowering. If an application mutates cached resolver
-inputs, refresh those inputs and use the compiler package's cache controls as
-needed.
+The compiler caches its own work between calls as an optimization; `cache: false` forces fresh
+lowering. That cache is not an application-level artifact store — if your resolver's inputs change,
+refresh them yourself.
 
-For canonical settle programs, use the shipped recipe source and the pinned
-verification surface described in [settlement verification](verification.md).
+For the canonical settle programs, use the shipped recipe source and the pinned verification surface
+in [settlement verification](verification.md).

package/docs/guides/intents.md

@@ -2,10 +2,15 @@
 
 [Documentation](../README.md) · [Routes API](../api/routes.md) · [Nested intents](nested-intents.md)
 
-`Base(body, options).reward(reward)` compiles a program for Base and packages it as an Eco intent. `Base.route(...)` has the same behavior. The destination chain selects the compiler target, token addresses, and protocol deployments.
+An Eco intent is an offer: _run this program on that chain, and the reward escrowed on this one is
+yours_. `Base(body, options).reward(reward)` builds one. The chain you call names the **destination**
+— where the program runs, and therefore which compiler target, token addresses and protocol
+deployments apply. `.reward(...)` names the **source**, where the reward sits until someone earns it.
+
+`Base.route(...)` is the same function. Every chain is a named export; import the ones you use.
 
 ```ts
-import "@eco-incorp/sauce";
+import { Base } from "@eco-incorp/sauce";
 import type { routes } from "@eco-incorp/sauce";
 
 export function buildApprovalIntent(routeOptions: routes.IntentOptions, reward: routes.RewardArg) {
@@ -15,7 +20,10 @@ export function buildApprovalIntent(routeOptions: routes.IntentOptions, reward:
 }
 ```
 
-The SDK constructs the intent and transaction requests. Your application supplies deployments, funds the source reward, submits transactions, and arranges fulfillment by a solver.
+The SDK builds the intent and the transaction requests, and sends nothing. It looks up the Portals,
+derives the destination Pot and engine, and resolves registered token and protocol addresses. You
+choose the deadlines, creator and prover, read the Kitchen fee, fund the reward and submit. A solver
+then decides whether to fulfill it; the SDK does not price the reward or promise a fill.
 
 ## Source, destination, and funding
 
@@ -25,7 +33,7 @@ An intent has two sides:
 | ---------------------------------------- | ----------------------------------------------------------------- |
 | `Base(...)`                              | Destination chain where the Sauce program executes                |
 | `options.portal`                         | Destination Portal recorded in the route                          |
-| `options.pot`, `options.engine`          | Destination Pot and interpreter used by `cook`                    |
+| `options.pot`, `options.engine`          | Overrides for the derived destination Pot and released engine     |
 | `options.tokens`, `options.nativeAmount` | Destination assets delivered by the solver to the Portal Executor |
 | `reward.source`                          | Chain where the reward is funded                                  |
 | `options.sourcePortal`                   | Source Portal used by submission and read helpers                 |
@@ -36,28 +44,65 @@ Destination route assets initially arrive in the **Executor**. The Sauce program
 
 Every EVM `cook` must receive the Kitchen's current `executionFee()` in native wei, including ERC-20-only programs. Set `execution.value` to **fee + native assets the program needs**, and budget `nativeAmount` for the route's calls. The Pot remits the fee before executing; its existing balance cannot replace this payment. Nested transfer programs add another cook and fee. Read the fee before building; an increase before fulfillment can make the route revert.
 
-Deadlines are absolute Unix timestamps in seconds. `route.deadline` limits destination fulfillment. `reward.deadline` allows source refunds when no valid proof exists; leave time for fulfillment and proof delivery before it.
-
-## Prepare the destination Pot
+On Arc the native coin is USDC, so every one of these native amounts is USDC at **18 decimals**,
+while `tokens` amounts of Arc's `USDC` are 6 decimals — and both draw on one balance. See
+[Arc: USDC is the native coin](../api/coverage.md#arc-usdc-is-the-native-coin).
 
-For direct Portal routes, the Pot's owner must be the destination **`Portal.executor()`**. A user-owned or solver-owned Pot rejects the Executor's call with `NotOwner()`.
-
-Use [evm-execution.ts](../examples/evm-execution.ts) on the destination chain to read the Executor, resolve the current Kitchen and engine, predict the Pot, and quote the execution fee. If the Pot is absent, the helper returns a deployment request. Send it, wait for a successful receipt, and run the helper again. Only use a result with `ready: true`, which confirms code is present and checks the Pot's `owner()` and `kitchen()`.
-
-Deployment helpers return release addresses; the historical chain roster does not attest current release liveness.
+Deadlines are absolute Unix timestamps in seconds. `route.deadline` limits destination fulfillment. `reward.deadline` allows source refunds when no valid proof exists; leave time for fulfillment and proof delivery before it.
 
-An Executor-owned Pot can be invoked by other valid Portal routes. Deliver assets, use them, and return leftovers **within the same fulfillment**; do not leave user funds or standing allowances in it. Source reward escrow belongs in the intent vault. These caller and custody rules follow [Eco Routes' Executor calls](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Executor.sol#L50-L74) and [destination fulfillment](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Inbox.sol#L225-L271).
+## The destination Pot
+
+A route call runs as the Executor of the Portal that fulfils it, and a Pot's `cook` accepts only
+its owner. So the Pot's owner must be the **`executor()` of the Portal the route records** —
+`options.portal` when you set it, the registry's otherwise. A user-owned or solver-owned Pot rejects
+the call with `NotOwner()`.
+
+You do not have to supply one. With no `execution.pot` and no `execution.engine`, the builder uses the
+same Pot the [native syntax](#the-destination-pot-is-derived) derives — CREATE2 from the released
+Kitchen over that Executor and salt zero (`SAUCE_INTENT_POT_SALT`) — and the released engine. That is
+the one Pot the solver deploys per Portal and every intent through that Portal shares. Both remain
+overrides. `destinationPot(Base.chain, { portal })` returns that address, for a `precalls`
+transfer into it.
+
+**The destination Pot must exist before the intent is fulfilled.** The SDK derives its address and
+deploys nothing: the route contains no deployment call. The solver deploys the shared Pot for each
+Portal. A fulfilment that cooks on a Pot that is not there reverts entirely, because the Executor
+refuses a call with calldata to an address without code (`CallToEOA`).
+
+To deploy it yourself first, send this on the destination chain:
+`routes.sauceEvmDeployPotCall({ kitchen: v12GateKitchen(), owner: executor, salt: SAUCE_INTENT_POT_SALT })`.
+The call is permissionless, and it returns the existing Pot when one is already there. A **Pot you
+name** instead must also exist, and be owned by that Executor, or the cook reverts with `NotOwner()`.
+Use
+[evm-execution.ts](../examples/evm-execution.ts) with the destination Portal and a salt — zero for
+the shared Pot — to predict the Pot and check that it is deployed, with the right `owner()` and
+`kitchen()`. Only use a result with `ready: true`.
+
+### Arc's Pot
+
+Arc's eco-routes Portal (`0xEC002CA16cE20c2a9F3C6200EF04E7d92a3dfBD8`) is not the Portal most other
+chains share, so its Executor (`0x95b2d45F49c68a54BDBa0356fc3034751A43b3D4`) and the Pot derived from
+it (`destinationPot("arc")`, `0x4edfB4576F91A9c2fE9aA50f669B7C81E4B82955`) are Arc's own. This prediction
+uses Kitchen **1.1.0** initcode. Upgrade the Kitchen and deploy the matching engine and Pot before
+sending intents; the release address alone does not confirm readiness.
+
+The deployment helpers return the released addresses. They do not check that code is live at those
+addresses on your chain. The same helper confirms the Kitchen and engine have code, and reads the
+execution fee you need either way.
+
+An Executor-owned Pot can be invoked by other valid Portal routes, and the derived one is shared by
+every intent through its Portal. Deliver assets, use them, and return leftovers **within the same
+fulfillment**; leave nothing in it — no user funds, no standing allowances. Source reward escrow
+belongs in the intent vault. These caller and custody rules follow [Eco Routes' Executor calls](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Executor.sol#L50-L74) and [destination fulfillment](https://github.com/eco/eco-routes/blob/49de5bb10a5eb00509b21702df6cf54de448ee11/contracts/Inbox.sol#L225-L271).
 
 ## Build a Base USDC transfer intent
 
 This function takes deployment and reward configuration as inputs. It delivers one USDC on Base to `recipient` and offers the configured source-token reward. It only constructs data.
 
 ```ts
-import { token, type routes } from "@eco-incorp/sauce";
+import { Base, destinationPot, token, type routes } from "@eco-incorp/sauce";
 
 interface TransferIntentConfig {
-  pot: routes.AddressInput;
-  engine: routes.AddressInput;
   executionFee: bigint;
   destinationPortal: routes.AddressInput;
   baseUsdc: routes.AddressInput;
@@ -74,14 +119,12 @@ interface TransferIntentConfig {
 
 export function buildBaseTransfer(config: TransferIntentConfig) {
   const amount = 1_000_000n;
-  const delivery = token.Token.transfer({
-    token: config.baseUsdc,
-    to: config.pot,
-    amount,
-  }).toCall();
+  // The Pot the route cooks on: the shared one for the Portal it records. It must already exist.
+  const pot = destinationPot(Base.chain, { portal: config.destinationPortal });
+  const delivery = token.Token.transfer({ token: config.baseUsdc, to: pot, amount }).toCall();
 
   return Base("USDC.transfer(RECIPIENT, AMOUNT);", {
-    execution: { pot: config.pot, engine: config.engine, value: config.executionFee },
+    execution: { value: config.executionFee },
     nativeAmount: config.executionFee,
     portal: config.destinationPortal,
     sourcePortal: config.sourcePortal,
@@ -100,12 +143,187 @@ export function buildBaseTransfer(config: TransferIntentConfig) {
 }
 ```
 
-Use an EVM source when using the Portal submission helpers below; they generate EVM calldata and reject an SVM source. The route model can represent SVM destinations, but the current SVM route emitter is incompatible with the released gated engine.
+The submission helpers below generate EVM calldata and reject an SVM source, so an intent you submit with them is EVM-sourced. Its **destination** may be Solana — the encoding supports it — but see the [Solana guide](solana.md) for how that execution is actually built.
 
+The route has two calls: the delivery into the Pot, and the cook.
 `executionFee` is the destination Kitchen quote obtained above. The source reward must separately compensate the solver for delivery, fees, and gas; the SDK does not price it.
 
 The explicit `tokenDefines` ensures that the token transferred into the Pot matches the token used by the program. To use the SDK's default Base USDC, resolve it with `routes.registryTokenAddress(Base.chain, "USDC")` and check the result before building. That lookup returns a `bigint`; convert it to a 20-byte hex address with Viem's `toHex(value, { size: 20 })` for intent token fields, as in the [complete example](../examples/first-intent.ts).
 
+## Create an intent from inside a program
+
+Everything above builds an intent in TypeScript, before anything runs. A program can also create one
+_while_ it is running, which is what you want when the amount is the output of the step before it:
+
+```js
+function main() {
+  const amount = USDC.balanceOf(ctx.self());
+  Arbitrum(() => {
+    USDC.transfer(RECIPIENT, amount);
+  }).reward({ tokens: [{ token: USDC, amount }] });
+}
+```
+
+Same shape as the TypeScript builder, written in the program. No Portal, prover, selector, encoding
+or approval appears, because none of them is a decision you are making. The closest TypeScript form
+is a [dynamic nest](nested-intents.md#create-the-child-on-chain-from-a-measured-amount), where you
+build a placeholder child, name the measurement and count each placeholder's occurrences yourself.
+
+### The braces are a Sauce program
+
+Anything a route body can do belongs in there: protocol calls, control flow, locals, and an intent
+of its own. There are two lowerings and the SDK picks between them, which matters to you because
+they cost different things.
+
+| The body is…                    | Becomes…                                               | Needs                   |
+| ------------------------------- | ------------------------------------------------------ | ----------------------- |
+| only token `transfer`/`approve` | one `route.calls` entry per statement                  | nothing further         |
+| anything else                   | a program compiled for the destination, run on its Pot | a Pot and a Kitchen fee |
+
+The first shape is free: a route already _is_ a list of calls, so a cook would only add a fee. The
+second is strictly more general.
+
+```js
+function main() {
+  const amount = USDC.balanceOf(ctx.self());
+  Arbitrum(
+    () => {
+      const here = USDC.balanceOf(ctx.self());
+      if (here > 0n) {
+        USDC.transfer(RECIPIENT, here);
+      }
+    },
+    { tokens: [{ token: USDC, amount }] },
+  ).reward({ tokens: [{ token: USDC, amount }] });
+}
+```
+
+**The second argument names what the solver delivers** so the body has something to work with, and
+the lowering adds the Executor-to-Pot transfer. For the token-only shape it is derived instead — a
+`transfer` of N moves N, so N is what has to arrive. It is _not_ derived for a program, and that is
+a judgement rather than an omission: a program's `balanceOf` reads what is _there_, which may be what
+an earlier call in the same route produced rather than what a solver must bring. Inferring an
+obligation from it would silently under- or over-state what the intent asks for, and an intent that
+asks for the wrong delivery is unfulfillable or overfunded.
+
+### Captured variables
+
+`amount` is a local of the enclosing program, so its value does not exist when the intent is
+encoded. It is encoded with a sentinel in its place and the program splices the real value in as it
+runs. Any scalar works — an amount, an address, anything one 256-bit word wide.
+
+A variable can arrive two ways, and the same variable can do both:
+
+- **Into the encoded intent** — a route call's argument, a reward amount, a delivery amount. One
+  slot per variable, however many of those it fills, so they are the same number by construction
+  rather than by several encodings agreeing.
+- **Into the child program** — it becomes one of that program's entry arguments, encoded at a
+  declared width so its offset does not move, and spliced into the cook's calldata.
+
+Used both ways, a variable gets a slot in each: they are different offsets carrying the same value.
+
+### Nesting
+
+An intent inside an intent is lowered recursively — the child is compiled by re-entering the same
+pipeline, so it gets its own chain's names and this same lowering, at any depth. That is how a chain
+of hops whose amounts are each measured on arrival is written; see
+[nested intents](nested-intents.md#a-cascade-in-native-syntax).
+
+### Names resolve per chain
+
+`USDC` inside the braces is _Arbitrum's_ USDC, because those calls run on Arbitrum. Resolving it
+against the enclosing chain would put one chain's address in another chain's route.
+
+### A throw reverts everything
+
+A `throw` or a failed `require` in a program, and every guard the SDK emits, reverts the whole
+fulfillment — no earlier route call survives it. A program that refuses to create an intent
+therefore leaves nothing behind, and a measurement below its floor cannot strand funds in the Pot.
+
+### Where each value comes from
+
+| Value              | Comes from                                                        |
+| ------------------ | ----------------------------------------------------------------- |
+| Portal, both sides | The eco-routes deployment tables, by chain                        |
+| Prover             | The tables, by source/destination pair                            |
+| Destination Pot    | Derived — see below                                               |
+| Engine             | The released engine address                                       |
+| Destination        | The chain you named                                               |
+| Source             | The chain the program runs on                                     |
+| Deadline           | **You.** Too early is unfulfillable, too late locks the reward up |
+| Creator            | **You.** See below                                                |
+| Execution fee      | **You**, for a program body. See below                            |
+
+The **creator** is the address that may reclaim the reward if nobody earns it. The executing Pot is
+the obvious default and the wrong one: it is owned by the Portal's Executor, which every solver can
+drive, so a refund landing there is a refund anyone can take. Set `IntentOptions.creator` and every
+intent the program creates inherits it, along with the deadline and the eco-routes deployment; a
+direct `compileSauceRoute` caller sets `compile.intents.creator`.
+
+The **execution fee** is the one value that cannot be derived. It is mutable on-chain, and it lives
+on the destination, which the source chain cannot read while it executes. Read it at build time and
+pass it as `compile.intents.executionFee`:
+
+```ts
+import { destinationExecutionFee } from "@eco-incorp/sauce";
+
+const request = destinationExecutionFee();
+// const { data } = await client.call(request);
+// const executionFee = request.decode(data!);
+```
+
+Read it shortly before building: an increase before fulfillment makes the cook revert, which reverts
+the fulfillment.
+
+### The destination Pot is derived
+
+A Pot is CREATE2 from the Kitchen over its owner and a salt, and the owner a route call must cook as
+is the `executor()` of the Portal the child's route records — itself that Portal's second `CREATE`,
+so it follows from the Portal address. That is the registry's Portal, or `destinationPortal` when you
+override it: a route recording one Portal is run by that Portal's Executor, and a Pot owned by any
+other Executor would refuse the cook with `NotOwner()`. Nothing is read from a chain and nothing is
+asked of you. The salt is zero (`SAUCE_INTENT_POT_SALT`), so there is **one shared Pot per Executor**
+rather than one per intent: the Pot the solver deploys for that Portal. A Pot is fixed by its owner
+and salt, so whoever calls `deployPot(executor, 0)` creates that same Pot, owned by the Executor.
+
+Deriving an address is not deploying a contract, and the lowering deploys nothing. **The Pot must
+exist before the child intent is fulfilled** — the solver deploys it — or the fulfilment reverts
+when the Executor calls an address without code. A token-only body cooks nothing, so it needs no Pot.
+
+A Pot you name with `pot` must equally exist already and be owned by that Executor.
+
+Because it is shared, **leave nothing in it**. Deliver assets, use them, and move the remainder out
+within the same fulfillment. Anything resting there, or any allowance left standing, belongs to
+whoever drives the Executor next.
+
+### Overrides
+
+Everything derived can be overridden through `compile.intents`, and `Base(...)` passes its own
+fields down so the common case sets none of them:
+
+| Field                        | Overrides                                                            |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `deadline`, `rewardDeadline` | The route and reward deadlines                                       |
+| `creator`, `prover`          | The reward's creator and prover                                      |
+| `sourcePortal`               | Where the intent is published                                        |
+| `destinationPortal`          | The Portal recorded in the child's route                             |
+| `pot`, `engine`              | Where a program body cooks, and on what; a named Pot is not deployed |
+| `executionFee`               | The cook's value                                                     |
+| `salt`, `allowPartial`       | The route salt, and partial funding                                  |
+| `generation`, `environment`  | Which eco-routes deployment to address                               |
+
+### What is refused
+
+Each of these is a compile error naming the construct, never a silently different intent:
+
+- An identifier that is neither a compile-time value nor a variable of the enclosing program.
+- A `.reward(...)` that is not an object, or a token entry missing `token` or `amount`.
+- A missing `deadline`, a missing `creator`, or a missing `executionFee` for a program body.
+- A chain with no eco-routes deployment, or a pair with no prover deployed on both sides.
+
+Inside a program body an unknown name is the _compiler's_ error rather than this lowering's, and
+reads the same way: it names the variable that is not declared.
+
 ## Callbacks are compiled source
 
 A callback is read with `Function.prototype.toString()`, parsed, and compiled as SauceScript. It is never invoked as a JavaScript callback and captures no outer variables. An `amount` in surrounding JavaScript does not become a value inside the program.
@@ -155,4 +373,4 @@ export async function readVault(
 
 Execute this read on the source chain. `hashCall()` cross-checks hashes against the Portal; `fundedCall()` checks funding. `predictVault({ portal, vaultInitCodeHash })` provides an offline CREATE2 prediction when you have verified the deployed vault configuration.
 
-The current SVM route emitter produces an older direct-engine instruction and cannot target the released gated engine. Code staging alone does not make those routes executable. See the [Solana guide](solana.md) for supported Kitchen execution and route-helper limitations.
+For a Solana destination, build the execution with the Kitchen client rather than the SVM route helpers: the instruction those helpers emit is not one the Solana engine accepts, and staging the code does not change that. The [Solana guide](solana.md) has the supported path.