Bridges¶

Connector for cross-chain bridge protocols.

almanak.framework.connectors.bridges ¶

Bridge Connectors.

This package contains adapters for cross-chain bridge protocols, providing a unified interface for bridging assets between chains.

Available Bridges: - Across: Fast bridge using optimistic verification (Arbitrum, Optimism, Base, Polygon, Ethereum) - Stargate: LayerZero-based bridge for stablecoins and native assets

Example

from almanak.framework.connectors.bridges import BridgeAdapter, BridgeQuote, BridgeStatus

Get a quote for bridging¶

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

Build the deposit transaction¶

tx = adapter.build_deposit_tx(quote, recipient="0x...")

AcrossBridgeAdapter ¶

AcrossBridgeAdapter(
    config: AcrossConfig | None = None,
    token_resolver: TokenResolver | None = None,
)

Bases: BridgeAdapter

Across Protocol bridge adapter implementation.

Provides integration with the Across bridge for fast cross-chain transfers using relayers and optimistic verification.

Features: - Fast finality via relayer network - Competitive fees through relayer competition - Support for ETH, USDC, WBTC and other major tokens - Multi-chain support (Ethereum, Arbitrum, Optimism, Base, Polygon)

Example

adapter = AcrossBridgeAdapter()

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 Across bridge adapter.

Parameters:

Name	Type	Description	Default
`config`	`AcrossConfig \| 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 Across.

Calls the Across API to get current fee and time estimates for the specified transfer.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol (e.g., "USDC", "ETH", "WBTC")	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
`AcrossQuoteError`	If quote cannot be retrieved

build_deposit_tx ¶

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

Build the deposit transaction for an Across bridge transfer.

Creates the transaction data to call depositV3() on the SpokePool 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
`AcrossTransactionError`	If transaction cannot be built

check_status ¶

check_status(bridge_deposit_id: str) -> BridgeStatus

Check the status of an Across bridge transfer.

Polls the Across API to check if a deposit has been filled 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
`AcrossStatusError`	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 historical data and relayer network activity.

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
`AcrossError`	If route is not supported

AcrossConfig `dataclass` ¶

AcrossConfig(
    api_base_url: str = "https://app.across.to/api",
    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
    request_timeout: int = 30,
    max_retries: int = 3,
)

Configuration for Across bridge adapter.

Attributes:

Name	Type	Description
`api_base_url`	`str`	Across API base URL
`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.

AcrossError ¶

Bases: BridgeError

Base exception for Across-related errors.

AcrossQuoteError ¶

Bases: AcrossError, BridgeQuoteError

Error when retrieving an Across quote.

AcrossStatusError ¶

Bases: AcrossError, BridgeStatusError

Error when checking Across transfer status.

AcrossTransactionError ¶

Bases: AcrossError, BridgeTransactionError

Error when building or submitting an Across transaction.

BridgeAdapter ¶

Bases: ABC

Abstract base class for bridge protocol adapters.

All bridge adapters must implement this interface to provide a consistent API for cross-chain asset transfers.

Bridge adapters handle: 1. Quote retrieval - Get fee and time estimates for a transfer 2. Transaction building - Build the deposit transaction 3. Status tracking - Poll for transfer completion 4. Time estimation - Estimate completion times for routes

Example implementation

class AcrossBridgeAdapter(BridgeAdapter): @property def name(self) -> str: return "Across"

@property
def supported_tokens(self) -> list[str]:
    return ["ETH", "USDC", "WBTC"]

def get_quote(self, token, amount, from_chain, to_chain, max_slippage):
    # Call Across API for quote
    pass

def build_deposit_tx(self, quote, recipient):
    # Build deposit transaction
    pass

name `abstractmethod` `property` ¶

name: str

Get the bridge adapter name.

Returns:

Type	Description
`str`	Human-readable name of the bridge (e.g., "Across", "Stargate")

supported_tokens `abstractmethod` `property` ¶

supported_tokens: list[str]

Get list of supported tokens.

Returns:

Type	Description
`list[str]`	List of token symbols supported by this bridge
`list[str]`	(e.g., ["ETH", "USDC", "WBTC"])

supported_routes `abstractmethod` `property` ¶

supported_routes: list[BridgeRoute]

Get list of supported bridge routes.

Returns:

Type	Description
`list[BridgeRoute]`	List of BridgeRoute objects describing supported
`list[BridgeRoute]`	chain-to-chain routes with their tokens and limits

get_quote `abstractmethod` ¶

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.

Retrieves fee and timing information for a potential bridge transfer. The quote contains all information needed to execute the transfer.

