solace-squads-smart-accounts 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02a25a8f810ed514e72c62cf865dd3ea92a4edb614260fc5fbc110f913d79b6e
-  data.tar.gz: 898e4feceedc71e37de62c3dcd02ef19cc79fbed1d6a982a6b3c294ddc58e11a
+  metadata.gz: 8e2d91139fbc5fb9289950a43d758100543f42bb0e3ad2dd537279e8c65020ba
+  data.tar.gz: df7ec92b6b9f92708397131d871cb03367bab0121e9bec4e7d228319367703e4
 SHA512:
-  metadata.gz: 15b4b488be4b53df4c2d61729c58fdae258478d24b59bd5b35f361b6087b9bcb2fdc4b204f3d796bcd21b833e0f76d476df7bdacd2f084b7fd3643ce5f0e421f
-  data.tar.gz: 746d685aba1a248a94f947910350396ce64b1dbf84ba9b86d50d29ab84a7ea597f65286003a0becf963630af77167e2fd5f37a1b530154503553cc5189708c21
+  metadata.gz: 46612e52fe84c894caee64a5fdcc037584c2fee6ba18621bd67cb211db1b78726053159b729338d69625dce186025d879bdd2d56b061538d4815441ff5ce5ed6
+  data.tar.gz: bbaaf0afb4bfa57582cd834ecfd6276366da02b5b73f41502d2a575504714fed1103211327d3ea1b402e617d41ee8a8ce2ba6d6ea5426e5ffb7596a1a51de9f2

data/lib/solace/squads_smart_accounts/codecs_extensions.rb

@@ -189,6 +189,14 @@ module Solace
         Array.new(decode_le_u32(stream)) { decode_pubkey(stream) }
       end
 
+      # Decodes a Borsh bytes / Vec<u8> field: u32 LE length prefix + raw bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String] The raw bytes as a binary string.
+      def decode_bytes(stream)
+        stream.read(decode_le_u32(stream))
+      end
+
       # Decodes a u8 from 1 byte.
       #
       # @param stream [IO, StringIO] The stream to read from.

data/lib/solace/squads_smart_accounts/composers/create_smart_account_composer.rb

@@ -7,8 +7,12 @@ module Solace
     # Required params:
     #   :creator   [String]                        Base58 pubkey of the account creating the smart account.
     #   :treasury  [String]                        Base58 pubkey of the treasury (from ProgramConfig).
-    #   :settings  [String]                        Base58 pubkey of the settings PDA to be created —
-    #                                              derive via Programs::SquadsSmartAccount.get_settings_address.
+    #   :settings  [#to_s, Array<#to_s>]           The settings PDA(s) to offer as remaining accounts.
+    #                                              Pass a single address for deterministic creation
+    #                                              (derive via Programs::SquadsSmartAccount.get_settings_address),
+    #                                              or an array (a "window" of candidates) for race-free creation —
+    #                                              the program initializes whichever matches the incremented
+    #                                              counter. See Programs::SquadsSmartAccount.next_smart_account_candidates.
     #   :threshold [Integer]                       Number of approvals required to execute a transaction.
     #   :signers   [Array<SquadsSmartAccounts::SmartAccountSigner>]  Signers on the smart account.
     #   :time_lock [Integer]                       Seconds between proposal and execution (0 to disable).
@@ -32,11 +36,14 @@ module Solace
         params[:creator].to_s
       end
 
-      # Extracts the settings address from the params
+      # Normalizes the :settings param to an array of base58 addresses.
       #
-      # @return [String] The settings address
+      # Accepts a single pubkey (deterministic creation) or an array of candidate
+      # pubkeys (windowed, race-free creation), so both flows share this composer.
+      #
+      # @return [Array<String>] The settings address(es), in seed order.
       def settings
-        params[:settings].to_s
+        Array(params[:settings]).map(&:to_s)
       end
 
       # Returns the program config address from the constants
@@ -111,7 +118,9 @@ module Solace
         # Writable accounts
         account_context.add_writable_nonsigner(config)
         account_context.add_writable_nonsigner(treasury)
-        account_context.add_writable_nonsigner(settings)
+
+        # Each candidate settings PDA is offered as a writable remaining account.
+        settings.each { |address| account_context.add_writable_nonsigner(address) }
 
         # Writable signers
         account_context.add_writable_signer(creator)
@@ -134,7 +143,7 @@ module Solace
           creator_index:        context.index_of(creator),
           system_program_index: context.index_of(system_program),
           program_index:        context.index_of(program_id),
