solace 0.1.4 → 0.1.6

data/lib/solace/message.rb

@@ -68,11 +68,11 @@ module Solace
     )
       super()
 
-      @version = version
-      @header = header
-      @accounts = accounts
-      @recent_blockhash = recent_blockhash
-      @instructions = instructions
+      @version               = version
+      @header                = header
+      @accounts              = accounts
+      @recent_blockhash      = recent_blockhash
+      @instructions          = instructions
       @address_lookup_tables = address_lookup_tables
     end
 

data/lib/solace/programs/associated_token_account.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# The AssociatedTokenAccount program is a Solana program that provides a standardized way to create and manage token accounts.
+# The AssociatedTokenAccount program is a Solana program that provides a standardized
+# way to create and manage token accounts.
 #
 # This class provides a Ruby interface to the Associated Token Account program, allowing you to easily
 # find or create associated token accounts for a given wallet and mint.
@@ -37,14 +38,25 @@ module Solace
       class << self
         # Gets the address of an associated token account.
         #
+        # The token program ID is part of the ATA derivation seed. For mints
+        # owned by the legacy SPL Token program this is {Constants::TOKEN_PROGRAM_ID}
+        # (the default). For mints owned by the Token-2022 program (e.g. PYUSD on
+        # Solana), pass +token_program_id: Solace::Constants::TOKEN_2022_PROGRAM_ID+
+        # to derive the correct address. Deriving with the wrong program ID
+        # returns an address that does not exist on chain.
+        #
+        # Use {Connection#get_mint_program_id} to discover which token program
+        # owns a given mint at runtime.
+        #
         # @param owner [Keypair, PublicKey] The keypair of the owner.
         # @param mint [Keypair, PublicKey] The keypair of the mint.
-        # @return [String] The address of the associated token account.
-        def get_address(owner:, mint:)
+        # @param token_program_id [String] The token program that owns the mint (defaults to legacy SPL Token).
+        # @return [Array<String, Integer>] The associated token account address and bump seed.
+        def get_address(owner:, mint:, token_program_id: Solace::Constants::TOKEN_PROGRAM_ID)
           Solace::Utils::PDA.find_program_address(
             [
               owner.to_s,
-              Solace::Constants::TOKEN_PROGRAM_ID,
+              token_program_id.to_s,
               mint.to_s
             ],
             Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
@@ -73,24 +85,27 @@ module Solace
       # @param funder [Keypair] The keypair that will pay for rent of the new associated token account.
       # @param owner [Keypair, PublicKey] The keypair of the owner.
       # @param mint [Keypair, PublicKey] The keypair of the mint.
+      # @param token_program_id [String] The token program that owns the mint (defaults to legacy SPL Token).
       # @return [String] The address of the associated token account
       def get_or_create_address(
         payer:,
         funder:,
         owner:,
-        mint:
+        mint:,
+        token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
       )
-        ata_address, = get_address(owner: owner, mint: mint)
+        ata_address, = get_address(owner: owner, mint: mint, token_program_id: token_program_id)
 
         account_balance = connection.get_account_info(ata_address)
 
         return ata_address unless account_balance.nil?
 
         tx = create_associated_token_account(
-          payer: payer,
-          funder: funder,
-          owner: owner,
-          mint: mint
+          payer:            payer,
+          funder:           funder,
+          owner:            owner,
+          mint:             mint,
+          token_program_id: token_program_id
         )
 
         connection.wait_for_confirmed_signature { tx.signature }
@@ -136,19 +151,22 @@ module Solace
       # @param owner [#to_s, PublicKey] The keypair of the owner.
       # @param mint [#to_s, PublicKey] The keypair of the mint.
       # @param funder [#to_s, PublicKey] The keypair that will pay for rent of the new associated token account.
-      # @return [Transaction] The signed transaction.
+      # @param token_program_id [String] The token program that owns the mint (defaults to legacy SPL Token).
+      # @return [TransactionComposer] A composer with the create-ATA instruction.
       def compose_create_associated_token_account(
         funder:,
         owner:,
-        mint:
+        mint:,
+        token_program_id: Solace::Constants::TOKEN_PROGRAM_ID
       )
-        ata_address, = get_address(owner: owner, mint: mint)
+        ata_address, = get_address(owner: owner, mint: mint, token_program_id: token_program_id)
 
         ix = Solace::Composers::AssociatedTokenAccountProgramCreateAccountComposer.new(
-          mint: mint,
-          owner: owner,
-          funder: funder,
-          ata_address: ata_address
+          mint:             mint,
+          owner:            owner,
+          funder:           funder,
+          ata_address:      ata_address,
+          token_program_id: token_program_id
         )
 
         TransactionComposer

data/lib/solace/programs/spl_token.rb

@@ -2,11 +2,13 @@
 
 module Solace
   module Programs
-    # Client for interacting with the SPL Token Program.
+    # Client for interacting with the legacy SPL Token Program.
     #
-    # This client provides methods for interacting with the SPL Token Program. It is a wrapper around
-    # the SPL Token Program and provides a more convenient interface for creating and managing SPL
-    # Token mints and accounts.
+    # This client provides methods for creating mints, minting tokens, and
+    # transferring tokens via the legacy SPL Token program
+    # (+TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA+). The shared method shape
+    # comes from {TokenProgramInterface}; this class supplies the SPL-bound
+    # composer classes.
     #
     # @example Create an SPL Token mint
     #   # Initialize the program with a connection
@@ -25,8 +27,11 @@ module Solace
     #   # Wait for the transaction to be finalized
     #   connection.wait_for_confirmed_signature('finalized') { result['result'] }
     #
+    # @see Solace::Programs::Token2022 for the Token-2022 successor program.
     # @since 0.0.2
     class SplToken < Base
+      include TokenProgramInterface
+
       # Initializes a new SPL Token client.
       #
       # @param connection [Solace::Connection] The connection to the Solana cluster.
@@ -34,263 +39,22 @@ module Solace
         super(connection: connection, program_id: Solace::Constants::TOKEN_PROGRAM_ID)
       end
 
-      # Creates a new SPL Token mint.
-      #
-      # @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 calling the compose_create_mint method.
-      # @return [String] The signature of the 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 SPL Token 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
-        )
+      private
 
