solana-ruby-kit 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 328621bd69f0601b600df302ea5169001983cf56fa44cf23225e3f2515d5d34a
-  data.tar.gz: 5e2bc165e53ff6818b5650f5d8551e6ec3331f65df3e656d0bb7ecd588c16fb3
+  metadata.gz: 8be22a1330f9190db447c2a209a2dc44991c75efc6758bbe9e94f6e56b579473
+  data.tar.gz: c33dc52550866af9c572ce7911fe0baa9d053dc0f4723e5b700f0473ee5ffee4
 SHA512:
-  metadata.gz: 7664963dae246c46ef5d09c7f1d3d05b5c67cecc38dbd961955da8e86cce9a4d0aeff55fcc47425b35826dfe552bb032715f5f178dea8e8c716828013ebb151d
-  data.tar.gz: a5ee1ed23cca39029dc7a5e84f6319f06ef3319aaeb62488b12b702c6f7c391b8256ed7c706c140e4242285042a4d5b8c0ce7eb0fa484368a182556aa7ac0b84
+  metadata.gz: ee653c6ea8f2b6b2dd5359e6d49281431d9127db48600d836d560ebd32dde7e75294fc6cc44f8b609de4fb0bc565bf3e810a30ca050ce78d7e8506177e7ba6cd
+  data.tar.gz: 5483176779980f87b8102e81dca85afc4f71a413281b5b296d50edee38ebae9b000c370d75362a442abd84589ec6014b661e075623aa5ba7cf5920df0b20bd4b

data/lib/solana/ruby/kit/programs/associated_token_account.rb

