@eco-incorp/sauce 0.99.6 → 0.99.7

package/docs/guides/solana.md

@@ -4,7 +4,7 @@
 
 Solana execution differs from EVM in one structural way, and everything on this page follows from it: **a Solana program must declare every account it touches, up front.** Those declarations are `Account` parameters on `main`, and the compiler returns them as an account manifest you resolve to real addresses before sending anything.
 
-Two consequences. The EVM name rewrites (`USDC.transfer(...)`, protocol members) do not apply here — there is no address to fold in without an account slot to put it in. And you want `@eco-incorp/sauce/compiler` directly: `routes.compileSauceRoute()` returns calls and bytecode but drops the manifest, which is the part you need.
+Two consequences. The EVM name rewrites (`USDC.transfer(...)`, protocol members) do not apply here — there is no address to fold in without an account slot to put it in. A registered token symbol is still a value: compiled for `solana` (`sauce compile --chain solana`, `routes.compileSauceProgram("solana", source)`), `USDC` is the mint's 32-byte key, which the `@sauce/token` functions take first (`balanceOf(USDC, account)`); `routes.SVM_TOKEN_REGISTRY` lists the mints, mainnet's and devnet's. And you want `@eco-incorp/sauce/compiler` directly: `routes.compileSauceRoute()` returns calls and bytecode but drops the manifest, which is the part you need.
 
 ## Compile an SPL transfer
 
