Intent Compiler¶

The compiler transforms high-level intents into executable transaction bundles.

IntentCompiler¶

almanak.framework.intents.compiler.IntentCompiler ¶

IntentCompiler(
    chain: str = "arbitrum",
    wallet_address: str = "0x0000000000000000000000000000000000000000",
    default_protocol: str = "uniswap_v3",
    price_oracle: dict[str, Decimal] | None = None,
    default_deadline_seconds: int = 300,
    rpc_url: str | None = None,
    rpc_timeout: float = 10.0,
    default_lp_slippage: Decimal = Decimal("0.99"),
    config: IntentCompilerConfig | None = None,
    gateway_client: GatewayClient | None = None,
    token_resolver: TokenResolver | None = None,
)

Compiles Intents into executable ActionBundles.

The IntentCompiler takes high-level trading intents and converts them into low-level transaction data ready for execution on-chain.

Example

compiler = IntentCompiler( chain="arbitrum", wallet_address="0x...", rpc_url="https://arb1.arbitrum.io/rpc", ) intent = Intent.swap("USDC", "ETH", amount_usd=Decimal("1000")) result = compiler.compile(intent) if result.status == CompilationStatus.SUCCESS: # Execute result.action_bundle pass

Initialize the compiler.

Parameters:

Name	Type	Description	Default
`chain`	`str`	Target blockchain (ethereum, arbitrum, etc.)	`'arbitrum'`
`wallet_address`	`str`	Address that will execute transactions	`'0x0000000000000000000000000000000000000000'`
`default_protocol`	`str`	Default DEX protocol for swaps	`'uniswap_v3'`
`price_oracle`	`dict[str, Decimal] \| None`	Price oracle dict (token -> USD price). Required for production use to calculate accurate slippage amounts.	`None`
`default_deadline_seconds`	`int`	Default transaction deadline	`300`
`rpc_url`	`str \| None`	RPC URL for on-chain queries (needed for LP close). DEPRECATED: Use gateway_client instead for production deployments.	`None`
`rpc_timeout`	`float`	HTTP timeout for direct RPC calls in seconds.	`10.0`
`default_lp_slippage`	`Decimal`	Default slippage for LP operations (0.99 = 99%). This controls the minimum acceptable amounts when adding/removing liquidity. LP operations differ from swaps - for concentrated liquidity, the actual deposit ratio depends heavily on where the current price is relative to your tick range. A price near the range edge means most liquidity is in one token. Default 99% allows nearly full flexibility for this behavior. Can be lowered for tighter protection if needed.	`Decimal('0.99')`
`config`	`IntentCompilerConfig \| None`	Optional configuration. If not provided, defaults to IntentCompilerConfig() which requires price_oracle.	`None`
`gateway_client`	`GatewayClient \| None`	Optional gateway client for RPC queries. When provided, all on-chain queries (allowance, balance, position liquidity) go through the gateway instead of direct RPC. This is the preferred mode for production deployments where strategies run in isolated containers.	`None`
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance for token resolution. If not provided, uses the singleton instance from get_token_resolver(). The resolver provides unified token lookup with caching and on-chain discovery support.	`None`

Raises:

Type	Description
`ValueError`	If no price_oracle is provided and allow_placeholder_prices is False.

polymarket_adapter `property` ¶

polymarket_adapter: PolymarketAdapter | None

Get the Polymarket adapter for prediction market intents.

Returns:

Type	Description
`PolymarketAdapter \| None`	PolymarketAdapter if initialized, None otherwise.

compile ¶

compile(intent: AnyIntent) -> CompilationResult

Compile an intent into an ActionBundle.

This is the main entry point for compiling intents. It dispatches to the appropriate handler based on intent type.

Parameters:

Name	Type	Description	Default
`intent`	`AnyIntent`	The intent to compile	required

Returns:

Type	Description
`CompilationResult`	CompilationResult with ActionBundle and metadata

set_allowance ¶

set_allowance(
    token_address: str, spender: str, amount: int
) -> None

Set cached allowance (for testing or after on-chain approval).

Parameters:

Name	Type	Description	Default
`token_address`	`str`	Token contract address	required
`spender`	`str`	Spender address	required
`amount`	`int`	Allowance amount	required

clear_allowance_cache ¶

clear_allowance_cache() -> None

Clear the allowance cache.

IntentCompilerConfig¶

almanak.framework.intents.compiler.IntentCompilerConfig `dataclass` ¶

IntentCompilerConfig(
    allow_placeholder_prices: bool = False,
    polymarket_config: PolymarketConfig | None = None,
    swap_pool_selection_mode: Literal[
        "auto", "fixed"
    ] = "auto",
    fixed_swap_fee_tier: int | None = None,
)

Configuration for IntentCompiler.

Attributes:

