# Looper Module

## Overview

**Looper** is the core contract responsible for **automated leverage position management** in the protocol. It coordinates **CBR** and **SLF**, implementing position creation, yield compounding, repayment, unstaking, reward claiming, and liquidation through **WalletInstance** and **LoopHelper**.

## How Looper Positions Work

When users open a Looper position, the system follows these steps:

**1. Deploy Position Wallet (Wallet Instance)**

* Deploy a lightweight wallet contract specifically for this position to custody collateral and borrowed assets

**2. Create Position in CBR**

* Collateralize RWA assets
* Borrow SLB
* Create position and save CBR position ID in Looper position information

**3. Register Dynamic Interest Lending Position in SLF**

* Call dynamic interest borrowing interface
* System calculates actual borrowable USDC based on SLB quantity
* Create SLF position and save SLF position ID in Looper position information

**4. Transfer Assets to Wallet Instance**

* User's RWA assets transfer to wallet
* Borrowed USDC (converted in SLF) transfers to wallet

**5. Call LoopHelper to Convert USDC to RWA Assets**

* LoopHelper executes the "borrow—invest—borrow again" cyclic leverage logic
* Currently uses mint for direct conversion between two assets (testing phase)

**6. Risk Control Check & Position Recording**

* Verify position meets safety requirements and leverage ratios
* Record position in user's portfolio

***

## Functions and Responsibilities

#### **1. Position Configuration Management**

Allow protocol administrators to define and update **position configurations (LooperConfig)**:

* Deposit Token
* Borrow Token
* Position logic executor (LoopHelper)
* Price oracle (Oracle)
* Maximum borrow rate (maxBorrowRate)
* Liquidation threshold (liquidationRate)

Bind configurations with corresponding deposit tokens for easy user strategy discovery.

#### **2. Position Lifecycle Management**

**Create Position (createPosition):**

* Initialize wallet instance (WalletInstance)
* Create loan in CBR, collateralize deposits and borrow CCR (Cleared Collateral Receipt)
* Convert CCR (Cleared Collateral Receipt) to liquidity, borrow target tokens in SLF
* Inject deposits and borrowed tokens into WalletInstance, execute initial investment logic through LoopHelper
* Check position borrow rate reasonableness

**Refresh Position Status (pokePosition):**

* Call WalletInstance and SLF to update yield and debt data

**Repay Position (repayForPosition):**

* Support user or third-party position debt repayment
* Reduce corresponding CBR collateral after repayment

**Unstake Assets (callUnstake / callClaimUnstake):**

* Unstake assets by user-specified amounts
* Support partial assets for debt repayment, remainder returned to user

**Extract Yields (callSkim / callClaimRewards):**

* Skim: Extract surplus assets
* ClaimRewards: Claim reward assets

**Position Liquidation (liquidate):**

* Executed by authorized liquidators
* Force takeover when position borrow rate exceeds liquidation ratio

#### **3. Risk Control & Access Control**

**Position Rate Check:**

* Use oracle prices to calculate position **debt value / collateral value**
* Exceeds maxBorrowRate → Block creation or operations
* Exceeds liquidationRate → Allow liquidator takeover

**Liquidator Management:**

* Protocol administrators can add/remove liquidators
* Only liquidators can execute position liquidations

***

## Interactions and Dependencies

**CBR Module**

* Used for collateral and lending logic (createLoan, repay)
* Manage collateral and borrowing token ledgers

**SLF Module**

* Responsible for borrowing fund pools and dynamic interest rate logic (borrowDynamic, decreaseDynamicBorrow, pokeUserDynamic)
* Provide position debt data

**WalletInstance**

* Independent wallet contract for each position, isolating position assets
* Execute position logic (investment, unstaking, reward claiming)

**LoopHelper**

* Strategy execution logic (e.g., leverage compounding)
* Called by LooperCore to operate assets within WalletInstance

**Oracle Interface**

* Provide collateral and borrowing token prices
* Used to calculate position borrow rates