solace 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab3415933c7875971ad410ecc1d8d7487233a7eb58e9c3701f23babdaae9fbd5
-  data.tar.gz: a9ef2bbb03d7988487ae48bff51122dc45670e5ad6ef8c8d6154fa386d0a1281
+  metadata.gz: 4e9ca7ab89db7412f9eea6ba3fc36e7a126fddf403fa639bb1d40fdf5a338a61
+  data.tar.gz: d35705a7acb46f5da7a4d421d32f5be1fb3cfbcdc293623799ba6be8467a3f2d
 SHA512:
-  metadata.gz: 869108bf70f8a9143e28dae425a5e843135aedfd78642c39683fd214ab4a3d1c847125e0e2f0fc60b1766ac45970dc8f14bfc512861db95b89cdaaedc593226d
-  data.tar.gz: 8ff9bcac1403007eb3dcc340587c76f4acb5dff266390621f16708589153644db16a16cdb0f08936f3d3a690c2943d78edd570735e9f0692eac6ffb62ee3c969
+  metadata.gz: a4621dc7f860419c640ad856ad602acb4c15dde56cc89a44130f4b505baf9856ac20e9227ffd88e7797c4df9aa58d3e9f0485e6f4e52acbd40a0de1d73b5feca
+  data.tar.gz: 305310534a9a2373ddb8df5e0208f2ab5723d9ba6b7c4be4d21533cc07f7faf94819f6744be7564ec0f20a82fc255230390b68f2a0b67cf69bc7009a05d5d60a

data/lib/solace/accounts/address_lookup_table.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Solace
+  # On-chain account models — the account state living at an address, as opposed
+  # to the wire-level structures that reference it. Conventions for these types
+  # (fetching, deserializing, deriving) are expected to grow here.
+  module Accounts
+    # Models an on-chain Address Lookup Table account: its address, the metadata
+    # the program stores (authority, activation slots), and the full, ordered
+    # list of addresses it holds.
+    #
+    # This is distinct from {Solace::AddressLookupTable}, which is the *reference*
+    # a v0 message carries (a table account plus the writable/readonly index
+    # positions into it). A composer decides which of this account's addresses
+    # load — a v0 concern that needs the account context — and this object owns
+    # the table-local part: turning the addresses it contributes into that
+    # message reference.
+    #
+    # @example Register a table on a composer
+    #   table = Solace::Accounts::AddressLookupTable.new(account: address, addresses: on_chain_addresses)
+    #   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
+    #
+    # @see Solace::AddressLookupTable
+    # @see Solace::TransactionComposer
+    # @since 0.1.8
+    class AddressLookupTable
+      # Byte offset at which the stored addresses begin — the program reserves a
+      # fixed-size metadata region ahead of them regardless of its contents.
+      META_SIZE = 56
+
+      # @!attribute [r] account
+      #   @return [String, nil] The lookup table's on-chain address
+      attr_reader :account
+
+      # @!attribute [r] addresses
+      #   @return [Array<String>] The full, ordered list of addresses stored in the table
+      attr_reader :addresses
+
+      # @!attribute [r] authority
+      #   @return [String, nil] The authority allowed to extend/close the table
+      attr_reader :authority
+
+      # @!attribute [r] deactivation_slot
+      #   @return [Integer, nil] The slot the table was deactivated in (max while active)
+      attr_reader :deactivation_slot
+
+      # @!attribute [r] last_extended_slot
+      #   @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
+        )
+      end
+
+      # Initialize a lookup table account
+      #
+      # @param account [#to_s, PublicKey, nil] The lookup table's on-chain address
+      # @param addresses [Array<#to_s>, nil] The full, ordered address list; may be
+      #   omitted (the composer then loads nothing through this table)
+      # @param authority [String, nil] The table authority
+      # @param deactivation_slot [Integer, nil] The deactivation slot
+      # @param last_extended_slot [Integer, nil] The last extended slot
+      def initialize(account: nil, addresses: nil, authority: nil, deactivation_slot: nil, last_extended_slot: nil)
+        @account            = account&.to_s
+        @addresses          = Array(addresses).map(&:to_s)
+        @authority          = authority
+        @deactivation_slot  = deactivation_slot
+        @last_extended_slot = last_extended_slot
+      end
+
+      # Build the v0 message reference for the addresses this table contributes
+      #
+      # @param writable [Array<String>] Loaded writable pubkeys drawn from this table
+      # @param readonly [Array<String>] Loaded readonly pubkeys drawn from this table
+      # @return [Solace::AddressLookupTable, nil] The reference, or nil if it loads nothing
+      def reference(writable, readonly)
+        writable_indexes = positions_of(writable)
+        readonly_indexes = positions_of(readonly)
+        return if writable_indexes.empty? && readonly_indexes.empty?
+
+        Solace::AddressLookupTable.new.tap do |reference|
+          reference.account          = account
+          reference.writable_indexes = writable_indexes
+          reference.readonly_indexes = readonly_indexes
+        end
+      end
+
+      private
+
+      # Positions of the given pubkeys within this table's address list
+      #
+      # @param pubkeys [Array<String>] The pubkeys to locate
+      # @return [Array<Integer>] Their positions in {#addresses}
+      def positions_of(pubkeys)
+        pubkeys.filter_map { |pubkey| addresses.index(pubkey) }
+      end
+    end
+  end
+end

