Stargate

Connector for Stargate, a cross-chain bridge built on LayerZero messaging.

almanak.framework.connectors.stargate

Stargate Bridge Adapter Package.

This package provides the StargateBridgeAdapter for cross-chain transfers via the Stargate protocol built on LayerZero messaging.

Stargate Protocol: - Unified liquidity pools across chains - LayerZero for cross-chain messaging - Instant guaranteed finality - Native asset transfers (no wrapped tokens)

Example

from almanak.framework.connectors.stargate import StargateBridgeAdapter

adapter = StargateBridgeAdapter() quote = adapter.get_quote( token="USDC", amount=Decimal("1000"), from_chain="arbitrum", to_chain="optimism", )

StargateBridgeAdapter

StargateBridgeAdapter(
    config: StargateConfig | None = None,
    token_resolver: TokenResolver | None = None,
)

Bases: BridgeAdapter

Stargate Protocol bridge adapter implementation.

Provides integration with the Stargate bridge for cross-chain transfers using LayerZero messaging infrastructure.

Features: - Unified liquidity pools for efficient capital utilization - Instant guaranteed finality via LayerZero messaging - Native asset transfers without wrapped tokens - Support for USDC, USDT, ETH across major chains

Example

adapter = StargateBridgeAdapter()

Get quote

quote = adapter.get_quote( token="USDC", amount=Decimal("1000"), from_chain="arbitrum", to_chain="optimism", )

Build transaction

tx = adapter.build_deposit_tx(quote, "0xRecipient...")

Check status after deposit

status = adapter.check_status(deposit_tx_hash)

Initialize Stargate bridge adapter.

参数：

名称	类型	描述	默认
config	StargateConfig | None	Optional configuration. Uses defaults if not provided.	None
token_resolver	TokenResolver | None	Optional TokenResolver instance. If None, uses singleton.	None

name property

name: str

Get bridge adapter name.

supported_tokens property

supported_tokens: list[str]

Get list of supported tokens.

supported_routes property

supported_routes: list[BridgeRoute]

Get list of supported bridge routes.

get_quote

get_quote(
    token: str,
    amount: Decimal,
    from_chain: str,
    to_chain: str,
    max_slippage: Decimal = Decimal("0.005"),
) -> BridgeQuote

Get a quote for bridging tokens via Stargate.

Calculates fees including LayerZero messaging fees and protocol fees for the specified transfer.

参数：

名称	类型	描述	默认
token	str	Token symbol (e.g., "USDC", "USDT", "ETH")	必需
amount	Decimal	Amount to bridge in token units	必需
from_chain	str	Source chain (e.g., "arbitrum", "optimism")	必需
to_chain	str	Destination chain	必需
max_slippage	Decimal	Maximum slippage tolerance (default 0.5%)	Decimal('0.005')

返回：

类型	描述
BridgeQuote	BridgeQuote with fee, timing, and route information

引发：

类型	描述
StargateQuoteError	If quote cannot be retrieved

build_deposit_tx

build_deposit_tx(
    quote: BridgeQuote, recipient: str
) -> dict[str, Any]

Build the deposit transaction for a Stargate bridge transfer.

Creates the transaction data to call send() on the Stargate OFT/Pool contract.

参数：

名称	类型	描述	默认
quote	BridgeQuote	BridgeQuote from get_quote()	必需
recipient	str	Address to receive tokens on destination chain	必需

返回：

类型	描述
dict[str, Any]	Transaction data dict with 'to', 'value', 'data' fields

引发：

类型	描述
StargateTransactionError	If transaction cannot be built

check_status

check_status(bridge_deposit_id: str) -> BridgeStatus

Check the status of a Stargate bridge transfer.

Polls the LayerZero scan API to check if the cross-chain message has been delivered on the destination chain.

参数：

名称	类型	描述	默认
bridge_deposit_id	str	Source chain deposit transaction hash	必需

返回：

类型	描述
BridgeStatus	BridgeStatus with current transfer status

引发：

类型	描述
StargateStatusError	If status cannot be retrieved

estimate_completion_time

estimate_completion_time(
    from_chain: str, to_chain: str
) -> int

Estimate completion time for a route.

Returns typical completion time based on LayerZero messaging and chain finality requirements.

参数：

名称	类型	描述	默认
from_chain	str	Source chain identifier	必需
to_chain	str	Destination chain identifier	必需

返回：

类型	描述
int	Estimated completion time in seconds

引发：

类型	描述
StargateError	If route is not supported

StargateConfig dataclass

StargateConfig(
    api_base_url: str = "https://api.stargate.finance/v1",
    layerzero_scan_url: str = "https://api.layerzeroscan.com",
    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
    request_timeout: int = 30,
    max_retries: int = 3,
)

Configuration for Stargate bridge adapter.

属性：

名称	类型	描述
api_base_url	str	Stargate API base URL
layerzero_scan_url	str	LayerZero scan API URL for message tracking
timeout_seconds	int	Timeout for bridge operations (default 30 min)
request_timeout	int	HTTP request timeout in seconds
max_retries	int	Maximum number of retry attempts for API calls

__post_init__

__post_init__() -> None

Validate configuration.

StargateError

Bases: BridgeError

Base exception for Stargate-related errors.

StargateQuoteError

Bases: StargateError, BridgeQuoteError

Error when retrieving a Stargate quote.

StargateStatusError

Bases: StargateError, BridgeStatusError

Error when checking Stargate transfer status.

StargateTransactionError

Bases: StargateError, BridgeTransactionError

Error when building or submitting a Stargate transaction.

StargateReceiptParser

StargateReceiptParser(**kwargs: Any)

Receipt parser for Stargate V2 bridge deposits.

Initialize StargateReceiptParser.

参数：

名称	类型	描述	默认
**kwargs	Any	Keyword arguments passed by the receipt_registry. chain: Source chain name for token-decimal resolution.	{}

parse_receipt

parse_receipt(receipt: dict[str, Any]) -> dict[str, Any]

Return a minimal parsed view of the receipt for cache reuse.

extract_bridge_data

extract_bridge_data(
    receipt: dict[str, Any],
    *,
    from_chain: str | None = None,
    to_chain: str | None = None,
    token: str | None = None,
    amount: str | Decimal | None = None,
    bridge: str | None = None,
    expected_amount_out: str | Decimal | None = None,
) -> BridgeData | None

Extract typed bridge data from a Stargate deposit receipt.