solace 0.0.2 → 0.0.5

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

@@ -1,11 +1,32 @@
+# frozen_string_literal: true
+
 # lib/solace/instructions/spl_token/initialize_account_instruction.rb
 
 module Solace
   module Instructions
     module SplToken
-      # A class to build the InitializeAccount instruction for the SPL Token Program.
+      # Instruction for initializing a new token account.
+      #
+      # 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
+      # is a special "all-in-one" instruction that creates and initializes the account in a single
+      # instruction.
+      #
+      # @example Build an InitializeAccount instruction
+      #   instruction = Solace::Instructions::SplToken::InitializeAccountInstruction.build(
+      #     account_index: 0,
+      #     mint_index: 1,
+      #     owner_index: 2,
+      #     rent_sysvar_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @see Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+      # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
+      # @since 0.0.2
       class InitializeAccountInstruction
-        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SPL Token Program's InitializeAccount instruction.
         INSTRUCTION_INDEX = [1].freeze
 
@@ -43,4 +64,4 @@ module Solace
       end
     end
   end
-end
+end

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

@@ -3,6 +3,23 @@
 module Solace
   module Instructions
     module SplToken
+      # Instruction for initializing a new mint.
+      #
+      # This instruction is used to initialize a new mint for a given token. It is used in conjunction with the SystemProgram::CreateAccount
+      # instruction to create and initialize a new mint account.
+      #
+      # @example Build an InitializeMint instruction
+      #   instruction = Solace::Instructions::SplToken::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
+      #   )
+      #
+      # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
+      # @since 0.0.2
       class InitializeMintInstruction
         # Instruction index for Initialize Mint
         INSTRUCTION_INDEX = [0].freeze
@@ -49,7 +66,7 @@ module Solace
         # @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] 1-byte instruction index + 1-byte decimals + 32-byte mint authority + 1-byte freeze authority option + 32-byte freeze authority
+        # @return [Array<u8>] The instruction data
         def self.data(decimals, mint_authority, freeze_authority)
           INSTRUCTION_INDEX +
             [decimals] +

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

@@ -3,9 +3,22 @@
 module Solace
   module Instructions
     module SplToken
-      # A class to build the MintTo instruction for the SPL Token Program.
+      # Instruction for minting tokens to a token account.
+      #
+      # This instruction is used to mint tokens to a token account for a given mint and owner.
+      #
+      # @example Build a MintTo instruction
+      #   instruction = Solace::Instructions::SplToken::MintToInstruction.build(
+      #     amount: 100,
+      #     mint_index: 1,
+      #     mint_authority_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.0.2
       class MintToInstruction
-        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SPL Token Program's MintTo instruction.
         INSTRUCTION_INDEX = [7].freeze
 
@@ -45,4 +58,4 @@ module Solace
       end
     end
   end
-end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      # Instruction for transferring SPL tokens.
+      #
+      # This instruction is used to transfer SPL tokens from one token account to another while checking the decimals
+      # of the token to ensure the transfer amount is correct.
+      #
+      # @example Build a TransferChecked instruction
+      #   instruction = Solace::Instructions::SplToken::TransferCheckedInstruction.build(
+      #     amount: 100,
+      #     decimals: 6,
+      #     to_index: 1,
+      #     from_index: 2,
+      #     mint_index: 3,
+      #     authority_index: 4,
+      #     program_index: 5
+      #   )
+      #
+      # @since 0.0.2
+      class TransferCheckedInstruction
+        # SPL Token Program instruction index for Transfer Checked
+        INSTRUCTION_INDEX = [12].freeze
+
+        # Builds a Solace::Instruction for transferring SPL tokens
+        #
+        # SPL Token Program transfer instruction layout:
+        #   - 1 byte: instruction index (12 for transfer checked)
+        #   - 8 bytes: amount (u64, little-endian)
+        #   - 8 bytes: decimals (u64, little-endian)
+        #
+        # @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 SPL Token Program in the transaction's accounts (default: 3)
+        # @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 token transfer instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #   - [Decimals (8 bytes little-endian u64)]
+        #
+        # @param amount [Integer] Amount to transfer
+        # @param decimals [Integer] Number of decimals for the token
+        # @return [Array] 1-byte instruction index + 8-byte amount + 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/spl_token/transfer_instruction.rb

