solace 0.1.4 → 0.1.5

data/lib/solace/instructions/token_2022/close_account_instruction.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction builder for Token-2022 CloseAccount.
+      #
+      # Closes a Token-2022 token account and transfers all remaining lamports
+      # to a destination account. The token account must have a balance of zero.
+      #
+      # Instruction discriminator: 9
+      #
+      # Accounts:
+      # 1. [writable] Token account to close
+      # 2. [writable] Destination account to receive lamports
+      # 3. [signer]   Account authority
+      #
+      # @since 0.1.5
+      class CloseAccountInstruction
+        # Instruction discriminator for CloseAccount
+        INSTRUCTION_DISCRIMINATOR = [9].freeze
+
+        # Builds a CloseAccount instruction.
+        #
+        # @param account_index [Integer] Index of the token account to close
+        # @param destination_index [Integer] Index of the destination account
+        # @param authority_index [Integer] Index of the account authority
+        # @param program_index [Integer] Index of the Token-2022 program
+        # @return [Solace::Instruction] The constructed instruction
+        def self.build(account_index:, destination_index:, authority_index:, program_index:)
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [account_index, destination_index, authority_index]
+            ix.data = data
+          end
+        end
+
+        # Builds the data for a CloseAccount instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_DISCRIMINATOR
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/initialize_account_instruction.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for initializing a new Token-2022 token account.
+      #
+      # Used in conjunction with the SystemProgram::CreateAccount instruction
+      # to create and initialize a new token account. For the common case of
+      # an associated token account, prefer
+      # {AssociatedTokenAccount::CreateAccountInstruction}.
+      #
+      # @example Build an InitializeAccount instruction
+      #   instruction = Solace::Instructions::Token2022::InitializeAccountInstruction.build(
+      #     account_index: 0,
+      #     mint_index: 1,
+      #     owner_index: 2,
+      #     rent_sysvar_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class InitializeAccountInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's InitializeAccount instruction.
+        INSTRUCTION_INDEX = [1].freeze
+
+        # Builds a Token2022::InitializeAccount instruction.
+        #
+        # @param account_index [Integer] Index of the new token account in the transaction's accounts.
+        # @param mint_index [Integer] Index of the mint account in the transaction's accounts.
+        # @param owner_index [Integer] Index of the owner of the new account in the transaction's accounts.
+        # @param rent_sysvar_index [Integer] Index of the Rent Sysvar in the transaction's accounts.
+        # @param program_index [Integer] Index of the Token-2022 program in the transaction's accounts.
+        # @return [Solace::Instruction]
+        def self.build(
+          account_index:,
+          mint_index:,
+          owner_index:,
+          rent_sysvar_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [account_index, mint_index, owner_index, rent_sysvar_index]
+            ix.data = data
+          end
+        end
+
+        # Builds the data for a Token2022::InitializeAccount instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_INDEX
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/initialize_mint_instruction.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for initializing a new Token-2022 mint.
+      #
+      # @example Build an InitializeMint instruction
+      #   instruction = Solace::Instructions::Token2022::InitializeMintInstruction.build(
+      #     decimals: 6,
+      #     mint_authority: mint_authority.address,
+      #     freeze_authority: freeze_authority.address,
+      #     rent_sysvar_index: 2,
+      #     mint_account_index: 1,
+      #     program_index: 3
+      #   )
+      #
+      # @since 0.1.5
+      class InitializeMintInstruction
+        # Instruction index for Initialize Mint
+        INSTRUCTION_INDEX = [0].freeze
+
+        # Builds a Solace::Instruction for initializing a Token-2022 mint.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Decimals (1 byte)]
+        #   - [Mint authority (32 bytes)]
+        #   - [Freeze authority option (1 byte)]
+        #   - [Freeze authority (32 bytes)]
+        #
+        # @param decimals [Integer] Number of decimals for the token
+        # @param mint_authority [String] Public key of the mint authority
+        # @param freeze_authority [String, nil] Public key of the freeze authority
+        # @param rent_sysvar_index [Integer] Index of the rent sysvar in the transaction's accounts
+        # @param mint_account_index [Integer] Index of the mint account in the transaction's accounts
+        # @param program_index [Integer] Index of the Token-2022 Program in the transaction's accounts
+        # @return [Solace::Instruction]
+        def self.build(
+          decimals:,
+          mint_authority:,
+          rent_sysvar_index:,
+          mint_account_index:,
+          freeze_authority: nil,
+          program_index: 2
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [mint_account_index, rent_sysvar_index]
+            ix.data = data(decimals, mint_authority, freeze_authority)
+          end
+        end
+
+        # Instruction data for an initialize mint instruction.
+        #
+        # @param decimals [Integer] Number of decimals for the token
+        # @param mint_authority [String] Public key of the mint authority
+        # @param freeze_authority [String, nil] Public key of the freeze authority
+        # @return [Array<u8>] The instruction data
+        def self.data(decimals, mint_authority, freeze_authority)
+          INSTRUCTION_INDEX +
+            [decimals] +
+            Solace::Utils::Codecs.base58_to_bytes(mint_authority) +
+            (
+              if freeze_authority
+                [1] + Solace::Utils::Codecs.base58_to_bytes(freeze_authority)
+              else
+                [0]
+              end
+            )
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/mint_to_instruction.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for minting Token-2022 tokens to a token account.
+      #
+      # @example Build a MintTo instruction
+      #   instruction = Solace::Instructions::Token2022::MintToInstruction.build(
+      #     amount: 100,
+      #     mint_index: 1,
+      #     mint_authority_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class MintToInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's MintTo instruction.
+        INSTRUCTION_INDEX = [7].freeze
+
+        # Builds a MintTo instruction.
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @param mint_index [Integer] The index of the mint account.
+        # @param destination_index [Integer] The index of the token account to mint to.
+        # @param mint_authority_index [Integer] The index of the mint authority account.
+        # @param program_index [Integer] The index of the Token-2022 Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          mint_index:,
+          mint_authority_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [mint_index, destination_index, mint_authority_index]
+            ix.data = data(amount)
+          end
+        end
+
+        # Builds the data for a MintTo instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @return [Array] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/transfer_checked_instruction.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for transferring Token-2022 tokens with decimal validation.
+      #
+      # @example Build a TransferChecked instruction
+      #   instruction = Solace::Instructions::Token2022::TransferCheckedInstruction.build(
+      #     amount: 100,
+      #     decimals: 6,
+      #     to_index: 1,
+      #     from_index: 2,
+      #     mint_index: 3,
+      #     authority_index: 4,
+      #     program_index: 5
+      #   )
+      #
+      # @since 0.1.5
+      class TransferCheckedInstruction
+        # Token-2022 instruction index for Transfer Checked
+        INSTRUCTION_INDEX = [12].freeze
+
+        # Builds a Solace::Instruction for transferring Token-2022 tokens.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #   - [Decimals (1 byte)]
+        #
+        # @param amount [Integer] Amount to transfer (in tokens, according to mint's decimals)
+        # @param decimals [Integer] Number of decimals for the token
+        # @param to_index [Integer] Index of the destination token account in the transaction's accounts
+        # @param from_index [Integer] Index of the source token account in the transaction's accounts
+        # @param mint_index [Integer] Index of the mint in the transaction's accounts
+        # @param authority_index [Integer] Index of the authority (owner) in the transaction's accounts
+        # @param program_index [Integer] Index of the Token-2022 Program in the transaction's accounts
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          decimals:,
+          to_index:,
+          from_index:,
+          mint_index:,
+          authority_index:,
+          program_index: 3
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [from_index, mint_index, to_index, authority_index]
+            ix.data = data(amount, decimals)
+          end
+        end
+
+        # Instruction data for a TransferChecked instruction.
+        #
+        # @param amount [Integer] Amount to transfer
+        # @param decimals [Integer] Number of decimals for the token
+        # @return [Array] 1-byte instruction index + 8-byte amount + 1-byte decimals
+        def self.data(amount, decimals)
+          INSTRUCTION_INDEX +
+            Solace::Utils::Codecs.encode_le_u64(amount).bytes +
+            [decimals]
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/transfer_instruction.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # The Token2022 module contains instruction builders for the Token-2022 Program
+    # (formerly Token Extensions, +TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb+).
+    #
+    # Token-2022 is wire-compatible with the legacy SPL Token program for its
+    # base instructions (Transfer, TransferChecked, CloseAccount, MintTo,
+    # InitializeMint, InitializeAccount). The instruction discriminators and
+    # data layouts are identical; only the program the instruction targets
+    # differs. These builders are duplicated from the {SplToken} namespace so
+    # that each instruction is unambiguously bound to a single on-chain program.
+    #
+    # @see Solace::Instructions::SplToken
+    # @since 0.1.5
+    module Token2022
+      # Instruction for transferring tokens via the Token-2022 program.
+      #
+      # @example Build a Transfer instruction
+      #   instruction = Solace::Instructions::Token2022::TransferInstruction.build(
+      #     amount: 100,
+      #     owner_index: 1,
+      #     source_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class TransferInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's Transfer instruction.
+        INSTRUCTION_INDEX = [3].freeze
+
+        # Builds a Transfer instruction.
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @param source_index [Integer] The index of the source token account.
+        # @param destination_index [Integer] The index of the destination token account.
+        # @param owner_index [Integer] The index of the source account's owner.
+        # @param program_index [Integer] The index of the Token-2022 Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          owner_index:,
+          source_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [source_index, destination_index, owner_index]
+            ix.data = data(amount)
+          end
+        end
+
+        # Builds the data for a Transfer instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @return [Array<Integer>] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end

data/lib/solace/programs/associated_token_account.rb

@@ -37,14 +37,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,14 +84,16 @@ 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)
 
@@ -90,7 +103,8 @@ module Solace
           payer: payer,
           funder: funder,
           owner: owner,
-          mint: mint
+          mint: mint,
+          token_program_id: token_program_id
         )
 
         connection.wait_for_confirmed_signature { tx.signature }
@@ -136,19 +150,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
+          ata_address: ata_address,
+          token_program_id: token_program_id
         )
 
         TransactionComposer