solace 0.0.3 → 0.0.5

data/lib/solace/public_key.rb

@@ -1,40 +1,43 @@
 # frozen_string_literal: true
 
-# =============================
-# PublicKey
-# =============================
-#
-# Represents a Solana Ed25519 Public Key
-# Provides utility methods for encoding, decoding, and validation
 module Solace
+  # Class representing a Solana Ed25519 Public Key
+  #
+  # This class provides utility methods for encoding, decoding, and validating public keys.
+  #
+  # @example
+  #   # Initialize a public key from a 32-byte array
+  #   pubkey = Solace::PublicKey.new(public_key_bytes)
+  #
+  #   # Get the address representation of the public key
+  #   pubkey.to_base58
+  #   pubkey.address
+  #
+  # @since 0.0.1
   class PublicKey
     include Solace::Utils::PDA
 
-    # !@const LENGTH
-    #   The length of a Solana public key in bytes
-    #
-    # @return [Integer] The length of a public key
+    # The length of a Solana public key in bytes
     LENGTH = 32
 
-    # !@const MAX_BUMP_SEED
-    #   The maximum seed value for a Program Derived Address
-    #
-    # @return [Integer] The maximum seed value
+    # The maximum seed value for a Program Derived Address
     MAX_BUMP_SEED = 255
 
-    # !@const PDA_MARKER
-    #   The marker for a Program Derived Address
-    #
-    # @return [String] The marker for a PDA
+    # The marker for a Program Derived Address
     PDA_MARKER = 'ProgramDerivedAddress'
 
-    # !@attribute bytes
-    #   @return [Array<Integer>] The bytes of the public key
+    # The bytes of the public key
+    #
+    # @return [Array<u8>] The bytes of the public key
     attr_reader :bytes
 
     # Initialize with a 32-byte array or string
     #
+    # @example
+    #   pubkey = Solace::PubKey.new(bytes)
+    #
     # @param bytes [String, Array<Integer>] 32-byte array or string
+    # @raise [ArgumentError] If the public key bytes length isn't 32 long
     # @return [PublicKey]
     def initialize(bytes)
       raise ArgumentError, "Public key must be #{LENGTH} bytes" unless bytes.length == LENGTH
@@ -44,6 +47,9 @@ module Solace
 
     # Return the base58 representation of the public key
     #
+    # @example
+    #   pubkey_str = instance.to_base58
+    #
     # @return [String]
     def to_base58
       Solace::Utils::Codecs.bytes_to_base58(@bytes)
@@ -51,13 +57,29 @@ module Solace
 
     # String representation (base58)
     #
+    # @example
+    #   pubkey_str = instance.to_s
+    #
     # @return [String]
     def to_s
       to_base58
     end
 
+    # Return the address of the public key
+    #
+    # @example
+    #   pubkey_str = instance.address
+    #
+    # @return [String]
+    def address
+      to_base58
+    end
+
     # Compare two public keys for equality
     #
+    # @example
+    #   pubkey1 == pubkey2
+    #
     # @param other [PublicKey]
     # @return [Boolean]
     def ==(other)
@@ -66,6 +88,9 @@ module Solace
 
     # Return the public key as a byte array
     #
+    # @example
+    #   pubkey_bytes = instance.to_bytes
+    #
     # @return [Array<Integer>]
     def to_bytes
       @bytes.dup

data/lib/solace/serializers/address_lookup_table_deserializer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# =============================
-# Address Lookup Table Deserializer
-# =============================
-#
-# Deserializes a Solana address lookup table from a binary format.
 module Solace
   module Serializers
+    # Deserializes a Solana address lookup table from a binary format.
+    #
+    # @since 0.0.2
     class AddressLookupTableDeserializer < Solace::Serializers::BaseDeserializer
       # @!attribute record_class
       #   The class of the record being deserialized

data/lib/solace/serializers/address_lookup_table_serializer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# =============================
-# Address Lookup Table Serializer
-# =============================
-#
-# Serializes a Solana address lookup table to a binary format.
 module Solace
   module Serializers
