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.

Parameters:

Name	Type	Description	Default
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.

Parameters:

Name	Type	Description	Default
token	str	Token symbol (e.g., "USDC", "USDT", "ETH")	required
amount	Decimal	Amount to bridge in token units	required
from_chain	str	Source chain (e.g., "arbitrum", "optimism")	required
to_chain	str	Destination chain	required
max_slippage	Decimal	Maximum slippage tolerance (default 0.5%)	Decimal('0.005')

Returns:

Type	Description
BridgeQuote	BridgeQuote with fee, timing, and route information

Raises:

Type	Description
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.

Parameters:

Name	Type	Description	Default
quote	BridgeQuote	BridgeQuote from get_quote()	required
recipient	str	Address to receive tokens on destination chain	required

Returns:

Type	Description
dict[str, Any]	Transaction data dict with 'to', 'value', 'data' fields

Raises:

Type	Description
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.

Parameters:

Name	Type	Description	Default
bridge_deposit_id	str	Source chain deposit transaction hash	required

Returns:

Type	Description
BridgeStatus	BridgeStatus with current transfer status

Raises:

Type	Description
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.

Parameters:

Name	Type	Description	Default
from_chain	str	Source chain identifier	required
to_chain	str	Destination chain identifier	required

Returns:

Type	Description
int	Estimated completion time in seconds

Raises:

Type	Description
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.

Attributes:

Name	Type	Description
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.

Parameters:

Name	Type	Description	Default
**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.