solana-ruby-kit 0.1.0

data/lib/solana/ruby/kit/codecs/strings.rb

@@ -0,0 +1,116 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+
+module Solana::Ruby::Kit
+  module Codecs
+    # String codecs — mirrors @solana/codecs-strings.
+    module Strings
+      extend T::Sig
+
+      module_function
+
+      # UTF-8 string codec.
+      # When +size+ is given the encoded bytes are fixed to that length
+      # (zero-padded or truncated); otherwise the codec is variable-length
+      # and must be used inside a size-prefixed container.
+      sig { params(size: T.nilable(Integer)).returns(Codec) }
+      def utf8_codec(size: nil)
+        enc = Encoder.new(fixed_size: size) do |v|
+          raw = v.to_s.encode('UTF-8').b
+          if size
+            raw.bytesize <= size ? raw.ljust(size, "\x00") : raw.byteslice(0, size) || ''.b
+          else
+            raw
+          end
+        end
+        dec = Decoder.new(fixed_size: size) do |bytes, offset|
+          len   = size || (bytes.bytesize - offset)
+          slice = bytes.b.byteslice(offset, len) || ''.b
+          # Strip null padding for fixed-size strings
+          str   = size ? slice.delete_suffix("\x00" * slice.bytesize.times.take_while { |i| slice.b[-1 - i] == "\x00" }.length) : slice
+          [str.force_encoding('UTF-8'), len]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Base58 codec — uses Solana::Ruby::Kit::Encoding::Base58.
+      sig { returns(Codec) }
+      def base58_codec
+        enc = Encoder.new do |v|
+          Solana::Ruby::Kit::Encoding::Base58.decode(v.to_s)
+        end
+        dec = Decoder.new do |bytes, offset|
+          remaining = bytes.b.byteslice(offset..) || ''.b
+          [Solana::Ruby::Kit::Encoding::Base58.encode(remaining), remaining.bytesize]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Base64 codec — strict (no newlines).
+      sig { returns(Codec) }
+      def base64_codec
+        enc = Encoder.new do |v|
+          Base64.strict_encode64(v.to_s)
+        end
+        dec = Decoder.new do |bytes, offset|
+          remaining = bytes.b.byteslice(offset..) || ''.b
+          [Base64.strict_decode64(remaining.force_encoding('ASCII')), remaining.bytesize]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Hex codec — lower-case hex string ↔ binary bytes.
+      sig { returns(Codec) }
+      def hex_codec
+        enc = Encoder.new do |v|
+          [v.to_s.tr(' ', '')].pack('H*')
+        end
+        dec = Decoder.new do |bytes, offset|
+          remaining = bytes.b.byteslice(offset..) || ''.b
+          [remaining.unpack1('H*'), remaining.bytesize]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Fixed-size raw bytes passthrough.
+      sig { params(size: Integer).returns(Codec) }
+      def bytes_codec(size)
+        enc = Encoder.new(fixed_size: size) do |v|
+          b = v.is_a?(String) ? v.b : v.to_s.b
+          Kernel.raise ArgumentError, "Expected #{size} bytes, got #{b.bytesize}" if b.bytesize != size
+
+          b
+        end
+        dec = Decoder.new(fixed_size: size) do |bytes, offset|
+          slice = bytes.b.byteslice(offset, size) || ''.b
+          [slice, size]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Bit-array codec.
+      # Encodes an Array of booleans into +size+ bytes (LSB-first within each byte).
+      sig { params(size: Integer).returns(Codec) }
+      def bit_array_codec(size)
+        total_bits = size * 8
+        enc = Encoder.new(fixed_size: size) do |bits|
+          arr   = T.cast(bits, T::Array[T::Boolean])
+          bytes = Array.new(size, 0)
+          arr.first(total_bits).each_with_index do |bit, idx|
+            bytes[idx / 8] |= (1 << (idx % 8)) if bit
+          end
+          bytes.pack('C*')
+        end
+        dec = Decoder.new(fixed_size: size) do |bytes, offset|
+          slice = bytes.b.byteslice(offset, size) || ''.b
+          byte_arr = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
+          bits = byte_arr.flat_map { |byte| 8.times.map { |i| byte[i] == 1 } }
+          [bits, size]
+        end
+        Codec.new(enc, dec)
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/codecs.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'set'
+
+# Codec system — mirrors @solana/codecs.
+# Provides Encoder, Decoder, and Codec classes plus helpers for numbers,
+# strings, and composite data structures.
+require_relative 'codecs/bytes'
+require_relative 'codecs/encoder'
+require_relative 'codecs/decoder'
+require_relative 'codecs/codec'
+require_relative 'codecs/numbers'
+require_relative 'codecs/strings'
+require_relative 'codecs/data_structures'
+
+module Solana::Ruby::Kit
+  module Codecs
+    # Make number helpers directly available as Codecs.u8_codec etc.
+    extend Numbers
+    extend Strings
+    extend DataStructures
+    extend Bytes
+  end
+end