Name	Type	Description
`allow_placeholder_prices`	`bool`	If False (default), raises ValueError when no price_oracle is given. Set to True ONLY for unit tests. NEVER set to True in production - placeholder prices will cause incorrect slippage calculations and swap reverts.
`polymarket_config`	`PolymarketConfig \| None`	Optional PolymarketConfig for prediction market intents. Required when compiling PredictionBuyIntent, PredictionSellIntent, or PredictionRedeemIntent on Polygon. If not provided when on Polygon, a warning is logged and prediction intents will fail to compile.
`swap_pool_selection_mode`	`Literal['auto', 'fixed']`	Pool selection mode for V3-style swaps. - "auto" (default): Try all supported fee tiers and pick best quote when RPC is available. - "fixed": Use fixed_swap_fee_tier for deterministic execution.
`fixed_swap_fee_tier`	`int \| None`	Optional fixed fee tier used when swap_pool_selection_mode="fixed". Must be valid for the selected protocol.

__post_init__ ¶

__post_init__() -> None

Validate swap pool selection settings.

CompilationResult¶

almanak.framework.intents.compiler.CompilationResult `dataclass` ¶

CompilationResult(
    status: CompilationStatus,
    action_bundle: ActionBundle | None = None,
    transactions: list[TransactionData] = list(),
    total_gas_estimate: int = 0,
    error: str | None = None,
    warnings: list[str] = list(),
    intent_id: str = "",
    compiled_at: datetime = (lambda: datetime.now(UTC))(),
)

Result of compiling an intent to an ActionBundle.

Attributes:

Name	Type	Description
`status`	`CompilationStatus`	Compilation status
`action_bundle`	`ActionBundle \| None`	The compiled ActionBundle (if successful)
`transactions`	`list[TransactionData]`	List of transaction data
`total_gas_estimate`	`int`	Sum of all gas estimates
`error`	`str \| None`	Error message (if failed)
`warnings`	`list[str]`	List of warnings encountered during compilation
`intent_id`	`str`	ID of the intent that was compiled
`compiled_at`	`datetime`	Timestamp of compilation

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary for serialization.

CompilationStatus¶

almanak.framework.intents.compiler.CompilationStatus ¶

Bases: Enum

Status of intent compilation.

TransactionData¶

almanak.framework.intents.compiler.TransactionData `dataclass` ¶

TransactionData(
    to: str,
    value: int,
    data: str,
    gas_estimate: int,
    description: str,
    tx_type: str,
)

Represents a single transaction in an ActionBundle.

Attributes:

Name	Type	Description
`to`	`str`	Target contract address
`value`	`int`	ETH value to send (in wei)
`data`	`str`	Encoded calldata
`gas_estimate`	`int`	Estimated gas for this transaction
`description`	`str`	Human-readable description of what this TX does
`tx_type`	`str`	Type of transaction (approve, swap, etc.)

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary for serialization.

TokenInfo¶

almanak.framework.intents.compiler.TokenInfo `dataclass` ¶

TokenInfo(
    symbol: str,
    address: str,
    decimals: int = 18,
    is_native: bool = False,
)

Information about a token.

Attributes:

Name	Type	Description
`symbol`	`str`	Token symbol (e.g., "USDC")
`address`	`str`	Token contract address
`decimals`	`int`	Token decimals
`is_native`	`bool`	Whether this is the native token (ETH, MATIC, etc.)

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

PriceInfo¶

almanak.framework.intents.compiler.PriceInfo `dataclass` ¶

PriceInfo(
    token: str,
    price_usd: Decimal,
    timestamp: datetime = (lambda: datetime.now(UTC))(),
)

Price information for amount calculations.

Attributes:

Name	Type	Description
`token`	`str`	Token symbol
`price_usd`	`Decimal`	Price in USD
`timestamp`	`datetime`	When this price was fetched

Intent Compiler¶

IntentCompiler¶

almanak.framework.intents.compiler.IntentCompiler ¶

polymarket_adapter property ¶

compile ¶

set_allowance ¶

clear_allowance_cache ¶

IntentCompilerConfig¶

almanak.framework.intents.compiler.IntentCompilerConfig dataclass ¶

__post_init__ ¶

CompilationResult¶

almanak.framework.intents.compiler.CompilationResult dataclass ¶

to_dict ¶

CompilationStatus¶

almanak.framework.intents.compiler.CompilationStatus ¶

TransactionData¶

almanak.framework.intents.compiler.TransactionData dataclass ¶

to_dict ¶

TokenInfo¶

almanak.framework.intents.compiler.TokenInfo dataclass ¶

to_dict ¶

PriceInfo¶

almanak.framework.intents.compiler.PriceInfo dataclass ¶

polymarket_adapter `property` ¶

almanak.framework.intents.compiler.IntentCompilerConfig `dataclass` ¶

almanak.framework.intents.compiler.CompilationResult `dataclass` ¶

almanak.framework.intents.compiler.TransactionData `dataclass` ¶

almanak.framework.intents.compiler.TokenInfo `dataclass` ¶

almanak.framework.intents.compiler.PriceInfo `dataclass` ¶