solace 0.0.2

data/lib/solace/address_lookup_table.rb

@@ -0,0 +1,50 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# =============================
+# Address Lookup Table
+# =============================
+#
+# Class representing an address lookup table.
+#
+# The BufferLayout is:
+#   - [Account key (32 bytes)]
+#   - [Number of writable indexes (compact u16)]
+#   - [Writable indexes (variable length)]
+#   - [Number of readonly indexes (compact u16)]
+#   - [Readonly indexes (variable length)]
+#
+module Solace
+  class AddressLookupTable
+    include Solace::Concerns::BinarySerializable
+
+    # @!attribute [rw] account
+    #   @return [String] The account key of the address lookup table
+    attr_accessor :account
+
+    # @!attribute [rw] writable_indexes
+    #   @return [Array<Integer>] The writable indexes in the address lookup table
+    attr_accessor :writable_indexes
+
+    # @!attribute [rw] readonly_indexes
+    #   @return [Array<Integer>] The readonly indexes in the address lookup table
+    attr_accessor :readonly_indexes
+
+    class << self
+      # Parse address lookup table from io stream
+      #
+      # @param io [IO or StringIO] The input to read bytes from.
+      # @return [Solace::AddressLookupTable] Parsed address lookup table object
+      def deserialize(io)
+        Solace::Serializers::AddressLookupTableDeserializer.call(io)
+      end
+    end
+
+    # Serialize the address lookup table
+    #
+    # @return [String] The serialized address lookup table (base64)
+    def serialize
+      Solace::Serializers::AddressLookupTableSerializer.call(self)
+    end
+  end
+end

data/lib/solace/concerns/binary_serializable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Solace
+  module Concerns
+    module BinarySerializable
+      # Returns the binary decoded from the serialized string
+      #
+      # Expects the class to have a `serialize` method that returns a base64 string.
+      #
+      # @return [String] The binary decoded from the serialized string
+      def to_binary
+        Base64.decode64(serialize)
+      end
+
+      # Returns a StringIO stream of the binary data
+      #
+      # @return [IO] The StringIO stream of the binary data
+      def to_io
+        StringIO.new(to_binary)
+      end
+
+      # Returns the bytes of the binary data as an array of integers
+      #
+      # @return [Array] The bytes of the binary data as an array of integers
+      def to_bytes
+        to_binary.bytes
+      end
+    end
+  end
+end

data/lib/solace/connection.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Solace
+  class Connection
+    attr_reader :rpc_url
+
+    # !const default options
+    DEFAULT_OPTIONS = {
+      encoding: 'base64',
+      commitment: 'confirmed'
+    }.freeze
+
+    # Initialize the connection with a default or custom RPC URL
+    #
+    # @param rpc_url [String] The URL of the Solana RPC node
+    # @return [Solace::Connection] The connection object
+    def initialize(rpc_url = 'http://localhost:8899')
+      @rpc_url = rpc_url
+      @request_id = nil
+    end
+
+    # Make an RPC request to the Solana node
+    #
+    # @param method [String] The RPC method to call
+    # @param params [Array] Parameters for the RPC method
+    # @return [Object] Result of the RPC call
+    def rpc_request(method, params = [])
+      uri = URI(rpc_url)
+
+      req = Net::HTTP::Post.new(uri)
+      req['Accept'] = 'application/json'
+      req['Content-Type'] = 'application/json'
+
+      @request_id = SecureRandom.uuid
+
+      req.body = {
+        jsonrpc: '2.0',
+        id: @request_id,
+        method: method,
+        params: params
+      }.to_json
+
+      res = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == 'https'
+      ) do |http|
+        http.request(req)
+      end
+
+      raise "RPC error: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+    # Request an airdrop of lamports to a given address
+    #
+    # @param pubkey [String] The public key of the account to receive the airdrop
+    # @param lamports [Integer] Amount of lamports to airdrop
+    # @return [String] The transaction signature of the airdrop
+    def request_airdrop(pubkey, lamports, options = {})
+      rpc_request(
+        'requestAirdrop',
+        [
+          pubkey,
+          lamports,
+          DEFAULT_OPTIONS.merge(options)
+        ]
+      )
+    end
+
+    # Get the latest blockhash from the Solana node
+    #
+    # @return [String] The latest blockhash
+    def get_latest_blockhash
+      rpc_request('getLatestBlockhash')['result']['value']['blockhash']
+    end
+
+    # Get the minimum required lamports for rent exemption
+    #
+    # @param space [Integer] Number of bytes to allocate for the account
+    # @return [Integer] The minimum required lamports
+    def get_minimum_lamports_for_rent_exemption(space)
+      rpc_request('getMinimumBalanceForRentExemption', [space])['result']
+    end
+
+    # Get the account information from the Solana node
+    #
+    # @param pubkey [String] The public key of the account
+    # @return [Object] The account information
+    def get_account_info(pubkey)
+      response = rpc_request(
+        'getAccountInfo',
+        [
+          pubkey,
+          DEFAULT_OPTIONS
+        ]
+      )['result']
+
+      return if response.nil?
+
+      response['value']
+    end
+
+    # Get the balance of a specific account
+    #
+    # @param pubkey [String] The public key of the account
+    # @return [Integer] The balance of the account
+    def get_balance(pubkey)
+      rpc_request(
+        'getBalance',
+        [
+          pubkey,
+          DEFAULT_OPTIONS
+        ]
+      )['result']['value']
+    end
+
+    # Get the transaction by signature
+    #
+    # @param signature [String] The signature of the transaction
+    # @return [Solace::Transaction] The transaction object
+    def get_transaction(signature, options = { maxSupportedTransactionVersion: 0 })
+      rpc_request(
+        'getTransaction',
+        [
+          signature,
+          DEFAULT_OPTIONS.merge(options)
+        ]
+      )['result']
+    end
+
+    # Get the signature status
+    #
+    # @param signatures [Array] The signatures of the transactions
+    # @return [Object] The signature status
+    def get_signature_status(signatures)
+      rpc_request(
+        'getSignatureStatuses',
+        [
+          signatures,
+          DEFAULT_OPTIONS.merge({ 'searchTransactionHistory' => true })
+        ]
+      )['result']
+    end
+
+    # Send a transaction to the Solana node
+    #
+    # @param transaction [Solace::Transaction] The transaction to send
+    # @return [String] The signature of the transaction
+    def send_transaction(transaction, options = {})
+      rpc_request(
+        'sendTransaction',
+        [
+          transaction,
+          DEFAULT_OPTIONS.merge(options)
+        ]
+      )
+    end
+
+    # Wait for a confirmed signature from the transaction
+    #
+    # @param commitment [String] The commitment level to wait for
+    # @return [Boolean] True if the transaction was confirmed, false otherwise
+    def wait_for_confirmed_signature(commitment = 'confirmed')
+      raise ArgumentError, 'Block required' unless block_given?
+
+      # Get the signature from the block
+      signature = yield
+
+      # Wait for confirmation
+      loop do
+        status = get_signature_status([signature]).dig('value', 0)
+
+        break if status && status['confirmationStatus'] == commitment
+
+        sleep 0.5
+      end
+
+      signature
+    end
+  end
+end

data/lib/solace/constants.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Constants module
+#
+# Contains constants used across the library.
+#
+# @return [Module] Constants module
+module Solace
+  module Constants
+    # @!const SYSTEM_PROGRAM_ID
+    #   The public key of the System Program (native SOL transfers, account creation, etc)
+    #   This is the same across all Solana clusters
+    # @return [String]
+    SYSTEM_PROGRAM_ID = '11111111111111111111111111111111'
+
+    # @!const SYSVAR_RENT_PROGRAM_ID
+    #   The public key of the Rent Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    SYSVAR_RENT_PROGRAM_ID = 'SysvarRent111111111111111111111111111111111'
+
+    # @!const COMPUTE_BUDGET_PROGRAM_ID
+    #   The public key of the Compute Budget Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    COMPUTE_BUDGET_PROGRAM_ID = 'ComputeBudget111111111111111111111111111111'
+
+    # @!const TOKEN_PROGRAM_ID
+    #   The public key of the SPL Token Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+
+    # @!const ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+    #   The public key of the Associated Token Account Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'
+
+    # @!const MEMO_PROGRAM_ID
+    #   The public key of the Memo Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
+
+    # @!const ADDRESS_LOOKUP_TABLE_PROGRAM_ID
+    #   The public key of the Address Lookup Table Program
+    #   This is the same across all Solana clusters
+    # @return [String]
+    ADDRESS_LOOKUP_TABLE_PROGRAM_ID = 'AddressLookupTab1e1111111111111111111111111'
+  end
+end

data/lib/solace/instruction.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# =============================
+# Instruction
+# =============================
+#
+# Class representing a Solana instruction.
+#
+# The BufferLayout is:
+#   - [Program index (1 byte)]
+#   - [Number of accounts (compact u16)]
+#   - [Accounts (variable length)]
+#   - [Data length (compact u16)]
+#   - [Data (variable length)]
+#
+module Solace
+  class Instruction < Solace::SerializableRecord
+    # @!const SERIALIZER
+    #   @return [Solace::Serializers::InstructionSerializer] The serializer for the instruction
+    SERIALIZER = Solace::Serializers::InstructionSerializer
+
+    # @!const DESERIALIZER
+    #   @return [Solace::Serializers::InstructionDeserializer] The deserializer for the instruction
+    DESERIALIZER = Solace::Serializers::InstructionDeserializer
+
+    # @!attribute [rw] program_index
+    #   @return [Integer] The program index of the instruction
+    attr_accessor :program_index
+
+    # @!attribute [rw] accounts
+    #   @return [Array<Integer>] The accounts of the instruction
+    attr_accessor :accounts
+
+    # @!attribute [rw] data
+    #   @return [Array<Integer>] The instruction data
+    attr_accessor :data
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module AssociatedTokenAccount
+      # A class to build the CreateAssociatedTokenAccount instruction for the Associated Token Account Program.
+      # This is a special "all-in-one" instruction that creates and initializes the account.
+      class CreateAssociatedTokenAccountInstruction
+        # !@const INSTRUCTION_INDEX
+        #   Instruction index for CreateAssociatedTokenAccount
+        #
+        # @return [Array<Integer>]
+        INSTRUCTION_INDEX = [0].freeze
+
+        # Builds a CreateAssociatedTokenAccount instruction.
+        #
+        # The on-chain program requires accounts in a specific order:
+        # 1. [writable, signer] Funder: The account paying for the rent.
+        # 2. [writable] ATA: The new Associated Token Account to be created.
+        # 3. [readonly] Owner: The wallet that will own the new ATA.
+        # 4. [readonly] Mint: The token mint for the new ATA.
+        # 5. [readonly] System Program: Required to create the account.
+        # 6. [readonly] SPL Token Program: Required to initialize the account.
+        #
+        # @param funder_index [Integer] Index of the funding account (payer).
+        # @param associated_token_account_index [Integer] Index of the Associated Token Account to be created.
+        # @param owner_index [Integer] Index of the wallet that will own the new ATA.
+        # @param mint_index [Integer] Index of the token mint.
+        # @param system_program_index [Integer] Index of the System Program.
+        # @param token_program_index [Integer] Index of the SPL Token Program.
+        # @param program_index [Integer] Index of the Associated Token Program itself.
+        # @return [Solace::Instruction]
+        def self.build(
+          funder_index:,
+          associated_token_account_index:,
+          owner_index:,
+          mint_index:,
+          system_program_index:,
+          token_program_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [
+              funder_index,
+              associated_token_account_index,
+              owner_index,
+              mint_index,
+              system_program_index,
+              token_program_index
+            ]
+            ix.data = data
+          end
+        end
+
+        # Data for a CreateAssociatedTokenAccount instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_INDEX
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# 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.
+      class InitializeAccountInstruction
+        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for SPL Token Program's InitializeAccount instruction.
+        INSTRUCTION_INDEX = [1].freeze
+
+        # Builds a SPLToken::InitializeAccount instruction.
+        #
+        # @param account_index [Integer] Index of the new token account in the transaction's accounts.
+        # @param mint_index [Integer] Index of the mint account in the transaction's accounts.
+        # @param owner_index [Integer] Index of the owner of the new account in the transaction's accounts.
+        # @param rent_sysvar_index [Integer] Index of the Rent Sysvar in the transaction's accounts.
+        # @param program_index [Integer] Index of the SPL Token program in the transaction's accounts.
+        # @return [Solace::Instruction]
+        def self.build(
+          account_index:,
+          mint_index:,
+          owner_index:,
+          rent_sysvar_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [account_index, mint_index, owner_index, rent_sysvar_index]
+            ix.data = data
+          end
+        end
+
+        # Builds the data for a SPLToken::InitializeAccount instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_INDEX
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      class InitializeMintInstruction
+        # Instruction index for Initialize Mint
+        INSTRUCTION_INDEX = [0].freeze
+
+        # Builds a Solace::Instruction for initializing an SPL Token Program mint
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Decimals (1 byte)]
+        #   - [Mint authority (32 bytes)]
+        #   - [Freeze authority option (1 byte)]
+        #   - [Freeze authority (32 bytes)]
+        #
+        # @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
+        # @param rent_sysvar_index [Integer] Index of the rent sysvar in the transaction's accounts
+        # @param mint_account_index [Integer] Index of the mint account 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(
+          decimals:,
+          mint_authority:,
+          rent_sysvar_index:,
+          mint_account_index:,
+          freeze_authority: nil,
+          program_index: 2
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [mint_account_index, rent_sysvar_index]
+            ix.data = data(decimals, mint_authority, freeze_authority)
+          end
+        end
+
+        # Instruction data for an initialize mint instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Decimals (1 byte)]
+        #   - [Mint authority (32 bytes)]
+        #   - [Freeze authority option (33 byte)]
+        #
+        # @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
+        def self.data(decimals, mint_authority, freeze_authority)
+          INSTRUCTION_INDEX +
+            [decimals] +
+            Solace::Utils::Codecs.base58_to_bytes(mint_authority) +
+            (
+              if freeze_authority
+                [1] + Solace::Utils::Codecs.base58_to_bytes(freeze_authority)
+              else
+                [0]
+              end
+            )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      # A class to build the MintTo instruction for the SPL Token Program.
+      class MintToInstruction
+        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for SPL Token Program's MintTo instruction.
+        INSTRUCTION_INDEX = [7].freeze
+
+        # Builds a MintTo instruction.
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @param mint_index [Integer] The index of the mint account.
+        # @param destination_index [Integer] The index of the token account to mint to.
+        # @param mint_authority_index [Integer] The index of the mint authority account.
+        # @param program_index [Integer] The index of the SPL Token Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          mint_index:,
+          mint_authority_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [mint_index, destination_index, mint_authority_index]
+            ix.data = data(amount)
+          end
+        end
+
+        # Builds the data for a MintTo instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @return [Array] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      # A class to build the Transfer instruction for the SPL Token Program.
+      class TransferInstruction
+        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for SPL Token Program's Transfer instruction.
+        INSTRUCTION_INDEX = [3].freeze
+
+        # Builds a Transfer instruction.
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @param source_index [Integer] The index of the source token account.
+        # @param destination_index [Integer] The index of the destination token account.
+        # @param owner_index [Integer] The index of the source account's owner.
+        # @param program_index [Integer] The index of the SPL Token Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          owner_index:,
+          source_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [source_index, destination_index, owner_index]
+            ix.data = data(amount)
+          end
+        end
+
+        # Builds the data for a Transfer instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @return [Array<Integer>] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end