LZBridgeGateway

Git Source

Inherits: ILayerZeroReceiver, IVersioned, ILZBridgeGateway, Policy, PolicyReEnabler, ReEnablerGracePeriod, OffsettingRateLimiter, Rescueable

Title: LZBridgeGateway

Infrastructure policy handling LayerZero V2 endpoint communication for cross-chain OHM transfers. Performs OHM mint/burn via MINTR, manages peers, enforces options and rate limits, tracks bridged supply on canonical chains, and bounds inflow minting to previously burned OHM via mint approval. OApp-authorized endpoint operations (libraries, ULN/Executor config, messaging channel control) live on the LZEndpointDelegate policy, which is assigned via setDelegate.

Constants

MSG_BRIDGE_OHM

Returns the message type identifier for OHM bridge transfers.

uint8 public constant override MSG_BRIDGE_OHM = 1;

Returns

Name	Type	Description
<none>	uint8

_BRIDGE_OHM_DATA_LENGTH

Expected byte length of an ABI-encoded (address, uint256) bridge payload.

uint256 internal constant _BRIDGE_OHM_DATA_LENGTH = 64;

_MIN_PAYLOAD_LENGTH

Minimum ABI-encoded length for (uint8, bytes): 32 + 32 offset + 32 length.

uint256 internal constant _MIN_PAYLOAD_LENGTH = 96;

_OPTION_TYPE_3

Type 3 option type identifier.

uint16 internal constant _OPTION_TYPE_3 = 3;

_KEYCODE_MINTR

Keycode for the MINTR module dependency.

Pre-computed to avoid the runtime cost of toKeycode("MINTR").

Keycode internal constant _KEYCODE_MINTR = Keycode.wrap(0x4D494E5452);

_KEYCODE_ROLES

Keycode for the ROLES module dependency.

Pre-computed to avoid the runtime cost of toKeycode("ROLES").

Keycode internal constant _KEYCODE_ROLES = Keycode.wrap(0x524F4C4553);

LZ_ENDPOINT

The LayerZero V2 endpoint address.

address public immutable override LZ_ENDPOINT;

Returns

Name	Type	Description
<none>	address

IS_CANONICAL

Returns whether this is the canonical (mainnet) chain.

bool public immutable override IS_CANONICAL;

Returns

Name	Type	Description
<none>	bool

State Variables

MINTR

Bophades module for minting and burning OHM.

MINTRv1 public MINTR;

ohm

Returns the OHM token address.

address public override ohm;

Returns

Name	Type	Description
<none>	address

bridgedSupply

Returns the current bridged supply (canonical only).

uint256 public override bridgedSupply;

Returns

Name	Type	Description
<none>	uint256

bridgedSupplyInitialized

Returns whether the one-shot initializeBridgedSupply has already succeeded.

bool public override bridgedSupplyInitialized;

Returns

Name	Type	Description
<none>	bool

isReceiveEnabled

Whether lzReceive() can process incoming messages.

Automatically set to true by enable() and false by disable(). Can be manually set via setIsReceiveEnabled() to allow receiving while the gateway is otherwise disabled (e.g., during gateway replacements).

bool public override isReceiveEnabled;

Returns

Name	Type	Description
<none>	bool

peers

Returns the peer for a given endpoint ID.

mapping(uint32 eid_ => bytes32) public override peers;

Parameters

Name	Type	Description
eid_	uint32	The remote endpoint ID.

Returns

Name	Type	Description
<none>	bytes32	The peer address (as bytes32).

enforcedOptions

Returns the enforced options for a given endpoint and message type.

mapping(uint32 eid_ => mapping(uint16 msgType_ => bytes)) public override enforcedOptions;

Parameters

Name	Type	Description
eid_	uint32	The endpoint ID.
msgType_	uint16	The message type.

Returns

Name	Type	Description
<none>	bytes	The enforced options bytes.

Functions

