@eco-incorp/sauce 0.99.6 → 0.99.8

package/docs/guides/compiling.md

@@ -17,6 +17,9 @@ execution time, a Solana account manifest, or full control over module resolutio
 | `routes.compileSauceRoute(destination, source, execution, options)` | Source, destination, execution settings                     | Registry rewrites, token defines, one encoded route call                                           |
 | `compile({ target, resolve, ... })`                                 | All source and dependency resolution, and compiler settings | Nothing — you get the compiler's own result                                                        |
 
+From a terminal, [`sauce compile`](cli.md) compiles a program file with everything the first row
+supplies except the intent, and `sauce tx` builds the call that runs it on your own Pot.
+
 Bare `USDC`, `Token(address)` and protocol members only exist on the route path. There,
 `USDC.approve(Uniswap.UniversalRouter, 1_000_000n)` becomes an import of `@sauce/token`'s
 `approve` and `approve(USDC, <the router's Base address>, 1_000_000n)`, with `USDC` defined as
@@ -47,9 +50,10 @@ spends none. For Portal fulfillment the Pot must be owned by the destination Por
 `route.nativeAmount` must cover every call value. [Create an intent](intents.md) covers reading the
 fee, deriving that Pot, and adding the reward and Portal calldata.
 
-`compileSauceRoute` takes a bare body or a complete `function main(...)`. Its rewrite passes parse
-the body as JavaScript, so a body carrying SauceScript type annotations belongs in raw `compile`,
-which accepts typed source directly.
+`compileSauceRoute` takes a SauceScript file as written: a module declaring `function main(...)`,
+or a script whose top-level statements are the entry. Its rewrite passes parse SauceScript as the
+compiler does, type annotations included, so a typed helper that takes or returns an array or a
+record compiles the same way through either.
 
 ## Compile a reusable program
 
@@ -106,6 +110,14 @@ That whole payload is the `program` argument to `Pot.cook(engine, program)`; the
 an ordinary contract call with its own ABI encoding. Passing those same values as `defines` instead
 would produce a _different_ program — one specialised to them.
 
+One parameter type differs from `abi.encode`. `main` reads each parameter from one 32-byte head
+word, so a tuple parameter, such as `leg: { amount: Uint256, to: Address }`, sits behind an offset
+word even when all its fields are fixed-size. `encodeAbiParameters` writes such a tuple's fields
+inline instead, and `main` would read the wrong values. Inside a parameter, as an array element or a
+field of another tuple, a fixed-size tuple is inline, as `abi.encode` writes it.
+`routes.encodeEntryArguments` encodes arguments in the layout `main` reads, from the parameters
+`main` declares, and `routes.decodeEntryArguments` reads them back.
+
 ### Pass arguments with compact-v1
 
 Compile with `compactArgs: true` and use the schema that comes back with it. The schema and the
@@ -196,10 +208,10 @@ For an ABI you already hold, raw compilation takes
 `contracts: { ERC20: { abi } }`, and adapts it. The two shapes are not interchangeable.
 
 Raw compilation serves nothing you do not. The route path serves the SDK's own files itself: the
