ILZBridgeGateway

Git Source

Inherits: IOffsettingRateLimiter

Title: ILZBridgeGateway

Interface for the LZ Bridge Gateway infrastructure policy (LayerZero V2).

Handles LayerZero endpoint communication, OHM mint/burn via MINTR, peer management, enforced options, bidirectional rate limiting, and bridged supply tracking.

Functions

burnAndSend

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

Only callable by an address with the bridge_facilitator role. The caller must transfer OHM to the gateway before calling this function. The gateway burns the OHM via MINTR and sends a LayerZero V2 message.

On canonical chains, increments bridgedSupply.

function burnAndSend(
        uint32 dstEid_,
        address to_,
        uint256 amount_,
        address payable refundAddress_,
        bytes calldata extraOptions_
    ) external payable 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.

function estimateSendFee(
        uint32 dstEid_,
        address to_,
        uint256 amount_,
        bytes calldata extraOptions_
    ) external view 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).

setPeer

Sets the peer gateway address for a remote endpoint ID (destination).

Only callable by the admin role. Pass bytes32(0) to clear.

function setPeer(uint32 eid_, bytes32 peer_) external;

Parameters

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

setIsReceiveEnabled

Sets whether the gateway can process inbound LayerZero messages.

Only callable by the emergency or admin role.

function setIsReceiveEnabled(bool isReceiveEnabled_) external;

Parameters

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

setDelegate

Sets the delegate on the LayerZero endpoint.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

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.

function setDelegate(address delegate_) external;

Parameters

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

initializeBridgedSupply

One-shot bootstrap of the bridged supply on the canonical chain.

Only callable by the bridge_admin or admin role and only on canonical chains.

function initializeBridgedSupply(uint256 amount_) external;

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.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy). Only available on canonical chains. Used for error-recovery (e.g. supply underflow caused by misrouted messages). Delta-based to avoid race conditions with concurrent bridge messages.

function increaseBridgedSupply(uint256 amount_) external;

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.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy). Only available on canonical chains. Used for error-recovery (e.g. correcting supply after undeliverable messages). Delta-based to avoid race conditions with concurrent bridge messages.

function decreaseBridgedSupply(uint256 amount_) external;

Parameters

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

setEnforcedOptions

Sets enforced options for specific endpoint and message type combinations.

Only callable by the admin role. Each option must be Type 3.

function setEnforcedOptions(EnforcedOptionParam[] calldata enforcedOptions_) external;

Parameters

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

setOutRateLimits

Configures outbound rate limits for one or more destination endpoints.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

function setOutRateLimits(RateLimitConfig[] calldata configs_) external;

Parameters

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

setInRateLimits

Configures inbound rate limits for one or more source endpoints.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

function setInRateLimits(RateLimitConfig[] calldata configs_) external;

Parameters

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

clearOutboundInFlight

Clears the outbound in-flight amount for one or more destination endpoints.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

function clearOutboundInFlight(uint32[] calldata eids_) external;

Parameters

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

clearInboundInFlight

Clears the inbound in-flight amount for one or more source endpoints.

Only callable by the bridge_configurator role, which is expected to be granted exclusively to LZBridgeAndDelegateConfig (the timelock policy).

function clearInboundInFlight(uint32[] calldata eids_) external;

Parameters

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

validateSetDelegate

Validates the payload that would be passed to setDelegate.

Mirrors the input invariants enforced by setDelegate so that callers (for instance, a timelock policy) can fail early at queue time rather than at execution time.

function validateSetDelegate(address delegate_) external pure;

Parameters

Name	Type	Description
delegate_	address	The candidate delegate address.

validateIncreaseBridgedSupply

Validates the payload that would be passed to increaseBridgedSupply.

Mirrors the input invariants enforced by increaseBridgedSupply so that callers (for instance, a timelock policy) can fail early at queue time rather than at execution time.

function validateIncreaseBridgedSupply(uint256 amount_) external view;

Parameters

Name	Type	Description
amount_	uint256	The candidate increase amount.

validateDecreaseBridgedSupply

