feat: include BIP44 derivation path on utxo xpub addresses

[kaladinlight]

Summary

• Add optional path field to the UTXO Address model exposing the BIP44 derivation path (e.g. m/84'/0'/0'/0/3) for xpub-derived addresses
• Populate path from the upstream Blockbook token.path when building the address list in the UTXO service

Test plan

• Query an xpub account on a UTXO coinstack and verify each derived address includes path
• Query a single address (non-xpub) and verify path is omitted

Summary by CodeRabbit

• New Features
  • Address records now optionally include a BIP44 derivation path for xpub-derived addresses.
  • This path is returned in API responses and address lists for supported chains (e.g., Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Zcash), allowing clients to show or use address derivation details when available.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: db27855f-ca14-409f-af2a-bbc5bc54553a

📥 Commits

Reviewing files that changed from the base of the PR and between 498a6f3 and a3ef65a.

📒 Files selected for processing (7)

• node/coinstacks/bitcoin/api/src/swagger.json
• node/coinstacks/bitcoincash/api/src/swagger.json
• node/coinstacks/common/api/src/utxo/models.ts
• node/coinstacks/common/api/src/utxo/service.ts
• node/coinstacks/dogecoin/api/src/swagger.json
• node/coinstacks/litecoin/api/src/swagger.json
• node/coinstacks/zcash/api/src/swagger.json

✅ Files skipped from review due to trivial changes (1)

• node/coinstacks/litecoin/api/src/swagger.json

---

📝 Walkthrough

Walkthrough

The UTXO Address interface now has an optional path field (BIP44 derivation path for xpub-derived addresses). Service.getAccount includes path: token.path on each derived address. Coin-specific OpenAPI components.schemas.Address entries were updated to add the optional path string with descriptive text.

Changes

BIP44 Derivation Path Field

Layer / File(s)	Summary
Address contract, service population, and API schemas node/coinstacks/common/api/src/utxo/models.ts, node/coinstacks/common/api/src/utxo/service.ts, node/coinstacks/bitcoin/api/src/swagger.json, node/coinstacks/bitcoincash/api/src/swagger.json, node/coinstacks/dogecoin/api/src/swagger.json, node/coinstacks/litecoin/api/src/swagger.json, node/coinstacks/zcash/api/src/swagger.json	Adds an optional path?: string JSDoc field to the UTXO Address interface, updates Service.getAccount to set path from token.path when building addresses, and adds an optional path string property with a BIP44 description to each coin's OpenAPI Address schema.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I nibble code where paths unwind,
Each address now keeps its line,
From token roots the path I trace,
BIP44 leads each little place,
Hopping home with tidy grace.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: include BIP44 derivation path on utxo xpub addresses' directly and accurately describes the main change: adding an optional path field to expose BIP44 derivation paths for UTXO addresses derived from xpubs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/utxo-address-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}