Network.Haskoin.Wallet

This package provides functions for generating hierarchical deterministic keys (BIP32). It also provides functions for building and signing both simple transactions and multisignature transactions. This package also provides a command line application called hw (haskoin wallet). It is a lightweight bitcoin wallet featuring BIP32 key management, deterministic signatures (RFC-6979) and first order support for multisignature transactions. A library API for hw is also exposed.

Extended Keys

type ChainCode = Hash256

Extended Private Keys

data XPrvKey

Data type representing an extended BIP32 private key. An extended key is a node in a tree of key derivations. It has a depth in the tree, a parent node and an index to differentiate it from other siblings.

Constructors

XPrvKey

Fields

xPrvDepth :: !Word8

Depth in the tree of key derivations.

xPrvParent :: !Word32

Fingerprint of the parent key.

xPrvIndex :: !Word32

Key derivation index.

xPrvChain :: !ChainCode

Chain code.

xPrvKey :: !PrvKey

The private key of this extended key node.

Instances

Eq XPrvKey

Show XPrvKey

Arbitrary XPrvKey

Binary XPrvKey

makeXPrvKey :: ByteString -> Maybe XPrvKey

Build a BIP32 compatible extended private key from a bytestring. This will produce a root node (depth=0 and parent=0).

xPrvIsPrime :: XPrvKey -> Bool

Returns True if the extended private key was derived through a prime derivation.

xPrvChild :: XPrvKey -> Word32

Returns the derivation index of this extended private key without the prime bit set.

xPrvID :: XPrvKey -> Hash160

Computes the key identifier of an extended private key.

xPrvFP :: XPrvKey -> Word32

Computes the key fingerprint of an extended private key.

xPrvExport :: XPrvKey -> String

Exports an extended private key to the BIP32 key export format (base 58).

xPrvImport :: String -> Maybe XPrvKey

Decodes a BIP32 encoded extended private key. This function will fail if invalid base 58 characters are detected or if the checksum fails.

xPrvWIF :: XPrvKey -> String

Export an extended private key to WIF (Wallet Import Format).

Extended Public Keys

data XPubKey

Data type representing an extended BIP32 public key.

Constructors

XPubKey

Fields

xPubDepth :: !Word8

Depth in the tree of key derivations.

xPubParent :: !Word32

Fingerprint of the parent key.

xPubIndex :: !Word32

Key derivation index.

xPubChain :: !ChainCode

Chain code.

xPubKey :: !PubKey

The public key of this extended key node.

Instances

Eq XPubKey

Show XPubKey

Arbitrary XPubKey

Binary XPubKey

deriveXPubKey :: XPrvKey -> XPubKey

Derive an extended public key from an extended private key. This function will preserve the depth, parent, index and chaincode fields of the extended private keys.

xPubIsPrime :: XPubKey -> Bool

Returns True if the extended public key was derived through a prime derivation.

xPubChild :: XPubKey -> Word32

Returns the derivation index of this extended public key without the prime bit set.

xPubID :: XPubKey -> Hash160

Computes the key identifier of an extended public key.

xPubFP :: XPubKey -> Word32

Computes the key fingerprint of an extended public key.

xPubAddr :: XPubKey -> Address

Computer the Address of an extended public key.

xPubExport :: XPubKey -> String

Exports an extended public key to the BIP32 key export format (base 58).

xPubImport :: String -> Maybe XPubKey

Decodes a BIP32 encoded extended public key. This function will fail if invalid base 58 characters are detected or if the checksum fails.

Child key derivations

prvSubKey

Arguments

:: XPrvKey

Extended parent private key

-> Word32

Child derivation index

-> Maybe XPrvKey

Extended child private key

Compute a private, non-prime child key derivation. A private non-prime derivation will allow the equivalent extended public key to derive the public key for this child. Given a parent key m and a derivation index i, this function will compute m/i/.

Non-prime derivations allow for more flexibility such as read-only wallets. However, care must be taken not the leak both the parent extended public key and one of the extended child private keys as this would compromise the extended parent private key.

pubSubKey

Arguments

:: XPubKey

Extended Parent public key

-> Word32

Child derivation index

-> Maybe XPubKey

Extended child public key

Compute a public, non-prime child key derivation. Given a parent key M and a derivation index i, this function will compute M/i/.

primeSubKey

Arguments

:: XPrvKey

Extended Parent private key

-> Word32

Child derivation index

-> Maybe XPrvKey

Extended child private key

Compute a prime child key derivation. Prime derivations can only be computed for private keys. Prime derivations do not allow the parent public key to derive the child public keys. However, they are safer as a breach of the parent public key and child private keys does not lead to a breach of the parent private key. Given a parent key m and a derivation index i, this function will compute m/i'/.

