solace 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e9ca7ab89db7412f9eea6ba3fc36e7a126fddf403fa639bb1d40fdf5a338a61
-  data.tar.gz: d35705a7acb46f5da7a4d421d32f5be1fb3cfbcdc293623799ba6be8467a3f2d
+  metadata.gz: 2f6a793f450df697c4f216ab4e5a483d7a331f57a3fccb05ecd7c76e788fa4ed
+  data.tar.gz: 479fcb0c38b8e5ea8d82636922ab327ec68ae18455550658c79b06ddd11b2bbd
 SHA512:
-  metadata.gz: a4621dc7f860419c640ad856ad602acb4c15dde56cc89a44130f4b505baf9856ac20e9227ffd88e7797c4df9aa58d3e9f0485e6f4e52acbd40a0de1d73b5feca
-  data.tar.gz: 305310534a9a2373ddb8df5e0208f2ab5723d9ba6b7c4be4d21533cc07f7faf94819f6744be7564ec0f20a82fc255230390b68f2a0b67cf69bc7009a05d5d60a
+  metadata.gz: ec35bdf08bf2ecdd235d25ec67f9c897a7a5c0a167c46d3f2dea8cfb21600b7c3523e236f9db644638fdb2aadd3b219a67296676d580d3ce2ef2ad1a9c8ebe00
+  data.tar.gz: 9647d86486a247042220f53b621591e2de5599868bb154350eb367a4d523301c60ac1735cc664c46ebb18e181f7095c9972748257d25373863d81c520ab7ba3a

data/lib/rubocop/cop/solace/exploded_hash.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Solace
+      # Every pair in a braced hash starts on its own line.
+      #
+      # A hash is read as a table: a reader scanning for one key, or diffing two
+      # of them, works down the left edge. Collapsing pairs onto a shared line
+      # hides a key mid-line and makes a one-key change show up as a rewritten
+      # line. Length is not the test — a short hash collapses just as badly as a
+      # long one, which is why the built-in layout cops are not enough: they only
+      # act once a hash is already multi-line.
+      #
+      # Only a hash written on one line is this cop's business. Once a hash spans
+      # lines, Layout/FirstHashElementLineBreak and Layout/MultilineHashKeyLineBreaks
+      # already break every pair onto its own line, and a second cop inserting the
+      # same break in the same correction loop leaves a blank line behind.
+      #
+      # Two more restrictions keep it from reaching where it does not belong. A
+      # hash of one pair is left inline, since it is already the only thing on
+      # its line. And only BRACED hashes are checked: a keyword argument list is
+      # a hash node too, and exploding it would break up every multi-argument
+      # call in the codebase.
+      #
+      # @example
+      #   # bad
+      #   page_id: { type: 'string', format: 'uuid' }
+      #
+      #   # good
+      #   page_id: {
+      #     type: 'string',
+      #     format: 'uuid'
+      #   }
+      #
+      #   # good — one pair, and a keyword argument list
+      #   { user: payload[:user_id] }
+      #   create(:user, name: 'Ada', email: 'ada@example.com')
+      class ExplodedHash < Base
+        extend AutoCorrector
+
+        MSG = 'Each pair in a hash starts on its own line.'
+
+        def on_hash(node)
+          pairs = braced_pairs(node)
+          return unless pairs
+
+          pairs.each { |pair| flag(pair) }
+        end
+
+        private
+
+        # Nil for anything this cop leaves alone: a hash already spanning lines,
+        # a keyword argument list, which carries no braces, and a hash of a
+        # single pair.
+        def braced_pairs(node)
+          return unless node.loc.begin
+          return if node.multiline?
+
+          pairs = node.pairs
+          pairs if pairs.size >= 2
+        end
+
+        # The break replaces the space in front of the pair rather than being
+        # inserted before it, or the old separator is left behind as trailing
+        # whitespace. Indentation is left to Layout/FirstHashElementIndentation
+        # and Layout/HashAlignment, which run in the same correction loop.
+        def flag(pair)
+          add_offense(pair) { |corrector| corrector.replace(leading_space(pair), "\n") }
+        end
+
+        def leading_space(pair)
+          range  = pair.source_range
+          source = range.source_buffer.source
+          start  = range.begin_pos
+          start -= 1 while start.positive? && [' ', "\t"].include?(source[start - 1])
+          Parser::Source::Range.new(range.source_buffer, start, range.begin_pos)
+        end
+      end
+    end
+  end
+end

