solace 0.0.3 → 0.0.6

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

@@ -3,7 +3,23 @@
 module Solace
   module Instructions
     module SplToken
-      # Service object for building an SPL Token Program transfer instruction
+      # 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

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

@@ -3,17 +3,25 @@
 module Solace
   module Instructions
     module SystemProgram
-      # Service object for building a System Program transfer instruction
-      class TransferInstruction < Base
+      # 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
         #
-        # System Program transfer instruction layout:
-        #   - 4 bytes: instruction index (0 for transfer)
-        #   - 8 bytes: amount (u64, little-endian)
-        #
         # @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
@@ -47,4 +55,4 @@ module Solace
       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,35 +46,37 @@ 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 (required if account needs to be created).
-      # @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.
+      # @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, _ = get_address(owner:, mint:)
-        
+        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:, owner:, mint:)
+        response = create_associated_token_account(payer: payer, owner: owner, mint: mint)
 
-        raise "Failed to create associated token account" unless response['result']
+        raise 'Failed to create associated token account' unless response['result']
 
         @connection.wait_for_confirmed_signature(commitment) { response['result'] }
-        
+
         ata_address
       end
 
@@ -70,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:, 
+        payer:,
+        owner:,
         mint:
       )
-        ata_address, _ = get_address(owner:, mint:)
+        ata_address, = get_address(owner: owner, mint: mint)
 
         accounts = [
           payer.address,
@@ -113,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
 

data/lib/solace/programs/spl_token.rb

@@ -2,7 +2,31 @@
 
 module Solace
   module Programs
-    # A client for interacting with the SPL Token Program.
+    # Client for interacting with the 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.
+    #
+    # @example Create an SPL Token mint
+    #   # Initialize the program with a connection
+    #   program = Solace::Programs::SplToken.new(connection: connection)
+    #
+    #   # Create an SPL Token mint
+    #   result = program.create_mint(
+    #     payer: payer,
+    #     decimals: 6,
+    #     mint_keypair: mint_keypair,
+    #     mint_authority: mint_authority,
+    #     freeze_authority: freeze_authority
+    #   )
+    #
+    #   # Wait for the transaction to be finalized
+    #   @connection.wait_for_confirmed_signature('finalized') { result['result'] }
+    #
+    # @since 0.0.2
+    #
+    # rubocop:disable Metrics/ClassLength
     class SplToken < Base
       # Initializes a new SPL Token client.
       #
@@ -29,6 +53,8 @@ module Solace
       # @param freeze_authority [String] (Optional) The base58 public key for the freeze authority.
       # @param mint_keypair [Solace::Keypair] (Optional) The keypair for the new mint.
       # @return [Solace::Transaction] The signed transaction.
+      #
+      # rubocop:disable Metrics/MethodLength
       def prepare_create_mint(
         payer:,
         decimals:,
@@ -78,6 +104,7 @@ module Solace
 
         tx
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Mint tokens to a token account
       #
@@ -91,10 +118,16 @@ module Solace
 
       # Prepares a mint to instruction and returns the signed transaction.
       #
-      # @param options [Hash] Options for calling the prepare_mint_to method.
+      # @param [Integer] amount The amount of tokens to mint.
+      # @param [PublicKey, Keypair, String] payer The payer of the transaction.
+      # @param [PublicKey, Keypair, String] mint The mint of the token.
+      # @param [PublicKey, Keypair, String] destination The destination of the token.
+      # @param [PublicKey, Keypair, String] mint_authority The mint authority of the token.
       # @return [Solace::Transaction] The signed transaction.
+      #
+      # rubocop:disable Metrics/MethodLength
       def prepare_mint_to(
-        payer:, 
+        payer:,
         mint:,
         destination:,
         amount:,
@@ -105,11 +138,11 @@ module Solace
           mint_authority.address,
           mint.address,
           destination,
-          Solace::Constants::TOKEN_PROGRAM_ID,
+          Solace::Constants::TOKEN_PROGRAM_ID
         ]
 
         ix = Solace::Instructions::SplToken::MintToInstruction.build(
-          amount:,
+          amount: amount,
           mint_authority_index: 1,
           mint_index: 2,
           destination_index: 3,
@@ -118,9 +151,9 @@ module Solace
 
         message = Solace::Message.new(
           header: [2, 0, 1],
-          accounts:,
+          accounts: accounts,
           instructions: [ix],
-          recent_blockhash: connection.get_latest_blockhash,
+          recent_blockhash: connection.get_latest_blockhash
         )
 
         tx = Solace::Transaction.new(message: message)
@@ -128,6 +161,7 @@ module Solace
 
         tx
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Transfers tokens from one account to another
       #
@@ -147,11 +181,13 @@ module Solace
       # @param amount [Integer] The number of tokens to transfer.
       # @param owner [Solace::Keypair] The keypair of the owner of the source account.
       # @return [Solace::Transaction] The signed transaction.
+      #
+      # rubocop:disable Metrics/MethodLength
       def prepare_transfer(
-        amount:, 
-        payer:, 
-        source:, 
-        destination:, 
+        amount:,
+        payer:,
+        source:,
+        destination:,
         owner:
       )
         accounts = [
@@ -163,7 +199,7 @@ module Solace
         ]
 
         ix = Solace::Instructions::SplToken::TransferInstruction.build(
-          amount:,
+          amount: amount,
           owner_index: 1,
           source_index: 2,
           destination_index: 3,
@@ -172,16 +208,18 @@ module Solace
 
         message = Solace::Message.new(
           header: [2, 0, 1],
-          accounts:,
+          accounts: accounts,
           instructions: [ix],
           recent_blockhash: connection.get_latest_blockhash
         )
 
-        tx = Solace::Transaction.new(message:)
+        tx = Solace::Transaction.new(message: message)
         tx.sign(payer, owner)
 
         tx
       end
+      # rubocop:enable Metrics/MethodLength
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end