Technical Requirements

This project has been developed using Foundry as the primary development environment. You can refer to the README file within the repo for instructions on how to build, test, and deploy the contracts.

Repository

Arcana-Finance

Contracts

arcUSD

src/arcUSD.sol

Description

ERC-20 contract that extends `LayerZeroRebaseTokenUpgradeable` to support cross chain bridging and rebasing. This token can only be minted by the arcUSDMinter and arcUSDTaxManager.

Key Features

setRebaseIndex

function setRebaseIndex(uint256 newIndex, uint256 nonce) external;

Allows the RebaseManager and TaxManager roles to update the `rebaseIndex`. The `rebaseIndex` is a multiplier used to determine the post-balance and post-totalSupply for the rebase token.

• Only callable by RebaseManager or TaxManager

• newIndex cannot be 0

• If caller is RebaseManager, arcUSDTaxManager::collectOnRebase is executed

disableRebase

function disableRebase(address account, bool isDisabled) external;

This method disables rebaseIndex multiplier for a given address. If an address has disabled rebase (aka “opted out”), their balance will not be affected rebases.

• Only callable by RebaseManager or the address being opted out.

setSupplyLimit

function setSupplyLimit(uint256 limit) external;

Allows the owner to set a ceiling on arcUSD total supply to throttle minting.

arcUSDMinter

src/arcUSDMinter.sol

Description

arcUSDMinter facilitates the minting and redemption process of arcUSD tokens against various supported assets. It allows for adding and removing assets and custodians, minting arcUSD by depositing assets, and requesting redemption of arcUSD for assets. The contract uses a delay mechanism for redemptions to enhance security and manages custody transfers of assets to designated custodians.

Key Features

withdrawFunds

function withdrawFunds(address asset, uint256 amount) external;

Allows the custodian to withdraw collateral from this contract. This function takes into account the required assets and only allows the custodian to claim the difference between what is required and the balance in this contract assuming the balance is greater than what is required. “Required” collateral refers to the collateral in the contract that is not being used to fulfill redemptions.

• Only callable by the CustodianManager address

addSupportedAsset

function addSupportedAsset(address asset, address oracle) external;

Adds a new asset to the list of supported assets for minting arcUSD. This function marks an asset as supported and disables rebasing for it if applicable. Only callable by the contract owner. It's essential for expanding the range of assets that can be used to mint arcUSD. Attempts to disable rebasing for the asset by calling `disableInitializers` on the asset contract. This is a safety measure for assets that implement a rebase mechanism.

• Only callable by the owner

removeSupportedAsset

function removeSupportedAsset(address asset) external;

Removes an asset from the list of supported assets for minting arcUSD, making it ineligible for future operations until restored. This function allows the contract owner to temporarily remove an asset from the list of supported assets. Removed assets can be restored using the `restoreAsset` function. It is crucial for managing the lifecycle and integrity of the asset pool.

• Only callable by the owner

mint

function mint(address asset, uint256 amountIn, uint256 minAmountOut) external;

Mints arcUSD tokens in exchange for a specified amount of a supported asset, which is directly transferred to the custodian. This function facilitates a user to deposit a supported asset directly to the custodian and receive arcUSD tokens in return. The function ensures the asset is supported and employs non-reentrancy protection to prevent double spending. The actual amount of arcUSD minted equals the asset amount received by the custodian, which may vary due to transaction fees or adjustments. The asset is pulled from the user to the custodian directly, ensuring transparency and traceability of asset transfer.

• Only callable by addresses that are whitelisted. Whitelisted wallets must go through a KYC system in order to participate here.

• Fetches the latest oracle price of `asset` to calculate the amount of arcUSD to mint.

requestTokens

function requestTokens(address asset, uint256 amount) external;

Requests the redemption of arcUSD tokens for a specified amount of a supported asset. Allows users to burn arcUSD tokens in exchange for a claim on a specified amount of a supported asset, after a delay defined by `claimDelay`. The request is recorded and can be claimed after the delay period. This function employs non-reentrancy protection and checks that the asset is supported. It burns the requested amount of arcUSD from the user's balance immediately.

• Only callable by addresses that are whitelisted. Whitelisted wallets must go through a KYC system in order to participate here.

• Fetches the latest oracle price of `asset` to calculate the amount of collateral to let the user claim for the amount of arcUSD being burned.

setRedemptionCap

function setRedemptionCap(address asset, uint256 cap) external;

Allows the owner to set the redemption cap for a given asset. If the redemptionCap is met via pendingClaims redemption requests will be briefly halted until pending claims have been claimed.

• Can only be called by owner

claimTokens

function claimableTokens(address user, address asset) external;