prvSubKeys :: XPrvKey -> Word32 -> [(XPrvKey, Word32)]

Cyclic list of all private non-prime child key derivations of a parent key starting from an offset index.

pubSubKeys :: XPubKey -> Word32 -> [(XPubKey, Word32)]

Cyclic list of all public non-prime child key derivations of a parent key starting from an offset index.

primeSubKeys :: XPrvKey -> Word32 -> [(XPrvKey, Word32)]

Cyclic list of all prime child key derivations of a parent key starting from an offset index.

Multisig derivations

mulSigSubKey

Arguments

:: [XPubKey]

List of extended parent public keys

-> Word32

Child key derivation index

-> Maybe [XPubKey]

List of extended child public keys

Compute a public, non-prime subkey derivation for all of the parent public keys in the input. This function will succeed only if the child key derivations for all the parent keys are valid.

This function is intended to be used in the context of multisignature accounts. Parties exchanging their master public keys to create a multisignature account can then individually generate all the receiving multisignature addresses without further communication.

mulSigSubKeys :: [XPubKey] -> Word32 -> [([XPubKey], Word32)]

Cyclic list of all public, non-prime multisig key derivations of a list of parent keys starting from an offset index.

Derivation tree interoperability

To improve BIP32 wallet interoperability, a standard derivation tree is used. All accounts are generated through prime derivations from the master key. This ensures that the master key is not compromised if an account is compromised. Every account will generate receiving addresses from the non-prime subtree index 0 and internal change addresses from the non-prime subtree index 1. MasterKey, AccountKey and AddressKey types are defined to conform to the wallet interoperability format.

type KeyIndex = Word32

Master keys

newtype MasterKey

Data type representing an extended private key at the root of the derivation tree. Master keys have depth 0 and no parents. They are represented as m/ in BIP32 notation.

Constructors

MasterKey

Fields

masterKey :: XPrvKey

Instances

Eq MasterKey

Show MasterKey

Arbitrary MasterKey

makeMasterKey :: ByteString -> Maybe MasterKey

Create a MasterKey from a seed.

loadMasterKey :: XPrvKey -> Maybe MasterKey

Load a MasterKey from an XPrvKey. This function will fail if the extended private key does not have the properties of a MasterKey.

Account keys

newtype AccPrvKey

Data type representing a private account key. Account keys are generated from a MasterKey through prime derivation. This guarantees that the MasterKey will not be compromised if the account key is compromised. AccPrvKey is represented as m/i'/ in BIP32 notation.

Constructors

AccPrvKey

Fields

getAccPrvKey :: XPrvKey

Instances

Eq AccPrvKey

Show AccPrvKey

Arbitrary AccPrvKey

newtype AccPubKey

Data type representing a public account key. It is computed through derivation from an AccPrvKey. It can not be derived from the MasterKey directly (property of prime derivation). It is represented as M/i'/ in BIP32 notation. AccPubKey is used for generating receiving payment addresses without the knowledge of the AccPrvKey.

Constructors

AccPubKey

Fields

getAccPubKey :: XPubKey

Instances

Eq AccPubKey

Show AccPubKey

Arbitrary AccPubKey

loadPrvAcc :: XPrvKey -> Maybe AccPrvKey

Load a private account key from an XPrvKey. This function will fail if the extended private key does not have the properties of a AccPrvKey.

loadPubAcc :: XPubKey -> Maybe AccPubKey

Load a public account key from an XPubKey. This function will fail if the extended public key does not have the properties of a AccPubKey.

accPrvKey :: MasterKey -> KeyIndex -> Maybe AccPrvKey

Computes an AccPrvKey from a MasterKey and a derivation index.

accPubKey :: MasterKey -> KeyIndex -> Maybe AccPubKey

Computes an AccPubKey from a MasterKey and a derivation index.

accPrvKeys :: MasterKey -> KeyIndex -> [(AccPrvKey, KeyIndex)]

Cyclic list of all valid AccPrvKey derived from a MasterKey and starting from an offset index.

accPubKeys :: MasterKey -> KeyIndex -> [(AccPubKey, KeyIndex)]

Cyclic list of all valid AccPubKey derived from a MasterKey and starting from an offset index.

Address keys

newtype AddrPrvKey

Data type representing a private address key. Private address keys are generated through a non-prime derivation from an AccPrvKey. Non-prime derivation is used so that the public account key can generate the receiving payment addresses without knowledge of the private account key. AccPrvKey is represented as m/i'/0/j/ in BIP32 notation if it is a regular receiving address. Internal (change) addresses are represented as m/i'/1/j/. Non-prime subtree 0 is used for regular receiving addresses and non-prime subtree 1 for internal (change) addresses.

