@eco-incorp/sauce 0.99.6 → 0.99.7

package/skills/sauce-globals/references/tokens.md

@@ -0,0 +1,53 @@
+<!-- Generated from the SDK's registries. Do not edit. -->
+
+# Token globals
+
+A program compiled for a chain names these symbols with no import; each is that chain's token,
+and amounts are in its smallest units (its decimals). Their addresses are in the chain's file in
+`sauce-chains`. Any other ERC-20 is `Token(<address>)`.
+
+- **Ethereum** (`ethereum`, [addresses](../../sauce-chains/references/ethereum.md)): `USDC` (6), `USDT` (6), `WETH` (18); and 1731 tokenized stocks ([stocks](stocks.md))
+- **Optimism** (`optimism`, [addresses](../../sauce-chains/references/optimism.md)): `USDC` (6), `USDT` (6), `WETH` (18)
+- **Polygon** (`polygon`, [addresses](../../sauce-chains/references/polygon.md)): `USDC` (6), `WETH` (18), `WPOL` (18)
+- **Monad** (`monad`, [addresses](../../sauce-chains/references/monad.md)): `USDC` (6), `WMON` (18)
+- **Arc** (`arc`, [addresses](../../sauce-chains/references/arc.md)): `EURC` (6), `USDC` (6), `USYC` (6), `WETH` (18)
+- **Base** (`base`, [addresses](../../sauce-chains/references/base.md)): `USDC` (6), `WETH` (18); and 67 tokenized stocks ([stocks](stocks.md))
+- **Arbitrum** (`arbitrum`, [addresses](../../sauce-chains/references/arbitrum.md)): `USDC` (6), `WETH` (18)
+- **Solana** (`solana`, [addresses](../../sauce-chains/references/solana.md)): `PYUSD` (6), `USDC` (6), `USDT` (6), `WSOL` (9)
+
+On Solana a symbol is the mint's 32-byte key, a value for the `@sauce/token` functions
+(`balanceOf(USDC, account)`); the token accounts are `Account` parameters, and the token
+methods (`USDC.transfer(...)`) are EVM-only. Devnet's mints, which differ, are in the Solana
+file in `sauce-chains`, passed as a define that wins over the symbol. That file also names each
+mint's token program: legacy SPL Token, or Token-2022, whose mints a program moves with the
+checked writes (`sauce-solana`).
+
+## Token functions
+
+Every program can call these `@sauce/token` functions with no import. The EVM writes are
+SafeERC20: a token that returns nothing works, and one that returns `false` reverts.
+
+On EVM chains:
+
+- `balanceOf(token: Address, account: Account): Uint256`
+- `totalSupply(token: Address): Uint256`
+- `decimals(token: Address): Uint256`
+- `allowance(token: Address, owner: Address, spender: Address): Uint256`
+- `transfer(token: Address, to: Address, amount: Uint256): void`
+- `transferFrom(token: Address, from: Address, to: Address, amount: Uint256): void`
+- `approve(token: Address, spender: Address, amount: Uint256): void`
+- `permit(token: Address, owner: Address, spender: Address, value: Uint256, deadline: Uint256, v: Uint256, r: Uint256, s: Uint256): void`
+- `permitTransferFrom(token: Address, owner: Address, amount: Uint256, nonce: Uint256, deadline: Uint256, signature: bytes, permit2: Address): void`
+
+On Solana:
+
+- `balanceOf(token: Address, account: Account): Uint256`
+- `ownerOf(token: Address, account: Account): Address`
+- `totalSupply(token: Account): Uint256`
+- `decimals(token: Account): Uint256`
+- `allowance(token: Address, account: Account, spender: Address): Uint256`
+- `transfer(token: Address, tokenProgram: Account, source: Account, dest: Account, authority: Account, amount: Uint256): void`
+- `transferFrom(token: Address, tokenProgram: Account, source: Account, dest: Account, authority: Account, amount: Uint256): void`
+- `approve(token: Address, tokenProgram: Account, source: Account, delegate: Account, authority: Account, amount: Uint256): void`
+- `transferChecked(token: Address, tokenProgram: Account, source: Account, mint: Account, dest: Account, authority: Account, amount: Uint256, decimals: Uint256): void`
+- `approveChecked(token: Address, tokenProgram: Account, source: Account, mint: Account, delegate: Account, authority: Account, amount: Uint256, decimals: Uint256): void`

package/skills/sauce-intents/SKILL.md

