Minting USDs

To mint new USDs, minters only need eligible collateral. Currently, the protocol is accepting USDC.e, USDC, USDC.e, Frax, DAI, USDT and LUSD as collateral and more tokens might be added to this list in the future. However, USDs tokens are fungible and redeemable in the same way, independent of their underlying minting collateral. It acts as an IOU on the pooled collateral.

The protocol will mint 1 USDs by collecting 1 USD worth of collateral.

Collateral tokens required = No. of USDs tokens minted/Min (Price of collateral in USD, 1 USD)

When a collateral token is worth less than 1 dollar, it will be treated with its actual market price. However, when it is worth more than 1 dollar, it will be treated as 1 dollar. Hence, USDs will always be fully collateralized or over-collateralized.

Mint fees are subject to Sperax DAO approval.

Redeeming USDs

Redeeming 1 USDs at the protocol level gives the user back any one unit of collateral (maximum 1 unit of collateral) after deducting the redemption fee. Redeemers can choose from the list of eligible collaterals that they want to receive. A portion of USDs redeemed is collected as a redemption fee by the protocol.

The protocol will redeem 1 USDs following this simple equation:

Fee = x% of USDs amount redeemed. 'x' depends on the selected collateral.

Collateral tokens redeemed = (1-x)% * (No. of USDs redeemed)

When a collateral token is worth more than 1 dollar, it will be treated with its actual market price. However, when it is worth less than 1 dollar, it will be treated as 1 dollar. Hence, USDs will always be fully collateralized or over-collateralized.

The aggregate collateral ratio (or CR = Total Value Locked/USDs Circulating Supply) should be close to 100% as USDs are backed by stablecoins and collateral is expected to hold their price even in situations of market volatility. However, in an extreme situation if the value of locked collateral changes and the collateral ratio drops by more than 10%, the protocol will be paused manually. Redemptions will begin based on governance or if the collateral ratio increases. To cover any gaps in collateralization SPA reserves from Treasury may be used by the protocol.

Redemption fees are subject to Sperax DAO approval.

Caps

While minting USDs, if the price of the collateral token is more than 1 USD, then USDs will treat the price of the collateral as 1 USD and will only mint 1 USDs per collateral token deposited. But if the price of the collateral is less than 1 USD then more units of the collateral will be required to mint a unit of USDs. In that case minters would need to provide 1 USD worth of collateral to mint 1 USDs. If the price of the collateral has dropped below 0.97 cents then users would not be able to use that collateral to mint USDs. While redeeming users would always receive one unit of any collateral token of their choice for one unit of USDs.

Fees

Fees will be calculated and configurable based on the current state of the protocol’s collateral composition. Anyone would be able to call a function that updates the fee parameters. When a collateral would exceed the desired collateral composition the fee for that collateral would increase and its redemption fee would decrease. Similarly when the amount of collateral in the protocol is less than the desired amount, the mint fee for that collateral will decrease and the redemption fee would increase. Initially all collaterals except for USDC will be set to have a desired collateral composition of 20% and the base fee will be set to 0.05%. Any collateral having a composition of greater than the desired collateral composition cap will have a mint fee of greater than the base fee. The exact applicable fee on a collateral will vary and can be queried via a view function in the contract.

x: Current collateral value in number of tokens

Ca: (Desired collateral composition in % x Total Collateral in the Vault)

Total collateral in vault = Total USDs supply

Base mint and redeem fee (f base): Base fee for mint and redemption which will be discounted/increased dynamically based on the collaterals composition.

Redeeming from Strategies

Now users can redeem their choice of collateral from any yield strategy, instead of relying on a preset default mechanism. Strategies are a set of smart contracts that control the depositing and withdrawal of collaterals from various other DeFi protocols like Aave, Compound, Curve etc.. The slippage that occurs is still transferred back to the redeemers but since redeemers have a choice, they could calculate and manage their own slippage. Withdrawing from single sided strategies like Aave and compound could have significantly less slippage as compared to withdrawing from complex liquidity pool strategies like Curve.

Auto-yield is distributed after a user redeems and before a user mints. So minters and redeemers should check if there’s an eligible auto-yield.

1. Cap/Floor collateral value to $1 while minting/redeeming 1 USDs

Minting 1 USDs - If a collateral token is worth less than $1, it will be treated with its actual market price. However, if it is worth more than 1 dollar, it will be treated as $1.

Redeeming 1 USDs - If a collateral token is worth more than $1, it will be treated with its actual market price. However, if it is worth less than 1 dollar, it will be treated as 1 units of collateral at its market price.

Hence, USDs will always be fully collateralized or over-collateralized. For more information on how mint and redeem functions work check outMinting and Redeeming

2. Redemption Fee

The protocol collects a redemption fee whenever USDs is redeemed. This fee is passed on to the SPA stakers. Redemption fee is levied so that protocol does not work like a free token swap instrument. The fee is static for each collateral token but can be upgraded through governance by the community. It is a percentage of the transaction value.

1. Mint Fee = 0

2. Redemption Fee = x% of the amount of USDs redeemed.

x depends on the selected collateral. Check the current redemption fee for the USDs in app.sperax.io

3. Pause minting USDs with de-pegged collateral

If the collateral being used to mint USDs has de-pegged by 2% or more to the downside then protocol will stop minting USDs using that collateral.

