@eco-incorp/sauce 0.99.5 → 0.99.7

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

@@ -0,0 +1,58 @@
+# Thales
+
+Positional markets protocol built on Synthetix offering binary options, speed markets, and sports markets on Optimism.
+
+## Category
+
+options | Chains and addresses: [registry/thales.md](registry/thales.md)
+
+## Key Operations
+
+- **exerciseMarket**: Exercise a matured market position to claim payout
+- **buyFromAMM**: Buy positional tokens (UP/DOWN) from the Thales AMM
+- **createSpeedMarket**: Create a speed market 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
+// Buy from AMM
+import { ThalesAMMABI as IThalesAMM } from "./abis";
+function main(
+  thalesAMMAddress: Address,
+  market: Address,
+  position: Uint256,
+  amount: Uint256,
+  expectedPayout: Uint256,
+  slippage: Uint256,
+): Uint256 {
+  const amm = IThalesAMM.at(thalesAMMAddress);
+  return amm.buyFromAMM(market, position, amount, expectedPayout, slippage);
+}
+
+// Exercise a matured market: on the market itself
+import { PositionalMarketABI as IPositionalMarket } from "./abis";
+function main(market: Address): Uint256 {
+  const positionalMarket = IPositionalMarket.at(market);
+  positionalMarket.exerciseOptions();
+  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/thales.md](registry/thales.md).
+
+## Notes
+
+- Position 0 = UP (price goes up), Position 1 = DOWN (price goes down)
+- Markets expire at set times - exercise only after maturation
+- Speed markets have short durations (minutes to hours)
+- Binary outcome: winning position gets payout, losing gets nothing
+- Approve sUSD/USDC to thalesAMM before buying

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

@@ -1,22 +1,23 @@
 # Thena
 
+> **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.
+
 BSC-native liquidity layer with ve(3,3) tokenomics. Solidly-fork supporting both volatile (x*y=k) and stable (Curve-like) AMM pools with gauge voting for directing emissions.
 
 ## Category
 
-dex | Chains: BSC
+dex | Chains and addresses: [registry/thena.md](registry/thena.md)
 
 ## Key Operations
 
 - **swap**: Swap tokens with route-based routing specifying stable or volatile pool type
 
-## SDK Usage
-
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/thena";
-```
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-## 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
 
@@ -52,18 +53,11 @@ function main(
 - Routes support multi-hop: `[{from: A, to: B, stable: false}, {from: B, to: C, stable: true}]`
 - Note: Thena routes do NOT include a `factory` field (unlike Velodrome/Aerodrome)
 
-## Key Addresses
-
-| Chain | Contract | Address                                      |
-| ----- | -------- | -------------------------------------------- |
-| BSC   | RouterV2 | `0xd4ae6eCA985340Dd434D38F470aCCce4DC78D109` |
-
-## ABI Methods
-
-### ThenaRouterABI
+## Deployments and ABI
 
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, tuple[](address from, address to, bool stable) 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
+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/thena.md](registry/thena.md).
 
 ## Notes
 

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

@@ -1,22 +1,23 @@
 # Thruster
 
+> **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.
+
 Blast-native DEX with concentrated liquidity (V3-style) pools. Optimized for Blast's native yield on ETH and USDB, and gas rebate features. Fork of Uniswap V3 architecture.
 
 ## Category
 
-dex | Chains: Blast
+dex | Chains and addresses: [registry/thruster.md](registry/thruster.md)
 
 ## Key Operations
 
 - **swap**: Exact input single-hop swap with fee tier selection via V3 SwapRouter
 
-## SDK Usage
-
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/thruster";
-```
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-## 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
 
@@ -52,19 +53,13 @@ function main(
 - `amountIn`: Exact input amount (in wei)
 - `amountOutMin`: Minimum output for slippage protection
 - `recipient`: Address to receive output tokens
-- `sqrtPriceLimitX96`: Set to `0` for no price limit
-
-## Key Addresses
-
-| Chain | Contract      | Address                                      |
-| ----- | ------------- | -------------------------------------------- |
-| Blast | V3 SwapRouter | `0x337827814155ECBf24D20231fCA4444F530c0555` |
-
-## ABI Methods
+- `sqrtPriceLimitX96`: `0` in this template, no price limit, so `amountOutMin` is the only bound
 
-### ThrusterV3SwapRouterABI
+## Deployments and ABI
 
-- `exactInputSingle(tuple(address tokenIn, address tokenOut, uint24 fee, address recipient, uint256 deadline, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96)) -> uint256 amountOut` - Single-hop exact input swap
+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/thruster.md](registry/thruster.md).
 
 ## Notes
 

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

