From f6080103760986c5a39b1c4b941d0a1e84737f95 Mon Sep 17 00:00:00 2001 From: justlend_dev <116065540+hyf1888@users.noreply.github.com> Date: Thu, 28 May 2026 17:01:48 +0800 Subject: [PATCH] Reintroduce contract summary and call flow sections Restored contract summary table and inter-contract call flow sections in the documentation. --- docs/developers/contracts_overview.md | 77 ++++++++++++++------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/docs/developers/contracts_overview.md b/docs/developers/contracts_overview.md index 2a9395d..3298c13 100644 --- a/docs/developers/contracts_overview.md +++ b/docs/developers/contracts_overview.md @@ -21,44 +21,6 @@ JustLend DAO Protocol contracts are divided in these repositories: * **Staked TRX:** the contracts utilized for staking TRX to earn high rewards. * **Energy Rental:** contracts enable users to rent energy anytime with a low price. -## Contract summary table (machine-readable) - -Single row per contract. Use this when integrating; treat the prose sections below as commentary. - -| Component | Contract | Mainnet address (Base58) | Upgradeable? | Proxy mode | Key functions | ABI | Doc | -|-----------|----------|--------------------------|--------------|------------|---------------|-----|-----| -| Comptroller | `Unitroller` (entrypoint) | [`TGjYzgCyPobsNS9n6WcbdLVR9dH7mWqFx7`](https://tronscan.org/#/contract/TGjYzgCyPobsNS9n6WcbdLVR9dH7mWqFx7) | **Yes** (impl behind proxy) | Compound `Unitroller` (`_setPendingImplementation` + `_acceptImplementation`) | `enterMarkets`, `exitMarket`, `getAccountLiquidity`, `markets`, `closeFactorMantissa`, `liquidationIncentiveMantissa` | [`comptroller.json`](abis/comptroller.json) | [Comptroller](supply_and_borrow_market/comptroller.md) | -| Comptroller | `Comptroller` (implementation) | [`TB23wYojvAsSx6gR8ebHiBqwSeABiBMPAr`](https://tronscan.org/#/contract/TB23wYojvAsSx6gR8ebHiBqwSeABiBMPAr) | Replaced via `Unitroller` | Implementation only | — (delegated through `Unitroller`) | [`comptroller.json`](abis/comptroller.json) | [Comptroller](supply_and_borrow_market/comptroller.md) | -| SBM (TRX market) | `CErc20Delegator` (jTRX) | [`TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP`](https://tronscan.org/#/contract/TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP) | **Yes** (impl behind delegator) | Compound `CErc20Delegator` (`_setImplementation`) | `mint()` (payable, TRX), `borrow`, `repayBorrow` (payable), `redeem`, `redeemUnderlying`, `liquidateBorrow` (payable) | [`jtoken.json`](abis/jtoken.json) (plus [`jtrx-mint.json`](abis/jtrx-mint.json), [`jtrx-repay.json`](abis/jtrx-repay.json) for TRX-specific payable variants) | [SBM](supply_and_borrow_market/sbm.md) | -| SBM (TRC20 markets) | `CErc20Delegator` (per market, 22 instances) | See [`apis.md §2`](apis.md#2-jtoken-address-reference) | **Yes** per market | Compound `CErc20Delegator` (`_setImplementation`) | `mint(uint)`, `borrow`, `repayBorrow(uint)`, `redeem`, `redeemUnderlying`, `liquidateBorrow(address, uint, address)` | [`jtoken.json`](abis/jtoken.json) | [SBM](supply_and_borrow_market/sbm.md), [Deployed Contracts](deployed_contracts.md) | -| Interest Rate Model | `WhitePaperInterestRateModel` (linear) | Per market — see [Deployed Contracts](deployed_contracts.md) | **No** (immutable per deployment; new model contract per parameter change) | None | `getBorrowRate(cash, borrows, reserves)`, `getSupplyRate(cash, borrows, reserves, reserveFactorMantissa)` | [`interest-rate-model.json`](abis/interest-rate-model.json) | [Interest Rate Model](supply_and_borrow_market/interest_rate_model.md) | -| Interest Rate Model | `JumpRateModelV2` (kinked) | Per market — see [Deployed Contracts](deployed_contracts.md) | **No** (immutable per deployment; new model contract per parameter change) | None | `getBorrowRate`, `getSupplyRate`, `multiplierPerBlock`, `jumpMultiplierPerBlock`, `kink`, `baseRatePerBlock` | [`interest-rate-model.json`](abis/interest-rate-model.json) | [Interest Rate Model](supply_and_borrow_market/interest_rate_model.md) | -| Price Oracle | `PriceOracleProxy` (entrypoint) | [`TCKp2AzuhzV4B4Ahx1ej4mvQgHZ1kH7F7k`](https://tronscan.org/#/contract/TCKp2AzuhzV4B4Ahx1ej4mvQgHZ1kH7F7k) | **Yes** (impl behind proxy) | Address-only proxy (governance updates implementation pointer) | `getUnderlyingPrice(cToken)` | [`price-oracle.json`](abis/price-oracle.json) | [Price Oracle](supply_and_borrow_market/price_oracle.md) | -| Price Oracle | `SimplePriceOracle` (implementation) | [`TMiNCmvD3zdsv6mk7niBU6NPBzVNjYMQTV`](https://tronscan.org/#/contract/TMiNCmvD3zdsv6mk7niBU6NPBzVNjYMQTV) | Replaced via proxy | Implementation only | `getPrice`, `assetPrices`, `setPrice` (poster-only) | [`price-oracle.json`](abis/price-oracle.json) | [Price Oracle](supply_and_borrow_market/price_oracle.md) | -| Governance | `GovernorBravoDelegator` (entrypoint) | [`TEqiF5JbhDPD77yjEfnEMncGRZNDt2uogD`](https://tronscan.org/#/contract/TEqiF5JbhDPD77yjEfnEMncGRZNDt2uogD) | **Yes** (impl behind delegator) | Compound `GovernorBravoDelegator` (`_setImplementation`) | `propose`, `queue`, `execute`, `cancel`, `castVote`, `castVoteWithReason`, `state`, `deposit` | [`governor-alpha.json`](abis/governor-alpha.json) (Governor ABI; the WJST escrow is `wjst.json`) | [Governance](supply_and_borrow_market/governance.md) | -| Governance | `GovernorBravoDelegate` (implementation) | [`TCiQTkxhzwSeXhRsNdHCvrxHRAvpjQn5Dt`](https://tronscan.org/#/contract/TCiQTkxhzwSeXhRsNdHCvrxHRAvpjQn5Dt) | Replaced via delegator | Implementation only | — (delegated) | [`governor-alpha.json`](abis/governor-alpha.json) | [Governance](supply_and_borrow_market/governance.md) | -| Governance | `Timelock` (executor) | [`TRWNvb15NmfNKNLhQpxefFz7cNjrYjEw7x`](https://tronscan.org/#/contract/TRWNvb15NmfNKNLhQpxefFz7cNjrYjEw7x) | **No** (constructor-fixed admin and delay) | None | `queueTransaction`, `executeTransaction`, `cancelTransaction` | — | [Governance](supply_and_borrow_market/governance.md) | -| Governance | `JST` (TRC20 governance token) | [`TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9`](https://tronscan.org/#/contract/TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9) | **No** (standard TRC20) | None | `transfer`, `approve`, `balanceOf` | [`trc20.json`](abis/trc20.json) | [Tokenomics](../governance/tokenomics.md) | -| Governance | `WJST` (voting-power escrow) | See [Deployed Contracts](deployed_contracts.md) | **No** | None | `deposit`, `withdraw`, vote-power tracking | [`wjst.json`](abis/wjst.json) | [Governance](supply_and_borrow_market/governance.md) | -| Staked TRX | `sTRX` (liquid-staking contract) | [`TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5`](https://tronscan.org/#/contract/TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5) | **No** (constructor-fixed; new contract on protocol upgrade) | None | `deposit()` (payable), `withdraw`, `withdrawExact`, `claim`, `claimAll`, `exchangeRate`, `balanceInTrx` | [`strx.json`](abis/strx.json) | [Staked TRX](staked_trx.md) | -| Energy Rental | `EnergyRental` market contract | [`TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd`](https://tronscan.org/#/contract/TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd) | **No** | None | `rentResource` (payable), `returnResource`, `returnResourceByReceiver`, `liquidate`, `getRentInfo`, `_rentalRate` | [`energy-market.json`](abis/energy-market.json), rate model in [`energy-rate-model.json`](abis/energy-rate-model.json) | [Energy Rental](energy_rental.md) | - -**Inter-contract call flow (most common write path — supply + borrow):** - -``` -User EOA - └─► CErc20Delegator (jToken) - ├─ delegatecall ► CErc20Delegate (mint/borrow logic) - ├─ staticcall ► PriceOracleProxy.getUnderlyingPrice() - ├─ call ► InterestRateModel.getBorrowRate() / getSupplyRate() - └─ call ► Unitroller (Comptroller proxy) - └─ delegatecall ► Comptroller.mintAllowed / borrowAllowed -``` - -`enterMarkets` is a precondition for any supplied asset to count as collateral — it is called directly on the `Unitroller` entrypoint, not on the jToken. - -**Version evolution (`JumpRateModelV2`):** each market's rate model is its own deployed contract instance (immutable). Updating parameters (kink, multipliers, baseRate) means deploying a fresh `JumpRateModelV2` contract and calling `_setInterestRateModel` on the jToken via Governance. Past instances remain on chain but unused. - ## **Core Contracts** There are 5 categories of core repository contracts (the prose below mirrors the summary table — refer to the table for addresses, function signatures, and ABI links): @@ -99,3 +61,42 @@ There are 5 categories of core repository contracts (the prose below mirrors the ## **Energy Rental** `Energy Rental:` contracts enable users to rent energy anytime with a low price. + + +## Contract summary table (machine-readable) + +Single row per contract. Use this when integrating; treat the prose sections below as commentary. + +| Component | Contract | Mainnet address (Base58) | Upgradeable? | Proxy mode | Key functions | ABI | Doc | +|-----------|----------|--------------------------|--------------|------------|---------------|-----|-----| +| Comptroller | `Unitroller` (entrypoint) | [`TGjYzgCyPobsNS9n6WcbdLVR9dH7mWqFx7`](https://tronscan.org/#/contract/TGjYzgCyPobsNS9n6WcbdLVR9dH7mWqFx7) | **Yes** (impl behind proxy) | Compound `Unitroller` (`_setPendingImplementation` + `_acceptImplementation`) | `enterMarkets`, `exitMarket`, `getAccountLiquidity`, `markets`, `closeFactorMantissa`, `liquidationIncentiveMantissa` | [`comptroller.json`](abis/comptroller.json) | [Comptroller](supply_and_borrow_market/comptroller.md) | +| Comptroller | `Comptroller` (implementation) | [`TB23wYojvAsSx6gR8ebHiBqwSeABiBMPAr`](https://tronscan.org/#/contract/TB23wYojvAsSx6gR8ebHiBqwSeABiBMPAr) | Replaced via `Unitroller` | Implementation only | — (delegated through `Unitroller`) | [`comptroller.json`](abis/comptroller.json) | [Comptroller](supply_and_borrow_market/comptroller.md) | +| SBM (TRX market) | `CErc20Delegator` (jTRX) | [`TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP`](https://tronscan.org/#/contract/TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP) | **Yes** (impl behind delegator) | Compound `CErc20Delegator` (`_setImplementation`) | `mint()` (payable, TRX), `borrow`, `repayBorrow` (payable), `redeem`, `redeemUnderlying`, `liquidateBorrow` (payable) | [`jtoken.json`](abis/jtoken.json) (plus [`jtrx-mint.json`](abis/jtrx-mint.json), [`jtrx-repay.json`](abis/jtrx-repay.json) for TRX-specific payable variants) | [SBM](supply_and_borrow_market/sbm.md) | +| SBM (TRC20 markets) | `CErc20Delegator` (per market, 22 instances) | See [`apis.md §2`](apis.md#2-jtoken-address-reference) | **Yes** per market | Compound `CErc20Delegator` (`_setImplementation`) | `mint(uint)`, `borrow`, `repayBorrow(uint)`, `redeem`, `redeemUnderlying`, `liquidateBorrow(address, uint, address)` | [`jtoken.json`](abis/jtoken.json) | [SBM](supply_and_borrow_market/sbm.md), [Deployed Contracts](deployed_contracts.md) | +| Interest Rate Model | `WhitePaperInterestRateModel` (linear) | Per market — see [Deployed Contracts](deployed_contracts.md) | **No** (immutable per deployment; new model contract per parameter change) | None | `getBorrowRate(cash, borrows, reserves)`, `getSupplyRate(cash, borrows, reserves, reserveFactorMantissa)` | [`interest-rate-model.json`](abis/interest-rate-model.json) | [Interest Rate Model](supply_and_borrow_market/interest_rate_model.md) | +| Interest Rate Model | `JumpRateModelV2` (kinked) | Per market — see [Deployed Contracts](deployed_contracts.md) | **No** (immutable per deployment; new model contract per parameter change) | None | `getBorrowRate`, `getSupplyRate`, `multiplierPerBlock`, `jumpMultiplierPerBlock`, `kink`, `baseRatePerBlock` | [`interest-rate-model.json`](abis/interest-rate-model.json) | [Interest Rate Model](supply_and_borrow_market/interest_rate_model.md) | +| Price Oracle | `PriceOracleProxy` (entrypoint) | [`TCKp2AzuhzV4B4Ahx1ej4mvQgHZ1kH7F7k`](https://tronscan.org/#/contract/TCKp2AzuhzV4B4Ahx1ej4mvQgHZ1kH7F7k) | **Yes** (impl behind proxy) | Address-only proxy (governance updates implementation pointer) | `getUnderlyingPrice(cToken)` | [`price-oracle.json`](abis/price-oracle.json) | [Price Oracle](supply_and_borrow_market/price_oracle.md) | +| Price Oracle | `SimplePriceOracle` (implementation) | [`TMiNCmvD3zdsv6mk7niBU6NPBzVNjYMQTV`](https://tronscan.org/#/contract/TMiNCmvD3zdsv6mk7niBU6NPBzVNjYMQTV) | Replaced via proxy | Implementation only | `getPrice`, `assetPrices`, `setPrice` (poster-only) | [`price-oracle.json`](abis/price-oracle.json) | [Price Oracle](supply_and_borrow_market/price_oracle.md) | +| Governance | `GovernorBravoDelegator` (entrypoint) | [`TEqiF5JbhDPD77yjEfnEMncGRZNDt2uogD`](https://tronscan.org/#/contract/TEqiF5JbhDPD77yjEfnEMncGRZNDt2uogD) | **Yes** (impl behind delegator) | Compound `GovernorBravoDelegator` (`_setImplementation`) | `propose`, `queue`, `execute`, `cancel`, `castVote`, `castVoteWithReason`, `state`, `deposit` | [`governor-alpha.json`](abis/governor-alpha.json) (Governor ABI; the WJST escrow is `wjst.json`) | [Governance](supply_and_borrow_market/governance.md) | +| Governance | `GovernorBravoDelegate` (implementation) | [`TCiQTkxhzwSeXhRsNdHCvrxHRAvpjQn5Dt`](https://tronscan.org/#/contract/TCiQTkxhzwSeXhRsNdHCvrxHRAvpjQn5Dt) | Replaced via delegator | Implementation only | — (delegated) | [`governor-alpha.json`](abis/governor-alpha.json) | [Governance](supply_and_borrow_market/governance.md) | +| Governance | `Timelock` (executor) | [`TRWNvb15NmfNKNLhQpxefFz7cNjrYjEw7x`](https://tronscan.org/#/contract/TRWNvb15NmfNKNLhQpxefFz7cNjrYjEw7x) | **No** (constructor-fixed admin and delay) | None | `queueTransaction`, `executeTransaction`, `cancelTransaction` | — | [Governance](supply_and_borrow_market/governance.md) | +| Governance | `JST` (TRC20 governance token) | [`TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9`](https://tronscan.org/#/contract/TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9) | **No** (standard TRC20) | None | `transfer`, `approve`, `balanceOf` | [`trc20.json`](abis/trc20.json) | [Tokenomics](../governance/tokenomics.md) | +| Governance | `WJST` (voting-power escrow) | See [Deployed Contracts](deployed_contracts.md) | **No** | None | `deposit`, `withdraw`, vote-power tracking | [`wjst.json`](abis/wjst.json) | [Governance](supply_and_borrow_market/governance.md) | +| Staked TRX | `sTRX` (liquid-staking contract) | [`TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5`](https://tronscan.org/#/contract/TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5) | **No** (constructor-fixed; new contract on protocol upgrade) | None | `deposit()` (payable), `withdraw`, `withdrawExact`, `claim`, `claimAll`, `exchangeRate`, `balanceInTrx` | [`strx.json`](abis/strx.json) | [Staked TRX](staked_trx.md) | +| Energy Rental | `EnergyRental` market contract | [`TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd`](https://tronscan.org/#/contract/TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd) | **No** | None | `rentResource` (payable), `returnResource`, `returnResourceByReceiver`, `liquidate`, `getRentInfo`, `_rentalRate` | [`energy-market.json`](abis/energy-market.json), rate model in [`energy-rate-model.json`](abis/energy-rate-model.json) | [Energy Rental](energy_rental.md) | + +**Inter-contract call flow (most common write path — supply + borrow):** + +``` +User EOA + └─► CErc20Delegator (jToken) + ├─ delegatecall ► CErc20Delegate (mint/borrow logic) + ├─ staticcall ► PriceOracleProxy.getUnderlyingPrice() + ├─ call ► InterestRateModel.getBorrowRate() / getSupplyRate() + └─ call ► Unitroller (Comptroller proxy) + └─ delegatecall ► Comptroller.mintAllowed / borrowAllowed +``` + +`enterMarkets` is a precondition for any supplied asset to count as collateral — it is called directly on the `Unitroller` entrypoint, not on the jToken. + +**Version evolution (`JumpRateModelV2`):** each market's rate model is its own deployed contract instance (immutable). Updating parameters (kink, multipliers, baseRate) means deploying a fresh `JumpRateModelV2` contract and calling `_setInterestRateModel` on the jToken via Governance. Past instances remain on chain but unused.