solace 0.1.7 → 0.1.9

data/lib/solace/instructions/address_lookup_table_program/extend_lookup_table_instruction.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module AddressLookupTableProgram
+      # Instruction for appending addresses to an existing address lookup table.
+      #
+      # Newly added addresses become usable one slot after the extend lands.
+      #
+      # @example Build an ExtendLookupTable instruction
+      #   instruction = Solace::Instructions::AddressLookupTableProgram::ExtendLookupTableInstruction.build(
+      #     addresses:            [recipient1, recipient2],
+      #     program_index:        4,
+      #     table_index:          1,
+      #     authority_index:      0,
+      #     payer_index:          0,
+      #     system_program_index: 3
+      #   )
+      #
+      # @since 0.1.8
+      class ExtendLookupTableInstruction
+        # Instruction discriminator for ExtendLookupTable (u32 LE)
+        INSTRUCTION_ID = [2, 0, 0, 0].freeze
+
+        # Builds a Solace::Instruction for extending a lookup table
+        #
+        # @param addresses [Array<#to_s>] The addresses to append to the table
+        # @param program_index [Integer] Index of the lookup table program
+        # @param table_index [Integer] Index of the table account (writable)
+        # @param authority_index [Integer] Index of the table authority (signer)
+        # @param payer_index [Integer] Index of the rent payer (writable signer)
+        # @param system_program_index [Integer] Index of the system program
+        # @return [Solace::Instruction]
+        def self.build(
+          addresses:,
+          program_index:,
+          table_index:,
+          authority_index:,
+          payer_index:,
+          system_program_index:
+        )
+          Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [table_index, authority_index, payer_index, system_program_index]
+            ix.data          = data(addresses)
+          end
+        end
+
+        # Instruction data for an extend lookup table instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction discriminator (4 bytes, u32 LE)]
+        #   - [Number of addresses (8 bytes, u64 LE)]
+        #   - [Addresses (32 bytes each)]
+        #
+        # The address vector uses a u64 length prefix (bincode), not the u32
+        # Borsh prefix of {Utils::Codecs.encode_vec_pubkeys}.
+        #
+        # @param addresses [Array<#to_s>] The addresses to append
+        # @return [Array<Integer>]
+        def self.data(addresses)
+          INSTRUCTION_ID +
+            Utils::Codecs.encode_le_u64(addresses.length).bytes +
+            addresses.flat_map { |address| Utils::Codecs.encode_pubkey(address) }
+        end
+      end
+    end
+  end
+end

data/lib/solace/transaction_composer.rb

@@ -73,13 +73,33 @@ module Solace
     #   The instruction composers
     attr_reader :instruction_composers
 
+    # @!attribute address_lookup_tables
+    #   The registered address lookup tables
+    attr_reader :address_lookup_tables
+
+    # @!attribute version
+    #   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
@@ -87,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
@@ -99,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
@@ -112,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
@@ -126,7 +146,7 @@ module Solace
     #
     # @since 0.1.0
     def merge(other, placement: :add, index: nil)
-      merge_accounts(other.context)
+      absorb(other)
 
       case placement
       when :add
@@ -154,36 +174,194 @@ 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
+    # compiled account found in a table that is allowed to load (a non-signer
+    # that is not the fee payer and not an invoked program id) is referenced by
+    # table index instead of occupying a static account slot. Adding the same
+    # table (by account) twice is a no-op.
+    #
+    # @example
+    #   composer.add_address_lookup_table(account: table_address, addresses: on_chain_addresses)
+    #
+    # @param account [#to_s, PublicKey] The lookup table's on-chain address
+    # @param addresses [Array<#to_s>, nil] The full, ordered list of addresses stored in the table
+    # @return [TransactionComposer] Self for chaining
+    #
+    # @since 0.1.8
+    def add_address_lookup_table(account:, addresses: nil)
+      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)
+      end
+
+      self
+    end
+
     # Compose the final transaction
     #
+    # Emits a message at the composer's {#version} — legacy by default, or v0
+    # 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
 
-      message = Solace::Message.new(
-        header:           context.header,
-        accounts:         context.accounts,
-        instructions:     build_instructions,
-        recent_blockhash: connection.get_latest_blockhash[0]
-      )
+      writable, readonly, references = resolve_address_lookup_tables
+      context.compile(loaded_accounts: writable + readonly)
 
-      Solace::Transaction.new(message: message)
+      Solace::Transaction.new(message: build_message(references))
     end
 
     private
 
-    # Build all instructions with resolved indices
+    # Fold the registered tables into the accounts they load and the references
+    # the message carries — a single pass over the tables (the order that
+    # defines the v0 combined account space).
+    #
+    # First table wins when tables share an address; within a table the on-chain
+    # address order is preserved, so the accumulated writable/readonly segments
+    # match the runtime's loaded-address order once concatenated.
+    #
+    # @return [Array(Array<String>, Array<String>, Array<Solace::AddressLookupTable>)]
+    #   The loaded writable pubkeys, loaded readonly pubkeys, and table references
+    def resolve_address_lookup_tables
+      loadable = loadable_accounts
+      writable = []
+      readonly = []
+
+      references = address_lookup_tables.filter_map do |table|
+        loaded    = table.addresses & loadable
+        loadable -= loaded
+        on, off   = loaded.partition { |pubkey| context.writable?(pubkey) }
+        writable.concat(on)
+        readonly.concat(off)
+        table.reference(on, off)
+      end
+
+      [writable, readonly, references]
+    end
+
+    # Accounts eligible to load through a table: referenced by the transaction,
+    # not a signer (which covers the fee payer), and not an invoked program id.
+    #
+    # @return [Array<String>] The loadable account pubkeys
+    def loadable_accounts
+      programs = program_ids
+      context.accounts.reject { |pubkey| context.signer?(pubkey) || programs.include?(pubkey) }
+    end
+
+    # Program ids invoked by the built instructions — these must stay static
+    #
+    # @return [Array<String>] The invoked program id pubkeys
+    def program_ids
+      build_instructions.map { context.accounts[_1.program_index] }.uniq
+    end
+
+    # Build the composed message at the composer's version (legacy or v0)
+    #
+    # @param references [Array<Solace::AddressLookupTable>] The table references
+    # @return [Solace::Message] The composed message
+    def build_message(references)
+      Solace::Message.new(
+        version:               version,
+        header:                context.header,
+        accounts:              context.accounts,
+        instructions:          build_instructions,
+        recent_blockhash:      blockhash || connection.get_latest_blockhash[0],
+        address_lookup_tables: references
+      )
+    end
+
+    # 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
+
+    # Take on another composer's accounts, tables (deduped by account) and
+    # budget (where it has one set)
+    #
+    # @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