Parameters:

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

Returns:

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

Raises:

Type	Description
`BridgeQuoteError`	If quote cannot be retrieved (unsupported route, amount out of range, API error, etc.)

build_deposit_tx `abstractmethod` ¶

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

Build the deposit transaction for a bridge transfer.

Creates the transaction data needed to initiate the bridge transfer on the source chain.

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: Contract address to call - value: ETH value to send (for native transfers) - data: Encoded calldata

Raises:

Type	Description
`BridgeTransactionError`	If transaction cannot be built (quote expired, invalid recipient, etc.)

check_status `abstractmethod` ¶

check_status(bridge_deposit_id: str) -> BridgeStatus

Check the status of a bridge transfer.

Polls the bridge for the current status of an in-flight transfer.

Parameters:

Name	Type	Description	Default
`bridge_deposit_id`	`str`	Bridge-specific deposit identifier (returned from deposit transaction or derived from source tx hash)	required

Returns:

Type	Description
`BridgeStatus`	BridgeStatus with current transfer status and transaction details

Raises:

Type	Description
`BridgeStatusError`	If status cannot be retrieved (unknown deposit ID, API error, etc.)

estimate_completion_time `abstractmethod` ¶

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

Estimate completion time for a route.

Returns the typical completion time in seconds for a bridge transfer between two chains.

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
`BridgeError`	If route is not supported

supports_token ¶

supports_token(token: str) -> bool

Check if bridge supports a token.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol to check	required

Returns:

Type	Description
`bool`	True if token is supported

supports_route ¶

supports_route(from_chain: str, to_chain: str) -> bool

Check if bridge supports a route.

Parameters:

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

Returns:

Type	Description
`bool`	True if route is supported

get_route ¶

get_route(
    from_chain: str, to_chain: str
) -> BridgeRoute | None

Get route information.

Parameters:

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

Returns:

Type	Description
`BridgeRoute \| None`	BridgeRoute if found, None otherwise

validate_transfer ¶

validate_transfer(
    token: str,
    amount: Decimal,
    from_chain: str,
    to_chain: str,
) -> tuple[bool, str | None]

Validate a transfer before getting a quote.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol	required
`amount`	`Decimal`	Amount to bridge	required
`from_chain`	`str`	Source chain	required
`to_chain`	`str`	Destination chain	required

Returns:

Type	Description
`tuple[bool, str \| None]`	Tuple of (is_valid, error_message)

BridgeError ¶

Bases: Exception

Base exception for bridge-related errors.

BridgeQuote `dataclass` ¶

BridgeQuote(
    bridge_name: str,
    token: str,
    input_amount: Decimal,
    output_amount: Decimal,
    from_chain: str,
    to_chain: str,
    fee_amount: Decimal,
    fee_usd: Decimal | None = None,
    gas_fee_amount: Decimal = Decimal("0"),
    relayer_fee_amount: Decimal = Decimal("0"),
    estimated_time_seconds: int = 300,
    quote_timestamp: datetime = (
        lambda: datetime.now(UTC)
    )(),
    expires_at: datetime | None = None,
    slippage_tolerance: Decimal = Decimal("0.005"),
    route_data: dict[str, Any] = dict(),
    quote_id: str | None = None,
)

Quote for a bridge transfer.

Contains all information needed to execute a bridge transfer, including fees, timing, and the resulting amount on destination.

Attributes:

Name	Type	Description
`bridge_name`	`str`	Name of the bridge providing this quote
`token`	`str`	Token being bridged
`input_amount`	`Decimal`	Amount being sent from source chain
`output_amount`	`Decimal`	Expected amount on destination (after fees)
`from_chain`	`str`	Source chain identifier
`to_chain`	`str`	Destination chain identifier
`fee_amount`	`Decimal`	Total fee in token units
`fee_usd`	`Decimal \| None`	Total fee in USD (if available)
`gas_fee_amount`	`Decimal`	Gas fee portion (in native token)
`relayer_fee_amount`	`Decimal`	Relayer/protocol fee portion (in bridged token)
`estimated_time_seconds`	`int`	Estimated completion time in seconds
`quote_timestamp`	`datetime`	When quote was generated
`expires_at`	`datetime \| None`	When quote expires
`slippage_tolerance`	`Decimal`	Maximum slippage as decimal (e.g., 0.005 = 0.5%)
`route_data`	`dict[str, Any]`	Bridge-specific route information
`quote_id`	`str \| None`	Bridge-specific quote identifier (if any)

