From 2cd46b125e068ac71cf6f1638f231aed741e2650 Mon Sep 17 00:00:00 2001 From: ccamel Date: Thu, 20 Mar 2025 17:02:09 +0100 Subject: [PATCH] docs(logic): clarify bech32_address/2 predicate limitations (HD derivation) --- docs/predicate/bech32_address_2.md | 22 +++++++++++++++--- x/logic/predicate/address.go | 37 ++++++++++++++++++++++++------ 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/predicate/bech32_address_2.md b/docs/predicate/bech32_address_2.md index 49dcb0a3..5e462f65 100644 --- a/docs/predicate/bech32_address_2.md +++ b/docs/predicate/bech32_address_2.md @@ -7,7 +7,9 @@ sidebar_position: 9 ## Description -`bech32_address/2` 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. +`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'\), and Base64Bytes is a list of integers \(0\-255\) representing the Base64\-encoded bytes git statof 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]() ## Examples diff --git a/x/logic/predicate/address.go b/x/logic/predicate/address.go index a63e6c1f..4ca48405 100644 --- a/x/logic/predicate/address.go +++ b/x/logic/predicate/address.go @@ -8,8 +8,12 @@ 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 // @@ -17,12 +21,31 @@ import ( // 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'), and Base64Bytes is a list of integers (0-255) representing the Base64-encoded bytes git statof 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)