@@ -3,9 +3,22 @@
 module Solace
   module Instructions
     module SplToken
-      # A class to build the Transfer instruction for the SPL Token Program.
+      # Instruction for transferring SPL tokens.
+      #
+      # This instruction is used to transfer SPL tokens from one token account to another.
+      #
+      # @example Build a Transfer instruction
+      #   instruction = Solace::Instructions::SplToken::TransferInstruction.build(
+      #     amount: 100,
+      #     owner_index: 1,
+      #     source_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.0.2
       class TransferInstruction
-        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SPL Token Program's Transfer instruction.
         INSTRUCTION_INDEX = [3].freeze
 

data/lib/solace/instructions/system_program/create_account_instruction.rb

@@ -3,11 +3,25 @@
 module Solace
   module Instructions
     module SystemProgram
+      # Instruction for creating a new account.
+      #
+      # This instruction is used to create a new account for a given program.
+      #
+      # @example Build a CreateAccount instruction
+      #   instruction = Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
+      #     space: 1024,
+      #     lamports: 1000,
+      #     from_index: 0,
+      #     new_account_index: 1,
+      #     owner: owner.address,
+      #     system_program_index: 2
+      #   )
+      #
+      # @since 0.0.2
       class CreateAccountInstruction
-        # !@const INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SystemProgram::CreateAccount
         #   This is the same across all Solana clusters
-        # @return [Array<Integer>]
         INSTRUCTION_INDEX = [0, 0, 0, 0].freeze
 
         # Builds a SystemProgram::CreateAccount instruction
@@ -22,9 +36,9 @@ module Solace
         def self.build(
           space:,
           lamports:,
-          owner: Solace::Constants::SYSTEM_PROGRAM_ID,
           from_index:,
           new_account_index:,
+          owner: Solace::Constants::SYSTEM_PROGRAM_ID,
           system_program_index: 2
         )
           Solace::Instruction.new.tap do |ix|
@@ -33,6 +47,7 @@ module Solace
             ix.data = data(lamports, space, owner)
           end
         end
+        # rubocop:enable Metrics/ParameterLists
 
         # Builds the data for a SystemProgram::CreateAccount instruction
         #

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SystemProgram
+      # Instruction for transferring SOL.
+      #
+      # This instruction is used to transfer SOL from one account to another.
+      #
+      # @example Build a Transfer instruction
+      #   instruction = Solace::Instructions::SystemProgram::TransferInstruction.build(
+      #     lamports: 100,
+      #     to_index: 1,
+      #     from_index: 2,
+      #     program_index: 3
+      #   )
+      #
+      # @since 0.0.2
+      class TransferInstruction
+        # Instruction ID for System Transfer
+        INSTRUCTION_ID = [2, 0, 0, 0].freeze
+
+        # Builds a Solace::Instruction for transferring SOL
+        #
+        # @param lamports [Integer] Amount to transfer (in lamports)
+        # @param to_index [Integer] Index of the recipient in the transaction's accounts
+        # @param from_index [Integer] Index of the sender in the transaction's accounts
+        # @param program_index [Integer] Index of the program in the transaction's accounts (default: 2)
+        # @return [Solace::Instruction]
+        def self.build(
+          lamports:,
+          to_index:,
+          from_index:,
+          program_index: 2
+        )
+          Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [from_index, to_index]
+            ix.data = data(lamports)
+          end
+        end
+
+        # Instruction data for a transfer instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction ID (4 bytes)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #
+        # @param lamports [Integer] Amount to transfer (in lamports)
+        # @return [Array] 4-byte instruction ID + 8-byte amount
+        def self.data(lamports)
+          INSTRUCTION_ID +
+            Utils::Codecs.encode_le_u64(lamports).bytes
+        end
+      end
+    end
+  end
+end

data/lib/solace/keypair.rb

