solace 0.1.5 → 0.1.6

data/lib/solace/utils/codecs.rb

@@ -24,23 +24,204 @@ module Solace
   # @see Solace::Keypair
   # @since 0.0.1
   module Utils
-    # Module for encoding and decoding data
+    # Module for encoding and decoding data.
+    #
+    # The helpers are grouped by category: base64/base58 string encodings,
+    # fixed-width little-endian integers, the Solana compact-u16 (shortvec)
+    # varint, length-prefixed byte/pubkey collections, and optionals.
+    #
+    # Serialization formats referenced below:
+    # - "Borsh" — the Anchor serialization spec. Borsh encodes `bool` as a single
+    #   0/1 byte, `Vec<T>`/`bytes` with a u32 little-endian length prefix, and
+    #   `Option<T>` as a 1-byte discriminant (0 = None, 1 = Some) followed by the
+    #   value. Methods that produce these layouts say so explicitly.
+    # - "SmallVec" — a Solana/Anchor-program convention (e.g. Squads) that prefixes
+    #   a collection with a u8 or u16 length instead of Borsh's u32. NOT Borsh.
+    # - "compact-u16" / "shortvec" — Solana's own variable-length integer used in
+    #   the transaction wire format. NOT Borsh.
+    #
+    # `extend self` exposes every method both as a module method
+    # (Solace::Utils::Codecs.<method>) and as an instance method when the module is
+    # included into a composed encoder/decoder.
     #
     # @since 0.0.1
     module Codecs
+      extend self
+
+      # --- Base64 -----------------------------------------------------------
+
       # Creates a StringIO from a base64 string.
       #
       # @param base64 [String] The base64 string to decode
       # @return [StringIO] A StringIO object containing the decoded bytes
-      def self.base64_to_bytestream(base64)
+      def base64_to_bytestream(base64)
         StringIO.new(Base64.decode64(base64))
       end
 
-      # Encodes a compact-u16 value in a compact form (shortvec)
+      # --- Base58 -----------------------------------------------------------
+
+      # Encodes a binary string in Base58 format.
+      #
+      # @param binary [String] The bytes to encode
+      # @return [String] The Base58 encoded string
+      def binary_to_base58(binary)
+        Base58.binary_to_base58(binary, :bitcoin)
+      end
+
+      # Decodes a Base58 string into a binary string
+      #
+      # @param string [String] The Base58 encoded string
+      # @return [String] The decoded binary string
+      def base58_to_binary(string)
+        base58_to_bytes(string).pack('C*')
+      end
+
+      # Encodes a byte array in Base58 format
+      #
+      # @param bytes [Array<Integer>] The bytes to encode
+      # @return [String] The Base58 encoded string
+      def bytes_to_base58(bytes)
+        binary_to_base58(bytes.pack('C*'))
+      end
+
+      # Decodes a Base58 string into a sequence of bytes
+      #
+      # @param string [String] The Base58 encoded string
+      # @return [Array<Integer>] The decoded bytes
+      def base58_to_bytes(string)
+        Base58.base58_to_binary(string, :bitcoin).bytes
+      end
+
+      # Checks if a string is a valid Base58 string
+      #
+      # @param string [String] The string to check
+      # @return [Boolean] True if the string is a valid Base58 string, false otherwise
+      def valid_base58?(string)
+        return false if string.nil? || string.empty?
+
+        Base58.decode(string)
+        true
+      rescue StandardError => _e
+        false
+      end
+
+      # --- Fixed-width little-endian integers -------------------------------
+
+      # Encodes a u8 as a single byte.
+      #
+      # @param byte [Integer] Value in range 0..255.
+      # @return [Array<Integer>] A single-element byte array.
+      def encode_u8(byte)
+        [byte]
+      end
+
+      # Decodes a u8 from 1 byte.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..255.
+      def decode_u8(stream)
+        stream.read(1).unpack1('C')
+      end
+
+      # Encodes a u16 as 2 little-endian bytes.
+      #
+      # @param u16 [Integer] Value in range 0..65535.
+      # @return [String] 2-byte little-endian binary string.
+      def encode_le_u16(u16)
+        [u16].pack('S<')
+      end
+
+      # Decodes a u16 from 2 little-endian bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..65535.
+      def decode_le_u16(stream)
+        stream.read(2).unpack1('S<')
+      end
+
+      # Encodes a u32 as 4 little-endian bytes.
+      #
+      # @param u32 [Integer] Value in range 0..4294967295.
+      # @return [String] 4-byte little-endian binary string.
+      def encode_le_u32(u32)
+        [u32].pack('L<')
+      end
+
+      # Decodes a u32 from 4 little-endian bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..4294967295.
+      def decode_le_u32(stream)
+        stream.read(4).unpack1('L<')
+      end
+
+      # Encodes a u64 value in little-endian format
+      #
+      # @param u64 [Integer] The u64 value to encode
+      # @return [String] The little-endian encoded u64 value
+      def encode_le_u64(u64)
+        [u64].pack('Q<') # 64-bit little-endian
+      end
+
+      # Decodes a little-endian u64 value from a sequence of bytes
+      #
+      # @param stream [IO, StringIO] The input to read bytes from.
+      # @return [Integer] The decoded u64 value
+      def decode_le_u64(stream)
+        stream.read(8).unpack1('Q<')
+      end
+
+      # Encodes a u128 as 16 little-endian bytes (two u64 words, low word first).
+      #
+      # @param u128 [Integer] Value in range 0..2**128-1.
+      # @return [String] 16-byte little-endian binary string.
+      def encode_le_u128(u128)
+        [u128 & 0xFFFFFFFFFFFFFFFF, u128 >> 64].pack('Q<Q<')
+      end
+
+      # Decodes a u128 from 16 little-endian bytes (two u64 words, low word first).
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..2**128-1.
+      def decode_le_u128(stream)
+        lo, hi = stream.read(16).unpack('Q<Q<')
+        lo + (hi << 64)
+      end
+
+      # Encodes an i64 as 8 little-endian bytes (two's complement).
+      #
+      # @param i64 [Integer] Value in range -2**63..2**63-1.
+      # @return [String] 8-byte little-endian binary string.
+      def encode_le_i64(i64)
+        [i64].pack('q<')
+      end
+
+      # Decodes an i64 from 8 little-endian bytes (two's complement).
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range -2**63..2**63-1.
+      def decode_le_i64(stream)
+        stream.read(8).unpack1('q<')
+      end
+
+      # --- Boolean ----------------------------------------------------------
+
+      # Encodes a Borsh bool as a single byte: false → 0, true → 1.
+      #
+      # @param bool [Boolean] The value to encode.
+      # @return [Array<Integer>] A single-element byte array.
+      def encode_bool(bool)
+        [bool ? 1 : 0]
+      end
+
+      # --- compact-u16 (Solana shortvec varint) -----------------------------
+
+      # Encodes an integer as a compact-u16 (shortvec) varint. This is Solana's
+      # transaction wire-format length prefix, NOT Borsh.
       #
       # @param u16 [Integer] The compact-u16 value to encode
       # @return [String] The compactly encoded compact-u16 value