@@ -36,15 +36,101 @@ export function compileSplTransfer(amount: bigint) {
 
 The account references are names, not addresses. `manifest.accounts` records their order and required roles. Resolve them to the mint, source token account, destination token account, authority, and token program before execution. Amounts are smallest-unit integers. The builder reads mint decimals for the checked instruction and defaults to the classic SPL Token program. Set the builder's top-level `tokenProgram: "token-2022"` for a supported Token-2022 operation; `svm.tokenProgram` names the account reference and must resolve to that token program.
 
-## Execute through the Kitchen
+## `@sauce/token` and Token-2022
 
-`createSauceSvmClient` requires an RPC URL, engine program ID, Kitchen program ID, and a Kit transaction signer. Its inline execution path constructs a Kitchen `cook`, includes the required heap-frame instruction, resolves accounts, and builds/signs transactions.
+A Solana mint belongs to one of two token programs, and so does every token account of it: the SPL Token program (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) or Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`). USDC and USDT are SPL Token mints; PYUSD (registered as `PYUSD`) and the tokenized stocks are Token-2022 mints. `@sauce/token`'s SVM arm takes both:
+
+- **Reads**, either program: `balanceOf(mint, account)`, `ownerOf(mint, account)`, `allowance(mint, account, spender)`, `totalSupply(mintAccount)`, `decimals(mintAccount)`. A Token-2022 account or mint is held to its base layout and, where it carries extensions, to its account-type byte.
+- **Checked writes**, either program: `transferChecked(mint, tokenProgram, source, mintAccount, dest, authority, amount, decimals)` and `approveChecked(mint, tokenProgram, source, mintAccount, delegate, authority, amount, decimals)`. `tokenProgram` must be one of the two and own the source, the destination and the mint; `mintAccount` must be `mint`; `decimals` must be the mint's.
+- **Legacy writes**, SPL Token only and unchanged: `transfer`, `transferFrom` and `approve`. Token-2022 refuses its plain transfer for a mint with a transfer fee, a transfer hook or a pause, so a program that moves a Token-2022 token uses `transferChecked`.
+
+What Token-2022's extensions do is the token program's: a transfer fee is withheld from what the destination receives, so a program measures the balance it got rather than the amount it sent; a scaled UI amount is a display multiplier, and every amount a program sees is raw; a paused mint, or a frozen account (a mint whose default account state is frozen starts every new account frozen), fails the transfer with Token-2022's own error. A transfer hook with no program set is no hook. One that names a program is refused by the library as `transfer hook`, before anything moves: the hook's extra accounts are not passed.
+
+A program's accounts depend on the mint's program, and the SDK resolves them per mint. `resolveSvmToken` reads the mint through a loader that returns each account's owner, which is the only way to tell an extensionless Token-2022 mint from a legacy one; the result gives the `tokenProgram` and `mintAccount` to attach and the `decimals` to pass, and `svmTokenAccount` derives a holder's associated token account under that program:
+
+```ts
+import { createSolanaRpc, type Address } from "@solana/kit";
+import {
+  coalescingOwnedAccountLoader,
+  kitBatchAccountLoader,
+  resolveSvmToken,
+  svmTokenAccount,
+  svmTokenToSend,
+} from "@eco-incorp/sauce/svm";
+
+export async function planTransfer(rpcUrl: string, mint: Address, pot: Address, epoch: bigint) {
+  const load = coalescingOwnedAccountLoader(kitBatchAccountLoader(createSolanaRpc(rpcUrl)));
+  const token = await resolveSvmToken(load, mint);
+  if (token.transferRefusals.length > 0) throw new Error(token.transferRefusals.join("; "));
+
+  return {
+    accounts: {
+      tokenProgram: token.tokenProgram,
+      mint: token.mint,
+      source: await svmTokenAccount(token, pot),
+    },
+    decimals: token.decimals,
+    // What to send at `epoch` for the destination to receive exactly 1,000 base units.
+    amount: svmTokenToSend(token, 1_000n, epoch),
+  };
+}
+```
+
+`svmTokenReceived` is the other direction: what a transfer of an amount delivers. Both apply the mint's transfer fee exactly as Token-2022 computes it. On the command line, `--account` names the same accounts by token: `program:PYUSD`, `mint:PYUSD`, `pot:PYUSD` ([CLI guide](cli.md#solana)).
+
+## Two ways to run a program
+
+The released engine has two entry points, and the SDK builds a cook for each. A client chooses with
+`via`, and the `sauce` command with `--via` ([CLI guide](cli.md#solana)).
+
+|                                 | Through the Kitchen: `via: "kitchen"` (the default)                      | Direct to the engine: `via: "engine"`                                                  |
+| ------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| What the transaction calls      | the Kitchen's `cook`, or `cook_from_account` for a staged program        | the engine's `cookAndPay`, or `cookAndPayFromAccountPinned` for a staged program       |
+| Whose authority the program has | the owner's Pot, which the Kitchen signs for, and any signer it is given | only the signers the transaction gives it, such as the wallet; nothing signs for a Pot |
+| The execution fee               | charged by the Kitchen, before it calls the engine                       | charged by the engine, before the program runs                                         |
+| CPI depth left for the program  | three levels below it, on mainnet; seven where SIMD-0268 is active       | four, on mainnet; eight where SIMD-0268 is active                                      |
+
+**Through the Kitchen** is for custody through a Pot: the program holds and spends what the Pot
+owns (token accounts whose owner is the Pot) and writes the Pot's own storage, at an address that is
+the same for every cook of that owner and salt. The owner signs every Kitchen cook.
+
+**Direct to the engine** is for a program that acts as the signer: it spends the wallet's own token
+accounts, with the wallet signing as their authority, and makes no Pot at all. It also starts the
+program's own calls one level higher on Solana's invoke stack, because no Kitchen frame sits under
+the engine. That is the difference between fitting and not fitting when the program calls a program
+that calls others — an aggregator into a pool into a token program, say. Solana allows 4 levels of
+CPI below a transaction's instruction (8 once SIMD-0268's feature is active): through the Kitchen
+the engine spends one of them.
+
+What does not change between them:
+
+- **The fee.** Both read it from the Kitchen's `["execution_fee"]` config account and pay it into
+  that same account, the Kitchen's treasury. Both instructions carry a signed `max_execution_fee`,
+  and a fee above it refuses the cook before anything runs or is paid. Directly, the fee payer must
+  be a System-owned account that holds no data, and the engine validates the config even when the
+  fee is zero, so a lookalike account is refused rather than read as free.
+- **The program.** The same compiled bytecode and the same account indices run either way: the
+  Kitchen's accounts, and the three a direct cook pays with, are taken off the list before the
+  program sees it.
+- **`ctx.self()`** is the engine program's id, and **`ctx.msgSender()`** the first signer among the
+  program's accounts.
+
+A program cannot write an account that does not sign (`svm.sstore` refuses it), so a direct cook
+cannot write a Pot's storage, and a transfer whose authority is a Pot fails for the missing
+signature. Attach the wallet, signing, where the program needs an authority.
+
+## Run with the client
+
+`createSauceSvmClient` requires an RPC URL, engine program ID, Kitchen program ID, and a Kit
+transaction signer. It builds the cook `via` names, includes the required heap-frame instruction,
+resolves accounts, and builds/signs transactions. The Kitchen ID is required either way: a direct
+cook pays the fee its config sets.
 
 Use `v12SvmEngineProgramId()` and `v12SvmKitchenProgramId()` from
 `@eco-incorp/sauce/deployments` for the released program identities, and confirm
-they are deployed on your cluster. `v12SvmProgramId` names an earlier engine
-generation, not these. The client derives a Pot owned by its `payer` signer;
-choose it with `potSalt` when you configure the client.
+they are deployed on your cluster. Through the Kitchen the client derives a Pot owned by its
+`payer` signer; choose it with `potSalt` when you configure the client. Direct, `payer` signs and
+pays the fee, and `potSalt` means nothing.
 
 ```ts
 import {
@@ -65,89 +151,115 @@ export async function simulateProgram(
 }
 ```
 
-For the transfer above, the resolution keys are `sourceAta`, `mint`, `destinationAta`, `owner`, and `tokenProgram`. A non-payer transaction authority should be supplied as `{ address, signer: transactionSigner }`; an address alone cannot provide its signature. A Pot PDA that the Kitchen signs for must be attached with `signer: false` in the transaction resolution. That override represents a signature supplied during invocation, not permission to bypass the program's authority requirement.
+For the transfer above, the resolution keys are `sourceAta`, `mint`, `destinationAta`, `owner`, and `tokenProgram`. A non-payer transaction authority should be supplied as `{ address, signer: transactionSigner }`; an address alone cannot provide its signature. A Pot PDA that the Kitchen signs for must be attached with `signer: false` in the transaction resolution. That override represents a signature supplied during invocation, not permission to bypass the program's authority requirement — and a direct cook has no Kitchen to supply it.
+
+Pass `{ accounts: [...] }` to `simulate` to see what the cook would move: the result's `accounts`
+holds each one's state after the transaction (`lamports`, `owner`, `data`), or `null` where it no
+longer exists, read without sending anything.
 
-After successful simulation, `client.execute(bytecode, manifest, resolution, { computeUnitLimit: "auto" })` simulates for compute budgeting and sends the transaction. `maxExecutionFee` in client configuration is the lamport fee ceiling accepted for each cook; its default is zero and fails when the Kitchen charges a positive fee. Lookup-table helpers can create or extend an address lookup table and wait until it is usable.
+After successful simulation, `client.execute(bytecode, manifest, resolution, { computeUnitLimit: "auto" })` simulates for compute budgeting and sends the transaction. `maxExecutionFee` in client configuration is the lamport fee ceiling each cook signs; its default is zero and fails when the Kitchen charges a positive fee. A cook's own `maxExecutionFee` option overrides it. Lookup-table helpers can create or extend an address lookup table and wait until it is usable.
 
 ### Select the released programs and quote the fee
 
 Read the program ids from the deployment helpers rather than pasting them, and
-confirm each is deployed on the cluster you are targeting. The SDK's clients cook
-through the Kitchen; the engine's direct paid instructions have no builder here.
+confirm each is deployed on the cluster you are targeting.
 
-Every cook pays the Kitchen's fee in lamports, and the fee is read from chain, not
-assumed. This example quotes it and refuses to sign past a budget the caller set:
+Every cook pays the Kitchen's fee in lamports, either way, and the fee is read from chain, not
+assumed: `fetchExecutionFee` (or a client's `executionFee()`) reads the config account and refuses
+one that is not the Kitchen's. This example quotes it, refuses to sign past a budget the caller set,
+and signs the quote as the cap:
 
 ```ts
-import { createHash } from "node:crypto";
-import {
-  address,
-  assertAccountExists,
-  createSolanaRpc,
-  fetchEncodedAccount,
-  type TransactionSigner,
-} from "@solana/kit";
+import { address, createSolanaRpc, type TransactionSigner } from "@solana/kit";
 import { v12SvmEngineProgramId, v12SvmKitchenProgramId } from "@eco-incorp/sauce/deployments";
-import { createSauceSvmClient, deriveExecutionFeeConfigPda } from "@eco-incorp/sauce/svm";
+import { createSauceSvmClient, fetchExecutionFee, type CookVia } from "@eco-incorp/sauce/svm";
 
 export async function createReleasedClient(
   rpcUrl: string,
   payer: TransactionSigner,
   feeBudgetLamports: bigint,
+  via: CookVia = "kitchen",
 ) {
   const kitchen = address(v12SvmKitchenProgramId());
-  const { address: feeConfig } = await deriveExecutionFeeConfigPda(kitchen);
-  const account = await fetchEncodedAccount(createSolanaRpc(rpcUrl), feeConfig);
-  assertAccountExists(account);
-  const discriminator = createHash("sha256")
-    .update("account:ExecutionFeeConfig")
-    .digest()
-    .subarray(0, 8);
-  if (
-    account.programAddress !== kitchen ||
-    account.data.length !== 16 ||
-    !discriminator.every((value, index) => account.data[index] === value)
-  )
-    throw new Error("Unexpected Kitchen fee account");
-  const fee = new DataView(
-    account.data.buffer,
-    account.data.byteOffset,
-    account.data.byteLength,
-  ).getBigUint64(8, true);
-  if (fee > feeBudgetLamports) throw new Error("Kitchen fee exceeds the approved budget");
+  const fee = await fetchExecutionFee(createSolanaRpc(rpcUrl), kitchen);
+  if (fee > feeBudgetLamports) throw new Error(`The execution fee ${fee} exceeds the budget`);
   return createSauceSvmClient({
     rpcUrl,
     payer,
     kitchen,
     programId: address(v12SvmEngineProgramId()),
     maxExecutionFee: fee,
+    via,
   });
 }
 ```
 
 The payer needs SOL for this per-cook fee, transaction fees, and any rent or program
-spending. The Kitchen charges its current fee up to the signed cap; a fee increase
+spending. The fee charged is the current one, up to the signed cap; a fee increase
 above the quoted amount makes the cook fail. Requote before signing a retry.
 
 `resolveAccounts` preserves manifest order. The reserved `payer` reference resolves to the fee payer. A manifest ending with `remaining` leaves the final account tail to the caller; do not insert accounts that shift that tail's indices.
 
+### Build a direct cook yourself
+
+The engine's three paid instructions have builders in `@eco-incorp/sauce/svm` (and the narrow
+`@eco-incorp/sauce/svm/engine`): `buildCookAndPayInstruction` for inline bytecode,
+`buildCookAndPayFromAccountPinnedInstruction` for a staged program and its digest, and
+`buildCookAndPayFromAccountInstruction`, unpinned. Each takes the program's tail and appends the
+fee payer, the System Program and the fee config, which the engine takes off before the program
+runs:
+
+```ts
+import type { Address, TransactionSigner } from "@solana/kit";
+import {
+  buildCookAndPayInstruction,
+  buildHeapFramePrepend,
+  deriveExecutionFeeConfigPda,
+  type ResolvedAccountMeta,
+} from "@eco-incorp/sauce/svm";
+
+export async function directCook(
+  engine: Address,
+  kitchen: Address,
+  wallet: TransactionSigner,
+  bytecode: Uint8Array,
+  tail: readonly ResolvedAccountMeta[],
+  quotedFee: bigint,
+) {
+  const { address: feeConfig } = await deriveExecutionFeeConfigPda(kitchen);
+  return [
+    buildHeapFramePrepend(),
+    buildCookAndPayInstruction({
+      engineProgram: engine,
+      feeConfig,
+      feePayer: wallet.address,
+      maxExecutionFee: quotedFee,
+      bytecode,
+      tail,
+    }),
+  ];
+}
+```
+
 ## Stage a larger program
 
-Staging belongs to the Kitchen. There is no `client.stageBuffer()` convenience method. Build and submit Kitchen instructions in this order:
+Staging belongs to the Kitchen, whichever way the program then runs. There is no `client.stageBuffer()` convenience method. Build and submit Kitchen instructions in this order:
 
 1. Derive metadata and code addresses with `deriveCodeBufferPda(kitchen, owner, nonce)` and `deriveCodePda(kitchen, codeBuffer)`.
 2. Allocate with `buildCreateCodeBufferInstruction`. Capacities above `GROWTH_STEP` require additional `buildGrowCodeBufferInstruction` calls.
 3. Write the bytecode in appropriately sized chunks using `buildWriteCodeBufferInstruction`.
 4. Finalize with `buildFinalizeCodeBufferInstruction`, supplying the byte length and its SHA-256 digest. Finalization verifies the digest and shrinks the code account to that length.
-5. Execute with a Kitchen `buildCookFromAccountInstruction`, or the client's `simulateStaged`/`executeStaged` methods.
+5. Execute with a Kitchen `buildCookFromAccountInstruction`, the engine's `buildCookAndPayFromAccountPinnedInstruction`, or the client's `simulateStaged`/`executeStaged` methods.
+
+The low-level instruction builders return instructions; the application groups, signs, submits, and confirms them. Every cook requires `buildHeapFramePrepend()` when assembling transactions yourself. A staged client's first argument is the **code-buffer metadata address**; it derives the associated code account.
 
-The low-level instruction builders return instructions; the application groups, signs, submits, and confirms them. The two Kitchen cook paths require `buildHeapFramePrepend()` when assembling transactions yourself. A staged client's first argument is the **code-buffer metadata address**; it derives the associated code account.
+Through the Kitchen, `buildCookFromAccountInstruction` takes a `pin` the Kitchen checks at execution time, and the Kitchen runs only a finalized buffer the signing owner holds. The client's `expectedSha256` option is rejected there — it is not a substitute for that pin. The digest checked when a buffer is finalized and a digest chosen by a caller at execution are different guarantees about different moments; read both before relying on either.
 
-`buildCookFromAccountInstruction` takes a `pin` the Kitchen checks at execution time. The client's `expectedSha256` option is rejected — it is not a substitute for that pin. The digest checked when a buffer is finalized and a digest chosen by a caller at execution are different guarantees about different moments; read both before relying on either.
+Direct, the engine checks nothing about the code account — not its owner, not that it is finalized — except, in `cookAndPayFromAccountPinned`, that the SHA-256 of all its data is the digest the instruction carries, and it runs exactly the bytes it hashed. So the client always pins a direct staged cook: to `expectedSha256`, or to the `sha256` of the `StagedBuffer` you pass, and a bare buffer address with neither is refused. `buildCookAndPayFromAccountInstruction` runs whatever the account holds when the transaction lands, with the signer's authority: use it only for an account no one else can change.
 
 ## SVM destinations in Eco intents
 
-**Build Solana execution with the Kitchen client, not the SVM route helpers.**
+**Build Solana execution with the SVM client (`createSauceSvmClient`), not the SVM route helpers.**
 
 `Solana(body, { execution, ... }).reward(...)`, `routes.compileSauceRoute()`,
 `buildSauceSvmCall()` and `buildSauceSvmCalls()` emit an `execute_from_account`
@@ -157,12 +269,47 @@ supplies, so that instruction is not one it will run — and pointing the helper
 a different engine id does not add the missing bytes.
 
 The [SVM Portal's fulfillment](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
-forwards a route's instruction bytes to their target unchanged and signs for its
-own Executor PDA. It does not assemble a Kitchen call or sign for a Sauce Pot.
-A Portal integration that reaches the Kitchen therefore needs cook data and
-accounts built separately — the owner signature, the Pot, the fee configuration
-and payer, the engine, and staged metadata and code where they apply. That
-assembly is not in this package.
+forwards a route's instruction bytes to their target unchanged and signs each
+call for its own executor PDA. So the executor can own a Kitchen Pot and cook on
+it: the Solana counterpart of an EVM intent's cook on the Executor's shared Pot.
+`svm` builds that route:
+
+- `svmIntentPot({ portal, kitchen })` is the executor's Pot (the zero salt by
+  convention), which every intent's cook through that Portal shares: send on in the
+  program what the intent delivers.
+- `svmIntentPotInstruction(...)` is the Kitchen's `create_pot` with the executor as
+  owner and rent payer. One route carries it once, the rent its native amount.
+- `svmIntentCookInstruction({ portal, kitchen, engineProgram, bytecode, manifest,
+resolution, maxExecutionFee })` is the Kitchen's `cook` with the executor as owner
+  and fee payer, the fee the route's native amount, the program's accounts resolved
+  from its manifest as for any cook.
+- `svmRouteCalls(portal, instructions, tokens)` turns instructions into route calls.
+  The Portal hashes each call account's flags as the fill transaction carries them,
+  and a transaction gives an account one set of flags: an account written anywhere
+  (the executor paying the cook's fee, the executor's token account the fill funds) is
+  committed writable everywhere, and the executor never as a signer. A route committed
+  with each call's own flags is another intent, which no fill matches.
+
+Publish the route with the EVM Portal helpers (`routes.publishAndFundTx`); the
+intent syntax does not build it yet. Moving delivered tokens from the executor's
+token account into the Pot's is a route call before the cook (an SPL
+`TransferChecked`, the executor its authority). The fill must request the
+engine's heap frame, as every cook does; `sauce intent fill` adds it when a route
+call is the Kitchen's.
+
+A route's program runs through the Kitchen, on the executor's Pot: that is what
+these builders make, and the `sauce intent` commands take no `--via`. The direct
+entry ([Two ways to run a program](#two-ways-to-run-a-program), `via: "engine"`)
+is for a cook a wallet sends with its own authority. An executor issuing one is
+not something this package builds or tests.
+
+The Portal's own instructions are `buildPortalFulfillInstruction`,
+`buildPortalHyperProveInstructions` (the proof through the HyperProver, with the
+gas for Hyperlane's delivery paid in the same transaction) and
+`buildPortalCancelInstruction`. `decodeFulfillMarker` reads what the Portal
+recorded, and `svmTokenTransferCall` is the route call eco-routes' Solana deposit
+addresses publish. `sauce intent fill`, `prove` and `cancel` send them
+([CLI guide](cli.md#an-intent-to-solana)).
 
 One detail worth knowing if you are reading routes somebody already built:
 `execution.code` there means the finalized **code account**, not its metadata

package/docs/guides/verification.md

@@ -220,8 +220,8 @@ instruction are the ones the application expects.
 ### Execution verification
 
 `decodeSvmSettleExecution({ instructionData, accounts })` resolves accounts
-positionally against the canonical settlement refs. The default `wireFormat: "gated-v1"` accepts raw **engine CPI instructions** produced by Kitchen 1.0.0 for
-engine 1.3.0:
+positionally against the canonical settlement refs. The default `wireFormat: "gated-v1"` accepts raw **engine CPI instructions** produced by the Kitchen for
+the engine this package pins:
 
 | Instruction            | Data                                                               | Full CPI account list                  |
 | ---------------------- | ------------------------------------------------------------------ | -------------------------------------- |

package/mcp/dist/config.js

@@ -0,0 +1,78 @@
+/**
+ * Where the server reads chains: the RPC endpoints of a `--config` file, in the `sauce` command's
+ * format (`{ "rpcUrls": { "<chain id>": "<url>" } }`), and nothing else. The server ships no
+ * endpoint and reads no environment variable.
+ *
+ * A provider URL usually carries a key, so every URL is registered as a secret the moment the file
+ * is read: `sdk.scrub` removes it from every tool result and every message the server writes. No
+ * result names the file either — on a remote server its path is the operator's business.
+ */
+import { endpointFor, secret, UsageError } from "./sdk.js";
+/** A server with no `--config`: it reads no chain. */
+export const NO_ENDPOINTS = { chainIds: [], endpoint: () => undefined };
+/** The name `endpointFor` gives the file in its messages: never its path. */
+const SHOWN = "(the server's config)";
+/**
+ * The endpoints in a config file's `text`. It is checked whole here, at start, so a malformed file
+ * stops the server rather than failing one tool call later; `path` is only for that message.
+ */
+export function readEndpoints(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new UsageError(`--config ${path}: not JSON`);
+    }
+    const urls = parsed?.rpcUrls;
+    if (urls === null || typeof urls !== "object" || Array.isArray(urls)) {
+        throw new UsageError(`--config ${path}: expected { "rpcUrls": { "<chain id>": "<url>" } }`);
+    }
+    const entries = Object.entries(urls);
+    // Every URL a secret before any entry is checked, so no failure below can print one.
+    for (const [, url] of entries)
+        if (typeof url === "string")
+            secret(url);
+    for (const [id, url] of entries) {
+        // Each id as a chain's id is written, so the lookup by `String(chain.id)` finds it: no `08453`.
+        if (!/^(?:0|[1-9]\d*)$/.test(id)) {
+            throw new UsageError(`--config ${path}: rpcUrls key '${id}' is not a chain id`);
+        }
+        if (typeof url !== "string") {
+            throw new UsageError(`--config ${path}: rpcUrls["${id}"] is not a string`);
+        }
+        // A placeholder fails `endpointFor` at the first call for its chain; refuse it here instead.
+        if (/^<.*>$/.test(url.trim())) {
+            throw new UsageError(`--config ${path}: rpcUrls["${id}"] is a placeholder: replace it with the chain's URL, ` +
+                "or remove the entry");
+        }
+        // An endpoint is reached over HTTP: anything else (file:, data:) is refused, never fetched.
+        if (!/^https?:\/\//i.test(url.trim())) {
+            throw new UsageError(`--config ${path}: rpcUrls["${id}"] is not an http(s) URL`);
+        }
+    }
+    const chainIds = entries.map(([id]) => Number(id));
+    return {
+        chainIds,
+        endpoint: (chain) => chainIds.includes(chain.id)
+            ? endpointFor(chain, undefined, { path: SHOWN, text })
+            : undefined,
+    };
+}
+/** Why a tool that reads `chain` cannot, said plainly. */
+export function noEndpoint(chain, endpoints, what) {
+    return new UsageError(`${what} needs an RPC endpoint for ${chain.slug} (chain id ${chain.id}), and this server ` +
+        (endpoints.chainIds.length === 0
+            ? "has none of its own. "
+            : `has none of its own for that chain (it has ${endpoints.chainIds.join(", ")}). `) +
+        "Pass rpcUrl with the call. (Or the server's operator adds the chain to its --config " +
+        `file: { "rpcUrls": { "${chain.id}": "<url>" } }.)`);
+}
+/** The endpoint for `chain`, or the plain refusal of a tool that needs one. */
+export function requireEndpoint(chain, endpoints, what) {
+    const url = endpoints.endpoint(chain);
+    if (url === undefined)
+        throw noEndpoint(chain, endpoints, what);
+    return url;
+}
+//# sourceMappingURL=config.js.map

