solana-ruby-kit 0.1.0

data/lib/solana/ruby/kit/instructions/accounts.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative 'roles'
+
+module Solana::Ruby::Kit
+  module Instructions
+    extend T::Sig
+    # Metadata for a single account referenced by an instruction.
+    # Mirrors TypeScript's `AccountMeta<TAddress>`.
+    #
+    # Combines an address with an `AccountRole` that declares whether the
+    # account is a signer, writable, or both.
+    class AccountMeta < T::Struct
+      const :address, Addresses::Address
+      const :role,    Integer  # one of AccountRole constants
+    end
+
+    # AccountMeta subtypes — mirrors the four TypeScript convenience types.
+
+    module_function
+
+    # Creates a read-only account reference.
+    sig { params(address: Addresses::Address).returns(AccountMeta) }
+    def readonly_account(address)
+      AccountMeta.new(address: address, role: AccountRole::READONLY)
+    end
+
+    # Creates a writable account reference.
+    sig { params(address: Addresses::Address).returns(AccountMeta) }
+    def writable_account(address)
+      AccountMeta.new(address: address, role: AccountRole::WRITABLE)
+    end
+
+    # Creates a read-only signer account reference.
+    sig { params(address: Addresses::Address).returns(AccountMeta) }
+    def readonly_signer_account(address)
+      AccountMeta.new(address: address, role: AccountRole::READONLY_SIGNER)
+    end
+
+    # Creates a writable signer account reference.
+    sig { params(address: Addresses::Address).returns(AccountMeta) }
+    def writable_signer_account(address)
+      AccountMeta.new(address: address, role: AccountRole::WRITABLE_SIGNER)
+    end
+
+    # -------------------------------------------------------------------
+    # Address lookup table accounts
+    # Mirrors TypeScript's `AccountLookupMeta<TAddress, TLookupTableAddress>`.
+    # Accounts resolved through a lookup table cannot act as signers.
+    # -------------------------------------------------------------------
+    class AccountLookupMeta < T::Struct
+      const :address,              Addresses::Address
+      const :address_index,        Integer
+      const :lookup_table_address, Addresses::Address
+      const :role,                 Integer  # READONLY or WRITABLE only
+    end
+
+    sig { params(address: Addresses::Address, lookup_table_address: Addresses::Address, address_index: Integer).returns(AccountLookupMeta) }
+    def readonly_lookup_account(address, lookup_table_address:, address_index:)
+      AccountLookupMeta.new(
+        address: address,
+        address_index: address_index,
+        lookup_table_address: lookup_table_address,
+        role: AccountRole::READONLY
+      )
+    end
+
+    sig { params(address: Addresses::Address, lookup_table_address: Addresses::Address, address_index: Integer).returns(AccountLookupMeta) }
+    def writable_lookup_account(address, lookup_table_address:, address_index:)
+      AccountLookupMeta.new(
+        address: address,
+        address_index: address_index,
+        lookup_table_address: lookup_table_address,
+        role: AccountRole::WRITABLE
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/instructions/instruction.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../errors'
+require_relative 'accounts'
+
+module Solana::Ruby::Kit
+  module Instructions
+    extend T::Sig
+    # A single instruction to be executed by a Solana program.
+    # Mirrors TypeScript's `Instruction<TProgramAddress, TAccounts, TData>`.
+    #
+    # All fields are optional — instructions may omit accounts or data.
+    class Instruction < T::Struct
+      const :program_address, Addresses::Address
+      const :accounts,        T.nilable(T::Array[T.any(AccountMeta, AccountLookupMeta)])
+      const :data,            T.nilable(String)  # binary String (Uint8Array equivalent)
+    end
+
+    module_function
+
+    # Returns true if the instruction targets the given program address.
+    # Mirrors `isInstructionForProgram()`.
+    sig { params(instruction: Instruction, program_address: Addresses::Address).returns(T::Boolean) }
+    def instruction_for_program?(instruction, program_address)
+      instruction.program_address == program_address
+    end
+
+    # Raises SolanaError unless the instruction targets the given program.
+    # Mirrors `assertIsInstructionForProgram()`.
+    sig { params(instruction: Instruction, program_address: Addresses::Address).void }
+    def assert_instruction_for_program!(instruction, program_address)
+      return if instruction_for_program?(instruction, program_address)
+
+      Kernel.raise SolanaError.new(
+        :SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_ACCOUNTS,
+        expected_program_address: program_address.value,
+        actual_program_address:   instruction.program_address.value
+      )
+    end
+
+    # Returns true if the instruction has at least one account.
+    # Mirrors `isInstructionWithAccounts()`.
+    sig { params(instruction: Instruction).returns(T::Boolean) }
+    def instruction_with_accounts?(instruction)
+      !instruction.accounts.nil? && !T.must(instruction.accounts).empty?
+    end
+
+    # Raises unless the instruction has accounts.
+    # Mirrors `assertIsInstructionWithAccounts()`.
+    sig { params(instruction: Instruction).void }
+    def assert_instruction_with_accounts!(instruction)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_ACCOUNTS) unless instruction_with_accounts?(instruction)
+    end
+
+    # Returns true if the instruction carries data bytes.
+    # Mirrors `isInstructionWithData()`.
+    sig { params(instruction: Instruction).returns(T::Boolean) }
+    def instruction_with_data?(instruction)
+      !instruction.data.nil?
+    end
+
+    # Raises unless the instruction has data.
+    # Mirrors `assertIsInstructionWithData()`.
+    sig { params(instruction: Instruction).void }
+    def assert_instruction_with_data!(instruction)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_DATA) unless instruction_with_data?(instruction)
+    end
+  end
+end