fee_percentage `property` ¶

fee_percentage: Decimal

Get fee as percentage of input amount.

is_expired `property` ¶

is_expired: bool

Check if quote has expired.

time_until_expiry `property` ¶

time_until_expiry: timedelta | None

Get time until quote expires.

estimated_completion_time `property` ¶

estimated_completion_time: datetime

Get estimated completion timestamp.

__post_init__ ¶

__post_init__() -> None

Set default expiration if not provided.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

BridgeQuoteError ¶

Bases: BridgeError

Error when retrieving a bridge quote.

BridgeRoute `dataclass` ¶

BridgeRoute(
    from_chain: str,
    to_chain: str,
    tokens: list[str] = list(),
    min_amount: Decimal = Decimal("0"),
    max_amount: Decimal = Decimal("0"),
    estimated_time_seconds: int = 300,
    is_active: bool = True,
)

Represents a bridge route between two chains.

Attributes:

Name	Type	Description
`from_chain`	`str`	Source chain identifier
`to_chain`	`str`	Destination chain identifier
`tokens`	`list[str]`	List of tokens supported on this route
`min_amount`	`Decimal`	Minimum transfer amount (in token units)
`max_amount`	`Decimal`	Maximum transfer amount (in token units)
`estimated_time_seconds`	`int`	Typical completion time
`is_active`	`bool`	Whether route is currently active

supports_token ¶

supports_token(token: str) -> bool

Check if route supports a specific token.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol to check	required

Returns:

Type	Description
`bool`	True if token is supported on this route

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

BridgeStatus `dataclass` ¶

BridgeStatus(
    bridge_name: str,
    bridge_deposit_id: str,
    status: BridgeStatusEnum,
    from_chain: str,
    to_chain: str,
    token: str,
    input_amount: Decimal,
    output_amount: Decimal | None = None,
    source_tx_hash: str | None = None,
    destination_tx_hash: str | None = None,
    deposited_at: datetime | None = None,
    filled_at: datetime | None = None,
    completed_at: datetime | None = None,
    error_message: str | None = None,
    relay_id: str | None = None,
    fill_deadline: datetime | None = None,
)

Status of a bridge transfer.

Tracks the progress of an in-flight bridge transfer including source and destination chain transaction details.

Attributes:

Name	Type	Description
`bridge_name`	`str`	Name of the bridge
`bridge_deposit_id`	`str`	Bridge-specific deposit identifier
`status`	`BridgeStatusEnum`	Current status of the transfer
`from_chain`	`str`	Source chain identifier
`to_chain`	`str`	Destination chain identifier
`token`	`str`	Token being bridged
`input_amount`	`Decimal`	Amount sent from source chain
`output_amount`	`Decimal \| None`	Amount received on destination (if known)
`source_tx_hash`	`str \| None`	Transaction hash on source chain
`destination_tx_hash`	`str \| None`	Transaction hash on destination chain (if complete)
`deposited_at`	`datetime \| None`	When deposit was confirmed on source
`filled_at`	`datetime \| None`	When fill was detected on destination
`completed_at`	`datetime \| None`	When transfer was fully completed
`error_message`	`str \| None`	Error details if failed
`relay_id`	`str \| None`	Relayer-specific identifier (if applicable)
`fill_deadline`	`datetime \| None`	Deadline for fill (for optimistic bridges)

is_complete `property` ¶

is_complete: bool

Check if transfer is complete (success or failure).

is_success `property` ¶

is_success: bool

Check if transfer completed successfully.

is_pending `property` ¶

is_pending: bool

Check if transfer is still in progress.

elapsed_time `property` ¶

elapsed_time: timedelta | None

Get elapsed time since deposit.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

BridgeStatusEnum ¶

Bases: Enum

Status of a bridge transfer.

States

PENDING: Transfer initiated but not yet detected on source chain DEPOSITED: Deposit confirmed on source chain IN_FLIGHT: Transfer in progress (relaying/bridging) FILLED: Destination chain credit detected, awaiting confirmations COMPLETED: Transfer fully completed and confirmed FAILED: Transfer failed (may need manual intervention) EXPIRED: Quote expired before execution REFUNDED: Transfer refunded on source chain

BridgeStatusError ¶

Bases: BridgeError

Error when checking bridge transfer status.

BridgeTransactionError ¶

Bases: BridgeError

Error when building or submitting a bridge transaction.

BridgeScore `dataclass` ¶

