@eco-incorp/sauce 0.99.6 → 0.99.8

package/skills/sauce-overview/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: sauce-overview
+description: Start here for any Sauce task — what Sauce is (a programmable-transaction runtime whose programs, written in SauceScript as .sauce.ts files, run atomically on EVM chains and Solana), the path from a program file to an executed transaction with the sauce command, the rules every program follows, and which Sauce skill to load next. Use when the user mentions Sauce, SauceScript, a .sauce or .sauce.ts file, @eco-incorp/sauce, the sauce command, a Pot, Kitchen, cook or engine, Eco intents, or asks to "write a Sauce program", "do this atomically on chain", or "swap/bridge/lend with Sauce".
+---
+
+# Sauce
+
+**Sauce is a programmable-transaction runtime.** You write a program in **SauceScript**, a checked
+subset of TypeScript, in a `.sauce.ts` file. It compiles for a chain into bytecode, and a Sauce
+engine executes it inside one transaction: on an EVM chain through your Pot's
+`cook(engine, program)`, on Solana through the Kitchen. Every step lands or none does. A program
+has control flow, reads and checks, and the engine runs it as written: it is not a multicall, and
+it does not use a magic header.
+
+On top of the runtime sit **intents**: an offer of work on another chain, with a reward escrowed on
+this one, written as a chain name called as a function: `Ethereum(() => { ... }).reward({ ... })`.
+A solver decides whether to fill it (`sauce-intents`).
+
+## You write the program
+
+Write each program yourself, in SauceScript, for the task as it is asked. These skills teach the
+language, the names each chain offers and the patterns; their example programs show idioms and the
+rules a correct program follows. They are not templates to copy, adapt or choose between: never
+ask the user which example or existing file to start from. Ask only for the facts the request
+leaves open (an amount, a price limit, a recipient, the chain); decide the rest, write the
+program, and rehearse it with `sauce simulate`.
+
+Call typed bindings, namespaces and library functions directly: `USDC.transfer(...)`,
+`UniswapV3.Factory.getPool(...)`, `uniswapV3(...)` from `@sauce/router`. Do not wrap a single call
+in a helper, and do not hand-roll a raw selector with `evm.static` and `abi.decode` where a typed
+binding or a namespace exists. Keep a helper only for real logic used more than once.
+
+Start every program with a comment that says, in order: what it does, in one line; the `sauce`
+command that runs it, with `--chain <chain>` and `--args` naming every `main` parameter in order
+(`--args <tokenIn> <tokenOut> <amountIn>`); one line per parameter with its type, its meaning and
+its units, in smallest units (`5000000000` is 5,000 USDC, which has 6 decimals; an array or a
+record is passed as JSON); and one concrete invocation on a supported chain with real values,
+addresses taken from the registry and the developer's own inputs left as `<placeholders>`. An
+intent file lists its defines the same way. `sauce-script` shows one.
+
+## Supported chains
+
+For the initial release, Sauce supports transactions on **Ethereum, Base and Solana** (`ethereum`,
+`base`, `solana`). Every other chain the SDK knows is a **preview chain**: a program compiles for
+it, and `sauce simulate` and the dry runs rehearse it there, but the `sauce` command and the MCP
+server build and send no transaction on it. `sauce tx`, `sauce run`, `sauce pot --deploy`,
+`sauce intent publish` and the intent steps sent there are refused before anything is read or
+signed, and the refusal names the supported chains and the chain-support request for that chain.
+An intent publishes only when every chain it involves is supported. `sauce-chains` marks each
+chain supported or preview.
+
+To ask for a chain, look among the
+[existing chain-support requests](https://github.com/eco-incorp/sauce/issues?q=is%3Aissue+label%3Achain-support)
+and add the use case to that chain's as a comment, or
+[open one](https://github.com/eco-incorp/sauce/issues/new?template=chain-support.yml) with the
+chain-support form: the chain and its id, what runs there, the protocols and tokens, and the
+expected volume and timing. The refusal carries both links, prefilled for its chain.
+
+## Writing a program
+
+A program names what the chain it is compiled for supplies, with no import: token symbols such as
+`USDC`, `Token(address)` for any other token, protocol namespaces such as `UniswapV3.Factory` and
+`AaveV3.Pool`, chain names such as `Ethereum`, and `ctx` for the transaction's context. The
+smallest complete program:
+
+```sauce chain=base,ethereum
+function main(recipient: Address, floor: Uint256) {
+  const held = USDC.balanceOf(ctx.self());
+  require(held >= floor, "not enough USDC in the Pot");
+  USDC.transfer(recipient, held);
+}
+```
+
+It names no chain. `sauce run <file> --chain base` compiles it for Base, where `USDC` is Base's
+USDC; `--chain ethereum` gives the same file Ethereum's. What changes per call, such as `recipient`
+and `floor`, is a parameter of `main`, passed with the transaction (`--args`), so one compiled
+program serves every call. That program is for an EVM chain: on Solana every account, a recipient
+included, is an `Account` parameter attached with `--account`, never an `Address` argument
+(`sauce-solana`).
+
+On an EVM chain the executing contract, `ctx.self()`, is the **Pot**: it holds the tokens and
+makes the calls. A Pot belongs to one owner, its address follows from the owner
+(`sauce pot --owner <address>`), and only the owner can run a program on it. Token writes are
+SafeERC20 however they are spelled, so USDT works. On Solana the Pot is the Kitchen's account for
+the owner, which the program is given as an account; `ctx.self()` there is the program's id.
+
+Two references hold what a program can name. The language (types, operators, statements, and the
+`ctx`, `crypto`, `Math`, `abi`, `evm` and `svm` builtins) is
+[../sauce-script/references/builtins.md](../sauce-script/references/builtins.md); the names a chain
+supplies are indexed in [../sauce-globals/references/](../sauce-globals/references/tokens.md), and
+`sauce globals --chain <chain>` lists them for one chain. Take every address from those or from
+the developer; never invent one.
+
+## From a file to a transaction
+
+The `sauce` command comes with the package, which needs Node.js 24 or newer: install it in the
+project with `npm i -D -E @eco-incorp/sauce` and run it with `npx sauce`. With the program above
+saved as `payout.sauce.ts`:
+
+```sh
+npx sauce globals --chain base                     # the names a program on Base can use
+npx sauce compile payout.sauce.ts --chain base     # check it compiles: the bytecode
+npx sauce simulate payout.sauce.ts --chain base --owner <address> --config sauce.config.json \
+  --assume-balance USDC:1 --args <recipient> 1000000
+npx sauce tx payout.sauce.ts --chain base --owner <address> --args <recipient> 1000000
+npx sauce run payout.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+  --args <recipient> 1000000
+```
+
+**Units differ by flag.** `--args` and defines take base units: `1000000` is 1 USDC (6
+decimals). `--assume-balance` and `--fund` take whole tokens: `USDC:1` is 1 USDC, and
+`USDC:1000000n`, ending in `n`, the same in base units.
+
+Compiling for a chain produces the program's bytecode; running it is one transaction to the
+owner's Pot, `cook(engine, program)` with `main`'s arguments appended to the program, paying the
+Kitchen's fee. `sauce tx` prints that transaction unsigned, `{ chainId, to, data, value }`, for
+any wallet or signer to send; `sauce run` signs and sends it itself, deploying the Pot first if it
+is not there. Both work on a supported chain only; on a preview chain, compile and simulate.
+`sauce-cli` covers each command. Endpoints come from a config file the developer passes, never
+from the program or the environment. Without the CLI, the same steps are tools of the Sauce MCP
+server (`npx -y @eco-incorp/sauce mcp`); `sauce-cli` maps each command to its tool.
+
+## Pick the next skill
+
+| Task                                                                                     | Skill                    |
+| ---------------------------------------------------------------------------------------- | ------------------------ |
+| The language: the two program forms, `main(...)` inputs and defines, compile errors      | `sauce-script`           |
+| Names with no import: tokens, `Token(...)`, protocol namespaces, chains, `ctx`           | `sauce-globals`          |
+| What is on a chain: support, tokens, every protocol with its addresses, intents          | `sauce-chains`           |
+| Every protocol: how to choose one, its deployments, how a program calls it, its pitfalls | `sauce-protocols`        |
+| Any swap: `@sauce/router`, price limits, the Pot's Router, the guard every leg needs     | `sauce-swaps`            |
+| One swap spread over several price-limited pools: a limit order                          | `sauce-distributed-swap` |
+| Protocol operations as JSON data, not a program: actions documents                       | `sauce-actions`          |
+| Continuing on another chain: intents, cascades, rewards                                  | `sauce-intents`          |
+| Solana programs: accounts, SPL, the Kitchen                                              | `sauce-solana`           |
+| Compiling and running: the `sauce` commands, the Pot, funding, simulating, publishing    | `sauce-cli`              |
+| Application code: compiling, arguments, cooks, actions and verification from TypeScript  | `sauce-typescript`       |
+| Complete programs, each showing an idiom                                                 | `sauce-examples`         |
+
+## Rules for every program
+
+1. **Nothing is left behind.** Measure outputs as balance deltas, move them out, return unspent
+   input, and approve exactly what the next call spends. An intent's body runs on a Pot every
+   intent to that chain shares, so there a leftover is anyone's.
+2. **A swap leg must not strand input.** Swap exact input, enforce a minimum output with `require`,
+   and return what a partial fill leaves (`sauce-swaps`).
+3. **Every check belongs in the program.** A failed `require` reverts the whole transaction; that
+   atomicity is the safety mechanism.
+4. **An intent is an offer.** Never promise it will be filled.
+5. **No endpoints or keys in code.** The package ships no RPC URL and reads no environment
+   variable: endpoints and signers are passed on the command line or from a config file.
+6. **Transactions on supported chains only.** Build and send on Ethereum, Base or Solana. On a
+   preview chain, compile and simulate; when a command refuses one, offer the user the
+   chain-support request it names instead of looking for another way to send.
+
+## Example
+
+[../sauce-cli/examples/pay.sauce.ts](../sauce-cli/examples/pay.sauce.ts) pays a recipient in USDC
+and USDT, and
+[../sauce-distributed-swap/examples/distributed-swap.sauce.ts](../sauce-distributed-swap/examples/distributed-swap.sauce.ts)
+is a complete swap. `sauce-examples` lists every example in every skill.

package/skills/sauce-protocols/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: sauce-protocols
+description: Every DeFi protocol a Sauce program can call, from the SDK's registry — an index by category with how to choose between them (a lending market versus another, a concentrated-liquidity pool versus a V2 pair or a stable pool, an aggregator, a bridge), a registry file per protocol (its deployments on every chain, how a program names each contract there, its ABI functions), and a document per protocol (what it is for, its pitfalls, a compiled example, its templates and notes). Covers every protocol as a registry namespace (deployed contracts, address-only contracts, interfaces called with an address), available(...) for a chain that may lack one, ABI imports for unrecorded contracts, factories and pool lookups, and checking a recorded address has code. Use when a program must call a protocol (PancakeSwap V3, Aerodrome Slipstream, Curve, Balancer, Camelot, Lido, …), when the user asks which protocols or pools exist on a chain or which to use, needs a factory or router address, or wants a protocol's pitfalls.
+---
+
+# Protocols
+
+Every protocol the SDK registers is in [references/index.md](references/index.md), grouped by
+category, each with **how to choose between them**. Each protocol then has:
+
+- `references/registry/<slug>.md`, generated from the registry: its deployments on every chain, how
+  a program names each contract there, and its ABI functions (for example
+  [references/registry/uniswap-v3.md](references/registry/uniswap-v3.md));
+- `references/<slug>.md`, its document: what it is for, its pitfalls for a program, a compiled
+  example, its templates and notes (for example [references/aave-v3.md](references/aave-v3.md)).
+
+## When to use
+
+- A program must call a protocol: find how it is named on the program's chain.
+- Choosing between protocols that do the same job: the category's "Choosing between them".
+- You need a factory, router or pool address on a chain, or want a protocol's pitfalls first.
+
+## Quick reference
+
+A program reaches a catalogued protocol through its **registry namespace**, with no import: the
+address and the ABI come from the registry for the chain the program is compiled for. A namespace
+member is one of three kinds:
+
+| Member              | Example                                                  | In a program                         |
+| ------------------- | -------------------------------------------------------- | ------------------------------------ |
+| A deployed contract | `PancakeswapV3.Factory`, `AerodromeSlipstream.CLFactory` | its address; `.method(...)` calls it |
+| An address only     | `Camelot.V3Factory` (no ABI the registry has verified)   | its address                          |
+| An interface        | `Erc4626.Vault` (a vault has no one fixed address)       | `(address).method(...)`              |
+
+An interface is called with the address of a deployment, `Erc4626.Vault(vault).totalAssets()`
+(`.at(vault)` is the same). `.at(address)` also reaches another deployment of a deployed contract's
+ABI; a deployed contract's name is never called with an address. A contract the
+registry does not record at all is called through its ABI, imported from
+`./protocols/<slug>/<Export>.json` and bound with `.at(address)` to an address passed in as a
+`main` input or a define.
+
+A program that should also compile for a chain without the protocol asks `available(...)`, which is
+decided when it is compiled; the branch it rules out is left out, names and all:
+
+```sauce chain=base,arbitrum,optimism
+function main(fee: Uint256) {
+  const uni = UniswapV3.Factory.getPool(WETH, USDC, fee);
+  let pancake = 0n;
+  if (available(PancakeswapV3.Factory)) {
+    pancake = PancakeswapV3.Factory.getPool(WETH, USDC, fee);
+  }
+  require(uni != 0n || pancake != 0n, "no WETH/USDC pool at that fee");
+}
+```
+
+With that program in `pools.sauce.ts`, a run on Base passes nothing but the fee (in millionths:
+`500` is the 0.05% tier):
+
+```sh
+npx sauce run pools.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+  --args 500
+```
+
+Written without `available(...)`, a member is required: the program does not compile for a chain
+that lacks it.
+
+## Decision guidance
+
+| Question                     | Answer                                                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Which protocol for a job     | the category's "Choosing between them" in [references/index.md](references/index.md)                     |
+| How to name a contract       | the registry file's "In a program" column for your chain                                                 |
+| A chain may lack it          | `if (available(Namespace.Contract)) { … }`                                                               |
+| A pool, not a fixed contract | look it up at run time through the factory (`getPool`, `getPair`), which returns `0` where there is none |
+| A swap                       | through the Sauce Router wherever it services the pool (`sauce-swaps`), not the protocol's own router    |
+| Code on another chain        | a Sauce intent (`sauce-intents`), not a bridge call alone                                                |
+
+## Workflow
+
+1. Find the protocol in [references/index.md](references/index.md) and open its registry file:
+   check it is deployed on your chain and how a program names the contract there.
+2. Read its document's pitfalls before writing the call.
+3. Write the program, compile it for the chain (`sauce compile <file> --chain <slug>`), and hand the
+   cook to any signer as `sauce tx`'s unsigned JSON, `{ chainId, to, data, value }`, or send it with
+   `sauce run` (`sauce-cli`). For the initial release that is on Ethereum, Base or Solana: every
+   protocol on every chain compiles and simulates, but on a preview chain `sauce tx` and `sauce run`
+   are refused with the chain-support request for that chain (`sauce-chains`).
+
+## Common gotchas
+
+- **Recorded is not live.** A registry address is what the registry records, not proof of code on
+  the chain: confirm `eth_getCode` returns code before relying on it.
+- **A document's templates are typed programs for the raw compiler**: their
+  `import { PoolABI as IPool } from "./abis"` is served by the template's caller. In a program for a
+  chain, use the namespace instead.
+- **Some factories are addresses only** (Algebra forks such as Camelot V3 and QuickSwap V3): the
+  registry has no verified ABI with their pool lookup, so discover the pool off chain and pass its
+  address as a `main` input.
+- **Solidity idioms in a document have SauceScript spellings**: `msg.sender` is `ctx.msgSender()`,
+  `address(this)` is `ctx.self()`, and `type(uint256).max` is `~0n`
+  ([../sauce-script/references/builtins.md](../sauce-script/references/builtins.md)).
+- **Approve exactly what the call spends**: the Pot keeps any allowance it grants.
+
+## Verification checklist
+
+- [ ] The protocol is deployed on the program's chain, and the address has code.
+- [ ] Each contract is named as its registry file says for that chain, or behind `available(...)`.
+- [ ] The document's pitfalls are handled: approvals, balance deltas, minimums.
+- [ ] The program compiles with `--chain`.
+- [ ] Its transaction goes to a supported chain (Ethereum, Base or Solana); a protocol on a preview
+      chain is compiled and simulated, and the chain requested.
+
+## Example
+
+[examples/protocols.sauce.ts](examples/protocols.sauce.ts) calls Aave and, where the chain has it,
+PancakeSwap V3 through their namespaces; [examples/protocols.mts](examples/protocols.mts) compiles it
+for Base, Arbitrum and Optimism (the last two preview chains, compiled only), loads a protocol
+document, and compiles a protocol template.

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

@@ -0,0 +1,77 @@
+// The registries a program author reads from TypeScript: which protocols exist and where, which
+// contracts a program can call by name, the per-protocol documents, and how a protocol module's
+// SauceScript template compiles. Compiles protocols.sauce.ts the way `sauce compile` does, for
+// chains with and without PancakeSwap V3.
+//
+//   node protocols.mts
+import { readFileSync } from "node:fs";
+
+import {
+  contracts,
+  getProtocol,
+  getProtocolSkill,
+  getProtocolsByChain,
+  listProtocols,
+  listSkillSlugs,
+  routes,
+} from "@eco-incorp/sauce";
+import { compile } from "@eco-incorp/sauce/compiler";
+import * as aaveV3 from "@eco-incorp/sauce/protocols/aave-v3";
+
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`check failed: ${message}`);
+}
+
+// Catalogued on Base (metadata and deployments), a much larger set than the callable namespaces.
+const onBase = getProtocolsByChain(8453);
+check(getProtocol("pancakeswap-v3")?.slug === "pancakeswap-v3", "catalog lookup by slug");
+check(contracts.on("base").AaveV3.Pool.available, "AaveV3.Pool is a namespace on Base");
+
+// protocols.sauce.ts names PancakeSwap V3's factory by namespace, behind `available(...)`: the
+// program carries the factory where the chain has one, and compiles without it elsewhere.
+const source = readFileSync(new URL("./protocols.sauce.ts", import.meta.url), "utf8");
+const sizes: string[] = [];
+for (const [slug, hasPancake] of [
+  ["base", true],
+  ["arbitrum", true],
+  ["optimism", false],
+] as const) {
+  const factory = contracts.on(slug).PancakeswapV3.Factory;
+  check(factory.available === hasPancake, `PancakeswapV3.Factory on ${slug}: ${hasPancake}`);
+  const program = routes.compileSauceProgram(slug, source);
+  check(program.source.includes("__sauce_approve(USDC,"), "the approve is SafeERC20");
+  const bytecode = Buffer.from(program.bytecode).toString("hex");
+  check(
+    hasPancake ===
+      (factory.available && bytecode.includes(factory.address!.slice(2).toLowerCase())),
+    `the program uses the factory on ${slug} only where it exists`,
+  );
+  sizes.push(`${slug} ${program.bytecode.length} bytes`);
+}
+
+// The per-protocol documents ship as this skill's references/, and `getProtocolSkill` returns the
+// same text. Not every catalogued protocol has one.
+const document = readFileSync(new URL("../references/pancakeswap-v3.md", import.meta.url), "utf8");
+check(
+  getProtocolSkill("pancakeswap-v3") === document,
+  "references/ is what getProtocolSkill reads",
+);
+check(listSkillSlugs().length < listProtocols().length, "some protocols have no document");
+
+// Templates are named exports; their `import { X as Y } from "./abis"` is a contract import, so
+// the resolver serves `./abis` with the named ABI's JSON.
+check(!("sauceFunctions" in aaveV3), "templates are exported by name");
+const entry = new TextEncoder().encode(aaveV3.supply);
+const abi = new TextEncoder().encode(JSON.stringify(aaveV3.PoolABI));
+const template = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve: (path) => (path === "main.ts" ? entry : path === "./abis" ? abi : undefined),
+});
+
+console.log(
+  `${listProtocols().length} protocols catalogued, ${onBase.length} on Base, ${listSkillSlugs().length} documents`,
+);
+console.log(
+  `protocols.sauce.ts: ${sizes.join(", ")}; aave-v3 supply template ${template.bytecode.length} bytes`,
+);

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

