block_range

Converts a UTC date or timestamp interval into a half-open block range: from_block is inclusive and to_block is exclusive.

Example

Needs RPC · RPC required

1
-- Resolve the [from_block, to_block) bounds for one UTC day
2
SELECT
3
(range).from_block AS from_block,
4
(range).to_block AS to_block
5
FROM (
6
SELECT block_range($client, '2024-01-15'::DATE) AS range
7
);
Notebook ready in readonly mode.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

block_range(CLIENT, DATE) # RPC required

Accepts a DATE and returns the block interval covering that UTC calendar day.

Inputs

Name Type Use
client CLIENT

Attached live CLIENT for the chain to search.

 required positional
date DATE

DATE for a UTC day or TIMESTAMP/TIMESTAMPTZ range start.

 required positional

Returns

Name Type
block_range STRUCT(from_block BIGINT, to_block BIGINT)

Inclusive/exclusive block range. Returns STRUCT(from_block BIGINT, to_block BIGINT) representing [from_block, to_block). get_logs uses an inclusive to_block, so pass (range).to_block - 1 when scanning the returned interval.

Guidance

Use the range with get_logs

block_range returns [from_block, to_block), while get_logs accepts inclusive block bounds.

Pass (range).from_block and (range).to_block - 1 when querying the returned interval.

Historical ranges require a provider that retains the requested blocks.

Using block_range with get_logs

block_range returns from_block inclusive and to_block exclusive. get_logs expects an inclusive to_block, so subtract one before passing the upper bound to get_logs.

Historical day ranges require an archive-capable provider.

Named parameters · RPC required

1
WITH r AS (
2
SELECT block_range($client, '2024-01-08'::DATE) AS range
3
)
4
SELECT transaction_hash, log_index, "from", "to", format_units(value, 18) AS pendle_amount
5
FROM r,
6
get_logs(
7
$client,
8
'0x808507121B80c02388fAd14726482e061B8da827'::ADDRESS,
9
'event Transfer(address indexed from, address indexed to, uint256 value)',
10
(range).from_block,
11
(range).to_block - 1
12
);
Notebook ready in readonly mode.

Additional overloads

block_range(CLIENT, TIMESTAMP WITH TIME ZONE, TIMESTAMP WITH TIME ZONE) # RPC required

Accepts two TIMESTAMPTZ values and resolves their absolute instants to a half-open block interval.

Inputs

Name Type Use
client CLIENT

Attached live CLIENT for the chain to search.

 required positional
from_timestamp TIMESTAMP WITH TIME ZONE

DATE for a UTC day or TIMESTAMP/TIMESTAMPTZ range start.

 required positional
to_timestamp TIMESTAMP WITH TIME ZONE

Exclusive TIMESTAMP/TIMESTAMPTZ range end.

 required positional

Returns

Name Type
block_range STRUCT(from_block BIGINT, to_block BIGINT)

Inclusive/exclusive block range. Returns STRUCT(from_block BIGINT, to_block BIGINT) representing [from_block, to_block). get_logs uses an inclusive to_block, so pass (range).to_block - 1 when scanning the returned interval.

block_range(CLIENT, TIMESTAMP, TIMESTAMP) # RPC required

Accepts two plain TIMESTAMP values, interprets them as UTC, and returns a half-open block interval.

Inputs

Name Type Use
client CLIENT

Attached live CLIENT for the chain to search.

 required positional
from_timestamp TIMESTAMP

DATE for a UTC day or TIMESTAMP/TIMESTAMPTZ range start.

 required positional
to_timestamp TIMESTAMP

Exclusive TIMESTAMP/TIMESTAMPTZ range end.

 required positional

Returns

Name Type
block_range STRUCT(from_block BIGINT, to_block BIGINT)

Inclusive/exclusive block range. Returns STRUCT(from_block BIGINT, to_block BIGINT) representing [from_block, to_block). get_logs uses an inclusive to_block, so pass (range).to_block - 1 when scanning the returned interval.

Related functions

Category and tags

Category
Chain reads
Tag
RPC