sToken

Overview

The SToken contract in the Soul Protocol is a key component that tracks the users supply, collateral and borrow positions in a specific money market. Each market is uniquely defined by the chain it resides on (e.g., Ethereum, Polygon), a base protocol (e.g. Aave, Compound) and an underlying asset (e.g. USDC, WBTC). It issues an interest-bearing ERC20 token, which accrues value over time based on the interest earned from the supplied assets in the protocol. Each lending market in the protocol has its own unique SToken contract, enabling granular tracking and management of user positions.

Key Features

• When users supply assets to a money market, they receive sTokens, which represent their supplied assets and the interest accrued over time.

• The value of sTokens increases based on the interest rate defined by the base protocol.

• The SToken acts as an intermediary between the user and the base protocol, ensuring seamless supply, borrow, redeem, and repay operations.

• Implements external functions that users can call to supply assets, add collateral, repay borrowed funds, or redeem their position.

• Integrates with the Soul Controller to enable cross-chain borrowing and collateralization.

• Implements standard ERC20 functions like balanceOf, transfer, and totalSupply, with additional mechanisms to track supply and borrow balances.

User Interactions

Supply Assets

• What Happens:

• Users supply an underlying asset to a lending market, receiving an equivalent amount of sTokens based on the current exchange rate.

• Example:

• If you supply 100 DAI to the Ethereum-Aave market, you will receive an equivalent amount of sADAI tokens at the current exchange rate.

Redeem Assets

• What Happens:

• Users redeem their supplied assets by converting their sTokens back to the underlying asset. The amount redeemed includes any accrued interest.

• Example:

• Redeeming the issued sADAI tokens will return the original deposit of 100 DAI plus the interest accrued since the tokens were issued.

Repay Loans

• What Happens:

• Borrowed assets can be repaid to reduce the outstanding debt and free up collateral.

• Example:

• Repaying a $50 loan will reduce your debt and restore your borrowing power.

Add Collateral

• What Happens:

• Users can designate a portion of their sTokens as collateral or withdraw collateralized tokens.

• Example:

• Adding 50 sADAI as collateral increases your borrowing limit proportionally.

Public Functions

• Supply Function

supply(address to, uint amount):

• Supplies the underlying asset and mints the corresponding amount of sTokens.

• Inputs: to (address of the recipient), amount (quantity of the asset to supply).

• Redeem Function

redeem(address to, uint sTokenAmount):

• Redeems a specified amount of sTokens, converting them into an equivalent amount of the underlying asset.

• Inputs: to (address of the recipient), sTokenAmount (quantity of sTokens to redeem).

• RepayBorrow Function

repayBorrow(address borrower, uint amount, RouterDataStructs.AdapterParams calldata adapterParams):

• Repays a portion of the outstanding debt on behalf of the borrower.

• Inputs: borrower (the address of the borrower), amount (quantity to repay), adapterParams (configuration params required for cross-chain communication)

• Add Collateral

addCollateral(uint sTokenAmount, RouterDataStructs.AdapterParams calldata adapterParams):

• Activates the specified amount of the supplied sTokens as collateral.

• Inputs: sTokenAmount (amount of sTokens to be activated as collateral), adapterParams (configuration params required for cross-chain communication)

• Implementation Details

1. Interest Calculation:

   • Interest accrual is managed via the accrueInterest function, which updates user total balances and indexes based on the interest rates provided by the base protocol.

2. Indexes for Efficiency:

   • The contract uses exchangeRate and borrowIndex to efficiently calculate accrued interest for all users without updating individual balances.

3. Native Asset Support:

   • Markets using native chain tokens (e.g., ETH or POL) have specialized STokenNative contracts to handle deposits and withdrawals of these assets.

• Important Considerations

• Cross-Chain Fees: Cross-chain operations incur additional costs for gas and messaging.
• Interest Rate Variations: Interest rates and collateral factors may vary across markets and base protocols.

This documentation aims to guide users in understanding and interacting with the sToken smart contract within the Soul Protocol, providing a seamless DeFi experience.