data/lib/solana/ruby/kit/instructions/roles.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Instructions
+    # Bitflag-based account roles for Solana instructions.
+    # Mirrors TypeScript's `AccountRole` enum from @solana/instructions.
+    #
+    # Bit layout:
+    #   bit 1 (0b10) → signer privilege
+    #   bit 0 (0b01) → writable privilege
+    module AccountRole
+      extend T::Sig
+
+      READONLY        = T.let(0b00, Integer)  # read-only, no signing required
+      WRITABLE        = T.let(0b01, Integer)  # writable, no signing required
+      READONLY_SIGNER = T.let(0b10, Integer)  # must sign, read-only
+      WRITABLE_SIGNER = T.let(0b11, Integer)  # must sign AND writable
+
+      ALL = T.let([READONLY, WRITABLE, READONLY_SIGNER, WRITABLE_SIGNER].freeze, T::Array[Integer])
+
+      module_function
+
+      # Returns true if the role requires the account to sign the transaction.
+      sig { params(role: Integer).returns(T::Boolean) }
+      def signer_role?(role)
+        (role & 0b10) != 0
+      end
+
+      # Returns true if the role permits writing to the account.
+      sig { params(role: Integer).returns(T::Boolean) }
+      def writable_role?(role)
+        (role & 0b01) != 0
+      end
+
+      # Returns the role that grants the highest privileges of both inputs.
+      # Mirrors `mergeRoles()`.
+      sig { params(a: Integer, b: Integer).returns(Integer) }
+      def merge(a, b)
+        a | b
+      end
+
+      # Removes the signer bit from a role.
+      # Mirrors `downgradeRoleToNonSigner()`.
+      sig { params(role: Integer).returns(Integer) }
+      def downgrade_to_non_signer(role)
+        role & 0b01
+      end
+
+      # Removes the writable bit from a role.
+      # Mirrors `downgradeRoleToReadonly()`.
+      sig { params(role: Integer).returns(Integer) }
+      def downgrade_to_readonly(role)
+        role & 0b10
+      end
+
+      # Adds the signer bit to a role.
+      # Mirrors `upgradeRoleToSigner()`.
+      sig { params(role: Integer).returns(Integer) }
+      def upgrade_to_signer(role)
+        role | 0b10
+      end
+
+      # Adds the writable bit to a role.
+      # Mirrors `upgradeRoleToWritable()`.
+      sig { params(role: Integer).returns(Integer) }
+      def upgrade_to_writable(role)
+        role | 0b01
+      end
+
+      # Human-readable name for a role (useful for debugging).
+      sig { params(role: Integer).returns(String) }
+      def name(role)
+        case role
+        when READONLY        then 'READONLY'
+        when WRITABLE        then 'WRITABLE'
+        when READONLY_SIGNER then 'READONLY_SIGNER'
+        when WRITABLE_SIGNER then 'WRITABLE_SIGNER'
+        else "UNKNOWN(#{role})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Instruction types and utilities — mirrors @solana/instructions.
+require_relative 'instructions/roles'
+require_relative 'instructions/accounts'
+require_relative 'instructions/instruction'

