@eco-incorp/sauce 0.99.0

package/sdk/src/skills/venus.md

@@ -0,0 +1,100 @@
+# Venus
+
+Leading lending and borrowing protocol on BNB Chain. Fork of Compound V2 with additional features including VAI stablecoin minting.
+
+## Category
+
+lending | Chains: BSC (56)
+
+## SauceScript Functions
+
+### supply
+
+Supply assets by minting vTokens. Exchange rate grows as interest accrues.
+
+```typescript
+import { VTokenABI as IVToken } from "./abis";
+
+function main(vTokenAddress: Address, amount: Uint256): Uint256 {
+  const vToken = IVToken.at(vTokenAddress);
+  return vToken.mint(amount);
+}
+```
+
+- `vTokenAddress`: The vToken market contract (each asset has its own vToken, e.g. vBNB)
+- Returns 0 on success, error code on failure
+- Requires ERC-20 approval of underlying to the vToken
+
+### withdraw
+
+Withdraw underlying assets by specifying the exact amount.
+
+```typescript
+import { VTokenABI as IVToken } from "./abis";
+
+function main(vTokenAddress: Address, amount: Uint256): Uint256 {
+  const vToken = IVToken.at(vTokenAddress);
+  return vToken.redeemUnderlying(amount);
+}
+```
+
+### borrow
+
+Borrow assets against vToken collateral. Must call enterMarkets first.
+
+```typescript
+import { VTokenABI as IVToken } from "./abis";
+
+function main(vTokenAddress: Address, amount: Uint256): Uint256 {
+  const vToken = IVToken.at(vTokenAddress);
+  return vToken.borrow(amount);
+}
+```
+
+- Must enable collateral via `VenusComptroller.enterMarkets([vTokenAddress])` first
+
+### repay
+
+Repay borrowed assets.
+
+```typescript
+import { VTokenABI as IVToken } from "./abis";
+
+function main(vTokenAddress: Address, amount: Uint256): Uint256 {
+  const vToken = IVToken.at(vTokenAddress);
+  return vToken.repayBorrow(amount);
+}
+```
+
+- 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 (view)
+
+### VenusComptrollerABI
+
+- `enterMarkets(address[] vTokens) returns (uint256[])` - Enable vTokens as collateral
+- `exitMarket(address vToken) returns (uint256)` - Remove vToken from collateral
+
+## Notes
+
+- Same interface as Compound V2 (forked codebase)
+- Must call `enterMarkets` on Comptroller before borrowing against any market
+- Also supports VAI stablecoin minting (separate contract)
+- Return values: 0 = success, non-zero = error code
+- BSC-only deployment. TVL: $3B+. Audited

package/sdk/src/skills/vertex.md

