skeleton_key 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7a0cbc245df26ea9b06a09ea21cc92336a5539853e235b33df9b49e65ab738
-  data.tar.gz: 055e8323ee4457a6704d422f110d6a7140b4541e5be1a951591c7d78e74b7134
+  metadata.gz: fb63b4370d3a11f016dee71efc6df9516df5fcd436987dfeed4b07c348dd7277
+  data.tar.gz: e22d95c59f1b24ab1f8b2532bd55c9cb2407c555cd0e62324e8cd536945caec1
 SHA512:
-  metadata.gz: 6baf89deae1dce76f2552a1133d3d42638e2604783f782c46f83357f49cad785742a859affdfdeaa393f721ffa9502fd413fe53937288d9deaf6a23d39a3f848
-  data.tar.gz: cb22f9883391cbc02a3589101ff8830bcd8beed1ea78f83b4094cb9ab002310414e06571da5ada1b5151d0e730708bc3ba888eccc399ad816e0627d6a6c2e080
+  metadata.gz: 12b8bb96fd60252d45e46859ed505181f150c3c589cde6f8e5ae0120f610a3c204ae4893bd9534af6aafc2ddd3ac37e477d84d59235ce37de1f455e40263315c
+  data.tar.gz: bde4855fada160f437f17da16a04eaf6195a543be73fd10d1991ed2e831850f926a99060c23753d8ffaaa54633501327b603aab784eb63f27bb5aa953fd8eadc

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-03-22
+
+### Added
+
+- Added explicit BIP39 passphrase support to `SkeletonKey::Seed.import` and `SkeletonKey::Keyring.new` when recovering from mnemonic input.
+- Added opt-in Solana `derivation_path: nil` support to match the default no-path behavior of `solana-keygen new`.
+- Added Solana CLI-backed golden vectors and integration coverage for the no-path derivation mode.
+- Added this changelog and included it in the packaged gem files.
+
+### Changed
+
+- Documented that BIP39 passphrases are separate from mnemonic words.
+- Documented the Solana default path mode and the opt-in Solana CLI compatibility mode.
+
+[Unreleased]: https://github.com/sebscholl/skeleton-key/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/sebscholl/skeleton-key/releases/tag/v0.1.1

data/README.md

@@ -30,12 +30,13 @@
                      ██████
 ```
 
-[![Gem Version](https://badge.fury.io/rb/skeleton_key.svg )](https://badge.fury.io/rb/skeleton_key )
+[![Gem Version](https://badge.fury.io/rb/skeleton_key.svg?icon=si%3Arubygems&icon_color=%23f00000)](https://badge.fury.io/rb/skeleton_key)
+[![Release](https://github.com/sebscholl/skeleton-key/actions/workflows/release.yml/badge.svg)](https://github.com/sebscholl/skeleton-key/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg )](LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.2-black )](https://www.ruby-lang.org )
 [![Safety-Critical](https://img.shields.io/badge/⚠%20Safety--Critical-black )](SECURITY.md)
 
-SkeletonKey is a Ruby library for deterministic wallet recovery and key derivation across Bitcoin, Ethereum, and Solana. It is designed around a strict boundary:
+SkeletonKey is a zero-dependency Ruby library for deterministic wallet recovery and key derivation across Bitcoin, Ethereum, and Solana. It is designed around a strict boundary:
 
 - recovery formats in the recovery layer
 - shared seed and derivation primitives in the shared layer
@@ -91,6 +92,15 @@ Generate a random keyring:
 keyring = SkeletonKey::Keyring.new
 ```
 
+Initialize from a mnemonic with a BIP39 passphrase:
+
+```ruby
+keyring = SkeletonKey::Keyring.new(
+  seed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+  passphrase: "TREZOR"
+)
+```
+
 Initialize from an existing hex seed:
 
 ```ruby
@@ -151,14 +161,18 @@ You can also pass a mnemonic directly to `Seed.import` or `Keyring.new`:
 
 ```ruby
 seed = SkeletonKey::Seed.import(
-  "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+  "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+  passphrase: "TREZOR"
 )
 
 keyring = SkeletonKey::Keyring.new(
-  seed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+  seed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+  passphrase: "TREZOR"
 )
 ```
 
+The BIP39 passphrase is separate from the mnemonic. It is not an extra mnemonic word.
+
 What BIP39 validation currently enforces:
 
 - official BIP39 word counts only: `12`, `15`, `18`, `21`, `24`
@@ -436,6 +450,18 @@ Derive deeper hardened children:
 node = account.address(change: 0, index: 15)
 ```
 