data/lib/solace/composers/address_lookup_table_program_create_composer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating an address lookup table.
+    #
+    # Resolves and orders the accounts for a `CreateLookupTable` instruction and
+    # delegates construction to
+    # `Instructions::AddressLookupTableProgram::CreateLookupTableInstruction`.
+    #
+    # The table address is a program-derived address of `[authority, recent_slot]`;
+    # derive it (and its bump) with {Solace::Utils::PDA} and pass both in.
+    #
+    # Required accounts:
+    # - **Table**: the uninitialized table account (writable, non-signer)
+    # - **Authority**: controls the table (readonly, signer)
+    # - **Payer**: funds the table's rent (writable, signer)
+    # - **System program** (readonly, non-signer)
+    #
+    # @example
+    #   composer = AddressLookupTableProgramCreateComposer.new(
+    #     table:       table_address,
+    #     authority:   authority,
+    #     payer:       payer,
+    #     recent_slot: recent_slot,
+    #     bump:        bump
+    #   )
+    #
+    # @see Instructions::AddressLookupTableProgram::CreateLookupTableInstruction
+    # @since 0.1.8
+    class AddressLookupTableProgramCreateComposer < Base
+      # @return [String] The table's on-chain address
+      def table
+        params[:table].to_s
+      end
+
+      # @return [String] The table authority
+      def authority
+        params[:authority].to_s
+      end
+
+      # @return [String] The rent payer
+      def payer
+        params[:payer].to_s
+      end
+
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID.to_s
+      end
+
+      # @return [String] The address lookup table program id
+      def lookup_table_program
+        Solace::Constants::ADDRESS_LOOKUP_TABLE_PROGRAM_ID.to_s
+      end
+
+      # @return [Integer] The slot used to derive the table address
+      def recent_slot
+        params[:recent_slot]
+      end
+
+      # @return [Integer] The bump seed for the table's program-derived address
+      def bump
+        params[:bump]
+      end
+
+      # Setup accounts required for the create lookup table instruction
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_nonsigner(table)
+        account_context.add_readonly_signer(authority)
+        account_context.add_writable_signer(payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(lookup_table_program)
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Solace::Instructions::AddressLookupTableProgram::CreateLookupTableInstruction.build(
+          recent_slot:          recent_slot,
+          bump:                 bump,
+          program_index:        account_context.index_of(lookup_table_program),
+          table_index:          account_context.index_of(table),
+          authority_index:      account_context.index_of(authority),
+          payer_index:          account_context.index_of(payer),
+          system_program_index: account_context.index_of(system_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/address_lookup_table_program_extend_composer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for extending an address lookup table with new addresses.
+    #
+    # Resolves and orders the accounts for an `ExtendLookupTable` instruction and
+    # delegates construction to
+    # `Instructions::AddressLookupTableProgram::ExtendLookupTableInstruction`.
+    #
+    # Addresses appended here become usable one slot after the extend lands.
+    #
+    # Required accounts:
+    # - **Table**: the table account being extended (writable, non-signer)
+    # - **Authority**: controls the table (readonly, signer)
+    # - **Payer**: funds any additional rent (writable, signer)
+    # - **System program** (readonly, non-signer)
+    #
+    # @example
+    #   composer = AddressLookupTableProgramExtendComposer.new(
+    #     table:     table_address,
+    #     authority: authority,
+    #     payer:     payer,
+    #     addresses: [recipient1, recipient2]
+    #   )
+    #
+    # @see Instructions::AddressLookupTableProgram::ExtendLookupTableInstruction
+    # @since 0.1.8
+    class AddressLookupTableProgramExtendComposer < Base
+      # @return [String] The table's on-chain address
+      def table
+        params[:table].to_s
+      end
+
+      # @return [String] The table authority
+      def authority
+        params[:authority].to_s
+      end
+
+      # @return [String] The rent payer
+      def payer
+        params[:payer].to_s
+      end
+
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID.to_s
+      end
+
+      # @return [String] The address lookup table program id
+      def lookup_table_program
+        Solace::Constants::ADDRESS_LOOKUP_TABLE_PROGRAM_ID.to_s
+      end
+
+      # @return [Array<String>] The addresses to append to the table
+      def addresses
+        params[:addresses].map(&:to_s)
+      end
+
+      # Setup accounts required for the extend lookup table instruction
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_nonsigner(table)
+        account_context.add_readonly_signer(authority)
+        account_context.add_writable_signer(payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(lookup_table_program)
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Solace::Instructions::AddressLookupTableProgram::ExtendLookupTableInstruction.build(
+          addresses:            addresses,
+          program_index:        account_context.index_of(lookup_table_program),
+          table_index:          account_context.index_of(table),
+          authority_index:      account_context.index_of(authority),
+          payer_index:          account_context.index_of(payer),
+          system_program_index: account_context.index_of(system_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/connection.rb

@@ -168,6 +168,16 @@ module Solace
       @rpc_client.rpc_request('getBlockHeight', [{ commitment: commitment }])['result']
     end
 
+    # Get the current slot from the Solana node
+    #
+    # @param commitment [String] The commitment level for the request
+    # @return [Integer] The current slot
+    #
+    # @since 0.1.8
+    def get_slot(commitment: default_options[:commitment])
+      @rpc_client.rpc_request('getSlot', [{ commitment: commitment }])['result']
+    end
+
     # Get the minimum required lamports for rent exemption
     #
     # @param space [Integer] Number of bytes to allocate for the account

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # The AddressLookupTableProgram module contains instruction builders for the
+    # Address Lookup Table program.
+    #
+    # Address lookup tables let a versioned (v0) transaction reference accounts by
+    # a compact table index instead of a full 32-byte key, so a single transaction
+    # can touch far more accounts than the legacy format allows.
+    #
+    # @see https://docs.solana.com/developing/lookup-tables
+    # @since 0.1.8
+    module AddressLookupTableProgram
+      # Instruction for creating a new (uninitialized) address lookup table.
+      #
+      # The table's address is a program-derived address of `[authority, recent_slot]`;
+      # the caller supplies the derived address and its bump seed.
+      #
+      # @example Build a CreateLookupTable instruction
+      #   instruction = Solace::Instructions::AddressLookupTableProgram::CreateLookupTableInstruction.build(
+      #     recent_slot:          123,
+      #     bump:                 254,
+      #     program_index:        4,
+      #     table_index:          1,
+      #     authority_index:      0,
+      #     payer_index:          0,
+      #     system_program_index: 3
+      #   )
+      #
+      # @since 0.1.8
+      class CreateLookupTableInstruction
+        # Instruction discriminator for CreateLookupTable (u32 LE)
+        INSTRUCTION_ID = [0, 0, 0, 0].freeze
+
+        # Builds a Solace::Instruction for creating a lookup table
+        #
+        # @param recent_slot [Integer] The slot used to derive the table address
+        # @param bump [Integer] The bump seed for the table's program-derived address
+        # @param program_index [Integer] Index of the lookup table program
+        # @param table_index [Integer] Index of the (uninitialized) table account
+        # @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(
+          recent_slot:,
+          bump:,
+          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(recent_slot, bump)
+          end
+        end
+
+        # Instruction data for a create lookup table instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction discriminator (4 bytes, u32 LE)]
+        #   - [Recent slot (8 bytes, u64 LE)]
+        #   - [Bump seed (1 byte)]
+        #
+        # @param recent_slot [Integer] The slot used to derive the table address
+        # @param bump [Integer] The bump seed
+        # @return [Array<Integer>]
+        def self.data(recent_slot, bump)
+          INSTRUCTION_ID +
+            Utils::Codecs.encode_le_u64(recent_slot).bytes +
+            [bump]
+        end
+      end
+    end
+  end
+end

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,6 +73,14 @@ 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)
+    attr_reader :version
+
     # Initialize the composer
     #
     # @param connection [Solace::Connection] The connection to the Solana cluster
@@ -80,6 +88,8 @@ module Solace
       @connection            = connection
       @instruction_composers = []
       @context               = Utils::AccountContext.new
+      @address_lookup_tables = []
+      @version               = nil
     end
 
     # Add an instruction composer to the transaction
@@ -127,6 +137,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)
 
       case placement
       when :add
@@ -154,24 +165,109 @@ module Solace
       self
     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
+      @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.
+    #
     # @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
 
+    # 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:      connection.get_latest_blockhash[0],
+        address_lookup_tables: references
+      )
+    end
+
     # Build all instructions with resolved indices
     #
     # @return [Array<Solace::Instruction>] The built instructions
@@ -185,5 +281,12 @@ module Solace
     def merge_accounts(account_context)
       context.merge_from(account_context)
     end
+
+    # Merge registered tables from another composer, deduped by account
+    #
+    # @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) }
+    end
   end
 end

data/lib/solace/utils/account_context.rb

@@ -62,6 +62,7 @@ module Solace
       def initialize
         @header             = []
         @accounts           = []
+        @loaded_accounts    = []
         @pubkey_account_map = {}
       end
 
@@ -173,26 +174,40 @@ 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
@@ -214,11 +229,15 @@ module Solace
         self
       end
 
-      # Order accounts by signer, writable, readonly signer, readonly
+      # Order the static accounts by signer, writable, readonly signer, readonly
       #
-      # @return [Array<String>] The ordered accounts
-      def order_accounts
-        @pubkey_account_map.keys.sort_by do |pubkey|
+      # 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)
+        (@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
@@ -237,9 +256,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/version.rb

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

data/lib/solace.rb

@@ -55,6 +55,10 @@ 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'
 
 # Base Classes (Abstract classes)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base58
@@ -202,7 +202,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - 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
@@ -231,6 +234,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