data/lib/solace/accounts/address_lookup_table.rb

@@ -21,9 +21,8 @@ module Solace
     #   table.reference(loaded_writable, loaded_readonly) # => Solace::AddressLookupTable or nil
     #
     # @example Read a table's on-chain state
-    #   data  = Base64.decode64(connection.get_account_info(address)['data'][0])
-    #   table = Solace::Accounts::AddressLookupTable.deserialize(StringIO.new(data))
-    #   table.addresses # => the stored addresses
+    #   table = Solace::Accounts::AddressLookupTable.fetch(address, connection: connection)
+    #   table&.addresses # => the stored addresses, or nil if the chain holds no such account
     #
     # @see Solace::AddressLookupTable
     # @see Solace::TransactionComposer
@@ -53,38 +52,61 @@ module Solace
       #   @return [Integer, nil] The slot the table was last extended in
       attr_reader :last_extended_slot
 
-      # Deserialize an on-chain lookup table account
-      #
-      # The BufferLayout is:
-      #   - [State type (4 bytes, u32 LE)]
-      #   - [Deactivation slot (8 bytes, u64 LE)]
-      #   - [Last extended slot (8 bytes, u64 LE)]
-      #   - [Last extended start index (1 byte)]
-      #   - [Authority (Borsh Option<Pubkey>)]
-      #   - [Padding, up to {META_SIZE}]
-      #   - [Addresses (32 bytes each, to end of data)]
-      #
-      # @param io [IO, StringIO] The account data to read from
-      # @return [AddressLookupTable] The parsed table
-      def self.deserialize(io)
-        Utils::Codecs.decode_le_u32(io) # state type (1 = lookup table); positional
-        deactivation_slot  = Utils::Codecs.decode_le_u64(io)
-        last_extended_slot = Utils::Codecs.decode_le_u64(io)
-
-        Utils::Codecs.decode_u8(io) # last extended start index; positional
-        authority = Utils::Codecs.decode_option_pubkey(io)
-
-        io.seek(META_SIZE) # addresses begin after the fixed-size metadata region
-
-        addresses = []
-        addresses << Utils::Codecs.decode_pubkey(io) until io.eof?
-
-        new(
-          deactivation_slot:  deactivation_slot,
-          last_extended_slot: last_extended_slot,
-          authority:          authority,
-          addresses:          addresses
-        )
+      class << self
+        # Fetch a lookup table account from chain
+        #
+        # Like {Solace::Connection#get_account_info}, answers nil when the chain
+        # holds no account at the address; the caller decides whether that is an error.
+        #
+        # @param account [#to_s, PublicKey] The lookup table's on-chain address
+        # @param connection [Solace::Connection] The connection to read it through
+        # @return [AddressLookupTable, nil] The table with its address set, or nil
+        def fetch(account, connection:)
+          info = connection.get_account_info(account.to_s)
+          return unless info
+
+          base64, = info['data'] # the RPC answers [data, encoding]
+          deserialize(Utils::Codecs.base64_to_bytestream(base64), account: account)
+        end
+
+        # Deserialize an on-chain lookup table account
+        #
+        # The BufferLayout is:
+        #   - [State type (4 bytes, u32 LE)]
+        #   - [Deactivation slot (8 bytes, u64 LE)]
+        #   - [Last extended slot (8 bytes, u64 LE)]
+        #   - [Last extended start index (1 byte)]
+        #   - [Authority (Borsh Option<Pubkey>)]
+        #   - [Padding, up to {META_SIZE}]
+        #   - [Addresses (32 bytes each, to end of data)]
+        #
+        # The account data does not carry its own address, so pass it to have
+        # the table know where it lives.
+        #
+        # @param io [IO, StringIO] The account data to read from
+        # @param account [#to_s, PublicKey, nil] The lookup table's on-chain address
+        # @return [AddressLookupTable] The parsed table
+        def deserialize(io, account: nil)
+          Utils::Codecs.decode_le_u32(io) # state type (1 = lookup table); positional
+          deactivation_slot  = Utils::Codecs.decode_le_u64(io)
+          last_extended_slot = Utils::Codecs.decode_le_u64(io)
+
+          Utils::Codecs.decode_u8(io) # last extended start index; positional
+          authority = Utils::Codecs.decode_option_pubkey(io)
+
+          io.seek(META_SIZE) # addresses begin after the fixed-size metadata region
+
+          addresses = []
+          addresses << Utils::Codecs.decode_pubkey(io) until io.eof?
+
+          new(
+            account:            account,
+            deactivation_slot:  deactivation_slot,
+            last_extended_slot: last_extended_slot,
+            authority:          authority,
+            addresses:          addresses
+          )
+        end
       end
 
       # Initialize a lookup table account