+Match the default no-path behavior of `solana-keygen new`:
+
+```ruby
+account = keyring.solana(derivation_path: nil)
+node = account.address
+
+node[:path]         # nil
+node[:private_key]  # first 32 bytes of the canonical seed, hex
+node[:public_key]   # 32-byte Ed25519 public key, hex
+node[:address]      # Base58-encoded Solana address
+```
+
 Solana in SkeletonKey is hardened-only. There is no supported unhardened child derivation path.
 
 ## Architecture

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

@@ -26,18 +26,33 @@ module SkeletonKey
 
         DEFAULT_PURPOSE = 44
         SOLANA_COIN = 501
-        LEGACY_CHANGELESS_PURPOSE = 44
+        DEFAULT_DERIVATION_PATH = Object.new.freeze
+        UNSPECIFIED_CHANGE = Object.new.freeze
 
         # @param seed [String] canonical seed bytes
         # @param purpose [Integer] derivation purpose, fixed at 44
         # @param coin_type [Integer] SLIP-0044 coin type, fixed at 501
         # @param account_index [Integer] hardened account index
+        # @param derivation_path [nil] set to `nil` to match Solana CLI no-path mode
         # @raise [Errors::UnsupportedPurposeError] if non-Solana path parameters are requested
-        def initialize(seed:, purpose: DEFAULT_PURPOSE, coin_type: SOLANA_COIN, account_index: 0)
+        def initialize(
+          seed:, 
+          purpose: DEFAULT_PURPOSE, 
+          coin_type: SOLANA_COIN, 
+          account_index: 0,
+          derivation_path:
+          DEFAULT_DERIVATION_PATH
+        )
           @purpose = purpose
           @coin_type = coin_type
           @account_index = account_index
-          @derived = derive_from_seed(seed, purpose: purpose, coin_type: coin_type, account: account_index)
+          @derived = derive(
+            seed, 
+            purpose: purpose, 
+            coin_type: coin_type, 
+            account: account_index,                     
+            derivation_path: derivation_path
+          )
         end
 
         # Returns the hardened account prefix for future child derivation.
@@ -55,9 +70,12 @@ module SkeletonKey
         # @param change [Integer, nil] hardened child directly beneath the account
         # @param index [Integer, nil] hardened child beneath the change node
         # @return [Hash] path, private key, public key, address, and chain code
-        def address(change: 0, index: nil)
+        def address(change: UNSPECIFIED_CHANGE, index: nil)
+          return no_path_address(change: change, index: index) if path.nil?
+
           key_seed, chain_code = derived[:key_seed], derived[:chain_code]
           current_path = path
+          change = 0 if change.equal?(UNSPECIFIED_CHANGE)
 
           unless change.nil?
             current_path = "#{current_path}/#{change}'"
@@ -73,15 +91,25 @@ module SkeletonKey
 
           {
             path: current_path,
-            private_key: private_key.unpack1("H*"),
-            public_key: public_key.unpack1("H*"),
+            chain_code: chain_code,
             address: to_address(public_key),
-            chain_code: chain_code
+            public_key: public_key.unpack1("H*"),
+            private_key: private_key.unpack1("H*"),
           }
         end
 
         private
 
+        def derive(seed_bytes, purpose:, coin_type:, account:, derivation_path:)
+          return derive_without_path(seed_bytes, purpose: purpose, coin_type: coin_type, account: account) if derivation_path.nil?
+
+          unless derivation_path.equal?(DEFAULT_DERIVATION_PATH)
+            raise Errors::InvalidPathFormatError, "unsupported Solana derivation_path override"
+          end
+
+          derive_from_seed(seed_bytes, purpose: purpose, coin_type: coin_type, account: account)
+        end
+
         def derive_from_seed(seed_bytes, purpose:, coin_type:, account:)
           raise Errors::UnsupportedPurposeError.new(purpose) unless purpose == 44
           raise Errors::UnsupportedPurposeError.new(coin_type) unless coin_type == SOLANA_COIN
