curvance 4.1.2 → 5.1.0

package/README.md

@@ -35,7 +35,6 @@ const { markets, reader, dexAgg, global_milestone } = await setupChain("monad-ma
 setupChain(
     chain: ChainRpcPrefix,
     provider: curvance_provider | null = null,   // signer (wallet) OR read-only provider; null → SDK default
-    approval_protection: boolean = false,         // revoke-before-approve pattern
     api_url: string = "https://api.curvance.com",
     options: {
         feePolicy?: FeePolicy;                    // zap/leverage fee routing (default: NO_FEE_POLICY)
@@ -57,11 +56,18 @@ setupChain(
 - **Explicit `options.readProvider`** → wins over all of the above. Use when you want deterministic read transport (e.g. fork testing).
 - **Writes** always route through the connected signer; they never use the chain RPC or fallbacks.
 
+### Write approvals
+
+- High-level write methods always preflight the approvals they need before submit.
+- Missing ERC20 allowance throws a descriptive error instead of sending a revert-prone transaction.
+- Missing zapper or position-manager delegate approval also throws before submit.
+- There is no setup-time approval mode switch. Use `approveUnderlying`, `approveZapAsset`, and `approvePlugin` explicitly when the caller needs to satisfy approvals.
+
 ### Explore markets
 
 ```ts
 for (const market of markets) {
-    console.log(`${market.name} | tvl: ${market.tvl} | debt: ${market.totalDebt}`);
+    console.log(`${market.name} | deposits: ${market.totalDeposits} | debt: ${market.totalDebt}`);
     for (const token of market.tokens) {
         console.log(`  ${token.symbol} | price: ${token.getPrice()} | apy: ${token.getApy(true)}%`);
     }
@@ -90,7 +96,7 @@ for (const market of markets) {
 ```ts
 market.name                 // market name
 market.address              // market contract address
-market.tvl                  // total value locked (USD, Decimal)
+market.totalDeposits        // total market deposits (USD, Decimal)
 market.totalDebt            // total outstanding debt (USD, Decimal)
 market.totalCollateral      // total posted collateral (USD, Decimal)
 market.cooldownLength       // hold period between actions (20 min)
@@ -182,7 +188,7 @@ token.getUserDebt(inUSD)              // outstanding debt (borrow tokens)
 ### Market totals & caps
 
 ```ts
-token.getTvl(inUSD)
+token.getDeposits(inUSD)               // underlying assets held (USD or bigint)
 token.getTotalCollateral(inUSD)
 token.getCollateralCap(inUSD)          // remaining collateral capacity
 token.getDebtCap(inUSD)               // remaining debt capacity
@@ -222,6 +228,7 @@ token.getMaxBorrowable()             // max amount given credit
 ```ts
 token.getSnapshot(account)                // position snapshot for an account
 token.maxRedemption(inShares, bufferTime) // max redeemable amount
+token.maxRemovableCollateral(inShares, bufferTime) // max posted collateral removable without violating health
 token.simulateDeposit(amount)             // preview deposit without executing
 token.simulateDepositAsCollateral(amount)
 ```
@@ -254,7 +261,8 @@ await token.redeemCollateral(amount, receiver?, owner?)
 
 // Manage posted collateral
 await token.postCollateral(amount)   // post unposted balance as collateral
-await token.removeCollateral(amount, removeAll?)
+await token.removeCollateralExact(amount) // exact collateral removal, capped to the safe removable max
+await token.removeMaxCollateral()         // remove the maximum valid posted collateral
 ```
 
 ### Borrow & Repay (`BorrowableCToken` only)
@@ -292,6 +300,7 @@ if (!approved) await token.approvePlugin('simple', 'zapper')
 // Plugin types
 // ZapperTypes:          'none' | 'native-vault' | 'vault' | 'simple' | 'native-simple'
 // PositionManagerTypes: 'native-vault' | 'simple' | 'vault'
+// `leverageDown(...)` currently executes through the 'simple' position manager only.
 
 const zapper = token.getZapper('simple')
 const positionManager = token.getPositionManager('simple')
@@ -338,6 +347,7 @@ await collateralToken.depositAsCollateral(amount)
 await collateralToken.leverageUp(borrowToken, new Decimal(3), 'simple', new Decimal(0.005))
 
 // Reduce leverage
+// Deleverage currently executes through the simple position manager path.
 await collateralToken.leverageDown(borrowToken, currentLeverage, targetLeverage, 'simple', slippage)
 
 // Check current leverage
@@ -522,7 +532,7 @@ const feePolicy = flatFeePolicy({
     stableToStableBps: 2n,             // optional lower fee for stable↔stable swaps
 })
 
-const { markets } = await setupChain("monad-mainnet", wallet, false, undefined, { feePolicy })
+const { markets } = await setupChain("monad-mainnet", wallet, undefined, { feePolicy })
 ```
 
 The SDK automatically returns 0 bps for native ↔ wrapped-native swaps and same-token no-op zaps.
@@ -575,6 +585,8 @@ const snapshot = await takePortfolioSnapshot(account)
 const marketSnapshot = snapshotMarket(market)
 ```
 
+`snapshotMarket(...)` requires full user token data. `takePortfolioSnapshot(...)` will automatically promote summary-scoped markets back to full user data before reading token balances. If you previously called `refreshActiveUserMarketSummaries(...)` and need a direct single-market snapshot, run `market.reloadUserData(account)` or `Market.reloadUserMarkets(...)` first.
+
 ## ❯ Optimizer
 
 The `OptimizerReader` reads yield-rebalancing vaults that allocate across markets.
@@ -582,7 +594,10 @@ The `OptimizerReader` reads yield-rebalancing vaults that allocate across market
 ```ts
 import { OptimizerReader } from "curvance"
 
-const optimizer = new OptimizerReader(provider)
+const optimizer = new OptimizerReader(optimizerReaderAddress, provider)
+
+await optimizer.getOptimizerAPY(optimizerAddress)
+// Returns: weighted-average optimizer APY in WAD
 
 await optimizer.getOptimizerMarketData(optimizerAddresses)
 // Returns: { totalAssets, sharePrice, performanceFee, markets[] }
@@ -590,9 +605,8 @@ await optimizer.getOptimizerMarketData(optimizerAddresses)
 await optimizer.getOptimizerUserData(optimizerAddresses, account)
 // Returns: user balance and redeemable amounts
 
-await optimizer.optimalDeposit(optimizer, assets)    // best market to deposit into
-await optimizer.optimalWithdrawal(optimizer, assets) // best market to withdraw from
-await optimizer.optimalRebalance(optimizer)          // suggested reallocations: { cToken, assets }[]
+await optimizer.optimalRebalance(optimizer, 100n)
+// Returns: { actions: { cToken, assetsOrBps }[], bounds: { cToken, minBps, maxBps }[] }
 ```
 
 ## ❯ TypeScript Types
@@ -617,6 +631,7 @@ type CollateralSource = "Renzo" | "Upshift" | "Yuzu" | "Native" | "Circle" | "Fa
 // Operations
 type ZapperTypes = 'none' | 'native-vault' | 'vault' | 'simple' | 'native-simple'
 type PositionManagerTypes = 'native-vault' | 'simple' | 'vault'
+// `leverageDown(...)` accepts 'simple' only.
 type ChangeRate = 'year' | 'month' | 'week' | 'day'
 
 // DEX
@@ -644,6 +659,46 @@ NATIVE_ADDRESS   // canonical native token address
 DEFAULT_SLIPPAGE_BPS  // 100n  (1%)
 ```
 
+### Leverage tuning (`LEVERAGE`)
+
+Exposed tuning block used by leverage preview / mutation paths. Values are considered tunable across releases — SDK consumers pinning against specific values opt into the coupling.
+
+```ts
+import { LEVERAGE } from 'curvance';
+
+LEVERAGE.MAX_LEVERAGE_FACTOR          // Decimal(0.98)
+// Cap applied to the theoretical max leverage span. Reserves ~2% of the
+// equity-fraction slippage budget for deterministic loss channels
+// (CURVANCE_FEE_BPS, pool-fee variance, Redstone drift, share rounding)
+// that would otherwise push post-op LTV above collRatio at the boundary.
+
+LEVERAGE.LEVERAGE_UP_BUFFER_BPS       // 10n
+// Flat BPS buffer added to leverage-up slippage for share-rounding + fresh
+// Redstone price drift between snapshot RPC and tx broadcast. NOT amplified
+// by (L-1); the contract's equity-fraction denominator handles amplification.
+
+LEVERAGE.DELEVERAGE_OVERHEAD_BPS      // 20n
+// BPS overhead added to full-deleverage swap sizing to absorb DEX impact
+// and oracle drift without leaving dust debt. The contract returns any
+// excess debt token to the user, so economic loss is zero — but
+// `checkSlippage` treats the intentional overshoot as equity loss and
+// amplifies it by (L-1), which the contract-slippage expansion compensates.
+
+LEVERAGE.SHARES_BUFFER_BPS            // 2n
+// Downward BPS buffer on `virtualConvertToShares` and the inner
+// `previewDeposit` step of `getVaultExpectedShares`. Covers exchange-rate
+// drift from interest accrual since cache load so actual mint satisfies
+// `shares >= expectedShares` at tx inclusion.
+
+LEVERAGE.LEVERAGE_UP_VAULT_DRIFT_BPS  // 30n
+// Per-leverage-unit BPS buffer for `checkSlippage` on vault + native-vault
+// leverage-up paths. Absorbs drift between the collateral vault's
+// fundamental mint rate at tx time and the stored oracle price that
+// `marketManager.statusOf` uses inside `checkSlippage`. Mirrors the
+// `(L-1) × feeBps` amplification the simple branch uses for DEX-fee
+// absorption, with a different K since vault paths have no DEX leg.
+```
+
 ## ❯ Dependencies
 
 | Package | Purpose |

package/dist/abis/OptimizerReader.json

@@ -1,4 +1,23 @@
 [
+    {
+        "type": "function",
+        "name": "getOptimizerAPY",
+        "inputs": [
+            {
+                "name": "optimizer",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "apy",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "getOptimizerMarketData",
@@ -70,7 +89,7 @@
                 ]
             }
         ],
-        "stateMutability": "view"
+        "stateMutability": "nonpayable"
     },
     {
         "type": "function",
@@ -115,7 +134,7 @@
     },
     {
         "type": "function",
-        "name": "optimalDeposit",
+        "name": "optimalRebalance",
         "inputs": [
             {
                 "name": "optimizer",
@@ -123,30 +142,11 @@
                 "internalType": "address"
             },
             {
-                "name": "assets",
+                "name": "slippageBps",
                 "type": "uint256",
                 "internalType": "uint256"
             }
         ],
-        "outputs": [
-            {
-                "name": "market",
-                "type": "address",
-                "internalType": "address"
-            }
-        ],
-        "stateMutability": "view"
-    },
-    {
-        "type": "function",
-        "name": "optimalRebalance",
-        "inputs": [
-            {
-                "name": "optimizer",
-                "type": "address",
-                "internalType": "address"
-            }
-        ],
         "outputs": [
             {
                 "name": "actions",
@@ -159,35 +159,33 @@
                         "internalType": "contract IBorrowableCToken"
                     },
                     {
-                        "name": "assets",
+                        "name": "assetsOrBps",
                         "type": "int256",
                         "internalType": "int256"
                     }
                 ]
-            }
-        ],
-        "stateMutability": "view"
-    },
-    {
-        "type": "function",
-        "name": "optimalWithdrawal",
-        "inputs": [
-            {
-                "name": "optimizer",
-                "type": "address",
-                "internalType": "address"
             },
             {
-                "name": "assets",
-                "type": "uint256",
-                "internalType": "uint256"
-            }
-        ],
-        "outputs": [
-            {
-                "name": "market",
-                "type": "address",
-                "internalType": "address"
+                "name": "bounds",
+                "type": "tuple[]",
+                "internalType": "struct LendingOptimizer.AllocationBound[]",
+                "components": [
+                    {
+                        "name": "cToken",
+                        "type": "address",
+                        "internalType": "address"
+                    },
+                    {
+                        "name": "minBps",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "maxBps",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    }
+                ]
             }
         ],
         "stateMutability": "view"

package/dist/abis/ProtocolReader.json

@@ -336,6 +336,108 @@
         ],
         "stateMutability": "view"
     },
+    {
+        "type": "function",
+        "name": "getDynamicMarketData",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "data",
+                "type": "tuple[]",
+                "internalType": "struct ProtocolReader.DynamicMarketData[]",
+                "components": [
+                    {
+                        "name": "_address",
+                        "type": "address",
+                        "internalType": "address"
+                    },
+                    {
+                        "name": "tokens",
+                        "type": "tuple[]",
+                        "internalType": "struct ProtocolReader.DynamicMarketToken[]",
+                        "components": [
+                            {
+                                "name": "_address",
+                                "type": "address",
+                                "internalType": "address"
+                            },
+                            {
+                                "name": "totalSupply",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "exchangeRate",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "totalAssets",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "collateral",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "debt",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "sharePrice",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "assetPrice",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "sharePriceLower",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "assetPriceLower",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "borrowRate",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "predictedBorrowRate",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "utilizationRate",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "supplyRate",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "liquidity",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            }
+                        ]
+                    }
+                ]
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "getLeverageSnapshot",
@@ -402,11 +504,56 @@
     },
     {
         "type": "function",
-        "name": "getDynamicMarketData",
-        "inputs": [],
+        "name": "getLiquidationPrice",
+        "inputs": [
+            {
+                "name": "account",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "cToken",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "long",
+                "type": "bool",
+                "internalType": "bool"
+            }
+        ],
         "outputs": [
             {
-                "name": "data",
+                "name": "price",
+                "type": "uint256",
+                "internalType": "uint256"
+            },
+            {
+                "name": "errorHit",
+                "type": "bool",
+                "internalType": "bool"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "getMarketStates",
+        "inputs": [
+            {
+                "name": "markets",
+                "type": "address[]",
+                "internalType": "address[]"
+            },
+            {
+                "name": "account",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "dynamicMarkets",
                 "type": "tuple[]",
                 "internalType": "struct ProtocolReader.DynamicMarketData[]",
                 "components": [
@@ -498,40 +645,151 @@
                         ]
                     }
                 ]
+            },
+            {
+                "name": "userMarkets",
+                "type": "tuple[]",
+                "internalType": "struct ProtocolReader.UserMarket[]",
+                "components": [
+                    {
+                        "name": "_address",
+                        "type": "address",
+                        "internalType": "address"
+                    },
+                    {
+                        "name": "collateral",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "maxDebt",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "debt",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "positionHealth",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "cooldown",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "errorCodeHit",
+                        "type": "bool",
+                        "internalType": "bool"
+                    },
+                    {
+                        "name": "tokens",
+                        "type": "tuple[]",
+                        "internalType": "struct ProtocolReader.UserMarketToken[]",
+                        "components": [
+                            {
+                                "name": "_address",
+                                "type": "address",
+                                "internalType": "address"
+                            },
+                            {
+                                "name": "userAssetBalance",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "userShareBalance",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "userUnderlyingBalance",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "userCollateral",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "userDebt",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            },
+                            {
+                                "name": "liquidationPrice",
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            }
+                        ]
+                    }
+                ]
             }
         ],
         "stateMutability": "view"
     },
     {
         "type": "function",
-        "name": "getLiquidationPrice",
+        "name": "getMarketSummaries",
         "inputs": [
             {
-                "name": "account",
-                "type": "address",
-                "internalType": "address"
+                "name": "markets",
+                "type": "address[]",
+                "internalType": "address[]"
             },
             {
-                "name": "cToken",
+                "name": "account",
                 "type": "address",
                 "internalType": "address"
-            },
-            {
-                "name": "long",
-                "type": "bool",
-                "internalType": "bool"
             }
         ],
         "outputs": [
             {
-                "name": "price",
-                "type": "uint256",
-                "internalType": "uint256"
-            },
-            {
-                "name": "errorHit",
-                "type": "bool",
-                "internalType": "bool"
+                "name": "userMarkets",
+                "type": "tuple[]",
+                "internalType": "struct ProtocolReader.UserMarketSummary[]",
+                "components": [
+                    {
+                        "name": "_address",
+                        "type": "address",
+                        "internalType": "address"
+                    },
+                    {
+                        "name": "collateral",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "maxDebt",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "debt",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "positionHealth",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "cooldown",
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    },
+                    {
+                        "name": "errorCodeHit",
+                        "type": "bool",
+                        "internalType": "bool"
+                    }
+                ]
             }
         ],
         "stateMutability": "view"
@@ -634,40 +892,6 @@
         ],
         "stateMutability": "view"
     },
-    {
-        "type": "function",
-        "name": "getPriceSafely",
-        "inputs": [
-            {
-                "name": "asset",
-                "type": "address",
-                "internalType": "address"
-            },
-            {
-                "name": "inUSD",
-                "type": "bool",
-                "internalType": "bool"
-            },
-            {
-                "name": "getLower",
-                "type": "bool",
-                "internalType": "bool"
-            },
-            {
-                "name": "errorCodeBreakpoint",
-                "type": "uint256",
-                "internalType": "uint256"
-            }
-        ],
-        "outputs": [
-            {
-                "name": "",
-                "type": "uint256",
-                "internalType": "uint256"
-            }
-        ],
-        "stateMutability": "view"
-    },
     {
         "type": "function",
         "name": "getStaticMarketData",