@@ -3,38 +3,40 @@
 require 'rbnacl'
 require 'base58'
 
-# =============================
-# Keypair
-# =============================
-#
-# Represents a Solana Ed25519 Keypair
 module Solace
+  # Class representing a Solana Ed25519 Keypair
+  #
+  # This class provides utility methods for encoding, decoding, signing, and validating keypairs.
+  #
+  # @example
+  #   # Generate a new keypair
+  #   keypair = Solace::Keypair.generate
+  #
+  #   # Get the address of the pubkey
+  #   keypair.address
+  #
+  #   # Sign a message using the keypair
+  #   keypair.sign("<any-message>")
+  #
+  # @since 0.0.1
   class Keypair
-    # !@const SECRET_LENGTH
-    #   The length of a Solana secret key in bytes
-    #
-    # @return [Integer] The length of a secret key
+    # The length of a Solana secret key in bytes.
     SECRET_LENGTH = 64
 
-    # !@const SEED_LENGTH
-    #   The length of a Solana seed in bytes (borrowed from RbNaCl)
-    #
-    # @return [Integer] The length of a seed
-    SEED_LENGTH = RbNaCl::Signatures::Ed25519::SEEDBYTES
+    # The length of a Solana seed in bytes.
+    SEED_LENGTH = 32
 
-    # !@const SigningKey
-    #   The RbNaCl signing key
+    # The full keypair bytes array
     #
-    # @return [RbNaCl::Signatures::Ed25519::SigningKey]
-    SigningKey = RbNaCl::Signatures::Ed25519::SigningKey
-
-    # !@attribute [r] keypair_bytes
-    #   @return [Array<Integer>] The keypair bytes
+    # @return [Array<u8>] The 64 bytes of the keypair
     attr_reader :keypair_bytes
 
     class << self
       # Generate a new random keypair
       #
+      # @example
+      #   keypair = Solace::Keypair.generate
+      #
       # @return [Keypair]
       def generate
         from_seed(RbNaCl::Random.random_bytes(SEED_LENGTH))
@@ -42,28 +44,40 @@ module Solace
 
       # Create a keypair from a 32-byte seed
       #
+      # @example
+      #   keypair = Solace::Keypair.from_seed(seed)
+      #
       # @param seed [String] 32-byte array
+      # @raise [ArgumentError] If the length of the seed isn't 32 bytes
       # @return [Keypair]
       def from_seed(seed)
         raise ArgumentError, 'Seed must be 32 bytes' unless seed.length == SEED_LENGTH
 
-        new(SigningKey.new(seed).keypair_bytes.bytes)
+        new(RbNaCl::Signatures::Ed25519::SigningKey.new(seed).keypair_bytes.bytes)
       end
 
       # Create a keypair from a 64-byte secret key
       #
+      # @example
+      #   keypair = Solace::Keypair.from_secret_key(secret_key)
+      #
       # @param secret_key [String] 64-byte array
+      # @raise [ArgumentError] If the length of the secret_key isn't 64 bytes
       # @return [Keypair]
       def from_secret_key(secret_key)
         raise ArgumentError, 'Secret key must be 64 bytes' unless secret_key.length == SECRET_LENGTH
 
-        new(SigningKey.new(secret_key[0..31]).keypair_bytes.bytes)
+        new(RbNaCl::Signatures::Ed25519::SigningKey.new(secret_key[0..31]).keypair_bytes.bytes)
       end
     end
 
     # Initialize a new keypair
     #
+    # @example
+    #   keypair = Solace::Keypair.new(bytes)
+    #
     # @param keypair_bytes [Array<Integer>] The keypair bytes
+    # @raise [ArgumentError] If the length of the keypair_bytes isn't 64 bytes
     # @return [Keypair] The new keypair object
     def initialize(keypair_bytes)
       raise ArgumentError, 'Keypair must be 64 bytes' unless keypair_bytes.length == SECRET_LENGTH
@@ -73,6 +87,9 @@ module Solace
 
     # Returns the public key
     #