onlyBridgeAdminOrAdmin

Modifier that reverts if the caller does not have the bridge_admin or admin role.

Used only by the one-shot initializeBridgedSupply; the other privileged mutators are gated by onlyBridgeConfigurator.

modifier onlyBridgeAdminOrAdmin();

_requireBridgeAdminOrAdmin

Reverts with IPolicyAdmin.NotAuthorised if msg.sender has neither the bridge_admin nor the admin role.

function _requireBridgeAdminOrAdmin() private view;

onlyBridgeConfigurator

Modifier that reverts if the caller does not have the bridge_configurator role.

Gated solely by the role; the role is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy), in which case calls are dispatched through that policy's timelock queue. Any holder that does not itself enforce a timelock on these mutators should only be granted the role temporarily for bootstrap. This contract does not enforce a timelock itself; it is enforced only by the LZBridgeAndDelegateConfig role holder. Granting bridge_configurator to any other address bypasses the timelock for these mutators.

modifier onlyBridgeConfigurator();

_requireBridgeConfigurator

Reverts with ROLESv1.ROLES_RequireRole(BRIDGE_CONFIGURATOR_ROLE) if msg.sender does not hold the bridge_configurator role.

function _requireBridgeConfigurator() private view;

constructor

Reverts if:

• The kernel address is the zero address.
• The LZ endpoint address is the zero address.
• The grace window length is zero.

constructor(
        Kernel kernel_,
        address lzEndpoint_,
        bool isCanonical_,
        uint32 grace_
    ) Policy(kernel_) ReEnablerGracePeriod(grace_);

Parameters

Name	Type	Description
kernel_	Kernel
lzEndpoint_	address
isCanonical_	bool
grace_	uint32

configureDependencies

Define module dependencies for this policy.

function configureDependencies() external override returns (Keycode[] memory dependencies);

Returns

Name	Type	Description
dependencies	Keycode[]	- Keycode array of module dependencies.

_requireMajorV1

Reverts with Policy_WrongModuleVersion if the given module major version is not 1.

function _requireMajorV1(uint8 major_) private pure;

Parameters

Name	Type	Description
major_	uint8	The major version reported by the module's VERSION().

requestPermissions

Function called by kernel to set module function permissions.

function requestPermissions()
        external
        view
        override
        returns (Permissions[] memory permissions);

Returns

Name	Type	Description
permissions	Permissions[]	- Array of keycodes and function selectors for requested permissions.

VERSION

Returns the version of the contract

function VERSION() external pure override returns (uint8 major, uint8 minor);

Returns

Name	Type	Description
major	uint8	- Major version upgrade indicates breaking change to the interface.
minor	uint8	- Minor version change retains backward-compatible interface.

_beforeEnable

Sets isReceiveEnabled to true when the gateway is enabled.

function _beforeEnable(bytes calldata) internal override;

Parameters

Name	Type	Description
_	bytes

_beforeDisable

Resets isReceiveEnabled to false if it is not already when the gateway is disabled.

function _beforeDisable(bytes calldata) internal override;

Parameters

Name	Type	Description
_	bytes

_beforeReEnable

Restores isReceiveEnabled when the manager re-enables the gateway. The grace check is inherited from ReEnablerGracePeriod via super.

function _beforeReEnable() internal override(ReEnabler, ReEnablerGracePeriod);

_authorizeSetGracePeriod

Validates that the caller is permitted to update the grace window.

Reverts if:

• The caller is not authorized to update the grace window.

Restricts setGracePeriod to the bridge_configurator role; that role is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

function _authorizeSetGracePeriod() internal view override;

_enableReceive

Sets isReceiveEnabled to true if it is not already.

Shared between _beforeEnable and _beforeReEnable because both transitions move the gateway into the enabled state with receiving allowed.

function _enableReceive() private;

burnAndSend

Burns OHM held by the gateway and sends a bridge message to a destination chain.

