Omnisea

Omnisea is the permissionless ERC-20 entrypoint. It coordinates five non-upgradeable contracts: the core, Router, Registry, Vault, and Fees Manager. The Router is the LayerZero OApp; the core itself does not expose lzReceive.

Composition

struct ComposeParams {
    address composer;
    uint128 gasLimit;
    bytes message;
}

Use ComposeParams(address(0), 0, "") for a plain transfer. A nonzero composer requires nonzero gas and a separate index-0 LayerZero lzCompose option.

Send functions

Canonical token

function quoteSendOriginal(
    uint32 dstEid,
    address originalToken,
    uint256 amount,
    address recipient,
    bool isFirstTransfer,
    ComposeParams calldata compose,
    bytes calldata options
) external view returns (uint256 totalFee);

function sendOriginal(
    uint32 dstEid,
    address originalToken,
    uint256 amount,
    address recipient,
    bool isFirstTransfer,
    ComposeParams calldata compose,
    bytes calldata options
) external payable returns (MessagingReceipt memory);

The core transfers the token directly from the sender to OmniseaVault, measures the received balance delta, records that exact amount as backing, and sends it through the Router. RepresentationMustUseSendOFT prevents treating a local Omniasset as an original.

Omniasset representation

function quoteSendOFT(
    uint32 dstEid,
    address representation,
    uint256 amount,
    address recipient,
    bool isFirstTransfer,
    ComposeParams calldata compose,
    bytes calldata options
) external view returns (uint256 totalFee);

function sendOFT(
    uint32 dstEid,
    address representation,
    uint256 amount,
    address recipient,
    bool isFirstTransfer,
    ComposeParams calldata compose,
    bytes calldata options
) external payable returns (MessagingReceipt memory);

The local OFT burns from the sender. The next chain mints the same origin identity, or the original chain unlocks canonical backing.

Quotes include the LayerZero fee and flat Omnisea fee. Standard EndpointV2 chains require exact msg.value; fee-token endpoints require ERC-20 approval and zero msg.value.

Identity

function representationFor(uint32 originalChainId, uint8 addressType, bytes32 originalToken)
    external view returns (address);

function predictRepresentation(uint32 originalChainId, uint8 addressType, bytes32 originalToken)
    external view returns (address);

mapping(address representation => OriginalToken original) public oftToOriginal;
mapping(bytes32 originalTokenKey => address representation) public originalToOFT;

The current system accepts EVM address type 1 only. The Registry stores the original chain and token, freezes om{symbol} / {name} ({origin chain}), and copies that rendered identity unchanged across multi-hop transfers.

Module reads

function router() external view returns (address);
function registry() external view returns (address);
function vault() external view returns (address);
function feesManager() external view returns (address);
function lockedBalance(address token) external view returns (uint256);
function endpointNativeToken() external view returns (address);
function minTransferGas() external view returns (uint128);
function minCreationGas() external view returns (uint128);

Read peer, activation, chain identity, and failed-message state on OmniseaRouter. Read fee caps, receiver, issuer attribution, and unpaid liabilities on OmniseaFeesManager.

Retry and restore

Anyone can call the core:

function retryFailedMessage(bytes32 guid) external;
function quoteRestore(bytes32 guid, bytes calldata options) external view returns (uint256);
function restoreFailedMessage(bytes32 guid, bytes calldata options)
    external payable returns (MessagingReceipt memory);

A normal execution failure is cached by the Router. Retry cannot repeat canonical owner synchronization. Restore sends a composition-free refund to the original sender and charges no protocol fee. Read Failed messages.

Owner functions

Core Safe:

setFixedProtocolFee(uint256)
setFixedFeeTokenProtocolFee(uint256)
setProtocolFeeReceiver(address)
setTokenIssuer(uint32,address,address)
authorizeOftFeature(address,OFT.Feature)
withdrawProtocolFees(address,uint256)
withdrawFeeTokenProtocolFees(address,address,uint256)
withdrawIssuerProtocolFees(address,address,uint256)
withdrawIssuerFeeTokenProtocolFees(address,address,address,uint256)
recoverVaultSurplus(address,address,uint256)
recoverCoreERC20(address,address,uint256)
recoverRouterERC20(address,address,uint256)
recoverRegistryERC20(address,address,uint256)
recoverFeesSurplus(address,address,uint256)

Router Safe:

setPeer(uint32,bytes32)
setChainIdForEid(uint32,uint32)
setLayerZeroDelegate(address)
setMinTransferGas(uint128)
setMinCreationGas(uint128)

Peers and chain IDs are set-once. Vault recovery can take only balanceOf(vault) - lockedBalance[token]. Fees Manager recovery excludes unpaid liabilities. No owner function can upgrade the system, pause a route, replace a peer, or arbitrarily withdraw backing.

Composition events

The core emits ComposeQueued with the GUID, composer, local token, recipient, amount, gas limit, and application-message hash. The Router also emits its transport-level ComposeQueued. Application execution happens later through LayerZero and has independent retry behavior.

Read Destination composition for the authenticated receiver base contract.