@@ -104,6 +132,39 @@ module SkeletonKey
           }
         end
 
+        def derive_without_path(seed_bytes, purpose:, coin_type:, account:)
+          unless purpose == DEFAULT_PURPOSE && coin_type == SOLANA_COIN && account.zero?
+            raise Errors::InvalidPathFormatError,
+                  "solana derivation_path=nil is incompatible with purpose, coin_type, or account_index overrides"
+          end
+
+          if seed_bytes.bytesize < Constants::PRIVATE_KEY_LENGTH
+            raise Errors::InvalidSeedError, "solana derivation_path=nil requires at least 32 seed bytes"
+          end
+
+          {
+            path_prefix: nil,
+            key_seed: seed_bytes.byteslice(0, Constants::PRIVATE_KEY_LENGTH),
+            chain_code: nil
+          }
+        end
+
+        def no_path_address(change:, index:)
+          unless (change.equal?(UNSPECIFIED_CHANGE) || change.nil?) && index.nil?
+            raise Errors::InvalidPathFormatError, "solana derivation_path=nil does not support child derivation"
+          end
+
+          private_key, public_key = keypair_from_seed(derived[:key_seed])
+
+          {
+            path: nil,
+            private_key: private_key.unpack1("H*"),
+            public_key: public_key.unpack1("H*"),
+            address: to_address(public_key),
+            chain_code: nil
+          }
+        end
+
         # Encodes a child index as a hardened SLIP-0010 index.
         #
         # @param index [Integer]

data/lib/skeleton_key/keyring.rb

@@ -33,9 +33,10 @@ module SkeletonKey
     # Initializes a new Keyring with an optional seed
     #
     # @param seed [String, Seed, Array<Integer>, nil] the seed to initialize the Keyring with (optional)
+    # @param passphrase [String] optional BIP39 passphrase when `seed` is a mnemonic
     # @return [Keyring] the initialized Keyring
-    def initialize(seed: nil)
-      @seed = Seed.import(seed)
+    def initialize(seed: nil, passphrase: "")
+      @seed = Seed.import(seed, passphrase: passphrase)
     end
 
     # Access the Bitcoin account derived from the seed

data/lib/skeleton_key/seed.rb

@@ -52,15 +52,16 @@ module SkeletonKey
       # - array of octets
       #
       # @param value [String, Seed, Recovery::Bip39, Array<Integer>, nil]
+      # @param passphrase [String] optional BIP39 passphrase for mnemonic input
       # @return [Seed]
       # @raise [Errors::InvalidSeedError] if the value cannot be normalized
-      def import(value)
+      def import(value, passphrase: "")
         case
         when value.nil? then generate
         when value.is_a?(Seed) then import_from_seed(value)
-        when value.is_a?(Recovery::Bip39) then import_from_mnemonic(value)
+        when value.is_a?(Recovery::Bip39) then import_from_mnemonic(value, passphrase: passphrase)
         when hex_string?(value) then import_from_hex(value)
-        when mnemonic_string?(value) then import_from_mnemonic(value)
+        when mnemonic_string?(value) then import_from_mnemonic(value, passphrase: passphrase)
         when byte_string?(value) then import_from_bytes(value)
         when octet_array?(value) then import_from_octets(value)
         else
@@ -110,9 +111,10 @@ module SkeletonKey
       # Recovers a seed from a BIP39 mnemonic phrase.
       #
       # @param mnemonic [Recovery::Bip39, String]
+      # @param passphrase [String] optional BIP39 passphrase
       # @return [Seed]
-      def import_from_mnemonic(mnemonic)
-        Recovery::Bip39.import(mnemonic).seed
+      def import_from_mnemonic(mnemonic, passphrase: "")
+        Recovery::Bip39.import(mnemonic).seed(passphrase: passphrase)
       end
 
       private

data/lib/skeleton_key/version.rb

@@ -4,5 +4,5 @@ module SkeletonKey
   # Current gem version.
   #
   # @return [String]
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: skeleton_key
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.0'
 description: SkeletonKey provides deterministic wallet recovery, seed normalization,
   and key derivation for Bitcoin, Ethereum, and Solana.
 email:
@@ -34,6 +34,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - bin/console
 - bin/lint