Safe Haskell	None
Language	Haskell2010

Cardano.Address.Derivation

Contents

Overview
Key Derivation
- Types
Abstractions
Low-Level Cryptography Primitives

Synopsis

data Index (derivationType :: DerivationType) (depth :: Depth)
indexToWord32 :: Index derivationType depth -> Word32
indexFromWord32 :: forall ix derivationType depth. (ix ~ Index derivationType depth, Bounded ix) => Word32 -> Maybe ix
wholeDomainIndex :: Word32 -> Index 'WholeDomain depth
coerceWholeDomainIndex :: Index ty depth0 -> Index 'WholeDomain depth1
nextIndex :: forall ix derivationType depth. (ix ~ Index derivationType depth, Bounded ix) => ix -> Maybe ix
data Depth
- = RootK
- | AccountK
- | PaymentK
- | DelegationK
- | ScriptK
- | PolicyK
data DerivationType
- = Hardened
- | Soft
- | WholeDomain
class GenMasterKey (key :: Depth -> Type -> Type) where
- type SecondFactor key :: Type
- genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor key -> key 'RootK XPrv
- genMasterKeyFromXPrv :: XPrv -> key 'RootK XPrv
class HardDerivation (key :: Depth -> Type -> Type) where
- type AccountIndexDerivationType key :: DerivationType
- type AddressIndexDerivationType key :: DerivationType
- type WithRole key :: 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) Source #

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

