The Ripe Finance architecture is built around modular departments and registry systems, with Hq.vy (Headquarters) as the protocol's central entry point. The Headquarters contract serves as the main controller of the protocol, managing interactions with the RIPE and GREEN tokens, coordinating governance through BoardRoom.vy, and linking to Departments.vy to manage specialized contracts for deposits, loans, liquidation, rewards, and reserves.
Tokens: The RIPE and GREEN ERC20 tokens are central to protocol functions, with Hq possessing minting powers for GREEN to support various protocol mechanisms.
Core Departments: Specialized contracts within Departments.vy manage essential functions, including deposits, loans, risk/liquidation, rewards, reserves, and other critical services.
Registries: Registry contracts such as PriceDesk.vy, RoloDex.vy, HumanResources.vy, and StratMap.vy store their data in PhoneBook.vy, which serves as a centralized abstraction. This setup allows for streamlined management and easy interaction across departments by accessing registry information through a unified interface.
Technical Overview
The Ripe Finance protocol implements a modular structure, with specific contracts for different core components. These contracts are divided into Config, Data, Gov, and Main Logic categories to ensure clear separation of concerns.
Main Logic Contracts
Purpose:
Core functionality, including credit issuance, asset management, and reward distribution.
Examples:
CreditUnion.vy and CreditBorrow.vy: Handle credit operations.
JuiceStand.vy: Manages reward distribution.
AuctionHouse.vy: Facilitates liquidations.
Config Contracts
Purpose:
Store adjustable protocol parameters, allowing the governance to modify settings without redeployment.
Examples:
CreditConfig.vy: Manages credit-specific parameters.
CommunalDepositConfig.vy: Handles communal deposit configurations.
JuiceStandConfig.vy: Oversees loyalty score configurations.
EndaoConfig.vy: Controls Endaoment strategy parameters.
TreasuryConfig.vy: Configures treasury operations.
Data Contracts
Purpose:
Serve as the storage layer, holding essential user and protocol data. This separation allows for data stability and integrity.
Examples:
CreditData.vy: Stores user-specific loan and credit data.
LedgerData.vy: Holds transaction and balance records.
CommunalData.vy: Contains strategy configuration details.
Other examples include TreasuryData.vy for treasury details and JuiceStandData.vy for participation metrics.
Gov Contracts
Purpose:
Enable decentralized governance, allowing the community to propose protocol parameter changes.
Examples:
CreditGov.vy, LedgerGov.vy, JuiceStandGov.vy, AuctionHouseGovA.vy: Manage department-specific proposals.
PropHouse.vy: Coordinates proposal submissions and governance updates.
Tokens
The Ripe Finance protocol includes two main ERC20 tokens: RIPE and GREEN. These tokens play crucial roles in the ecosystem, supporting governance, rewards, and financial operations within the protocol. Below is an overview of each token and its functionalities.
RIPE Token
RIPE is the native governance token of the Ripe Finance ecosystem, granting token holders the ability to participate in the governance of the protocol and influence key decisions.
Contract: RipeErc20.vy
Purpose: Primarily used for governance and protocol ownership representation.
Key Functions
Governance Participation: RIPE holders can stake their tokens in the Ripe Governance Strategy, allowing them to accrue governance points that influence protocol decision-making.
Delegation: Token holders may delegate their voting power to other users, allowing community-driven representation within the governance framework.
GREEN Token
GREEN is a synthetic stablecoin within the Ripe Finance ecosystem, minted when users borrow against their deposited assets.
Contract: GreenErc20.vy
Purpose: Acts as a stablecoin within the protocol, providing a stable unit of account for borrowing, rewards, and collateral.
Key Functions
Borrowing: GREEN is minted whenever users take out a loan against their deposited assets, providing them with liquidity within the Ripe Finance ecosystem.
Stability Mechanism: GREEN is used in the Stability Pool to protect the protocol during liquidations. Assets held here provide the first line of defense, stabilizing the protocol during market fluctuations.
Collateral and Rewards: GREEN can be used as a collateral asset within the protocol, and it is also distributed as rewards for users who participate in protocol activities such as staking and depositing assets.
Swap Assist and Yield: Users can swap their stable assets (e.g., USDC) for GREEN via the Swap Assist feature, which aids in protocol liquidity.
ERC20 Token Features Implemented
Both RIPE and GREEN tokens implement standard ERC20 functionality, with several additional features tailored to their roles within the protocol.
Standard ERC20 Features
Balance Tracking (balanceOf): Tracks each address's token balance, enabling users to query their current holdings.
Transfer (transfer): Standard ERC20 transfer function allows direct transfers of tokens between user accounts. It deducts the token amount from the sender’s balance and credits it to the recipient’s balance.
Approval and Allowance (approve and allowance): These functions allow users to set spending limits for third-party accounts, typically used for staking or borrowing activities where the protocol requires authorization to spend tokens on behalf of the user.
TransferFrom (transferFrom): Enables the transfer of tokens from a user’s address by an approved third party, supporting features like delegated staking and yield distribution.
Minting Control
Only Hq.vy has minting rights for both tokens, ensuring centralized control over token issuance. Minting permissions are verified with BoardRoom.vy before new tokens are issued, providing additional security and compliance with protocol governance.
Departments
Departments are where all the core logic and functionality of the protocol live. As with a giant bank or corporation, there are different departments for different functions/purposes. Each department is relatively independent from the other departments, but sometimes they still communicate with each other (mostly read information, but sometimes write).
Teller
Manages deposits and withdrawals for both fungible tokens and NFTs, ensuring seamless asset transfers to and from their designated strategies within the protocol.
Teller.vy: Core contract for managing deposits and withdrawals.
TellerDeposit.vy: Handles logic for depositing fungible tokens into the protocol.
TellerWithdraw.vy: Handles logic for withdrawing fungible tokens from the protocol.
TellerDepositNFT.vy: Specialized contract for depositing NFTs into the protocol.
TellerWithdrawNFT.vy: Specialized contract for withdrawing NFTs.
Communal
This set of contracts stores asset configuration, debt terms, limits, and all related to deposits and assets.
Communal.vy: Entry point for communal functionality.
CommunalDebtConfig.vy: Manages configuration related to debt settings.
CommunalDepositConfig.vy: Configuration contract for deposits and asset limits.
CommunalOtherConfig.vy: Handles additional communal configuration needs.
CommunalData.vy: Stores configuration data for strategies.
Credit Union
This department handles all borrowing (credit/loans) within Ripe.
CreditUnion.vy: Main contract for managing credit operations.
CreditConfig.vy: Configuration for borrowing parameters.
CreditData.vy: Stores user-specific loan and collateral data.
CreditBorrow.vy: Allows users to initiate new loans.
CreditByAssets.vy: Utility for tracking debt against collateral assets.
CreditRedeem.vy: Allows users to redeem GREEN tokens for collateral.
CreditRepay.vy: Enables debt repayment within the protocol.
Endaoment
This is where the protocol-owned assets sit (the yield-bearing reserves), and all the functionality that relates to it.
Endaoment.vy: The main Endaoment contract.
EndaoConfig.vy: Configuration for the Endaoment strategy.
EndaoData.vy: Stores Endaoment-specific data.
EndaoAllocate.vy: Allocates reserves to specific strategies.
EndaoLiqManager.vy: Handles liquidity management for the Endaoment.
EndaoManager.vy: Coordinates Endaoment operations.
EndaoPrinter.vy: Distributes yield generated by the Endaoment.
EndaoReduce.vy: Allows users to redeem GREEN for protocol-held reserves.
EndaoWallet.vy: Endaoment's reserves wallet contract.
EndaoLiqWallet.vy: Endaoment's liquidity wallet contract.
Treasury Direct
This is where all bonding-related activity happens.
TreasuryDirect.vy: Main entry point for bond activities.
TreasuryConfig.vy: Configuration for bond operations.
TreasuryData.vy: Stores bond-related data.
TreasuryClaims.vy: Allows users to claim their bond payouts.
TreasuryEpochs.vy: Manages epochs for bond issuance.
TreasuryGreenBonds.vy: Handles the issuance of GREEN token bonds.
TreasuryRipeBonds.vy: Handles the issuance of RIPE token bonds.
Auction House
If a user is liquidated and their asset cannot go directly to the Stability Pool, it’ll be sent to Auction House for auctioning.
AuctionHouse.vy: Main contract for the Auction House operations.
AuctionHouseConfig.vy: Configuration contract for auctions.
AuctionHouseData.vy: Stores data related to ongoing and completed auctions.
AuctionHouseCollections.vy: Executes liquidations and create necessary auctions.
AuctionHouseEscrow.vy: Manages escrowed assets during auctions.
AuctionHouseFinalize.vy: Handles the finalization of auctions.
AuctionHouseFungible.vy: Manages fungible asset auctions.
AuctionHouseNFT.vy: Manages NFT auctions.
Loot Box
This is where all the rewards in Ripe protocol are handled, including Ripe emissions and GREEN yield distribution from Endaoment.
LootBox.vy: Core contract for reward management.
LootBoxConfig.vy: Handles configuration for reward distribution.
LootBoxData.vy: Stores data related to user rewards.
LootBoxClaims.vy: Allows users to claim their earned rewards.
LootBoxPoints.vy: Tracks reward points for users.
LootBoxRewards.vy: Manages the distribution of rewards.
Juice Stand
The loyalty score system for Ripe. Calculates loyalty scores by reading data from various departments; scores range from 0-100.
JuiceStand.vy: Core contract for loyalty score management.
JuiceStandConfig.vy: Configuration for the loyalty score system.
JuiceStandData.vy: Stores data related to user loyalty scores.
JuiceStandScores.vy: Calculates and updates user loyalty scores.
Ledger
Tracks user balances, transactions, and safety mechanisms.
Ledger.vy: Core utility for tracking balances and transactions.
LedgerData.vy: Stores user and transaction data.
LedgerLocker.vy: Handles locking mechanisms for deposits.
LedgerManager.vy: Manages ledger-related operations.
LedgerSafetySlips.vy: Ensures safety by issuing slips for asset tracking.
LedgerTouchTx.vy: Tracks and verifies transactions for security purposes.
Janitorial
Responsible for cleaning up user states and refreshing required data.
Janitorial.vy: Handles background maintenance tasks.
Registries
There are five important areas of the protocol that require extensibility (four of them are Departments). These are essentially registry contracts where new address entries can be added, and old entries can be updated. Because they all behave similarly, they each use PhoneBook.vy as a shared resource (abstraction).
BoardRoom.vy
Manages governance contracts and facilitates interaction between governance components, such as PropHouse.vy, ElectionHall.vy, and department-specific governor contracts. It ensures that governance processes remain transparent and efficient.
PriceDesk.vy
Handles price oracles and feeds. This registry ensures that the protocol has access to up-to-date pricing data for supported assets, enabling accurate calculations for collateralization, borrowing, and liquidation thresholds.
RoloDex.vy
Integrates with decentralized exchanges (DEXs) to provide liquidity and facilitate trades within the protocol. This registry supports swapping, routing, and other interactions with external liquidity pools.
StratMap.vy
Maintains a map of deposit strategies, including collateral assets and DeFi yield integrations. It allows for the addition of new strategies or updates to existing ones, ensuring the protocol remains adaptable and optimized for yield generation.
HumanResources.vy
Manages DAO contributors by tracking vesting schedules, unlocks, and staking mechanisms. This registry ensures contributors receive their allocations in a transparent and timely manner while supporting decentralized workforce management.
Strategies
Strategies are the core mechanisms of the Ripe Finance protocol that determine how assets are managed, allocated, and used to generate yield. They provide flexibility and scalability, allowing for the addition of new strategies over time. Each strategy is designed to serve specific functions within the protocol and can be easily updated or replaced to adapt to changing market conditions or protocol needs.
Strategies operate independently but are integrated with the broader protocol architecture. This modular design ensures that strategies can be expanded or tailored to support new assets, collateral types, or financial instruments.
Core Strategies
Stability Pool
The Stability Pool is a central strategy in Ripe Finance that supports protocol stability during liquidations. It serves as the first line of defense in absorbing undercollateralized positions. Users can deposit GREEN tokens into the Stability Pool and earn rewards in return. These rewards may include liquidated collateral assets or additional tokens distributed by the protocol.
Purpose: Absorbs undercollateralized positions to protect the protocol during market volatility.
Rewards: Distributes collateral and other incentives to users who participate.
Mechanism: Automatically processes liquidations and allocates collateral to Stability Pool depositors.
RipeGovStrat
The RipeGovStrat strategy is designed to incentivize governance participation within the protocol. Users can stake their RIPE tokens into this strategy to earn governance points, which grant voting power on protocol decisions. Additionally, RipeGovStrat distributes rewards to participants, aligning incentives with active governance involvement.
Purpose: Encourages and rewards governance participation.
Rewards: Distributes governance points and additional incentives to participants.
Mechanism: Stakes RIPE tokens to accumulate governance power and receive rewards.
Governance
Ripe Finance’s governance framework combines community-driven decision-making with efficient management by elected committees. Governance is handled through a series of specialized contracts, including PropHouse, CSuite, RuleBook, ElectionHall, and department-specific governor contracts.
PropHouse.vy: Central to the proposal lifecycle, PropHouse manages the creation, voting, and execution of proposals. When a proposal is approved and moves to the execution phase, PropHouse calls back to the relevant governor contract to finalize the change. This setup ensures that each proposal’s progress and outcome are transparent to all participants.
CSuite.vy: Oversees governance at an executive level, managing elected committees responsible for handling certain types of proposals. Committees are elected through ElectionHall to enable more agile decision-making, especially for time-sensitive matters that require efficient handling.
RuleBook.vy: Defines governance rules and policies, ensuring that all proposals adhere to the protocol’s standards. RuleBook maintains consistency and enforces protocol-wide policies for all governance actions.
ElectionHall.vy: Facilitates the election of committee members by token holders. Committees are responsible for managing specific types of proposals, providing a balance between agility and community control.
DynamicGovHelper.vy: Facilitates dynamic voting for specific protocol configurations, such as reward distribution categories. This allows token holders to make governance-driven changes without the need to create formal proposals, leveraging their governance power for efficient decision-making.
Governor Contracts: Each department has its own governor contract (e.g., CreditGov.vy, AuctionHouseGovA.vy) that interfaces with PropHouse. For any parameter change, a token holder or committee member calls the governor contract, which then creates a proposal in PropHouse. If the proposal is approved, PropHouse calls back to the governor to execute the change.
Department Config Contracts: The governor contracts interact with department config contracts to implement parameter updates. Once a proposal is approved in PropHouse, the corresponding governor contract updates the department’s configuration according to the community’s decision.
Once a proposal is created, it proceeds through the following stages:
Pending: Initial discussion phase where the community can review and discuss the proposal’s purpose before the voting period begins.
Voting: Committee members or token holders cast their votes to support, reject, or abstain from the proposal. Abstaining counts toward quorum participation but does not influence support or rejection.
Weight Adjust: If a committee handles the vote, token holders can adjust their support for committee members during this phase, potentially impacting the vote's outcome based on updated support.
Time Lock: Once approved, the proposal enters a waiting period before execution. This delay allows token holders and protocol users time to prepare for upcoming changes.
Veto: Before the proposal reaches the execution phase, any token holder can submit a veto. A successful veto will prevent the proposal from moving forward.
Execution: The final phase where the proposal’s changes are implemented, bringing the proposed updates into effect.
User Flows
The Ripe Finance protocol provides several user flows to interact with its ecosystem. These flows include borrowing, depositing, and withdrawing assets, among other key operations. Below is an overview of some of these flows and their functionalities, accompanied by detailed diagrams for better understanding.
Borrow Flow
The borrowing flow allows users to borrow assets using collateral. The flow starts with the user specifying the borrowing amount and determining if rewards or staking options should be claimed. The system then updates user debts, distributes rewards, and manages asset transfers seamlessly.
Deposit ETH Flow
This flow handles depositing ETH into the protocol. The ETH is wrapped into WETH, processed through any necessary swaps, and then allocated to the user’s chosen strategy for yield generation. The protocol tracks balances and updates the ledger.
Deposit Fungible Tokens Flow
Users can deposit fungible tokens such as ERC20 assets into the protocol. Depending on the selected strategy, the tokens may be swapped or added to liquidity pools. The protocol records the transactions and updates the user’s balance in the ledger.
Deposit NFTs Flow
This flow manages depositing NFTs into the protocol. Each token in a collection is transferred and allocated to the appropriate strategy. The system ensures the NFTs are securely stored and updates the user’s ledger balances accordingly.
Withdraw NFTs Flow
Users can withdraw NFTs from the protocol. The flow retrieves NFTs from their designated strategies and returns them to the user’s wallet while updating the ledger to reflect the changes.
Withdraw Fungible Tokens Flow
The flow for withdrawing fungible tokens involves transferring assets from the user’s strategy back to their wallet. If required, the tokens are swapped or liquidity is removed before finalizing the transaction. The protocol updates the ledger to record the withdrawal.