data/lib/solana/ruby/kit/keys/key_pair.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative '../errors'
+require_relative 'signatures'
+
+module Solana::Ruby::Kit
+  module Keys
+    extend T::Sig
+    # Represents an Ed25519 key pair: a signing key (private) and its
+    # corresponding verification key (public).
+    #
+    # Mirrors TypeScript's `CryptoKeyPair`:
+    #   { privateKey: CryptoKey, publicKey: CryptoKey }
+    #
+    # In TypeScript this wraps Web Crypto opaque `CryptoKey` handles.
+    # In Ruby, RbNaCl::SigningKey holds the 32-byte private key seed, and
+    # RbNaCl::VerifyKey holds the 32-byte public key.
+    class KeyPair < T::Struct
+      # 32-byte Ed25519 signing (private) key
+      const :signing_key, T.untyped  # RbNaCl::SigningKey
+      # Corresponding 32-byte verification (public) key
+      const :verify_key,  T.untyped  # RbNaCl::VerifyKey
+    end
+
+    module_function
+
+    # Generates a fresh Ed25519 key pair using a cryptographically secure RNG.
+    # Mirrors `generateKeyPair()` in TypeScript.
+    sig { returns(KeyPair) }
+    def generate_key_pair
+      signing_key = RbNaCl::SigningKey.generate
+      KeyPair.new(signing_key: signing_key, verify_key: signing_key.verify_key)
+    end
+
+    # Creates a KeyPair from a 64-byte seed array (first 32 = private seed,
+    # last 32 = expected public key bytes) and verifies they match by performing
+    # a sign-and-verify round-trip.
+    #
+    # Mirrors `createKeyPairFromBytes(bytes: ReadonlyUint8Array)` in TypeScript.
+    #
+    # @param bytes [String] A 64-byte binary string (private seed || public key).
+    sig { params(bytes: String).returns(KeyPair) }
+    def create_key_pair_from_bytes(bytes)
+      if bytes.bytesize != 64
+        Kernel.raise SolanaError.new(
+          SolanaError::KEYS__INVALID_KEY_PAIR_BYTE_LENGTH,
+          byte_length: bytes.bytesize
+        )
+      end
+
+      private_seed = bytes.byteslice(0, 32) || Kernel.raise(SolanaError.new(SolanaError::KEYS__INVALID_KEY_PAIR_BYTE_LENGTH, byte_length: bytes.bytesize))
+      public_bytes = bytes.byteslice(32, 32) || Kernel.raise(SolanaError.new(SolanaError::KEYS__INVALID_KEY_PAIR_BYTE_LENGTH, byte_length: bytes.bytesize))
+
+      signing_key = RbNaCl::SigningKey.new(private_seed.b)
+      verify_key  = signing_key.verify_key
+
+      # Verify that the embedded public key matches the derived one.
+      unless verify_key.to_bytes == public_bytes.b
+        Kernel.raise SolanaError.new(SolanaError::KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY)
+      end
+
+      # Round-trip sign-and-verify with random data (mirrors the TypeScript check).
+      random_data = RbNaCl::Random.random_bytes(32)
+      signed_data = sign_bytes(signing_key, random_data)
+      unless verify_signature(verify_key, signed_data, random_data)
+        Kernel.raise SolanaError.new(SolanaError::KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY)
+      end
+
+      KeyPair.new(signing_key: signing_key, verify_key: verify_key)
+    end
+
+    # Creates a KeyPair from a 32-byte private key seed alone.
+    # The matching public key is derived automatically.
+    #
+    # Mirrors `createKeyPairFromPrivateKeyBytes(bytes: ReadonlyUint8Array)`.
+    sig { params(bytes: String).returns(KeyPair) }
+    def create_key_pair_from_private_key_bytes(bytes)
+      signing_key = RbNaCl::SigningKey.new(bytes.b)
+      KeyPair.new(signing_key: signing_key, verify_key: signing_key.verify_key)
+    end
+  end
+end

