Repository navigation
go-mhda v1.2.0
The reference implementation and specification of MHDA 1.2. The C++ port, censync/mhda v1.2.0, is a behavioral mirror: the two give byte-identical results, checked with shared conformance tables and a differential run over 500 000 mutated URNs and 600 000 derivation paths.
URNs and values accepted by 1.1 are refused now: see Changed. Code that
builds addresses gets stricter constructors and setters, and
Chain.SetNetworkType / Chain.SetChainId return an error.
Changed
- A derivation-path level index of 2^31 or more is refused with
ErrInvalidDerivationPath, at every level of every derivation type
(bip32,bip44,bip49,bip54,bip74,bip84,bip86,cip11,
cip1852,zip32,slip10), hardened or not. 1.1 accepted any value up
to 2^32-1. A BIP-32 child number keeps the hardened flag in its top bit
(n'is child number 2^31+n), so such an index aliased another key: a
consumer computinghardened ? 0x80000000 | index : indexderives the key
ofm/44'/60'/0'/0/0form/44'/60'/2147483648'/0/0, and an unhardened
m/44'/60'/0'/0/2147483648asks for a hardened child number through the
public-key formula. No longer parse: anydpwith a level of
2147483648to4294967295, with or without a hardened marker, e.g.
urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/2147483648'/0/0and
urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/4294967295. The largest
index is2147483647. Thectcomponent is not a path level and keeps
its 32-bit range. - Leading zeros in a path level are unchanged and now documented: accepted
in a variable level and dropped in canonical output (060'is60'),
refused in a fixed level (the purpose, the fixed coin ofcip11,
cip1852andzip32, the0/1charge ofbip32and the BIP-44
family). - Programmatic values are validated like parsed input. The network
type, the chain id and the derivation type are written verbatim into
every URN, and nothing checked them when set in code: a chain id
1:dt:bip44:dp:m/44'/60'/0'/0/666on a root address produced a URN that
re-parsed as a bip44 path.NewChainnow requires a registered network
type and a non-empty chain id of printable ASCII without:,?or#
(ASCII-trimmed) and panics otherwise, likeNewAddress.
Chain.SetNetworkTypeandChain.SetChainIdreturn an error
(ErrInvalidNetworkType,ErrMissingChainID,ErrInvalidValue) and
leave the chain unchanged; they returned nothing before.
NewDerivationPathandNewDerivationPathFromLevelspanic with
ErrInvalidDerivationTypeon an unregistered type. AnAddresswhose
path has no type serialises like a root address instead of emitting
emptydt/dpcomponents. - A derivation path without a derivation type, or under
dt:root, is
refused withErrInvalidDerivationPath. Both used to be dropped
silently:urn:mhda:nt:evm:ci:1:dp:m/44'/60'/0'/0/0and
urn:mhda:nt:evm:ci:1:dt:root:dp:m/0parsed as the root address
urn:mhda:nt:evm:ci:1, naming the root key instead of the path they
spell out.Address.SetDerivationPathon a root address accepts only an
empty path. - The NSS is parsed strictly as
key:valuepairs. An unknown key was
skipped as a single token, so its value was read as the next key and a
key with the wrong case vanished:...:ci:1:DT:bip44:DP:m/44'/60'/0'/0/5
parsed as the root addressurn:mhda:nt:evm:ci:1, and
...:ci:1:ext:wi:dt:bip44:...readdtas the wallet id. An unknown
component is now skipped together with its value; a key that differs from
a known key only by case, a dangling token, a trailing:and an empty
key are refused withErrInvalidNSS.ChainFromKeyreports a dangling
token asErrInvalidChainKey, as before. ParseNSS,ChainFromNSSandChainFromKeyrefuse?and#with
ErrInvalidNSS.ParseURNstrips the RFC 8141 r/q/f components before
parsing, but an NSS given on its own kept the byte in a value:
ParseNSS("nt:evm:ci:1?=q:dt:bip44:dp:m/44'/60'/0'/0/0")returned a bip44
address whose URN re-parsed as the root addressurn:mhda:nt:evm:ci:1,
andChainFromKey("nt:evm:ci:1#a")was accepted.FuzzParseNSSnow
checks that the emitted URN re-parses to itself.- A
slip10path has at most 255 levels; a deeper one is refused with
ErrInvalidDerivationPath. BIP-32 serialises a key's depth in one byte,
so no wallet can represent a deeper key. - Strict validation refuses curve, purpose and format combinations no
wallet can derive. It checked the algorithm, the format and the
derivation type each on its own, so it accepted SLIP-10 ed25519 paths
with soft levels (nt:solana:...:dp:m/44'/501'/0/0; ed25519 has no soft
derivation),bip44with ed25519 on XRPL, NEAR and Aptos, Suibip54
with ed25519 or secp256r1, a Bitcoinbip84path withaf:p2pkh, and
Cosmosbip44with coin118', which is thecip11path again.
ParseURNStrict/Validatenow returnErrIncompatiblefor: an
ed25519 path with an unhardened level (exceptcip1852, which is
BIP32-Ed25519); a derivation type with another curve than its own on Sui
(slip10ed25519,bip54secp256k1,bip74secp256r1), Aptos and NEAR
(slip10ed25519,bip44secp256k1); an explicit Bitcoin format that
does not match the purpose (bip44p2pkh,bip49p2sh,bip84p2wpkh
or bech32,bip86p2tr or bech32m); and Cosmosbip44with coin
118'. A Bitcoin URN withoutafstays valid; SPEC.md no longer claims
strict mode requires it. Lenient parsing is unchanged. - No whitespace inside the NSS. Each value was trimmed, so
urn:mhda:nt:evm:ci: 1 :dt: bip44 :...parsed like the URN without the
spaces, against SPEC §6.1. ASCII whitespace is now trimmed only around the
whole URN, around an NSS or chain key parsed on its own, and before a
stripped r/q/f component (ci:0 #fragstill parses); around a key or
value it is refused withErrInvalidNSS. - NSS bytes follow RFC 3986. Keys and values accepted any printable
ASCII, so",<,>,\,^,`,{,|,},[,]and a
raw%passed and were emitted in URNs that RFC 8141 does not allow. A
key or value is now made of letters, digits and-._~!$&'()*+,;=@/
only (RFC 3986 pchar and/, without:and%); anything else is
ErrInvalidNSSwhen parsed andErrInvalidValuefrom the setters and
NewChain.%is refused because percent-encoding is not supported and
%41would be a second spelling ofA.
Fixed
ChargeTypeis 32 bits wide (wasuint8). The CIP-11 charge and the
CIP-1852 role accept any level index, but the parsed value was truncated
to a byte:m/1852'/1815'/0'/256/0parsed as role 0, so it named the
role-0 key, re-serialised asm/1852'/1815'/0'/0/0, andLevels()
returned the truncated value. The full value is now kept inCharge(),
Levels()andString(). Code that convertsCharge()touint8must
widen its own variable.- No stale or mixed derivation state.
ParsePathupdated the fields
of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level
one kept the old index (m/32'/133'/1'read back asm/32'/133'/1'/5),
a SLIP-10 path kept the coin, account and charge of a BIP-44 path parsed
before it, and an error midway left a half-updated path.
SetDerivationTypechanged the type and kept the old path, so a bip44
address switched to zip32 serialised asdt:zip32:dp:m/32'/133'/3'/9, a
valid URN naming a key nobody gave.ParsePathnow replaces the whole
path or nothing. A new derivation type drops the old path; until a path
is set the URN carriesdtwithoutdp(and does not parse), and
Validate/MarshalTextreturnErrInvalidDerivationPath. The new
Address.SetDerivation(dt, dp)sets both at once and changes nothing on
error; the URN parser uses it. Levels()andString()cannot disagree.NewDerivationPathFromLevels
kept any levels it was given whileString()printed the type's
template: a BIP-44 path built from49'/60'/0/0/0printed
m/44'/60'/0'/0/0but returned purpose 49' and an unhardened account from
Levels(), and too few levels or an index of 2^31 produced a URN that
does not parse. Both constructors now return exactly the path the parser
gives back forString(), and panic withErrInvalidDerivationPath
otherwise.Levels()returned the internal slice, so a caller that
changed it changed the path; it returns a copy.NewAddressstored the
caller's chain and path, so two addresses built from them changed
together; it keeps copies.- No nil dereference on a zero or partial
Address.String(),
NSS(), the hashes,Algorithm()andFormat()panicked on the zero
Addressor one built with a nil chain, andSetDerivationPathpanicked
on an address built without a path. They now treat a missing chain as the
zero chain (urn:mhda:nt::ci:, as the C++ port's default address) and a
missing path as root;SetCoinTypewithout a chain returns
ErrUninitializedAddress. - An
Addressheld by value encodes as its URN.MarshalTexthad a
pointer receiver, so anAddressstruct field or map value was encoded
byencoding/jsonandencoding/xmlas an empty object ({"A":{}}),
which then failed to decode.MarshalTextnow has a value receiver. A
nil*Addressis still encoded by the codec (asnull); calling
MarshalTextdirectly on a nil pointer now panics like any value method
instead of returningErrUninitializedAddress. - The lookup helpers wrap their sentinels.
AlgorithmFromString,
FormatFromStringandNetworkTypeFromStringreturned plain
errors.Newvalues, soerrors.Iscould not tell them apart, unlike
DerivationTypeFromStringand the parsers. They now wrap
ErrInvalidAlgorithm,ErrInvalidFormatandErrInvalidNetworkType. - Setters and lookup helpers normalise ASCII only. They trimmed with
strings.TrimSpaceand lowercased withstrings.ToLower, which are
Unicode-aware:SetAddressAlgorithm("secp256\u212a1")(Kelvin sign)
was accepted assecp256k1, and NBSP or ideographic spaces around a
derivation type, path, format or coin type were trimmed, while the URN
parser and the C++ port refuse the same bytes. They now trim ASCII
whitespace and fold ASCII case only.
Documentation
- SPEC.md states that an explicit
dt:rootis folded away (root is the
default and has no path, so a root address has one canonical form and
one hash); the Algorand and TON notes no longer calldt:rootthe
canonical form. It also lists ZIP-32 as a known limitation:zip32
parses, but no network registers it, so strict parsing refuses it. Both
behaviours are unchanged and now pinned by tests. - SPEC.md notes that an EVM chain id is opaque:
ci:1,ci:0x1and
ci:01are three chain keys for one chain, and a producer must keep to
one spelling.
Testing
go vet, gofmt andgo test -raceclean on Go 1.18, 1.20, 1.21 and the current stable release.- Fuzz targets for URNs, NSS strings and derivation paths ran with new invariants: the URN emitted from a parsed NSS re-parses to itself,
Levels()survives a round trip, and no accepted level index reaches 2^31. testdata/dp_conformance.txtandtestdata/urn_conformance.txtare shared verbatim with the C++ port.