@eco-incorp/sauce 0.99.0

package/sdk/src/skills/aave-v3.md

@@ -0,0 +1,134 @@
+# Aave V3
+
+Non-custodial liquidity protocol for earning interest on deposits and borrowing assets. The most widely deployed lending protocol in DeFi.
+
+## Category
+
+lending | Chains: Ethereum (1), Polygon (137), Arbitrum (42161), Optimism (10), Avalanche (43114), Base (8453), BSC (56), Scroll (534352), Fantom (250), Gnosis (100), Metis (1088)
+
+## SauceScript Functions
+
+### supply
+
+Supply assets to earn interest. Mints aTokens to the supplier.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, onBehalfOf: Address): Uint256 {
+  const pool = IPool.at(poolAddress);
+  pool.supply(asset, amount, onBehalfOf, 0);
+  return 1;
+}
+```
+
+- `poolAddress`: Pool contract for the target chain
+- `asset`: ERC-20 token address to supply
+- `amount`: Amount in token's native decimals. Use `type(uint256).max` for entire balance
+- `onBehalfOf`: Address that receives aTokens (use msg.sender for self)
+- Requires ERC-20 approval to the Pool before calling
+
+### withdraw
+
+Withdraw supplied assets by burning aTokens.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, to: Address): Uint256 {
+  const pool = IPool.at(poolAddress);
+  return pool.withdraw(asset, amount, to);
+}
+```
+
+- `amount`: Use `type(uint256).max` to withdraw entire balance
+- Returns the actual withdrawn amount
+
+### borrow
+
+Borrow assets against supplied collateral.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IPool.at(poolAddress);
+  pool.borrow(asset, amount, interestRateMode, 0, onBehalfOf);
+  return 1;
+}
+```
+
+- `interestRateMode`: 1 = stable (being phased out), 2 = variable. Use 2 for variable rate
+- Must have sufficient collateral supplied first
+
+### repay
+
+Repay borrowed assets to reduce debt.
+
+```typescript
+import { PoolABI as IPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IPool.at(poolAddress);
+  return pool.repay(asset, amount, interestRateMode, onBehalfOf);
+}
+```
+
+- `interestRateMode`: Must match the debt type (1 = stable, 2 = variable)
+- `amount`: Use `type(uint256).max` to repay entire debt
+- Requires ERC-20 approval to the Pool
+
+## Deployed Addresses
+
+| Chain     | Contract              | Address                                      |
+| --------- | --------------------- | -------------------------------------------- |
+| Ethereum  | pool                  | `0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2` |
+| Ethereum  | poolAddressesProvider | `0x2f39d218133AFaB8F2B819B1066c7E434Ad94E9e` |
+| Polygon   | pool                  | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Polygon   | poolAddressesProvider | `0xa97684ead0e402dC232d5A977953DF7ECBaB3CDb` |
+| Arbitrum  | pool                  | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Arbitrum  | poolAddressesProvider | `0xa97684ead0e402dC232d5A977953DF7ECBaB3CDb` |
+| Optimism  | pool                  | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Optimism  | poolAddressesProvider | `0xa97684ead0e402dC232d5A977953DF7ECBaB3CDb` |
+| Avalanche | pool                  | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Avalanche | poolAddressesProvider | `0xa97684ead0e402dC232d5A977953DF7ECBaB3CDb` |
+| Base      | pool                  | `0xA238Dd80C259a72e81d7e4664a9801593F98d1c5` |
+| Base      | poolAddressesProvider | `0xe20fCBdBfFC4Dd138cE8b2E6FBb6CB49777ad64D` |
+| BSC       | pool                  | `0x6807dc923806fE8Fd134338EABCA509979a7e0cB` |
+| Scroll    | pool                  | `0x11fCfe756c05AD438e312a7fd934381537D3cFfe` |
+| Fantom    | pool                  | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Gnosis    | pool                  | `0xb50201558B00496A145fE76f7424749556E326D8` |
+| Metis     | pool                  | `0x90df02551bB792286e8D4f13E0e357b4Bf1D6a57` |
+
+## ABI Reference
+
+### PoolABI
+
+- `supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)` - Supply asset to earn interest
+- `withdraw(address asset, uint256 amount, address to) returns (uint256)` - Withdraw supplied asset
+- `borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)` - Borrow against collateral
+- `repay(address asset, uint256 amount, uint256 interestRateMode, address onBehalfOf) returns (uint256)` - Repay borrowed debt
+- `flashLoanSimple(address receiverAddress, address asset, uint256 amount, bytes params, uint16 referralCode)` - Single-asset flash loan (receiver must implement IFlashLoanSimpleReceiver)
+- `liquidationCall(address collateralAsset, address debtAsset, address user, uint256 debtToCover, bool receiveAToken)` - Liquidate undercollateralized position (healthFactor < 1e18)
+- `getUserAccountData(address user) returns (uint256 totalCollateralBase, uint256 totalDebtBase, uint256 availableBorrowsBase, uint256 currentLiquidationThreshold, uint256 ltv, uint256 healthFactor)` - Get account health data (view)
+
+## Notes
+
+- interestRateMode: 1 = stable (deprecated on most markets), 2 = variable
+- referralCode is always 0 (referral program inactive)
+- V3 introduced efficiency mode (eMode) for correlated assets, isolation mode for new assets, and siloed borrowing
+- All supply/repay operations require prior ERC-20 approval to the Pool address
+- healthFactor < 1e18 means position is liquidatable
+- TVL: $40B+. Audited

package/sdk/src/skills/abracadabra.md

@@ -0,0 +1,93 @@
+# Abracadabra
+
+Lending protocol that lets users borrow MIM stablecoin against yield-bearing collateral via isolated Cauldron markets built on DegenBox.
+
+## Category
+
+cdp | Chains: Ethereum, Arbitrum
+
+## Key Operations
+
+- **borrow**: Borrow MIM from a Cauldron
+- **repay**: Repay MIM debt
+- **addCollateral**: Add collateral to a Cauldron position
+- **removeCollateral**: Remove collateral from a Cauldron position
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/abracadabra";
+```
+
+## SauceScript Examples
+
+```typescript
+// Borrow MIM from Cauldron
+import { CauldronABI as ICauldron } from "./abis";
+function main(
+  cauldronAddress: Address,
+  to: Address,
+  amount: Uint256,
+): { part: Uint256; share: Uint256 } {
+  const cauldron = ICauldron.at(cauldronAddress);
+  return cauldron.borrow(to, amount);
+}
+
+// Repay MIM debt
+import { CauldronABI as ICauldron } from "./abis";
+function main(cauldronAddress: Address, to: Address, part: Uint256): Uint256 {
+  const cauldron = ICauldron.at(cauldronAddress);
+  return cauldron.repay(to, 0, part);
+}
+
+// Add collateral
+import { CauldronABI as ICauldron } from "./abis";
+function main(cauldronAddress: Address, to: Address, share: Uint256): Uint256 {
+  const cauldron = ICauldron.at(cauldronAddress);
+  cauldron.addCollateral(to, 0, share);
+  return 1;
+}
+
+// Remove collateral
+import { CauldronABI as ICauldron } from "./abis";
+function main(cauldronAddress: Address, to: Address, share: Uint256): Uint256 {
+  const cauldron = ICauldron.at(cauldronAddress);
+  cauldron.removeCollateral(to, share);
+  return 1;
+}
+```
+
+## Key Addresses
+
+| Chain    | Contract | Address                                      |
+| -------- | -------- | -------------------------------------------- |
+| Ethereum | degenBox | `0xd96f48665a1410C0cd669A88898ecA36B9Fc2cce` |
+| Ethereum | mim      | `0x99D8a9C45b2ecA8864373A26D1459e3Dff1e17F3` |
+| Arbitrum | degenBox | `0x7C8FeF8eA9b1fE46A7689bfb8149341C90431D38` |
+| Arbitrum | mim      | `0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A` |
+
+## ABI Methods
+
+### CauldronABI
+
+- `borrow(address,uint256)` - Borrow MIM. Params: to (recipient), amount (MIM to borrow). Returns (part, share) - part is debt units, share is DegenBox shares
+- `repay(address,bool,uint256)` - Repay MIM debt. Params: to (whose debt to repay), skim (true=use DegenBox balance), part (debt part to repay). Returns amount repaid
+- `addCollateral(address,bool,uint256)` - Add collateral. Params: to (position owner), skim (true=use DegenBox balance), share (collateral shares to add)
+- `removeCollateral(address,uint256)` - Remove collateral. Params: to (recipient), share (collateral shares to remove)
+- `userCollateralShare(address)` - Query user's collateral. Params: user. Returns share amount
+- `userBorrowPart(address)` - Query user's debt. Params: user. Returns borrow part
+
+### DegenBoxABI
+
+- `deposit(address,address,address,uint256,uint256)` - Deposit tokens into DegenBox. Payable. Params: token, from, to, amount (0 if using share), share (0 if using amount). Returns (amountOut, shareOut)
+- `withdraw(address,address,address,uint256,uint256)` - Withdraw from DegenBox. Params: token, from, to, amount (0 if using share), share (0 if using amount). Returns (amountOut, shareOut)
+- `balanceOf(address,address)` - Query balance. Params: token, user. Returns share amount
+
+## Notes
+
+- Isolated Cauldron markets - each has specific collateral type and risk parameters
+- DegenBox is the underlying vault that holds all assets (BentoBox fork)
+- Amounts use "part" (debt accounting) and "share" (DegenBox shares) - not raw token amounts
+- skim=false means transfer tokens from caller; skim=true means use tokens already in DegenBox
+- Deposit collateral to DegenBox first, then addCollateral to a Cauldron
+- Common collateral: sSPELL, yv tokens, LP tokens, yield-bearing assets

