Usual Tech Docs
Usual WebsiteGeneral DocsContract DeploymentsAuditsAccess dApp
  • 🚀GM GM
    • Usual Tech Hub
  • 🔭Overview
    • Usual Protocol Primer
    • Features
      • Mint & Redeem Engine
      • USD0
      • USD0++
      • USUAL
      • USUAL*
      • USUALx (USUAL staking)
      • USUAL distribution
      • USUAL Airdrop
      • Usual USD0++ Investment Vault
    • Architecture
      • Role Management
      • USUAL Distribution Model
  • ⛓️Smart Contracts
    • Protocol Contracts
      • DaoCollateral
      • Swapper Engine
      • USUAL staking
      • USUAL* Vested Allocation Staking
      • USUAL Distribution
        • Distribution Module
        • Yield Module
      • Airdrop Module
    • Token Contracts
      • USD0
      • USD0++
      • USUAL
      • USUAL*
      • USUALx
      • Usual USD0++ Investment Vault
        • VaultRouter
    • Utility Contracts
      • ClassicalOracle
      • Abstract Oracle
      • Chainlink Oracles
      • Pyth Oracles
      • RedStone Oracles
    • Real World Assets
      • USYC (by Hashnote)
      • M (by M0)
        • UsualM
      • USDtb
    • Contract Deployments
  • 🛡️Security & Audits
    • Security Practices
    • Testing Framework
    • Monitoring Framework
    • Audits
    • Bug Bounty
  • 🧩Integrations
    • Integrate USD0++
      • Reward redistribution by integration partner
      • Claim Address Redirect
      • Daily Distribution powered by Brevis (coming soon)
  • 📚Resources
    • Community & Support
    • References
  • 📖Support
    • FAQ
    • Glossary
  • ⚖️Legal
    • Terms of Services
    • Legal Notice
    • Privacy Policy
Powered by GitBook
On this page
  • Role & Permissions
  • DEFAULT_ADMIN_ROLE
  • PAUSING_CONTRACTS_ROLE
  • NONCE_THRESHOLD_SETTER_ROLE
  • INTENT_MATCHING_ROLE
  • DISTRIBUTION_OPERATOR_ROLE
  • DISTRIBUTION_ALLOCATOR_ROLE
  • DISTRIBUTION_CHALLENGER_ROLE
  • BLACKLIST_ROLE
  • USD0_MINT
  • USD0_BURN
  • EARLY_BOND_UNLOCK_ROLE
  • PEG_MAINTAINER_ROLE
  • USUAL_MINT
  • USUAL_BURN
  • USUALS_BURN
  • USUALSP_OPERATOR_ROLE
  • WITHDRAW_FEE_UPDATER_ROLE
  • FLOOR_PRICE_UPDATER_ROLE
  • USD0PP_USUAL_DISTRIBUTION_ROLE
  • USD0PP_DURATION_COST_FACTOR_ROLE
  • USD0PP_TREASURY_ALLOCATION_RATE_ROLE
  • USD0PP_TARGET_REDEMPTION_RATE_ROLE
  • TokenMapping
  • DaoCollateral.sol
  • DistributionModule.sol
  • L2Usd0PP.sol
  • AbstractContract.sol
  • ClassicalOracle.sol
  • UsualOracle.sol
  • RegistryAccess.sol
  • RegistryContract.sol
  • SwapperEngine.sol
  • USD0pp.sol
  • Usual.sol
  • UsualS.sol
  • USUALSP.sol
  • UsualX.sol
  • AirdropDistribution.sol
  • AirdropTaxCollector.sol

Was this helpful?

  1. Overview
  2. Architecture

Role Management

Role & Permissions

DEFAULT_ADMIN_ROLE

The DEFAULT_ADMIN_ROLE serves as the highest administrative authority in the system, possessing complete control over role management and critical system parameters. This role can manage all other roles, control emergency functions, configure core system parameters, and execute privileged operations across all contracts. It is typically assigned to a secure multisig wallet or governance contract and cannot be renounced to prevent system lockup. A delay of three days must be observed before granting that role to a new address.

