Qubic Bridge SC in develop. testnet

[anarojoagusti]

This is the PR for the Qubic Bridge Smart Contract (QUBIC to Ethereum and vice versa)

Purpose of the Qubic Bridge Contract

The Qubic Bridge Contract ensures seamless and secure transfer of native QUBIC tokens between the Qubic network and Ethereum using a lock-and-mint mechanism:

1. From Qubic to Ethereum:
   QUBIC tokens are locked in the contract, and equivalent wrapped QUBIC (WQUBIC) tokens are minted on Ethereum.
2. From Ethereum to Qubic:
   WQUBIC tokens are burned on Ethereum, and equivalent QUBIC tokens are unlocked on the Qubic network.

---

Design Features

Single-contract solution

Tokens are locked and managed directly in this contract without relying on an external locking contract, simplifying the architecture.

Role-based access control

The contract includes role-based permissions for secure and decentralized operations:

• Admin: Manages the contract's key settings and roles.
• Managers: Authorized to confirm and refund orders.

Efficient order management

The contract uses a HashMap for rapid order lookups and tracks the lifecycle of each order, ensuring data integrity.

Comprehensive state tracking

The contract maintains variables to monitor locked tokens, total received tokens, and order states, preventing invalid state transitions.

---

Roles and Permissions

Admin

• Can assign a new admin (setAdmin).
• Can add or remove managers (addManager, removeManager).

Managers

• Can confirm bridge orders (completeOrder).
• Can refund bridge orders (refundOrder).

Users

• Can create bridge orders (createOrder).
• Can query the status of their orders (getOrder).

---

Core Functionalities

User Functions

createOrder

• Purpose: Creates a bridge order to transfer tokens and locks the amount in the contract.
• Inputs:
  • ethAddress (Ethereum destination address).
  • amount (number of tokens to transfer).
  • fromQubicToEthereum (transfer direction flag).
• Outputs:
  • orderId for tracking the order.
  • Status codes (e.g., 0 = Success, 1 = Invalid amount).
• Backend: Tracks orderId for further processing.

getOrder

• Purpose: Retrieves details of an existing order.
• Inputs: orderId (order identifier).
• Outputs: Order status and detailed information (OrderResponse).

---

Manager Functions

completeOrder

• Purpose: Finalizes an order by releasing/minting tokens.
• Logic:
  • Qubic to Ethereum: Ensures locked tokens are sufficient and adjusts balances.
  • Ethereum to Qubic: Verifies sufficient tokens and processes refunds/mints.
• Outputs: Operation result and a success or failure message.

refundOrder

• Purpose: Refunds tokens to the sender if the order cannot proceed.
• Logic: Validates state before processing refunds.

---

Admin Functions

1. setAdmin: Assigns a new admin to the contract.
2. addManager: Adds a new manager for operational tasks.
3. removeManager: Removes an existing manager.

---

Additional Utility Methods

• transferToContract: Allows users to deposit tokens into the contract.

---

Security Considerations

• Role-based Access Control: Ensures only authorized admins and managers can execute critical functions.
• State Validation: Prevents invalid state transitions, such as completing or refunding non-existent orders.
• Balance Validation: Verifies user and contract balances before any operations.

---

How the Contract Works

Initialization

Upon deployment, key variables such as nextOrderId and lockedTokens are initialized, and the deploying address is set as the admin.

Qubic-to-Ethereum Transfer

• Order Creation:
  Users call createOrder, which locks QUBIC tokens. Managers confirm the order by minting WQUBIC tokens on Ethereum.
• Order Completion:
  Managers call completeOrder to finalize the transaction, updating the order state and transferring/minting tokens.

Refunds

If the transfer cannot proceed, managers can call refundOrder to return the locked tokens to the sender.

---

Frontend Requirements

User Inputs

• Create Order: Requires ethAddress, amount, and fromQubicToEthereum.
• Get Order: Requires orderId.

Admin/Manager Inputs

• setAdmin: New admin's address.
• addManager/removeManager: Manager's address.
• completeOrder/refundOrder: orderId.

---

[philippwerner]

Thanks for the clear contract description and easy-to-read code!

Here is some feedback. I haven’t read everything in detail, but you can start improving some things right now.

First, about the name. Because this is in Qubic, we don’t need Qubic in the name, but rather Ethereum, because this is what is connected here. I suggest to name the file EthBridge.h and the contract state struct ETHBRIDGE (please rename BridgeContract). The state struct name in capital case letters, because it is used in many constants and macros.

Second, please include the contract in contract_core/contract_def.h by adding the following behind #include "contracts/QVAULT.h":

#undef CONTRACT_INDEX
#undef CONTRACT_STATE_TYPE
#undef CONTRACT_STATE2_TYPE

#define ETHBRIDGE_CONTRACT_INDEX 11
#define CONTRACT_INDEX ETHBRIDGE_CONTRACT_INDEX
#define CONTRACT_STATE_TYPE ETHBRIDGE
#define CONTRACT_STATE2_TYPE ETHBRIDGE2
#include "contracts/EthBridge.h"

After that, you can compile the core with MS Visual C++ 2022 and get compiler errors / warnings about your code.

It is great that you provide detailed error information with output.message, but unfortunately the output is not accessible for procedures if they are called through a transaction (only available when called from other contract).

But I recommend provide the error information via logging. Like with:

struct EthBridgeLogger
{
    uint32 _contractIndex;
    uint32 _errorCode;
    // Other data go here
    char _terminator; // Only data before "_terminator" are logged
};

With an enum of error code you can emit a log entry by: LOG_INFO(QuotteryLogger{CONTRACT_INDEX, EthBridgeError::onlyManagersCanCompleteOrders});

[philippwerner]

Here is the current draft of the contract dev docs: https://github.com/qubic/core/blob/d67fc559557793b8abe0efa56fe0c04e54c63fce/doc/contracts.md

[anarojoagusti]

Hi @krypdkat and @philipwerner, I’ve resolved all the comments and addressed the requested changes. Please review the updates when you have time. Let me know if there’s anything else that needs adjustment. Thank you!

[philippwerner]

Thanks, I will review the updates when I have time.

One important thing that I can tell you now, is that you have to implement tests with GoogleTest in the test project. See https://github.com/qubic/core/blob/main/doc/contracts.md

[philippwerner]

Thanks for your revision.

Please add contract_ethbridge.cpp to the test project and EthBridge.h to the contracts filter in the Qubic project. The files will then appear in the *.vcxproj and *.vcxproj.filters files as in https://github.com/qubic/core/pull/237/files

Please compile the test project, fix the compiler warnings, and revise the tests based on my comments. And run it to make sure all tests pass without error. Running the debug build will help you to debug the tests.

Please change the PR target branch to qubic:develop. It is qubic:main at the moment. See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request

For the finalizing the PR, you will have to remove the testnet config commit.