RPCUsageDatabase

Documentation for eth_defi.provider.rpcdb.RPCUsageDatabase Python class.

class RPCUsageDatabase

Bases: object

Append-only DuckDB storage for JSON-RPC scan accounting.

One connection belongs to one externally serialised writer. Callers sharing a database across processes must hold their pipeline lock for the complete connection lifetime.

Open the tracking database and initialise its fixed schema.

Parameters

path – DuckDB file path. Parent directories are created automatically.

Methods summary

__init__(path)	Open the tracking database and initialise its fixed schema.
allocate_cycle()	Allocate the next persistent cycle number.
close()	Checkpoint and close the DuckDB connection explicitly.
fetch_cycle_calls(chain, cycle_started, ...)	Fetch current-cycle method rows for one chain.
fetch_cycle_errors(chain, cycle_started, ...)	Fetch current-cycle error totals for one chain.
fetch_daily_totals(chain, cycle_started)	Fetch daily provider totals without multiplying retry item counts.
record_scan(chain, phase, cycle_started, ...)	Append one completed scan-attempt aggregate atomically.

__init__(path)

Open the tracking database and initialise its fixed schema.

Parameters

path (pathlib.Path) – DuckDB file path. Parent directories are created automatically.

Return type

None

allocate_cycle()

Allocate the next persistent cycle number.

Allocation uses both tables and must be called while the external pipeline-writer lock is held. A crash before the first row is inserted may reuse the unpersisted number on the next invocation.

Returns

Next positive cycle number.

Return type

int

record_scan(chain, phase, cycle_started, cycle_number, stats, items_scanned)

Append one completed scan-attempt aggregate atomically.

Call and error rows are committed in the same transaction. An empty call aggregate writes a zero-count marker so the scan iteration and its item count remain visible. Unknown item counts on early failures should be passed as zero.

Parameters

• chain (int) – EVM chain id.

• phase (str) – Caller-defined scan phase, for example lead_discovery.

• cycle_started (datetime.date) – Naive UTC calendar date on which the logical cycle started.

• cycle_number (int) – Persistent cycle identifier shared by scanner retries.

• stats (eth_defi.provider.rpcdb.RPCRequestStats) – Physical request and error counters for this attempt only.

• items_scanned (int) – Non-negative number of logical items submitted during the attempt.

Return type

None

fetch_cycle_calls(chain, cycle_started, cycle_number)

Fetch current-cycle method rows for one chain.

Parameters

• chain (int) – EVM chain id.

• cycle_started (datetime.date) – UTC cycle date.

• cycle_number (int) – Persistent cycle number.

Returns

Rows of (phase, provider_domain, api_call, call_count, items_scanned) aggregated across retry attempts.

Return type

list[tuple[str, str, str, int, int]]

fetch_daily_totals(chain, cycle_started)

Fetch daily provider totals without multiplying retry item counts.

Each cycle contributes the sum of its method rows and the maximum item count reported by any retry. Provider rows display provider-specific calls with the cycle-level item denominator.

Returns

Rows of (phase, provider_domain, call_count, items_scanned).

Parameters

• chain (int) –

• cycle_started (datetime.date) –

Return type

list[tuple[str, str, int, int]]

fetch_cycle_errors(chain, cycle_started, cycle_number)

Fetch current-cycle error totals for one chain.

Returns

Rows of (phase, provider_domain, error_code, error_message, error_count).

Parameters

• chain (int) –

• cycle_started (datetime.date) –

• cycle_number (int) –

Return type

list[tuple[str, str, str, str, int]]

close()

Checkpoint and close the DuckDB connection explicitly.

Return type

None