cardano-bech32 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61879ba04ac1f386b78a11a2627b3517b503153030fa714066e46d63ffaf1ca6
+  data.tar.gz: 5fdac5c7012890bb2eec29d1ed10162806c13657e7db539b05f38583312eb8da
+SHA512:
+  metadata.gz: eaba40171f236c8887414261a9063c9139c016331a1ed37984684c145655dd701c43a0963eb99888f83c2b6a27bf2c1d7a845c88e78582ff2f45b38910b6b8fd
+  data.tar.gz: b9f1737243afdfb79c5d19748c7cbbbabcab019ae29262569dc01c79ec21c4e4f3bcddfb1500dac5b6a3d0ef25bce23796ee88a20e1b33b494bd3dfffe69620a

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-29
+
+### Added
+- Initial release of `cardano-bech32`
+- Encoding of Cardano Governance Action IDs (`gov_action`) as defined in CIP-0129
+- 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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"cardano_bech32" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["robin.boening@gmail.com"](mailto:"robin.boening@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Robin Böning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# CardanoBech32
+
+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.
+
+Currently supported
+
+- [x] Governance Action IDs (gov_action) — [CIP-0129](https://cips.cardano.org/cip/CIP-0129)
+- [ ] Addresses
+- [ ] Stake pool IDs
+- [ ] DRep 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:
+
+```sh
+gem "cardano-bech32"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install cardano-bech32
+```
+
+## Usage
+
+### Governance Action IDs (CIP-0129)
+
+A Governance Action ID is derived as:
+tx_id (32 bytes) || index (1 byte)
+→ Bech32 encode with HRP "gov_action"
+
+#### Encoding
+
+```ruby
+require "cardano_bech32"
+
+txref = "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5#0"
+
+CardanoBech32::GovAction.encode(txref)
+# => "gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn"
+```
+
+#### Decoding
+
+```ruby
+CardanoBech32::GovAction.decode(
+  "gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn"
+)
+# => {
+  tx_id: "b2a591ac219ce6dcca5847e0248015209c7cb0436aa6bd6863d0c1f152a60bc5",
+  index: 0
+}
+```
+
+#### Validation
+
+Validation checks:
+* Bech32 checksum
+* Correct HRP (gov_action)
+* Correct payload length (33 bytes)
+
+```ruby
+CardanoBech32::GovAction.valid?("gov_action1k2jertppnnndejjcglszfqq4yzw8evzrd2nt66rr6rqlz54xp0zsq05ecsn")
+# => true
+```
+
+### Error Handling
+
+The library normalizes all Bech32 decoding and validation failures into
+explicit, typed errors:
+
+* InvalidFormat — malformed input, wrong HRP, invalid Bech32
+* InvalidPayload — incorrect byte length, invalid index
+
+```ruby
+# Example
+begin
+  CardanoBech32::GovAction.encode("invalid")
+rescue CardanoBech32::GovAction::Error => e
+  puts e.message
+end
+
+```
+
+## 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.
+
+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).
+
+## 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).
+
+## 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 CardanoBech32 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/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/cardano_bech32/gov_action.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "bech32"
+
+module CardanoBech32
+  # 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

data/lib/cardano_bech32/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CardanoBech32
+  VERSION = "0.1.0"
+end

data/lib/cardano_bech32.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "cardano_bech32/version"
+require_relative "cardano_bech32/gov_action"
+
+module CardanoBech32
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/cardano_bech32.rbs

@@ -0,0 +1,4 @@
+module CardanoBech32
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: cardano-bech32
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robin Böning
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bech32
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |
+  A small, focused Ruby library for encoding and decoding Cardano Bech32 identifiers.
+  The gem intentionally limits its scope to specification-compliant Bech32
+  handling and avoids higher-level ledger or transaction concerns.
+email:
+- robin.boening@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/cardano_bech32.rb
+- lib/cardano_bech32/gov_action.rb
+- lib/cardano_bech32/version.rb
+- sig/cardano_bech32.rbs
+homepage: https://github.com/lacepool/cardano-bech32
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lacepool/cardano-bech32
+  source_code_uri: https://github.com/lacepool/cardano-bech32
+  changelog_uri: https://github.com/lacepool/cardano-bech32/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Bech32 encoding and decoding for Cardano identifiers
+test_files: []