@@ -0,0 +1,55 @@
+# 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: Arbitrum
+
+## Key Operations
+
+- **depositCollateral**: Deposit collateral into Vertex endpoint
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/vertex";
+```
+
+## SauceScript Examples
+
+```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;
+}
+```
+
+## Key Addresses
+
+| Chain    | Contract      | Address                                      |
+| -------- | ------------- | -------------------------------------------- |
+| Arbitrum | endpoint      | `0x73eab16c88b9f38d3f2661c9e5875ec0eeee2965` |
+| Arbitrum | clearinghouse | `0x773bb71b0108b060b76746422ee810bfec9a963d` |
+
+## ABI Methods
+
+### EndpointABI
+
+- `depositCollateral(bytes12,uint32,uint128)` - Deposit collateral. Params: subaccountName (bytes12), productId (uint32), amount (uint128)
+- `submitSlowModeTransaction(bytes)` - Submit slow-mode tx (fallback when sequencer is down)
+
+### ClearinghouseABI
+
+- `withdrawCollateral(bytes12,uint32,uint128)` - Withdraw collateral. Same params as depositCollateral
+
+## 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/sdk/src/skills/wormhole.md

@@ -0,0 +1,76 @@
+# 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: Ethereum (1), Arbitrum (42161), Optimism (10), Base (8453), Polygon (137), Avalanche (43114)
+
+## SauceScript Functions
+
+### 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)
+
+## Deployed Addresses
+
+| Chain     | Contract    | Address                                      |
+| --------- | ----------- | -------------------------------------------- |
+| Ethereum  | coreBridge  | `0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B` |
+| Ethereum  | tokenBridge | `0x3ee18B2214AFF97000D974cf647E7C347E8fa585` |
+| Arbitrum  | coreBridge  | `0xa5f208e072434bC67592E4C49C1B991BA79BCA46` |
+| Arbitrum  | tokenBridge | `0x0b2402144Bb366A632D14B83F244D2e0e21bD39c` |
+| Optimism  | coreBridge  | `0xEe91C335eab126dF5fDB3797EA9d6aD93aeC9722` |
+| Optimism  | tokenBridge | `0x1D68124e65faFC907325e3EDbF8c4d84499DAa8b` |
+| Base      | coreBridge  | `0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6` |
+| Base      | tokenBridge | `0x8d2de8d2f73F1F4cAB472AC9A881C9b123C79627` |
+| Polygon   | coreBridge  | `0x7A4B5a56256163F07b2C80A7cA55aBE66c4ec4d7` |
+| Polygon   | tokenBridge | `0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE` |
+| Avalanche | coreBridge  | `0x54a8e5f9c4CbA08F9943965859F6c34eAF03E26c` |
+| Avalanche | tokenBridge | `0x0e082F06FF657D94310cB8cE8B0D9a04541d8052` |
+
+## ABI Reference
+
+### WormholeCoreBridgeABI
+
+- `publishMessage(uint32 nonce, bytes payload, uint8 consistencyLevel) returns (uint64 sequence)` [payable] - Publish arbitrary message for guardian attestation
+- `messageFee() returns (uint256)` - Get current message fee (view)
+
+### WormholeTokenBridgeABI
+
+- `transferTokens(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) returns (uint64 sequence)` [payable] - Bridge tokens to destination chain. Returns sequence number for tracking
+- `completeTransfer(bytes encodedVm)` - Complete transfer on destination by submitting signed VAA (Verified Action Approval)
+- `wrappedAsset(uint16 tokenChainId, bytes32 tokenAddress) returns (address)` - Look up wrapped asset address on current chain (view)
+
+## 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

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

@@ -0,0 +1,71 @@
+# Yearn V3
+
+Yield aggregator protocol. V3 vaults follow the ERC-4626 standard for automated yield optimization with multi-strategy allocations.
+
+## Category
+
+yield | Chains: Ethereum
+
+## Key Operations
+
+- **deposit**: Deposit assets into vault, receive yield-bearing shares
+- **withdraw**: Withdraw assets by specifying asset amount
+- **redeem**: Withdraw by specifying share amount
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/yearn-v3";
+```
+
+## SauceScript Examples
+
+```typescript
+// Deposit into Yearn V3 vault
+import { YearnV3VaultABI as IYearnV3Vault } from "./abis";
+function main(vaultAddress: Address, assets: Uint256, receiver: Address): Uint256 {
+  const vault = IYearnV3Vault.at(vaultAddress);
+  return vault.deposit(assets, receiver);
+}
+
+// Withdraw from vault
+import { YearnV3VaultABI as IYearnV3Vault } from "./abis";
+function main(vaultAddress: Address, assets: Uint256, receiver: Address, owner: Address): Uint256 {
+  const vault = IYearnV3Vault.at(vaultAddress);
+  return vault.withdraw(assets, receiver, owner);
+}
+
+// Redeem shares
+import { YearnV3VaultABI as IYearnV3Vault } from "./abis";
+function main(vaultAddress: Address, shares: Uint256, receiver: Address, owner: Address): Uint256 {
+  const vault = IYearnV3Vault.at(vaultAddress);
+  return vault.redeem(shares, receiver, owner);
+}
+```
+
+## Key Addresses
+
+| Chain    | Contract     | Address                                      |
+| -------- | ------------ | -------------------------------------------- |
+| Ethereum | vaultFactory | `0x770D0d1Fb036483Ed4AbB6d53c1C89fb277D812F` |
+
+## ABI Methods
+
+### YearnV3VaultABI (ERC-4626)
+
+- `deposit(uint256,address)` - Deposit assets, receive shares. Returns shares minted
+- `withdraw(uint256,address,address)` - Withdraw by asset amount. Params: assets, receiver, owner
+- `redeem(uint256,address,address)` - Redeem by share amount. Returns assets
+- `convertToShares(uint256)` - Preview shares for asset amount
+- `convertToAssets(uint256)` - Preview assets for share amount
+- `totalAssets()` - Total assets managed by vault
+- `pricePerShare()` - Current share price (Yearn-specific, equivalent to convertToAssets(1e18))
+- `balanceOf(address)` - Query vault share balance
+- `approve(address,uint256)` - Approve share spending
+
+## Notes
+
+- TVL: $500M+. ERC-4626 compliant (same interface as sfrxETH, pufETH, sDAI)
+- Each vault has a unique address per underlying asset + strategy combination
+- Approve underlying token to vault before depositing
+- Vaults are deployed via factory - no single canonical vault address

