chainlink.bundle_aggregator

Documentation for eth_defi.chainlink.bundle_aggregator Python module.

Read Chainlink Data Feeds bundle aggregators and their report history.

Chainlink bundle feeds publish multiple values in a single opaque bytes payload. The proxy exposes the current bundle through latestBundle(), while the underlying DataFeedsCache emits every accepted update as a BundleReportUpdated event. Historical event discovery is performed with Hypersync, avoiding JSON-RPC log-range limitations.

The bundle schema is feed-specific. Callers must know the word index and decimal scale for the value they consume; this module deliberately does not guess field meanings. See the verified DataFeedsCache contract and an example BundleReportUpdated transaction.

Module Attributes

BUNDLE_REPORT_UPDATED_EVENT_SIGNATURE	Solidity signature emitted by Chainlink's DataFeedsCache for bundle updates.
BUNDLE_REPORT_UPDATED_TOPIC0	Topic zero for BUNDLE_REPORT_UPDATED_EVENT_SIGNATURE.
BUNDLE_AGGREGATOR_PROXY_ABI	Minimal Chainlink bundle proxy ABI used for current and historical state reads.
BUNDLE_DATA_ID_SIZE	Number of bytes in a Chainlink bundle data identifier.
EVENT_TOPIC_SIZE	Number of bytes in an EVM event topic.
BUNDLE_REPORT_UPDATED_TOPIC_COUNT	Topic count for BundleReportUpdated.

Functions

create_bundle_aggregator_proxy(web3, ...)	Create a minimal Chainlink bundle proxy contract instance.
decode_bundle_data_id_topic(topic)	Decode an indexed bytes16 feed identifier.
decode_bundle_decimal(bundle, index, decimals, *)	Decode one fixed-width numeric field from a Chainlink bundle.
decode_bundle_report_event(*, ...)	Decode one BundleReportUpdated event.
encode_bundle_data_id_topic(data_id)	Encode an indexed bytes16 feed identifier as an event topic.
fetch_chainlink_bundle_reports_hypersync(...)	Synchronously fetch Chainlink bundle reports through Hypersync.
fetch_chainlink_bundle_reports_hypersync_async(...)	Fetch Chainlink bundle reports through Hypersync.
fetch_chainlink_latest_bundle(web3, ...[, ...])	Fetch a Chainlink bundle from its proxy at a specific block.

Classes

ChainlinkBundleReport	A historical Chainlink BundleReportUpdated event.
ChainlinkLatestBundleData	Current state returned by a Chainlink bundle aggregator proxy.

BUNDLE_REPORT_UPDATED_EVENT_SIGNATURE = 'BundleReportUpdated(bytes16,uint256,bytes)'

Solidity signature emitted by Chainlink’s DataFeedsCache for bundle updates.

BUNDLE_REPORT_UPDATED_TOPIC0 = '0x1dc1bef0b59d624eab3f0ec044781bb5b8594cd64f0ba09d789f5b51acab1614'

Topic zero for BUNDLE_REPORT_UPDATED_EVENT_SIGNATURE.

