Copyright	2020 Input Output (Hong Kong) Ltd. 2021-2022 Input Output Global Inc. (IOG) 2023-2025 Intersect
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Cardano.Address.Derivation

Contents

Overview
Key Derivation
- Types
Abstractions
Low-Level Cryptography Primitives

Description

Synopsis

data Index (derivationType :: DerivationType) (depth :: Depth)
indexToWord32 :: Index derivationType depth -> Word32
indexFromWord32 :: forall ix (derivationType :: DerivationType) (depth :: Depth). (ix ~ Index derivationType depth, Bounded ix) => Word32 -> Maybe ix
wholeDomainIndex :: forall (depth :: Depth). Word32 -> Index 'WholeDomain depth
coerceWholeDomainIndex :: forall (ty :: DerivationType) (depth0 :: Depth) (depth1 :: Depth). Index ty depth0 -> Index 'WholeDomain depth1
nextIndex :: forall ix (derivationType :: DerivationType) (depth :: Depth). (ix ~ Index derivationType depth, Bounded ix) => ix -> Maybe ix
data Depth
- = RootK
- | AccountK
- | PaymentK
- | DelegationK
- | DRepK
- | CCColdK
- | CCHotK
- | ScriptK
- | PolicyK
data DerivationType
- = Hardened
- | Soft
- | WholeDomain
class GenMasterKey (key :: Depth -> Type -> Type) where
- type SecondFactor (key :: Depth -> Type -> Type)
- genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor key -> key 'RootK XPrv
- genMasterKeyFromXPrv :: XPrv -> key 'RootK XPrv
class HardDerivation (key :: Depth -> Type -> Type) where
- type AccountIndexDerivationType (key :: Depth -> Type -> Type) :: DerivationType
- type AddressIndexDerivationType (key :: Depth -> Type -> Type) :: DerivationType
- type WithRole (key :: Depth -> Type -> Type)
- deriveAccountPrivateKey :: key 'RootK XPrv -> Index (AccountIndexDerivationType key) 'AccountK -> key 'AccountK XPrv
- deriveAddressPrivateKey :: key 'AccountK XPrv -> WithRole key -> Index (AddressIndexDerivationType key) 'PaymentK -> key 'PaymentK XPrv
class HardDerivation key => SoftDerivation (key :: Depth -> Type -> Type) where
- deriveAddressPublicKey :: key 'AccountK XPub -> WithRole key -> Index 'Soft 'PaymentK -> key 'PaymentK XPub
type XPrv = XPrv
xprvFromBytes :: ByteString -> Maybe XPrv
xprvToBytes :: XPrv -> ByteString
xprvPrivateKey :: XPrv -> ByteString
xprvChainCode :: XPrv -> ByteString
toXPub :: HasCallStack => XPrv -> XPub
type XPub = XPub
xpubFromBytes :: ByteString -> Maybe XPub
xpubToBytes :: XPub -> ByteString
xpubPublicKey :: XPub -> ByteString
xpubChainCode :: XPub -> ByteString
data Pub
pubFromBytes :: ByteString -> Maybe Pub
pubToBytes :: Pub -> ByteString
xpubToPub :: XPub -> Pub
type XSignature = XSignature
sign :: ByteArrayAccess msg => XPrv -> msg -> XSignature
verify :: ByteArrayAccess msg => XPub -> msg -> XSignature -> Bool

Overview

These abstractions allow generating root private key, also called Master Key and then basing on it enable address derivation

Key Derivation

Types

data Index (derivationType :: DerivationType) (depth :: Depth) #

A derivation index, with phantom-types to disambiguate derivation type.

let accountIx = Index 'Hardened 'AccountK
let addressIx = Index 'Soft 'PaymentK

Since: 1.0.0

Instances

Instances details

