feat: materialized locked-STX table and v3 principal balance endpoints

[rafa-stacks]

Summary

This branch introduces a materialized current-state table for locked STX (modeled on ft_balances) and three new v3 principal balance endpoints, all backed by materialized tables so balances are single-row / index-served lookups rather than multi-version event scans.

Locked STX (stx_locked_balances)

• New stx_locked_balances table: one row per principal holding the current lock state (amount, unlock burn height, pox version, lock provenance), so a principal's locked STX is a single-row lookup.
• Maintained on write from pox-5 stake / stake-update / unstake events and inherited pox-1..4 stx_lock events; backfilled in the migration from existing canonical lock events.
• Reorg-safe: affected principals are recomputed from their latest canonical lock-changing event (locked STX is a set/latest-wins value, so it can't be delta-applied like ft_balances).
• Read-path switch: getStxBalance (current tip) and the v2 /addresses/:principal/balances/stx endpoint now read locked STX from this table — which also surfaces pox-5 locks in balance responses for the first time. Historical (until_block) reads keep the per-version event scan.

New v3 endpoints

• GET /extended/v3/principals/:principal/balances/stx — total + spendable (available) balance, a nested locked object, and projected mempool balance (mempool-aware ETag cache).
• GET /extended/v3/principals/:principal/balances/ft — fungible-token positions, sorted by balance descending, cursor-paginated.
• GET /extended/v3/principals/:principal/balances/nft — owned NFT instances, cursor-paginated by (asset_identifier, value).

Supporting indexes

• ft_balances (address, balance DESC, token) and nft_custody (recipient, asset_identifier, value) so the keyset-paginated scans are served directly from an index.

Testing

• New tests/api/pox5/stx-lock.test.ts: stake/unstake materialization, pox-4 stx_lock inheritance, reorg recompute, and balance read-path coverage.
• Extended tests/api/v3/principals.test.ts: the stx/ft/nft balance endpoints incl. cursor pagination and ETag behavior.

[codecov]

Codecov Report

❌ Patch coverage is 85.73868% with 167 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/datastore/pg-store.ts	14.68%	151 Missing ⚠️
src/datastore/helpers.ts	93.27%	8 Missing ⚠️
src/api/routes/v3/principals.ts	98.75%	2 Missing ⚠️
src/datastore/pg-write-store.ts	99.02%	2 Missing ⚠️
migrations/1779800000000_stx-locked-balances.ts	99.09%	0 Missing and 1 partial ⚠️
...1779800000001_ft-balances-address-balance-index.ts	96.00%	0 Missing and 1 partial ⚠️
...0000002_nft-custody-recipient-asset-value-index.ts	96.29%	0 Missing and 1 partial ⚠️
src/datastore/pg-store-v2.ts	96.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!