package/sdk/src/skills/zerolend.md

@@ -0,0 +1,108 @@
+# ZeroLend
+
+Leading lending protocol on zkSync Era. Aave V3 fork optimized for zero-knowledge rollups with low transaction costs.
+
+## Category
+
+lending | Chains: zkSync (324)
+
+## SauceScript Functions
+
+### supply
+
+Supply assets to earn interest. Same interface as Aave V3.
+
+```typescript
+import { ZeroLendPoolABI as IZeroLendPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, onBehalfOf: Address): Uint256 {
+  const pool = IZeroLendPool.at(poolAddress);
+  pool.supply(asset, amount, onBehalfOf, 0);
+  return 1;
+}
+```
+
+- `onBehalfOf`: Address receiving the supply tokens (use msg.sender for self)
+- Requires ERC-20 approval to the Pool
+
+### withdraw
+
+Withdraw supplied assets.
+
+```typescript
+import { ZeroLendPoolABI as IZeroLendPool } from "./abis";
+
+function main(poolAddress: Address, asset: Address, amount: Uint256, to: Address): Uint256 {
+  const pool = IZeroLendPool.at(poolAddress);
+  return pool.withdraw(asset, amount, to);
+}
+```
+
+- `amount`: Use `type(uint256).max` to withdraw all
+- Returns actual withdrawn amount
+
+### borrow
+
+Borrow assets against supplied collateral.
+
+```typescript
+import { ZeroLendPoolABI as IZeroLendPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IZeroLendPool.at(poolAddress);
+  pool.borrow(asset, amount, interestRateMode, 0, onBehalfOf);
+  return 1;
+}
+```
+
+- `interestRateMode`: 2 = variable rate
+
+### repay
+
+Repay borrowed debt.
+
+```typescript
+import { ZeroLendPoolABI as IZeroLendPool } from "./abis";
+
+function main(
+  poolAddress: Address,
+  asset: Address,
+  amount: Uint256,
+  interestRateMode: Uint256,
+  onBehalfOf: Address,
+): Uint256 {
+  const pool = IZeroLendPool.at(poolAddress);
+  return pool.repay(asset, amount, interestRateMode, onBehalfOf);
+}
+```
+
+- `amount`: Use `type(uint256).max` to repay full debt
+- Requires ERC-20 approval to the Pool
+
+## Deployed Addresses
+
+| Chain  | Contract | Address                                      |
+| ------ | -------- | -------------------------------------------- |
+| zkSync | pool     | `0x4d9429246EA989C9CeE203B43F6d1D7D83e3B8F8` |
+
+## ABI Reference
+
+### ZeroLendPoolABI
+
+- `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 debt
+
+## Notes
+
+- Same interface as Aave V3 (forked codebase) -- referralCode always 0
+- interestRateMode: 2 = variable (stable rate not supported)
+- All supply/repay operations require ERC-20 approval to the Pool
+- zkSync Era-only deployment. TVL: $100M+. Audited

package/sdk/src/skills/zerox.md

@@ -0,0 +1,51 @@
+# 0x Protocol
+
+DEX aggregation protocol powering swaps across the DeFi ecosystem. Exchange Proxy provides a single entry point for token swaps across multiple sources.
+
+## Category
+
+aggregator | Chains: Ethereum, Arbitrum, Optimism, Polygon, BSC, Avalanche, Base
+
+## Key Operations
+
+- **transformERC20**: Execute a token swap via the Exchange Proxy transformer pipeline
+
+## SDK Usage
+
+```typescript
+import { protocolInfo, deployments, sauceFunctions } from "@eco-incorp/sauce/protocols/zerox";
+```
+
+## SauceScript Examples
+
+```typescript
+// Note: 0x requires off-chain route computation via 0x API before on-chain execution.
+// The transformERC20 function uses transformations array populated from API response.
+```
+
+## Key Addresses
+
+| Chain     | Contract      | Address                                      |
+| --------- | ------------- | -------------------------------------------- |
+| Ethereum  | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| Arbitrum  | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| Optimism  | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| Polygon   | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| BSC       | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| Avalanche | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+| Base      | exchangeProxy | `0xDef1C0ded9bec7F1a1670819833240f027b25EfF` |
+
+## ABI Methods
+
+### ExchangeProxyABI
+
+- `transformERC20(address,address,uint256,uint256,tuple[])` - Execute token swap via transformer pipeline. Payable. Params: inputToken, outputToken, inputTokenAmount, minOutputTokenAmount, transformations (array of Transformation tuples). Returns outputTokenAmount
+  - Transformation tuple: `{ deploymentNonce (uint32), data (bytes) }` - Each transformation specifies a deployed transformer and its calldata
+
+## Notes
+
+- Same Exchange Proxy address across all 7 chains
+- Uses transformer pipeline architecture - each swap is a sequence of transformations
+- Route computation happens via 0x API - transformations array comes from API response
+- Approve inputToken to exchangeProxy before swapping
+- 0x API provides the optimal route, slippage protection, and transformer calldata

package/sdk/src/skills/zksync-bridge.md

@@ -0,0 +1,67 @@
+# zkSync Native Bridge
+
+Official zkSync Era bridge via DiamondProxy. Deposits ETH and executes L2 transactions from Ethereum with ZK proof-based finality.
+
+## Category
+
+native L2 bridge | Direction: L1 to L2 (Ethereum to zkSync Era) | Chains: Ethereum (1), zkSync Era (324)
+
+## SauceScript Functions
+
+### depositETH
+
+Deposit ETH from Ethereum L1 to zkSync Era L2.
+
+```typescript
+import { ZkSyncDiamondProxyABI as IDiamondProxy } from "./abis";
+
+function main(diamondProxyAddress: Address, recipient: Address, l2GasLimit: Uint256): Uint256 {
+  const proxy = IDiamondProxy.at(diamondProxyAddress);
+  return proxy.requestL2Transaction(
+    recipient,
+    ctx.msgValue(),
+    0x00,
+    l2GasLimit,
+    800,
+    [],
+    ctx.msgSender(),
+  );
+}
+```
+
+- `recipient`: Address to receive ETH on zkSync L2 (also the contract to call if `_calldata` is provided)
+- `_l2Value`: Amount of ETH to send to the recipient on L2 (use `msg.value`)
+- `_calldata`: Optional calldata to execute on L2. `0x00` for simple ETH deposits
+- `_l2GasLimit`: Gas limit for L2 execution (e.g. 300000)
+- `_l2GasPerPubdataByteLimit`: Gas per pubdata byte limit (800 is the standard value)
+- `_factoryDeps`: Array of contract bytecodes to deploy on L2. Empty `[]` for standard operations
+- `_refundRecipient`: Address to receive excess gas refund on L2 (use `msg.sender`)
+- `msg.value` must cover: L2 value + L2 gas costs. Use `l2TransactionBaseCost()` to estimate
+
+## Deployed Addresses
+
+| Chain    | Contract     | Address                                      |
+| -------- | ------------ | -------------------------------------------- |
+| Ethereum | diamondProxy | `0x32400084C286CF3E17e7B677ea9583e60a000324` |
+| zkSync   | l2Bridge     | `0x11f943b2c77b743AB90f4A0Ae7d5A4e7FCA3E102` |
+
+## ABI Reference
+
+### ZkSyncDiamondProxyABI
+
+- `requestL2Transaction(address _contractL2, uint256 _l2Value, bytes _calldata, uint256 _l2GasLimit, uint256 _l2GasPerPubdataByteLimit, bytes[] _factoryDeps, address _refundRecipient) returns (uint256 canonicalTxHash)` [payable] - Request an L2 transaction from L1. Used for ETH deposits, contract calls, and contract deployments
+- `l2TransactionBaseCost(uint256 _gasPrice, uint256 _l2GasLimit, uint256 _l2GasPerPubdataByteLimit) returns (uint256)` - Estimate the base cost of an L2 transaction (view). Use to calculate required msg.value
+
+## Notes
+
+- **L1 to L2** via DiamondProxy. For L2 to L1 withdrawals, use the L2 withdraw mechanism on zkSync Era
+- `requestL2Transaction` is a general-purpose L1-to-L2 transaction request -- handles ETH deposits, contract calls, and even contract deployments (via `_factoryDeps`)
+- `msg.value` must cover: `_l2Value + l2TransactionBaseCost(gasPrice, _l2GasLimit, _l2GasPerPubdataByteLimit)`
+- Use `l2TransactionBaseCost()` to estimate the gas cost component before submitting
+- `_l2GasPerPubdataByteLimit`: 800 is the standard value (required for pubdata pricing)
+- `_factoryDeps`: used when deploying contracts via L1. Empty array for standard ETH transfers
+- zkEVM architecture -- L2 to L1 withdrawals finalize with ZK proofs (typically 1-24 hours)
+- L1 to L2 deposits finalize after the batch containing the transaction is committed (~minutes)
+- For ERC-20 bridging, use the zkSync ERC20 Bridge contracts (separate from the DiamondProxy)
+- Canonical bridge -- no third-party risk, secured by zkSync's ZK proving system (Matter Labs)
+- Audited