@eco-incorp/sauce 0.99.6 → 0.99.7

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

@@ -0,0 +1,188 @@
+# Uniswap 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 allowing LPs to allocate capital within custom price ranges for higher capital efficiency. Supports multiple fee tiers per pair and NFT-based liquidity positions.
+
+## When to use it
+
+- Concentrated-liquidity pools in fee tiers of 0.01%, 0.05%, 0.3% and 1% (`100n`, `500n`,
+  `3000n`, `10000n`): usually the deepest pools for liquid pairs.
+- A Sauce program swaps a pool through the Sauce Router's `swapV3`, with a price limit; the
+  Factory finds the pool, the position manager manages liquidity positions.
+
+## Pitfalls for a program
+
+- A pool pays out first and then calls back for its input: only the Sauce Router can pay that
+  callback from a program, so do not call `pool.swap` yourself.
+- Each fee tier is a separate pool, with its own price and depth.
+- The price limit bounds the pool's price, not the price paid: the fee comes on top
+  (`sauce-swaps`).
+- Uniswap's own SwapRouter takes a `deadline` in its params; SwapRouter02 does not.
+
+## In a Sauce program
+
+One guarded swap on the 0.05% WETH/USDC pool:
+
+```sauce chain=base,arbitrum
+import { ISauceRouter } from "./artifacts/ISauceRouter.json";
+
+function main(amountIn: Uint256, sqrtPriceLimitX96: Uint256, minOut: Uint256, recipient: Address) {
+  const self = ctx.self();
+  const pool = UniswapV3.Factory.getPool(WETH, USDC, 500n);
+  require(pool != 0n, "no WETH/USDC pool at 0.05%");
+  const before = USDC.balanceOf(self);
+  ISauceRouter.at(self).swapV3(pool, WETH, USDC, amountIn, sqrtPriceLimitX96, self, self);
+  const out = USDC.balanceOf(self) - before;
+  require(out >= minOut, "below minOut");
+  USDC.transfer(recipient, out);
+  const unspent = WETH.balanceOf(self);
+  if (unspent > 0n) {
+    WETH.transfer(recipient, unspent);
+  }
+}
+```
+
+## Category
+
+dex | Chains and addresses: [registry/uniswap-v3.md](registry/uniswap-v3.md)
+
+## Key Operations
+
+- **swap**: Swap tokens using exact input (single-hop or multi-hop via encoded path)
+- **addLiquidity**: Mint a new concentrated liquidity position as an NFT within a tick range
+- **removeLiquidity**: Decrease liquidity from an existing NFT 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`).
+
+### swap
+
+```typescript
+import { UniswapV3SwapRouterABI as ISwapRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenIn: Address,
+  tokenOut: Address,
+  fee: Uint256,
+  amountIn: Uint256,
+  amountOutMin: Uint256,
+  recipient: Address,
+): Uint256 {
+  const router = ISwapRouter.at(routerAddress);
+  return router.exactInputSingle({
+    tokenIn: tokenIn,
+    tokenOut: tokenOut,
+    fee: fee,
+    recipient: recipient,
+    deadline: 99999999999,
+    amountIn: amountIn,
+    amountOutMinimum: amountOutMin,
+    sqrtPriceLimitX96: 0,
+  });
+}
+```
+
+- `routerAddress`: Uniswap V3 SwapRouter address for the target chain. This `swap` uses SwapRouter's params (with `deadline`); chains that only have SwapRouter02 (Base, BSC, Avalanche, Celo, Monad) need `UniswapV3SwapRouter02ABI`, whose params have no `deadline`
+- `tokenIn` / `tokenOut`: Input and output token addresses
+- `fee`: Pool fee tier in hundredths of a bip. Common values: `500` (0.05%), `3000` (0.3%), `10000` (1%)
+- `amountIn`: Exact amount of input token (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`)
+
+### addLiquidity (mint position)
+
+```typescript
+import { UniswapV3NonfungiblePositionManagerABI as INonfungiblePositionManager } from "./abis";
+
+function main(
+  nfpmAddress: Address,
+  token0: Address,
+  token1: Address,
+  fee: Uint256,
+  tickLower: Uint256,
+  tickUpper: Uint256,
+  amount0Desired: Uint256,
+  amount1Desired: Uint256,
+  amount0Min: Uint256,
+  amount1Min: Uint256,
+  recipient: Address,
+): { tokenId: Uint256; liquidity: Uint256; amount0: Uint256; amount1: Uint256 } {
+  const nfpm = INonfungiblePositionManager.at(nfpmAddress);
+  return nfpm.mint({
+    token0: token0,
+    token1: token1,
+    fee: fee,
+    tickLower: tickLower,
+    tickUpper: tickUpper,
+    amount0Desired: amount0Desired,
+    amount1Desired: amount1Desired,
+    amount0Min: amount0Min,
+    amount1Min: amount1Min,
+    recipient: recipient,
+    deadline: 99999999999,
+  });
+}
+```
+
+- `nfpmAddress`: NonfungiblePositionManager contract address
+- `token0` / `token1`: Pair tokens sorted by address (token0 < token1)
+- `fee`: Pool fee tier (500, 3000, or 10000)
+- `tickLower` / `tickUpper`: Price range boundaries as tick values. Ticks must be multiples of the pool's tick spacing (10 for 0.05%, 60 for 0.3%, 200 for 1%)
+- `amount0Desired` / `amount1Desired`: Target deposit amounts
+- `amount0Min` / `amount1Min`: Minimum deposit amounts (slippage protection)
+- Both tokens must be approved to the NonfungiblePositionManager
+
+### removeLiquidity (decrease liquidity)
+
+```typescript
+import { UniswapV3NonfungiblePositionManagerABI as INonfungiblePositionManager } from "./abis";
+
+function main(
+  nfpmAddress: Address,
+  tokenId: Uint256,
+  liquidity: Uint256,
+  amount0Min: Uint256,
+  amount1Min: Uint256,
+): { amount0: Uint256; amount1: Uint256 } {
+  const nfpm = INonfungiblePositionManager.at(nfpmAddress);
+  return nfpm.decreaseLiquidity({
+    tokenId: tokenId,
+    liquidity: liquidity,
+    amount0Min: amount0Min,
+    amount1Min: amount1Min,
+    deadline: 99999999999,
+  });
+}
+```
+
+- `tokenId`: NFT ID of the liquidity position
+- `liquidity`: Amount of liquidity to remove (not token amounts)
+- `amount0Min` / `amount1Min`: Minimum tokens to receive (slippage protection)
+- After decreasing liquidity, call `collect` to actually withdraw the tokens
+
+## 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/uniswap-v3.md](registry/uniswap-v3.md).
+
+## Notes
+
+- Fee tiers: `100` (0.01%, stablecoins), `500` (0.05%, correlated pairs), `3000` (0.3%, standard), `10000` (1%, exotic)
+- Token order matters: `token0` must be the lower address. Sort before calling mint
+- Tick spacing varies by fee tier: 1 (0.01%), 10 (0.05%), 60 (0.3%), 200 (1%)
+- After `decreaseLiquidity`, tokens sit in the position until `collect` is called
+- For multi-hop swaps via `exactInput`, the `path` is ABI-encoded as `tokenIn + fee + tokenMiddle + fee + tokenOut`
+- Input token must be ERC20-approved to the SwapRouter for swaps
+- Both tokens must be ERC20-approved to the NFPM for minting positions
+- Prefer V3 over V2 for major pairs to benefit from concentrated liquidity and lower effective slippage
+- From a Pot program, `@sauce/router`'s `uniswapV3(pool, tokenIn, tokenOut, amountIn, sqrtPriceLimitX96, minOut, recipient)` swaps one pool through the Pot's Sauce Router, which answers the pool's callback from the Pot — no SwapRouter and no approval — checks the pool's tokens, sends `amountIn` as positive exact input, and returns the amount out. A path is one call per pool, each spending the last one's output. The `uniswapV3Swap` action is the same call
+- On Arc (5042) `WETH9()` on SwapRouter02 and the position manager is a stub that always reverts with `UnsupportedProtocolError()`, so `unwrapWETH9`, `refundETH` and native-value swaps revert. Trade USDC's ERC-20 `0x3600000000000000000000000000000000000000`; Arc's native coin is USDC and it has no canonical wrapped native
+- SwapRouter02's params structs drop `deadline` (wrap the call in a deadline check if needed).

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

