SettlementChainGateway

Git Source

Inherits: ISettlementChainGateway, Migratable, Initializable

A SettlementChainGateway exposes the ability to send parameters to any app chain gateways, via their respective inboxes on the settlement chain.

State Variables

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

appChainGateway

The address of the app chain gateway.

address public immutable appChainGateway;

feeToken

The address of the fee token on the settlement chain, that is used to pay for gas on app chains.

address public immutable feeToken;

_underlyingFeeToken

The address of the token underlying the fee token.

address internal immutable _underlyingFeeToken;

_feeTokenDecimals

The number of decimals of the fee token.

uint8 internal immutable _feeTokenDecimals;

_receiveDepositDataLength

The length of the submission data for the receiveDeposit call to the app chain gateway.

uint256 internal immutable _receiveDepositDataLength;

_scale

The precomputed scaling factor between the fee token's decimals and 18 decimals (wei).

uint256 internal immutable _scale;

_SETTLEMENT_CHAIN_GATEWAY_STORAGE_LOCATION

bytes32 internal constant _SETTLEMENT_CHAIN_GATEWAY_STORAGE_LOCATION =
    0xa66588577d68bb28d3fa2c7238607341f39141e4eaf5f706037ae5c1c2a15700;

Functions

_getSettlementChainGatewayStorage

function _getSettlementChainGatewayStorage() internal pure returns (SettlementChainGatewayStorage storage $);

whenNotPaused

modifier whenNotPaused();

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

The parameter registry, app chain gateway, and fee token must not be the zero address.

The parameter registry, app chain gateway, and fee token are immutable so that they are inlined in the contract code, and have minimal gas cost.

constructor(address parameterRegistry_, address appChainGateway_, address feeToken_);

Parameters

initialize

Initializes the contract.

function initialize() external initializer;

deposit

Deposits fee tokens as gas token to an app chain.

function deposit(uint256 chainId_, address recipient_, uint256 amount_, uint256 gasLimit_, uint256 maxFeePerGas_)
    external
    whenNotPaused;

Parameters

depositWithPermit

Deposits fee tokens as gas token to an app chain, given caller's signed approval.