NFData (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

rnf :: Index derivationType depth -> () #

Buildable (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

build :: Index derivationType depth -> Builder #

Bounded (Index 'Hardened depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

minBound :: Index 'Hardened depth #

maxBound :: Index 'Hardened depth #

Bounded (Index 'Soft depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

minBound :: Index 'Soft depth #

maxBound :: Index 'Soft depth #

Bounded (Index 'WholeDomain depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

minBound :: Index 'WholeDomain depth #

maxBound :: Index 'WholeDomain depth #

Generic (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Associated Types

type Rep (Index derivationType depth)
Instance details Defined in Cardano.Address.Derivation type Rep (Index derivationType depth) = D1 ('MetaData "Index" "Cardano.Address.Derivation" "cardano-addresses-4.0.2-inplace" 'True) (C1 ('MetaCons "Index" 'PrefixI 'True) (S1 ('MetaSel ('Just "indexToWord32") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word32)))

Methods

from :: Index derivationType depth -> Rep (Index derivationType depth) x #

to :: Rep (Index derivationType depth) x -> Index derivationType depth #

Show (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

showsPrec :: Int -> Index derivationType depth -> ShowS #

show :: Index derivationType depth -> String #

showList :: [Index derivationType depth] -> ShowS #

Eq (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

(==) :: Index derivationType depth -> Index derivationType depth -> Bool #

(/=) :: Index derivationType depth -> Index derivationType depth -> Bool #

Ord (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

Methods

compare :: Index derivationType depth -> Index derivationType depth -> Ordering #

(<) :: Index derivationType depth -> Index derivationType depth -> Bool #

(<=) :: Index derivationType depth -> Index derivationType depth -> Bool #

(>) :: Index derivationType depth -> Index derivationType depth -> Bool #

(>=) :: Index derivationType depth -> Index derivationType depth -> Bool #

max :: Index derivationType depth -> Index derivationType depth -> Index derivationType depth #

min :: Index derivationType depth -> Index derivationType depth -> Index derivationType depth #

type Rep (Index derivationType depth) #

Instance details

Defined in Cardano.Address.Derivation

type Rep (Index derivationType depth) = D1 ('MetaData "Index" "Cardano.Address.Derivation" "cardano-addresses-4.0.2-inplace" 'True) (C1 ('MetaCons "Index" 'PrefixI 'True) (S1 ('MetaSel ('Just "indexToWord32") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word32)))

indexToWord32 :: Index derivationType depth -> Word32 #

Get the index as a Word32 @since 3.3.0

indexFromWord32 :: forall ix (derivationType :: DerivationType) (depth :: Depth). (ix ~ Index derivationType depth, Bounded ix) => Word32 -> Maybe ix #

Construct derivation path indices from raw Word32 values.

wholeDomainIndex :: forall (depth :: Depth). Word32 -> Index 'WholeDomain depth #

Constructs a full domain Index. This can't fail, unlike fromWord32.

Since: 3.3.0

coerceWholeDomainIndex :: forall (ty :: DerivationType) (depth0 :: Depth) (depth1 :: Depth). Index ty depth0 -> Index 'WholeDomain depth1 #

Upcasts an Index to one with the full Word32 domain.

Since: 3.3.0

nextIndex :: forall ix (derivationType :: DerivationType) (depth :: Depth). (ix ~ Index derivationType depth, Bounded ix) => ix -> Maybe ix #

Increment an index, if possible.

Since: 3.3.0

data Depth #

Key Depth in the derivation path, according to BIP-0039 and BIP-0044.

root | purpose' | cointype' | account' | role | address
0th      1st         2nd        3rd       4th     5th

We do not manipulate purpose, cointype and change paths directly, so there are no constructors for these.

Since: 1.0.0

Constructors

RootK
AccountK
PaymentK
DelegationK
DRepK
CCColdK
CCHotK
ScriptK
PolicyK

data DerivationType #

Type of derivation that should be used with the given indexes.

In theory, we should only consider two derivation types: soft and hard.

However, historically, addresses in Cardano used to be generated across both the soft and the hard domain. We therefore introduce a WholeDomain derivation type that is the exact union of Hardened and Soft.

Since: 1.0.0

Constructors

Hardened
Soft
WholeDomain

Abstractions

class GenMasterKey (key :: Depth -> Type -> Type) where #

Abstract interface for constructing a Master Key.

Since: 1.0.0

Associated Types

type SecondFactor (key :: Depth -> Type -> Type) #

Methods

genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor key -> key 'RootK XPrv #

Generate a root key from a corresponding mnemonic.

Since: 1.0.0

genMasterKeyFromXPrv :: XPrv -> key 'RootK XPrv #

Generate a root key from a corresponding root XPrv

Since: 1.0.0

Instances

Instances details

GenMasterKey Byron #

Key Derivation

Example:

Generating a root key from `SomeMnemonic`

>>> :set -XOverloadedStrings
>>> :set -XTypeApplications
>>> :set -XDataKinds
>>> :set -XFlexibleContexts
>>> import Cardano.Mnemonic ( mkSomeMnemonic )
>>> import Cardano.Address ( base58 )
>>> import Cardano.Address.Derivation ( toXPub )
>>> import qualified Cardano.Address.Style.Byron as Byron

>>> let (Right mw) = mkSomeMnemonic @'[12] ["moon","fox","ostrich","quick","cactus","raven","wasp","intact","first","ring","crumble","error"]
>>> let rootK = Byron.genMasterKeyFromMnemonic mw :: Byron 'RootK XPrv

Deriving child keys

Both accIx and addIx assume values from 0 to 4294967295 (ie. 0xFFFFFFFF) In case of account one can get this bound via

let accIxMin = minBound (Index 'WholeDomain 'AccountK)
let accIxMax = maxBound (Index 'WholeDomain 'AccountK)

>>> let Just accIx = wholeDomainIndex 0x80000000
>>> let acctK = Byron.deriveAccountPrivateKey rootK accIx

>>> let Just addIx = wholeDomainIndex 0x80000014
>>> let addrK = Byron.deriveAddressPrivateKey acctK addIx

>>> base58 $ Byron.paymentAddress Byron.byronMainnet (toXPub $ addrK)
DdzFFzCqrhsq3KjLtT51mESbZ4RepiHPzLqEhamexVFTJpGbCXmh7qSxnHvaL88QmtVTD1E1sjx8Z1ZNDhYmcBV38ZjDST9kYVxSkhcw

Instance details

Defined in Cardano.Address.Style.Byron

Associated Types

type SecondFactor Byron
Instance details Defined in Cardano.Address.Style.Byron type SecondFactor Byron = ()

Methods

genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Byron -> Byron 'RootK XPrv #

genMasterKeyFromXPrv :: XPrv -> Byron 'RootK XPrv #

GenMasterKey Icarus #

Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type SecondFactor Icarus
Instance details Defined in Cardano.Address.Style.Icarus type SecondFactor Icarus = ScrubbedBytes

Methods

genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Icarus -> Icarus 'RootK XPrv #

genMasterKeyFromXPrv :: XPrv -> Icarus 'RootK XPrv #

GenMasterKey Shared #

Instance details

Defined in Cardano.Address.Style.Shared

Associated Types

type SecondFactor Shared
Instance details Defined in Cardano.Address.Style.Shared type SecondFactor Shared = ScrubbedBytes

Methods

genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Shared -> Shared 'RootK XPrv #

genMasterKeyFromXPrv :: XPrv -> Shared 'RootK XPrv #

GenMasterKey Shelley #

Instance details

Defined in Cardano.Address.Style.Shelley

Associated Types

type SecondFactor Shelley
Instance details Defined in Cardano.Address.Style.Shelley type SecondFactor Shelley = ScrubbedBytes

Methods

genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Shelley -> Shelley 'RootK XPrv #

genMasterKeyFromXPrv :: XPrv -> Shelley 'RootK XPrv #

class HardDerivation (key :: Depth -> Type -> Type) where #

An interface for doing hard derivations from the root private key, Master Key

Since: 1.0.0

Associated Types

type AccountIndexDerivationType (key :: Depth -> Type -> Type) :: DerivationType #

type AddressIndexDerivationType (key :: Depth -> Type -> Type) :: DerivationType #

type WithRole (key :: Depth -> Type -> Type) #

Methods

deriveAccountPrivateKey :: key 'RootK XPrv -> Index (AccountIndexDerivationType key) 'AccountK -> key 'AccountK XPrv #

Derives account private key from the given root private key, using derivation scheme 2 (see cardano-crypto package for more details).

Since: 1.0.0

deriveAddressPrivateKey :: key 'AccountK XPrv -> WithRole key -> Index (AddressIndexDerivationType key) 'PaymentK -> key 'PaymentK XPrv #

Derives address private key from the given account private key, using derivation scheme 2 (see cardano-crypto package for more details).

Since: 1.0.0

Instances

Instances details

HardDerivation Byron #

Instance details

Defined in Cardano.Address.Style.Byron

Associated Types

type AccountIndexDerivationType Byron
Instance details Defined in Cardano.Address.Style.Byron type AccountIndexDerivationType Byron = 'WholeDomain
type AddressIndexDerivationType Byron
Instance details Defined in Cardano.Address.Style.Byron type AddressIndexDerivationType Byron = 'WholeDomain
type WithRole Byron
Instance details Defined in Cardano.Address.Style.Byron type WithRole Byron = ()

Methods

deriveAccountPrivateKey :: Byron 'RootK XPrv -> Index (AccountIndexDerivationType Byron) 'AccountK -> Byron 'AccountK XPrv #

deriveAddressPrivateKey :: Byron 'AccountK XPrv -> WithRole Byron -> Index (AddressIndexDerivationType Byron) 'PaymentK -> Byron 'PaymentK XPrv #

HardDerivation Icarus #

Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type AccountIndexDerivationType Icarus
Instance details Defined in Cardano.Address.Style.Icarus type AccountIndexDerivationType Icarus = 'Hardened
type AddressIndexDerivationType Icarus
Instance details Defined in Cardano.Address.Style.Icarus type AddressIndexDerivationType Icarus = 'Soft
type WithRole Icarus
Instance details Defined in Cardano.Address.Style.Icarus type WithRole Icarus = Role

Methods

deriveAccountPrivateKey :: Icarus 'RootK XPrv -> Index (AccountIndexDerivationType Icarus) 'AccountK -> Icarus 'AccountK XPrv #

deriveAddressPrivateKey :: Icarus 'AccountK XPrv -> WithRole Icarus -> Index (AddressIndexDerivationType Icarus) 'PaymentK -> Icarus 'PaymentK XPrv #

HardDerivation Shared #

Instance details

Defined in Cardano.Address.Style.Shared

Associated Types

type AccountIndexDerivationType Shared
Instance details Defined in Cardano.Address.Style.Shared type AccountIndexDerivationType Shared = 'Hardened
type AddressIndexDerivationType Shared
Instance details Defined in Cardano.Address.Style.Shared type AddressIndexDerivationType Shared = 'Soft
type WithRole Shared
Instance details Defined in Cardano.Address.Style.Shared type WithRole Shared = Role

Methods

deriveAccountPrivateKey :: Shared 'RootK XPrv -> Index (AccountIndexDerivationType Shared) 'AccountK -> Shared 'AccountK XPrv #

deriveAddressPrivateKey :: Shared 'AccountK XPrv -> WithRole Shared -> Index (AddressIndexDerivationType Shared) 'PaymentK -> Shared 'PaymentK XPrv #

HardDerivation Shelley #

Instance details

Defined in Cardano.Address.Style.Shelley

Associated Types

type AccountIndexDerivationType Shelley
Instance details Defined in Cardano.Address.Style.Shelley type AccountIndexDerivationType Shelley = 'Hardened
type AddressIndexDerivationType Shelley
Instance details Defined in Cardano.Address.Style.Shelley type AddressIndexDerivationType Shelley = 'Soft
type WithRole Shelley
Instance details Defined in Cardano.Address.Style.Shelley type WithRole Shelley = Role

Methods

deriveAccountPrivateKey :: Shelley 'RootK XPrv -> Index (AccountIndexDerivationType Shelley) 'AccountK -> Shelley 'AccountK XPrv #

deriveAddressPrivateKey :: Shelley 'AccountK XPrv -> WithRole Shelley -> Index (AddressIndexDerivationType Shelley) 'PaymentK -> Shelley 'PaymentK XPrv #

class HardDerivation key => SoftDerivation (key :: Depth -> Type -> Type) where #

An interface for doing soft derivations from an account public key

Methods

deriveAddressPublicKey :: key 'AccountK XPub -> WithRole key -> Index 'Soft 'PaymentK -> key 'PaymentK XPub #

Derives address public key from the given account public key, using derivation scheme 2 (see cardano-crypto package for more details).

This is the preferred way of deriving new sequential address public keys.

Since: 1.0.0

Instances

Instances details

SoftDerivation Icarus #
Instance details Defined in Cardano.Address.Style.Icarus Methods deriveAddressPublicKey :: Icarus 'AccountK XPub -> WithRole Icarus -> Index 'Soft 'PaymentK -> Icarus 'PaymentK XPub #
SoftDerivation Shared #
Instance details Defined in Cardano.Address.Style.Shared Methods deriveAddressPublicKey :: Shared 'AccountK XPub -> WithRole Shared -> Index 'Soft 'PaymentK -> Shared 'PaymentK XPub #
SoftDerivation Shelley #
Instance details Defined in Cardano.Address.Style.Shelley Methods deriveAddressPublicKey :: Shelley 'AccountK XPub -> WithRole Shelley -> Index 'Soft 'PaymentK -> Shelley 'PaymentK XPub #

Low-Level Cryptography Primitives

XPrv

type XPrv = XPrv #

An opaque type representing an extended private key.

Properties:

Roundtripping

forall xprv. xprvFromBytes (xprvToBytes xprv) == Just xprv

Chain Code Invariance

forall xprv. xprvChainCode xprv == xpubChainCode (toXPub xprv)

Public Key Signature

forall xprv msg. verify (toXPub xprv) msg (sign xprv msg) == True

Since: 1.0.0

xprvFromBytes :: ByteString -> Maybe XPrv #

Construct an XPrv from raw ByteString (96 bytes).

Since: 1.0.0

xprvToBytes :: XPrv -> ByteString #

Convert an XPrv to a raw ByteString (96 bytes).

Since: 1.0.0

xprvPrivateKey :: XPrv -> ByteString #

Extract the private key from an XPrv as a raw ByteString (64 bytes).

Since: 2.0.0

xprvChainCode :: XPrv -> ByteString #

Extract the chain code from an XPrv as a raw ByteString (32 bytes).

Since: 2.0.0

toXPub :: HasCallStack => XPrv -> XPub #

Derive the XPub associated with an XPrv.

Since: 1.0.0

XPub

type XPub = XPub #

An opaque type representing an extended public key.

Properties:

Roundtripping

forall xpub. xpubFromBytes (xpubToBytes xpub) == Just xpub

Since: 1.0.0

xpubFromBytes :: ByteString -> Maybe XPub #

Construct an XPub from raw ByteString (64 bytes).

Since: 1.0.0

xpubToBytes :: XPub -> ByteString #

Convert an XPub to a raw ByteString (64 bytes).

Since: 1.0.0

xpubPublicKey :: XPub -> ByteString #

Extract the public key from an XPub as a raw ByteString (32 bytes).

Since: 2.0.0

xpubChainCode :: XPub -> ByteString #

Extract the chain code from an XPub as a raw ByteString (32 bytes).

Since: 2.0.0

Pub

data Pub #

An opaque type representing a non-extended public key.

Properties:

Roundtripping

forall pub. pubFromBytes (pubToBytes pub) == Just pub

Since: 3.12.0

Instances

Instances details

Show Pub #
Instance details Defined in Cardano.Address.Derivation Methods showsPrec :: Int -> Pub -> ShowS # show :: Pub -> String # showList :: [Pub] -> ShowS #
Eq Pub #
Instance details Defined in Cardano.Address.Derivation Methods (==) :: Pub -> Pub -> Bool # (/=) :: Pub -> Pub -> Bool #