data/lib/solana/ruby/kit/configuration.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  class Configuration
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :rpc_url
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :ws_url
+
+    sig { returns(Symbol) }
+    attr_reader :commitment
+
+    sig { returns(Integer) }
+    attr_reader :timeout
+
+    sig { void }
+    def initialize
+      @rpc_url    = T.let('https://api.mainnet-beta.solana.com', String)
+      @ws_url     = T.let(nil, T.nilable(String))
+      @commitment  = T.let(:confirmed, Symbol)
+      @timeout    = T.let(30, Integer)
+    end
+
+    sig { params(value: String).void }
+    def rpc_url=(value)
+      @rpc_url = value
+    end
+
+    sig { params(value: T.nilable(String)).void }
+    def ws_url=(value)
+      @ws_url = value
+    end
+
+    sig { params(value: Symbol).void }
+    def commitment=(value)
+      @commitment = value
+    end
+
+    sig { params(value: Integer).void }
+    def timeout=(value)
+      @timeout = value
+    end
+  end
+end

data/lib/solana/ruby/kit/encoding/base58.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Encoding
+    # Base58 codec using the Bitcoin/Solana alphabet (no check bytes).
+    # This module provides the shared base58 encoding used by both
+    # Solana::Ruby::Kit::Addresses and Solana::Ruby::Kit::Keys::Signatures.
+    module Base58
+      extend T::Sig
+      ALPHABET = T.let(
+        '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz',
+        String
+      )
+
+      module_function
+
+      # Encodes a binary String to a base58 string.
+      sig { params(bytes: String).returns(String) }
+      def encode(bytes)
+        # Each leading zero byte maps to a leading '1'.
+        leading_ones = 0
+        bytes.each_byte { |b| b == 0 ? leading_ones += 1 : break }
+
+        # Convert big-endian byte string to an integer.
+        n = bytes.unpack1('H*').to_i(16)
+
+        result = +''
+        while n > 0
+          result.prepend(T.must(ALPHABET[n % 58]))
+          n /= 58
+        end
+
+        ('1' * leading_ones) + result
+      end
+
+      # Decodes a base58 string to a binary String.
+      # Raises ArgumentError if the string contains characters not in the alphabet.
+      sig { params(str: String).returns(String) }
+      def decode(str)
+        # Each leading '1' maps to a leading zero byte.
+        leading_zeros = 0
+        str.each_char { |c| c == '1' ? leading_zeros += 1 : break }
+
+        n = 0
+        str.each_char do |c|
+          idx = ALPHABET.index(c)
+          Kernel.raise ArgumentError, "Invalid base58 character: #{c.inspect}" if idx.nil?
+
+          n = n * 58 + idx
+        end
+
+        # Convert integer back to a big-endian byte string.
+        hex = n.zero? ? '' : n.to_s(16)
+        hex = hex.rjust((hex.length + 1) & ~1, '0')  # guarantee even hex length
+
+        raw = [hex].pack('H*')
+        ("\x00" * leading_zeros + raw).b
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/errors.rb

