@eco-incorp/sauce 0.99.4 → 0.99.6

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,217 @@ 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` | plain `route.calls` the Portal's Executor runs         | 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.
+
+A body takes the first shape only when **every** statement in the braces is a
+`transfer(to, amount)` or `approve(spender, amount)` call, on a registered token symbol such as
+`USDC` or on `Token(address)` with a literal or compile-time address, and each argument is a
+literal, a compile-time define, or a variable of the enclosing program. A single statement of any
+other kind — a local, a balance read, a condition, a loop, a `transferFrom`, a protocol call, an
+intent of its own — makes the whole body a program.
+
+#### Token-only bodies run on the Executor
+
+A token-only body is not a Sauce program. The Portal's Executor runs each call itself, and checks
+only that the call did not revert and that the target has code. It does not decode what a token
+returns:
+
+- **USDT is fully supported.** A token that returns nothing from `transfer` or `approve` works.
+  Every `approve` becomes two calls, `approve(spender, 0)` and then `approve(spender, amount)`,
+  because USDT refuses to change one non-zero allowance to another and one Executor runs every
+  intent on a chain, so an earlier intent's allowance may still be standing. A transfer stays one
+  call. The reset adds about 8,000 gas per approve.
+- **A token that returns `false` instead of reverting is not detected.** The tokens the solver
+  delivers are pulled by the Portal with OpenZeppelin's `safeTransferFrom`, so one that returns
+  `false` fails delivery. But when the Executor's own `transfer` or `approve` returns `false`, the
+  intent is still fulfilled, with nothing moved.
+
+For full `SafeERC20` checks, make the body a program by adding any statement that is not a token
+write, such as `const held = USDC.balanceOf(ctx.self());`. A program's token writes are
+[`SafeERC20`](protocols-and-tokens.md#writes-follow-safeerc20), and a `false` return reverts the
+fulfilment. A program needs the destination's Kitchen fee and a deployed Pot, as the table says,
+and the solver's delivery named in the second argument, because it is not derived for a program
+(see below).
+
+```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.
@@ -114,7 +362,7 @@ Use literals for self-contained callbacks, or source strings plus `defines` for
 
 Callbacks must be synchronous and take no parameters. Bound/native functions, generators, and async functions are rejected. If a bundler transforms function source, ship an explicit SauceScript string or source asset. A TypeScript type declaration does not create a captured value.
 
-`Base(...)` adds the SDK's default ambient token module, enabling function forms such as `approve(tokenAddress, spender, amount)`. Direct `compileSauceRoute(...)` does not automatically add that ambient module. The token and protocol member syntax described in [protocols and tokens](protocols-and-tokens.md) is a separate rewrite.
+`Base(...)` adds the SDK's default ambient token module, enabling function forms such as `approve(tokenAddress, spender, amount)`. Direct `compileSauceRoute(...)` does not automatically add that ambient module. The token and protocol member syntax described in [protocols and tokens](protocols-and-tokens.md) is a separate rewrite that works on both paths; its writes import the same module's functions themselves, so they have the same `SafeERC20` semantics either way.
 
 ## Submit the source reward
 
@@ -155,4 +403,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.

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.