Constructors

AddrPrvKey

Fields

getAddrPrvKey :: XPrvKey

Instances

Eq AddrPrvKey

Show AddrPrvKey

Arbitrary AddrPrvKey

newtype AddrPubKey

Data type representing a public address key. They are generated through non-prime derivation from an AccPubKey. This is a useful feature for read-only wallets. They are represented as M/i'/0/j in BIP32 notation for regular receiving addresses and by M/i'/1/j for internal (change) addresses.

Constructors

AddrPubKey

Fields

getAddrPubKey :: XPubKey

Instances

Eq AddrPubKey

Show AddrPubKey

Arbitrary AddrPubKey

addr :: AddrPubKey -> Address

Computes an Address from an AddrPubKey.

extPrvKey :: AccPrvKey -> KeyIndex -> Maybe AddrPrvKey

Computes an external AddrPrvKey from an AccPrvKey and a derivation index.

extPubKey :: AccPubKey -> KeyIndex -> Maybe AddrPubKey

Computes an external AddrPubKey from an AccPubKey and a derivation index.

intPrvKey :: AccPrvKey -> KeyIndex -> Maybe AddrPrvKey

Computes an internal AddrPrvKey from an AccPrvKey and a derivation index.

intPubKey :: AccPubKey -> KeyIndex -> Maybe AddrPubKey

Computes an internal AddrPubKey from an AccPubKey and a derivation index.

extPrvKeys :: AccPrvKey -> KeyIndex -> [(AddrPrvKey, KeyIndex)]

Cyclic list of all valid external AddrPrvKey derived from a AccPrvKey and starting from an offset index.

extPubKeys :: AccPubKey -> KeyIndex -> [(AddrPubKey, KeyIndex)]

Cyclic list of all valid external AddrPubKey derived from a AccPubKey and starting from an offset index.

intPrvKeys :: AccPrvKey -> KeyIndex -> [(AddrPrvKey, KeyIndex)]

Cyclic list of all internal AddrPrvKey derived from a AccPrvKey and starting from an offset index.

intPubKeys :: AccPubKey -> KeyIndex -> [(AddrPubKey, KeyIndex)]

Cyclic list of all internal AddrPubKey derived from a AccPubKey and starting from an offset index.

extAddr :: AccPubKey -> KeyIndex -> Maybe String

Computes an external base58 address from an AccPubKey and a derivation index.

intAddr :: AccPubKey -> KeyIndex -> Maybe String

Computes an internal base58 addres from an AccPubKey and a derivation index.

extAddrs :: AccPubKey -> KeyIndex -> [(String, KeyIndex)]

Cyclic list of all external base58 addresses derived from a AccPubKey and starting from an offset index.

intAddrs :: AccPubKey -> KeyIndex -> [(String, KeyIndex)]

Cyclic list of all internal base58 addresses derived from a AccPubKey and starting from an offset index.

extAddrs' :: AccPubKey -> KeyIndex -> [(String, KeyIndex)]

Same as extAddrs with the list reversed.

intAddrs' :: AccPubKey -> KeyIndex -> [(String, KeyIndex)]

Same as intAddrs with the list reversed.

Multisig address keys

extMulSigKey :: AccPubKey -> [XPubKey] -> KeyIndex -> Maybe [AddrPubKey]

Computes a list of external AddrPubKey from an AccPubKey, a list of thirdparty multisig keys and a derivation index. This is useful for computing the public keys associated with a derivation index for multisig accounts.

intMulSigKey :: AccPubKey -> [XPubKey] -> KeyIndex -> Maybe [AddrPubKey]

Computes a list of internal AddrPubKey from an AccPubKey, a list of thirdparty multisig keys and a derivation index. This is useful for computing the public keys associated with a derivation index for multisig accounts.

extMulSigKeys :: AccPubKey -> [XPubKey] -> KeyIndex -> [([AddrPubKey], KeyIndex)]

Cyclic list of all external multisignature AddrPubKey derivations starting from an offset index.

intMulSigKeys :: AccPubKey -> [XPubKey] -> KeyIndex -> [([AddrPubKey], KeyIndex)]

Cyclic list of all internal multisignature AddrPubKey derivations starting from an offset index.

extMulSigAddr :: AccPubKey -> [XPubKey] -> Int -> KeyIndex -> Maybe String

Computes an external base58 multisig address from an AccPubKey, a list of thirdparty multisig keys and a derivation index.

