solace 0.1.7 → 0.1.9

data/lib/solace/utils/account_context.rb

@@ -62,6 +62,7 @@ module Solace
       def initialize
         @header             = []
         @accounts           = []
+        @loaded_accounts    = []
         @pubkey_account_map = {}
       end
 
@@ -100,6 +101,27 @@ module Solace
         merge_account(pubkey, signer: false, writable: false)
       end
 
+      # Add or merge an account into the context
+      #
+      # The primitive the +add_*+ methods above name a role for; call it
+      # directly when the flags are data in hand. Permissions only ever widen:
+      # an account added twice keeps the union of what it was given.
+      #
+      # @param pubkey [#to_s, PublicKey] The public key of the account
+      # @param signer [Boolean] Whether the account is a signer
+      # @param writable [Boolean] Whether the account is writable
+      # @param fee_payer [Boolean] Whether the account pays the fee (see {#set_fee_payer})
+      def merge_account(pubkey, signer:, writable:, fee_payer: false)
+        pubkey_str = pubkey.to_s
+
+        @pubkey_account_map[pubkey_str]             ||= DEFAULT_ACCOUNT.dup
+        @pubkey_account_map[pubkey_str][:signer]    ||= signer
+        @pubkey_account_map[pubkey_str][:writable]  ||= writable
+        @pubkey_account_map[pubkey_str][:fee_payer] ||= fee_payer
+
+        self
+      end
+
       # Predicate to check if an account is a fee payer
       #
       # @param pubkey [String] The pubkey of the account
@@ -173,60 +195,69 @@ module Solace
       #   - Then writable accounts
       #   - Then readonly accounts
       #
-      # @return [Hash] The compiled accounts and header
-      def compile
-        self.header   = calculate_header
-        self.accounts = order_accounts
+      # For a v0 (versioned) transaction, accounts resolved through lookup tables
+      # leave the static account list entirely: the message carries only the
+      # static keys, and the runtime rebuilds the combined space
+      # [static..., loaded...] at execution time. Passing them keeps {#index_of}
+      # resolving against that combined space (so instructions index correctly)
+      # while dropping them from the static accounts and the header. They must be
+      # ordered writable-first to match the runtime's combined space. With no
+      # loaded accounts (the default) this is the legacy compilation, unchanged.
+      #
+      # @param loaded_accounts [Array<String>] Pubkeys resolved through lookup tables
+      # @return [AccountContext] Self
+      def compile(loaded_accounts: [])
+        @loaded_accounts = loaded_accounts
+
+        self.header   = calculate_header(loaded_accounts)
+        self.accounts = order_accounts(loaded_accounts)
         self
       end
 
-      # Index of a pubkey in the accounts array
+      # Index of a pubkey in the combined account space
       #
       # @param pubkey_str [String] The public key of the account
-      # @return [Integer] The index of the pubkey in the accounts array or -1 if not found
+      # @return [Integer] The index in the combined space, or -1 if not found
       def index_of(pubkey_str)
         indices[pubkey_str] || -1
       end
 
-      # Get map of indicies for pubkeys in accounts array
+      # Map of pubkey => index across the combined space (static keys followed by
+      # any loaded accounts), so instruction indices resolve the same way the
+      # runtime does once lookup tables are expanded.
       #
-      # @return [Hash{String => Integer}] The indices of the pubkeys in the accounts array
+      # @return [Hash{String => Integer}] The indices of the pubkeys
       def indices
-        accounts.each_with_index.to_h
+        (accounts + @loaded_accounts).each_with_index.to_h
       end
 
       private
 
-      # Add or merge an account into the context
+      # Order the static accounts by signer, writable, readonly signer, readonly
       #
-      # @param pubkey [#to_s, PublicKey] The public key of the account
-      # @param signer [Boolean] Whether the account is a signer
-      # @param writable [Boolean] Whether the account is writable
-      # @param [Boolean] fee_payer
-      def merge_account(pubkey, signer:, writable:, fee_payer: false)
-        pubkey_str = pubkey.is_a?(String) ? pubkey : pubkey.address
-
-        @pubkey_account_map[pubkey_str]             ||= DEFAULT_ACCOUNT.dup
-        @pubkey_account_map[pubkey_str][:signer]    ||= signer
-        @pubkey_account_map[pubkey_str][:writable]  ||= writable
-        @pubkey_account_map[pubkey_str][:fee_payer] ||= fee_payer
-
-        self
+      # Loaded accounts are excluded — they leave the static account list and are
+      # resolved through lookup tables at runtime.
+      #
+      # @param loaded_accounts [Array<String>] Pubkeys resolved through lookup tables
+      # @return [Array<String>] The ordered static accounts
+      def order_accounts(loaded_accounts)
+        # Keyed on the position too: sort_by is not stable, and accounts of the
+        # same rank must keep the order they were added in
+        (@pubkey_account_map.keys - loaded_accounts).sort_by.with_index { |pubkey, index| [rank_of(pubkey), index] }
       end
 