-      def self.encode_compact_u16(u16)
+      def encode_compact_u16(u16)
         out = []
 
         loop do
@@ -74,23 +255,23 @@ module Solace
         out.pack('C*')
       end
 
-      # Decodes a compact-u16 (ShortVec) value from an IO-like object.
+      # Decodes a compact-u16 (shortvec) value from an IO-like object.
       #
       # Reads bytes one at a time, accumulating the result until the MSB is 0.
       #
       # @param stream [IO, StringIO] The input to read bytes from.
       # @return [Integer, Integer] The decoded value and the number of bytes read.
-      def self.decode_compact_u16(stream)
-        value = 0
-        shift = 0
+      def decode_compact_u16(stream)
+        value      = 0
+        shift      = 0
         bytes_read = 0
 
         loop do
           byte = stream.read(1)
           raise EOFError, 'Unexpected end of input while decoding compact-u16' unless byte
 
-          byte = byte.ord
-          value |= (byte & 0x7F) << shift
+          byte        = byte.ord
+          value      |= (byte & 0x7F) << shift
           bytes_read += 1
           break if byte.nobits?(0x80)
 
@@ -100,65 +281,144 @@ module Solace
         [value, bytes_read]
       end
 
-      # Encodes a u64 value in little-endian format
+      # --- Length-prefixed byte sequences -----------------------------------
+
+      # Encodes a Borsh bytes field / Vec<u8>: u32 LE length prefix + raw bytes.
       #
-      # @param u64 [Integer] The u64 value to encode
-      # @return [String] The little-endian encoded u64 value
-      def self.encode_le_u64(u64)
-        [u64].pack('Q<') # 64-bit little-endian
+      # @param bytes [Array<Integer>] The raw bytes.
+      # @return [Array<Integer>]
+      def encode_bytes(bytes)
+        encode_le_u32(bytes.length).bytes + bytes
       end
 
-      # Decodes a little-endian u64 value from a sequence of bytes
+      # Decodes a Borsh bytes / Vec<u8> field: u32 LE length prefix + raw bytes.
       #
-      # @param stream [IO, StringIO] The input to read bytes from.
-      # @return [Integer] The decoded u64 value
-      def self.decode_le_u64(stream)
-        stream.read(8).unpack1('Q<')
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String] The raw bytes as a binary string.
+      def decode_bytes(stream)
+        stream.read(decode_le_u32(stream))
       end
 