4. Auto-yield for USDs holders

As more people use USDs, the yield rate will serve as a second-layer protection from a high selling pressure, further empowering a mass adoption in various use cases including payment, derivatives, and portfolio construction. For more information on how auto-yield works check out Auto Yield

5. Mint SPA when sufficient collateral is not available

When sufficient collateral is not available, USDs redeemers would get $1 worth of collateral in the form of SPA tokens. This would be the collateral of last resort.

Key parameters upgradeable via governance

• Collateral types to mint/ redeem USDs.

• Desired collateral composition, oracle used for price feed of the collateral, base Mint Fee, base Redemption Fee and price floor for each collateral type. Updating the price floor for collateral used to mint USDs. Setting the price floors for each collateral will allow the protocol to remain solvent when collaterals depeg. The protocol will not mint USDs with the collateral when the price of the collateral falls below the price floor.

• Yield generation strategies for each collateral type. For example, adding new delta-neutral yield farming strategies based on other decentralized exchanges.

• Harvesting incentive.

• The USDs dripping rate from the dripper contract.

• Minimum and maximum APR for distribution of Auto-Yield.

Key functions available to the public

• Harvesting or claiming all kinds of yield tokens from the yield generation strategies. The harvester will be incentivized with a portion of the yield-farmed tokens.

• Purchase harvested yield tokens for market price. We will use the respective oracles for the yield tokens to determine the market price. This experience will be similar to the currently implemented buyback contract.

• Distributing the auto-yield to all addresses eligible to collect it. Rebase will also be triggered when someone Mints or Redeems.

The highlights of this protocol:

1. Auto-yield - Users holding USDs in their wallets automatically earn organic yield. No staking is required by the end user. Users do not need to spend gas calling the smart contract to claim their yield.

2. Layer 2 native — Cheaper transaction fees on Arbitrum make this protocol retail investor-friendly

3. Fully Backed Model - USDs is 100% backed by a diversified basket of whitelisted crypto assets (stablecoins)

USDs automates the process of earning yield on stablecoins. Yield is generated organically by sending collateral to audited decentralized finance protocols. 50% of yield generated on collateral is used to pay USDs holders Auto-Yield. USDs Auto-yield rate is adjustable and depends on the actual yield generated by the collaterals. Any yield generated beyond the max Auto-yield rate will be stored in Auto-yield reserves. This novel passive income strategy does not require any action from the user. Users can just hold USDs and see wallet balance grow, auto-compounding the yield in the process.

SPA is the governance and value accrual token of the Sperax ecosystem. SPA holders can stake SPA tokens to receive veSPA. veSPA holders are decision makers of the protocol. They will earn staking rewards and manage the protocol revenue via voting power in Sperax governance. Off-chain governance is live and community (veSPA holders) can control parameters of USDs protocol, yield strategies, eligible collateral, new product features, etc. On-chain governance will be launched soon making veSPA holders true owners of the Sperax ecosystem.

This technical document is about the upgrade to USDs-v2. It details the changes made to enhance the protocol's decentralization, transparency, security, and scalability. The document covers new features and functionalities.

Externally owned accounts (EOAs) holding USDs were always eligible for the Auto-yield feature, but smart contract / smart wallets were not.

Sperax has introduced a new function: now smart accounts (or smart wallets) can call to opt in for auto rebase in USDs contract and to get Auto-yield.

An owners of a smart contract / smart wallet can opt in for rebase in USDs contract. The users will not need to claim (or send out any transactions to claim) the interest earned.

This is how to opt in your smart contract / smart wallet for rebase in USDs:

1. Go to Arbiscan and search for USDs. Verify the correct USDs contract address: 0xD74f5255D557944cf7Dd0E45FF521520002D5748

2. Go to the Token contract. ensure it is Sperax USD (USDs) deployed by Sperax Deployer 0x42d2f9f84EeB86574aA4E9FCccfD74066d809600

3. Click on the contract and make sure your account is connected (Metamask, Gnosis Safe, or any other smart account).

4. Go to “Write as Proxy”.

5. Connect your wallet (choose WalletConnect, Coinbase Wallet, or any other wallet).

6. Once connected, you will see two functions with the same name: rebaseOptIn You don’t have to call the first function because it’s an owner-only function (can be called only by the USDs owner). Instead, click the second function rebaseOptIn. This allows you to opt in for rebase for your own account (your smart contract account).

7. Confirm the transaction, and your smart account will be opted in for auto rebase.

That’s it. Your smart account / smart wallet is eligible for auto-yield!

USDs stands out from other stablecoins thanks to its inflation fighting Auto-Yield feature. USDs is novel in the stablecoin ecosystem, because it requires no action by the user. Users do not need to stake USDs nor spend gas to claim their yield. One simply holds USDs, and their wallet balance will grow.

The collateral received for minting USDs is deployed in other audited, defi projects to generate organic yield. USDs collateral earns yield in the form of reward tokens and swapping fees from the pools. This yield is shared between USDs holders and SPA stakers (The split is 50% for Auto-Yield and 50% for SPA buyback and burns. This share can be changed through governance).

Gas free yield: 50% of yield generated on USDs collateral is used to mint USDs. This USDs is distributed to anyone who holds USDs in their wallet.

