@eco-incorp/sauce 0.99.6 → 0.99.7

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

@@ -1,10 +1,38 @@
 # PancakeSwap V2
 
+> **In a Sauce program**, swap through the Sauce Router wherever it services the pool, with a price limit, a minimum output and the unspent input returned (`sauce-swaps`; several pools under one limit, `sauce-distributed-swap`). The templates below call the protocol's own contracts.
+
 The most popular DEX on BNB Chain using the constant product AMM model (x*y=k). Forked from Uniswap V2 with additional features like yield farming and lottery. Expanded to 6 chains.
 
+## When to use it
+
+- A Uniswap V2 fork with a 0.25% fee, deepest on BNB Chain; the same Router interface.
+
+## Pitfalls for a program
+
+- As Uniswap V2: `amountOutMin` is the only bound, approve exactly `amountIn`, pass a deadline.
+- The 0.25% fee differs from Uniswap V2's 0.3%: quote with this protocol's Router
+  (`getAmountsOut`), not Uniswap's formula.
+
+## In a Sauce program
+
+Sell the Pot's USDC for WETH through the Router:
+
+```sauce chain=base,arbitrum
+function main(amountIn: Uint256, minOut: Uint256, recipient: Address) {
+  const self = ctx.self();
+  const before = WETH.balanceOf(self);
+  USDC.approve(PancakeswapV2.Router, amountIn);
+  PancakeswapV2.Router.swapExactTokensForTokens(amountIn, minOut, [USDC, WETH], self, ctx.timestamp());
+  const out = WETH.balanceOf(self) - before;
+  require(out >= minOut, "below minOut");
+  WETH.transfer(recipient, out);
+}
+```
+
 ## Category
 
-dex | Chains: BSC, Ethereum, Arbitrum, Base, Linea, opBNB
+dex | Chains and addresses: [registry/pancakeswap-v2.md](registry/pancakeswap-v2.md)
 
 ## Key Operations
 
@@ -12,17 +40,12 @@ dex | Chains: BSC, Ethereum, Arbitrum, Base, Linea, opBNB
 - **addLiquidity**: Deposit two tokens to mint CAKE-LP tokens
 - **removeLiquidity**: Burn LP tokens to withdraw underlying tokens
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import {
-  protocolInfo,
-  deployments,
-  sauceFunctions,
-} from "@eco-incorp/sauce/protocols/pancakeswap-v2";
-```
-
-## SauceScript Examples
+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`).
 
 ### swap
 
