Contract Components

OUROProtocol

Core protocol interface defining main functionalities

// // SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IOUROMintRouter {
    function sendCommissionToMinter(address to, uint256 amount) external;
}

OUROMinterManager

Manage minters, including permissions and roles for minting tokens within the protocol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IOUROMinterManager {

    struct MinterInfo {
        uint256 dailyAllowance;    // Daily minting limit
        string name;               // Minter name
        uint256 activeAt;          // Activation time
        uint256 totalMinted;       // Total minted amount
        uint256 lastMintDay;       // Last minting date
        uint256 lastMintAmount;    // Last minting amount
    }

    // -- Admin write Functions ---
    function addMinter(address minter, string memory name, uint256 dailyAllowance) external;
    function updateMinterName(address minter, string memory name) external;
    function removeMinter(address minter) external;

    // --- User write Functions ---
    /**
     * @dev Mint USDO by minter
     * @param minter The address of the minter
     * @param amount The amount of OURO to mint
     */
    function mintByMinter(address minter, uint256 amount) external;

    // --- User view Functions ---
    /**
     * @dev Get the minters info and today's remaining allowance for each minter
     * @param minterAddressList Array of minter addresses to query
     * @return mintersInfo Array of MinterInfo structs containing minter details
     * @return todayAllowance Array of remaining daily allowance for each minter
     * @notice Only returns data for whitelisted addresses, non-whitelisted addresses will be skipped
     */
    function getMintersInfoAndAllowance(address[] memory minterAddressList) external view returns (MinterInfo[] memory, uint256[] memory);
} 

OUROTokenRegistry

Registry contract to keep track of supported tokens, their addresses, and possibly their metadata or status within the protocol.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IOUROProtocol {

    event CoreInitialized(address usdo, address star, address vipManager, address minterManager, address mintRouter, address tokenRegistry, address treasure);
    event EpochAdvanced(uint32 indexed newEpoch, uint256 timestamp, uint256 duration);
    // record user tax burned
    // user: user address
    // to: to address
    // taxAmount: tax amount
    // starAmount: star amount
    // epoch: epoch number
    event UserTaxBurned(address indexed user, address indexed to, uint256 taxAmount, uint256 starAmount, uint256 epoch);
    // record new appended star amount, including user and referrer rebate star amount
    // currentEpoch: current epoch number when STAR added
    // effectiveEpoch: effective epoch number when STAR take effect
    // epochUserTotalEnAmount: user's total star amount in the epoch, including pending epoch
    event StarAppended(address indexed user, uint256 indexed currentEpoch, uint256 indexed effectiveEpoch, uint256 starAmount, uint256 epochUserTotalStarAmount);
    event TokenDeposited(address indexed to, address indexed token, uint256 amount, uint256 usdoAmount, address referrer);
    event TokenRedeemed(address indexed user, address indexed token, uint256 amount, uint256 tokenAmount, uint256 redeemTax);
    event AirdropApplied(address indexed user, uint64 indexed epoch, uint64 indexed level, uint256 amount);
    event AirdropClaimed(address indexed user, uint256 indexed amount);
    event PendingRewardsBecameClaimable(address indexed user, uint32 indexed epoch, uint256 amount, uint32 currentEpoch);
    event TotalRewardsApplied(address indexed user, uint32 indexed applyEpoch, uint256 amount, uint32 currentEpoch);

    // referrer event
    event ReferrerSet(address indexed user, address indexed referrer);
    event ReferrerRebate(address indexed user, address indexed referrer, uint256 amount, uint256 epoch);
    event ReferrerQualificationSet(address indexed referrer);

    // withdraw event
    event RedeemTaxWithdrawal(address indexed user, address indexed token, uint256 amount);


    event MintByMinter(address indexed user, address indexed minter, uint256 usdoAmount, uint256 commissionAmount);
    event ExemptSenderAddressAdded(address indexed addr);
    event ExemptSenderAddressRemoved(address indexed addr);

    event CumulativeValuesSet(uint[] cumulativeValues);

    /** mint usdo from token, etc.
     * 
     * 
     * Requirements:
     * - amount: must be greater than 0
     * - referrer: must be valid address
     * - only new user can set referrer
     * - old user can't change referrer, and can only add referrer's referrer amount
     */
    function deposit(uint256 amount, address referrer, address token) external;

        /**
     * @dev Redeem token from USDO
     * @param amount The amount of token to redeem
     * @param token The token to redeem
     * 
     * Requirements:
     * - amount: must be greater than 0
     * - Insufficient balance: must have enough USDO balance
     * - will charge a tax for redeem
     * - only manager can call
     * - will burn the USDO
     */
    function redeem(uint256 amount, address token) external;

    /**
     * @dev Claim the airdrop
     *  user will receive USDO as airdrop
     * 
     * Requirements:
     * - totalClaimableAmount: must be greater than 0
     */
    function claimAirdrop() external;


    // internal
    /**
     * @dev Handles the tax calculation and collection for token transfers
     * @param from The address sending tokens
     * @param to The address receiving tokens
     * @param amount The original transfer amount
     * @return The amount after tax that should be transferred to the recipient
     */
    function handleConsumerTax(address from, address to, uint256 amount) external returns (uint256);

    /**
     * @dev Set the referrer for the user
     * @param referrer The address of the referrer
     */
    function setReferrerQualification(address referrer) external;

    // --- User View Functions ---
    /**
     * @dev Calculate the cumulative applyable rewards amount for the user
     * @return The cumulative applyable rewards amount for the user
     */
    function userCumulativeApplyableRewardsAmount() external view  returns (uint256);

    /**
     * @dev Get the user's valid star amount for a specific epoch
     * @param user The address of the user
     * @param epoch The epoch number
     * @return The user's valid star amount for the specified epoch
     */
    function getUserValidStar(address user, uint256 epoch) external view returns (uint256);

    /**
     * @dev get the epoch info  
     * @param epoch The epoch number
     * @return currentTime current time     
     * @return startTime current epoch start time
     * @return endTime current epoch end time
     * @return remainingTime current epoch remaining time
     * @return usdoVolume current epoch STAR volume
     * @return usdoBurned current epoch STAR burned
     */
    function getEpochInfo(uint256 epoch) external view returns (
        uint256 currentTime,
        uint256 startTime,
        uint256 endTime,
        uint256 remainingTime,
        uint256 usdoVolume,
        uint256 usdoBurned
    );

    // -- User write Functions ---
    /**
     * @dev Mint USDO by minter
     * @param minterAddress The address of the minter
     * @param starAmount The amount of Star to mint
     */
    function mintStarByMinter(address minterAddress, uint256 starAmount) external;


    // -- Admin Functions ---
    /**
     * @dev Set the cumulative values for the star rate
     * @param _values The cumulative values for the star rate
     */
    function setCumulativeValues(uint[] calldata _values) external;
}

