cardano-addresses-3.12.0: Library utilities for mnemonic generation and address derivation.
Copyright© 2018-2020 IOHK
LicenseApache-2.0
Safe HaskellNone
LanguageHaskell2010

Cardano.Address.Style.Icarus

Description

 
Synopsis

Documentation

This module provides an implementation of:

  • GenMasterKey: for generating Icarus master keys from mnemonic sentences
  • HardDerivation: for hierarchical hard derivation of parent to child keys
  • SoftDerivation: for hierarchical soft derivation of parent to child keys
  • PaymentAddress: for constructing addresses from a public key

We call Icarus addresses the new format of Cardano addresses which came after Byron. This is the format initially used in Yoroi and now also used by Daedalus.

Icarus

data Icarus (depth :: Depth) key Source #

A cryptographic key for sequential-scheme address derivation, with phantom-types to disambiguate key types.

let rootPrivateKey = Icarus 'RootK XPrv
let accountPubKey  = Icarus 'AccountK XPub
let addressPubKey  = Icarus 'PaymentK XPub

Since: 1.0.0

Instances

Instances details
GenMasterKey Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type SecondFactor Icarus Source #

SoftDerivation Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

HardDerivation Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

HasNetworkDiscriminant Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type NetworkDiscriminant Icarus Source #

PaymentAddress Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Functor (Icarus depth) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Methods

fmap :: (a -> b) -> Icarus depth a -> Icarus depth b #

(<$) :: a -> Icarus depth b -> Icarus depth a #

Eq key => Eq (Icarus depth key) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Methods

(==) :: Icarus depth key -> Icarus depth key -> Bool #

(/=) :: Icarus depth key -> Icarus depth key -> Bool #

Show key => Show (Icarus depth key) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Methods

showsPrec :: Int -> Icarus depth key -> ShowS #

show :: Icarus depth key -> String #

showList :: [Icarus depth key] -> ShowS #

Generic (Icarus depth key) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type Rep (Icarus depth key) :: Type -> Type #

Methods

from :: Icarus depth key -> Rep (Icarus depth key) x #

to :: Rep (Icarus depth key) x -> Icarus depth key #

NFData key => NFData (Icarus depth key) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Methods

rnf :: Icarus depth key -> () #