On canonical chains, increments bridgedSupply.

Reverts if:

• The caller does not have the bridge_facilitator role.
• The gateway is not enabled.
• The recipient address is the zero address.
• No peer exists for the destination endpoint ID.
• The rate limit would be exceeded.

function burnAndSend(
        uint32 dstEid_,
        address to_,
        uint256 amount_,
        address payable refundAddress_,
        bytes calldata extraOptions_
    )
        external
        payable
        override
        givenEnabled
        onlyRole(BRIDGE_FACILITATOR_ROLE)
        returns (MessagingReceipt memory receipt);

Parameters

Name	Type	Description
dstEid_	uint32	The LayerZero destination endpoint ID.
to_	address	The recipient address on the destination chain.
amount_	uint256	The amount of OHM to burn and send.
refundAddress_	address payable	The address to receive excess native token refund.
extraOptions_	bytes	Additional Type 3 options to combine with enforced options.

Returns

Name	Type	Description
receipt	MessagingReceipt	The LayerZero messaging receipt. receipt.fee.nativeFee is the actual native amount charged by the endpoint (may be less than msg.value; excess is refunded to refundAddress_).

estimateSendFee

Estimates the fee for sending OHM to a destination chain.

Reverts if:

• The recipient address is zero.
• No peer exists for the destination endpoint ID.

function estimateSendFee(
        uint32 dstEid_,
        address to_,
        uint256 amount_,
        bytes calldata extraOptions_
    ) external view override returns (MessagingFee memory fee);

Parameters

Name	Type	Description
dstEid_	uint32	The LayerZero destination endpoint ID.
to_	address	The recipient address on the destination chain.
amount_	uint256	The amount of OHM to send.
extraOptions_	bytes	Additional Type 3 options to combine with enforced options.

Returns

Name	Type	Description
fee	MessagingFee	The estimated messaging fee (native + lzToken).

lzReceive

Reverts if:

• Receiving is not enabled (isReceiveEnabled is false).
• The caller is not the LayerZero endpoint.
• The origin sender is not the configured peer for the source endpoint ID.
• No peer is configured for the source endpoint ID.
• The message payload is shorter than the minimum encoded length.
• The message type is not MSG_BRIDGE_OHM.
• The bridge data payload has an unexpected length.
• (Canonical) The bridged supply would underflow.
• The OHM recipient address is the zero address when the message type is MSG_BRIDGE_OHM.

function lzReceive(
        Origin calldata origin_,
        bytes32 guid_,
        bytes calldata message_,
        address,
        bytes calldata
    ) external payable override;

Parameters

Name	Type	Description
origin_	Origin
guid_	bytes32
message_	bytes
_	address
_	bytes

allowInitializePath

function allowInitializePath(Origin calldata origin_) external view override returns (bool);

Parameters

Name	Type	Description
origin_	Origin

Returns

Name	Type	Description
<none>	bool

nextNonce

function nextNonce(uint32, bytes32) external pure override returns (uint64);

Parameters

Name	Type	Description
_	uint32
_	bytes32

Returns

Name	Type	Description
<none>	uint64

setPeer

Reverts if:

• The caller does not have the admin role.

WARNING: Updating or clearing the peer for an EID strands any in-flight inbound messages from the previous peer that have already been verified on the LayerZero endpoint but not yet executed. Such messages will revert in lzReceive on the peer check and become permanently undeliverable.

Recovery requires the admin to handle each stranded message individually via the LayerZero endpoint recovery functions (skip, nilify, burn, or clear). A separate governance proposal may also be required to restore the OHM owed to the affected users, and a corresponding decreaseBridgedSupply call is required to keep the bookkeeping consistent.

function setPeer(uint32 eid_, bytes32 peer_) external override onlyAdminRole;

Parameters

Name	Type	Description
eid_	uint32	The remote endpoint ID.
peer_	bytes32	The peer (remote gateway) address (bytes32 or bytes32(0) to clear).