The actual yield generated depends on the yield rate of the strategies where collateral is deployed. However, the protocol will try to maintain a target yield of 11% APY (maximum) so that USDs holders get stable returns irrespective of market conditions. Any yield generated over 11% is stored in the protocol to help fund the APY for lean periods when actual yield generated is less than 11%.

Yield Strategies

Different yield generation strategies are proposed by the community/team and evaluated by the community based on their yield generation potential, risk profile etc. Community then votes to choose pools/farms where collateral will be deployed. Following strategies are being used for yield generation. We will keep updating this list to include newer strategies approved by the community.

Strategy list as per SIP-55:

• USDC:

  • Compound (USDC)

  • Aave (USDC)

  Maximum cap of 75% of total USDC collateral for each strategy.

• USDC.e:

  • Compound (USDC.e)

  • Stargate (Stargate-LP USDC.e)

  • Aave (USDC.e)

  • Curve (FRAX-USDC.E)

  Maximum cap of 50% of total USDC.e collateral for each strategy.

• DAI:

  • Aave (DAI)

  • Radiant V2 (DAI)

  Maximum cap of 75% of total DAI collateral for each strategy.

• USDT:

  • Aave (USDT)

  • Stargate (Stargate-LP USDT)

  Maximum cap of 75% of total USDT collateral for each strategy.

• FRAX:

  • Frax (Curve-LP FRAX/VST)

  • Curve (FRAX-USDC.E)

  Maximum cap of 75% of total FRAX collateral for each strategy.

• LUSD:

  • Camelot (LUSD-USDC V2 Pool)

  • Aave (LUSD).

  Maximum cap of 75% of total LUSD collateral for each strategy.

Old strategies that are not in use / deprecated:

Curve | Curve-LP USDC/USDT [Not in use]

Saddle | Saddle-LP FRAX/USDC [Saddle sunset] Frax | Curve-LP FRAX/VST [Vesta sunset]

Eligibility

USDs held in EOA wallets, i.e. non-contract addresses, will receive auto-yield on a regular basis. For now, USDs that are deployed by users to yield-earning strategies within the Sperax suite of yield farms will not receive auto-yield.

By default, smart contracts holding USDs are not included in the yield distribution process and do not earn any yield. A smart contract’s USDs balance remains the same after an auto-yield distribution event. However, based on community’s feedback and once approved by veSPA holders via Snapshot voting, the Sperax team can whitelist specific smart contracts to be part of auto-yield, and provide technical support to determine whether a protocol is compatible with the auto-yield feature of USDs.

Auto-yield distribution mechanism

USDs follows the ERC20 token standard. A wallet holding USDs should expect its USDs balance to increase automatically over time. This increase is triggered by a distribution event that happens on average every 7 days. The earned USDs are not explicitly transferred into the user’s wallet, instead a global parameter is changed to update the holder's balance.

Unlike most ERC20, where the token contract directly stores the amount of tokens each wallet holds, USDs’ token contract has a shared state variable creditPerToken, and the contract stores each wallet’s credit. A wallet’s balance = credit / creditPerToken.

When yield is generated:

1. The yield is swapped for USDs in the open market

2. The USDs from step (1) is burned

3. The value of creditPerToken is *decreased globally and therefore every wallet’s balance increases (since every wallet’s credit is unchanged during this process)

*: creditPerToken is decreased according to the amount of USDs burnt in step (2) such that total supply of USDs remains unchanged after steps (2) and (3)

The circulating supply of USDs remains unchanged through this process as the USDs that are bought from the market are burnt and then the USDs balance of the holders increase proportionally. As a result, a user can expect its USDs balance to increase automatically over time without any additional USDs explicitly being transferred to the user’s wallet.

Yield distribution frequency

Yield is distributed approximately every 7 days. The exact distribution time is determined in a quasi-random way. We have decided on this randomised distribution time to prevent users from timing their USDs minting and redeeming with yield distribution events. Huge spike in minting or redeeming around the time of yield distribution can put strain on the peg and this randomisation works as a defence mechanism for maintaining peg.

Inherits: Ownable, IOracle

Author: Sperax Foundation

Communicates with different price feeds to get the price

State Variables

tokenPriceFeed

Store price feed data for tokens.

Functions

updateTokenPriceFeed

Add/Update price feed for _token

Have to be extra cautious while updating the price feed.

Parameters

removeTokenPriceFeed

Remove an existing price feed for _token.

Parameters

getPrice

Gets the price feed for _token.

Function reverts if the price feed does not exists.

Parameters

Returns

priceFeedExists

Validates if price feed exists for a _token

Function reverts if price feed not set.

Parameters

Returns

_getPriceFeed

Gets the price feed for a _token given the feed data.

Parameters

Returns

Events

PriceFeedUpdated

PriceFeedRemoved

Errors

InvalidAddress

UnableToFetchPriceFeed

InvalidPriceFeed

PriceFeedNotFound

Vault

• Responsible for following actions on USDs:

  • Mint USDs token

  • Redeem USDs token

  • Carry out rebase for USDs token

  • Allocate collateral to strategies

  • Withdraw collateral from strategies ?

Contract documentation

Inherits: Initializable, OwnableUpgradeable, ReentrancyGuardUpgradeable

Author: Sperax Foundation

This contract enables users to mint and redeem USDs with allowed collaterals.