+    # Serializes a Solana address lookup table to a binary format.
+    #
+    # @since 0.0.2
     class AddressLookupTableSerializer < Solace::Serializers::BaseSerializer
       # @!attribute steps
       #   An ordered list of methods to serialize the address lookup table
@@ -36,7 +34,8 @@ module Solace
       #
       # @return [Array<Integer>] The bytes of the encoded writable indexes
       def encode_writable_indexes
-        Codecs.encode_compact_u16(record.writable_indexes.size).bytes + record.writable_indexes
+        Codecs.encode_compact_u16(record.writable_indexes.size).bytes +
+          record.writable_indexes
       end
 
       # Encodes the readonly indexes of the address lookup table
@@ -47,7 +46,8 @@ module Solace
       #
       # @return [Array<Integer>] The bytes of the encoded readonly indexes
       def encode_readonly_indexes
-        Codecs.encode_compact_u16(record.readonly_indexes.size).bytes + record.readonly_indexes
+        Codecs.encode_compact_u16(record.readonly_indexes.size).bytes +
+          record.readonly_indexes
       end
     end
   end

data/lib/solace/serializers/base_deserializer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Solace
+  # Serializers module
   module Serializers
     # Autoload deserializers
     autoload :TransactionDeserializer, 'solace/serializers/transaction_deserializer'
@@ -8,38 +9,33 @@ module Solace
     autoload :InstructionDeserializer, 'solace/serializers/instruction_deserializer'
     autoload :AddressLookupTableDeserializer, 'solace/serializers/address_lookup_table_deserializer'
 
-    # Base deserializer class
-    class BaseDeserializer < Serializers::Base
-      class << self
-        # @!attribute STEPS
-        #   An ordered list of methods to deserialize the record
-        #
-        # @return [Array] The steps to deserialize the record
-        attr_accessor :steps
-
-        # @!attribute RECORD_CLASS
-        #   The class of the record being deserialized
-        #
-        # @return [Class] The class of the record
-        attr_accessor :record_class
-      end
+    # The base deserializer class
+    #
+    # This class provides a consistent interface for deserializing records.
+    #
+    # @abstract
+    # @since 0.0.1
+    class BaseDeserializer
+      include Solace::Utils
 
       # @!attribute io
       #   The input to read bytes from.
       #
-      # @return [IO or StringIO] The input to read bytes from.
-      #
+      # @return [IO, StringIO] The input to read bytes from.
+      attr_reader :io
+
       # @!attribute record
       #   The record instance being deserialized.
       #
       # @return [Record] The deserialized record.
-      attr_reader :io, :record
+      attr_reader :record
 
       # Initialize a new deserializer
       #
-      # @param io [IO or StringIO] The input to read bytes from.
+      # @param io [IO, StringIO] The input to read bytes from.
       # @return [BaseDeserializer] The new deserializer object
       def initialize(io)
+        super()
         @io = io
         @record = self.class.record_class.new
       end
@@ -51,6 +47,20 @@ module Solace
         self.class.steps.each { send(_1) }
         record
       end
+
+      class << self
+        # @!attribute steps
+        #   An ordered list of methods to deserialize the record
+        #
+        # @return [Array] The steps to deserialize the record
+        attr_accessor :steps
+
+        # @!attribute record_class
+        #   The class of the record being deserialized
+        #
+        # @return [Class] The class of the record
+        attr_accessor :record_class
+      end
     end
   end
 end

data/lib/solace/serializers/base_serializer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Solace
+  # Serializers module
   module Serializers
     # Autoload serializers
     autoload :TransactionSerializer, 'solace/serializers/transaction_serializer'
@@ -8,15 +9,14 @@ module Solace
     autoload :InstructionSerializer, 'solace/serializers/instruction_serializer'
     autoload :AddressLookupTableSerializer, 'solace/serializers/address_lookup_table_serializer'
 
