Merge branch 'main' into pod-restarts

Author: shezaan-hashgraph

docs/rpc-api.md

@@ -11,6 +11,11 @@ import jsonResp from '@hashgraph/json-rpc-server/dist/koaJsonRpc/lib/RpcResponse
 import { Context } from 'koa';
 import { Logger } from 'pino';
 
+type SubscriptionId = string | undefined;
+export interface SubscriptionResponse extends IJsonRpcResponse {
+  result: SubscriptionId;
+}
+
 import { SubscriptionService } from '../service/subscriptionService';
 import {
   areSubscriptionsEnabled,
@@ -27,15 +32,15 @@ import { ISharedParams } from './jsonRpcController';
  * @param {string} event - The event name to subscribe to (e.g., "newHeads").
  * @param {Relay} relay - The relay object used for managing WebSocket subscriptions.
  * @param {Logger} logger - The logger object used for logging subscription information.
- * @returns {string | undefined} Returns the subscription ID.
+ * @returns {SubscriptionId} Returns the subscription ID.
  */
 const subscribeToNewHeads = (
   filters: any,
   ctx: Context,
   event: string,
   logger: Logger,
   subscriptionService: SubscriptionService,
-): string | undefined => {
+): SubscriptionId => {
   const subscriptionId = subscriptionService.subscribe(ctx.websocket, event, filters);
   logger.info(`Subscribed to newHeads, subscriptionId: ${subscriptionId}`);
   return subscriptionId;
@@ -51,7 +56,7 @@ const subscribeToNewHeads = (
  * @param {Relay} relay - The relay object used for managing WebSocket subscriptions.
  * @param {any} logger - The logger object used for logging subscription information.
  * @param {RequestDetails} requestDetails - The request details for logging and tracking.
- * @returns {{ response: any; subscriptionId: any }} Returns an object containing the response and subscription ID.
+ * @returns {SubscriptionResponse} Returns an object containing the response and subscription ID.
  */
 const handleEthSubscribeNewHeads = (
   filters: any,
@@ -61,7 +66,7 @@ const handleEthSubscribeNewHeads = (
   logger: Logger,
   requestDetails: RequestDetails,
   subscriptionService: SubscriptionService,
-): IJsonRpcResponse => {
+): SubscriptionResponse => {
   const wsNewHeadsEnabled = ConfigService.get('WS_NEW_HEADS_ENABLED');
 
   if (!wsNewHeadsEnabled) {
@@ -72,7 +77,7 @@ const handleEthSubscribeNewHeads = (
   }
 
   const subscriptionId = subscribeToNewHeads(filters, ctx, event, logger, subscriptionService);
-  return jsonResp(request.id, null, subscriptionId);
+  return jsonResp(request.id, null, subscriptionId) as SubscriptionResponse;
 };
 
 /**
@@ -86,7 +91,7 @@ const handleEthSubscribeNewHeads = (
  * @param {Relay} relay - The relay object used for managing WebSocket subscriptions.
  * @param {MirrorNodeClient} mirrorNodeClient - The client for interacting with the MirrorNode API.
  * @param {RequestDetails} requestDetails - The request details for logging and tracking.
- * @returns {{ response: any; subscriptionId: any }} Returns an object containing the response and subscription ID.
+ * @returns {Promise<SubscriptionResponse>} Returns an object containing the response and subscription ID.
  */
 const handleEthSubscribeLogs = async (
   filters: any,
@@ -96,7 +101,7 @@ const handleEthSubscribeLogs = async (
   mirrorNodeClient: MirrorNodeClient,
   requestDetails: RequestDetails,
   subscriptionService: SubscriptionService,
-): Promise<IJsonRpcResponse> => {
+): Promise<SubscriptionResponse> => {
   const validFiltersObject = constructValidLogSubscriptionFilter(filters);
 
   await validateSubscribeEthLogsParams(validFiltersObject, mirrorNodeClient, requestDetails);
@@ -108,7 +113,7 @@ const handleEthSubscribeLogs = async (
     throw predefined.INVALID_PARAMETER('filters.address', 'Only one contract address is allowed');
   }
   const subscriptionId = subscriptionService.subscribe(ctx.websocket, event, validFiltersObject);
-  return jsonResp(request.id, null, subscriptionId);
+  return jsonResp(request.id, null, subscriptionId) as SubscriptionResponse;
 };
 
 /**
@@ -123,7 +128,7 @@ const handleEthSubscribeLogs = async (
  * @param {ConnectionLimiter} args.limiter - The limiter object for managing connection subscriptions.
  * @param {Logger} args.logger - The logger object for logging messages and events.
  * @param {RequestDetails} args.requestDetails - The request details for logging and tracking.
- * @returns {Promise<any>} Returns a promise that resolves with the subscription response.
+ * @returns {Promise<SubscriptionResponse>} Returns a promise that resolves with the subscription response.
  */
 export const handleEthSubscribe = async ({
   ctx,

packages/ws-server/src/controllers/subscribeController.ts

@@ -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/.env.example

@@ -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/ERC20Mock.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/ExampleOFTAdapter.sol

@@ -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/README.md

@@ -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/SimpleReceiver.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/contracts/WHBAR.sol

@@ -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.