fathom-fyi

Instructions

Implementation Reference

• src/tools/get-onchain-pulse.ts:9-85 (handler)

  The `getOnchainPulse` function retrieves and computes Bitcoin network metrics, including mempool congestion, network security, and mining economics. It caches the result and returns a guidance string.

  export async function getOnchainPulse(cache: CacheService): Promise<OnchainPulseOutput | ErrorOutput> {
    const cached = cache.get<OnchainPulseOutput>(CACHE_KEY);
    if (cached) return cached.data;
  
    try {
      const [fees, blockHeight, pools, difficulty] = await Promise.allSettled([
        getRecommendedFees(),
        getBlockTipHeight(),
        getHashratePools(),
        getDifficultyAdjustments(),
      ]);
  
      // Fees & congestion
      let recommendedFee = 0;
      let congestion: Congestion = 'normal';
      if (fees.status === 'fulfilled') {
        recommendedFee = fees.value.halfHourFee;
        congestion = classifyCongestion(fees.value);
      }
  
      // Block height
      const height = blockHeight.status === 'fulfilled' ? blockHeight.value : 0;
  
      // Miner distribution
      let minerDistribution: MinerPool[] = [];
      let security: NetworkSecurity = 'normal';
      if (pools.status === 'fulfilled' && pools.value.pools) {
        minerDistribution = pools.value.pools
          .sort((a, b) => b.share - a.share)
          .slice(0, 10)
          .map(p => ({
            pool_name: p.name,
            share_percentage: Math.round(p.share * 10000) / 100,
          }));
  
        // Security assessment: if top pool > 30%, weak; if no pool > 20%, strong
        const topShare = minerDistribution.length > 0 ? minerDistribution[0].share_percentage : 0;
        security = topShare > 30 ? 'weak' : topShare < 20 ? 'strong' : 'normal';
      }
  
      // Mining economics
      let miningEconomics: MiningEconomics = 'profitable';
      if (difficulty.status === 'fulfilled' && difficulty.value.length > 0) {
        const latestDiff = difficulty.value[0];
        if (latestDiff.difficultyChange > 5) miningEconomics = 'profitable';
        else if (latestDiff.difficultyChange < -5) miningEconomics = 'stressed';
        else miningEconomics = 'marginal';
      }
  
      // On-chain activity
      const activity = classifyActivity(congestion, recommendedFee);
  
      const guidance = generateOnchainGuidance(congestion, security, miningEconomics, activity, recommendedFee);
  
      const result: OnchainPulseOutput = {
        block_height: height,
        mempool_congestion: congestion,
        recommended_fee_sats: recommendedFee,
        miner_distribution: minerDistribution,
        network_security: security,
        mining_economics: miningEconomics,
        onchain_activity: activity,
        agent_guidance: guidance,
      };
  
      cache.set(CACHE_KEY, result, getCacheTtl(BASE_TTL));
      return result;
    } catch (err) {
      return {
        error: true,
        error_source: 'get_onchain_pulse',
        agent_guidance: 'Bitcoin on-chain data unavailable. Without network health context, avoid making timing-sensitive BTC transactions. Network conditions are unknown.',
        last_known_data: cache.get<OnchainPulseOutput>(CACHE_KEY)?.data ?? null,
        data_warnings: ['On-chain data source temporarily unavailable. Retry shortly.'],
      };
    }
  }