Copyright	(c) 2025 Jared Tobin
License	MIT
Maintainer	Jared Tobin <jared@ppad.tech>
Safe Haskell	None
Language	Haskell2010

Crypto.HDKey.BIP32

Contents

Hierarchical deterministic keys
Extended keys
Child derivation via path
Serialization
Parsing
Child key derivation functions

Description

BIP32 hierarchical deterministic wallets and extended keys, with support for serialization and parsing.

Synopsis

data HDKey = HDKey {
- hd_key :: !(Either XPub XPrv)
- hd_depth :: !Word8
- hd_parent :: !ByteString
- hd_child :: !ByteString
}
master :: ByteString -> Maybe HDKey
class Extended k where
- identifier :: k -> ByteString
- fingerprint :: k -> ByteString
data XPub
xpub_key :: XPub -> Projective
xpub_cod :: XPub -> ByteString
data XPrv
xprv_key :: XPrv -> Integer
xprv_cod :: XPrv -> ByteString
data X a
derive :: HDKey -> ByteString -> Maybe HDKey
derive_partial :: HDKey -> ByteString -> HDKey
xpub :: HDKey -> ByteString
xprv :: HDKey -> Maybe ByteString
tpub :: HDKey -> ByteString
tprv :: HDKey -> Maybe ByteString
parse :: ByteString -> Maybe HDKey
derive_child_pub :: HDKey -> Word32 -> Maybe HDKey
derive_child_priv :: HDKey -> Word32 -> Maybe HDKey

Hierarchical deterministic keys

data HDKey Source #

A BIP32 hierarchical deterministic key.

This differs from lower-level "extended" keys in that it carries all information required for serialization.

Constructors

HDKey
Fields hd_key :: !(Either XPub XPrv) extended public or private key hd_depth :: !Word8 key depth hd_parent :: !ByteString parent fingerprint hd_child :: !ByteString index or child number

Instances

Instances details

Generic HDKey Source #

Instance details

Defined in Crypto.HDKey.BIP32

Associated Types

type Rep HDKey

Instance details

Defined in Crypto.HDKey.BIP32