type SecondFactor Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type SecondFactor Icarus = ScrubbedBytes
type AccountIndexDerivationType Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type AddressIndexDerivationType Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type WithRole Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type NetworkDiscriminant Icarus Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type Rep (Icarus depth key) Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type Rep (Icarus depth key) = D1 ('MetaData "Icarus" "Cardano.Address.Style.Icarus" "cardano-addresses-3.12.0-CXdZXYlvM2IBJZenPvTIY5" 'True) (C1 ('MetaCons "Icarus" 'PrefixI 'True) (S1 ('MetaSel ('Just "getKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 key)))

getKey :: Icarus depth key -> key Source #

Extract the raw XPrv or XPub wrapped by this type.

Since: 1.0.0

Key Derivation

Generating a root key from SomeMnemonic

:set -XOverloadedStrings
:set -XTypeApplications
:set -XDataKinds
import Cardano.Mnemonic ( mkSomeMnemonic )

let (Right mw) = mkSomeMnemonic @'[15] ["network","empty","cause","mean","expire","private","finger","accident","session","problem","absurd","banner","stage","void","what"]
let sndFactor = mempty -- Or alternatively, a second factor mnemonic transformed to bytes via someMnemonicToBytes
let rootK = genMasterKeyFromMnemonic mw sndFactor :: Icarus 'RootK XPrv

Deriving child keys

Let's consider the following 3rd, 4th and 5th derivation paths 0'/0/14

let Just accIx = indexFromWord32 0x80000000
let acctK = deriveAccountPrivateKey rootK accIx

let Just addIx = indexFromWord32 0x00000014
let addrK = deriveAddressPrivateKey acctK UTxOExternal addIx

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

Generate a root key from a corresponding root XPrv

Since: 1.0.0

genMasterKeyFromMnemonic Source #

Arguments

:: SomeMnemonic

Some valid mnemonic sentence.

-> ScrubbedBytes

An optional second-factor passphrase (or mempty)

-> Icarus 'RootK XPrv 

Generate a root key from a corresponding mnemonic.

Since: 1.0.0

deriveAccountPrivateKey :: Icarus 'RootK XPrv -> Index 'Hardened 'AccountK -> Icarus 'AccountK XPrv Source #

Derives an account private key from the given root private key.

Since: 1.0.0

deriveAddressPrivateKey :: Icarus 'AccountK XPrv -> Role -> Index 'Soft 'PaymentK -> Icarus 'PaymentK XPrv Source #

Derives an address private key from the given account private key.

Since: 1.0.0

deriveAddressPublicKey :: Icarus 'AccountK XPub -> Role -> Index 'Soft 'PaymentK -> Icarus 'PaymentK XPub Source #

Derives an address public key from the given account public key.

Since: 1.0.0

Addresses

Generating a PaymentAddress

import Cardano.Address ( bech32 )
import Cardano.Address.Derivation ( toXPub(..) )

bech32 $ paymentAddress icarusMainnet (toXPub <$> addrK)
"addr1vxpfffuj3zkp5g7ct6h4va89caxx9ayq2gvkyfvww48sdncxsce5t"

data AddressInfo Source #

The result of eitherInspectAddress for Icarus addresses.

Since: 3.4.0

Instances

Instances details
Eq AddressInfo Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Show AddressInfo Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Generic AddressInfo Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type Rep AddressInfo :: Type -> Type #

ToJSON AddressInfo Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Methods

toJSON :: AddressInfo -> Value

toEncoding :: AddressInfo -> Encoding

toJSONList :: [AddressInfo] -> Value

toEncodingList :: [AddressInfo] -> Encoding

type Rep AddressInfo Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type Rep AddressInfo = D1 ('MetaData "AddressInfo" "Cardano.Address.Style.Icarus" "cardano-addresses-3.12.0-CXdZXYlvM2IBJZenPvTIY5" 'False) (C1 ('MetaCons "AddressInfo" 'PrefixI 'True) (S1 ('MetaSel ('Just "infoAddressRoot") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "infoNetworkTag") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Maybe NetworkTag))))

eitherInspectAddress :: Address -> Either ErrInspectAddress AddressInfo Source #

Determines whether an Address is an Icarus address.

Returns either details about the Address, or ErrInspectAddress if it's not a valid icarus address.

Since: 3.4.0

inspectAddress :: MonadThrow m => Address -> m Value Source #

Determines whether an Address is an Icarus address.

Returns a JSON object with information about the address, or throws ErrInspectAddress if the address isn't an icarus address.

Since: 2.0.0

paymentAddress :: NetworkDiscriminant Icarus -> Icarus 'PaymentK XPub -> Address Source #

Convert a public key to a payment Address valid for the given network discrimination.

Since: 1.0.0

data ErrInspectAddress Source #

Possible errors from inspecting a Shelley address

Since: 3.0.0

Instances

Instances details
Eq ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Show ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Generic ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

Associated Types

type Rep ErrInspectAddress :: Type -> Type #

Exception ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

ToJSON ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type Rep ErrInspectAddress Source # 
Instance details

Defined in Cardano.Address.Style.Icarus

type Rep ErrInspectAddress = D1 ('MetaData "ErrInspectAddress" "Cardano.Address.Style.Icarus" "cardano-addresses-3.12.0-CXdZXYlvM2IBJZenPvTIY5" 'False) (C1 ('MetaCons "UnexpectedDerivationPath" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DeserialiseError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 DeserialiseFailure)))

Network Discrimination

Unsafe

liftXPrv :: XPrv -> Icarus depth XPrv Source #

Unsafe backdoor for constructing an Icarus key from a raw XPrv. this is unsafe because it lets the caller choose the actually derivation depth.

This can be useful however when serializing / deserializing such a type, or to speed up test code (and avoid having to do needless derivations from a master key down to an address key for instance).

Since: 1.0.0

liftXPub :: XPub -> Icarus depth XPub Source #

Unsafe backdoor for constructing an Icarus key from a raw XPub. this is unsafe because it lets the caller choose the actually derivation depth.

This can be useful however when serializing / deserializing such a type, or to speed up test code (and avoid having to do needless derivations from a master key down to an address key for instance).

Since: 2.0.0