Skip to content

README.md

Latest commit

 

History

History
92 lines (62 loc) · 2.3 KB

README.md

File metadata and controls

92 lines (62 loc) · 2.3 KB
Raw

BTC Energy API

GraphQL service for estimating Bitcoin network energy usage from public blockchain data.

Overview

The service exposes a single GraphQL endpoint and provides:

  • energy consumption per transaction for a specific block;
  • total daily energy consumption for the last N days;
  • total energy consumption for transactions linked to a wallet address.

The API is designed for frontend dashboards and reporting workloads where low latency and predictable API behavior are required.

Stack

  • Runtime: Node.js 20
  • Language: TypeScript
  • API: GraphQL (graphql, graphql-compose, graphql-helix)
  • HTTP/Lambda adapter: lambda-api
  • Deployment model: AWS Lambda + API Gateway (serverless)
  • Build: serverless-esbuild, esbuild
  • Local development: serverless-offline
  • Testing: jest

Domain Model

  • Bitcoin network consists of blocks.
  • Blocks include transactions.
  • Transaction size is measured in bytes (tx.size).
  • Energy coefficient is fixed: 4.56 kWh per byte.

API

Endpoint:

http://localhost:4000/graphql

Queries

  1. energyPerTransactionByBlock(blockHash: String, blockHeight: Int)
  • Calculates per-transaction energy for one block.
  • Requires exactly one selector: blockHash or blockHeight.
  1. dailyEnergyConsumptionLastDays(days: Int!)
  • Returns daily energy totals for the last N days.
  • Uses cumulative blockchain size chart deltas plus per-day block count lookup.
  • Optimized to reduce upstream request volume and avoid rate-limit bursts.
  1. walletEnergyConsumption(address: String!)
  • Returns energy total for transactions associated with a wallet address.

Data Sources

Public Blockchain APIs:

  • https://blockchain.info/rawblock/{hash}
  • https://blockchain.info/block-height/{height}?format=json
  • https://blockchain.info/blocks/{unix_ms}?format=json
  • https://blockchain.info/rawaddr/{address}
  • https://api.blockchain.info/charts/blocks-size?timespan={N}days&format=json

Running Locally

Requirements:

  • Node.js 20.x
  • Yarn

Install dependencies:

yarn

Run the API:

yarn start

Type check:

yarn compile

Notes

  • Upstream blockchain endpoints may enforce strict rate limits.
  • The service applies in-memory caching and request throttling.
  • Daily aggregation uses chart deltas to keep external call volume low.