Spark¶

Field	Value
Module	`almanak.connectors.spark`
Protocol kind	Lending
Aliases	N/A

Supported Chains And Intents¶

Chain	Family	Supported Intents
Ethereum	EVM	`BORROW`, `REPAY`, `SUPPLY`, `WITHDRAW`

API Reference¶

almanak.connectors.spark ¶

Spark Connector.

This module provides an adapter for interacting with Spark lending protocol, which is an Aave V3 fork with Spark-specific addresses and configurations.

Spark is a decentralized lending protocol supporting: - Supply assets to earn yield - Borrow against collateral - Variable interest rates

Supported chains: - Ethereum

Example

from almanak.connectors.spark import SparkAdapter, SparkConfig

config = SparkConfig( chain="ethereum", wallet_address="0x...", ) adapter = SparkAdapter(config)

Supply collateral¶

result = adapter.supply( asset="USDC", amount=Decimal("1000"), )

Borrow against collateral¶

result = adapter.borrow( asset="DAI", amount=Decimal("500"), )

Parse transaction receipt¶

from almanak.connectors.spark import SparkReceiptParser

parser = SparkReceiptParser() result = parser.parse_receipt(receipt)

SparkAdapter ¶

SparkAdapter(
    config: SparkConfig,
    token_resolver: TokenResolver | None = None,
)

Adapter for Spark lending protocol.

This adapter provides methods for interacting with Spark: - Supply/withdraw collateral - Borrow/repay assets

Spark is an Aave V3 fork with the same ABI but different contract addresses.

Example

config = SparkConfig( chain="ethereum", wallet_address="0x...", ) adapter = SparkAdapter(config)

Supply DAI as collateral¶

result = adapter.supply("DAI", Decimal("1000"))

Borrow WETH¶

result = adapter.borrow("WETH", Decimal("0.5"))

Initialize the adapter.

Parameters:

Name	Type	Description	Default
`config`	`SparkConfig`	Adapter configuration	required
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance. If None, uses singleton.	`None`

supply ¶

supply(
    asset: str,
    amount: Decimal,
    on_behalf_of: str | None = None,
) -> TransactionResult

Build a supply transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol to supply	required
`amount`	`Decimal`	Amount to supply	required
`on_behalf_of`	`str \| None`	Address to supply on behalf of (default: wallet_address)	`None`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

borrow ¶

borrow(
    asset: str,
    amount: Decimal,
    interest_rate_mode: int = SPARK_VARIABLE_RATE_MODE,
    on_behalf_of: str | None = None,
) -> TransactionResult

Build a borrow transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol to borrow	required
`amount`	`Decimal`	Amount to borrow	required
`interest_rate_mode`	`int`	Interest rate mode (2 = variable)	`SPARK_VARIABLE_RATE_MODE`
`on_behalf_of`	`str \| None`	Address to borrow on behalf of (default: wallet_address)	`None`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

repay ¶

repay(
    asset: str,
    amount: Decimal,
    interest_rate_mode: int = SPARK_VARIABLE_RATE_MODE,
    on_behalf_of: str | None = None,
    repay_all: bool = False,
) -> TransactionResult

Build a repay transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol to repay	required
`amount`	`Decimal`	Amount to repay	required
`interest_rate_mode`	`int`	Interest rate mode (2 = variable)	`SPARK_VARIABLE_RATE_MODE`
`on_behalf_of`	`str \| None`	Address to repay on behalf of (default: wallet_address)	`None`
`repay_all`	`bool`	If True, use MAX_UINT256 to repay full debt	`False`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

withdraw ¶

withdraw(
    asset: str,
    amount: Decimal,
    to: str | None = None,
    withdraw_all: bool = False,
) -> TransactionResult

Build a withdraw transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol to withdraw	required
`amount`	`Decimal`	Amount to withdraw	required
`to`	`str \| None`	Address to send withdrawn assets (default: wallet_address)	`None`
`withdraw_all`	`bool`	If True, use MAX_UINT256 to withdraw all	`False`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

SparkConfig `dataclass` ¶

SparkConfig(
    chain: str,
    wallet_address: str,
    default_slippage_bps: int = 50,
)

Configuration for Spark adapter.

Attributes:

Name	Type	Description
`chain`	`str`	Blockchain network (ethereum)
`wallet_address`	`str`	User wallet address
`default_slippage_bps`	`int`	Default slippage tolerance in basis points

__post_init__ ¶

__post_init__() -> None