It also allocates collateral to strategies based on the Collateral Manager contract.

State Variables

feeVault

yieldReceiver

collateralManager

feeCalculator

oracle

rebaseManager

Functions

constructor

initialize

updateFeeVault

Updates the address receiving fee.

Parameters

updateYieldReceiver

Updates the address receiving yields from strategies.

Parameters

updateCollateralManager

Updates the address having the configuration for collaterals.

Parameters

updateRebaseManager

Updates the address having the configuration for rebases.

Parameters

updateFeeCalculator

Updates the fee calculator library.

Parameters

updateOracle

Updates the price oracle address.

Parameters

allocate

Allocates _amount of _collateral to _strategy.

Parameters

mint

Mint USDs by depositing collateral.

Parameters

mintBySpecifyingCollateralAmt

Mint USDs by depositing collateral (backward compatibility).

This function is for backward compatibility.

Parameters

redeem

Redeem USDs for _collateral.

In case where there is not sufficient collateral available in the vault, the collateral is withdrawn from the default strategy configured for the collateral.

Parameters

redeem

Redeem USDs for _collateral from a specific strategy.

Parameters

redeemView

Get the expected redeem result.

Parameters

Returns

redeemView

Get the expected redeem result from a specific strategy.

Parameters

Returns

rebase

Rebase USDs to share earned yield with the USDs holders.

If Rebase manager returns a non-zero value, it calls the rebase function on the USDs contract.

mintView

Get the expected mint result (USDs amount, fee).

Parameters

Returns

_mint

Mint USDs by depositing collateral.

Mints USDs by locking collateral based on user input, ensuring a minimum expected minted amount is met.

If the minimum expected amount is not met, the transaction will revert.

Fee is collected, and collateral is transferred accordingly.

A rebase operation is triggered after minting.

Parameters

_redeem

Redeem USDs for collateral.

Redeems USDs for collateral, ensuring a minimum expected collateral amount is met.

If the minimum expected collateral amount is not met, the transaction will revert.

Fee is collected, collateral is transferred, and a rebase operation is triggered.

Parameters

_redeemView

Get the expected redeem result.

Calculates the expected results of a redemption, including collateral amount, fees, and strategy-specific details.

Ensures that the redemption is allowed for the specified collateral.

Calculates fees, burn amounts, and collateral amounts based on prices and conversion factors.

Determines if collateral needs to be withdrawn from a strategy, and if so, checks the availability of collateral in the strategy.

Parameters

Returns

Events

FeeVaultUpdated

YieldReceiverUpdated

CollateralManagerUpdated

FeeCalculatorUpdated

RebaseManagerUpdated

OracleUpdated

Minted

Redeemed

RebasedUSDs

Allocated

Errors

AllocationNotAllowed

RedemptionPausedForCollateral

InsufficientCollateral

InvalidStrategy

MintFailed

Git Source

Inherits: ICollateralManager, Ownable

Author: Sperax Foundation

This contract manages the addition and removal of collateral, configuration of collateral strategies, and allocation percentages.

Collateral Manager interacts with the Vault and various strategies for collateral management.

State Variables

collateralCompositionUsed

uint16 public collateralCompositionUsed;

VAULT

address public immutable VAULT;

collaterals

address[] private collaterals;

collateralInfo

mapping(address => CollateralData) public collateralInfo;

collateralStrategyInfo

mapping(address => mapping(address => StrategyData)) private collateralStrategyInfo;

collateralStrategies

mapping(address => address[]) private collateralStrategies;

Functions

constructor

Constructor to initialize the Collateral Manager

constructor(address _vault);

Parameters

addCollateral

Register a collateral for mint & redeem in USDs

function addCollateral(address _collateral, CollateralBaseData memory _data) external onlyOwner;

Parameters

updateCollateralData

Update existing collateral configuration

function updateCollateralData(address _collateral, CollateralBaseData memory _updateData) external onlyOwner;

Parameters

removeCollateral

Un-list a collateral

function removeCollateral(address _collateral) external onlyOwner;

Parameters

addCollateralStrategy

Add a new strategy to collateral

function addCollateralStrategy(address _collateral, address _strategy, uint16 _allocationCap) external onlyOwner;

Parameters

updateCollateralStrategy

Update existing strategy for collateral

function updateCollateralStrategy(address _collateral, address _strategy, uint16 _allocationCap) external onlyOwner;

Parameters

removeCollateralStrategy

Remove an existing strategy from collateral

Ensure all the collateral is removed from the strategy before calling this Otherwise it will create error in collateral accounting

function removeCollateralStrategy(address _collateral, address _strategy) external onlyOwner;

Parameters

updateCollateralDefaultStrategy

function updateCollateralDefaultStrategy(address _collateral, address _strategy) external onlyOwner;

validateAllocation

Validate allocation for a collateral

function validateAllocation(address _collateral, address _strategy, uint256 _amount) external view returns (bool);

Parameters

Returns

getFeeCalibrationData

Get the required data for mint

function getFeeCalibrationData(address _collateral) external view returns (uint16, uint16, uint16, uint256);

Parameters

Returns

getMintParams

Get the required data for mint

function getMintParams(address _collateral) external view returns (CollateralMintData memory mintData);

Parameters

Returns

getRedeemParams

