Refund Logic

This describes the refund logic required for certain implementations of client-side logic, such as omnichain tokens.

In some implementations of client-side logic that involve real assets (for example, the Asterizm Omnichain Token), you need the ability to refund locked tokens if a transfer fails at one of the execution stages on the destination network.

Logic Overview

The Asterizm Protocol team has developed a native refund logic integrated into the client abstraction. Only the user address that initiated the transfer on the source network can initiate a refund; therefore, neither the Asterizm Protocol contract owner nor the client owner can do this independently.

To add a refund request, the client must call the function addRefundRequest(bytes32 _transferHash) on the client contract

The Asterizm Protocol team has provided a way for the client owner to set a fee for calling the function, covering client expenses involved in processing a user’s refund request. This fee is specified in the native currency of the source network.

By default, the fee is set to 0. However, the client owner can call setRefundFee(uint _fee) on the client contract to set the desired fee amount.

You can retrieve the currently set fee value from uint public refundFee param on the client contract.

After a user address adds a refund request, the client’s off-chain module takes over. This module processes the refund request, checks the current status of the transfer (for instance, whether it has already been executed on the destination network), and if all checks are successful, it sends information to the destination network stating that the transfer has been placed in a refund queue. This information is stored on-chain, so once a refund is approved, it becomes impossible to execute the transfer on the destination network (this check is implemented at the client contract level). Next, the off-chain module calls the function confirmRefund(bytes32 _transferHash) on the destination network, waits for the transaction to be mined, and only then sends approval for the refund back to the source network by calling processRefundRequest(bytes32 _transferHash, bool _status) in the source network. As a result, the user is refunded the coins/tokens they sent or burned during the transfer initialization.

If the client’s off-chain module rejects the refund request (for example, if the transfer has already been successfully executed on the destination network), the same function processRefundRequest(bytes32 _transferHash, bool _status) is called in the source network, but the value passed to _status is false. In this case, no coins/tokens are refunded to the user.

Integration Logic

Refund logic is disabled by default, so to activate it, you need to complete three steps:

1. Enable the refund logic. For this, set the internal parameter refundLogicIsAvailable = true (example - https://github.com/Asterizm-Protocol/asterizm-contracts-evm/blob/master/contracts/demo/MultichainToken.sol#L19)

2. When the client initializes a transfer, add a function call to include that transfer in a pool of transfers that support the refund logic (example - https://github.com/Asterizm-Protocol/asterizm-contracts-evm/blob/master/contracts/demo/MultichainToken.sol#L37). This pool is used to validate the transfer at the moment the client creates a refund request.

3. Implement an internal function for refunding native coins (_refundCoins(address _targetAddress, uint _amount)) or tokens (_refundTokens(address _targetAddress, uint _amount, address _tokenAddress)), depending on what the user sends during transfer initialization and what needs to be refunded in the event of approval (example - https://github.com/Asterizm-Protocol/asterizm-contracts-evm/blob/master/contracts/demo/MultichainToken.sol#L74). This step is optional, because by default, the refund logic already includes standard functions for sending native coins (https://github.com/Asterizm-Protocol/asterizm-contracts-evm/blob/master/contracts/base/AsterizmRefund.sol#L164) and tokens (https://github.com/Asterizm-Protocol/asterizm-contracts-evm/blob/master/contracts/base/AsterizmRefund.sol#L175)

After completing these steps, the client contract can work with the refund logic

Adding Refund Request

Only the user address that initiated the transfer on the source network can add a refund request. Accordingly, to begin a refund, the user’s address must call the function addRefundRequest(bytes32 _transferHash) on the client contract. After this action, the client off-chain module will start processing the request.