package/sdk/src/skills/across.md

@@ -0,0 +1,72 @@
+# Across
+
+Optimistic cross-chain bridge powered by UMA's optimistic oracle. Uses relayers for fast fills and canonical bridges for settlement.
+
+## Category
+
+bridge | Direction: L2-to-L2, L1-to-L2, L2-to-L1 | Chains: Ethereum (1), Arbitrum (42161), Optimism (10), Base (8453), Polygon (137), zkSync (324), Linea (59144), Mode (34443), Blast (81457), Scroll (534352)
+
+## SauceScript Functions
+
+### bridge
+
+Deposit tokens into SpokePool for cross-chain transfer. Uses the legacy `deposit` function.
+
+```typescript
+import { AcrossSpokePoolABI as ISpokePool } from "./abis";
+
+function main(
+  spokePoolAddress: Address,
+  token: Address,
+  amount: Uint256,
+  destinationChainId: Uint256,
+  recipient: Address,
+): Uint256 {
+  const spokePool = ISpokePool.at(spokePoolAddress);
+  spokePool.deposit(recipient, token, amount, destinationChainId, 0, 0, ctx.msgSender(), 0);
+  return 1;
+}
+```
+
+- `token`: ERC-20 token to bridge (must be supported by Across)
+- `destinationChainId`: EVM chain ID of destination chain
+- `recipient`: Address to receive tokens on destination chain
+- Requires ERC-20 approval to the SpokePool
+- Note: `depositV3` is the current recommended method (see ABI below)
+
+## Deployed Addresses
+
+| Chain    | Contract  | Address                                      |
+| -------- | --------- | -------------------------------------------- |
+| Ethereum | hubPool   | `0xc186fA914353c44b2E33eBE05f21846F1048bEda` |
+| Ethereum | spokePool | `0x5c7BCd6E7De5423a257D81B442095A1a6ced35C5` |
+| Arbitrum | spokePool | `0xe35e9842fceaCA96570B734083f4a58e8F7C5f2A` |
+| Optimism | spokePool | `0x6f26Bf09B1C792e3228e5467807a900A503c0281` |
+| Base     | spokePool | `0x09aea4b2242abC8bb4BB78D537A67a245A7bEC64` |
+| Polygon  | spokePool | `0x9295ee1d8C5b022Be115A2AD3c30C72E34e7F096` |
+| zkSync   | spokePool | `0xE0B015E54d54fc84a6cB9B666099c46adE9335FF` |
+| Linea    | spokePool | `0x7E63A5f1a8F0B4d0934B2f2327DAED3F6bb2ee75` |
+| Mode     | spokePool | `0x3baD7AD0728f9917d1Bf08af5782dCbD516cDd96` |
+| Blast    | spokePool | `0x2D509190Ed0172ba588407D4c2df918F955Cc6E1` |
+| Scroll   | spokePool | `0x3baD7AD0728f9917d1Bf08af5782dCbD516cDd96` |
+
+## ABI Reference
+
+### AcrossSpokePoolABI
+
+- `depositV3(address depositor, address recipient, address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 destinationChainId, address exclusiveRelayer, uint32 quoteTimestamp, uint32 fillDeadline, uint32 exclusivityDeadline, bytes message)` [payable] - Current recommended deposit method. Supports cross-chain swaps (inputToken != outputToken), exclusive relayer, and arbitrary message passing
+- `deposit(address recipient, address originToken, uint256 amount, uint256 destinationChainId, int64 relayerFeePct, uint32 quoteTimestamp, bytes message, uint256 maxCount)` [payable] - Legacy deposit method (deprecated, use depositV3)
+
+### AcrossHubPoolABI
+
+- `liquidityUtilizationCurrent(address l1Token) returns (uint256)` - Get current utilization rate (view)
+- `pooledTokens(address l1Token) returns (address lpToken, bool isEnabled, uint32 lastLpFeeUpdate, int256 utilizedReserves, uint256 liquidReserves, uint256 undistributedLpFees)` - Get pool token info (view)
+
+## Notes
+
+- Fast fills: relayers fill deposits on destination within minutes, then claim reimbursement via optimistic oracle
+- Finality: deposit confirmation on source chain, fill within 1-10 minutes typically
+- `depositV3` is recommended over legacy `deposit` -- supports output token specification and exclusive relayers
+- Requires ERC-20 approval to the SpokePool address on source chain
+- HubPool on Ethereum only -- SpokePools on all supported L2s
+- TVL: $500M+. Audited