@@ -110,37 +133,11 @@ function main(
 - `liquidity`: Amount of LP tokens to burn
 - LP token must be approved to the router
 
-## Key Addresses
-
-| Chain    | Contract | Address                                      |
-| -------- | -------- | -------------------------------------------- |
-| BSC      | Factory  | `0xcA143Ce32Fe78f1f7019d7d551a6402fC5350c73` |
-| BSC      | Router   | `0x10ED43C718714eb63d5aA57B78B54704E256024E` |
-| Ethereum | Factory  | `0x1097053Fd2ea711dad45caCcc45EfF7548fCB362` |
-| Ethereum | Router   | `0xEfF92A263d31888d860bD50809A8D171709b7b1c` |
-| Arbitrum | Factory  | `0x02a84c1b3BBD7401a5f7fa98a384EBC70bB5749E` |
-| Arbitrum | Router   | `0x8cFe327CEc66d1C090Dd72bd0FF11d690C33a2Eb` |
-| Base     | Factory  | `0x02a84c1b3BBD7401a5f7fa98a384EBC70bB5749E` |
-| Base     | Router   | `0x8cFe327CEc66d1C090Dd72bd0FF11d690C33a2Eb` |
-| Linea    | Factory  | `0x02a84c1b3BBD7401a5f7fa98a384EBC70bB5749E` |
-| Linea    | Router   | `0x8cFe327CEc66d1C090Dd72bd0FF11d690C33a2Eb` |
-| opBNB    | Factory  | `0x02a84c1b3BBD7401a5f7fa98a384EBC70bB5749E` |
-| opBNB    | Router   | `0x8cFe327CEc66d1C090Dd72bd0FF11d690C33a2Eb` |
-
-## ABI Methods
-
-### PancakeSwapV2RouterABI
-
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline) -> uint256[] amounts` - Swap exact input along path
-- `swapTokensForExactTokens(uint256 amountOut, uint256 amountInMax, address[] path, address to, uint256 deadline) -> uint256[] amounts` - Swap to get exact output
-- `addLiquidity(address tokenA, address tokenB, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB, uint256 liquidity)` - Add liquidity and mint LP tokens
-- `removeLiquidity(address tokenA, address tokenB, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB)` - Burn LP tokens for underlying
-- `getAmountsOut(uint256 amountIn, address[] path) -> uint256[] amounts` - Quote output amounts (view)
-
-### PancakeSwapV2FactoryABI
+## Deployments and ABI
 
-- `getPair(address tokenA, address tokenB) -> address pair` - Look up pair address (view)
-- `createPair(address tokenA, address tokenB) -> address pair` - Create a new pair
+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/pancakeswap-v2.md](registry/pancakeswap-v2.md).
 
 ## Notes
 
@@ -149,3 +146,4 @@ function main(
 - Arbitrum, Base, Linea, and opBNB share the same Factory and Router addresses
 - LP tokens can be staked in MasterChef for CAKE rewards
 - PancakeSwap is the default choice for BSC trading; use PancakeSwap V3 for concentrated liquidity
+- From a Pot program, `@sauce/router` trades a PancakeSwap V2 pair directly, with no router and no approval: `uniswapV2(pair, tokenIn, tokenOut, amountIn, 2500n, minOut, recipient)` — 2500 ppm is PancakeSwap V2's 0.25% fee — reads the pair's `getReserves`, prices the output in the program with the pair's fee in parts per million, transfers the input to the pair and calls `pair.swap` with empty `data`, returning the amount out. The direction is the sort order of `tokenIn` and `tokenOut` (`token0` is the lower address), so there is no argument to get wrong. The swap consumes its whole input or reverts; there is no refund path. `tryUniswapV2` takes the same arguments and returns `0n`, moving nothing, when the pair cannot fill the whole input at the floor. The `uniswapV2Swap` action is the same call

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

@@ -0,0 +1,72 @@
+# PancakeSwap V3
+
+> **In a Sauce program**, swap through the Sauce Router wherever it services the pool, with a price limit, a minimum output and the unspent input returned (`sauce-swaps`; several pools under one limit, `sauce-distributed-swap`). The templates below call the protocol's own contracts.
+
+Concentrated liquidity AMM on BNB Chain and multiple EVM chains. Built on Uniswap V3 architecture with custom fee tiers and farming integration via the SmartRouter.
+
+## Category
+
+dex | Chains and addresses: [registry/pancakeswap-v3.md](registry/pancakeswap-v3.md)
+
+## Key Operations
+
+- **swap**: Exact input single-hop swap with fee tier selection via SmartRouter
+
+## 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`).
+
+### swap
+
+```typescript
+import { PancakeSwapV3SmartRouterABI as ISmartRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenIn: Address,
+  tokenOut: Address,
+  fee: Uint256,
+  amountIn: Uint256,
+  amountOutMin: Uint256,
+  recipient: Address,
+): Uint256 {
+  const router = ISmartRouter.at(routerAddress);
+  return router.exactInputSingle({
+    tokenIn: tokenIn,
+    tokenOut: tokenOut,
+    fee: fee,
+    recipient: recipient,
+    amountIn: amountIn,
+    amountOutMinimum: amountOutMin,
+    sqrtPriceLimitX96: 0,
+  });
+}
+```
+
+- `routerAddress`: PancakeSwap V3 SmartRouter address for the target chain
+- `tokenIn` / `tokenOut`: Input and output token addresses
+- `fee`: Pool fee tier in hundredths of a bip. Common: `100` (0.01%), `500` (0.05%), `2500` (0.25%), `10000` (1%)
+- `amountIn`: Exact input amount (in wei)
+- `amountOutMin`: Minimum output for slippage protection
+- `recipient`: Address to receive output tokens
+- `sqrtPriceLimitX96`: `0` in this template, no price limit, so `amountOutMin` is the only bound. Through the Sauce Router, set a real limit (`sauce-swaps`)
+- Note: SmartRouter does NOT include a `deadline` param in the struct (unlike Uniswap V3)
+
+## 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/pancakeswap-v3.md](registry/pancakeswap-v3.md).
+
+## Notes
+
+- Fee tiers may differ from Uniswap V3; PancakeSwap includes a 2500 (0.25%) tier
+- SmartRouter struct does NOT include `deadline` (unlike Uniswap V3's router)
+- Factory address is the same across all chains; SmartRouter addresses vary
+- NFPM address is consistent across all chains (`0x46A15B...`)
+- Swapping through the SmartRouter needs the input token approved to it; the Sauce Router needs no approval, since its callback pays the pool from the Pot (`sauce-swaps`)
+- Both tokens must be ERC20-approved to the NFPM for minting positions
+- Prefer V3 over V2 for major pairs on BSC for better capital efficiency

package/skills/sauce-protocols/references/paraswap.md

@@ -0,0 +1,39 @@
+# ParaSwap
+
+> **In a Sauce program**, swap through the Sauce Router wherever it services the pool, with a price limit, a minimum output and the unspent input returned (`sauce-swaps`; several pools under one limit, `sauce-distributed-swap`). The templates below call the protocol's own contracts.
+
+Multi-chain DEX aggregator optimizing swap rates across decentralized exchanges. Supports limit orders and delta algorithm for MEV protection.
+
+## Category
+
+aggregator | Chains and addresses: [registry/paraswap.md](registry/paraswap.md)
+
+## Key Operations
+
+- **simpleSwap**: Execute a simple single-path swap via Augustus router
+
+## 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`).
+
+```typescript
+// Note: ParaSwap requires off-chain route computation via API before on-chain execution.
+// The simpleSwap function uses complex tuple params populated from API response.
+```
+
+## 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/paraswap.md](registry/paraswap.md).
+
+## Notes
+
+- Augustus V5 and V6 both deployed on all chains
+- Delta algorithm protects against MEV/sandwich attacks
+- Route computation happens off-chain via ParaSwap API - callees/exchangeData come from API
+- Approve srcToken to Augustus contract before swapping
+- V6 is newer but V5 is more widely integrated

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

@@ -1,10 +1,42 @@
 # Pendle
 
+> **In a Sauce program**, swap through the Sauce Router wherever it services the pool, with a price limit, a minimum output and the unspent input returned (`sauce-swaps`; several pools under one limit, `sauce-distributed-swap`). The templates below call the protocol's own contracts.
+
 Yield trading protocol that tokenizes future yield. Split yield-bearing assets into principal tokens (PT) and yield tokens (YT) for trading. PT = discounted principal (fixed yield), YT = future variable yield.
 
+## When to use it
+
+- Splits a yield-bearing asset into PT (the principal, redeemable for the underlying at the
+  market's expiry: a fixed yield) and YT (the yield until then), each traded in a market per
+  expiry.
+- Choose PT to lock a fixed yield to a date, YT to speculate on the yield.
+
+## Pitfalls for a program
+
+- Each market has an expiry: PT trades below the underlying before it, and redeems at it.
+- Router calls take approximation and routing structs that Pendle's own API usually builds:
+  take that calldata as `main`'s input, approve the input, forward it, and check the PT you
+  got as a delta.
+- PT and YT are separate tokens per market: name the right one.
+
+## In a Sauce program
+
+Buy PT with calldata from Pendle's API, checked by the PT received:
+
+```sauce chain=arbitrum,ethereum
+function main(tokenIn: Address, amountIn: Uint256, pt: Address, minPtOut: Uint256, call: bytes) {
+  const self = ctx.self();
+  const before = Token(pt).balanceOf(self);
+  Token(tokenIn).approve(Pendle.Router, amountIn);
+  evm.call(Pendle.Router, 0n, call);
+  const out = Token(pt).balanceOf(self) - before;
+  require(out >= minPtOut, "below minPtOut");
+}
+```
+
 ## Category
 
-yield | Chains: Ethereum, Arbitrum
+yield | Chains and addresses: [registry/pendle.md](registry/pendle.md)
 
 ## Key Operations
 
@@ -13,13 +45,12 @@ yield | Chains: Ethereum, Arbitrum
 - **addLiquiditySingleToken**: Add single-sided liquidity to a Pendle market
 - **removeLiquiditySingleToken**: Remove liquidity and receive single token
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/pendle";
-```
-
-## SauceScript Examples
+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`).
 
 ```typescript
 // Buy PT (fixed yield)
@@ -113,29 +144,11 @@ function main(
 }
 ```
 
-## Key Addresses
-
-| Chain    | Contract | Address                                      |
-| -------- | -------- | -------------------------------------------- |
-| Ethereum | router   | `0x888888888889758F76e7103c6CbF23ABbF58F946` |
-| Arbitrum | router   | `0x888888888889758F76e7103c6CbF23ABbF58F946` |
+## Deployments and ABI
 
-## ABI Methods
-
-### PendleRouterABI
-
-- `swapExactTokenForPt(address,address,uint256,tuple,tuple,tuple)` - Buy PT. Complex params: receiver, market, minPtOut, ApproxParams, TokenInput, LimitOrderData
-- `swapExactTokenForYt(address,address,uint256,tuple,tuple,tuple)` - Buy YT. Same param structure as swapExactTokenForPt
-- `addLiquiditySingleToken(address,address,uint256,tuple,tuple,tuple)` - Add single-sided liquidity. Params: receiver, market, minLpOut, ApproxParams, TokenInput, LimitOrderData
-- `removeLiquiditySingleToken(address,address,uint256,tuple,tuple)` - Remove liquidity. Params: receiver, market, netLpToRemove, TokenOutput, LimitOrderData
-
-### Param Structs
-
-- **ApproxParams**: { guessMin, guessMax, guessOffchain, maxIteration, eps } - Binary search params for PT/YT amount
-- **TokenInput**: { tokenIn, netTokenIn, tokenMintSy, pendleSwap, swapData } - Input token config
-- **TokenOutput**: { tokenOut, minTokenOut, tokenRedeemSy, pendleSwap, swapData } - Output token config
-- **SwapData**: { swapType, extRouter, extCalldata, needScale } - External swap config (use zeros for direct)
-- **LimitOrderData**: { limitRouter, epsSkipMarket, normalFills, flashFills, optData } - Limit orders (use zeros/empty)
+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/pendle.md](registry/pendle.md).
 
 ## Notes
 
