USD0a Gateway

High-Level Overview

The Gateway contract is a fully permissioned smart contract designed to manage intermediary treasury operations between the protocol's collateral treasury and external collateral services such as Superstate and Circle. The contract facilitates the conversion of USDC tokens (from Circle) to USCC tokens (from Superstate) through an order-based tracking system, enabling the protocol to rebalance treasury collaterals efficiently.

The main objective of the Gateway contract is to provide a secure, auditable, and controlled mechanism for interacting with external collateral services while maintaining USD0a price stability through the DebtUSDC token system. When the protocol needs to switch some USDC to USCC, the Gateway manages these operations by tracking deposits and withdrawals through orders. Critically, the Gateway mints DebtUSDC tokens when USDC is sent to Superstate to prevent USD0a price from decreasing while waiting for USCC, since USD0a price depends on the amount of collaterals in the treasury.

Key Use Case: The Gateway is primarily used for treasury rebalancing operations. For example, if the protocol wants to convert USDC to USCC, an authorized operator can deposit USDC through the Gateway, which transfers the USDC to the Superstate contract. The Gateway then mints DebtUSDC tokens (1:1 with the USDC amount) to maintain USD0a price stability. This is critical because USD0a price depends on the amount of collaterals in the treasury. Without minting DebtUSDC, the USD0a price would decrease when USDC is sent to Superstate (reducing treasury collateral) while waiting for USCC. By minting DebtUSDC, the protocol maintains the accounting balance, preventing USD0a price from decreasing during the conversion process. When USCC is received from Superstate, the operator can withdraw through the Gateway, which burns the corresponding DebtUSDC tokens and transfers the USCC to the collateral treasury, replacing the debt token with actual collateral.

Contract Summary

The contract provides the following main functions:

deposit: Allows authorized users to deposit USDC tokens, transfer them to the Superstate contract, and create a tracking order. This function also mints DebtUSDC tokens (1:1 with USDC) to the collateral treasury to maintain USD0a price stability. Without this minting, the USD0a price would decrease because it depends on the amount of collaterals in the treasury, and USDC is temporarily reduced while waiting for USCC.
withdraw: Allows authorized users to withdraw USCC tokens by burning the corresponding DebtUSDC tokens for specified orders. The function accepts a usccAmount parameter because the exact amount received from Superstate cannot be predicted.
emergencyWithdraw: Provides an emergency mechanism to recover tokens that may have been accidentally sent to the contract.
setSuperstateAddress: Allows authorized users to update the Superstate contract address, enabling the protocol to adapt to contract upgrades or migrations.

The contract also includes utility functions such as getOrder, getNextOrderId, superstate, and collateralTreasury to retrieve order details and contract configuration.

The Gateway uses an order-based system to track deposits and withdrawals. Each deposit creates an order that stores the USDC amount, active status, and timestamp. Orders are deactivated during withdrawal to prevent double-spending. The DebtUSDC token system ensures that USD0a price stability is maintained during collateral conversion operations. When USDC is sent to Superstate, the treasury temporarily loses collateral, which would cause USD0a price to decrease. By minting DebtUSDC tokens (1:1 with the USDC amount), the protocol maintains the accounting balance, preventing USD0a price from decreasing while waiting for USCC. When USCC is received and DebtUSDC is burned, the actual collateral replaces the debt token.

Inherited Contracts

Initializable (OZ): Used to provide a safe and controlled way to initialize the contract's state variables. It ensures that the contract's initializer function can only be called once, preventing accidental or malicious reinitialization.

ReentrancyGuardUpgradeable (OZ): Used to protect against reentrancy attacks. It provides a modifier that can be applied to functions to prevent them from being called recursively or from being called from other functions that are also protected by the same guard.

PausableUpgradeable (OZ): Allows contract functionality to be paused by authorized accounts (PAUSING_CONTRACTS_ROLE to pause the contract and UNPAUSING_CONTRACTS_ROLE to unpause).

Functionality Breakdown

The Gateway contract's primary purpose is to facilitate treasury rebalancing operations by managing interactions with external collateral services. The contract's functionality can be broken down into the following key components:

Order Creation (Deposit):

Users with the GATEWAY_DEPOSIT_ROLE can create new orders by calling the deposit function and specifying the amount of USDC tokens to deposit.

The contract transfers the specified amount of USDC tokens from the caller directly to the Superstate contract (not to the Gateway contract itself).

The contract creates a new order with a unique order ID, storing the USDC amount, active status (set to true), and the current block timestamp.

