Spark

Connector for Spark lending protocol.

almanak.framework.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.framework.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.framework.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, **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
**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

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.