Role Holders: Usual Multisig

  • Add USD0 RWA (TokenMapping)

  • Unpause (AirdropDistribution, AirdropTaxCollector, DaoCollateral, DistributionModule, L2Usd0, L2Usd0PP, SwapperEngine, Usd0, USD0pp, Usual, UsualS, USUALSP, UsualX)

  • Activate/Deactivate CBR (DaoCollateral)

  • Set redeem fee (DaoCollateral)

  • Redeem DAO (DaoCollateral)

  • Unpause redeem/swap (DaoCollateral)

  • Set max depeg threshold (AbstractContract)

  • Initialize token oracle (ClassicalOracle, UsualOracle)

  • Set role admin (RegistryAccess)

  • Set contract (RegistryContract)

  • Update minimum USDC amount provided (SwapperEngine)

  • Emergency withdraw (USD0pp)

PAUSING_CONTRACTS_ROLE

The PAUSING_CONTRACTS_ROLE exists as an emergency control mechanism to halt contract operations when critical issues are detected. This role has the ability to pause functionality across multiple core contracts including token transfers, airdrop distributions, DAO collateral operations, and swapper engine activities. It serves as a first line of defense against potential exploits or system anomalies.

Role Holders: Usual Multisig

  • Pause (AirdropTaxCollector, DaoCollateral, DistributionModule, L2Usd0, L2Usd0PP, SwapperEngine, Usd0, USD0pp, Usual, UsualS, USUALSP, UsualX)

NONCE_THRESHOLD_SETTER_ROLE

The NONCE_THRESHOLD_SETTER_ROLE exists to manage the nonce threshold parameters in the DAO collateral system. This role is responsible for setting and adjusting the nonce threshold that determines the validity of swap intents, helping prevent replay attacks and ensuring transaction ordering in the RWA to STBC swap process.

Role Holders: Usual Multisig

  • Set nonce threshold (DaoCollateral)

INTENT_MATCHING_ROLE

The INTENT_MATCHING_ROLE exists to facilitate secure RWA to STBC token swaps in the DAO collateral system. This role is responsible for executing swap intents by matching off-chain orders with on-chain transactions, ensuring proper order execution and token transfers between parties. The role is typically assigned to trusted swap operators or automated market makers authorized by the Usual Multisig.

Role Holders: Swapper Engine Keeper

  • Swap RWA to STBC intent (DaoCollateral)

DISTRIBUTION_OPERATOR_ROLE

The DISTRIBUTION_OPERATOR_ROLE exists to manage the daily distribution of USUAL tokens across various protocol buckets and off-chain distributions. This role is responsible for executing the core token distribution mechanics, including calculating new emissions, distributing tokens to on-chain vaults (Usual+ and Usual*), and managing the off-chain distribution queue through merkle proofs. The role is typically assigned to an automated keeper managed.

Role Holders: Google KMS Service Account (Keeper)

  • Distribute USUAL to buckets (DistributionModule)

  • Queue off-chain USUAL distribution (DistributionModule)

  • Reset off-chain distribution queue (DistributionModule)

DISTRIBUTION_ALLOCATOR_ROLE

The DISTRIBUTION_ALLOCATOR_ROLE exists to manage the core economic parameters of the USUAL token distribution system. This role is responsible for configuring the distribution mechanics by setting emission rates, bucket allocations, and key distribution parameters that determine how USUAL tokens are distributed across different protocol components. The role has significant control over the tokenomics and must be carefully managed to ensure fair and efficient token distribution. It is typically assigned to a Usual Multisig under DAO oversight.

Role Holders: Usual DAO

  • Set buckets distribution (DistributionModule)

  • Set gamma (DistributionModule)

  • Set rate min (DistributionModule)

  • Set D (DistributionModule)

  • Set M0 (DistributionModule)

DISTRIBUTION_CHALLENGER_ROLE

The DISTRIBUTION_CHALLENGER_ROLE exists as a security mechanism to ensure the integrity of off-chain USUAL token distributions. This role has the authority to challenge and invalidate potentially incorrect or malicious distributions before they are finalized. It can challenge all distributions in the queue that are older than a specified timestamp and optionally propose new valid distributions with corrected merkle roots. The role serves as a critical safeguard against distribution errors or manipulation attempts and is typically assigned to the Usual Multisig.

Role Holders: Usual Multisig

  • Challenge distribution (DistributionModule)