-    # Base serializer class
-    class BaseSerializer < Serializers::Base
-      class << self
-        # @!attribute STEPS
-        #   An ordered list of methods to deserialize the record
-        #
-        # @return [Array] The steps to deserialize the record
-        attr_accessor :steps
-      end
+    # The base serializer class
+    #
+    # This class provides a consistent interface for serializing records.
+    #
+    # @abstract
+    # @since 0.0.1
+    class BaseSerializer
+      include Solace::Utils
 
       # @!attribute record
       #   The record instance being serialized.
@@ -29,6 +29,7 @@ module Solace
       # @param record [Record] The record to serialize
       # @return [BaseSerializer] The new serializer object
       def initialize(record)
+        super()
         @record = record
       end
 
@@ -47,6 +48,14 @@ module Solace
       rescue NameError => e
         raise "STEPS must be defined: #{e.message}"
       end
+
+      class << self
+        # @!attribute steps
+        #   An ordered list of methods to serialize the record
+        #
+        # @return [Array] The steps to serialize the record
+        attr_accessor :steps
+      end
     end
   end
 end

data/lib/solace/serializers/instruction_deserializer.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-# =============================
-# Instruction Deserializer
-# =============================
-#
-# Deserializes a binary instruction into a Solace::Instruction object.
 module Solace
   module Serializers
+    # Deserializes a binary instruction into a Solace::Instruction object.
+    #
+    # @since 0.0.1
     class InstructionDeserializer < Solace::Serializers::BaseDeserializer
-      # @!attribute record_class
+      # @!attribute  record_class
       #   The class of the record being deserialized
       #
       # @return [Class] The class of the record
       self.record_class = Solace::Instruction
 
-      # @!attribute steps
+      # @!attribute  steps
       #   An ordered list of methods to deserialize the instruction
       #
       # @return [Array] The steps to deserialize the instruction

data/lib/solace/serializers/instruction_serializer.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
-# =============================
-# Instruction Serializer
-# =============================
-#
-# Serializes a Solana instruction to a binary format.
 module Solace
   module Serializers
+    # Serializes a Solana instruction to a binary format.
+    #
+    # @since 0.0.1
     class InstructionSerializer < Solace::Serializers::BaseSerializer
-      # @!attribute steps
+      # @!attribute  steps
       #   An ordered list of methods to serialize the instruction
       #
       # @return [Array] The steps to serialize the instruction

data/lib/solace/serializers/message_deserializer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# =============================
-# Message Deserializer
-# =============================
-#
-# Deserializes a binary message into a Solace::Message object.
 module Solace
   module Serializers
+    # Deserializes a binary message into a Solace::Message object.
+    #
+    # @since 0.0.1
     class MessageDeserializer < Solace::Serializers::BaseDeserializer
       # @!attribute record_class
       #   The class of the record being deserialized

data/lib/solace/serializers/message_serializer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# =============================
-# Message Serializer
-# =============================
-#
-# Serializes a Solana message to a binary format.
 module Solace
   module Serializers
+    # Serializes a Solana message to a binary format.
+    #
+    # @since 0.0.1
     class MessageSerializer < Solace::Serializers::BaseSerializer
       # @!attribute steps
       #   An ordered list of methods to serialize the message

data/lib/solace/serializers/transaction_deserializer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# =============================
-# Transaction Deserializer
-# =============================
-#
-# Deserializes a binary transaction into a Solace::Transaction object.
 module Solace
   module Serializers
+    # Deserializes a binary transaction into a Solace::Transaction object.
+    #
+    # @since 0.0.1
     class TransactionDeserializer < Solace::Serializers::BaseDeserializer
       # @!attribute record_class
       #   The class of the record being deserialized
@@ -14,7 +12,7 @@ module Solace
       # @return [Class] The class of the record
       self.record_class = Solace::Transaction
 
-      # @!attribute steps
+      # @!attribute  steps
       #   An ordered list of methods to deserialize the transaction
       #
       # @return [Array] The steps to deserialize the transaction
@@ -42,7 +40,7 @@ module Solace
       #
       # @return [Solace::Message] The deserialized message instance
       def next_extract_message
-        record.message = Solace::Serializers::MessageDeserializer.call(io)
+        record.message = Solace::Serializers::MessageDeserializer.new(io).call
       end
     end
   end

