solace-squads-smart-accounts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02a25a8f810ed514e72c62cf865dd3ea92a4edb614260fc5fbc110f913d79b6e
+  data.tar.gz: 898e4feceedc71e37de62c3dcd02ef19cc79fbed1d6a982a6b3c294ddc58e11a
+SHA512:
+  metadata.gz: 15b4b488be4b53df4c2d61729c58fdae258478d24b59bd5b35f361b6087b9bcb2fdc4b204f3d796bcd21b833e0f76d476df7bdacd2f084b7fd3643ce5f0e421f
+  data.tar.gz: 746d685aba1a248a94f947910350396ce64b1dbf84ba9b86d50d29ab84a7ea597f65286003a0becf963630af77167e2fd5f37a1b530154503553cc5189708c21

data/lib/solace/squads_smart_accounts/codecs_extensions.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Solace
+  module Utils
+    # Extensions to Solace::Utils::Codecs for Anchor programs and Borsh types not
+    # covered by the base gem. Candidates for upstreaming to solace when the need
+    # is confirmed across other extension gems.
+    module Codecs
+      extend self
+
+      # Encodes a SmallVec<u8, u8>: u8 length prefix + raw bytes.
+      #
+      # @param bytes [Array<Integer>] The raw bytes (max 255).
+      # @return [Array<Integer>]
+      def encode_smallvec_u8_bytes(bytes)
+        [bytes.length] + bytes
+      end
+
+      # Encodes a u16 as 2 little-endian bytes.
+      #
+      # @param u16 [Integer] Value in range 0..65535.
+      # @return [String] 2-byte little-endian binary string.
+      def encode_le_u16(u16)
+        [u16].pack('S<')
+      end
+
+      # Encodes a SmallVec<u16, u8>: u16 LE length prefix + raw bytes.
+      #
+      # @param bytes [Array<Integer>] The raw bytes (max 65535).
+      # @return [Array<Integer>]
+      def encode_smallvec_u16_bytes(bytes)
+        encode_le_u16(bytes.length).bytes + bytes
+      end
+
+      # Encodes a u32 as 4 little-endian bytes.
+      #
+      # @param u32 [Integer] Value in range 0..4294967295.
+      # @return [String] 4-byte little-endian binary string.
+      def encode_le_u32(u32)
+        [u32].pack('L<')
+      end
+
+      # Encodes an i64 as 8 little-endian bytes (two's complement).
+      #
+      # @param i64 [Integer] Value in range -2**63..2**63-1.
+      # @return [String] 8-byte little-endian binary string.
+      def encode_le_i64(i64)
+        [i64].pack('q<')
+      end
+
+      # Encodes a Borsh bool as a single byte: false → 0, true → 1.
+      #
+      # @param bool [Boolean] The value to encode.
+      # @return [Array<Integer>] A single-element byte array.
+      def encode_bool(bool)
+        [bool ? 1 : 0]
+      end
+
+      # Encodes a u128 as 16 little-endian bytes (two u64 words, low word first).
+      #
+      # @param u128 [Integer] Value in range 0..2**128-1.
+      # @return [String] 16-byte little-endian binary string.
+      def encode_le_u128(u128)
+        [u128 & 0xFFFFFFFFFFFFFFFF, u128 >> 64].pack('Q<Q<')
+      end
+
+      # Encodes a Borsh bytes field: u32 LE length prefix + raw bytes.
+      #
+      # @param bytes [Array<Integer>] The raw bytes.
+      # @return [Array<Integer>]
+      def encode_bytes(bytes)
+        encode_le_u32(bytes.length).bytes + bytes
+      end
+
+      # Encodes an Option<String> in Borsh format.
+      # None → [0], Some(str) → [1] + u32 length + UTF-8 bytes.
+      #
+      # @param str [String, nil]
+      # @return [Array<Integer>]
+      def encode_option_string(str)
+        return [0] if str.nil?
+
+        bytes = str.encode('UTF-8').bytes
+        [1] + encode_le_u32(bytes.length).bytes + bytes
+      end
+
+      # Encodes a public key as 32 bytes. Accepts any representation that
+      # resolves to a base58 string via #to_s (String, Keypair, PublicKey).
+      #
+      # @param pubkey [#to_s] The public key in any representation.
+      # @return [Array<Integer>] 32 bytes.
+      def encode_pubkey(pubkey)
+        Solace::Utils::Codecs.base58_to_bytes(pubkey.to_s)
+      end
+
+      # Encodes an Option<publicKey> in Borsh format.
+      # None → [0], Some(key) → [1] + 32 bytes.
+      #
+      # @param pubkey [String, nil] Base58 public key or nil.
+      # @return [Array<Integer>]
+      def encode_option_pubkey(pubkey)
+        return [0] if pubkey.nil?
+
+        [1] + encode_pubkey(pubkey)
+      end
+
+      # Encodes a Vec<publicKey> in Borsh format.
+      # u32 LE count prefix followed by each 32-byte pubkey.
+      #
+      # @param pubkeys [Array<#to_s>] The public keys in any representation.
+      # @return [Array<Integer>]
+      def encode_vec_pubkeys(pubkeys)
+        encode_le_u32(pubkeys.length).bytes +
+          pubkeys.flat_map { |pubkey| encode_pubkey(pubkey) }
+      end
+
+      # Encodes a SmallVec<u8, Pubkey>: u8 count prefix followed by each 32-byte
+      # pubkey. Used by the transaction message header's account_keys (distinct
+      # from encode_vec_pubkeys, which uses a u32 count).
+      #
+      # @param pubkeys [Array<#to_s>] The public keys in any representation (max 255).
+      # @return [Array<Integer>]
+      def encode_smallvec_u8_pubkeys(pubkeys)
+        [pubkeys.length] + pubkeys.flat_map { |pubkey| encode_pubkey(pubkey) }
+      end
+
+      # Encodes a Vec<SmartAccountSigner> in Borsh format.
+      # u32 length prefix followed by each signer's 32-byte pubkey + 1-byte permission mask.
+      #
+      # @param signers [Array<SquadsSmartAccounts::SmartAccountSigner>]
+      # @return [Array<Integer>]
+      def encode_smart_account_signers(signers)
+        encode_le_u32(signers.length).bytes +
+          signers.flat_map do |signer|
+            encode_pubkey(signer.pubkey) + [signer.permission]
+          end
+      end
+
+      # Encodes a Vec<SettingsAction> in Borsh format.
+      # u32 LE count prefix followed by each action's variant index + field bytes.
+      #
+      # @param actions [Array<SquadsSmartAccounts::SettingsAction>]
+      # @return [Array<Integer>]
+      def encode_settings_actions(actions)
+        encode_le_u32(actions.length).bytes + actions.flat_map(&:serialize)
+      end
+
+      # Encodes a SmallVec<u8, CompiledInstruction> — the wire format the Squads
+      # program expects for synchronously executed inner instructions.
+      #
+      # NOTE: this intentionally does NOT reuse Solace's InstructionSerializer.
+      # That serializer produces the Solana transaction wire format, which uses
+      # compact-u16 (varint) length prefixes for the vec count, account indexes,
+      # and data. The Squads SmallVec format uses fixed-width prefixes instead:
+      # u8 for the vec count, u8 for the account indexes length, and u16 LE for
+      # the data length. The two encodings coincide for lengths < 128 (compact-u16
+      # encodes those as a single byte) but diverge beyond that, so reusing the
+      # Solana format would corrupt larger instructions silently.
+      #
+      # Each instruction is a {Solace::Instruction} whose program_index and
+      # accounts are indexes into the full remaining-accounts list (signers included).
+      # Layout per instruction: u8 program_id_index + SmallVec<u8,u8> account
+      # indexes + SmallVec<u16,u8> data.
+      #
+      # @param instructions [Array<Solace::Instruction>]
+      # @return [Array<Integer>]
+      def encode_compiled_instructions(instructions)
+        [instructions.length] +
+          instructions.flat_map do |ix|
+            [ix.program_index] +
+              encode_smallvec_u8_bytes(ix.accounts) +
+              encode_smallvec_u16_bytes(ix.data)
+          end
+      end
+
+      # Decodes an i64 from 8 little-endian bytes (two's complement).
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range -2**63..2**63-1.
+      def decode_le_i64(stream)
+        stream.read(8).unpack1('q<')
+      end
+
+      # Decodes a Vec<publicKey> in Borsh format.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Array<String>] Base58 public keys.
+      def decode_vec_pubkeys(stream)
+        Array.new(decode_le_u32(stream)) { decode_pubkey(stream) }
+      end
+
+      # Decodes a u8 from 1 byte.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..255.
+      def decode_u8(stream)
+        stream.read(1).unpack1('C')
+      end
+
+      # Decodes a u16 from 2 little-endian bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..65535.
+      def decode_le_u16(stream)
+        stream.read(2).unpack1('S<')
+      end
+
+      # Decodes a u32 from 4 little-endian bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..4294967295.
+      def decode_le_u32(stream)
+        stream.read(4).unpack1('L<')
+      end
+
+      # Decodes a u128 from 16 little-endian bytes (two u64 words, low word first).
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Integer] Value in range 0..2**128-1.
+      def decode_le_u128(stream)
+        lo, hi = stream.read(16).unpack('Q<Q<')
+        lo + (hi << 64)
+      end
+
+      # Decodes a public key from 32 bytes.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String] Base58 public key.
+      def decode_pubkey(stream)
+        Solace::Utils::Codecs.bytes_to_base58(stream.read(32).bytes)
+      end
+
+      # Decodes an Option<publicKey> in Borsh format.
+      # None → nil, Some(key) → base58 pubkey.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [String, nil] Base58 public key or nil.
+      def decode_option_pubkey(stream)
+        return nil if decode_u8(stream).zero?
+
+        decode_pubkey(stream)
+      end
+
+      # Decodes a Vec<SmartAccountSigner> in Borsh format.
+      # u32 length prefix followed by each signer's 32-byte pubkey + 1-byte permission mask.
+      #
+      # @param stream [IO, StringIO] The stream to read from.
+      # @return [Array<SquadsSmartAccounts::SmartAccountSigner>]
+      def decode_smart_account_signers(stream)
+        Array.new(decode_le_u32(stream)) do
+          SquadsSmartAccounts::SmartAccountSigner.new(
+            pubkey:     decode_pubkey(stream),
+            permission: decode_u8(stream)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes an `activateProposal` instruction for the Squads Smart Account program.
+    #
+    # Moves a Draft proposal to Active. The signer must be a smart-account member
+    # with the Initiate permission. Only needed for proposals created as drafts.
+    #
+    # Required params:
+    #   :settings [#to_s]          Base58 address of the settings account.
+    #   :signer   [#to_s, Keypair] The activating signer (must sign).
+    #   :proposal [#to_s]          The Proposal PDA to activate.
+    class SquadsSmartAccountsActivateProposalComposer < Base
+      # Extracts the settings address from the params
+      #
+      # @return [String] The settings address
+      def settings
+        params[:settings].to_s
+      end
+
+      # Extracts the activating signer address from the params
+      #
+      # @return [String] The signer address
+      def signer
+        params[:signer].to_s
+      end
+
+      # Extracts the proposal PDA address from the params
+      #
+      # @return [String] The proposal address
+      def proposal
+        params[:proposal].to_s
+      end
+
+      # Returns the Squads Smart Account program id from the constants
+      #
+      # @return [String] The Squads Smart Account program id
+      def program_id
+        SquadsSmartAccounts::PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction. The Squads program
+      # is registered so it appears in the message account keys (it is the
+      # invoked program), but — unlike the other proposal instructions — it is
+      # NOT included in this instruction's account-metas list (no trailing
+      # program account).
+      def setup_accounts
+        account_context.add_readonly_nonsigner(settings)
+        account_context.add_writable_signer(signer)
+        account_context.add_writable_nonsigner(proposal)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        SquadsSmartAccounts::Instructions::ActivateProposalInstruction.build(
+          settings_index: context.index_of(settings),
+          signer_index:   context.index_of(signer),
+          proposal_index: context.index_of(proposal),
+          program_index:  context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes an `addSignerAsAuthority` instruction for the Squads Smart Account program.
+    #
+    # Adds a new signer to a controlled smart account. Only the account's
+    # settings authority may do this — single signature, no consensus.
+    #
+    # Required params:
+    #   :settings           [String]              Base58 address of the settings account.
+    #   :settings_authority [#to_s, Keypair]      The account's settings authority (must sign).
+    #   :rent_payer         [#to_s, Keypair]      Pays for settings account reallocation (must sign).
+    #   :new_signer         [SquadsSmartAccounts::SmartAccountSigner] The signer to add.
+    #
+    # Optional params:
+    #   :memo [String] Indexing memo (default: nil).
+    class SquadsSmartAccountsAddSignerAsAuthorityComposer < Base
+      # Extracts the settings address from the params
+      #
+      # @return [String] The settings address
+      def settings
+        params[:settings].to_s
+      end
+
+      # Extracts the settings authority address from the params
+      #
+      # @return [String] The settings authority address
+      def settings_authority
+        params[:settings_authority].to_s
+      end
+
+      # Extracts the rent payer address from the params
+      #
+      # @return [String] The rent payer address
+      def rent_payer
+        params[:rent_payer].to_s
+      end
+
+      # Extracts the new signer from the params
+      #
+      # @return [SquadsSmartAccounts::SmartAccountSigner] The signer to add
+      def new_signer
+        params[:new_signer]
+      end
+
+      # Extracts the memo from the params
+      #
+      # @return [String, nil] The memo
+      def memo
+        params[:memo]
+      end
+
+      # Returns the Squads Smart Account program id from the constants
+      #
+      # @return [String] The Squads Smart Account program id
+      def program_id
+        SquadsSmartAccounts::PROGRAM_ID
+      end
+
+      # Returns the system program id from the constants
+      #
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_writable_nonsigner(settings)
+        account_context.add_readonly_signer(settings_authority)
+        account_context.add_writable_signer(rent_payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        SquadsSmartAccounts::Instructions::AddSignerAsAuthorityInstruction.build(
+          new_signer:,
+          memo:,
+          settings_index:           context.index_of(settings),
+          settings_authority_index: context.index_of(settings_authority),
+          rent_payer_index:         context.index_of(rent_payer),
+          system_program_index:     context.index_of(system_program),
+          program_index:            context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes an `addSpendingLimitAsAuthority` instruction for the Squads
+    # Smart Account program.
+    #
+    # Creates a SpendingLimit PDA granting designated signers a pre-authorized
+    # allowance from a vault. Only the account's settings authority may do
+    # this — single signature, no consensus.
+    #
+    # Required params:
+    #   :settings           [#to_s]          Base58 address of the settings account.
+    #   :settings_authority [#to_s, Keypair] The account's settings authority (must sign).
+    #   :spending_limit     [#to_s]          The SpendingLimit PDA to create — derive via
+    #                                        Programs::SquadsSmartAccount.get_spending_limit_address.
+    #   :rent_payer         [#to_s, Keypair] Funds the new account's rent (must sign).
+    #   :seed               [#to_s]          The pubkey the spending_limit PDA was derived with.
+    #   :amount             [Integer]        Amount spendable per period (mint decimals).
+    #   :period             [Integer]        Period enum value (reset cadence).
+    #   :signers            [Array<#to_s>]   Pubkeys allowed to use the limit.
+    #
+    # Optional params:
+    #   :account_index [Integer]      Vault index the limit spends from (default: 0).
+    #   :mint          [#to_s]        Token mint (default: DEFAULT_PUBKEY = SOL).
+    #   :destinations  [Array<#to_s>] Allowed destinations; empty = any (default: []).
+    #   :expiration    [Integer]      Unix expiration timestamp (default: I64_MAX = never).
+    #   :memo          [String]       Indexing memo (default: nil).
+    class SquadsSmartAccountsAddSpendingLimitAsAuthorityComposer < Base
+      # Extracts the settings address from the params
+      #
+      # @return [String] The settings address
+      def settings
+        params[:settings].to_s
+      end
+
+      # Extracts the settings authority address from the params
+      #
+      # @return [String] The settings authority address
+      def settings_authority
+        params[:settings_authority].to_s
+      end
+
+      # Extracts the spending limit PDA address from the params
+      #
+      # @return [String] The spending limit address
+      def spending_limit
+        params[:spending_limit].to_s
+      end
+
+      # Extracts the rent payer address from the params
+      #
+      # @return [String] The rent payer address
+      def rent_payer
+        params[:rent_payer].to_s
+      end
+
+      # Extracts the PDA seed pubkey from the params
+      #
+      # @return [String] The seed pubkey
+      def seed
+        params[:seed].to_s
+      end
+
+      # Extracts the vault index from the params
+      #
+      # @return [Integer] The vault index (defaults to 0)
+      def account_index
+        params[:account_index] || 0
+      end
+
+      # Extracts the mint from the params
+      #
+      # @return [String] The mint address (defaults to DEFAULT_PUBKEY = SOL)
+      def mint
+        (params[:mint] || SquadsSmartAccounts::DEFAULT_PUBKEY).to_s
+      end
+
+      # Extracts the per-period amount from the params
+      #
+      # @return [Integer] The amount spendable per period
+      def amount
+        params[:amount]
+      end
+
+      # Extracts the reset period from the params
+      #
+      # @return [Integer] The Period enum value
+      def period
+        params[:period]
+      end
+
+      # Extracts the allowed signer pubkeys from the params
+      #
+      # @return [Array<String>] The allowed signer addresses
+      def signers
+        params[:signers].map(&:to_s)
+      end
+
+      # Extracts the allowed destinations from the params
+      #
+      # @return [Array<String>] The allowed destination addresses (defaults to [])
+      def destinations
+        (params[:destinations] || []).map(&:to_s)
+      end
+
+      # Extracts the expiration from the params
+      #
+      # @return [Integer] Unix expiration timestamp (defaults to I64_MAX = never)
+      def expiration
+        params[:expiration] || SquadsSmartAccounts::I64_MAX
+      end
+
+      # Extracts the memo from the params
+      #
+      # @return [String, nil] The memo
+      def memo
+        params[:memo]
+      end
+
+      # Returns the Squads Smart Account program id from the constants
+      #
+      # @return [String] The Squads Smart Account program id
+      def program_id
+        SquadsSmartAccounts::PROGRAM_ID
+      end
+
+      # Returns the system program id from the constants
+      #
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_readonly_nonsigner(settings)
+        account_context.add_readonly_signer(settings_authority)
+        account_context.add_writable_nonsigner(spending_limit)
+        account_context.add_writable_signer(rent_payer)
+        account_context.add_readonly_nonsigner(system_program)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        SquadsSmartAccounts::Instructions::AddSpendingLimitAsAuthorityInstruction.build(
+          seed:,
+          account_index:,
+          mint:,
+          amount:,
+          period:,
+          signers:,
+          destinations:,
+          expiration:,
+          memo:,
+          settings_index:           context.index_of(settings),
+          settings_authority_index: context.index_of(settings_authority),
+          spending_limit_index:     context.index_of(spending_limit),
+          rent_payer_index:         context.index_of(rent_payer),
+          system_program_index:     context.index_of(system_program),
+          program_index:            context.index_of(program_id)
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composes an `approveProposal` instruction for the Squads Smart Account program.
+    #
+    # Casts an approval vote on an active proposal. The signer must be a smart
+    # account member with the Vote permission.
+    #
+    # Required params:
+    #   :settings [#to_s]          Base58 address of the settings account.
+    #   :signer   [#to_s, Keypair] The voting signer (must sign).
+    #   :proposal [#to_s]          The Proposal PDA to vote on.
+    #
+    # Optional params:
+    #   :memo [String] Indexing memo (default: nil).
+    class SquadsSmartAccountsApproveProposalComposer < Base
+      # Extracts the settings address from the params
+      #
+      # @return [String] The settings address
+      def settings
+        params[:settings].to_s
+      end
+
+      # Extracts the voting signer address from the params
+      #
+      # @return [String] The signer address
+      def signer
+        params[:signer].to_s
+      end
+
+      # Extracts the proposal PDA address from the params
+      #
+      # @return [String] The proposal address
+      def proposal
+        params[:proposal].to_s
+      end
+
+      # Extracts the memo from the params
+      #
+      # @return [String, nil] The memo
+      def memo
+        params[:memo]
+      end
+
+      # Returns the Squads Smart Account program id from the constants. The
+      # systemProgram account is optional and absent for a vote, so this id
+      # also fills that slot.
+      #
+      # @return [String] The Squads Smart Account program id
+      def program_id
+        SquadsSmartAccounts::PROGRAM_ID
+      end
+
+      # Declares all accounts required by this instruction.
+      def setup_accounts
+        account_context.add_readonly_nonsigner(settings)
+        account_context.add_writable_signer(signer)
+        account_context.add_writable_nonsigner(proposal)
+        account_context.add_readonly_nonsigner(program_id)
+      end
+
+      # Builds the instruction with resolved account indices. The absent
+      # systemProgram slot resolves to the Squads program id index.
+      #
+      # @param context [Solace::Utils::AccountContext] Merged context from TransactionComposer.
+      # @return [Solace::Instruction]
+      def build_instruction(context)
+        SquadsSmartAccounts::Instructions::ApproveProposalInstruction.build(
+          memo:,
+          settings_index:       context.index_of(settings),
+          signer_index:         context.index_of(signer),
+          proposal_index:       context.index_of(proposal),
+          system_program_index: context.index_of(program_id),
+          program_index:        context.index_of(program_id)
+        )
+      end
+    end
+  end
+end