setIsReceiveEnabled

Reverts if:

• The caller does not have the emergency or admin role.
• The gateway is currently enabled.
• The value is already in the desired state.

The flag isReceiveEnabled is managed automatically by the policy lifecycle: enable() and the re-enable path set it to true, and disable() resets it to false. This function provides a manual override for the disabled state, so that a disabled gateway can keep delivering in-flight inbound LayerZero messages after sending stops.

The intended use case is a gateway replacement on a given chain. The admin calls disable followed by setIsReceiveEnabled(true). The old gateway is disabled (which stops outbound sends), but any inbound LayerZero messages already in flight to the old gateway can still settle on it. Once the migration is complete, the old gateway is deactivated in the Kernel.

If disable is triggered by the emergency role without a proposal, it automatically sets isReceiveEnabled to false. If it is confirmed that re-enabling is safe, the manager can call reEnable within the grace window, which automatically sets isReceiveEnabled to true.

function setIsReceiveEnabled(
        bool isReceiveEnabled_
    ) external override givenDisabled onlyEmergencyOrAdminRole;

Parameters

Name	Type	Description
isReceiveEnabled_	bool	The desired state of the flag.

setDelegate

Sets the delegate on the LayerZero endpoint.

The delegate is authorized to configure anything on the LayerZero endpoint

on behalf of this contract (e.g. send/receive libraries, DVN config).

delegate_ must be nonzero: the delegate cannot be cleared, only replaced

with another nonzero address.

Reverts if:

• The caller does not have the bridge_configurator role.
• delegate_ is the zero address.

function setDelegate(address delegate_) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
delegate_	address	The new delegate address; must be nonzero.

initializeBridgedSupply

Intended for use immediately after the OCG proposal so the DAO MS can write the computed initial bridged supply without going through the bridge_configurator role (and therefore, in the intended deployment, without waiting for the LZBridgeAndDelegateConfig timelock). After this call further mutations must go through increaseBridgedSupply / decreaseBridgedSupply.

Reverts if:

• The caller does not have the bridge_admin or admin role.
• The chain is not canonical.
• The bridged supply has already been initialized.
• The current bridged supply is non-zero.
• amount_ is zero.

function initializeBridgedSupply(uint256 amount_) external override onlyBridgeAdminOrAdmin;

Parameters

Name	Type	Description
amount_	uint256	The initial bridged supply to write.

increaseBridgedSupply

Increases the bridged supply by the given amount and syncs the MINTR mint approval.

Reverts if:

• The caller does not have the bridge_configurator role.
• IS_CANONICAL is false.
• amount_ is zero.

function increaseBridgedSupply(uint256 amount_) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
amount_	uint256	The amount to increase bridged supply by.

decreaseBridgedSupply

Decreases the bridged supply by the given amount and syncs the MINTR mint approval.

Reverts if:

• The caller does not have the bridge_configurator role.
• IS_CANONICAL is false.
• amount_ is zero.
• The bridged supply would underflow.

function decreaseBridgedSupply(uint256 amount_) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
amount_	uint256	The amount to decrease bridged supply by.

setEnforcedOptions

Sets enforced options for specific endpoint and message type combinations.

Reverts if:

• The caller does not have the admin role.
• Any option entry is not Type 3 format.

function setEnforcedOptions(
        EnforcedOptionParam[] calldata enforcedOptions_
    ) external override onlyAdminRole;

Parameters

Name	Type	Description
enforcedOptions_	EnforcedOptionParam[]	Array of enforced option parameters.

setOutRateLimits

Reverts if:

• The caller does not have the bridge_configurator role.

Decays the existing in-flight amount of the targeted outbound limit and checkpoints the counterpart inbound limit before writing the new limit and window. The counterpart inbound limit's own limit and window are preserved.

function setOutRateLimits(
        RateLimitConfig[] calldata configs_
    ) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