-      # Order accounts by signer, writable, readonly signer, readonly
+      # The position of an account's segment in the static account list
       #
-      # @return [Array<String>] The ordered accounts
-      def order_accounts
-        @pubkey_account_map.keys.sort_by do |pubkey|
-          if fee_payer?(pubkey) then 0
-          elsif writable_signer?(pubkey) then 1
-          elsif readonly_signer?(pubkey) then 2
-          elsif writable_nonsigner?(pubkey) then 3
-          elsif readonly_nonsigner?(pubkey) then 4
-          else
-            raise ArgumentError, "Unknown account type for pubkey: #{pubkey}"
-          end
+      # @param pubkey [String] The pubkey of the account
+      # @return [Integer] The segment rank
+      def rank_of(pubkey)
+        if fee_payer?(pubkey) then 0
+        elsif writable_signer?(pubkey) then 1
+        elsif readonly_signer?(pubkey) then 2
+        elsif writable_nonsigner?(pubkey) then 3
+        elsif readonly_nonsigner?(pubkey) then 4
+        else
+          raise ArgumentError, "Unknown account type for pubkey: #{pubkey}"
         end
       end
 
@@ -237,9 +268,14 @@ module Solace
       #   - The number of readonly signers
       #   - The number of readonly unsigned accounts
       #
+      # Loaded accounts no longer occupy the static account list, so they drop
+      # out of the header. They are never signers, so only the readonly-unsigned
+      # count changes.
+      #
+      # @param loaded_accounts [Array<String>] Pubkeys resolved through lookup tables
       # @return [Array] The header for the transaction
-      def calculate_header
-        @pubkey_account_map.keys.each_with_object([0, 0, 0]) do |pubkey, acc|
+      def calculate_header(loaded_accounts)
+        (@pubkey_account_map.keys - loaded_accounts).each_with_object([0, 0, 0]) do |pubkey, acc|
           acc[0] += 1 if signer?(pubkey)
 
           if readonly_signer?(pubkey) then acc[1]       += 1

data/lib/solace/utils/compute_budget.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative '../composers/base'
+require_relative '../composers/compute_budget_program_set_compute_unit_limit_composer'
+require_relative '../composers/compute_budget_program_set_compute_unit_price_composer'
+
+module Solace
+  module Utils
+    # The compute budget a transaction composer carries as a setting
+    #
+    # Holds the compute unit limit and price, answers the ComputeBudget composers
+    # they translate to (limit then price), and decides which directly added
+    # ComputeBudget composers the setting supersedes so the budget is never
+    # declared twice. Instances are immutable; {#merge} answers a new one.
+    #
+    # @example
+    #   budget = Solace::Utils::ComputeBudget.new(units: 200_000, micro_lamports: 50_000)
+    #   budget.composers # => [SetComputeUnitLimit composer, SetComputeUnitPrice composer]
+    #
+    # @see Solace::TransactionComposer#set_compute_budget
+    # @since 0.1.9
+    class ComputeBudget
+      # The composer a compute unit limit translates to
+      LIMIT_COMPOSER = Composers::ComputeBudgetProgramSetComputeUnitLimitComposer
+      private_constant :LIMIT_COMPOSER
+
+      # The composer a compute unit price translates to
+      PRICE_COMPOSER = Composers::ComputeBudgetProgramSetComputeUnitPriceComposer
+      private_constant :PRICE_COMPOSER
+
+      # @!attribute units
+      #   The compute unit limit, or nil when none is set
+      attr_reader :units
+
+      # @!attribute micro_lamports
+      #   The compute unit price in micro-lamports, or nil when none is set
+      attr_reader :micro_lamports
+
+      # Initialize the compute budget
+      #
+      # @param units [Integer, nil] The compute unit limit
+      # @param micro_lamports [Integer, nil] The compute unit price in micro-lamports
+      def initialize(units: nil, micro_lamports: nil)
+        @units          = units
+        @micro_lamports = micro_lamports
+      end
+
+      # Whether any part of the budget is set
+      #
+      # @return [Boolean]
+      def set?
+        !(units.nil? && micro_lamports.nil?)
+      end
+
+      # The ComputeBudget composers the budget translates to, limit then price
+      #
+      # @return [Array<Composers::Base>] The composers, empty when nothing is set
+      def composers
+        [
+          (LIMIT_COMPOSER.new(units: units) if units),
+          (PRICE_COMPOSER.new(micro_lamports: micro_lamports) if micro_lamports)
+        ].compact
+      end
+
+      # Whether a directly added composer is replaced by a setting of the same kind
+      #
+      # @param composer [Composers::Base] The added composer
+      # @return [Boolean]
+      def supersedes?(composer)
+        (!units.nil? && composer.is_a?(LIMIT_COMPOSER)) || (!micro_lamports.nil? && composer.is_a?(PRICE_COMPOSER))
+      end
+
+      # A budget with the other's settings where it has them, and this one's otherwise
+      #
+      # @param other [ComputeBudget] The budget to fold in
+      # @return [ComputeBudget] The merged budget
+      def merge(other)
+        self.class.new(
+          units:          other.units || units,
+          micro_lamports: other.micro_lamports || micro_lamports
+        )
+      end
+    end
+  end
+end