BLACKLIST_ROLE

The BLACKLIST_ROLE exists as a security mechanism to protect the protocol from malicious actors, comply with regulatory requirements, and ensure rapid response to security incidents. This role has the authority to restrict specific addresses from participating in token transfers and protocol operations across multiple core contracts including L2USD0, L2USD0PP, USD0PP, USD0, USUAL, USUALS, and USUALX.

Role Holders: Usual Multisig

  • Blacklist/Unblacklist (L2Usd0, L2Usd0PP, USD0pp, Usd0, Usual, UsualS, UsualX)

USD0_MINT

The USD0_MINT role exists as a critical control mechanism for managing the supply of USD0 tokens in the system. This role has the authority to mint new USD0 tokens across multiple contracts including L2USD0, L2USD0PP, and USD0, but only when there is sufficient backing in the treasury. The role is typically assigned to the DAO Collateral contract and other protocol-controlled contracts to ensure automated and secure minting operations.

Role Holders: DAO Collateral Contract, SwapperEngine

  • Mint (L2Usd0, L2Usd0PP, Usd0)

USD0_BURN

The USD0_BURN role exists as a critical control mechanism for managing the supply of USD0 tokens in the system. This role has the authority to burn USD0 tokens across multiple contracts including L2USD0, L2USD0PP, and USD0, ensuring proper supply management and redemption functionality. The role is typically assigned to the DAO Collateral contract and SwapperEngine to enable automated burning operations during redemptions and swaps.

Role Holders: DAO Collateral Contract, SwapperEngine

  • Burn (L2Usd0, L2Usd0PP, Usd0)

  • Burn from (L2Usd0, L2Usd0PP, Usd0)

EARLY_BOND_UNLOCK_ROLE

The EARLY_BOND_UNLOCK_ROLE exists to manage early bond unlocking functionality in the USD0PP (USD0 Plus Plus) contract. This role is responsible for configuring and executing early bond release mechanisms, allowing authorized entities to set up special unlock periods and allocate early unlock balances for specific bond holders.

Role Holders: Usual Multisig

  • Allocate early unlock balance (USD0pp)

  • Setup early unlock period (USD0pp)

PEG_MAINTAINER_ROLE

The PEG_MAINTAINER_ROLE exists to maintain the USD0 peg through interactions with Curve pools and peg maintenance mechanisms. This role is responsible for triggering the Par mechanism on the USD0/USD0PP Curve pools in the case the peg is broken.

Role Holders: Usual Multisig

  • Trigger PAR mechanism Curvepool (USD0pp)

  • Unwrap peg maintainer (USD0pp)

USUAL_MINT

The USUAL_MINT role exists to control the minting of new USUAL tokens. This role has the authority to mint new USUAL tokens to specified addresses, ensuring that token supply expansion follows protocol rules and economic parameters. The role is typically assigned to the Distribution Module contract to handle automated emissions and rewards distribution.

Role Holders: Distribution Module Contract

  • Mint (Usual)

USUAL_BURN

The USUAL_BURN role exists as a critical control mechanism for managing the supply of USUAL tokens in the system. This role has the authority to burn USUAL tokens from any address, ensuring proper supply management during redemptions, liquidations, or other protocol operations that require token destruction. The role is typically assigned to protocol-controlled contracts.

Role Holders: N/A

  • Burn (Usual)

  • Burn from (Usual)

USUALS_BURN

The USUALS_BURN role exists as a critical control mechanism for managing the supply of USUALS tokens in the system. This role has the authority to burn USUALS tokens from any address. The role is typically assigned to protocol-controlled contracts that need to manage USUALS token supply, particularly during staking and unstaking operations.

Role Holders: USUALSP Contract

  • Burn (UsualS)

  • Burn from (UsualS)

USUALSP_OPERATOR_ROLE

The USUALSP_OPERATOR_ROLE exists to manage the staking and allocation mechanics of the USUALS token staking program. This role is responsible for configuring initial token allocations, managing the staking process, and handling original allocation removals in the USUALSP (USUAL Staking Pool) contract. The role has significant control over the staking parameters and must be carefully managed to ensure fair distribution and proper vesting of tokens.

Role Holders: Usual Multisig

  • Allocate (USUALSP)

  • Remove original allocation (USUALSP)

  • Stake UsualS (USUALSP)

WITHDRAW_FEE_UPDATER_ROLE

The WITHDRAW_FEE_UPDATER_ROLE exists to manage withdrawal fee parameters in the UsualX contract. This role is responsible for adjusting the fees charged when users withdraw their tokens, allowing the protocol to maintain economic stability and prevent exploitation of the withdrawal mechanism.

Role Holders: Usual Multisig

  • Update withdraw fee (UsualX)

FLOOR_PRICE_UPDATER_ROLE

The FLOOR_PRICE_UPDATER_ROLE exists to manage the minimum price threshold for USD0PP tokens in the system. This role is responsible for adjusting the floor price parameter that helps maintain price stability and protect token holders from excessive devaluation. The role has the authority to update floor prices in the USD0PP contract, which directly impacts the minimum value guarantee of the token.

Role Holders: Usual Multisig

  • Update floor price (USD0pp)

USD0PP_USUAL_DISTRIBUTION_ROLE

The USD0PP_USUAL_DISTRIBUTION_ROLE exists to manage the USUAL token distribution rate per USD0PP token. This role is responsible for adjusting the distribution rate parameter that determines how much USUAL is distributed per USD0PP token.

Role Holders: Usual Multisig

  • Update usualDistributionPerUsd0pp (USD0pp)

USD0PP_DURATION_COST_FACTOR_ROLE

The USD0PP_DURATION_COST_FACTOR_ROLE exists to manage the duration cost factor that affects early redemption costs. This role is responsible for adjusting the duration cost factor parameter that helps determine the USUAL burn amount required for early redemptions.

Role Holders: Usual Multisig

  • Update durationCostFactor (USD0pp)

USD0PP_TREASURY_ALLOCATION_RATE_ROLE

The USD0PP_TREASURY_ALLOCATION_RATE_ROLE exists to manage the percentage of burned USUAL that goes to the treasury during early redemptions. This role is responsible for adjusting the treasury allocation rate in basis points.

Role Holders: Usual Multisig

  • Update treasuryAllocationRate (USD0pp)

USD0PP_TARGET_REDEMPTION_RATE_ROLE

The USD0PP_TARGET_REDEMPTION_RATE_ROLE exists to manage the daily redemption target rate for USD0PP tokens. This role is responsible for adjusting the target redemption rate (in basis points of total supply) that affects the USUAL burn calculations for early redemptions.

Role Holders: Usual Multisig

  • Update targetRedemptionRate (USD0pp)

AIRDROP_OPERATOR_ROLE

The AIRDROP_OPERATOR_ROLE is responsible for managing the core airdrop distribution parameters. This role exists to ensure secure and controlled configuration of the initial token distribution mechanism. It can set the merkle root for validating initial claims, configure maximum chargeable tax rates, and establish USD0pp prelaunch balances in the AirdropTaxCollector contract.

Role Holders: Usual Multisig

  • Set merkle root (AirdropDistribution)

  • Set max chargeable tax (AirdropTaxCollector)

  • Set USD0pp prelaunch balances (AirdropTaxCollector)

AIRDROP_PENALTY_OPERATOR_ROLE

The AIRDROP_PENALTY_OPERATOR_ROLE is responsible for managing penalty parameters in the airdrop distribution system. This role exists to enforce compliance and incentive alignment by allowing authorized entities to set penalty percentages for accounts based on off-chain criteria. It can configure penalty rates that affect user claim amounts during the vesting period.

Role Holders: Usual Multisig

  • Set penalty percentages (AirdropDistribution)

TokenMapping

  • DEFAULT_ADMIN_ROLE

    • can call addUsd0Rwa

DaoCollateral.sol

  • DEFAULT_ADMIN_ROLE

    • can call activateCBR

    • can call deactivateCBR

    • can call setRedeemFee

    • can call redeemDao

    • can call unpause

    • can call unpauseRedeem

    • can call unpauseSwap

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • NONCE_THRESHOLD_SETTER_ROLE

    • can call setNonceThreshold

  • INTENT_MATCHING_ROLE

    • can call swapRWAtoStbcIntent