@@ -0,0 +1,27 @@
+// A program reaches a catalogued protocol through its registry namespace: `AaveV3.Pool`,
+// `PancakeswapV3.Factory`. The address and the ABI come from the registry for the chain the program
+// is compiled for, with no import, and `available(...)` uses a contract only where that chain has
+// it, so the file compiles for chains without PancakeSwap V3 too.
+//
+//   sauce run protocols.sauce.ts --chain <chain> --config sauce.config.json --keystore <keystore> \
+//     --args <beneficiary> <amount>
+//
+//   beneficiary: Address  who the Aave V3 position is supplied for
+//   amount: Uint256       the Pot's USDC to supply, in its smallest units (6 decimals):
+//                         5000000000 is 5,000 USDC
+//
+// On Base, 5,000 USDC supplied for the beneficiary:
+//
+//   sauce run protocols.sauce.ts --chain base --config sauce.config.json --keystore <keystore> \
+//     --args <beneficiary> 5000000000
+function main(beneficiary: Address, amount: Uint256) {
+  // 1. Supply `amount` of the Pot's USDC to Aave V3 for `beneficiary`, approving exactly that.
+  USDC.approve(AaveV3.Pool, amount);
+  AaveV3.Pool.supply(USDC, amount, beneficiary, 0n);
+
+  // 2. Look a pool up through PancakeSwap V3's factory, where the chain has one.
+  if (available(PancakeswapV3.Factory)) {
+    const pool = PancakeswapV3.Factory.getPool(WETH, USDC, 500n);
+    require(pool != 0n, "no PancakeSwap V3 WETH/USDC 0.05% pool");
+  }
+}

