Detailed Withdrawal Flow with State Transitions

Detailed Withdrawal Flow with State Transitions

State Transition Analysis:

1. UNKNOWN → PROCESSING

   • Triggered by: authorizeWithdraw() call from WITHDRAW_AUTHORITY_ROLE

   • Requirements: Valid WithdrawMessage, contract not paused

   • State data stored: Message hash, start time, message details

   • Events emitted: WithdrawAuthorized

   • This transition initiates the withdrawal process and starts the fraud window

2. PROCESSING → PENDING

   • Triggered by: Time passage (fraud window duration)

   • No explicit function call required

   • The status is calculated dynamically based on current time vs. start time + fraud window

   • This transition occurs automatically after the fraud window expires

   • It indicates that the withdrawal is ready to be claimed

3. PENDING → CLOSED

   • Triggered by: claimWithdraw() call from user

   • Requirements: Fraud window expired, valid message

   • State changes: Message status set to CLOSED

   • Actions: ETH transferred from Treasury to user

   • Events emitted: WithdrawClaimed

   • This transition completes the withdrawal process

4. PROCESSING → CLOSED (Cancellation)

   • Triggered by: deleteWithdrawMessage() call from WITHDRAW_CANCELLER_ROLE

   • Requirements: Message in PROCESSING state

   • State changes: Message deleted

   • Events emitted: WithdrawCancelled

   • This transition cancels a suspicious withdrawal during the fraud window

State Management

The CanonicalBridge contract manages withdrawal states using an enum and a mapping:

enum WithdrawStatus { UNKNOWN, PROCESSING, PENDING, CLOSED }

mapping(bytes32 => WithdrawMessageInfo) private withdrawMessages;

struct WithdrawMessageInfo {
    uint256 startTime;
    WithdrawMessage message;
}

State Calculation Logic:

function getWithdrawStatus(bytes32 messageHash) public view returns (WithdrawStatus) {
    WithdrawMessageInfo storage info = withdrawMessages[messageHash];
    
    if (info.startTime == 0) {
        return WithdrawStatus.UNKNOWN;
    }
    
    if (withdrawalClosed[messageHash]) {
        return WithdrawStatus.CLOSED;
    }
    
    if (block.timestamp >= info.startTime + fraudWindowDuration) {
        return WithdrawStatus.PENDING;
    }
    
    return WithdrawStatus.PROCESSING;
}

This function calculates the current status of a withdrawal based on its state data. The status is determined by:

• If the withdrawal doesn't exist (startTime is 0), it's UNKNOWN

• If the withdrawal has been explicitly closed, it's CLOSED

• If the fraud window has expired, it's PENDING

• Otherwise, it's still in PROCESSING

This dynamic calculation approach allows for efficient state management without requiring explicit state transitions for time-based changes.

Key Operations

Deposit Operation - Technical Implementation

The deposit function in the CanonicalBridge contract:

function deposit(bytes32 recipient, uint256 amountWei)
    external
    payable
    virtual
    override
    whenNotPaused
    bytes32Initialized(recipient)
    validDepositAmount(amountWei)
    nonReentrant
{
    bool success;
    (success,) = payable(address(TREASURY)).call{value: amountWei}(abi.encodeWithSignature("depositEth()"));
    if (!success) revert CanonicalBridgeTransactionRejected(0, "failed to transfer funds to the treasury");

    // Emit deposit message
    uint256 amountLamports = amountWei / WEI_PER_LAMPORT;
    emit Deposited(msg.sender, recipient, amountWei, amountLamports);
}

This function handles the deposit process, validating the parameters, transferring ETH to the Treasury, and emitting an event for L2 processing. The modifiers ensure that the function is non-reentrant, can only be called when the contract is not paused, and validates the deposit parameters.

The deposit validation modifier:

modifier validDepositAmount(uint256 amountWei) {
    if (msg.value != amountWei) revert CanonicalBridgeTransactionRejected(0, "Deposit amount mismatch");
    if (msg.value % WEI_PER_LAMPORT != 0) revert CanonicalBridgeTransactionRejected(0, "Fractional value not allowed");
    if (msg.value < MIN_DEPOSIT) revert CanonicalBridgeTransactionRejected(0, "Deposit less than minimum");
    _;
}

This modifier validates the deposit parameters, ensuring that the deposit amount meets the minimum requirement, and the sent ETH matches the specified amount. These validations prevent common errors and potential attacks.

Withdrawal Operation - Technical Implementation

The withdrawal authorization function:

function _authorizeWithdraw(
    WithdrawMessage memory message
)
    private
    validWithdrawMessage(message)
{
    bytes32 messageHash = withdrawMessageHash(message);
    uint256 messageStartTime = block.timestamp + fraudWindowDuration;

    /// @dev CanonicalBridgeV1 replay protection.
    if ((ICanonicalBridge(CANONICAL_BRIDGE_V1).withdrawMsgIdProcessed(message.withdrawId) != 0)) {
        revert CanonicalBridgeTransactionRejected(message.withdrawId, "Message replay protection");
    }

    /// @dev This would occur if the relayer passed the same message twice.
    if (withdrawMessageStatus(messageHash) != WithdrawStatus.UNKNOWN) {
        revert CanonicalBridgeTransactionRejected(message.withdrawId, "Message already exists");
    }
    /// @dev This would only occur if the same message Id was used for two different messages.
    if (withdrawMsgIdProcessed[message.withdrawId] != 0) {
        revert CanonicalBridgeTransactionRejected(message.withdrawId, "Message Id already exists");
    }
    startTime[messageHash] = messageStartTime;
    withdrawMsgIdProcessed[message.withdrawId] = block.number;

    emit WithdrawAuthorized(
        msg.sender,
        message,
        messageHash,
        messageStartTime
    );
}

This function authorizes a withdrawal, validating the message, storing the withdrawal information, and emitting an event. The modifiers ensure that only entities with the WITHDRAW_AUTHORITY_ROLE can call this function, it can only be called when the contract is not paused, and the withdrawal message is valid.

The claim withdrawal function:

function claimWithdraw(
    WithdrawMessage calldata message
)
    external
    override
    whenNotPaused
    nonReentrant
    validWithdrawMessage(message)
{
    bool authorizedWithdrawer = (msg.sender == message.destination || hasRole(CLAIM_AUTHORITY_ROLE, msg.sender));
    if (!authorizedWithdrawer) {
        revert IAccessControl.AccessControlUnauthorizedAccount(msg.sender, CLAIM_AUTHORITY_ROLE);
    }

    bytes32 messageHash = withdrawMessageHash(message);
    if (withdrawMessageStatus(messageHash) != WithdrawStatus.PENDING) revert WithdrawUnauthorized();

    startTime[messageHash] = NEVER;
    emit WithdrawClaimed(message.destination, message.from, messageHash, message);

    /// @dev Transfer amountWei - feeWei to recipient.
    bool success = ITreasury(TREASURY).withdrawEth(
        message.destination,
        message.amountWei - message.feeWei
    );

    /// @dev The following condition should never occur and the error should be unreachable code.
    if (!success) revert WithdrawFailed();

    /// @dev Transfer feeWei to fee receiver.
    success = ITreasury(TREASURY).withdrawEth(
        message.feeReceiver,
        message.feeWei
    );

    /// @dev The following condition should never occur and the error should be unreachable code.
    if (!success) revert WithdrawFailed();
}

This function allows users to claim their withdrawal after the fraud window has expired. It verifies that the withdrawal is in the PENDING state, marks it as CLOSED, handles fee distribution if applicable, and transfers the ETH to the destination address. The modifiers ensure that the function is non-reentrant and can only be called when the contract is not paused.

Administrative Operations - Technical Examples