BSV.ExtKey (BSV v2.1.0) View Source

An ExtKey is a data structure representing a Bitcoin extended key.

An extended key is a private or public key that you can derive new keys from in a hierarchical deterministic wallet. This implements BIP-32.

A master extended key is usually created by passing a BSV.Mnemonic.seed/0 to from_seed/2. From there, child keys can be derived by passing a BSV.ExtKey.derivation_path/0 to derive/2.

Extended private keys can be converted to extended public keys. Using a common derivation path, an extended public key can derive the same child public key corresponding to the child private key derived from the corresponding parent extended private key.

Extended keys can be serialised using to_string/1, to make the key easier to store or share.

Link to this section Summary

Types

Derivation path

t()

Extended key struct

Serialised extended private key (xprv)

Serialised extended public key (xpub)

Functions

Derives a new BSV.ExtKey.t/0 from the given extended key and BSV.ExtKey.derivation_path/0.

Generates and returns a new BSV.ExtKey.t/0 from the given binary seed.

Generates and returns a new BSV.ExtKey.t/0 from the given binary seed.

Generates and returns a new random BSV.ExtKey.t/0.

Converts the given BSV.ExtKey.t/0 into a public extended key by dropping the BSV.PrivKey.t/0 and setting the appropriate version bytes.

Link to this section Types

Specs

derivation_path() :: String.t()

Derivation path

Derivation paths are used to derive a tree of keys from a common parent known as the master extended key. Paths are of the format:

m/child_index[/child_index...]

# or

m/0/1/2'

The first character m represents the master key. A lowercase m derives a private extended key, an uppercase M derives a public extended key.

The slashes seperate levels in the heirachy and each integer represents the child index in that level. A derivation path can be any number of levels deep meaning a practically limitless structure of private keys can be derived from a single master key.

When a child index is followed by a ' character, this denotes a hardened child extended private key. It is not possible to derive a hardened child extended public key from the same master key.

Specs

t() :: %BSV.ExtKey{
  chain_code: binary(),
  child_index: integer(),
  depth: integer(),
  fingerprint: binary(),
  privkey: BSV.PrivKey.t() | nil,
  pubkey: BSV.PubKey.t(),
  version: binary()
}

Extended key struct

Specs

xprv() :: String.t()

Serialised extended private key (xprv)

Specs

xpub() :: String.t()

Serialised extended public key (xpub)

Link to this section Functions

Specs

derive(t(), derivation_path()) :: t()

Derives a new BSV.ExtKey.t/0 from the given extended key and BSV.ExtKey.derivation_path/0.

Example

iex> ExtKey.derive(@extkey, "m/44'/0'/0'/0/99")
%BSV.ExtKey{
  chain_code: <<72, 111, 223, 181, 41, 141, 163, 217, 66, 98, 70, 93, 27, 235, 244, 143, 117, 254, 208, 161, 245, 132, 121, 135, 47, 56, 192, 127, 164, 121, 211, 197>>,
  child_index: 99,
  depth: 5,
  fingerprint: <<235, 254, 153, 73>>,
  privkey: %BSV.PrivKey{
    compressed: true,
    d: <<66, 22, 68, 9, 137, 109, 47, 233, 148, 194, 17, 198, 13, 207, 48, 235, 180, 185, 175, 29, 71, 244, 194, 128, 71, 231, 242, 49, 202, 226, 172, 105>>
  },
  pubkey: %BSV.PubKey{
    compressed: true,
    point: %Curvy.Point{
      x: 48097579158919705714136072738459690665844860244952534154601241870317938609256,
      y: 19116837737882717027311822027213492368729037447422592302419792121787000376066
    }
  },
  version: <<4, 136, 173, 228>>
}
Link to this function

from_seed(seed, opts \\ [])

View Source

Specs

from_seed(Mnemonic.seed(), keyword()) :: {:ok, t()} | {:error, term()}

Generates and returns a new BSV.ExtKey.t/0 from the given binary seed.

Returns the result in an :ok / :error tuple pair.

Options

The accepted options are:

  • :encoding - Optionally decode the binary with either the :base64 or :hex encoding scheme.
Link to this function

from_seed!(seed, opts \\ [])

View Source

Specs

from_seed!(Mnemonic.seed(), keyword()) :: t()