@@ -0,0 +1,40 @@
+# Tokemak
+
+Liquidity routing protocol with Autopilot Autopools that automatically deploy and rebalance liquidity across DeFi destinations.
+
+## Category
+
+yield | Chains and addresses: [registry/tokemak.md](registry/tokemak.md)
+
+## Key Operations
+
+- **deposit**: Deposit assets into Autopool
+- **withdraw**: Withdraw assets from Autopool
+- **redeem**: Redeem Autopool shares
+
+## 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 into Tokemak Autopool
+import { AutopoolABI as IAutopool } from "./abis";
+
+function main(autopoolAddress: Address, assets: Uint256, receiver: Address): Uint256 {
+  const autopool = IAutopool.at(autopoolAddress);
+  return autopool.deposit(assets, receiver);
+}
+```
+
+## 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/tokemak.md](registry/tokemak.md).
+
+## Notes
+
+- Autopools are ERC-4626 vaults. Autopilot automatically rebalances across DeFi venues.

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

@@ -1,22 +1,23 @@
 # Trader Joe
 
+> **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.
+
 Liquidity Book DEX with variable-width bins for concentrated liquidity. Uses discrete price bins instead of continuous curves, allowing LPs to concentrate liquidity at specific price points. Native to Avalanche with expansion to Arbitrum and BSC.
 
 ## Category
 
-dex | Chains: Avalanche, Arbitrum, BSC
+dex | Chains and addresses: [registry/trader-joe.md](registry/trader-joe.md)
 
 ## Key Operations
 
 - **swap**: Swap exact input tokens via Liquidity Book path routing
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/trader-joe";
-```
-
-## 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
 