data/lib/solace/composers/opaque_instruction_composer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for an instruction it does not interpret.
+    #
+    # Where every other composer derives its accounts' roles from domain
+    # arguments, this one is handed the program id, the accounts in order, the
+    # data, and an {Utils::AccountContext} declaring each account's role, and
+    # rebuilds the instruction by index against whatever context it is
+    # composed into. It is what {Solace::TransactionDecomposer} answers for
+    # each instruction of a transaction taken apart, and what a caller reaches
+    # for to rebuild one of those with an account swapped out.
+    #
+    # @example Rebuild a recovered instruction with a different rent payer
+    #   roles = Solace::Utils::AccountContext.new
+    #   roles.merge_from(recovered.account_context)
+    #   roles.add_writable_signer(sponsor)
+    #
+    #   composer = Solace::Composers::OpaqueInstructionComposer.new(
+    #     program_id: recovered.program_id,
+    #     accounts:   [sponsor, *recovered.accounts.drop(1)],
+    #     data:       recovered.data,
+    #     roles:      roles
+    #   )
+    #
+    # @since 0.1.9
+    class OpaqueInstructionComposer < Base
+      # The program the instruction invokes
+      #
+      # @return [String] The program id
+      def program_id
+        params[:program_id].to_s
+      end
+
+      # The accounts the instruction touches, in order
+      #
+      # @return [Array<String>] The pubkeys
+      def accounts
+        @accounts ||= params[:accounts].map(&:to_s)
+      end
+
+      # The instruction data, untouched
+      #
+      # @return [Array<Integer>] The data bytes
+      def data
+        params[:data]
+      end
+
+      # The context declaring each account's role
+      #
+      # @return [Utils::AccountContext]
+      def roles
+        params[:roles]
+      end
+
+      # Declare every account with the role given for it, plus the program
+      #
+      # @return [void]
+      # @raise [ArgumentError] When an account has no role declared
+      def setup_accounts
+        accounts.each do |pubkey|
+          raise ArgumentError, "No role declared for account #{pubkey}" unless roles.pubkey_account_map.key?(pubkey)
+
+          account_context.merge_account(pubkey, signer: roles.signer?(pubkey), writable: roles.writable?(pubkey))
+        end
+
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Build the instruction with indices resolved against the given context
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Solace::Instruction.new.tap do |instruction|
+          instruction.program_index = account_context.index_of(program_id)
+          instruction.accounts      = accounts.map { |pubkey| account_context.index_of(pubkey) }
+          instruction.data          = data
+        end
+      end
+    end
+  end
+end