Generates and returns a new BSV.ExtKey.t/0 from the given binary seed.

As from_seed/2 but returns the result or raises an exception.

Specs

from_string(xprv() | xpub()) :: {:ok, t()} | {:error, term()}

Decodes the given BSV.ExtKey.xprv/0 or BSV.ExtKey.xpub/0 into a BSV.ExtKey.t/0.

Returns the result in an :ok / :error tuple pair.

Examples

iex> ExtKey.from_string("xprv9s21ZrQH143K3qcbMJpvTQQQ1zRCPaZjXUD1zPouMDtKY9QQQ9DskzrZ3Cx38GnYXpgY2awCmJfz2QXkpxLN3Pp2PmUddbnrXziFtArpZ5v")
{:ok, %BSV.ExtKey{
  chain_code: <<178, 208, 232, 46, 183, 65, 27, 66, 14, 172, 46, 66, 222, 84, 220, 98, 70, 249, 25, 3, 50, 209, 218, 236, 96, 142, 211, 79, 59, 166, 41, 106>>,
  child_index: 0,
  depth: 0,
  fingerprint: <<0, 0, 0, 0>>,
  privkey: %BSV.PrivKey{
    compressed: true,
    d: <<219, 231, 28, 56, 5, 76, 224, 63, 77, 224, 151, 38, 251, 136, 26, 87, 11, 186, 248, 245, 84, 56, 152, 11, 115, 35, 148, 32, 239, 241, 174, 90>>
  },
  pubkey: %BSV.PubKey{
    compressed: true,
    point: %Curvy.Point{
      x: 81914731537127506607736443451065612706836400740211682375254444777841949022440,
      y: 84194918502426421393864928067925727177552578328971362502574621746528696729690
    }
  },
  version: <<4, 136, 173, 228>>
}}

iex> ExtKey.from_string("xpub661MyMwAqRbcGKh4TLMvpYM8a2Fgo3Hath8cnnDWuZRJQwjYwgY8JoB2tTgiTDdwf4rdGvgUpGhGNH54Ycb8vegrhHVVpdfYCdBBii94CLF")
{:ok, %BSV.ExtKey{
  chain_code: <<178, 208, 232, 46, 183, 65, 27, 66, 14, 172, 46, 66, 222, 84, 220, 98, 70, 249, 25, 3, 50, 209, 218, 236, 96, 142, 211, 79, 59, 166, 41, 106>>,
  child_index: 0,
  depth: 0,
  fingerprint: <<0, 0, 0, 0>>,
  privkey: nil,
  pubkey: %BSV.PubKey{
    compressed: true,
    point: %Curvy.Point{
      x: 81914731537127506607736443451065612706836400740211682375254444777841949022440,
      y: 84194918502426421393864928067925727177552578328971362502574621746528696729690
    }
  },
  version: <<4, 136, 178, 30>>
}}

Specs

from_string!(xprv() | xpub()) :: t()

Decodes the given BSV.ExtKey.xprv/0 or BSV.ExtKey.xpub/0 into a BSV.ExtKey.t/0.

As from_string/1 but returns the result or raises an exception.

Specs

new() :: t()

Generates and returns a new random BSV.ExtKey.t/0.

Specs

to_public(t()) :: t()

Converts the given BSV.ExtKey.t/0 into a public extended key by dropping the BSV.PrivKey.t/0 and setting the appropriate version bytes.

Specs

to_string(t()) :: xprv() | xpub()

Encodes the given BSV.ExtKey.t/0 into a BSV.ExtKey.xprv/0 or BSV.ExtKey.xpub/0.

Examples

iex> ExtKey.to_string(@extkey)
"xprv9s21ZrQH143K3qcbMJpvTQQQ1zRCPaZjXUD1zPouMDtKY9QQQ9DskzrZ3Cx38GnYXpgY2awCmJfz2QXkpxLN3Pp2PmUddbnrXziFtArpZ5v"

iex> ExtKey.to_public(@extkey)
...> |> ExtKey.to_string()
"xpub661MyMwAqRbcGKh4TLMvpYM8a2Fgo3Hath8cnnDWuZRJQwjYwgY8JoB2tTgiTDdwf4rdGvgUpGhGNH54Ycb8vegrhHVVpdfYCdBBii94CLF"