Safe Haskell	None
Language	Haskell2010

Cardano.Address.Derivation

Contents

Overview
Key Derivation
- Types
Abstractions
Low-Level Cryptography Primitives
- XPrv
- XPub
- XSignature

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
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 Source # maxBound :: Index ' Hardened depth Source #
Bounded ( Index ' Soft depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods minBound :: Index ' Soft depth Source # maxBound :: Index ' Soft depth Source #
Bounded ( Index ' WholeDomain depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods minBound :: Index ' WholeDomain depth Source # maxBound :: Index ' WholeDomain depth Source #
Eq ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods (==) :: Index derivationType depth -> Index derivationType depth -> Bool Source # (/=) :: Index derivationType depth -> Index derivationType depth -> Bool Source #
Ord ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods compare :: Index derivationType depth -> Index derivationType depth -> Ordering Source # (<) :: Index derivationType depth -> Index derivationType depth -> Bool Source # (<=) :: Index derivationType depth -> Index derivationType depth -> Bool Source # (>) :: Index derivationType depth -> Index derivationType depth -> Bool Source # (>=) :: Index derivationType depth -> Index derivationType depth -> Bool Source # max :: Index derivationType depth -> Index derivationType depth -> Index derivationType depth Source # min :: Index derivationType depth -> Index derivationType depth -> Index derivationType depth Source #
Show ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods showsPrec :: Int -> Index derivationType depth -> ShowS Source # show :: Index derivationType depth -> String Source # showList :: [ Index derivationType depth] -> ShowS Source #
Generic ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Associated Types type Rep ( Index derivationType depth) :: Type -> Type Source # Methods from :: Index derivationType depth -> Rep ( Index derivationType depth) x Source # to :: Rep ( Index derivationType depth) x -> Index derivationType depth Source #
NFData ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods rnf :: Index derivationType depth -> () Source #
Buildable ( Index derivationType depth) Source #
Instance details Defined in Cardano.Address.Derivation Methods build :: Index derivationType depth -> Builder Source #
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.11.0-D40zGSHo3QMFNy9OpWafYI" ' 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

XSignature

type XSignature = XSignature Source #

An opaque type representing a signature made from an XPrv .

Since: 1.0.0

sign :: ByteArrayAccess msg => XPrv -> msg -> XSignature Source #

Produce a signature of the given msg from an XPrv .

Since: 1.0.0

verify :: ByteArrayAccess msg => XPub -> msg -> XSignature -> Bool Source #

Verify the XSignature of a msg with the XPub associated with the XPrv used for signing.

Since: 1.0.0