Stargate

Field	Value
Module	almanak.connectors.stargate
Protocol kind	Bridge
Aliases	N/A

Supported Chains And Intents

Chain	Family	Supported Intents
Arbitrum	EVM	BRIDGE
Avalanche	EVM	BRIDGE
Base	EVM	BRIDGE
BNB Chain	EVM	BRIDGE
Ethereum	EVM	BRIDGE
Optimism	EVM	BRIDGE
Polygon	EVM	BRIDGE

API Reference

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

__getattr__

__getattr__(name: str) -> Any

PEP 562 lazy attribute access.