-`@sauce/token` library, the ERC-20 and Sauce Router ABIs and every protocol ABI twin. For a raw
-compile that needs them, fall back to `resolveSdkModule` and `resolveSdkPackage` from
-`@eco-incorp/sauce/compiler` — the [compiler reference](../api/compiler.md#the-sdks-own-modules)
-shows how.
+`@sauce/token` and [`@sauce/router`](../api/router.md) libraries, the ERC-20 and Sauce Router ABIs
+and every protocol ABI twin. For a raw compile that needs them, fall back to `resolveSdkModule` and
+`resolveSdkPackage` from `@eco-incorp/sauce/compiler` — the
+[compiler reference](../api/compiler.md#the-sdks-own-modules) shows how.
 
 The filesystem resolver above is the one Node-only part of this page. In a browser, serve modules
 from memory.

package/docs/guides/intents.md

@@ -25,6 +25,14 @@ derives the destination Pot and engine, and resolves registered token and protoc
 choose the deadlines, creator and prover, read the Kitchen fee, fund the reward and submit. A solver
 then decides whether to fulfill it; the SDK does not price the reward or promise a fill.
 
+The SDK builds an intent between any two registry chains. For the initial release, Sauce supports
+transactions on Ethereum, Base and Solana, and the [`sauce` command](cli.md) and the
+[MCP server](mcp.md) publish an intent only when its source and every destination it opens, nested
+ones included, are among them; each step after publishing is refused on a preview chain by the
+chain it is sent on ([Supported chains](../README.md#supported-chains)). Several examples below
+name Arbitrum or Optimism, which are preview chains: the SDK builds them as shown, and submitting
+one is at your own risk.
+
 ## Source, destination, and funding
 
 An intent has two sides:
@@ -64,13 +72,18 @@ the one Pot the solver deploys per Portal and every intent through that Portal s
 overrides. `destinationPot(Base.chain, { portal })` returns that address, for a `precalls`
 transfer into it.
 
+The address also follows the pinned Kitchen release's Pot bytecode, whose hash is part of every Pot
+address. A Kitchen release that changes that bytecode starts a new family: the shared Pot for the
+same Executor moves to a new address, and a Pot of the earlier family keeps running on the engine
+built for it. `destinationPot` always answers for the family this SDK pins.
+
 **The destination Pot must exist before the intent is fulfilled.** The SDK derives its address and
 deploys nothing: the route contains no deployment call. The solver deploys the shared Pot for each
 Portal. A fulfilment that cooks on a Pot that is not there reverts entirely, because the Executor
 refuses a call with calldata to an address without code (`CallToEOA`).
 
 To deploy it yourself first, send this on the destination chain:
-`routes.sauceEvmDeployPotCall({ kitchen: v12GateKitchen(), owner: executor, salt: SAUCE_INTENT_POT_SALT })`.
+`routes.sauceEvmDeployPotCall({ owner: executor, salt: SAUCE_INTENT_POT_SALT })`.
 The call is permissionless, and it returns the existing Pot when one is already there. A **Pot you
 name** instead must also exist, and be owned by that Executor, or the cook reverts with `NotOwner()`.
 Use
@@ -78,13 +91,19 @@ Use
 the shared Pot — to predict the Pot and check that it is deployed, with the right `owner()` and
 `kitchen()`. Only use a result with `ready: true`.
 
-### Arc's Pot
+### One Portal, one Pot
 
-Arc's eco-routes Portal (`0xEC002CA16cE20c2a9F3C6200EF04E7d92a3dfBD8`) is not the Portal most other
-chains share, so its Executor (`0x95b2d45F49c68a54BDBa0356fc3034751A43b3D4`) and the Pot derived from
-it (`destinationPot("arc")`, `0x4edfB4576F91A9c2fE9aA50f669B7C81E4B82955`) are Arc's own. This prediction
-uses Kitchen **1.1.0** initcode. Upgrade the Kitchen and deploy the matching engine and Pot before
-sending intents; the release address alone does not confirm readiness.
+The registry records one eco-routes Portal, `0xEC000769A73b70e16f361a442292500b3BCf4A85`, on every
+EVM chain it has eco-routes on, Arc included. So one Executor
+(`0x8B5D51AF4C4542f241C4e54CFd903CeEd145f082`) and one derived Pot
+(`destinationPot(chain)`, `0xDd330394620fBFF4D0AdcfA33B0D7b3622Db15B0`) serve every destination.
+This prediction uses the pinned Kitchen release's Pot bytecode. The Kitchen, the matching engine and
+that Pot must be deployed on the destination before an intent to it can run; the release address
+alone does not confirm readiness.
+
+A solver fills an intent only on the Portal it serves: an intent published on a different Portal
+deployment is not one it can fill. Set `options.portal` or `options.sourcePortal` only to a Portal
+you have confirmed a solver serves.
 
 The deployment helpers return the released addresses. They do not check that code is live at those
 addresses on your chain. The same helper confirms the Kitchen and engine have code, and reads the
@@ -252,6 +271,40 @@ A variable can arrive two ways, and the same variable can do both:
 
 Used both ways, a variable gets a slot in each: they are different offsets carrying the same value.
 
+### The file's functions, imports and constants
+
+A program body was written in the file, so it can use what the file declares: its functions, its
+imports, its interfaces and its module-level constants. Its program carries the ones the body
+reaches, and the ones those reach, as written, and nothing else:
+
+```ts
+import { balanceOf } from "@sauce/token";
+
+function fee(amount: Uint256): Uint256 {
+  return amount / 100n;
+}
+
+function main() {
+  const amount = USDC.balanceOf(ctx.self());
+  Arbitrum(
+    () => {
+      const [held] = abi.decode(abi.encode(balanceOf(USDC, ctx.self())), ["Uint256"]);
+      USDC.transfer(RECIPIENT, held - fee(held));
+    },
+    { tokens: [{ token: USDC, amount }] },
+  ).reward({ tokens: [{ token: USDC, amount }] });
+}
+```
+
+A carried declaration is compiled for the chain its program runs on, so `USDC` in `fee` would mean
+Arbitrum's USDC there. A function only intent bodies call moves out of the enclosing program, which
+never runs it; one that another remaining function calls stays. A local of the enclosing function
+shadows a file declaration of the same name, as it does in the compiler: the body captures the
+local. A module-level `let` the body's program uses starts with the value it has where the intent
+opens — the program carries the declaration and is handed its value, the same value a reward naming
+it escrows — so the body and every function it calls see one number. A body cannot call the
+function that opens it, since that function's program would contain the intent it is the body of.
+
 ### Nesting
 
 An intent inside an intent is lowered recursively — the child is compiled by re-entering the same
@@ -261,8 +314,31 @@ of hops whose amounts are each measured on arrival is written; see
 
 ### Names resolve per chain
 
-`USDC` inside the braces is _Arbitrum's_ USDC, because those calls run on Arbitrum. Resolving it
-against the enclosing chain would put one chain's address in another chain's route.
+Two chains meet in `Arbitrum(() => { ... }).reward({ ... })`, and each part belongs to one of them.
+A token symbol resolves on the chain where its part runs:
+
+| Part                                   | Runs on                       | `USDC` is    |
+| -------------------------------------- | ----------------------------- | ------------ |
+| The braces                             | Arbitrum, the destination     | Arbitrum's   |
+| The second argument, what is delivered | Arbitrum, the destination     | Arbitrum's   |
+| `.reward(...)`                         | The chain the program runs on | That chain's |
+
+The reward belongs to the enclosing chain because the program escrows it there: it pays the reward
+token into the intent's vault on that chain's Portal and publishes the intent in the same
+fulfillment. Resolving a name on the other chain names an address that is not that token where it
+is used. A reward token taken from the destination fails the transfer's code check and reverts the
+fulfillment. A body token taken from the enclosing chain makes the intent unfulfillable.
+
+The rule repeats at every depth. An intent opened inside a body is funded on that body's chain, so
+its reward resolves there and its own body on its own destination. The same holds for the other
+values that belong to a chain, `chainId` and protocol addresses such as `UniswapV4_UniversalRouter`:
+a body on another chain sees that chain's own.
+
+A literal address means that address wherever it appears, and so does a compile-time define whose
+name no chain uses, such as `RECIPIENT`. A define or a `tokens` override under a chain-scoped name —
+a token symbol, `chainId`, a protocol address — is a name on the chain the program is compiled for.
+It applies to that program and to the reward it funds. A body on another chain keeps that chain's
+value, whether the define came from `chainDefines(base)` or was chosen by hand.
 
 ### A throw reverts everything
 
@@ -339,9 +415,28 @@ fields down so the common case sets none of them:
 | `destinationPortal`          | The Portal recorded in the child's route                             |
 | `pot`, `engine`              | Where a program body cooks, and on what; a named Pot is not deployed |
 | `executionFee`               | The cook's value                                                     |
-| `salt`, `allowPartial`       | The route salt, and partial funding                                  |
+| `fundVia`                    | How the reward is funded — see below                                 |
+| `salt`, `allowPartial`       | The route salt, and partial funding (`publishAndFund` only)          |
 | `generation`, `environment`  | Which eco-routes deployment to address                               |
 
+### How the reward is funded
+
+By default the program pays the reward into the intent's vault itself, then publishes the intent.
+In the same transaction it asks the source Portal for `intentVaultAddress` over the bytes it is
+about to publish, transfers each reward token there with
+[`SafeERC20`](protocols-and-tokens.md#writes-follow-safeerc20) semantics, sends the native amount
+from the Pot's balance, and calls `Portal.publish`. The Portal counts an intent funded when its
+vault holds the reward (`isIntentFunded`), which is what a solver checks once it has seen
+`IntentPublished`. Nothing is approved, so no allowance is left on the shared Pot and a USDT-style
+token needs no reset; a token whose transfer returns `false` reverts the fulfillment.
+
+`fundVia: "publishAndFund"` — in `compile.intents`, `IntentOptions.fundVia`, or
+`--intent-fund-via publishAndFund` on the command line — approves the Portal for each reward token
+instead (resetting a standing allowance first) and calls `publishAndFund`, forwarding the native
+amount as the call's value. The Portal pulls the reward into the same vault, records the intent
+`Funded` and emits `IntentFunded`. Choose it when something you rely on reads that event or status
+rather than the vault's balance. `allowPartial` applies only here.
+
 ### What is refused
 
 Each of these is a compile error naming the construct, never a silently different intent:
@@ -350,6 +445,8 @@ Each of these is a compile error naming the construct, never a silently differen
 - A `.reward(...)` that is not an object, or a token entry missing `token` or `amount`.
 - A missing `deadline`, a missing `creator`, or a missing `executionFee` for a program body.
 - A chain with no eco-routes deployment, or a pair with no prover deployed on both sides.
+- A program body that calls the function opening it.
+- A program body using a module variable that a local of the opening function shadows.
 
 Inside a program body an unknown name is the _compiler's_ error rather than this lowering's, and
 reads the same way: it names the variable that is not declared.
@@ -360,8 +457,12 @@ A callback is read with `Function.prototype.toString()`, parsed, and compiled as
 
 Use literals for self-contained callbacks, or source strings plus `defines` for application inputs, as above. Defines accept scalar `bigint`, `number`, or `boolean` values; use `bigint` for addresses and token quantities. `compile.defines` overrides `options.defines`, which overrides chain defaults. Local declarations in the program take precedence over ambient names.
 
+The package declares SauceScript's builtins for TypeScript — `ctx`, `crypto.keccak256`, `hex`, `Math.mulDiv`, `require(condition, message)`, `abi`, `evm`, `svm`, `.toBytesBe(...)` and the rest of the [reference](../../skills/sauce-script/references/builtins.md) — as it declares token symbols and protocols, so a typed callback that uses them typechecks. The declarations install nothing at run time, and a builtin's comment says which targets have it: TypeScript does not know which chain the callback compiles for.
+
 Callbacks must be synchronous and take no parameters. Bound/native functions, generators, and async functions are rejected. If a bundler transforms function source, ship an explicit SauceScript string or source asset. A TypeScript type declaration does not create a captured value.
 
+A function the callback declares in its own body is a helper of the program: SauceScript has no nested functions, so it is declared beside `main`, and an intent opened inside the callback can call it like any other function of the file. Its annotations are whatever the host's TypeScript compilation left in the callback's text, which is usually none, so a helper that takes or returns an array or a record belongs in a source string.
+
 `Base(...)` adds the SDK's default ambient token module, enabling function forms such as `approve(tokenAddress, spender, amount)`. Direct `compileSauceRoute(...)` does not automatically add that ambient module. The token and protocol member syntax described in [protocols and tokens](protocols-and-tokens.md) is a separate rewrite that works on both paths; its writes import the same module's functions themselves, so they have the same `SafeERC20` semantics either way.
 
 ## Submit the source reward
@@ -371,17 +472,129 @@ For a built intent, prepare the source-chain requests:
 ```ts
 import type { routes } from "@eco-incorp/sauce";
 
-export function sourceTransactions(built: routes.BuiltIntent) {
-  return [...built.approvals(), built.publishAndFundCalldata(false)];
+export async function sourceTransactions(
+  built: routes.BuiltIntent,
+  ethCall: (request: Pick<routes.PortalReadCall<routes.Hex>, "to" | "data">) => Promise<routes.Hex>,
+) {
+  const read = built.vaultCall();
+  const vault = read.decode(await ethCall({ to: read.to, data: read.data }));
+  return built.sourceTxs({ vault });
 }
 ```
 
-Each request is `{ to, data, value }`. Send them from the intended funder on `built.source`, in order, waiting for successful approvals before funding. ERC-20 approvals authorize the **source Portal**, which pulls tokens into the intent vault. Native rewards are included as transaction `value`. `.approvals()` covers only the root reward, even when the intent has children.
+Each request is `{ to, data, value }`. Send them from the intended funder on `built.source`, in order. By default an intent is funded **by transfer to its vault**: one ERC-20 `transfer` per reward token to the vault (for the largest amount listed for it), a plain send of the native amount, then `Portal.publish`. The Portal counts an intent funded when its vault holds the reward (`isIntentFunded`), and that is what a solver checks after it sees `IntentPublished`. No approval is asked for, so none is left standing and a USDT-style token needs no reset. `sourceTxs()` covers only the root reward, even when the intent has children.
+
+**Pass the vault you read.** `vault` is checked against `predictVault()`, the SDK's own derivation, and a mismatch throws `IntentVaultMismatchError` before anything is built: a transfer is final, so an address two sources disagree on is not paid. Without `vault`, the derivation alone is used. It is held to the `intentVaultAddress` of every eco-routes Portal the SDK records.
 
-`false` selects full funding; use partial funding only when the application deliberately supports it. `publishCalldata()` publishes without funding, and `fundCalldata(allowPartial)` funds separately. These methods do no RPC and send no transactions.
+**Send the transfers first, and publish once they have landed.** The solver then sees `IntentPublished` with the vault already funded. If `publish` fails, the reward stays in the vault: publish again later, or refund it after the reward deadline. A token whose `transfer` returns `false` instead of reverting leaves the vault short, so check `fundedCall()` before sending `publish`. [`sauce intent publish`](cli.md#intents-sauce-run-or-sauce-intent) does all of this for you.
+
+`sourceTxs({ fundVia: "publishAndFund" })`, or `IntentOptions.fundVia: "publishAndFund"`, returns `[...approvals(), publishAndFundCalldata(allowPartial)]` instead. ERC-20 approvals authorize the **source Portal**, which pulls tokens into the vault, records the intent `Funded` and emits `IntentFunded`. Native rewards are included as transaction `value`. Wait for successful approvals before funding. `allowPartial` defaults to `false`; use partial funding only when the application deliberately supports it. Choose this mode when something you rely on reads the `IntentFunded` event or the `Funded` status rather than the vault's balance.
+
+`publishCalldata()` publishes without funding, and `fundCalldata(allowPartial)` funds separately. These methods do no RPC and send no transactions.
 
 Set `sourcePortal` while building, or pass `{ portal: sourcePortal }` to each helper. The destination `portal` is never silently reused as the submission target.
 
+## Rehearse the fill on the destination
+
+Publishing proves the reward is escrowed, not that the intent works. Its body runs on the
+destination, inside the solver's fill, so a swap that falls short of its minimum or a refund that
+fails shows up only there. A solver sends two things on the destination chain:
+
+- an approval of the destination Portal for each token the route delivers, which the Portal pulls
+  from the solver into its Executor;
+- `Portal.fulfill(intentHash, route, rewardHash, claimant)`, with `route.nativeAmount` as its value
+  — the Kitchen's fee for each cook in the route, plus any native the calls spend.
+
+`routes.fulfillApprovalTxs(built.intent)` and `routes.fulfillTx(built.intent, { claimant })` build
+them, for an EVM destination:
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+
+export function solverTransactions(built: routes.BuiltIntent, claimant: routes.Hex) {
+  return [...routes.fulfillApprovalTxs(built.intent), routes.fulfillTx(built.intent, { claimant })];
+}
+```
+
+Rehearse them before publishing. A route that cooks needs the shared Pot deployed first, so a
+rehearsal on a chain where nobody has deployed it yet puts `Kitchen.deployPot(executor, 0)` ahead
+of the fill, in the same simulated block. From the command line,
+[`sauce intent fill`](cli.md#rehearsing-the-fill-sauce-intent-fill) does all of it with no key: it
+builds the file's intents as `sauce intent publish` does, gives a solver the route's tokens by
+state override, runs the deployment, the approvals and the fill in one `eth_simulateV1` block on
+the destination, and prints what moved, what the shared Pot and the Executor were left holding, and
+the decoded reason when it reverts. With `--send` and a signer it then sends them, the signer being
+the solver ([`fill --send`](cli.md#filling-it-for-real-sauce-intent-fill---send)), on a supported
+destination only.
+
+## After the fill: prove, claim, refund, cancel
+
+The fill is recorded on the destination; the reward is on the source. What carries one to the other,
+and what happens when nobody fills, is the Portal's, on eco-routes' own terms:
+
+1. **Prove.** The destination Portal's `prove(prover, sourceDomain, intentHashes, data)` hands what
+   it recorded for each intent (the claimant, or a cancellation) to the destination's prover, which
+   sends it to the reward's prover on the source for a fee it quotes. `fulfillAndProve` is the fill
+   and the proof in one transaction, its value the route's native amount plus that fee. Through
+   Hyperlane, `data` is `abi.encode((bytes32 sourceChainProver, bytes metadata, address hook))` — the
+   source prover, empty metadata and no hook take the Mailbox's defaults — and the source domain
+   is an EVM source's chain id. The Portal forwards its whole balance to the prover, which keeps its
+   fee and refunds the rest to the sender, so overpaying is safe.
+2. **Claim.** Once the bridge delivers it, the source prover's `provenIntents(intentHash)` returns
+   the claimant, and the source Portal's `withdraw(destination, routeHash, reward)`, sent by anyone,
+   pays that claimant the reward from the vault (`batchWithdraw` for several).
+3. **Refund.** `refund(destination, routeHash, reward)`, sent by anyone, returns everything the
+   vault holds of the reward to its creator: from the reward's deadline when no fill is proven,
+   only the leftovers once the claimant has withdrawn, and never while a proven claimant has not.
+4. **Cancel.** A destination Portal with `cancel` lets anyone cancel an unfilled intent strictly
+   after the route's deadline; no fill can land after it, and proving the cancellation lets the
+   creator refund at once. The cancellation travels as a claimant nobody controls, so the source
+   Portal must refuse to pay it (its `withdraw` reverting `CancelledIntent`): prove one only to a
+   source whose Portal does, and only once the cancel is final on the destination.
+
+`routes` builds each as calldata, and the reads that decide them:
+
+```ts
+import { routes } from "@eco-incorp/sauce";
+
+export function afterTheFill(
+  intent: routes.Intent,
+  sourcePortal: routes.Hex,
+  prover: routes.Hex,
+  fee: bigint,
+) {
+  const data = routes.hyperlaneProverData({ sourceProver: intent.reward.prover });
+  const proof = { prover, sourceDomain: intent.sourceChainId, data, fee };
+
+  return {
+    prove: routes.proveTx([intent], proof), // on the destination; value: the fee
+    claim: routes.withdrawTx(intent, { portal: sourcePortal }), // on the source
+    refund: routes.refundTx(intent, { portal: sourcePortal }), // on the source
+    cancel: routes.cancelTx(intent), // on the destination, after the route's deadline
+    proven: routes.provenIntentCall(intent), // the source prover's record: claimant, destination
+    recorded: routes.fulfillmentCall(intent), // the destination's claimants[intentHash]
+    status: routes.rewardStatusCall(intent, { portal: sourcePortal }), // Initial … Refunded
+    fee: routes.proverFeeCall({
+      prover,
+      sourceDomain: intent.sourceChainId,
+      destinationChainId: intent.destination,
+      pairs: [
+        { intentHash: routes.hashIntent(intent).intentHash, claimant: intent.reward.creator },
+      ],
+      data,
+    }),
+  };
+}
+```
+
+`routes.fulfillAndProveTx(intent, { claimant, ...proof })` is the fill and its proof in one, and
+`routes.cancelAndProveTx(intent, proof)` the cancellation and its. From the command line,
+[`sauce intent prove, claim, refund and cancel`](cli.md#after-the-fill-prove-claim-refund-cancel)
+send them on a supported chain, reading the state first and saying why not, and
+[`sauce intent status`](cli.md#after-the-fill-prove-claim-refund-cancel) reads where an intent
+stands on both chains. `routes.intentFromPublished(log, sourceChainId)` rebuilds an intent from its
+`IntentPublished` log, which `sauce intent import` stores.
+
 ## Inspect hashes, vaults, and status
 
 `built.hash()` returns `intentHash`, `routeHash`, and `rewardHash`. `built.intent` or `.root()` returns the normalized intent. `.intents()` returns the root and descendants in preorder; it does not imply they execute atomically across chains.
@@ -401,6 +614,6 @@ export async function readVault(
 }
 ```
 
-Execute this read on the source chain. `hashCall()` cross-checks hashes against the Portal; `fundedCall()` checks funding. `predictVault({ portal, vaultInitCodeHash })` provides an offline CREATE2 prediction when you have verified the deployed vault configuration.
+Execute this read on the source chain. `hashCall()` cross-checks hashes against the Portal; `fundedCall()` checks funding. `predictVault()` is the offline CREATE2 prediction of the same address, with nothing read from a chain: an eco-routes Portal's vaults are clones, salted with the intent hash, of a Proxy over the Portal's first `CREATE`, so the address follows from the Portal's own. For a Portal built some other way, pass its configuration: `predictVault({ portal, vaultInitCodeHash })`.
 
 For a Solana destination, build the execution with the Kitchen client rather than the SVM route helpers: the instruction those helpers emit is not one the Solana engine accepts, and staging the code does not change that. The [Solana guide](solana.md) has the supported path.