configs_	RateLimitConfig[]	The outbound rate limit configurations to apply.

setInRateLimits

Reverts if:

• The caller does not have the bridge_configurator role.

Symmetric with setOutRateLimits: decays the existing inbound in-flight and checkpoints the counterpart outbound limit before writing the new inbound limit and window. The counterpart outbound limit's own limit and window are preserved.

function setInRateLimits(
        RateLimitConfig[] calldata configs_
    ) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
configs_	RateLimitConfig[]	The inbound rate limit configurations to apply.

clearOutboundInFlight

Reverts if:

• The caller does not have the bridge_configurator role.

Sets inFlight to zero and refreshes lastUpdated to the current timestamp; the configured limit and window are preserved. The corresponding inbound rate limit is not affected.

function clearOutboundInFlight(
        uint32[] calldata eids_
    ) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
eids_	uint32[]	The endpoint identifiers whose outbound in-flight amount should be cleared.

clearInboundInFlight

Reverts if:

• The caller does not have the bridge_configurator role.

Sets inFlight to zero and refreshes lastUpdated to the current timestamp; the configured limit and window are preserved. The corresponding outbound rate limit is not affected.

function clearInboundInFlight(
        uint32[] calldata eids_
    ) external override onlyBridgeConfigurator;

Parameters

Name	Type	Description
eids_	uint32[]	The endpoint identifiers whose inbound in-flight amount should be cleared.

_authorizeRescue

Hook for subclasses to authorize the caller of rescue().

Implementations MUST revert if the caller is not authorised.

function _authorizeRescue() internal view override onlyManagerOrAdminRole;

combineOptions

Combines enforced options with caller-provided extra options.

Reverts if:

• Extra options are provided but are not Type 3 format.
• Extra options have length 1 (insufficient for Type 3 prefix).

function combineOptions(
        uint32 eid_,
        uint16 msgType_,
        bytes calldata extraOptions_
    ) external view override returns (bytes memory);

Parameters

Name	Type	Description
eid_	uint32	The endpoint ID.
msgType_	uint16	The message type.
extraOptions_	bytes	Caller-provided options.

Returns

Name	Type	Description
<none>	bytes	The combined options bytes.

validateSetDelegate

Validates the payload that would be passed to setDelegate.

Reverts if:

• delegate_ is the zero address.

function validateSetDelegate(address delegate_) public pure override;

Parameters

Name	Type	Description
delegate_	address	The candidate delegate address.

validateIncreaseBridgedSupply

Validates the payload that would be passed to increaseBridgedSupply.

Reverts if:

• The chain is not canonical.
• amount_ is zero.

function validateIncreaseBridgedSupply(uint256 amount_) public view override;

Parameters

Name	Type	Description
amount_	uint256	The candidate increase amount.

validateDecreaseBridgedSupply

Validates the payload that would be passed to decreaseBridgedSupply.

Reverts if:

• The chain is not canonical.
• amount_ is zero.
• The current bridgedSupply is below amount_.

function validateDecreaseBridgedSupply(uint256 amount_) public view override;

Parameters

Name	Type	Description
amount_	uint256	The candidate decrease amount.

supportsInterface

function supportsInterface(
        bytes4 interfaceId
    ) public view override(PolicyReEnabler, ReEnablerGracePeriod, Rescueable) returns (bool);

Parameters

Name	Type	Description
interfaceId	bytes4

Returns

Name	Type	Description
<none>	bool

_increaseSupplyAndMintApproval

Increments bridgedSupply by amount_ and grants the matching MINTR mint approval to the gateway.

Used on canonical chains to keep bridgedSupply and the MINTR mint approval in lockstep during outflow and forced supply increases.

function _increaseSupplyAndMintApproval(uint256 amount_) private;

Parameters

Name	Type	Description
amount_	uint256	The amount of OHM to add to bridged supply and mint approval.

_increaseMintApproval

Grants amount_ of additional MINTR mint approval to the gateway.

