solace 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9bca105aef6d20a1a5b6d5dc6b2fce8c7a8523c9a2a24afd3ad15bf36efbb55
-  data.tar.gz: e6a70370368a4822249bf7c912f70f54a02ce5389ef128e40acdc769b315ebae
+  metadata.gz: 4c4e4949dfaad369b5fbe6db182896b73fce66456fa04b480a394753bd76f3d8
+  data.tar.gz: e0fc2a7292a0ef3688555b419a534b7d8aa64fae214cc5f0317aebcd2af767e1
 SHA512:
-  metadata.gz: 44fc38f19753ed736c05e1ba58bc7799fbe96d736553e3df220cfa38cae60a0dc2d2ecb3459990300efc108d56b9ec0ae8ce4fc552c39b31cf668e54878f52bd
-  data.tar.gz: 4ffe860837dc85e925f308fdff68129ba01cdc41fb192495af4926bbd91328c62847f862c2847a819c9615cd1b223d512910a421713ee64f9b038bee25def482
+  metadata.gz: a1653573d2cabf8c0253157a03b7bb5ebfadedf0eeeb6dea1eefa89c0b79aa01250637bab175f0d91e3072bcf7fd18a43b082d40851cb9b5d5bc7759971d54fe
+  data.tar.gz: 718ea842339b67b89b99f9c1a674148b510e3ed6bdd4921a9fa574cd83525452e8ff7e17d8138a97821d9885cdb54a8b09037b3826666c7db59328bdfc25f67c

data/CHANGELOG

@@ -18,10 +18,29 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 ### Fixed
 ```
 
-Got it — here’s your changelog tidied up for clarity and consistency without changing any of the substance. I only fixed grammar/typos and tightened phrasing.
+---
+
+## 0.1.3 - 2025-06-11
+
+### Added
+
+1. Added `Solace::Instructions::AssociatedTokenAccount::CreateIdempotentAccountInstruction`
+2. Added `Solace::Composers::AssociatedTokenAccountCreateIdempotentAccountComposer`
+
+### Changed
+
+1. Renamed `Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction` to `Solace::Instructions::AssociatedTokenAccount::CreateAccountInstruction` with backwards compatibility
 
 ---
 
+## [0.1.2] - 2025-05-11
+
+### Added
+
+1. Added support for closing SPL token accounts with:
+  - `Solace::Composers::SystemProgramCreateAccountComposer`
+  - `Solace::Instructions::SystemProgram::CreateAccountInstruction`
+
 ## [0.1.1] - 2025-05-11
 
 ### Added

data/lib/solace/composers/associated_token_account_program_create_account_composer.rb

@@ -6,7 +6,7 @@ module Solace
     #
     # This composer resolves and orders the required accounts for a `CreateAssociatedTokenAccount` instruction,
     # sets up their access permissions, and delegates construction to the appropriate
-    # instruction builder (`Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction`).
+    # instruction builder (`Instructions::AssociatedTokenAccount::CreateAccountInstruction`).
     #
     # Required accounts:
     # - **Funder**: the account that will pay for fees and rent.
@@ -25,7 +25,7 @@ module Solace
     #     mint: mint_address
     #   )
     #
-    # @see Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+    # @see Instructions::AssociatedTokenAccount::CreateAccountInstruction
     # @since 0.0.7
     class AssociatedTokenAccountProgramCreateAccountComposer < Base
       # Extracts the owner address from the params
@@ -96,7 +96,7 @@ module Solace
       # @param account_context [Utils::AccountContext] The account context
       # @return [Solace::Instruction] The instruction
       def build_instruction(account_context)
-        Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction.build(
+        Instructions::AssociatedTokenAccount::CreateAccountInstruction.build(
           funder_index: account_context.index_of(funder),
           owner_index: account_context.index_of(owner),
           mint_index: account_context.index_of(mint),

data/lib/solace/composers/associated_token_account_program_create_idempotent_account_composer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating an associated token account program create account instruction with idempotency
+    #
+    # This composer resolves and orders the required accounts for a `CreateIdempotentAssociatedTokenAccount` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::AssociatedTokenAccount::CreateIdempotentAssociatedTokenAccountInstruction`).
+    #
+    # Required accounts:
+    # - **Funder**: the account that will pay for fees and rent.
+    # - **Owner**: the account that will own the new ATA.
+    # - **ATA**: the address of the new ATA.
+    # - **Mint**: the mint address of the token.
+    # - **System Program**: the system program id.
+    # - **Token Program**: the token program id.
+    # - **Associated Token Account Program**: the associated token account program id.
+    #
+    # @example Compose and build a create account instruction
+    #   composer = AssociatedTokenAccountProgramCreateAccountComposer.new(
+    #     funder: funder_address,
+    #     owner: owner_address,
+    #     ata_address: ata_address,
+    #     mint: mint_address
+    #   )
+    #
+    # @see Instructions::AssociatedTokenAccount::CreateAccountInstruction
+    # @since 0.1.3
+    #
+    # rubocop:disable Layout
+    class AssociatedTokenAccountProgramCreateIdempotentAccountComposer < AssociatedTokenAccountProgramCreateAccountComposer
+      # Builds the instruction for the associated token account program create account instruction
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction] The instruction
+      def build_instruction(account_context)
+        Instructions::AssociatedTokenAccount::CreateIdempotentAccountInstruction.build(
+          funder_index: account_context.index_of(funder),
+          owner_index: account_context.index_of(owner),
+          mint_index: account_context.index_of(mint),
+          associated_token_account_index: account_context.index_of(ata_address),
+          system_program_index: account_context.index_of(system_program_id),
+          token_program_index: account_context.index_of(token_program_id),
+          program_index: account_context.index_of(associated_token_account_program_id)
+        )
+      end
+    end
+    # rubocop:enable Layout
+  end
+end