package/mcp/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/mcp/dist/entry.js

@@ -0,0 +1,112 @@
+/**
+ * What `sauce mcp` runs (`sdk/src/cli/mcp.ts` loads this build lazily): the server over stdio or
+ * Streamable HTTP, and `setup`. The `sauce` command has already read the flags; the values are
+ * checked here. `mcpEntry` is typed by the CLI's own `McpEntry`, so the two cannot drift.
+ *
+ * NODE-ONLY, and reached by nothing browser-facing. It reads no environment variable and ships no
+ * endpoint: the chains it reads are the `--config` file's. It holds no key unless it serves stdio
+ * with `--wallets`, whose password the `sauce` command has already read from the source it was
+ * given; then its wallet tools sign with those wallets alone. Over HTTP it never signs.
+ */
+import { readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { NO_ENDPOINTS, readEndpoints } from "./config.js";
+import { createRpcGuard } from "./guard.js";
+import { DEFAULT_MAX_BODY, endpointUrl, isLoopback, serveHttp } from "./http.js";
+import { UsageError, WalletStore, } from "./sdk.js";
+import { createSauceServer, packageInfo } from "./server.js";
+import { parseSetupAgents, setupLines, setupProject } from "./setup.js";
+function readConfig(path) {
+    if (path === undefined)
+        return NO_ENDPOINTS;
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        throw new UsageError(`--config ${path}: ${code === "ENOENT" ? "no such file" : "unreadable"}`);
+    }
+    return readEndpoints(text, path);
+}
+function wholeNumber(flag, raw, min, max) {
+    if (!/^\d+$/.test(raw) || Number(raw) < min || Number(raw) > max) {
+        throw new UsageError(`--${flag}: '${raw}' is not a whole number from ${min} to ${max}`);
+    }
+    return Number(raw);
+}
+async function serve(options) {
+    const endpoints = readConfig(options.config);
+    const maxBody = options.maxBody === undefined
+        ? DEFAULT_MAX_BODY
+        : wholeNumber("max-body", options.maxBody, 1, 64 * 1024 * 1024);
+    if (options.http === undefined) {
+        if (options.host !== undefined)
+            throw new UsageError("--host goes with --http");
+        if (options.allowedHosts.length > 0)
+            throw new UsageError("--allowed-host goes with --http");
+        if (options.allowPrivateRpc) {
+            throw new UsageError("--allow-private-rpc goes with --http: over stdio a caller's rpcUrl is not guarded at all");
+        }
+        // Over stdio the caller is the server's own user, on the same machine: its endpoints, local
+        // nodes included, are used as given. A message past the bound closes the connection.
+        const wallets = options.wallets === undefined
+            ? undefined
+            : {
+                store: new WalletStore(options.wallets.dir),
+                password: options.wallets.password,
+                source: options.wallets.source,
+            };
+        await createSauceServer({ endpoints, ...(wallets === undefined ? {} : { wallets }) }).connect(new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: maxBody }));
+        if (wallets !== undefined) {
+            options.log(`sauce mcp: signing with the wallets in ${wallets.store.dir}\n`);
+        }
+        return;
+    }
+    // The HTTP server never signs: it is not given the wallets at all.
+    if (options.wallets !== undefined) {
+        throw new UsageError("--wallets is for stdio: the HTTP server never signs");
+    }
+    const port = wholeNumber("http", options.http, 0, 65_535);
+    const host = options.host ?? "127.0.0.1";
+    // Off loopback the Host check is what stands between a browser and the server, so the name it
+    // is served as has to be given: `*` only by an operator whose proxy checks Host itself.
+    if (!isLoopback(host) && options.allowedHosts.length === 0) {
+        throw new UsageError(`--host ${host} is beyond loopback: name the host the server is served as with ` +
+            "--allowed-host <name> (or --allowed-host '*' behind a proxy that checks the Host itself)");
+    }
+    // One guard for the process: every caller's rpcUrl is reached through it, checked again at
+    // each connection.
+    const guard = createRpcGuard({ allowPrivate: options.allowPrivateRpc });
+    const http = await serveHttp({
+        port,
+        host,
+        allowedHosts: options.allowedHosts,
+        maxBody,
+        server: () => createSauceServer({ endpoints, guard }),
+        log: options.log,
+    });
+    options.log(`sauce mcp: Streamable HTTP at ${endpointUrl(http, host)} (stateless, no authentication)\n`);
+    if (!isLoopback(host)) {
+        options.log("sauce mcp: bound beyond loopback, and it authenticates no one: serve it behind your own " +
+            "authentication.\n");
+    }
+    const stop = () => http.close(() => process.exit(0));
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}
+function setup(options) {
+    const project = options.dir ?? ".";
+    const { name, version } = packageInfo();
+    const files = setupProject({
+        project,
+        agents: parseSetupAgents(options.agents),
+        ...(options.config === undefined ? {} : { config: options.config }),
+        force: options.force,
+        packageName: name,
+        version,
+    });
+    return [`The ${name} MCP server, in ${project}:`, ...setupLines(files)];
+}
+export const mcpEntry = { serve, setup };
+//# sourceMappingURL=entry.js.map