@@ -145,3 +158,8 @@ function main(
 - For limit orders: set limitRouter to zero address, empty arrays for fills
 - ApproxParams eps is typically 1e15 (0.1%), maxIteration typically 256
 - tokenMintSy = the token that the SY (standardized yield) wrapper accepts
+- **ApproxParams**: { guessMin, guessMax, guessOffchain, maxIteration, eps } - Binary search params for PT/YT amount
+- **TokenInput**: { tokenIn, netTokenIn, tokenMintSy, pendleSwap, swapData } - Input token config
+- **TokenOutput**: { tokenOut, minTokenOut, tokenRedeemSy, pendleSwap, swapData } - Output token config
+- **SwapData**: { swapType, extRouter, extCalldata, needScale } - External swap config (use zeros for direct)
+- **LimitOrderData**: { limitRouter, epsSkipMarket, normalFills, flashFills, optData } - Limit orders (use zeros/empty)

package/skills/sauce-protocols/references/permit2.md

@@ -0,0 +1,101 @@
+# Permit2
+
+Universal token approval infrastructure by Uniswap. Provides a single approval contract for all DeFi protocols, improving security and UX.
+
+## When to use it
+
+- Uniswap's token-approval contract at one address on every chain it is on. A signature transfer
+  (`permitTransferFrom`) moves a user's tokens with a one-time signed permit; an allowance
+  transfer (`approve` with an expiry, then `transferFrom`) works like an expiring ERC-20
+  allowance.
+- `sauce run --fund` pulls with Permit2 by default: the owner signs, the Pot receives.
+
+## Pitfalls for a program
+
+- The user approves Permit2 itself once per token, by an ordinary ERC-20 `approve`.
+- A signed permit names the spender (the contract calling Permit2: the Pot), the amount, a
+  nonce and a deadline; nonces are unordered bits, each usable once.
+- Allowance amounts are `uint160` and expiries `uint48`.
+
+## In a Sauce program
+
+Pull a user's tokens into the Pot with their signed permit:
+
+```sauce chain=base,arbitrum
+function main(
+  owner: Address,
+  token: Address,
+  amount: Uint256,
+  nonce: Uint256,
+  deadline: Uint256,
+  signature: bytes
+) {
+  const self = ctx.self();
+  const permit = { permitted: { token: token, amount: amount }, nonce: nonce, deadline: deadline };
+  const details = { to: self, requestedAmount: amount };
+  const before = Token(token).balanceOf(self);
+  Permit2.Permit2.permitTransferFrom(permit, details, owner, signature);
+  require(Token(token).balanceOf(self) - before == amount, "the permit moved another amount");
+}
+```
+
+## Category
+
+infrastructure | Chains and addresses: [registry/permit2.md](registry/permit2.md)
+
+## Key Operations
+
+- **approve**: Set token allowance for a spender via Permit2
+- **transferFrom**: Transfer tokens using a Permit2 allowance
+
+## 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`).
+
+```typescript
+// Approve token via Permit2
+import { Permit2ABI as IPermit2 } from "./abis";
+function main(
+  permit2Address: Address,
+  token: Address,
+  spender: Address,
+  amount: Uint256,
+  expiration: Uint256,
+): Uint256 {
+  const permit2 = IPermit2.at(permit2Address);
+  permit2.approve(token, spender, amount, expiration);
+  return 1;
+}
+
+// Transfer tokens using Permit2 allowance
+import { Permit2ABI as IPermit2 } from "./abis";
+function main(
+  permit2Address: Address,
+  from: Address,
+  to: Address,
+  amount: Uint256,
+  token: Address,
+): Uint256 {
+  const permit2 = IPermit2.at(permit2Address);
+  permit2.transferFrom(from, to, amount, token);
+  return 1;
+}
+```
+
+## 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/permit2.md](registry/permit2.md).
+
+## Notes
+
+- Same address on all 7 chains (deterministic CREATE2 deployment)
+- Approve once: ERC-20 approve to Permit2, then use Permit2 to manage per-protocol allowances
+- amount is uint160 (not uint256) - max value is type(uint160).max
+- expiration is uint48 unix timestamp - approvals auto-expire for security
+- Uniswap V3/V4, 1inch, and many protocols use Permit2 for token transfers
+- lockdown is an emergency function to batch-revoke compromised approvals

package/skills/sauce-protocols/references/perpetual-protocol.md

@@ -0,0 +1,53 @@
+# Perpetual Protocol
+
+Decentralized perpetual futures exchange (Curie v2) on Optimism. Concentrated-liquidity virtual AMM with cross-margin trading.
+
+## Category
+
+perpetuals | Chains and addresses: [registry/perpetual-protocol.md](registry/perpetual-protocol.md)
+
+## Key Operations
+
+- **deposit**: Deposit collateral into Vault for trading
+- **withdraw**: Withdraw collateral from Vault
+- **openPosition**: Open a leveraged perpetual position
+- **closePosition**: Close an existing perpetual position
+
+## 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`).
+
+```typescript
+// Deposit collateral
+import { VaultABI as IVault } from "./abis";
+function main(vaultAddress: Address, token: Address, amount: Uint256): Uint256 {
+  const vault = IVault.at(vaultAddress);
+  vault.deposit(token, amount);
+  return 1;
+}
+
+// Withdraw collateral
+import { VaultABI as IVault } from "./abis";
+function main(vaultAddress: Address, token: Address, amount: Uint256): Uint256 {
+  const vault = IVault.at(vaultAddress);
+  vault.withdraw(token, amount);
+  return 1;
+}
+```
+
+## 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/perpetual-protocol.md](registry/perpetual-protocol.md).
+
+## Notes
+
+- Virtual AMM (vAMM) based pricing - no actual liquidity pools
+- Cross-margin trading - all positions share the same collateral
+- isBaseToQuote: true = short (sell base for quote), false = long (buy base with quote)
+- Deposit collateral to Vault first, then trade via ClearingHouse
+- sqrtPriceLimitX96 = 0 means no price limit (market order)

package/{sdk/src/skills → skills/sauce-protocols/references}/polygon-bridge.md

@@ -4,9 +4,14 @@ Official Polygon PoS bridge via RootChainManager. Supports ETH, ERC-20, ERC-721,
 
 ## Category
 
-native L2 bridge | Direction: L1 to L2 (Ethereum to Polygon) | Chains: Ethereum (1), Polygon (137)
+native L2 bridge | Direction: L1 to L2 (Ethereum to Polygon) | Chains and addresses: [registry/polygon-bridge.md](registry/polygon-bridge.md)
 
-## SauceScript Functions
+## 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`).
 
 ### depositETH
 
@@ -50,22 +55,11 @@ function main(
 - `depositData`: ABI-encoded amount as bytes. Encode via `abi.encode(uint256 amount)`
 - Requires ERC-20 approval to the **ERC20Predicate** contract (NOT the RootChainManager)
 
-## Deployed Addresses
-
-| Chain    | Contract          | Address                                      |
-| -------- | ----------------- | -------------------------------------------- |
-| Ethereum | rootChainManager  | `0xA0c68C638235ee32657e8f720a23ceC1bFc77C77` |
-| Ethereum | erc20Predicate    | `0x40ec5B33f54e0E8A33A975908C5BA1c14e5BbbDf` |
-| Ethereum | etherPredicate    | `0x8484Ef722627bf18ca5Ae6BcF031c23E6e922B30` |
-| Polygon  | childChainManager | `0xA6FA4fB5f76172d178d61B04b0ecd319C5d1C0aa` |
-
-## ABI Reference
-
-### PolygonRootChainManagerABI
+## Deployments and ABI
 
-- `depositEtherFor(address user)` [payable] - Deposit ETH to Polygon for a specified user. Received as WETH
-- `depositFor(address user, address rootToken, bytes depositData)` - Deposit ERC-20 tokens to Polygon. `depositData` = ABI-encoded amount
-- `exit(bytes inputData)` - Process a withdrawal on L1 using a burn proof from Polygon (checkpoint-based)
+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/polygon-bridge.md](registry/polygon-bridge.md).
 
 ## Notes
 

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

@@ -4,7 +4,7 @@ Decentralized options protocol with an AMM-based pricing model and concentrated
 
 ## Category
 
-options | Chains: Arbitrum
+options | Chains and addresses: [registry/premia.md](registry/premia.md)
 
 ## Key Operations
 
@@ -12,13 +12,12 @@ options | Chains: Arbitrum
 - **settle**: Settle a short options position after expiry
 - **trade**: Buy or sell options via the Premia AMM
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/premia";
-```
-
-## SauceScript Examples
+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`).
 
 Premia v3 has one pool contract per market (base, quote, strike, maturity, call/put), deployed by the PoolFactory; its `PoolDeployed` event names each pool. `exercise` and `settle` act on the caller's own position in that pool.
 
