feat: capture bond registration BTC/sBTC lockup data

[rafa-stacks]

Description

The @stacks/codec register-for-bond event now carries BTC/sBTC lockup provenance (btc_lockup), describing how a participant locked the BTC backing their bond registration — either a proven Bitcoin L1 lockup (with a list of proven outputs) or an sBTC ("l2") lockup. This PR captures that data end-to-end and exposes it through the bond registration endpoints.

Motivation: the codec upgrade added btc_lockup to the register-for-bond event; without ingesting it we lose the lockup type and the proven L1 outputs.

What changed:

1. Codec bump to the pox5 release that includes btc_lockup on the register-for-bond event.
2. Ingestion + storage (bond_registrations):
   • Added btc_lockup_type (a smallint backed by the new DbBondLockupType enum — L1 = 0, L2 = 1, mirroring DbTxTypeId / DbPrincipalBondPositionStatus) and btc_lockup_txs (jsonb, the proven L1 outputs; null for sBTC).
   • Removed the now-redundant is_l1_lock column (fully encoded by btc_lockup_type).
   • Reorg-safe automatically: the data rides the bond_registrations row whose canonical flag is already flipped during reorgs.
3. API schema split for registrations:
   • GET /staking/bonds/:index/registrations (list) returns a lightweight summary (signer, staker, type, balances) — no per-lockup transaction details.
   • GET /staking/bonds/:index/registrations/:principal (detail) returns the full registration as a union: an l1_lockup variant (transactions: [{ tx_id, output_index }]) or an l2_lockup variant (tx_id).
4. Tests updated to the new shapes, including an L1-lockup case asserting the proven outputs round-trip.

Impact on app developers: the registration list response is now a summary (lockup type only); the per-principal endpoint carries the lockup details. is_l1_lock is replaced by btc_lockup.type / the type field.

Type of Change

• New feature
• Bug fix
• API reference/documentation update
• Other

Does this introduce a breaking change?

This targets the unreleased pox5 branch. Within that line it reshapes the bond registration responses (summary vs detail) and removes is_l1_lock in favor of btc_lockup.type.

Are documentation updates required?

• Link to documentation updates:

Testing information

1. Testing is covered by the simulated tests/api/pox5/bonds.test.ts suite (block ingestion via TestBlockBuilder → API assertions).
2. Not a bug fix.
3. Affected code paths: pox-5 register-for-bond ingestion (pg-write-store), bond_registrations schema/migration, bond registration read methods + serializers + API schemas.
4. Run: npm run test:api:pox5 (bonds suite: 17/17 passing).
5. Watch out for: the btc_lockup_txs jsonb column is returned as a string by the pg driver and is parsed on read; the list endpoint must still select the cursor columns for pagination.

Checklist

• Code is commented where needed
• Unit test coverage for new or modified code paths
• npm run test passes (pox5 api suite)
• Changelog is updated

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.93478% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/datastore/v3/helpers.ts	68.75%	5 Missing ⚠️
src/datastore/v3/pg-store-v3.ts	80.00%	3 Missing ⚠️
src/datastore/common.ts	91.66%	2 Missing ⚠️
src/datastore/pg-write-store.ts	71.42%	2 Missing ⚠️
src/api/serializers/v3/bonds.ts	97.72%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!