OUROVipManager

Manage and coordinate different VIP memberships, their privileges.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IOUROTokenRegistry {

    // --- View Functions ---
    function isSupported(address token) external view returns (bool);
    function getRedeemFee(address token) external view returns (uint256);
    function getLastUpdated(address token) external view returns (uint256);
    function getBaseRedeemFeeRate() external pure returns (uint256);
    function getPendingFee(address token) external view returns (uint256);
    function getActivationTime(address token) external view returns (uint256);
    function getPendingTokenInfo(address token) external view returns (uint256 fee, uint256 activationTime);
    function getTokenPriceUsd(address token) external view returns (uint256 price, uint8 decimals);

    // --- Admin Functions ---
    function addToken(address token, uint256 fee) external;
    function removeToken(address token) external;
    function reactivateToken(address token) external;
    function updateRedeemFee(address token, uint256 newFee) external;
    function activatePendingFee(address token) external;
    function activatePendingToken(address token) external;
    function setPriceFeed(address token, address aggregator) external;

}

OUROTreasure

Manage the protocol’s treasury, including holding, distributing, and accounting for protocol funds

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;


interface IOUROTreasure {
    function withdraw(address token, address to, uint256 amount) external;
    function balanceOf(address token) external view returns (uint256);
}

OUROMintRouter

Intermediate contract for STAR minting

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IOUROMintRouter {
    function sendCommissionToMinter(address to, uint256 amount) external;
}

USDO

Ouroboros USDO ERC20 token

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.20;

interface IUSDO {
    function mint(address to, uint256 amount) external;
    function burn(address from, uint256 amount) external;
    function update(address from, address to, uint256 value) external;
    function setConsumerTaxExemptReceiver(address receiver, bool isExempt) external;
    function setConsumerTaxExemptSender(address sender, bool isExempt) external;
}

STAR

Ouroboros STAR (ERC20): Cashback vouncher

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.20;

interface ISTAR {
    function mint(address to, uint256 amount) external;
}