StargateBridgeAdapter
Inherits: IStargateBridgeAdapter
Title: StargateBridgeAdapter
Authors: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80), Modified from Stargate (https://github.com/stargate-protocol/stargate-v2)
Stargate v2 pooled-liquidity token-bridge facet — the third token rail beside CCTP (burn/mint) and
Across (intent): sendToken pulls the token from the caller and deposits it into the LOCAL
Stargate pool (unified liquidity), which has the DESTINATION pool credit the ERC-7930 recipient.
OUTBOUND-ONLY for plain transfers: the destination-side LayerZero receiver is Stargate's own pool,
NOT a Lattice facet — there is no inbound surface, no receiveId, no source attribution, and this
facet is never routed through OpenBridge. composeMsg/lzCompose and bus mode are DEFERRED.
Stateless delegator — logic/storage live in StargateBridgeAdapterLib. The outbound send is
nonReentrant with strict CEI, a quoted fee PRECHECK, exact-amount approval hygiene, and a dust
sweep (pools truncate to shared decimals — any un-debited remainder returns to the caller in the same
call). msg.value is the LayerZero fee EXCLUSIVELY (ERC-20 pools only in v1; StargatePoolNative is
deferred); excess fee refunds go to the calling user, never the diamond.
Notes:
- lattice-version: 0.1.0
- lattice-source: Stargate
Functions
sendToken
Sends p.amountLD of p.token (pulled from msg.sender) through its registered Stargate
pool toward the ERC-7930 p.recipient on p.destinationChainId. msg.value is the LayerZero
fee EXCLUSIVELY (quoted precheck; excess refunds to msg.sender, never the diamond).
TAXI ONLY (issue #77 Q11): the send is dispatched with EMPTY oftCmd (immediate/taxi mode) and
EMPTY composeMsg/extraOptions — bus mode (deferred batched sends) and lzCompose destination
hooks are DEFERRED to a future revision. DUST SWEEP: pools truncate amountLD to shared decimals,
so the pool may debit less than was pulled; the exact un-debited remainder is returned to
msg.sender in the same call and the diamond nets zero.
function sendToken(SendTokenParams calldata p)
external
payable
virtual
returns (bytes32 guid, uint256 amountSentLD, uint256 amountReceivedLD);Parameters
| Name | Type | Description |
|---|---|---|
| p | SendTokenParams |
Returns
| Name | Type | Description |
|---|---|---|
| guid | bytes32 | The LayerZero message guid. |
| amountSentLD | uint256 | The amount the pool ACTUALLY debited (post dust truncation). |
| amountReceivedLD | uint256 | The amount credited on the destination (post pool fees). |
registerStargateEid
Registers an EVM chainId ↔ LayerZero eid equivalence (both directions, fail-loud — identities are never remapped; zero chainId/eid rejected). Admin only.
Stargate rides LayerZero, so the eid here equals the LayerZero adapter's eid for the same chain — recorded in this adapter's OWN map (adapters never share hot-path storage).
function registerStargateEid(uint256 chainId, uint32 eid) external virtual;Parameters
| Name | Type | Description |
|---|---|---|
| chainId | uint256 | |
| eid | uint32 |
registerPool
Registers token's Stargate pool (identity — register once; StargateTokenAlreadyRegistered
on a duplicate). FAIL-CLOSED: reverts StargatePoolTokenMismatch unless pool.token() == token. Admin only.
ERC-20 pools only in v1 — never register a StargatePoolNative (its token() is address(0), so
the zero-token guard rejects it structurally). A pool upgrade cannot re-point an existing token
entry in v1 (deliberate YAGNI): ship a new adapter config instead.
function registerPool(address token, address pool) external virtual;Parameters
| Name | Type | Description |
|---|---|---|
| token | address | |
| pool | address |
stargateEidOf
The LayerZero eid registered for chainId (0 = unset).
function stargateEidOf(uint256 chainId) external view virtual returns (uint32);Parameters
| Name | Type | Description |
|---|---|---|
| chainId | uint256 |
Returns
| Name | Type | Description |
|---|---|---|
| <none> | uint32 |
stargateChainIdOf
The EVM chainId registered for eid (0 = unset).
function stargateChainIdOf(uint32 eid) external view virtual returns (uint256);Parameters
| Name | Type | Description |
|---|---|---|
| eid | uint32 |
Returns
| Name | Type | Description |
|---|---|---|
| <none> | uint256 |
poolOf
The Stargate pool registered for token (0 = unset).
function poolOf(address token) external view virtual returns (address);Parameters
| Name | Type | Description |
|---|---|---|
| token | address |
Returns
| Name | Type | Description |
|---|---|---|
| <none> | address |
quoteSendFee
Quotes the LayerZero native fee of a send, building the IDENTICAL SendParam the send path
dispatches (same internal builder — quote/send can never drift).
function quoteSendFee(SendTokenParams calldata p) external view virtual returns (uint256 nativeFee);Parameters
| Name | Type | Description |
|---|---|---|
| p | SendTokenParams |
Returns
| Name | Type | Description |
|---|---|---|
| nativeFee | uint256 |
exportSelectors
ERC-8153 selector export: this facet's cuttable selectors, tightly packed (4 bytes each).
Excludes exportSelectors() itself (0x0ef22643) - it is never cut into a diamond. Order matches
forge inspect StargateBridgeAdapter methodIdentifiers (alphabetical by signature); kept in exact parity by
ExportSelectorsParityTest. Chunks:
poolOf(address) 0x988b1fa7
quoteSendFee((bytes,address,uint256,uint256,uint256)) 0x248b67b0
registerPool(address,address) 0x7286e5e5
registerStargateEid(uint256,uint32) 0xb18dcea7
sendToken((bytes,address,uint256,uint256,uint256)) 0x396e0d4c
stargateChainIdOf(uint32) 0x67a67974
stargateEidOf(uint256) 0x385ce1dd
function exportSelectors() external pure virtual returns (bytes memory selectors);Returns
| Name | Type | Description |
|---|---|---|
| selectors | bytes |