@evvm/testnet-contracts 2.3.0 → 3.0.1

package/contracts/treasuryTwoChains/TreasuryExternalChainStation.sol

@@ -3,53 +3,35 @@
 
 pragma solidity ^0.8.0;
 
-/**
- _____                                                       
-/__   \_ __ ___  __ _ ___ _   _ _ __ _   _                   
-  / /\| '__/ _ \/ _` / __| | | | '__| | | |                  
- / /  | | |  __| (_| \__ | |_| | |  | |_| |                  
- \/   |_|  \___|\__,_|___/\__,_|_|   \__, |                  
-                                     |___/                   
-   ___ _           _       __ _        _   _                 
-  / __| |__   __ _(_)_ __ / _| |_ __ _| |_(_) ___  _ __      
- / /  | '_ \ / _` | | '_ \\ \| __/ _` | __| |/ _ \| '_ \     
-/ /___| | | | (_| | | | | _\ | || (_| | |_| | (_) | | | |    
-\____/|_| |_|\__,_|_|_| |_\__/\__\__,_|\__|_|\___/|_| |_|    
-                                                             
-                                                             
-                                                             
- _____ _____ _____ _____ _____ _____ _____ _____ _____ _____ 
-|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|
-                                                             
-    ______     __                        __        __          _     
-   / _____  __/ /____  _________  ____ _/ /  _____/ /_  ____ _(_____ 
-  / __/ | |/_/ __/ _ \/ ___/ __ \/ __ `/ /  / ___/ __ \/ __ `/ / __ \
- / /____>  </ /_/  __/ /  / / / / /_/ / /  / /__/ / / / /_/ / / / / /
-/_____/_/|_|\__/\___/_/  /_/ /_/\__,_/_/   \___/_/ /_/\__,_/_/_/ /_/ 
-                                                                      
- * @title Treasury Cross-Chain Host Station Contract
- * @author Mate labs
- */
-
-import {IERC20} from "@evvm/testnet-contracts/library/primitives/IERC20.sol";
 import {
-    ErrorsLib
-} from "@evvm/testnet-contracts/contracts/treasuryTwoChains/lib/ErrorsLib.sol";
+    CrossChainTreasuryError as Error
+} from "@evvm/testnet-contracts/library/errors/CrossChainTreasuryError.sol";
 import {
-    ExternalChainStationStructs
-} from "@evvm/testnet-contracts/contracts/treasuryTwoChains/lib/ExternalChainStationStructs.sol";
-
-import {SafeTransferLib} from "@solady/utils/SafeTransferLib.sol";
-
+    TreasuryCrossChainHashUtils as Hash
+} from "@evvm/testnet-contracts/library/utils/signature/TreasuryCrossChainHashUtils.sol";
 import {
-    SignatureUtils
-} from "@evvm/testnet-contracts/contracts/treasuryTwoChains/lib/SignatureUtils.sol";
+    ExternalChainStationStructs as Structs
+} from "@evvm/testnet-contracts/library/structs/ExternalChainStationStructs.sol";
 import {
     PayloadUtils
 } from "@evvm/testnet-contracts/contracts/treasuryTwoChains/lib/PayloadUtils.sol";
 
-import {IMailbox} from "@hyperlane-xyz/core/contracts/interfaces/IMailbox.sol";
+import {CoreError} from "@evvm/testnet-contracts/library/errors/CoreError.sol";
 
