@eco-incorp/sauce 0.99.6 → 0.99.8

package/skills/sauce-distributed-swap/examples/distributed-swap.sauce.ts

@@ -0,0 +1,115 @@
+// A limit buy spread over Base's Aerodrome Slipstream and Uniswap V3 pools: spends up to `budget`
+// of `payToken` on `buyToken`, never paying more than `maxPrice` for any unit, fees included.
+// Returns abi.encode(spent, bought, unspent).
+//
+//   sauce run distributed-swap.sauce.ts --chain <chain> --config sauce.config.json \
+//     --keystore <keystore> --fund <payToken>:<budget> \
+//     --args <payToken> <buyToken> <budget> <maxPrice> <minTokens> <maxAvgPrice> \
+//     <recipient> <refundTo>
+//
+//   payToken: Address     the token paid; the budget must be in the Pot (`--fund` pulls it in)
+//   buyToken: Address     the token bought
+//   budget: Uint256       the most payToken to spend, in its base units: 1000000000 is 1,000 USDC
+//   maxPrice: Uint256     the most one buyToken may cost, fees included, as payToken base units per
+//                         buyToken base unit times 1e18: the price in whole tokens times
+//                         10^(18 + payDecimals - buyDecimals), so 150 USDC (6 decimals) for SPCXc
+//                         (8 decimals) is 150 × 10^16 = 1500000000000000000
+//   minTokens: Uint256    the least buyToken to receive, in its base units; less reverts the cook
+//   maxAvgPrice: Uint256  the most the average may cost, in maxPrice's units; 0 turns it off
+//   recipient: Address    receives what is bought
+//   refundTo: Address     receives what is left of the budget
+//
+//   Buying SPCXc (8 decimals) on Base with up to 1,000 USDC, at most 150 USDC each, at least 6.6
+//   SPCXc in all and an average of at most 149.5:
+//   sauce run distributed-swap.sauce.ts --chain base --config sauce.config.json \
+//     --keystore <keystore> --fund USDC:1000 \
+//     --args 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 0xb2000000000000000000007b9fcbd005511aCBd5 \
+//     1000000000 1500000000000000000 660000000 1495000000000000000 <recipient> <refundTo>
+import { uniswapV3 } from "@sauce/router";
+
+// One pool, from either venue: skipped when missing, empty or already past its own limit, else
+// offered all of the budget still unspent, up to its own limit. Returns what it bought.
+// `slipstream` picks the pool's ABI: a Slipstream pool's slot0 has no feeProtocol.
+function trade(
+  pool: Address,
+  slipstream: bool,
+  payToken: Address,
+  buyToken: Address,
+  kept: Uint256,
+  limit: Uint256,
+  recipient: Address,
+): Uint256 {
+  const unspent = Token(payToken).balanceOf(ctx.self()) - kept;
+  if (pool == 0n || unspent == 0n) {
+    return 0n;
+  }
+  let liquidity = 0n;
+  let price = 0n;
+  let fee = 0n;
+  if (slipstream) {
+    liquidity = AerodromeSlipstream.Pool(pool).liquidity();
+    price = AerodromeSlipstream.Pool(pool).slot0().sqrtPriceX96;
+    fee = AerodromeSlipstream.Pool(pool).fee();
+  } else {
+    liquidity = UniswapV3.Pool(pool).liquidity();
+    price = UniswapV3.Pool(pool).slot0().sqrtPriceX96;
+    fee = UniswapV3.Pool(pool).fee();
+  }
+  // The pool's own limit: the caller's moved by √(1 − fee), so that its last unit, fee paid,
+  // costs exactly maxPrice. Paying token0 pushes the price down, token1 pushes it up.
+  const paysToken0 = payToken < buyToken;
+  const root = Math.sqrt((1000000n - fee) * 10n ** 30n); // √(1 − fee), times 1e18
+  const own = paysToken0
+    ? Math.mulDiv(limit, 10n ** 18n, root)
+    : Math.mulDiv(limit, root, 10n ** 18n);
+  const better = paysToken0 ? price > own : price < own;
+  if (liquidity == 0n || !better) {
+    return 0n;
+  }
+  return uniswapV3(pool, payToken, buyToken, unspent, own, 0n, recipient);
+}
+
+function main(
+  payToken: Address,
+  buyToken: Address,
+  budget: Uint256,
+  maxPrice: Uint256,
+  minTokens: Uint256,
+  maxAvgPrice: Uint256,
+  recipient: Address,
+  refundTo: Address,
+): bytes {
+  const self = ctx.self();
+  const pay = Token(payToken);
+  require(maxPrice > 0n, "maxPrice is 0");
+  require(pay.balanceOf(self) >= budget, "budget is not in the Pot");
+  const kept = pay.balanceOf(self) - budget; // the Pot's other payToken, never spent
+  let bought = 0n;
+
+  // maxPrice as a pool's sqrt price (token1 per token0, times 2^96): where a unit costs maxPrice.
+  let limit = Math.sqrt(Math.mulDiv(maxPrice, 1n << 192n, 10n ** 18n));
+  if (payToken < buyToken) {
+    limit = Math.sqrt(Math.mulDiv(1n << 192n, 10n ** 18n, maxPrice));
+  }
+
+  // The loops only find pools; trade() decides and swaps. Slipstream, keyed by tick spacing.
+  for (const spacing of [1n, 10n, 50n, 80n, 100n, 150n, 200n, 500n, 2000n]) {
+    const pool = AerodromeSlipstream.CLFactoryGaugesV3.getPool(payToken, buyToken, spacing);
+    bought += trade(pool, true, payToken, buyToken, kept, limit, recipient);
+  }
+  // Uniswap V3, keyed by fee tier: the seven Base's factory enables.
+  for (const fee of [100n, 200n, 300n, 400n, 500n, 3000n, 10000n]) {
+    const pool = UniswapV3.Factory.getPool(payToken, buyToken, fee);
+    bought += trade(pool, false, payToken, buyToken, kept, limit, recipient);
+  }
+
+  // Settle: what was bought is already with the recipient; what is left of the budget goes back.
+  const unspent = pay.balanceOf(self) - kept;
+  const spent = budget - unspent;
+  require(bought >= minTokens, "bought below minTokens");
+  require(maxAvgPrice == 0n || spent * 10n ** 18n <= maxAvgPrice * bought, "average too high");
+  if (unspent > 0n) {
+    pay.transfer(refundTo, unspent);
+  }
+  return abi.encode(spent, bought, unspent);
+}

