Skip to content

Reintroduce contract summary and call flow sections #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ghacct930 merged 1 commit into from
Jun 1, 2026
Merged

Reintroduce contract summary and call flow sections #59

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 39 additions & 38 deletions docs/developers/contracts_overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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.