package/{sdk/src/skills → skills/sauce-protocols/references}/aave-v2.md

@@ -2,11 +2,40 @@
 
 Legacy version of Aave lending protocol. Still holds significant TVL on Ethereum, Polygon, and Avalanche.
 
+## When to use it
+
+- The previous Aave generation, where a chain still runs its market. Where a chain has both,
+  Aave V3 is the current market (`aave-v3`).
+
+## Pitfalls for a program
+
+- The supply call is `deposit`, not `supply`; approve the LendingPool first.
+- aTokens are rebasing: measure balances as deltas.
+- A frozen reserve refuses new deposits: check the reserve accepts them before relying on it.
+- Borrowing and liquidation work as in Aave V3, by health factor.
+
+## In a Sauce program
+
+Deposit the Pot's USDC:
+
+```sauce chain=ethereum
+function main(amount: Uint256) {
+  const self = ctx.self();
+  USDC.approve(AaveV2.LendingPool, amount);
+  AaveV2.LendingPool.deposit(USDC, amount, self, 0n);
+}
+```
+
 ## Category
 
-lending | Chains: Ethereum (1), Polygon (137), Avalanche (43114)
+lending | Chains and addresses: [registry/aave-v2.md](registry/aave-v2.md)
+
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-## SauceScript Functions
+These import the protocol's ABI from `./abis`, the way the registry compiles them with the raw
+compiler; `sauce compile` has no such module. In a program for a chain, name the contract by its
+namespace, or import its ABI from `./protocols/<slug>/<Export>.json` as the registry file at the
+top of this document shows, and write SauceScript's values (`~0n`, not `type(uint256).max`).
 
 ### deposit
 