package/skills/sauce-examples/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: sauce-examples
+description: Index of every example in the Sauce skills — each SauceScript program (.sauce.ts) with the chains it is checked on and the sauce command that runs it, and each TypeScript runner (.mts), what it demonstrates and which skill explains it. Use when the user says "show me an example", "sample Sauce program", "example .sauce file", "how do I write X in Sauce", or wants to see how a complete program does something (a payment, a swap, a distributed swap, a cross-chain intent, a protocol call, a Solana transfer).
+---
+
+# Sauce examples
+
+Every example lives in the skill that explains it, and demonstrates an idiom. Read one for the
+pattern, with its skill, then write the program the task needs (`sauce-overview`): an example is not
+a template to fill in. A program names no chain: `--chain` picks one, and the chains below are the
+ones it is checked on. Each program's first comment lines say what it does, give the `sauce`
+command that runs it with every `main` parameter named, say what each parameter is and its units,
+and show one run on a supported chain with real values.
+
+For the initial release, Sauce supports transactions on Ethereum, Base and Solana. A chain marked
+(preview) is a preview chain: the program is compiled for it, and its cook is checked to be
+refused there, as the `sauce` command and the MCP server refuse every transaction on a preview
+chain. Run an example's transaction on a supported chain; on a preview chain compile and simulate
+it, and to run it there,
+[request the chain](https://github.com/eco-incorp/sauce/issues/new?template=chain-support.yml)
+(or add the use case to its
+[existing request](https://github.com/eco-incorp/sauce/issues?q=is%3Aissue+label%3Achain-support)). Each program's first comment lines say what it does and give the `sauce`
+command that runs it; runtime inputs are `main(...)` parameters passed with `--args`, and an intent
+file's values are defines (`sauce-script`).
+
+Before writing a program, look its names up: the chain's file in `sauce-chains`
+([../sauce-chains/references/index.md](../sauce-chains/references/index.md)) lists its tokens and
+every protocol there with how a program names it, and the generated indexes of globals list the
+names alone ([../sauce-globals/references/tokens.md](../sauce-globals/references/tokens.md),
+[../sauce-globals/references/protocols.md](../sauce-globals/references/protocols.md),
+[../sauce-globals/references/chains.md](../sauce-globals/references/chains.md)); or run
+`npx sauce globals --chain <chain>`.
+
+## SauceScript programs
+
+| Program                                                                                                                        | Chains                                             | Demonstrates                                                                                                                                                                                                                                                                                                                                                     | Skill                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| [`../sauce-cli/examples/pay.sauce.ts`](../sauce-cli/examples/pay.sauce.ts)                                                     | `ethereum`, `optimism` (preview)                   | The smallest complete program: pay a recipient in USDC and USDT, SafeERC20 writes, both values `main` inputs                                                                                                                                                                                                                                                     | `sauce-cli`              |
+| [`../sauce-cli/examples/split.sauce.ts`](../sauce-cli/examples/split.sauce.ts)                                                 | `base`, `arbitrum` (preview), `ethereum`           | Array and bool arguments: pay several recipients any token, and the chain's USDC as well                                                                                                                                                                                                                                                                         | `sauce-cli`              |
+| [`../sauce-chains/examples/chains.sauce.ts`](../sauce-chains/examples/chains.sauce.ts)                                         | `base`, `arbitrum` (preview), `ethereum`           | One file for every chain: each name resolves on the chain it is compiled for, and the cook `sauce tx` prints for any signer                                                                                                                                                                                                                                      | `sauce-chains`           |
+| [`../sauce-script/examples/twap.sauce.ts`](../sauce-script/examples/twap.sauce.ts)                                             | `base`, `ethereum`                                 | Calling a contract: namespaces (the Uniswap V3 factory, and a pool it returns through `UniswapV3.Pool`) and the program's own ABI beside it ([`IOracle.json`](../sauce-script/examples/IOracle.json)) for the function the registry's pool ABI lacks, a tuple result destructured to the one field needed                                                        | `sauce-script`           |
+| [`../sauce-globals/examples/globals.sauce.ts`](../sauce-globals/examples/globals.sauce.ts)                                     | `ethereum`, `optimism` (preview)                   | Every name available without an import: `USDT`/`USDC`, `Token(address)` bound once, `@sauce/token` functions, `AaveV3.Pool`, `ctx`                                                                                                                                                                                                                               | `sauce-globals`          |
+| [`../sauce-protocols/examples/protocols.sauce.ts`](../sauce-protocols/examples/protocols.sauce.ts)                             | `base`, `arbitrum` (preview), `optimism` (preview) | Protocols through their namespaces: Aave V3, and a PancakeSwap V3 factory lookup where the chain has one (`available(...)`)                                                                                                                                                                                                                                      | `sauce-protocols`        |
+| [`../sauce-swaps/examples/swap-leg.sauce.ts`](../sauce-swaps/examples/swap-leg.sauce.ts)                                       | `base`, `arbitrum` (preview)                       | One guarded Uniswap V3 leg: a price limit, the output measured as a delta, `minOut`, the unspent input returned                                                                                                                                                                                                                                                  | `sauce-swaps`            |
+| [`../sauce-distributed-swap/examples/distributed-swap.sauce.ts`](../sauce-distributed-swap/examples/distributed-swap.sauce.ts) | `base`                                             | A limit buy (SPCXc with USDC in its header) over Base's Aerodrome Slipstream and Uniswap V3 pools: one `trade` helper per pool that skips missing, empty and past-limit pools and swaps up to the pool's fee-adjusted limit from one `maxPrice`, loops that only find pools, minimum and average-price checks, the unspent budget refunded, the outcome returned | `sauce-distributed-swap` |
+| [`../sauce-intents/examples/cross-chain.sauce.ts`](../sauce-intents/examples/cross-chain.sauce.ts)                             | `base`                                             | An intent file (top-level statements, values as defines): forward the Pot's measured USDC to Ethereum and supply it to Aave there, with a solver margin                                                                                                                                                                                                          | `sauce-intents`          |
+| [`../sauce-intents/examples/swap-on-base.sauce.ts`](../sauce-intents/examples/swap-on-base.sauce.ts)                           | `ethereum`                                         | An intent file whose body is a distributed swap in one pass: WETH delivered on Base is offered to every Uniswap V3 and V4 pool with liquidity, each up to its own fee-adjusted limit, and the solver is paid in WETH on the source chain                                                                                                                         | `sauce-intents`          |
+| [`../sauce-intents/examples/fund-by-transfer.sauce.ts`](../sauce-intents/examples/fund-by-transfer.sauce.ts)                   | `base`, `ethereum`                                 | Funds an intent by a transfer into its vault, then publishes it: one cook on a Pot, no approval                                                                                                                                                                                                                                                                  | `sauce-intents`          |
+| [`../sauce-solana/examples/solana.sauce.ts`](../sauce-solana/examples/solana.sauce.ts)                                         | `solana`                                           | A Solana program: `Account` parameters with roles, the mint as a define, the `@sauce/token` SPL arm, proof the destination received the amount                                                                                                                                                                                                                   | `sauce-solana`           |
+| [`../sauce-solana/examples/token-2022.sauce.ts`](../sauce-solana/examples/token-2022.sauce.ts)                                 | `solana`                                           | A Token-2022 transfer: PYUSD moved with `transferChecked`, the mint and its token program as accounts, what arrived measured                                                                                                                                                                                                                                     | `sauce-solana`           |
+
+## Actions documents
+
+| Document                                                                                           | Chains                                                         | Demonstrates                                                                                                        | Skill           |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------- |
+| [`../sauce-actions/examples/swap-by-key.json`](../sauce-actions/examples/swap-by-key.json)         | `ethereum`, `base`, `arbitrum` (preview)                       | One swap by token symbols and a pool's factory key, the amount an argument: no chain and no address in the document | `sauce-actions` |
+| [`../sauce-actions/examples/swap-and-supply.json`](../sauce-actions/examples/swap-and-supply.json) | `ethereum`, `base`, `arbitrum` (preview), `optimism` (preview) | Chaining: a swap's output saved by name, approved to the Aave pool and supplied on the Pot's behalf                 | `sauce-actions` |
+
+## TypeScript runners
+
+| Runner                                                                                                               | Compiles and checks                                                                                                                                                                                                            | Skill                    |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| [`../sauce-script/examples/saucescript.mts`](../sauce-script/examples/saucescript.mts)                               | what compiles, what a define changes, each rejected construct, per-target differences, and what compiling for a chain adds                                                                                                     | `sauce-script`           |
+| [`../sauce-globals/examples/globals.mts`](../sauce-globals/examples/globals.mts)                                     | the globals program, the SafeERC20 lowering of every write, the `IERC20` import rule, family aliases and `available(...)`                                                                                                      | `sauce-globals`          |
+| [`../sauce-protocols/examples/protocols.mts`](../sauce-protocols/examples/protocols.mts)                             | the protocols program on chains with and without PancakeSwap V3, registry lookups, a per-protocol document, a protocol template                                                                                                | `sauce-protocols`        |
+| [`../sauce-swaps/examples/swaps.mts`](../sauce-swaps/examples/swaps.mts)                                             | the guarded leg on two chains, `@sauce/router`'s functions, and the Router's entry points, price parameters and callbacks                                                                                                      | `sauce-swaps`            |
+| [`../sauce-distributed-swap/examples/distributed-swap.mts`](../sauce-distributed-swap/examples/distributed-swap.mts) | the distributed swap for Base: the skill's copy of its code, its typed pool reads and venues, `maxPrice` for SPCXc and WETH and the limits they give, per-pool limits, `minTokens`, the three rehearsals' arguments, the cooks | `sauce-distributed-swap` |
+| [`../sauce-intents/examples/intents.mts`](../sauce-intents/examples/intents.mts)                                     | both intent files: on which chain each name resolves, the fee requirement, a token-only child, the pool ABI's selectors, and the transactions that rehearse a body on a fork                                                   | `sauce-intents`          |
+| [`../sauce-solana/examples/solana.mts`](../sauce-solana/examples/solana.mts)                                         | the Solana programs' manifests and arguments, the mints' token programs, and the client's `rpcUrl` requirement                                                                                                                 | `sauce-solana`           |
+| [`../sauce-typescript/examples/cook.mts`](../sauce-typescript/examples/cook.mts)                                     | owner, Pot, deploy call, a program compiled with its arguments, the cook transaction, and the packaged Solana binaries                                                                                                         | `sauce-typescript`       |
+| [`../sauce-typescript/examples/compiler.mts`](../sauce-typescript/examples/compiler.mts)                             | raw compilation, ABI-v1 and compact-v1 arguments, `@sauce/token` through the package's resolvers                                                                                                                               | `sauce-typescript`       |
+| [`../sauce-typescript/examples/actions.mts`](../sauce-typescript/examples/actions.mts)                               | JSON action programs: validation, runtime amounts, a quote                                                                                                                                                                     | `sauce-typescript`       |
+| [`../sauce-typescript/examples/verify.mts`](../sauce-typescript/examples/verify.mts)                                 | settlement verification: a payload, a cook, a tampered program, pins, reproduction                                                                                                                                             | `sauce-typescript`       |
+
+## Run them
+
+A program runs with the command in its first comment lines, from a project with
+`@eco-incorp/sauce` installed:
+
+```sh
+npx sauce compile ../sauce-cli/examples/pay.sauce.ts --chain ethereum
+npx sauce tx ../sauce-cli/examples/pay.sauce.ts --chain ethereum --owner <address> --value 0 \
+  --args <recipient> 1000000
+```
+
+A runner runs with Node, from its own directory, with the inputs its usage line names (the owner of
+a Pot, a recipient, a fee in wei); none touches a network:
+
+```sh
+node ../sauce-distributed-swap/examples/distributed-swap.mts --owner <address> --recipient <address>
+node ../sauce-typescript/examples/cook.mts --owner <address> --recipient <address>
+```
+
+Every program here is compiled through the `sauce` command on each chain listed, its command line
+run offline (its cook built on each supported chain, and refused on each preview chain), and every
+runner executed, by the package's own checks before it ships.

package/skills/sauce-globals/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: sauce-globals
+description: The names a Sauce program uses without any import, and how they resolve on the chain it is compiled for — token symbols (USDC, USDT, WETH, …) and tokenized stocks (SPCXc, TSLAon, TSLAx, NVDA_US, SPACEX, …, on Ethereum, Base and Solana), Token(address) and a bound const t = Token(x), the token methods .transfer/.approve/.transferFrom/.balanceOf with SafeERC20 behaviour and USDT, the @sauce/token functions, protocol namespaces (UniswapV3.Factory, UniswapV4.StateView, AaveV3.Pool, …) and family aliases, available(...) for a venue a chain may lack, the Namespace_Contract compile-time defines, chain names, chainId and ctx.*. Links generated indexes of every token, protocol contract and chain, the same lists sauce globals prints. Use when writing any Sauce program that moves tokens, calls a protocol or names a chain, when checking whether a name exists on a chain, or when a name does not resolve ("is not a declared variable", "ambiguous", "is not deployed").
+---
+
+# Globals in a Sauce program
+
+A program compiled for a chain resolves these names against **that chain**, with no import. They
+are program syntax, not JavaScript values. **Look names up before writing a program**:
+`npx sauce globals --chain <chain>` lists one chain's, and these indexes list every chain's, from
+the same registries the compile reads:
+
+- [references/tokens.md](references/tokens.md): every token symbol per chain, with its decimals,
+  and the `@sauce/token` functions.
+- [references/stocks.md](references/stocks.md): every tokenized stock per chain, with what it is
+  and its issuer.
+- [references/protocols.md](references/protocols.md): every `Namespace.Contract`, and the family
+  aliases.
+- [references/chains.md](references/chains.md): every chain name, its id, and whether it takes
+  intents.
+
+These are the names. Where each is deployed and its address there are the full map: per chain in
+`sauce-chains` ([../sauce-chains/references/index.md](../sauce-chains/references/index.md)), and per
+protocol in `sauce-protocols`
+([../sauce-protocols/references/index.md](../sauce-protocols/references/index.md)).
+
+A name that is absent on the target chain (a token the chain does not register, a contract not
+deployed there) is a **compile error**, never a wrong address at run time.
+
+The language's own builtins (`ctx`, `crypto`, `Math`, `abi`, `evm`, `svm`, methods on values) are
+in [../sauce-script/references/builtins.md](../sauce-script/references/builtins.md): look a builtin
+up there before using it.
+
+## Tokens
+
+A symbol is that chain's token address: a value (`balanceOf(USDC, account)`) or the target of its
+methods. Any other ERC-20 is `Token(address)`, or bound once: `const t = Token(address);` (declared
+once, never reassigned, used only as `t.<method>(...)`).
+
+| Method                            | Behaviour                                                 |
+| --------------------------------- | --------------------------------------------------------- |
+| `.transfer(to, amount)`           | SafeERC20 transfer                                        |
+| `.transferFrom(from, to, amount)` | SafeERC20 transferFrom                                    |
+| `.approve(spender, amount)`       | forceApprove: a non-zero allowance is reset to zero first |
+| `.balanceOf(owner)`               | balance read; `self.USDC` is `USDC.balanceOf(ctx.self())` |
+
+Writes are **SafeERC20**: a token that returns nothing (USDT) works when it has code; a `false`
+return, a malformed return or an address with no code reverts the program. A write returns
+nothing, so `const ok = USDT.transfer(...)` does not compile. Approve exactly what the next call
+spends: a standing allowance outlives the program.
+
+The same library as functions, token first: `transfer(token, to, amount)`,
+`transferFrom(token, from, to, amount)`, `approve(token, spender, amount)`,
+`balanceOf(token, account)`, `allowance(token, owner, spender)`, `totalSupply(token)`,
+`decimals(token)`, and the signature pulls `permit` and `permitTransferFrom` (the bottom of
+[references/tokens.md](references/tokens.md) has every signature). The methods compile to exactly
+these.
+
+```sauce chain=ethereum,optimism
+function main(payee: Address, amount: Uint256) {
+  require(USDT.balanceOf(ctx.self()) >= amount, "not enough USDT");
+  USDT.transfer(payee, amount);
+  require(allowance(USDT, ctx.self(), payee) == 0n, "no allowance left standing");
+}
+```
+
+**`IERC20` is low level, and only imported.** `import { IERC20 as Erc20 } from
+"./artifacts/IERC20.json"` binds the raw ERC-20 ABI for a call the token syntax does not offer. Its
+writes decode the declared `bool`, so they are not SafeERC20 (USDT's `transfer` reverts there, and
+a `false` return passes): never write a token transfer or approval through it. Import it under a
+name of its own, as here, in a file that also uses the token syntax, which binds `IERC20` itself.
+
+## Tokenized stocks
+
+A tokenized stock is a token like any other, named by its symbol with no import:
+`SPCXc.balanceOf(ctx.self())`, `SPCXc.transfer(to, amount)`, a value for `@sauce/token`'s
+functions, a token a swap buys or sells.
+
+- **Ethereum**: Backed's xStocks (`TSLAx`, `SPCXx`) and bTokens (`bTSLA`), Ondo Global Markets'
+  (`TSLAon`, `SPCXon`), and Mt Pelerin's own shares (`MPS`).
+- **Base**: Coinbase's (`TSLAc`, `SPCXc`) and Backed's bTokens.
+- **Solana**: Backed's xStocks (`TSLAx`), Ondo Global Markets' (`TSLAon`), Backpack Securities'
+  (`NVDA_US`, `SPCX_US`) and PreStocks' shares of private companies (`SPACEX`, `OPENAI`), each a
+  Token-2022 mint (below).
+
+The symbol is the issuer's own ticker for the token, in its case: symbols are case-sensitive, and
+`SPCXC` is not `SPCXc`. A `.` in a ticker is written `_`: `BRK.Bx` is `BRK_Bx`, and Backpack's
+`NVDA.US` is `NVDA_US`. PreStocks' symbol is the company's name, `SPACEX`. One company has one token
+per issuer: SpaceX is `SPCXx` and `SPCXon` on Ethereum, `SPCXc` on Base, and `SPCXx`, `SPCXon`,
+`SPCX_US` and `SPACEX` on Solana. Find one by the company's name or ticker with
+`npx sauce globals --chain base --search spacex`, list a chain's with `--stocks`, or read
+[references/stocks.md](references/stocks.md).
+
+Buying and selling one on a DEX needs no account with its issuer, and any contract can hold it,
+the program's Pot included; only minting and redeeming with the issuer need KYC. What differs from
+a plain ERC-20:
+
+- An issuer can pause its token, and refuses a sanctioned or blocked address.
+- Backed's tokens rebase: a balance is shares times a multiplier the issuer moves, so it changes
+  between transactions, never within one. A transfer can credit one unit less than sent, so paying
+  one into a pool that checks what it received can fail; buying one is unaffected.
+- Ondo's keep their balance: dividends raise the shares each token stands for (Ondo's multiplier),
+  so its price follows the stock with dividends reinvested.
+- Coinbase's are B20 tokens, built into the Base node: they run on Base, and not in a local copy of
+  the chain. Rehearse a program that moves one with `sauce simulate` against Base itself.
+
+```sauce chain=base
+function main(recipient: Address, amount: Uint256) {
+  require(SPCXc.balanceOf(ctx.self()) >= amount, "not enough SPCXc");
+  SPCXc.transfer(recipient, amount);
+}
+```
+
+### On Solana
+
+A stock on Solana is a Token-2022 mint, and its symbol is the mint's 32-byte key, a value for
+`@sauce/token`'s functions: `balanceOf(TSLAx, account)`. A program moves one with the checked
+writes, `transferChecked` and `approveChecked`, which take the mint's token program, the mint and
+its decimals beside the token accounts (`transfer` and `approve` take legacy SPL Token mints only).
+`sauce` names each of those accounts by the symbol: `program:TSLAx` the token program,
+`mint:TSLAx` the mint, `pot:TSLAx` the Pot's token account and `owner:TSLAx` the owner's.
+
+- Amounts are raw, in the mint's decimals. The issuer's multiplier, by which a wallet shows them,
+  moves for splits and dividends, so a raw unit is not always one share.
+- PreStocks' mints charge a transfer fee: the token program keeps part of every transfer, so the
+  recipient gets less than was sent. Measure what arrived, as below; the references mark each mint
+  that charges one.
+- Every stock mint has a transfer hook that names no program, which is no hook. `@sauce/token`
+  refuses a mint whose hook names a program (`transfer hook`), and no registered mint has one.
+- The issuer can pause its mint, and can hold a permanent delegate, which can move or burn any
+  balance. A new token account is usable, not frozen.
+
+```sauce chain=solana
+function main(
+  tokenProgram: Account,
+  source: Account<Writable>,
+  mint: Account,
+  destination: Account<Writable>,
+  pot: Account<Signer>,
+  amount: Uint256,
+): Uint256 {
+  const before = balanceOf(SPACEX, destination);
+  transferChecked(SPACEX, tokenProgram, source, mint, destination, pot, amount, 9n);
+  return balanceOf(SPACEX, destination) - before;
+}
+```
+
+## Protocols
+
+- `Namespace.Contract` is the contract's address on the program's chain where a value is expected,
+  and a bound contract where a method is called: `UniswapV3.Factory.getPool(a, b, 500n)`. A
+  Uniswap fee is in millionths: `500n` is the 0.05% tier, `3000n` 0.3%.
+- A namespace's default contract is also called by the namespace alone:
+  `Cctp.depositForBurn(...)` calls `Cctp.TokenMessenger`.
+- A family alias (`Uniswap`, `Aave`, …) names a contract only when one member has it on the chain:
+  `Uniswap.UniversalRouter` is `UniswapV4.UniversalRouter`; `Uniswap.Factory` is ambiguous.
+- `Ethereum.UniswapV4.UniversalRouter` takes Ethereum's address but still executes on the program's
+  own chain; running on another chain is an intent (`sauce-intents`).
+- Every catalogued protocol has a namespace. An interface, such as `Erc4626.Vault` or
+  `UniswapV3.Pool`, has no one address and is called with one, together with a method in the same
+  expression: `Erc4626.Vault(vault).deposit(...)`, or `UniswapV3.Pool(pool).liquidity()` for a pool
+  its factory returned (`.at(pool)` is the same).
+  [references/protocols.md](references/protocols.md) lists every interface.
+
+**A venue a chain may not have** is asked with `available(<name>)`, decided when the program is
+compiled for a chain: `if (available(UniswapV3.Factory)) { ... }` keeps its branch where the chain
+has the contract, and removes it, names and all, where it does not. It takes a contract or a token
+symbol (`available(USDT)`); it folds `if`/`else`, `?:`, `&&`, `||` and `!`; and a guard
+`if (!available(X)) { return 0n; }` drops the rest of its function. A name no chain has is an
+error rather than `false`, so a typo cannot quietly drop a branch. `Namespace.Contract` without it
+is for a contract the program requires: on a chain without it, the program does not compile.
+
+```sauce chain=base,linea
+function main(tokenA: Address, tokenB: Address) {
+  if (available(UniswapV3.Factory)) {
+    const pool = UniswapV3.Factory.getPool(tokenA, tokenB, 500n);
+    require(pool != 0n, "no 0.05% pool");
+  }
+}
+```
+
+## Chains, context, imports
+
+- **Chain names** (`Base`, `Ethereum`, … in [references/chains.md](references/chains.md)) open an
+  intent from inside a program: `Ethereum(() => { ... }).reward({ ... })`. Every chain's names
+  compile; for the initial release its transactions are built and sent only on Ethereum, Base and
+  Solana, and [references/chains.md](references/chains.md) marks every other chain a preview chain
+  (`sauce-chains` says how to request one).
+- **`chainId`** is the chain the program is compiled for.
+- **`ctx`**: context reads, each a call. The complete list, with what each returns per target, is
+  section 6 of [../sauce-script/references/builtins.md](../sauce-script/references/builtins.md).
+
+| Read                                                                                                         | EVM                                                   | Solana                                                   |
+| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
+| `ctx.self()`                                                                                                 | the executing contract: the Pot, which holds balances | the executing Sauce program's id                         |
+| `ctx.msgSender()`                                                                                            | the immediate caller                                  | the transaction's first signer                           |
+| `ctx.msgData()`                                                                                              | the program's whole input                             | the instruction data                                     |
+| `ctx.timestamp()`, `ctx.chainId()`, `ctx.selfBalance()`                                                      | yes                                                   | yes                                                      |
+| `ctx.balance(a)`                                                                                             | the balance of `a`                                    | the lamports of an attached account: pass `acct.address` |
+| `ctx.blockNumber()`                                                                                          | block number                                          | slot                                                     |
+| `ctx.msgValue()`, `ctx.gasLeft()`, `ctx.codeSize(a)`, `ctx.codeHash(a)`, `ctx.isContract(a)`, `ctx.isEOA(a)` | yes                                                   | rejected                                                 |
+
+There is no read for the transaction origin.
+
+- **Imports the package serves** to a program: `@sauce/router` (the swap library, `sauce-swaps`),
+  `@sauce/token`, `./artifacts/IERC20.json`, `./artifacts/ISauceRouter.json` (the Router itself),
+  and every protocol ABI as `./protocols/<slug>/<Export>.json`.
+
+## Example
+
+[examples/globals.sauce.ts](examples/globals.sauce.ts) uses each kind of name;
+[examples/globals.mts](examples/globals.mts) compiles it and pins the SafeERC20 lowering, the
+`IERC20` import rule, the family-alias rules and `available(...)`.

package/skills/sauce-globals/examples/globals.mts

@@ -0,0 +1,111 @@
+// Compiles globals.sauce.ts the way `sauce compile` does (`routes.compileSauceProgram`, with the
+// chain's names), and pins how token writes lower: every spelling becomes a SafeERC20 function of
+// @sauce/token, reads stay typed calls, and a write returns nothing. The name tables live in
+// ../references/, generated from the registries.
+//
+//   node globals.mts
+import { readFileSync } from "node:fs";
+
+import { routes } from "@eco-incorp/sauce";
+
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`check failed: ${message}`);
+}
+
+const source = readFileSync(new URL("./globals.sauce.ts", import.meta.url), "utf8");
+for (const slug of ["ethereum", "optimism"]) {
+  const program = routes.compileSauceProgram(slug, source);
+  console.log(`globals.sauce.ts on ${slug}: ${program.bytecode.length} bytes`);
+}
+
+// Writes lower to @sauce/token in every spelling; reads stay typed IERC20 calls.
+const writes = routes.compileSauceProgram(
+  "ethereum",
+  "function main(to: Address, token: Address, amount: Uint256) { USDT.transfer(to, amount); USDT.approve(to, amount); const t = Token(token); t.transferFrom(to, ctx.self(), amount); require(USDC.balanceOf(ctx.self()) > 0n); }",
+).source;
+check(/__sauce_transfer\(USDT,/.test(writes), "USDT.transfer is SafeERC20");
+check(/__sauce_approve\(USDT,/.test(writes), "USDT.approve is forceApprove");
+check(/__sauce_transferFrom\(t,/.test(writes), "a bound Token's transferFrom is SafeERC20");
+check(/IERC20\.at\(USDC\)\.balanceOf\(/.test(writes), "reads are plain typed calls");
+check(!/IERC20\.at\([^)]*\)\.(transfer|approve|transferFrom)\(/.test(writes), "no raw writes");
+
+const rejects = (slug: string, body: string) => {
+  try {
+    routes.compileSauceProgram(slug, body);
+  } catch {
+    return true;
+  }
+  return false;
+};
+// A write returns nothing.
+check(
+  rejects("ethereum", "function main(to: Address) { const ok = USDT.transfer(to, 1n); }"),
+  "no bool to read",
+);
+// IERC20 is imported, never ambient, and under its own name it collides with the binding a token
+// read brings in; an alias does not.
+check(
+  rejects(
+    "base",
+    "function main(t: Address) { require(IERC20.at(t).balanceOf(ctx.self()) > 0n); }",
+  ),
+  "IERC20 needs an import",
+);
+check(
+  !rejects(
+    "base",
+    'import { IERC20 as Erc20 } from "./artifacts/IERC20.json";\nfunction main(t: Address) { require(Erc20.at(t).balanceOf(ctx.self()) > USDC.balanceOf(ctx.self())); }',
+  ),
+  "IERC20 imported under another name, beside a token read",
+);
+// A family alias resolves only where one member owns the name.
+check(
+  !rejects("base", "function main() { require(Uniswap.UniversalRouter != 0n); }"),
+  "Uniswap.UniversalRouter",
+);
+check(
+  rejects("base", "function main() { require(Uniswap.Factory != 0n); }"),
+  "Uniswap.Factory is ambiguous",
+);
+// A namespace's default contract is called by the namespace alone.
+check(
+  !rejects(
+    "base",
+    "function main(amount: Uint256, to: Uint256) { Cctp.depositForBurn(amount, 3n, to, USDC, 0n, 0n, 2000n); }",
+  ),
+  "Cctp.depositForBurn calls Cctp.TokenMessenger",
+);
+// A namespace absent on the chain is a compile error, unless `available(...)` rules its branch out;
+// a name no chain has is an error either way.
+check(
+  rejects("linea", "function main() { require(UniswapV3.Factory != 0n); }"),
+  "absent namespace",
+);
+check(
+  !rejects(
+    "linea",
+    "function main() { if (available(UniswapV3.Factory)) { require(UniswapV3.Factory != 0n); } }",
+  ),
+  "available() removes the branch where the chain lacks the contract",
+);
+// It takes a token symbol too: Base registers no USDT, so the guarded transfer is removed there.
+check(rejects("base", "function main() { USDT.transfer(ctx.self(), 1n); }"), "no USDT on Base");
+check(
+  !rejects("base", "function main() { if (available(USDT)) { USDT.transfer(ctx.self(), 1n); } }"),
+  "available(USDT) removes the branch on Base",
+);
+check(
+  rejects("base", "function main() { if (available(UniswapV9.Factory)) { require(false); } }"),
+  "available() of a name no chain has is an error",
+);
+// The Pot's own balance of a symbol, and the chain's id.
+check(
+  !rejects("base", "function main() { require(self.USDC >= 0n && chainId == 8453n); }"),
+  "self.USDC and chainId",
+);
+console.log(
+  writes
+    .split("\n")
+    .filter((line) => line.includes("__sauce_"))
+    .join("\n"),
+);

package/skills/sauce-globals/examples/globals.sauce.ts

@@ -0,0 +1,47 @@
+// Every kind of name a program uses without an import. USDC and USDT are the chain's registered
+// token symbols; AaveV3.Pool is a registry contract (an address as a value, a bound contract as a
+// call target); Token(address) covers any other ERC-20; allowance(...) is a @sauce/token function.
+// Every write is SafeERC20, so USDT works and a false return reverts. The addresses and amounts are
+// main(...) inputs, passed with the transaction.
+//
+//   sauce run globals.sauce.ts --chain <chain> --config sauce.config.json --keystore <keystore> \
+//     --args <payee> <payer> <otherToken> <usdtAmount> <otherAmount> <usdcAmount>
+//
+//   payee: Address         who receives the USDT and the other token, and the Aave position
+//   payer: Address         whose `otherToken` moves: it approved this Pot for `otherAmount`
+//   otherToken: Address    any ERC-20 the chain does not name, such as its WETH
+//   usdtAmount: Uint256    USDT from the Pot to `payee`, in its smallest units (6 decimals):
+//                          1000000 is 1 USDT
+//   otherAmount: Uint256   `otherToken` from `payer` to `payee`, in its smallest units:
+//                          1000000000000000 is 0.001 WETH (18 decimals)
+//   usdcAmount: Uint256    the Pot's USDC supplied to Aave V3 for `payee`, in its smallest units
+//                          (6 decimals): 1000000 is 1 USDC
+//
+// On Ethereum, 1 USDT, 0.001 WETH from the payer, and 1 USDC supplied to Aave:
+//
+//   sauce run globals.sauce.ts --chain ethereum --config sauce.config.json \
+//     --keystore <keystore> --args <payee> <payer> 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
+//     1000000 1000000000000000 1000000
+function main(
+  payee: Address,
+  payer: Address,
+  otherToken: Address,
+  usdtAmount: Uint256,
+  otherAmount: Uint256,
+  usdcAmount: Uint256,
+) {
+  const me = ctx.self();
+
+  // Registered symbols, and the Pot's own balance.
+  require(USDT.balanceOf(me) >= usdtAmount, "not enough USDT in the Pot");
+  USDT.transfer(payee, usdtAmount);
+
+  // Any ERC-20, bound once: move `payer`'s tokens, which it approved to this Pot, to `payee`.
+  const other = Token(otherToken);
+  other.transferFrom(payer, payee, otherAmount);
+
+  // A protocol call. The approve is exact, so no allowance is left standing afterwards.
+  USDC.approve(AaveV3.Pool, usdcAmount);
+  AaveV3.Pool.supply(USDC, usdcAmount, payee, 0n);
+  require(allowance(USDC, me, AaveV3.Pool) == 0n, "an allowance was left standing");
+}