BUNDLE_AGGREGATOR_PROXY_ABI = [{'inputs': [], 'name': 'aggregator', 'outputs': [{'type': 'address'}], 'stateMutability': 'view', 'type': 'function'}, {'inputs': [], 'name': 'bundleDecimals', 'outputs': [{'type': 'uint8[]'}], 'stateMutability': 'view', 'type': 'function'}, {'inputs': [], 'name': 'description', 'outputs': [{'type': 'string'}], 'stateMutability': 'view', 'type': 'function'}, {'inputs': [], 'name': 'latestBundle', 'outputs': [{'type': 'bytes'}], 'stateMutability': 'view', 'type': 'function'}, {'inputs': [], 'name': 'latestBundleTimestamp', 'outputs': [{'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'}]

Minimal Chainlink bundle proxy ABI used for current and historical state reads.

BUNDLE_DATA_ID_SIZE = 16

Number of bytes in a Chainlink bundle data identifier.

EVENT_TOPIC_SIZE = 32

Number of bytes in an EVM event topic.

BUNDLE_REPORT_UPDATED_TOPIC_COUNT = 3

Topic count for BundleReportUpdated.

encode_bundle_data_id_topic(data_id)

Encode an indexed bytes16 feed identifier as an event topic.

Solidity right-pads indexed fixed-size byte arrays to a 32-byte topic.

Parameters

data_id (bytes) – Chainlink bundle feed identifier.

Returns

0x-prefixed 32-byte event topic.

Raises

ValueError – If data_id is not exactly 16 bytes.

Return type

str

decode_bundle_data_id_topic(topic)

Decode an indexed bytes16 feed identifier.

Parameters

topic (str) – 0x-prefixed 32-byte event topic.

Returns

The first 16 bytes containing the feed identifier.

Raises

ValueError – If the topic is not 32 bytes.

Return type

bytes

decode_bundle_decimal(bundle, index, decimals, *, signed=False)

Decode one fixed-width numeric field from a Chainlink bundle.

Bundle schemas may mix numeric and dynamic fields. The caller is responsible for selecting a numeric word and supplying the corresponding scale from bundleDecimals().

Parameters

• bundle (bytes) – Raw bundle returned by latestBundle() or its update event.

• index (int) – Zero-based 32-byte word index.

• decimals (int) – Decimal scale for this field.

• signed (bool) – Decode the word as a signed two’s-complement integer.

Returns

Human-readable decimal value.

Raises

ValueError – If the index, decimal scale, or payload length is invalid.

Return type

decimal.Decimal

class ChainlinkLatestBundleData

Bases: object

Current state returned by a Chainlink bundle aggregator proxy.

proxy: web3.contract.contract.Contract

Bundle proxy contract.

bundle: bytes

Feed-specific opaque bundle payload.

updated_at: int

Chainlink report timestamp as Unix seconds.

decimals: tuple[int, ...]

Decimal metadata for feed fields.

description: str

Human-readable feed description.

aggregator_address: eth_typing.evm.HexAddress

Underlying DataFeedsCache contract emitting report events.

property update_time: datetime.datetime

Return the report timestamp as a naive UTC datetime.

decode_decimal(index, *, signed=False)

Decode a numeric field using the proxy-provided decimal scale.

Parameters

• index (int) – Zero-based bundle field index.

• signed (bool) – Decode a signed integer field.

Returns

Human-readable decimal value.

Raises

IndexError – If the proxy has no decimal metadata for index.

Return type

decimal.Decimal

__init__(proxy, bundle, updated_at, decimals, description, aggregator_address)

Parameters

• proxy (web3.contract.contract.Contract) –

• bundle (bytes) –

• updated_at (int) –

• decimals (tuple[int, ...]) –

• description (str) –

• aggregator_address (eth_typing.evm.HexAddress) –

Return type

None

class ChainlinkBundleReport

Bases: object

A historical Chainlink BundleReportUpdated event.

aggregator_address: eth_typing.evm.HexAddress

DataFeedsCache contract that emitted the event.

data_id: bytes

Feed-specific Chainlink data identifier.

updated_at: int

Chainlink report timestamp as Unix seconds.

bundle: bytes

Feed-specific opaque bundle payload.

block_number: int

Block containing the accepted report.

block_timestamp: Optional[datetime.datetime]

Naive UTC timestamp of the containing block, when returned by Hypersync.

transaction_hash: str

Transaction hash containing the report.

log_index: int

Event position in the transaction receipt.

property update_time: datetime.datetime

Return the report timestamp as a naive UTC datetime.

decode_decimal(index, decimals, *, signed=False)

Decode a feed-specific numeric bundle field.

Parameters

• index (int) – Zero-based bundle field index.

• decimals (int) – Feed-specific decimal scale for this field.

• signed (bool) – Decode a signed integer field.

Returns

Human-readable decimal value.

Return type

decimal.Decimal

__init__(aggregator_address, data_id, updated_at, bundle, block_number, block_timestamp, transaction_hash, log_index)

Parameters

• aggregator_address (eth_typing.evm.HexAddress) –

• data_id (bytes) –

• updated_at (int) –

• bundle (bytes) –

• block_number (int) –

• block_timestamp (Optional[datetime.datetime]) –

• transaction_hash (str) –

• log_index (int) –

Return type

None

create_bundle_aggregator_proxy(web3, proxy_address)

Create a minimal Chainlink bundle proxy contract instance.

Parameters

• web3 (web3.main.Web3) – Web3 connection for the proxy’s chain.

• proxy_address (Union[eth_typing.evm.HexAddress, str]) – Chainlink bundle aggregator proxy address.

Returns

Web3 contract instance.

Return type

web3.contract.contract.Contract

fetch_chainlink_latest_bundle(web3, proxy_address, block_identifier='latest')

Fetch a Chainlink bundle from its proxy at a specific block.

Parameters

• web3 (web3.main.Web3) – Web3 connection for the proxy’s chain.

• proxy_address (Union[eth_typing.evm.HexAddress, str]) – Chainlink bundle aggregator proxy address.

• block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Current or historical block identifier.

Returns

Bundle, report timestamp, decimal metadata, description and cache address.

Raises

ValueError – If the proxy returns an empty or untimestamped bundle.

Return type

eth_defi.chainlink.bundle_aggregator.ChainlinkLatestBundleData

decode_bundle_report_event(*, aggregator_address, topics, data, block_number, block_timestamp, transaction_hash, log_index)

Decode one BundleReportUpdated event.

Parameters

• aggregator_address (Union[eth_typing.evm.HexAddress, str]) – DataFeedsCache contract emitting the event.

• topics (list[str | None]) – Event topics containing signature, data id and report timestamp.

• data (Union[bytes, str]) – ABI-encoded non-indexed bytes bundle value.

• block_number (int) – Block containing the event.

• block_timestamp (Optional[datetime.datetime]) – Naive UTC timestamp of the containing block.

• transaction_hash (str) – Transaction containing the event.

• log_index (int) – Event position within the receipt.

Returns

Decoded bundle report.

Raises

ValueError – If the topics do not match the expected event.

Return type

eth_defi.chainlink.bundle_aggregator.ChainlinkBundleReport

async fetch_chainlink_bundle_reports_hypersync_async(hypersync_client, *, aggregator_address, start_block, end_block, data_ids=None, recv_timeout=90.0)

Fetch Chainlink bundle reports through Hypersync.

The query targets the underlying DataFeedsCache address, not the bundle proxy: the cache emits reports while the proxy only forwards state reads.

Parameters

• hypersync_client – Configured native or throttled Hypersync client.

• aggregator_address (Union[eth_typing.evm.HexAddress, str]) – DataFeedsCache contract emitting report events.

• start_block (int) – Inclusive first block.

• end_block (int) – Inclusive final block.

• data_ids (Optional[set[bytes]]) – Optional set of 16-byte feed identifiers to include.

• recv_timeout (float) – Maximum wait for each streamed response.

Returns

Reports sorted by block and log index.

Return type

list[eth_defi.chainlink.bundle_aggregator.ChainlinkBundleReport]

fetch_chainlink_bundle_reports_hypersync(hypersync_client, *, aggregator_address, start_block, end_block, data_ids=None, recv_timeout=90.0)

Synchronously fetch Chainlink bundle reports through Hypersync.

Parameters

• hypersync_client – Configured native or throttled Hypersync client.

• aggregator_address (Union[eth_typing.evm.HexAddress, str]) – DataFeedsCache contract emitting report events.

• start_block (int) – Inclusive first block.

• end_block (int) – Inclusive final block.

• data_ids (Optional[set[bytes]]) – Optional set of 16-byte feed identifiers to include.

• recv_timeout (float) – Maximum wait for each streamed response.

Returns

Reports sorted by block and log index.

Return type

list[eth_defi.chainlink.bundle_aggregator.ChainlinkBundleReport]