@@ -0,0 +1,226 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  # Maps TypeScript's SolanaError pattern to Ruby exceptions.
+  # Each error code corresponds to a constant and carries structured context.
+  # Mirrors @solana/errors codes.ts + messages.ts.
+  class SolanaError < StandardError
+    extend T::Sig
+
+    # ── General ──────────────────────────────────────────────────────────────
+    INVALID_KEYPAIR_SEED_LENGTH                          = :SOLANA_ERROR__INVALID_KEYPAIR_SEED_LENGTH
+    INVALID_NONCE                                        = :SOLANA_ERROR__INVALID_NONCE
+
+    # ── Addresses ─────────────────────────────────────────────────────────────
+    ADDRESSES__INVALID_BASE58_ENCODED_ADDRESS            = :SOLANA_ERROR__ADDRESSES__INVALID_BASE58_ENCODED_ADDRESS
+    ADDRESSES__INVALID_BYTE_LENGTH_FOR_ADDRESS           = :SOLANA_ERROR__ADDRESSES__INVALID_BYTE_LENGTH_FOR_ADDRESS
+    ADDRESSES__STRING_LENGTH_OUT_OF_RANGE                = :SOLANA_ERROR__ADDRESSES__STRING_LENGTH_OUT_OF_RANGE_FOR_ADDRESS
+    ADDRESSES__INVALID_ED25519_PUBLIC_KEY                = :SOLANA_ERROR__ADDRESSES__INVALID_ED25519_PUBLIC_KEY
+    ADDRESSES__SEEDS_POINT_ON_CURVE                      = :SOLANA_ERROR__ADDRESSES__SEEDS_POINT_ON_CURVE
+    ADDRESSES__MAX_SEED_LENGTH_EXCEEDED                  = :SOLANA_ERROR__ADDRESSES__MAX_SEED_LENGTH_EXCEEDED
+    ADDRESSES__TOO_MANY_SEEDS                            = :SOLANA_ERROR__ADDRESSES__TOO_MANY_SEEDS
+    ADDRESSES__FAILED_TO_FIND_VIABLE_PDA_BUMP_SEED       = :SOLANA_ERROR__ADDRESSES__FAILED_TO_FIND_VIABLE_PDA_BUMP_SEED
+    ADDRESSES__INVALID_SEEDS_POINT_ON_CURVE              = :SOLANA_ERROR__ADDRESSES__INVALID_SEEDS_POINT_ON_CURVE
+    ADDRESSES__PDA_BUMP_SEED_OUT_OF_RANGE                = :SOLANA_ERROR__ADDRESSES__PDA_BUMP_SEED_OUT_OF_RANGE
+
+    # ── Accounts ──────────────────────────────────────────────────────────────
+    ACCOUNTS__ACCOUNT_NOT_FOUND                          = :SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND
+    ACCOUNTS__ONE_OR_MORE_ACCOUNTS_NOT_FOUND             = :SOLANA_ERROR__ACCOUNTS__ONE_OR_MORE_ACCOUNTS_NOT_FOUND
+    ACCOUNTS__EXPECTED_DECODED_ACCOUNT                   = :SOLANA_ERROR__ACCOUNTS__EXPECTED_DECODED_ACCOUNT
+    ACCOUNTS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED        = :SOLANA_ERROR__ACCOUNTS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED
+    ACCOUNTS__FAILED_TO_DECODE_ACCOUNT                   = :SOLANA_ERROR__ACCOUNTS__FAILED_TO_DECODE_ACCOUNT
+
+    # ── Keys ──────────────────────────────────────────────────────────────────
+    KEYS__INVALID_KEY_PAIR_BYTE_LENGTH                   = :SOLANA_ERROR__KEYS__INVALID_KEY_PAIR_BYTE_LENGTH
+    KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY              = :SOLANA_ERROR__KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY
+    KEYS__INVALID_SIGNATURE_BYTE_LENGTH                  = :SOLANA_ERROR__KEYS__INVALID_SIGNATURE_BYTE_LENGTH
+    KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE           = :SOLANA_ERROR__KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE
+
+    # ── Instructions ──────────────────────────────────────────────────────────
+    INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS              = :SOLANA_ERROR__INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS
+    INSTRUCTIONS__EXPECTED_TO_HAVE_DATA                  = :SOLANA_ERROR__INSTRUCTIONS__EXPECTED_TO_HAVE_DATA
+    INSTRUCTIONS__PROGRAM_ADDRESS_MISMATCH               = :SOLANA_ERROR__INSTRUCTIONS__PROGRAM_ADDRESS_MISMATCH
+    INSTRUCTIONS__ACCOUNT_NOT_FOUND                      = :SOLANA_ERROR__INSTRUCTIONS__ACCOUNT_NOT_FOUND
+    INSTRUCTIONS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED    = :SOLANA_ERROR__INSTRUCTIONS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED
+
+    # ── Transactions ──────────────────────────────────────────────────────────
+    TRANSACTIONS__TRANSACTION_NOT_SIGNABLE               = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_NOT_SIGNABLE
+    TRANSACTIONS__MISSING_SIGNER                         = :SOLANA_ERROR__TRANSACTIONS__MISSING_SIGNER
+    TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE            = :SOLANA_ERROR__TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE
+    TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS
+    TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING
+    TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND
+    TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE     = :SOLANA_ERROR__TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE
+    TRANSACTIONS__BLOCKHASH_NOT_FOUND                    = :SOLANA_ERROR__TRANSACTIONS__BLOCKHASH_NOT_FOUND
+    TRANSACTIONS__FAILED_TRANSACTION_PLAN                = :SOLANA_ERROR__TRANSACTIONS__FAILED_TRANSACTION_PLAN
+    TRANSACTIONS__TRANSACTION_EXPIRED_BLOCKHEIGHT_EXCEEDED = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_EXPIRED_BLOCKHEIGHT_EXCEEDED
+    TRANSACTIONS__TRANSACTION_EXPIRED_NONCE_INVALID      = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_EXPIRED_NONCE_INVALID
+    TRANSACTIONS__TRANSACTION_CONFIRMATION_TIMEOUT       = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_CONFIRMATION_TIMEOUT
+
+    # ── Signers ───────────────────────────────────────────────────────────────
+    SIGNERS__ADDRESS_CANNOT_HAVE_MULTIPLE_SIGNERS        = :SOLANA_ERROR__SIGNERS__ADDRESS_CANNOT_HAVE_MULTIPLE_SIGNERS
+    SIGNERS__EXPECTED_MESSAGE_MODIFYING_SIGNER           = :SOLANA_ERROR__SIGNERS__EXPECTED_MESSAGE_MODIFYING_SIGNER
+    SIGNERS__EXPECTED_TRANSACTION_MODIFYING_SIGNER       = :SOLANA_ERROR__SIGNERS__EXPECTED_TRANSACTION_MODIFYING_SIGNER
+    SIGNERS__EXPECTED_TRANSACTION_SENDING_SIGNER         = :SOLANA_ERROR__SIGNERS__EXPECTED_TRANSACTION_SENDING_SIGNER
+    SIGNERS__TRANSACTION_CANNOT_HAVE_MULTIPLE_SENDING_SIGNERS = :SOLANA_ERROR__SIGNERS__TRANSACTION_CANNOT_HAVE_MULTIPLE_SENDING_SIGNERS
+    SIGNERS__WALLET_MULTISIGN_UNIMPLEMENTED              = :SOLANA_ERROR__SIGNERS__WALLET_MULTISIGN_UNIMPLEMENTED
+
+    # ── Codecs ────────────────────────────────────────────────────────────────
+    CODECS__CANNOT_DECODE_EMPTY_BYTE_ARRAY               = :SOLANA_ERROR__CODECS__CANNOT_DECODE_EMPTY_BYTE_ARRAY
+    CODECS__EXPECTED_POSITIVE_BYTE_LENGTH                = :SOLANA_ERROR__CODECS__EXPECTED_POSITIVE_BYTE_LENGTH
+    CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH          = :SOLANA_ERROR__CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH
+    CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH            = :SOLANA_ERROR__CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH
+    CODECS__INVALID_NUMBER_OF_ITEMS                      = :SOLANA_ERROR__CODECS__INVALID_NUMBER_OF_ITEMS
+    CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE              = :SOLANA_ERROR__CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE
+    CODECS__UNION_VARIANT_OUT_OF_RANGE                   = :SOLANA_ERROR__CODECS__UNION_VARIANT_OUT_OF_RANGE
+    CODECS__OFFSET_OUT_OF_RANGE                          = :SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE
+    CODECS__SENTINEL_MISSING_IN_DECODED_BYTES            = :SOLANA_ERROR__CODECS__SENTINEL_MISSING_IN_DECODED_BYTES
+    CODECS__INVALID_STRING_FOR_BASE58_CODEC              = :SOLANA_ERROR__CODECS__INVALID_STRING_FOR_BASE58_CODEC
+    CODECS__INVALID_STRING_FOR_BASE64_CODEC              = :SOLANA_ERROR__CODECS__INVALID_STRING_FOR_BASE64_CODEC
+    CODECS__INVALID_STRING_FOR_HEX_CODEC                 = :SOLANA_ERROR__CODECS__INVALID_STRING_FOR_HEX_CODEC
+    CODECS__INVALID_BYTE_LENGTH                          = :SOLANA_ERROR__CODECS__INVALID_BYTE_LENGTH
+    CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR = :SOLANA_ERROR__CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR
+    CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC = :SOLANA_ERROR__CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC
+
+    # ── RPC / JSON-RPC ────────────────────────────────────────────────────────
+    RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER
+    RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER
+    RPC__TRANSPORT_HTTP_ERROR                             = :SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR
+    RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST
+    RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID   = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID
+    RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED
+    RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED         = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED
+    RPC_SUBSCRIPTIONS__WEBSOCKET_CONNECTION_FAILED        = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__WEBSOCKET_CONNECTION_FAILED
+
+    # ── Offchain messages ─────────────────────────────────────────────────────
+    OFFCHAIN_MESSAGES__FAILED_TO_DECODE_MESSAGE          = :SOLANA_ERROR__OFFCHAIN_MESSAGES__FAILED_TO_DECODE_MESSAGE
+    OFFCHAIN_MESSAGES__INVALID_MESSAGE_FORMAT            = :SOLANA_ERROR__OFFCHAIN_MESSAGES__INVALID_MESSAGE_FORMAT
+    OFFCHAIN_MESSAGES__INVALID_MESSAGE_VERSION           = :SOLANA_ERROR__OFFCHAIN_MESSAGES__INVALID_MESSAGE_VERSION
+    OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER     = :SOLANA_ERROR__OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER
+    OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG                  = :SOLANA_ERROR__OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG
+    OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN    = :SOLANA_ERROR__OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN
+
+    # ── Invariant violations (internal) ──────────────────────────────────────
+    INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING = :SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING
+    INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE = :SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE
+
+    ERROR_MESSAGES = T.let(
+      {
+        # General
+        INVALID_KEYPAIR_SEED_LENGTH                      => 'Keypair seed must be 32 bytes, got %{actual_length}',
+        INVALID_NONCE                                    => 'The supplied nonce is not a valid nonce',
+
+        # Addresses
+        ADDRESSES__INVALID_BASE58_ENCODED_ADDRESS        => 'Not a valid base58-encoded address',
+        ADDRESSES__INVALID_BYTE_LENGTH_FOR_ADDRESS       => 'Expected 32 bytes for an address, got %{byte_length}',
+        ADDRESSES__STRING_LENGTH_OUT_OF_RANGE            => 'Address string length out of range (32–44 chars), got %{actual_length}',
+        ADDRESSES__INVALID_ED25519_PUBLIC_KEY            => 'The public key is not a valid Ed25519 public key',
+        ADDRESSES__SEEDS_POINT_ON_CURVE                  => 'The seeds resolve to a point on the Ed25519 curve; it cannot be used as a PDA',
+        ADDRESSES__MAX_SEED_LENGTH_EXCEEDED              => 'A seed exceeds the maximum allowed length of 32 bytes, got %{actual_length}',
+        ADDRESSES__TOO_MANY_SEEDS                        => 'Too many seeds provided (max 16)',
+        ADDRESSES__FAILED_TO_FIND_VIABLE_PDA_BUMP_SEED   => 'Could not find a viable bump seed for the given program and seeds',
+        ADDRESSES__INVALID_SEEDS_POINT_ON_CURVE          => 'The seeds result in a public key that lies on the Ed25519 curve',
+        ADDRESSES__PDA_BUMP_SEED_OUT_OF_RANGE            => 'Bump seed must be in range [0, 255]',
+
+        # Accounts
+        ACCOUNTS__ACCOUNT_NOT_FOUND                      => 'Account not found at address %{address}',
+        ACCOUNTS__ONE_OR_MORE_ACCOUNTS_NOT_FOUND         => 'One or more accounts were not found',
+        ACCOUNTS__EXPECTED_DECODED_ACCOUNT               => 'Expected account at address %{address} to be decoded',
+        ACCOUNTS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED    => 'Expected all %{count} account(s) to be decoded',
+        ACCOUNTS__FAILED_TO_DECODE_ACCOUNT               => 'Failed to decode account data at address %{address}',
+
+        # Keys
+        KEYS__INVALID_KEY_PAIR_BYTE_LENGTH               => 'Key pair byte array must be 64 bytes, got %{byte_length}',
+        KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY          => 'The public key does not match the private key',
+        KEYS__INVALID_SIGNATURE_BYTE_LENGTH              => 'Signature must be 64 bytes, got %{actual_length}',
+        KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE       => 'Signature string length out of range (64–88 chars), got %{actual_length}',
+
+        # Instructions
+        INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS          => 'Expected instruction to have accounts',
+        INSTRUCTIONS__EXPECTED_TO_HAVE_DATA              => 'Expected instruction to have data',
+        INSTRUCTIONS__PROGRAM_ADDRESS_MISMATCH           => 'Instruction program address mismatch: expected %{expected}, got %{actual}',
+        INSTRUCTIONS__ACCOUNT_NOT_FOUND                  => 'Account at index %{index} not found in instruction',
+        INSTRUCTIONS__EXPECTED_ALL_ACCOUNTS_TO_BE_DECODED => 'Expected all instruction accounts to be decoded',
+
+        # Transactions
+        TRANSACTIONS__TRANSACTION_NOT_SIGNABLE           => 'Transaction is not signable (missing fee payer or lifetime constraint)',
+        TRANSACTIONS__MISSING_SIGNER                     => 'Transaction is missing a required signer: %{address}',
+        TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE        => 'Transaction version %{version} is out of range',
+        TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS => 'Failed to decompile address lookup table contents',
+        TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING => 'Failed to decompile transaction: fee payer is missing',
+        TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND => 'Failed to decompile instruction: program address not found',
+        TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE => 'Transaction simulation failed: %{message}',
+        TRANSACTIONS__BLOCKHASH_NOT_FOUND                => 'Blockhash not found',
+        TRANSACTIONS__FAILED_TRANSACTION_PLAN            => 'Failed to execute transaction plan',
+        TRANSACTIONS__TRANSACTION_EXPIRED_BLOCKHEIGHT_EXCEEDED => 'Transaction expired: block height exceeded',
+        TRANSACTIONS__TRANSACTION_EXPIRED_NONCE_INVALID  => 'Transaction expired: nonce is no longer valid',
+        TRANSACTIONS__TRANSACTION_CONFIRMATION_TIMEOUT   => 'Timed out waiting for transaction %{signature} to confirm',
+
+        # Signers
+        SIGNERS__ADDRESS_CANNOT_HAVE_MULTIPLE_SIGNERS    => 'Address %{address} cannot be assigned multiple signers',
+        SIGNERS__EXPECTED_MESSAGE_MODIFYING_SIGNER       => 'Expected signer to be a message modifying signer',
+        SIGNERS__EXPECTED_TRANSACTION_MODIFYING_SIGNER   => 'Expected signer to be a transaction modifying signer',
+        SIGNERS__EXPECTED_TRANSACTION_SENDING_SIGNER     => 'Expected signer to be a transaction sending signer',
+        SIGNERS__TRANSACTION_CANNOT_HAVE_MULTIPLE_SENDING_SIGNERS => 'Transaction cannot have multiple sending signers',
+        SIGNERS__WALLET_MULTISIGN_UNIMPLEMENTED          => 'Wallet multisign is not yet implemented',
+
+        # Codecs
+        CODECS__CANNOT_DECODE_EMPTY_BYTE_ARRAY           => 'Cannot decode an empty byte array',
+        CODECS__EXPECTED_POSITIVE_BYTE_LENGTH            => 'Expected a positive byte length, got %{byte_length}',
+        CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH      => 'Encoder fixed size (%{encoder_size}) does not match decoder fixed size (%{decoder_size})',
+        CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH        => 'Encoder max size (%{encoder_max}) does not match decoder max size (%{decoder_max})',
+        CODECS__INVALID_NUMBER_OF_ITEMS                  => 'Expected %{expected} items but got %{actual}',
+        CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE          => 'Enum discriminator %{discriminator} is out of range [0, %{max}]',
+        CODECS__UNION_VARIANT_OUT_OF_RANGE               => 'Union variant index %{index} is out of range',
+        CODECS__OFFSET_OUT_OF_RANGE                      => 'Codec offset %{offset} is out of range for byte array of length %{byte_length}',
+        CODECS__SENTINEL_MISSING_IN_DECODED_BYTES        => 'Sentinel bytes not found in decoded data',
+        CODECS__INVALID_STRING_FOR_BASE58_CODEC          => 'Invalid base58 string: %{value}',
+        CODECS__INVALID_STRING_FOR_BASE64_CODEC          => 'Invalid base64 string: %{value}',
+        CODECS__INVALID_STRING_FOR_HEX_CODEC             => 'Invalid hex string: %{value}',
+        CODECS__INVALID_BYTE_LENGTH                      => 'Expected %{expected} bytes but got %{actual}',
+        CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR => 'Expected zero value to match fixed discriminator',
+        CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC => 'A fixed-size nullable codec cannot wrap a variable-size codec',
+
+        # RPC
+        RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER   => 'Integer overflow while serializing large integer %{value}',
+        RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER => 'Integer overflow while deserializing large integer %{value}',
+        RPC__TRANSPORT_HTTP_ERROR                               => 'HTTP transport error: %{status} %{message}',
+        RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST  => 'Cannot create subscription request',
+        RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID     => 'Expected server to return a subscription ID',
+        RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED => 'WebSocket channel closed before message could be buffered',
+        RPC_SUBSCRIPTIONS__CHANNEL_CONNECTION_CLOSED           => 'WebSocket connection closed: %{reason}',
+        RPC_SUBSCRIPTIONS__WEBSOCKET_CONNECTION_FAILED         => 'Failed to establish WebSocket connection to %{url}',
+
+        # Offchain messages
+        OFFCHAIN_MESSAGES__FAILED_TO_DECODE_MESSAGE      => 'Failed to decode offchain message',
+        OFFCHAIN_MESSAGES__INVALID_MESSAGE_FORMAT        => 'Invalid offchain message format',
+        OFFCHAIN_MESSAGES__INVALID_MESSAGE_VERSION       => 'Invalid offchain message version %{version}',
+        OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER => 'Offchain message v0 contains non-printable ASCII character at index %{index}',
+        OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG              => 'Offchain message is too long (%{length} bytes, max %{max})',
+        OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN => 'Offchain message signing domain must not start with a null byte',
+
+        # Invariant violations
+        INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING => 'Subscription iterator state is missing (internal error)',
+        INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE => 'Subscription iterator must not poll before resolving existing message (internal error)',
+      }.freeze,
+      T::Hash[Symbol, String]
+    )
+
+    sig { returns(Symbol) }
+    attr_reader :code
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    attr_reader :context
+
+    sig { params(code: Symbol, context: T::Hash[Symbol, T.untyped]).void }
+    def initialize(code, context = {})
+      @code    = T.let(code, Symbol)
+      @context = T.let(context, T::Hash[Symbol, T.untyped])
+
+      template = ERROR_MESSAGES[code] || code.to_s
+      message  = context.empty? ? template : (template % context rescue "#{template} #{context}")
+      super(message)
+    end
+  end
+end