-      # Encodes a sequence of bytes in Base58 format
+      # Encodes a SmallVec<u8, u8>: u8 length prefix + raw bytes. SmallVec is a
+      # Solana/Anchor-program convention, NOT Borsh (which would use a u32 prefix).
       #
-      # @param binary [String] The bytes to encode
-      # @return [String] The Base58 encoded string
-      def self.binary_to_base58(binary)
-        Base58.binary_to_base58(binary, :bitcoin)
+      # @param bytes [Array<Integer>] The raw bytes (max 255).
+      # @return [Array<Integer>]
+      def encode_smallvec_u8_bytes(bytes)
+        [bytes.length] + bytes
       end
 
-      # Decodes a Base58 string into a binary string
+      # Encodes a SmallVec<u16, u8>: u16 LE length prefix + raw bytes. SmallVec is a
+      # Solana/Anchor-program convention, NOT Borsh (which would use a u32 prefix).
       #
-      # @param string [String] The Base58 encoded string
-      # @return [String] The decoded binary string
-      def self.base58_to_binary(string)
-        base58_to_bytes(string).pack('C*')
+      # @param bytes [Array<Integer>] The raw bytes (max 65535).
+      # @return [Array<Integer>]
+      def encode_smallvec_u16_bytes(bytes)
+        encode_le_u16(bytes.length).bytes + bytes
       end
 
-      # Encodes a sequence of bytes in Base58 format
+      # --- Public keys ------------------------------------------------------
+
+      # Encodes a public key as 32 raw bytes (a Solana primitive, not a Borsh
+      # type). Accepts any representation that resolves to a base58 string via
+      # #to_s (String, Keypair, PublicKey).
       #
-      # @param bytes [String] The bytes to encode
-      # @return [String] The Base58 encoded string
-      def self.bytes_to_base58(bytes)
-        binary_to_base58(bytes.pack('C*'))
+      # @param pubkey [#to_s] The public key in any representation.
+      # @return [Array<Integer>] 32 bytes.
+      def encode_pubkey(pubkey)
+        base58_to_bytes(pubkey.to_s)
       end
 
-      # Decodes a Base58 string into a sequence of bytes
+      # Decodes a public key from 32 bytes.
       #
-      # @param string [String] The Base58 encoded string
-      # @return [String] The decoded bytes
-      def self.base58_to_bytes(string)
-        Base58.base58_to_binary(string, :bitcoin).bytes
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String] Base58 public key.
+      def decode_pubkey(stream)
+        bytes_to_base58(stream.read(32).bytes)
       end
 
-      # Checks if a string is a valid Base58 string
+      # Encodes a Borsh Vec<publicKey>: u32 LE count prefix followed by each
+      # 32-byte pubkey.
       #
-      # @param string [String] The string to check
-      # @return [Boolean] True if the string is a valid Base58 string, false otherwise
-      def self.valid_base58?(string)
-        return false if string.nil? || string.empty?
+      # @param pubkeys [Array<#to_s>] The public keys in any representation.
+      # @return [Array<Integer>]
+      def encode_vec_pubkeys(pubkeys)
+        encode_le_u32(pubkeys.length).bytes +
+          pubkeys.flat_map { |pubkey| encode_pubkey(pubkey) }
+      end
 
-        Base58.decode(string)
-        true
-      rescue StandardError => _e
-        false
+      # Decodes a Borsh Vec<publicKey>: u32 LE count prefix followed by each
+      # 32-byte pubkey.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Array<String>] Base58 public keys.
+      def decode_vec_pubkeys(stream)
+        Array.new(decode_le_u32(stream)) { decode_pubkey(stream) }
+      end
+
+      # Encodes a SmallVec<u8, Pubkey>: u8 count prefix followed by each 32-byte
+      # pubkey. SmallVec is a Solana convention (NOT Borsh); used by the
+      # transaction message header's account_keys (distinct from
+      # encode_vec_pubkeys, which uses Borsh's u32 count).
+      #
+      # @param pubkeys [Array<#to_s>] The public keys in any representation (max 255).
+      # @return [Array<Integer>]
+      def encode_smallvec_u8_pubkeys(pubkeys)
+        [pubkeys.length] + pubkeys.flat_map { |pubkey| encode_pubkey(pubkey) }
+      end
+
+      # --- Optionals (Borsh Option<T>) --------------------------------------
+
+      # Encodes a Borsh Option<publicKey>: None → [0], Some(key) → [1] + 32 bytes.
+      #
+      # @param pubkey [#to_s, nil] Base58 public key or nil.
+      # @return [Array<Integer>]
+      def encode_option_pubkey(pubkey)
+        return [0] if pubkey.nil?
+
+        [1] + encode_pubkey(pubkey)
+      end
+
+      # Decodes a Borsh Option<publicKey>: None → nil, Some(key) → base58 pubkey.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String, nil] Base58 public key or nil.
+      def decode_option_pubkey(stream)
+        return nil if decode_u8(stream).zero?
+
+        decode_pubkey(stream)
+      end
+
+      # Encodes a Borsh Option<i64>: None → [0], Some(i64) → [1] + 8 LE bytes.
+      #
+      # @param i64 [Integer, nil]
+      # @return [Array<Integer>]
+      def encode_option_i64(i64)
+        return [0] if i64.nil?
+
+        [1] + encode_le_i64(i64).bytes
+      end
+
+      # Decodes a Borsh Option<i64>: None → nil, Some(i64) → integer.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer, nil]
+      def decode_option_i64(stream)
+        return nil if decode_u8(stream).zero?
+
+        decode_le_i64(stream)
+      end
+
+      # Encodes a Borsh Option<String>:
+      # None → [0], Some(str) → [1] + u32 LE length + UTF-8 bytes.
+      #
+      # @param str [String, nil]
+      # @return [Array<Integer>]
+      def encode_option_string(str)
+        return [0] if str.nil?
+
+        bytes = str.encode('UTF-8').bytes
+        [1] + encode_le_u32(bytes.length).bytes + bytes
       end
     end
   end

