cardano-bech32 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc7e539a8a0e31cc6e25a42a84ba58419f9ce689be6be07f6e92cc8d6f4a04c
-  data.tar.gz: 04a8ff0509d920547f2e9f181e7659c3743fee575bf7f11ea61c35f9c0111fb2
+  metadata.gz: c13d50b51db3aad428e4dc97ed0036c8bdd2bc04340a13af4d5634f372015300
+  data.tar.gz: 9ec070ab4fd53ad9b6cfc0e64d7bb9de66cee2bb6644b235f4557eebc96feabc
 SHA512:
-  metadata.gz: 90641e5ad5e7a0bfcd19e061fa8a02ed8442a9f25a7e023cc43ce447e7536270ae06029fdaef142ab92fe55be914d731d21ee7476236f359de1ebed5cfdd88eb
-  data.tar.gz: 29b7495b3e916622a6d3792fc412f2bc8471879c1d8a4f4ec9ba3e135c66ff0e814366fceefabe7472a2a9e6f0c1ac4b4870921f3952b1318f0516891892d28c
+  metadata.gz: ebbf68a3fb7bbcd5b07530d435cc78901fdc1c64e8135a87d12bb053b4fb70088da9fa2ea540ec10f85863efad2e750c4510d475e87059bd62a778b5b98c7b7b
+  data.tar.gz: 34b20e1373a2d0953f04d2fca08e465b4dc2549b4df53c3bcd08207dccc7aad7b945a955918ce6c748752d005927595053394668097c62b04ba7c02bd410598f

data/CHANGELOG.md

@@ -8,3 +8,14 @@
 - Decoding of `gov_action` Bech32 identifiers into transaction ID and index
 - Validation helpers for governance action identifiers
 - RSpec test suite with normative CIP-0129 test vectors
+
+## [0.1.0] - 2026-01-05
+
+### Added
+- Encoding of DRep IDs `drep` as defined in CIP-0129
+- Decoding of `drep` Bech32 identifiers into hex and byte data
+- Encoding of CC (cold / hot) IDs `cc_cold` `cc_hot` as defined in CIP-0129
+- Decoding of `cc_cold` `cc_hot` into hex and byte data
+- Encoding of Stake Pool identifier `pool`
+- Decoding of Stake Pool identifiers into hex and byte data
+- Decoding of Addresses such as Base, Stake, Pointer, Enterprise into network info, byte data

data/README.md

@@ -1,22 +1,28 @@
 # cardano-bech32
 
 A small, focused Ruby library for encoding and decoding Cardano Bech32 identifiers.
-This gem deliberately avoids higher-level ledger concerns and focuses solely on correct, specification-compliant Bech32 handling.
+This gem deliberately avoids higher-level ledger concerns and focuses solely on **specification-compliant Bech32 handling**.
 
-Currently supported
+## Supported Identifiers
 