data/lib/solace/errors/address_lookup_table_not_found.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Solace
+  module Errors
+    # Raised when an address lookup table a transaction references does not
+    # exist on chain. A message that loads addresses through a table cannot be
+    # taken apart without the table's address list, so a missing table is an
+    # error rather than an empty list.
+    #
+    # @example
+    #   begin
+    #     Solace::TransactionDecomposer.new(connection: connection).decompose_transaction(transaction)
+    #   rescue Solace::Errors::AddressLookupTableNotFound => e
+    #     puts "missing table: #{e.account}"
+    #   end
+    #
+    # @since 0.1.9
+    class AddressLookupTableNotFound < Error
+      # @return [String] The lookup table's on-chain address
+      attr_reader :account
+
+      # @param account [String] The lookup table's on-chain address
+      def initialize(account)
+        super("address lookup table #{account} not found on chain")
+        @account = account
+      end
+    end
+  end
+end

data/lib/solace/errors/rpc_error.rb

@@ -47,7 +47,13 @@ module Solace
       end
 
       # @return [Hash] The error as a hash
-      def to_h = { code: rpc_code, message: rpc_message, data: rpc_data }
+      def to_h
+        {
+          code:    rpc_code,
+          message: rpc_message,
+          data:    rpc_data
+        }
+      end
     end
   end
 end

data/lib/solace/errors.rb

@@ -21,5 +21,6 @@ module Solace
     require 'solace/errors/http_error'
     require 'solace/errors/parse_error'
     require 'solace/errors/confirmation_timeout'
+    require 'solace/errors/address_lookup_table_not_found'
   end
 end

data/lib/solace/transaction_composer.rb

@@ -78,18 +78,28 @@ module Solace
     attr_reader :address_lookup_tables
 
     # @!attribute version
-    #   The transaction version (nil for legacy, 0 for v0)
+    #   The transaction version (nil for legacy, 0 for v0); see {#set_version}
     attr_reader :version
 
+    # @!attribute compute_budget
+    #   The compute budget set on the composer (see {Utils::ComputeBudget})
+    attr_reader :compute_budget
+
+    # @!attribute blockhash
+    #   The blockhash set on the composer, or nil when the latest is fetched at compose time
+    attr_reader :blockhash
+
     # Initialize the composer
     #
     # @param connection [Solace::Connection] The connection to the Solana cluster
     def initialize(connection:)
       @connection            = connection
+      @blockhash             = nil
       @instruction_composers = []
       @context               = Utils::AccountContext.new
       @address_lookup_tables = []
       @version               = nil
+      @compute_budget        = Utils::ComputeBudget.new
     end
 
     # Add an instruction composer to the transaction
@@ -97,7 +107,7 @@ module Solace
     # @param composer [Composers::Base] The instruction composer
     # @return [TransactionComposer] Self for chaining
     def add_instruction(composer)
-      merge_accounts(composer.account_context)
+      context.merge_from(composer.account_context)
       instruction_composers << composer
       self
     end
@@ -109,7 +119,7 @@ module Solace
     #
     # @since 0.1.0
     def prepend_instruction(composer)
-      merge_accounts(composer.account_context)
+      context.merge_from(composer.account_context)
       instruction_composers.unshift(composer)
       self
     end
@@ -122,7 +132,7 @@ module Solace
     #
     # @since 0.1.0
     def insert_instruction(index, composer)
-      merge_accounts(composer.account_context)
+      context.merge_from(composer.account_context)
       instruction_composers.insert(index, composer)
       self
     end
@@ -136,8 +146,7 @@ module Solace
     #
     # @since 0.1.0
     def merge(other, placement: :add, index: nil)
-      merge_accounts(other.context)
-      merge_address_lookup_tables(other.address_lookup_tables)
+      absorb(other)
 
       case placement
       when :add
@@ -165,6 +174,58 @@ module Solace
       self
     end
 