Get the required data for USDs redemption

function getRedeemParams(address _collateral) external view returns (CollateralRedeemData memory redeemData);

Parameters

Returns

getAllCollaterals

Gets a list of all listed collaterals

function getAllCollaterals() external view returns (address[] memory);

Returns

getCollateralStrategies

Gets a list of all strategies linked to a collateral

function getCollateralStrategies(address _collateral) external view returns (address[] memory);

Parameters

Returns

isValidStrategy

Verifies if a strategy is linked to a collateral

function isValidStrategy(address _collateral, address _strategy) external view returns (bool);

Parameters

Returns

getCollateralInStrategies

Get the amount of collateral in all Strategies

function getCollateralInStrategies(address _collateral) public view returns (uint256 amountInStrategies);

Parameters

Returns

getCollateralInVault

Get the amount of collateral in vault

function getCollateralInVault(address _collateral) public view returns (uint256 amountInVault);

Parameters

Returns

getCollateralInAStrategy

Get the amount of collateral allocated in a strategy

function getCollateralInAStrategy(address _collateral, address _strategy) public view returns (uint256 allocatedAmt);

Parameters

Returns

Events

CollateralAdded

event CollateralAdded(address collateral, CollateralBaseData data);

CollateralRemoved

event CollateralRemoved(address collateral);

CollateralInfoUpdated

event CollateralInfoUpdated(address collateral, CollateralBaseData data);

CollateralStrategyAdded

event CollateralStrategyAdded(address collateral, address strategy);

CollateralStrategyUpdated

event CollateralStrategyUpdated(address collateral, address strategy);

CollateralStrategyRemoved

event CollateralStrategyRemoved(address collateral, address strategy);

Errors

CollateralExists

error CollateralExists();

CollateralDoesNotExist

error CollateralDoesNotExist();

CollateralStrategyExists

error CollateralStrategyExists();

CollateralStrategyMapped

error CollateralStrategyMapped();

CollateralStrategyNotMapped

error CollateralStrategyNotMapped();

CollateralNotSupportedByStrategy

error CollateralNotSupportedByStrategy();

CollateralAllocationPaused

error CollateralAllocationPaused();

CollateralStrategyInUse

error CollateralStrategyInUse();

AllocationPercentageLowerThanAllocatedAmt

error AllocationPercentageLowerThanAllocatedAmt();

IsDefaultStrategy

error IsDefaultStrategy();

Structs

CollateralData

struct CollateralData {
    bool mintAllowed;
    bool redeemAllowed;
    bool allocationAllowed;
    bool exists;
    address defaultStrategy;
    uint16 baseMintFee;
    uint16 baseRedeemFee;
    uint16 downsidePeg;
    uint16 desiredCollateralComposition;
    uint16 collateralCapacityUsed;
    uint256 conversionFactor;
}

StrategyData

struct StrategyData {
    uint16 allocationCap;
    bool exists;
}

Git Source

Inherits: IFeeCalculator

Author: Sperax Foundation

A contract that calculates fees for minting and redeeming USDs.

State Variables

LOWER_THRESHOLD

uint16 private constant LOWER_THRESHOLD = 5000;

UPPER_THRESHOLD

uint16 private constant UPPER_THRESHOLD = 15000;

DISCOUNT_FACTOR

uint16 private constant DISCOUNT_FACTOR = 2;

PENALTY_MULTIPLIER

uint16 private constant PENALTY_MULTIPLIER = 2;

CALIBRATION_GAP

uint32 private constant CALIBRATION_GAP = 1 days;

COLLATERAL_MANAGER

ICollateralManager public immutable COLLATERAL_MANAGER;

collateralFee

mapping(address => FeeData) public collateralFee;

Functions

constructor

constructor(address _collateralManager);

calibrateFee

Calibrates fee for a particular collateral

function calibrateFee(address _collateral) external;

Parameters

getMintFee

Calculates fee to be collected for minting

function getMintFee(address _collateral) external view returns (uint256);

Parameters

Returns

getRedeemFee

Calculates fee to be collected for redeeming

function getRedeemFee(address _collateral) external view returns (uint256);

Parameters

Returns

calibrateFeeForAll

Calibrates fee for all the collaterals registered

function calibrateFeeForAll() public;

_calibrateFee

Helper function for calibrating fee for a collateral

function _calibrateFee(address _collateral) private;

Parameters

Events

FeeCalibrated

event FeeCalibrated(address indexed collateral, uint16 mintFee, uint16 redeemFee);

Errors

InvalidCalibration

error InvalidCalibration();

Structs

FeeData

struct FeeData {
    uint32 nextUpdate;
    uint16 mintFee;
    uint16 redeemFee;
}

Git Source

Inherits: IDripper, Ownable

Author: Sperax Foundation

This contract releases tokens at a steady rate to the Vault contract, for rebasing the USDs stablecoin.

The Dripper contract ensures that tokens are released gradually over time, allowing for consistent and controlled distribution.

State Variables

vault

address public vault;

dripRate

uint256 public dripRate;

dripDuration

uint256 public dripDuration;

lastCollectTS

uint256 public lastCollectTS;

Functions

constructor

Constructor to initialize the Dripper.

constructor(address _vault, uint256 _dripDuration);

Parameters

recoverTokens

Emergency fund recovery function.