package/sdk/src/skills/aerodrome.md

@@ -0,0 +1,151 @@
+# Aerodrome
+
+The central trading and liquidity marketplace on Base. Fork of Velodrome with ve(3,3) tokenomics, the largest DEX on Base by TVL ($1B+). Supports both stable and volatile pool types.
+
+## Category
+
+dex | Chains: Base
+
+## Key Operations
+
+- **swap**: Swap tokens with route-based routing specifying stable or volatile pool type
+- **addLiquidity**: Add liquidity to a stable or volatile pool
+- **removeLiquidity**: Remove liquidity from a stable or volatile pool
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/aerodrome";
+```
+
+## SauceScript Examples
+
+### swap
+
+```typescript
+import { AerodromeRouterABI as IRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenIn: Address,
+  tokenOut: Address,
+  stable: bool,
+  factory: Address,
+  amountIn: Uint256,
+  amountOutMin: Uint256,
+  recipient: Address,
+): Uint256[] {
+  const router = IRouter.at(routerAddress);
+  return router.swapExactTokensForTokens(
+    amountIn,
+    amountOutMin,
+    [{ from: tokenIn, to: tokenOut, stable: stable, factory: factory }],
+    recipient,
+    99999999999,
+  );
+}
+```
+
+- `routerAddress`: Aerodrome Router address on Base
+- `tokenIn` / `tokenOut`: Input and output token addresses
+- `stable`: `true` for stable pools (pegged assets), `false` for volatile pools (uncorrelated assets)
+- `factory`: Pool factory address (`0x420DD381b31aEf6683db6B902084cB0FFECe40Da` on Base)
+- `amountIn`: Exact input amount (in wei)
+- `amountOutMin`: Minimum output for slippage protection
+- `recipient`: Address to receive output tokens
+- Supports multi-hop routes array
+
+### addLiquidity
+
+```typescript
+import { AerodromeRouterABI as IRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenA: Address,
+  tokenB: Address,
+  stable: bool,
+  amountADesired: Uint256,
+  amountBDesired: Uint256,
+  amountAMin: Uint256,
+  amountBMin: Uint256,
+  recipient: Address,
+): { amountA: Uint256; amountB: Uint256; liquidity: Uint256 } {
+  const router = IRouter.at(routerAddress);
+  return router.addLiquidity(
+    tokenA,
+    tokenB,
+    stable,
+    amountADesired,
+    amountBDesired,
+    amountAMin,
+    amountBMin,
+    recipient,
+    99999999999,
+  );
+}
+```
+
+- `stable`: Must match the pool type you want to provide liquidity to
+- Both tokens must be approved to the router
+
+### removeLiquidity
+
+```typescript
+import { AerodromeRouterABI as IRouter } from "./abis";
+
+function main(
+  routerAddress: Address,
+  tokenA: Address,
+  tokenB: Address,
+  stable: bool,
+  liquidity: Uint256,
+  amountAMin: Uint256,
+  amountBMin: Uint256,
+  recipient: Address,
+): { amountA: Uint256; amountB: Uint256 } {
+  const router = IRouter.at(routerAddress);
+  return router.removeLiquidity(
+    tokenA,
+    tokenB,
+    stable,
+    liquidity,
+    amountAMin,
+    amountBMin,
+    recipient,
+    99999999999,
+  );
+}
+```
+
+- `liquidity`: Amount of LP tokens to burn
+- LP token must be approved to the router
+
+## Key Addresses
+
+| Chain | Contract    | Address                                      |
+| ----- | ----------- | -------------------------------------------- |
+| Base  | Router      | `0xcF77a3Ba9A5CA399B7c97c74d54e5b1Beb874E43` |
+| Base  | PoolFactory | `0x420DD381b31aEf6683db6B902084cB0FFECe40Da` |
+
+## ABI Methods
+
+### AerodromeRouterABI
+
+- `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
+
+### AerodromePoolFactoryABI
+
+- `getPool(address tokenA, address tokenB, bool stable) -> address pool` - Look up pool address (view)
+
+## Notes
+
+- Same interface as Velodrome (forked codebase); Aerodrome is Velodrome's Base deployment
+- Two pool types: `stable=true` (Curve-like invariant for pegged assets), `stable=false` (x*y=k for uncorrelated)
+- Fees: volatile pools ~0.3%, stable pools ~0.04% (governance-controlled)
+- ve(3,3) model: AERO holders vote-lock tokens to direct gauge emissions weekly
+- The dominant DEX on Base by TVL and volume; preferred for most Base swaps
+- LP tokens can be staked in gauges for AERO emissions
+- Routes include both `stable` flag and `factory` address per hop