data/lib/solace/utils/rpc_client.rb

@@ -35,7 +35,7 @@ module Solace
         open_timeout:,
         read_timeout:
       )
-        @url = url
+        @url          = url
         @open_timeout = open_timeout
         @read_timeout = read_timeout
       end
@@ -52,7 +52,7 @@ module Solace
       #   Solace::Errors::ConfirmationTimeout
       # ]
       def rpc_request(method, params = [])
-        request = build_rpc_request(method, params)
+        request  = build_rpc_request(method, params)
         response = perform_http_request(*request)
         handle_rpc_response(response)
       end
@@ -67,10 +67,10 @@ module Solace
       def build_rpc_request(method, params)
         uri = URI(url)
 
-        req = Net::HTTP::Post.new(uri)
-        req['Accept'] = 'application/json'
+        req                 = Net::HTTP::Post.new(uri)
+        req['Accept']       = 'application/json'
         req['Content-Type'] = 'application/json'
-        req.body = build_request_body(method, params)
+        req.body            = build_request_body(method, params)
 
         [uri, req]
       end
@@ -83,9 +83,9 @@ module Solace
       def build_request_body(method, params)
         {
           jsonrpc: '2.0',
-          id: SecureRandom.uuid,
-          method: method,
-          params: params
+          id:      SecureRandom.uuid,
+          method:  method,
+          params:  params
         }.to_json
       end
 
@@ -99,7 +99,7 @@ module Solace
         Net::HTTP.start(
           uri.hostname,
           uri.port,
-          use_ssl: uri.scheme == 'https',
+          use_ssl:      uri.scheme == 'https',
           open_timeout: open_timeout,
           read_timeout: read_timeout
         ) do |http|

data/lib/solace/version.rb

@@ -2,5 +2,5 @@
 
 module Solace
   # Latest version of the Solace gem.
-  VERSION = '0.1.5'
+  VERSION = '0.1.6'
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Sebastian Scholl
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base58
@@ -51,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +108,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tty-spinner
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +164,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Ruby library for working with Solana blockchain. Provides both low-level
   instruction builders and high-level program clients for interacting with Solana
   programs.
@@ -102,9 +201,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG
-- LICENSE
-- README.md
 - lib/solace.rb
 - lib/solace/address_lookup_table.rb
 - lib/solace/composers/associated_token_account_program_create_account_composer.rb
@@ -182,10 +278,15 @@ files:
 - lib/solace/utils/pda.rb
 - lib/solace/utils/rpc_client.rb
 - lib/solace/version.rb
-homepage: https://github.com/sebscholl/solace
+homepage: https://github.com/zarpay/solace
 licenses:
 - MIT
-metadata: {}
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/zarpay/solace
+  changelog_uri: https://github.com/zarpay/solace/blob/main/CHANGELOG
+  documentation_uri: https://zarpay.github.io/solace
+  rubygems_mfa_required: 'true'
 post_install_message: |2+
 
   Thank you for installing Solace!
@@ -193,7 +294,7 @@ post_install_message: |2+
   This gem includes native binaries for curve25519 operations.
   If you encounter any issues with native library loading,
   please check that your platform is supported or file an issue at:
-  https://github.com/sebscholl/solace/issues
+  https://github.com/zarpay/solace/issues
 
 rdoc_options: []
 require_paths:
@@ -209,7 +310,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Solana ruby library
 test_files: []