Validates the payload that would be passed to decreaseBridgedSupply.

Mirrors the input invariants enforced by decreaseBridgedSupply so that callers (for instance, a timelock policy) can fail early at queue time rather than at execution time.

function validateDecreaseBridgedSupply(uint256 amount_) external view;

Parameters

Name	Type	Description
amount_	uint256	The candidate decrease amount.

LZ_ENDPOINT

The LayerZero V2 endpoint address.

function LZ_ENDPOINT() external view returns (address);

Returns

Name	Type	Description
<none>	address

ohm

Returns the OHM token address.

function ohm() external view returns (address);

Returns

Name	Type	Description
<none>	address

bridgedSupply

Returns the current bridged supply (canonical only).

function bridgedSupply() external view returns (uint256);

Returns

Name	Type	Description
<none>	uint256

bridgedSupplyInitialized

Returns whether the one-shot initializeBridgedSupply has already succeeded.

function bridgedSupplyInitialized() external view returns (bool);

Returns

Name	Type	Description
<none>	bool

peers

Returns the peer for a given endpoint ID.

function peers(uint32 eid) external view returns (bytes32);

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.

function enforcedOptions(uint32 eid, uint16 msgType) external view returns (bytes memory);

Parameters

Name	Type	Description
eid	uint32	The endpoint ID.
msgType	uint16	The message type.

Returns

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

combineOptions

Combines enforced options with caller-provided extra options.

function combineOptions(
        uint32 eid_,
        uint16 msgType_,
        bytes calldata extraOptions_
    ) external view 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.

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).

function isReceiveEnabled() external view returns (bool);

Returns

Name	Type	Description
<none>	bool

IS_CANONICAL

Returns whether this is the canonical (mainnet) chain.

function IS_CANONICAL() external view returns (bool);

Returns

Name	Type	Description
<none>	bool

MSG_BRIDGE_OHM

Returns the message type identifier for OHM bridge transfers.

function MSG_BRIDGE_OHM() external view returns (uint8);

Returns

Name	Type	Description
<none>	uint8

Events

Sent

Emitted when OHM is burned and sent to another chain.

event Sent(address indexed sender, uint256 amount, uint32 indexed dstEid, bytes32 guid);

Parameters

Name	Type	Description
sender	address	The address that initiated the send.
amount	uint256	The amount of OHM sent.
dstEid	uint32	The destination endpoint ID.
guid	bytes32	The LayerZero message GUID.

Received

Emitted when OHM is received and minted from another chain.

event Received(address indexed receiver, uint256 amount, uint32 indexed srcEid, bytes32 guid);

Parameters

Name	Type	Description
receiver	address	The address that received the minted OHM.
amount	uint256	The amount of OHM minted.
srcEid	uint32	The LayerZero source endpoint ID.
guid	bytes32	The LayerZero message GUID.

PeerSet

Emitted when a peer is set for a destination endpoint.

event PeerSet(uint32 eid, bytes32 peer);

Parameters

Name	Type	Description
eid	uint32	The endpoint ID.
peer	bytes32	The peer address (bytes32).

DelegateSet

Emitted when the delegate is set on the endpoint.

event DelegateSet(address indexed delegate);

Parameters

Name	Type	Description
delegate	address	The new delegate address.

BridgedSupplyInitialized

Emitted when the bridged supply is initialized via the one-shot bootstrap path.

event BridgedSupplyInitialized(uint256 amount);

Parameters

Name	Type	Description
amount	uint256	The initial bridged supply written to the gateway.

BridgedSupplyForciblyIncreased

Emitted when bridged supply is forcibly increased by an admin.

event BridgedSupplyForciblyIncreased(uint256 amount);

Parameters

Name	Type	Description
amount	uint256	The amount added.

BridgedSupplyForciblyDecreased

Emitted when bridged supply is forcibly decreased by an admin.

event BridgedSupplyForciblyDecreased(uint256 amount);

Parameters

Name	Type	Description
amount	uint256	The amount subtracted.

BridgedSupplyIncreased

Emitted when bridged supply increases (outbound transfer on canonical chain).