Validate configuration.

TransactionResult `dataclass` ¶

TransactionResult(
    success: bool,
    tx_data: dict[str, Any] | None = None,
    gas_estimate: int = 0,
    description: str = "",
    error: str | None = None,
)

Result of a transaction build operation.

Attributes:

Name	Type	Description
`success`	`bool`	Whether operation succeeded
`tx_data`	`dict[str, Any] \| None`	Transaction data (to, value, data)
`gas_estimate`	`int`	Estimated gas
`description`	`str`	Human-readable description
`error`	`str \| None`	Error message if failed

BorrowEventData `dataclass` ¶

BorrowEventData(
    reserve: str,
    user: str,
    on_behalf_of: str,
    amount: Decimal,
    interest_rate_mode: int,
    borrow_rate: Decimal = Decimal("0"),
    referral_code: int = 0,
)

Parsed data from Borrow event.

is_variable_rate `property` ¶

is_variable_rate: bool

Check if borrow is variable rate.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

ParseResult `dataclass` ¶

ParseResult(
    success: bool,
    supplies: list[SupplyEventData] = list(),
    withdraws: list[WithdrawEventData] = list(),
    borrows: list[BorrowEventData] = list(),
    repays: list[RepayEventData] = list(),
    error: str | None = None,
    transaction_hash: str = "",
    block_number: int = 0,
)

Result of parsing a receipt.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

RepayEventData `dataclass` ¶

RepayEventData(
    reserve: str,
    user: str,
    repayer: str,
    amount: Decimal,
    use_atokens: bool = False,
)

Parsed data from Repay event.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

SparkEventType ¶

Bases: Enum

Spark event types.

SparkReceiptParser ¶

SparkReceiptParser(
    pool_addresses: set[str] | None = None,
    chain: str | None = None,
    **kwargs: Any,
)

Parser for Spark transaction receipts.

Refactored to use base infrastructure utilities for hex decoding and event registry management. Maintains pool address filtering to avoid false positives with Aave V3 events.

Initialize the parser.

Parameters:

Name	Type	Description	Default
`pool_addresses`	`set[str] \| None`	Optional set of known Spark pool addresses to filter by. If not provided, uses the default SPARK_POOL_ADDRESSES. Addresses should be lowercase.	`None`
`chain`	`str \| None`	Blockchain network (threaded by the ResultEnricher) — used to resolve the `reserve` address to its ERC-20 symbol/decimals for the declared money legs (VIB-5218).	`None`
`**kwargs`	`Any`	Additional arguments (ignored for compatibility)	`{}`

parse_receipt ¶

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

Parse a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict	required

Returns:

Type	Description
`ParseResult`	ParseResult with extracted events

parse_supply ¶

parse_supply(log: dict[str, Any]) -> SupplyEventData | None

Parse a Supply event from a single log entry.

parse_borrow ¶

parse_borrow(log: dict[str, Any]) -> BorrowEventData | None

Parse a Borrow event from a single log entry.

parse_repay ¶

parse_repay(log: dict[str, Any]) -> RepayEventData | None

Parse a Repay event from a single log entry.

parse_withdraw ¶

parse_withdraw(
    log: dict[str, Any],
) -> WithdrawEventData | None

Parse a Withdraw event from a single log entry.

is_spark_event ¶

is_spark_event(topic: str | bytes) -> bool

Check if a topic is a known Spark event.

Parameters:

Name	Type	Description	Default
`topic`	`str \| bytes`	Event topic (supports bytes, hex string with/without 0x, any case)	required

Returns:

Type	Description
`bool`	True if topic is a known Spark event

get_event_type ¶

get_event_type(topic: str | bytes) -> SparkEventType

Get the event type for a topic.

Parameters:

Name	Type	Description	Default
`topic`	`str \| bytes`	Event topic (supports bytes, hex string with/without 0x, any case)	required

Returns:

Type	Description
`SparkEventType`	Event type or UNKNOWN

is_spark_pool ¶

is_spark_pool(address: str) -> bool

Check if an address is a known Spark pool.

extract_supply_amount ¶

extract_supply_amount(
    receipt: dict[str, Any],
) -> int | None

Extract supply amount from transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Supply amount in token units if found, None otherwise

extract_withdraw_amount ¶

extract_withdraw_amount(
    receipt: dict[str, Any],
) -> int | None

Extract withdraw amount from transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Withdraw amount in token units if found, None otherwise

extract_borrow_amount ¶