@@ -98,22 +127,11 @@ function main(
 - Requires ERC-20 approval to the LendingPool
 - Returns the actual repaid amount
 
-## Deployed Addresses
-
-| Chain     | Contract    | Address                                      |
-| --------- | ----------- | -------------------------------------------- |
-| Ethereum  | lendingPool | `0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9` |
-| Polygon   | lendingPool | `0x8dFf5E27EA6b7AC08EbFdf9eB090F32ee9a30fcf` |
-| Avalanche | lendingPool | `0x4F01AeD16D97E3aB5ab2B501154DC9bb0F1A5A2C` |
-
-## ABI Reference
-
-### LendingPoolABI
+## Deployments and ABI
 
-- `deposit(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)` - Deposit asset into pool
-- `withdraw(address asset, uint256 amount, address to) returns (uint256)` - Withdraw asset from pool
-- `borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)` - Borrow asset
-- `repay(address asset, uint256 amount, uint256 rateMode, address onBehalfOf) returns (uint256)` - Repay borrowed asset
+The registry's addresses per chain, how a program names each contract there (a namespace, or
+an ABI import bound to the address), and the ABI functions are generated in
+[registry/aave-v2.md](registry/aave-v2.md).
 
 ## Notes
 

package/skills/sauce-protocols/references/aave-v3.md

