@eco-incorp/sauce 0.99.1 → 0.99.2

package/docs/api/README.md

@@ -0,0 +1,71 @@
+# API reference
+
+Install `@eco-incorp/sauce` and import through the package's public entry points. All paths below
+are suffixes of that package name; `.` means `@eco-incorp/sauce` itself.
+
+| Import                         | Contents                                                                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `.`                            | `routes`, `token`, `swap`, `deposit`, `contracts`, `svmVenues`; protocol and chain queries; installation of chain globals |
+| `/compiler`                    | `compile`, compiler types, `encodeCompactArguments`, and `decodeCompactArguments`                                         |
+| `/actions`                     | Action primitives and `actionsToSauce` composition                                                                        |
+| `/protocols/*`                 | One protocol's `protocolInfo`, `deployments`, ABI exports, and named SauceScript templates                                |
+| `/chains`                      | Canonical chain identities and EVM chain metadata                                                                         |
+| `/deployments`                 | Sauce engine/Kitchen addresses, Pot derivation inputs, and recorded deployment coverage                                   |
+| `/recipes`                     | EVM settlement source and CCTP/plain-transfer recipe builders and sources                                                 |
+| `/recipes/settle.sauce.ts`     | EVM settlement source asset                                                                                               |
+| `/svm`                         | SVM clients, account plans, resolution, staging, Kitchen instructions, recipes, and transactions                          |
+| `/svm/engine`                  | SVM engine wire format and instruction builders                                                                           |
+| `/svm/engine-artifacts`        | Node helpers locating packaged SVM engine/Kitchen binaries and IDL                                                        |
+| `/svm/verify`                  | SVM program and gated engine CPI verification; separate Kitchen decoding is required                                      |
+| `/svm/recipes/settle.sauce.ts` | SVM settlement source asset                                                                                               |
+| `/evm/engine`                  | EVM Pot and Kitchen ABIs and call encoders (`v12PotAbi`, `v12KitchenAbi`, `v12Pot`, `v12Kitchen`)                         |
+| `/verify`                      | EVM settlement encoding, structural decoding, and validation against the pinned program                                   |
+| `/skills`                      | Protocol Markdown index and skill-file loaders                                                                            |
+
+The [`exports` map](../../package.json) defines this list. There is no `/routes`, `/token`,
+`/swap`, `/deposit`, or `/contracts` subpath; import these namespaces from the root:
+
+```ts
+import { routes, token, contracts } from "@eco-incorp/sauce";
+import { compile } from "@eco-incorp/sauce/compiler";
+```
+
+`Base`, `Solana`, `chain`, and `Token` are installed globals, rather than named root exports.
+Bare protocol and token globals such as `Uniswap` and `USDC` describe compiled route source and
+have no corresponding host JavaScript objects. See
+[protocols and tokens](../guides/protocols-and-tokens.md).
+
+## Detailed references
+
+- [Compiler](compiler.md): direct compilation, result metadata, compact argument encoding.
+- [Routes](routes.md): compile options, intent construction, nested execution, and submission helpers.
+- [Coverage](coverage.md): distinguish catalog entries, callable descriptors, and available deployments.
+
+For structured program creation, see [builders and actions](../guides/builders-and-actions.md).
+For account-based execution and settlement checks, see the [Solana](../guides/solana.md) and
+[verification](../guides/verification.md) guides.
+
+## Protocol resources
+
+```ts
+import { getProtocol, getProtocolsByChain, listProtocols } from "@eco-incorp/sauce";
+import { PoolABI } from "@eco-incorp/sauce/protocols/aave-v3";
+import { getProtocolIndex, getProtocolSkill, listSkillSlugs } from "@eco-incorp/sauce/skills";
+
+const baseProtocols = getProtocolsByChain(8453);
+const aave = getProtocol("aave-v3");
+const protocols = listProtocols();
+const indexMarkdown = getProtocolIndex();
+const aaveMarkdown = getProtocolSkill("aave-v3");
+const availableSkills = listSkillSlugs();
+```
+
+Skill resources are documentation strings; loading one performs no protocol operation.
+`getProtocolSkill` throws for a slug absent from `listSkillSlugs()`.
+
+## Runtime requirements
+
+The root SDK, its route compiler integration, recipe source loaders, skill loaders, and artifact
+resolvers use Node.js APIs. `/verify` has a `viem`-only dependency closure and can validate EVM
+settlement payloads in a browser without loading the compiler. See the
+[compiler reference](compiler.md) for the compiler dependency's separate browser entry point.

