GlacisTokenClient

The base of your cross-chain token transfer contracts.

GlacisTokenClient is a smart contract base that can be used by developers to interact with token passing features that Glacis has to offer. By inheriting from GlacisTokenClient, a smart contract is able to send and receive messages and tokens across chains through the GlacisTokenMediator with specific security/availability features. You can discover the source smart contract GlacisTokenClient.sol in this repository. There is also an Ownable variant, GlacisTokenClientOwnable.sol.

This contract inherits from GlacisClient extending its message passing capabilities with token passing features, it communicates with GlacisTokenMediator.sol to perform message and/or token routing actions through Glacis infrastructure.

These are the constructor arguments for GlacisTokenClient:

• The address for GlacisRouter

• The address for GlacisTokenMediator to create the underlying GlacisClient

• The default GMP quorum for this contract to effectively receive a message

    constructor(
        address glacisTokenMediator_,
        address glacisRouter_,
        uint256 quorum
    ) GlacisClient(glacisRouter_, quorum) {
        GLACIS_TOKEN_ROUTER = glacisTokenMediator_;
    }

The Route Function

GlacisTokenClient has multiple internal route functions that mirror the route functions that GlacisRouter provides, each which return a bytes32 message ID:

• _sendMessageAndTokens__abstract( uint256 chainId, address to, uint8 gmp, bytes memory payload, uint256 gasPayment, address token, uint256 tokenAmount ) internal returns (bytes32)

    Convenient method - Routes message and tokens to destination through GlacisTokenMediator using specified GMP without any additional feature

• _sendMessageAndTokens__redundant( uint256 chainId, address to, uint8[] memory gmps, uint256[] memory fees, bytes memory payload, uint256 gasPayment, address token, uint256 tokenAmount ) internal returns (bytes32)

    Convenient method - Routes message and tokens to destination through the specific GMP without any additional Glacis Features

• _sendMessageAndTokens__retriable( uint256 chainId, address to, uint8[] memory gmps, uint256[] memory fees, bytes memory payload, uint256 gasPayment, address token, uint256 tokenAmount ) internal returns (bytes32)

    Convenient method - Routes message and tokens to destination through GlacisTokenMediator using specified GMPs with redundancy feature

• _sendMessageAndTokens( uint256 chainId, address to, bytes memory payload, uint8[] memory gmps, uint256[] memory fees, bool retriable, address token, uint256 tokenAmount, uint256 gasPayment ) internal returns (bytes32)

    Routes message and tokens to destination through GlacisTokenMediator using any feature

The following parameters are applicable to each of these route functions, similar to GlacisTokenMediator:

Parameter Name	Parameter Description
uint256 chainId	The Glacis chain ID of the blockchain that you wish to send a message and/or tokens to
bytes32 to	The address of the destination contract that you are sending a message and/or tokens to
bytes memory payload	The payload of data (message) that you wish to send to the destination contract
address[] memory adapters	An array of adapters to send the message over, such as an Axelar adapter. Can be an address if you wish to use an adapter that Glacis does not use, otherwise it can be a GMP ID stored as an address
address adapter	A single adapter for the message to send over, used in lieu of the adapters parameter for conveniently defining a single GMP route
GlacisRouter.CrossChainGas[] memory fees	An array of fees that correspond to the amount provided to each adapter. This is a parallel array to the adapters parameter. Its rules are the same as in the GlacisRouter
address refundAddress	The address to which excess native currency is sent to if an adapter deems that the user overpaid
bool retryable	Whether to allow the message to be retried (stores owner of the message ID on-chain, slightly more gas expensive)
uint256 gasPayment	The amount of native currency to forward to the GlacisRouter to pay for cross-chain gas fees
address token	The address of the XERC20 token you wish to send to the destination contract
uint256 tokenAmount	The amount of XERC20 tokens you wish to send to the destination contract

Each of the routing functions returns a bytes32, which is the Glacis message ID for the routing. The more verbose route function also returns a uint256 nonce.

The Retry Route

An additional route is provided within GlacisTokenClient, which doesn't send a new message and/or tokens. Instead, it resends a previous message and tokens so long as it receives identical input.

• _retrySendWithTokens( uint256 chainId, address to, uint8[] memory gmps, uint256[] memory fees, bytes memory payload, bytes32 messageId, uint256 nonce, uint256 gasPayment, address token, uint256 tokenAmount ) internal returns (bytes32)

Two additional parameters are required with this function:

Parameter Name	Parameter Description
bytes32 messageId	The Glacis message ID of the original message
uint256 nonce	The nonce of the message, which can be retrieved in the original message's event log

Keep in mind that in the GlacisTokenMediator, only the original sender can retry routes. If this internal function is exposed publicly, anyone can retry on your smart contract's behalf.

The Receive Message Function

The GlacisTokenMediator will call the receiveMessageWithTokens function within your GlacisTokenClient whenever there is a message sent to your smart contract. You must override the following internal function to react to cross-chain messages:

• function _receiveMessageWithTokens( uint8[] memory fromGmpIds, uint256 fromChainId, address fromAddress, address toAddress, bytes memory payload, address token, uint256 tokenAmount ) internal virtual {}

The parameters involved with this function are:

Parameter Name	Parameter Description
address[] memory fromAdapters	The adapters through which the messages were received
uint256 fromChainId	The Glacis chain ID of the message's source/origin
bytes32 fromAddress	The address of the message's source/origin
bytes memory payload	The generic bytes payload of the message, which can be decoded to your liking
address token	The token that was sent with the message
uint256 tokenAmount	The amount of the token that was sent with this message

Adding Routes for Access Control

This operation is inherited so it is performed exactly as in GlacisClient

Setting Quorum

This operation is inherited so it is performed exactly as in GlacisClient

Read-Only

These are some of the read-only functions in GlacisClient:

• GLACIS_TOKEN_ROUTER() returns(address) — returns the address set as the GlacisTokenMediator, which was set in the constructor

• isAllowedRoute(GlacisRoute memory accessRoute) returns(bool) — returns true if the provided route is available, false otherwise. Used by the GlacisRouter to verify access

Errors

Glacis is not compatible with fee-on-transfer tokens.

GlacisTokenClient includes the following errors, which you might encounter:

Error Name	Error Description
GlacisTokenClient__CanOnlyBeCalledByTokenRouter()	Occurs when an address that is not the GlacisTokenMediator attempts to call the receiveMessage function