package/sdk/src/skills/aevo.md

@@ -0,0 +1,50 @@
+# Aevo
+
+High-performance options and perpetuals exchange built on a custom OP Stack rollup. Off-chain orderbook with on-chain settlement.
+
+## Category
+
+options | Chains: Ethereum (deposits)
+
+## Key Operations
+
+- **depositERC20**: Deposit ERC-20 tokens into Aevo L2 for trading
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/aevo";
+```
+
+## SauceScript Examples
+
+```typescript
+// Deposit ERC-20 into Aevo
+import { DepositContractABI as IDeposit } from "./abis";
+function main(depositAddress: Address, token: Address, amount: Uint256): Uint256 {
+  const deposit = IDeposit.at(depositAddress);
+  deposit.depositERC20(token, amount);
+  return 1;
+}
+```
+
+## Key Addresses
+
+| Chain    | Contract        | Address                                      |
+| -------- | --------------- | -------------------------------------------- |
+| Ethereum | depositContract | `0x4082C9647c098a6493Fb499EaE63b5ce3259C574` |
+
+## ABI Methods
+
+### DepositContractABI
+
+- `depositERC20(address,uint256)` - Deposit ERC-20 tokens to Aevo L2. Params: token (ERC-20 address), amount (deposit amount). Approve token to depositContract first
+- `depositETH()` - Deposit ETH to Aevo L2. Payable (send ETH as msg.value)
+
+## Notes
+
+- Custom OP Stack rollup with off-chain orderbook for sub-second matching
+- Supports options and perpetual futures trading
+- Deposits are on Ethereum L1, trading happens on Aevo L2
+- Withdrawals processed by the rollup bridge (takes ~7 days for L2 to L1)
+- Approve ERC-20 tokens to depositContract before calling depositERC20

package/sdk/src/skills/alchemix.md

@@ -0,0 +1,92 @@
+# Alchemix
+
+Self-repaying loan protocol. Deposit yield-bearing collateral to borrow synthetic assets (alUSD, alETH) that repay themselves over time via yield.
+
+## Category
+
+cdp | Chains: Ethereum
+
+## Key Operations
+
+- **deposit**: Deposit yield-bearing token as collateral
+- **withdraw**: Withdraw collateral
+- **mint**: Borrow synthetic asset (alUSD or alETH) against collateral
+- **burn**: Repay synthetic asset debt
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/alchemix";
+```
+
+## SauceScript Examples
+
+```typescript
+// Deposit yield-bearing collateral
+import { AlchemistABI as IAlchemist } from "./abis";
+function main(
+  alchemistAddress: Address,
+  yieldToken: Address,
+  amount: Uint256,
+  recipient: Address,
+): Uint256 {
+  const alchemist = IAlchemist.at(alchemistAddress);
+  return alchemist.deposit(yieldToken, amount, recipient);
+}
+
+// Withdraw collateral
+import { AlchemistABI as IAlchemist } from "./abis";
+function main(
+  alchemistAddress: Address,
+  yieldToken: Address,
+  shares: Uint256,
+  recipient: Address,
+): Uint256 {
+  const alchemist = IAlchemist.at(alchemistAddress);
+  return alchemist.withdraw(yieldToken, shares, recipient);
+}
+
+// Borrow (mint) synthetic asset
+import { AlchemistABI as IAlchemist } from "./abis";
+function main(alchemistAddress: Address, amount: Uint256, recipient: Address): Uint256 {
+  const alchemist = IAlchemist.at(alchemistAddress);
+  alchemist.mint(amount, recipient);
+  return 1;
+}
+
+// Repay (burn) synthetic asset
+import { AlchemistABI as IAlchemist } from "./abis";
+function main(alchemistAddress: Address, amount: Uint256, recipient: Address): Uint256 {
+  const alchemist = IAlchemist.at(alchemistAddress);
+  return alchemist.burn(amount, recipient);
+}
+```
+
+## Key Addresses
+
+| Chain    | Contract       | Address                                      |
+| -------- | -------------- | -------------------------------------------- |
+| Ethereum | alchemistAlUSD | `0x5C6374a2ac4EBC38DeA0Fc1F8716e5Ea1ADD94dd` |
+| Ethereum | alchemistAlETH | `0x062Bf725dC4cDF947aa79Ca2aaCCD4F385b13b5c` |
+| Ethereum | alUSD          | `0xBC6DA0FE9aD5f3b0d58160288917AA56653660E9` |
+| Ethereum | alETH          | `0x0100546F2cD4C9D97f798fFC9755E47865FF7Ee6` |
+
+## ABI Methods
+
+### AlchemistABI
+
+- `deposit(address,uint256,address)` - Deposit yield-bearing collateral. Params: yieldToken (e.g. yvDAI, yvUSDC), amount, recipient. Returns shares
+- `withdraw(address,uint256,address)` - Withdraw collateral. Params: yieldToken, shares (deposit shares to burn), recipient. Returns amountWithdrawn
+- `mint(uint256,address)` - Borrow synthetic asset. Params: amount (alUSD/alETH to mint), recipient. Max borrow = 50% of collateral value
+- `burn(uint256,address)` - Repay debt by burning synthetic. Params: amount (alUSD/alETH to burn), recipient (whose debt to repay). Returns uint256
+- `liquidate(address,uint256,uint256)` - Liquidate undercollateralized position. Params: yieldToken, shares, minimumAmountOut. Returns uint256
+- `accounts(address)` - Query account info. Params: owner. Returns (debt as int256, depositedTokens as address[])
+
+## Notes
+
+- Self-repaying: yield from deposited collateral automatically reduces debt over time
+- Two Alchemist contracts: alchemistAlUSD (for USD synthetics) and alchemistAlETH (for ETH synthetics)
+- Max LTV: 50% - can borrow up to half the value of deposited collateral
+- yieldToken is the yield-bearing version (e.g. yvDAI, aDAI, stETH), not the base token
+- Approve yieldToken to the appropriate Alchemist contract before depositing
+- debt is int256 because it can be negative (overpaid/surplus)

