feat(zenrock): add historical query support with x-cosmos-block-height header

- Add timestampToBlockHeight function with hybrid estimation + binary search
  to ensure accuracy within 60 seconds
- Add apiRequest helper function to pass x-cosmos-block-height header
  for all API calls to api.diamond.zenrocklabs.io
- Update zcashTvl to use historical queries for timestamps > 1 hour ago
- Update bitcoin tvl to pass blockHeight to zenrock fetcher
- Update zenrock fetcher to accept blockHeight parameter and use header
  for all treasury API endpoints
- Support historical queries for last ~274k blocks (~16 days)
- Enable timetravel: true for DefiLlama historical charts

Author: Peyton-Spencer

projects/helper/bitcoin-book/fetchers.js

@@ -242,12 +242,27 @@ module.exports = {
     })
     return Array.from(new Set(staticAddresses))
   },
-  zenrock: async () => {
+  zenrock: async (blockHeight = null) => {
     const ZRCHAIN_WALLETS_API = 'https://api.diamond.zenrocklabs.io/zrchain/treasury/zenbtc_wallets';
     const ZENBTC_PARAMS_API = 'https://api.diamond.zenrocklabs.io/zenbtc/params';
     const ZRCHAIN_KEY_BY_ID_API = 'https://api.diamond.zenrocklabs.io/zrchain/treasury/key_by_id';
 
-    return getConfig('zenrock/addresses', undefined, {
+    // Helper function to make API requests with optional height header
+    async function apiRequest(url, height = null) {
+      const options = {};
+      if (height) {
+        options.headers = {
+          'x-cosmos-block-height': String(height)
+        };
+      }
+
+      return await get(url, options);
+    }
+
+    // Use cache key that includes block height for historical queries
+    const cacheKey = blockHeight ? `zenrock/addresses/${blockHeight}` : 'zenrock/addresses';
+
+    return getConfig(cacheKey, undefined, {
       fetcher: async () => {
         async function getBitcoinAddresses() {
           const btcAddresses = [];
@@ -258,7 +273,11 @@ module.exports = {
             if (nextKey) {
               url += `?pagination.key=${encodeURIComponent(nextKey)}`;
             }
-            const { data } = await axios.get(url);
+            const data = await apiRequest(url, blockHeight);
+            if (!data) {
+              // Historical state not available, return empty array
+              return [];
+            }
             if (data.zenbtc_wallets && Array.isArray(data.zenbtc_wallets)) {
               for (const walletGroup of data.zenbtc_wallets) {
                 if (walletGroup.wallets && Array.isArray(walletGroup.wallets)) {
@@ -282,10 +301,17 @@ module.exports = {
         async function getChangeAddresses() {
           const changeAddresses = [];
 
-          const { data: paramsData } = await axios.get(ZENBTC_PARAMS_API);
+          const paramsData = await apiRequest(ZENBTC_PARAMS_API, blockHeight);
+          if (!paramsData) {
+            // Historical state not available, return empty array
+            return [];
+          }
           const changeAddressKeyIDs = paramsData.params?.changeAddressKeyIDs || [];
           for (const keyID of changeAddressKeyIDs) {
-            const { data: keyData } = await axios.get(`${ZRCHAIN_KEY_BY_ID_API}/${keyID}/WALLET_TYPE_BTC_MAINNET/`);
+            const keyData = await apiRequest(`${ZRCHAIN_KEY_BY_ID_API}/${keyID}/WALLET_TYPE_BTC_MAINNET/`, blockHeight);
+            if (!keyData) {
+              continue; // Skip this key if historical state not available
+            }
             if (keyData.wallets && Array.isArray(keyData.wallets)) {
               for (const wallet of keyData.wallets) {
                 if (wallet.type === 'WALLET_TYPE_BTC_MAINNET' && wallet.address) {

projects/zenrock/index.js

@@ -1,49 +1,164 @@
 const { sumTokens: sumBitcoinTokens } = require('../helper/chain/bitcoin');
 const { zenrock } = require('../helper/bitcoin-book/fetchers');
+const { get } = require('../helper/http');
+const sdk = require('@defillama/sdk');
+
+const ZRCHAIN_RPC = 'https://rpc.diamond.zenrocklabs.io';
+const ZRCHAIN_API = 'https://api.diamond.zenrocklabs.io';
+
+// Chain launch timestamp (genesis block): 2024-11-20T17:39:07Z
+const GENESIS_TIMESTAMP = 1732124347;
+
+// Cache for block height lookups to avoid repeated RPC calls
+const blockHeightCache = new Map();
+
+async function timestampToBlockHeight(timestamp) {
+  // Ensure timestamp is not before chain launch
+  if (timestamp < GENESIS_TIMESTAMP) {
+    return 1; // Return genesis block height
+  }
+
+  // Check cache first (cache by day to reduce API calls)
+  const dayKey = Math.floor(timestamp / 86400);
+  if (blockHeightCache.has(dayKey)) {
+    return blockHeightCache.get(dayKey);
+  }
+
+  // Get latest block height
+  const status = await get(`${ZRCHAIN_RPC}/status`);
+  const latestHeight = parseInt(status.result.sync_info.latest_block_height);
+
+  // Get latest block timestamp
+  const latestBlock = await get(`${ZRCHAIN_RPC}/block?height=${latestHeight}`);
+  const latestBlockTime = new Date(latestBlock.result.block.header.time).getTime() / 1000;
+
+  // Estimate block height (5 seconds per block for zrchain)
+  const avgBlockTime = 5; // seconds
+  const genesisTime = latestBlockTime - (latestHeight * avgBlockTime);
+  let estimatedHeight = Math.max(1, Math.min(
+    Math.floor((timestamp - genesisTime) / avgBlockTime),
+    latestHeight
+  ));
+
+  // Refine estimate to ensure accuracy within 60 seconds
+  const targetAccuracy = 60; // seconds
+  let low = Math.max(1, estimatedHeight - 1000); // Search range: ±1000 blocks
+  let high = Math.min(latestHeight, estimatedHeight + 1000);
+  let bestHeight = estimatedHeight;
+  let bestDiff = Infinity;
+
+  // Binary search to find block within target accuracy
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const block = await get(`${ZRCHAIN_RPC}/block?height=${mid}`);
+    const blockTime = new Date(block.result.block.header.time).getTime() / 1000;
+    const diff = Math.abs(blockTime - timestamp);
+
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      bestHeight = mid;
+    }
+
+    // If within target accuracy, we're done
+    if (diff <= targetAccuracy) {
+      estimatedHeight = mid;
+      break;
+    }
+
+    if (blockTime < timestamp) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  // Use best height found if we didn't find one within accuracy
+  if (bestDiff > targetAccuracy) {
+    estimatedHeight = bestHeight;
+  }
+
+  // Cache the result
+  blockHeightCache.set(dayKey, estimatedHeight);
+
+  // Limit cache size
+  if (blockHeightCache.size > 100) {
+    const firstKey = blockHeightCache.keys().next().value;
+    blockHeightCache.delete(firstKey);
+  }
+
+  return estimatedHeight;
+}
+
+// Helper function to make API requests with optional height header
+async function apiRequest(url, blockHeight = null) {
+  const options = {};
+  if (blockHeight) {
+    options.headers = {
+      'x-cosmos-block-height': String(blockHeight)
+    };
+  }
+
+  try {
+    return await get(url, options);
+  } catch (error) {
+    // If historical query fails (code 13 - nil pointer), return null
+    // This indicates historical state is not available
+    const errorStr = error.message || error.toString() || '';
+    if (errorStr.includes('code 13') || errorStr.includes('nil pointer')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function tvl(api) {
+  // Extract timestamp from api parameter
+  const timestamp = api?.timestamp;
+  const now = Date.now() / 1000;
+
+  // Determine block height for historical queries
+  let blockHeight = null;
+  if (timestamp && (now - timestamp) > 3600) {
+    blockHeight = await timestampToBlockHeight(timestamp);
+  }
 
-/**
- * Queries Bitcoin balances for all zrchain treasury and change addresses
- * Returns balances object with Bitcoin TVL
- */
-async function tvl() {
   // Fetch all protocol addresses (treasury + change) from the bitcoin-book fetcher
-  const allAddresses = await zenrock();
+  // Pass blockHeight for historical queries
+  const allAddresses = await zenrock(blockHeight);
 
   if (allAddresses.length === 0) {
     return { bitcoin: '0' };
   }
 
   // Use Bitcoin helper to sum balances for all addresses
+  // Pass timestamp if available for historical queries
   const balances = {};
-  await sumBitcoinTokens({ balances, owners: allAddresses });
+  await sumBitcoinTokens({ balances, owners: allAddresses, timestamp });
 
   return balances;
 }
 
-/**
- * Queries Zcash balances for all zrchain treasury and change addresses
- * Returns balances object with Zcash TVL
- *
- * NOTE: Currently using supply-based approach as a test implementation.
- * The address-based approach is commented out below for future use.
- */
-async function zcashTvl() {
-  // Fetch custodied amount from DCT supply endpoint
-  const { get } = require('../helper/http');
-  const { getConfig } = require('../helper/cache');
-  const sdk = require('@defillama/sdk');
-
-  const DCT_SUPPLY_API = 'https://api.diamond.zenrocklabs.io/dct/supply';
-
-  const supplyData = await getConfig('zenrock/dct_supply', DCT_SUPPLY_API, {
-    fetcher: async () => {
-      const response = await get(DCT_SUPPLY_API);
-      return response;
-    }
-  });
-
+async function zcashTvl(api) {
   const balances = {};
 
+  // Extract timestamp from api parameter
+  const timestamp = api?.timestamp;
+  const now = Date.now() / 1000;
+
+  // Determine block height for historical queries
+  let blockHeight = null;
+  if (timestamp && (now - timestamp) > 3600) {
+    blockHeight = await timestampToBlockHeight(timestamp);
+  }
+
+  // Fetch custodied amount from DCT supply endpoint with height header
+  const supplyData = await apiRequest(`${ZRCHAIN_API}/dct/supply`, blockHeight);
+
+  // If historical query failed (state not available), return empty balances
+  if (!supplyData) {
+    return balances;
+  }
+
   // Find ASSET_ZENZEC in supplies array
   const zenZecSupply = supplyData.supplies?.find(
     item => item.supply?.asset === 'ASSET_ZENZEC'
@@ -62,6 +177,8 @@ async function zcashTvl() {
 }
 
 module.exports = {
+  timetravel: true,
+  start: GENESIS_TIMESTAMP,
   methodology: 'zrchain locks native assets through its decentralized MPC network. zenBTC, Zenrock\'s flagship product, is a yield-bearing wrapped Bitcoin issued on Solana and EVM chains. TVL represents the total Bitcoin locked in zrchain treasury addresses. All zenBTC is fully backed by native Bitcoin, with the price of zenBTC anticipated to increase as yield payments are made continuously.',
   bitcoin: {
     tvl,