data/lib/solana/ruby/kit/fast_stable_stringify.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Mirrors @solana/fast-stable-stringify.
+# Produces deterministic JSON by sorting Hash keys recursively.
+# Used internally by RPC transport so request bodies are stable.
+module Solana::Ruby::Kit
+  module FastStableStringify
+    extend T::Sig
+
+    module_function
+
+    # Serialize +value+ to a deterministic JSON string.
+    # Hash keys are sorted lexicographically at every level.
+    # Unsupported types (custom objects, Symbols as values, etc.) are treated
+    # as +nil+ (same behaviour as JSON.generate's default replacer).
+    sig { params(value: T.untyped).returns(String) }
+    def stringify(value)
+      serialize(value)
+    end
+
+    # Internal recursive serializer (exposed as module_function for testability).
+    sig { params(value: T.untyped).returns(String) }
+    def serialize(value) # rubocop:disable Metrics/MethodLength
+      case value
+      when NilClass  then 'null'
+      when TrueClass then 'true'
+      when FalseClass then 'false'
+      when Integer
+        # Sorbet: plain integer — output as-is
+        value.to_s
+      when Float
+        # Match JSON behaviour: NaN / Infinity → null
+        if value.nan? || value.infinite?
+          'null'
+        else
+          # Avoid trailing zeros while staying valid JSON
+          int = value.to_i
+          int.to_f == value ? int.to_s : value.to_s
+        end
+      when String
+        value.to_json
+      when Array
+        inner = value.map { |el| serialize(el) }.join(',')
+        "[#{inner}]"
+      when Hash
+        pairs = value.keys.map(&:to_s).sort.filter_map do |k|
+          raw_val = value[k] || value[k.to_sym]
+          serialized = serialize(raw_val)
+          next if serialized == 'undefined' # skip undefined-equivalent keys
+
+          "#{k.to_s.to_json}:#{serialized}"
+        end
+        "{#{pairs.join(',')}}"
+      else
+        # Symbol, custom class, etc. → null
+        'null'
+      end
+    end
+    private_class_method :serialize
+  end
+end