package/mcp/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"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"}

package/mcp/dist/files.js

@@ -0,0 +1,64 @@
+/**
+ * The files a program compiles from, as a tool call gives them: the program's own text and the
+ * modules it imports by relative path. Nothing is ever read from the server's disk — a remote
+ * server must not hand its own files to whoever calls it — so the `CliFiles` the commands read
+ * through serves only what the call carried.
+ */
+import { posix, relative, resolve, sep } from "node:path";
+import { UsageError } from "./sdk.js";
+/** The name a program goes by when the call gives none. */
+export const DEFAULT_FILE = "program.sauce.ts";
+/** A path a call names: relative, `/`-separated, and inside the program's directory tree. */
+function cleanPath(path, what) {
+    if (path.includes("\0"))
+        throw new UsageError(`${what}: a path holds a NUL byte`);
+    const clean = posix.normalize(path.replace(/\\/g, "/")).replace(/^\.\//, "");
+    if (clean === "" || clean === "." || clean.startsWith("../") || clean === "..") {
+        throw new UsageError(`${what} '${path}' is not a relative path inside the program's tree`);
+    }
+    if (posix.isAbsolute(clean) || /^[A-Za-z]:/.test(clean)) {
+        throw new UsageError(`${what} '${path}' is absolute: give it relative to the program`);
+    }
+    return clean;
+}
+/**
+ * The program's file name and the `CliFiles` that serve it and its `modules` (keyed by path from
+ * the same root as `file`). The commands resolve an import beside the program, against the
+ * process's working directory; this answers for exactly the paths the call named, and for nothing
+ * else.
+ */
+export function callFiles(file, text, modules) {
+    const name = cleanPath(file ?? DEFAULT_FILE, "file");
+    const served = new Map([[name, text]]);
+    for (const [path, source] of Object.entries(modules ?? {})) {
+        const key = cleanPath(path, "modules:");
+        if (served.has(key))
+            throw new UsageError(`modules: '${path}' is given twice`);
+        served.set(key, source);
+    }
+    const root = process.cwd();
+    const lookup = (path) => {
+        const key = relative(root, resolve(root, path)).split(sep).join("/");
+        return served.get(key);
+    };
+    const encoder = new TextEncoder();
+    return {
+        file: name,
+        files: {
+            readText: (path) => {
+                const found = lookup(path);
+                if (found === undefined) {
+                    throw Object.assign(new Error(`${path}: not among the files this call gave`), {
+                        code: "ENOENT",
+                    });
+                }
+                return found;
+            },
+            readModule: (path) => {
+                const found = lookup(path);
+                return found === undefined ? undefined : encoder.encode(found);
+            },
+        },
+    };
+}
+//# sourceMappingURL=files.js.map

package/mcp/dist/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}