GlacisClient
The base of your cross-chain contracts.
GlacisClient is a smart contract base that can be used by developers to interact with the features that Glacis has to offer. By inheriting from GlacisClient, a smart contract is able to send and receive messages across chains with Glacis features.
You can discover the source smart contract GlacisClient.sol
in this repository. There is also an Ownable
variant, GlacisClientOwnable.sol
.
These are the constructor arguments for GlacisClient:
The address for GlacisRouter
The default GMP quorum for this contract to effectively receive a message
The Route Function
GlacisClient has multiple internal route functions that mirror the route functions that GlacisRouter provides, each which return a bytes32 message ID:
Each of these 3 varieties perform the same function: sending an original cross-chain message. _route
is the encompassing route function that allows for complete configuration of all Glacis features. _routeSingle
allows you to easily route through a single GMP. _routeRedundant
allows you to easily route redundant messages (each message has the same ID and data) through multiple GMPs.
The following parameters are applicable to each of these route functions, similar to GlacisRouter:
Parameter Name | Parameter Description |
---|---|
uint256 chainId | The Glacis chain ID of the blockchain that you wish to send a message to |
address to | The address of the destination contract that you are sending a message to |
bytes memory payload | The payload of data that you wish to send to the destination contract |
uint8[] memory gmps | An array of GMP IDs that you wish the message to send over (identical messages will be sent over with the same message ID, which helps with redundancy) |
uint8 gmp | A single GMP ID for the message to send over, used in lieu of the gmps parameter for conveniently defining a single GMP route |
bool retriable | 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 |
Each of the routing functions returns a bytes32
, which is the Glacis message ID for the routing.
The Retry Route
An additional route is provided within GlacisClient, which doesn't send a new message. Instead, it resends a previous message so long as it receives identical input.
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 GlacisRouter, 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 GlacisRouter will call the receiveMessage function within your GlacisClient whenever there is a message sent to your smart contract. You must override the following internal function to react to cross-chain messages:
The parameters involved with this function are:
Parameter Name | Parameter Description |
---|---|
uint8 fromGmpId | The Glacis GMP ID through which the most recent message was received |
uint256 sourceChain | The Glacis chain ID of the message's source/origin |
address sourceAddress | The address of the message's source/origin |
address to | The destination address of the message (your smart contract) |
bytes calldata payload | The generic bytes payload of the message, which can be decoded to your liking |
Adding Routes for Access Control
You must set up routes within your instance of GlacisClient before it can receive messages. To do so, use the following function:
addAllowedRoute(GlacisRoute memory allowedRoute)
The GlacisRoute struct is defined as:
Leaving any value as 0 indicates that it is a wildcard route. You can have multiple routes at a time. To remove a route, use one of the following functions:
removeAllowedRoute(GlacisRoute calldata route)
removeAllAllowedRoutes()
Setting Quorum
Quorum is an important concept for Glacis, as it defines how many times a message with a specific message ID must be received before glacis calls your receiveMessage
function. It is most likely that this number should be 1
, but you can increase this number if you intend to have greater security through higher redundancy.
You can set the quorum's default value in the constructor by setting the quorum
value.
If you wish to instead manually handle quorum per message, override the getQuorum
function:
function getQuorum(GlacisCommons.GlacisData memory glacisData, bytes memory payload) external view virtual returns (uint256)
The parameters involved with this function are:
Parameter Name | Parameter Description |
---|---|
GlacisCommons.GlacisData memory glacisData | The Glacis metadata surrounding the message, found within GlacisCommons |
bytes memory payload | The generic payload data associated with the function |
Read-Only
These are some of the read-only functions in GlacisClient:
glacisRouter() returns(address) — returns the address set as the GlacisRouter, 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
GlacisClient includes the following errors, which you might encounter:
Error Name | Error Description |
---|---|
GlacisClient**CanOnlyBeCalledByRouter | Occurs when an address that is not the GlacisRouter attempts to call the receiveMessage function |
GlacisClient**InvalidRouterAddress | Occurs when constructing the GlacisClient with an empty value for the GlacisRouter |
Last updated