@eco-incorp/sauce 0.99.5 → 0.99.7

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
 

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

@@ -0,0 +1,45 @@
+# Pyth Network
+
+High-fidelity oracle network providing low-latency price feeds from institutional sources. Uses pull-based model for efficient on-chain price updates.
+
+## Category
+
+oracle | Chains and addresses: [registry/pyth.md](registry/pyth.md)
+
+## Key Operations
+
+- **getPrice**: Read price from Pyth oracle by price feed ID
+
+## 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
+// Get price by feed ID
+import { PythOracleABI as IPythOracle } from "./abis";
+function main(
+  oracleAddress: Address,
+  priceId: Uint256,
+): { price: Uint256; conf: Uint256; expo: Uint256; publishTime: Uint256 } {
+  const oracle = IPythOracle.at(oracleAddress);
+  return oracle.getPrice(priceId);
+}
+```
+
+## 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/pyth.md](registry/pyth.md).
+
+## Notes
+
+- Pull-based oracle: users must call updatePriceFeeds before reading prices
+- Sub-second latency from institutional market data providers
+- Actual price = price * 10^expo (e.g. price=12345, expo=-2 means $123.45)
+- Price feed IDs are bytes32 - see Pyth docs for specific feed IDs per asset
+- updatePriceFeeds requires sending ETH to pay the update fee (use getUpdateFee to check)
+- Get price update data from Pyth Hermes API off-chain, then submit on-chain

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

@@ -1,10 +1,12 @@
 # QuickSwap
 
+> **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 leading DEX on Polygon with V2 (constant product, x*y=k) and V3 (Algebra-based concentrated liquidity with dynamic fees) pools. Low-fee trading powered by Polygon's infrastructure.
 
 ## Category
 
-dex | Chains: Polygon
+dex | Chains and addresses: [registry/quickswap.md](registry/quickswap.md)
 
 ## Key Operations
 
@@ -13,13 +15,12 @@ dex | Chains: Polygon
 - **addLiquidity**: Add liquidity to V2 pools
 - **removeLiquidity**: Remove liquidity from V2 pools
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/quickswap";
-```
-
-## 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`).
 
 ### swapV2
 
@@ -71,7 +72,7 @@ function main(
 ```
 
 - No `fee` parameter: QuickSwap V3 uses Algebra protocol with dynamic fees (not fixed fee tiers)
-- `limitSqrtPrice`: Set to `0` for no price limit
+- `limitSqrtPrice`: `0` in this template, no price limit, so `amountOutMin` is the only bound. QuickSwap V3 is an Algebra pool, which the Sauce Router's `swapV3` drives with a real limit (`sauce-swaps`)
 
 ### addLiquidity
 
@@ -133,26 +134,11 @@ function main(
 
 - LP token must be approved to the V2 router
 
-## Key Addresses
-
-| Chain   | Contract      | Address                                      |
-| ------- | ------------- | -------------------------------------------- |
-| Polygon | V2 Factory    | `0x5757371414417b8C6CAad45bAeF941aBc7d3Ab32` |
-| Polygon | V2 Router     | `0xa5E0829CaCEd8fFDD4De3c43696c57F7D7A678ff` |
-| Polygon | V3 Factory    | `0x411b0fAcC3489691f28ad58c47006AF5E3Ab3A28` |
-| Polygon | V3 SwapRouter | `0xf5b509bB0909a69B1c207E495f687a596C168e12` |
-
-## ABI Methods
-
-### QuickSwapV2RouterABI
-
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline) -> uint256[] amounts` - V2 swap exact input along path
-- `addLiquidity(address tokenA, address tokenB, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB, uint256 liquidity)` - Add V2 LP
-- `removeLiquidity(address tokenA, address tokenB, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB)` - Remove V2 LP
-
-### QuickSwapV3SwapRouterABI
+## Deployments and ABI
 
-- `exactInputSingle(tuple(address tokenIn, address tokenOut, address recipient, uint256 deadline, uint256 amountIn, uint256 amountOutMinimum, uint160 limitSqrtPrice)) -> uint256 amountOut` - V3 concentrated liquidity swap with dynamic fees
+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/quickswap.md](registry/quickswap.md).
 
 ## Notes