@eco-incorp/sauce 0.99.4 → 0.99.6

package/docs/api/coverage.md

@@ -1,20 +1,21 @@
-# Registry and global namespace coverage
+# What is actually registered
 
-The SDK has several registries with different purposes. A protocol catalog entry does not
-necessarily have a global contract accessor or a deployment on your selected chain.
+The SDK carries several registries, and they answer different questions. "Is this protocol in the
+catalog?" is not "can I call it by name in a program?", and neither is "is it deployed on my chain?".
+Each of the three can be true without the others.
 
 | Registry                         | Current scope                                                                     | Inspect it                                                             |
 | -------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Protocol catalog                 | 129 protocols with metadata, deployments, ABI fragments, and program templates    | `listProtocols()`, `getProtocol(slug)`, `getProtocolsByChain(id)`      |
+| Protocol catalog                 | 135 protocols with metadata, deployments, ABI fragments, and program templates    | `listProtocols()`, `getProtocol(slug)`, `getProtocolsByChain(id)`      |
 | Contract descriptors             | 30 descriptors across 16 protocol/interface namespaces                            | `contracts.listDescriptors()`, `contracts.listContracts(slug)`         |
 | Compiled-source protocol globals | 26 singleton contract leaves across 14 protocol namespaces, plus 5 family aliases | TypeScript completion after importing `@eco-incorp/sauce`; names below |
-| Token symbols                    | 5 symbols distributed across 6 EVM chains                                         | `routes.TOKEN_REGISTRY`, `routes.knownTokenSymbols(chain)`             |
-| Canonical chain identities       | 40 chains: 39 EVM and Solana                                                      | `CANONICAL_CHAINS`, `requireChain(ref)`                                |
-| EVM chain metadata               | 33 records with RPC and explorer information                                      | `chains`, `getChain(id)`, `getAllChainIds()`                           |
+| Token symbols                    | 7 symbols distributed across 7 EVM chains                                         | `routes.TOKEN_REGISTRY`, `routes.knownTokenSymbols(chain)`             |
+| Canonical chain identities       | 41 chains: 40 EVM and Solana                                                      | `CANONICAL_CHAINS`, `requireChain(ref)`                                |
+| EVM chain metadata               | 34 records with native-currency and explorer information                          | `chains`, `getChain(id)`, `getAllChainIds()`                           |
 
-The descriptor registry connects each supported address role to an ABI and a contract name.
-Use `contracts.listDescriptors()` to inspect these curated associations; they cannot be
-inferred reliably for every catalog entry.
+The descriptor registry is the one that makes a name callable: it ties a contract name to an ABI and
+an address role. `contracts.listDescriptors()` lists them. These associations are curated rather than
+derived, which is why the catalog is much larger.
 
 ## Protocol globals
 
@@ -22,27 +23,26 @@ These names are available inside compiled EVM route bodies. Availability on the
 is checked during compilation. The declarations describe the vendored ABI surface, which is a
 subset of each protocol's complete API.
 
-| Namespace       | Contract leaves                                                                       |
-| --------------- | ------------------------------------------------------------------------------------- |
-| `UniswapV2`     | `Factory`, `Router`                                                                   |
-| `UniswapV3`     | `Factory`†, `SwapRouter`†, `SwapRouter02`†, `QuoterV2`†, `NonfungiblePositionManager` |
-| `UniswapV4`     | `PoolManager`†, `UniversalRouter`, `PositionManager`                                  |
-| `SushiswapV2`   | `Factory`, `Router`                                                                   |
-| `PancakeswapV2` | `Factory`, `Router`                                                                   |
-| `Aerodrome`     | `Router`, `PoolFactory`                                                               |
-| `Cctp`          | `TokenMessenger`                                                                      |
-| `AaveV3`        | `Pool`                                                                                |
-| `AaveV2`        | `LendingPool`                                                                         |
-| `Permit2`       | `Permit2`                                                                             |
-| `Oneinch`       | `AggregationRouterV6`                                                                 |
-| `Pendle`        | `Router`                                                                              |
-| `MorphoBlue`    | `Morpho`                                                                              |
-| `CompoundV3`    | `CometUSDC`, `CometWETH`, `CometUSDT`                                                 |
-
-† These descriptors have **widened ABI types** whose selectors differ from the deployed contract.
-Compilation refuses them by default, with an explanation in `descriptor.coverage.caveats`.
-`compile.accessors.allowWidenedSelectors: true` only bypasses that check; it does not repair the
-ABI or make the resulting call valid.
+| Namespace       | Contract leaves                                                                   |
+| --------------- | --------------------------------------------------------------------------------- |
+| `UniswapV2`     | `Factory`, `Router`                                                               |
+| `UniswapV3`     | `Factory`, `SwapRouter`, `SwapRouter02`, `QuoterV2`, `NonfungiblePositionManager` |
+| `UniswapV4`     | `PoolManager`, `UniversalRouter`, `PositionManager`                               |
+| `SushiswapV2`   | `Factory`, `Router`                                                               |
+| `PancakeswapV2` | `Factory`, `Router`                                                               |
+| `Aerodrome`     | `Router`, `PoolFactory`                                                           |
+| `Cctp`          | `TokenMessenger`                                                                  |
+| `AaveV3`        | `Pool`                                                                            |
+| `AaveV2`        | `LendingPool`                                                                     |
+| `Permit2`       | `Permit2`                                                                         |
+| `Oneinch`       | `AggregationRouterV6`                                                             |
+| `Pendle`        | `Router`                                                                          |
+| `MorphoBlue`    | `Morpho`                                                                          |
+| `CompoundV3`    | `CometUSDC`, `CometWETH`, `CometUSDT`                                             |
+
+Every descriptor declares its contract's deployed ABI types, so its selectors are the deployed
+ones. `compile.accessors.allowWidenedSelectors` is still accepted, and no shipped descriptor needs
+it.
 
 Family aliases are `Uniswap`, `Sushiswap`, `Pancakeswap`, `Aave`, and `Compound`. A family exposes
 a contract only when exactly one member owns its name. Consequently:
