solana-ruby-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 328621bd69f0601b600df302ea5169001983cf56fa44cf23225e3f2515d5d34a
+  data.tar.gz: 5e2bc165e53ff6818b5650f5d8551e6ec3331f65df3e656d0bb7ecd588c16fb3
+SHA512:
+  metadata.gz: 7664963dae246c46ef5d09c7f1d3d05b5c67cecc38dbd961955da8e86cce9a4d0aeff55fcc47425b35826dfe552bb032715f5f178dea8e8c716828013ebb151d
+  data.tar.gz: a5ee1ed23cca39029dc7a5e84f6319f06ef3319aaeb62488b12b702c6f7c391b8256ed7c706c140e4242285042a4d5b8c0ce7eb0fa484368a182556aa7ac0b84

data/lib/core_extensions/tapioca/name_patch.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+
+module T
+  module Types
+    class Simple
+      module NamePatch
+        NAME_METHOD = T.let(::Module.instance_method(:name), UnboundMethod)
+
+        def name
+          # Sorbet memoizes this method into the `@name` instance variable but
+          # doing so means that types get memoized before this patch is applied
+          qualified_name_of(@raw_type)
+        end
+
+        def qualified_name_of(constant)
+          name = NAME_METHOD.bind_call(constant)
+          name = nil if name&.start_with?("#<")
+          return if name.nil?
+
+          if name.start_with?("::")
+            name
+          else
+            "::#{name}"
+          end
+        end
+      end
+
+      prepend NamePatch
+    end
+  end
+end

data/lib/core_extensions/tapioca/required_ancestors.rb

@@ -0,0 +1,13 @@
+module T
+  module Helpers
+    prepend(::Module.new do
+      def requires_ancestor(&block)
+        # We can't directly call the block since the ancestor might not be loaded yet.
+        # We save the block in the map and will resolve it later.
+        Tapioca::Runtime::Trackers::RequiredAncestor.register(self, block)
+
+        super
+      end
+    end)
+  end
+end

data/lib/generators/solana/ruby/kit/install/install_generator.rb

@@ -0,0 +1,17 @@
+# typed: ignore
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Solana::Ruby::Kit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates a SolanaRubyKit initializer in config/initializers'
+
+      def copy_initializer
+        template 'solana_ruby_kit.rb.tt', 'config/initializers/solana_ruby_kit.rb'
+      end
+    end
+  end
+end

data/lib/generators/solana/ruby/kit/install/templates/solana_ruby_kit.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Solana::Ruby::Kit.configure do |config|
+  # config.rpc_url    = 'https://api.mainnet-beta.solana.com'
+  # config.ws_url     = 'wss://api.mainnet-beta.solana.com'
+  # config.commitment = :confirmed
+  # config.timeout    = 30
+end

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

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Accounts
+    # The number of bytes required to store the on-chain account header
+    # (lamports, owner, executable flag, rent epoch, and padding).
+    # Mirrors TypeScript's `BASE_ACCOUNT_SIZE = 128`.
+    BASE_ACCOUNT_SIZE = T.let(128, Integer)
+
+    # All on-chain attributes shared by every Solana account.
+    # Mirrors TypeScript's `BaseAccount`.
+    class BaseAccount < T::Struct
+      # Whether the account holds a program (executable code).
+      const :executable,      T::Boolean
+      # Balance of the account in lamports (1 SOL = 1_000_000_000 lamports).
+      # TypeScript uses `bigint`; Ruby uses arbitrary-precision Integer.
+      const :lamports,        Integer
+      # Address of the program that owns this account.
+      const :program_address, Addresses::Address
+      # Allocated storage in bytes.
+      const :space,           Integer
+    end
+
+    # A fully-populated Solana account including its address and data.
+    # Mirrors TypeScript's `Account<TData, TAddress>`.
+    #
+    # `data` is either:
+    #   - a binary String (when the account is encoded / raw bytes), or
+    #   - any Ruby object (when the account has been decoded by a codec).
+    class Account < T::Struct
+      const :address,         Addresses::Address
+      const :data,            T.untyped  # String (binary) or decoded struct
+      const :executable,      T::Boolean
+      const :lamports,        Integer
+      const :program_address, Addresses::Address
+      const :space,           Integer
+    end
+
+    # Convenience alias for an account whose data is still raw bytes.
+    # Mirrors TypeScript's `EncodedAccount<TAddress>`.
+    EncodedAccount = T.type_alias { Account }
+  end
+end

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