+    # @example
+    #   pubkey = keypair.public_key
+    #
     # @return [PublicKey]
     def public_key
       @public_key ||= Solace::PublicKey.new(public_key_bytes)
@@ -80,16 +97,22 @@ module Solace
 
     # Returns the signing key
     #
+    # @example
+    #   signing_key = instance.signing_key
+    #
     # @return [RbNaCl::Signatures::Ed25519::SigningKey]
     def signing_key
-      @signing_key ||= SigningKey.new(private_key)
+      @signing_key ||= RbNaCl::Signatures::Ed25519::SigningKey.new(private_key_bytes.pack('C*'))
     end
 
     # Returns the public key bytes
     #
     # The public key bytes are the last 32 bytes of the keypair
     #
-    # @return [String] 32 bytes
+    # @example
+    #   public_key_bytes = instance.public_key_bytes
+    #
+    # @return [Array<u8>] 32 bytes
     def public_key_bytes
       keypair_bytes[32..63]
     end
@@ -98,12 +121,18 @@ module Solace
     #
     # The private key is the first 32 bytes of the keypair
     #
-    # @return [String] 32 characters
-    def private_key
-      keypair_bytes[0..31].pack('C*')
+    # @example
+    #   private_key_bytes = instance.private_key_bytes
+    #
+    # @return [Array<u8>] 32 characters
+    def private_key_bytes
+      keypair_bytes[0..31]
     end
 
-    # Returns the public key as a Base58 string
+    # Returns the public key address as a Base58 string
+    #
+    # @example
+    #   pubkey_str = instance.address
     #
     # @return [String] Base58 encoded public key
     def address
@@ -112,8 +141,12 @@ module Solace
 
     # Signs a message (string or binary)
     #
-    # @param message [String | Binary]
-    # @return [Binary] signature (binary)
+    # @example
+    #   message = "An important message to be signed,"
+    #   signature = instance.sign(message)
+    #
+    # @param message [String, Binary]
+    # @return [String] signature (binary string)
     def sign(message)
       signing_key.sign(message)
     end

data/lib/solace/message.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
-# =============================
-# Message
-# =============================
-#
-# Represents the message portion of a Solana transaction (legacy or versioned).
-# Handles serialization and deserialization of message fields.
 module Solace
-  class Message < Solace::SerializableRecord
-    # @!const SERIALIZER
+  # Solace::Message represents the message portion of a Solana transaction (legacy or versioned). It handles
+  # serialization and deserialization of message fields.
+  #
+  # @example
+  #   message = Solace::Message.new(
+  #     version: 0,
+  #     header: [0, 0, 0],
+  #     accounts: ['11111111111111111111111111111111'],
+  #     recent_blockhash: '11111111111111111111111111111111',
+  #     instructions: [],
+  #     address_lookup_tables: []
+  #   )
+  #
+  # @since 0.0.1
+  class Message
+    include Solace::Concerns::BinarySerializable
+
+    # @!attribute SERIALIZER
     #   @return [Solace::Serializers::MessageSerializer] The serializer for the message
     SERIALIZER = Solace::Serializers::MessageSerializer
 
-    # @!const DESERIALIZER
+    # @!attribute DESERIALIZER
     #   @return [Solace::Serializers::MessageDeserializer] The deserializer for the message
     DESERIALIZER = Solace::Serializers::MessageDeserializer
 
@@ -46,7 +56,7 @@ module Solace
     # @param accounts [Array<String>] Account public keys (base58)
     # @param instructions [Array<Solace::Instruction>] Instructions in the message
     # @param recent_blockhash [String] Recent blockhash (base58)
-    # @param header [Array<Integer>] Message header [num_required_signatures, num_readonly_signed, num_readonly_unsigned]
+    # @param header [Array<Integer>] Message header
     # @param address_lookup_tables [Array<Solace::AddressLookupTable>]
     def initialize(
       version: nil,
@@ -56,6 +66,8 @@ module Solace
       header: [0, 0, 0],
       address_lookup_tables: []
     )
+      super()
+
       @version = version
       @header = header
       @accounts = accounts

data/lib/solace/programs/associated_token_account.rb