function depositWithPermit(
    uint256 chainId_,
    address recipient_,
    uint256 amount_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external whenNotPaused;

Parameters

depositFromUnderlying

Deposits fee tokens as gas token to an app chain, by wrapping underlying fee tokens.

function depositFromUnderlying(
    uint256 chainId_,
    address recipient_,
    uint256 amount_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_
) external whenNotPaused;

Parameters

depositFromUnderlyingWithPermit

Deposits fee tokens as gas token to an app chain, by wrapping underlying fee tokens, given caller's signed approval.

function depositFromUnderlyingWithPermit(
    uint256 chainId_,
    address recipient_,
    uint256 amount_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external whenNotPaused;

Parameters

sendParameters

Sends parameters to the app chain as retryable tickets (which may be a direct contract call).

This will perform an L2->L3 message, where the settlement gateway alias must have enough balance to pay for the function call (IAppChainGateway.receiveParameters), and the gas limit and price must suffice. If not, the message will remain as a retryable ticket on the app chain, that anyone can trigger and pay for.

function sendParameters(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_
) external whenNotPaused returns (uint256 totalSent_);

Parameters

Returns

sendParametersWithPermit

Sends parameters to the app chain as retryable tickets (which may be a direct contract call), given caller's signed approval to pull fee tokens.

This will perform an L2->L3 message, where the settlement gateway alias must have enough balance to pay for the function call (IAppChainGateway.receiveParameters), and the gas limit and price must suffice. If not, the message will remain as a retryable ticket on the app chain, that anyone can trigger and pay for.

function sendParametersWithPermit(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external whenNotPaused returns (uint256 totalSent_);

Parameters

Returns

sendParametersFromUnderlying

Sends parameters to the app chain as retryable tickets (which may be a direct contract call).

This will perform an L2->L3 message, where the settlement gateway alias must have enough balance to pay for the function call (IAppChainGateway.receiveParameters), and the gas limit and price must suffice. If not, the message will remain as a retryable ticket on the app chain, that anyone can trigger and pay for.

function sendParametersFromUnderlying(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_
) external whenNotPaused returns (uint256 totalSent_);

Parameters

Returns

sendParametersFromUnderlyingWithPermit

Sends parameters to the app chain as retryable tickets (which may be a direct contract call), given caller's signed approval to pull underlying fee tokens.

This will perform an L2->L3 message, where the settlement gateway alias must have enough balance to pay for the function call (IAppChainGateway.receiveParameters), and the gas limit and price must suffice. If not, the message will remain as a retryable ticket on the app chain, that anyone can trigger and pay for.

function sendParametersFromUnderlyingWithPermit(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external whenNotPaused returns (uint256 totalSent_);

Parameters

Returns

updateInbox

Updates the inbox for a chain ID.

function updateInbox(uint256 chainId_) external;

Parameters

updatePauseStatus

Updates the pause status.

Ensures the new pause status is not equal to the old pause status.

function updatePauseStatus() external;

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

receiveWithdrawal

Receives withdrawal of fee tokens from the app chain gateway.

function receiveWithdrawal(address recipient_) external returns (uint256 amount_);

Parameters

Returns

receiveWithdrawalIntoUnderlying

Receives withdrawal of fee tokens from the app chain gateway, and unwraps them into underlying fee tokens.

function receiveWithdrawalIntoUnderlying(address recipient_) external returns (uint256 amount_);

Parameters

Returns

appChainAlias

This contract's alias address on the L3 app chain.

function appChainAlias() public view returns (address alias_);

inboxParameterKey

The parameter registry key used to fetch the inbox.

function inboxParameterKey() public pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() public pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() public pure returns (string memory key_);

paused

The pause status.

function paused() external view returns (bool paused_);

calculateMaxDepositFee

Calculates the maximum fees (in wei, 18 decimals) that will be consumed for a deposit to an app chain.

function calculateMaxDepositFee(uint256 chainId_, uint256 gasLimit_, uint256 maxFeePerGas_, uint256 maxBaseFee_)
    external
    view
    returns (uint256 fees_);

Parameters

Returns

getInbox

The inbox address for a chain ID.

function getInbox(uint256 chainId_) external view returns (address inbox_);

_depositFeeToken

Transfers amount_ of fee tokens from the caller to this contract to satisfy a deposit to an app chain.

function _depositFeeToken(
    uint256 chainId_,
    address recipient_,
    uint256 amount_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_
) internal;

_depositFromUnderlying

Transfers amount_ of underlying fee tokens from the caller to this contract to satisfy a deposit to an app chain.

function _depositFromUnderlying(
    uint256 chainId_,
    address recipient_,
    uint256 amount_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_
) internal;

_deposit

Deposits fee tokens into an inbox, to be used as native gas token on the app chain.

function _deposit(uint256 chainId_, address recipient_, uint256 amount_, uint256 gasLimit_, uint256 maxFeePerGas_)
    internal;

_pullAndConvertUnderlying

Pull the underlying fee tokens from the caller, and convert them to fee tokens.

function _pullAndConvertUnderlying(uint256 amount_) internal;

_sendParametersFromFeeToken

Sends parameters to the app chains via a retryable tickets, pulling fee tokens from the caller.

function _sendParametersFromFeeToken(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_
) internal returns (uint256 totalSent_);

_sendParametersFromUnderlying

Sends parameters to the app chains via a retryable tickets, pulling underlying fee tokens from the caller.

function _sendParametersFromUnderlying(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_
) internal returns (uint256 totalSent_);

_sendParameters

Sends parameters to the app chains via a retryable tickets.

function _sendParameters(
    uint256[] calldata chainIds_,
    string[] calldata keys_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 amountToSend_
) internal;

_createRetryableTicket

Creates a retryable ticket, via the inbox, to perform a call to the app chain gateway (on the app chain).

feeTokenAmount_ (converted to 18 decimals) must be greater or equal to maxSubmissionCost_ + callValue_ + (gasLimit_ * maxFeePerGas_)

function _createRetryableTicket(
    address inbox_,
    uint256 callValue_,
    uint256 maxSubmissionCost_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 feeTokenAmount_,
    bytes memory data_
) internal returns (uint256 messageNumber_);

Parameters

Returns

_usePermit

Uses a permit to approve the deposit of amount_ of token_ from the caller to this contract.

Silently ignore a failing permit, as it may indicate that the permit was already used and/or the allowance has already been approved.

function _usePermit(address token_, uint256 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_) internal;

_prepareWithdrawal

Prepares a withdrawal of fee tokens by querying the available balance and emitting an event.

function _prepareWithdrawal(address recipient_) internal returns (uint256 amount_);

_calculateMaxCosts

Calculates the total fees to submit a retryable ticket and call the app chain gateway on the app chain.

function _calculateMaxCosts(
    address inbox_,
    uint256 dataLength_,
    uint256 gasLimit_,
    uint256 maxFeePerGas_,
    uint256 maxBaseFee_
) internal view returns (uint256 maxSubmissionCost_, uint256 maxTransactionCost_);

Parameters

Returns

_convertToWei

function _convertToWei(uint256 value_) internal view returns (uint256 wei_);

_convertFromWei

function _convertFromWei(uint256 value_) internal view returns (uint256 newValue_);

_getInboxKey

Returns the inbox-specific key used to query to parameter registry to determine the inbox for a chain ID. The inbox-specific key is the concatenation of the inbox parameter key and the chain ID. For example, if the inbox parameter key is "xmtp.settlementChainGateway.inbox", then the key for chain ID 1 is "xmtp.settlementChainGateway.inbox.1".

function _getInboxKey(string memory inboxParameterKey_, uint256 chainId_) internal pure returns (string memory key_);

_getInbox

function _getInbox(uint256 chainId_) internal view returns (address inbox_);

_isZero

function _isZero(address input_) internal pure returns (bool isZero_);

_revertIfPaused

function _revertIfPaused() internal view;

Structs

SettlementChainGatewayStorage

The UUPS storage for the settlement chain gateway.

Note: storage-location: erc7201:xmtp.storage.SettlementChainGateway

struct SettlementChainGatewayStorage {
    bool paused;
    uint256 nonce;
    mapping(uint256 chainId => address inbox) inboxes;
}

Properties