feat: implement a new version of HTSConnector for Stargate v2 OFT contract

[natanasow]

Description

Stargate has released a new version v2, and a concept of Hydra tokens. To be able to bridge WEth, USDC, and USDT (called hydra tokens), we need to implement the StargateHTSConnector.

The difference between the existing connector and the new connector is that we need to implement inflow and outflow.

The idea is to release a Stargate Connector, which includes this extra function, and implement an end-to-end test with an HTS token in Testnet, following the cross-chain bridge strategy we did for Stargate.

The methods to implement and adapt to HTS https://github.com/stargate-protocol/stargate-v2/blob/main/packages/stg-evm-v2/src/StargateOFT.sol

• _inflow

/// @notice Burn tokens to represent their removal from the local chain
/// @param _from The address to burn tokens from
/// @param _amount How many tokens to burn in LD
/// @return amountSD The amount burned in SD
function _inflow(address _from, uint256 _amount) internal virtual override returns (uint64 amountSD) {
    amountSD = _ld2sd(_amount);
    IERC20Minter(token).burnFrom(_from, _sd2ld(amountSD)); // remove dust and burn
}

• _outflow

/// @notice Mint tokens to represent their lading into the local chain
/// @param _to The account to mint tokens for
/// @param _amount The amount of tokens to mint
/// @return success Whether the minting was successful
function _outflow(address _to, uint256 _amount) internal virtual override returns (bool success) {
    try IERC20Minter(token).mint(_to, _amount) {
        success = true;
    } catch {} // solhint-disable-line no-empty-blocks
}

PS: All new contracts are inherited from the official stargate v2 contracts repo https://github.com/stargate-protocol/stargate-v2. Only StargateHTSConnectorExistingToken and ExampleStargateHTSConnectorExistingToken are introduced in this PR.

Related issue(s)

Fixes #3957

Testing Guide

Changes from original design (optional)

N/A

Additional work needed (optional)

N/A

Checklist

• I've assigned an assignee to this PR and related issue(s) (if applicable)
• I've assigned a label to this PR and related issue(s) (if applicable)
• I've assigned a milestone to this PR and related issue(s) (if applicable)
• I've updated documentation (code comments, README, etc. if applicable)
• I've done sufficient testing (unit, integration, etc.)

[github-actions]

Test Results

 20 files  ±0  265 suites  ±0   26m 59s ⏱️ + 8m 29s
712 tests ±0  706 ✅ ±0  5 💤 ±0  1 ❌ ±0 
728 runs  ±0  722 ✅ ±0  5 💤 ±0  1 ❌ ±0 

For more details on these failures, see this check.

Results for commit 4d67e4c. ± Comparison against base commit 68c2469.

♻️ This comment has been updated with latest results.

[quiet-node]

LG but left a nit and a question

[quiet-node]

Also Codacy seems to fail with one item https://github.com/hiero-ledger/hiero-json-rpc-relay/pull/4195/checks?check_run_id=48407035874

[acuarica]

should we move this to the smart-contracts repo? I may be late to the party, but here we are not testing any Relay specific functionality, so maybe the smart-contracts repo is a better place for this.

[natanasow]

should we move this to the smart-contracts repo? I may be late to the party, but here we are not testing any Relay specific functionality, so maybe the smart-contracts repo is a better place for this.

It's tightly coupled with the LayerZero example, and that's why we put it here. We need to duplicate almost the entire LayerZero example into smart-contracts to make it work for the Stargate contracts. That's the main reason.

Another question might be why we don't move the LZ example within the smart-contracts? - Hardhat projects support only one version of ethers within it. In the smart-contracts repo, we're using ethers v6 while the LZ example requires ethers v5. It's a known issue, and as far as I know, they're working on bumping it (here is the discussion - LayerZero-Labs/LayerZero-v2#22). Once they fix it, we can move the LZ example in the smart-contracts and make the relay repo cleaner.

[quiet-node]

Looks cleaner now but seems like it's breaking the flow.

[quiet-node]

LGTM! Great work as always!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main    #4195      +/-   ##
==========================================
+ Coverage   95.46%   95.59%   +0.13%     
==========================================
  Files         121      121              
  Lines       20106    19911     -195     
  Branches     1732     1732              
==========================================
- Hits        19194    19034     -160     
+ Misses        886      851      -35     
  Partials       26       26              

Flag	Coverage Δ
config-service	98.80% <ø> (ø)
relay	90.65% <ø> (-0.09%)	⬇️
server	88.82% <ø> (ø)
ws-server	53.86% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 14 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.