data/lib/solana/ruby/kit/functional.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  # Function composition utilities.
+  # Mirrors the TypeScript package @solana/functional.
+  module Functional
+    extend T::Sig
+    module_function
+
+    # Passes an initial value through a series of single-argument callables,
+    # returning the final result.
+    #
+    # Mirrors TypeScript's `pipe(init, fn1, fn2, ...)`.  TypeScript requires
+    # 10 overloads for static typing; Ruby achieves the same with a single
+    # variadic implementation.
+    #
+    # @example Building a transaction message
+    #   msg = Solana::Ruby::Kit::Functional.pipe(
+    #     Solana::Ruby::Kit::TransactionMessages.create_transaction_message(version: 0),
+    #     ->(tx) { Solana::Ruby::Kit::TransactionMessages.set_fee_payer(fee_payer_address, tx) },
+    #     ->(tx) { Solana::Ruby::Kit::TransactionMessages.set_blockhash_lifetime(blockhash, tx) },
+    #   )
+    sig { params(value: T.untyped, fns: T::Array[T.proc.params(arg0: T.untyped).returns(T.untyped)]).returns(T.untyped) }
+    def pipe(value, *fns)
+      fns.reduce(value) { |acc, fn| T.unsafe(fn).call(acc) }
+    end
+  end
+end