BridgeScore(
    bridge: BridgeAdapter,
    quote: BridgeQuote | None = None,
    cost_score: float = 1.0,
    speed_score: float = 1.0,
    liquidity_score: float = 1.0,
    reliability_score: float = 1.0,
    overall_score: float = 1.0,
    is_available: bool = False,
    unavailable_reason: str | None = None,
)

Score for a bridge based on selection criteria.

Attributes:

Name	Type	Description
`bridge`	`BridgeAdapter`	The bridge adapter being scored
`quote`	`BridgeQuote \| None`	The quote from this bridge (if available)
`cost_score`	`float`	Normalized cost score (0-1, lower is better)
`speed_score`	`float`	Normalized speed score (0-1, lower is better)
`liquidity_score`	`float`	Normalized liquidity score (0-1, lower is better)
`reliability_score`	`float`	Normalized reliability score (0-1, lower is better)
`overall_score`	`float`	Weighted overall score
`is_available`	`bool`	Whether bridge can fulfill request
`unavailable_reason`	`str \| None`	Reason if bridge unavailable

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

BridgeSelectionResult `dataclass` ¶

BridgeSelectionResult(
    bridge: BridgeAdapter | None = None,
    quote: BridgeQuote | None = None,
    scores: list[BridgeScore] = list(),
    selection_reasoning: str = "",
)

Result of bridge selection.

Attributes:

Name	Type	Description
`bridge`	`BridgeAdapter \| None`	Selected bridge adapter (or None if no bridge available)
`quote`	`BridgeQuote \| None`	Quote from selected bridge
`scores`	`list[BridgeScore]`	Scores for all evaluated bridges
`selection_reasoning`	`str`	Human-readable explanation of selection

is_success `property` ¶

is_success: bool

Check if a bridge was successfully selected.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

BridgeSelector ¶

BridgeSelector(
    bridges: list[BridgeAdapter],
    reliability_scores: dict[str, float] | None = None,
    default_priority: SelectionPriority = SelectionPriority.COST,
)

Selects optimal bridge for cross-chain transfers.

The selector evaluates all registered bridge adapters and selects the best one based on configurable priority criteria.

Attributes:

Name	Type	Description
`bridges`		List of registered bridge adapters
`reliability_scores`		Historical reliability scores per bridge
`default_priority`		Default selection priority

Example

selector = BridgeSelector([ AcrossBridgeAdapter(), StargateBridgeAdapter(), ])

result = selector.select_bridge( token="USDC", amount=Decimal("1000"), from_chain="arbitrum", to_chain="optimism", priority="cost", )

Initialize the bridge selector.

Parameters:

Name	Type	Description	Default
`bridges`	`list[BridgeAdapter]`	List of bridge adapters to evaluate	required
`reliability_scores`	`dict[str, float] \| None`	Optional custom reliability scores per bridge name	`None`
`default_priority`	`SelectionPriority`	Default selection priority	`COST`

select_bridge ¶

select_bridge(
    token: str,
    amount: Decimal,
    from_chain: str,
    to_chain: str,
    priority: str = "cost",
    max_slippage: Decimal = Decimal("0.005"),
) -> BridgeSelectionResult

Select the optimal bridge for a transfer.

Evaluates all registered bridges for the given route and returns the best one based on the priority criteria.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol to bridge (e.g., "ETH", "USDC")	required
`amount`	`Decimal`	Amount to bridge in token units	required
`from_chain`	`str`	Source chain identifier	required
`to_chain`	`str`	Destination chain identifier	required
`priority`	`str`	Selection priority ("cost", "speed", "liquidity", "reliability")	`'cost'`
`max_slippage`	`Decimal`	Maximum slippage tolerance	`Decimal('0.005')`

Returns:

Type	Description
`BridgeSelectionResult`	BridgeSelectionResult with selected bridge and quote

Raises:

Type	Description
`NoBridgeAvailableError`	If no bridge can fulfill the request

get_available_bridges ¶

get_available_bridges(
    token: str, from_chain: str, to_chain: str
) -> list[BridgeAdapter]

Get list of bridges that support a route.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol	required
`from_chain`	`str`	Source chain	required
`to_chain`	`str`	Destination chain	required

Returns:

Type	Description
`list[BridgeAdapter]`	List of bridge adapters that support the route

select_bridge_with_fallback ¶

select_bridge_with_fallback(
    token: str,
    amount: Decimal,
    from_chain: str,
    to_chain: str,
    priority: str = "cost",
    max_slippage: Decimal = Decimal("0.005"),
    excluded_bridges: list[str] | None = None,
) -> BridgeSelectionResult

Select bridge with automatic fallback if primary fails.