data/lib/solana/ruby/kit/keys/private_key.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Keys
+    extend T::Sig
+    module_function
+
+    # Creates an Ed25519 signing key from a raw 32-byte private key seed.
+    #
+    # Mirrors `createPrivateKeyFromBytes(bytes, extractable)` in TypeScript.
+    # TypeScript wraps the raw seed in a PKCS#8 ASN.1 header before calling
+    # `crypto.subtle.importKey` because the Web Crypto API requires PKCS#8 format.
+    # In Ruby, RbNaCl::SigningKey accepts raw 32-byte seeds directly, so no
+    # wrapping is necessary.
+    #
+    # The `extractable` parameter exists for API parity with the TypeScript
+    # original. RbNaCl::SigningKey always allows seed extraction via `#to_bytes`.
+    # Pass `extractable: false` to signal intent; enforcement is caller-side.
+    #
+    # @param bytes      [String] 32-byte binary string (Ed25519 private key seed)
+    # @param extractable [Boolean] whether the raw seed may be re-exported (advisory)
+    # @return [RbNaCl::SigningKey]
+    sig { params(bytes: String, extractable: T::Boolean).returns(T.untyped) }
+    def create_private_key_from_bytes(bytes, extractable: false)
+      if bytes.bytesize != 32
+        Kernel.raise SolanaError.new(
+          SolanaError::KEYS__INVALID_KEY_PAIR_BYTE_LENGTH,
+          byte_length: bytes.bytesize
+        )
+      end
+
+      RbNaCl::SigningKey.new(bytes.b)
+    end
+  end
+end

data/lib/solana/ruby/kit/keys/public_key.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Keys
+    extend T::Sig
+    module_function
+
+    # Derives the Ed25519 verification (public) key from a signing (private) key.
+    #
+    # Mirrors `getPublicKeyFromPrivateKey(privateKey, extractable)` in TypeScript.
+    # TypeScript exports the JWK representation of the private key and re-imports
+    # only the public component because Web Crypto keys are opaque handles.
+    # In Ruby, RbNaCl::SigningKey#verify_key returns the VerifyKey directly.
+    #
+    # @param signing_key [RbNaCl::SigningKey]
+    # @param extractable [Boolean] advisory flag for API parity with TypeScript
+    # @return [RbNaCl::VerifyKey]
+    sig { params(signing_key: T.untyped, extractable: T::Boolean).returns(T.untyped) }
+    def get_public_key_from_private_key(signing_key, extractable: false)
+      unless signing_key.respond_to?(:verify_key)
+        Kernel.raise SolanaError.new(SolanaError::ADDRESSES__INVALID_ED25519_PUBLIC_KEY)
+      end
+
+      signing_key.verify_key
+    end
+  end
+end

data/lib/solana/ruby/kit/keys/signatures.rb