event BridgedSupplyIncreased(uint256 amount);

Parameters

Name	Type	Description
amount	uint256	The amount added.

BridgedSupplyDecreased

Emitted when bridged supply decreases (inbound transfer on canonical chain).

event BridgedSupplyDecreased(uint256 amount);

Parameters

Name	Type	Description
amount	uint256	The amount subtracted.

EnforcedOptionsSet

Emitted when enforced options are set.

event EnforcedOptionsSet(EnforcedOptionParam[] enforcedOptions);

Parameters

Name	Type	Description
enforcedOptions	EnforcedOptionParam[]	The enforced option parameters.

IsReceiveEnabledSet

Emitted when the isReceiveEnabled flag is changed.

event IsReceiveEnabledSet(bool isReceiveEnabled);

Parameters

Name	Type	Description
isReceiveEnabled	bool	The new value.

Errors

LZBridgeGateway_InvalidAddress

Thrown when an address argument is the zero address.

error LZBridgeGateway_InvalidAddress(string parameter);

Parameters

Name	Type	Description
parameter	string	The name of the invalid parameter.

LZBridgeGateway_OnlyEndpoint

Thrown when msg.sender is not the LayerZero endpoint.

error LZBridgeGateway_OnlyEndpoint();

LZBridgeGateway_OnlyPeer

Thrown when a message originates from a non-peer source.

error LZBridgeGateway_OnlyPeer(uint32 eid, bytes32 sender);

Parameters

Name	Type	Description
eid	uint32	The source endpoint ID.
sender	bytes32	The sender bytes32 address.

LZBridgeGateway_NoPeer

Thrown when no peer is configured for a destination endpoint.

error LZBridgeGateway_NoPeer(uint32 eid);

Parameters

Name	Type	Description
eid	uint32	The endpoint ID.

LZBridgeGateway_InvalidMessageType

Thrown when a received message has an unknown message type.

error LZBridgeGateway_InvalidMessageType(uint8 msgType);

Parameters

Name	Type	Description
msgType	uint8	The unknown message type.

LZBridgeGateway_InvalidPayload

Thrown when a received message payload has an invalid length.

error LZBridgeGateway_InvalidPayload();

LZBridgeGateway_BridgedSupplyUnderflow

Thrown when the bridged supply would underflow on receive.

error LZBridgeGateway_BridgedSupplyUnderflow(uint256 bridgedSupply, uint256 amount);

Parameters

Name	Type	Description
bridgedSupply	uint256	The current bridged supply.
amount	uint256	The amount being received.

LZBridgeGateway_NotCanonical

Thrown when a canonical-only function is called on a non-canonical chain.

error LZBridgeGateway_NotCanonical();

LZBridgeGateway_InvalidOptions

Thrown when options are invalid (not Type 3 or malformed).

error LZBridgeGateway_InvalidOptions(bytes options);

Parameters

Name	Type	Description
options	bytes	The invalid options bytes.

LZBridgeGateway_ReceiveNotEnabled

Thrown when lzReceive is called while receiving is disabled.

error LZBridgeGateway_ReceiveNotEnabled();

LZBridgeGateway_ReceiveAlreadyInDesiredState

Thrown when setIsReceiveEnabled is called with the current value.

error LZBridgeGateway_ReceiveAlreadyInDesiredState();

LZBridgeGateway_BridgedSupplyAlreadyInitialized

Thrown when initializeBridgedSupply is called after it has already succeeded.

error LZBridgeGateway_BridgedSupplyAlreadyInitialized();

LZBridgeGateway_BridgedSupplyAlreadyNonZero

Thrown when initializeBridgedSupply is called while bridgedSupply is non-zero.

error LZBridgeGateway_BridgedSupplyAlreadyNonZero(uint256 bridgedSupply);

Parameters

Name	Type	Description
bridgedSupply	uint256	The current bridged supply.

LZBridgeGateway_ZeroAmount

Thrown when an amount argument is zero. Used by initializeBridgedSupply, increaseBridgedSupply, and decreaseBridgedSupply.

error LZBridgeGateway_ZeroAmount();