@@ -0,0 +1,155 @@
+# Uniswap V4
+
+> **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.
+
+Singleton AMM with hooks architecture enabling custom pool logic, flash accounting, and native ETH support. All pools share a single PoolManager contract for gas savings on multi-hop swaps.
+
+## When to use it
+
+- Every pool lives in one PoolManager, keyed by `(currency0, currency1, fee, tickSpacing,
+hooks)`. A pool can attach a hook contract that runs around swaps and liquidity changes, and a
+  currency of `0x0` is the native coin.
+- A Sauce program swaps through the Sauce Router's `swapV4`, with a price limit; no
+  UniversalRouter commands are needed.
+
+## Pitfalls for a program
+
+- Exact input is a **negative** `amountSpecified` (`-amount`), the reverse of V3's pool.
+- A hook can change a pool's behaviour and fee: use hookless keys (`hooks: 0n`) unless you have
+  reviewed the hook.
+- A protocol fee can apply on top of the LP fee; both are in the pool's state
+  (`sauce-distributed-swap` reads them).
+- Anyone can initialize a key: a pool can exist with no liquidity at a stale price. Read its
+  liquidity before trusting its price.
+- A native-coin pool (`currency0` of `0x0`) is a different pair from the WETH pools.
+
+## In a Sauce program
+
+One guarded swap on the hookless 0.05% WETH/USDC pool:
+
+```sauce chain=base,arbitrum
+import { ISauceRouter } from "./artifacts/ISauceRouter.json";
+
+function main(amountIn: Uint256, sqrtPriceLimitX96: Uint256, minOut: Uint256, recipient: Address) {
+  const self = ctx.self();
+  const zeroForOne = WETH < USDC;
+  const key = {
+    currency0: zeroForOne ? WETH : USDC,
+    currency1: zeroForOne ? USDC : WETH,
+    fee: 500n,
+    tickSpacing: 10n,
+    hooks: 0n
+  };
+  const before = USDC.balanceOf(self);
+  ISauceRouter.at(self).swapV4(UniswapV4.PoolManager, key, zeroForOne, -amountIn, sqrtPriceLimitX96, self, self);
+  const out = USDC.balanceOf(self) - before;
+  require(out >= minOut, "below minOut");
+  USDC.transfer(recipient, out);
+  const unspent = WETH.balanceOf(self);
+  if (unspent > 0n) {
+    WETH.transfer(recipient, unspent);
+  }
+}
+```
+
+## Category
+
+dex | Chains and addresses: [registry/uniswap-v4.md](registry/uniswap-v4.md)
+
+## Key Operations
+
+- **swap**: Execute a swap through the UniversalRouter using command-based encoding
+- **addLiquidity**: Modify liquidity positions through the PositionManager
+- **removeLiquidity**: Decrease or remove liquidity positions through the PositionManager
+
+## 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 { UniswapV4UniversalRouterABI as IUniversalRouter } from "./abis";
+
+function main(routerAddress: Address, commands: bytes, inputs: bytes[]): Uint256 {
+  const router = IUniversalRouter.at(routerAddress);
+  router.execute(commands, inputs, 99999999999);
+  return 1;
+}
+```
+
+- `routerAddress`: UniversalRouter address for the target chain
+- `commands`: Encoded bytes of command IDs defining the sequence of operations (each byte = one command)
+- `inputs`: Encoded bytes array of ABI-encoded parameters for each command
+- Commands and inputs must be pre-encoded off-chain; the router decodes and executes sequentially
+
+### addLiquidity
+
+```typescript
+import { UniswapV4PositionManagerABI as IPositionManager } from "./abis";
+
+function main(positionManagerAddress: Address, unlockData: bytes): Uint256 {
+  const pm = IPositionManager.at(positionManagerAddress);
+  pm.modifyLiquidities(unlockData, 99999999999);
+  return 1;
+}
+```
+
+- `positionManagerAddress`: PositionManager address for the target chain
+- `unlockData`: ABI-encoded liquidity modification data including pool key, tick range, and amounts
+- Data must be pre-encoded off-chain with the position parameters
+
+### removeLiquidity
+
+```typescript
+import { UniswapV4PositionManagerABI as IPositionManager } from "./abis";
+
+function main(positionManagerAddress: Address, unlockData: bytes): Uint256 {
+  const pm = IPositionManager.at(positionManagerAddress);
+  pm.modifyLiquidities(unlockData, 99999999999);
+  return 1;
+}
+```
+
+- Same interface as addLiquidity but with negative liquidityDelta in the encoded data
+
+## 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/uniswap-v4.md](registry/uniswap-v4.md).
+
+### UniswapV4StateViewABI
+
+StateView (v4-periphery `src/lens/StateView.sol`) reads the PoolManager's pool state as views. A `poolId` is a `bytes32`: keccak256 of the ABI-encoded pool key.
+
+- `getSlot0(bytes32 poolId) -> (uint160 sqrtPriceX96, int24 tick, uint24 protocolFee, uint24 lpFee)` - Current price, tick and fees
+- `getLiquidity(bytes32 poolId) -> uint128 liquidity` - In-range liquidity
+- `getTickInfo(bytes32 poolId, int24 tick) -> (uint128 liquidityGross, int128 liquidityNet, uint256 feeGrowthOutside0X128, uint256 feeGrowthOutside1X128)` - One tick's state
+- `getTickLiquidity(bytes32 poolId, int24 tick) -> (uint128 liquidityGross, int128 liquidityNet)` - One tick's liquidity
+- `getTickFeeGrowthOutside(bytes32 poolId, int24 tick) -> (uint256 feeGrowthOutside0X128, uint256 feeGrowthOutside1X128)` - One tick's fee growth outside
+- `getTickBitmap(bytes32 poolId, int16 tick) -> uint256 tickBitmap` - One word of the initialized-tick bitmap
+- `getFeeGrowthGlobals(bytes32 poolId) -> (uint256 feeGrowthGlobal0, uint256 feeGrowthGlobal1)` - Global fee growth
+- `getFeeGrowthInside(bytes32 poolId, int24 tickLower, int24 tickUpper) -> (uint256 feeGrowthInside0X128, uint256 feeGrowthInside1X128)` - Fee growth inside a range
+- `getPositionInfo(bytes32 poolId, bytes32 positionId) -> (uint128 liquidity, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128)` - A position by id
+- `getPositionInfo(bytes32 poolId, address owner, int24 tickLower, int24 tickUpper, bytes32 salt) -> (uint128 liquidity, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128)` - A position by its key
+- `getPositionLiquidity(bytes32 poolId, bytes32 positionId) -> uint128 liquidity` - A position's liquidity
+- `poolManager() -> address` - The PoolManager it reads
+
+## Notes
+
+- V4 uses a singleton architecture: ALL pools live in a single PoolManager contract, saving gas on multi-hop swaps
+- Hooks: each pool can attach a custom hooks contract that intercepts before/after swap and liquidity events
+- Pool key: `(currency0, currency1, fee, tickSpacing, hooks)` uniquely identifies a pool
+- `currency0` = address(0) means native ETH; V4 supports native ETH directly (no WETH wrapping needed)
+- `zeroForOne`: true = swap currency0 for currency1; false = swap currency1 for currency0
+- `amountSpecified`: negative = exact input; positive = exact output (the reverse of Uniswap V3's pool `swap`)
+- Flash accounting: V4 uses transient storage for balance tracking within a transaction, settling at the end
+- Commands/inputs for the UniversalRouter must be constructed off-chain; this is more complex than V3 but more powerful
+- A Sauce program needs no UniversalRouter commands: the Sauce Router's `swapV4(poolManager, key, zeroForOne, -amount, sqrtPriceLimitX96, payer, recipient)` unlocks the PoolManager and settles the swap itself (`sauce-swaps`)
+- V4 is the newest Uniswap version; use it for advanced pool logic (custom hooks) or when gas efficiency on multi-hop matters most
+- From a Pot program, `@sauce/router`'s `uniswapV4(poolManager, tokenIn, tokenOut, amountIn, fee, tickSpacing, hooks, sqrtPriceLimitX96, minOut, recipient)` swaps one pool through the Pot's Sauce Router, which unlocks the PoolManager, swaps, takes the output and settles the input from the Pot — no UniversalRouter and no approval. The pool key is `tokenIn` and `tokenOut` in sort order (native ETH, the zero address, first) with `fee`, `tickSpacing` and `hooks`; the function passes `-amountIn`, exact input, and returns the amount out. The `uniswapV4Swap` action is the same call
+- On Arc (5042) the PositionManager's `WETH9()` is a stub that always reverts with `UnsupportedProtocolError()`. Arc's native coin is USDC at 18 decimals, so a pool keyed on `address(0)` is native USDC, a different currency from the 6-decimal ERC-20 `0x3600000000000000000000000000000000000000` over the same balance

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

@@ -0,0 +1,63 @@
+# UnitFlow 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 Arc, forked from Uniswap V3 with native USDC in place of WETH9.
+
+## Category
+
+dex | Chains and addresses: [registry/unitflow-v3.md](registry/unitflow-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`).
+
+### swap
+
+Exact-input single-hop swap through UnitFlowV3Router.
+
+```typescript
+import { UnitFlowV3RouterABI as IRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenIn: Address,
+  tokenOut: Address,
+  fee: Uint256,
+  amountIn: Uint256,
+  amountOutMin: Uint256,
+  recipient: Address,
+  deadline: Uint256,
+): Uint256 {
+  const router = IRouter.at(routerAddress);
+  return router.exactInputSingle({
+    tokenIn: tokenIn,
+    tokenOut: tokenOut,
+    fee: fee,
+    recipient: recipient,
+    deadline: deadline,
+    amountIn: amountIn,
+    amountOutMinimum: amountOutMin,
+    sqrtPriceLimitX96: 0,
+  });
+}
+```
+
+- The router has Uniswap V3 SwapRouter's shape: its params include `deadline`
+- `tokenIn` must be `approve`d to the router
+
+## 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/unitflow-v3.md](registry/unitflow-v3.md).
+
+## Notes
+
+- Pools call back `unitFlowV3SwapCallback`, not `uniswapV3SwapCallback`, so a contract that swaps against a pool directly must implement the renamed callback
+- The GitHub README lists testnet addresses; these mainnet addresses are the defaults in UnitFlow's own app build
+- Through a Pot's Sauce Router instead of the protocol's own router: `@sauce/router`'s `uniswapV3(pool, tokenIn, tokenOut, amountIn, sqrtPriceLimitX96, minOut, recipient)` calls the Router's `swapV3`, and only a generation-3 Router answers `unitFlowV3SwapCallback`; on an older one the swap reverts. A Pot for which `potRouterUpdate(client, pot)` returns nothing runs the Kitchen's Router, generation `v12RouterGeneration()`; otherwise its owner signs the update it returns
+- Every Sauce Router swap is exact input: the Router caps what the callback may take at the exact input

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