data/lib/solace/serializers/transaction_serializer.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
-# =============================
-# Transaction Serializer
-# =============================
-#
-# Serializes a Solana transaction to a binary format.
 module Solace
   module Serializers
+    # Serializes a Solana transaction to a binary format.
+    #
+    # @since 0.0.1
     class TransactionSerializer < Solace::Serializers::BaseSerializer
-      # @!const SIGNATURE_PLACEHOLDER
+      # @!attribute SIGNATURE_PLACEHOLDER
       #   @return [String] Placeholder for a signature in the transaction
       SIGNATURE_PLACEHOLDER = ([0] * 64).pack('C*')
 
@@ -32,7 +30,7 @@ module Solace
       #
       # @return [Array<Integer>] The bytes of the encoded signatures
       def encode_signatures
-        Codecs.encode_compact_u16(record.signatures.size).bytes +
+        Codecs.encode_compact_u16(record.message.num_required_signatures).bytes +
           index_signatures(record.message.num_required_signatures)
       end
 

data/lib/solace/transaction.rb

@@ -1,40 +1,54 @@
 # encoding: ASCII-8BIT
 # frozen_string_literal: true
 
-# =============================
-# Transaction
-# =============================
-#
-# Class representing a Solana transaction.
-#
-# The BufferLayout is:
-#   - [Signatures (variable length)]
-#   - [Version (1 byte)] (if versioned)
-#   - [Message header (3 bytes)]
-#   - [Account keys (variable length)]
-#   - [Recent blockhash (32 bytes)]
-#   - [Instructions (variable length)]
-#   - [Address lookup table (variable length)] (if versioned)
-#
 module Solace
-  class Transaction < Solace::SerializableRecord
-    # @!const SERIALIZER
+  # Class representing a Solana transaction
+  #
+  # Transactions are the basic building blocks of Solana. They contain a message and an array of signatures. The
+  # message contains the instructions to be executed and the accounts that are used by the instructions. The signatures
+  # are the signatures of the accounts that are used by the instructions. This class provides methods for signing,
+  # serializing, and deserializing transactions.
+  #
+  # The BufferLayout is:
+  #   - [Signatures (variable length)]
+  #   - [Version (1 byte)] (if versioned)
+  #   - [Message header (3 bytes)]
+  #   - [Account keys (variable length)]
+  #   - [Recent blockhash (32 bytes)]
+  #   - [Instructions (variable length)]
+  #   - [Address lookup table (variable length)] (if versioned)
+  #
+  # @example
+  #   # Create a new transaction
+  #   tx = Solace::Transaction.new
+  #
+  #   # Add a message to the transaction
+  #   tx.message = Solace::Message.new(**message_params)
+  #
+  #   # Sign the transaction
+  #   tx.sign(payer_keypair)
+  #
+  # @since 0.0.1
+  class Transaction
+    include Solace::Concerns::BinarySerializable
+
+    # @!attribute SERIALIZER
     #   @return [Solace::Serializers::TransactionSerializer] The serializer for the transaction
     SERIALIZER = Solace::Serializers::TransactionSerializer
 
-    # @!const DESERIALIZER
+    # @!attribute DESERIALIZER
     #   @return [Solace::Serializers::TransactionDeserializer] The deserializer for the transaction
     DESERIALIZER = Solace::Serializers::TransactionDeserializer
 
-    # @!const SIGNATURE_PLACEHOLDER
+    # @!attribute SIGNATURE_PLACEHOLDER
     #   @return [String] Placeholder for a signature in the transaction
     SIGNATURE_PLACEHOLDER = Solace::Utils::Codecs.base58_to_binary('1' * 64)
 
-    # @!attribute [rw] signatures
+    # @!attribute  [rw] signatures
     #   @return [Array<String>] Signatures of the transaction (binary)
     attr_accessor :signatures
 
-    # @!attribute [rw] message
+    # @!attribute  [rw] message
     #   @return [Solace::Message] Message of the transaction
     attr_accessor :message
 