@@ -0,0 +1,144 @@
+# Aave V3
+
+Non-custodial liquidity protocol for earning interest on deposits and borrowing assets. The most widely deployed lending protocol in DeFi.
+
+## When to use it
+
+- Earn interest on an asset the market lists, or borrow one against everything you supplied in
+  that market. One Pool per market holds every reserve.
+- Choose it over Compound V3 when you need to borrow more than one asset against shared
+  collateral, and over Morpho Blue when you want one shared market rather than isolated ones.
+
+## Pitfalls for a program
+
+- `supply` pulls the asset with `transferFrom`: approve the Pool for exactly the amount first.
+- The aToken minted to `onBehalfOf` is rebasing: its balance grows with interest, so measure it
+  as a delta, not as the amount supplied.
+- A reserve can be frozen, paused or at its supply cap, and then `supply` reverts.
+- Borrowing needs collateral and keeps the position's health factor (from
+  `getUserAccountData`, scaled by 1e18) above 1; below it, anyone may liquidate.
+- `withdraw` with `~0n` withdraws everything; it reverts if that would leave a borrow
+  undercollateralized.
+- `flashLoanSimple` calls back a receiver contract, which a Sauce program cannot be.
+
+## In a Sauce program
+
+Supply the Pot's USDC and check the position now has collateral:
+
+```sauce chain=base,arbitrum
+function main(amount: Uint256) {
+  const self = ctx.self();
+  USDC.approve(AaveV3.Pool, amount);
+  AaveV3.Pool.supply(USDC, amount, self, 0n);
+  const account = AaveV3.Pool.getUserAccountData(self);
+  require(account.totalCollateralBase > 0n, "nothing supplied");
+}
+```
+
+## Category
+
+lending | Chains and addresses: [registry/aave-v3.md](registry/aave-v3.md)
+
+## Typed templates for the raw compiler (not for `sauce compile`)
+
+These import the protocol's ABI from `./abis`, the way the registry compiles them with the raw
+compiler; `sauce compile` has no such module. In a program for a chain, name the contract by its
+namespace, or import its ABI from `./protocols/<slug>/<Export>.json` as the registry file at the
+top of this document shows, and write SauceScript's values (`~0n`, not `type(uint256).max`).
+
+### supply
+
+Supply assets to earn interest. Mints aTokens to the supplier.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, onBehalfOf: Address): Uint256 {
+  const pool = IPool.at(poolAddress);
+  pool.supply(asset, amount, onBehalfOf, 0);
+  return 1;
+}
+```
+
+- `poolAddress`: Pool contract for the target chain
+- `asset`: ERC-20 token address to supply
+- `amount`: Amount in token's native decimals. Use `type(uint256).max` for entire balance
+- `onBehalfOf`: Address that receives aTokens (use msg.sender for self)
+- Requires ERC-20 approval to the Pool before calling
+
+### withdraw
+
+Withdraw supplied assets by burning aTokens.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, to: Address): Uint256 {
+  const pool = IPool.at(poolAddress);
+  return pool.withdraw(asset, amount, to);
+}
+```
+
+- `amount`: Use `type(uint256).max` to withdraw entire balance
+- Returns the actual withdrawn amount
+
+### borrow
+
+Borrow assets against supplied collateral.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IPool.at(poolAddress);
+  pool.borrow(asset, amount, interestRateMode, 0, onBehalfOf);
+  return 1;
+}
+```
+
+- `interestRateMode`: 1 = stable (being phased out), 2 = variable. Use 2 for variable rate
+- Must have sufficient collateral supplied first
+
+### repay
+
+Repay borrowed assets to reduce debt.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IPool.at(poolAddress);
+  return pool.repay(asset, amount, interestRateMode, onBehalfOf);
+}
+```
+
+- `interestRateMode`: Must match the debt type (1 = stable, 2 = variable)
+- `amount`: Use `type(uint256).max` to repay entire debt
+- Requires ERC-20 approval to the Pool
+
+## Deployments and ABI
+
+The registry's addresses per chain, how a program names each contract there (a namespace, or
+an ABI import bound to the address), and the ABI functions are generated in
+[registry/aave-v3.md](registry/aave-v3.md).
+
+## Notes
+
+- interestRateMode: 1 = stable (deprecated on most markets), 2 = variable
+- referralCode is always 0 (referral program inactive)
+- V3 introduced efficiency mode (eMode) for correlated assets, isolation mode for new assets, and siloed borrowing
+- All supply/repay operations require prior ERC-20 approval to the Pool address
+- healthFactor < 1e18 means position is liquidatable
+- TVL: $40B+. Audited