@@ -0,0 +1,505 @@
+---
+name: sauce-intents
+description: Cross-chain intents written in Sauce — a file that is the intent, Base(() => { ... }).reward({ ... }) as top-level statements with no main and its values as defines; how an intent is published, funded, discovered, filled, proven, claimed, cancelled and refunded (a sauce intent command each) (the intent hash, the per-intent vault, IntentPublished and IntentFunded, isIntentFunded); every way to publish and fund it (sauce intent publish from a wallet, sauce run from a Pot, a transfer into the vault then publish, cascade children, quoted intents); amounts measured on chain; token-only bodies versus program bodies; the delivery; on which chain each name resolves; the shared destination Pot and the Kitchen fee the solver pays; rehearsing both sides; and the deadline and creator every intent needs. Use when a program should continue on another chain, forward a swap or bridge output, build a cascade, pay a solver, or when the user mentions intents, rewards, vaults, solvers, Portals, provers, Executors or Pots.
+---
+
+# Cross-chain intents in Sauce
+
+An intent is an **offer**: run this on the destination chain, and the reward escrowed on this chain
+is yours. An intent file is written as **top-level statements, with no `main`**: the chain name
+called as a function opens the intent, and every value the file does not compute is a define, left
+undeclared in the file and set with `--define NAME=VALUE` (`sauce-script`).
+
+```sauce chain=base define=RECIPIENT,AMOUNT
+Ethereum(() => {
+  USDC.transfer(RECIPIENT, AMOUNT); // Ethereum's USDC: the body runs there
+}).reward({ tokens: [{ token: USDC, amount: AMOUNT }] }); // the source chain's USDC
+```
+
+Nothing about the fill is guaranteed: a solver decides whether the reward is worth it, and the
+package prices nothing. Say an intent is _offered_, never that it _will execute_.
+
+## Supported chains
+
+For the initial release, intents are published, and every step of their life sent, only between
+**Ethereum, Base and Solana**, the chains Sauce supports transactions on. Every other chain in the
+registry is a **preview chain**: an intent that involves one still compiles, `sauce inspect` lists
+it, and `sauce intent publish --dry-run` and `sauce intent fill` without `--send` rehearse it, but
+the `sauce` command and its MCP server build and send none of its transactions. They refuse before
+anything is built, signed or sent:
+
+- **Publishing** — `sauce intent publish` (sent, or printed with `--format`), and `sauce run` or
+  `sauce tx` of a file that opens the intent — is refused unless the source and every destination
+  it opens are supported. The later levels of a cascade are not checked: keep every level on a
+  supported chain.
+- **Each later step** is refused by the chain it is sent on: `fill --send`, `prove` and `cancel` by
+  the destination; `claim` and `refund` by the source.
+
+The refusal names the supported chains and links the request for that chain (an MCP tool returns it
+as `refused`, with the issue's title, body and a comment to post). To ask for a chain, find its
+request among the existing ones
+(https://github.com/eco-incorp/sauce/issues?q=is%3Aissue+label%3Achain-support) and add the use case
+as a comment, or open one from the form
+(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, and the volume expected and when.
+
+## The lifecycle
+
+An intent is three values: the **destination** chain, the **route** (what runs there: a salt, the
+route's deadline, the destination Portal, `nativeAmount`, the tokens the solver delivers, and the
+calls) and the **reward** (its deadline, the creator, the prover, a native amount and tokens). Its
+hash is `keccak256(abi.encodePacked(uint64 destination, keccak256(route bytes), keccak256(abi.encode(reward))))`,
+so every field is in it: the deadlines and the destination Kitchen's fee (the route's
+`nativeAmount`) too. **Changing any of them is a different intent**: rebuild every transaction,
+including any unsigned one printed earlier.
+
+1. **Fund.** The reward sits in the intent's own **vault** on the source chain. Its address follows
+   from the intent hash, so it exists before anything is published or deployed:
+   `Portal.intentVaultAddress(destination, route, reward)` returns it, and tokens sent there count.
+2. **Publish.** `Portal.publish` records the intent and emits `IntentPublished`, which solvers
+   watch. It needs no funding and anyone may send it; sending it again re-emits the event.
+3. **Discover and check.** A solver picks the intent up from `IntentPublished` (or, for an intent
+   it quoted, from `IntentFunded`) and calls `Portal.isIntentFunded(destination, route, reward)`:
+   true when the intent's status is Funded **or** the vault already holds the whole reward. A
+   solver that finds it unfunded may retry for a while, then drop it: fund before or with the
+   publication.
+4. **Fill.** On the destination the solver calls the destination Portal's `fulfill`, sending the
+   route's `nativeAmount` as value and delivering the route's tokens; the Portal's Executor runs the
+   calls. Before the route's deadline, once. `fulfillAndProve` does the same and sends the proof in
+   the same transaction, its value the `nativeAmount` plus the prover's fee.
+5. **Prove.** The destination Portal's `prove(prover, sourceDomain, intentHashes, data)` hands what
+   it recorded (the claimant, or a cancellation) to the destination's prover, which sends it to the
+   reward's prover on the source chain for a fee it quotes (`fetchFee`). With Hyperlane, a relayer
+   delivers the message; the source prover then records the claimant, which
+   `provenIntents(intentHash)` returns.
+6. **Claim.** Once the source has the proof, `withdraw(destination, routeHash, reward)`, sent by
+   anyone, pays the vault's reward to the claimant the proof names (`batchWithdraw` claims several).
+7. **Refund.** After the reward's deadline, with no proven fill, `refund(destination, routeHash,
+reward)`, sent by anyone, returns everything the vault holds of the reward to the creator (the
+   creator alone may send `refundTo` to choose another recipient). Before the deadline it reverts
+   `InvalidStatusForRefund`. A vault that was funded but never published refunds the same way.
+8. **Cancel, for an earlier refund.** Where the destination Portal has `cancel`, anyone may cancel
+   an unfilled intent strictly after the route's deadline: no fill can land after it. Proving the
+   cancellation (5) lets the creator refund at once, before the reward's deadline. A cancellation is
+   recorded as a claimant no key controls, so the source Portal must refuse to pay it
+   (`withdraw` reverting `CancelledIntent`); prove one only to a source Portal that does. Prove it
+   once the cancel is final on the destination: a reorg that let a fill in first would leave that
+   solver unpaid.
+
+## Every step from the command line
+
+`sauce intent` drives the whole lifecycle. Each verb takes the intent file (with `--chain`, the
+source, and the flags it was built with) or the intent's hash, and `--config sauce.config.json`
+with both chains' endpoints. Every intent the commands publish, fill or import goes into a local
+store in your home directory (`--store <dir>` names another), so later steps name it by hash; where it
+stands is read from the chains each time.
+
+```sh
+npx sauce intent publish --config sauce.config.json --keystore <keystore>
+npx sauce intent status <intent-hash> --config sauce.config.json
+npx sauce intent fill <intent-hash> --config sauce.config.json --send --keystore <keystore>
+npx sauce intent prove <intent-hash> --config sauce.config.json --keystore <keystore>
+npx sauce intent claim <intent-hash> --chain <source> --config sauce.config.json --keystore <keystore>
+npx sauce intent refund <intent-hash> --chain <source> --config sauce.config.json --keystore <keystore>
+npx sauce intent cancel <intent-hash> --config sauce.config.json --keystore <keystore>
+npx sauce intent import <tx-hash> --chain <source> --config sauce.config.json
+```
+
+- `publish` with no file asks, at a terminal, for the chains, the token and amount delivered and
+  to whom, the reward (suggested: what is delivered plus a margin over the solver's destination
+  costs), the deadlines, the prover and how the reward is funded (a transfer to the vault by
+  default), writes the intent as a `.sauce.ts` file, rehearses publishing and filling it, and
+  publishes it once approved. Each question has a flag (`--source`, `--destination`, `--token`,
+  `--amount`, `--recipient`, `--reward-token`, `--reward`, `--prover`, `--fill-deadline`,
+  `--reward-deadline`, `--intent-fund-via`), so it runs without a terminal.
+- `status` prints the intent's state on both chains (unfunded, funded, filled, cancelled, proven,
+  cancelProven, claimed, refunded), its deadlines, and whether each next step can be taken now,
+  with why not and from when. An intent funded by a transfer into its vault counts as funded,
+  though the Portal's status for it stays Initial.
+- `fill --send` fills it as a solver, from the signer: rehearsed first on the signer's real
+  balances and not sent if it reverts, and what it spends (each delivered token, and the value)
+  shown for approval (`--auto-approve` approves). It sends the approvals (zero first where a smaller one
+  stands), then `fulfillAndProve` with the prover's fee, or `fulfill` with `--no-prove`. It prints
+  the Hyperlane message the proof travels as.
+- `prove` sends the proof of a filled or cancelled intent, paying the prover's fee; `claim` pays the
+  reward once the source has the proof, and says so, with the message's id, while it has not;
+  `refund` returns the reward when the Portal allows it, and says from when otherwise; `cancel`
+  cancels after the route's deadline, refusing where either Portal lacks the cancellation support
+  described above.
+- Without a signer, each prints its transactions unsigned, for a wallet to send in order.
+- `sauce intent` alone, at a terminal, lists the stored intents with where each stands, and runs
+  these on the one picked.
+
+**An intent to Solana.** An intent Ethereum or Base publishes for Solana is filled, proven and
+cancelled on Solana, through its Portal program, and claimed or refunded on its source as above.
+The config gives Solana's endpoint under its chain id, `1399811149`.
+
+```sh
+npx sauce intent import <tx-hash> --chain <source> --config sauce.config.json
+npx sauce intent fill <intent-hash> --config sauce.config.json --solver <solana-key> --claimant <address>
+npx sauce intent fill <intent-hash> --config sauce.config.json --claimant <address> --send --keypair <keypair>
+npx sauce intent cancel <intent-hash> --config sauce.config.json --keypair <keypair>
+```
+
+- `--claimant` is required: the address on the source chain the reward pays. A Solana key is not
+  one.
+- The rehearsal runs on the solver's accounts as they are, since Solana's simulation takes no
+  overrides: the solver must hold the route's tokens.
+- `fill --send` sends the fill, then the proof through the HyperProver, with Hyperlane's gas paid in
+  the same transaction. Each spend is approved.
+- `prove` and `cancel` sign with `--keypair`, which pays their fee. A cancellation's proof waits
+  until the slot that cancelled it is finalized.
+
+The Portal's functions, events and errors, with selectors and topics, are in
+[references/portal.md](references/portal.md).
+
+## Names resolve per chain
+
+The file is compiled for the **source** chain, the one that pays the reward (`--chain`).
+
+- **In `.reward(...)`**, names are the source chain's, which funds and escrows the reward: `USDC`
+  there is the source chain's USDC. A reward token must be known when the file is compiled: a
+  symbol, or a token's address on the source chain as a literal, a define or a top-level `const` of
+  a literal. Its amount may be a measured value.
+- **Inside the braces, and in the delivery argument**, the code runs on the destination, and every
+  name a chain supplies resolves there: in an `Ethereum(...)` body, `USDC` is Ethereum's USDC,
+  `AaveV3.Pool` is Ethereum's pool, and `chainId` and a `Namespace_Contract` define are Ethereum's.
+  The tokens a destination has are listed in
+  [../sauce-globals/references/tokens.md](../sauce-globals/references/tokens.md), with their
+  addresses in the destination's file in `sauce-chains`
+  ([../sauce-chains/references/ethereum.md](../sauce-chains/references/ethereum.md) for Ethereum).
+- **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.
+- **Name a token by a symbol, a literal, a define or a top-level `const` of a literal.** Any other
+  top-level `const` holding a token's address (`const TOKEN = USDC;`), used in the reward or the
+  delivery, counts as a value the program computes, so the compile refuses the intent, saying the
+  token's address must be known when the intent is built, and so does `sauce intent publish`. A
+  `const` inside the braces is fine.
+- A literal address means that address everywhere, and so does a define whose name no chain uses
+  (`RECIPIENT`). A define under a chain-scoped name (`USDC`, `chainId`, a protocol address) is a
+  name on the source chain: it applies to the file's own statements and the reward, and a body on
+  another chain keeps that chain's value.
+
+## Publishing and funding
+
+| Way                                       | What is sent                                                                                     | Emits                             | Choose it when                                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------- | ----------------------------------------------------------------------------------- |
+| (a) From a wallet, `sauce intent publish` | a transfer of each reward token to the intent's vault, then `publish`: no approval               | `IntentPublished`                 | every amount is known when you build it, and a wallet pays                          |
+| (b) From a Pot, `sauce run`               | the same, by the Pot, inside the cook, with the vault read from the Portal                       | `IntentPublished`                 | an amount is measured on chain, or the intent must open atomically with other steps |
+| (c) Transfer into the vault, by hand      | a token transfer to `intentVaultAddress(...)`, then `publish`, for an intent you encode yourself | `IntentPublished`                 | the intent was not built from a file the package compiles                           |
+| `--intent-fund-via publishAndFund`        | (a) or (b) with `approve(Portal, reward)` per token, then `publishAndFund`                       | `IntentPublished`, `IntentFunded` | an intent built from a solver's quote (below)                                       |
+
+Funding by transfer needs no approval, so no allowance is left standing and USDT needs nothing
+special. The vault counts whatever it holds, so `isIntentFunded` is true from the moment the
+transfer lands; the intent's status stays Initial (only `publishAndFund` or `fund` set Funded), and
+`isIntentFunded`, the check solvers make, accepts either. The reward always goes into the vault
+**before** `publish` is sent, so a solver that sees `IntentPublished` finds the intent funded.
+
+**(a) From a wallet.** `sauce intent publish` builds each intent before anything runs, so every amount
+must be a literal, a define or a top-level `const` of a literal, and the file may do nothing but
+open intents (a file with an amount measured or computed on chain is refused, with `sauce run` named
+instead). For each intent it computes the vault from the
+Portal's address and the intent and, with an endpoint, reads it from the Portal's
+`intentVaultAddress`: the two must agree, or nothing is sent. The wallet then transfers each reward
+token to the vault (and sends a native reward to it), only what the vault does not hold yet, and
+calls `publish(destination, route, reward)` once the Portal reports the intent funded. A token whose
+transfer returns `false` stops it there, before the intent is published, with what was paid still
+in the vault: top it up and run it again, or `refund` after the deadline. A second run that finds
+the vault funded only publishes.
+
+```sh
+npx sauce intent publish pay-on-ethereum.sauce.ts --chain base --config sauce.config.json \
+  --from <address> --dry-run --assume-balance USDC:1 --define RECIPIENT=<address> \
+  --define AMOUNT=1000000 --intent-deadline <unix seconds> --intent-creator <address>
+npx sauce intent publish pay-on-ethereum.sauce.ts --chain base --from <address> --format json \
+  --define RECIPIENT=<address> --define AMOUNT=1000000 \
+  --intent-deadline <unix seconds> --intent-creator <address>
+```
+
+- `--dry-run` rehearses the transfers and `publish` together from the wallet, then reports what
+  `isIntentFunded` returns after them, and sends nothing; `--assume-balance USDC:1` (whole tokens)
+  gives the wallet the reward for the rehearsal only, so a wallet that does not hold it yet can
+  rehearse. Without `--dry-run`, `--keystore <keystore>` in place of `--from` signs and sends them.
+- `--format json` (or `cast`) with `--from` and no signer prints the transactions, unsigned, for that
+  wallet to send in order, transfers first, with each intent's `vault`. With no endpoint the vault
+  is the package's own computation and each transfer is for the whole reward; with one, the vault
+  is also read from the Portal and only what it does not hold yet is transferred. Send `publish`
+  only once the transfers have landed.
+
+**(b) From a Pot.** `sauce run` cooks the file on your Pot, and opening the intent is one of its
+steps: in the same transaction as everything else, the Pot reads the intent's vault from the Portal
+(`intentVaultAddress` over the very bytes it then publishes), transfers each reward token there,
+sends a native reward, and calls `publish`, so nothing is published unless the whole cook succeeds,
+and a token whose transfer returns `false` reverts it. Values measured while it runs can flow into the intent: in
+`const amount = USDC.balanceOf(ctx.self())`, `amount` does not exist until the program runs, and
+using it inside the braces, in the delivery or in the reward is enough. The package encodes the
+intent with a slot for it, and the program writes the measured value in before it publishes. Any
+one-word value can be carried this way.
+
+```sh
+npx sauce run cross-chain.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+  --define BENEFICIARY=<address> --intent-deadline <unix seconds> --intent-creator <address> \
+  --intent-execution-fee <wei>
+```
+
+**(c) Transfer into the vault, by hand.** (a) and (b) do this for every intent a file opens. For an
+intent encoded some other way, do the same in one cook, with the program reading the vault from the
+Portal itself so it cannot be wrong:
+[examples/fund-by-transfer.sauce.ts](examples/fund-by-transfer.sauce.ts) takes the intent as
+`publish`'s three arguments, transfers each reward token to
+`intentVaultAddress(destination, route, reward)` and calls `publish(destination, route, reward)`,
+which returns the intent hash and the vault. For an intent file, those three arguments are the
+arguments of the `publish` that `sauce intent publish … --from <address> --format json` prints; decode them
+with its signature (in [references/portal.md](references/portal.md)).
+
+```sh
+npx sauce run fund-by-transfer.sauce.ts --chain base --config sauce.config.json \
+  --keystore <keystore> --args <portal> <destination> <route> <reward>
+```
+
+- **From a wallet**, it is two transactions: **transfer first, then publish**, so a solver that sees
+  `IntentPublished` finds the intent funded. If the publish fails or is never sent, nothing is lost:
+  publish later (the vault still holds the reward), or `refund` after the deadline.
+- **What the CLI emits**: `sauce intent publish` and `sauce run` fund every intent this way by default, as
+  (a) and (b) describe; `--intent-fund-via publishAndFund` gives the approve and `publishAndFund`
+  instead.
+- A native reward (`reward.nativeAmount`) is native coin sent to the vault the same way, by
+  `sauce intent publish` and `sauce run` alike; the example funds tokens only and refuses a native reward.
+
+**Quoted intents.** A solver that quoted an intent marks its quote funded when it sees
+`IntentFunded`, which only `publishAndFund` and `fund` emit. For an intent built from a solver's
+quote, fund it with `publishAndFund`: (a) or (b) with `--intent-fund-via publishAndFund`, not by
+transfer. The wallet then approves each reward token to the **Portal** for exactly the reward (with
+an endpoint, a smaller allowance already standing is reset to zero first, as USDT requires), and
+`publishAndFund(destination, route, reward, false)` pulls the reward into the same vault and marks
+the intent Funded; from a Pot, the same happens inside the cook.
+
+`sauce inspect <file> --chain <chain>` with the same defines and intent flags prints each intent
+the file opens: its destination, hashes, the route's calls and the reward, with every measured value
+named.
+
+## Two kinds of body
+
+| The body is…                                                                                                | Lowers to                                                    | Needs                                                                  | Token writes                                                                              |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| only `transfer`/`approve` calls on a symbol or `Token(address)`, with literal, define or captured arguments | plain calls the destination Portal's Executor makes          | nothing more: no Pot, no Kitchen fee                                   | USDT works and `approve` is reset to zero first, but a `false` return is **not** detected |
+| anything else: a local, a balance read, a condition, a protocol call, `transferFrom`, a nested intent       | a program compiled for the destination and cooked on its Pot | the destination's Kitchen fee, and the delivery as the second argument | SafeERC20: a `false` return reverts the fulfilment                                        |
+
+The Executor checks only that each call did not revert, so a token-only body's transfer that
+returns `false` fills the intent with nothing moved; a call with data to an address with no code
+reverts `CallToEOA`. A program body must say what the solver delivers, because a balance read
+inside it reads what is there, not what must be brought:
+
+```sauce chain=base define=BENEFICIARY
+const amount = USDC.balanceOf(ctx.self());
+const delivered = amount - (amount * 10n) / 10000n;
+Ethereum(
+  () => {
+    USDC.approve(AaveV3.Pool, delivered);
+    AaveV3.Pool.supply(USDC, delivered, BENEFICIARY, 0n);
+  },
+  { tokens: [{ token: USDC, amount: delivered }] },
+).reward({ tokens: [{ token: USDC, amount }] });
+```
+
+The gap between `delivered` (brought on Ethereum) and `amount` (paid on Base) is the solver's
+margin. Make it worth filling.
+
+## A whole program as the body
+
+The body can be any program for the destination. It is written inside the braces and uses the
+file's defines as values. It may also use what the file declares: its imports (an ABI, a library)
+and its helper functions, each compiled into the body's program for the destination. It calls
+contracts as any program does (`sauce-script`): by namespace (`UniswapV3.Factory.getPool(...)`),
+through a registry ABI import, or through an ABI of the file's own imported at its top. A swap is a
+`@sauce/router`
+call (`sauce-swaps`), imported at the top of the file. Every unsold input and every output leaves the destination Pot
+before the body ends, and a refund the body makes lands on the destination chain. The body runs on
+the shared intent Pot, which holds nothing of anyone's between intents, so it may return a token's
+whole balance there, as the refunds below do; a program on an owner's Pot returns only what is left
+of its own amount instead (`sauce-distributed-swap`).
+
+A one-pool swap, with the guard every swap needs (`sauce-swaps`): WETH a solver delivers on Base is
+sold on the Uniswap V3 0.05% pool down to `SQRT_PRICE_LIMIT_X96`, at least `MIN_OUT` USDC goes to
+`RECIPIENT`, and any unsold WETH to `REFUND_TO`, on Base. A fill below `MIN_OUT` reverts the whole
+fulfilment, so set it from the limit (`sauce-distributed-swap` has the recipe), never above what the
+pool can pay.
+
+```sauce chain=ethereum define=AMOUNT_IN,REWARD,SQRT_PRICE_LIMIT_X96,MIN_OUT,RECIPIENT,REFUND_TO
+import { uniswapV3 } from "@sauce/router";
+
+Base(
+  () => {
+    const pool = UniswapV3.Factory.getPool(WETH, USDC, 500n); // Base's 0.05% tier
+    require(pool != 0n, "no WETH/USDC pool at 0.05%");
+    // Pays RECIPIENT the USDC, and reverts the whole fulfilment below MIN_OUT.
+    uniswapV3(pool, WETH, USDC, AMOUNT_IN, SQRT_PRICE_LIMIT_X96, MIN_OUT, RECIPIENT);
+    const unsold = WETH.balanceOf(ctx.self()); // the shared Pot: return all of it
+    if (unsold > 0n) {
+      WETH.transfer(REFUND_TO, unsold);
+    }
+  },
+  { tokens: [{ token: WETH, amount: AMOUNT_IN }] }, // Base's WETH, which the solver delivers
+).reward({ tokens: [{ token: WETH, amount: REWARD }] }); // the source chain's WETH
+```
+
+`REWARD` must exceed what the solver delivers, `AMOUNT_IN`, by what filling costs it (below). To buy
+WETH instead, swap `USDC` for `WETH` and deliver USDC: USDC is token1 on Base, so the limit is then
+a ceiling, the `buy` block of `sauce price`.
+[examples/swap-on-base.sauce.ts](examples/swap-on-base.sauce.ts) is the same with a distributed
+swap as the body (`sauce-distributed-swap`): one pass over every Uniswap V3 and hookless V4 pool of
+the pair, each offered the WETH still unsold up to its own fee-adjusted limit, and skipped when it
+has no liquidity or is past that limit. It swaps through `@sauce/router`, finds each V3 pool with
+`UniswapV3.Factory.getPool` and reads it as `UniswapV3.Pool(pool)`, and reads the V4 pools from
+`UniswapV4.StateView`.
+
+## Cascades
+
+An intent's body can open the next one. Each level's amounts are measured at that level's own
+execution and carried into the level below; no amount past the first exists when the user signs.
+
+```sauce chain=base define=RECIPIENT
+const amount = USDC.balanceOf(ctx.self());
+Ethereum(
+  () => {
+    const arrived = USDC.balanceOf(ctx.self()); // Ethereum's USDC
+    Base(() => {
+      USDC.transfer(RECIPIENT, arrived); // Base's USDC
+    }).reward({ tokens: [{ token: USDC, amount: arrived }] }); // Ethereum's: it funds this level
+  },
+  { tokens: [{ token: USDC, amount }] },
+).reward({ tokens: [{ token: USDC, amount }] });
+```
+
+Each level is a separate fulfilment by a solver, later, on its own chain: a failure on a later hop
+does not undo an earlier one. The child is published and funded **by the parent's body**, as (b)
+above: when the Ethereum level runs, the shared Pot there pays the next level's reward into its
+vault on Ethereum's Portal from what it holds, in Ethereum's USDC, and calls `publish`, so the child
+is published like any other intent and any solver can discover it. Keep every level on a supported
+chain, as here (Base, Ethereum, then Base again): the command checks the first level's chains only.
+Each level's deadline must be no
+earlier than its parent's. (The TypeScript cascade builder, `.nest()` in `sauce-typescript`, also
+funds a child by a transfer into its vault by default, but with no publication of its own, and
+takes `publishAndFund` as an option.)
+
+## What the compile supplies, and what you pass
+
+The Portal, the prover, the destination Pot and the encoding are looked up from the eco-routes
+registry, which records each chain's Portal and a prover deployed on both sides. Each chain's file in
+`sauce-chains` says whether it takes intents and gives its Portal, Executor and shared intent Pot
+([../sauce-chains/references/index.md](../sauce-chains/references/index.md)). Three values are the
+developer's:
+
+- **`--intent-deadline <unix seconds>`**: when the intent must be filled by.
+- **`--intent-creator <address>`**: who may reclaim an unearned reward. Never a Pot.
+- **`--intent-execution-fee <wei>`** for a program body: the destination Kitchen's fee. It is
+  mutable on chain and lives on the destination, so read it there just before sending: an
+  `eth_call` of `executionFee()` on the destination's Kitchen (its address is in the chain's file in
+  `sauce-chains`), or pass `--intent-execution-fee auto`, which reads it through `--config`. An
+  increase before the fill makes the cook, and the fulfilment, revert.
+
+**Units and defines.** Amounts are base units (`AMOUNT=1000000` is 1 USDC); only `--assume-balance`
+and `--fund` take whole tokens. In a `--defines` file, write an address or any value past 2^53 as a
+JSON string (`"AMOUNT_IN": "1000000000000000000"`): a JSON number loses precision. The intent file
+stays top-level statements with no `main`, so every input is a define.
+
+Refused at compile time, never silently changed: a name that is neither a define nor a program
+variable, a missing deadline, creator or fee, a chain with no eco-routes deployment, a pair with no
+prover deployed on both sides.
+
+## The destination side
+
+- **The shared Pot.** A program body cooks on the destination Portal Executor's **shared Pot** (its
+  owner is the Executor, its salt zero); the destination's file in `sauce-chains` gives the Pot and
+  the Executor. **The Pot must exist before any fill**: until it does, every fulfilment of a program
+  body reverts (`CallToEOA`). `npx sauce pot --chain <destination> --owner <Executor>` prints its
+  address and deploy transaction; with `--deploy --config sauce.config.json --keystore <keystore>`
+  any signer deploys it (the Pot is the Executor's either way), and an existing one is reported, not
+  redeployed; `sauce intent fill` says whether it is deployed on the destination, and deploys it in its
+  rehearsal when it is not. Anything left in the Pot after the program, token or allowance, belongs
+  to the next intent through that Portal: approve exactly what is spent and move every remainder
+  out.
+- **What the solver pays.** The Kitchen fee becomes the route's `nativeAmount`: the solver sends it,
+  in the destination's native coin, as the value of `fulfill`, and pays the destination gas too.
+  Nothing in the reward pays either back, so the margin (the reward minus what the solver delivers)
+  must cover both; a body that reads and swaps on many pools costs a lot of gas, so measure it in a
+  rehearsal (below). Solvers apply checks of their own, such as the reward covering the route's
+  tokens plus their fee, and decide which routes they fill.
+- **Refunds of unsold input land on the destination**, where the body runs.
+
+## Rehearse both sides before a solver does
+
+- **The source side**: `sauce intent publish --dry-run --assume-balance …` (above) rehearses the transfers
+  into the vault and `publish`; `sauce simulate` rehearses a file run from a Pot.
+- **The fill, on the destination**: the body runs there, when a solver fills the intent, and that is
+  where a swap misses its minimum or a refund fails. Rehearse it with `sauce intent fill`, the same file
+  and flags, before publishing; it signs nothing and sends nothing:
+
+```sh
+npx sauce intent fill swap-on-base.sauce.ts --chain <chain> --config sauce.config.json \
+  --defines <defines.json> --intent-deadline <unix seconds> --intent-creator <address> \
+  --intent-execution-fee <Base Kitchen fee in wei>
+```
+
+On each intent's destination it runs, in one simulated block, what a solver sends: the shared
+Pot's deployment when the body cooks on it and nobody has deployed it yet, the solver's approval
+of the destination Portal for the delivered tokens, then `Portal.fulfillAndProve` with the
+Kitchen's fee and the prover's fee as its value (or `Portal.fulfill` with the Kitchen's fee alone,
+with `--no-prove` or a prover it does not drive). The solver is given the delivered tokens for the rehearsal only. It prints each
+transfer, each address's net change (an address a define holds is named by the define) and what
+the shared Pot and the Executor were left holding, which must be nothing; or why the fill
+reverts, down to the body's own `require` message. It warns when the shared Pot is not deployed,
+and when `--intent-execution-fee` is below the destination Kitchen's fee, naming the fee to pass.
+`--config` must name the destination chain's endpoint (`--rpc-url` works when every intent goes
+to one chain, and is then that chain's endpoint). An intent that uses a value measured on chain
+cannot be rehearsed this way: its route exists only once the program runs. Fix what it reports
+and rehearse again before `sauce intent publish` or `sauce run`. With `--send` and a signer,
+`sauce intent fill` then fills it for real (above).
+
+- **The body alone, as a program**: copy the body (what is inside the braces) into a file of its own,
+  top-level statements with the same defines, and rehearse it as a program for the destination,
+  with the delivered tokens assumed in the Pot. It runs on your Pot instead of the shared one, but
+  executes the same calls, shows what moves, and gives the gas:
+
+```sh
+npx sauce simulate one-pool-body.sauce.ts --chain base --owner <address> \
+  --config sauce.config.json --assume-balance WETH:0.001 --define AMOUNT_IN=1000000000000000 \
+  --define SQRT_PRICE_LIMIT_X96=<sqrtPriceX96> --define MIN_OUT=<amount> \
+  --define RECIPIENT=<address> --define REFUND_TO=<address>
+```
+
+- **The fill by hand**, as a solver sends it, on a fork of the destination
+  (`anvil --fork-url <destination endpoint>`), with any client:
+  1. Get the intent: `sauce inspect <file> --chain <source> --json`, with the same defines and
+     intent flags, prints each intent's `intentHash`, `routeHash`, `rewardHash`, route and reward;
+     the raw route bytes are the `route` argument of the `publish` that
+     `sauce intent publish <file> … --from <address> --format json` prints (their keccak-256 is
+     `routeHash`).
+  2. Make sure the shared Pot exists (above).
+  3. Hold the route's `tokens` in an account and approve the **destination** Portal for each;
+     `fulfill` pulls them from the sender.
+  4. From that account, call the destination Portal's
+     `fulfill(bytes32 intentHash, Route route, bytes32 rewardHash, bytes32 claimant)` with **value =
+     the route's `nativeAmount`**, the route decoded from its bytes and the claimant the solver's
+     address as 32 bytes. Less value reverts `InsufficientNativeAmount(sent, required)`, a missing
+     Pot `CallToEOA(<Pot>)`, and a body that reverts surfaces as the Executor's `CallFailed`, with
+     the body's own reason inside.
+  5. Read the outcome: what the recipient got, what was refunded, the gas, and that the Pot holds
+     nothing.
+
+Solana destinations are not built this way (see `sauce-solana`). An application can also build an
+intent from TypeScript around a program it compiles itself (`sauce-typescript`).
+
+## Examples
+
+- [examples/cross-chain.sauce.ts](examples/cross-chain.sauce.ts) forwards the Pot's USDC to Aave on
+  Ethereum. It measures its amount, so it runs from a Pot.
+- [examples/swap-on-base.sauce.ts](examples/swap-on-base.sauce.ts) is the distributed swap as the
+  body of an intent to Base, opened from Ethereum. Its amounts are defines, so it can be run from a
+  Pot or published from a wallet.
+- [examples/fund-by-transfer.sauce.ts](examples/fund-by-transfer.sauce.ts) funds an intent by a
+  transfer into its vault and publishes it, in one cook on a Pot.
+- [examples/intents.mts](examples/intents.mts) compiles the intent files, with the deadline, the
+  creator, Base's and Ethereum's fees and the recipient as developer inputs, and pins on which chain
+  each name resolves, the fee requirement, the token-only case, the pool ABI's selectors, and the
+  rehearsal's transactions: the Pot's deploy and `fulfill` with the fee as its value.

package/skills/sauce-intents/examples/cross-chain.sauce.ts

@@ -0,0 +1,37 @@
+// Forwards the USDC this Pot holds to Ethereum, where a solver supplies it to Aave V3 for
+// BENEFICIARY. The amount is only known when this runs, so the file runs on the owner's Pot (sauce
+// run) and opens the intent as it goes. The whole file is the program: top-level statements, no
+// main, and BENEFICIARY a define.
+//
+// `--chain` is the source chain, which funds the reward: `USDC` in `.reward(...)` is its USDC.
+// Inside the braces, and in the delivery argument after them, the code runs on Ethereum: `USDC` and
+// `AaveV3.Pool` there are Ethereum's. The gap between what is delivered and the reward is the
+// solver's margin.
+//
+//   sauce run cross-chain.sauce.ts --chain <chain> --config sauce.config.json \
+//     --keystore <keystore> --define BENEFICIARY=<address> --intent-deadline <unix seconds> \
+//     --intent-creator <address> --intent-execution-fee <Ethereum Kitchen fee in wei>
+//
+//   BENEFICIARY: Address               who the Aave V3 position on Ethereum is supplied for
+//   --intent-deadline: unix seconds    the last second a solver may fill it
+//   --intent-creator: Address          who may reclaim the reward if no solver earns it
+//   --intent-execution-fee: wei        Ethereum's Kitchen fee for the body's cook; `auto` reads it
+//                                      through --config
+//
+// From Base, with the fee read from Ethereum:
+//
+//   sauce run cross-chain.sauce.ts --chain base --config sauce.config.json \
+//     --keystore <keystore> --define BENEFICIARY=<address> --intent-deadline <unix seconds> \
+//     --intent-creator <address> --intent-execution-fee auto
+require(BENEFICIARY != 0n, "set BENEFICIARY");
+const amount = USDC.balanceOf(ctx.self());
+require(amount > 0n, "nothing to forward");
+const delivered = amount - (amount * 10n) / 10000n; // the solver keeps 0.1%
+
+Ethereum(
+  () => {
+    USDC.approve(AaveV3.Pool, delivered);
+    AaveV3.Pool.supply(USDC, delivered, BENEFICIARY, 0n);
+  },
+  { tokens: [{ token: USDC, amount: delivered }] },
+).reward({ tokens: [{ token: USDC, amount }] });