type Rep HDKey = D1 ('MetaData "HDKey" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'False) (C1 ('MetaCons "HDKey" 'PrefixI 'True) ((S1 ('MetaSel ('Just "hd_key") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Either XPub XPrv)) :*: S1 ('MetaSel ('Just "hd_depth") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Word8)) :*: (S1 ('MetaSel ('Just "hd_parent") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "hd_child") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString))))

Methods

from :: HDKey -> Rep HDKey x #

to :: Rep HDKey x -> HDKey #

Show HDKey Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

showsPrec :: Int -> HDKey -> ShowS #

show :: HDKey -> String #

showList :: [HDKey] -> ShowS #

Eq HDKey Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

(==) :: HDKey -> HDKey -> Bool #

(/=) :: HDKey -> HDKey -> Bool #

Extended HDKey Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

identifier :: HDKey -> ByteString Source #

fingerprint :: HDKey -> ByteString Source #

type Rep HDKey Source #

Instance details

Defined in Crypto.HDKey.BIP32

type Rep HDKey = D1 ('MetaData "HDKey" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'False) (C1 ('MetaCons "HDKey" 'PrefixI 'True) ((S1 ('MetaSel ('Just "hd_key") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Either XPub XPrv)) :*: S1 ('MetaSel ('Just "hd_depth") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Word8)) :*: (S1 ('MetaSel ('Just "hd_parent") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "hd_child") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString))))

master :: ByteString -> Maybe HDKey Source #

Derive a master HDKey from a master seed.

Fails with Nothing if the provided seed has an invalid length.

Extended keys

class Extended k where Source #

Key types supporting identifier/fingerprint calculation.

>>> let Just hd = master "my very secret entropy"
>>> let Right my_xprv = hd_key hd
>>> let my_xpub = n k
>>> -- all have the same fingerprint
>>> fingerprint hd
"G\157\&8\146"
>>> fingerprint my_xprv
"G\157\&8\146"
>>> fingerprint my_xpub
"G\157\&8\146"

Minimal complete definition

identifier

Methods

identifier :: k -> ByteString Source #

Calculate the identifier for an extended key.

fingerprint :: k -> ByteString Source #

Calculate the fingerprint of an extended key.

Instances

Instances details

Extended HDKey Source #
Instance details Defined in Crypto.HDKey.BIP32 Methods identifier :: HDKey -> ByteString Source # fingerprint :: HDKey -> ByteString Source #
Extended XPrv Source #
Instance details Defined in Crypto.HDKey.BIP32 Methods identifier :: XPrv -> ByteString Source # fingerprint :: XPrv -> ByteString Source #
Extended XPub Source #
Instance details Defined in Crypto.HDKey.BIP32 Methods identifier :: XPub -> ByteString Source # fingerprint :: XPub -> ByteString Source #

data XPub Source #

An extended public key.

Instances

Instances details

Generic XPub Source #

Instance details

Defined in Crypto.HDKey.BIP32

Associated Types

type Rep XPub
Instance details Defined in Crypto.HDKey.BIP32 type Rep XPub = D1 ('MetaData "XPub" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'True) (C1 ('MetaCons "XPub" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (X Projective))))

Methods

from :: XPub -> Rep XPub x #

to :: Rep XPub x -> XPub #

Show XPub Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

showsPrec :: Int -> XPub -> ShowS #

show :: XPub -> String #

showList :: [XPub] -> ShowS #

Eq XPub Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

(==) :: XPub -> XPub -> Bool #

(/=) :: XPub -> XPub -> Bool #

Extended XPub Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

identifier :: XPub -> ByteString Source #

fingerprint :: XPub -> ByteString Source #

type Rep XPub Source #

Instance details

Defined in Crypto.HDKey.BIP32

type Rep XPub = D1 ('MetaData "XPub" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'True) (C1 ('MetaCons "XPub" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (X Projective))))

xpub_key :: XPub -> Projective Source #

Read the raw public key from an XPub.

xpub_cod :: XPub -> ByteString Source #

Read the raw chain code from an XPub.

data XPrv Source #

An extended private key.

Instances

Instances details

Generic XPrv Source #

Instance details

Defined in Crypto.HDKey.BIP32

Associated Types

type Rep XPrv
Instance details Defined in Crypto.HDKey.BIP32 type Rep XPrv = D1 ('MetaData "XPrv" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'True) (C1 ('MetaCons "XPrv" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (X Integer))))

Methods

from :: XPrv -> Rep XPrv x #

to :: Rep XPrv x -> XPrv #

Show XPrv Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

showsPrec :: Int -> XPrv -> ShowS #

show :: XPrv -> String #

showList :: [XPrv] -> ShowS #

Eq XPrv Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

(==) :: XPrv -> XPrv -> Bool #

(/=) :: XPrv -> XPrv -> Bool #

Extended XPrv Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

identifier :: XPrv -> ByteString Source #

fingerprint :: XPrv -> ByteString Source #

type Rep XPrv Source #

Instance details

Defined in Crypto.HDKey.BIP32

type Rep XPrv = D1 ('MetaData "XPrv" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'True) (C1 ('MetaCons "XPrv" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (X Integer))))

xprv_key :: XPrv -> Integer Source #

Read the raw private key from an XPrv.

xprv_cod :: XPrv -> ByteString Source #

Read the raw chain code from an XPrv.

data X a Source #

A public or private key, extended with a chain code.

Instances

Instances details

Generic (X a) Source #

Instance details

Defined in Crypto.HDKey.BIP32

Associated Types

type Rep (X a)

Instance details

Defined in Crypto.HDKey.BIP32

type Rep (X a) = D1 ('MetaData "X" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'False) (C1 ('MetaCons "X" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString)))

Methods

from :: X a -> Rep (X a) x #

to :: Rep (X a) x -> X a #

Show a => Show (X a) Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

showsPrec :: Int -> X a -> ShowS #

show :: X a -> String #

showList :: [X a] -> ShowS #

Eq a => Eq (X a) Source #

Instance details

Defined in Crypto.HDKey.BIP32

Methods

(==) :: X a -> X a -> Bool #

(/=) :: X a -> X a -> Bool #

type Rep (X a) Source #

Instance details

Defined in Crypto.HDKey.BIP32

type Rep (X a) = D1 ('MetaData "X" "Crypto.HDKey.BIP32" "ppad-bip32-0.2.0-D3Evs48uGWDKq6IyiQiDtl" 'False) (C1 ('MetaCons "X" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString)))

Child derivation via path

derive Source #

Arguments

:: HDKey
-> ByteString	derivation path
-> Maybe HDKey

Derive a child node via the provided derivation path.

Fails with Nothing if derivation is impossible, or if the provided path is invalid.

>>> let Just hd = master "my very secret master seed"
>>> let Just child = derive hd "m/44'/0'/0'/0/0"
>>> xpub child
"xpub6FvaeGNFmCkLky6jwefrUfyH7gCGSAUckRBANT6wLQkm4eWZApsf4LqAadtbM8EBFfuKGFgzhgta4ByP6xnBodk2EV7BiwxCPLgu13oYWGp"

derive_partial :: HDKey -> ByteString -> HDKey Source #

Derive a child node via the provided derivation path.

Fails with error if derivation is impossible, or if the provided path is invalid.

>>> let other_child = derive_partial hd "m/44'/0'/0'/0/1"
>>> xpub other_child
"xpub6FvaeGNFmCkLpkT3uahJnGPTfEX62PtH7uZAyjtru8S2FvPuYTQKn8ct6CNQAwHMXaGN6EYuwi1Tz2VD7msftH8VTAtzgNra9CForA9FBP4"

Serialization

xpub :: HDKey -> ByteString Source #

Serialize a mainnet extended public key in base58check format.

>>> let Just hd = master "my very secret entropy"
>>> xpub hd
"xpub661MyMwAqRbcGTJPtZRqZyrvjxHCfhqXeiqb5GVU3EGuFBy4QxT3yt8iiHwZTiCzZFyuyNiqXB3eqzqFZ8z4L6HCrPSkDVFNuW59LXYvMjs"

xprv :: HDKey -> Maybe ByteString Source #

Serialize a mainnet extended private key in base58check format.

>>> xprv hd
Just "xprv9s21ZrQH143K3yDvnXtqCqvCBvSiGF7gHVuzGt5rUtjvNPdusR8oS5pErywDM1jDDTcLpNNCbg9a9NuidBczRzSUp7seDeu8am64h6nfdrg"

tpub :: HDKey -> ByteString Source #

Serialize a testnet extended public key in base58check format.

>>> tpub hd
"tpubD6NzVbkrYhZ4YFVFLkQvmuCJ55Nrf6LbCMRtRpYcP92nzUdmVBJ98KoYxL2LzDAEMAWpaxEi4GshYBKrwzqJDXjVuzC3u1ucVTfZ6ZD415x"

tprv :: HDKey -> Maybe ByteString Source #

Serialize a testnet extended private key in base58check format.

>>> tprv hd
Just "tprv8ZgxMBicQKsPenTTT6kLNVYBW3rvVm9gd3q79JWJxsEQ9zNzrnUYwqBgnA6sMP7Xau97pTyxm2jNcETTkPxwF3i5Lm5wt1dBVrqV8kKi5v5"

Parsing

parse :: ByteString -> Maybe HDKey Source #

Parse a base58check-encoded ByteString into a HDKey.

Fails with Nothing if the provided key is invalid.

>>> let Just hd = master "my very secret entropy"
>>> let Just my_xprv = parse (xprv hd)
>>> my_xprv == hd
True

Child key derivation functions

derive_child_pub :: HDKey -> Word32 -> Maybe HDKey Source #

Derive a public child node at the provided index.

Fails with Nothing if derivation is impossible.

>>> :set -XNumericUnderscores
>>> let Just child_pub = derive_child_pub child_prv 0x8000_0000
>>> xpub child_pub
"xpub6B6LoU83Cpyx1UVMwuoQdQvY2BuGbPd2xsEVxCnj85UGgDN9bRz82hQhe9UFmyo4Pokuhjc8M1Cfc8ufLxcL6FkCF7Zc2eajEfWfZwMFF6X"

derive_child_priv :: HDKey -> Word32 -> Maybe HDKey Source #

Derive a private child node at the provided index.

Fails with Nothing if derivation is impossible.

>>> let Just child_prv = derive_child_priv hd 0
>>> xpub child_prv
"xpub68R2ZbtFeJTFJApdEdPqW5cy3d5wF96tTfJErhu3mTi2Ttaqvc88BMPrgS3hQSrHj91kRbzVLM9pue9f8219szRKZuTAx1LWbdLDLFDm6Ly"