lends-sdk 0.1.0__tar.gz

lends_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.mypy_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/

lends_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LENDS Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lends_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: lends-sdk
+Version: 0.1.0
+Summary: Non-custodial Python SDK for LENDS lending, leUSD, and sleUSD.
+Project-URL: Homepage, https://github.com/lendsprotocol/lends-sdk-python
+Project-URL: Repository, https://github.com/lendsprotocol/lends-sdk-python
+Project-URL: Issues, https://github.com/lendsprotocol/lends-sdk-python/issues
+Author: LENDS Protocol
+License: MIT License
+        
+        Copyright (c) 2026 LENDS Protocol
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: defi,ethereum,lending,lends,leusd,sleusd
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: web3<8,>=7.14
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LENDS Python SDK
+
+Typed, non-custodial access to LENDS lending/borrowing, the leUSD PSM, and sleUSD staking.
+
+## Install
+
+```bash
+python -m pip install lends-sdk
+```
+
+## Usage
+
+```python
+import os
+from lends_sdk import LendsClient
+
+lends = LendsClient(os.environ["RPC_URL"])
+lends.assert_chain()
+
+protocol = lends.get_protocol_state()
+markets = lends.get_markets()
+position = lends.get_position(
+    "0x1111111111111111111111111111111111111111",
+    markets[0].address,
+)
+
+amount = 10 ** markets[0].collateral_decimals
+approval = lends.transactions.approve_collateral(markets[0].address, amount)
+deposit = lends.transactions.deposit(markets[0].address, amount)
+```
+
+`PreparedTransaction.as_dict()` returns `to`, `data`, `value`, and `chainId` for a wallet or signing system. The SDK does not accept private keys, sign, or broadcast.
+
+All amounts are raw integer token units. leUSD and sleUSD use 6 decimals; collateral and USDG decimals are read on-chain; oracle prices are normalized to 8 decimals. Quotes and projected position values are point-in-time previews. Contract execution is authoritative.
+
+## Scope
+
+Included: approvals, collateral deposit/withdrawal, borrow/repay, fee accrual, PSM conversion, sleUSD stake/unstake lifecycle, and relevant state/statistics.
+
+Excluded: every privileged write, liquidation execution, reserves, harvests, losses, minters, risk settings, pauses, ownership, upgrades, LENDS purchases, locks, liquidity, and vesting.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests
+ruff check .
+mypy
+python -m build
+twine check dist/*
+```
+

lends_sdk-0.1.0/README.md

@@ -0,0 +1,52 @@
+# LENDS Python SDK
+
+Typed, non-custodial access to LENDS lending/borrowing, the leUSD PSM, and sleUSD staking.
+
+## Install
+
+```bash
+python -m pip install lends-sdk
+```
+
+## Usage
+
+```python
+import os
+from lends_sdk import LendsClient
+
+lends = LendsClient(os.environ["RPC_URL"])
+lends.assert_chain()
+
+protocol = lends.get_protocol_state()
+markets = lends.get_markets()
+position = lends.get_position(
+    "0x1111111111111111111111111111111111111111",
+    markets[0].address,
+)
+
+amount = 10 ** markets[0].collateral_decimals
+approval = lends.transactions.approve_collateral(markets[0].address, amount)
+deposit = lends.transactions.deposit(markets[0].address, amount)
+```
+
+`PreparedTransaction.as_dict()` returns `to`, `data`, `value`, and `chainId` for a wallet or signing system. The SDK does not accept private keys, sign, or broadcast.
+
+All amounts are raw integer token units. leUSD and sleUSD use 6 decimals; collateral and USDG decimals are read on-chain; oracle prices are normalized to 8 decimals. Quotes and projected position values are point-in-time previews. Contract execution is authoritative.
+
+## Scope
+
+Included: approvals, collateral deposit/withdrawal, borrow/repay, fee accrual, PSM conversion, sleUSD stake/unstake lifecycle, and relevant state/statistics.
+
+Excluded: every privileged write, liquidation execution, reserves, harvests, losses, minters, risk settings, pauses, ownership, upgrades, LENDS purchases, locks, liquidity, and vesting.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests
+ruff check .
+mypy
+python -m build
+twine check dist/*
+```
+

lends_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lends-sdk"
+version = "0.1.0"
+description = "Non-custodial Python SDK for LENDS lending, leUSD, and sleUSD."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "LENDS Protocol" }]
+keywords = ["lends", "lending", "defi", "leusd", "sleusd", "ethereum"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+dependencies = ["web3>=7.14,<8"]
+
+[project.urls]
+Homepage = "https://github.com/lendsprotocol/lends-sdk-python"
+Repository = "https://github.com/lendsprotocol/lends-sdk-python"
+Issues = "https://github.com/lendsprotocol/lends-sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mypy>=1.15",
+  "ruff>=0.11",
+  "twine>=6.1"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lends_sdk"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["lends_sdk"]
+mypy_path = "src"
+

lends_sdk-0.1.0/src/lends_sdk/__init__.py

@@ -0,0 +1,56 @@
+from .client import ROBINHOOD_MAINNET, LendsClient
+from .math import (
+    BPS_DENOMINATOR,
+    LEUSD_SCALE,
+    PRICE_SCALE,
+    SECONDS_PER_YEAR,
+    collateral_value,
+    convert_decimals_exact,
+    health_factor,
+    liquidation_price,
+    max_borrow,
+    pending_vault_fee,
+    scale_price_to_e8,
+    withdrawable_collateral,
+)
+from .transactions import LendsTransactions
+from .types import (
+    Deployment,
+    LiquidationPlan,
+    MarketState,
+    PositionState,
+    PreparedTransaction,
+    ProtocolState,
+    PsmQuote,
+    StakingState,
+    TokenState,
+    UnstakeRequest,
+)
+
+__all__ = [
+    "BPS_DENOMINATOR",
+    "LEUSD_SCALE",
+    "PRICE_SCALE",
+    "ROBINHOOD_MAINNET",
+    "SECONDS_PER_YEAR",
+    "Deployment",
+    "LendsClient",
+    "LendsTransactions",
+    "LiquidationPlan",
+    "MarketState",
+    "PositionState",
+    "PreparedTransaction",
+    "ProtocolState",
+    "PsmQuote",
+    "StakingState",
+    "TokenState",
+    "UnstakeRequest",
+    "collateral_value",
+    "convert_decimals_exact",
+    "health_factor",
+    "liquidation_price",
+    "max_borrow",
+    "pending_vault_fee",
+    "scale_price_to_e8",
+    "withdrawable_collateral",
+]

lends_sdk-0.1.0/src/lends_sdk/abi.py

@@ -0,0 +1,222 @@
+"""Minimal public ABIs. Privileged state-changing functions are intentionally absent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _io(name: str, type_: str, components: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    item: dict[str, Any] = {"name": name, "type": type_}
+    if components is not None:
+        item["components"] = components
+    return item
+
+
+def _fn(
+    name: str,
+    inputs: list[dict[str, Any]] | None = None,
+    outputs: list[dict[str, Any]] | None = None,
+    mutability: str = "view",
+) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "name": name,
+        "stateMutability": mutability,
+        "inputs": inputs or [],
+        "outputs": outputs or [],
+    }
+
+
+U256 = _io("", "uint256")
+ADDRESS = _io("", "address")
+BOOL = _io("", "bool")
+
+LENDING_ABI = [
+    _fn("leusd", outputs=[ADDRESS]),
+    _fn("usdg", outputs=[ADDRESS]),
+    _fn("usdgDecimals", outputs=[_io("", "uint8")]),
+    _fn("paused", outputs=[BOOL]),
+    _fn("collateralCount", outputs=[U256]),
+    _fn("collateralList", [_io("", "uint256")], [ADDRESS]),
+    _fn(
+        "collateralConfigs",
+        [_io("", "address")],
+        [
+            _io("enabled", "bool"),
+            _io("token", "address"),
+            _io("priceFeed", "address"),
+            _io("symbol", "bytes32"),
+            _io("collateralDecimals", "uint8"),
+            _io("borrowLtvBps", "uint16"),
+            _io("liquidationThresholdBps", "uint16"),
+            _io("liquidationPenaltyBps", "uint16"),
+            _io("closeFactorBps", "uint16"),
+            _io("perVaultDebtCap", "uint256"),
+            _io("collateralDebtCap", "uint256"),
+            _io("depositCapRaw", "uint256"),
+            _io("totalDebt", "uint256"),
+            _io("totalDepositsRaw", "uint256"),
+            _io("depositsPaused", "bool"),
+            _io("borrowsPaused", "bool"),
+            _io("withdrawsPaused", "bool"),
+            _io("marketPaused", "bool"),
+        ],
+    ),
+    _fn(
+        "vaults",
+        [_io("", "address"), _io("", "address")],
+        [
+            _io("collateralRaw", "uint256"),
+            _io("principalDebt", "uint256"),
+            _io("accruedFee", "uint256"),
+            _io("lastAccrualTs", "uint256"),
+        ],
+    ),
+    _fn("vaultDebt", [_io("", "address"), _io("", "address")], [U256]),
+    _fn("healthFactorBps", [_io("", "address"), _io("", "address")], [U256]),
+    _fn(
+        "liquidationPlan",
+        [_io("borrower", "address"), _io("collateral", "address")],
+        [
+            _io(
+                "plan",
+                "tuple",
+                [
+                    _io("collateralRaw", "uint256"),
+                    _io("debtToCover", "uint256"),
+                    _io("principalToCover", "uint256"),
+                    _io("feeToCover", "uint256"),
+                    _io("targetSettlementLeusd", "uint256"),
+                    _io("fullLiquidation", "bool"),
+                    _io("healthFactorAfterBps", "uint256"),
+                ],
+            )
+        ],
+    ),
+    *[
+        _fn(name, outputs=[U256])
+        for name in (
+            "totalDebt",
+            "totalUncollectedFees",
+            "realizedRevenueForStakers",
+            "realizedRevenueForProtocol",
+            "insuranceFundLeusd",
+            "badDebtLeusd",
+            "protocolDebtCap",
+            "stabilityFeeAprBps",
+            "insuranceTargetBps",
+            "insuranceFeeShareBps",
+            "psmUsdgLiabilities",
+            "psmLeusdSupply",
+            "psmIdleUsdgAssets",
+            "psmMorphoDeployedUsdgAssets",
+            "psmMorphoShares",
+            "psmCap",
+            "stakerTargetRevenueDue",
+            "stakerTargetLastAccrualTs",
+            "stakerTargetAprBps",
+            "stakingCapacityLeusd",
+            "pendingLiquidationPrincipal",
+            "pendingLiquidationFees",
+        )
+    ],
+    _fn(
+        "deposit",
+        [_io("collateral", "address"), _io("amount", "uint256")],
+        mutability="nonpayable",
+    ),
+    _fn(
+        "withdraw",
+        [_io("collateral", "address"), _io("amount", "uint256")],
+        mutability="nonpayable",
+    ),
+    _fn(
+        "accrueFee",
+        [_io("borrower", "address"), _io("collateral", "address")],
+        mutability="nonpayable",
+    ),
+    _fn(
+        "borrow",
+        [_io("collateral", "address"), _io("amount", "uint256")],
+        mutability="nonpayable",
+    ),
+    _fn(
+        "repay",
+        [_io("collateral", "address"), _io("maxAmount", "uint256")],
+        [_io("feePaid", "uint256"), _io("principalPaid", "uint256"), _io("overpayment", "uint256")],
+        "nonpayable",
+    ),
+    _fn("psmSwapIn", [_io("usdgAssets", "uint256")], [_io("leusdAmount", "uint256")], "nonpayable"),
+    _fn("psmSwapOut", [_io("leusdAmount", "uint256")], [_io("executed", "bool")], "nonpayable"),
+]
+
+ERC20_ABI = [
+    _fn("name", outputs=[_io("", "string")]),
+    _fn("symbol", outputs=[_io("", "string")]),
+    _fn("decimals", outputs=[_io("", "uint8")]),
+    _fn("totalSupply", outputs=[U256]),
+    _fn("balanceOf", [_io("", "address")], [U256]),
+    _fn("allowance", [_io("", "address"), _io("", "address")], [U256]),
+    _fn("approve", [_io("spender", "address"), _io("amount", "uint256")], [BOOL], "nonpayable"),
+]
+
+STAKING_ABI = [
+    *ERC20_ABI,
+    _fn("paused", outputs=[BOOL]),
+    *[
+        _fn(name, outputs=[U256])
+        for name in (
+            "totalPoolShares",
+            "stakingVaultLeusd",
+            "accountedAssets",
+            "claimableAssets",
+            "stakeEntryAssets",
+            "totalManagedAssets",
+            "realizedLossLeusd",
+            "unvestedRevenue",
+            "reservedPendingClaims",
+            "vestingStartTs",
+            "vestingEndTs",
+            "lastVestingSyncTs",
+            "cooldownSeconds",
+            "UNSTAKE_CLAIM_WINDOW_SECONDS",
+            "MIN_INITIAL_STAKE_LEUSD",
+            "revenueVestingSeconds",
+            "nextPendingWithdrawalId",
+        )
+    ],
+    _fn(
+        "pendingWithdrawals",
+        [_io("", "uint256")],
+        [
+            _io("owner", "address"),
+            _io("shares", "uint256"),
+            _io("requestTs", "uint256"),
+            _io("claimDeadlineTs", "uint256"),
+            _io("completed", "bool"),
+        ],
+    ),
+    _fn(
+        "stake",
+        [_io("amount", "uint256"), _io("minSharesOut", "uint256")],
+        [_io("shares", "uint256")],
+        "nonpayable",
+    ),
+    _fn("requestUnstake", [_io("shares", "uint256")], [_io("id", "uint256")], "nonpayable"),
+    _fn("completeUnstake", [_io("id", "uint256")], [_io("assets", "uint256")], "nonpayable"),
+    _fn("cancelExpiredUnstake", [_io("id", "uint256")], [_io("shares", "uint256")], "nonpayable"),
+]
+
+ORACLE_ABI = [
+    _fn("decimals", outputs=[_io("", "uint8")]),
+    _fn(
+        "latestRoundData",
+        outputs=[
+            _io("roundId", "uint80"),
+            _io("answer", "int256"),
+            _io("startedAt", "uint256"),
+            _io("updatedAt", "uint256"),
+            _io("answeredInRound", "uint80"),
+        ],
+    ),
+]

lends_sdk-0.1.0/src/lends_sdk/client.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+from typing import Any
+
+from web3 import HTTPProvider, Web3
+
+from .abi import ERC20_ABI, LENDING_ABI, ORACLE_ABI, STAKING_ABI
+from .math import (
+    collateral_value,
+    convert_decimals_exact,
+    health_factor,
+    liquidation_price,
+    max_borrow,
+    pending_vault_fee,
+    scale_price_to_e8,
+    withdrawable_collateral,
+)
+from .transactions import LendsTransactions
+from .types import (
+    Deployment,
+    LiquidationPlan,
+    MarketState,
+    PositionState,
+    ProtocolState,
+    PsmQuote,
+    StakingState,
+    TokenState,
+    UnstakeRequest,
+)
+
+ROBINHOOD_MAINNET = Deployment(
+    chain_id=4663,
+    lending="0x064b2eb0209E85ADAd216bba9B7f115063cd2b24",
+    leusd="0x71108CB9c3c0258762F97986535cb018a163675F",
+    sleusd="0x347Fd44634eCf2b394a46dF3816cd6d0BDB35FAb",
+    usdg="0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+)
+
+
+class LendsClient:
+    def __init__(
+        self,
+        rpc_url: str | None = None,
+        *,
+        web3: Web3 | None = None,
+        deployment: Deployment = ROBINHOOD_MAINNET,
+        request_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        if web3 is None and not rpc_url:
+            raise ValueError("rpc_url or web3 is required")
+        self.web3 = web3 or Web3(HTTPProvider(rpc_url, request_kwargs=request_kwargs or {}))
+        self.deployment = deployment
+        self.transactions = LendsTransactions(deployment)
+        self._lending = self.web3.eth.contract(
+            address=Web3.to_checksum_address(deployment.lending), abi=LENDING_ABI
+        )
+        self._staking = self.web3.eth.contract(
+            address=Web3.to_checksum_address(deployment.sleusd), abi=STAKING_ABI
+        )
+
+    def assert_chain(self) -> None:
+        actual = self.web3.eth.chain_id
+        if actual != self.deployment.chain_id:
+            raise RuntimeError(
+                f"RPC chain ID {actual} does not match deployment chain ID "
+                f"{self.deployment.chain_id}"
+            )
+
+    def get_protocol_state(self) -> ProtocolState:
+        names = (
+            "paused",
+            "collateralCount",
+            "totalDebt",
+            "totalUncollectedFees",
+            "realizedRevenueForStakers",
+            "realizedRevenueForProtocol",
+            "insuranceFundLeusd",
+            "badDebtLeusd",
+            "protocolDebtCap",
+            "stabilityFeeAprBps",
+            "insuranceTargetBps",
+            "insuranceFeeShareBps",
+            "psmUsdgLiabilities",
+            "psmLeusdSupply",
+            "psmIdleUsdgAssets",
+            "psmMorphoDeployedUsdgAssets",
+            "psmMorphoShares",
+            "psmCap",
+            "stakerTargetRevenueDue",
+            "stakerTargetLastAccrualTs",
+            "stakerTargetAprBps",
+            "stakingCapacityLeusd",
+            "pendingLiquidationPrincipal",
+            "pendingLiquidationFees",
+        )
+        block = self.web3.eth.get_block("latest")
+        state = {
+            name: getattr(self._lending.functions, name)().call(block_identifier=block["number"])
+            for name in names
+        }
+        return ProtocolState(
+            block_number=block["number"],
+            block_timestamp=block["timestamp"],
+            paused=state["paused"],
+            collateral_count=state["collateralCount"],
+            total_debt=state["totalDebt"],
+            total_uncollected_fees=state["totalUncollectedFees"],
+            realized_revenue_for_stakers=state["realizedRevenueForStakers"],
+            realized_revenue_for_protocol=state["realizedRevenueForProtocol"],
+            insurance_fund_leusd=state["insuranceFundLeusd"],
+            bad_debt_leusd=state["badDebtLeusd"],
+            protocol_debt_cap=state["protocolDebtCap"],
+            stability_fee_apr_bps=state["stabilityFeeAprBps"],
+            insurance_target_bps=state["insuranceTargetBps"],
+            insurance_fee_share_bps=state["insuranceFeeShareBps"],
+            psm_usdg_liabilities=state["psmUsdgLiabilities"],
+            psm_leusd_supply=state["psmLeusdSupply"],
+            psm_idle_usdg_assets=state["psmIdleUsdgAssets"],
+            psm_morpho_deployed_usdg_assets=state["psmMorphoDeployedUsdgAssets"],
+            psm_morpho_shares=state["psmMorphoShares"],
+            psm_cap=state["psmCap"],
+            staker_target_revenue_due=state["stakerTargetRevenueDue"],
+            staker_target_last_accrual_ts=state["stakerTargetLastAccrualTs"],
+            staker_target_apr_bps=state["stakerTargetAprBps"],
+            staking_capacity_leusd=state["stakingCapacityLeusd"],
+            pending_liquidation_principal=state["pendingLiquidationPrincipal"],
+            pending_liquidation_fees=state["pendingLiquidationFees"],
+        )
+
+    def get_markets(self) -> list[MarketState]:
+        count = self._lending.functions.collateralCount().call()
+        return [
+            self.get_market(self._lending.functions.collateralList(index).call())
+            for index in range(count)
+        ]
+
+    def get_market(self, collateral: str) -> MarketState:
+        address = Web3.to_checksum_address(collateral)
+        config = self._lending.functions.collateralConfigs(address).call()
+        feed = self.web3.eth.contract(address=config[2], abi=ORACLE_ABI)
+        decimals = feed.functions.decimals().call()
+        round_data = feed.functions.latestRoundData().call()
+        if round_data[1] <= 0 or round_data[3] == 0:
+            raise RuntimeError(f"invalid oracle response for {address}")
+        symbol = bytes(config[3]).rstrip(b"\x00").decode("utf-8")
+        return MarketState(
+            address=address,
+            enabled=config[0],
+            token=config[1],
+            price_feed=config[2],
+            symbol=symbol,
+            collateral_decimals=config[4],
+            borrow_ltv_bps=config[5],
+            liquidation_threshold_bps=config[6],
+            liquidation_penalty_bps=config[7],
+            close_factor_bps=config[8],
+            per_vault_debt_cap=config[9],
+            collateral_debt_cap=config[10],
+            deposit_cap_raw=config[11],
+            total_debt=config[12],
+            total_deposits_raw=config[13],
+            deposits_paused=config[14],
+            borrows_paused=config[15],
+            withdraws_paused=config[16],
+            market_paused=config[17],
+            oracle_price_e8=scale_price_to_e8(round_data[1], decimals),
+            oracle_updated_at=round_data[3],
+        )
+
+    def get_position(
+        self, owner: str, collateral: str, *, timestamp: int | None = None
+    ) -> PositionState:
+        account = Web3.to_checksum_address(owner)
+        market = self.get_market(collateral)
+        vault = self._lending.functions.vaults(account, market.address).call()
+        fee_apr = self._lending.functions.stabilityFeeAprBps().call()
+        stored_debt = vault[1] + vault[2]
+        at = (
+            int(self.web3.eth.get_block("latest")["timestamp"])
+            if timestamp is None
+            else timestamp
+        )
+        pending_fee = pending_vault_fee(stored_debt, fee_apr, vault[3], at)
+        debt = stored_debt + pending_fee
+        value = collateral_value(
+            vault[0], market.collateral_decimals, market.oracle_price_e8
+        )
+        capacity = max_borrow(value, market.borrow_ltv_bps)
+        return PositionState(
+            owner=account,
+            collateral=market.address,
+            collateral_raw=vault[0],
+            collateral_value_leusd=value,
+            principal_debt=vault[1],
+            accrued_fee=vault[2],
+            pending_fee=pending_fee,
+            debt=debt,
+            last_accrual_ts=vault[3],
+            health_factor_bps=health_factor(
+                value, debt, market.liquidation_threshold_bps
+            ),
+            borrow_capacity=capacity,
+            available_to_borrow=max(capacity - debt, 0),
+            withdrawable_collateral_raw=withdrawable_collateral(
+                vault[0],
+                debt,
+                market.collateral_decimals,
+                market.oracle_price_e8,
+                market.borrow_ltv_bps,
+            ),
+            liquidation_price_e8=liquidation_price(
+                vault[0], debt, market.collateral_decimals, market.liquidation_threshold_bps
+            ),
+        )
+
+    def get_staking_state(self) -> StakingState:
+        names = (
+            "paused",
+            "totalSupply",
+            "totalPoolShares",
+            "stakingVaultLeusd",
+            "accountedAssets",
+            "claimableAssets",
+            "stakeEntryAssets",
+            "totalManagedAssets",
+            "realizedLossLeusd",
+            "unvestedRevenue",
+            "reservedPendingClaims",
+            "vestingStartTs",
+            "vestingEndTs",
+            "lastVestingSyncTs",
+            "cooldownSeconds",
+            "UNSTAKE_CLAIM_WINDOW_SECONDS",
+            "MIN_INITIAL_STAKE_LEUSD",
+            "revenueVestingSeconds",
+            "nextPendingWithdrawalId",
+        )
+        block = self.web3.eth.get_block("latest")
+        state = {
+            name: getattr(self._staking.functions, name)().call(block_identifier=block["number"])
+            for name in names
+        }
+        return StakingState(
+            block_number=block["number"],
+            block_timestamp=block["timestamp"],
+            paused=state["paused"],
+            total_supply=state["totalSupply"],
+            total_pool_shares=state["totalPoolShares"],
+            staking_vault_leusd=state["stakingVaultLeusd"],
+            accounted_assets=state["accountedAssets"],
+            claimable_assets=state["claimableAssets"],
+            stake_entry_assets=state["stakeEntryAssets"],
+            total_managed_assets=state["totalManagedAssets"],
+            realized_loss_leusd=state["realizedLossLeusd"],
+            unvested_revenue=state["unvestedRevenue"],
+            reserved_pending_claims=state["reservedPendingClaims"],
+            vesting_start_ts=state["vestingStartTs"],
+            vesting_end_ts=state["vestingEndTs"],
+            last_vesting_sync_ts=state["lastVestingSyncTs"],
+            cooldown_seconds=state["cooldownSeconds"],
+            claim_window_seconds=state["UNSTAKE_CLAIM_WINDOW_SECONDS"],
+            min_initial_stake_leusd=state["MIN_INITIAL_STAKE_LEUSD"],
+            revenue_vesting_seconds=state["revenueVestingSeconds"],
+            next_pending_withdrawal_id=state["nextPendingWithdrawalId"],
+            capacity_leusd=self._lending.functions.stakingCapacityLeusd().call(
+                block_identifier=block["number"]
+            ),
+        )
+
+    def get_unstake_request(self, request_id: int) -> UnstakeRequest:
+        if request_id < 0:
+            raise ValueError("request_id cannot be negative")
+        owner, shares, requested, deadline, completed = (
+            self._staking.functions.pendingWithdrawals(request_id).call()
+        )
+        return UnstakeRequest(
+            id=request_id,
+            owner=owner,
+            shares=shares,
+            request_ts=requested,
+            claim_deadline_ts=deadline,
+            completed=completed,
+        )
+
+    def get_liquidation_plan(self, owner: str, collateral: str) -> LiquidationPlan:
+        plan = self._lending.functions.liquidationPlan(
+            Web3.to_checksum_address(owner), Web3.to_checksum_address(collateral)
+        ).call()
+        return LiquidationPlan(
+            collateral_raw=plan[0],
+            debt_to_cover=plan[1],
+            principal_to_cover=plan[2],
+            fee_to_cover=plan[3],
+            target_settlement_leusd=plan[4],
+            full_liquidation=plan[5],
+            health_factor_after_bps=plan[6],
+        )
+
+    def get_token_state(
+        self, token: str, owner: str, spenders: tuple[str, ...] = ()
+    ) -> TokenState:
+        address = Web3.to_checksum_address(token)
+        account = Web3.to_checksum_address(owner)
+        contract = self.web3.eth.contract(address=address, abi=ERC20_ABI)
+        return TokenState(
+            address=address,
+            name=contract.functions.name().call(),
+            symbol=contract.functions.symbol().call(),
+            decimals=contract.functions.decimals().call(),
+            total_supply=contract.functions.totalSupply().call(),
+            balance=contract.functions.balanceOf(account).call(),
+            allowances={
+                Web3.to_checksum_address(spender): contract.functions.allowance(
+                    account, Web3.to_checksum_address(spender)
+                ).call()
+                for spender in spenders
+            },
+        )
+
+    def quote_psm_swap_in(self, usdg_assets: int) -> PsmQuote:
+        state = self.get_protocol_state()
+        decimals = self._lending.functions.usdgDecimals().call()
+        output = convert_decimals_exact(usdg_assets, decimals, 6)
+        if output is None:
+            return PsmQuote(usdg_assets, 0, False, "NON_EXACT_AMOUNT")
+        if state.paused:
+            return PsmQuote(usdg_assets, output, False, "PROTOCOL_PAUSED")
+        if state.psm_usdg_liabilities + output > state.psm_cap:
+            return PsmQuote(usdg_assets, output, False, "PSM_CAP")
+        return PsmQuote(usdg_assets, output, True)
+
+    def quote_psm_swap_out(self, leusd_amount: int) -> PsmQuote:
+        state = self.get_protocol_state()
+        decimals = self._lending.functions.usdgDecimals().call()
+        output = convert_decimals_exact(leusd_amount, 6, decimals)
+        if output is None:
+            return PsmQuote(leusd_amount, 0, False, "NON_EXACT_AMOUNT")
+        if state.paused:
+            return PsmQuote(leusd_amount, output, False, "PROTOCOL_PAUSED")
+        if state.bad_debt_leusd > 0:
+            return PsmQuote(leusd_amount, output, False, "BAD_DEBT")
+        if state.psm_idle_usdg_assets < output:
+            return PsmQuote(leusd_amount, output, False, "PSM_LIQUIDITY")
+        return PsmQuote(leusd_amount, output, True)
+
+    def quote_stake(self, amount: int) -> int:
+        if amount <= 0:
+            raise ValueError("amount must be greater than zero")
+        shares = self._staking.functions.totalPoolShares().call()
+        if shares == 0:
+            return amount
+        assets = self._staking.functions.stakeEntryAssets().call()
+        if assets == 0:
+            raise RuntimeError("staking pool has shares but no entry assets")
+        return int(amount * shares // assets)

lends_sdk-0.1.0/src/lends_sdk/math.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+BPS_DENOMINATOR = 10_000
+LEUSD_SCALE = 1_000_000
+PRICE_SCALE = 100_000_000
+SECONDS_PER_YEAR = 31_536_000
+
+
+def _power_of_ten(exponent: int) -> int:
+    if exponent < 0:
+        raise ValueError("decimal exponent cannot be negative")
+    return int(10**exponent)
+
+
+def pending_vault_fee(debt: int, fee_apr_bps: int, last_accrual_ts: int, timestamp: int) -> int:
+    if debt <= 0 or fee_apr_bps <= 0 or timestamp <= last_accrual_ts:
+        return 0
+    return debt * fee_apr_bps * (timestamp - last_accrual_ts) // (
+        BPS_DENOMINATOR * SECONDS_PER_YEAR
+    )
+
+
+def scale_price_to_e8(answer: int, decimals: int) -> int:
+    if answer <= 0:
+        raise ValueError("oracle answer must be positive")
+    if decimals < 0:
+        raise ValueError("oracle decimals cannot be negative")
+    if decimals == 8:
+        return answer
+    if decimals < 8:
+        return answer * _power_of_ten(8 - decimals)
+    return answer // _power_of_ten(decimals - 8)
+
+
+def collateral_value(collateral_raw: int, collateral_decimals: int, price_e8: int) -> int:
+    return (
+        collateral_raw
+        * price_e8
+        * LEUSD_SCALE
+        // _power_of_ten(collateral_decimals)
+        // PRICE_SCALE
+    )
+
+
+def max_borrow(value_leusd: int, borrow_ltv_bps: int) -> int:
+    return value_leusd * borrow_ltv_bps // BPS_DENOMINATOR
+
+
+def health_factor(value_leusd: int, debt_leusd: int, threshold_bps: int) -> int | None:
+    return None if debt_leusd == 0 else value_leusd * threshold_bps // debt_leusd
+
+
+def _ceil_div(numerator: int, denominator: int) -> int:
+    if denominator <= 0:
+        raise ValueError("denominator must be positive")
+    return (numerator + denominator - 1) // denominator
+
+
+def withdrawable_collateral(
+    collateral_raw: int,
+    debt_leusd: int,
+    collateral_decimals: int,
+    price_e8: int,
+    borrow_ltv_bps: int,
+) -> int:
+    if debt_leusd == 0:
+        return collateral_raw
+    if price_e8 <= 0 or borrow_ltv_bps <= 0:
+        return 0
+    required_value = _ceil_div(debt_leusd * BPS_DENOMINATOR, borrow_ltv_bps)
+    required_raw = _ceil_div(
+        required_value * _power_of_ten(collateral_decimals) * PRICE_SCALE,
+        price_e8 * LEUSD_SCALE,
+    )
+    return max(collateral_raw - required_raw, 0)
+
+
+def liquidation_price(
+    collateral_raw: int,
+    debt_leusd: int,
+    collateral_decimals: int,
+    liquidation_threshold_bps: int,
+) -> int | None:
+    if collateral_raw == 0 or debt_leusd == 0:
+        return None
+    return _ceil_div(
+        debt_leusd
+        * BPS_DENOMINATOR
+        * _power_of_ten(collateral_decimals)
+        * PRICE_SCALE,
+        collateral_raw * liquidation_threshold_bps * LEUSD_SCALE,
+    )
+
+
+def convert_decimals_exact(amount: int, from_decimals: int, to_decimals: int) -> int | None:
+    if amount < 0:
+        raise ValueError("amount cannot be negative")
+    if from_decimals == to_decimals:
+        return amount
+    if from_decimals < to_decimals:
+        return amount * _power_of_ten(to_decimals - from_decimals)
+    divisor = _power_of_ten(from_decimals - to_decimals)
+    return amount // divisor if amount % divisor == 0 else None

lends_sdk-0.1.0/src/lends_sdk/py.typed

@@ -0,0 +1 @@
+

lends_sdk-0.1.0/src/lends_sdk/transactions.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any
+
+from web3 import Web3
+
+from .abi import ERC20_ABI, LENDING_ABI, STAKING_ABI
+from .types import Deployment, PreparedTransaction
+
+
+def _positive(amount: int) -> int:
+    if amount <= 0:
+        raise ValueError("amount must be greater than zero")
+    return amount
+
+
+class LendsTransactions:
+    """Constructs calldata only. It never signs or broadcasts."""
+
+    def __init__(self, deployment: Deployment) -> None:
+        self.deployment = deployment
+        offline = Web3()
+        self._lending = offline.eth.contract(
+            address=Web3.to_checksum_address(deployment.lending), abi=LENDING_ABI
+        )
+        self._staking = offline.eth.contract(
+            address=Web3.to_checksum_address(deployment.sleusd), abi=STAKING_ABI
+        )
+
+    def _encode(self, contract: Any, function: str, args: list[Any]) -> PreparedTransaction:
+        return PreparedTransaction(
+            to=contract.address,
+            data=contract.encode_abi(function, args=args),
+            value=0,
+            chain_id=self.deployment.chain_id,
+        )
+
+    def approve(self, token: str, spender: str, amount: int) -> PreparedTransaction:
+        if amount < 0:
+            raise ValueError("amount cannot be negative")
+        contract = Web3().eth.contract(address=Web3.to_checksum_address(token), abi=ERC20_ABI)
+        return self._encode(contract, "approve", [Web3.to_checksum_address(spender), amount])
+
+    def approve_collateral(self, collateral: str, amount: int) -> PreparedTransaction:
+        return self.approve(collateral, self.deployment.lending, amount)
+
+    def approve_leusd_for_repay(self, amount: int) -> PreparedTransaction:
+        return self.approve(self.deployment.leusd, self.deployment.lending, amount)
+
+    def approve_usdg_for_psm(self, amount: int) -> PreparedTransaction:
+        return self.approve(self.deployment.usdg, self.deployment.lending, amount)
+
+    def approve_leusd_for_psm(self, amount: int) -> PreparedTransaction:
+        return self.approve(self.deployment.leusd, self.deployment.lending, amount)
+
+    def approve_leusd_for_staking(self, amount: int) -> PreparedTransaction:
+        return self.approve(self.deployment.leusd, self.deployment.sleusd, amount)
+
+    def deposit(self, collateral: str, amount: int) -> PreparedTransaction:
+        return self._encode(
+            self._lending, "deposit", [Web3.to_checksum_address(collateral), _positive(amount)]
+        )
+
+    def withdraw(self, collateral: str, amount: int) -> PreparedTransaction:
+        return self._encode(
+            self._lending, "withdraw", [Web3.to_checksum_address(collateral), _positive(amount)]
+        )
+
+    def borrow(self, collateral: str, amount: int) -> PreparedTransaction:
+        return self._encode(
+            self._lending, "borrow", [Web3.to_checksum_address(collateral), _positive(amount)]
+        )
+
+    def repay(self, collateral: str, max_amount: int) -> PreparedTransaction:
+        return self._encode(
+            self._lending, "repay", [Web3.to_checksum_address(collateral), _positive(max_amount)]
+        )
+
+    def accrue_fee(self, borrower: str, collateral: str) -> PreparedTransaction:
+        return self._encode(
+            self._lending,
+            "accrueFee",
+            [Web3.to_checksum_address(borrower), Web3.to_checksum_address(collateral)],
+        )
+
+    def psm_swap_in(self, usdg_assets: int) -> PreparedTransaction:
+        return self._encode(self._lending, "psmSwapIn", [_positive(usdg_assets)])
+
+    def psm_swap_out(self, leusd_amount: int) -> PreparedTransaction:
+        return self._encode(self._lending, "psmSwapOut", [_positive(leusd_amount)])
+
+    def stake(self, amount: int, min_shares_out: int) -> PreparedTransaction:
+        return self._encode(
+            self._staking, "stake", [_positive(amount), _positive(min_shares_out)]
+        )
+
+    def request_unstake(self, shares: int) -> PreparedTransaction:
+        return self._encode(self._staking, "requestUnstake", [_positive(shares)])
+
+    def complete_unstake(self, request_id: int) -> PreparedTransaction:
+        if request_id < 0:
+            raise ValueError("request_id cannot be negative")
+        return self._encode(self._staking, "completeUnstake", [request_id])
+
+    def cancel_expired_unstake(self, request_id: int) -> PreparedTransaction:
+        if request_id < 0:
+            raise ValueError("request_id cannot be negative")
+        return self._encode(self._staking, "cancelExpiredUnstake", [request_id])
+

lends_sdk-0.1.0/src/lends_sdk/types.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class Deployment:
+    chain_id: int
+    lending: str
+    leusd: str
+    sleusd: str
+    usdg: str
+    deployment_block: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedTransaction:
+    to: str
+    data: str
+    value: int
+    chain_id: int
+
+    def as_dict(self) -> dict[str, str | int]:
+        return {"to": self.to, "data": self.data, "value": self.value, "chainId": self.chain_id}
+
+
+@dataclass(frozen=True, slots=True)
+class ProtocolState:
+    block_number: int
+    block_timestamp: int
+    paused: bool
+    collateral_count: int
+    total_debt: int
+    total_uncollected_fees: int
+    realized_revenue_for_stakers: int
+    realized_revenue_for_protocol: int
+    insurance_fund_leusd: int
+    bad_debt_leusd: int
+    protocol_debt_cap: int
+    stability_fee_apr_bps: int
+    insurance_target_bps: int
+    insurance_fee_share_bps: int
+    psm_usdg_liabilities: int
+    psm_leusd_supply: int
+    psm_idle_usdg_assets: int
+    psm_morpho_deployed_usdg_assets: int
+    psm_morpho_shares: int
+    psm_cap: int
+    staker_target_revenue_due: int
+    staker_target_last_accrual_ts: int
+    staker_target_apr_bps: int
+    staking_capacity_leusd: int
+    pending_liquidation_principal: int
+    pending_liquidation_fees: int
+
+
+@dataclass(frozen=True, slots=True)
+class MarketState:
+    address: str
+    enabled: bool
+    token: str
+    price_feed: str
+    symbol: str
+    collateral_decimals: int
+    borrow_ltv_bps: int
+    liquidation_threshold_bps: int
+    liquidation_penalty_bps: int
+    close_factor_bps: int
+    per_vault_debt_cap: int
+    collateral_debt_cap: int
+    deposit_cap_raw: int
+    total_debt: int
+    total_deposits_raw: int
+    deposits_paused: bool
+    borrows_paused: bool
+    withdraws_paused: bool
+    market_paused: bool
+    oracle_price_e8: int
+    oracle_updated_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class PositionState:
+    owner: str
+    collateral: str
+    collateral_raw: int
+    collateral_value_leusd: int
+    principal_debt: int
+    accrued_fee: int
+    pending_fee: int
+    debt: int
+    last_accrual_ts: int
+    health_factor_bps: int | None
+    borrow_capacity: int
+    available_to_borrow: int
+    withdrawable_collateral_raw: int
+    liquidation_price_e8: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class StakingState:
+    block_number: int
+    block_timestamp: int
+    paused: bool
+    total_supply: int
+    total_pool_shares: int
+    staking_vault_leusd: int
+    accounted_assets: int
+    claimable_assets: int
+    stake_entry_assets: int
+    total_managed_assets: int
+    realized_loss_leusd: int
+    unvested_revenue: int
+    reserved_pending_claims: int
+    vesting_start_ts: int
+    vesting_end_ts: int
+    last_vesting_sync_ts: int
+    cooldown_seconds: int
+    claim_window_seconds: int
+    min_initial_stake_leusd: int
+    revenue_vesting_seconds: int
+    next_pending_withdrawal_id: int
+    capacity_leusd: int
+
+
+@dataclass(frozen=True, slots=True)
+class UnstakeRequest:
+    id: int
+    owner: str
+    shares: int
+    request_ts: int
+    claim_deadline_ts: int
+    completed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class LiquidationPlan:
+    collateral_raw: int
+    debt_to_cover: int
+    principal_to_cover: int
+    fee_to_cover: int
+    target_settlement_leusd: int
+    full_liquidation: bool
+    health_factor_after_bps: int
+
+
+@dataclass(frozen=True, slots=True)
+class TokenState:
+    address: str
+    name: str
+    symbol: str
+    decimals: int
+    total_supply: int
+    balance: int
+    allowances: dict[str, int]
+
+
+@dataclass(frozen=True, slots=True)
+class PsmQuote:
+    input_amount: int
+    output_amount: int
+    available: bool
+    reason: Literal[
+        "PROTOCOL_PAUSED", "PSM_CAP", "BAD_DEBT", "PSM_LIQUIDITY", "NON_EXACT_AMOUNT"
+    ] | None = None

lends_sdk-0.1.0/tests/test_sdk.py

@@ -0,0 +1,37 @@
+import unittest
+
+from lends_sdk import (
+    ROBINHOOD_MAINNET,
+    LendsTransactions,
+    collateral_value,
+    pending_vault_fee,
+)
+
+
+class TransactionTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.txs = LendsTransactions(ROBINHOOD_MAINNET)
+        self.collateral = "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC"
+
+    def test_deposit_calldata(self) -> None:
+        tx = self.txs.deposit(self.collateral, 10**18)
+        self.assertEqual(tx.to, ROBINHOOD_MAINNET.lending)
+        self.assertEqual(tx.value, 0)
+        self.assertEqual(tx.data[:10], "0x47e7ef24")
+
+    def test_zero_borrow_rejected(self) -> None:
+        with self.assertRaisesRegex(ValueError, "greater than zero"):
+            self.txs.borrow(self.collateral, 0)
+
+
+class MathTests(unittest.TestCase):
+    def test_collateral_scaling(self) -> None:
+        self.assertEqual(collateral_value(2 * 10**18, 18, 125 * 10**8), 250 * 10**6)
+
+    def test_fee_floor_rounding(self) -> None:
+        self.assertEqual(pending_vault_fee(1_000 * 10**6, 150, 0, 31_536_000), 15 * 10**6)
+
+
+if __name__ == "__main__":
+    unittest.main()
+