Bounded (Index 'Hardened depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods minBound :: Index 'Hardened depth # maxBound :: Index 'Hardened depth #
Bounded (Index 'Soft depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods minBound :: Index 'Soft depth # maxBound :: Index 'Soft depth #
Bounded (Index 'WholeDomain depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods minBound :: Index 'WholeDomain depth # maxBound :: Index 'WholeDomain depth #
Eq (Index derivationType depth) Source #
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) Source #
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 #
Show (Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods showsPrec :: Int -> Index derivationType depth -> ShowS # show :: Index derivationType depth -> String # showList :: [Index derivationType depth] -> ShowS #
Generic (Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Associated Types type Rep (Index derivationType depth) :: Type -> Type # Methods from :: Index derivationType depth -> Rep (Index derivationType depth) x # to :: Rep (Index derivationType depth) x -> Index derivationType depth #
NFData (Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods rnf :: Index derivationType depth -> () #
Buildable (Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods build :: Index derivationType depth -> Builder
type Rep (Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation type Rep (Index derivationType depth) = D1 ('MetaData "Index" "Cardano.Address.Derivation" "cardano-addresses-3.12.0-CXdZXYlvM2IBJZenPvTIY5" 'True) (C1 ('MetaCons "Index" 'PrefixI 'True) (S1 ('MetaSel ('Just "indexToWord32") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word32)))

indexToWord32 :: Index derivationType depth -> Word32 Source #

Get the index as a Word32 @since 3.3.0

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

Construct derivation path indices from raw Word32 values.

wholeDomainIndex :: Word32 -> Index 'WholeDomain depth Source #

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

Since: 3.3.0

coerceWholeDomainIndex :: Index ty depth0 -> Index 'WholeDomain depth1 Source #

Upcasts an Index to one with the full Word32 domain.

Since: 3.3.0

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

Increment an index, if possible.

Since: 3.3.0

data Depth Source #

Key Depth in the derivation path, according to BIP-0039 / 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
ScriptK
PolicyK

data DerivationType Source #

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 Source #

Abstract interface for constructing a Master Key.

Since: 1.0.0

Associated Types

type SecondFactor key :: Type Source #

Methods

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

Generate a root key from a corresponding mnemonic.

Since: 1.0.0

genMasterKeyFromXPrv :: XPrv -> key 'RootK XPrv Source #

Generate a root key from a corresponding root XPrv

Since: 1.0.0

Instances

Instances details

GenMasterKey Byron Source #
Instance details Defined in Cardano.Address.Style.Byron Associated Types type SecondFactor Byron Source # Methods genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Byron -> Byron 'RootK XPrv Source # genMasterKeyFromXPrv :: XPrv -> Byron 'RootK XPrv Source #
GenMasterKey Icarus Source #
Instance details Defined in Cardano.Address.Style.Icarus Associated Types type SecondFactor Icarus Source # Methods genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Icarus -> Icarus 'RootK XPrv Source # genMasterKeyFromXPrv :: XPrv -> Icarus 'RootK XPrv Source #
GenMasterKey Shelley Source #
Instance details Defined in Cardano.Address.Style.Shelley Associated Types type SecondFactor Shelley Source # Methods genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Shelley -> Shelley 'RootK XPrv Source # genMasterKeyFromXPrv :: XPrv -> Shelley 'RootK XPrv Source #
GenMasterKey Shared Source #
Instance details Defined in Cardano.Address.Style.Shared Associated Types type SecondFactor Shared Source # Methods genMasterKeyFromMnemonic :: SomeMnemonic -> SecondFactor Shared -> Shared 'RootK XPrv Source # genMasterKeyFromXPrv :: XPrv -> Shared 'RootK XPrv Source #

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

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

Since: 1.0.0

Associated Types

type AccountIndexDerivationType key :: DerivationType Source #

type AddressIndexDerivationType key :: DerivationType Source #

type WithRole key :: Type Source #

Methods

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

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 Source #

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 Source #
Instance details Defined in Cardano.Address.Style.Byron Associated Types type AccountIndexDerivationType Byron :: DerivationType Source # type AddressIndexDerivationType Byron :: DerivationType Source # type WithRole Byron Source # Methods deriveAccountPrivateKey :: Byron 'RootK XPrv -> Index (AccountIndexDerivationType Byron) 'AccountK -> Byron 'AccountK XPrv Source # deriveAddressPrivateKey :: Byron 'AccountK XPrv -> WithRole Byron -> Index (AddressIndexDerivationType Byron) 'PaymentK -> Byron 'PaymentK XPrv Source #
HardDerivation Icarus Source #
Instance details Defined in Cardano.Address.Style.Icarus Associated Types type AccountIndexDerivationType Icarus :: DerivationType Source # type AddressIndexDerivationType Icarus :: DerivationType Source # type WithRole Icarus Source # Methods deriveAccountPrivateKey :: Icarus 'RootK XPrv -> Index (AccountIndexDerivationType Icarus) 'AccountK -> Icarus 'AccountK XPrv Source # deriveAddressPrivateKey :: Icarus 'AccountK XPrv -> WithRole Icarus -> Index (AddressIndexDerivationType Icarus) 'PaymentK -> Icarus 'PaymentK XPrv Source #
HardDerivation Shelley Source #
Instance details Defined in Cardano.Address.Style.Shelley Associated Types type AccountIndexDerivationType Shelley :: DerivationType Source # type AddressIndexDerivationType Shelley :: DerivationType Source # type WithRole Shelley Source # Methods deriveAccountPrivateKey :: Shelley 'RootK XPrv -> Index (AccountIndexDerivationType Shelley) 'AccountK -> Shelley 'AccountK XPrv Source # deriveAddressPrivateKey :: Shelley 'AccountK XPrv -> WithRole Shelley -> Index (AddressIndexDerivationType Shelley) 'PaymentK -> Shelley 'PaymentK XPrv Source #
HardDerivation Shared Source #
Instance details Defined in Cardano.Address.Style.Shared Associated Types type AccountIndexDerivationType Shared :: DerivationType Source # type AddressIndexDerivationType Shared :: DerivationType Source # type WithRole Shared Source # Methods deriveAccountPrivateKey :: Shared 'RootK XPrv -> Index (AccountIndexDerivationType Shared) 'AccountK -> Shared 'AccountK XPrv Source # deriveAddressPrivateKey :: Shared 'AccountK XPrv -> WithRole Shared -> Index (AddressIndexDerivationType Shared) 'PaymentK -> Shared 'PaymentK XPrv Source #

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

An interface for doing soft derivations from an account public key

Methods

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

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 Source #
Instance details Defined in Cardano.Address.Style.Icarus Methods deriveAddressPublicKey :: Icarus 'AccountK XPub -> WithRole Icarus -> Index 'Soft 'PaymentK -> Icarus 'PaymentK XPub Source #
SoftDerivation Shelley Source #
Instance details Defined in Cardano.Address.Style.Shelley Methods deriveAddressPublicKey :: Shelley 'AccountK XPub -> WithRole Shelley -> Index 'Soft 'PaymentK -> Shelley 'PaymentK XPub Source #
SoftDerivation Shared Source #
Instance details Defined in Cardano.Address.Style.Shared Methods deriveAddressPublicKey :: Shared 'AccountK XPub -> WithRole Shared -> Index 'Soft 'PaymentK -> Shared 'PaymentK XPub Source #

Low-Level Cryptography Primitives

XPrv

type XPrv = XPrv Source #

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 Source #

Construct an XPrv from raw ByteString (96 bytes).

Since: 1.0.0

xprvToBytes :: XPrv -> ByteString Source #

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

Since: 1.0.0

xprvPrivateKey :: XPrv -> ByteString Source #

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

Since: 2.0.0

xprvChainCode :: XPrv -> ByteString Source #

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

Since: 2.0.0

toXPub :: HasCallStack => XPrv -> XPub Source #

Derive the XPub associated with an XPrv.

Since: 1.0.0

XPub

type XPub = XPub Source #

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 Source #

Construct an XPub from raw ByteString (64 bytes).

Since: 1.0.0

xpubToBytes :: XPub -> ByteString Source #

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

Since: 1.0.0

xpubPublicKey :: XPub -> ByteString Source #

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

Since: 2.0.0

xpubChainCode :: XPub -> ByteString Source #

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

Since: 2.0.0

Pub

data Pub Source #

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

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