@@ -0,0 +1,86 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../errors'
+require_relative 'account'
+
+module Solana::Ruby::Kit
+  module Accounts
+    extend T::Sig
+    # Represents an account that may or may not exist on-chain.
+    # Mirrors TypeScript's discriminated union:
+    #   MaybeAccount<TData, TAddress> = Account<TData, TAddress> & { exists: true }
+    #                                 | { address: Address<TAddress>; exists: false }
+    #
+    # In Ruby we use a single class with an `exists` flag rather than a union
+    # type, since Sorbet cannot narrow struct unions at runtime as easily.
+    class MaybeAccount < T::Struct
+      # true  → the account exists; all Account fields are populated.
+      # false → the account does not exist; only `address` is set.
+      const :exists,          T::Boolean
+      const :address,         Addresses::Address
+      # The following fields are only valid when exists == true.
+      const :data,            T.untyped          # nil when exists == false
+      const :executable,      T.nilable(T::Boolean)
+      const :lamports,        T.nilable(Integer)
+      const :program_address, T.nilable(Addresses::Address)
+      const :space,           T.nilable(Integer)
+    end
+
+    module_function
+
+    # Builds a MaybeAccount representing a found account.
+    sig { params(account: Account).returns(MaybeAccount) }
+    def existing_account(account)
+      MaybeAccount.new(
+        exists:          true,
+        address:         account.address,
+        data:            account.data,
+        executable:      account.executable,
+        lamports:        account.lamports,
+        program_address: account.program_address,
+        space:           account.space
+      )
+    end
+
+    # Builds a MaybeAccount representing a missing account.
+    sig { params(address: Addresses::Address).returns(MaybeAccount) }
+    def missing_account(address)
+      MaybeAccount.new(
+        exists:          false,
+        address:         address,
+        data:            nil,
+        executable:      nil,
+        lamports:        nil,
+        program_address: nil,
+        space:           nil
+      )
+    end
+
+    # Raises SolanaError if the account does not exist.
+    # Mirrors `assertAccountExists()`.
+    sig { params(maybe_account: MaybeAccount).void }
+    def assert_account_exists!(maybe_account)
+      return if maybe_account.exists
+
+      Kernel.raise SolanaError.new(
+        :SOLANA_ERROR__ACCOUNTS__ACCOUNT_NOT_FOUND,
+        address: maybe_account.address.value
+      )
+    end
+
+    # Raises SolanaError listing all missing addresses if any account is absent.
+    # Mirrors `assertAccountsExist()`.
+    sig { params(maybe_accounts: T::Array[MaybeAccount]).void }
+    def assert_accounts_exist!(maybe_accounts)
+      missing = maybe_accounts.reject(&:exists).map { |a| a.address.value }
+      return if missing.empty?
+
+      Kernel.raise SolanaError.new(
+        :SOLANA_ERROR__ACCOUNTS__ONE_OR_MORE_ACCOUNTS_NOT_FOUND,
+        addresses: missing
+      )
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Account types and utilities — mirrors @solana/accounts.
+require_relative 'accounts/account'
+require_relative 'accounts/maybe_account'

data/lib/solana/ruby/kit/addresses/address.rb

@@ -0,0 +1,133 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../encoding/base58'
+
+module Solana::Ruby::Kit
+  module Addresses
+    extend T::Sig
+    # A validated, base58-encoded Solana address (32 bytes on-wire).
+    # Mirrors the TypeScript branded type:
+    #   type Address<TAddress extends string = string> = Brand<EncodedString<TAddress, 'base58'>, 'Address'>
+    #
+    # Because Sorbet does not support nominal/branded string types, Address is a
+    # lightweight value object whose string representation is always a validated
+    # base58 string.
+    class Address
+      extend T::Sig
+      include Comparable
+
+      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 { returns(String) }
+      def inspect = "#<#{self.class} \"#{@value}\">"
+
+      sig { params(other: T.untyped).returns(T.nilable(Integer)) }
+      def <=>(other)
+        return nil unless other.is_a?(Address)
+
+        @value <=> other.value
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        !!(other.is_a?(Address) && @value == other.value)
+      end
+
+      sig { returns(Integer) }
+      def hash = @value.hash
+
+      alias eql? ==
+    end
+
+    # ---------------------------------------------------------------------------
+    # Constants
+    # ---------------------------------------------------------------------------
+
+    # Expected byte length of a Solana address.
+    ADDRESS_BYTE_LENGTH = T.let(32, Integer)
+
+    # Minimum / maximum character lengths for a base58-encoded 32-byte address.
+    ADDRESS_MIN_STR_LEN = T.let(32, Integer)
+    ADDRESS_MAX_STR_LEN = T.let(44, Integer)
+
+    module_function
+
+    # Encodes raw bytes (binary String, length == 32) to a base58 address string.
+    # Mirrors `getAddressEncoder()` in TypeScript.
+    sig { params(bytes: String).returns(String) }
+    def encode_address(bytes)
+      Kernel.raise SolanaError.new(
+        SolanaError::ADDRESSES__INVALID_BYTE_LENGTH_FOR_ADDRESS,
+        byte_length: bytes.bytesize
+      ) unless bytes.bytesize == ADDRESS_BYTE_LENGTH
+
+      Encoding::Base58.encode(bytes)
+    end
+
+    # Decodes a base58 address string to a 32-byte binary String.
+    # Mirrors `getAddressDecoder()` in TypeScript.
+    sig { params(addr: Address).returns(String) }
+    def decode_address(addr)
+      bytes = Encoding::Base58.decode(addr.value)
+      Kernel.raise SolanaError.new(
+        SolanaError::ADDRESSES__INVALID_BYTE_LENGTH_FOR_ADDRESS,
+        byte_length: bytes.bytesize
+      ) unless bytes.bytesize == ADDRESS_BYTE_LENGTH
+
+      bytes
+    end
+
+    # Returns true if the string is a syntactically valid Solana address.
+    # Mirrors `isAddress()` in TypeScript.
+    sig { params(putative: String).returns(T::Boolean) }
+    def address?(putative)
+      return false unless putative.length.between?(ADDRESS_MIN_STR_LEN, ADDRESS_MAX_STR_LEN)
+      return false unless putative.chars.all? { |c| Encoding::Base58::ALPHABET.include?(c) }
+
+      bytes = Encoding::Base58.decode(putative)
+      bytes.bytesize == ADDRESS_BYTE_LENGTH
+    rescue ArgumentError
+      false
+    end
+
+    # Raises SolanaError if the string is not a valid Solana address.
+    # Mirrors `assertIsAddress()` in TypeScript.
+    sig { params(putative: String).void }
+    def assert_address!(putative)
+      unless putative.length.between?(ADDRESS_MIN_STR_LEN, ADDRESS_MAX_STR_LEN)
+        Kernel.raise SolanaError.new(
+          SolanaError::ADDRESSES__STRING_LENGTH_OUT_OF_RANGE,
+          actual_length: putative.length
+        )
+      end
+
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__INVALID_BASE58_ENCODED_ADDRESS) unless address?(putative)
+    end
+
+    # Validates and wraps a string in an Address value object.
+    # Mirrors `address()` in TypeScript.
+    sig { params(putative: String).returns(Address) }
+    def address(putative)
+      assert_address!(putative)
+      Address.new(putative)
+    end
+
+    # Returns a Proc that compares two Address values lexicographically,
+    # matching the semantics of `getAddressComparator()` in TypeScript.
+    sig { returns(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)) }
+    def address_comparator
+      ->(a, b) { a.value <=> b.value }
+    end
+  end
+end

data/lib/solana/ruby/kit/addresses/curve.rb

@@ -0,0 +1,112 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'address'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Addresses
+    extend T::Sig
+    # OffCurveAddress marks an Address whose 32-byte representation does NOT lie
+    # on the Ed25519 curve. PDAs are always off-curve by definition.
+    #
+    # Mirrors TypeScript:
+    #   type OffCurveAddress = Brand<Address, AffinePoint>
+    class OffCurveAddress < Address; end
+
+    # ---------------------------------------------------------------------------
+    # Ed25519 curve parameters (RFC 8032, Section 5.1)
+    # ---------------------------------------------------------------------------
+
+    # Field prime p = 2^255 − 19
+    CURVE_P = T.let(T.unsafe(2**255 - 19), Integer)
+
+    # Curve constant d = −121665/121666 mod p  (computed to avoid oversized literals)
+    CURVE_D = T.let((-121665 * 121666.pow(CURVE_P - 2, CURVE_P)) % CURVE_P, Integer)
+
+    # sqrt(−1) mod p  =  2^((p−1)/4) mod p
+    CURVE_SQRT_M1 = T.let(2.pow((CURVE_P - 1) / 4, CURVE_P), Integer)
+
+    module_function
+
+    # Returns true if the 32-byte binary string represents a point on the
+    # Ed25519 twisted-Edwards curve.
+    #
+    # Algorithm follows RFC 8032, Section 5.1.3 (point decompression):
+    #   1. Extract y coordinate and the sign bit of x.
+    #   2. Compute x² = (y²−1) / (d·y²+1)  mod p.
+    #   3. Recover x using the curve's square-root formula.
+    #   4. If no valid x exists the bytes are off-curve → return false.
+    sig { params(bytes: String).returns(T::Boolean) }
+    def on_ed25519_curve?(bytes)
+      return false unless bytes.bytesize == 32
+
+      p = CURVE_P
+      d = CURVE_D
+
+      y_arr = bytes.bytes.dup
+      x_sign = (y_arr[31] >> 7) & 1
+      y_arr[31] &= 0x7f
+
+      # Little-endian byte array → big integer
+      y = y_arr.each_with_index.sum { |b, i| b << (8 * i) }
+      return false if y >= p
+
+      y2 = y.pow(2, p)
+      u  = (y2 - 1) % p       # numerator:   y² − 1
+      v  = (d * y2 + 1) % p   # denominator: d·y² + 1
+
+      # RFC 8032 square-root formula:
+      #   x = (u·v³) · (u·v⁷)^((p−5)/8)  mod p
+      v3   = v.pow(3, p)
+      v7   = v.pow(7, p)
+      exp  = (p - 5) / 8
+      x    = u * v3 % p * (u * v7 % p).pow(exp, p) % p
+      vx2  = v * x.pow(2, p) % p
+
+      if vx2 == u % p
+        # Valid root found; adjust sign.
+        x = (p - x) % p if (x & 1) != x_sign
+        return true
+      end
+
+      if vx2 == (p - u) % p
+        # x must be multiplied by sqrt(−1).
+        x = x * CURVE_SQRT_M1 % p
+        x = (p - x) % p if (x & 1) != x_sign
+        return true
+      end
+
+      false
+    end
+
+    # Returns true if the address bytes are NOT on the Ed25519 curve.
+    sig { params(bytes: String).returns(T::Boolean) }
+    def off_curve_bytes?(bytes)
+      !on_ed25519_curve?(bytes)
+    end
+
+    # Type guard — returns true if the given Address is off-curve.
+    # Mirrors `isOffCurveAddress()` in TypeScript.
+    sig { params(addr: Address).returns(T::Boolean) }
+    def off_curve_address?(addr)
+      bytes = decode_address(addr)
+      off_curve_bytes?(bytes)
+    end
+
+    # Raises SolanaError if the address is on the Ed25519 curve.
+    # Mirrors `assertIsOffCurveAddress()` in TypeScript.
+    sig { params(addr: Address).void }
+    def assert_off_curve_address!(addr)
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__SEEDS_POINT_ON_CURVE) if on_ed25519_curve?(decode_address(addr))
+    end
+
+    # Validates and narrows an Address to OffCurveAddress.
+    # Mirrors `offCurveAddress()` in TypeScript.
+    sig { params(addr: Address).returns(OffCurveAddress) }
+    def off_curve_address(addr)
+      assert_off_curve_address!(addr)
+      OffCurveAddress.new(addr.value)
+    end
+  end
+end

