solana-ruby-kit 0.1.0 → 0.1.5

data/lib/solana/ruby/kit/transactions/compiler.rb

@@ -0,0 +1,211 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'transaction'
+require_relative '../addresses/address'
+require_relative '../transaction_messages/transaction_message'
+require_relative '../instructions/roles'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Transactions
+    # Maximum wire-encoded transaction size in bytes (Solana protocol limit).
+    TRANSACTION_SIZE_LIMIT = T.let(1232, Integer)
+
+    module_function
+
+    # Returns the compiled byte-size of a transaction message.
+    # Mirrors `getTransactionMessageSize()` from @solana/transactions.
+    # The message must have a fee payer and a blockhash lifetime set.
+    sig { params(message: TransactionMessages::TransactionMessage).returns(Integer) }
+    def get_transaction_message_size(message)
+      compile_transaction_message(message).message_bytes.bytesize
+    end
+
+    # ---------------------------------------------------------------------------
+    # compile_transaction_message
+    # ---------------------------------------------------------------------------
+    # Compiles a TransactionMessage into a Transaction ready for signing.
+    #
+    # Only legacy (version: :legacy) transactions are supported; the serialised
+    # format follows the Solana on-wire message layout:
+    #
+    #   [header: 3 bytes]
+    #   [compact-u16 account count] [32-byte addresses …]
+    #   [recent blockhash: 32 bytes]
+    #   [compact-u16 instruction count]
+    #   [for each instruction:
+    #     [program_id_index: u8]
+    #     [compact-u16 account count] [account indices: u8 …]
+    #     [compact-u16 data length]  [data bytes]
+    #   ]
+    #
+    # The returned Transaction contains:
+    #   - message_bytes  — the serialised message (the bytes that are signed)
+    #   - signatures     — an ordered hash of signer_address → nil (unfilled)
+    #
+    # Use wire_encode_transaction to prepend the signatures section before
+    # submitting to the RPC node via sendTransaction.
+    sig { params(message: TransactionMessages::TransactionMessage).returns(Transaction) }
+    def compile_transaction_message(message)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__TRANSACTION__FEE_PAYER_MISSING) if message.fee_payer.nil?
+      fee_payer = T.must(message.fee_payer)
+
+      # ── 1. Collect accounts and merge roles ────────────────────────────────
+      # Insertion-ordered hash: address_str → merged AccountRole integer.
+      account_roles = T.let({}, T::Hash[String, Integer])
+
+      # Fee payer is always the first writable signer.
+      account_roles[fee_payer.value] = Instructions::AccountRole::WRITABLE_SIGNER
+
+      message.instructions.each do |ix|
+        # The instruction's program address is a readonly non-signer participant.
+        prog = ix.program_address.value
+        account_roles[prog] ||= Instructions::AccountRole::READONLY
+
+        (ix.accounts || []).each do |meta|
+          addr     = meta.address.value
+          existing = account_roles[addr] || Instructions::AccountRole::READONLY
+          account_roles[addr] = Instructions::AccountRole.merge(existing, meta.role)
+        end
+      end
+
+      # ── 2. Partition into the four groups and sort within each ─────────────
+      fp = fee_payer.value
+
+      writable_signers    = T.let([], T::Array[String])
+      readonly_signers    = T.let([], T::Array[String])
+      writable_non_signers = T.let([], T::Array[String])
+      readonly_non_signers = T.let([], T::Array[String])
+
+      account_roles.each do |addr, role|
+        next if addr == fp  # fee payer is handled separately
+
+        is_signer   = Instructions::AccountRole.signer_role?(role)
+        is_writable = Instructions::AccountRole.writable_role?(role)
+
+        if is_signer && is_writable
+          writable_signers << addr
+        elsif is_signer
+          readonly_signers << addr
+        elsif is_writable
+          writable_non_signers << addr
+        else
+          readonly_non_signers << addr
+        end
+      end
+
+      writable_signers.sort!
+      readonly_signers.sort!
+      writable_non_signers.sort!
+      readonly_non_signers.sort!
+
+      # Fee payer first, then writable signers, readonly signers, non-signers.
+      ordered = [fp] + writable_signers + readonly_signers +
+                writable_non_signers + readonly_non_signers
+
+      # ── 3. Build index lookup ──────────────────────────────────────────────
+      account_index = T.let({}, T::Hash[String, Integer])
+      ordered.each_with_index { |addr, i| account_index[addr] = i }
+
+      # ── 4. Message header (3 bytes) ────────────────────────────────────────
+      num_required_sigs    = 1 + writable_signers.size + readonly_signers.size
+      num_readonly_signed  = readonly_signers.size
+      num_readonly_unsigned = readonly_non_signers.size
+
+      header = [num_required_sigs, num_readonly_signed, num_readonly_unsigned].pack('CCC').b
+
+      # ── 5. Account addresses section ───────────────────────────────────────
+      accounts_section = encode_compact_u16(ordered.size)
+      ordered.each do |addr_str|
+        accounts_section = accounts_section + Addresses.decode_address(Addresses::Address.new(addr_str))
+      end
+
+      # ── 6. Recent blockhash (32 bytes) ─────────────────────────────────────
+      # Mirrors upstream compile-transaction.ts #581:
+      #   - BlockhashLifetime → use the blockhash bytes
+      #   - DurableNonceLifetime → use the nonce value bytes (stored in the same field)
+      #   - No lifetime → 32 zero bytes (placeholder; must be replaced before signing)
+      constraint = message.lifetime_constraint
+      blockhash_bytes =
+        if constraint.is_a?(TransactionMessages::BlockhashLifetimeConstraint)
+          Addresses.decode_address(Addresses::Address.new(constraint.blockhash))
+        elsif constraint.is_a?(TransactionMessages::DurableNonceLifetimeConstraint)
+          Addresses.decode_address(Addresses::Address.new(constraint.nonce))
+        else
+          ("\x00" * 32).b
+        end
+
+      # ── 7. Instructions section ────────────────────────────────────────────
+      ixs_section = encode_compact_u16(message.instructions.size)
+
+      message.instructions.each do |ix|
+        prog_idx    = T.must(account_index[ix.program_address.value])
+        ix_accounts = ix.accounts || []
+        ix_indices  = ix_accounts.map { |m| T.must(account_index[m.address.value]) }
+        data_bytes  = (ix.data || '').b
+
+        ixs_section = ixs_section +
+                      [prog_idx].pack('C').b +
+                      encode_compact_u16(ix_indices.size) +
+                      ix_indices.pack('C*').b +
+                      encode_compact_u16(data_bytes.bytesize) +
+                      data_bytes
+      end
+
+      message_bytes = (header + accounts_section + blockhash_bytes + ixs_section).b
+
+      # ── 8. Signatures map (one nil slot per required signer) ───────────────
+      signer_addresses = [fp] + writable_signers + readonly_signers
+      signatures = T.let({}, T::Hash[String, T.nilable(String)])
+      signer_addresses.each { |addr| signatures[addr] = nil }
+
+      Transaction.new(message_bytes: message_bytes, signatures: signatures)
+    end
+
+    # ---------------------------------------------------------------------------
+    # wire_encode_transaction
+    # ---------------------------------------------------------------------------
+    # Encodes a Transaction (signed or partially signed) into the full Solana
+    # on-wire format that the RPC node's sendTransaction method expects:
+    #
+    #   [compact-u16 signature count]
+    #   [64-byte signature or 64 zero bytes if nil] × count
+    #   [message bytes]
+    #
+    # The result is a binary String; base64-encode it before sending via HTTP.
+    sig { params(transaction: Transaction).returns(String) }
+    def wire_encode_transaction(transaction)
+      sigs    = transaction.signatures
+      header  = encode_compact_u16(sigs.size)
+      sig_bytes = sigs.values.map { |s| (s || ("\x00" * 64)).b }.join
+
+      (header + sig_bytes + transaction.message_bytes).b
+    end
+
+    # ---------------------------------------------------------------------------
+    # Private helpers
+    # ---------------------------------------------------------------------------
+
+    # Encodes a non-negative integer using Solana's compact-u16 format.
+    #   0–127     → 1 byte
+    #   128–16383 → 2 bytes
+    #   16384+    → 3 bytes (max value 0x7fff used in practice)
+    sig { params(value: Integer).returns(String) }
+    def encode_compact_u16(value)
+      result    = T.let([], T::Array[Integer])
+      remaining = value
+
+      Kernel.loop do
+        byte       = remaining & 0x7f
+        remaining  = remaining >> 7
+        byte      |= 0x80 if remaining > 0
+        result << byte
+        break if remaining == 0
+      end
+
+      result.pack('C*').b
+    end
+    private_class_method :encode_compact_u16
+  end
+end

data/lib/solana/ruby/kit/transactions/transaction.rb

@@ -67,6 +67,42 @@ module Solana::Ruby::Kit
       )
     end
 
+    # Returns true if the wire-encoded transaction fits within TRANSACTION_SIZE_LIMIT.
+    # Mirrors `isTransactionWithinSizeLimit(transaction)`.
+    sig { params(transaction: Transaction).returns(T::Boolean) }
+    def within_size_limit?(transaction)
+      wire_encode_transaction(transaction).bytesize <= TRANSACTION_SIZE_LIMIT
+    end
+
+    # Raises SolanaError if the wire-encoded transaction exceeds TRANSACTION_SIZE_LIMIT.
+    # Mirrors `assertIsTransactionWithinSizeLimit(transaction)`.
+    sig { params(transaction: Transaction).void }
+    def assert_within_size_limit!(transaction)
+      actual = wire_encode_transaction(transaction).bytesize
+      return if actual <= TRANSACTION_SIZE_LIMIT
+
+      Kernel.raise SolanaError.new(
+        SolanaError::TRANSACTIONS__EXCEEDS_SIZE_LIMIT,
+        { actual_size: actual, limit: TRANSACTION_SIZE_LIMIT }
+      )
+    end
+
+    # Returns true if the transaction is both fully signed and within the size limit.
+    # Mirrors `isSendableTransaction(transaction)`.
+    # sendableTransaction = FullySignedTransaction & TransactionWithinSizeLimit
+    sig { params(transaction: Transaction).returns(T::Boolean) }
+    def sendable_transaction?(transaction)
+      fully_signed_transaction?(transaction) && within_size_limit?(transaction)
+    end
+
+    # Raises SolanaError unless the transaction is fully signed and within size limit.
+    # Mirrors `assertIsSendableTransaction(transaction)`.
+    sig { params(transaction: Transaction).void }
+    def assert_sendable_transaction!(transaction)
+      assert_fully_signed_transaction!(transaction)
+      assert_within_size_limit!(transaction)
+    end
+
     # Signs a transaction with one or more RbNaCl::SigningKey objects.
     # Only keys whose address appears in `transaction.signatures` are applied.
     # Raises SolanaError if a key is not expected to sign this transaction.

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

@@ -3,3 +3,4 @@
 
 # Transaction types and signing utilities — mirrors @solana/transactions.
 require_relative 'transactions/transaction'
+require_relative 'transactions/compiler'

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '0.1.0'
+      VERSION = '0.1.5'
     end
   end
 end

data/solana-ruby-kit.gemspec

@@ -5,7 +5,7 @@ require_relative 'lib/solana/ruby/kit/version'
 Gem::Specification.new do |spec|
   spec.name                  = 'solana-ruby-kit'
   spec.version               = Solana::Ruby::Kit::VERSION
-  spec.authors               = ['Paul Zupan']
+  spec.authors               = ['Paul Zupan, Idhra Inc.']
   spec.summary               = 'Ruby port of the Anza TypeScript SDK (@anza-xyz/kit)'
   spec.license               = 'MIT'
   spec.required_ruby_version = '>= 3.2.0'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.5
 platform: ruby
 authors:
-- Paul Zupan
+- Paul Zupan, Idhra Inc.
 bindir: bin
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -208,7 +208,12 @@ files:
 - lib/solana/ruby/kit/fast_stable_stringify.rb
 - lib/solana/ruby/kit/functional.rb
 - lib/solana/ruby/kit/instruction_plans.rb
+- lib/solana/ruby/kit/instruction_plans/instruction_plan.rb
 - lib/solana/ruby/kit/instruction_plans/plans.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan_executor.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan_result.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_planner.rb
 - lib/solana/ruby/kit/instructions.rb
 - lib/solana/ruby/kit/instructions/accounts.rb
 - lib/solana/ruby/kit/instructions/instruction.rb
@@ -225,6 +230,8 @@ files:
 - lib/solana/ruby/kit/options/option.rb
 - lib/solana/ruby/kit/plugin_core.rb
 - lib/solana/ruby/kit/programs.rb
+- lib/solana/ruby/kit/programs/associated_token_account.rb
+- lib/solana/ruby/kit/programs/system_program.rb
 - lib/solana/ruby/kit/promises.rb
 - lib/solana/ruby/kit/railtie.rb
 - lib/solana/ruby/kit/rpc.rb
@@ -285,6 +292,7 @@ files:
 - lib/solana/ruby/kit/transaction_messages.rb
 - lib/solana/ruby/kit/transaction_messages/transaction_message.rb
 - lib/solana/ruby/kit/transactions.rb
+- lib/solana/ruby/kit/transactions/compiler.rb
 - lib/solana/ruby/kit/transactions/transaction.rb
 - lib/solana/ruby/kit/version.rb
 - solana-ruby-kit.gemspec