Transfers the asset to the owner of the contract.

function recoverTokens(address _asset) external onlyOwner;

Parameters

addUSDs

Function to be used to send USDs to dripper and update dripRate.

function addUSDs(uint256 _amount) external;

Parameters

collect

Transfers the dripped tokens to the vault.

This function also updates the dripRate based on the fund state.

function collect() public returns (uint256);

Returns

updateVault

Update the vault address.

function updateVault(address _vault) public onlyOwner;

Parameters

updateDripDuration

Updates the dripDuration.

function updateDripDuration(uint256 _dripDuration) public onlyOwner;

Parameters

getCollectableAmt

Gets the collectible amount of tokens at the current time.

function getCollectableAmt() public view returns (uint256);

Returns

Events

Collected

event Collected(uint256 amount);

Recovered

event Recovered(address owner, uint256 amount);

VaultUpdated

event VaultUpdated(address vault);

DripDurationUpdated

event DripDurationUpdated(uint256 dripDuration);

USDsAdded

event USDsAdded(uint256 _amount);

Errors

NothingToRecover

error NothingToRecover();

Git Source

Inherits: IRebaseManager, Ownable

Author: Sperax Foundation

This contract handles the configuration and execution of the rebasing mechanism for the USDs stablecoin. It ensures that rebases occur only when certain prerequisites are fulfilled, such as the time gap between rebases and acceptable APR (Annual Percentage Rate) ranges.

The Rebase Manager coordinates with the Vault and Dripper contracts to manage the rebase process.

State Variables

ONE_YEAR

uint256 private constant ONE_YEAR = 365 days;

vault

address public vault;

dripper

address public dripper;

gap

uint256 public gap;

aprCap

uint256 public aprCap;

aprBottom

uint256 public aprBottom;

lastRebaseTS

uint256 public lastRebaseTS;

Functions

onlyVault

modifier onlyVault();

constructor

Constructor to initialize the Rebase Manager

constructor(address _vault, address _dripper, uint256 _gap, uint256 _aprCap, uint256 _aprBottom);

Parameters

fetchRebaseAmt

Get the current amount valid for rebase

Function is called by the vault while rebasing

function fetchRebaseAmt() external onlyVault returns (uint256);

Returns

updateVault

Updates the vault address

function updateVault(address _newVault) public onlyOwner;

Parameters

updateDripper

Updates the dripper contract for USDs vault

function updateDripper(address _dripper) public onlyOwner;

Parameters

updateGap

Update the minimum time gap required between two rebases

function updateGap(uint256 _gap) public onlyOwner;

Parameters

updateAPR

Update the APR requirements for each rebase

function updateAPR(uint256 _aprBottom, uint256 _aprCap) public onlyOwner;

Parameters

getAvailableRebaseAmt

Gets the current available rebase fund

function getAvailableRebaseAmt() public view returns (uint256);

Returns

getMinAndMaxRebaseAmt

Gets the minimum and maximum rebase USDs amount based on the APR config

function getMinAndMaxRebaseAmt() public view returns (uint256, uint256);

Returns

Events

VaultUpdated

event VaultUpdated(address vault);

DripperUpdated

event DripperUpdated(address dripper);

GapUpdated

event GapUpdated(uint256 gap);

APRUpdated

event APRUpdated(uint256 aprBottom, uint256 aprCap);

Errors

CallerNotVault

error CallerNotVault(address caller);

InvalidAPRConfig

error InvalidAPRConfig(uint256 aprBottom, uint256 aprCap);

SPA holders can stake SPA tokens on either Arbitrum or Ethereum and receive veSPA tokens which are non transferable. veSPA balance is proportional to the lockup period, meaning if user locks up for higher duration they receive proportionally more veSPA tokens. veSPA balance determines the share of staking reward and voting power

1. Staking rewards: rewards will be distributed proportionally to the user's veSPA balance. Users who lock SPA for longer periods are eligible for proportionally more rewards (accrued on a weekly base) than users who locked the same amount of SPA for shorter periods. Rewards are accumulated through:

   • Yield Share Rewards - 25% of the yield generated by USDs protocol.

   • Fee Rewards - 100% of the Fee income from USDs mints and redemptions.

   The yield and fee income is originally generated in USDs. It is then swapped for SPA tokens before distribution. This makes the reward claiming process simple for stakers and maintains a constant buying pressure on the SPA token.

2. Voting power: once governance protocol is launched, voting power will depend on users' veSPA balance. Users who are committed to longer lockups will own more votes, whatever they are voting for.

veSPA balance at the moment of staking will not stay the same all the time - it will decay/reduce linearly. User's rewards per week and voting power will also decrease over time, together with the veSPA balance. Stakers can increase their veSPA balance and thereby their staking rewards and voting power by either extending the locking period or locking more SPA or re-staking SPA rewards.

At the end of the lockup period, veSPA balance will reduce depending on the pre-selected withdrawal option:

1. For Auto-cooldown option - to zero.

2. For the "Staying Staked" option (manual cooldown) - to [0.01917*staked SPA tokens]. Please note that for new stakers the "Staying Staked option" is not available.

To Stake SPA through our dapp checkout Stake SPA

veSPA is SPA locked with the "vote escrow" mechanism (ve-). This is the mechanism of locking tokens for relatively long pre-defined time periods. On staking SPA, the staker receives non-tranferrable tokens veSPA.