@@ -38,19 +37,11 @@ function main(poolAddress: Address): Uint256 {
 }
 ```
 
-## Key Addresses
-
-| Chain    | Contract    | Address                                      |
-| -------- | ----------- | -------------------------------------------- |
-| Arbitrum | poolFactory | `0xAE4fB6622F25f397587F11638dA8CE88C27b5645` |
-
-## ABI Methods
-
-### DiamondABI (a Premia v3 pool)
+## Deployments and ABI
 
-- `trade(uint256 size, bool isBuy, uint256 premiumLimit, address referrer) returns (uint256 totalPremium, (int256 collateral, int256 longs, int256 shorts) delta)` - Buy/sell options from the pool's AMM. `size` is 18-decimal
-- `exercise() returns (uint256 exerciseValue, uint256 exerciseFee)` - Exercise the caller's long position after maturity
-- `settle() returns (uint256 collateral)` - Settle the caller's short position after maturity
+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/premia.md](registry/premia.md).
 
 ## Notes
 

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

@@ -4,20 +4,19 @@ Liquid restaking protocol that issues pufETH via an ERC-4626 vault. Deposits are
 
 ## Category
 
-restaking | Chains: Ethereum
+restaking | Chains and addresses: [registry/puffer.md](registry/puffer.md)
 
 ## Key Operations
 
 - **deposit**: Deposit assets into PufferVault, receive pufETH shares
 - **redeem**: Redeem pufETH shares for underlying assets
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/puffer";
-```
-
-## SauceScript Examples
+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`).
 
 ```typescript
 // Deposit into PufferVault
@@ -40,21 +39,11 @@ function main(
 }
 ```
 
-## Key Addresses
-
-| Chain    | Contract             | Address                                      |
-| -------- | -------------------- | -------------------------------------------- |
-| Ethereum | pufETH / pufferVault | `0xD9A442856C234a39a81a089C06451EBAa4306a72` |
-
-## ABI Methods
-
-### PufferVaultABI (ERC-4626)
+## Deployments and ABI
 
-- `deposit(uint256,address)` - Deposit assets, receive pufETH shares. Returns shares minted
-- `redeem(uint256,address,address)` - Redeem shares for assets. Params: shares, receiver, owner
-- `convertToShares(uint256)` - Preview shares for asset amount
-- `convertToAssets(uint256)` - Preview assets for share amount
-- `balanceOf(address)` - Query pufETH balance
+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/puffer.md](registry/puffer.md).
 
 ## Notes