-          settings_index:       context.index_of(settings)
+          settings_index:       settings.map { |address| context.index_of(address) }
         )
       end
     end

data/lib/solace/squads_smart_accounts/instructions/create_smart_account_instruction.rb

@@ -14,7 +14,9 @@ module Solace
       #   2. creator        — writable, signer
       #   3. systemProgram  — readonly, non-signer
       #   4. program        — readonly, non-signer
-      #   5. settings       — writable, non-signer (remaining account — PDA to be created)
+      #   5+. settings      — writable, non-signer (one or more candidate settings
+      #                       PDAs as remaining accounts; the program initializes
+      #                       the one matching the freshly incremented counter)
       class CreateSmartAccountInstruction
         # 8-byte Anchor discriminator: SHA256("global:create_smart_account")[0..7]
         DISCRIMINATOR = [197, 102, 253, 231, 77, 84, 50, 17].freeze
@@ -33,7 +35,9 @@ module Solace
         # @param creator_index [Integer] Account index of creator.
         # @param system_program_index [Integer] Account index of systemProgram.
         # @param program_index [Integer] Account index of the Squads program.
-        # @param settings_index [Integer] Account index of the settings PDA to be created.
+        # @param settings_index [Integer, Array<Integer>] Account index/indices of the
+        #   candidate settings PDA(s), appended as remaining accounts. Pass a single
+        #   index for deterministic creation, or an array (a window) for race-free creation.
         # @return [Solace::Instruction]
         def self.build(
           settings_authority:,
@@ -57,7 +61,7 @@ module Solace
               creator_index,
               system_program_index,
               program_index,
-              settings_index
+              *Array(settings_index)
             ]
 
             ix.data = data(

data/lib/solace/squads_smart_accounts/programs/squads_smart_account.rb

@@ -17,6 +17,13 @@ module Solace
     #
     # @see Solace::SquadsSmartAccounts
     class SquadsSmartAccount < Base
+      # Default number of candidate settings PDAs offered by windowed creation.
+      # The on-chain counter must land inside this window for the transaction to
+      # succeed; ~20 absorbs heavy concurrency while staying well under the
+      # transaction account limit. Non-winning candidates are never initialized,
+      # so a larger window costs transaction size only, never rent.
+      DEFAULT_CREATION_WINDOW = 20
+
       class << self
         # Gets the address of the settings PDA for a given settings seed.
         #
@@ -229,6 +236,36 @@ module Solace
         )
       end
 
+      # Fetches a confirmed createSmartAccount transaction and deserializes the
+      # CreateSmartAccountEvent it emitted, revealing the settings address the
+      # program actually created.
+      #
+      # This is how a windowed creation (see {#compose_create_smart_account} with
+      # `window > 1`) learns which candidate won: the program picks one of the
+      # offered PDAs, observable only after the transaction lands. Match the
+      # returned `new_settings_pubkey` against your {#next_smart_account_candidates}
+      # to recover the seed and vault.
+      #
+      # @param signature [String] Signature of the confirmed createSmartAccount transaction.
+      # @return [SquadsSmartAccounts::CreateSmartAccountEvent] The deserialized event.
+      # @raise [RuntimeError] If the transaction is missing or carries no logEvent.
+      def get_created_smart_account_event(signature:)
+        transaction = connection.get_transaction(
+          signature,
+          commitment:                     'confirmed',
+          encoding:                       'json',
+          maxSupportedTransactionVersion: 0
+        )
+        raise "Transaction not found for signature #{signature}" unless transaction
+
+        io = log_event_stream(transaction)
+        raise "No logEvent inner instruction found in transaction #{signature}" unless io
+
+        args = Solace::SquadsSmartAccounts::LogEventArgsV2.deserialize(io)
+
+        Solace::SquadsSmartAccounts::CreateSmartAccountEvent.deserialize(StringIO.new(args.event))
+      end
+
       # Gets the full deterministic identity of the next smart account to be
       # created: the settings seed, settings address, and default vault address.
       #
@@ -252,6 +289,33 @@ module Solace
         )
       end
 