@@ -0,0 +1,171 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative '../errors'
+require_relative '../encoding/base58'
+
+module Solana::Ruby::Kit
+  module Keys
+    extend T::Sig
+    # A validated base58-encoded Ed25519 signature string (64 bytes on-wire).
+    # Mirrors TypeScript:
+    #   type Signature = Brand<EncodedString<string, 'base58'>, 'Signature'>
+    class Signature
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :value
+
+      sig { params(value: String).void }
+      def initialize(value)
+        @value = T.let(value, String)
+      end
+
+      sig { returns(String) }
+      def to_s = @value
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        !!(other.is_a?(Signature) && @value == other.value)
+      end
+    end
+
+    # A 64-byte binary string holding raw Ed25519 signature bytes.
+    # Mirrors TypeScript:
+    #   type SignatureBytes = Brand<Uint8Array, 'SignatureBytes'>
+    class SignatureBytes
+      extend T::Sig
+
+      BYTE_LENGTH = 64
+
+      sig { returns(String) }
+      attr_reader :value  # binary String, always 64 bytes
+
+      sig { params(value: String).void }
+      def initialize(value)
+        @value = T.let(value, String)
+      end
+
+      sig { returns(Integer) }
+      def bytesize = @value.bytesize
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        !!(other.is_a?(SignatureBytes) && @value == other.value)
+      end
+    end
+
+    # Length bounds for a base58-encoded 64-byte signature string.
+    SIGNATURE_MIN_STR_LEN = 64
+    SIGNATURE_MAX_STR_LEN = 88
+
+    module_function
+
+    # Returns true if the string is a valid base58-encoded Ed25519 signature.
+    # Mirrors `isSignature()` in TypeScript.
+    sig { params(putative: String).returns(T::Boolean) }
+    def signature?(putative)
+      return false unless putative.length.between?(SIGNATURE_MIN_STR_LEN, SIGNATURE_MAX_STR_LEN)
+
+      bytes = Encoding::Base58.decode(putative)
+      bytes.bytesize == SignatureBytes::BYTE_LENGTH
+    rescue ArgumentError
+      false
+    end
+
+    # Raises SolanaError if the string is not a valid base58-encoded signature.
+    # Mirrors `assertIsSignature()` in TypeScript.
+    sig { params(putative: String).void }
+    def assert_signature!(putative)
+      unless putative.length.between?(SIGNATURE_MIN_STR_LEN, SIGNATURE_MAX_STR_LEN)
+        Kernel.raise SolanaError.new(
+          SolanaError::KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE,
+          actual_length: putative.length
+        )
+      end
+
+      bytes = Encoding::Base58.decode(putative)
+      assert_signature_bytes!(bytes)
+    rescue ArgumentError
+      Kernel.raise SolanaError.new(SolanaError::KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE, actual_length: putative.length)
+    end
+
+    # Validates and wraps a string in a Signature value object.
+    # Mirrors `signature()` in TypeScript.
+    sig { params(putative: String).returns(Signature) }
+    def signature(putative)
+      assert_signature!(putative)
+      Signature.new(putative)
+    end
+
+    # Returns true if the binary string is exactly 64 bytes (valid signature length).
+    # Mirrors `isSignatureBytes()` in TypeScript.
+    sig { params(putative: String).returns(T::Boolean) }
+    def signature_bytes?(putative)
+      putative.bytesize == SignatureBytes::BYTE_LENGTH
+    end
+
+    # Raises SolanaError if the binary string is not exactly 64 bytes.
+    # Mirrors `assertIsSignatureBytes()` in TypeScript.
+    sig { params(putative: String).void }
+    def assert_signature_bytes!(putative)
+      unless putative.bytesize == SignatureBytes::BYTE_LENGTH
+        Kernel.raise SolanaError.new(
+          SolanaError::KEYS__INVALID_SIGNATURE_BYTE_LENGTH,
+          actual_length: putative.bytesize
+        )
+      end
+    end
+
+    # Validates and wraps raw bytes in a SignatureBytes value object.
+    # Mirrors `signatureBytes()` in TypeScript.
+    sig { params(putative: String).returns(SignatureBytes) }
+    def signature_bytes(putative)
+      assert_signature_bytes!(putative)
+      SignatureBytes.new(putative.b)
+    end
+
+    # Signs data with an Ed25519 signing key, returning raw 64-byte SignatureBytes.
+    #
+    # Mirrors `signBytes(key: CryptoKey, data: ReadonlyUint8Array)` in TypeScript.
+    # TypeScript uses `crypto.subtle.sign` (async); Ruby uses RbNaCl (sync).
+    #
+    # @param signing_key [RbNaCl::SigningKey]
+    # @param data        [String] binary string to sign
+    sig { params(signing_key: T.untyped, data: String).returns(SignatureBytes) }
+    def sign_bytes(signing_key, data)
+      raw = signing_key.sign(data.b)
+      SignatureBytes.new(raw)
+    end
+
+    # Verifies an Ed25519 signature against a message.
+    #
+    # Mirrors `verifySignature(key, signature, data)` in TypeScript.
+    # Returns false rather than raising on mismatch, matching the TS return type.
+    #
+    # @param verify_key  [RbNaCl::VerifyKey]
+    # @param sig_bytes   [SignatureBytes]
+    # @param data        [String] binary string that was signed
+    sig { params(verify_key: T.untyped, sig_bytes: SignatureBytes, data: String).returns(T::Boolean) }
+    def verify_signature(verify_key, sig_bytes, data)
+      verify_key.verify(sig_bytes.value, data.b)
+      true
+    rescue RbNaCl::BadSignatureError
+      false
+    end
+
+    # Convenience: encode a SignatureBytes to a base58 Signature string.
+    sig { params(sig_bytes: SignatureBytes).returns(Signature) }
+    def encode_signature(sig_bytes)
+      Signature.new(Encoding::Base58.encode(sig_bytes.value))
+    end
+
+    # Convenience: decode a base58 Signature string to SignatureBytes.
+    sig { params(sig: Signature).returns(SignatureBytes) }
+    def decode_signature(sig)
+      bytes = Encoding::Base58.decode(sig.value)
+      signature_bytes(bytes)
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Utilities for validating, generating, and manipulating Ed25519 key material
+# and signatures. Mirrors the TypeScript package @solana/keys.
+#
+# Can be used standalone or as part of Solana::Ruby::Kit.
+require_relative 'keys/private_key'
+require_relative 'keys/public_key'
+require_relative 'keys/signatures'
+require_relative 'keys/key_pair'

