feat: Implement LayerZero WHBAR Cross-Chain Bridge with Comprehensive E2E Testing (hiero-ledger#3821)

Signed-off-by: Logan Nguyen <[email protected]>

Author: quiet-node

tools/hedera-crosschain-bridge/.env.example

@@ -1,13 +1,39 @@
-# Hedera Network Configuration
-HEDERA_CHAIN_ID=
+# =============================================================================
+# HEDERA NETWORK CONFIGURATION
+# =============================================================================
+
+# Hedera JSON-RPC endpoint URL (e.g. https://testnet.hashio.io/api)
 HEDERA_RPC_URL=
+
+# Hedera account private key
 HEDERA_PK=
+
+# Hedera block explorer URL (e.g. https://hashscan.io/testnet)
+HEDERA_BLOCK_EXPLORER_URL=
+
+# LayerZero V2 Endpoint for Hedera Network (e.g. 0x6EDCE65403992e310A62460808c4b910D972f10f for Hedera Testnet)
+# Find LZ Endpoint V2 at https://docs.layerzero.network/v2/deployments/deployed-contracts
 HEDERA_LZ_ENDPOINT_V2=
+
+# LayerZero Endpoint ID (EID) for Hedera Network (e.g. 40267 for Hedera Testnet)
+# Find LZ EID V2 at https://docs.layerzero.network/v2/deployments/deployed-contracts
 HEDERA_LZ_EID_V2=
 
-# Sepolia Network Configuration
-SEPOLIA_CHAIN_ID=
+# =============================================================================
+# SEPOLIA NETWORK CONFIGURATION
+# =============================================================================
+
+# Sepolia JSON-RPC endpoint URL (e.g. https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID)
 SEPOLIA_RPC_URL=
+
+# Sepolia account private key
 SEPOLIA_PK=
-SEPOLIA_LZ_ENDPOINT_V2=
-SEPOLIA_LZ_EID_V2=
+
+# Sepolia block explorer URL (e.g. https://sepolia.etherscan.io)
+SEPOLIA_BLOCK_EXPLORER_URL=
+
+# LayerZero V2 Endpoint for Sepolia Testnet
+SEPOLIA_LZ_ENDPOINT_V2=0x6EDCE65403992e310A62460808c4b910D972f10f
+
+# LayerZero Endpoint ID (EID) for Sepolia Testnet
+SEPOLIA_LZ_EID_V2=40161

tools/hedera-crosschain-bridge/contracts/ERC20Mock.sol

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+contract ERC20Mock is ERC20 {
+    uint8 decimalsArg = 18;
+
+    constructor(uint256 _initialMint, uint8 _decimals) ERC20("ERC20Mock", "E20M") {
+        _mint(msg.sender, _initialMint);
+        decimalsArg = _decimals;
+    }
+
+    function decimals() public view override returns (uint8) {
+        return decimalsArg;
+    }
+}

tools/hedera-crosschain-bridge/contracts/ExampleOFTAdapter.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+import {OFTAdapter} from "@layerzerolabs/lz-evm-oapp-v2/contracts/oft/OFTAdapter.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+contract ExampleOFTAdapter is OFTAdapter {
+    constructor(
+        address _token,
+        address _lzEndpoint,
+        address _owner
+    ) OFTAdapter(_token, _lzEndpoint, _owner) Ownable(_owner) {}
+}

tools/hedera-crosschain-bridge/contracts/README.md

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.0;
+
+/**
+ * @title SimpleReceiver
+ * @dev A minimal contract that can receive tokens/ETH
+ * Used as a test receiver for cross-chain transfers
+ */
+contract SimpleReceiver {
+    /**
+     * @dev Allows the contract to receive ETH/HBAR/tokens
+     */
+    receive() external payable {}
+    
+    /**
+     * @dev Fallback function to receive ETH/HBAR/tokens
+     */
+    fallback() external payable {}
+}

tools/hedera-crosschain-bridge/contracts/SimpleReceiver.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+// the contract is based on WETH9 with updated solidity versions and functions
+contract WHBAR {
+    string public name = "Wrapped HBAR";
+    string public symbol = "WHBAR";
+    uint8 public decimals = 8;
+
+    event Approval(address indexed src, address indexed guy, uint wad);
+    event Transfer(address indexed src, address indexed dst, uint wad);
+    event Deposit(address indexed dst, uint wad);
+    event Withdrawal(address indexed src, uint wad);
+
+    mapping(address => uint) public balanceOf;
+    mapping(address => mapping(address => uint)) public allowance;
+
+    fallback() external payable {
+        deposit();
+    }
+
+    receive() external payable {
+        deposit();
+    }
+
+    function deposit() public payable {
+        balanceOf[msg.sender] += msg.value;
+
+        emit Deposit(msg.sender, msg.value);
+    }
+
+    function withdraw(uint wad) public {
+        require(balanceOf[msg.sender] >= wad);
+
+        balanceOf[msg.sender] -= wad;
+        payable(msg.sender).transfer(wad);
+
+        emit Withdrawal(msg.sender, wad);
+    }
+
+    function totalSupply() public view returns (uint) {
+        return address(this).balance;
+    }
+
+    function approve(address guy, uint wad) public returns (bool) {
+        allowance[msg.sender][guy] = wad;
+
+        emit Approval(msg.sender, guy, wad);
+
+        return true;
+    }
+
+    function transfer(address dst, uint wad) public returns (bool) {
+        return transferFrom(msg.sender, dst, wad);
+    }
+
+    function transferFrom(address src, address dst, uint wad) public returns (bool) {
+        require(balanceOf[src] >= wad);
+
+        if (src != msg.sender && allowance[src][msg.sender] !=
+    type(uint256).max) {
+        require(allowance[src][msg.sender] >= wad);
+        allowance[src][msg.sender] -= wad;
+        }
+
+        balanceOf[src] -= wad;
+        balanceOf[dst] += wad;
+
+        emit Transfer(src, dst, wad);
+
+    return true;
+    }
+}

tools/hedera-crosschain-bridge/contracts/WHBAR.sol

@@ -1,6 +1,12 @@
 {
   "name": "hedera-crosschain-bridge",
-  "scripts": {},
+  "scripts": {
+    "deploy-whbar": "hardhat run scripts/deployments/deploy-whbar.ts",
+    "deploy-erc20": "hardhat run scripts/deployments/deploy-erc20.ts",
+    "deploy-oftAdapter": "hardhat run scripts/deployments/deploy-oft-adapter.ts",
+    "deployment-script-test": "hardhat test --grep @deployment-test",
+    "whbar-e2e-test": "hardhat test --grep @whbar-bridge"
+  },
   "license": "Apache-2.0",
   "devDependencies": {
     "@layerzerolabs/lz-evm-oapp-v2": "^3.0.98",

tools/hedera-crosschain-bridge/package.json

@@ -1 +1,11 @@
-SCRIPTS_PLACE_HOLDER
+# Scripts
+
+This directory contains various scripts designed to streamline development and deployment workflows for the Hedera Crosschain Bridge project. All scripts follow standardized practices to ensure consistency across different environments and use cases.
+
+## Available Script Categories
+
+### Deployments
+
+Smart contract deployment scripts for various blockchain networks. Includes scripts for deploying ERC20 tokens, OFT adapters, and WHBAR tokens across supported networks.
+
+See the [Deployment Guide](./deployments/README.md) for detailed documentation, configuration, and troubleshooting guides.