extract_borrow_amount(
    receipt: dict[str, Any],
) -> int | None

Extract borrow amount from transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Borrow amount in token units if found, None otherwise

extract_repay_amount ¶

extract_repay_amount(receipt: dict[str, Any]) -> int | None

Extract repay amount from transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Repay amount in token units if found, None otherwise

extract_a_token_received ¶

extract_a_token_received(
    receipt: dict[str, Any],
) -> int | None

Extract spToken amount received from transaction receipt.

Spark uses spTokens (similar to Aave's aTokens) to represent deposits. This extracts the amount from Transfer events (mint from zero address).

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	spToken amount minted if found, None otherwise

extract_borrow_rate ¶

extract_borrow_rate(
    receipt: dict[str, Any],
) -> Decimal | None

Extract borrow rate from transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`Decimal \| None`	Borrow rate as Decimal (already converted from ray) if found, None otherwise

extract_primitive_money_legs ¶

extract_primitive_money_legs(
    receipt: dict[str, Any],
) -> PrimitiveMoneyLegs | None

VIB-5218 — declare the lending money legs as a typed PrimitiveMoneyLegs the ledger dispatcher consumes directly (the Lido / Curve / Pendle pattern).

Inverts the legacy control flow (blueprint 27 §6.6): instead of the ledger reverse-engineering a SUPPLY / WITHDRAW / BORROW / REPAY's token_in from the intent's loosely-typed attributes (which it never matched for lending, landing an empty token_in → asset = "UNKNOWN" → no FIFO lot → deployed_capital_usd = 0), the connector DECLARES the principal asset it actually moved on-chain. Spark is an Aave V3 fork: every Supply / Withdraw / Borrow / Repay event carries the reserve token address directly, so the principal token is self-describing from chain truth.

Emits ONE PRINCIPAL leg (the dispatcher projects it onto token_in / amount_in). Token identity is the reserve's resolved ERC-20 symbol so the lending handler's symbol-keyed price oracle can value the principal into deployed_capital_usd; the amount is a human-unit MeasuredMoney carrying Empty ≠ Zero (§10.10) via :func:lending_principal_legs.

Returns None (→ legacy fallback, byte-identical rows) when the receipt carries no Spark lending event or the reserve symbol cannot be resolved — so non-Spark-resolvable receipts degrade unchanged. Never raises: any failure degrades to None rather than halting the live accounting writer.

SupplyEventData `dataclass` ¶

SupplyEventData(
    reserve: str,
    user: str,
    on_behalf_of: str,
    amount: Decimal,
    referral_code: int = 0,
)

Parsed data from Supply event.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

WithdrawEventData `dataclass` ¶

WithdrawEventData(
    reserve: str, user: str, to: str, amount: Decimal
)

Parsed data from Withdraw event.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

getattr ¶

__getattr__(name: str) -> Any

PEP 562 lazy attribute access.

Spark¶

Supported Chains And Intents¶

API Reference¶

almanak.connectors.spark ¶

Supply collateral¶

Borrow against collateral¶

Parse transaction receipt¶

SparkAdapter ¶

Supply DAI as collateral¶

Borrow WETH¶

supply ¶

borrow ¶

repay ¶

withdraw ¶

SparkConfig dataclass ¶

__post_init__ ¶

TransactionResult dataclass ¶

BorrowEventData dataclass ¶

is_variable_rate property ¶

to_dict ¶

ParseResult dataclass ¶

to_dict ¶

RepayEventData dataclass ¶

to_dict ¶

SparkEventType ¶

SparkReceiptParser ¶

parse_receipt ¶

parse_supply ¶

parse_borrow ¶

parse_repay ¶

parse_withdraw ¶

is_spark_event ¶

get_event_type ¶

is_spark_pool ¶

extract_supply_amount ¶

extract_withdraw_amount ¶

extract_borrow_amount ¶

extract_repay_amount ¶

extract_a_token_received ¶

extract_borrow_rate ¶

extract_primitive_money_legs ¶

SupplyEventData dataclass ¶

to_dict ¶

WithdrawEventData dataclass ¶

to_dict ¶

__getattr__ ¶

SparkConfig `dataclass` ¶

TransactionResult `dataclass` ¶

BorrowEventData `dataclass` ¶

is_variable_rate `property` ¶

ParseResult `dataclass` ¶

RepayEventData `dataclass` ¶

SupplyEventData `dataclass` ¶

WithdrawEventData `dataclass` ¶

getattr ¶