-        # Build the initialize mint composer
-        initialize_mint_ix = Composers::SplTokenProgramInitializeMintComposer.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)
+      def initialize_mint_composer_class
+        Composers::SplTokenProgramInitializeMintComposer
       end
-      # rubocop:enable Metrics/MethodLength
-
-      # Mint 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 calling the compose_mint_to method.
-      # @return [String] The signature of the 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
+      def mint_to_composer_class
+        Composers::SplTokenProgramMintToComposer
       end
 
-      # Prepares a mint to instruction and returns the signed transaction.
-      #
-      # @param [Integer] amount The amount of tokens to mint.
-      # @param [#to_s, PublicKey] mint The mint of the token.
-      # @param [#to_s, PublicKey] destination The destination of the token.
-      # @param [#to_s, PublicKey] mint_authority The mint authority of the token.
-      # @return [TransactionComposer] A composer with required instructions.
-      #
-      # @param [Boolean] ensure_account
-      def compose_mint_to(
-        mint:,
-        amount:,
-        destination:,
-        mint_authority:
-      )
-        ix = Composers::SplTokenProgramMintToComposer.new(
-          amount: amount,
-          mint: mint,
-          destination: destination,
-          mint_authority: mint_authority
-        )
-
-        TransactionComposer
-          .new(connection: connection)
-          .add_instruction(ix)
+      def transfer_composer_class
+        Composers::SplTokenProgramTransferComposer
       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 calling the compose_transfer method.
-      # @return [String] The signature of the 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 and returns the signed transaction.
-      #
-      # @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 keypair of the owner of the source account.
-      # @return [TransactionComposer] A composer with required instructions.
-      #
-      def compose_transfer(
-        amount:,
-        source:,
-        destination:,
-        owner:
-      )
-        ix = Composers::SplTokenProgramTransferComposer.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 calling the compose_transfer_checked method.
-      # @return [String] The signature of the 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 and returns the signed transaction.
-      #
-      # @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 keypair of the owner of the source account.
-      # @return [TransactionComposer] A composer with required instructions.
-      def compose_transfer_checked(
-        to:,
-        from:,
-        mint:,
-        authority:,
-        amount:,
-        decimals:
-      )
-        ix = Composers::SplTokenProgramTransferCheckedComposer.new(
-          to: to,
-          from: from,
-          mint: mint,
-          authority: authority,
-          amount: amount,
-          decimals: decimals
-        )
-
-        TransactionComposer
-          .new(connection: connection)
-          .add_instruction(ix)
+      def transfer_checked_composer_class
+        Composers::SplTokenProgramTransferCheckedComposer
       end
     end
   end

data/lib/solace/programs/token_2022.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    # Client for interacting with the Token-2022 Program (formerly Token Extensions).
+    #
+    # Token-2022 is the successor to the legacy SPL Token program
+    # (+TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb+). Its base instructions —
+    # Transfer, TransferChecked, CloseAccount, MintTo, InitializeMint — are
+    # wire-compatible with the legacy program; only the program account they
+    # target is different. The shared method shape comes from
+    # {TokenProgramInterface}; this class supplies the Token-2022-bound
+    # composer classes. Branching between SPL Token and Token-2022 belongs at
+    # the call site, where the developer already knows which mint they hold.
+    #
+    # Important: mints owned by Token-2022 (e.g. PYUSD on Solana) derive
+    # their Associated Token Accounts with this program ID in the seed.
+    # When working with such a mint, pass
+    # +token_program_id: Solace::Constants::TOKEN_2022_PROGRAM_ID+ to
+    # {Programs::AssociatedTokenAccount.get_address}. Use
+    # {Connection#get_mint_program_id} to discover which token program owns
+    # a given mint at runtime.
+    #
+    # This class does not yet expose the Token-2022 extension instructions
+    # (transfer hooks, transfer fees, confidential transfer, etc.); those
+    # are out of scope for the base instruction surface.
+    #
+    # @example Create a Token-2022 mint
+    #   program = Solace::Programs::Token2022.new(connection: connection)
+    #
+    #   tx = program.create_mint(
+    #     payer: payer,
+    #     funder: funder,
+    #     decimals: 6,
+    #     mint_account: mint_account,
+    #     mint_authority: mint_authority
+    #   )
+    #
+    # @see Solace::Programs::SplToken
+    # @since 0.1.5
+    class Token2022 < Base
+      include TokenProgramInterface
+
+      # Initializes a new Token-2022 client.
+      #
+      # @param connection [Solace::Connection] The connection to the Solana cluster.
+      def initialize(connection:)
+        super(connection: connection, program_id: Solace::Constants::TOKEN_2022_PROGRAM_ID)
+      end
+
+      private
+
+      def initialize_mint_composer_class
+        Composers::Token2022ProgramInitializeMintComposer
+      end
+
+      def mint_to_composer_class
+        Composers::Token2022ProgramMintToComposer
+      end
+
+      def transfer_composer_class
+        Composers::Token2022ProgramTransferComposer
+      end
+
+      def transfer_checked_composer_class
+        Composers::Token2022ProgramTransferCheckedComposer
+      end
+    end
+  end
+end