@@ -44,26 +45,11 @@ function main(
 - `amountOutMin`: Minimum output for slippage protection
 - `recipient`: Address to receive output tokens
 
-## Key Addresses
-
-| Chain     | Contract   | Address                                      |
-| --------- | ---------- | -------------------------------------------- |
-| Avalanche | LB Factory | `0xb43120c4745967fa9b93E79C149E66B0f2D6Fe0c` |
-| Avalanche | LB Router  | `0x18556DA13313f3532c54711497A8FedAC273220E` |
-| Arbitrum  | LB Router  | `0x18556da13313f3532c54711497a8fedac273220e` |
-| BSC       | LB Router  | `0xb4315e873dBcf96Ffd0acd8EA43f689D8c20fB30` |
-
-## ABI Methods
-
-### LBRouterABI
-
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, tuple(uint256[] pairBinSteps, uint8[] versions, address[] tokenPath) path, address to, uint256 deadline) -> uint256 amountOut` - Swap exact input through LB path
-- `swapTokensForExactTokens(uint256 amountOut, uint256 amountInMax, tuple(uint256[] pairBinSteps, uint8[] versions, address[] tokenPath) path, address to, uint256 deadline) -> uint256[] amountsIn` - Swap to get exact output
-- `addLiquidity(tuple(address tokenX, address tokenY, uint256 binStep, uint256 amountX, uint256 amountY, uint256 amountXMin, uint256 amountYMin, uint256 activeIdDesired, uint256 idSlippage, int256[] deltaIds, uint256[] distributionX, uint256[] distributionY, address to, address refundTo, uint256 deadline)) -> (uint256 amountXAdded, uint256 amountYAdded, uint256 amountXLeft, uint256 amountYLeft, uint256[] depositIds, uint256[] liquidityMinted)` - Add liquidity with precise bin distribution control
-
-### LBFactoryABI
+## Deployments and ABI
 
-- `getLBPairInformation(address tokenA, address tokenB, uint256 binStep) -> tuple(uint16 binStep, address LBPair, bool createdByOwner, bool ignoredForRouting)` - Look up LB pair info for a token pair and bin step (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/trader-joe.md](registry/trader-joe.md).
 
 ## Notes
 
@@ -75,3 +61,4 @@ function main(
 - Each LB pair is uniquely identified by (tokenX, tokenY, binStep)
 - Trader Joe is the dominant DEX on Avalanche; use it for AVAX pairs and Avalanche ecosystem tokens
 - Input token must be ERC20-approved to the LB Router
+- From a Pot program, `@sauce/router` swaps at an LB pair directly, with no router and no approval: `traderJoeLB(pair, tokenIn, tokenOut, amountIn, tokenX, tokenY, minOut, recipient)` reverts unless `tokenIn` and `tokenOut` are the pair's X and Y, transfers the input to the pair and calls `swap(swapForY, to)` with `swapForY = tokenIn == tokenX`, returning the received lane of the packed `amountsOut` (X low, Y high). The pair spends the whole input or reverts `LBPair__OutOfLiquidity`, and a wrong `swapForY` reverts `LBPair__InsufficientAmountIn`. `tryTraderJoeLB` asks `getSwapOut` first and pushes only when nothing would be left over, returning `0n` otherwise. The `traderJoeLBSwap` action is the same call

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

@@ -1,10 +1,44 @@
 # Uniswap 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.
+
 Constant product AMM (x*y=k) with permissionless pair creation. The most forked DEX protocol in DeFi, deployed across 9 chains with identical interfaces.
 
+## When to use it
+
+- Constant-product pairs, one per token pair, with a 0.3% fee. Simple and everywhere, but with
+  more price impact than a V3 pool for the same trade.
+- The pair fills in full or reverts, so its Router, with an exact approval and `amountOutMin`,
+  strands nothing. The Sauce Router's unified `swap` also serves V2 pairs.
+
+## Pitfalls for a program
+
+- `amountOutMin` is the only bound: there is no price limit.
+- Approve the Router for exactly `amountIn`, and give a `deadline` (`ctx.timestamp()` is this
+  block).
+- A fee-on-transfer token needs the `...SupportingFeeOnTransferTokens` variants, which the
+  registry ABI does not declare.
+- The pair must exist: `Factory.getPair` returns `0` where it does not.
+
+## 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(UniswapV2.Router, amountIn);
+  UniswapV2.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: Ethereum, Arbitrum, Optimism, Polygon, Base, BSC, Avalanche, Blast, Zora, Arc
+dex | Chains and addresses: [registry/uniswap-v2.md](registry/uniswap-v2.md)
 
 ## Key Operations
 
@@ -12,13 +46,12 @@ dex | Chains: Ethereum, Arbitrum, Optimism, Polygon, Base, BSC, Avalanche, Blast
 - **addLiquidity**: Deposit two tokens into a pair to mint LP tokens proportional to pool share
 - **removeLiquidity**: Burn LP tokens to withdraw both underlying tokens from a pair
 
-## SDK Usage
+## Typed templates for the raw compiler (not for `sauce compile`)
 
-```typescript
-import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/uniswap-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,43 +143,11 @@ function main(
 - `amountAMin` / `amountBMin`: Minimum amounts of each token to receive (slippage protection)
 - LP token must be approved to the router before calling
 
-## Key Addresses
-
-| Chain     | Contract | Address                                      |
-| --------- | -------- | -------------------------------------------- |
-| Ethereum  | Factory  | `0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f` |
-| Ethereum  | Router   | `0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D` |
-| Arbitrum  | Factory  | `0xf1D7CC64Fb4452F05c498126312eBE29f30Fbcf9` |
-| Arbitrum  | Router   | `0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24` |
-| Optimism  | Factory  | `0x0c3c1c532F1e39EdF36BE9Fe0bE1410313E074Bf` |
-| Optimism  | Router   | `0x4A7b5Da61326A6379179b40d00F57E5bbDC962c2` |
-| Polygon   | Factory  | `0x9e5A52f57b3038F1B8EeE45F28b3C1967e22799C` |
-| Polygon   | Router   | `0xedf6066a2b290C185783862C7F4776A2C8077AD1` |
-| Base      | Factory  | `0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6` |
-| Base      | Router   | `0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24` |
-| BSC       | Factory  | `0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6` |
-| BSC       | Router   | `0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24` |
-| Avalanche | Factory  | `0x9e5A52f57b3038F1B8EeE45F28b3C1967e22799C` |
-| Avalanche | Router   | `0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24` |
-| Blast     | Factory  | `0x5C346464d33F90bABaf70dB6388507CC889C1070` |
-| Blast     | Router   | `0xBB66Eb1c5e875933D44DAe661dbD80e5D9B03035` |
-| Zora      | Factory  | `0x0F797dC7efaEA995bB916f268D919d0a1950eE3C` |
-| Zora      | Router   | `0xa00F34A632630EFd15223B1968358bA4845bEEC7` |
-
-## ABI Methods
-
-### UniswapV2RouterABI
-
-- `swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline) -> uint256[] amounts` - Swap exact input tokens along path, returns amounts at each hop
-- `swapTokensForExactTokens(uint256 amountOut, uint256 amountInMax, address[] path, address to, uint256 deadline) -> uint256[] amounts` - Swap tokens to get exact output amount, returns amounts at each hop
-- `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 to a pair, returns actual amounts deposited and LP tokens minted
-- `removeLiquidity(address tokenA, address tokenB, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) -> (uint256 amountA, uint256 amountB)` - Burn LP tokens and withdraw underlying tokens
-- `getAmountsOut(uint256 amountIn, address[] path) -> uint256[] amounts` - Quote: calculate output amounts for given input along path (view)
-
-### UniswapV2FactoryABI
-
-- `getPair(address tokenA, address tokenB) -> address pair` - Look up the pair contract address for two tokens (view)
-- `createPair(address tokenA, address tokenB) -> address pair` - Create a new pair (if it doesn't exist)
+## 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-v2.md](registry/uniswap-v2.md).
 
 ## Notes
 
@@ -157,3 +158,4 @@ function main(
 - For tokens with transfer taxes (fee-on-transfer), use `swapExactTokensForTokensSupportingFeeOnTransferTokens` instead (not in SDK but available on-chain)
 - Uniswap V2 is the simplest and most battle-tested DEX model; prefer V3 for better capital efficiency, but V2 for maximum compatibility and simplicity
 - On Arc (5042) the router's `WETH()` is a stub that always reverts with `UnsupportedProtocolError()`, so the ETH paths (`swapExactETHForTokens`, `addLiquidityETH`, …) revert. Trade USDC's ERC-20 `0x3600000000000000000000000000000000000000`; Arc's native coin is USDC and it has no canonical wrapped native
+- From a Pot program, `@sauce/router` trades a Uniswap V2 pair directly, with no router and no approval: `uniswapV2(pair, tokenIn, tokenOut, amountIn, 3000n, minOut, recipient)` 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/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).