+    # Set the transaction version
+    #
+    # Registering a lookup table opts into v0 on its own; this is for a v0
+    # transaction that loads nothing through a table, which is still v0 on the
+    # wire. nil composes a legacy message.
+    #
+    # @param version [Integer, nil] 0 for v0, nil for legacy
+    # @return [TransactionComposer] Self for chaining
+    # @raise [ArgumentError] For a version other than 0 or nil
+    def set_version(version)
+      raise ArgumentError, "Unsupported transaction version: #{version.inspect}" unless [nil, 0].include?(version)
+
+      @version = version
+      self
+    end
+
+    # Set the blockhash to compose against
+    #
+    # Beside {#set_fee_payer}: a caller re-composing a transaction it was handed
+    # wants the blockhash that transaction carried, so the expiry its origin
+    # reports stays true. With none set, {#compose_transaction} fetches the
+    # latest from the connection. nil clears it.
+    #
+    # @example
+    #   composer.set_blockhash(original.message.recent_blockhash)
+    #
+    # @param blockhash [#to_s, nil] The blockhash (base58)
+    # @return [TransactionComposer] Self for chaining
+    def set_blockhash(blockhash)
+      @blockhash = blockhash&.to_s
+      self
+    end
+
+    # Set the compute budget for the transaction
+    #
+    # The composer owns the budget as a setting: when it composes, the
+    # ComputeBudget instructions are written first, and any
+    # ComputeBudget composer of the same kind that was added as a plain
+    # instruction is left out, so the budget can never be declared twice
+    # (a duplicate `SetComputeUnitLimit` fails on chain). Each keyword
+    # replaces that setting; nil clears it. Read it back through {#compute_budget}.
+    #
+    # @example
+    #   composer.set_compute_budget(units: 200_000, micro_lamports: 50_000)
+    #
+    # @param units [Integer, nil] The compute unit limit
+    # @param micro_lamports [Integer, nil] The compute unit price in micro-lamports
+    # @return [TransactionComposer] Self for chaining
+    def set_compute_budget(units: nil, micro_lamports: nil)
+      apply_compute_budget(Utils::ComputeBudget.new(units: units, micro_lamports: micro_lamports))
+    end
+
     # Make an address lookup table available to the transaction
     #
     # Registering a table opts the transaction into the v0 format: every
@@ -182,8 +243,8 @@ module Solace
     #
     # @since 0.1.8
     def add_address_lookup_table(account:, addresses: nil)
-      account   = account.to_s
-      @version  = 0 # Lookup tables require a v0 transaction
+      account = account.to_s
+      set_version(0) # Lookup tables require a v0 transaction
 
       unless address_lookup_tables.any? { |table| table.account == account }
         address_lookup_tables << Solace::Accounts::AddressLookupTable.new(account: account, addresses: addresses)
@@ -198,6 +259,9 @@ module Solace
     # once a lookup table has been added — loading eligible accounts through any
     # registered tables.
     #
+    # Composes against the {#blockhash} set with {#set_blockhash}, or the latest
+    # fetched from the connection when none is set.
+    #
     # @return [Transaction] The composed transaction (unsigned)
     def compose_transaction
       context.compile
@@ -263,30 +327,41 @@ module Solace
         header:                context.header,
         accounts:              context.accounts,
         instructions:          build_instructions,
-        recent_blockhash:      connection.get_latest_blockhash[0],
+        recent_blockhash:      blockhash || connection.get_latest_blockhash[0],
         address_lookup_tables: references
       )
     end
 
-    # Build all instructions with resolved indices
+    # Build all instructions with resolved indices: the budget first, then the
+    # added composers minus any ComputeBudget composer the budget supersedes
     #
     # @return [Array<Solace::Instruction>] The built instructions
     def build_instructions
-      instruction_composers.map { _1.build_instruction(context) }.flatten
+      kept = instruction_composers.reject { |composer| compute_budget.supersedes?(composer) }
+
+      (compute_budget.composers + kept).map { _1.build_instruction(context) }.flatten
     end
 
-    # Merge all accounts from another AccountContext into this one
+    # Replace the compute budget, bringing its program into the account context
     #
