[rafa-stacks]

Schedule points on past Bitcoin blocks that no canonical Stacks block anchored to (e.g. missed sortitions) now return an estimated time / time_iso in bond and PoX cycle schedules, interpolated between the nearest anchored blocks before and after them, instead of null; projected_time stays reserved for future blocks.

Sample responses from a seeded fixture (Stacks blocks anchored only to Bitcoin heights 150 and 160, test block times at 9-minute spacing, so 155 and 159 are interpolated):

GET /extended/v3/staking/bonds/0 (schedule excerpt)

{
  "index": 0,
  "schedule": {
    "enrollment_cutoff": { "bitcoin_height": 155, "pox_cycle": 7, "time": 1700083700, "time_iso": "2023-11-15T21:28:20.000Z", "projected_time": null, "projected_time_iso": null },
    "activation": { "bitcoin_height": 160, "pox_cycle": 8, "time": 1700086400, "time_iso": "2023-11-15T22:13:20.000Z", "projected_time": null, "projected_time_iso": null },
    "unlock": { "bitcoin_height": 410, "pox_cycle": 20, "time": null, "time_iso": null, "projected_time": 1700221400, "projected_time_iso": "2023-11-17T11:43:20.000Z" }
  }
}

GET /extended/v3/staking/cycles/7 (schedule excerpt; 140 predates every Stacks block, so it stays null)

{
  "number": 7,
  "status": "finished",
  "schedule": {
    "start": { "bitcoin_height": 140, "time": null, "time_iso": null, "projected_time": null, "projected_time_iso": null },
    "prepare_phase_start": { "bitcoin_height": 155, "time": 1700083700, "time_iso": "2023-11-15T21:28:20.000Z", "projected_time": null, "projected_time_iso": null },
    "end": { "bitcoin_height": 159, "time": 1700085860, "time_iso": "2023-11-15T22:04:20.000Z", "projected_time": null, "projected_time_iso": null }
  }
}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

The fixture helper mishandles its first anchored height, and bond endpoint interpolation lacks direct coverage.

2 open findings

• Add interpolation coverage for bond and bond-event schedules · New
• Include oldest anchor height in confirmed schedule results · New

What changed in this PR

Adds interpolated timestamps for past unanchored Bitcoin heights in PoX schedules.

Changes:

• Interpolates times between canonical anchored blocks.
• Serializes estimates as confirmed schedule times.
• Updates schemas and tests for the new behavior.

File	Description
src/​datastore/​bitcoin-block-time.ts	Defines interpolation support.
src/​datastore/​v3/​pg-store-v3.ts	Queries neighboring anchors and interpolates.
src/​api/​serializers/​v3/​bitcoin-block-times.ts	Serializes interpolated times.
src/​api/​schemas/​v3/​entities/​common.ts	Documents estimated timestamps.
tests/​api/​pox5/​bitcoin-block-time.test.ts	Tests interpolation and canonicality.
tests/​api/​pox5/​staking-cycle.test.ts	Updates cycle schedule expectations.
tests/​api/​pox5/​bonds.test.ts	Updates fixture commentary.
tests/​api/​pox5/​bond-events.test.ts	Updates fixture commentary.

🧠 Review effort: Balanced

---

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

[Copilot]

🔵 Needs a closer look

The public schema description contradicts the new interpolated timestamp semantics.

0 open findings

2 resolved since last review

• Include oldest anchor height in confirmed schedule results
• Add interpolation coverage for bond and bond-event schedules

Previously missed (1)

In code that hasn't changed since last review

Clarify OpenAPI description for header times versus estimates

src/​api/​schemas/​v3/​entities/​common.ts:118

The opening sentence says every time value was recorded in a Bitcoin header, but this field now also contains synthesized timestamps, as the following sentence acknowledges. This makes the public OpenAPI description contradictory; distinguish exact anchored header times from interpolated estimates.

🧠 Review effort: Balanced