@eco-incorp/sauce 0.99.6 → 0.99.8

package/docs/README.md

@@ -8,6 +8,37 @@ tokens and protocols a program calls by name; you write the program, not a contr
 **Routes** are the layer above: a route packages a program as an Eco intent, so it can be executed
 on another chain in exchange for a reward escrowed on this one. Everything cross-chain lives there.
 
+## Supported chains
+
+For the initial release, Sauce supports transactions on three chains: **Ethereum**, **Base** and
+**Solana**.
+
+Every other chain in the registry is a **preview chain**. Programs compile for it, and the
+[`sauce` command](guides/cli.md#supported-and-preview-chains) and the
+[MCP server](guides/mcp.md#supported-and-preview-chains) rehearse and read there as anywhere:
+`sauce simulate`, `sauce intent publish --dry-run`, `sauce intent fill` without `--send`, and every
+read. What they do not do on a preview chain is build or send a transaction. `tx`, `run`,
+`pot --deploy` (and the deployment `pot` prints), `intent publish`, `intent fill --send`, `prove`,
+`claim`, `refund` and `cancel` are refused there before any endpoint is reached or any key is read,
+with the supported chains and a link to request the chain. An intent publishes only when its source
+and every destination it opens are supported; the later levels of a cascade (an intent opened inside
+another's body) are not checked, so keep every level on a supported chain. Each step after
+publishing is refused by the chain it is sent on: a fill, a proof or a cancellation by the
+destination, a claim or a refund by the source.
+
+The TypeScript SDK is not gated. Its builders take every registry chain and build its
+transactions, and an integrator who submits one on a preview chain does so at their own risk.
+The MCP server's `sauce_chains` gives each chain's support, and every refusal names the supported
+chains.
+
+To ask for a chain, first
+[search the existing requests](https://github.com/eco-incorp/sauce/issues?q=is%3Aissue+label%3Achain-support)
+and add your use case to the one for that chain as a comment. If there is none,
+[open a chain-support request](https://github.com/eco-incorp/sauce/issues/new?template=chain-support.yml):
+the chain and its id, what you want to run there, the protocols and tokens it needs, the volume you
+expect and from when, and optionally how to reach you. A refusal links both, prefilled for the chain
+it refused.
+
 ## First program in five minutes
 
 1. [Install](guides/quick-start.md) the package. The compiler is inside it.
@@ -29,6 +60,10 @@ Complete programs live in the [examples](examples/README.md).
 | Construct, fund, submit and inspect an intent                   | [Create an intent](guides/intents.md)                  |
 | Chain intents — statically, or from an amount measured on chain | [Nested intents](guides/nested-intents.md)             |
 | Compile a standalone program and pass it runtime arguments      | [Compiling programs](guides/compiling.md)              |
+| Compile and run a program file from a terminal                  | [The sauce command](guides/cli.md)                     |
+| Have a coding agent write and run programs                      | [Agent skills](guides/cli.md#agent-skills)             |
+| Give a coding agent Sauce's tools and skills over MCP           | [The MCP server](guides/mcp.md)                        |
+| Give an agent a wallet of its own, with a policy that limits it | [Agent wallets](guides/cli.md#agent-wallets)           |
 | Generate programs from structured data                          | [Builders](guides/builders-and-actions.md)             |
 | Write protocol actions as JSON, then run them or make an intent | [Actions](guides/actions.md)                           |
 | Plan accounts, stage code and execute on Solana                 | [Solana](guides/solana.md)                             |
@@ -45,6 +80,9 @@ Complete programs live in the [examples](examples/README.md).
 
 - [API entry points](api/README.md) — every published import and what it contains.
 - [Routes](api/routes.md) — chain entry points, intent options, built intents, nesting.
+- [Contracts and tokens](api/contracts.md) — every protocol namespace and token, in a program and in TypeScript.
+- [SauceScript reference](../skills/sauce-script/references/builtins.md) — every type, builtin, statement and limit, per target.
 - [Compiler](api/compiler.md) — `compile()` options and result, and the compact argument codec.
+- [`@sauce/router`](api/router.md) — the SauceScript swap library: one function per venue.
 - [Coverage](api/coverage.md) — which protocols, tokens and chains are actually registered.
 - [Examples](examples/README.md) — complete programs, and how they are kept working.

package/docs/api/README.md

@@ -3,27 +3,28 @@
 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                                                                                                                                   |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.`                            | Chain accessors (`Base`, `Solana`, …); `routes`, `token`, `swap`, `deposit`, `contracts`, `svmVenues`; protocol and chain queries; `ready` |
-| `/compiler`                    | `compile`, `ready`, compiler types, the compact codec, and `resolveSdkModule`/`resolveSdkPackage`                                          |
-| `/actions`                     | JSON action programs: validation, compilation and intents; the JSON Schema is `/actions/action-program.schema.json`                        |
-| `/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-only 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                                                                                             |
+| Import                         | Contents                                                                                                                                                                            |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`                            | Chain accessors (`Base`, `Solana`, …); `routes`, `token`, `deposit`, `contracts`, `svmVenues`; protocol and chain queries; `sqrtPriceX96FromPrice`/`priceFromSqrtPriceX96`; `ready` |
+| `/compiler`                    | `compile`, `ready`, compiler types, the compact codec, and `resolveSdkModule`/`resolveSdkPackage`                                                                                   |
+| `/actions`                     | JSON action programs by names and pool keys: validation, compilation for a chain, and intents; the JSON Schema is `/actions/action-program.schema.json`                             |
+| `/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 which engine runs which compiler's programs                                                                              |
+| `/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-only 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`), and `potRouterUpdate`                                                            |
+| `/verify`                      | EVM settlement encoding, structural decoding, and validation against the pinned program                                                                                             |
+| `/skills`                      | The per-protocol documents (the `sauce-protocols` agent skill's references) and their index, as text                                                                                |
+| `/sauce-script`                | Types only: SauceScript's builtins, chains and ABI modules, for an editor checking `*.sauce.ts` programs ([In an editor](../guides/cli.md#in-an-editor))                            |
 
 The [`exports` map](../../package.json) defines this list. There is no `/routes`, `/token`,
-`/swap`, `/deposit`, or `/contracts` subpath; import these namespaces from the root:
+`/deposit`, or `/contracts` subpath; import these namespaces from the root:
 
 ```ts
 import { routes, token, contracts } from "@eco-incorp/sauce";
@@ -35,13 +36,21 @@ Importing the package puts nothing on `globalThis`. `chain(ref)` and the host `T
 named exports too.
 
 Bare names such as `USDC` and `Uniswap` are different: they are _program syntax_, resolved by the
-compiler inside a route body, with no host JavaScript object behind them. See
+compiler inside a route body, with no host JavaScript object behind them. The same registry entries
+are on the chain export in TypeScript (`Base.USDC`, `Base.Uniswap`). See
 [protocols and tokens](../guides/protocols-and-tokens.md).
 
 ## Detailed references
 
+- [SauceScript reference](../../skills/sauce-script/references/builtins.md): every type, operator,
+  statement, builtin and limit, per target, checked against the compiler;
+  [`builtins.json`](../../skills/sauce-script/references/builtins.json) lists the builtins with an
+  example program each. It is the `sauce-script` agent skill's reference, shipped in the package.
 - [Compiler](compiler.md): direct compilation, result metadata, compact argument encoding.
+- [`@sauce/router`](router.md): the SauceScript swap library a program imports — one function per
+  venue.
 - [Routes](routes.md): compile options, intent construction, nested execution, and submission helpers.
+- [Contracts and tokens](contracts.md): every protocol namespace and token, in a program and in TypeScript, and running a call through viem.
 - [Coverage](coverage.md): distinguish catalog entries, callable descriptors, and available deployments.
 
 For programs assembled from data rather than written, see [builders](../guides/builders-and-actions.md).
@@ -63,14 +72,19 @@ const aaveMarkdown = getProtocolSkill("aave-v3");
 const availableSkills = listSkillSlugs();
 ```
 
-Skill files are Markdown written for AI coding assistants; loading one reads a document and
-performs no protocol operation. `getProtocolSkill` throws for a slug absent from `listSkillSlugs()`.
+Each document is Markdown written for coding agents; loading one reads a document and performs no
+protocol operation. `getProtocolSkill` throws for a slug absent from `listSkillSlugs()`. The
+documents are the `sauce-protocols` agent skill's references
+([`skills/sauce-protocols/references/`](../../skills/sauce-protocols/references/index.md)), the same
+files `sauce skills install` puts in a project ([Agent skills](../guides/cli.md#agent-skills)), so the
+text this export returns is the text an agent reads.
 
 ## Where each import runs
 
 Every import runs in Node **24 or newer** and in a browser, with one exception:
 `/svm/engine-artifacts` returns filesystem paths to the packaged engine binaries for a local
-LiteSVM harness, and is Node-only.
+LiteSVM harness, and is Node-only. The [`sauce` command](../guides/cli.md) is not an import at
+all: it is the package's executable, and Node-only too.
 
 Anything that compiles — `/compiler`, route compilation, the builders, the recipes, `/actions`,
 `/svm/verify` — needs one `await ready()` first in a browser, while the compiler's WebAssembly

package/docs/api/compiler.md

@@ -19,9 +19,11 @@ import {
 } from "@eco-incorp/sauce/compiler";
 ```
 
-This SDK pins compiler **2.4.0**, EVM engine and Kitchen **1.1.0**, SVM engine **1.3.0**,
-and SVM Kitchen **1.0.0**. Release addresses identify this compatible set; they do not
-confirm it has been deployed on a chain. Check deployment readiness before using it live.
+This SDK pins one compiler and the four v12 releases its output runs on: the EVM
+engine and Kitchen, and the SVM engine and Kitchen. `v12ReleaseSet()` names them —
+see [Which engine runs a program](#which-engine-runs-a-program). Release addresses
+identify this compatible set; they do not confirm it has been deployed on a chain.
+Check deployment readiness before using it live.
 
 Every example here is checked against the compiler version this package ships.
 
@@ -96,10 +98,11 @@ specifier and let the compiler select the arm.
 ### The SDK's own modules
 
 `resolveSdkModule(path)` and `resolveSdkPackage(specifier)` serve the files the SDK
-ships, from memory, with the contracts above: the `@sauce/token` library, the
-`./artifacts/IERC20.json` and `./artifacts/ISauceRouter.json` ABIs, and every protocol
-ABI as `./protocols/<slug>/<Export>.json`. Fall back to them from your own resolver
-to compile a program the SDK's builders emit, or one that imports `@sauce/token`:
+ships, from memory, with the contracts above: the `@sauce/token` and
+[`@sauce/router`](router.md) libraries, the `./artifacts/IERC20.json` and
+`./artifacts/ISauceRouter.json` ABIs, and every protocol ABI as
+`./protocols/<slug>/<Export>.json`. Fall back to them from your own resolver to compile
+a program the SDK's builders emit, or one that imports either library:
 
 ```ts
 const entry = new TextEncoder().encode(`
@@ -131,11 +134,15 @@ interface CompileResult {
 
 - `bytecode` is one reusable program. Per-execution argument values have not been
   appended.
-- `isaRevision` labels the instruction set this artifact was built for. Record it
-  with the artifact and run the program on an engine built for the same one; it is
-  a label, not a check against any deployed address.
-- `entryEncoding` selects the argument encoder: ordinary ABI arguments by
-  default, compact arguments when `compactArgs: true`. It does not describe
+- `isaRevision` labels the instruction set this artifact was built for. It is a
+  label, not a compatibility check: two engine releases can report the same
+  revision while only one of them runs a given compiler's output. Pair a program
+  with an engine by exact package version — see
+  [Which engine runs a program](#which-engine-runs-a-program).
+- `entryEncoding` selects the argument encoder: ABI arguments by default, with
+  every tuple parameter behind an offset
+  ([Pass arguments with ABI-v1](../guides/compiling.md#pass-arguments-with-abi-v1)),
+  compact arguments when `compactArgs: true`. It does not describe
   [program return encoding](../guides/compiling.md#return-values-an-abi-decoder-can-read).
 - `entrySchema` describes compact argument structure. Pass this exact schema to
   the compact codec; do not infer or rebuild it from example bytes.
@@ -171,6 +178,40 @@ The subpath also exports `AccountEntry`, `AccountManifest`, `AccountRole`,
 `CompileOptions`, `CompileResult`, `ResolveModule`, `ResolvePackage`, and
 `SauceTarget` as types from the compiler package.
 
+### Which engine runs a program
+
+Compiler output and v12 engines pair by exact package version, in both
+directions: a compiler's programs run only on the engine releases its row names,
+and an engine runs only the output of the compiler its row names. A new compiler
+release can change the instructions it emits for the same source, so an engine
+from an earlier row can misread its programs, and an earlier compiler's programs
+can fail on a newer engine. `V12_RELEASE_SETS` (from
+`@eco-incorp/sauce/deployments`) holds one row per compiler version: the four v12
+releases that compiler pairs with, each asset's digest, and each engine's
+address or program id. The SDK pins one compiler and ships the engines of that
+compiler's row, so `v12EngineAddress()` and `v12SvmEngineProgramId()` always
+name engines that run the SDK's own programs.
+
+Every SDK builder that names an engine — `v12Pot.encodeCook`,
+`routes.buildSauceEvmCall`, the SVM engine instructions and the Kitchen cook
+instructions — calls `assertEngineRunsCompiler(target, engine)` first. It throws
+for an engine a release set names for another compiler, saying which engine
+this compiler's output needs instead. An engine no release set names, such as
+one you deployed yourself, is not refused: the SDK cannot tell what it is.
+
+```ts
+import { assertEngineRunsCompiler, v12ReleaseSet } from "@eco-incorp/sauce/deployments";
+
+const set = v12ReleaseSet(); // this SDK's compiler and the four releases it pairs with
+console.log(set.compiler, set["v12-evm"].version, set["v12-svm"].version);
+assertEngineRunsCompiler("evm", set["v12-evm"].engine!); // passes: the pinned engine
+```
+
+`v12ReleaseSet(compiler)` returns another compiler's row, and throws for a
+compiler no row pairs with. When you run programs from a different compiler
+version than the SDK's, pass that version as the third argument:
+`assertEngineRunsCompiler("evm", engine, compiler)`.
+
 ## Compact argument codec
 
 ```ts

package/docs/api/contracts.md

@@ -0,0 +1,105 @@
+# Contracts and tokens API
+
+[API reference](README.md) · [Protocols and tokens](../guides/protocols-and-tokens.md) · [Coverage](coverage.md)
+
+Every registry protocol is a namespace and every registered token a name, with the same names in a
+program and in TypeScript. This page lists both surfaces; the
+[guide](../guides/protocols-and-tokens.md) shows them in use.
+
+| Registry entry             | In a program                                    | In TypeScript                                        |
+| -------------------------- | ----------------------------------------------- | ---------------------------------------------------- |
+| A token                    | `USDC`                                          | `Base.USDC`                                          |
+| A deployed contract        | `UniswapV3.QuoterV2`                            | `Base.UniswapV3.QuoterV2`                            |
+| Its method                 | `UniswapV3.QuoterV2.quoteExactInputSingle(...)` | `Base.UniswapV3.QuoterV2.quoteExactInputSingle(...)` |
+| The ABI at another address | `UniswapV3.Factory.at(address).getPool(...)`    | `Base.UniswapV3.Factory.at(address).getPool(...)`    |
+| An interface               | `Erc4626.Vault(vault).deposit(...)`             | `Base.Erc4626.Vault.at(vault).deposit(...)`          |
+| A family alias             | `Uniswap.UniversalRouter`                       | `Base.Uniswap.UniversalRouter`                       |
+| Another chain's address    | `Arbitrum.UniswapV3.Factory`                    | `Arbitrum.UniswapV3.Factory`                         |
+| Whether the chain has it   | `available(UniswapV3.Factory)`                  | `Base.UniswapV3.Factory.available`                   |
+
+## Names
+
+- A namespace is the protocol's registry slug in PascalCase (`aerodrome-slipstream` →
+  `AerodromeSlipstream`).
+- A deployed contract, and an address-only one, is named by its role in the protocol's
+  `addresses.ts`, first letter upper-cased, keeping its ABI name's spelling of the role's leading
+  words (`clFactory` under `SlipstreamCLFactoryABI` → `CLFactory`).
+- An interface is named by its ABI export without `ABI` and the protocol's prefix
+  (`contracts.deriveContractName`), as is a role that runs different ABIs on different chains.
+- A slug ending in `-v<N>` also joins the family `PascalOf(<rest>)`. A family carries a contract
+  only where exactly one member has one by that name; an ambiguous name is absent from its type and
+  throws when read.
+- No protocol, family, token or venue name can collide with a chain export's own `route`, `chain`,
+  or a function property: composing the export refuses it.
+
+## TypeScript: chain exports
+
+`import { Base } from "@eco-incorp/sauce"` — one export per canonical chain — carries:
+
+| Property               | What it is                                                                                                                                                                                            |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Base(body, options)`  | Opens an intent on Base; see [routes](routes.md#chain-entry-points)                                                                                                                                   |
+| `Base.chain`, `.route` | The chain record, and the same intent entry point                                                                                                                                                     |
+| `Base.<Symbol>`        | A registry token: a frozen `{ address, decimals, symbol, chain }` (`routes.RegistryToken`); on `Solana`, a registered mint, its `address` the mint's 32-byte key as hex and `mint` its base58 address |
+| `Base.<Namespace>`     | A protocol or family namespace, typed by the generated `contracts.ChainContracts`                                                                                                                     |
+
+A chain's token properties are exactly its registry rows, and the type names only those: `Base.USDT`
+is a type error and `undefined`. `routes.registryTokens(chain)` returns the same objects for a
+chain chosen at run time, and `contracts.on(ref)` the same namespace tree.
+
+## TypeScript: a contract
+
+| Member              | Type                                  | Meaning                                                                            |
+| ------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
+| `address`           | `` `0x${string}` `` or `undefined`    | The deployment on this chain; `undefined` where there is none, or for an interface |
+| `available`         | `boolean`                             | Whether `address` is set                                                           |
+| `chains`            | `ChainSlug[]`                         | Every chain the registry has an address for                                        |
+| `abi`, `methods`    | the ABI, `DescriptorMethod[]`         | What the registry declares, with signatures and selectors                          |
+| `coverage`          | `ContractCoverage`                    | `caveats`: deployments that differ from the ABI, from the registry's evidence      |
+| `descriptor`        | `ContractDescriptor`                  | The chain-independent registry entry                                               |
+| `at(address)`       | the same contract, bound to `address` | Required before an interface's methods                                             |
+| `<method>(...args)` | `ContractCall`                        | One per ABI function, arguments typed by viem from the ABI                         |
+
+An address-only contract (`contracts.AddressOnlyContract`) has no methods, and an interface
+(`contracts.InterfaceContract`) has them only after `.at(address)`. Calling a method of a contract
+with no deployment on the chain throws, naming the chains that have one.
+
+## TypeScript: a call
+
+A `ContractCall` is built synchronously and reads nothing.
+
+| Member                      | Meaning                                                                                                    |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `chain`, `address`          | Where it calls                                                                                             |
+| `protocol`, `contract`      | The registry entry                                                                                         |
+| `method`, `args`            | The ABI method (the overload, by argument count) and the arguments                                         |
+| `data`, `encode(options?)`  | The calldata                                                                                               |
+| `toCall(options?)`          | `{ target, data, value }`                                                                                  |
+| `toSauceScript(options?)`   | The same call as a program, with its ABI import                                                            |
+| `read(client)`              | An `eth_call` through viem's `readContract`, resolving to the decoded outputs; sends nothing               |
+| `simulate(client, options)` | `simulateContract` as `options.account`, with `options.value`; resolves to `{ result, request }`           |
+| `write(client, options?)`   | `writeContract` from `options.account` or the client's account, with `options.value`; resolves to the hash |
+
+`read` exists on every call: a view's value, or what a state-changing method would return. `simulate`
+and `write` exist on a state-changing method's call only, and throw on a view or pure one. All three
+take a viem client the caller creates; the SDK embeds no RPC endpoint. Each first checks that the
+client is on the call's chain — from `client.chain`, or by asking a client that has none for its
+chain id once — and refuses one on another chain. viem's actions are imported on the first call.
+
+## Programs
+
+In a program, a namespace member is a Sauce scalar: a deployed or address-only contract is its
+address on the chain the program is compiled for, a method call is an ABI call there, and
+`.at(address).method(...)` calls the same ABI at `address`. An interface, which has no address of its
+own, is called with one: `Erc4626.Vault(vault).deposit(...)` (`.at(vault)` too). A deployed
+contract's name is never called with an address. `<Chain>.<Namespace>.<Contract>` reads
+another chain's address, without moving execution there. A protocol with a single deployed
+contract also takes its methods directly (`Cctp.depositForBurn(...)`).
+
+`available(<contract or token symbol>)` is a compile-time `boolean`: whether the chain the program
+is compiled for has it. A branch it rules out is removed before anything in it resolves; see
+[use a venue only where the chain has it](../guides/protocols-and-tokens.md#use-a-venue-only-where-the-chain-has-it).
+
+The declarations a typed closure checks against, for every namespace, token and `available`, ship
+in the package root's types. The ERC-20 syntax for tokens is in the
+[guide](../guides/protocols-and-tokens.md#token-methods-and-balances).

package/docs/api/coverage.md

@@ -4,62 +4,54 @@ The SDK carries several registries, and they answer different questions. "Is thi
 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                 | 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                    | 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 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
-
-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`                                             |
-
-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:
+| Registry                         | Current scope                                                                  | Inspect it                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Protocol catalog                 | 135 protocols with metadata, deployments, ABI fragments, and program templates | `listProtocols()`, `getProtocol(slug)`, `getProtocolsByChain(id)`      |
+| Contract descriptors             | 316 descriptors across 135 protocol namespaces                                 | `contracts.listDescriptors()`, `contracts.listContracts(slug)`         |
+| Compiled-source protocol globals | The same 135 protocol namespaces, plus 13 family aliases                       | TypeScript completion after importing `@eco-incorp/sauce`; names below |
+| Token symbols                    | 1796 symbols distributed across 7 EVM chains, 1789 of them tokenized stocks    | `routes.TOKEN_REGISTRY`, `routes.knownTokenSymbols(chain)`             |
+| Solana mints                     | 1803 mints on mainnet-beta, 1799 of them tokenized stocks                      | `routes.SVM_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()`                           |
+
+Every catalog protocol is a namespace, in a program and in TypeScript: the descriptor registry is
+generated from the same binding of addresses to ABIs that the registry's ABI evidence is checked
+against, so a contract is exposed exactly as it is evidenced. `contracts.listDescriptors()` lists
+them and `contracts.listContracts(slug)` one protocol's.
+
+## Protocol namespaces
+
+A namespace is its protocol's slug in PascalCase, and every one has a contract per registered
+deployment role, plus its interfaces. The [contracts reference](contracts.md) has the naming rules
+and both surfaces.
+
+| Contract kind     | Count | What it is                                                                    |
+| ----------------- | ----- | ----------------------------------------------------------------------------- |
+| Deployed contract | 226   | An address per chain and a verified ABI: callable, and its address as a value |
+| Address only      | 51    | An address per chain with no verified ABI: usable as an address, no methods   |
+| Interface         | 39    | An ABI with no fixed address: called with one, `Erc4626.Vault(vault)`         |
+
+A name existing does not mean the contract is deployed on your chain: `available(...)` in a program
+and `.available` in TypeScript answer that, and naming an absent contract fails at compile or call
+construction, listing the chains that have it.
+
+Family aliases are `Aave`, `Balancer`, `Compound`, `Euler`, `Gmx`, `Liquity`, `Pancakeswap`,
+`Sushiswap`, `Synthetix`, `Synthra`, `Uniswap`, `Unitflow` and `Yearn`. 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.
+- `Uniswap.Factory` and `Pancakeswap.Factory` are 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.
+A protocol with exactly one deployed contract also supports a shortcut in programs, such as
+`Cctp.depositForBurn(...)` or `AaveV3.supply(...)`.
 
-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.
+Every registry ABI declares its contract's deployed types, so its selectors are the deployed ones,
+and is a subset of the contract's complete API. A `coverage.caveats` entry records a deployment the
+evidence shows differs from its ABI — a bridged token without the L1 token's functions, a function
+whose selector is checked but whose source is not verified. `compile.accessors.allowWidenedSelectors`
+is still accepted, and no shipped descriptor needs it.
 
 ## Tokens
 
@@ -78,6 +70,51 @@ The exported `routes.TOKEN_REGISTRY` contains:
 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).
 
+### Tokenized stocks
+
+Ethereum, Base and Solana also register tokenized stocks, which a program names by symbol like any
+other token (`SPCXc.balanceOf(ctx.self())` on Base, `balanceOf(TSLAx, account)` on Solana). Each list
+is copied from its issuer's own published list and every row is checked on chain; a stock row
+carries `stock`, its issuer, name and ticker:
+
+| Chain    | ID         | Issuer                            | Tokens | For example                     |
+| -------- | ---------- | --------------------------------- | ------ | ------------------------------- |
+| Ethereum | 1          | Backed (xStocks, and its bTokens) | 1280   | `TSLAx`, `SPCXx`, `bTSLA`       |
+| Ethereum | 1          | Ondo Global Markets               | 450    | `TSLAon`, `SPCXon`, `SPYon`     |
+| Ethereum | 1          | Mt Pelerin (its own shares)       | 1      | `MPS`                           |
+| Base     | 8453       | Coinbase                          | 58     | `TSLAc`, `SPCXc`, `NVDAc`       |
+| Base     | 8453       | Backed (its bTokens)              | 9      | `bTSLA`, `bNVDA`, `bCOIN`       |
+| Solana   | 1399811149 | Backed (xStocks)                  | 1271   | `TSLAx`, `SPCXx`, `BRK_Bx`      |
+| Solana   | 1399811149 | Ondo Global Markets               | 450    | `TSLAon`, `SPCXon`, `SPYon`     |
+| Solana   | 1399811149 | Backpack Securities               | 69     | `NVDA_US`, `SPCX_US`, `MSTR_US` |
+| Solana   | 1399811149 | PreStocks (private companies)     | 9      | `SPACEX`, `OPENAI`, `ANTHROPIC` |
+
+A stock's symbol is its issuer's ticker for the token, which is not always uppercase, with a `.`
+written `_` (`BRK.Bx` is `BRK_Bx`, Backpack's `NVDA.US` is `NVDA_US`); PreStocks' is the company's
+name (`SPACEX`). In a program and an actions document it is case-sensitive; the
+command line matches it without regard to case. `sauce globals --chain <chain>` counts a chain's
+stock tokens, `--stocks` lists them and `--search <text>` finds one by symbol, company name or
+ticker (`sauce_globals` takes `stocks` and `search` too, a page of 200 tokens at a time).
+
+Any contract, a Pot included, can hold and swap them: only minting and redeeming with the issuer
+need KYC. An issuer can pause its token or refuse a sanctioned address. Backed's tokens rebase: a
+balance changes between transactions, never within one, and a transfer can credit one unit less
+than sent, so paying one into a pool that checks what it received can fail. Ondo's keep their
+balance while dividends raise the shares each token stands for. Coinbase's are B20 tokens built into
+the Base node, so they run on Base but not in a local EVM such as anvil: `sauce simulate` against
+Base rehearses them, and `--assume-balance` cannot give one, since no state override reaches a B20
+balance.
+
+On Solana each is a Token-2022 mint, registered with `tokenProgram` set to Token-2022: the symbol is
+the mint's 32-byte key, and a program moves one with `@sauce/token`'s checked writes
+(`transferChecked`, `approveChecked`). Every row is checked on chain: owned by Token-2022,
+initialized, with its decimals and its issuer's symbol in its own metadata, and no transfer hook that
+names a program, which the token functions refuse. Amounts are raw; the issuer's multiplier (the
+scaled UI amount) is for display and moves for corporate actions. PreStocks' mints charge a transfer
+fee, so the recipient gets less than was sent: a program measures the balance change. Backpack lists
+mints it has not opened yet, which are left out, as are Superstate's, which only an allowlisted
+holder can hold.
+
 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
@@ -129,10 +166,13 @@ Arc (chain 5042) pays gas in USDC, and it has **one USDC balance with two decima
   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.
+- **A reward offers native value or `USDC`, not both.** Arc's eco-routes Portal treats the native
+  coin and the `USDC` ERC-20 as one asset, so an intent reward with a `nativeAmount` and a `USDC`
+  token leg reverts `RewardTokensNotUnique(USDC)` when it is published or funded. The SDK refuses
+  such a reward when it is built, before anything is signed: fold the two into one leg.
 
-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).
+An intent to Arc uses the same Portal, Executor and derived Pot as every other chain; see
+[One Portal, one Pot](../guides/intents.md#one-portal-one-pot).
 
 ## Host discovery and chain coverage
 
@@ -149,10 +189,9 @@ const resolved = contracts.describeContract("base", "uniswap-v4", "UniversalRout
 const onBase = contracts.contractsOnChain("base");
 ```
 
-Host accessors such as `Base.Uniswap.UniversalRouter` and `contracts.on(...)` build inert
-`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.
+Host accessors such as `Base.Uniswap.UniversalRouter` and `contracts.on(...)` build `ContractCall`
+objects when their methods are invoked, typed from the contract's ABI, and run them against a viem
+client you pass; see the [contracts reference](contracts.md).
 
 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,