-    # @param account_context [AccountContext] The other context to merge from
-    def merge_accounts(account_context)
-      context.merge_from(account_context)
+    # @param budget [Utils::ComputeBudget] The budget to hold
+    # @return [TransactionComposer] Self for chaining
+    def apply_compute_budget(budget)
+      @compute_budget = budget
+      budget.composers.each { |composer| context.merge_from(composer.account_context) }
+      self
     end
 
-    # Merge registered tables from another composer, deduped by account
+    # Take on another composer's accounts, tables (deduped by account) and
+    # budget (where it has one set)
     #
-    # @param tables [Array<Solace::Accounts::AddressLookupTable>] The other composer's tables
-    def merge_address_lookup_tables(tables)
-      tables.each { |table| add_address_lookup_table(account: table.account, addresses: table.addresses) }
+    # @param other [TransactionComposer] The other composer
+    def absorb(other)
+      context.merge_from(other.context)
+      other.address_lookup_tables.each do |table|
+        add_address_lookup_table(account: table.account, addresses: table.addresses)
+      end
+      apply_compute_budget(compute_budget.merge(other.compute_budget))
     end
   end
 end

data/lib/solace/transaction_decomposer.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative 'composers/base'
+require_relative 'composers/opaque_instruction_composer'
+require_relative 'instructions/compute_budget/set_compute_unit_limit_instruction'
+require_relative 'instructions/compute_budget/set_compute_unit_price_instruction'
+
+module Solace
+  # Takes a transaction apart into the composer that composes it again
+  #
+  # The reverse of {TransactionComposer}: given a transaction (or its base64),
+  # answers a {TransactionComposer} holding one
+  # {Composers::OpaqueInstructionComposer} per instruction, in order, each
+  # carrying the program it invokes, its accounts with the signer and writable
+  # flags the message header gave them, and its data untouched. The lookup
+  # tables a v0 message references are read from chain once and registered, and
+  # the version is kept, so the composer composes as v0 again (with or without
+  # tables); a `SetComputeUnitLimit` or
+  # `SetComputeUnitPrice` the transaction carried becomes the composer's
+  # {TransactionComposer#compute_budget}; and the blockhash it was composed
+  # against is set as the composer's {TransactionComposer#blockhash}.
+  #
+  # The Solana facts applied:
+  #
+  # - Static keys take their flags from the header ordering: signers first,
+  #   writable before read-only, then non-signers the same way.
+  # - A v0 message's instruction indexes address the combined space: the
+  #   static keys, then every table's writable entries in table order, then
+  #   every table's read-only entries. A loaded address never signs and is
+  #   writable by the segment it sits in.
+  # - A table that does not exist on chain is an error, not an empty list.
+  #
+  # For a transaction a {TransactionComposer} built, the composer answered here
+  # composes the same bytes again.
+  #
+  # @example
+  #   composer = Solace::TransactionDecomposer.new(connection: connection).decompose_transaction(transaction)
+  #   composer.instruction_composers # => the recovered instructions
+  #   composer.compose_transaction   # => the transaction again
+  #
+  # @see Solace::TransactionComposer
+  # @since 0.1.9
+  class TransactionDecomposer
+    # The discriminators of the two directives the budget setting holds
+    LIMIT_INDEX = Instructions::ComputeBudget::SetComputeUnitLimitInstruction::INSTRUCTION_INDEX.first
+    PRICE_INDEX = Instructions::ComputeBudget::SetComputeUnitPriceInstruction::INSTRUCTION_INDEX.first
+    private_constant :LIMIT_INDEX, :PRICE_INDEX
+
+    # What one call reads off a message: the message, the tables it references
+    # (by account, read from chain), the combined account space in index
+    # order, and a context declaring every account's role
+    Reading = Struct.new(:message, :tables, :accounts, :roles, keyword_init: true)
+    private_constant :Reading
+
+    # @!attribute connection
+    #   The connection lookup tables are read through
+    attr_reader :connection
+
+    # @param connection [Solace::Connection] The connection to read lookup tables through
+    def initialize(connection:)
+      @connection = connection
+    end
+
+    # Take a transaction apart
+    #
+    # @param transaction [Solace::Transaction, String] The transaction, or its base64
+    # @return [Solace::TransactionComposer] A composer that composes it again
+    # @raise [Solace::Errors::AddressLookupTableNotFound] When a referenced table is not on chain
+    def decompose_transaction(transaction)
+      message  = message_of(transaction)
+      reading  = read(message)
+      composer = TransactionComposer.new(connection: connection)
+                                    .set_version(message.version)
+                                    .set_blockhash(message.recent_blockhash)
+
+      seed(composer, reading)
+      fill(composer, reading)
+    end
+
+    private
+
+    # Read a message: its tables from chain, its combined account space, and
+    # the role of every account in it
+    #
+    # @param message [Solace::Message]
+    # @return [Reading]
+    def read(message)
+      tables   = fetch_tables(message)
+      writable = loaded(message, tables, :writable_indexes)
+      readonly = loaded(message, tables, :readonly_indexes)
+      roles    = Utils::AccountContext.new
+
+      declare_static(roles, message)
+      writable.each { |pubkey| roles.merge_account(pubkey, signer: false, writable: true) }
+      readonly.each { |pubkey| roles.merge_account(pubkey, signer: false, writable: false) }
+
+      accounts = message.accounts + writable + readonly
+
+      Reading.new(message: message, tables: tables, accounts: accounts, roles: roles)
+    end
+
+    # Declare the static keys with the roles their header positions give them:
+    # signers first, writable before read-only, then non-signers the same way
+    #
+    # @param roles [Utils::AccountContext]
+    # @param message [Solace::Message]
+    # @return [void]
+    def declare_static(roles, message)
+      signers, readonly_signed, readonly_unsigned = message.header
+
+      message.accounts.each_with_index do |pubkey, index|
+        is_signer     = index < signers
+        readonly_from = is_signer ? signers - readonly_signed : message.accounts.size - readonly_unsigned
+        is_writable   = index < readonly_from
+
+        roles.merge_account(pubkey, signer: is_signer, writable: is_writable)
+      end
+    end
+
+    # Seed the composer's accounts in message order and set the fee payer, so
+    # it composes the same account order again
+    #
+    # @param composer [Solace::TransactionComposer]
+    # @param reading [Reading]
+    # @return [void]
+    def seed(composer, reading)
+      composer.context.merge_from(reading.roles)
+      composer.set_fee_payer(reading.message.accounts.first)
+    end
+
+    # Add the instructions, register the tables, and set the budget
+    #
+    # @param composer [Solace::TransactionComposer]
+    # @param reading [Reading]
+    # @return [Solace::TransactionComposer] The composer
+    def fill(composer, reading)
+      instruction_composers(reading).each { |instruction| composer.add_instruction(instruction) }
+
+      reading.tables.each_value do |table|
+        composer.add_address_lookup_table(account: table.account, addresses: table.addresses)
+      end
+
+      budget = compute_budget(reading)
+      composer.set_compute_budget(units: budget.units, micro_lamports: budget.micro_lamports) if budget.set?
+
+      composer
+    end
+
+    # The message of a transaction given as the object or its base64
+    #
+    # @param transaction [Solace::Transaction, String]
+    # @return [Solace::Message]
+    def message_of(transaction)
+      transaction = Solace::Transaction.from(transaction) if transaction.is_a?(String)
+      transaction.message
+    end
+
+    # The tables the message references, read from chain once each, in message order
+    #
+    # @param message [Solace::Message]
+    # @return [Hash{String => Accounts::AddressLookupTable}] Keyed by table account
+    def fetch_tables(message)
+      references = Array(message.address_lookup_tables)
+      accounts   = references.map(&:account).uniq
+
+      accounts.to_h do |account|
+        table = Accounts::AddressLookupTable.fetch(account, connection: connection)
+        raise Errors::AddressLookupTableNotFound, account unless table
+
+        [account, table]
+      end
+    end
+
+    # The pubkeys one segment loads, across every table in table order
+    #
+    # @param message [Solace::Message]
+    # @param tables [Hash{String => Accounts::AddressLookupTable}]
+    # @param kind [Symbol] :writable_indexes or :readonly_indexes
+    # @return [Array<String>]
+    def loaded(message, tables, kind)
+      references = Array(message.address_lookup_tables)
+
+      references.flat_map do |reference|
+        addresses = tables.fetch(reference.account).addresses
+        indexes   = kind == :writable_indexes ? reference.writable_indexes : reference.readonly_indexes
+
+        indexes.map { |index| addresses.fetch(index) }
+      end
+    end
+
+    # The message's instructions as composers, the budget directives left out
+    #
+    # @param reading [Reading]
+    # @return [Array<Composers::OpaqueInstructionComposer>]
+    def instruction_composers(reading)
+      lifted = reading.message.instructions.reject { |instruction| budget?(instruction, reading) }
+
+      lifted.map do |instruction|
+        program_id = reading.accounts.fetch(instruction.program_index)
+        accounts   = instruction.accounts.map { |index| reading.accounts.fetch(index) }
+
+        Composers::OpaqueInstructionComposer.new(
+          program_id: program_id,
+          accounts:   accounts,
+          data:       instruction.data,
+          roles:      reading.roles
+        )
+      end
+    end
+
+    # Whether an instruction is a limit or price directive the budget setting holds
+    #
+    # @param instruction [Solace::Instruction]
+    # @param reading [Reading]
+    # @return [Boolean]
+    def budget?(instruction, reading)
+      program_id    = reading.accounts.fetch(instruction.program_index)
+      discriminator = instruction.data.first
+
+      program_id == Constants::COMPUTE_BUDGET_PROGRAM_ID && [LIMIT_INDEX, PRICE_INDEX].include?(discriminator)
+    end
+
+    # The budget the message carried, decoded from its limit and price directives
+    #
+    # @param reading [Reading]
+    # @return [Utils::ComputeBudget] Unset when the message carried neither
+    def compute_budget(reading)
+      directives = reading.message.instructions.select { |instruction| budget?(instruction, reading) }
+
+      Utils::ComputeBudget.new(
+        units:          decode(directives, LIMIT_INDEX, 'L<'),
+        micro_lamports: decode(directives, PRICE_INDEX, 'Q<')
+      )
+    end
+
+    # The value of the first directive with the given discriminator, or nil
+    #
+    # @param directives [Array<Solace::Instruction>] The budget directives
+    # @param discriminator [Integer] The directive's first data byte
+    # @param format [String] The pack format of the value that follows it
+    # @return [Integer, nil]
+    def decode(directives, discriminator, format)
+      directive = directives.find { |instruction| instruction.data.first == discriminator }
+      return unless directive
+
+      value_bytes = directive.data.drop(1)
+      value_bytes.pack('C*').unpack1(format)
+    end
+  end
+end

data/lib/solace/utils/account_context.rb

@@ -101,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
@@ -212,23 +233,6 @@ module Solace
 
       private
 
-      # Add or merge an account into the context
-      #
-      # @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
-      end
-
       # Order the static accounts by signer, writable, readonly signer, readonly
       #
       # Loaded accounts are excluded — they leave the static account list and are
@@ -237,15 +241,23 @@ module Solace
       # @param loaded_accounts [Array<String>] Pubkeys resolved through lookup tables
       # @return [Array<String>] The ordered static accounts
       def order_accounts(loaded_accounts)
-        (@pubkey_account_map.keys - loaded_accounts).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
+        # 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
+
+      # The position of an account's segment in the static account list
+      #
+      # @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
 

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.8'
+  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'
@@ -60,6 +63,7 @@ require_relative 'solace/address_lookup_table'
 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.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base58
@@ -201,6 +201,7 @@ 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
@@ -211,6 +212,7 @@ files:
 - 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
@@ -227,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
@@ -276,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