package/sdk/src/skills/ambient.md

@@ -0,0 +1,78 @@
+# Ambient
+
+Single-contract DEX (formerly CrocSwap) with ambient (full-range) and concentrated liquidity in one unified pool. Extremely gas-efficient architecture where all liquidity lives in one contract.
+
+## Category
+
+dex | Chains: Ethereum, Scroll
+
+## Key Operations
+
+- **swap**: Swap tokens via the CrocSwapDex contract with base/quote pair addressing
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/ambient";
+```
+
+## SauceScript Examples
+
+### swap
+
+```typescript
+import { CrocSwapDexABI as ICrocSwapDex } from "./abis";
+
+function main(
+  dexAddress: Address,
+  base: Address,
+  quote: Address,
+  poolIdx: Uint256,
+  isBuy: bool,
+  inBaseQty: bool,
+  qty: Uint256,
+  minOut: Uint256,
+): { baseFlow: Uint256; quoteFlow: Uint256 } {
+  const dex = ICrocSwapDex.at(dexAddress);
+  return dex.swap(base, quote, poolIdx, isBuy, inBaseQty, qty, 0, 0, minOut, 0);
+}
+```
+
+- `dexAddress`: CrocSwapDex contract address (same on both chains: `0xAaAaAAAaA24eEeb8d57D431224f73832bC34f688`)
+- `base`: Base token address (lower address of the pair by convention)
+- `quote`: Quote token address (higher address of the pair)
+- `poolIdx`: Pool index identifying the pool type (e.g., `420` for standard pools on Ethereum)
+- `isBuy`: `true` = buy base with quote (swap quote->base); `false` = sell base for quote (swap base->quote)
+- `inBaseQty`: `true` = qty is denominated in base token; `false` = qty is in quote token
+- `qty`: Amount to swap (in wei)
+- `minOut`: Minimum output for slippage protection
+- Additional params set to `0`: `tip` (optional tip), `limitPrice` (no price limit), `reserveFlags` (no reserve usage)
+
+## Key Addresses
+
+| Chain    | Contract    | Address                                      |
+| -------- | ----------- | -------------------------------------------- |
+| Ethereum | CrocSwapDex | `0xAaAaAAAaA24eEeb8d57D431224f73832bC34f688` |
+| Scroll   | CrocSwapDex | `0xAaAaAAAaA24eEeb8d57D431224f73832bC34f688` |
+
+## ABI Methods
+
+### CrocSwapDexABI
+
+- `swap(address base, address quote, uint256 poolIdx, bool isBuy, bool inBaseQty, uint128 qty, uint16 tip, uint128 limitPrice, uint128 minOut, uint8 reserveFlags) -> (int128 baseFlow, int128 quoteFlow)` - Execute a swap with full parameter control. Returns signed token flows (negative = tokens out from user)
+- `userCmd(uint16 callpath, bytes cmd) -> bytes result` - Execute arbitrary protocol commands (advanced: liquidity operations, governance, etc.)
+
+## Notes
+
+- Single contract holds ALL liquidity (similar to Balancer V2 Vault and Uniswap V4 PoolManager)
+- Same contract address on both Ethereum and Scroll
+- `poolIdx` identifies the pool type: different pool indices have different fee rates and tick spacing
+- Common pool indices: `420` (standard on Ethereum), `36000` (stable pairs on Scroll)
+- `isBuy` + `inBaseQty` together determine the exact swap semantics
+- `tip`: Optional tip in basis points for priority execution (usually `0`)
+- `limitPrice`: Price limit as sqrt price Q64.64 fixed-point (set to `0` for no limit)
+- `reserveFlags`: Bitmask for using surplus collateral (set to `0` for standard swaps)
+- `userCmd` is the universal command interface for all non-swap operations (adding/removing liquidity, etc.)
+- callpath `1` = liquidity operations, `3` = warm path operations
+- Gas-efficient for simple swaps; more complex for LP operations via `userCmd`
+- Input token must be ERC20-approved to the CrocSwapDex contract