+      # Gets a window of candidate identities for race-free creation: the next
+      # `count` consecutive smart accounts (seeds `index+1 .. index+count`).
+      #
+      # Pass the candidates' settings addresses to {#create_smart_account_windowed},
+      # which offers them all and lets the program pick whichever matches the
+      # freshly incremented counter — so creation succeeds even if other accounts
+      # are created concurrently, as long as the true index lands in the window.
+      #
+      # @param count [Integer] Size of the candidate window (default: {DEFAULT_CREATION_WINDOW}).
+      # @return [Array<SquadsSmartAccounts::SmartAccountIdentity>] Candidate identities, in seed order.
+      def next_smart_account_candidates(count: DEFAULT_CREATION_WINDOW)
+        start_seed = get_program_config.smart_account_index + 1
+
+        Array.new(count) do |offset|
+          settings_seed = start_seed + offset
+
+          settings_address,      = get_settings_address(settings_seed:)
+          smart_account_address, = get_smart_account_address(settings_address:)
+
+          Solace::SquadsSmartAccounts::SmartAccountIdentity.new(
+            settings_seed:,
+            settings_address:,
+            smart_account_address:
+          )
+        end
+      end
+
       # Creates a new smart account, signs it, and (optionally) sends it.
       #
       # @example Create a smart account, retaining the values to index
@@ -300,10 +364,18 @@ module Solace
       # clients can derive and persist the settings and vault addresses before
       # sending the transaction.
       #
-      # @param settings_seed [Integer] The seed for the settings PDA (see {#next_settings_seed}).
+      # With the default `window: 1` this offers a single settings PDA and is
+      # subject to the same races as {#next_smart_account}. Pass `window > 1` to
+      # offer a window of consecutive candidate PDAs (seeds `settings_seed ..
+      # settings_seed + window - 1`); the program initializes whichever matches the
+      # freshly incremented counter, so creation tolerates concurrent creations.
+      # The chosen address is then resolved via {#get_created_smart_account_event}.
+      #
+      # @param settings_seed [Integer] The (starting) seed for the settings PDA (see {#next_settings_seed}).
       # @param creator [#to_s, Keypair] The account creating the smart account (must sign).
       # @param threshold [Integer] Number of approvals required to execute a transaction.
       # @param signers [Array<SquadsSmartAccounts::SmartAccountSigner>] Signers on the smart account.
+      # @param window [Integer] (Optional) Number of candidate PDAs to offer (default: 1).
       # @param time_lock [Integer] (Optional) Seconds between proposal and execution (default: 0).
       # @param settings_authority [#to_s] (Optional) Pubkey of the reconfiguration authority.
       # @param rent_collector [#to_s] (Optional) Pubkey for reclaiming rent on closed accounts.
@@ -314,6 +386,7 @@ module Solace
         creator:,
         threshold:,
         signers:,
+        window: 1,
         time_lock: 0,
         settings_authority: nil,
         rent_collector: nil,
@@ -321,12 +394,15 @@ module Solace
       )
         program_config = get_program_config
 
