> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jup.ag/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Architecture

> Jupiter Lend architecture: how Liquidity, Lending (Earn), and Vaults (Borrow) interact.

Jupiter Lend is built on three core programs: **Liquidity** (the shared lending engine), **Lending** (Earn), and **Vaults** (Borrow). Lending and Vaults do not hold tokens directly. They CPI into Liquidity, which holds all underlying assets and tracks supply and borrow positions.

## Three-program design

| Program | Purpose | Program ID |
| - | - | - |
| Liquidity | Core layer: token vaults, exchange prices, utilisation, rates | `jupeiUmn818Jg1ekPURTpr4mFo29p46vygyykFJ3wZC` |
| Lending | Earn: deposit assets, mint jlTokens, supply into Liquidity | `jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9` |
| Vaults | Borrow: collateralize, borrow, liquidate, supply/borrow via Liquidity | `jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi` |

![Core architecture: Users → Lending (Earn) and Vaults (Borrow) → CPI → Operate → Liquidity Layer (Core)](https://mintcdn.com/jupiter/PZgF9iOWX2MLsK4u/static/images/core-architecture.png?fit=max\&auto=format\&n=PZgF9iOWX2MLsK4u\&q=85\&s=5016332682ec3e6fae00a4020ec649b5)

***

## Liquidity (core layer)

Liquidity serves as the foundational layer, owning all token vaults and custodying every deposited and borrowed asset. User-facing protocols never interact with tokens directly; they always make CPI calls into Liquidity to handle supply and borrow operations.

### Key state

| Account | Purpose |
| - | - |
| TokenReserve | Per-mint: vault, exchange prices, totals, utilisation, rate config |
| UserSupplyPosition | Per (mint, protocol): supply amount, withdrawal limit, status |
| UserBorrowPosition | Per (mint, protocol): borrow amount, debt ceiling, status |
| RateModel | Interest rate curve driven by utilisation |

### Protocol registration

Protocols (Lending, Vaults) must be registered via `init_new_protocol(supply_mint, borrow_mint, protocol)`:

* **Lending:** supply mint only (Earn supplies into Liquidity, no borrow)
* **Vaults:** supply mint (collateral) and borrow mint (debt)

### Operate flow

1. **pre\_operate(mint):** marks the interacting protocol and timestamp on `TokenReserve`
2. Caller moves tokens into the Liquidity vault (via SPL transfer)
3. **operate(supply\_amount, borrow\_amount, withdraw\_to, borrow\_to, transfer\_type):** updates exchange prices, UserSupplyPosition/UserBorrowPosition, TokenReserve totals, and performs transfers

Exchange prices and rates are updated during `operate`, so interest accrues on every interaction.

***

## Lending (Earn)

Earn lets users deposit assets and receive jlTokens (shares). Deposits are supplied into Liquidity, and jlTokens represent a share of the pool with accrued interest and rewards.

### Key state

| Account | Purpose |
| - | - |
| LendingAdmin | Factory: authority, `liquidity_program`, rebalancer, auths |
| Lending | Per-mint pool: mint, `jl_token_mint`, `token_reserves_liquidity`, `supply_position_on_liquidity`, exchange prices |

### User flow

* **Deposit:** User transfers tokens → Lending CPIs Liquidity `pre_operate` + `operate(supply)` → mints jlTokens
* **Withdraw/Redeem:** Burns jlTokens → CPIs Liquidity `operate(withdraw)` → user receives underlying

The protocol signer for Liquidity CPI is the **Lending PDA** (not the user). Each Lending pool has a single `UserSupplyPosition` on Liquidity for that mint. The rewards rate model (separate program) adjusts the jlToken exchange price to include rewards on top of base yield.

### CPI summary

| Caller | Signer | Supply position | Borrow position |
| - | - | - | - |
| Lending | Lending PDA | Lending PDA (1 per mint) | None |

***

## Vaults (Borrow)

Borrow vaults are collateralized lending markets. Each vault has a **supply token** (collateral) and a **borrow token** (debt). Users deposit collateral, borrow against it, and can be liquidated if collateral falls below the liquidation threshold. Positions are represented as NFTs.

### Key state

| Account | Purpose |
| - | - |
| VaultConfig | Params: supply\_token, borrow\_token, oracle, collateral\_factor, liquidation\_threshold, rebalancer |
| VaultState | Runtime: total\_supply, total\_borrow, topmost\_tick, absorbed debt/collateral |
| Position | User position: vault\_id, tick, supply\_amount, debt, liquidation status |
| Branch | Liquidation structure: minima tick, debt factor, status |
| Tick | Price-ratio ticks for collateralization |

### Tick-based pricing

Vaults use **tick-based** pricing: collateralization is computed from a price-ratio tick rather than a simple LTV. Collateral factor is derived from tick ratio. Branches track liquidation state and merge positions when liquidated.

### User flow

* **init\_position:** create Position + position mint NFT
* **operate:** deposit/withdraw collateral, borrow/repay debt
* **liquidate:** liquidate undercollateralized positions
* **rebalance:** rebalancer supplies/borrows on Liquidity to match vault demand

The protocol signer for Liquidity CPI is the **VaultConfig PDA**. Each vault has both a `UserSupplyPosition` (collateral) and a `UserBorrowPosition` (debt) on Liquidity. The Oracle program provides prices for collateral valuation and liquidation checks.

### CPI summary

| Caller | Signer | Supply position | Borrow position |
| - | - | - | - |
| Vaults | VaultConfig PDA | VaultConfig PDA | VaultConfig PDA |

***

## Shared data flow

Both Lending and Vaults share the same Liquidity layer:

| Shared account | Used by | Role |
| - | - | - |
| TokenReserve | Both | Aggregated supply/borrow per mint |
| UserSupplyPosition | Both | Per-protocol supply |
| UserBorrowPosition | Vaults | Per-protocol borrow |
| Vault (ATA) | Both | Liquidity holds all tokens |
| RateModel | Both | Interest rate parameters |

### Deposit (Earn)

```
User → Lending.deposit() → transfer tokens to Liquidity vault
                         → pre_operate (Lending PDA)
                         → operate(supply, borrow=0)
                         → mint jlTokens
```

### Borrow (Vaults)

```
User → Vaults.operate() → transfer collateral to vault
                        → pre_operate (VaultConfig PDA)
                        → operate(supply=collateral, borrow=debt)
                        → update Position / Branch / Tick
```

***

## Dependency graph

| Program | Depends on |
| - | - |
| Lending | Liquidity (CPI), Lending Rewards Rate Model |
| Vaults | Liquidity (CPI), Oracle |
| Liquidity | Standalone |
| Oracle | Standalone |

***

## Related docs

* [Unifying Liquidity](https://developers.jup.ag/docs/lend/liquidity/index.md): Liquidity layer overview and key features
* [Earn Overview](https://developers.jup.ag/docs/lend/earn/index.md): deposit/withdraw mechanics
* [Borrow Overview](https://developers.jup.ag/docs/lend/borrow/index.md): vaults, positions, liquidations
* [Liquidity analytics](https://developers.jup.ag/docs/lend/liquidity/analytics.md): market data, utilisation, exchange prices
* [Oracles](https://developers.jup.ag/docs/lend/oracles.md): price feeds for vaults
* [Program addresses](https://developers.jup.ag/docs/lend/program-addresses.md): program IDs and IDL


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.