docs(logic): clarify bech32_address/2 predicate limitations (HD derivation)

Author: ccamel

docs/predicate/bech32_address_2.md

@@ -7,7 +7,9 @@ sidebar_position: 9
 
 ## Description
 
-`bech32_address/2` is a predicate that convert a [bech32](<https://docs.cosmos.network/main/build/spec/addresses/bech32#hrp-table>) encoded string into [base64](<https://fr.wikipedia.org/wiki/Base64>) bytes and give the address prefix, or convert a prefix \(HRP\) and [base64](<https://fr.wikipedia.org/wiki/Base64>) encoded bytes to [bech32](<https://docs.cosmos.network/main/build/spec/addresses/bech32#hrp-table>) encoded string.
+`bech32_address/2` is a predicate that converts a Bech32\-encoded string into a prefix \(HRP\) and Base64\-encoded bytes, or constructs a Bech32\-encoded string from a prefix and Base64 bytes.
+
+This predicate handles Bech32 address encoding and decoding as per the Cosmos specification. In the Cosmos ecosystem, most chains \(e.g., Cosmos Hub, Akash\) share the BIP\-44 coin type 118', allowing HRP conversion \(e.g., 'cosmos' to 'akash'\) to produce valid addresses from the same underlying key.
 
 ## Signature
 
@@ -18,8 +20,22 @@ bech32_address(+Address, -Bech32) is det
 
 where:
 
-- Address is a pair of the HRP \(Human\-Readable Part\) which holds the address prefix and a list of numbers ranging from 0 to 255 that represent the base64 encoded bech32 address string.
-- Bech32 is an Atom or string representing the bech32 encoded string address
+- Address: A pair \`HRP\-Base64Bytes\`, where: HRP is an atom representing the Human\-Readable Part \(e.g., 'cosmos', 'akash', 'axone', 'bitsong'\), and Base64Bytes is a list of integers \(0\-255\) representing the Base64\-encoded bytes of the address.
+- Bech32: An atom or string representing the Bech32\-encoded address \(e.g., 'cosmos17sc02mcgjzdv5l4jwnzffxw7g60y5ta4pggcp4'\).
+
+## Limitations
+
+Conversion between HRPs is only valid for chains sharing the same BIP\-44 coin type \(e.g., 118'\). For chains with distinct coin types \(e.g., Secret: 529', Bitsong: 639'\), this predicate cannot derive the correct address from another chain’s Bech32 string.
+
+## References
+
+- [Bech32 on Cosmos](<https://docs.cosmos.network/main/build/spec/addresses/bech32>)
+
+- [Base64 Encoding](<https://fr.wikipedia.org/wiki/Base64>)
+
+- [Cosmos Chain Registry](<https://github.com/cosmos/chain-registry>)
+
+- [BIP 44](<https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki>)
 
 ## Examples
 

x/logic/predicate/address.go

@@ -8,21 +8,44 @@ import (
 	"github.com/axone-protocol/axoned/v11/x/logic/prolog"
 )
 
-// Bech32Address is a predicate that convert a [bech32] encoded string into [base64] bytes and give the address prefix,
-// or convert a prefix (HRP) and [base64] encoded bytes to [bech32] encoded string.
+// Bech32Address is a predicate that converts a Bech32-encoded string into a prefix (HRP) and Base64-encoded bytes,
+// or constructs a Bech32-encoded string from a prefix and Base64 bytes.
+//
+// This predicate handles Bech32 address encoding and decoding as per the Cosmos specification. In the Cosmos ecosystem,
+// most chains (e.g., Cosmos Hub, Akash) share the BIP-44 coin type 118', allowing HRP conversion (e.g., 'cosmos' to 'akash')
+// to produce valid addresses from the same underlying key.
 //
 // # Signature
 //
 //	bech32_address(-Address, +Bech32) is det
 //	bech32_address(+Address, -Bech32) is det
 //
 // where:
-//   - Address is a pair of the HRP (Human-Readable Part) which holds the address prefix and a list of numbers
-//     ranging from 0 to 255 that represent the base64 encoded bech32 address string.
-//   - Bech32 is an Atom or string representing the bech32 encoded string address
 //
-// [bech32]: https://docs.cosmos.network/main/build/spec/addresses/bech32#hrp-table
-// [base64]: https://fr.wikipedia.org/wiki/Base64
+//   - Address: A pair `HRP-Base64Bytes`, where: HRP is an atom representing the Human-Readable Part (e.g., 'cosmos', 'akash', 'axone', 'bitsong'),
+//     and Base64Bytes is a list of integers (0-255) representing the Base64-encoded bytes of the address.
+//   - Bech32: An atom or string representing the Bech32-encoded address (e.g., 'cosmos17sc02mcgjzdv5l4jwnzffxw7g60y5ta4pggcp4').
+//
+// # Limitations
+//
+// Conversion between HRPs is only valid for chains sharing the same BIP-44 coin type (e.g., 118'). For chains with
+// distinct coin types (e.g., Secret: 529', Bitsong: 639'), this predicate cannot derive the correct address from another
+// chain’s Bech32 string.
+//
+// # References
+//
+//   - [Bech32 on Cosmos]
+//
+//   - [Base64 Encoding]
+//
+//   - [Cosmos Chain Registry]
+//
+//   - [BIP 44]
+//
+// [Bech32 on Cosmos]: https://docs.cosmos.network/main/build/spec/addresses/bech32
+// [Base64 Encoding]: https://fr.wikipedia.org/wiki/Base64
+// [Cosmos Chain Registry]: https://github.com/cosmos/chain-registry
+// [BIP 44]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
 func Bech32Address(_ *engine.VM, address, bech32 engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	forwardConverter := func(value []engine.Term, _ engine.Term, env *engine.Env) ([]engine.Term, error) {
 		hrpTerm, dataTerm, err := prolog.AssertPair(value[0], env)