@@ -0,0 +1,133 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../addresses/program_derived_address'
+require_relative '../instructions/instruction'
+require_relative '../instructions/accounts'
+
+module Solana::Ruby::Kit
+  module Programs
+    # Ruby interface for the SPL Associated Token Account on-chain program.
+    #
+    # An Associated Token Account (ATA) is a Program Derived Address that holds
+    # SPL token balances for a given wallet + mint pair.  The ATA address is
+    # deterministic: given a wallet and a mint, there is exactly one "canonical"
+    # token account for that combination.
+    #
+    # Seeds used for PDA derivation (all raw 32-byte address buffers):
+    #   [ wallet_bytes, token_program_bytes, mint_bytes ]
+    # Program: PROGRAM_ID (the Associated Token Account program)
+    #
+    # Reference: https://github.com/solana-program/associated-token-account
+    module AssociatedTokenAccount
+      extend T::Sig
+
+      # SPL Associated Token Account program.
+      PROGRAM_ID = T.let(
+        Addresses::Address.new('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'),
+        Addresses::Address
+      )
+
+      # Original SPL Token program (spl-token).
+      TOKEN_PROGRAM_ID = T.let(
+        Addresses::Address.new('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
+        Addresses::Address
+      )
+
+      # Token Extensions program (spl-token-2022).
+      TOKEN_2022_PROGRAM_ID = T.let(
+        Addresses::Address.new('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'),
+        Addresses::Address
+      )
+
+      # Solana System Program.
+      SYSTEM_PROGRAM_ID = T.let(
+        Addresses::Address.new('11111111111111111111111111111111'),
+        Addresses::Address
+      )
+
+      module_function
+
+      # Derives the canonical Associated Token Account address (a PDA) for a
+      # given wallet and mint.
+      #
+      # @param wallet           [Addresses::Address]  the account that will own the ATA
+      # @param mint             [Addresses::Address]  the token mint
+      # @param token_program_id [Addresses::Address]  TOKEN_PROGRAM_ID or TOKEN_2022_PROGRAM_ID
+      # @return [Addresses::ProgramDerivedAddress]    the ATA address + bump seed
+      sig do
+        params(
+          wallet:           Addresses::Address,
+          mint:             Addresses::Address,
+          token_program_id: Addresses::Address
+        ).returns(Addresses::ProgramDerivedAddress)
+      end
+      def get_associated_token_address(wallet:, mint:, token_program_id: TOKEN_PROGRAM_ID)
+        wallet_bytes        = Addresses.decode_address(wallet)
+        token_program_bytes = Addresses.decode_address(token_program_id)
+        mint_bytes          = Addresses.decode_address(mint)
+
+        Addresses.get_program_derived_address(
+          program_address: PROGRAM_ID,
+          seeds:           [wallet_bytes, token_program_bytes, mint_bytes]
+        )
+      end
+
+      # Builds an instruction that creates an Associated Token Account.
+      #
+      # Account layout expected by the on-chain program (in order):
+      #   0. payer                    — writable, signer (funds the rent)
+      #   1. associated_token_account — writable (the new ATA; derived via PDA)
+      #   2. wallet                   — readonly  (the ATA's owner)
+      #   3. mint                     — readonly
+      #   4. system_program           — readonly
+      #   5. token_program            — readonly
+      #
+      # Instruction data:
+      #   nil / empty  →  "Create"         (fails if the ATA already exists)
+      #   "\x01"       →  "CreateIdempotent" (no-op if already initialised)
+      #
+      # @param payer            [Addresses::Address]  pays for rent
+      # @param wallet           [Addresses::Address]  will own the ATA
+      # @param mint             [Addresses::Address]  token mint
+      # @param token_program_id [Addresses::Address]  which token program to use
+      # @param idempotent       [Boolean]             use the idempotent variant
+      # @return [Instructions::Instruction]
+      sig do
+        params(
+          payer:            Addresses::Address,
+          wallet:           Addresses::Address,
+          mint:             Addresses::Address,
+          token_program_id: Addresses::Address,
+          idempotent:       T::Boolean
+        ).returns(Instructions::Instruction)
+      end
+      def create_instruction(
+        payer:,
+        wallet:,
+        mint:,
+        token_program_id: TOKEN_PROGRAM_ID,
+        idempotent: false
+      )
+        ata = get_associated_token_address(wallet: wallet, mint: mint, token_program_id: token_program_id)
+
+        # Discriminator: none for "Create", 0x01 for "CreateIdempotent"
+        data = idempotent ? "\x01".b : nil
+
+        Instructions::Instruction.new(
+          program_address: PROGRAM_ID,
+          accounts: [
+            Instructions.writable_signer_account(payer),          # 0 payer
+            Instructions.writable_account(ata.address),            # 1 ATA to create
+            Instructions.readonly_account(wallet),                  # 2 owner (readonly)
+            Instructions.readonly_account(mint),                    # 3 mint
+            Instructions.readonly_account(SYSTEM_PROGRAM_ID),      # 4 System Program
+            Instructions.readonly_account(token_program_id),       # 5 Token Program
+          ],
+          data: data
+        )
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/programs/system_program.rb

@@ -0,0 +1,69 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../instructions/instruction'
+require_relative '../instructions/accounts'
+
+module Solana::Ruby::Kit
+  module Programs
+    # Ruby interface for the Solana System Program (11111111111111111111111111111111).
+    #
+    # The System Program is responsible for creating accounts, transferring SOL,
+    # and other low-level operations.  Instruction data uses little-endian encoding:
+    # a u32 discriminator identifying the instruction variant, followed by any
+    # instruction-specific fields.
+    #
+    # Reference: https://github.com/solana-program/system
+    module SystemProgram
+      extend T::Sig
+
+      # The System Program address (all zeros, encoded in base58).
+      PROGRAM_ID = T.let(
+        Addresses::Address.new('11111111111111111111111111111111'),
+        Addresses::Address
+      )
+
+      # Instruction discriminators (u32 little-endian).
+      DISCRIMINATOR_TRANSFER = T.let(2, Integer)
+
+      module_function
+
+      # Builds a System Program Transfer instruction that moves +lamports+ from
+      # +sender+ to +recipient+.
+      #
+      # Instruction data layout (12 bytes):
+      #   [0..3]  u32 LE  — discriminator (2)
+      #   [4..11] u64 LE  — lamports
+      #
+      # Accounts:
+      #   0. sender    — writable, signer (source of SOL)
+      #   1. recipient — writable         (destination)
+      #
+      # @param sender    [Addresses::Address]
+      # @param recipient [Addresses::Address]
+      # @param lamports  [Integer]  amount to transfer (1 SOL = 1_000_000_000 lamports)
+      # @return [Instructions::Instruction]
+      sig do
+        params(
+          sender:    Addresses::Address,
+          recipient: Addresses::Address,
+          lamports:  Integer
+        ).returns(Instructions::Instruction)
+      end
+      def transfer_instruction(sender:, recipient:, lamports:)
+        # Pack as: u32 LE discriminator || u64 LE lamports
+        data = [DISCRIMINATOR_TRANSFER, lamports].pack('VQ<').b
+
+        Instructions::Instruction.new(
+          program_address: PROGRAM_ID,
+          accounts: [
+            Instructions.writable_signer_account(sender),    # 0 sender
+            Instructions.writable_account(recipient),         # 1 recipient
+          ],
+          data: data
+        )
+      end
+    end
+  end
+end

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

@@ -3,6 +3,8 @@
 
 # Mirrors @solana/programs — helpers for inspecting custom program errors
 # returned in Solana transaction failures.
+require_relative 'programs/associated_token_account'
+require_relative 'programs/system_program'
 #
 # A program error in a transaction result looks like:
 #   { "InstructionError" => [0, { "Custom" => 1234 }] }

data/lib/solana/ruby/kit/rpc/api/send_transaction.rb

@@ -3,6 +3,7 @@
 
 require 'base64'
 require_relative '../../keys/signatures'
+require_relative '../../transactions/compiler'
 
 module Solana::Ruby::Kit
   module Rpc
@@ -43,7 +44,7 @@ module Solana::Ruby::Kit
               transaction
             else
               # Assume it responds to .message_bytes (Transactions::Transaction)
-              Base64.strict_encode64(transaction.message_bytes)
+              Base64.strict_encode64(Transactions.wire_encode_transaction(transaction))
             end
 
           config = { 'encoding' => 'base64' }

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

@@ -0,0 +1,192 @@
+# 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
+    module_function
+
+    # ---------------------------------------------------------------------------
+    # 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)
+
+      constraint = message.lifetime_constraint
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__TRANSACTION__EXPECTED_BLOCKHASH_LIFETIME) unless constraint.is_a?(TransactionMessages::BlockhashLifetimeConstraint)
+      blockhash_str = constraint.blockhash
+
+      # ── 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) ─────────────────────────────────────
+      blockhash_bytes = Addresses.decode_address(Addresses::Address.new(blockhash_str))
+
+      # ── 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.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.4'
     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.4
 platform: ruby
 authors:
-- Paul Zupan
+- Paul Zupan, Idhra Inc.
 bindir: bin
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -225,6 +225,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 +287,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