data/lib/solace/composers/spl_token_program_close_account_composer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a SPL Token Program CloseAccount instruction.
+    #
+    # This composer resolves and orders the required accounts for a `CloseAccount` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder.
+    #
+    # The CloseAccount instruction closes a token account and transfers remaining lamports
+    # to a destination account. The account must have a balance of zero tokens.
+    #
+    # Required accounts:
+    # - **Account**: token account to close (writable, non-signer)
+    # - **Destination**: account to receive lamports (writable, non-signer)
+    # - **Authority**: account authority (non-writable, signer)
+    #
+    # @example Compose and build a close account instruction
+    #   composer = SplTokenProgramCloseAccountComposer.new(
+    #     account: token_account_address,
+    #     destination: destination_address,
+    #     authority: authority_address
+    #   )
+    #
+    # @since 0.1.2
+    class SplTokenProgramCloseAccountComposer < Base
+      # Extracts the token account address from the params
+      #
+      # @return [String] The token account address
+      def account
+        params[:account].to_s
+      end
+
+      # Extracts the destination address from the params
+      #
+      # @return [String] The destination address
+      def destination
+        params[:destination].to_s
+      end
+
+      # Extracts the authority address from the params
+      #
+      # @return [String] The authority address
+      def authority
+        params[:authority].to_s
+      end
+
+      # Returns the spl token program id
+      #
+      # @return [String] The spl token program id
+      def spl_token_program
+        Constants::TOKEN_PROGRAM_ID.to_s
+      end
+
+      # Setup accounts required for close account instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_nonsigner(account)
+        account_context.add_writable_nonsigner(destination)
+        account_context.add_readonly_signer(authority)
+        account_context.add_readonly_nonsigner(spl_token_program)
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Instructions::SplToken::CloseAccountInstruction.build(
+          account_index: account_context.index_of(account),
+          authority_index: account_context.index_of(authority),
+          destination_index: account_context.index_of(destination),
+          program_index: account_context.index_of(spl_token_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/instructions/associated_token_account/{create_associated_token_account_instruction.rb → create_account_instruction.rb}

@@ -2,7 +2,7 @@
 
 module Solace
   module Instructions
-    # The AssociatedTokenAccount module contains instruction builders for the
+    # The Account module contains instruction builders for the
     # Associated Token Account Program.
     #
     # The Associated Token Account (ATA) Program provides a deterministic way to
@@ -17,8 +17,8 @@ module Solace
       # This is a special "all-in-one" instruction that creates and initializes the account. It
       # is used to create an Associated Token Account (ATA) for a given mint and owner.
       #
-      # @example Build a CreateAssociatedTokenAccount instruction
-      #   instruction = Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction.build(
+      # @example Build a CreateAccount instruction
+      #   instruction = Solace::Instructions::AssociatedTokenAccount::CreateAccountInstruction.build(
       #     funder_index: 0,
       #     associated_token_account_index: 1,
       #     owner_index: 2,
@@ -27,14 +27,14 @@ module Solace
       #     token_program_index: 5,
       #     program_index: 6
       #   )
-      class CreateAssociatedTokenAccountInstruction
+      class CreateAccountInstruction
         # !@const INSTRUCTION_INDEX
-        #   Instruction index for CreateAssociatedTokenAccount
+        #   Instruction index for CreateAccount
         #
         # @return [Array<Integer>]
         INSTRUCTION_INDEX = [0].freeze
 
-        # Builds a CreateAssociatedTokenAccount instruction.
+        # Builds a CreateAccount instruction.
         #
         # The on-chain program requires accounts in a specific order:
         # 1. [writable, signer] Funder: The account paying for the rent.
@@ -75,7 +75,7 @@ module Solace
           end
         end
 
-        # Data for a CreateAssociatedTokenAccount instruction
+        # Data for a CreateAccount instruction
         #
         # The BufferLayout is:
         #   - [Instruction Index (1 byte)]
@@ -85,6 +85,9 @@ module Solace
           INSTRUCTION_INDEX
         end
       end
+
+      # Alias for CreateAccountInstruction for backward compatibility
+      CreateAssociatedTokenAccountInstruction = CreateAccountInstruction
     end
   end
 end

data/lib/solace/instructions/associated_token_account/create_idempotent_account_instruction.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # The AssociatedTokenAccount module contains instruction builders for the
+    # Associated Token Account Program.
+    #
+    # The Associated Token Account (ATA) Program provides a deterministic way to
+    # derive token account addresses for a given wallet and mint. This ensures that
+    # each wallet has a single, predictable token account for each token type.
+    #
+    # @see https://spl.solana.com/associated-token-account
+    # @since 0.1.3
+    module AssociatedTokenAccount
+      # Instruction for creating an Associated Token Account idempotently.
+      #
+      # This instruction behaves like `CreateAccountInstruction`, but will not fail
+      # if the account already exists. This is useful for scenarios where the existence of the
+      # account is uncertain, and you want to ensure it exists without causing an error.
+      #
+      # @example Build a CreateIdempotentAccount instruction
+      #   instruction = Solace::Instructions::AssociatedTokenAccount::CreateIdempotentAccountInstruction.build(
+      #     funder_index: 0,
+      #     associated_token_account_index: 1,
+      #     owner_index: 2,
+      #     mint_index: 3,
+      #     system_program_index: 4,
+      #     token_program_index: 5,
+      #     program_index: 6
+      #   )
+      #
+      # @see CreateAccountInstruction
+      class CreateIdempotentAccountInstruction < CreateAccountInstruction
+        # !@const INSTRUCTION_INDEX
+        #   Instruction index for CreateIdempotentAccount
+        #
+        # @return [Array<Integer>]
+        INSTRUCTION_INDEX = [1].freeze
+
+        # Data for a CreateAccount 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/spl_token/close_account_instruction.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      # Instruction builder for SPL Token Program CloseAccount.
+      #
+      # The CloseAccount instruction closes a 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.2
+      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 SPL Token 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/spl_token/initialize_account_instruction.rb

@@ -9,7 +9,7 @@ module Solace
       #
       # This instruction is used to initialize a new token account for a given mint and owner. It
       # is used in conjunction with the CreateAccount instruction to create and initialize a new
-      # token account. Note that the AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+      # token account. Note that the AssociatedTokenAccount::CreateAccountInstruction
       # is a special "all-in-one" instruction that creates and initializes the account in a single
       # instruction.
       #
@@ -22,7 +22,7 @@ module Solace
       #     program_index: 4
       #   )
       #
-      # @see Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+      # @see Solace::Instructions::AssociatedTokenAccount::CreateAccountInstruction
       # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
       # @since 0.0.2
       class InitializeAccountInstruction

data/lib/solace/version.rb

@@ -2,6 +2,5 @@
 
 module Solace
   # Latest version of the Solace gem.
-  # @since 0.1.1
-  VERSION = '0.1.1'
+  VERSION = '0.1.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -108,7 +108,9 @@ files:
 - lib/solace.rb
 - lib/solace/address_lookup_table.rb
 - lib/solace/composers/associated_token_account_program_create_account_composer.rb
+- lib/solace/composers/associated_token_account_program_create_idempotent_account_composer.rb
 - lib/solace/composers/base.rb
+- lib/solace/composers/spl_token_program_close_account_composer.rb
 - lib/solace/composers/spl_token_program_initialize_mint_composer.rb
 - lib/solace/composers/spl_token_program_mint_to_composer.rb
 - lib/solace/composers/spl_token_program_transfer_checked_composer.rb
@@ -124,7 +126,9 @@ files:
 - lib/solace/errors/parse_error.rb
 - lib/solace/errors/rpc_error.rb
 - lib/solace/instruction.rb
-- lib/solace/instructions/associated_token_account/create_associated_token_account_instruction.rb
+- lib/solace/instructions/associated_token_account/create_account_instruction.rb
+- lib/solace/instructions/associated_token_account/create_idempotent_account_instruction.rb
+- lib/solace/instructions/spl_token/close_account_instruction.rb
 - lib/solace/instructions/spl_token/initialize_account_instruction.rb
 - lib/solace/instructions/spl_token/initialize_mint_instruction.rb
 - lib/solace/instructions/spl_token/mint_to_instruction.rb