#27260 Enhanced error messages for invalid network prefix during address parsing.

• Provide specific error messages when an address has an invalid network prefix
• Stop misreporting wrong-network addresses as completely invalid Bech32 or Base58

This PR refactors destination address decoding in key_io and bech32 to provide specific, network-aware error messages when parsing fails. Instead of guessing encoding based on the current network prefix and falling through to Base58, it attempts Bech32 decoding upfront and reports explicit network prefix mismatches. It also converts bech32::LocateErrors to return an error code enum and adds human-readable Base58 prefix information to chainparams.

Problem: When a valid Bech32 address for one network (such as signet) is passed to a node on another network (such as mainnet), DecodeDestination fails to recognize the prefix, falls through to the Base58 decoder, and returns a misleading generic error stating the address is neither valid Base58 nor Bech32 (issue #26290).

P3 · bug fix

• P3 because it fixes misleading error messages when RPC callers pass an address from another network
• Helps node operators debug invalid input without affecting transaction safety or correctness

Resolves issue #26290, eliminating misleading error messages when users supply valid addresses from a different chain to RPCs like validateaddress. The improvement directly benefits node operators and RPC consumers debugging invalid input, but the problem does not affect safety or correctness of valid transactions.

Membership: Alters error responses and diagnostic output for validateaddress and other RPC methods calling DecodeDestination

Factors: security/stability 0, bug 1, performance 0, user value 2, leverage 0

P3 · cleanup

• P3 because it replaces string-based error diagnostics in the bech32 helper with an error enum
• Allows callers to handle and translate decoding failures programmatically

Improves bech32 library error reporting by replacing user-facing strings in LocateErrors with an Error enum code, allowing consumers to handle and translate errors cleanly.

Membership: Modifies bech32 utility functions in src/bech32.* and address decoding helpers in src/key_io.*

Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 1

• Review is blocked because the branch has merge conflicts and needs a rebase

The PR has merge conflicts with current master and is marked as needing a rebase.

Author status: active; force-pushed updates recently and awaiting reviewer signal

Resolved concerns:

• Hardcoded prefix text vs. calculated prefix ranges was resolved in favor of adding static tables in chainparams to keep maintenance low (achow101, portlandhodl)
• Removing chain names from user-facing error strings in favor of only mentioning the expected prefix was resolved per review feedback (Sjors, luke-jr)
• Splitting Base58 and Bech32 changes into focused commits and data-driving functional tests in JSON (l0rinc, Sjors)

• Strong concept consensus on improving address error diagnostics
• Concept approval noting real-world debugging usefulness (rkrux)
• Concept approval with assistance on tests and commit structure (Sjors, l0rinc)
• Concept or approach approval without detailed rationale (jonatack, RandyMcMillan)

Strong concept consensus; review comments focus on commit structure and refactoring separation

Multiple contributors and maintainers expressed Concept ACKs and confirmed the utility of better address error diagnostics, with review focused on code organization.

• Sjors Concept ACKed and helped fix intermediate commits and test setups
• rkrux Concept ACKed and shared real-world debugging motivation
• jonatack Concept ACKed
• l0rinc Concept ACKed and requested commit splitting to separate refactors from behavior changes
• RandyMcMillan gave Approach ACK

Review verdicts (DrahtBot): 0

• Approach ACK: RandyMcMillan
• Concept ACK: Sjors, rkrux, jonatack, l0rinc

603 lines under test/bench/ci.

• src/key_io.cpp +154/-103
• test/functional/data/rpc_validateaddress.json +245/-0
• test/functional/rpc_validateaddress.py +28/-176
• src/test/bech32_tests.cpp +38/-38
• src/test/key_io_tests.cpp +37/-3
• test/functional/rpc_invalid_address_message.py +20/-16
• src/kernel/chainparams.cpp +30/-0
• src/bech32.cpp +14/-13
• src/bech32.h +20/-2
• src/kernel/chainparams.h +3/-0
• test/functional/wallet_basic.py +1/-1

PR 27260 improves address parsing error messages by decoding Bech32 upfront rather than guessing the encoding by network prefix, preventing valid Bech32 addresses on other networks from falling through to generic Base58 check failures. It also converts bech32::LocateErrors to return a typed error code enum instead of formatted text, letting callers format user-facing messages consistently. This resolves long-standing confusion in validateaddress and address-handling RPCs when testing against different network types. Concept support is strong with multiple maintainers backing the change, though review iterations have centered on commit structure. The PR currently requires a rebase to resolve merge conflicts with master.