DistributionModule.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • DISTRIBUTION_OPERATOR_ROLE

    • can call distributeUsualToBuckets

    • can call queueOffChainUsualDistribution

    • can call resetOffChainDistributionQueue

  • DISTRIBUTION_ALLOCATOR_ROLE

    • can call setBucketsDistribution

    • can call setGamma

    • can call setRateMin

    • can call setD

    • can call setM0

  • DISTRIBUTION_CHALLENGER_ROLE

    • can call challengeDistribution

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • BLACKLIST_ROLE

    • can call blacklist

    • can call unBlacklist

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • USD0_MINT

    • can call mint

  • USD0_BURN

    • can call burn

    • can call burnFrom

L2Usd0PP.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • USD0_MINT

    • can call mint

  • USD0_BURN

    • can call burn

    • can call burnFrom

AbstractContract.sol

  • DEFAULT_ADMIN_ROLE

    • can call setMaxDepegThreshold

ClassicalOracle.sol

  • DEFAULT_ADMIN_ROLE

    • can call initializeTokenOracle

UsualOracle.sol

  • DEFAULT_ADMIN_ROLE

    • can call initializeTokenOracle

RegistryAccess.sol

  • DEFAULT_ADMIN_ROLE

    • can call setRoleAdmin

RegistryContract.sol

  • DEFAULT_ADMIN_ROLE

    • can call setContract

SwapperEngine.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

    • can call updateMinimumUSDCAmountProvided

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • DEFAULT_ADMIN_ROLE

    • can call blacklist

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • USD0_BURN

    • can call burn

    • can call burnFrom

  • USD0_MINT

    • can call mint

  • BLACKLIST_ROLE

    • can call blacklist

    • can call unBlacklist

USD0pp.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

    • can call emergencyWithdraw

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • EARLY_BOND_UNLOCK_ROLE

    • can call allocateEarlyUnlockBalance

    • can call setupEarlyUnlockPeriod

  • PEG_MAINTAINER_ROLE

    • can call triggerPARMechanismCurvepool

    • can call unwrapPegMaintainer

  • FLOOR_PRICE_UPDATER_ROLE

    • can call updateFloorPrice

  • USD0PP_USUAL_DISTRIBUTION_ROLE

    • can call setUsualDistributionPerUsd0pp

  • USD0PP_DURATION_COST_FACTOR_ROLE

    • can call setDurationCostFactor

  • USD0PP_TREASURY_ALLOCATION_RATE_ROLE

    • can call setTreasuryAllocationRate

  • USD0PP_USUAL_BURN_TARGET_REDEMPTION_ROLE

    • can call setTargetRedemptionRate

Usual.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • BLACKLIST_ROLE

    • can call blacklist

    • can call unBlacklist

  • USUAL_MINT

    • can call mint

  • USUAL_BURN

    • can call burn

    • can call burnFrom

UsualS.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • BLACKLIST_ROLE

    • can call blacklist

    • can call unBlacklist

  • USUALS_BURN

    • can call burn

    • can call burnFrom

USUALSP.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • USUALSP_OPERATOR_ROLE

    • can call allocate

    • can call removeOriginalAllocation

    • can call stakeUsualS

UsualX.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • PAUSING_CONTRACTS_ROLE

    • can call pause

  • BLACKLIST_ROLE

    • can call blacklist

    • can call unBlacklist

  • WHITELIST_ROLE

    • can call whitelist

    • can call unWhitelist

  • WITHDRAW_FEE_UPDATER_ROLE

    • can call updateWithdrawFee

AirdropDistribution.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • AIRDROP_OPERATOR_ROLE

    • can call setMerkleRoot

  • AIRDROP_PENALTY_OPERATOR_ROLE

    • can call setPenaltyPercentages

  • PAUSING_CONTRACTS_ROLE

AirdropTaxCollector.sol

  • DEFAULT_ADMIN_ROLE

    • can call unpause

  • AIRDROP_OPERATOR_ROLE

    • can call setMaxChargeableTax

    • can call setUsd0ppPrelaunchBalances

  • PAUSING_CONTRACTS_ROLE

    • can call pause

PreviousArchitectureNextUSUAL Distribution Model

Last updated 12 days ago

Was this helpful?

🔭