@@ -44,7 +58,7 @@ module Solace
       # @param base64_tx [String] The base64 encoded transaction
       # @return [Solace::Transaction] The deserialized transaction
       def from(base64_tx)
-        DESERIALIZER.call Solace::Utils::Codecs.base64_to_bytestream(base64_tx)
+        DESERIALIZER.new(Solace::Utils::Codecs.base64_to_bytestream(base64_tx)).call
       end
     end
 
@@ -55,6 +69,7 @@ module Solace
       signatures: [],
       message: Solace::Message.new
     )
+      super()
       @signatures = signatures
       @message = message
     end
@@ -63,7 +78,7 @@ module Solace
     #
     # Calls sign_and_update_signatures for each keypair passed in.
     #
-    # @param keypairs [<Solace::Keypair>] The keypairs to sign the transaction with
+    # @param keypairs [Array<Solace::Keypair>] The keypairs to sign the transaction with
     # @return [Array<String>] The signatures of the transaction
     def sign(*keypairs)
       keypairs.map { |keypair| sign_and_update_signatures(keypair) }

data/lib/solace/transaction_composer.rb

@@ -1,21 +1,55 @@
+# frozen_string_literal: true
+
 # lib/solace/transaction_composer.rb
 module Solace
   # Composes multi-instruction transactions with automatic account management
+  #
+  # @example
+  #   # Initialize a transaction composer
+  #   composer = Solace::TransactionComposer.new(connection: connection)
+  #
+  #   # Add an instruction composer
+  #   composer.add_instruction(
+  #     Solace::Composers::SystemProgramTransferComposer.new(
+  #       to: 'pubkey1',
+  #       from: 'pubkey2',
+  #       lamports: 100
+  #     )
+  #   )
+  #
+  #   # Add another instruction composer
+  #   composer.add_instruction(
+  #     Solace::Composers::SplTokenProgramTransferCheckedComposer.new(
+  #       from: 'pubkey4',
+  #       to: 'pubkey5',
+  #       mint: 'pubkey6',
+  #       authority: 'pubkey7',
+  #       amount: 1_000_000,
+  #       decimals: 6
+  #     )
+  #   )
+  #
+  #   # Set the fee payer
+  #   composer.set_fee_payer('pubkey8')
+  #
+  #   # Compose the transaction
+  #   tx = composer.compose_transaction
+  #
+  #   # Sign the transaction with all required signers
+  #   tx.sign(*required_signers)
+  #
+  # @since 0.0.1
   class TransactionComposer
-
     # @!attribute connection
-    #
-    # @return [Solace::Connection] The connection to the Solana cluster
+    #   The connection to the Solana cluster
     attr_reader :connection
 
     # @!attribute context
-    #
-    # @return [Utils::AccountContext] The account registry
+    #   The account context
     attr_reader :context
 
     # @!attribute instruction_composers
-    #
-    # @return [Array<Composers::Base>] The instruction composers
+    #   The instruction composers
     attr_reader :instruction_composers
 
     # Initialize the composer
@@ -26,7 +60,7 @@ module Solace
       @instruction_composers = []
       @context = Utils::AccountContext.new
     end
-    
+
     # Add an instruction composer to the transaction
     #
     # @param composer [Composers::Base] The instruction composer
@@ -36,10 +70,10 @@ module Solace
       instruction_composers << composer
       self
     end
-    
+
     # Set the fee payer for the transaction
     #
-    # @param pubkey [String | Solace::PublicKey | Solace::Keypair] The fee payer pubkey
+    # @param pubkey [String, Solace::PublicKey, Solace::Keypair] The fee payer pubkey
     # @return [TransactionComposer] Self for chaining
     def set_fee_payer(pubkey)
       context.set_fee_payer(pubkey)
@@ -56,11 +90,11 @@ module Solace
         header: context.header,
         accounts: context.accounts,
         instructions: build_instructions,
-        recent_blockhash: connection.get_latest_blockhash,
+        recent_blockhash: connection.get_latest_blockhash
       )
-      
+
       Solace::Transaction.new(message: message)
-    end    
+    end
 
     private