@eco-incorp/sauce 0.99.3 → 0.99.5

package/docs/guides/nested-intents.md

@@ -7,7 +7,7 @@
 Use the thunk form to receive the parent's destination as the child's source:
 
 ```ts
-import "@eco-incorp/sauce";
+import { Arbitrum, Base } from "@eco-incorp/sauce";
 import type { routes } from "@eco-incorp/sauce";
 
 export function buildCascade(
@@ -30,9 +30,9 @@ export function buildCascade(
 }
 ```
 
-The example isolates composition: replace the no-op bodies with your programs. Each options object supplies its destination execution, Portal, deadline, and body cook fee. `executionFee` is the Base Kitchen quote for the additional transfer cook; include it in `parentOptions.nativeAmount` alongside the parent body and any native reward forwarding. Configure `childOptions.sourcePortal` as the Portal on Base. Deliver or earn the child's reward assets in the parent fulfillment before the funding step; see [the Executor-to-Pot example](intents.md#build-a-base-usdc-transfer-intent).
+The example isolates composition: replace the no-op bodies with your programs. Each options object supplies its deadline and body cook fee, and optionally its Portal; each level's Pot and engine are derived, and each level's Pot must exist before that level is fulfilled. `executionFee` is the Base Kitchen quote for the additional transfer cook; include it in `parentOptions.nativeAmount` alongside the parent body and any native reward forwarding. Configure `childOptions.sourcePortal` as the Portal on Base. Deliver or earn the child's reward assets in the parent fulfillment before the funding step; see [the Executor-to-Pot example](intents.md#build-a-base-usdc-transfer-intent).
 
-You can also pass an already built child. The SDK checks that its source matches the parent's destination. Both forms produce static children: reward amounts and other hashed fields are fixed before execution. A runtime balance can determine how much is transferred to a child's vault; it does not rewrite the child's reward or hash.
+You can also pass an already built child. The SDK checks that its source matches the parent's destination. Under the two default modes both forms produce static children: reward amounts and other hashed fields are fixed before execution. A runtime balance can determine how much is transferred to a child's vault; it does not rewrite the child's reward or hash. [`via: "dynamic"`](#create-the-child-on-chain-from-a-measured-amount) is the exception, and it changes the child's hash.
 
 ## Default: transfer to the child vault
 
@@ -61,7 +61,167 @@ Use `{ via: "publishAndFund" }` to insert ERC-20 approvals followed by a Portal
 
 The builder checks that declared parent route assets cover child rewards for this mode. Set `fundedByBody: true` only when the parent program actually earns or supplies those assets and makes them available to the Executor. That option skips a static coverage check; it does not move assets.
 