@@ -1,10 +1,12 @@
 # Velodrome
 
+> **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 central trading and liquidity marketplace on Optimism. Solidly-fork with ve(3,3) tokenomics, supporting both stable (correlated assets) and volatile (uncorrelated assets) pool types.
 
 ## Category
 
-dex | Chains: Optimism
+dex | Chains and addresses: [registry/velodrome.md](registry/velodrome.md)
 
 ## Key Operations
 
@@ -12,13 +14,12 @@ dex | Chains: Optimism
 - **addLiquidity**: Add liquidity to a stable or volatile pool
 - **removeLiquidity**: Remove liquidity from a stable or volatile pool
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/velodrome";
-```
-
-## 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
 
@@ -121,24 +122,11 @@ function main(
 - `liquidity`: Amount of LP tokens to burn
 - LP token must be approved to the router
 
-## Key Addresses
-
-| Chain    | Contract    | Address                                      |
-| -------- | ----------- | -------------------------------------------- |
-| Optimism | RouterV2    | `0xa062aE8A9c5e11aaA026fc2670B0D65cCc8B2858` |
-| Optimism | PoolFactory | `0xF1046053aa5682b4F9a81b5481394DA16BE5FF5a` |
-
-## ABI Methods
-
-### VelodromeRouterABI
-
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, tuple[](address from, address to, bool stable, address factory) routes, address to, uint256 deadline) -> uint256[] amounts` - Swap with route tuples specifying pool type per hop
-- `addLiquidity(address tokenA, address tokenB, bool stable, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB, uint256 liquidity)` - Add liquidity to a stable or volatile pool
-- `removeLiquidity(address tokenA, address tokenB, bool stable, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB)` - Remove liquidity from a pool
-
-### VelodromePoolFactoryABI
+## Deployments and ABI
 