-- [x] Governance Action IDs (gov_action) — [CIP-0129](https://cips.cardano.org/cip/CIP-0129)
-- [ ] Addresses
-- [ ] Stake pool IDs
-- [ ] DRep IDs
+- [x] Governance [CIP-0129](https://cips.cardano.org/cip/CIP-0129)
+  - [x] GovAction IDs
+  - [x] DRep IDs
+  - [x] CC hot/cold
+- [x] Addresses
+  - [x] Base Address
+  - [x] Enterprise Address
+  - [x] Pointer Address
+  - [x] Stake Address
+- [x] Stake Pool IDs
 
 The API is designed to grow conservatively as additional Cardano Improvement Proposals (CIPs) are implemented.
 
 ## Installation
 
-Add this line to your application’s Gemfile:
+Add to your Gemfile:
 
-```sh
+```ruby
 gem "cardano-bech32"
 ```
 
@@ -34,79 +40,184 @@ gem install cardano-bech32
 
 ## Usage
 
-### Governance Action IDs (CIP-0129)
+### Governance Credentials (CIP-0129)
 
-A Governance Action ID is derived as:
-tx_id (32 bytes) || index (1 byte)
-→ Bech32 encode with HRP "gov_action"
+Cardano governance identifiers defined in CIP-0129 are Bech32-encoded binary payloads used throughout on-chain governance.
 
-#### Encoding
+This library supports all CIP-0129 governance identifiers, including:
 
-```ruby
-require "cardano/bech32"
+* Constitutional Committee credentials (hot & cold)
+* DRep credentials
+* Governance Action IDs
 
-txref = "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5#0"
+#### Constitutional Committee & DRep Credentials
 
-Cardano::Bech32::GovAction.encode(txref)
-# => "gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn"
+Governance credentials consist of:
+
+```
+header (1 byte) || credential hash (N bytes)
 ```
 
-#### Decoding
+The header byte is authoritative and encodes:
+* Credential type (CC Hot, CC Cold, DRep)
+* Key type (key hash or script hash)
 
-```ruby
-Cardano::Bech32::GovAction.decode(
-  "gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn"
+The HRP is derived from the header and validated during decoding.
+
+Decode a governance credential
+
+```
+require "cardano/bech32"
+
+cred = Cardano::Bech32::GovCredentials.decode(
+  "cc_cold1zvqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6kflvs"
 )
-# => {
-  tx_id: "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5",
-  index: 0
-}
+
+cred.credential      # => :cc_cold
+cred.hash_bytes      # => [0, 0, 0, ...]
+cred.header_byte     # => 19
+cred.hrp             # => "cc_cold"
+cred.key_type        # => :script
+cred.payload_bytes   # => [19, 0, 0, ...]
+cred.payload_hex     # => "1300000000..."
 ```
 
-#### Validation
+The returned object is one of:
+* `Cardano::Bech32::GovCredentials::Cc`
+* `Cardano::Bech32::GovCredentials::Drep`
 
-Validation checks:
-* Bech32 checksum
-* Correct HRP (gov_action)
-* Correct payload length (33 bytes)
+Both inherit from `AbstractCredential` and expose a uniform interface.
+
+Encode a governance credential
+
+```
+payload_hex = "130000000000000000000000000000000000000000000000000000000000"
+
+bech32 = Cardano::Bech32::GovCredentials.encode(payload_hex)
+# => "cc_cold1zvqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6kflvs"
+```
+
+The encoder:
+* Accepts raw bytes or hex
+* Infers HRP from the header byte
+
+
+#### Governance Action IDs
+
+Governance Action IDs identify a governance action on-chain and consist of:
+
+
+```
+tx_id (32 bytes) || index (1 byte)
+```
+
+They are encoded as Bech32 using HRP `gov_action`.
 
 ```ruby
-Cardano::Bech32::GovAction.valid?("gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn")
+require "cardano/bech32"
+
+txref = "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5#0"
+bech32 = Cardano::Bech32::GovAction.encode(txref)
+# => "gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn"
+
+gov_action = Cardano::Bech32::GovAction.decode(bech32)
+gov_action.tx_id          # => "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5"
+gov_action.index          # => 0
+gov_action.payload_bytes  # => [178, 165, 145, 172, ...]
+gov_action.hrp            # => "gov_action"
+
+Cardano::Bech32::GovAction.valid?(bech32)
 # => true
 ```
 
-### Error Handling
-
-The library normalizes all Bech32 decoding and validation failures into
-explicit, typed errors:
+All decoding/validation failures for `GovAction` raise explicit, typed errors:
 
-* InvalidFormat — malformed input, wrong HRP, invalid Bech32
-* InvalidPayload — incorrect byte length, invalid index
+* `Cardano::Bech32::GovAction::InvalidFormat` — malformed input, wrong HRP, invalid Bech32
+* `Cardano::Bech32::GovAction::InvalidPayload` — incorrect payload length, invalid index
 
 ```ruby
-# Example
 begin
-  Cardano::Bech32::GovAction.encode("invalid")
-rescue Cardano::Bech32::GovAction::Error => e
+  Cardano::Bech32::GovAction.decode("invalid")
+rescue Cardano::Bech32::GovAction::InvalidFormat,
+       Cardano::Bech32::GovAction::InvalidPayload => e
   puts e.message
 end
+```
+
 
+
+### Stake Pool IDs
+
+Stake Pool IDs are Bech32-encoded 28-byte hashes identifying a registered stake pool.
+
+```ruby
+pool_hash = "6e90911fdb579e203f556f3f24aca5b8714be049ccf716008ab849fd"
+Cardano::Bech32::StakePool.encode(pool_hash)
+# => pool1d6gfz87m270zq064duljft99hpc5hczfenm3vqy2hpyl67tteq9
+
+pool_id = "pool1d6gfz87m270zq064duljft99hpc5hczfenm3vqy2hpyl67tteq9"
+Cardano::Bech32::StakePool.decode(pool_id)
+# => { bytes: "\x8C\xB8\...", hex: "6e90911..." }
+
+Cardano::Bech32::StakePool.valid?(pool_id)
+# => true
+```
+
+### Addresses
+
+```ruby
+# Decode a Cardano Address
+addr_bech32 = "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x"
+address = CardanoBech32::Address.decode(addr_bech32)
+
+address.address_type         # => :base, :stake, :pointer, or :enterprise
+address.payment_credential   # => :key or :script (nil for stake/pointer-only addresses)
+address.stake_credential     # => :key or :script (nil if not applicable)
+address.network              # => network string derived from HRP
 ```
 
+#### Bech32 and Cardano Addresses
+
+Some Bech32 libraries may report the variant incorrectly (Bech32 / Bech32m), but for Cardano this does **not affect validity**.
+
+This library validates addresses based on:
+
+* The HRP (`addr`, `addr_test`, `stake`, etc.)
+* The header byte
+* The network id encoded in the payload
+
+Checksum and payload parsing are fully specification-compliant.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```
+bin/setup       # install dependencies
+rake spec       # run tests
+bin/console     # interactive console
+```
+
+To install locally:
+
+```
+bundle exec rake install
+```
+
+To release a new version:
+
+```
+# update version.rb
+bundle exec rake release
+```
+
+This creates a git tag, pushes commits, and uploads the gem to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cardano_bech32. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/cardano_bech32/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/lacepool/cardano-bech32.
+Please follow the [code of conduct](https://github.com/lacepool/cardano-bech32/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Cardano::Bech32 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/cardano_bech32/blob/main/CODE_OF_CONDUCT.md).

data/lib/cardano/bech32/address/abstract_address.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Cardano
+  module Bech32
+    module Address
+      # Abstract class for different types of Cardano Bech32 addresses
+      class AbstractAddress
+        attr_reader :hrp, :network, :payload_bytes, :header, :address_type, :payment_credential, :stake_credential
+
+        def initialize(hrp:, network:, payload_bytes:, header:)
+          @hrp           = hrp
+          @network       = network
+          @payload_bytes = payload_bytes
+          @header        = header
+
+          @address_type = Address.address_type(header)
+
+          @payment_credential = Address.payment_credential_kind(@header, @address_type)
+          @stake_credential   = Address.stake_credential_kind(@header, @address_type)
+        end
+
+        def base? = @address_type == :base
+        def pointer? = @address_type == :pointer
+        def enterprise? = @address_type == :enterprise
+        def stake? = @address_type == :stake
+
+        def script_payment? = @payment_credential == Address::Credential::SCRIPT
+        def script_stake? = @stake_credential == Address::Credential::SCRIPT
+      end
+    end
+  end
+end

data/lib/cardano/bech32/address/payment.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "abstract_address"
+
+module Cardano
+  module Bech32
+    module Address
+      class Payment < AbstractAddress; end
+    end
+  end
+end

data/lib/cardano/bech32/address/stake.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "abstract_address"
+
+module Cardano
+  module Bech32
+    module Address
+      class Stake < AbstractAddress; end
+    end
+  end
+end

data/lib/cardano/bech32/address.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "bech32"
+require_relative "address/payment"
+require_relative "address/stake"
+
+module Cardano
+  module Bech32
+    # Module for Cardano Bech32 addresses
+    module Address
+      module Credential
+        KEY    = :key
+        SCRIPT = :script
+      end
+
+      module Type
+        BASE       = :base
+        POINTER    = :pointer
+        ENTERPRISE = :enterprise
+        STAKE      = :stake
+      end
+
+      ADDRESS_TYPE_BY_HEADER = {
+        0b0000 => Type::BASE,
+        0b0001 => Type::BASE,
+        0b0010 => Type::BASE,
+        0b0011 => Type::BASE,
+        0b0100 => Type::POINTER,
+        0b0101 => Type::POINTER,
+        0b0110 => Type::ENTERPRISE,
+        0b0111 => Type::ENTERPRISE,
+        0b1110 => Type::STAKE,
+        0b1111 => Type::STAKE
+      }.freeze
+
+      def self.address_type(header)
+        high_nibble = high_nibble_from_header(header)
+
+        ADDRESS_TYPE_BY_HEADER.fetch(high_nibble) do
+          raise InvalidFormat, "Unknown header type: #{header.to_s(2)}"
+        end
+      end
+
+      # Payment credential: only exists for Base, Pointer, Enterprise
+      # Last bit of high nibble (0 = key, 1 = script)
+      def self.payment_credential_kind(header, address_type)
+        return nil if address_type == Type::STAKE
+
+        (high_nibble_from_header(header) & 0b0001).zero? ? Credential::KEY : Credential::SCRIPT
+      end
+
+      # Stake credential: varies by address type
+      def self.stake_credential_kind(header, address_type)
+        case address_type
+        when Type::STAKE
+          # last bit of high nibble: 0 = key, 1 = script
+          (high_nibble_from_header(header) & 0b0001).zero? ? Credential::KEY : Credential::SCRIPT
+        when Type::BASE
+          # third bit of high nibble: 1 = script, 0 = key
+          (high_nibble_from_header(header) & 0b0010).zero? ? Credential::KEY : Credential::SCRIPT
+        end
+      end
+
+      def self.network_symbol(header)
+        header & 0x0F == 1 ? :mainnet : :testnet
+      end
+
+      def self.high_nibble_from_header(header)
+        (header & 0b11110000) >> 4
+      end
+
+      def self.decode(bech32)
+        hrp, data = Cardano::Bech32.decode(bech32)
+        raise InvalidFormat, "invalid bech32 string" if hrp.nil? || data.nil?
+
+        # Convert 5-bit array to bytes
+        payload_bytes = Cardano::Bech32.convert_bits(data, from_bits: 5, to_bits: 8, pad: true)
+        raise InvalidPayload, "invalid payload length" unless payload_bytes.length.positive?
+
+        header = payload_bytes.first
+        type = address_type(header)
+        klass = type == :stake ? Stake : Payment
+
+        klass.new(
+          hrp: hrp,
+          network: network_symbol(header),
+          payload_bytes: payload_bytes,
+          header: header
+        )
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/abstract_credential.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "header"
+
+module Cardano
+  module Bech32
+    module GovCredentials
+      # Abstract base class for CIP-0129 governance credentials
+      #
+      # Header byte is authoritative and is interpreted exclusively
+      # via GovCredentials::Header.
+      class AbstractCredential
+        attr_reader :credential,
+                    :hash_bytes,
+                    :header_byte,
+                    :hrp,
+                    :key_type,
+                    :payload_bytes,
+                    :payload_hex
+
+        HASH_SIZE = 28
+
+        def initialize(hrp:, payload_bytes:)
+          @payload_bytes = payload_bytes
+          @header_byte   = payload_bytes.first
+          @credential    = Header.credential_type(@header_byte)
+          @hash_bytes    = payload_bytes[1..]
+          @hrp           = hrp
+          @key_type      = Header.key_type(@header_byte)
+          @payload_hex   = @payload_bytes.pack("C*").unpack1("H*").encode(Encoding::UTF_8)
+
+          validate!
+        end
+
+        # -----------------------------
+        # KeyType helpers
+        # -----------------------------
+
+        def key?    = @key_type == Header::KeyType::KEY
+        def script? = @key_type == Header::KeyType::SCRIPT
+
+        # Returns a JSON-safe hash representation
+        #
+        # @return [Hash]
+        def to_h
+          {
+            credential: @credential,
+            hash_bytes: @hash_bytes,
+            header_byte: @header_byte,
+            hrp: @hrp,
+            key_type: @key_type,
+            payload_bytes: @payload_bytes,
+            payload_hex: @payload_hex
+          }
+        end
+
+        private
+
+        # -----------------------------
+        # Validation
+        # -----------------------------
+
+        def validate!
+          unless @hash_bytes.length == HASH_SIZE
+            raise InvalidPayload,
+                  "invalid hash length: expected #{HASH_SIZE} bytes, got #{@hash_bytes.length}"
+          end
+
+          expected_hrp = Header.hrp(@header_byte)
+          unless @hrp == expected_hrp
+            raise InvalidFormat,
+                  "HRP mismatch: expected #{expected_hrp}, got #{@hrp}"
+          end
+
+          return if @payload_bytes.length > 1
+
+          raise InvalidPayload,
+                "payload must include header + hash, got #{@payload_bytes.length} bytes"
+        end
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/cc.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "abstract_credential"
+
+module Cardano
+  module Bech32
+    module GovCredentials
+      # Class for Cold and Hot CC credentials
+      class Cc < AbstractCredential
+        def hot?  = @key_type == Header::KeyType::CC_HOT
+        def cold? = @key_type == Header::KeyType::CC_COLD
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/decode.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "bech32"
+require_relative "cc"
+require_relative "drep"
+require_relative "header"
+require_relative "abstract_credential"
+
+module Cardano
+  module Bech32
+    # CIP-0129 Governance Credentials
+    module GovCredentials
+      class << self
+        # Decode a governance credential
+        #
+        # @param bech32 [String] Bech32 encoded governance credential
+        # @return [AbstractCredential, GovAction]
+        #
+        # Raises:
+        # - Cardano::Bech32::InvalidFormat
+        # - Cardano::Bech32::InvalidPayload
+        #
+        def decode(bech32)
+          hrp, data = Cardano::Bech32.decode(bech32)
+          raise InvalidFormat, "invalid bech32 string" if hrp.nil? || data.nil?
+
+          case hrp
+          when "gov_action"
+            GovAction.decode_from_data(data)
+          when "cc_hot", "cc_cold", "drep"
+            # when Header::HRP_BY_CREDENTIAL_TYPE.values
+            decode_credential(hrp, data)
+          else
+            raise InvalidFormat, "unknown governance HRP: #{hrp}"
+          end
+        end
+
+        private
+
+        def decode_credential(hrp, data)
+          payload_bytes =
+            Cardano::Bech32.convert_bits(data, from_bits: 5, to_bits: 8, pad: false)
+
+          raise InvalidPayload, "empty payload" if payload_bytes.empty?
+
+          header_byte = payload_bytes.first
+          credential_type = Header.credential_type(header_byte)
+
+          klass =
+            case credential_type
+            when Header::CredentialType::CC_HOT, Header::CredentialType::CC_COLD
+              Cc
+            when Header::CredentialType::DREP
+              Drep
+            else
+              raise InvalidFormat, "unknown governance credential header: #{header_byte}"
+            end
+
+          klass.new(hrp: hrp, payload_bytes: payload_bytes)
+        end
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/drep.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "abstract_credential"
+
+module Cardano
+  module Bech32
+    module GovCredentials
+      # Class for DRep credentials
+      class Drep < AbstractCredential; end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/encode.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "bech32"
+require_relative "header"
+require_relative "abstract_credential"
+
+module Cardano
+  module Bech32
+    # CIP-0129 Governance Credentials
+    module GovCredentials
+      class << self
+        #
+        # Encode a governance-related Bech32 object
+        #
+        # Supports:
+        # - Governance credentials (header + hash payload)
+        # - Governance actions (txid#index)
+        #
+        # @param payload [String, Array<Integer>] Hex string or byte array
+        # @return [String] Bech32 encoded governance credential
+        #
+        # Raises:
+        # - ArgumentError
+        #
+        def encode(input)
+          case input
+          when String
+            if gov_action_ref?(input)
+              GovAction.encode(input)
+            else
+              encode_credential(input)
+            end
+          when Array
+            encode_credential(input)
+          else
+            raise ArgumentError, "invalid input type: #{input.class}"
+          end
+        end
+
+        private
+
+        def encode_credential(payload)
+          bytes = bytes_from_payload(payload)
+          raise ArgumentError, "empty payload" if bytes.empty?
+
+          header_byte = bytes.first
+          hrp = Header.hrp(header_byte)
+          data = Cardano::Bech32.convert_bits(bytes, from_bits: 8, to_bits: 5, pad: true)
+
+          Cardano::Bech32.encode(hrp, data)
+        end
+
+        def gov_action_ref?(value)
+          value.include?("#")
+        end
+
+        def bytes_from_payload(payload)
+          case payload
+          when String
+            if payload.match?(/\A[0-9a-fA-F]+\z/) && payload.length.even?
+              [payload].pack("H*").bytes
+            else
+              payload.bytes
+            end
+          when Array
+            payload
+          else
+            raise ArgumentError, "invalid payload type: #{payload.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/gov_action.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "bech32"
+
+module Cardano
+  module Bech32
+    module GovCredentials
+      # Bech32 encoding for governance action references.
+      # A governance action reference is of the form "txid#index"
+      # where txid is a 32-byte hex string and index is a 0..255 integer
+      # The Bech32 encoding has HRP "gov_action" and a payload of 33 bytes:
+      # - 32 bytes: txid (binary)
+      # - 1 byte: index (binary)
+      #
+      class GovAction
+        HRP = "gov_action"
+        TX_ID_BYTES = 32
+        INDEX_BYTES = 1
+        TOTAL_BYTES = TX_ID_BYTES + INDEX_BYTES
+
+        attr_reader :tx_id, :index, :payload_bytes, :hrp
+
+        def initialize(hrp:, payload_bytes:)
+          @payload_bytes = payload_bytes
+          @index         = payload_bytes.last
+          @tx_id         = payload_bytes[0, TX_ID_BYTES].pack("C*").unpack1("H*").encode(Encoding::UTF_8)
+          @hrp           = hrp
+
+          validate!
+        end
+
+        def self.encode(tx_ref)
+          txid_hex, index_str = tx_ref.split("#", 2)
+          index = index_str.to_i if index_str
+
+          raise InvalidFormat, "expected txid#index" unless txid_hex && index
+          raise InvalidFormat, "invalid hex" unless txid_hex.match?(/\A[0-9a-fA-F]{64}\z/)
+
+          payload_bytes = [txid_hex].pack("H*").bytes + [index]
+
+          raise InvalidPayload, "invalid payload length" unless payload_bytes.length == TOTAL_BYTES
+          raise InvalidPayload, "index must be 0..255" unless index.between?(0, 255)
+
+          data = Cardano::Bech32.convert_bits(payload_bytes, from_bits: 8, to_bits: 5, pad: true)
+
+          Cardano::Bech32.encode(HRP, data)
+        end
+
+        def self.decode(bech32)
+          hrp, data = Cardano::Bech32.decode(bech32)
+          raise InvalidFormat, "invalid HRP" unless hrp == HRP
+
+          decode_from_data(data)
+        end
+
+        def self.decode_from_data(data)
+          bytes = Cardano::Bech32.convert_bits(data, from_bits: 5, to_bits: 8, pad: false)
+          raise InvalidPayload, "invalid payload length" unless bytes.length == TOTAL_BYTES
+
+          new(hrp: HRP, payload_bytes: bytes)
+        rescue ArgumentError
+          raise InvalidFormat, "invalid bech32 encoding"
+        end
+
+        def self.valid?(bech32)
+          decode(bech32)
+          true
+        rescue Error
+          false
+        end
+
+        def validate!
+          return if @payload_bytes.length == TOTAL_BYTES
+
+          raise InvalidPayload,
+                "invalid payload length: expected #{TOTAL_BYTES} bytes, got #{@payload_bytes.length}"
+        end
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials/header.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Cardano
+  module Bech32
+    module GovCredentials
+      # Header byte utilities for Governance credentials
+      module Header
+        #
+        # CIP-0129 Header byte layout:
+        #
+        #   7 6 5 4 | 3 2 1 0
+        #   --------+--------
+        #   credential type | key type
+        #
+        # High nibble (credential type):
+        #   0000 = CC Hot
+        #   0001 = CC Cold
+        #   0010 = DRep
+        #
+        # Lower nibble (key type):
+        #   0010 = Key hash
+        #   0011 = Script hash
+        #
+
+        # -----------------------------
+        # Key Types (upper nibble)
+        # -----------------------------
+
+        module CredentialType
+          CC_HOT  = :cc_hot
+          CC_COLD = :cc_cold
+          DREP    = :drep
+        end
+
+        CREDENTIAL_TYPE_BY_NIBBLE = {
+          0b0000 => CredentialType::CC_HOT,
+          0b0001 => CredentialType::CC_COLD,
+          0b0010 => CredentialType::DREP
+        }.freeze
+
+        NIBBLE_BY_CREDENTIAL_TYPE = CREDENTIAL_TYPE_BY_NIBBLE.invert.freeze
+
+        # -----------------------------
+        # Key Types (lower nibble)
+        # -----------------------------
+
+        module KeyType
+          KEY    = :key
+          SCRIPT = :script
+        end
+
+        KEY_TYPE_BY_NIBBLE = {
+          0b0010 => KeyType::KEY,
+          0b0011 => KeyType::SCRIPT
+        }.freeze
+
+        NIBBLE_BY_KEY_TYPE = KEY_TYPE_BY_NIBBLE.invert.freeze
+
+        # -----------------------------
+        # HRP Mapping (by key type)
+        # -----------------------------
+
+        HRP_BY_CREDENTIAL_TYPE = {
+          CredentialType::CC_HOT => "cc_hot",
+          CredentialType::CC_COLD => "cc_cold",
+          CredentialType::DREP => "drep"
+        }.freeze
+
+        # -----------------------------
+        # Public API
+        # -----------------------------
+
+        def self.credential_type(header)
+          nibble = high_nibble(header)
+
+          CREDENTIAL_TYPE_BY_NIBBLE.fetch(nibble) do
+            raise InvalidFormat, "Unknown governance credential type: #{nibble.to_s(2)}"
+          end
+        end
+
+        def self.key_type(header)
+          nibble = low_nibble(header)
+
+          KEY_TYPE_BY_NIBBLE.fetch(nibble) do
+            raise InvalidFormat, "Unknown governance key type: #{nibble.to_s(2)}"
+          end
+        end
+
+        def self.hrp(header)
+          HRP_BY_CREDENTIAL_TYPE.fetch(credential_type(header))
+        end
+
+        # -----------------------------
+        # Header Construction
+        # -----------------------------
+
+        def self.build(key_type:, credential:)
+          cred_nibble = NIBBLE_BY_CREDENTIAL_TYPE.fetch(credential) do
+            raise ArgumentError, "Invalid credential type: #{credential}"
+          end
+
+          key_nibble = NIBBLE_BY_KEY_TYPE.fetch(key_type) do
+            raise ArgumentError, "Invalid key type: #{key_type}"
+          end
+
+          ((cred_nibble << 4) | key_nibble) & 0xFF
+        end
+
+        # -----------------------------
+        # Bit Helpers
+        # -----------------------------
+
+        def self.high_nibble(header)
+          (header & 0b1111_0000) >> 4
+        end
+
+        def self.low_nibble(header)
+          header & 0b0000_1111
+        end
+      end
+    end
+  end
+end

data/lib/cardano/bech32/gov_credentials.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "gov_credentials/header"
+require_relative "gov_credentials/abstract_credential"
+require_relative "gov_credentials/cc"
+require_relative "gov_credentials/drep"
+require_relative "gov_credentials/gov_action"
+require_relative "gov_credentials/decode"
+require_relative "gov_credentials/encode"

data/lib/cardano/bech32/stake_pool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "bech32"
+
+module Cardano
+  module Bech32
+    # Module for encoding and decoding Cardano stake pool identifiers.
+    module StakePool
+      HRP = "pool"
+      POOL_HASH_LENGTH = 28 # bytes (blake2b-224)
+
+      module_function
+
+      # Encode a stake pool hash into Bech32.
+      #
+      # @param pool_hash [String] 56-char hex string or 28-byte binary string
+      # @return [String] Bech32 stake pool id
+      def encode(pool_hash)
+        raise InvalidPayload, "pool_hash must be a String" unless pool_hash.is_a?(String)
+
+        payload =
+          if pool_hash.encoding == Encoding::BINARY
+            pool_hash
+          elsif pool_hash.match?(/\A[0-9a-fA-F]{56}\z/)
+            [pool_hash].pack("H*")
+          else
+            raise InvalidPayload, "pool_hash must be 28 bytes or 56 hex chars"
+          end
+
+        raise InvalidPayload, "invalid pool hash length" unless payload.bytesize == POOL_HASH_LENGTH
+
+        data = Cardano::Bech32.convert_bits(payload.bytes, from_bits: 8, to_bits: 5, pad: true)
+        Cardano::Bech32.encode(HRP, data)
+      end
+
+      # Decode a Bech32 stake pool id.
+      #
+      # @param bech32 [String]
+      # @return [Hash] with keys :bytes (28-byte binary string) and :hex (56-char hex string)
+      def decode(bech32)
+        hrp, data = Cardano::Bech32.decode(bech32)
+
+        raise InvalidFormat, "invalid bech32 string" unless hrp && data
+        raise InvalidFormat, "invalid stake pool HRP: #{hrp}" unless hrp == HRP
+
+        bytes = Cardano::Bech32.convert_bits(data, from_bits: 5, to_bits: 8, pad: false)
+        raise InvalidPayload, "invalid payload" unless bytes
+        raise InvalidPayload, "invalid pool hash length" unless bytes.length == POOL_HASH_LENGTH
+
+        {
+          bytes: bytes.pack("C*"),
+          hex: bytes.pack("C*").unpack1("H*")
+        }
+      end
+
+      # Check whether a Bech32 string is a valid stake pool id.
+      #
+      # @param bech32 [String]
+      # @return [Boolean]
+      def valid?(bech32)
+        decode(bech32)
+        true
+      rescue Error
+        false
+      end
+    end
+  end
+end

data/lib/cardano/bech32/version.rb

@@ -2,6 +2,6 @@
 
 module Cardano
   module Bech32
-    VERSION = "0.3.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/cardano/bech32.rb

@@ -1,11 +1,50 @@
 # frozen_string_literal: true
 
-require_relative "bech32/version"
-require_relative "bech32/gov_action"
-
 module Cardano
+  # Bech32 module for encoding and decoding Cardano Bech32 identifiers.
   module Bech32
+    # Maximum length for a Bech32-encoded Cardano identifier.
+    # Chosen to be very high (2048) to allow all current and foreseeable
+    # identifiers while protecting against excessively long/malformed input.
+    MAX_BECH32_LENGTH = 2048
+
+    # Wrapper around bech32rb encode function.
+    # @param hrp [String] human-readable part
+    # @param data [Array<Integer>] data as array of integers
+    # @return [String] Bech32-encoded string
+    def self.encode(hrp, data)
+      ::Bech32.encode(hrp, data, ::Bech32::Encoding::BECH32)
+    end
+
+    # Wrapper around bech32rb decode function.
+    # @param bech32 [String]
+    # @return [Array(String, Array<Integer>), nil] human-readable part and data
+    def self.decode(bech32)
+      hrp, data, _spec = ::Bech32.decode(bech32, MAX_BECH32_LENGTH)
+      [hrp, data]
+    rescue StandardError
+      raise InvalidFormat, "invalid bech32 string"
+    end
+
+    # Convert bits between different bases.
+    # @param data [Array<Integer>] input data as array of integers
+    # @param from_bits [Integer] number of bits per input value
+    # @param to_bits [Integer] number of bits per output value
+    # @param pad [Boolean] whether to pad the output
+    # @return [Array<Integer>, nil] converted data as array of integers, or nil on failure
+    def self.convert_bits(data, from_bits: 5, to_bits: 8, pad: true)
+      ::Bech32.convert_bits(data, from_bits, to_bits, pad)
+    rescue StandardError
+      nil
+    end
+
     class Error < StandardError; end
-    # Your code goes here...
+    class InvalidFormat < Error; end
+    class InvalidPayload < Error; end
   end
 end
+
+require_relative "bech32/version"
+require_relative "bech32/address"
+require_relative "bech32/stake_pool"
+require_relative "bech32/gov_credentials"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cardano-bech32
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Robin Böning
@@ -53,7 +53,19 @@ files:
 - README.md
 - Rakefile
 - lib/cardano/bech32.rb
-- lib/cardano/bech32/gov_action.rb
+- lib/cardano/bech32/address.rb
+- lib/cardano/bech32/address/abstract_address.rb
+- lib/cardano/bech32/address/payment.rb
+- lib/cardano/bech32/address/stake.rb
+- lib/cardano/bech32/gov_credentials.rb
+- lib/cardano/bech32/gov_credentials/abstract_credential.rb
+- lib/cardano/bech32/gov_credentials/cc.rb
+- lib/cardano/bech32/gov_credentials/decode.rb
+- lib/cardano/bech32/gov_credentials/drep.rb
+- lib/cardano/bech32/gov_credentials/encode.rb
+- lib/cardano/bech32/gov_credentials/gov_action.rb
+- lib/cardano/bech32/gov_credentials/header.rb
+- lib/cardano/bech32/stake_pool.rb
 - lib/cardano/bech32/version.rb
 - sig/cardano/bech32.rbs
 homepage: https://github.com/lacepool/cardano-bech32

data/lib/cardano/bech32/gov_action.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-require "bech32"
-
-module Cardano
-  module Bech32
-    # Bech32 encoding for governance action references.
-    # A governance action reference is of the form "txid#index"
-    # where txid is a 32-byte hex string and index is a 0..255 integer
-    # The Bech32 encoding has HRP "gov_action" and a payload of 33 bytes:
-    # - 32 bytes: txid (binary)
-    # - 1 byte: index (binary)
-    #
-    module GovAction
-      HRP = "gov_action"
-      TX_ID_BYTES = 32
-      INDEX_BYTES = 1
-      TOTAL_BYTES = TX_ID_BYTES + INDEX_BYTES
-
-      class Error < StandardError; end
-      class InvalidFormat < Error; end
-      class InvalidPayload < Error; end
-
-      def self.encode(tx_ref)
-        txid_hex, index_str = tx_ref.split("#", 2)
-        raise InvalidFormat, "expected txid#index" unless txid_hex && index_str
-
-        txid_bytes = hex_to_bytes(txid_hex)
-        index = Integer(index_str)
-
-        raise InvalidPayload, "txid must be 32 bytes" unless txid_bytes.bytesize == TX_ID_BYTES
-        raise InvalidPayload, "index must be 0..255" unless index.between?(0, 255)
-
-        payload = txid_bytes + [index].pack("C")
-
-        # Convert to 5-bit array
-        # args: data (array of integers), from_bits, to_bits, pad (boolean)
-        data_5bit = ::Bech32.convert_bits(payload.bytes, 8, 5, true)
-        ::Bech32.encode(HRP, data_5bit, ::Bech32::Encoding::BECH32)
-      end
-
-      def self.decode(bech32)
-        hrp, data = ::Bech32.decode(bech32)
-        raise InvalidFormat, "invalid HRP" unless hrp == HRP
-
-        # Convert to 5-bit array
-        # args: data (array of integers), from_bits, to_bits, pad (boolean)
-        bytes = ::Bech32.convert_bits(data, 5, 8, false)
-        raise InvalidPayload, "invalid payload length" unless bytes.length == TOTAL_BYTES
-
-        {
-          tx_id: bytes_to_hex(bytes[0, TX_ID_BYTES]),
-          index: bytes.last
-        }
-      rescue ArgumentError
-        raise InvalidFormat, "invalid bech32 encoding"
-      end
-
-      def self.valid?(bech32)
-        decode(bech32)
-        true
-      rescue Error
-        false
-      end
-
-      def self.hex_to_bytes(hex)
-        raise InvalidFormat, "invalid hex" unless hex.match?(/\A[0-9a-fA-F]{64}\z/)
-
-        [hex].pack("H*")
-      end
-
-      def self.bytes_to_hex(bytes)
-        bytes.pack("C*").unpack1("H*")
-      end
-    end
-  end
-end