package/docs/api/compiler.md

@@ -0,0 +1,234 @@
+# Compiler API
+
+[Documentation](../README.md) · [Compiling programs](../guides/compiling.md)
+
+`@eco-incorp/sauce/compiler` exposes the published Rust/WASM compiler to Node
+consumers and supplies the SDK's compact argument codec.
+
+```ts
+import {
+  compile,
+  encodeCompactArguments,
+  decodeCompactArguments,
+  type CompileOptions,
+  type CompileResult,
+} from "@eco-incorp/sauce/compiler";
+```
+
+The compiler is installed with the SDK. This reference and its examples are
+validated with `@eco-incorp/sauce-compiler` **2.3.0**.
+
+## `compile(options): CompileResult`
+
+Compilation is synchronous. The host supplies source and dependency bytes through
+callbacks; the compiler does not fetch a filesystem path or network URL itself.
+
+```ts
+const source = new TextEncoder().encode(`
+  function main(amount: Uint256): Uint256 {
+    return amount + 1n;
+  }
+`);
+
+const artifact = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve: (path) => (path === "main.ts" ? source : undefined),
+});
+
+console.log(artifact.bytecode, artifact.isaRevision, artifact.entryEncoding);
+```
+
+### Options
+
+| Field             | Type                                                   | Meaning                                                                |
+| ----------------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `target`          | `"evm" \| "svm"`                                       | Required target runtime                                                |
+| `resolve`         | `(path: string) => Uint8Array \| undefined \| null`    | Required synchronous module/JSON resolver                              |
+| `entry`           | `string`                                               | Entry module; default `"main.js"`                                      |
+| `resolvePackage`  | `(specifier, importer) => string \| undefined \| null` | Map a bare package specifier to a path understood by `resolve`         |
+| `contracts`       | `[name, path][]`                                       | Register entry-module ABI bindings by resolver path                    |
+| `inlineContracts` | `[name, abiJson][]`                                    | Register entry-module ABI bindings from JSON strings                   |
+| `ambient`         | `string[]`                                             | Resolve libraries and broadcast their exports into every module        |
+| `defines`         | `[name, value][]`                                      | Program-wide scalar compile-time constants; values are integer strings |
+| `optimize`        | `boolean`                                              | Enable compiler optimizations; default `true`                          |
+| `compactArgs`     | `boolean`                                              | Use compact-v1 entry arguments; default `false`                        |
+| `cache`           | `boolean`                                              | Enable the per-function lowering cache; default `true`                 |
+
+`optimize: false` disables optimizations such as constant folding, loop unrolling,
+common-subexpression elimination, and helper inlining. Validation still runs.
+
+`defines` accepts decimal or `0x` integer strings, with supported literal
+separators and an optional trailing `n`. Use strings so the JavaScript host does
+not round 256-bit values. A repeated name is an error. A define replaces a
+module's same-named `const`; incompatible declarations, such as a module-level
+`let` or a function, are errors. Function-local declarations can shadow it.
+
+An ambient export yields to a module's own declarations, imports, and bindings.
+Two ambient modules exporting the same name are an error. Ambient libraries must
+be resolvable SauceScript modules and cannot supply an entry `main`.
+
+### Resolver contract
+
+Return bytes for an existing module. Return `undefined` or `null` for a missing
+candidate; this lets resolution try a neutral module when a target-specific arm
+does not exist. Throw when resolving an existing resource fails and compilation
+must stop. The compiler propagates that failure rather than treating it as a
+missing arm.
+
+Paths can retain `./`, and dependencies are resolved in the importing module's
+context. An in-memory map must serve the paths actually requested. A filesystem
+resolver can resolve candidates relative to a known root. Serve JSON bytes as
+well as source bytes: bare JSON imports denote ABIs, while
+`with { type: "json" }` imports JSON data.
+
+For a package with a neutral entry such as `token.js`, resolution can probe
+`token.evm.js` or `token.svm.js` according to the target. Supply the neutral
+specifier and let the compiler select the arm.
+
+### Result
+
+```ts
+interface CompileResult {
+  bytecode: Uint8Array;
+  isaRevision: "stack-compact-v2";
+  entryEncoding: "abi-v1" | "compact-v1";
+  entrySchema?: Uint8Array;
+  manifest?: AccountManifest;
+}
+```
+
+- `bytecode` is one reusable program. Per-execution argument values have not been
+  appended.
+- `isaRevision` identifies the compiler's instruction-set contract. It does not
+  check which runtime is deployed at an address.
+- `entryEncoding` selects the argument encoder: ordinary ABI arguments by
+  default, compact arguments when `compactArgs: true`. It does not describe
+  [program return encoding](../guides/compiling.md#encode-evm-return-values).
+- `entrySchema` describes compact argument structure. Pass this exact schema to
+  the compact codec; do not infer or rebuild it from example bytes.
+- `manifest` is present for SVM and describes attached accounts. It is absent
+  for EVM.
+
+Compilation and resolution failures throw a JavaScript `Error`. Source diagnostics
+include a location and span; option, resolver, and target-capability errors may
+have neither. A resolver callback's thrown message is preserved. There is no
+success-with-error result or warning array in this API.
+
+### SVM account manifest
+
+`AccountManifest.accounts` contains these entries:
+
+```ts
+type AccountEntry =
+  | {
+      kind: "slot";
+      index: number;
+      name: string;
+      requires: "readonly" | "writable" | "readonly_signer" | "writable_signer";
+    }
+  | { kind: "remaining"; from: number };
+```
+
+Slots correspond to `main`'s `Account` parameters. Their roles are declarations
+made by the author, not permissions inferred by examining a CPI callee. A
+`remaining` entry marks the start of the variable account tail when the source
+uses it. SVM `Account` parameters do not occupy compact argument fields.
+
+The subpath also exports `AccountEntry`, `AccountManifest`, `AccountRole`,
+`CompileOptions`, `CompileResult`, `ResolveModule`, `ResolvePackage`, and
+`SauceTarget` as types from the compiler package.
+
+## Compact argument codec
+
+```ts
+encodeCompactArguments(schema: Uint8Array, value: CompactValue): Uint8Array;
+
+decodeCompactArguments(
+  schema: Uint8Array,
+  data: Uint8Array,
+  options?: { maxValues?: number },
+): CompactValue;
+```
+
+`CompactValue` accepts `bigint`, safe integer `number`, `boolean`, integer or hex
+`string`, `Uint8Array`, and recursively nested positional arrays.
+
+For a compiled entry, the root value is an array containing its arguments in
+declaration order. Omit `Account` parameters only on SVM, where accounts are
+attached separately; EVM `Account` parameters are encoded as scalars. For
+`main(account: Account, amount: Uint256)`, pass `[account, amount]` on EVM and
+`[amount]` on SVM. Nested records are positional arrays too.
+`bytes` values accept a `Uint8Array` or an even-length `0x` hex string. Scalar
+addresses/public keys are integers or hexadecimal integers; base58 public-key
+text is not a scalar encoding.
+
+The encoder emits compact-v1 data beginning with `53 41 01 00`, minimum-width
+256-bit scalars, canonical booleans, unpadded bytes, and big-endian collection
+lengths. Negative integers preserve their 256-bit two's-complement bit pattern.
+The decoder returns scalar words as unsigned `bigint`, booleans as `boolean`,
+bytes as `Uint8Array`, and collections as arrays. It does not recover a signed
+application type from a scalar word.
+
+The decoder rejects non-minimal scalars, non-canonical booleans, malformed or
+truncated lengths, and trailing data. `maxValues` bounds its decoded value graph
+and defaults to `1_000_000`. Schemas are limited to 65,535 bytes and 32 nested
+levels. The engine applies its own heap and execution limits as well; successful
+host encoding does not establish that a payload fits a transaction or runtime.
+
+Compact-v1 changes **program entry arguments**. EVM contract calls made by the
+program still use their contract ABIs. The SDK's canonical EVM settlement verifier
+currently expects its pinned ABI-v1 settlement payload, not a compact recompile.
+
+## Raw compiler versus route compilation
+
+`routes.compileSauceRoute()` is a separate SDK API with a source string,
+destination, execution settings, and `SauceCompileOptions`. It supplies registry
+rewrites and call encoding. Its result is:
+
+```ts
+{
+  calls: readonly CallInput[];
+  compiled: { bytecode: Uint8Array[]; warnings: string[] };
+  source: string;
+}
+```
+
+There is one compiled segment and one route call. `source` is the SDK-rewritten
+program; the internal compiler adapter can additionally annotate a falling-through
+`main` as `void`. `warnings` is currently empty: compilation failures throw.
+
+The route adapter does not return the raw compiler's ISA metadata, entry schema,
+or SVM manifest, and its options do not expose `compactArgs`, `cache`, or
+`optimize`. Use raw `compile()` when you need those fields, explicit runtime
+parameters, or the compiler's full resolver control. Route `target: "v1"` is a
+compatibility spelling mapped to the same EVM backend as `"v12"`.
+
+See [routes](routes.md) for the route-specific API.
+
+## Node, browsers, and compiler-only features
+
+The SDK requires Node **24 or newer**. Its `/compiler` export loads the compiler
+through Node's `createRequire`; SDK route compilation also uses filesystem and
+path APIs. These integrations are Node APIs.
+
+The underlying compiler package separately supplies Node and browser builds.
+For a browser application, install `@eco-incorp/sauce-compiler` directly and use
+its initialization API:
+
+```ts
+import { ready } from "@eco-incorp/sauce-compiler/ready";
+
+const { compile } = await ready();
+// Supply source/dependencies through synchronous in-memory resolvers.
+```
+
+`ready()` initializes the browser WASM build and is a no-op for the already
+initialized Node build. Arrange for the compiler's WASM asset and dependency
+bytes to be available before compiling. This does not provide the SDK's route
+rewrites or registry resolver in a browser.
+
+The compiler package also exports `clearFunctionCache()` and
+`functionCacheStats()`. The SDK `/compiler` barrel does not re-export them or
+`ready()`. Applications using these compiler-only exports should declare the
+compiler as a direct dependency and import from its published package name.

package/docs/api/coverage.md

@@ -0,0 +1,117 @@
+# Registry and global namespace coverage
+
+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.
+
+| Registry                         | Current scope                                                                     | Inspect it                                                             |
+| -------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Protocol catalog                 | 129 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()`                           |
+
+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.
+
+## Protocol globals
+
+These names are available inside compiled EVM route bodies. Availability on the destination chain
+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.
+
+Family aliases are `Uniswap`, `Sushiswap`, `Pancakeswap`, `Aave`, and `Compound`. A family exposes
+a contract only when exactly one member owns its name. Consequently:
+
+- `Uniswap.UniversalRouter` resolves to `UniswapV4.UniversalRouter`.
+- `Uniswap.Factory` is ambiguous; use a versioned namespace.
+- `UniswapV3.UniversalRouter` is absent from this registry.
+- A family always requires a contract name, even when it has one protocol member.
+
+A protocol with exactly one callable contract also supports a shortcut such as
+`Cctp.depositForBurn(...)` or `AaveV3.supply(...)`. See
+[protocols and tokens](../guides/protocols-and-tokens.md) for argument conventions and examples.
+
+The four remaining descriptors are available for host-side discovery: `AaveV3.PoolAddressesProvider`
+and `MorphoBlue.Bundler3` have addresses but no vendored ABI; `Erc20.ERC20` and
+`Erc4626.ERC4626Vault` are unbound interfaces. They are excluded from source globals. Use
+`Token(address)` for route-body ERC-20 calls or supply a contract ABI directly to the compiler.
+
+## Tokens
+
+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`         |
+
+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`
+can override or add a chain-local mapping. Amounts are integer token units; the compiler does not
+apply decimal scaling.
+
+```ts
+import { requireChain, routes } from "@eco-incorp/sauce";
+
+const base = requireChain("base");
+routes.knownTokenSymbols(base); // ["USDC", "WETH"]
+routes.registryTokenAddress(base, "USDC"); // bigint address, or undefined if absent
+```
+
+These ERC-20 source globals target EVM. Use the [Solana account and token helpers](../guides/solana.md)
+for SPL tokens.
+
+## Host discovery and chain coverage
+
+```ts
+import { contracts } from "@eco-incorp/sauce";
+
+const router = contracts.on("base").Uniswap.UniversalRouter;
+router.available;
+router.address;
+router.methods;
+router.coverage;
+
+const resolved = contracts.describeContract("base", "uniswap-v4", "UniversalRouter");
+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.

package/docs/api/routes.md

@@ -0,0 +1,110 @@
+# Routes API
+
+[Documentation](../README.md) · [Create an intent](../guides/intents.md) · [Compiler](compiler.md)
+
+Import the routes namespace from the package root:
+
+```ts
+import { 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.
+
+## Chain entry points
+
+| Entry point                            | Result                                            |
+| -------------------------------------- | ------------------------------------------------- |
+| `Base(body, options)`                  | Pending destination route awaiting `.reward(...)` |
+| `Base.route(body, options)`            | Same behavior as the callable chain               |
+| `routes.chain(ref)`                    | Chain route entry point for a chain reference     |
+| `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.
+
+`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).
+
+`.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.
+
+The compiler needs no source reward to compile a destination program. Use `compileSauceRoute` when you only need destination calls.
+
+## Compile a destination route
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+
+export function compileProgram(execution: routes.SauceEvmExecutionInput) {
+  return routes.compileSauceRoute("base", "return 7n;", execution);
+}
+```
+
+`compileSauceRoute(destination, source, execution, options?)` returns:
+
+| Field      | Contents                                                              |
+| ---------- | --------------------------------------------------------------------- |
+| `calls`    | Destination call inputs, normally one call for one program            |
+| `compiled` | Route compatibility result with `bytecode: Uint8Array[]` and warnings |
+| `source`   | Source after wrapping and SDK token/protocol rewrites                 |
+
+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.
+
+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).
+
+## Already compiled programs
+
+`buildSauceEvmCall({ pot, engine, program, value? })` builds one Pot `cook` call; `program` is a hex string. `value` defaults to zero and must include the Kitchen fee. `buildSauceEvmCalls({ pot, engine, cooks, value? })` applies that value to **each** ordered cook. Multiple statements within one program need only one cook and fee.
+
+## 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.
+
+`buildSauceSvmCall` and the SVM route path emit a legacy 8-byte staged-engine instruction, which is **incompatible with engine 1.0.1** 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).
+
+## Built intents
+
+| Member                                      | Behavior                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------- |
+| `intent`, `root()`                          | Normalized head intent                                              |
+| `source`, `destination`                     | Canonical chain records                                             |
+| `compiled`                                  | Head destination program's compilation result                       |
+| `children`                                  | Direct nested children                                              |
+| `intents()`                                 | Root-first preorder traversal of all intents                        |
+| `hash()`                                    | Intent, route, and reward hashes                                    |
+| `encodeEVM()`, `encodeSVM()`                | Explicit codec serialization of route and reward                    |
+| `approvals()`                               | EVM approval requests for the head reward                           |
+| `publishCalldata()`                         | Source Portal publication request                                   |
+| `publishAndFundCalldata(allowPartial)`      | Publication and funding request                                     |
+| `fundCalldata(allowPartial)`                | Funding request                                                     |
+| `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.
+
+## Composition and lower-level encoding
+
+Call `.nest(childOrThunk, options?)` before `.reward(...)`. The fluent default is transfer funding after the parent program. [Nested intents](../guides/nested-intents.md) explains funding modes, deadlines, account custody, and execution ordering.
+
+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.