Wraps the MINTR call so the address(this) argument is not duplicated at each use site, saving bytecode.

function _increaseMintApproval(uint256 amount_) private;

Parameters

Name	Type	Description
amount_	uint256	The mint approval delta to add.

_setIsReceiveEnabled

Sets isReceiveEnabled and emits the corresponding event.

function _setIsReceiveEnabled(bool isReceiveEnabled_) private;

Parameters

Name	Type	Description
isReceiveEnabled_	bool	The new flag value.

_requireSupplyAtLeastAmount

Reverts with LZBridgeGateway_BridgedSupplyUnderflow if the current bridgedSupply is below amount_.

function _requireSupplyAtLeastAmount(uint256 amount_) private view;

Parameters

Name	Type	Description
amount_	uint256	The amount that would be subtracted from bridged supply.

_requireNonzeroAmount

Reverts with LZBridgeGateway_ZeroAmount if amount_ is zero.

function _requireNonzeroAmount(uint256 amount_) private pure;

Parameters

Name	Type	Description
amount_	uint256	The amount to validate.

_encodeBridgeOhmMessage

Builds the outbound bridge-OHM payload and the combined options for a given destination.

function _encodeBridgeOhmMessage(
        uint32 dstEid_,
        address to_,
        uint256 amount_,
        bytes calldata extraOptions_
    ) private view returns (bytes memory payload, bytes memory options);

Parameters

Name	Type	Description
dstEid_	uint32	The LayerZero destination endpoint ID.
to_	address	The recipient address on the destination chain.
amount_	uint256	The amount of OHM being bridged.
extraOptions_	bytes	Caller-supplied Type 3 options to merge with enforced options.

Returns

Name	Type	Description
payload	bytes	The ABI-encoded (MSG_BRIDGE_OHM, abi.encode(to_, amount_)) message.
options	bytes	The combination of enforced and caller-supplied options.

_decodeAndRoute

Decodes the message type from the payload and routes to the appropriate handler.

function _decodeAndRoute(uint32 srcEid_, bytes32 guid_, bytes calldata payload_) private;

Parameters

Name	Type	Description
srcEid_	uint32
guid_	bytes32
payload_	bytes

_receiveBridgeOhm

Processes a received OHM bridge message.

On canonical chains, decrements bridgedSupply and mints from pre-funded approval (set during outflow). On non-canonical chains, uses JIT self approval.

function _receiveBridgeOhm(uint32 srcEid_, bytes32 guid_, bytes memory data_) private;

Parameters

Name	Type	Description
srcEid_	uint32
guid_	bytes32
data_	bytes

_getPeerOrRevert

function _getPeerOrRevert(uint32 eid_) private view returns (bytes32);

Parameters

Name	Type	Description
eid_	uint32

Returns

Name	Type	Description
<none>	bytes32

_requireCanonical

function _requireCanonical() private view;

_requireNonzeroAddress

function _requireNonzeroAddress(address address_, string memory parameter_) private pure;

Parameters

Name	Type	Description
address_	address
parameter_	string

_requireNonzeroRecipient

Reverts with LZBridgeGateway_InvalidAddress("to") if to_ is the zero address.

function _requireNonzeroRecipient(address to_) private pure;

Parameters

Name	Type	Description
to_	address	The recipient address to validate.

_combineOptions

Combines enforced options with caller-provided extra options.

function _combineOptions(
        uint32 eid_,
        uint16 msgType_,
        bytes calldata extraOptions_
    ) internal view returns (bytes memory);

Parameters

Name	Type	Description
eid_	uint32
msgType_	uint16
extraOptions_	bytes

Returns

Name	Type	Description
<none>	bytes

_assertOptionsType3

Validates that calldata options bytes begin with the Type 3 prefix.

function _assertOptionsType3(bytes calldata options_) internal pure;

Parameters

Name	Type	Description
options_	bytes