If the primary selection fails for any reason, attempts to use the next best bridge as a fallback.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol to bridge	required
`amount`	`Decimal`	Amount to bridge	required
`from_chain`	`str`	Source chain	required
`to_chain`	`str`	Destination chain	required
`priority`	`str`	Selection priority	`'cost'`
`max_slippage`	`Decimal`	Maximum slippage tolerance	`Decimal('0.005')`
`excluded_bridges`	`list[str] \| None`	List of bridge names to exclude from selection	`None`

Returns:

Type	Description
`BridgeSelectionResult`	BridgeSelectionResult with selected bridge

Raises:

Type	Description
`NoBridgeAvailableError`	If no bridge (including fallbacks) available

BridgeSelectorError ¶

Bases: BridgeError

Base exception for bridge selector errors.

NoBridgeAvailableError ¶

Bases: BridgeSelectorError

Raised when no bridge can fulfill the request.

SelectionPriority ¶

Bases: Enum

Priority for bridge selection.

Attributes:

Name	Type	Description
`COST`		Minimize total fees
`SPEED`		Minimize completion time
`LIQUIDITY`		Prefer deeper liquidity
`RELIABILITY`		Prefer more reliable bridges

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.

Bridges¶

almanak.framework.connectors.bridges ¶

Get a quote for bridging¶

Build the deposit transaction¶

AcrossBridgeAdapter ¶

Get quote¶

Build transaction¶

Check status after deposit¶

name property ¶

supported_tokens property ¶

supported_routes property ¶

get_quote ¶

build_deposit_tx ¶

check_status ¶

estimate_completion_time ¶

AcrossConfig dataclass ¶

__post_init__ ¶

AcrossError ¶

AcrossQuoteError ¶

AcrossStatusError ¶

AcrossTransactionError ¶

BridgeAdapter ¶

name abstractmethod property ¶

supported_tokens abstractmethod property ¶

supported_routes abstractmethod property ¶

get_quote abstractmethod ¶

build_deposit_tx abstractmethod ¶

check_status abstractmethod ¶

estimate_completion_time abstractmethod ¶

supports_token ¶

supports_route ¶

get_route ¶

validate_transfer ¶

BridgeError ¶

BridgeQuote dataclass ¶

fee_percentage property ¶

is_expired property ¶

time_until_expiry property ¶

estimated_completion_time property ¶

__post_init__ ¶

to_dict ¶

BridgeQuoteError ¶

BridgeRoute dataclass ¶

supports_token ¶

to_dict ¶

BridgeStatus dataclass ¶

is_complete property ¶

is_success property ¶

is_pending property ¶

elapsed_time property ¶

to_dict ¶

BridgeStatusEnum ¶

BridgeStatusError ¶

BridgeTransactionError ¶

BridgeScore dataclass ¶

to_dict ¶

BridgeSelectionResult dataclass ¶

is_success property ¶

to_dict ¶

BridgeSelector ¶

select_bridge ¶

get_available_bridges ¶

select_bridge_with_fallback ¶

BridgeSelectorError ¶

NoBridgeAvailableError ¶

SelectionPriority ¶

StargateBridgeAdapter ¶

Get quote¶

Build transaction¶

Check status after deposit¶

name property ¶

supported_tokens property ¶

supported_routes property ¶

get_quote ¶

build_deposit_tx ¶

check_status ¶

estimate_completion_time ¶

StargateConfig dataclass ¶

__post_init__ ¶

StargateError ¶

name `property` ¶

supported_tokens `property` ¶

supported_routes `property` ¶

AcrossConfig `dataclass` ¶

name `abstractmethod` `property` ¶

supported_tokens `abstractmethod` `property` ¶

supported_routes `abstractmethod` `property` ¶

get_quote `abstractmethod` ¶

build_deposit_tx `abstractmethod` ¶

check_status `abstractmethod` ¶

estimate_completion_time `abstractmethod` ¶

BridgeQuote `dataclass` ¶

fee_percentage `property` ¶

is_expired `property` ¶

time_until_expiry `property` ¶

estimated_completion_time `property` ¶

BridgeRoute `dataclass` ¶

BridgeStatus `dataclass` ¶

is_complete `property` ¶

is_success `property` ¶

is_pending `property` ¶

elapsed_time `property` ¶

BridgeScore `dataclass` ¶

BridgeSelectionResult `dataclass` ¶

is_success `property` ¶

name `property` ¶

supported_tokens `property` ¶

supported_routes `property` ¶

StargateConfig `dataclass` ¶