-- `getPool(address tokenA, address tokenB, bool stable) -> address pool` - Look up pool address (view)
+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/velodrome.md](registry/velodrome.md).
 
 ## Notes
 

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

@@ -4,9 +4,14 @@ Leading lending and borrowing protocol on BNB Chain. Fork of Compound V2 with ad
 
 ## Category
 
-lending | Chains: BSC (56)
+lending | Chains and addresses: [registry/venus.md](registry/venus.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`).
 
 ### supply
 
@@ -68,36 +73,11 @@ function main(vTokenAddress: Address, amount: Uint256): Uint256 {
 
 - Requires ERC-20 approval of underlying to the vToken
 
-## Deployed Addresses
-
-| Chain | Contract    | Address                                      |
-| ----- | ----------- | -------------------------------------------- |
-| BSC   | comptroller | `0xfD36E2c2a6789Db23113685031d7F16329158384` |
-| BSC   | vBNB        | `0xA07c5b74C9B40447a954e1466938b865b6BBea36` |
-
-## ABI Reference
-
-### VTokenABI
-
-- `mint(uint256 mintAmount) returns (uint256)` - Supply underlying, receive vTokens
-- `redeem(uint256 redeemTokens) returns (uint256)` - Redeem vTokens for underlying
-- `redeemUnderlying(uint256 redeemAmount) returns (uint256)` - Redeem exact underlying amount
-- `borrow(uint256 borrowAmount) returns (uint256)` - Borrow underlying
-- `repayBorrow(uint256 repayAmount) returns (uint256)` - Repay borrow debt
-- `balanceOfUnderlying(address owner) returns (uint256)` - Get underlying balance including accrued interest. Not a view: it accrues interest first, so it cannot be STATICCALLed
-
-### VBNBABI
-
-vBNB (`vBNB`) takes native BNB, so its `mint` and `repayBorrow` take no amount: the BNB sent with the call is the amount.
-
-- `mint()` - Supply BNB (payable), receive vBNB. Returns nothing; reverts on failure
-- `repayBorrow()` - Repay BNB borrow debt (payable). Returns nothing; reverts on failure
-- `redeem`, `redeemUnderlying`, `borrow`, `balanceOfUnderlying` - As on `VTokenABI`
-
-### VenusComptrollerABI
+## Deployments and ABI
 
-- `enterMarkets(address[] vTokens) returns (uint256[])` - Enable vTokens as collateral
-- `exitMarket(address vToken) returns (uint256)` - Remove vToken from collateral
+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/venus.md](registry/venus.md).
 
 ## Notes
 
@@ -106,3 +86,4 @@ vBNB (`vBNB`) takes native BNB, so its `mint` and `repayBorrow` take no amount:
 - Also supports VAI stablecoin minting (separate contract)
 - Return values: 0 = success, non-zero = error code
 - BSC-only deployment. TVL: $3B+. Audited
+- vBNB (`vBNB`) takes native BNB, so its `mint` and `repayBorrow` take no amount: the BNB sent with the call is the amount.

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

@@ -0,0 +1,42 @@
+# Vertex
+
+Vertically integrated DEX combining spot, perpetuals, and money markets with an off-chain sequencer for sub-second order matching on Arbitrum.
+
+## Category
+
+perpetuals | Chains and addresses: [registry/vertex.md](registry/vertex.md)
+
+## Key Operations
+
+- **depositCollateral**: Deposit collateral into Vertex endpoint
+
+## 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 { EndpointABI as IEndpoint } from "./abis";
+function main(endpointAddress: Address, productId: Uint256, amount: Uint256): Uint256 {
+  const endpoint = IEndpoint.at(endpointAddress);
+  endpoint.depositCollateral(0x000000000000000000000000, productId, 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/vertex.md](registry/vertex.md).
+
+## Notes
+
+- TVL: $100M+. Off-chain sequencer for sub-second order matching
+- Uses subaccount system (bytes12 identifier) for position isolation
+- productId identifies the market (spot or perp)
+- Most trading happens off-chain via sequencer - on-chain methods are for deposits/withdrawals
+- Approve collateral token to endpoint before depositing

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

@@ -0,0 +1,57 @@
+# Wormhole
+
+Generic cross-chain messaging protocol with guardian-based attestation. Supports token bridging and arbitrary message passing across 30+ chains.
+
+## Category
+
+cross-chain messaging + bridge | Direction: any-to-any | Chains and addresses: [registry/wormhole.md](registry/wormhole.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`).
+
+### bridgeTokens
+
+Transfer tokens cross-chain via the Wormhole TokenBridge.
+
+```typescript
+import { WormholeTokenBridgeABI as ITokenBridge } from "./abis";
+
+function main(
+  tokenBridgeAddress: Address,
+  token: Address,
+  amount: Uint256,
+  recipientChain: Uint256,
+  recipient: Uint256,
+): Uint256 {
+  const bridge = ITokenBridge.at(tokenBridgeAddress);
+  return bridge.transferTokens(token, amount, recipientChain, recipient, 0, 0);
+}
+```
+
+- `token`: ERC-20 token to bridge
+- `recipientChain`: Wormhole chain ID (NOT EVM chain ID). E.g. Ethereum=2, Arbitrum=23, Base=30
+- `recipient`: Destination address as bytes32 (left-padded)
+- `arbiterFee`: Fee for relayer (set to 0 for self-redemption)
+- `nonce`: Unique identifier (set to 0)
+- Requires ERC-20 approval to the TokenBridge
+- Requires native token for Wormhole message fee (sent as msg.value, use `coreBridge.messageFee()` to query)
+
+## 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/wormhole.md](registry/wormhole.md).
+
+## Notes
+
+- Uses Wormhole chain IDs (NOT EVM chain IDs). E.g. Ethereum=2, BSC=4, Polygon=5, Avalanche=6, Arbitrum=23, Optimism=24, Base=30
+- Two-step process: (1) `transferTokens` on source, (2) `completeTransfer` on destination with signed VAA
+- If `arbiterFee` > 0, any relayer can submit the VAA and earn the fee. Otherwise, recipient must self-redeem
+- Bridged tokens are wrapped versions (e.g. "Wormhole-wrapped USDC") unless using CCTP integration
+- 19 guardians must reach 2/3+1 consensus for message finality (typically 1-15 minutes)
+- Query `messageFee()` on CoreBridge to know how much native token to attach
+- TVL: $3B+. Audited