-`allowPartial` and `fundedByBody` belong to publication mode. `vault`, `vaultConfig`, `clamp`, `requireCap`, `native`, `fundNativeFromRoute`, `executionFee`, `pot`, `engine`, and `compile` belong to transfer mode. Mixing mode-specific options throws.
+`fundedByBody` belongs to publication mode, and `allowPartial` to publication and dynamic modes. `vault`, `vaultConfig`, `clamp`, `requireCap`, `native`, and `fundNativeFromRoute` belong to transfer mode; `executionFee`, `pot`, `engine`, and `compile` to transfer and dynamic modes. `measure`, `scale`, `minAmountIn`, `placeholders`, `approve`, and `value` belong to dynamic mode. Mixing mode-specific options throws, naming the modes the option is valid under.
+
+## Create the child on-chain from a measured amount
+
+The two modes above require every child reward amount before the parent is signed. When the amount is the output of a swap the parent itself performs, it does not exist yet. `{ via: "dynamic" }` builds that child anyway.
+
+Write a placeholder wherever a runtime amount belongs, then name the measurement:
+
+```ts
+import { Arbitrum, Base, routes } from "@eco-incorp/sauce";
+
+const { AMOUNT_IN_PLACEHOLDER, AMOUNT_OUT_PLACEHOLDER } = routes;
+
+const child = Arbitrum("return 1n;", {
+  ...childOptions,
+  tokens: [{ token: USDC_ARBITRUM, amount: AMOUNT_OUT_PLACEHOLDER }],
+}).reward({ ...childReward, tokens: [{ token: USDC_BASE, amount: AMOUNT_IN_PLACEHOLDER }] });
+
+const parent = Base(swapProgram, parentOptions)
+  .nest(child, {
+    via: "dynamic",
+    measure: { kind: "erc20Balance", token: USDC_BASE },
+    scale: 990000000000000000n,
+    placeholders: [
+      { value: AMOUNT_IN_PLACEHOLDER, source: "amountIn", occurrences: 1 },
+      { value: AMOUNT_OUT_PLACEHOLDER, source: "amountOut", occurrences: 1 },
+    ],
+  })
+  .reward(parentReward);
+```
+
+The child's `publishAndFund` calldata is encoded once off-chain, cut at every placeholder, and emitted as literal byte runs inside an additional cook. At execution that cook reads the Pot's balance, derives `amountOut = ceil(amountIn * scale / WAD)` with `WAD = 1e18`, approves the Portal, concatenates the calldata around the two numbers, and calls the Portal. No additional contract is involved.
+
+| Option         | Default                     | Effect                                                                                   |
+| -------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `measure`      | required                    | `erc20Balance`, `nativeBalance`, or a caller-supplied SauceScript expression             |
+| `scale`        | `10n ** 18n`                | `amountOut = ceil(amountIn * scale / WAD)`; carries decimals conversion and margin       |
+| `minAmountIn`  | `1n`                        | Revert the parent fulfillment below this floor; `0n` removes the check                   |
+| `placeholders` | both 32-byte sentinels      | Which sentinels to cut at, with per-slot `scale`, `width`, `littleEndian`, `occurrences` |
+| `approve`      | `"auto"`                    | Emit the Pot's reward-token approvals; `"none"` leaves them to you                       |
+| `value`        | `child.reward.nativeAmount` | Native forwarded to `publishAndFund`                                                     |
+| `allowPartial` | `false`                     | Passed through to `publishAndFund`                                                       |
+| `executionFee` | `0n`                        | The cook's total value: Kitchen fee plus any native the child forwards                   |
+
+Every guard in the generated program — the floor, the scale-overflow check, and the per-field width check — reverts the parent's whole fulfilment when it trips. No earlier route call survives it, so a rejected measurement cannot leave a parent completed with its child unpublished and the measured funds sitting in the Pot.
+
+Declare `occurrences` for every placeholder. Without it any count above zero is accepted, and a sentinel that matched one word too few leaves a placeholder amount in a published intent.
+
+The measurement is the Pot's current balance, not a delta against a baseline, so a donated balance rides along — the same property transfer mode has. A child whose destination is Solana needs `AMOUNT_IN_PLACEHOLDER_U64`/`AMOUNT_OUT_PLACEHOLDER_U64` with `width: 8, littleEndian: true` for its Borsh route amounts; its reward stays on the EVM source chain and keeps the 32-byte sentinels.
+
+The child's hash is not known until the parent executes, so `child.hash()`, `child.vaultCall()`, and the approval helpers describe the placeholder intent, not the published one. Recover the real hash from the Portal's `IntentPublished` event. Off-chain, `routes.renderDynamicChild(child.intent, dynamicOptions, amountIn)` returns the exact `publishAndFund` calldata a given measurement produces, where `dynamicOptions` is the `portal`/`measure`/`scale`/`placeholders` set passed to `.nest()`; rebuild the child with those amounts and hash it with `routes.hashIntent`. Funding coverage is not checked for this mode: the funding is the measurement, bounded by the Pot's balance.
+
+A child built this way is an ordinary built intent, so it can nest dynamically in turn; see [Chain more than one hop](#chain-more-than-one-hop).
+
+## A cascade in native syntax
+
+The shortest way to chain hops is to write them inside the program, one intent opening the next:
+
+```js
+// 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 }] });
+}
+```
+
+Three hops, and **no amount below the first exists when this is signed**. `amount` is measured on the
+first chain. `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. Each level's numbers are filled in by
+the level above it, at that level's own execution time.
+
+Nesting is recursive rather than special-cased: the middle body is compiled by re-entering the same
+pipeline, so the same lowering runs inside it at any depth. [Create an intent from inside a
+program](intents.md#create-an-intent-from-inside-a-program) covers what may be captured, the two
+lowerings, and the values you supply.
+
+Use this when the hops are a chain and the amounts are discovered as you go. Use the `.nest(...)`
+builder below when you are assembling intents in TypeScript from data you already hold, when you
+want several children on one parent, or when you need the transfer and publication modes it offers.
+
+## Chain more than one hop
+
+A dynamic child is an ordinary built intent, so it can carry a dynamic nest of its own. That is how a chain of swaps whose every hop's output is only known at that hop works: the parent swaps A for B and publishes the child, the child swaps B for C and publishes the grandchild, and the grandchild delivers C. Nothing below the first amount exists when the parent is signed.
+
+```ts
+import { Arbitrum, Base, Optimism, routes } from "@eco-incorp/sauce";
+
+const { AMOUNT_IN_PLACEHOLDER, AMOUNT_OUT_PLACEHOLDER } = routes;
+
+const placeholders = [
+  { value: AMOUNT_IN_PLACEHOLDER, source: "amountIn", occurrences: 1 },
+  { value: AMOUNT_OUT_PLACEHOLDER, source: "amountOut", occurrences: 1 },
+] as const;
+
+const grandchild = Optimism("return 1n;", {
+  ...grandchildOptions,
+  tokens: [{ token: USDC_OPTIMISM, amount: AMOUNT_OUT_PLACEHOLDER }],
+}).reward({
+  ...grandchildReward,
+  tokens: [{ token: USDC_ARBITRUM, amount: AMOUNT_IN_PLACEHOLDER }],
+});
+
+const child = Arbitrum(swapBforC, {
+  ...childOptions,
+  tokens: [{ token: USDC_ARBITRUM, amount: AMOUNT_OUT_PLACEHOLDER }],
+})
+  .nest(grandchild, {
+    via: "dynamic",
+    measure: { kind: "erc20Balance", token: USDC_ARBITRUM },
+    placeholders: [...placeholders],
+  })
+  .reward({ ...childReward, tokens: [{ token: USDC_BASE, amount: AMOUNT_IN_PLACEHOLDER }] });
+
+const parent = Base(swapAforB, parentOptions)
+  .nest(child, {
+    via: "dynamic",
+    measure: { kind: "erc20Balance", token: USDC_BASE },
+    placeholders: [...placeholders],
+  })
+  .reward(parentReward);
+```
+
+The middle level is not a special form. It is the same construct applied twice, so depth 3 and beyond follow from depth 2 without new options.
+
+### Why levels do not collide
+
+Each level's route embeds the next level's compiled program as literal calldata, and the level above splices amounts into that. The obvious hazard is that a parent's placeholder search also matches the sentinels belonging to levels below it, overwriting a placeholder the grandchild still needs.
+
+It cannot, and this is an invariant of the mechanism rather than a property of any particular cascade. Splitting a payload **cuts the sentinels out**: a compiled dynamic program holds the literal segments that sat _around_ each placeholder and never the placeholder bytes themselves. So when a parent splits its child's encoding it finds the child's own slots and nothing else, and adding a nest to a level does not change that level's own `occurrences` counts — the extra cook call contributes bytes, not sentinels.
+
+Each level's numbers are therefore spliced by the level directly above it, at that level's own execution time. No level needs to know the amounts below it, and none can disturb them.
+
+### Cost and depth
+
+Growth is linear, not multiplicative: each level's bytes appear exactly once in the chain, so the outermost payload is the sum of the per-level overheads. On the SDK's own fixture that is about 1,500 bytes of `cook` calldata at depth 1 and about 1,950 bytes for each level after it. A measured depth-2 cascade cost roughly 286,000 gas to fulfill the parent and 267,000 to fulfill the child; every one of these numbers moves with the size of the intents you nest, so treat them as an order of magnitude rather than a budget.
+
+The hard ceiling is the compiler's, and it is named rather than silent. A `hex` segment carries a `u16` length, so no single segment may exceed 65,535 bytes; on that fixture the deepest cascade that compiles is 34 levels, and one level further fails with `an array literal has … elements, beyond the 65535 the engine can encode`. Nothing truncates. In practice gas binds long before that, and a cascade deep enough to approach the limit is one to reconsider rather than to budget for.
+
+Depth 2 is executed end to end against a real engine, Pot and Portal in the SDK's own suite. Deeper cascades are established by compilation and encoding only — none has been run on a chain.
+
+### What changes beyond the first hop
+
+Hash recovery becomes sequential. At depth 1 the child's real hash is unknown until the parent executes; at depth 2 the grandchild's is unknown until the _child_ executes, which is a separate fulfillment by a different solver at a later time. An indexer must follow `IntentPublished` level by level, and no amount of off-chain computation shortens that — the input to each level is a measurement that has not happened yet.
+
+Everything else compounds rather than changes. Deadlines must still increase with depth, checked per level, and every level cooks on an Executor-owned Pot — the derived shared one unless you name one, deployed beforehand either way — and pays the current Kitchen fee on its own chain. The `Create the child on-chain from a measured amount` section's properties — the current-balance measurement, the guard behavior, the Solana sentinel widths — apply unchanged at every level.
 
 ## Ordering and constraints
 
@@ -72,7 +232,7 @@ The current call order is:
 3. The parent's compiled program.
 4. Children positioned `"after"`.
 
-Within either position group, publication-mode calls precede the merged transfer program. Transfer children execute in their `.nest()` order inside that program. Do not depend on an interleaving of different funding modes. Transfer children merged into one position must use the same Pot, engine, and execution fee.
+Within either position group, publication-mode calls precede the merged transfer program, which precedes the merged dynamic program. Children of one mode execute in their `.nest()` order inside that mode's program. Do not depend on an interleaving of different funding modes; when one must run before another, put it in the other position group. Transfer children merged into one position must use the same Pot, engine, and execution fee, and so must dynamic children.
 
 The builder enforces an EVM parent destination, matching parent-destination/child-source chains, and child route and reward deadlines at least as late as the parent route deadline. The codec accepts SVM children, but the [built-in SVM Sauce route is incompatible with the released engine](solana.md#svm-destinations-in-eco-intents). Duplicate direct-child intent hashes are rejected; use distinct salts for otherwise identical children. The default salt is zero, so separate construction alone does not create a distinct intent.
 

package/docs/guides/protocols-and-tokens.md

@@ -2,7 +2,8 @@
 
 [Documentation](../README.md) · [Quick start](quick-start.md) · [Coverage](../api/coverage.md)
 
-Within an EVM route, token symbols and protocol names resolve against the destination chain:
+Inside an EVM route body, token symbols and protocol contracts are names the compiler resolves
+against the destination chain — so a program reads like the operation it performs:
 
 ```js
 USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
@@ -42,7 +43,9 @@ const baseTokens = routes.knownTokenSymbols(routes.chain("base").chain);
 console.log(protocol, descriptors.length, router.available, baseTokens);
 ```
 
-Contract accessors expose `address`, `available`, `chains`, `abi`, `methods`, and `coverage`. A namespace's presence does not establish deployment on every chain. A call to a registered contract with no deployment on the selected chain fails during construction or compilation.
+Contract accessors expose `address`, `available`, `chains`, `abi`, `methods` and `coverage`. A name
+existing does not mean the contract is deployed on your chain — calling one that is not fails when
+you build or compile, which is the point at which you can still do something about it.
 
 Versioned names are explicit: `UniswapV2.Factory` and `UniswapV3.Factory` select different descriptors. A family alias only resolves a contract name when it identifies one descriptor; `Uniswap.Factory` is ambiguous and fails. A protocol with a single default contract also permits the shorter `Protocol.method(...)` form.
 
@@ -86,11 +89,16 @@ Custom symbol names work in source strings. The package's generated TypeScript d
 
 ## Route source and host JavaScript
 
-Importing the package installs real chain globals such as `Base` and `Solana`, plus the host `Token` builder. The package also supplies TypeScript declarations for bare route names such as `USDC` and `Uniswap`. Those bare names are **route syntax**: there is no host JavaScript `USDC` or `Uniswap` object to execute.
+Two different mechanisms share the look of a bare name, and the difference is what you import.
 
-Use a side-effect import, `import "@eco-incorp/sauce"`, when relying on installed globals. A type-only import does not install them, and TypeScript can erase a named import used only for types.
+Chain accessors such as `Base` and `Solana`, the `chain(ref)` front door, and the host `Token` builder are **named exports**: `import { Base, Solana, Token } from "@eco-incorp/sauce"`. They are ordinary JavaScript values, and importing the package installs nothing on `globalThis`.
 
-Outside a route, `Base.UniswapV4.UniversalRouter` or `contracts.on("base").UniswapV4.UniversalRouter` is a real host accessor. Its methods return inert `ContractCall` objects. A call can provide encoded `data`, `.toCall()` for `{ target, data, value }`, or `.toSauceScript()` for source and import paths. Host accessor methods currently have the static type `unknown`; use an explicit signature when invoking one in TypeScript:
+Bare route names such as `USDC` and `Uniswap` are **route syntax**, resolved by the compiler against the destination chain. The package supplies TypeScript declarations for them so a typed callback checks, but there is no host JavaScript `USDC` or `Uniswap` object to import or execute.
+
+A host that wants the chain names as runtime globals anyway can opt in with `installRouteGlobals()`, which defines them on `globalThis` (or any target you pass) and never overwrites a name already there. It installs values only; declare the names yourself.
+
+Outside a route, `Base.UniswapV4.UniversalRouter` or `contracts.on("base").UniswapV4.UniversalRouter` is a real host accessor. Its methods return inert `ContractCall` objects. A call can provide encoded `data`, `.toCall()` for `{ target, data, value }`, or `.toSauceScript()` for source and import paths. A host accessor's methods are typed `unknown`, because their signatures come from an ABI the type
+system has not seen. Narrow one before calling it:
 
 ```ts
 import { contracts } from "@eco-incorp/sauce";
@@ -103,13 +111,13 @@ const execute = router.execute as (
 ) => contracts.ContractCall;
 ```
 
-That declaration does not build or send a swap. Supply valid Universal Router commands before calling it. For ordinary ERC-20 operations from host code, the typed `token.Token.transfer({ ... })` and `.approve({ ... })` builders are usually more convenient; see [builders and actions](builders-and-actions.md).
+That declaration does not build or send a swap. Supply valid Universal Router commands before calling it. For ordinary ERC-20 operations from host code, the typed `token.Token.transfer({ ... })` and `.approve({ ... })` builders are usually more convenient; see [builders](builders-and-actions.md).
 
 ## Chain selection and ABI bindings
 
 A bare protocol reference uses the enclosing destination. A qualified reference such as `Ethereum.UniswapV4.UniversalRouter` selects an address from Ethereum's registry. It does **not** move execution to Ethereum: the resulting call still executes on the enclosing route's chain. Use separate intents and [nesting](nested-intents.md) for cross-chain execution. Set `compile.accessors.chainScope` to restrict explicitly qualified chain names when needed.
 
-Route rewriting rejects missing methods, ambiguous aliases, missing deployments, and descriptors marked with widened ABI types. A widened ABI can produce a selector different from the deployed contract. Inspect `coverage` and use the exact ABI for that deployment; opting past the check does not repair the ABI.
+Route rewriting rejects missing methods, ambiguous aliases and missing deployments. Every descriptor declares its contract's deployed ABI types, so the selectors it computes are the ones the deployed contract dispatches.
 
 To call a contract outside the descriptor registry, supply an ABI binding through `compile.contracts` or a resolved ABI import, then call `Binding.at(address).method(...)` in source. See [compiler integration](../api/compiler.md). Host `.at(address)` rebinding and SauceScript ABI `.at(address)` are separate APIs; the global protocol rewrite does not provide arbitrary `.at(...)` chains.
 

package/docs/guides/quick-start.md

@@ -1,30 +1,27 @@
 # Quick start
 
-[Documentation](../README.md) · [Protocols and tokens](protocols-and-tokens.md) · [Intents](intents.md)
-
-Use Node.js 24 or newer and install the single public package:
+[Documentation](../README.md) · [Protocols and tokens](protocols-and-tokens.md) · [Create an intent](intents.md)
 
 ```sh
 pnpm add @eco-incorp/sauce
 ```
 
-The Sauce compiler is a dependency of that package. You do not need a compiler checkout or a separate compiler install.
+Node.js **24 or newer**. The SauceScript compiler is a dependency of this package — there is nothing
+else to install and no compiler checkout to keep in sync.
 
-## Compile your first intent
+## Build your first intent
 
-This complete TypeScript example builds an approval intent offline. Addresses and the fee are fixtures; the zero reward demonstrates construction only. Before submission, [read the current Kitchen fee and prepare an Executor-owned Pot](intents.md#prepare-the-destination-pot).
+This is a complete program. It builds an Eco intent offline: the addresses and the fee are fixtures
+and nothing is sent to a chain.
 
 ```ts
-import "@eco-incorp/sauce";
+import { Base } from "@eco-incorp/sauce";
 import type { routes } from "@eco-incorp/sauce";
 
-const executionFee = 1_000n; // Fixture: read the destination Kitchen's executionFee() before use.
+const executionFee = 1_000n; // Read the destination Kitchen's executionFee() before a real run.
 const options: routes.IntentOptions = {
-  execution: {
-    pot: "0x1111111111111111111111111111111111111111",
-    engine: "0x2222222222222222222222222222222222222222",
-    value: executionFee,
-  },
+  // The Pot and engine are derived. The Pot must exist before fulfilment; the solver deploys it.
+  execution: { value: executionFee },
   nativeAmount: executionFee,
   portal: "0x3333333333333333333333333333333333333333",
   deadline: 2_000_000_000n,
@@ -43,22 +40,54 @@ const built = Base(() => {
 console.log(built.hash().intentHash);
 ```
 
-Importing the root package installs `Base` and the other chain globals. Inside the callback, the SDK resolves `USDC` and `Uniswap.UniversalRouter` for Base, compiles the body with Sauce, and encodes a Pot `cook(engine, program)` call. `.reward(...)` completes the Eco intent. Nothing is submitted to a chain.
+`Base` names the **destination**, the chain the program runs on; `.reward(...)` names the
+**source**, where the reward is escrowed. That one expression does what an intent otherwise takes
+by hand:
+
+- looks up USDC and the Universal Router on Base, and binds the ERC-20 ABI;
+- compiles the body, so there is no contract to write or deploy;
+- derives the Pot and engine, and encodes the `cook(engine, program)` call on that Pot — the shared
+  one the solver deploys for that Portal;
+- assembles the route and reward, which is all `built.hash()` and the source Portal requests need.
+
+What stays yours: the deadlines, the creator and prover, the Kitchen fee, and a reward that pays a
+solver to fill the intent. The SDK sends nothing, and it does not price the reward.
+
+## The three things that trip people up
 
-For execution, deploy the Pot with the destination `Portal.executor()` as owner and pay the current Kitchen fee on every cook. [Intent setup](intents.md#prepare-the-destination-pot) shows the reads and deployment call. Fund and empty that shared Pot within the fulfillment.
+**The callback is source, not a function.** It is read with `Function.prototype.toString()`, parsed
+and compiled. It never runs as JavaScript, so it captures nothing: a surrounding `const amount` is
+invisible inside it. Pass application values through `defines`, or write the body as a string. If
+your bundler rewrites function bodies, use a string or a source file.
 
-`USDC` and protocol names have generated TypeScript declarations but are source syntax, not JavaScript clients. The router is registered as `UniswapV4.UniversalRouter`, with `Uniswap.UniversalRouter` as a family alias. `UniswapV3.UniversalRouter` is not a registered name. See [coverage](../api/coverage.md) for which protocols expose these namespaces.
+**`USDC` and `Uniswap` are not imports.** They are program syntax the compiler resolves against the
+destination chain. The package ships TypeScript declarations so a typed body checks, but there is no
+JavaScript object to import. `Base`, by contrast, _is_ a named export. The registered spelling of the
+router is `UniswapV4.UniversalRouter`, with `Uniswap.UniversalRouter` as an unambiguous family alias;
+`UniswapV3.UniversalRouter` does not exist. [Coverage](../api/coverage.md) lists what is registered.
 
-The callback captures no outer variables. Pass dynamic scalars through `defines`, or use explicit source strings; see the complete [transfer example](../examples/first-intent.ts). Callbacks must remain recognizable synchronous source after your build tooling transforms them.
+**The Pot is not yours alone.** For a Portal-driven intent the Pot's owner is the destination
+`Portal.executor()`, which every solver can drive. The SDK derives that Pot, so the example names
+none; the solver deploys it before the intent is fulfilled. Deliver assets into it, use them, and
+take the remainder out inside the same fulfillment. Every cook also pays the Kitchen's current fee in native value.
+[The destination Pot](intents.md#the-destination-pot) covers deployment and overrides.
 
 ## Deliver assets and fund the reward
 
-In a transfer intent, the destination assets and source reward are separate. Destination `tokens` reach the Portal Executor. Add a transfer precall to deliver tokens into the Pot before Sauce spends them. Source reward tokens are approved to the source Portal and escrowed through its funding call.
+The destination assets and the source reward are separate things. Destination `tokens` arrive at the
+Portal's Executor, so a program that spends them needs a transfer precall moving them into the Pot
+first. Source reward tokens are approved to the source Portal, which escrows them in the intent vault.
 
-The [first-intent.ts example](../examples/first-intent.ts) constructs both sides and returns source transaction requests. Read [creating intents](intents.md) before submitting those requests, and [nested intents](nested-intents.md) to compose subsequent routes.
+[first-intent.ts](../examples/first-intent.ts) builds both sides and returns the source transaction
+requests. Read [create an intent](intents.md) before submitting them, and
+[nested intents](nested-intents.md) to chain a second execution onto the first.
 
-## Compile a standalone program
+## Compile without an intent
 
-Use `@eco-incorp/sauce/compiler` when you need raw bytecode, entry schemas, or an SVM account manifest. It exposes the published Rust/Wasm compiler through `compile(options)`; it does not install SDK protocol namespaces into arbitrary compiler input.
+Reach for `@eco-incorp/sauce/compiler` when you want raw bytecode, runtime entry arguments or a
+Solana account manifest — a reusable program you supply values to at execution time rather than one
+specialised at compile time.
 
-The [compiler example](../examples/compile-program.ts) compiles a typed SauceScript entry point and appends compact arguments. [Compiling](compiling.md) explains module resolution and the distinction between raw compiler output and the route wrapper.
+[compile-program.ts](../examples/compile-program.ts) compiles a typed entry point and appends compact
+arguments. [Compiling programs](compiling.md) explains module resolution and how the raw compiler
+differs from the route wrapper.

package/docs/guides/solana.md

@@ -2,9 +2,9 @@
 
 [Documentation](../README.md) · [Compiler](../api/compiler.md) · [Coverage](../api/coverage.md)
 
-Solana programs use the `svm` compiler target, explicit account parameters, and a Kitchen that invokes the engine. EVM token/protocol member rewrites such as `USDC.transfer(...)` do not apply to SVM routes.
+Solana execution differs from EVM in one structural way, and everything on this page follows from it: **a Solana program must declare every account it touches, up front.** Those declarations are `Account` parameters on `main`, and the compiler returns them as an account manifest you resolve to real addresses before sending anything.
 
-Use `@eco-incorp/sauce/compiler` to retain the compiler's account manifest. `routes.compileSauceRoute()` returns execution calls and a `compiled.bytecode` segment list, but does not expose that manifest; applications resolving account slots should use the direct compiler result.
+Two consequences. The EVM name rewrites (`USDC.transfer(...)`, protocol members) do not apply here — there is no address to fold in without an account slot to put it in. And you want `@eco-incorp/sauce/compiler` directly: `routes.compileSauceRoute()` returns calls and bytecode but drops the manifest, which is the part you need.
 
 ## Compile an SPL transfer
 
@@ -42,9 +42,9 @@ The account references are names, not addresses. `manifest.accounts` records the
 
 Use `v12SvmEngineProgramId()` and `v12SvmKitchenProgramId()` from
 `@eco-incorp/sauce/deployments` for the released program identities, and confirm
-they are deployed on your cluster. The older `v12SvmProgramId` constant identifies
-a legacy engine. The client derives a Pot owned by its `payer` signer; select it
-with `potSalt` when configuring the client.
+they are deployed on your cluster. `v12SvmProgramId` names an earlier engine
+generation, not these. The client derives a Pot owned by its `payer` signer;
+choose it with `potSalt` when you configure the client.
 
 ```ts
 import {
@@ -71,13 +71,12 @@ After successful simulation, `client.execute(bytecode, manifest, resolution, { c
 
 ### Select the released programs and quote the fee
 
-The pinned SVM engine **1.1.0** is `7MetdnWSaEsowvUmVyvwrbAeUW9xXFpVWXUXw4MxZ5CG`;
-Kitchen **1.0.0** is `SauceYLdWyabKFwtevSAgsSDoMjCoTKtx1HTb63eJot`.
-These are release addresses; confirm deployment on your cluster before use.
-Engine 1.1.0 adds direct paid calls. The SDK clients use Kitchen-mediated cooks;
-builders for the direct paid instructions are not yet exposed.
-Use the deployment helpers and read the Kitchen's fee configuration on the selected
-cluster. This example checks a caller-selected lamport budget before signing:
+Read the program ids from the deployment helpers rather than pasting them, and
+confirm each is deployed on the cluster you are targeting. The SDK's clients cook
+through the Kitchen; the engine's direct paid instructions have no builder here.
+
+Every cook pays the Kitchen's fee in lamports, and the fee is read from chain, not
+assumed. This example quotes it and refuses to sign past a budget the caller set:
 
 ```ts
 import { createHash } from "node:crypto";
@@ -144,38 +143,38 @@ Staging belongs to the Kitchen. There is no `client.stageBuffer()` convenience m
 
 The low-level instruction builders return instructions; the application groups, signs, submits, and confirms them. The two Kitchen cook paths require `buildHeapFramePrepend()` when assembling transactions yourself. A staged client's first argument is the **code-buffer metadata address**; it derives the associated code account.
 
-`buildCookFromAccountInstruction` supports a `pin` that the Kitchen checks at execution. The client's `expectedSha256` option is currently rejected; it is not a supported substitute for that low-level `pin`. A finalized buffer's digest and an execution-time caller-selected digest are different guarantees.
+`buildCookFromAccountInstruction` takes a `pin` the Kitchen checks at execution time. The client's `expectedSha256` option is rejected — it is not a substitute for that pin. The digest checked when a buffer is finalized and a digest chosen by a caller at execution are different guarantees about different moments; read both before relying on either.
 
 ## SVM destinations in Eco intents
 
-**The SDK's SVM route helpers are incompatible with the released gated engine.**
-For an SVM destination, `Solana(body, { execution, ... }).reward(...)`,
-`routes.compileSauceRoute()`, `buildSauceSvmCall()`, and `buildSauceSvmCalls()` emit
-a legacy `execute_from_account` instruction containing only its 8-byte
-discriminator. Engine 1.1.0 still requires another 65 bytes of Pot derivation material
-and a trailing Pot signer supplied by the Kitchen.
-
-The [SVM Portal fulfillment implementation](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
-forwards the route's instruction bytes to its target unchanged. It signs for its
-Executor PDA; it does not construct a Kitchen call or sign for a Sauce Pot.
-Changing only the helper's engine program ID therefore does not make these routes
-executable. Do not distribute them as executable intents against the pinned release.
-
-A Kitchen-targeted Portal integration needs separately constructed cook data and
-accounts, including the owner signature, Pot, fee configuration and payer, engine,
-and staged metadata/code where applicable. The SDK does not currently build or
-validate that complete integration. For standalone execution, use the client or
-Kitchen instruction builders described above.
-
-The legacy route's `execution.code` means the finalized **code account**, not its
-metadata address. The helper neither stages nor checks that code against its newly
-compiled bytes, and it drops the compiler account manifest. Keep the direct
-compilation result when inspecting historical routes. EVM-source Portal helpers
-can encode an SVM destination; they do not provide Solana-origin submission.
+**Build Solana execution with the Kitchen client, not the SVM route helpers.**
+
+`Solana(body, { execution, ... }).reward(...)`, `routes.compileSauceRoute()`,
+`buildSauceSvmCall()` and `buildSauceSvmCalls()` emit an `execute_from_account`
+instruction carrying only its 8-byte discriminator. The engine needs 65 further
+bytes of Pot derivation material and a trailing Pot signer that the Kitchen
+supplies, so that instruction is not one it will run — and pointing the helper at
+a different engine id does not add the missing bytes.
+
+The [SVM Portal's fulfillment](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
+forwards a route's instruction bytes to their target unchanged and signs for its
+own Executor PDA. It does not assemble a Kitchen call or sign for a Sauce Pot.
+A Portal integration that reaches the Kitchen therefore needs cook data and
+accounts built separately — the owner signature, the Pot, the fee configuration
+and payer, the engine, and staged metadata and code where they apply. That
+assembly is not in this package.
+
+One detail worth knowing if you are reading routes somebody already built:
+`execution.code` there means the finalized **code account**, not its metadata
+address, and the helper neither stages that code nor checks it against the bytes
+it just compiled. Keep the direct compilation result when you inspect one.
+
+The EVM-source Portal helpers can encode a Solana destination perfectly well.
+That is about encoding, not about submitting from Solana.
 
 ## Venue accessors
 
-The `Solana` global includes the venues registered for runtime access. A venue accessor exposes a program ID, pool configuration loading, quote-source generation, swap CPI construction, and a TypeScript reference quote:
+The `Solana` accessor, imported from the package root, includes the venues registered for runtime access. A venue accessor exposes a program ID, pool configuration loading, quote-source generation, swap CPI construction, and a TypeScript reference quote:
 
 ```ts
 import { venue } from "@eco-incorp/sauce/svm";
@@ -194,6 +193,6 @@ export async function buildRaydiumSwap(
 }
 ```
 
-`Solana.RaydiumCpSwap` exposes the same accessor when globals are installed. `poolConfig` uses the account loader you supply; it does not create an RPC client or discover pools. `quoteSource` returns SauceScript source, and `.swap` returns CPI data plus account references, not a transaction.
+`Solana.RaydiumCpSwap` exposes the same accessor after `import { Solana } from "@eco-incorp/sauce"`. `poolConfig` uses the account loader you supply; it does not create an RPC client or discover pools. `quoteSource` returns SauceScript source, and `.swap` returns CPI data plus account references, not a transaction.
 
 Venue swap builders use a venue-level minimum output of one; the composed program must enforce the user's actual minimum with a post-swap output balance delta. Runtime accessors cover the registered venue set. Other adapters exported from `/svm` do not automatically appear as `Solana.<Venue>`; consult [coverage](../api/coverage.md).