Claims the requested supported assets in exchange for previously burned arcUSD tokens, if the claim delay has passed. This function allows users to claim supported assets for which they have previously made redemption requests and the claim delay has elapsed. Uses `_unsafeRedemptionRequestByAssetAccess` to access redemption requests directly in storage, optimizing gas usage.

• Only callable by addresses that are whitelisted. Whitelisted wallets must go through a KYC system in order to participate here.

• Partial claims are not allowed. If a request is made and the claim delay has elapsed, the entire request must be claimed.

extendClaimTimestamp

function extendClaimTimestamp(address user, address asset, uint256 index, uint48 newClaimableAfter) external;

Extends the claimable after timestamp for a specific redemption request. Allows the custodian to delay the claimability of assets for a particular redemption request. This can be used in scenarios where additional time is needed before the assets can be released or in response to changing conditions affecting the asset or market stability. This action updates both the general and asset-specific redemption request entries to ensure consistency across the contract's tracking mechanisms.

• Only callable by Admin role or owner

setCoverageRatio

function setCoverageRatio(uint256 ratio) external;

This method allows the admin to update the coverageRatio. The coverageRatio cannot be greater than 1e18. In the event the protocol's collateral is less than the amount needed to fund 100% of requests, this ratio would be set to sub-1e18 until the protocol goes back to 100%. Only used in very serious cases where the overall amount of collateral goes below the amount needed to fund all outstanding requests.

• Only callable by Admin role or owner

setMaxAge

function setMaxAge(uint256 newMaxAge) external;

This method allows the owner to update the maxAge. The `maxAge` is the maximum amount of time allowed to elapse from the last time a collateral’s oracle has been updated before being deemed “stale” and therefore halting mints and redemptions.

• Only callable by the owner

arcUSDTaxManager

src/arcUSDTaxManager.sol

Description

This contract manages the taxation of rebases on the arcUSD token. This contract facilitates the rebase of arcUSD and during rebase, will calculate an amount of arcUSD to mint to the `feeCollector` and thus re-calculating the rebaseIndex to result in the targeted post-rebase totalSupply with the newly minted tokens in mind.

Key Features

collectOnRebase

function collectOnRebase(uint256 currentIndex, uint256 nextIndex) external;

This method facilitates the taxed rebase of arcUSD. It calculates the new total supply, given `nextIndex`. It then takes a tax by minting a percentage of the total supply delta and then calculates a new rebaseIndex.

• Only callable by arcUSD token

arcUSDFeeCollector

src/arcUSDFeeCollector.sol

Description

This contract receives arcUSD from rebase fees and distributes them to the necessary addresses.

Key Features

distributearcUSD

function distributearcUSD() external;

This method is used to distribute arcUSD rewards from this contract to the various addresses stored in the `distributors` array. This method is not permissioned aka it can be called by any address.

arcUSDPointsBoostingVault

src/arcUSDPointsBoostingVault.sol

Description

This contract represents a points-based system for arcUSD token holders. By depositing arcUSD tokens, users receive PTa tokens, which can be redeemed back to arcUSD. This mechanism effectively disables rebase functionality for arcUSD within this system.

Key Features

deposit

function deposit(uint256 assets, address recipient) external returns (uint256 shares);

Deposits arcUSD tokens into the vault in exchange for PTa tokens. Mints PTa tokens to the recipient equivalent to the amount of arcUSD tokens deposited.

• Returns the amount of PTa tokens minted to msg.sender

redeem

function redeem(uint256 shares, address recipient) external returns (uint256 assets);

Redeems PTa tokens in exchange for arcUSD tokens. Burns the PTa tokens from the sender and returns the equivalent amount of arcUSD tokens.

• Returns the amount of arcUSD tokens returned to msg.sender

previewRedeem

function previewRedeem(address from, uint256 shares) external view returns (uint256 assets);

Provides a preview of arcUSD assets for a given amount of PTa shares to be redeemed. Accounts for the user's rebase opt-out status. If opted out, a 1:1 ratio is used. Otherwise, rebase adjustments apply.

CustodianManager

src/CustodianManager.sol

Description

This contract will withdraw from the arcUSDMinter contract and transfer collateral to the multisig custodian.

Key Features

withdrawable

function withdrawable(address asset) public view returns (uint256);

This view method returns the amount of assets that can be withdrawn from the arcUSDMinter contract. This method takes into account the amount of tokens the arcUSDMinter contract needs to fulfill pending claims and therefore is subtracted from what is withdrawable from the balance. If the amount of required tokens (to fulfill pending claims) is greater than or equal to the contract’s total balance, withdrawable will return 0.

withdrawFunds

function withdrawFunds(address asset, uint256 amount) external;

This method will withdraw assets from the arcUSDMinter contract and transfer it to the custodian address.

• Will only withdraw up to what `withdrawable` returns

• Only callable by a gelato task or owner