Skip to content

Add the BSQ SegWit derivation path - #87

Closed
hiciefte wants to merge 3 commits into
mainfrom
content/bsq-derivation-list
Closed

hiciefte wants to merge 3 commits into
mainfrom
content/bsq-derivation-list

Conversation

@hiciefte

Copy link
Copy Markdown
Collaborator

Addresses migration note wallet-derivation-template-incomplete ("The historical BSQ derivation list is incomplete") for Backing up your wallet seed, Restoring your wallet from seed and Wallet.

Where the list is

The list is not in the article text. Each article has one {{Wallet derivation paths}} / {{Wallet_derivation_paths}} call, rendered at build time from archived template 261 (revision 2003, 6 January 2021, public/wiki-source/archive-templates/261.wiki.txt). It gives BTC SegWit m/44'/0'/1', BTC legacy m/44'/0'/0' and only one BSQ path, m/44'/142'/0'.

The template and its rendering are hash-locked historical sources, so the correction is one paragraph placed directly after the template in each article. The template block, including its "Historical template from the 14 October 2026 archive" line, stays as it is.

Commits

  1. Format the wallet-seed backup source for review (formatting only). backing-up-your-wallet-seed.md was still one source line. Its 15 
 entities become line breaks, recorded in migration/source-formatting.json like the other formatting records (95 on main, 96 here). The rendered page differs from main only in writing a newline as \n instead of 
. The other two articles were already formatted.
  2. Add the BSQ SegWit derivation path (wording, one added paragraph in each of three articles).
  3. Name the BSQ script type and warn against spending BSQ elsewhere (wording, from review): the same paragraph, made more precise.

Wording change

Added after the template placement in all three articles (in Wallet, before the "Watch keys" line):

In Bisq 1 v1.10.11, the BSQ path above is not the only one: BSQ native SegWit (P2WPKH) addresses use m/44'/142'/1', and m/44'/142'/0' is the legacy BSQ path. That version creates new wallets with SegWit keychains and adds them to older legacy wallets, so these paths are not a complete recipe for restoring a Bisq wallet in other software. Other wallets show BSQ as ordinary bitcoin, and spending it there will probably lose the BSQ.

Why the review changed it: both SegWit paths use purpose 44' with native P2WPKH scripts, which other wallets will not infer from the path (BIP84 would use 84'); the template renders as paragraphs, so "this list" could attach to the wrong list in Wallet; and in Restoring the paragraph sits under "Restoring to a non-Bisq wallet", where a reader who imports the BSQ path elsewhere sees an ordinary BTC balance. The last sentence follows Bisq's own Wallet info warning.

Nothing is removed. The template's own warning against sending BSQ to a non-Bisq wallet still appears directly above.

Sources

At Bisq commit ea9d5dff90c99ac462f2b0a7bf9ef92683956619 (tag v1.10.11):

  • BisqKeyChainGroupStructure.java L32-L77: BTC m/44'/0'/0' (legacy) and m/44'/0'/1' (SegWit); BSQ m/44'/142'/0' (legacy) and m/44'/142'/1' (SegWit); P2WPKH maps to the SegWit path.
  • WalletConfig.java L429-L450: new BTC and BSQ wallets, and wallets restored from seed in Bisq, are built with P2WPKH as the preferred output type; unencrypted wallets are migrated on load (L429).
  • WalletConfig.java L566-L610: if a wallet's active keychain is the legacy path, Bisq backs up the wallet file and adds and activates a SegWit keychain, for the BTC and the BSQ wallet.
  • WalletsManager.java L145-L149: the same step for encrypted wallets, after the password is entered.
  • Bisq's Wallet info screen warns: "NEVER send BSQ from a non-Bisq wallet, as it will probably lead to an invalid BSQ transaction and losing your BSQ" (core/src/main/resources/i18n/displayStrings.properties).

What was checked and what was not

  • Checked: the source lines above. The three pages were built and the paragraph checked in the built HTML.
  • Not done: no wallet was created, upgraded or restored, in Bisq or in other software. The paths are given as the code defines them, not as a tested external-wallet restore.
  • Not settled: whether a wallet created by v1.10.11 also contains a legacy keychain. Bisq requests a P2PKH address for the arbitrator entry on a fresh BTC wallet (AddressEntryList.java L139-L142), which suggests it does, but the bitcoinj fork's builder was not read. The paragraph does not say "only", so it holds either way.

Overlap

Expected check results

  • Commit 1: npm test 37/37 pass; DOCS_SITE=https://hiciefte.github.io DOCS_BASE=/bisq-docs/ npm run build passes.
  • Commits 2 and 3 (wording): npm test 37/37 pass. The restoration gate fails as intended, with four findings:
    • src/content/docs/wiki/backing-up-your-wallet-seed.md: formatted source file drift
    • src/content/docs/wiki/restoring-your-wallet-from-seed.md: formatted source file drift
    • src/content/docs/wiki/wallet.md: formatted source file drift
    • migration/restoration-fidelity.json: expected 130 contextual image occurrences (128 !== 130). This one follows from the first two: the image count skips articles whose check failed, and two of the edited articles have one image each. Add current seed-restore safeguards #8 shows the same pattern (129 !== 130).
      Running the remaining build steps directly (template, section, link and category checks, browse indexes, astro build, check-site.mjs) passes: 601 pages. The original hashes were not refreshed.

claude and others added 3 commits November 10, 2026 09:24
Decode the 15 newline entities in the one-line Backing up your wallet
seed source so its paragraphs and the template placement can be reviewed
separately. The rendered page is unchanged apart from entity spelling.

Record the offsets in source-formatting.json so the fidelity check
rebuilds the exact original bytes. Original hashes are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcbFo7FxLxPktLKLFLLxae
The archived Wallet derivation paths template, rendered in three wallet
articles, lists only m/44'/142'/0' for BSQ. Add one sentence after each
placement giving the BSQ SegWit path m/44'/142'/1' and saying that the
list is not a complete recipe for restoring a Bisq wallet in other
software. The template and its receipts stay unchanged.

Sources: Bisq 1 v1.10.11 BisqKeyChainGroupStructure.java L32-L74 (BTC
and BSQ legacy and SegWit paths), WalletConfig.java L434-L450 (new
wallets use SegWit) and L566-L605 (legacy wallets gain a SegWit
keychain), commit ea9d5dff.

Keep original source and review snapshots unchanged. Leave publication
blocked pending support review and explicit acceptance of these edits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcbFo7FxLxPktLKLFLLxae
Both SegWit paths use purpose 44' with native P2WPKH scripts, which other
wallets will not infer from the path. Say so, refer to "the paths above"
because the template renders as paragraphs, not a list, and add the warning
Bisq's own Wallet info screen gives: other wallets show BSQ as ordinary
bitcoin, and spending it there will probably lose the BSQ.
@coderabbitai

coderabbitai Bot commented Nov 10, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d268d590-4303-4b1d-a8b8-111726426b43
Commits

Reviewing files that changed from the base of the PR and between 574168b and 11330d5.

Files selected for processing: 4

  • migration/source-formatting.json
  • src/content/docs/wiki/backing-up-your-wallet-seed.md
  • src/content/docs/wiki/restoring-your-wallet-from-seed.md
  • src/content/docs/wiki/wallet.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@hiciefte

Copy link
Copy Markdown
Collaborator Author

Automated note: moved to #99, opened from a fork with the same changes and corrected commit authorship. Please continue the review there.

@hiciefte hiciefte closed this Nov 10, 2026
@hiciefte
hiciefte deleted the content/bsq-derivation-list branch November 10, 2026 10:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants