solace 0.0.2

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SystemProgram
+      class CreateAccountInstruction
+        # !@const 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
+        #
+        # @param space [Integer] Number of bytes to allocate for the new account
+        # @param lamports [Integer] Amount of lamports to fund the new account
+        # @param owner [String] The program_id of the owner of the new account
+        # @param from_index [Integer] Index of the funding account (payer) in the transaction's accounts
+        # @param new_account_index [Integer] Index of the new account to create in the transaction's accounts
+        # @param system_program_index [Integer] Index of the system program in the transaction's accounts (default: 2)
+        # @return [Solace::Instruction]
+        def self.build(
+          space:,
+          lamports:,
+          owner: Solace::Constants::SYSTEM_PROGRAM_ID,
+          from_index:,
+          new_account_index:,
+          system_program_index: 2
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = system_program_index
+            ix.accounts = [from_index, new_account_index]
+            ix.data = data(lamports, space, owner)
+          end
+        end
+
+        # Builds the data for a SystemProgram::CreateAccount instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (4 bytes)]
+        #   - [Lamports (8 bytes)]
+        #   - [Space (8 bytes)]
+        #   - [Owner (32 bytes)]
+        #
+        # @param lamports [Integer] Amount of lamports to fund the new account
+        # @param space [Integer] Number of bytes to allocate for the new account
+        # @param owner [String] The program_id of the owner of the new account
+        # @return [Array] 4-byte instruction index + 8-byte lamports + 8-byte space + 32-byte owner
+        def self.data(lamports, space, owner)
+          INSTRUCTION_INDEX +
+            Solace::Utils::Codecs.encode_le_u64(lamports).bytes +
+            Solace::Utils::Codecs.encode_le_u64(space).bytes +
+            Solace::Utils::Codecs.base58_to_bytes(owner)
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/transfer_checked_instruction.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # Service object for building an SPL Token Program transfer instruction
+    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

data/lib/solace/instructions/transfer_instruction.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # Service object for building a System Program transfer instruction
+    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
+      # @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
+      )
+        Solace::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 +
+          Solace::Utils::Codecs.encode_le_u64(lamports).bytes
+      end
+    end
+  end
+end

data/lib/solace/keypair.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'rbnacl'
+require 'base58'
+
+# =============================
+# Keypair
+# =============================
+#
+# Represents a Solana Ed25519 Keypair
+module Solace
+  class Keypair
+    # !@const SECRET_LENGTH
+    #   The length of a Solana secret key in bytes
+    #
+    # @return [Integer] The length of a secret key
+    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
+
+    # !@const SigningKey
+    #   The RbNaCl signing key
+    #
+    # @return [RbNaCl::Signatures::Ed25519::SigningKey]
+    SigningKey = RbNaCl::Signatures::Ed25519::SigningKey
+
+    # !@attribute [r] keypair_bytes
+    #   @return [Array<Integer>] The keypair bytes
+    attr_reader :keypair_bytes
+
+    class << self
+      # Generate a new random keypair
+      #
+      # @return [Keypair]
+      def generate
+        from_seed(RbNaCl::Random.random_bytes(SEED_LENGTH))
+      end
+
+      # Create a keypair from a 32-byte seed
+      #
+      # @param seed [String] 32-byte array
+      # @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)
+      end
+
+      # Create a keypair from a 64-byte secret key
+      #
+      # @param secret_key [String] 64-byte array
+      # @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)
+      end
+    end
+
+    # Initialize a new keypair
+    #
+    # @param keypair_bytes [Array<Integer>] The keypair bytes
+    # @return [Keypair] The new keypair object
+    def initialize(keypair_bytes)
+      raise ArgumentError, 'Keypair must be 64 bytes' unless keypair_bytes.length == SECRET_LENGTH
+
+      @keypair_bytes = keypair_bytes
+    end
+
+    # Returns the public key
+    #
+    # @return [PublicKey]
+    def public_key
+      @public_key ||= Solace::PublicKey.new(public_key_bytes)
+    end
+
+    # Returns the signing key
+    #
+    # @return [RbNaCl::Signatures::Ed25519::SigningKey]
+    def signing_key
+      @signing_key ||= SigningKey.new(private_key)
+    end
+
+    # Returns the public key bytes
+    #
+    # The public key bytes are the last 32 bytes of the keypair
+    #
+    # @return [String] 32 bytes
+    def public_key_bytes
+      keypair_bytes[32..63]
+    end
+
+    # Returns the private key
+    #
+    # The private key is the first 32 bytes of the keypair
+    #
+    # @return [String] 32 characters
+    def private_key
+      keypair_bytes[0..31].pack('C*')
+    end
+
+    # Returns the public key as a Base58 string
+    #
+    # @return [String] Base58 encoded public key
+    def address
+      public_key.to_base58
+    end
+
+    # Signs a message (string or binary)
+    #
+    # @param message [String | Binary]
+    # @return [Binary] signature (binary)
+    def sign(message)
+      signing_key.sign(message)
+    end
+  end
+end

data/lib/solace/message.rb

@@ -0,0 +1,95 @@
+# 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
+    #   @return [Solace::Serializers::MessageSerializer] The serializer for the message
+    SERIALIZER = Solace::Serializers::MessageSerializer
+
+    # @!const DESERIALIZER
+    #   @return [Solace::Serializers::MessageDeserializer] The deserializer for the message
+    DESERIALIZER = Solace::Serializers::MessageDeserializer
+
+    # @!attribute [rw] version
+    #   @return [Integer, nil] Message version (nil for legacy)
+    attr_accessor :version
+
+    # @!attribute [rw] header
+    #   @return [Array<Integer>] Message header [num_required_signatures, num_readonly_signed, num_readonly_unsigned]
+    attr_accessor :header
+
+    # @!attribute [rw] accounts
+    #   @return [Array<String>] Account public keys (base58)
+    attr_accessor :accounts
+
+    # @!attribute [rw] recent_blockhash
+    #   @return [String] Recent blockhash (base58)
+    attr_accessor :recent_blockhash
+
+    # @!attribute [rw] instructions
+    #   @return [Array<Solace::Instruction>] Instructions in the message
+    attr_accessor :instructions
+
+    # @!attribute [rw] address_lookup_tables
+    #   @return [Array<Solace::AddressLookupTable>] Address lookup tables (for versioned messages)
+    attr_accessor :address_lookup_tables
+
+    # Initialize a new Message
+    #
+    # @param version [Integer, nil] Message version (nil for legacy)
+    # @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 address_lookup_tables [Array<Solace::AddressLookupTable>]
+    def initialize(
+      version: nil,
+      accounts: [],
+      instructions: [],
+      recent_blockhash: nil,
+      header: [0, 0, 0],
+      address_lookup_tables: []
+    )
+      @version = version
+      @header = header
+      @accounts = accounts
+      @recent_blockhash = recent_blockhash
+      @instructions = instructions
+      @address_lookup_tables = address_lookup_tables
+    end
+
+    # Check if the message is versioned
+    #
+    # @return [Boolean] True if the message is versioned, false otherwise
+    def versioned?
+      !version.nil?
+    end
+
+    # Returns the number of required signatures
+    #
+    # @return [Integer] The number of required signatures
+    def num_required_signatures
+      header[0]
+    end
+
+    # Returns the number of readonly signed accounts
+    #
+    # @return [Integer] The number of readonly signed accounts
+    def num_readonly_signed_accounts
+      header[1]
+    end
+
+    # Returns the number of readonly unsigned accounts
+    #
+    # @return [Integer] The number of readonly unsigned accounts
+    def num_readonly_unsigned_accounts
+      header[2]
+    end
+  end
+end

data/lib/solace/programs/associated_token_account.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    # A client for interacting with the SPL Token Program.
+    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.
+        # @return [String] The address of the associated token account.
+        def get_address(owner:, mint:)
+          Solace::Utils::PDA.find_program_address(
+            [
+              owner.address,
+              Solace::Constants::TOKEN_PROGRAM_ID,
+              mint.address
+            ],
+            Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+          )
+        end
+      end
+
+      # Initializes a new Associated Token Account client.
+      #
+      # @param connection [Solace::Connection] The connection to the Solana cluster.
+      def initialize(connection:)
+        super(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
+      def get_address(**options)
+        self.class.get_address(**options)
+      end
+
+      # Creates a new associated token account.
+      #
+      # @param options [Hash] Options for calling the prepare_create_associated_token_account method.
+      # @return [String] The signature of the transaction.
+      def create_associated_token_account(**options)
+        tx = prepare_create_associated_token_account(**options)
+
+        @connection.send_transaction(tx.serialize)
+      end
+
+      # 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 payer [Solace::Keypair] The keypair that will pay for fees and rent.
+      # @return [Solace::Transaction] The signed transaction.
+      def prepare_create_associated_token_account(
+        owner:,
+        mint:,
+        payer:
+      )
+        ata_address, _ = get_address(owner:, mint:)
+
+        accounts = [
+          payer.address,
+          ata_address,
+          owner.address,
+          mint.address,
+          Solace::Constants::SYSTEM_PROGRAM_ID,
+          Solace::Constants::TOKEN_PROGRAM_ID,
+          Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+        ]
+
+        instruction = Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction.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
+        )
+
+        message = Solace::Message.new(
+          header: [1, 0, 4],
+          accounts: accounts,
+          recent_blockhash: @connection.get_latest_blockhash,
+          instructions: [instruction]
+        )
+
+        tx = Solace::Transaction.new(message: message)
+        tx.sign(payer)
+
+        tx
+      end
+    end
+  end
+end

data/lib/solace/programs/base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# lib/solace/programs/base.rb
+
+module Solace
+  module Programs
+    # Base class for program-specific clients.
+    # Provides a consistent interface for interacting with on-chain programs.
+    class Base
+      attr_reader :connection, :program_id
+
+      # Initializes a new program client.
+      #
+      # @param connection [Solace::Connection] The connection to the Solana cluster.
+      # @param program_id [String] The base58 public key of the on-chain program.
+      def initialize(connection:, program_id:)
+        @connection = connection
+        @program_id = program_id
+      end
+    end
+  end
+end

data/lib/solace/programs/spl_token.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Solace
+  module Programs
+    # A client for interacting with the SPL Token Program.
+    class SplToken < Base
+      # Initializes a new SPL Token client.
+      #
+      # @param connection [Solace::Connection] The connection to the Solana cluster.
+      def initialize(connection:)
+        super(connection: connection, program_id: Solace::Constants::TOKEN_PROGRAM_ID)
+      end
+
+      # Creates a new SPL Token mint.
+      #
+      # @param options [Hash] Options for calling the prepare_create_mint method.
+      # @return [String] The signature of the transaction.
+      def create_mint(**options)
+        tx = prepare_create_mint(**options)
+
+        @connection.send_transaction(tx.serialize)
+      end
+
+      # Prepares a new SPL Token mint and returns the signed transaction.
+      #
+      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
+      # @param decimals [Integer] The number of decimal places for the token.
+      # @param mint_authority [String] The base58 public key for the mint authority.
+      # @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.
+      def prepare_create_mint(
+        payer:,
+        decimals:,
+        mint_authority:,
+        freeze_authority:,
+        mint_keypair: Solace::Keypair.generate
+      )
+        accounts = [
+          payer.address,
+          mint_keypair.address,
+          Solace::Constants::SYSVAR_RENT_PROGRAM_ID,
+          Solace::Constants::TOKEN_PROGRAM_ID,
+          Solace::Constants::SYSTEM_PROGRAM_ID
+        ]
+
+        rent_lamports = @connection.get_minimum_lamports_for_rent_exemption(82)
+
+        create_account_ix = Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
+          from_index: 0,
+          new_account_index: 1,
+          system_program_index: 4,
+          lamports: rent_lamports,
+          space: 82,
+          owner: program_id
+        )
+
+        freeze_authority_address = freeze_authority.respond_to?(:address) ? freeze_authority.address : nil
+
+        initialize_mint_ix = Solace::Instructions::SplToken::InitializeMintInstruction.build(
+          mint_account_index: 1,
+          rent_sysvar_index: 2,
+          program_index: 3,
+          decimals: decimals,
+          mint_authority: mint_authority.address,
+          freeze_authority: freeze_authority_address
+        )
+
+        message = Message.new(
+          header: [2, 0, 3],
+          accounts: accounts,
+          recent_blockhash: @connection.get_latest_blockhash,
+          instructions: [create_account_ix, initialize_mint_ix]
+        )
+
+        tx = Transaction.new(message: message)
+        tx.sign(payer, mint_keypair)
+
+        tx
+      end
+
+      # Mint tokens to a token account
+      #
+      # @param options [Hash] Options for calling the prepare_mint_to method.
+      # @return [String] The signature of the transaction.
+      def mint_to(**options)
+        tx = prepare_mint_to(**options)
+
+        @connection.send_transaction(tx.serialize)
+      end
+
+      # Prepares a mint to instruction and returns the signed transaction.
+      #
+      # @param options [Hash] Options for calling the prepare_mint_to method.
+      # @return [Solace::Transaction] The signed transaction.
+      def prepare_mint_to(
+        payer:, 
+        mint:,
+        destination:,
+        amount:,
+        mint_authority:
+      )
+        accounts = [
+          payer.address,
+          mint_authority.address,
+          mint.address,
+          destination,
+          Solace::Constants::TOKEN_PROGRAM_ID,
+        ]
+
+        ix = Solace::Instructions::SplToken::MintToInstruction.build(
+          amount:,
+          mint_authority_index: 1,
+          mint_index: 2,
+          destination_index: 3,
+          program_index: 4
+        )
+
+        message = Solace::Message.new(
+          header: [2, 0, 1],
+          accounts:,
+          instructions: [ix],
+          recent_blockhash: connection.get_latest_blockhash,
+        )
+
+        tx = Solace::Transaction.new(message: message)
+        tx.sign(payer, mint_authority)
+
+        tx
+      end
+
+      # Transfers tokens from one account to another
+      #
+      # @param options [Hash] Options for calling the prepare_transfer method.
+      # @return [String] The signature of the transaction.
+      def transfer(**options)
+        tx = prepare_transfer(**options)
+
+        @connection.send_transaction(tx.serialize)
+      end
+
+      # Prepares a transfer instruction and returns the signed transaction.
+      #
+      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
+      # @param source [String] The source token account address.
+      # @param destination [String] The destination token account address.
+      # @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.
+      def prepare_transfer(
+        amount:, 
+        payer:, 
+        source:, 
+        destination:, 
+        owner:
+      )
+        accounts = [
+          payer.address,
+          owner.address,
+          source,
+          destination,
+          Solace::Constants::TOKEN_PROGRAM_ID
+        ]
+
+        ix = Solace::Instructions::SplToken::TransferInstruction.build(
+          amount:,
+          owner_index: 1,
+          source_index: 2,
+          destination_index: 3,
+          program_index: 4
+        )
+
+        message = Solace::Message.new(
+          header: [2, 0, 1],
+          accounts:,
+          instructions: [ix],
+          recent_blockhash: connection.get_latest_blockhash
+        )
+
+        tx = Solace::Transaction.new(message:)
+        tx.sign(payer, owner)
+
+        tx
+      end
+    end
+  end
+end