data/lib/solana/ruby/kit/addresses/program_derived_address.rb

@@ -0,0 +1,155 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'address'
+require_relative 'curve'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Addresses
+    extend T::Sig
+    # The integer bump seed used when deriving a PDA.  Must be in [0, 255].
+    # Mirrors TypeScript: `type ProgramDerivedAddressBump = Brand<number, 'ProgramDerivedAddressBump'>`
+    ProgramDerivedAddressBump = T.type_alias { Integer }
+
+    # A PDA is an (address, bump_seed) pair.
+    # Mirrors TypeScript: `type ProgramDerivedAddress = [Address, ProgramDerivedAddressBump]`
+    class ProgramDerivedAddress < T::Struct
+      const :address, Address
+      const :bump,    Integer   # 0–255
+    end
+
+    # Accepted seed types mirror TypeScript's `Seeds` union:
+    #   type Seed = ReadonlyUint8Array | string
+    # In Ruby, a seed is either a binary String or an Integer Array.
+    Seed = T.type_alias { T.any(String, T::Array[Integer]) }
+
+    # ---------------------------------------------------------------------------
+    # Constants
+    # ---------------------------------------------------------------------------
+
+    # Maximum byte length of a single seed.
+    MAX_SEED_LENGTH = T.let(32, Integer)
+
+    # Maximum number of seeds per PDA derivation.
+    MAX_SEEDS = T.let(16, Integer)
+
+    # Marker bytes appended during hashing: UTF-8 "ProgramDerivedAddress".
+    PDA_MARKER_BYTES = T.let('ProgramDerivedAddress'.b, String)
+
+    module_function
+
+    # Returns true if the value is a well-formed ProgramDerivedAddress.
+    # Mirrors `isProgramDerivedAddress()` in TypeScript.
+    sig { params(value: T.untyped).returns(T::Boolean) }
+    def program_derived_address?(value)
+      return false unless value.is_a?(ProgramDerivedAddress)
+      return false unless address?(value.address.value)
+
+      bump = value.bump
+      bump.between?(0, 255)
+    end
+
+    # Raises SolanaError if the value is not a valid ProgramDerivedAddress.
+    # Mirrors `assertIsProgramDerivedAddress()` in TypeScript.
+    sig { params(value: T.untyped).void }
+    def assert_program_derived_address!(value)
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__INVALID_SEEDS_POINT_ON_CURVE) unless value.is_a?(ProgramDerivedAddress)
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__PDA_BUMP_SEED_OUT_OF_RANGE) unless value.bump.between?(0, 255)
+    end
+
+    # Derives the Program Derived Address for a given program and up to 16 seeds.
+    #
+    # Searches from bump seed 255 down to 0, returning the first address whose
+    # 32-byte SHA-256 hash does NOT lie on the Ed25519 curve.
+    #
+    # Mirrors `getProgramDerivedAddress()` in TypeScript.
+    sig do
+      params(
+        program_address: Address,
+        seeds:           T::Array[Seed]
+      ).returns(ProgramDerivedAddress)
+    end
+    def get_program_derived_address(program_address:, seeds:)
+      if seeds.length > MAX_SEEDS
+        Kernel.raise SolanaError.new(SolanaError::ADDRESSES__TOO_MANY_SEEDS)
+      end
+
+      seeds.each do |seed|
+        seed_bytes = seed_to_bytes(seed)
+        if seed_bytes.bytesize > MAX_SEED_LENGTH
+          Kernel.raise SolanaError.new(
+            SolanaError::ADDRESSES__MAX_SEED_LENGTH_EXCEEDED,
+            actual_length: seed_bytes.bytesize
+          )
+        end
+      end
+
+      program_bytes = decode_address(program_address)
+
+      255.downto(0) do |bump|
+        seed_bytes_list = seeds.map { |s| seed_to_bytes(s) }
+        bump_bytes       = [bump].pack('C').b
+
+        # hash_input = seed1 || seed2 || ... || bump || program_address || "ProgramDerivedAddress"
+        hash_input = (seed_bytes_list + [bump_bytes, program_bytes, PDA_MARKER_BYTES]).join
+
+        candidate_bytes = Digest::SHA256.digest(hash_input)
+
+        next if on_ed25519_curve?(candidate_bytes)
+
+        candidate_address = Address.new(encode_address(candidate_bytes))
+        return ProgramDerivedAddress.new(address: candidate_address, bump: bump)
+      end
+
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__FAILED_TO_FIND_VIABLE_PDA_BUMP_SEED)
+    end
+
+    # Derives an address from a base address, program address, and an arbitrary seed.
+    # Uses SHA-256 of (base_address || seed || program_address).
+    #
+    # Mirrors `createAddressWithSeed()` in TypeScript.
+    sig do
+      params(
+        base_address:    Address,
+        program_address: Address,
+        seed:            String
+      ).returns(Address)
+    end
+    def create_address_with_seed(base_address:, program_address:, seed:)
+      seed_bytes = seed.b
+
+      if seed_bytes.bytesize > MAX_SEED_LENGTH
+        Kernel.raise SolanaError.new(
+          SolanaError::ADDRESSES__MAX_SEED_LENGTH_EXCEEDED,
+          actual_length: seed_bytes.bytesize
+        )
+      end
+
+      base_bytes    = decode_address(base_address)
+      program_bytes = decode_address(program_address)
+
+      # hash_input = base_address || seed || program_address
+      hash_input   = base_bytes + seed_bytes + program_bytes
+      result_bytes = Digest::SHA256.digest(hash_input)
+
+      Address.new(encode_address(result_bytes))
+    end
+
+    # ---------------------------------------------------------------------------
+    # Private helpers
+    # ---------------------------------------------------------------------------
+
+    # Converts a Seed (binary String or Integer Array) to a binary String.
+    sig { params(seed: Seed).returns(String) }
+    def seed_to_bytes(seed)
+      case seed
+      when String then seed.b
+      when Array  then seed.pack('C*').b
+      else T.absurd(seed)
+      end
+    end
+    private_class_method :seed_to_bytes
+  end
+end

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

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative 'address'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Addresses
+    extend T::Sig
+    module_function
+
+    # Given an RbNaCl::VerifyKey (Ed25519 public key), returns its Solana Address.
+    #
+    # Mirrors TypeScript's `getAddressFromPublicKey(publicKey: CryptoKey)`.
+    # In TypeScript this is async because it uses Web Crypto API's `exportKey`.
+    # In Ruby, RbNaCl exposes the raw bytes directly, so no async overhead is needed.
+    sig { params(verify_key: T.untyped).returns(Address) }
+    def get_address_from_public_key(verify_key)
+      unless verify_key.is_a?(RbNaCl::VerifyKey)
+        Kernel.raise SolanaError.new(SolanaError::ADDRESSES__INVALID_ED25519_PUBLIC_KEY)
+      end
+
+      Address.new(encode_address(verify_key.to_bytes))
+    end
+
+    # Given a Solana Address, returns the corresponding RbNaCl::VerifyKey.
+    # Raises SolanaError if the address bytes are not a valid Ed25519 public key.
+    #
+    # Mirrors TypeScript's `getPublicKeyFromAddress(address: Address)`.
+    sig { params(addr: Address).returns(T.untyped) }
+    def get_public_key_from_address(addr)
+      bytes = decode_address(addr)
+      RbNaCl::VerifyKey.new(bytes)
+    rescue RangeError, ScriptError => e
+      Kernel.raise SolanaError.new(SolanaError::ADDRESSES__INVALID_ED25519_PUBLIC_KEY)
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Utilities for generating and validating Solana account addresses.
+# Mirrors the TypeScript package @solana/addresses.
+#
+# Can be used standalone or as part of Solana::Ruby::Kit.
+require_relative 'addresses/address'
+require_relative 'addresses/curve'
+require_relative 'addresses/program_derived_address'
+require_relative 'addresses/public_key'