Add Historical Query Support for Zenrock DefiLlama Adapter

[Peyton-Spencer]

Summary

This PR adds historical query support to the Zenrock DefiLlama adapter, enabling timeseries charts for Bitcoin and Zcash TVL. The implementation uses Cosmos SDK's x-cosmos-block-height HTTP header to query historical blockchain state.

Changes

Core Implementation

• Hybrid timestamp-to-block-height conversion: Combines fast estimation with binary search refinement to ensure accuracy within 60 seconds
• Historical query support: All API calls to api.diamond.zenrocklabs.io now support historical queries via x-cosmos-block-height header
• Error handling: Throws descriptive errors when historical state is unavailable

Files Modified

• projects/zenrock/index.js - Added historical query logic and hybrid block height conversion
• projects/helper/bitcoin-book/fetchers.js - Updated zenrock fetcher to accept blockHeight parameter

Features

• ✅ Enabled timetravel: true for DefiLlama historical charts
• ✅ Accurate timestamp-to-block-height conversion (within 60 seconds)
• ✅ Caching by day to reduce RPC calls
• ✅ Supports historical queries for both Bitcoin and Zcash TVL
• ✅ All treasury API endpoints support historical queries
• ✅ Throws errors for timestamps before chain genesis
• ✅ Throws errors when historical data is unavailable

Testing

Verified Endpoints

All API endpoints tested and confirmed working with x-cosmos-block-height header:

• ✅ /dct/supply - Returns historical custodied amounts
• ✅ /zrchain/treasury/zenbtc_wallets - Returns historical wallet addresses
• ✅ /zenbtc/params - Returns historical change address key IDs
• ✅ /zrchain/treasury/key_by_id/{id}/WALLET_TYPE_BTC_MAINNET/ - Returns historical wallet data

Historical Query Accuracy

Tested with different block heights:

• Height 5,350,000: custodied_amount = 56,537,756,747 Zatoshi (565.38 ZEC)
• Height 5,300,000: custodied_amount = 44,067,009,310 Zatoshi (440.67 ZEC)
• Current: custodied_amount = 56,937,756,747 Zatoshi (569.38 ZEC)

✅ Confirmed historical queries return accurate historical data showing TVL growth over time.

Important Limitation

⚠️ Historical State Availability: Historical data availability varies by module:

• DCT module (/dct/supply): Launched on 2025-10-31. Historical queries fail with code 13 error for blocks before the module existed or when historical state has been pruned.
• zenbtc/treasury endpoints: Have much deeper historical availability (300+ days tested). Historical queries work reliably for older blocks.

Queries for unavailable historical blocks will return:

{"code": 13, "message": "runtime error: invalid memory address or nil pointer dereference"}

The adapter throws descriptive errors when historical data is unavailable, rather than silently returning empty balances.

Technical Details

Algorithm

1. Initial Estimation: Uses average block time (5 seconds) to estimate block height
2. Binary Search Refinement: Searches within ±1000 blocks to find block within 60 seconds of target timestamp
3. Caching: Results cached by day to reduce redundant RPC calls

Performance

• Binary search makes at most ~20 RPC calls (log2(2000) ≈ 11) per timestamp conversion
• Caching significantly reduces API load for repeated queries
• Historical queries slower than current queries (expected behavior)

DefiLlama Compliance

• ✅ No try/catch blocks
• ✅ No dotenv usage
• ✅ Error handling throws errors instead of returning empty data
• ✅ timetravel: true enabled

Checklist

• Code follows DefiLlama adapter standards
• All endpoints tested with historical queries
• Error handling implemented for unavailable historical state
• Documentation added
• No breaking changes to existing functionality

[llamabutler]

The adapter at projects/zenrock exports TVL:

bitcoin                   7.52 M
zcash                     242.31 k

total                    7.76 M 

[llamabutler]

The adapter at projects/zenrock exports TVL:

bitcoin                   7.53 M
zcash                     242.70 k

total                    7.77 M 

[llamabutler]

The adapter at projects/zenrock exports TVL:

bitcoin                   7.63 M
zcash                     310.75 k

total                    7.94 M 

[Peyton-Spencer]

@waynebruce0x applied your feedback, thanks for review