package/skills/sauce-protocols/references/aave-v4.md

@@ -0,0 +1,50 @@
+# Aave V4
+
+Hub-and-spoke lending. Liquidity sits in a Hub; users supply, borrow and repay through Spokes, and each Spoke addresses its assets by reserve id rather than by token address.
+
+## Category
+
+lending | Chains and addresses: [registry/aave-v4.md](registry/aave-v4.md)
+
+## Typed templates for the raw compiler (not for `sauce compile`)
+
+These import the protocol's ABI from `./abis`, the way the registry compiles them with the raw
+compiler; `sauce compile` has no such module. In a program for a chain, name the contract by its
+namespace, or import its ABI from `./protocols/<slug>/<Export>.json` as the registry file at the
+top of this document shows, and write SauceScript's values (`~0n`, not `type(uint256).max`).
+
+### supply
+
+```typescript
+import { AaveV4SpokeABI as ISpoke } from "./abis";
+
+function main(
+  spokeAddress: Address,
+  reserveId: Uint256,
+  amount: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const spoke = ISpoke.at(spokeAddress);
+  spoke.supply(reserveId, amount, onBehalfOf);
+  return 1;
+}
+```
+
+- `reserveId`: the Spoke's reserve id for the asset. Resolve it with `spoke.getReserveId(hub, hub.getAssetId(token))`
+- The underlying token must be `approve`d to the Spoke first
+
+`withdraw`, `borrow` and `repay` take the same `(reserveId, amount, onBehalfOf)` arguments.
+
+## Deployments and ABI
+
+The registry's addresses per chain, how a program names each contract there (a namespace, or
+an ABI import bound to the address), and the ABI functions are generated in
+[registry/aave-v4.md](registry/aave-v4.md).
+
+## Notes
+
+- Arc's market lists USDC, EURC, WETH and cirBTC. The Main Spoke carries all four; the Forex Spoke carries USDC and EURC
+- A chain can carry several Hubs, and a Spoke draws on one or more of them: `getReserveId(hub, assetId)` needs the Hub the asset lives in. Base carries only an equities market (tokenized stocks and USDC) with no core hub
+- Each chain also has a Treasury Spoke, which collects fees; it is not a market and is not registered
+- Hub, Spokes and their implementations are upgradeable (EIP-1967) proxies
+- Addresses come from bgd-labs/aave-address-book (`AaveV4Ethereum`, `AaveV4Base`, `AaveV4Avalanche`, `AaveV4Arc`)