[rafa-stacks]

Adds two v3 endpoints that expose a principal's matured miner rewards.

• GET /extended/v3/principals/{principal}/mining: lifetime totals.
• GET /extended/v3/principals/{principal}/mining/rewards: the individual rewards, cursor-paginated.

Sample responses

GET /extended/v3/principals/SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW/mining

{
  "rewards": {
    "count": 3,
    "coinbase": "2000000000",
    "fees": "2535218",
    "total": "2002535218"
  }
}

GET /extended/v3/principals/SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW/mining/rewards?limit=2

{
  "total": 3,
  "limit": 2,
  "cursor": {
    "next": "4:0",
    "previous": null,
    "current": "5:0"
  },
  "results": [
    {
      "id": "0x000000000000000000000000000000000000000000000000000000000000b005:0",
      "recipient": "SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW",
      "miner": "SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW",
      "block": {
        "height": 5,
        "hash": "0x000000000000000000000000000000000000000000000000000000000000a005",
        "index_hash": "0x000000000000000000000000000000000000000000000000000000000000b005",
        "time": 1759000025
      },
      "source_block": {
        "height": 2,
        "hash": "0x000000000000000000000000000000000000000000000000000000000000a002",
        "index_hash": "0x000000000000000000000000000000000000000000000000000000000000b002",
        "time": 1759000010
      },
      "coinbase": "1000000000",
      "fees": "955218",
      "total": "1000955218"
    },
    {
      "id": "0x000000000000000000000000000000000000000000000000000000000000b004:1",
      "recipient": "SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW",
      "miner": "SP1NQA8HBMS6TCF9RXGQ2ZHE1VD87NE0Z6PNRNAFW",
      "block": {
        "height": 4,
        "hash": "0x000000000000000000000000000000000000000000000000000000000000a004",
        "index_hash": "0x000000000000000000000000000000000000000000000000000000000000b004",
        "time": 1759000020
      },
      "source_block": {
        "height": 1,
        "hash": "0x000000000000000000000000000000000000000000000000000000000000a001",
        "index_hash": "0x000000000000000000000000000000000000000000000000000000000000b001",
        "time": 1759000005
      },
      "coinbase": "0",
      "fees": "1580000",
      "total": "1580000"
    }
  ]
}

[codecov]

Codecov Report

❌ Patch coverage is 99.09256% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/datastore/pg-store.ts	0.00%	3 Missing ⚠️
...ons/1779800000028_miner-reward-index-and-totals.ts	98.93%	0 Missing and 1 partial ⚠️
src/api/routes/v3/principals.ts	98.63%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Copilot review overview

🔵 Needs a closer look

The persistent aggregate migration and bidirectional reorg accounting warrant final human validation despite strong test coverage.

Review effort: Balanced
Findings: None

What changed in this PR

Adds v3 principal mining summary and paginated matured-reward endpoints, backed by materialized totals and reorg-aware accounting.

Changes:

• Adds reward indexing, aggregation, serialization, schemas, and routes.
• Maintains totals during ingestion and reorgs.
• Adds comprehensive endpoint, pagination, migration, and cache tests.

File	Description
migrations/​1779800000028_miner-reward-index-and-totals.ts	Adds reward indexes and aggregate totals.
src/​api/​pagination.ts	Defines mining reward page limits.
src/​api/​routes/​v3/​principals.ts	Adds both mining endpoints.
src/​api/​schemas/​v3/​cursors.ts	Defines reward cursors.
src/​api/​schemas/​v3/​entities/​common.ts	Centralizes block summaries.
src/​api/​schemas/​v3/​entities/​principal-miner-rewards.ts	Defines response entities.
src/​api/​schemas/​v3/​entities/​search.ts	Uses the shared block summary.
src/​api/​serializers/​v3/​miner-rewards.ts	Serializes rewards and totals.
src/​datastore/​common.ts	Extends miner reward types.
src/​datastore/​pg-store.ts	Reads indexed rewards.
src/​datastore/​pg-write-store.ts	Maintains totals and reorg deltas.
src/​datastore/​v3/​helpers.ts	Parses and encodes reward cursors.
src/​datastore/​v3/​pg-store-v3.ts	Implements mining queries and pagination.
src/​datastore/​v3/​types.ts	Adds mining query result types.
src/​event-stream/​event-server.ts	Assigns reward indexes during ingestion.
tests/​api/​datastore/​datastore.test.ts	Updates reward fixtures.
tests/​api/​datastore/​other.test.ts	Updates reward fixture compatibility.
tests/​api/​principal-v3/​principal-mining.test.ts	Tests endpoints, reorgs, and migration.
tests/​api/​test-builders.ts	Supports indexed reward fixtures.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.