intMulSigAddr :: AccPubKey -> [XPubKey] -> Int -> KeyIndex -> Maybe String

Computes an internal base58 multisig address from an AccPubKey, a list of thirdparty multisig keys and a derivation index.

extMulSigAddrs :: AccPubKey -> [XPubKey] -> Int -> KeyIndex -> [(String, KeyIndex)]

Cyclic list of all external base58 multisig addresses derived from an AccPubKey and a list of thirdparty multisig keys. The list starts at an offset index.

intMulSigAddrs :: AccPubKey -> [XPubKey] -> Int -> KeyIndex -> [(String, KeyIndex)]

Cyclic list of all internal base58 multisig addresses derived from an AccPubKey and a list of thirdparty multisig keys. The list starts at an offset index.

Build Transactions

buildTx :: [OutPoint] -> [(ScriptOutput, Word64)] -> Either String Tx

Build a transaction by providing a list of outpoints as inputs and a list of ScriptOutput and amounts as outputs.

buildAddrTx :: [OutPoint] -> [(String, Word64)] -> Either String Tx

Build a transaction by providing a list of outpoints as inputs and a list of recipients addresses and amounts as outputs.

Transaction signing

data SigInput

Data type used to specify the signing parameters of a transaction input. To sign an input, the previous output script, outpoint and sighash are required. When signing a pay to script hash output, an additional redeem script is required.

Constructors

SigInput

Parameters for signing a pay to public key hash output.

Fields

sigDataOut :: Script

Output script to spend.

sigDataOP :: OutPoint

Reference to the transaction output to spend.

sigDataSH :: SigHash

Signature type.

SigInputSH

Parameters for signing a pay to script hash output.

Fields

sigDataOut :: Script

Output script to spend.

sigDataOP :: OutPoint

Reference to the transaction output to spend.

sigRedeem :: Script

Redeem script.

sigDataSH :: SigHash

Signature type.

Instances

Eq SigInput

Show SigInput

signTx

Arguments

:: Monad m

=> Tx

Transaction to sign

-> [SigInput]

SigInput signing parameters

-> [PrvKey]

List of private keys to use for signing

-> SecretT (BuildT m) Tx

Signed transaction

Sign a transaction by providing the SigInput signing parameters and a list of private keys. The signature is computed within the SecretT monad to generate the random signing nonce and within the BuildT monad to add information on wether the result was fully or partially signed.

detSignTx

Arguments

:: Tx

Transaction to sign

-> [SigInput]

SigInput signing parameters

-> [PrvKey]

List of private keys to use for signing

-> Build Tx

Signed transaction

Sign a transaction by providing the SigInput signing paramters and a list of private keys. The signature is computed deterministically as defined in RFC-6979. The signature is computed within the Build monad to add information on wether the result was fully or partially signed.

isTxComplete :: Tx -> Bool

Returns True if all the inputs of a transactions are non-empty and if all multisignature inputs are fully signed.

Coin selection

data Coin

A Coin is something that can be spent by a transaction and is represented by a transaction output, an outpoint and optionally a redeem script.

Constructors

Coin

Fields

coinTxOut :: TxOut

Transaction output

coinOutPoint :: OutPoint

Previous outpoint

coinRedeem :: Maybe Script

Redeem script

Instances

Eq Coin

Show Coin

Arbitrary Coin

chooseCoins

Arguments

:: Word64

Target price to pay.

-> Word64

Fee price per 1000 bytes.

-> [Coin]

List of coins to choose from.

-> Either String ([Coin], Word64)

Coin selection result and change amount.

Coin selection algorithm for normal (non-multisig) transactions. This function returns the selected coins together with the amount of change to send back to yourself, taking the fee into account.

chooseMSCoins

Arguments

:: Word64

Target price to pay.

-> Word64

Fee price per 1000 bytes.

-> (Int, Int)

Multisig parameters m of n (m,n).

-> [Coin]

List of coins to choose from.

-> Either String ([Coin], Word64)

Coin selection result and change amount.

Coin selection algorithm for multisignature transactions. This function returns the selected coins together with the amount of change to send back to yourself, taking the fee into account. This function assumes all the coins are script hash outputs that send funds to a multisignature address.

guessTxSize

Arguments

:: Int

Number of regular transaction inputs.

-> [(Int, Int)]

For every multisig input in the transaction, provide the multisig parameters m of n (m,n) for that input.

-> Int

Number of pay to public key hash outputs.

-> Int

Number of pay to script hash outputs.

-> Int

Upper bound on the transaction size.

Computes an upper bound on the size of a transaction based on some known properties of the transaction.