The veSPA balance will depend on the amount of SPA tokens locked and the user's chosen lockup period. Stakers can lock their tokens for a maximum of 4 years or a minimum of 7 days. A higher lockup period means a higher veSPA balance for the same amount of SPA staked.

veSPA value = SPA tokens staked * (Lockup Period in days / 365)

Below table shows how veSPA value will be determined

veSPA balance will decay linearly with time. At the end of lockup period, veSPA balance will reduce to 0 or (0.01917*staked SPA tokens) based on the withdrawal method user chooses while staking the SPA. Two withdrawal methods were available to the early stakers, they will work till the end of their lockup period. For all the new stakers method 1 (Auto-cooldown) stays the only available method.

1. Auto-cooldown - veSPA balance reduces to 0 at the end of lockup period and staker is able to withdraw locked SPA balance immediately after expiry date

2. Stay Staked at Residual Value - Stakers can opt to remain staked at the end of the unlock date at a residual veSPA balance (0.01917*staked SPA tokens). They can initiate cooldown when 7 days are left in the staking period or anytime after. After the cooldown period of 7 days is over, they can withdraw the staked SPA tokens. Check outStay Staked at Residual Valuefor more details.

Some important points to consider before locking your SPA tokens:

1. Staking is an irreversible process, once locked the tokens cannot be unlocked before the unlock date. Users cannot prepone the expiry date or reduce the amount of locked SPA.

2. Due to precision issues it may not always be possible to choose an exact unlock date. Users can select the lockup period but the exact unlock date is rounded down to nearest Thursday UTC. Stakers will be able to choose these eligible unlock dates in our dapp.

3. Users rewards per week and voting power will also decrease over time, together with the veSPA balance. The users who are committed to long-term staking can increase their rewards per week and voting power by:

   • Extending the locking period

   • Locking more SPA

   • Claiming SPA staking rewards and restaking them into veSPA (compounding)

Extension of Lockup

Stakers can extend their lockup such that the lockup expiry date is <= 4 years from the current date. At no point, lockup period can be more than 4 years.

The lockup period cannot be extended in the following scenarios:

1. When a staker’s lockup period has expired and they only have residual veSPA balance

2. When a staker has already initiated cooldown period Example: If a user has 100 veSPA tokens which expire in 3 years, the user can increase the lockup by a maximum of 1 year.

Increasing Staked Balance

Users can also increase their veSPA balance by staking any additional amount of SPA tokens for the same lockup as their existing veSPA balance.

Example: if a user has 100 veSPA tokens which are expiring in 34 days, they can stake any amount of additional SPA for 34 days. The increase in veSPA balance will be calculated based on the same lockup period as the previously staked tokens.

Users who initiate staking will get the auto-cooldown feature. Users who initiated staking in the past were able select one of two cooldown options that will stay active till the end of the staking period:

1. Auto-cooldown: the protocol will automatically initiate a cooldown 7 days before expiry. In this case, the assets will be available immediately after the lock period, but they will not bring any more rewards post-expiry.

2. Stay staked at residual value (or manual cooldown): After the lock expires, the assets remain locked with the residual value of [0.01917*staked SPA tokens], and will continue to bring rewards to the user. If one day the user decides to take their assets out - they need to initiate the cooldown manually. After a one-week cooldown, the assets will become available.

Withdrawing from the protocol does not automatically claim all the SPA rewards. The users would be required to claim the rewards separately. In case the staking rewards are not distributed till that point of time, users can still claim the rewards and fee earnings accrued to them after they have withdrawn their staked SPA tokens.

Auto-Cooldown

When new users start staking, the auto-cooldown feature is applied. Auto-cooldown means that the veSPA balance decays to zero linearly and the stakers are able to withdraw their staked SPA balance at the end of their lockup period.

Stay Staked at Residual Value

Currently, this option is not available. If a user has chosen this option while staking in the past, their final veSPA balance was set at the residual veSPA balance. They would continue to earn all the staking rewards at this veSPA balance for as long as the protocol keeps distributing rewards. The residual veSPA balance is equivalent to the veSPA balance of a staking position that unlocks in 7 days.

Residual veSPA balance = (7/365)*Staked SPA tokens = 0.01917*Staked SPA tokens

Initiate Cooldown

Stakers can initiate cooldown when 7 days are left in lockup expiry or anytime after that. When the staker’s veSPA balance is set to the residual veSPA balance or when only 7 days are left in the lockup period, the staker can initiate a transaction to start a cooldown period. When the cooldown period is initiated the lockup expiry date is updated to a new date which would be 7 days from the date on which the cooldown was initiated.

Staker’s veSPA balance decays from the residual veSPA balance to zero during the cooldown period. At the end of the cooldown period, the staker can withdraw the SPA they had deposited. Stakers receive rewards during the cooldown period in proportion to their veSPA balance.

At the end of the cooldown period, the veSPA balance remains zero and the user doesn’t get any rewards. The users can unstake at any point in time after the cooldown period has ended.

USDs

• ERC20 contract

• USDs is a stable coin which generates auto-yield natively.