data/lib/solana/ruby/kit/offchain_messages/codec.rb

@@ -0,0 +1,107 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+
+module Solana::Ruby::Kit
+  module OffchainMessages
+    # Wire format for off-chain messages (Solana standard).
+    #
+    # v0: [0xFF, 0xFF] + domain_len(u8) + domain + version(u8) + message_len(u16LE) + message
+    # v1: [0xFF, 0xFF] + domain_len(u8) + domain + version(u8) + app_domain_len(u16LE)
+    #       + app_domain + message_len(u16LE) + message
+    module Codec
+      extend T::Sig
+
+      MAGIC = T.let("\xFF\xFF".b.freeze, String)
+
+      module_function
+
+      # Serialize a Message to its canonical binary form.
+      sig { params(msg: Message).returns(String) }
+      def encode_offchain_message(msg)
+        domain_b = msg.domain.encode('ASCII').b
+        Kernel.raise ArgumentError, 'Domain exceeds 255 bytes' if domain_b.bytesize > 255
+
+        message_b = msg.message.encode('UTF-8').b
+        Kernel.raise ArgumentError, 'Message too large' if message_b.bytesize > 0xFFFF
+
+        buf = MAGIC.dup
+        buf << [domain_b.bytesize].pack('C')
+        buf << domain_b
+        buf << [msg.version].pack('C')
+
+        if msg.version >= 1 && msg.application_domain
+          app_b = T.must(msg.application_domain).encode('ASCII').b
+          Kernel.raise ArgumentError, 'Application domain exceeds 65535 bytes' if app_b.bytesize > 0xFFFF
+
+          buf << [app_b.bytesize].pack('v')
+          buf << app_b
+        end
+
+        buf << [message_b.bytesize].pack('v')
+        buf << message_b
+        buf.b
+      end
+
+      # Deserialize a Message from its canonical binary form.
+      sig { params(bytes: String).returns(Message) }
+      def decode_offchain_message(bytes) # rubocop:disable Metrics/MethodLength
+        b = bytes.b
+        Kernel.raise SolanaError.new(SolanaError::OFFCHAIN_MESSAGES__INVALID_MESSAGE_FORMAT) unless b.byteslice(0, 2) == MAGIC
+
+        offset     = 2
+        domain_len = b.byteslice(offset, 1)&.unpack1('C') || 0
+        offset    += 1
+        domain     = b.byteslice(offset, domain_len)&.force_encoding('ASCII') || ''
+        offset    += domain_len
+        version    = b.byteslice(offset, 1)&.unpack1('C') || 0
+        offset    += 1
+
+        application_domain = nil
+        if version >= 1
+          app_len = b.byteslice(offset, 2)&.unpack1('v') || 0
+          offset += 2
+          application_domain = b.byteslice(offset, app_len)&.force_encoding('ASCII')
+          offset += app_len
+        end
+
+        msg_len = b.byteslice(offset, 2)&.unpack1('v') || 0
+        offset += 2
+        message = b.byteslice(offset, msg_len)&.force_encoding('UTF-8') || ''
+
+        Message.new(
+          version:            version,
+          domain:             domain,
+          message:            message,
+          application_domain: application_domain
+        )
+      end
+
+      # Sign an off-chain message with a KeyPairSigner.
+      sig { params(signer: Signers::KeyPairSigner, msg: Message).returns(Keys::Signature) }
+      def sign_offchain_message(signer, msg)
+        payload = encode_offchain_message(msg)
+        Keys.encode_signature(signer.sign(payload))
+      end
+
+      # Verify an off-chain message signature.
+      sig do
+        params(
+          verify_key: String,   # 32-byte Ed25519 public key
+          signature:  Keys::Signature,
+          msg:        Message
+        ).returns(T::Boolean)
+      end
+      def verify_offchain_message_signature(verify_key, signature, msg)
+        payload  = encode_offchain_message(msg)
+        vk       = RbNaCl::VerifyKey.new(verify_key)
+        sig_bytes = signature.respond_to?(:to_bytes) ? signature.to_s : [signature.value].pack('H*')
+        vk.verify(sig_bytes, payload)
+        true
+      rescue RbNaCl::BadSignatureError
+        false
+      end
+    end
+  end
+end