@@ -65,14 +65,18 @@ and `MorphoBlue.Bundler3` have addresses but no vendored ABI; `Erc20.ERC20` and
 
 The exported `routes.TOKEN_REGISTRY` contains:
 
-| Chain    | ID    | Symbols                |
-| -------- | ----- | ---------------------- |
-| Ethereum | 1     | `USDC`, `USDT`, `WETH` |
-| Optimism | 10    | `USDC`, `USDT`, `WETH` |
-| Polygon  | 137   | `USDC`, `WETH`, `WPOL` |
-| Monad    | 143   | `USDC`, `WMON`         |
-| Base     | 8453  | `USDC`, `WETH`         |
-| Arbitrum | 42161 | `USDC`, `WETH`         |
+| Chain    | ID    | Symbols                        |
+| -------- | ----- | ------------------------------ |
+| Ethereum | 1     | `USDC`, `USDT`, `WETH`         |
+| Optimism | 10    | `USDC`, `USDT`, `WETH`         |
+| Polygon  | 137   | `USDC`, `WETH`, `WPOL`         |
+| Monad    | 143   | `USDC`, `WMON`                 |
+| Arc      | 5042  | `USDC`, `EURC`, `USYC`, `WETH` |
+| Base     | 8453  | `USDC`, `WETH`                 |
+| Arbitrum | 42161 | `USDC`, `WETH`                 |
+
+On Arc, `USDC` is the ERC-20 face of the chain's native coin, and `WETH` is bridged ETH rather than
+a wrapped native. See [Arc: USDC is the native coin](#arc-usdc-is-the-native-coin).
 
 A missing symbol means the registry has no verified row under that name. Token variants can have
 different symbols and addresses. `IntentOptions.tokenDefines` or `SauceCompileOptions.tokens`
@@ -90,6 +94,46 @@ routes.registryTokenAddress(base, "USDC"); // bigint address, or undefined if ab
 These ERC-20 source globals target EVM. Use the [Solana account and token helpers](../guides/solana.md)
 for SPL tokens.
 
+## Arc: USDC is the native coin
+
+Arc (chain 5042) pays gas in USDC, and it has **one USDC balance with two decimal scales**:
+
+| Read through                                               | Scale       | 1 USDC is             |
+| ---------------------------------------------------------- | ----------- | --------------------- |
+| Native: `msg.value`, `eth_getBalance`, gas                 | 18 decimals | `1000000000000000000` |
+| The ERC-20 at `0x3600000000000000000000000000000000000000` | 6 decimals  | `1000000`             |
+
+`getChain(5042).nativeCurrency.erc20` records the ERC-20, and `nativeErc20(chainId)` returns it, or
+`undefined` on a chain whose native coin is separate from every token.
+
+- **One balance.** Sending native value and calling `USDC.transfer` move the same money. A Pot that
+  bridges its whole `balanceOf(USDC)` and also pays a native fee — a Hyperlane or LayerZero fee,
+  the Kitchen's execution fee, deBridge's fixed fee — runs out, because the fee comes from that same
+  balance. Leave room for the fee.
+- **Dust is invisible to the ERC-20.** `balanceOf` is the native balance divided by 10¹² and rounded
+  down, so less than 10¹² wei reads as 0. `nativeToErc20Amount(5042, wei)` converts the same way.
+  Compare native and token amounts only after converting one to the other's scale.
+- **Every native amount is 18 decimals.** That includes `executionFee`, `execution.value`,
+  `nativeAmount` in a route or reward, and a cook's `value`. `1_000_000n` of native value is
+  10⁻¹² USDC, not 1 USDC. `Kitchen.executionFee()` read on Arc on 2026-09-28 was
+  `10000000000000000`, which is 0.01 USDC.
+- **Gas has a 20 gwei floor.** The minimum base fee is 20 gwei, and the mempool silently drops a
+  transaction whose `maxFeePerGas` is below it: no error, no receipt. Gas costs
+  `gasUsed × gasPrice / 10¹²` in `USDC` token units.
+- **There is no canonical wrapped native.** Nothing needs wrapping. `WETH` in the token registry is
+  bridged ETH with no `deposit()` or `withdraw()`, and Uniswap's Arc periphery reports a `WETH9()` that
+  always reverts, so the ETH paths of those routers revert too. The one WETH9-shaped contract on Arc is
+  CCIP's fee token `CCIP_USDC`, which the SDK does not register. Actions `wrapETH`, `unwrapETH`, the
+  native ETH stakes, and a `nativeBalance` spent as a token amount are rejected when a program's
+  `chainId` is 5042. The deposit builder's `weth` templates reject Arc's `USDC` and registry tokens as
+  a target.
+- **Native value can be refused.** A value transfer to the zero address, to or from a
+  blocklisted address, or to a self-destructed account reverts, including one a contract forwards.
+
+An intent to Arc also needs its own Pot. Arc's Portal is a different deployment from the one most
+chains share, so its Executor and derived Pot differ; see
+[Arc's Pot](../guides/intents.md#arcs-pot).
+
 ## Host discovery and chain coverage
 
 ```ts
@@ -106,12 +150,19 @@ const onBase = contracts.contractsOnChain("base");
 ```
 
 Host accessors such as `Base.Uniswap.UniversalRouter` and `contracts.on(...)` build inert
-`ContractCall` objects when their methods are invoked. Their dynamic method properties are currently
-typed `unknown`; TypeScript callers must narrow or cast a method before calling it. This is distinct
-from the generated ABI method types on bare protocol names inside compiled source.
-
-Use `requireChain` for route identities. The separate metadata lookup `getChain` does not currently
-include Unichain, Monad, Sonic, Ronin, Plasma, or Ink, although they are canonical chains. Chain
-identity, protocol availability, and Sauce engine deployment are separate checks. Deployment helpers
-expose recorded addresses and coverage; applications still need a live deployment suitable for their
-execution path.
+`ContractCall` objects when their methods are invoked. Those methods are typed `unknown` — their
+signatures come from an ABI the type system never sees — so narrow one before calling it. The bare
+protocol names _inside_ a compiled program are different: those do have generated ABI method types.
+
+Use `requireChain` for route identities. `getChain` is a separate metadata lookup with
+native-currency and explorer details, and it covers fewer chains: Unichain, Monad, Sonic, Ronin,
+Plasma and Ink are canonical chains with no metadata record.
+
+The SDK ships no RPC endpoints; pass your own. No chain record, Solana cluster or default carries a
+URL, and nothing reads one from the environment. Whatever reads a chain takes its connection from
+you: a client you construct for the EVM reads, and `rpcUrl` for `createSauceSvmClient`, which throws
+naming that option when it is missing.
+
+Three questions, three answers: whether a chain is canonical, whether a protocol is available on it,
+and whether a Sauce engine is deployed there. The deployment helpers report recorded addresses — what
+your execution path needs is code that is live, which is a read you make.

package/docs/api/routes.md

@@ -2,15 +2,17 @@
 
 [Documentation](../README.md) · [Create an intent](../guides/intents.md) · [Compiler](compiler.md)
 
-Import the routes namespace from the package root:
+`routes` is the namespace behind every chain accessor: the intent builder, the encoders and hashes,
+the Portal helpers and the nesting modes. Import it from the package root, next to the chains you use:
 
 ```ts
-import { routes } from "@eco-incorp/sauce";
+import { Base, routes } from "@eco-incorp/sauce";
 
 const destination = routes.chain("base");
 ```
 
-There is no published `/routes` subpath. Public route types are available as `routes.IntentOptions`, `routes.BuiltIntent`, and other members of this namespace.
+There is no `/routes` subpath. The public types are members of the namespace: `routes.IntentOptions`,
+`routes.BuiltIntent`, and so on.
 
 ## Chain entry points
 
@@ -22,26 +24,30 @@ There is no published `/routes` subpath. Public route types are available as `ro
 | `routes.chainAccessors.Base`           | Explicit access to the route chain entry point    |
 | `routes.openRoute(ref, body, options)` | Direct function behind chain entry points         |
 
-Chain references accept canonical slugs, names/aliases supported by the registry, numeric chain IDs, and canonical chain records. `.chain` exposes the canonical record. Root import installs the composed globals, which also expose host contract/venue accessors; `routes.chain(...)` is the route entry point.
+Chain references accept canonical slugs, names/aliases supported by the registry, numeric chain IDs, and canonical chain records. `.chain` exposes the canonical record.
+
+`Base` and every other chain are **named exports of the package root**; importing the package installs nothing on `globalThis`. A root-imported accessor is the composed one, which also exposes host contract and venue accessors (`Base.Uniswap.UniversalRouter`, `Solana.RaydiumCpSwap`); `routes.chainAccessors.Base` is the bare route entry point without that tree. A host that wants the bare names at run time can call `installRouteGlobals()`; `uninstallRouteGlobals()` reverses it, and neither installs TypeScript declarations.
 
 `body` accepts a source string or a synchronous zero-argument callback. A string can contain a full `function main(...)` or a bare body. A callback supplies source text, with no JavaScript capture. See [callback semantics](../guides/intents.md#callbacks-are-compiled-source).
 
 ## Intent options
 
-| Option                                          | Purpose                                                                              |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `execution`                                     | EVM `{ pot, engine, value? }`; SVM route calls cannot execute on the released engine |
-| `pot`, `engine`                                 | EVM shorthand instead of `execution`; both are required together                     |
-| `portal`, `deadline`                            | Required destination Portal and absolute route deadline                              |
-| `salt`                                          | Route salt; defaults to 32 zero bytes                                                |
-| `tokens`, `nativeAmount`                        | Solver-delivered destination assets                                                  |
-| `precalls`                                      | Calls before the compiled program and nested calls                                   |
-| `tokenDefines`                                  | Token-symbol address overrides                                                       |
-| `defines`, `compile`                            | Program specialization and compile options                                           |
-| `sourcePortal`                                  | Default source Portal for submission/read requests                                   |
-| `source`, `creator`, `prover`, `rewardDeadline` | Fallback fields for `.reward(...)`                                                   |
-
-The EVM shorthand sends zero `cook` value and only works with a fee-free Kitchen when the program needs no native input. For released deployments, use `execution: { pot, engine, value }` with the current Kitchen fee plus any native assets the program spends, and budget `nativeAmount` for all route call values. The direct route's Pot owner must equal the destination `Portal.executor()`. See [deployment and fee setup](../guides/intents.md#prepare-the-destination-pot).
+| Option                                          | Purpose                                                                          |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| `execution`                                     | EVM `{ pot?, engine?, value? }`; an SVM route call is not executable (see below) |
+| `pot`, `engine`                                 | EVM shorthand for `execution.pot` and `execution.engine`; each optional          |
+| `deadline`                                      | Absolute route deadline. Required                                                |
+| `portal`                                        | Destination Portal. Defaults to the eco-routes deployment for that chain         |
+| `ecoRoutes`                                     | Which eco-routes deployment to address: `generation` and `environment`           |
+| `salt`                                          | Route salt; defaults to 32 zero bytes                                            |
+| `tokens`, `nativeAmount`                        | Solver-delivered destination assets                                              |
+| `precalls`                                      | Calls before the compiled program and nested calls                               |
+| `tokenDefines`                                  | Token-symbol address overrides                                                   |
+| `defines`, `compile`                            | Program specialization and compile options                                       |
+| `sourcePortal`                                  | Source Portal for submission/read requests. Defaults like `portal`               |
+| `source`, `creator`, `prover`, `rewardDeadline` | Fallback fields for `.reward(...)`                                               |
+
+On an EVM destination the Pot and engine are derived when omitted: the Pot owned by the `executor()` of the Portal the route records, under salt zero (`SAUCE_INTENT_POT_SALT`) — the one Pot per Portal the solver deploys — and the released engine. The route does not deploy it: the Pot must exist before fulfilment, and the solver deploys it. A Pot you name must equally exist and be owned by that Executor. `destinationPot(chain, { portal?, ecoRoutes? })` returns the derived address. Set `execution.value` to the current Kitchen fee plus any native assets the program spends, and budget `nativeAmount` for all route call values; with no `value`, the cook sends zero and works only with a fee-free Kitchen. See [the destination Pot](../guides/intents.md#the-destination-pot).
 
 `.reward(...)` accepts an object, a native amount as `bigint`, or an array of `{ token, amount }`. Object fields override option fallbacks. `source`, `creator`, and `prover` must resolve from one of those places. Reward deadline resolution is `reward.deadline`, then `options.rewardDeadline`, then `options.deadline`. Native and token amounts default to zero/empty where omitted.
 
@@ -67,7 +73,7 @@ export function compileProgram(execution: routes.SauceEvmExecutionInput) {
 
 The route wrapper differs from the direct `/compiler` API, which returns one byte array plus compiler metadata and an optional SVM account manifest. Use the direct API when you need that metadata. The route target defaults to `"v12"` for EVM and `"svm"` for SVM; direct compiler targets are `"evm"` and `"svm"`.
 
-`SauceCompileOptions` supports `baseDirs`, scalar `defines`, token-address `tokens`, ABI `contracts`, `ambient` module names, and `accessors`. Accessor rewriting defaults on; an options object can configure qualified-chain scope or other rewrite behavior. `openRoute` merges chain defaults and the default ambient token module. Direct `compileSauceRoute` performs token/protocol rewrites but does not automatically merge that ambient module.
+`SauceCompileOptions` supports `resolve` and `resolvePackage` for the program's own imports, scalar `defines`, token-address `tokens`, ABI `contracts`, `ambient` module names, and `accessors`. `resolve` has the [compiler's resolver contract](compiler.md#resolver-contract) and is asked for any path the program imports; the SDK itself serves `@sauce/token`, `./artifacts/IERC20.json`, `./artifacts/ISauceRouter.json` and every `./protocols/<slug>/<Export>.json`, so source from the SDK's builders needs neither option. Accessor rewriting defaults on; an options object can configure qualified-chain scope or other rewrite behavior. `openRoute` merges chain defaults and the default ambient token module. Direct `compileSauceRoute` performs token/protocol rewrites but does not automatically merge that ambient module.
 
 The route wrapper has no runtime argument-payload parameter. Use compile-time defines here, or direct compilation and a suitable execution API for parameterized entry points; see [compiler integration](compiler.md).
 
@@ -77,9 +83,11 @@ The route wrapper has no runtime argument-payload parameter. Use compile-time de
 
 ## Deployment addresses
 
-`sauceEvmDeployPotCall({ owner, salt, kitchen })` encodes Pot deployment through the supplied Kitchen; direct intent routes use the destination `Portal.executor()` as owner. Its `chainId` alternative selects the pinned release Kitchen only for chains in the historical successful-deployment roster. `v12Deployment` and `requireV12Deployment` also return current release addresses under that historical filter; none of these helpers verifies current on-chain deployment. Prefer explicit `v12KitchenAddress()` after checking the target chain. `V12_EVM_CONTRACTS` and `v12SvmProgramId` are legacy addresses; use the current `/deployments` address functions. [evm-execution.ts](../examples/evm-execution.ts) demonstrates prediction, deployment, and owner/Kitchen checks.
+`sauceEvmDeployPotCall({ owner, salt, kitchen })` encodes Pot deployment through the Kitchen you name; for a direct intent route the owner is the destination `Portal.executor()`. No route the SDK builds includes this call. To deploy an intent's shared Pot yourself before the solver does, pass `kitchen: v12GateKitchen()`, that Executor, and `SAUCE_INTENT_POT_SALT`.
 
-`buildSauceSvmCall` and the SVM route path emit a legacy 8-byte staged-engine instruction, which is **incompatible with engine 1.2.0** even when supplied a code account and the current engine ID. They do not construct the required Kitchen call. Use the direct Kitchen client for Solana execution; see [the SVM intent limitation](../guides/solana.md#svm-destinations-in-eco-intents).
+Every address helper here returns a **recorded** address, never a verified one. `v12EngineAddress()` and `v12KitchenAddress()` give the released addresses directly and are the ones to prefer. `sauceEvmDeployPotCall`'s `chainId` form, `v12Deployment` and `requireV12Deployment` filter by a roster of chains where deployment previously succeeded, which is a different question from whether code is there now. `V12_EVM_CONTRACTS` and `v12SvmProgramId` name an earlier deployment generation. Check the chain before trusting any of them; [evm-execution.ts](../examples/evm-execution.ts) shows prediction, deployment and the owner/Kitchen checks.
+
+`buildSauceSvmCall` and the SVM route path emit an 8-byte engine instruction that the Solana engine does not accept, whatever code account or engine id you give them: they do not build the Kitchen call the engine requires. Build Solana execution with the Kitchen client instead — see [SVM destinations in Eco intents](../guides/solana.md#svm-destinations-in-eco-intents).
 
 ## Built intents
 
@@ -99,7 +107,7 @@ The route wrapper has no runtime argument-payload parameter. Use compile-time de
 | `vaultCall()`, `hashCall()`, `fundedCall()` | Source Portal read request plus result decoder                      |
 | `predictVault(config)`                      | Offline CREATE2 prediction with caller-provided vault configuration |
 
-Submission/read helpers accept an optional `{ portal }` override; otherwise `sourcePortal` is required. They generate EVM requests, require an EVM source, and never perform RPC. The codec can represent an SVM destination, but the built-in SVM Sauce route has the execution limitation above. Source/destination-selected encoding is used internally by hashing and Portal helpers; explicitly forcing a codec does not change an intent's chain kinds.
+Submission and read helpers take an optional `{ portal }` override; without one they use `sourcePortal`, which itself defaults to the eco-routes Portal for the reward's source chain. They build EVM requests, require an EVM source, and perform no RPC — you send them. The codec represents an SVM destination fine; building that execution is the separate matter above. `encodeEVM()`/`encodeSVM()` force a codec for inspection; they do not change an intent's chain kinds.
 
 ## Composition and lower-level encoding
 
@@ -108,3 +116,24 @@ Call `.nest(childOrThunk, options?)` before `.reward(...)`. The fluent default i
 For callers building their own calls, `assembleIntent(source, destination, route, reward)` normalizes an intent without compiling a program. `encodeRoute`, `encodeReward`, `hashIntent`, and their explicit EVM/SVM variants expose encoding and hashing. `toUniversalAddress` normalizes addresses for the cross-chain intent model, while `denormalizeToEvm` converts an EVM-shaped universal address back to its 20-byte form.
 
 The low-level `nestedChildCalls` helper builds approval/publication calls with explicit Portal and `allowPartial` settings. The fluent `.nest()` default is `"transfer"`; pass the current `executionFee` for its additional cook.
+
+`via: "dynamic"` creates the child **during** the parent's execution, from an amount measured on
+chain. `AMOUNT_IN_PLACEHOLDER` and `AMOUNT_OUT_PLACEHOLDER` mark the amounts to splice;
+`renderDynamicChild(child, options, amountIn)` reproduces the resulting calldata off-chain, and
+`dynamicChildTemplate` / `dynamicChildStatements` / `dynamicChildProgram` expose the segments,
+statements and merged program the builder generates. Underneath are `splitByPlaceholders`,
+`renderTemplate` and `emitTemplate` — byte-templating primitives that work against any encoding whose
+fields sit at fixed offsets, not only intents.
+
+A program can also create an intent itself, with `Chain(() => { ... }).reward({ ... })` written in
+its body — see [create an intent](../guides/intents.md#create-an-intent-from-inside-a-program).
+`SauceCompileOptions.intents` carries what that lowering cannot look up (a deadline, a creator) and
+what overrides it: `sourcePortal`, `destinationPortal`, `prover`, `salt`, `allowPartial`, and the
+eco-routes `generation`/`environment`. Through `Base(...)` those are inherited from the enclosing
+intent, so the common case sets none of them.
+
+Where eco-routes is deployed is a registry: `ecoRoutesPortal(chain)`, `ecoRoutesProver(source,
+destination)`, `ecoRoutesDeployment(chain)` and `ecoRoutesGenerations()` from
+`@eco-incorp/sauce/protocols/eco-routes`. Both generations ship — `v3`'s single Portal and `v2`'s
+separate `IntentSource`/`Inbox` — in production and staging, vendored from
+`@eco-foundation/routes-ts` at a pinned version and digest.

package/docs/concepts/architecture.md

@@ -1,134 +1,103 @@
-# SDK, compiler, and runtime
-
-[Documentation](../README.md) · [Quick start](../guides/quick-start.md)
-
-Sauce turns a program into an atomic on-chain execution. The SDK supplies chain and
-protocol knowledge, the compiler translates SauceScript into bytecode, and a
-compatible on-chain engine executes that bytecode. An Eco intent describes the
-destination execution and the reward for fulfilling it.
-
-## The three layers
-
-| Layer    | Published surface                                                                  | Responsibility                                                                                                                             |
-| -------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| SDK      | `@eco-incorp/sauce` and its subpaths                                               | Protocol and token registries, route syntax, builders, intent encoding, account planning, transaction helpers, and settlement verification |
-| Compiler | `@eco-incorp/sauce-compiler`; exposed in Node through `@eco-incorp/sauce/compiler` | Parse and check SauceScript, resolve modules and ABIs, apply compile-time parameters, and emit EVM or SVM bytecode                         |
-| Runtime  | Deployed Sauce EVM/SVM engines and Kitchen/Pot contracts or programs               | Execute compatible bytecode against the chain's accounts and contracts                                                                     |
-
-The compiler is included when you install `@eco-incorp/sauce`. Import
-`@eco-incorp/sauce/compiler` to compile standalone programs, or use the SDK
-route builders to resolve protocol and token names automatically.
-
-```mermaid
-flowchart TD
-    A[Route closure or source string] --> B[SDK: destination, tokens, protocols, defines]
-    B --> C[Rewritten SauceScript and ABI bindings]
-    C --> D[Published Sauce compiler]
-    E[Standalone SauceScript and resolver] --> D
-    D --> F[EVM bytecode]
-    D --> G[SVM bytecode and account manifest]
-    F --> H[Pot.cook: engine and program]
-    G --> I[Account plan and Kitchen cook instruction]
-    H --> J[Direct transaction or Eco route call]
-    I --> K[Solana transaction]
-```
+# How Sauce fits together
+
+[Documentation](../README.md) · [Quick start](../guides/quick-start.md) · [SauceScript](saucescript.md)
+
+Sauce turns a program into one atomic on-chain execution. Three pieces divide that work, and knowing
+which piece owns a problem is most of what this page is for.
+
+| Piece    | Where it lives                                   | What it does                                                                                                 |
+| -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| This SDK | `@eco-incorp/sauce` and its subpaths             | Chain, protocol and token knowledge; route syntax; builders; intent encoding; account planning; verification |
+| Compiler | bundled, exposed at `@eco-incorp/sauce/compiler` | Checks SauceScript, resolves modules and ABIs, applies compile-time values, emits bytecode for a target      |
+| Engine   | deployed on chain, with a Kitchen and Pot        | Executes that bytecode against the chain's real contracts and accounts                                       |
+
+You only install one package. The compiler comes with it.
 
-Both compiler targets use Sauce bytecode. EVM output is not a Solidity contract's
-deployment bytecode, and SVM output is not a Solana ELF program. The selected
-Sauce engine interprets it.
+What the engine actually does is simple enough to state in a sentence and is all you need to reason
+about: **it runs your program's steps in order, inside the surrounding transaction, and anything
+that reverts reverts the whole thing.** There is no partial execution, no retry, no rollback of one
+step. The bytecode is Sauce's own — not a Solidity contract's deployment code, not a Solana ELF
+program — and only a Sauce engine interprets it.
 
-## From global names to contract calls
+## From a name to a contract call
 
-Inside an EVM route, the SDK lets you write:
+Inside an EVM route body you write:
 
 ```js
 USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
 ```
 
-The destination chain selects `USDC` and the router deployment. Before invoking
-the compiler, the SDK rewrites token and protocol access into contract bindings,
-supplies the matching ABIs, and injects scalar addresses. The compiler then sees
-the equivalent `IERC20.at(...).approve(...)` call.
+The destination chain picks which `USDC` and which router that means. Before compiling, the SDK
+rewrites those names, supplies the matching ABIs and injects the addresses. A token write becomes a
+call to the `@sauce/token` library, whose writes follow OpenZeppelin `SafeERC20`, so the compiler
+sees the equivalent of `approve(USDC, <the router's address>, 1_000_000n)`. A token read and a
+protocol call become ABI-bound calls such as `IERC20.at(USDC).balanceOf(...)`.
 
-These names are SDK syntax, not builtins of the standalone compiler. A direct
-`compile()` call needs explicit ABI imports/bindings and any addresses or defines
-the program uses. See [protocols and tokens](../guides/protocols-and-tokens.md) and
-[the compiler API](../api/compiler.md).
+These names belong to the SDK's route path, not to the compiler. A direct `compile()` call resolves
+nothing for you: bind ABIs and supply addresses yourself. See
+[protocols and tokens](../guides/protocols-and-tokens.md) and [compiling](../guides/compiling.md).
 
-There are also separate host JavaScript and SauceScript environments. Importing
-the SDK installs chain helpers such as `Base` in the host. A route callback is
-read as source and compiled; it is never invoked as a JavaScript callback and
-does not capture its surrounding variables. Generated TypeScript declarations
-help you author route bodies, but compilation still resolves each name against
-the selected destination's actual registry.
+## Two environments that look alike
+
+A route body is **source text**, not a callback. The SDK reads it, rewrites it and compiles it; it
+is never invoked as JavaScript and captures no surrounding variable. A host `const amount = …` does
+not exist inside the program — pass it through `defines`.
+
+That is why `Base` and `USDC` behave differently even though both are bare names. `Base` is a named
+export you import. `USDC` is program syntax the compiler resolves. The package ships TypeScript
+declarations for the program names so a typed body still checks, but a declaration is a type, not a
+value.
 
 ## From bytecode to execution
 
 ### EVM
 
-`V12Pot.cook(address engine, bytes program)` runs one program. A Pot has an owner;
-the engine is supplied on each cook. Constructing a call therefore needs both a
-**Pot address** and an **engine address**. The SDK does not infer them from the
-protocol namespace. The released engine accepts only canonical Pots deployed through
-its configured Kitchen. Each cook must send the Kitchen's current `executionFee()`
-in `msg.value`; the Pot remits it before running the program. Add native program
-funding on top of that fee. An existing Pot balance does not replace this payment.
-
-A multi-statement route body compiles to one program and one cook. To run separate
-programs, construct separate calls and use an authorized execution mechanism that
-propagates failures if the entire operation must be atomic. The caller must have
-authority to invoke the Pot. For direct Eco route calls, the caller and required
-Pot owner is the destination `Portal.executor()`. Keep funds in that shared Pot
-only during the fulfillment; [intent setup](../guides/intents.md#prepare-the-destination-pot)
-shows deployment, custody, and fee handling.
-
-### SVM
-
-The compiler returns an account manifest as well as bytecode. `Account` parameters
-name attached slots; their `Writable` and `Signer` modifiers describe required
-roles. Account identities and instruction data travel through separate channels.
-
-The SVM SDK resolves account plans, builds instructions and transactions, and
-supports Kitchen-managed code staging. Staged Kitchen execution uses finalized
-metadata and code accounts. The built-in SVM route helper emits a legacy engine
-instruction and is incompatible with the released engine; use the direct Kitchen
-client described in the [Solana guide](../guides/solana.md).
-
-The released engine's `execute_from_account` instruction names a code account;
-its instruction data does not carry a content hash. A program hash checked during
-Kitchen staging or cooking and the identity of the account later executed are
-distinct evidence. See [settlement verification](../guides/verification.md#svm-verify-program-and-accounts).
+A program runs through `Pot.cook(engine, program)`. A Pot has an owner; the engine is named on each
+cook, so a call needs **both** addresses. A direct `compileSauceRoute` takes them from you. An intent
+derives them: the released engine, and the Pot the recorded Portal's Executor owns under salt zero
+(`SAUCE_INTENT_POT_SALT`). That Pot must exist before the route runs; the solver deploys it. An
+engine accepts only Pots created by its own Kitchen.
+
+Every cook must send the Kitchen's current `executionFee()` as native value, even for a program that
+moves only ERC-20s. Native the program itself spends is on top of that. A balance already sitting in
+the Pot does not pay the fee. On Arc, native value is USDC at 18 decimals, drawn from the same
+balance as the USDC ERC-20 ([Arc: USDC is the native coin](../api/coverage.md#arc-usdc-is-the-native-coin)).
+
+One route body is one program and one cook, however many statements it contains. For a Portal-driven
+intent the Pot's owner must be the destination `Portal.executor()`, and the Pot is shared: put
+assets in, use them and take the remainder out within the same fulfillment.
+[The destination Pot](../guides/intents.md#the-destination-pot) covers deployment and overrides.
+
+### Solana
+
+The compiler returns an **account manifest** alongside the bytecode. Each `Account` parameter of
+`main` is a slot; its `Writable`/`Signer` modifiers state the role that slot requires. Account
+identities travel with the instruction, separately from the encoded argument values.
+
+The SDK resolves those slots into a plan, builds the instructions and transactions, and can stage a
+larger program through the Kitchen before executing it. See the [Solana guide](../guides/solana.md).
 
 ## Intents connect executions across chains
 
-`Base(() => { ... }, options).reward(reward)` creates an Eco intent whose route
-executes on Base. The source chain and funding information come from the intent
-options and reward. The SDK compiles the destination program, constructs the
-route, and provides Portal calldata and hashes.
-
-Building an intent does not publish, fund, or fulfill it. Those are transactions
-submitted by the application and fulfillment actors. Nested intents are separate
-executions composed with `.nest(...)`; they do not form one synchronous call
-stack across chains. See [creating intents](../guides/intents.md).
-
-## Compiler and engine compatibility
-
-Compiler 2.3.0 identifies its output as `isaRevision: "stack-compact-v2"` and
-reports the selected entry-argument format. These fields describe the artifact;
-they do not inspect an address or negotiate runtime support.
-
-Use `v12EngineAddress()`, `v12KitchenAddress()`, `v12SvmEngineProgramId()`, and
-`v12SvmKitchenProgramId()` from `@eco-incorp/sauce/deployments` to obtain released
-engine and Kitchen addresses. The legacy chain roster records an older
-deployment and does not attest liveness of the pinned release. Check deployed
-code, cluster, and instruction support on the target chain. Pair programs with the engine
-release intended for them, and retain the compiler version, ISA revision, target,
-and argument format with cached or staged artifacts.
-
-Changing the compiler can change bytecode without changing the source-level API.
-Settlement hash pins, compiled-program caches, and staged programs therefore
-belong in a compiler upgrade's validation. The [verification guide](../guides/verification.md)
-explains the SDK's current settlement pins.
-
-Start with [SauceScript concepts](saucescript.md) for the language boundary, or
-[compiling programs](../guides/compiling.md) for direct compiler integration.
+`Base(body, options).reward(reward)` builds an Eco intent whose route executes on Base. The SDK
+compiles the destination program, assembles the route, and hands back hashes and Portal calldata.
+
+A program can also create an intent itself, with the same `Chain(() => { ... }).reward({ ... })`
+written in its body — which is how a hop whose amount is only known on arrival gets built at all.
+See [create an intent from inside a program](../guides/intents.md#create-an-intent-from-inside-a-program).
+
+Building an intent publishes nothing. Your application submits the source-chain transactions, and a
+solver fulfills the destination. Nested intents are separate executions composed with `.nest(...)` —
+a cascade, not one call stack spanning chains. See [create an intent](../guides/intents.md).
+
+## Versions travel with artifacts
+
+A compiled program is paired with an engine that understands it. The compiler reports what it
+produced; it does not inspect an address to find out what is deployed there. Read the deployment
+helpers in `@eco-incorp/sauce/deployments` for released engine and Kitchen addresses, and confirm the
+code is live on the chain or cluster you are targeting.
+
+Changing the compiler can change bytecode without changing a line of source. Anything that pins
+bytes — a settlement hash, a cached program, a staged code account — has to be re-derived when the
+compiler moves. Keep the compiler version, target and argument format with any artifact you store.
+[Verification](../guides/verification.md) covers the settlement pins the SDK ships.