@@ -2,13 +2,33 @@
 
 module Solace
   module Programs
-    # A client for interacting with the SPL Token Program.
+    # Client for interacting with the Associated Token Account Program.
+    #
+    # This client provides methods for interacting with the Associated Token Account Program. It is a
+    # wrapper around the SPL Token Program and provides a more convenient interface for creating and
+    # managing associated token accounts.
+    #
+    # @example Create an associated token account
+    #   # Initialize the program with a connection
+    #   program = Solace::Programs::AssociatedTokenAccount.new(connection: connection)
+    #
+    #   # Create an associated token account
+    #   result = program.create_associated_token_account(
+    #     payer: payer,
+    #     owner: owner,
+    #     mint: mint
+    #   )
+    #
+    #   # Wait for the transaction to be finalized
+    #   @connection.wait_for_confirmed_signature('finalized') { result['result'] }
+    #
+    # @since 0.0.2
     class AssociatedTokenAccount < Base
       class << self
         # Gets the address of an associated token account.
         #
-        # @param owner [Solace::Keypair || Solace::PublicKey] The keypair of the owner.
-        # @param mint [Solace::Keypair || Solace::PublicKey] The keypair of the mint.
+        # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
+        # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
         # @return [String] The address of the associated token account.
         def get_address(owner:, mint:)
           Solace::Utils::PDA.find_program_address(
@@ -26,16 +46,40 @@ module Solace
       #
       # @param connection [Solace::Connection] The connection to the Solana cluster.
       def initialize(connection:)
-        super(connection:, program_id: Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID)
+        super(connection: connection, program_id: Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID)
       end
 
       # Alias method for get_address
-      # 
-      # @param oprtions [Hash] A hash of options for the get_address class method
+      #
+      # @option options [Hash] A hash of options for the get_address class method
+      # @return [Array<String, Integer>] The address of the associated token account and the bump seed
       def get_address(**options)
         self.class.get_address(**options)
       end
 
+      # Gets the address of an associated token account, creating it if it doesn't exist.
+      #
+      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
+      # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
+      # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
+      # @param commitment [String] The commitment level for the get_account_info call.
+      # @return [String] The address of the associated token account
+      def get_or_create_address(payer:, owner:, mint:, commitment: 'confirmed')
+        ata_address, _bump = get_address(owner: owner, mint: mint)
+
+        account_info = @connection.get_account_info(ata_address)
+
+        return ata_address if account_info
+
+        response = create_associated_token_account(payer: payer, owner: owner, mint: mint)
+
+        raise 'Failed to create associated token account' unless response['result']
+
+        @connection.wait_for_confirmed_signature(commitment) { response['result'] }
+
+        ata_address
+      end
+
       # Creates a new associated token account.
       #
       # @param options [Hash] Options for calling the prepare_create_associated_token_account method.
@@ -48,16 +92,18 @@ module Solace
 
       # Prepares a new associated token account and returns the signed transaction.
       #
-      # @param owner [Solace::Keypair || Solace::PublicKey] The keypair of the owner.
-      # @param mint [Solace::Keypair || Solace::PublicKey] The keypair of the mint.
+      # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
+      # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
       # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
       # @return [Solace::Transaction] The signed transaction.
+      #
+      # rubocop:disable Metrics/MethodLength
       def prepare_create_associated_token_account(
+        payer:,
         owner:,
-        mint:,
-        payer:
+        mint:
       )
-        ata_address, _ = get_address(owner:, mint:)
+        ata_address, = get_address(owner: owner, mint: mint)
 
         accounts = [
           payer.address,
@@ -91,6 +137,7 @@ module Solace
 
         tx
       end
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/solace/programs/base.rb

@@ -5,7 +5,13 @@
 module Solace
   module Programs
     # Base class for program-specific clients.
+    #
     # Provides a consistent interface for interacting with on-chain programs.
+    #
+    # @abstract
+    # @see Solace::Programs::SplToken
+    # @see Solace::Programs::AssociatedTokenAccount
+    # @since 0.0.2
     class Base
       attr_reader :connection, :program_id