data/lib/solace/version.rb

@@ -2,5 +2,5 @@
 
 module Solace
   # Latest version of the Solace gem.
-  VERSION = '0.1.7'
+  VERSION = '0.1.9'
 end

data/lib/solace.rb

@@ -35,11 +35,14 @@ require_relative 'solace/version'
 require_relative 'solace/errors'
 require_relative 'solace/constants'
 require_relative 'solace/connection'
+require_relative 'solace/concerns/binary_serializable'
+
+# Utils
 require_relative 'solace/utils/codecs'
 require_relative 'solace/utils/pda'
 require_relative 'solace/utils/account_context'
+require_relative 'solace/utils/compute_budget'
 require_relative 'solace/utils/curve25519_dalek'
-require_relative 'solace/concerns/binary_serializable'
 
 # Tokens
 require_relative 'solace/tokens'
@@ -55,7 +58,12 @@ require_relative 'solace/transaction'
 require_relative 'solace/message'
 require_relative 'solace/instruction'
 require_relative 'solace/address_lookup_table'
+
+# Accounts (on-chain account models)
+require_relative 'solace/accounts/address_lookup_table'
+
 require_relative 'solace/transaction_composer'
+require_relative 'solace/transaction_decomposer'
 
 # Base Classes (Abstract classes)
 require_relative 'solace/programs/base'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base58
@@ -201,13 +201,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/rubocop/cop/solace/exploded_hash.rb
 - lib/solace.rb
+- lib/solace/accounts/address_lookup_table.rb
 - lib/solace/address_lookup_table.rb
+- lib/solace/composers/address_lookup_table_program_create_composer.rb
+- lib/solace/composers/address_lookup_table_program_extend_composer.rb
 - lib/solace/composers/associated_token_account_program_create_account_composer.rb
 - lib/solace/composers/associated_token_account_program_create_idempotent_account_composer.rb
 - lib/solace/composers/base.rb
 - lib/solace/composers/compute_budget_program_set_compute_unit_limit_composer.rb
 - lib/solace/composers/compute_budget_program_set_compute_unit_price_composer.rb
+- lib/solace/composers/opaque_instruction_composer.rb
 - lib/solace/composers/spl_token_program_close_account_composer.rb
 - lib/solace/composers/spl_token_program_initialize_mint_composer.rb
 - lib/solace/composers/spl_token_program_mint_to_composer.rb
@@ -224,6 +229,7 @@ files:
 - lib/solace/connection.rb
 - lib/solace/constants.rb
 - lib/solace/errors.rb
+- lib/solace/errors/address_lookup_table_not_found.rb
 - lib/solace/errors/confirmation_timeout.rb
 - lib/solace/errors/connection_error.rb
 - lib/solace/errors/error.rb
@@ -231,6 +237,8 @@ files:
 - lib/solace/errors/parse_error.rb
 - lib/solace/errors/rpc_error.rb
 - lib/solace/instruction.rb
+- lib/solace/instructions/address_lookup_table_program/create_lookup_table_instruction.rb
+- lib/solace/instructions/address_lookup_table_program/extend_lookup_table_instruction.rb
 - lib/solace/instructions/associated_token_account/create_account_instruction.rb
 - lib/solace/instructions/associated_token_account/create_idempotent_account_instruction.rb
 - lib/solace/instructions/compute_budget/set_compute_unit_limit_instruction.rb
@@ -271,8 +279,10 @@ files:
 - lib/solace/tokens/token.rb
 - lib/solace/transaction.rb
 - lib/solace/transaction_composer.rb
+- lib/solace/transaction_decomposer.rb
 - lib/solace/utils/account_context.rb
 - lib/solace/utils/codecs.rb
+- lib/solace/utils/compute_budget.rb
 - lib/solace/utils/curve25519_dalek.rb
 - lib/solace/utils/libcurve25519_dalek-linux-arm64/libcurve25519_dalek.so
 - lib/solace/utils/libcurve25519_dalek-linux/libcurve25519_dalek.so