Borsh for Ruby

Borsh.rb is a Ruby library for encoding and decoding data in the Borsh binary serialization format designed for security-critical projects where consistency, safety, and performance matter.

✨ Features

100% pure Ruby with zero dependencies and no bloat.
Implements the full Borsh specification with support for every type.
Supports both in-memory buffers and I/O streams for serialization.
Provides a simple and intuitive API for reading and writing data.
Provides a convenient buffer interface layered on top of StringIO.
Supports customizable serialization using the #to_borsh protocol.
Plays nice with others: entirely contained in the Borsh module.
100% free and unencumbered public domain software.

🛠️ Prerequisites

Ruby 2.6+

⬇️ Installation

Installation via RubyGems

gem install borsh

👉 Examples

Importing the library

require 'borsh'

Writing to an in-memory buffer

serialized_data = Borsh::Buffer.open do |buf|
  # Primitive types:
  buf.write_bool(true)
  buf.write_u8(255)
  buf.write_i32(-12345)
  buf.write_u128(2**100)
  buf.write_i128(-2**100)
  buf.write_f64(3.14159)
  buf.write_string("Hello, Borsh!")

  # Fixed-size array:
  buf.write_array([1, 2, 3])

  # Dynamic-sized array (array with a length prefix):
  buf.write_vector(['a', 'b', 'c'])

  # Set of integers:
  buf.write_set(Set.new([1, 2, 3]))

  # Map with string keys and integer values:
  buf.write_map({a: 1, b: 2})
end

Reading from an in-memory buffer

Borsh::Buffer.new(serialized_data) do |buf|
  # Primitive types:
  bool_val = buf.read_bool             # => true
  u8_val = buf.read_u8                 # => 255
  i32_val = buf.read_i32               # => -12345
  u128_val = buf.read_u128             # => 2**100
  i128_val = buf.read_i128             # => -2**100
  f64_val = buf.read_f64               # => 3.14159
  string_val = buf.read_string         # => "Hello, Borsh!"

  # Fixed-size array:
  array = buf.read_array(:i64, 3)      # => [1, 2, 3]

  # Dynamic-sized array (array with a length prefix):
  vector = buf.read_vector(:string)    # => ['a', 'b', 'c']

  # Set of integers:
  set = buf.read_set(:i64)             # => Set.new([1, 2, 3])

  # Map with string keys and integer values:
  map = buf.read_map(:string, :i64)    # => {'a' => 1, 'b' => 2}
end

Writing to any output stream

$stdout.extend(Borsh::Writable)
$stdout.write_string("Hello, world!")

Reading from any input stream

$stdin.extend(Borsh::Readable)
puts $stdin.read_string

📚 Reference

Informal Type	`Borsh::Writable`	`Borsh::Readable`
nil/unit	`write_unit()`	`read_unit()`
boolean	`write_bool(x)`	`read_bool()`
u8 integer	`write_u8(n)`	`read_u8()`
u16 integer	`write_u16(n)`	`read_u16()`
u32 integer	`write_u32(n)`	`read_u32()`
u64 integer	`write_u64(n)`	`read_u64()`
u128 integer	`write_u128(n)`	`read_u128()`
i8 integer	`write_i8(n)`	`read_i8()`
i16 integer	`write_i16(n)`	`read_i16()`
i32 integer	`write_i32(n)`	`read_i32()`
i64 integer	`write_i64(n)`	`read_i64()`
i128 integer	`write_i128(n)`	`read_i128()`
f32 float	`write_f32(f)`	`read_f32()`
f64 float	`write_f64(f)`	`read_f64()`
string	`write_string(x)`	`read_string()`
array	`write_array(x)`	`read_array(element_type, count)`
vector	`write_vector(x)`	`read_vector(element_type)`
set	`write_set(x)`	`read_set(element_type)`
map/hash	`write_map(x)`	`read_map(key_type, value_type)`
option	`write_option(x)`	`read_option(element_type)`
result	`write_result([ok, value])`	`read_result(ok_type, err_type)`
enum	`write_enum([ordinal, value])`	`read_enum(variants)`
struct	`write_struct(x)`	`read_struct(struct_class)`

👨‍💻 Development

git clone https://github.com/dryruby/borsh.rb.git