+import {
+    SignatureRecover
+} from "@evvm/testnet-contracts/library/primitives/SignatureRecover.sol";
+import {
+    ProposalStructs
+} from "@evvm/testnet-contracts/library/utils/governance/ProposalStructs.sol";
+import {
+    AdvancedStrings
+} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
+
+import {IERC20} from "@evvm/testnet-contracts/library/primitives/IERC20.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {SafeTransferLib} from "@solady/utils/SafeTransferLib.sol";
+import {IMailbox} from "@hyperlane-xyz/core/contracts/interfaces/IMailbox.sol";
 import {
     MessagingParams,
     MessagingReceipt
@@ -65,8 +47,6 @@ import {
 import {
     OptionsBuilder
 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";
-import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
-
 import {
     AxelarExecutable
 } from "@axelar-network/axelar-gmp-sdk-solidity/contracts/executable/AxelarExecutable.sol";
@@ -76,39 +56,67 @@ import {
 import {
     IInterchainGasEstimation
 } from "@axelar-network/axelar-gmp-sdk-solidity/contracts/interfaces/IInterchainGasEstimation.sol";
-import {
-    AdvancedStrings
-} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
+
+
+/**
+ _____                                                       
+/__   \_ __ ___  __ _ ___ _   _ _ __ _   _                   
+  / /\| '__/ _ \/ _` / __| | | | '__| | | |                  
+ / /  | | |  __| (_| \__ | |_| | |  | |_| |                  
+ \/   |_|  \___|\__,_|___/\__,_|_|   \__, |                  
+                                     |___/                   
+   ___ _           _       __ _        _   _                 
+  / __| |__   __ _(_)_ __ / _| |_ __ _| |_(_) ___  _ __      
+ / /  | '_ \ / _` | | '_ \\ \| __/ _` | __| |/ _ \| '_ \     
+/ /___| | | | (_| | | | | _\ | || (_| | |_| | (_) | | | |    
+\____/|_| |_|\__,_|_|_| |_\__/\__\__,_|\__|_|\___/|_| |_|    
+                                                             
+                                                             
+                                                             
+ _____ _____ _____ _____ _____ _____ _____ _____ _____ _____ 
+|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|
+                                                             
+    ______     __                        __        __          _     
+   / _____  __/ /____  _________  ____ _/ /  _____/ /_  ____ _(_____ 
+  / __/ | |/_/ __/ _ \/ ___/ __ \/ __ `/ /  / ___/ __ \/ __ `/ / __ \
+ / /____>  </ /_/  __/ /  / / / / /_/ / /  / /__/ / / / /_/ / / / / /
+/_____/_/|_|\__/\___/_/  /_/ /_/\__,_/_/   \___/_/ /_/\__,_/_/_/ /_/ 
+                                                                      
+ * @title EVVM External Chain Station
+ * @author Mate labs
+ * @notice Manages cross-chain deposits from an external chain to the EVVM host chain.
+ * @dev Multi-protocol bridge supporting Hyperlane, LayerZero V2, and Axelar. 
+ *      Facilitates token transfers using a sequential nonce system and ECDSA signatures.
+ */
 
 contract TreasuryExternalChainStation is
-    ExternalChainStationStructs,
     OApp,
     OAppOptionsType3,
     AxelarExecutable
 {
     /// @notice Admin address management with time-delayed proposals
     /// @dev Stores current admin, proposed admin, and acceptance timestamp
-    AddressTypeProposal admin;
+    ProposalStructs.AddressTypeProposal admin;
 
     /// @notice Fisher executor address management with time-delayed proposals
     /// @dev Fisher executor can process cross-chain bridge transactions
-    AddressTypeProposal fisherExecutor;
+    ProposalStructs.AddressTypeProposal fisherExecutor;
 
     /// @notice Hyperlane protocol configuration for cross-chain messaging
     /// @dev Contains domain ID, host chain address, and mailbox contract address
-    HyperlaneConfig hyperlane;
+    Structs.HyperlaneConfig hyperlane;
 
     /// @notice LayerZero protocol configuration for omnichain messaging
     /// @dev Contains endpoint ID, host chain address, and endpoint contract address
-    LayerZeroConfig layerZero;
+    Structs.LayerZeroConfig layerZero;
 
     /// @notice Axelar protocol configuration for cross-chain communication
     /// @dev Contains chain name, host chain address, gas service, and gateway addresses
-    AxelarConfig axelar;
+    Structs.AxelarConfig axelar;
 
     /// @notice Pending proposal for changing host chain addresses across all protocols
     /// @dev Used for coordinated updates to host chain addresses with time delay
-    ChangeHostChainAddressParams hostChainAddressChangeProposal;
+    Structs.ChangeHostChainAddressParams hostChainAddress;
 
     /// @notice Unique identifier for the EVVM instance this station belongs to
     /// @dev Immutable value set at deployment for signature verification
@@ -116,9 +124,7 @@ contract TreasuryExternalChainStation is
 
     uint256 windowTimeToChangeEvvmID;
 
-    /// @notice Tracks the next nonce for Fisher bridge operations per user address
-    /// @dev Prevents replay attacks in Fisher bridge transactions
-    mapping(address => uint256) nextFisherExecutionNonce;
+    mapping(address user => mapping(uint256 nonce => bool isUsed)) asyncNonce;
 
     /// @notice LayerZero execution options with gas limit configuration
     /// @dev Pre-built options for LayerZero message execution (200k gas limit)
@@ -173,32 +179,32 @@ contract TreasuryExternalChainStation is
     /// @param _crosschainConfig Configuration struct containing all cross-chain protocol settings
     constructor(
         address _admin,
-        CrosschainConfig memory _crosschainConfig
+        Structs.CrosschainConfig memory _crosschainConfig
     )
         OApp(_crosschainConfig.layerZero.endpointAddress, _admin)
         Ownable(_admin)
         AxelarExecutable(_crosschainConfig.axelar.gatewayAddress)
     {
-        admin = AddressTypeProposal({
+        admin = ProposalStructs.AddressTypeProposal({
             current: _admin,
             proposal: address(0),
             timeToAccept: 0
         });
-        hyperlane = HyperlaneConfig({
+        hyperlane = Structs.HyperlaneConfig({
             hostChainStationDomainId: _crosschainConfig
                 .hyperlane
                 .hostChainStationDomainId,
             hostChainStationAddress: "",
             mailboxAddress: _crosschainConfig.hyperlane.mailboxAddress
         });
-        layerZero = LayerZeroConfig({
+        layerZero = Structs.LayerZeroConfig({
             hostChainStationEid: _crosschainConfig
                 .layerZero
                 .hostChainStationEid,
             hostChainStationAddress: "",
             endpointAddress: _crosschainConfig.layerZero.endpointAddress
         });
-        axelar = AxelarConfig({
+        axelar = Structs.AxelarConfig({
             hostChainStationChainName: _crosschainConfig
                 .axelar
                 .hostChainStationChainName,
@@ -230,6 +236,8 @@ contract TreasuryExternalChainStation is
             layerZero.hostChainStationAddress
         );
 
+        hostChainAddress.currentAddress = hostChainStationAddress;
+
         fuseSetHostChainAddress = 0x00;
     }
 
@@ -240,7 +248,7 @@ contract TreasuryExternalChainStation is
     function setEvvmID(uint256 newEvvmID) external onlyAdmin {
         if (evvmID != 0) {
             if (block.timestamp > windowTimeToChangeEvvmID)
-                revert ErrorsLib.WindowToChangeEvvmIDExpired();
+                revert Error.WindowToChangeEvvmIDExpired();
         }
 
         evvmID = newEvvmID;
@@ -248,12 +256,42 @@ contract TreasuryExternalChainStation is
         windowTimeToChangeEvvmID = block.timestamp + 24 hours;
     }
 
-    /// @notice Deposits ERC20 tokens and sends them to host chain via selected protocol
-    /// @dev Supports Hyperlane (0x01), LayerZero (0x02), and Axelar (0x03) protocols
-    /// @param toAddress Recipient address on the host chain
-    /// @param token ERC20 token contract address to deposit and transfer
-    /// @param amount Amount of tokens to deposit and send to host chain
-    /// @param protocolToExecute Protocol selector: 0x01=Hyperlane, 0x02=LayerZero, 0x03=Axelar
+    /**
+     * @notice Deposits ERC20 tokens via selected protocol
+     * @dev Transfers tokens then bridges to host chain
+     *
+     * Process:
+     * - Transfer: User → this contract (via approval)
+     * - Encode: PayloadUtils.encodePayload(token, to, amt)
+     * - Route: Protocol-specific message dispatch
+     * - Receive: Host chain credits Core.sol balance
+     *
+     * Protocol Routing:
+     * - 0x01: Hyperlane (mailbox.dispatch + quote fee)
+     * - 0x02: LayerZero (_lzSend + quote fee)
+     * - 0x03: Axelar (payNativeGas + callContract)
+     *
+     * Fee Payment:
+     * - Hyperlane: msg.value = quote
+     * - LayerZero: msg.value = quote (refund excess)
+     * - Axelar: msg.value for gas service
+     *
+     * Host Chain Integration:
+     * - Receives: handle/_lzReceive/_execute
+     * - Credits: Core.sol balance for recipient
+     * - Fisher Bridge: Independent from Core.sol nonces
+     *
+     * Security:
+     * - Approval: Must approve this contract first
+     * - Validation: verifyAndDepositERC20 checks balance
+     * - Sender checks: Host validates origin on receive
+     *
+     * @param toAddress Recipient on host chain
+     * @param token ERC20 token address
+     * @param amount Token amount to bridge
+     * @param protocolToExecute 0x01=Hyperlane, 0x02=LZ,
+     * 0x03=Axelar
+     */
     function depositERC20(
         address toAddress,
         address token,
@@ -306,17 +344,48 @@ contract TreasuryExternalChainStation is
         }
     }
 
-    /// @notice Deposits native ETH and sends it to host chain via selected protocol
-    /// @dev msg.value must cover both the amount and protocol fees
-    /// @param toAddress Recipient address on the host chain
-    /// @param amount Amount of ETH to send to host chain (must be <= msg.value - fees)
-    /// @param protocolToExecute Protocol selector: 0x01=Hyperlane, 0x02=LayerZero, 0x03=Axelar
+    /**
+     * @notice Deposits native ETH via selected protocol
+     * @dev msg.value covers amount + protocol fees
+     *
+     * Process:
+     * - Validate: msg.value >= amount + fees
+     * - Encode: PayloadUtils.encodePayload(0x0, to, amt)
+     * - Route: Protocol-specific message dispatch
+     * - Receive: Host chain credits Core.sol balance
+     *
+     * Protocol Routing:
+     * - 0x01: Hyperlane (dispatch w/ quote + amount)
+     * - 0x02: LayerZero (_lzSend w/ fee + amount)
+     * - 0x03: Axelar (payNativeGas then callContract)
+     *
+     * Fee Calculation:
+     * - Hyperlane: msg.value = quote + amount
+     * - LayerZero: msg.value = fee + amount (refund)
+     * - Axelar: msg.value = gasService + amount
+     *
+     * Host Chain Integration:
+     * - Token Representation: address(0) for native ETH
+     * - Payload: Encoded with zero address
+     * - Credits: Core.sol balance as native token
+     * - Fisher Bridge: Independent nonce system
+     *
+     * Security:
+     * - Balance Check: Reverts if insufficient value
+     * - Excess Handling: LZ refunds, others use full
+     * - Validation: Host validates origin and sender
+     *
+     * @param toAddress Recipient on host chain
+     * @param amount ETH amount to bridge
+     * @param protocolToExecute 0x01=Hyperlane, 0x02=LZ,
+     * 0x03=Axelar
+     */
     function depositCoin(
         address toAddress,
         uint256 amount,
         bytes1 protocolToExecute
     ) external payable {
-        if (msg.value < amount) revert ErrorsLib.InsufficientBalance();
+        if (msg.value < amount) revert Error.InsufficientBalance();
 
         bytes memory payload = PayloadUtils.encodePayload(
             address(0),
@@ -327,8 +396,7 @@ contract TreasuryExternalChainStation is
         if (protocolToExecute == 0x01) {
             // 0x01 = Hyperlane
             uint256 quote = getQuoteHyperlane(toAddress, address(0), amount);
-            if (msg.value < quote + amount)
-                revert ErrorsLib.InsufficientBalance();
+            if (msg.value < quote + amount) revert Error.InsufficientBalance();
             /*messageId = */ IMailbox(hyperlane.mailboxAddress).dispatch{
                 value: quote
             }(
@@ -339,8 +407,7 @@ contract TreasuryExternalChainStation is
         } else if (protocolToExecute == 0x02) {
             // 0x02 = LayerZero
             uint256 fee = quoteLayerZero(toAddress, address(0), amount);
-            if (msg.value < fee + amount)
-                revert ErrorsLib.InsufficientBalance();
+            if (msg.value < fee + amount) revert Error.InsufficientBalance();
             _lzSend(
                 layerZero.hostChainStationEid,
                 payload,
@@ -368,70 +435,164 @@ contract TreasuryExternalChainStation is
         }
     }
 
-    /// @notice Receives and validates Fisher bridge transactions from host chain
-    /// @dev Verifies signature and increments nonce but doesn't transfer tokens (receive-only)
-    /// @param from Original sender address from host chain
-    /// @param addressToReceive Intended recipient address on this chain
-    /// @param tokenAddress Token contract address (address(0) for ETH)
-    /// @param priorityFee Fee amount for priority processing
-    /// @param amount Amount of tokens being received
-    /// @param signature ECDSA signature proving transaction authorization
+    /**
+     * @notice Validates Fisher bridge receive confirmation
+     * @dev Confirms tokens sent FROM host TO external chain
+     *
+     * Purpose:
+     * - Acknowledge: Confirm host sent tokens
+     * - Validate: Signature from original sender
+     * - Track: Mark nonce as used
+     * - Security: Prevent replay attacks
+     *
+     * Signature Validation:
+     * - Payload: AdvancedStrings.buildSignaturePayload
+     * - Components: evvmID, host address, hash, nonce
+     * - Hash: TreasuryCrossChainHashUtils.hashData...
+     * - Recovers: Must match 'from' address
+     *
+     * Nonce System:
+     * - Independent: asyncNonce[from][nonce] mapping
+     * - Sequential: User manages nonce ordering
+     * - NOT Core.sol: Fisher bridge separate system
+     * - Prevention: Revert if nonce already used
+     *
+     * Integration Context:
+     * - Core.sol: NOT used (independent nonces)
+     * - Core.sol: NOT on external chain
+     * - SignatureRecover: ECDSA signature validation
+     * - Host Chain: Sends tokens via protocol messages
+     *
+     * Security Flow:
+     * - Check: Nonce not already used
+     * - Recover: Signer from signature payload
+     * - Validate: Recovered signer == from address
+     * - Mark: asyncNonce[from][nonce] = true
+     *
+     * @param from Original sender on host chain
+     * @param addressToReceive Recipient on external chain
+     * @param tokenAddress Token (address(0) for ETH)
+     * @param priorityFee Fee for priority processing
+     * @param amount Token amount received
+     * @param nonce Sequential nonce from user
+     * @param signature ECDSA signature from 'from' address
+     */
     function fisherBridgeReceive(
         address from,
         address addressToReceive,
         address tokenAddress,
         uint256 priorityFee,
         uint256 amount,
+        uint256 nonce,
         bytes memory signature
     ) external onlyFisherExecutor {
+        if (asyncNonce[from][nonce]) revert CoreError.AsyncNonceAlreadyUsed();
+
         if (
-            !SignatureUtils.verifyMessageSignedForFisherBridge(
-                evvmID,
-                from,
-                addressToReceive,
-                nextFisherExecutionNonce[from],
-                tokenAddress,
-                priorityFee,
-                amount,
+            SignatureRecover.recoverSigner(
+                AdvancedStrings.buildSignaturePayload(
+                    evvmID,
+                    hostChainAddress.currentAddress,
+                    Hash.hashDataForFisherBridge(
+                        addressToReceive,
+                        tokenAddress,
+                        priorityFee,
+                        amount
+                    ),
+                    fisherExecutor.current,
+                    nonce,
+                    true
+                ),
                 signature
-            )
-        ) revert ErrorsLib.InvalidSignature();
+            ) != from
+        ) revert CoreError.InvalidSignature();
 
-        nextFisherExecutionNonce[from]++;
+        asyncNonce[from][nonce] = true;
     }
 
-    /// @notice Processes Fisher bridge ERC20 token transfers to host chain
-    /// @dev Validates signature, deposits tokens, and emits tracking event
-    /// @param from Original sender address initiating the bridge transaction
-    /// @param addressToReceive Recipient address on the host chain
-    /// @param tokenAddress ERC20 token contract address to bridge
-    /// @param priorityFee Fee amount for priority processing
-    /// @param amount Amount of tokens to bridge to host chain
-    /// @param signature ECDSA signature proving transaction authorization
+    /**
+     * @notice Executes Fisher bridge ERC20 deposit to host
+     * @dev Validates signature, deposits, emits event
+     *
+     * Purpose:
+     * - Deposit: Transfer ERC20 from user to contract
+     * - Validate: ECDSA signature from sender
+     * - Track: Mark nonce as used
+     * - Emit: Log for Fisher executor on host chain
+     *
+     * Fisher Bridge Flow:
+     * - External: User signs intent + executor calls this
+     * - Deposit: Tokens held in this contract
+     * - Event: FisherBridgeSend logged
+     * - Host: Fisher monitors events + credits balance
+     * - Core.sol: Host chain credits recipient balance
+     *
+     * Signature Validation:
+     * - Payload: evvmID + host address + hash + nonce
+     * - Hash: hashDataForFisherBridge(to, token, fee,
+     *   amt)
+     * - Recover: SignatureRecover.recoverSigner
+     * - Match: Recovered signer must equal 'from'
+     *
+     * Nonce System:
+     * - Independent: asyncNonce[from][nonce]
+     * - NOT Core.sol: Separate from EVVM nonces
+     * - Sequential: User manages own nonces
+     * - Replay Prevention: Mark used after validation
+     *
+     * Integration Context:
+     * - Core.sol: NOT used (Fisher independent)
+     * - Core.sol: Credits balance on host chain
+     * - Fisher Executor: Monitors events + processes
+     * - Host Station: Receives event + credits user
+     *
+     * Security:
+     * - Approval: Requires token approval first
+     * - Signature: ECDSA validation prevents forgery
+     * - Nonce: Sequential tracking prevents replays
+     * - Executor Only: onlyFisherExecutor modifier
+     *
+     * @param from Original sender (signer)
+     * @param addressToReceive Recipient on host chain
+     * @param tokenAddress ERC20 token address
+     * @param priorityFee Fee for priority processing
+     * @param amount Token amount to bridge
+     * @param nonce Sequential nonce from user
+     * @param signature ECDSA signature from 'from'
+     */
     function fisherBridgeSendERC20(
         address from,
         address addressToReceive,
         address tokenAddress,
         uint256 priorityFee,
         uint256 amount,
+        uint256 nonce,
         bytes memory signature
     ) external onlyFisherExecutor {
+        if (asyncNonce[from][nonce]) revert CoreError.AsyncNonceAlreadyUsed();
+
         if (
-            !SignatureUtils.verifyMessageSignedForFisherBridge(
-                evvmID,
-                from,
-                addressToReceive,
-                nextFisherExecutionNonce[from],
-                tokenAddress,
-                priorityFee,
-                amount,
+            SignatureRecover.recoverSigner(
+                AdvancedStrings.buildSignaturePayload(
+                    evvmID,
+                    hostChainAddress.currentAddress,
+                    Hash.hashDataForFisherBridge(
+                        addressToReceive,
+                        tokenAddress,
+                        priorityFee,
+                        amount
+                    ),
+                    fisherExecutor.current,
+                    nonce,
+                    true
+                ),
                 signature
-            )
-        ) revert ErrorsLib.InvalidSignature();
+            ) != from
+        ) revert CoreError.InvalidSignature();
 
         verifyAndDepositERC20(tokenAddress, amount);
 
-        nextFisherExecutionNonce[from]++;
+        asyncNonce[from][nonce] = true;
 
         emit FisherBridgeSend(
             from,
@@ -439,41 +600,98 @@ contract TreasuryExternalChainStation is
             tokenAddress,
             priorityFee,
             amount,
-            nextFisherExecutionNonce[from] - 1
+            nonce
         );
     }
 
-    /// @notice Processes Fisher bridge ETH transfers to host chain
-    /// @dev Validates signature and exact payment (amount + priority fee)
-    /// @param from Original sender address initiating the bridge transaction
-    /// @param addressToReceive Recipient address on the host chain
-    /// @param priorityFee Fee amount for priority processing
-    /// @param amount Amount of ETH to bridge to host chain
-    /// @param signature ECDSA signature proving transaction authorization
+    /**
+     * @notice Executes Fisher bridge ETH deposit to host
+     * @dev Validates signature and exact payment
+     *
+     * Purpose:
+     * - Deposit: Receive ETH from executor caller
+     * - Validate: ECDSA signature from original sender
+     * - Track: Mark nonce as used
+     * - Emit: Log for Fisher executor on host chain
+     *
+     * Fisher Bridge Flow:
+     * - External: User signs intent + pays executor
+     * - Deposit: msg.value = amount + priorityFee
+     * - Event: FisherBridgeSend with address(0)
+     * - Host: Fisher monitors + credits Evvm balance
+     * - Core.sol: Host chain credits recipient
+     *
+     * Payment Validation:
+     * - Exact Match: msg.value == amount + priorityFee
+     * - No Excess: Prevents overpayment mistakes
+     * - Native Token: Represented as address(0)
+     * - Host Credits: Full amount to recipient
+     *
+     * Signature Validation:
+     * - Payload: evvmID + host + hash + nonce
+     * - Hash: hashDataForFisherBridge(to, 0x0, fee,
+     *   amt)
+     * - Token: address(0) represents native ETH
+     * - Recover: Must match 'from' address
+     *
+     * Nonce System:
+     * - Independent: asyncNonce[from][nonce]
+     * - NOT Core.sol: Fisher bridge separate
+     * - Sequential: User-managed ordering
+     * - Anti-Replay: Mark used after validation
+     *
+     * Integration Context:
+     * - Core.sol: NOT used (independent system)
+     * - Core.sol: Credits native balance on host
+     * - Fisher Executor: Pays ETH + processes
+     * - Host Station: Credits recipient balance
+     *
+     * Security:
+     * - Exact Payment: Prevents partial payments
+     * - Signature: ECDSA prevents unauthorized sends
+     * - Nonce: Sequential tracking prevents replays
+     * - Executor Only: onlyFisherExecutor modifier
+     *
+     * @param from Original sender (signer)
+     * @param addressToReceive Recipient on host chain
+     * @param priorityFee Fee for priority processing
+     * @param amount ETH amount to bridge
+     * @param nonce Sequential nonce from user
+     * @param signature ECDSA signature from 'from'
+     */
     function fisherBridgeSendCoin(
         address from,
         address addressToReceive,
         uint256 priorityFee,
         uint256 amount,
+        uint256 nonce,
         bytes memory signature
     ) external payable onlyFisherExecutor {
+        if (asyncNonce[from][nonce]) revert CoreError.AsyncNonceAlreadyUsed();
+
         if (
-            !SignatureUtils.verifyMessageSignedForFisherBridge(
-                evvmID,
-                from,
-                addressToReceive,
-                nextFisherExecutionNonce[from],
-                address(0),
-                priorityFee,
-                amount,
+            SignatureRecover.recoverSigner(
+                AdvancedStrings.buildSignaturePayload(
+                    evvmID,
+                    hostChainAddress.currentAddress,
+                    Hash.hashDataForFisherBridge(
+                        addressToReceive,
+                        address(0),
+                        priorityFee,
+                        amount
+                    ),
+                    fisherExecutor.current,
+                    nonce,
+                    true
+                ),
                 signature
-            )
-        ) revert ErrorsLib.InvalidSignature();
+            ) != from
+        ) revert CoreError.InvalidSignature();
 
         if (msg.value != amount + priorityFee)
-            revert ErrorsLib.InsufficientBalance();
+            revert Error.InsufficientBalance();
 
-        nextFisherExecutionNonce[from]++;
+        asyncNonce[from][nonce] = true;
 
         emit FisherBridgeSend(
             from,
@@ -481,18 +699,44 @@ contract TreasuryExternalChainStation is
             address(0),
             priorityFee,
             amount,
-            nextFisherExecutionNonce[from] - 1
+            nonce
         );
     }
 
     // Hyperlane Specific Functions //
 
-    /// @notice Calculates the fee required for Hyperlane cross-chain message dispatch
-    /// @dev Queries the Hyperlane mailbox for accurate fee estimation
-    /// @param toAddress Recipient address on the destination chain
-    /// @param token Token contract address being transferred
-    /// @param amount Amount of tokens being transferred
-    /// @return Fee amount in native currency required for the Hyperlane message
+    /**
+     * @notice Quotes Hyperlane cross-chain message fee
+     * @dev Queries mailbox for accurate fee estimation
+     *
+     * Purpose:
+     * - Estimate: Calculate native token fee for message
+     * - Quote: Query Hyperlane mailbox contract
+     * - Planning: Users know cost before depositERC20
+     * - Payment: Fee paid in msg.value on deposit
+     *
+     * Hyperlane Fee Model:
+     * - Calculation: mailbox.quoteDispatch
+     * - Components: Destination domain + payload size
+     * - Payment: Native token to mailbox
+     * - Delivery: Relayers submit to destination
+     *
+     * Quote Components:
+     * - Domain ID: hyperlane.hostChainStationDomainId
+     * - Recipient: hyperlane.hostChainStationAddress
+     * - Payload: PayloadUtils.encodePayload(token, to,
+     *   amt)
+     *
+     * Usage:
+     * - Pre-Deposit: Call to estimate required msg.value
+     * - Display: Show users total cost
+     * - Payment: depositERC20 uses quote for dispatch
+     *
+     * @param toAddress Recipient on host chain
+     * @param token Token address (or 0x0 for ETH)
+     * @param amount Token amount to bridge
+     * @return Native token fee for Hyperlane message
+     */
     function getQuoteHyperlane(
         address toAddress,
         address token,
@@ -506,36 +750,97 @@ contract TreasuryExternalChainStation is
             );
     }
 
-    /// @notice Handles incoming Hyperlane messages from the host chain
-    /// @dev Validates origin, sender authorization, and processes the payload
-    /// @param _origin Source chain domain ID where the message originated
-    /// @param _sender Address of the message sender (must be host chain station)
-    /// @param _data Encoded payload containing transfer instructions
+    /**
+     * @notice Handles incoming Hyperlane messages
+     * @dev Validates origin, sender, processes payload
+     *
+     * Purpose:
+     * - Receive: Messages from host chain via Hyperlane
+     * - Validate: Origin domain + sender address
+     * - Process: Decode payload + transfer tokens
+     * - Security: Multi-layer validation checks
+     *
+     * Hyperlane Message Flow:
+     * - Host: TreasuryHostChainStation dispatches
+     * - Relayer: Submits message to this chain
+     * - Mailbox: Calls this handle() function
+     * - Process: decodeAndGive transfers tokens
+     *
+     * Validation Layers:
+     * - Caller: Must be hyperlane.mailboxAddress
+     * - Sender: Must be hyperlane.hostChainStation...
+     * - Origin: Must be hyperlane.hostChainStation
+     *   DomainId
+     * - All checks prevent unauthorized messages
+     *
+     * Payload Processing:
+     * - Decode: PayloadUtils.decodePayload(_data)
+     * - Extract: token address, recipient, amount
+     * - Transfer: ETH (address 0) or ERC20 tokens
+     * - Recipient: Receives tokens on external chain
+     *
+     * Security:
+     * - Mailbox Only: Reverts if caller not mailbox
+     * - Sender Check: Reverts if not host station
+     * - Domain Check: Reverts if wrong origin
+     * - Three-layer validation prevents attacks
+     *
+     * @param _origin Source chain domain ID
+     * @param _sender Sender address (host station)
+     * @param _data Encoded payload (token, to, amount)
+     */
     function handle(
         uint32 _origin,
         bytes32 _sender,
         bytes calldata _data
     ) external payable virtual {
         if (msg.sender != hyperlane.mailboxAddress)
-            revert ErrorsLib.MailboxNotAuthorized();
+            revert Error.MailboxNotAuthorized();
 
         if (_sender != hyperlane.hostChainStationAddress)
-            revert ErrorsLib.SenderNotAuthorized();
+            revert Error.SenderNotAuthorized();
 
         if (_origin != hyperlane.hostChainStationDomainId)
-            revert ErrorsLib.ChainIdNotAuthorized();
+            revert Error.ChainIdNotAuthorized();
 
         decodeAndGive(_data);
     }
 
     // LayerZero Specific Functions //
 
-    /// @notice Calculates the fee required for LayerZero cross-chain message
-    /// @dev Queries LayerZero endpoint for accurate native fee estimation
-    /// @param toAddress Recipient address on the destination chain
-    /// @param token Token contract address being transferred
-    /// @param amount Amount of tokens being transferred
-    /// @return Native fee amount required for the LayerZero message
+    /**
+     * @notice Quotes LayerZero cross-chain message fee
+     * @dev Queries endpoint for native fee estimation
+     *
+     * Purpose:
+     * - Estimate: Calculate native token fee for LZ send
+     * - Quote: Query LayerZero V2 endpoint
+     * - Planning: Users know cost before deposit
+     * - Payment: Fee paid in msg.value on deposit
+     *
+     * LayerZero Fee Model:
+     * - Calculation: _quote (internal OApp function)
+     * - Components: Destination eid + payload + options
+     * - Options: 200k gas limit for execution
+     * - Refund: Excess fees returned to sender
+     *
+     * Quote Components:
+     * - Endpoint ID: layerZero.hostChainStationEid
+     * - Payload: PayloadUtils.encodePayload
+     * - Options: Pre-built with 200k gas limit
+     * - Pay ZRO: false (only native token)
+     *
+     * Usage:
+     * - Pre-Deposit: Call to estimate required msg.value
+     * - Display: Show users total cost
+     * - Payment: depositERC20/Coin uses quote
+     * - Refund: LZ returns excess to sender
+     *
+     * @param toAddress Recipient on host chain
+     * @param token Token address (or 0x0 for ETH)
+     * @param amount Token amount to bridge
+     * @return Native token fee for LayerZero message
+     */
     function quoteLayerZero(
         address toAddress,
         address token,
@@ -550,10 +855,46 @@ contract TreasuryExternalChainStation is
         return fee.nativeFee;
     }
 
-    /// @notice Handles incoming LayerZero messages from the host chain
-    /// @dev Validates origin chain and sender, then processes the transfer payload
-    /// @param _origin Origin information containing source endpoint ID and sender
-    /// @param message Encoded payload containing transfer instructions
+    /**
+     * @notice Handles incoming LayerZero messages
+     * @dev Validates origin + sender, processes payload
+     *
+     * Purpose:
+     * - Receive: Messages from host via LayerZero V2
+     * - Validate: Origin eid + sender address
+     * - Process: Decode payload + transfer tokens
+     * - Security: Multi-layer validation checks
+     *
+     * LayerZero Message Flow:
+     * - Host: TreasuryHostChainStation.lzSend
+     * - DVNs: Verify message across networks
+     * - Executor: Submits message to this chain
+     * - Endpoint: Calls this _lzReceive function
+     *
+     * Validation Layers:
+     * - Origin EID: Must be layerZero.hostChainStation
+     *   Eid
+     * - Sender: Must be layerZero.hostChainStation
+     *   Address
+     * - Peer: OApp validates via _getPeerOrRevert
+     * - All checks prevent unauthorized messages
+     *
+     * Payload Processing:
+     * - Decode: PayloadUtils.decodePayload(message)
+     * - Extract: token address, recipient, amount
+     * - Transfer: ETH (address 0) or ERC20 tokens
+     * - Recipient: Receives tokens on external chain
+     *
+     * Security:
+     * - EID Check: Reverts if wrong source endpoint
+     * - Sender Check: Reverts if not host station
+     * - OApp Pattern: Peer validation built-in
+     * - Two-layer validation prevents attacks
+     *
+     * @param _origin Origin info (srcEid, sender,
+     * nonce)
+     * @param message Encoded payload (token, to, amount)
+     */
     function _lzReceive(
         Origin calldata _origin,
         bytes32 /*_guid*/,
@@ -563,10 +904,10 @@ contract TreasuryExternalChainStation is
     ) internal override {
         // Decode the payload to get the message
         if (_origin.srcEid != layerZero.hostChainStationEid)
-            revert ErrorsLib.ChainIdNotAuthorized();
+            revert Error.ChainIdNotAuthorized();
 
         if (_origin.sender != layerZero.hostChainStationAddress)
-            revert ErrorsLib.SenderNotAuthorized();
+            revert Error.SenderNotAuthorized();
 
         decodeAndGive(message);
     }
@@ -606,11 +947,52 @@ contract TreasuryExternalChainStation is
 
     // Axelar Specific Functions //
 
-    /// @notice Handles incoming Axelar messages from the host chain
-    /// @dev Validates source chain and address, then processes the transfer payload
-    /// @param _sourceChain Source blockchain name (must match configured host chain)
-    /// @param _sourceAddress Source contract address (must match host chain station)
-    /// @param _payload Encoded payload containing transfer instructions
+    /**
+     * @notice Handles incoming Axelar messages
+     * @dev Validates source chain/address, processes payload
+     *
+     * Purpose:
+     * - Receive: Messages from host via Axelar Network
+     * - Validate: Source chain name + sender address
+     * - Process: Decode payload + transfer tokens
+     * - Security: Multi-layer validation checks
+     *
+     * Axelar Message Flow:
+     * - Host: TreasuryHostChainStation.callContract
+     * - Axelar: Validates via validator network
+     * - Gateway: Calls this _execute function
+     * - Process: decodeAndGive transfers tokens
+     *
+     * Validation Layers:
+     * - Source Chain: Must be axelar.hostChainStation
+     *   ChainName
+     * - Source Address: Must be axelar.hostChainStation
+     *   Address
+     * - Gateway: AxelarExecutable validates caller
+     * - All checks prevent unauthorized messages
+     *
+     * String Comparison:
+     * - AdvancedStrings.equal: Chain name validation
+     * - Case-Sensitive: Exact match required
+     * - Address Format: String type for Axelar
+     * - Security: Double validation of source
+     *
+     * Payload Processing:
+     * - Decode: PayloadUtils.decodePayload(_payload)
+     * - Extract: token address, recipient, amount
+     * - Transfer: ETH (address 0) or ERC20 tokens
+     * - Recipient: Receives tokens on external chain
+     *
+     * Security:
+     * - Chain Check: Reverts if wrong source chain
+     * - Address Check: Reverts if not host station
+     * - Gateway Pattern: AxelarExecutable validation
+     * - Two-layer validation prevents attacks
+     *
+     * @param _sourceChain Source blockchain name
+     * @param _sourceAddress Source contract address
+     * @param _payload Encoded payload (token, to, amount)
+     */
     function _execute(
         bytes32 /*commandId*/,
         string calldata _sourceChain,
@@ -622,14 +1004,14 @@ contract TreasuryExternalChainStation is
                 _sourceChain,
                 axelar.hostChainStationChainName
             )
-        ) revert ErrorsLib.ChainIdNotAuthorized();
+        ) revert Error.ChainIdNotAuthorized();
 
         if (
             !AdvancedStrings.equal(
                 _sourceAddress,
                 axelar.hostChainStationAddress
             )
-        ) revert ErrorsLib.SenderNotAuthorized();
+        ) revert Error.SenderNotAuthorized();
 
         decodeAndGive(_payload);
     }
@@ -711,9 +1093,10 @@ contract TreasuryExternalChainStation is
     ) external onlyAdmin {
         if (fuseSetHostChainAddress == 0x01) revert();
 
-        hostChainAddressChangeProposal = ChangeHostChainAddressParams({
+        hostChainAddress = Structs.ChangeHostChainAddressParams({
             porposeAddress_AddressType: hostChainStationAddress,
             porposeAddress_StringType: hostChainStationAddressString,
+            currentAddress: hostChainAddress.currentAddress,
             timeToAccept: block.timestamp + 1 minutes
         });
     }
@@ -721,9 +1104,10 @@ contract TreasuryExternalChainStation is
     /// @notice Cancels a pending host chain address change proposal
     /// @dev Resets the host chain address proposal to default state
     function rejectProposalHostChainAddress() external onlyAdmin {
-        hostChainAddressChangeProposal = ChangeHostChainAddressParams({
+        hostChainAddress = Structs.ChangeHostChainAddressParams({
             porposeAddress_AddressType: address(0),
             porposeAddress_StringType: "",
+            currentAddress: hostChainAddress.currentAddress,
             timeToAccept: 0
         });
     }
@@ -731,37 +1115,39 @@ contract TreasuryExternalChainStation is
     /// @notice Accepts pending host chain address changes across all protocols
     /// @dev Updates Hyperlane, LayerZero, and Axelar configurations simultaneously
     function acceptHostChainAddress() external {
-        if (block.timestamp < hostChainAddressChangeProposal.timeToAccept)
-            revert();
+        if (block.timestamp < hostChainAddress.timeToAccept) revert();
 
         hyperlane.hostChainStationAddress = bytes32(
-            uint256(
-                uint160(
-                    hostChainAddressChangeProposal.porposeAddress_AddressType
-                )
-            )
+            uint256(uint160(hostChainAddress.porposeAddress_AddressType))
         );
         layerZero.hostChainStationAddress = bytes32(
-            uint256(
-                uint160(
-                    hostChainAddressChangeProposal.porposeAddress_AddressType
-                )
-            )
+            uint256(uint160(hostChainAddress.porposeAddress_AddressType))
         );
-        axelar.hostChainStationAddress = hostChainAddressChangeProposal
+        axelar.hostChainStationAddress = hostChainAddress
             .porposeAddress_StringType;
 
         _setPeer(
             layerZero.hostChainStationEid,
             layerZero.hostChainStationAddress
         );
+
+        hostChainAddress = Structs.ChangeHostChainAddressParams({
+            porposeAddress_AddressType: address(0),
+            porposeAddress_StringType: "",
+            currentAddress: hostChainAddress.porposeAddress_AddressType,
+            timeToAccept: 0
+        });
     }
 
     // Getter functions //
 
     /// @notice Returns the complete admin configuration including proposals and timelock
     /// @return Current admin address, proposed admin, and acceptance timestamp
-    function getAdmin() external view returns (AddressTypeProposal memory) {
+    function getAdmin()
+        external
+        view
+        returns (ProposalStructs.AddressTypeProposal memory)
+    {
         return admin;
     }
 
@@ -770,19 +1156,16 @@ contract TreasuryExternalChainStation is
     function getFisherExecutor()
         external
         view
-        returns (AddressTypeProposal memory)
+        returns (ProposalStructs.AddressTypeProposal memory)
     {
         return fisherExecutor;
     }
 
-    /// @notice Returns the next nonce for Fisher bridge operations for a specific user
-    /// @dev Used to prevent replay attacks in cross-chain bridge transactions
-    /// @param user Address to query the next Fisher execution nonce for
-    /// @return Next sequential nonce value for the user's Fisher bridge operations
-    function getNextFisherExecutionNonce(
-        address user
-    ) external view returns (uint256) {
-        return nextFisherExecutionNonce[user];
+    function getIfUsedAsyncNonce(
+        address user,
+        uint256 nonce
+    ) public view virtual returns (bool) {
+        return asyncNonce[user][nonce];
     }
 
     /// @notice Returns the complete Hyperlane protocol configuration
@@ -790,7 +1173,7 @@ contract TreasuryExternalChainStation is
     function getHyperlaneConfig()
         external
         view
-        returns (HyperlaneConfig memory)
+        returns (Structs.HyperlaneConfig memory)
     {
         return hyperlane;
     }
@@ -800,14 +1183,18 @@ contract TreasuryExternalChainStation is
     function getLayerZeroConfig()
         external
         view
-        returns (LayerZeroConfig memory)
+        returns (Structs.LayerZeroConfig memory)
     {
         return layerZero;
     }
 
     /// @notice Returns the complete Axelar protocol configuration
     /// @return Axelar configuration including chain name, addresses, gas service, and gateway
-    function getAxelarConfig() external view returns (AxelarConfig memory) {
+    function getAxelarConfig()
+        external
+        view
+        returns (Structs.AxelarConfig memory)
+    {
         return axelar;
     }
 
@@ -837,7 +1224,7 @@ contract TreasuryExternalChainStation is
     function verifyAndDepositERC20(address token, uint256 amount) internal {
         if (token == address(0)) revert();
         if (IERC20(token).allowance(msg.sender, address(this)) < amount)
-            revert ErrorsLib.InsufficientBalance();
+            revert Error.InsufficientBalance();
 
         IERC20(token).transferFrom(msg.sender, address(this), amount);
     }
@@ -851,4 +1238,4 @@ contract TreasuryExternalChainStation is
     /// @notice Disabled ownership renouncement function for security
     /// @dev Prevents accidental loss of administrative control over the contract
     function renounceOwnership() public virtual override onlyOwner {}
-}
+}