• USDs is a rebasing token with two modes of accounting for users:

  • Rebasing wallets

    • Users holding tokens in their EOA are by default in this category and are eligible for auto-yield via a rebasing mechanism.

    • Any contract opted-in for rebase also comes in this category.

    • Balance for this category is tracked via a credit system, as described below :

    • creditsPerToken is tracked at a global level and is updated when doing a rebase.

    • creditBalance is tracked at an account level and is updated via token transfer, mint, redemption of USDs

  • Non-Rebasing wallets

    • For Non-Rebasing wallets this token acts as a normal ERC20 token and tracks the balance of the wallet as usual.

• Rebasing Mechanism

  • Users mint USDs using approved list of collaterals

  • These collaterals accumulated in the USDs vault are then deployed to various yield on-chain earning opportunities.

  • Yield is harvested periodically and is used to buyback USDs from the market of which 50% is used as revenue for veSPA holders and rest of it goes for USDs auto yield.

  • While doing a rebase the x amount of USDs is partially burnt (without changing the overall total supply) and the creditsPerToken value is adjusted such that the burnt amount is proportionally distributed across all rebasing wallets.

Contract Documentation

Author: Sperax Foundation

ERC20 compatible contract for USDs supporting the rebase feature. This ERC20 token represents USDs on the Arbitrum (L2) network. Note that the invariant holds that the sum of balanceOf(x) for all x is not greater than totalSupply(). This is a consequence of the rebasing design. Integrations with USDs should be aware of this feature.

State Variables

MAX_SUPPLY

_totalSupply

_deprecated_vars

_allowances

vault

_creditBalances

_deprecated_rebasingCredits

rebasingCreditsPerToken

nonRebasingSupply

nonRebasingCreditsPerToken

rebaseState

_deprecated_gatewayAddr

_deprecated_isUpgraded

paused

Functions

onlyVault

Verifies that the caller is the Savings Manager contract.

constructor

initialize

Initializes the contract with the provided name, symbol, and vault address.

Parameters

mint

Mints new USDs tokens, increasing totalSupply.

Parameters

burn

Burns tokens, decreasing totalSupply.

Parameters

rebaseOptIn

Voluntary opt-in for rebase.

Useful for smart-contract wallets.

rebaseOptOut

Voluntary opt-out from rebase.

rebaseOptIn

Adds _account to the rebasing account list.

Parameters

rebaseOptOut

Adds _account to the non-rebasing account list.

Parameters

rebase

The rebase function. Modifies the supply without minting new tokens. This uses a change in the exchange rate between "credits" and USDs tokens to change balances.

Parameters

updateVault

Change the vault address.

Parameters

pauseSwitch

Called by the owner to pause or unpause the contract.

Parameters

transfer

Transfer tokens to a specified address.

Parameters

Returns

transferFrom

Transfer tokens from one address to another.

Parameters

Returns

approve

Approve the passed address to spend the specified amount of tokens on behalf of msg.sender. This method is included for ERC20 compatibility.

increaseAllowance and decreaseAllowance should be used instead. Changing an allowance with this method brings the risk that someone may transfer both the old and the new allowance - if they are both greater than zero - if a transfer transaction is mined before the later approve() call is mined.

Parameters

Returns

increaseAllowance

Increase the amount of tokens that an owner has allowed a _spender to spend. This method should be used instead of approve() to avoid the double approval vulnerability described above.

Parameters

Returns

decreaseAllowance

Decrease the amount of tokens that an owner has allowed a _spender to spend.

Parameters

Returns

totalSupply

Check the current total supply of USDs.

Returns

balanceOf

Gets the USDs balance of the specified address.

Parameters

Returns

creditsBalanceOf

Gets the credits balance of the specified address.

Parameters

Returns

allowance

Function to check the amount of tokens that an owner has allowed a spender.

Parameters

Returns

_mint

Creates _amount tokens and assigns them to _account, increasing the total supply.

Emits a {Transfer} event with from set to the zero address.

Requirements - to cannot be the zero address.

Parameters

_burn

Destroys _amount tokens from _account, reducing the total supply.

Emits a {Transfer} event with to set to the zero address.

• Requirements:

• _account cannot be the zero address.

• _account must have at least _amount tokens.*

Parameters

_executeTransfer

For non-rebasing accounts credit amount = _amount

Update the count of non-rebasing credits in response to a transfer

Parameters

_rebaseOptIn

Add a contract address to the non-rebasing exception list. I.e., the address's balance will be part of rebases so the account will be exposed to upside and downside.

Parameters

_rebaseOptOut

Remove a contract address from the non-rebasing exception list.

_isNonRebasingAccount

Is an account using rebasing accounting or non-rebasing accounting? Also, ensure contracts are non-rebasing if they have not opted in.

Parameters

_ensureNonRebasingMigration

Ensures internal account for rebasing and non-rebasing credits and supply is updated following the deployment of frozen yield change.

Parameters

_balanceOf

Calculates the balance of the account.

Function assumes the _account is already upgraded.

Parameters

_creditsPerToken

Get the credits per token for an account. Returns a fixed amount if the account is non-rebasing.

Parameters

_isNotPaused

Validates if the contract is not paused.

Events

TotalSupplyUpdated

Paused

VaultUpdated

RebaseOptIn

RebaseOptOut

Errors

CallerNotVault

ContractPaused

IsAlreadyRebasingAccount

IsAlreadyNonRebasingAccount