data/lib/solana/ruby/kit/instruction_plans/plans.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    # A plan that wraps a single instruction.
+    class SingleInstructionPlan < T::Struct
+      const :instruction, Instructions::Instruction
+    end
+
+    # A plan that executes a sequence of sub-plans in order.
+    # When +divisible+ is true the planner may split steps across transactions.
+    class SequentialInstructionPlan < T::Struct
+      const :steps,     T::Array[T.untyped]  # Array[InstructionPlan]
+      const :divisible, T::Boolean, default: false
+    end
+
+    # A plan whose sub-plans may execute concurrently or be packed into the
+    # same transaction in any order.
+    class ParallelInstructionPlan < T::Struct
+      const :plans, T::Array[T.untyped]  # Array[InstructionPlan]
+    end
+
+    # Union type alias (used only in doc strings; Ruby is duck-typed).
+    # InstructionPlan = SingleInstructionPlan | SequentialInstructionPlan | ParallelInstructionPlan
+  end
+end

data/lib/solana/ruby/kit/instruction_plans.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Mirrors @solana/instruction-plans.
+# An InstructionPlan describes operations that may span multiple transactions.
+require_relative 'instruction_plans/plans'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    module_function
+
+    # Build a plan that wraps a single instruction.
+    sig { params(instruction: Instructions::Instruction).returns(SingleInstructionPlan) }
+    def single_instruction_plan(instruction)
+      SingleInstructionPlan.new(instruction: instruction)
+    end
+
+    # Build a sequential plan from an array of sub-plans.
+    sig { params(steps: T::Array[T.untyped], divisible: T::Boolean).returns(SequentialInstructionPlan) }
+    def sequential_instruction_plan(steps, divisible: false)
+      SequentialInstructionPlan.new(steps: steps, divisible: divisible)
+    end
+
+    # Build a parallel plan from an array of sub-plans.
+    sig { params(plans: T::Array[T.untyped]).returns(ParallelInstructionPlan) }
+    def parallel_instruction_plan(plans)
+      ParallelInstructionPlan.new(plans: plans)
+    end
+
+    # Flatten a plan tree into a single ordered Array of Instructions.
+    sig { params(plan: T.untyped).returns(T::Array[Instructions::Instruction]) }
+    def flatten_instruction_plan(plan)
+      case plan
+      when SingleInstructionPlan
+        [plan.instruction]
+      when SequentialInstructionPlan
+        plan.steps.flat_map { |s| flatten_instruction_plan(s) }
+      when ParallelInstructionPlan
+        plan.plans.flat_map { |p| flatten_instruction_plan(p) }
+      else
+        Kernel.raise ArgumentError, "Unknown InstructionPlan type: #{plan.class}"
+      end
+    end
+  end
+end