-        settings_address, = get_settings_address(settings_seed:)
+        settings = Array.new(window) do |offset|
+          address, = get_settings_address(settings_seed: settings_seed + offset)
+          address
+        end
 
         create_smart_account_ix = Composers::SquadsSmartAccountsCreateSmartAccountComposer.new(
           creator:,
           treasury:           program_config.treasury,
-          settings:           settings_address,
+          settings:,
           threshold:,
           signers:,
           time_lock:,
@@ -1813,6 +1889,30 @@ module Solace
 
       private
 
+      # Locates the program's `logEvent` self-CPI among a landed transaction's
+      # inner instructions and returns its args as a bytestream (the instruction
+      # data past the 8-byte discriminator), or nil if absent. The instruction is
+      # identified by its stable discriminator, so the match is exact.
+      #
+      # @param transaction [Hash] The raw getTransaction result.
+      # @return [StringIO, nil] Stream positioned at the start of the LogEventArgsV2.
+      def log_event_stream(transaction)
+        groups = transaction.dig('meta', 'innerInstructions') || []
+
+        groups.each do |group|
+          Array(group['instructions']).each do |ix|
+            next if ix['data'].nil?
+
+            binary = Solace::Utils::Codecs.base58_to_binary(ix['data'])
+            next unless binary.byteslice(0, 8).bytes == Solace::SquadsSmartAccounts::LogEventArgsV2::DISCRIMINATOR
+
+            return StringIO.new(binary.byteslice(8..))
+          end
+        end
+
+        nil
+      end
+
       # Derives the vault and destination ATAs for a token spending-limit spend.
       #
       # @param smart_account [#to_s] The vault PDA (owner of the source ATA).

data/lib/solace/squads_smart_accounts/types/create_smart_account_event.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Solace
+  module SquadsSmartAccounts
+    # Immutable value object representing the `CreateSmartAccountEvent` the program
+    # emits when a smart account is created. It is the `CreateSmartAccountEvent`
+    # variant of the Borsh `SmartAccountEvent` enum carried inside
+    # {LogEventArgs#event}, so deserialization reads the 1-byte enum variant tag
+    # before the event fields.
+    #
+    # On windowed creation the program picks one candidate settings PDA from the
+    # offered window; this event is the only way to learn which one was chosen
+    # (see Solace::Programs::SquadsSmartAccount#created_smart_account_settings).
+    #
+    # The on-chain event also carries `new_settings_content: Settings`, but only
+    # `new_settings_pubkey` is decoded here — it is all the caller needs to derive
+    # the vault, and the trailing Settings can be fetched on demand.
+    #
+    # @example
+    #   event = CreateSmartAccountEvent.deserialize(StringIO.new(log_event_args.event))
+    #   event.new_settings_pubkey # => base58 settings address
+    CreateSmartAccountEvent = Data.define(
+      :new_settings_pubkey # String — base58 address of the newly created settings account
+    ) do
+      # Deserializes a CreateSmartAccountEvent from a stream of Borsh-encoded
+      # SmartAccountEvent bytes (positioned at the enum variant tag).
+      #
+      # @param io [IO, StringIO] Stream positioned at the start of the event.
+      # @return [CreateSmartAccountEvent] The deserialized, frozen event value.
+      def self.deserialize(io)
+        Solace::Utils::Codecs.decode_u8(io) # SmartAccountEvent enum variant tag
+
+        new(
+          new_settings_pubkey: Solace::Utils::Codecs.decode_pubkey(io)
+        )
+      end
+    end
+  end
+end

data/lib/solace/squads_smart_accounts/types/log_event_args_v2.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Solace
+  module SquadsSmartAccounts
+    # Immutable value object for the arguments of the program's `logEvent`
+    # instruction, the self-CPI through which the program records events. The
+    # deployed program takes `LogEventArgsV2 { event: Vec<u8> }` — a single
+    # Borsh-encoded `SmartAccountEvent`. (An older `LogEventArgs` form carrying
+    # `account_seeds`/`bump` is dead code in the program and described by the
+    # bundled IDL, but is never emitted.)
+    #
+    # Extracting the args bytestream from a landed transaction is the Program
+    # layer's responsibility — see
+    # Solace::Programs::SquadsSmartAccount#get_created_smart_account_event.
+    #
+    # @example
+    #   args  = LogEventArgsV2.deserialize(io)
+    #   event = CreateSmartAccountEvent.deserialize(StringIO.new(args.event))
+    LogEventArgsV2 = Data.define(
+      :event # String — Borsh-encoded SmartAccountEvent bytes (binary string)
+    ) do
+      # Deserializes a LogEventArgsV2 from a stream of Borsh-encoded instruction
+      # data (positioned just past the 8-byte logEvent discriminator).
+      #
+      # @param io [IO, StringIO] Stream positioned at the start of the args.
+      # @return [LogEventArgsV2] The deserialized, frozen args value.
+      def self.deserialize(io)
+        new(event: Solace::Utils::Codecs.decode_bytes(io))
+      end
+    end
+
+    # 8-byte Anchor discriminator of the `logEvent` instruction (sha256("global:
+    # log_event")[0, 8]), a stable name-derived instruction discriminator — not
+    # per-event data. The Program layer uses it to locate the logEvent self-CPI
+    # among a transaction's inner instructions. (Defined here rather than inside
+    # the Data.define block, where constant assignment would leak to the enclosing
+    # module instead of the class.)
+    LogEventArgsV2::DISCRIMINATOR = [5, 9, 90, 141, 223, 134, 57, 217].freeze
+  end
+end

data/lib/solace/squads_smart_accounts/version.rb

@@ -2,6 +2,6 @@
 
 module Solace
   module SquadsSmartAccounts
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solace-squads-smart-accounts
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sebastian Scholl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -165,6 +165,8 @@ files:
 - lib/solace/squads_smart_accounts/instructions/set_time_lock_as_authority_instruction.rb
 - lib/solace/squads_smart_accounts/instructions/use_spending_limit_instruction.rb
 - lib/solace/squads_smart_accounts/programs/squads_smart_account.rb
+- lib/solace/squads_smart_accounts/types/create_smart_account_event.rb
+- lib/solace/squads_smart_accounts/types/log_event_args_v2.rb
 - lib/solace/squads_smart_accounts/types/period.rb
 - lib/solace/squads_smart_accounts/types/permissions.rb
 - lib/solace/squads_smart_accounts/types/program_config.rb