solace 0.1.4 → 0.1.6

data/lib/solace/programs/token_program_interface.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    # Mixin describing the common surface of a token-program client.
+    #
+    # The legacy SPL Token program and Token-2022 expose a wire-compatible
+    # base instruction set (Transfer, TransferChecked, CloseAccount, MintTo,
+    # InitializeMint). This module captures the *shape* of a client that
+    # speaks that surface — the public methods +create_mint+, +mint_to+,
+    # +transfer+, +transfer_checked+ and their +compose_*+ pairs — without
+    # binding to either program.
+    #
+    # State (connection, program_id) lives on {Programs::Base}; this module
+    # is purely behavior. Including classes must implement four private
+    # readers that name the composer class for each operation:
+    #
+    # - {#initialize_mint_composer_class}
+    # - {#mint_to_composer_class}
+    # - {#transfer_composer_class}
+    # - {#transfer_checked_composer_class}
+    #
+    # Each composer returned by those readers is itself bound to a single
+    # on-chain program, which is how this mixin keeps the boundary clean:
+    # +SplToken+ and +Token2022+ share *methods* but never share a composer.
+    #
+    # @see Solace::Programs::SplToken
+    # @see Solace::Programs::Token2022
+    # @since 0.1.5
+    # rubocop:disable Metrics/ModuleLength
+    module TokenProgramInterface
+      # Creates a new mint, signs it, and (optionally) sends it.
+      #
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for {#compose_create_mint}.
+      # @return [Transaction] The created or sent transaction.
+      def create_mint(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_create_mint(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:funder],
+            composer_opts[:mint_account]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+
+        tx
+      end
+
+      # Prepares a new mint transaction.
+      #
+      # @param funder [#to_s, PublicKey] The keypair that will pay for rent of the new mint account.
+      # @param decimals [Integer] The number of decimal places for the token.
+      # @param mint_authority [#to_s, PublicKey] The base58 public key for the mint authority.
+      # @param freeze_authority [#to_s, PublicKey] (Optional) The base58 public key for the freeze authority.
+      # @param mint_account [#to_s, PublicKey] (Optional) The keypair for the new mint.
+      # @return [TransactionComposer] A composer with required instructions.
+      # rubocop:disable Metrics/MethodLength
+      def compose_create_mint(
+        funder:,
+        decimals:,
+        mint_authority:,
+        freeze_authority: nil,
+        mint_account: Solace::Keypair.generate
+      )
+        # Mint accounts need 82 bytes of space, and we need to fund it with enough lamports to be rent-exempt
+        rent_lamports = connection.get_minimum_lamports_for_rent_exemption(82)
+
+        # Build the account for the mint
+        create_account_ix = Composers::SystemProgramCreateAccountComposer.new(
+          from:        funder,
+          new_account: mint_account,
+          owner:       program_id,
+          lamports:    rent_lamports,
+          space:       82
+        )
+
+        # Build the initialize mint composer (per-program class supplied by includer)
+        initialize_mint_ix = initialize_mint_composer_class.new(
+          decimals:         decimals,
+          mint_account:     mint_account,
+          mint_authority:   mint_authority,
+          freeze_authority: freeze_authority
+        )
+
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(create_account_ix)
+          .add_instruction(initialize_mint_ix)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Mints tokens to a token account.
+      #
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for {#compose_mint_to}.
+      # @return [Transaction] The created or sent transaction.
+      def mint_to(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_mint_to(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:mint_authority]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+
+        tx
+      end
+
+      # Prepares a mint_to instruction.
+      #
+      # @param amount [Integer] The amount of tokens to mint.
+      # @param mint [#to_s, PublicKey] The mint of the token.
+      # @param destination [#to_s, PublicKey] The destination token account.
+      # @param mint_authority [#to_s, PublicKey] The mint authority.
+      # @return [TransactionComposer] A composer with the mint_to instruction.
+      def compose_mint_to(
+        mint:,
+        amount:,
+        destination:,
+        mint_authority:
+      )
+        ix = mint_to_composer_class.new(
+          amount:         amount,
+          mint:           mint,
+          destination:    destination,
+          mint_authority: mint_authority
+        )
+
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
+      end
+
+      # Transfers tokens from one account to another.
+      #
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for {#compose_transfer}.
+      # @return [Transaction] The created or sent transaction.
+      def transfer(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_transfer(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:owner]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+        tx
+      end
+
+      # Prepares a transfer instruction.
+      #
+      # @param source [#to_s, PublicKey] The source token account address.
+      # @param destination [#to_s, PublicKey] The destination token account address.
+      # @param amount [Integer] The number of tokens to transfer.
+      # @param owner [#to_s, PublicKey] The owner of the source account.
+      # @return [TransactionComposer] A composer with the transfer instruction.
+      def compose_transfer(
+        amount:,
+        source:,
+        destination:,
+        owner:
+      )
+        ix = transfer_composer_class.new(
+          amount:      amount,
+          owner:       owner,
+          source:      source,
+          destination: destination
+        )
+
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
+      end
+
+      # Transfers tokens with decimal precision and validation checks.
+      #
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for {#compose_transfer_checked}.
+      # @return [Transaction] The created or sent transaction.
+      def transfer_checked(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_transfer_checked(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:authority]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+
+        tx
+      end
+
+      # Prepares a transfer_checked instruction.
+      #
+      # @param amount [Integer] The number of tokens to transfer.
+      # @param decimals [Integer] The number of decimals for the token.
+      # @param from [#to_s, PublicKey] The source token account address.
+      # @param to [#to_s, PublicKey] The destination token account address.
+      # @param mint [#to_s, PublicKey] The mint address.
+      # @param authority [#to_s, PublicKey] The owner of the source account.
+      # @return [TransactionComposer] A composer with the transfer_checked instruction.
+      def compose_transfer_checked(
+        to:,
+        from:,
+        mint:,
+        authority:,
+        amount:,
+        decimals:
+      )
+        ix = transfer_checked_composer_class.new(
+          to:        to,
+          from:      from,
+          mint:      mint,
+          authority: authority,
+          amount:    amount,
+          decimals:  decimals
+        )
+
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
+      end
+
+      private
+
+      # @return [Class] Composer class used by {#compose_create_mint}.
+      def initialize_mint_composer_class
+        raise NotImplementedError, "#{self.class} must implement #initialize_mint_composer_class"
+      end
+
+      # @return [Class] Composer class used by {#compose_mint_to}.
+      def mint_to_composer_class
+        raise NotImplementedError, "#{self.class} must implement #mint_to_composer_class"
+      end
+
+      # @return [Class] Composer class used by {#compose_transfer}.
+      def transfer_composer_class
+        raise NotImplementedError, "#{self.class} must implement #transfer_composer_class"
+      end
+
+      # @return [Class] Composer class used by {#compose_transfer_checked}.
+      def transfer_checked_composer_class
+        raise NotImplementedError, "#{self.class} must implement #transfer_checked_composer_class"
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/solace/serializers/address_lookup_table_deserializer.rb

@@ -40,7 +40,7 @@ module Solace
       #
       # @return [Array<Integer>] The writable indexes
       def next_extract_writable_indexes
-        length, = Codecs.decode_compact_u16(io)
+        length,                 = Codecs.decode_compact_u16(io)
         record.writable_indexes = io.read(length).unpack('C*')
       end
 
@@ -52,7 +52,7 @@ module Solace
       #
       # @return [Array<Integer>] The readonly indexes
       def next_extract_readonly_indexes
-        length, = Codecs.decode_compact_u16(io)
+        length,                 = Codecs.decode_compact_u16(io)
         record.readonly_indexes = io.read(length).unpack('C*')
       end
     end

data/lib/solace/serializers/base_deserializer.rb

@@ -36,7 +36,7 @@ module Solace
       # @return [BaseDeserializer] The new deserializer object
       def initialize(io)
         super()
-        @io = io
+        @io     = io
         @record = self.class.record_class.new
       end
 

data/lib/solace/serializers/instruction_deserializer.rb

@@ -40,7 +40,7 @@ module Solace
       #
       # @return [Array] The accounts
       def next_extract_accounts
-        length, = Codecs.decode_compact_u16(io)
+        length,         = Codecs.decode_compact_u16(io)
         record.accounts = io.read(length).unpack('C*')
       end
 
@@ -52,7 +52,7 @@ module Solace
       #
       # @return [Array] The instruction data
       def next_extract_data
-        length, = Codecs.decode_compact_u16(io)
+        length,     = Codecs.decode_compact_u16(io)
         record.data = io.read(length).unpack('C*')
       end
     end

data/lib/solace/serializers/message_deserializer.rb

@@ -64,7 +64,7 @@ module Solace
       #
       # @return [Array<String>] The account keys of the message
       def next_extract_accounts
-        count, = Codecs.decode_compact_u16(io)
+        count,          = Codecs.decode_compact_u16(io)
         record.accounts = count.times.map do
           Codecs.bytes_to_base58 io.read(32).bytes
         end
@@ -88,7 +88,7 @@ module Solace
       #
       # @return [Array<Solace::Instruction>] The instructions of the message
       def next_extract_instructions
-        count, = Codecs.decode_compact_u16(io)
+        count,              = Codecs.decode_compact_u16(io)
         record.instructions = count.times.map do
           Solace::Instruction.deserialize(io)
         end
@@ -104,7 +104,7 @@ module Solace
       def next_extract_address_lookup_table
         return unless record.versioned?
 
-        count, = Codecs.decode_compact_u16(io)
+        count,                       = Codecs.decode_compact_u16(io)
         record.address_lookup_tables = count.times.map do
           Solace::AddressLookupTable.deserialize(io)
         end

data/lib/solace/serializers/transaction_deserializer.rb

@@ -29,7 +29,7 @@ module Solace
       #
       # @return [Array] Array of base58 encoded signatures
       def next_extract_signatures
-        count, = Codecs.decode_compact_u16(io)
+        count,            = Codecs.decode_compact_u16(io)
         record.signatures = count.times.map { io.read(64) }
       end
 

data/lib/solace/tokens/token.rb

@@ -18,7 +18,7 @@ module Solace
       # @param metadata [Hash] A hash containing the token's metadata attributes
       # @return [self] The initialized Token object
       def initialize(symbol, metadata)
-        @symbol = symbol
+        @symbol   = symbol
         @metadata = metadata.transform_keys(&:to_sym)
       end
 

data/lib/solace/tokens.rb

@@ -29,7 +29,7 @@ module Solace
     # @param network [String, Symbol] Network name (e.g., 'mainnet', 'testnet')
     # @return [void]
     def self.load(path:, network:)
-      data = YAML.load_file(path)
+      data   = YAML.load_file(path)
       tokens = data.fetch(network.to_s) do
         raise ArgumentError, "Network '#{network}' not found in config"
       end
@@ -40,7 +40,7 @@ module Solace
       @registry = {}
 
       tokens.each do |symbol, attrs|
-        token = Solace::Tokens::Token.new(symbol, attrs)
+        token                  = Solace::Tokens::Token.new(symbol, attrs)
         const_set(symbol, token)
         @registry[symbol.to_s] = token
       end

data/lib/solace/transaction.rb

@@ -66,7 +66,7 @@ module Solace
     )
       super()
       @signatures = signatures
-      @message = message
+      @message    = message
     end
 
     # Returns the first signature of the transaction (signature of the transaction fee payer)

data/lib/solace/transaction_composer.rb

@@ -77,9 +77,9 @@ module Solace
     #
     # @param connection [Solace::Connection] The connection to the Solana cluster
     def initialize(connection:)
-      @connection = connection
+      @connection            = connection
       @instruction_composers = []
-      @context = Utils::AccountContext.new
+      @context               = Utils::AccountContext.new
     end
 
     # Add an instruction composer to the transaction
@@ -161,9 +161,9 @@ module Solace
       context.compile
 
       message = Solace::Message.new(
-        header: context.header,
-        accounts: context.accounts,
-        instructions: build_instructions,
+        header:           context.header,
+        accounts:         context.accounts,
+        instructions:     build_instructions,
         recent_blockhash: connection.get_latest_blockhash[0]
       )
 

data/lib/solace/utils/account_context.rb

@@ -35,8 +35,8 @@ module Solace
       #
       # @return [Hash] The default account data with lowest level of permissions
       DEFAULT_ACCOUNT = {
-        signer: false,
-        writable: false,
+        signer:    false,
+        writable:  false,
         fee_payer: false
       }.freeze
 
@@ -60,8 +60,8 @@ module Solace
 
       # Initialize the account context
       def initialize
-        @header = []
-        @accounts = []
+        @header             = []
+        @accounts           = []
         @pubkey_account_map = {}
       end
 
@@ -175,7 +175,7 @@ module Solace
       #
       # @return [Hash] The compiled accounts and header
       def compile
-        self.header = calculate_header
+        self.header   = calculate_header
         self.accounts = order_accounts
         self
       end
@@ -206,9 +206,9 @@ module Solace
       def merge_account(pubkey, signer:, writable:, fee_payer: false)
         pubkey_str = pubkey.is_a?(String) ? pubkey : pubkey.address
 
-        @pubkey_account_map[pubkey_str] ||= DEFAULT_ACCOUNT.dup
-        @pubkey_account_map[pubkey_str][:signer] ||= signer
-        @pubkey_account_map[pubkey_str][:writable] ||= writable
+        @pubkey_account_map[pubkey_str]             ||= DEFAULT_ACCOUNT.dup
+        @pubkey_account_map[pubkey_str][:signer]    ||= signer
+        @pubkey_account_map[pubkey_str][:writable]  ||= writable
         @pubkey_account_map[pubkey_str][:fee_payer] ||= fee_payer
 
         self
@@ -242,7 +242,7 @@ module Solace
         @pubkey_account_map.keys.each_with_object([0, 0, 0]) do |pubkey, acc|
           acc[0] += 1 if signer?(pubkey)
 
-          if readonly_signer?(pubkey) then acc[1] += 1
+          if readonly_signer?(pubkey) then acc[1]       += 1
           elsif readonly_nonsigner?(pubkey) then acc[2] += 1
           end
         end