The contract mints DebtUSDC tokens (1:1 with the USDC amount) to the collateral treasury. The debt token maintains the accounting balance until USCC is received and replaces it.

The order is assigned a unique order ID (starting from 1) and stored in the contract's orders mapping.

Order Fulfillment (Withdraw):

Users with the GATEWAY_WITHDRAW_ROLE can fulfill orders by calling the withdraw function and specifying an array of order IDs to process and the amount of USCC tokens to withdraw.

The contract validates that all specified orders are active and exist.

For each order, the contract deactivates the order (sets active to false) to prevent double-spending.

The contract burns DebtUSDC tokens from the collateral treasury (1:1 with each order's USDC amount). This clears the protocol's obligation for the fulfilled orders.

The contract transfers the specified amount of USCC tokens from the Gateway contract to the collateral treasury.

Important: The usccAmount parameter is provided by the caller because the exact amount of USCC received from Superstate cannot be predicted in advance. This allows the protocol to handle variable exchange rates, fees, or other factors that may affect the final amount received from external services.

DebtUSDC Accounting:

The Gateway uses the DebtUSDC token system to maintain USD0a price stability during collateral conversion operations. When USDC is deposited and sent to Superstate, the treasury temporarily loses USDC collateral. Since USD0a price depends on the amount of collaterals in the treasury, this reduction would cause USD0a price to decrease. To prevent this, DebtUSDC tokens are minted (1:1 with the USDC amount) to maintain the accounting balance. This ensures that USD0a price remains stable while waiting for USCC from Superstate. When USCC is received and withdrawn, the corresponding DebtUSDC tokens are burned, and the actual USCC collateral replaces the debt token. This mechanism ensures that USD0a price stability is maintained throughout the entire conversion process, even when interacting with third-party services that may have processing delays.

External Integration:

The Gateway integrates with the Superstate contract for USDC transfers and USCC redemptions. USDC (from Circle) is transferred directly to the Superstate contract during deposits, and USCC is expected to be received from Superstate before withdrawals can be processed. The Gateway also integrates with the Registry system to access the DebtUSDC contract, collateral treasury address, and access control mechanisms.

Security Analysis

Method: deposit

This method allows authorized users to deposit USDC tokens, transfer them to the Superstate contract, create a tracking order, and mint DebtUSDC tokens to the collateral treasury.

Function Description:

The function is protected against reentrancy attacks by using the nonReentrant modifier, ensuring that the function cannot be called recursively or from other functions that are also protected by the same guard.
The function is protected by the whenNotPaused modifier, ensuring that deposits cannot be made when the contract is paused.
Validates that the USDC amount is greater than zero.
Validates that the caller has the GATEWAY_DEPOSIT_ROLE using role-based access control.
Sets the value of orderId to the current value of $.nextOrderId then increments by 1. Since it is initialized as 1, the first orderId will be one and so on.
Creates a new GatewayOrder struct in storage using the order ID as key. The struct contains: the USDC amount, the active flag set to true, and the current block timestamp.
Transfers the specified amount of USDC tokens from the caller directly to the Superstate contract (not to the Gateway contract) using safeTransferFrom to ensure that the transfer is successful. If the transfer fails, the function will revert.
Mints DebtUSDC tokens (1:1 with the USDC amount) to the collateral treasury. This is critical for maintaining USD0a price stability. Since USD0a price depends on the amount of collaterals in the treasury, and USDC is temporarily reduced while waiting for USCC from Superstate, minting DebtUSDC prevents the USD0a price from decreasing during the conversion process. The debt token maintains the accounting balance until USCC is received and replaces it.
Emits a Deposit event, providing the caller address, order ID, and USDC amount for tracking.

Method: withdraw

This method allows authorized users to withdraw USCC tokens by burning the corresponding DebtUSDC tokens for specified orders and transferring USCC to the collateral treasury.

Function Description:

The function is protected against reentrancy attacks by using the nonReentrant modifier.
The function is protected by the whenNotPaused modifier, ensuring that withdrawals cannot be made when the contract is paused.
Validates that at least one order ID is provided (orderIds.length > 0).
Validates that the USCC amount is greater than zero.
Validates that the caller has the GATEWAY_WITHDRAW_ROLE using role-based access control.
Iterates through the provided order IDs and validates that each order is active. If any order is not active or does not exist, the function will revert with an appropriate error message. This prevents any attempts to withdraw from invalid or already processed orders.
For each order, deactivates the order by setting the active flag to false in storage. This prevents double-spending and ensures that orders can only be processed once.
Burns DebtUSDC tokens from the collateral treasury (1:1 with each order's USDC amount). This clears the protocol's obligation for the fulfilled orders and ensures proper accounting.
Accumulates the total debt tokens burned across all orders for event emission.
Transfers the specified amount of USCC tokens from the Gateway contract to the collateral treasury using the safeTransfer function. This ensures that the transfer is successful. If the transfer fails, the function will revert.
Important: The usccAmount parameter is provided by the caller because the exact amount of USCC received from Superstate cannot be predicted in advance. This allows the protocol to handle variable exchange rates, fees, or other factors that may affect the final amount received from external services.
Emits a Withdraw event, providing the caller address, order IDs, total debt tokens burned, and USCC amount for tracking.

Method: emergencyWithdraw

This method provides an emergency mechanism to recover tokens that may have been accidentally sent to the Gateway contract.

Function Description:

The function is protected against reentrancy attacks by using the nonReentrant modifier.
Validates that the token address is not the zero address.
Validates that the recipient address is not the zero address.
Validates that the amount is greater than zero.
Validates that the caller has the EMERGENCY_WITHDRAW_ROLE using role-based access control.
Transfers the specified amount of tokens from the Gateway contract to the recipient using the safeTransfer function. This ensures that the transfer is successful. If the transfer fails, the function will revert.
Emits an EmergencyWithdraw event, providing the token address, amount, and recipient for tracking.

Method: setSuperstateAddress

This method allows authorized users to update the Superstate contract address, enabling the protocol to adapt to contract upgrades or migrations.

Function Description:

Validates that the new Superstate address is not the zero address.
Validates that the new Superstate address is different from the current address to prevent unnecessary state changes.
Validates that the caller has the GATEWAY_SUPERSTATE_SETTER_ROLE using role-based access control.
Updates the Superstate address in storage.
Emits a SuperstateUpdated event, providing the old and new Superstate addresses for tracking.

Getter Functions

getOrder: Returns the details of a specific order including USDC amount, active status, and timestamp.

getNextOrderId: Returns the next order ID that will be assigned.

superstate: Returns the current Superstate contract address.

collateralTreasury: Returns the current collateral treasury address.

Constants

CONTRACT_REGISTRY_ACCESS: Address of the registry access contract.

CONTRACT_DEBT_USDC: Address of the DebtUSDC token contract.

CONTRACT_TREASURY: Address of the collateral treasury contract.

GATEWAY_DEPOSIT_ROLE: Role identifier for depositing USDC and creating orders.

GATEWAY_WITHDRAW_ROLE: Role identifier for withdrawing USCC and fulfilling orders.

EMERGENCY_WITHDRAW_ROLE: Role identifier for emergency token recovery.

GATEWAY_SUPERSTATE_SETTER_ROLE: Role identifier for updating the Superstate address.

PAUSING_CONTRACTS_ROLE: Role identifier for pausing contract operations.

UNPAUSING_CONTRACTS_ROLE: Role identifier for unpausing contract operations.

Safeguards Implementation

Pausability: Allows pausing of contract functionality in emergencies. The contract can be paused by PAUSING_CONTRACTS_ROLE and unpaused by UNPAUSING_CONTRACTS_ROLE.

Reentrancy Protection: Uses OpenZeppelin's ReentrancyGuard to prevent reentrancy attacks. All state-changing functions are protected with the nonReentrant modifier.

Access Control: Restricts sensitive operations to authorized roles. Deposit operations require GATEWAY_DEPOSIT_ROLE, withdrawal operations require GATEWAY_WITHDRAW_ROLE, emergency withdrawals require EMERGENCY_WITHDRAW_ROLE, and Superstate address updates require GATEWAY_SUPERSTATE_SETTER_ROLE.

Amount Validation: Validates that amounts are non-zero and that order arrays are not empty before processing operations.

Order Validation: Validates that orders are active before processing withdrawals, preventing attempts to process invalid or already processed orders.

Null Address Checks: Validates that all addresses (registry, Superstate, tokens, recipient) are not the zero address before processing operations.

Order Deactivation: Deactivates orders during withdrawal to prevent double-spending and ensure that orders can only be processed once.

SafeERC20: Uses SafeERC20 for all token transfers to prevent failures from going unnoticed and to handle non-standard ERC20 implementations safely.

Storage Safety: Uses ERC-7201 namespaced storage pattern (GatewayStorageV0) to prevent storage collisions during upgrades. The contract is upgradeable via UUPS proxy pattern.

Same Value Protection: Prevents unnecessary state changes by validating that the new Superstate address is different from the current address before updating.

PreviousUSD0a SwapperEngine NextETH0

Last updated 10 days ago

Was this helpful?