skeleton_key 0.1.0

data/lib/skeleton_key/chains/bitcoin/account_derivation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Bitcoin
+      # Internal account-derivation helpers for Bitcoin account objects.
+      module AccountDerivation
+        private
+
+        def derive_from_seed(seed_bytes, purpose: 84, coin_type: 0, account: 0)
+          return derive_legacy_root_from_seed(seed_bytes) if legacy_root_branch_purpose?(purpose)
+
+          derive_standard_account_from_seed(seed_bytes, purpose: purpose, coin_type: coin_type, account: account)
+        end
+
+        def derive_standard_account_from_seed(seed_bytes, purpose:, coin_type:, account:)
+          key, chain_code = master_from_seed(seed_bytes)
+          depth = 0
+
+          key, chain_code, depth, = derive_step(key, chain_code, depth, hardened(purpose))
+          key, chain_code, depth, = derive_step(key, chain_code, depth, hardened(coin_type))
+          account_key, account_chain_code, account_depth, account_parent_fpr, account_child_num =
+            derive_step(key, chain_code, depth, hardened(account))
+
+          serialize_standard_account(
+            account_key,
+            account_chain_code,
+            account_depth,
+            account_parent_fpr,
+            account_child_num
+          )
+        end
+
+        def derive_legacy_root_from_seed(seed_bytes)
+          master_key, master_chain_code = master_from_seed(seed_bytes)
+          master_pubkey = privkey_to_pubkey_compressed(master_key)
+          master_fingerprint = fingerprint_from_pubkey(master_pubkey)
+          branch_key, branch_chain_code = ckd_priv(master_key, master_chain_code, 0)
+          branch_pubkey = privkey_to_pubkey_compressed(branch_key)
+
+          {
+            k_int: master_key,
+            c: master_chain_code,
+            bip32_xprv: serialize_xprv(
+              branch_key,
+              branch_chain_code,
+              depth: 1,
+              parent_fpr: master_fingerprint,
+              child_num: 0,
+              version: version_byte(network: network, purpose: purpose, private: true)
+            ),
+            bip32_xpub: serialize_xpub(
+              branch_pubkey,
+              branch_chain_code,
+              depth: 1,
+              parent_fpr: master_fingerprint,
+              child_num: 0,
+              version: version_byte(network: network, purpose: purpose)
+            ),
+            account_xprv: "",
+            account_xpub: ""
+          }
+        end
+
+        def derive_step(parent_key, parent_chain_code, parent_depth, child_index)
+          parent_pubkey = privkey_to_pubkey_compressed(parent_key)
+          parent_fingerprint = fingerprint_from_pubkey(parent_pubkey)
+          child_key, child_chain_code = ckd_priv(parent_key, parent_chain_code, child_index)
+
+          [child_key, child_chain_code, parent_depth + 1, parent_fingerprint, child_index]
+        end
+
+        def serialize_standard_account(account_key, account_chain_code, account_depth, account_parent_fpr, account_child_num)
+          account_pubkey = privkey_to_pubkey_compressed(account_key)
+          branch_key, branch_chain_code, branch_depth, branch_parent_fpr, branch_child_num = derive_step(
+            account_key,
+            account_chain_code,
+            account_depth,
+            0
+          )
+          branch_pubkey = privkey_to_pubkey_compressed(branch_key)
+
+          {
+            k_int: account_key,
+            c: account_chain_code,
+            bip32_xprv: serialize_xprv(
+              branch_key,
+              branch_chain_code,
+              depth: branch_depth,
+              parent_fpr: branch_parent_fpr,
+              child_num: branch_child_num,
+              version: version_byte(network: network, purpose: purpose, private: true)
+            ),
+            bip32_xpub: serialize_xpub(
+              branch_pubkey,
+              branch_chain_code,
+              depth: branch_depth,
+              parent_fpr: branch_parent_fpr,
+              child_num: branch_child_num,
+              version: version_byte(network: network, purpose: purpose)
+            ),
+            account_xprv: serialize_xprv(
+              account_key,
+              account_chain_code,
+              depth: account_depth,
+              parent_fpr: account_parent_fpr,
+              child_num: account_child_num,
+              version: version_byte(network: network, purpose: purpose, private: true)
+            ),
+            account_xpub: serialize_xpub(
+              account_pubkey,
+              account_chain_code,
+              depth: account_depth,
+              parent_fpr: account_parent_fpr,
+              child_num: account_child_num,
+              version: version_byte(network: network, purpose: purpose)
+            )
+          }
+        end
+
+        def hardened(index)
+          index | 0x8000_0000
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/bitcoin/support/outputs.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Bitcoin
+      module Support
+        module Outputs
+          module_function
+
+          def derive_address_from_account(change: 0, index: 0, hardened_change: false, hardened_index: false)
+            k, c = derived[:k_int], derived[:c]
+            change_index = hardened_change ? change | Derivation::Path::HARDENED_FLAG : change
+            address_index = hardened_index ? index | Derivation::Path::HARDENED_FLAG : index
+
+            k, c = ckd_priv(k, c, change_index)
+            k, c = ckd_priv(k, c, address_index)
+
+            pub = privkey_to_pubkey_compressed(k)
+
+            {
+              path: build_derived_path(change: change, index: index, hardened_change: hardened_change, hardened_index: hardened_index),
+              privkey: k,
+              pubkey: pub,
+              chain_code: c,
+              wif: to_wif(ser256(k), network: network),
+              address: address_for_pubkey(pub)
+            }
+          end
+
+          def derive_branch_extended_keys(change: 0, hardened_change: false)
+            parent_key = derived[:k_int]
+            parent_chain_code = derived[:c]
+            parent_pubkey = privkey_to_pubkey_compressed(parent_key)
+            child_num = hardened_change ? change | Derivation::Path::HARDENED_FLAG : change
+            branch_key, branch_chain_code = ckd_priv(parent_key, parent_chain_code, child_num)
+            branch_pubkey = privkey_to_pubkey_compressed(branch_key)
+
+            {
+              path: branch_derived_path(change: change, hardened_change: hardened_change),
+              xprv: serialize_xprv(
+                branch_key,
+                branch_chain_code,
+                depth: legacy_root_branch? ? 1 : 4,
+                parent_fpr: fingerprint_from_pubkey(parent_pubkey),
+                child_num: child_num,
+                version: version_byte(network: network, purpose: purpose, private: true)
+              ),
+              xpub: serialize_xpub(
+                branch_pubkey,
+                branch_chain_code,
+                depth: legacy_root_branch? ? 1 : 4,
+                parent_fpr: fingerprint_from_pubkey(parent_pubkey),
+                child_num: child_num,
+                version: version_byte(network: network, purpose: purpose)
+              )
+            }
+          end
+
+          private
+
+          def address_for_pubkey(pubkey)
+            case purpose
+            when 32, 44
+              to_p2pkh_address(pubkey, network: network)
+            when 49
+              to_p2sh_p2wpkh_address(pubkey, network: network)
+            when 84, 141
+              to_bech32_address(pubkey, hrp: network == :mainnet ? "bc" : "tb")
+            else
+              raise Errors::UnsupportedPurposeError.new(purpose)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/bitcoin/support/paths.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Bitcoin
+      module Support
+        module Paths
+          module_function
+
+          def build_derived_path(change:, index:, hardened_change:, hardened_index:)
+            rendered_change = hardened_change ? "#{change}'" : change.to_s
+            rendered_index = hardened_index ? "#{index}'" : index.to_s
+
+            if legacy_root_branch?
+              "m/#{rendered_change}/#{rendered_index}"
+            else
+              "m/#{purpose}'/#{coin_type}'/#{account_index}'/#{rendered_change}/#{rendered_index}"
+            end
+          end
+
+          def branch_derived_path(change:, hardened_change:)
+            rendered_change = hardened_change ? "#{change}'" : change.to_s
+
+            if legacy_root_branch?
+              "m/#{rendered_change}"
+            else
+              "m/#{purpose}'/#{coin_type}'/#{account_index}'/#{rendered_change}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/bitcoin/support/versioning.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Bitcoin
+      module Support
+        module Versioning
+          VERSION_BYTES = {
+            mainnet: {
+              bip44: { xpub: 0x0488B21E, xprv: 0x0488ADE4 },
+              bip49: { ypub: 0x049D7CB2, yprv: 0x049D7878 },
+              bip84: { zpub: 0x04B24746, zprv: 0x04B2430C }
+            },
+            testnet: {
+              bip44: { tpub: 0x043587CF, tprv: 0x04358394 },
+              bip49: { upub: 0x044A5262, uprv: 0x044A4E28 },
+              bip84: { vpub: 0x045F1CF6, vprv: 0x045F18BC }
+            }
+          }.freeze
+
+          module_function
+
+          def version_byte(network:, purpose:, private: false)
+            version = if private
+              private_version_byte(network: network, purpose: purpose)
+            else
+              public_version_byte(network: network, purpose: purpose)
+            end
+
+            [version].pack("N")
+          end
+
+          def version_bytes(network:, purpose:)
+            case [purpose, network]
+            when [32, :mainnet] then VERSION_BYTES[:mainnet][:bip44]
+            when [32, :testnet] then VERSION_BYTES[:testnet][:bip44]
+            when [141, :mainnet] then VERSION_BYTES[:mainnet][:bip84]
+            when [141, :testnet] then VERSION_BYTES[:testnet][:bip84]
+            when [44, :mainnet] then VERSION_BYTES[:mainnet][:bip44]
+            when [44, :testnet] then VERSION_BYTES[:testnet][:bip44]
+            when [49, :mainnet] then VERSION_BYTES[:mainnet][:bip49]
+            when [49, :testnet] then VERSION_BYTES[:testnet][:bip49]
+            when [84, :mainnet] then VERSION_BYTES[:mainnet][:bip84]
+            when [84, :testnet] then VERSION_BYTES[:testnet][:bip84]
+            else
+              raise Errors::UnsupportedPurposeNetworkError.new(purpose: purpose, network: network)
+            end
+          end
+
+          def public_version_byte(network:, purpose:)
+            case [purpose, network]
+            when [32, :mainnet] then VERSION_BYTES[:mainnet][:bip44][:xpub]
+            when [32, :testnet] then VERSION_BYTES[:testnet][:bip44][:tpub]
+            when [141, :mainnet] then VERSION_BYTES[:mainnet][:bip84][:zpub]
+            when [141, :testnet] then VERSION_BYTES[:testnet][:bip84][:vpub]
+            when [44, :mainnet] then VERSION_BYTES[:mainnet][:bip44][:xpub]
+            when [44, :testnet] then VERSION_BYTES[:testnet][:bip44][:tpub]
+            when [49, :mainnet] then VERSION_BYTES[:mainnet][:bip49][:ypub]
+            when [49, :testnet] then VERSION_BYTES[:testnet][:bip49][:upub]
+            when [84, :mainnet] then VERSION_BYTES[:mainnet][:bip84][:zpub]
+            when [84, :testnet] then VERSION_BYTES[:testnet][:bip84][:vpub]
+            else
+              raise Errors::UnsupportedPurposeNetworkError.new(purpose: purpose, network: network)
+            end
+          end
+
+          def private_version_byte(network:, purpose:)
+            case [purpose, network]
+            when [32, :mainnet] then VERSION_BYTES[:mainnet][:bip44][:xprv]
+            when [32, :testnet] then VERSION_BYTES[:testnet][:bip44][:tprv]
+            when [141, :mainnet] then VERSION_BYTES[:mainnet][:bip84][:zprv]
+            when [141, :testnet] then VERSION_BYTES[:testnet][:bip84][:vprv]
+            when [44, :mainnet] then VERSION_BYTES[:mainnet][:bip44][:xprv]
+            when [44, :testnet] then VERSION_BYTES[:testnet][:bip44][:tprv]
+            when [49, :mainnet] then VERSION_BYTES[:mainnet][:bip49][:yprv]
+            when [49, :testnet] then VERSION_BYTES[:testnet][:bip49][:uprv]
+            when [84, :mainnet] then VERSION_BYTES[:mainnet][:bip84][:zprv]
+            when [84, :testnet] then VERSION_BYTES[:testnet][:bip84][:vprv]
+            else
+              raise Errors::UnsupportedPurposeNetworkError.new(purpose: purpose, network: network)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/bitcoin/support.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Bitcoin
+      module Support
+        extend Utils::Hashing
+        extend Utils::Encoding
+        include Versioning
+        include Paths
+        include Outputs
+
+        module_function
+
+        def to_wif(priv_bytes, compressed: true, network: :mainnet)
+          prefix = (network == :mainnet ? "\x80".b : "\xEF".b)
+          payload = prefix + priv_bytes.b
+          payload += "\x01".b if compressed
+          base58check_encode(payload)
+        end
+
+        def to_p2pkh_address(pubkey_bytes, network: :mainnet)
+          prefix = (network == :mainnet ? "\x00" : "\x6F")
+          payload = prefix + hash160(pubkey_bytes)
+          base58check_encode(payload)
+        end
+
+        def to_p2sh_p2wpkh_address(pubkey_bytes, network: :mainnet)
+          prog = hash160(pubkey_bytes)
+          redeem_script = "\x00\x14" + prog
+          script_hash = hash160(redeem_script)
+
+          prefix = (network == :mainnet ? "\x05" : "\xC4")
+          payload = prefix + script_hash
+          base58check_encode(payload)
+        end
+
+        def to_bech32_address(pubkey_bytes, hrp: "bc")
+          prog = hash160(pubkey_bytes)
+          prog5 = Codecs::Bech32.convert_bits(prog.bytes, 8, 5, true)
+          data = [0] + prog5
+
+          Codecs::Bech32.encode(hrp, data, Codecs::Bech32::Encoding::BECH32)
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/ethereum/account.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Ethereum
+      ##
+      # Ethereum account derivation from a shared {Seed}.
+      #
+      # This class owns Ethereum path conventions and Ethereum-facing account
+      # semantics. Shared secp256k1 and BIP32 primitives remain in the derivation
+      # layer; this class decides which path to walk and how to expose the
+      # resulting branch and address data.
+      #
+      # Supported modes:
+      # - legacy BIP32 root mode (`purpose == 32`)
+      # - BIP44 account mode (`m/44'/60'/account'`)
+      #
+      # @example Derive the first Ethereum address from a BIP44 account
+      #   account = SkeletonKey::Chains::Ethereum::Account.new(seed: seed.bytes)
+      #   account.address(change: 0, index: 0)
+      class Account
+        include Support
+        include Derivation::BIP32
+
+        # @return [Integer] derivation purpose (32 or 44)
+        # @return [Integer] SLIP-0044 coin type, normally 60 for Ethereum
+        # @return [Integer] account index within the purpose/coin namespace
+        # @return [Hash] cached derived account metadata and extended keys
+        attr_reader :purpose, :coin_type, :account_index, :derived
+
+        LEGACY_BIP32_PURPOSE = 32
+        DEFAULT_PURPOSE = 44
+        ETHEREUM_COIN = 60
+
+        # @param seed [String] canonical seed bytes
+        # @param purpose [Integer] derivation purpose (32 or 44)
+        # @param coin_type [Integer] SLIP-0044 coin type
+        # @param account_index [Integer] account number to derive
+        # @raise [Errors::UnsupportedPurposeError] if the requested path family is unsupported
+        def initialize(seed:, purpose: DEFAULT_PURPOSE, coin_type: ETHEREUM_COIN, account_index: 0)
+          @purpose = purpose
+          @coin_type = coin_type
+          @account_index = account_index
+          @derived = derive_from_seed(seed, purpose: purpose, coin_type: coin_type, account: account_index)
+        end
+
+        # Returns the account path prefix that future branch and address
+        # derivations are anchored to.
+        #
+        # @return [String]
+        def path
+          derived[:path_prefix]
+        end
+
+        # Derives an Ethereum address node below the account prefix.
+        #
+        # Ethereum keeps the BIP44 `change/index` shape for compatibility even
+        # though the chain is account-based rather than UTXO-based.
+        #
+        # @param change [Integer] branch index beneath the account
+        # @param index [Integer] address index within the branch
+        # @param hardened_change [Boolean] whether to harden the branch step
+        # @param hardened_index [Boolean] whether to harden the address step
+        # @return [Hash] private key, public keys, checksummed address, and path metadata
+        def address(change: 0, index: 0, hardened_change: false, hardened_index: false)
+          derive_address_from_node(
+            change: change,
+            index: index,
+            hardened_change: hardened_change,
+            hardened_index: hardened_index
+          )
+        end
+
+        # Serializes the extended keypair for a branch directly beneath the
+        # current account or root node.
+        #
+        # @param change [Integer] branch index to derive
+        # @param hardened_change [Boolean] whether the branch child is hardened
+        # @return [Hash] serialized extended keypair and rendered path
+        def branch_extended_keys(change: 0, hardened_change: false)
+          derive_branch_extended_keys(change: change, hardened_change: hardened_change)
+        end
+
+        private
+
+        def derive_from_seed(seed_bytes, purpose:, coin_type:, account:)
+          return derive_legacy_root_from_seed(seed_bytes) if purpose == LEGACY_BIP32_PURPOSE
+          return derive_bip44_account_from_seed(seed_bytes, purpose: purpose, coin_type: coin_type, account: account) if purpose == 44
+
+          raise Errors::UnsupportedPurposeError.new(purpose)
+        end
+
+      def derive_legacy_root_from_seed(seed_bytes)
+        k_master, c_master = master_from_seed(seed_bytes)
+        master_pub = privkey_to_pubkey_compressed(k_master)
+        master_fpr = fingerprint_from_pubkey(master_pub)
+        k_branch, c_branch = ckd_priv(k_master, c_master, 0)
+        pub_branch = privkey_to_pubkey_compressed(k_branch)
+
+        {
+          path_prefix: "m",
+          k_int: k_master,
+          c: c_master,
+          account_extended_private_key: "",
+          account_extended_public_key: "",
+          branch_extended_private_key: serialize_xprv(
+            k_branch,
+            c_branch,
+            depth: 1,
+            parent_fpr: master_fpr,
+            child_num: 0,
+            version: extended_private_version
+          ),
+          branch_extended_public_key: serialize_xpub(
+            pub_branch,
+            c_branch,
+            depth: 1,
+            parent_fpr: master_fpr,
+            child_num: 0,
+            version: extended_public_version
+          )
+        }
+      end
+
+      def derive_bip44_account_from_seed(seed_bytes, purpose:, coin_type:, account:)
+        k_int, chain_code = master_from_seed(seed_bytes)
+        depth = 0
+
+        # Walk the BIP44 hardened account path one level at a time so the
+        # serialized parent fingerprint and child number remain explicit.
+        derive_step = ->(k_in, c_in, depth_in, index) do
+          parent_pub = privkey_to_pubkey_compressed(k_in)
+          parent_fpr = fingerprint_from_pubkey(parent_pub)
+          k_out, c_out = ckd_priv(k_in, c_in, index)
+          [k_out, c_out, depth_in + 1, parent_fpr, index]
+        end
+
+        k_int, chain_code, depth, _, _ = derive_step.call(k_int, chain_code, depth, 0x8000_0000 | purpose)
+        k_int, chain_code, depth, _, _ = derive_step.call(k_int, chain_code, depth, 0x8000_0000 | coin_type)
+        k_account, c_account, depth_account, parent_fpr, child_num = derive_step.call(k_int, chain_code, depth, 0x8000_0000 | account)
+        pub_account = privkey_to_pubkey_compressed(k_account)
+
+        k_branch, c_branch, depth_branch, branch_parent_fpr, branch_child_num = derive_step.call(k_account, c_account, depth_account, 0)
+        pub_branch = privkey_to_pubkey_compressed(k_branch)
+
+        {
+          path_prefix: "m/#{purpose}'/#{coin_type}'/#{account}'",
+          k_int: k_account,
+          c: c_account,
+          account_extended_private_key: serialize_xprv(
+            k_account,
+            c_account,
+            depth: depth_account,
+            parent_fpr: parent_fpr,
+            child_num: child_num,
+            version: extended_private_version
+          ),
+          account_extended_public_key: serialize_xpub(
+            pub_account,
+            c_account,
+            depth: depth_account,
+            parent_fpr: parent_fpr,
+            child_num: child_num,
+            version: extended_public_version
+          ),
+          branch_extended_private_key: serialize_xprv(
+            k_branch,
+            c_branch,
+            depth: depth_branch,
+            parent_fpr: branch_parent_fpr,
+            child_num: branch_child_num,
+            version: extended_private_version
+          ),
+          branch_extended_public_key: serialize_xpub(
+            pub_branch,
+            c_branch,
+            depth: depth_branch,
+            parent_fpr: branch_parent_fpr,
+            child_num: branch_child_num,
+            version: extended_public_version
+          )
+        }
+      end
+
+        def legacy_root_branch?
+          purpose == LEGACY_BIP32_PURPOSE
+        end
+      end
+    end
+  end
+end