solrengine-programs 0.1.0

data/lib/solrengine/programs/borsh_types.rb

@@ -0,0 +1,160 @@
+require "digest"
+require "base58"
+
+module Solrengine
+  module Programs
+    module BorshTypes
+      # Solana PublicKey: 32-byte fixed array, exposed as Base58 string
+      module PublicKey
+        def self.decode(buffer)
+          bytes = buffer.read(32)
+          Base58.binary_to_base58(bytes, :bitcoin)
+        end
+
+        def self.encode(buffer, value)
+          bytes = Base58.base58_to_binary(value, :bitcoin)
+          raise DeserializationError, "PublicKey must be 32 bytes (got #{bytes.bytesize})" unless bytes.bytesize == 32
+          buffer.write(bytes)
+        end
+
+        def self.size
+          32
+        end
+      end
+
+      # Anchor discriminator: first 8 bytes of SHA256
+      module Discriminator
+        def self.for_account(name)
+          Digest::SHA256.digest("account:#{name}")[0, 8]
+        end
+
+        def self.for_instruction(name)
+          Digest::SHA256.digest("global:#{name}")[0, 8]
+        end
+      end
+
+      # Maps IDL type strings to borsh gem read/write operations
+      TYPE_REGISTRY = {
+        "bool"   => { read: :read_bool,   write: :write_bool,   size: 1 },
+        "u8"     => { read: :read_u8,     write: :write_u8,     size: 1 },
+        "u16"    => { read: :read_u16,    write: :write_u16,    size: 2 },
+        "u32"    => { read: :read_u32,    write: :write_u32,    size: 4 },
+        "u64"    => { read: :read_u64,    write: :write_u64,    size: 8 },
+        "u128"   => { read: :read_u128,   write: :write_u128,   size: 16 },
+        "i8"     => { read: :read_i8,     write: :write_i8,     size: 1 },
+        "i16"    => { read: :read_i16,    write: :write_i16,    size: 2 },
+        "i32"    => { read: :read_i32,    write: :write_i32,    size: 4 },
+        "i64"    => { read: :read_i64,    write: :write_i64,    size: 8 },
+        "i128"   => { read: :read_i128,   write: :write_i128,   size: 16 },
+        "f32"    => { read: :read_f32,    write: :write_f32,    size: 4 },
+        "f64"    => { read: :read_f64,    write: :write_f64,    size: 8 },
+        "string" => { read: :read_string, write: :write_string, size: nil },
+        "pubkey" => { read: :read_pubkey, write: :write_pubkey, size: 32 }
+      }.freeze
+
+      # Read a value from a Borsh::Buffer based on IDL type
+      def self.read_field(buffer, type)
+        case type
+        when String
+          if type == "pubkey"
+            PublicKey.decode(buffer)
+          elsif TYPE_REGISTRY.key?(type)
+            buffer.send(TYPE_REGISTRY[type][:read])
+          else
+            raise DeserializationError, "Unknown type: #{type}"
+          end
+        when Hash
+          read_complex_type(buffer, type)
+        else
+          raise DeserializationError, "Unsupported type spec: #{type.inspect}"
+        end
+      end
+
+      # Write a value to a Borsh::Buffer based on IDL type
+      def self.write_field(buffer, type, value)
+        case type
+        when String
+          if type == "pubkey"
+            PublicKey.encode(buffer, value)
+          elsif TYPE_REGISTRY.key?(type)
+            buffer.send(TYPE_REGISTRY[type][:write], value)
+          else
+            raise DeserializationError, "Unknown type: #{type}"
+          end
+        when Hash
+          write_complex_type(buffer, type, value)
+        else
+          raise DeserializationError, "Unsupported type spec: #{type.inspect}"
+        end
+      end
+
+      # Calculate the fixed byte size for a type (nil if variable-length)
+      def self.field_size(type)
+        case type
+        when String
+          TYPE_REGISTRY.dig(type, :size)
+        when Hash
+          nil # complex types are variable-length
+        else
+          nil
+        end
+      end
+
+      def self.read_complex_type(buffer, type_hash)
+        if type_hash.key?("vec")
+          element_type = type_hash["vec"]
+          count = buffer.read_u32
+          Array.new(count) { read_field(buffer, element_type) }
+        elsif type_hash.key?("option")
+          inner_type = type_hash["option"]
+          present = buffer.read_bool
+          present ? read_field(buffer, inner_type) : nil
+        elsif type_hash.key?("array")
+          element_type, count = type_hash["array"]
+          Array.new(count) { read_field(buffer, element_type) }
+        elsif type_hash.key?("defined")
+          raise DeserializationError, "Custom defined types must be resolved before decoding: #{type_hash["defined"]}"
+        else
+          raise DeserializationError, "Unknown complex type: #{type_hash.inspect}"
+        end
+      end
+      private_class_method :read_complex_type
+
+      def self.write_complex_type(buffer, type_hash, value)
+        if type_hash.key?("vec")
+          element_type = type_hash["vec"]
+          buffer.write_u32(value.size)
+          value.each { |v| write_field(buffer, element_type, v) }
+        elsif type_hash.key?("option")
+          inner_type = type_hash["option"]
+          if value.nil?
+            buffer.write_bool(false)
+          else
+            buffer.write_bool(true)
+            write_field(buffer, inner_type, value)
+          end
+        elsif type_hash.key?("array")
+          element_type, _count = type_hash["array"]
+          value.each { |v| write_field(buffer, element_type, v) }
+        else
+          raise DeserializationError, "Unknown complex type: #{type_hash.inspect}"
+        end
+      end
+      private_class_method :write_complex_type
+
+      # Encode compact-u16 (Solana's variable-length encoding for array lengths in transactions)
+      def self.encode_compact_u16(value)
+        bytes = []
+        val = value
+        loop do
+          byte = val & 0x7F
+          val >>= 7
+          byte |= 0x80 if val > 0
+          bytes << byte
+          break if val == 0
+        end
+        bytes.pack("C*")
+      end
+    end
+  end
+end

data/lib/solrengine/programs/configuration.rb

@@ -0,0 +1,44 @@
+require "base58"
+require "json"
+
+module Solrengine
+  module Programs
+    class Configuration
+      attr_accessor :keypair_format
+
+      def initialize
+        @keypair_format = :base58
+      end
+
+      def server_keypair
+        @server_keypair ||= load_keypair
+      end
+
+      def server_keypair?
+        !ENV["SOLANA_KEYPAIR"].nil? && !ENV["SOLANA_KEYPAIR"].empty?
+      end
+
+      private
+
+      def load_keypair
+        raw = ENV["SOLANA_KEYPAIR"]
+        return nil if raw.nil? || raw.empty?
+
+        bytes = case keypair_format
+        when :base58
+                  Base58.base58_to_binary(raw, :bitcoin)
+        when :json_array
+                  JSON.parse(raw).pack("C*")
+        else
+                  raise ConfigurationError, "Unsupported keypair format: #{keypair_format}"
+        end
+
+        unless bytes.bytesize == 64
+          raise ConfigurationError, "Keypair must be 64 bytes (got #{bytes.bytesize})"
+        end
+
+        { secret_key: bytes[0, 32], public_key: bytes[32, 32] }
+      end
+    end
+  end
+end

data/lib/solrengine/programs/engine.rb

@@ -0,0 +1,11 @@
+module Solrengine
+  module Programs
+    class Engine < ::Rails::Engine
+      isolate_namespace Solrengine::Programs
+
+      initializer "solrengine-programs.assets" do |app|
+        app.config.assets.paths << root.join("app/assets/javascripts")
+      end
+    end
+  end
+end

data/lib/solrengine/programs/error_mapper.rb

@@ -0,0 +1,50 @@
+module Solrengine
+  module Programs
+    class ErrorMapper
+      ANCHOR_ERROR_OFFSET = 6000
+
+      def initialize(parsed_errors)
+        @errors_by_code = parsed_errors.each_with_object({}) do |err, h|
+          h[err.code] = err
+        end
+      end
+
+      def map(error_code)
+        err = @errors_by_code[error_code]
+        return nil unless err
+
+        { code: err.code, name: err.name, message: err.message }
+      end
+
+      # Extract custom error code from an RPC InstructionError response
+      # Example: {"InstructionError":[0,{"Custom":6001}]}
+      def self.extract_custom_error(rpc_error)
+        return nil unless rpc_error.is_a?(Hash)
+
+        instruction_error = rpc_error["InstructionError"]
+        return nil unless instruction_error.is_a?(Array) && instruction_error.size == 2
+
+        custom = instruction_error[1]
+        return nil unless custom.is_a?(Hash) && custom.key?("Custom")
+
+        custom["Custom"]
+      end
+
+      def raise_if_program_error!(rpc_error)
+        code = self.class.extract_custom_error(rpc_error)
+        return unless code
+
+        mapped = map(code)
+        if mapped
+          raise ProgramError.new(
+            code: mapped[:code],
+            error_name: mapped[:name],
+            message: mapped[:message]
+          )
+        else
+          raise TransactionError, "Program error with unknown code: #{code}"
+        end
+      end
+    end
+  end
+end

data/lib/solrengine/programs/idl_parser.rb

@@ -0,0 +1,151 @@
+require "json"
+
+module Solrengine
+  module Programs
+    class IdlParser
+      class UnsupportedVersionError < Error; end
+
+      SUPPORTED_SPEC = "0.1.0"
+
+      ParsedIdl = Struct.new(
+        :program_id, :name, :version, :instructions, :accounts, :types, :errors,
+        keyword_init: true
+      )
+
+      ParsedInstruction = Struct.new(
+        :name, :discriminator, :accounts, :args,
+        keyword_init: true
+      )
+
+      ParsedAccount = Struct.new(
+        :name, :discriminator, :fields,
+        keyword_init: true
+      )
+
+      ParsedType = Struct.new(
+        :name, :kind, :fields,
+        keyword_init: true
+      )
+
+      ParsedField = Struct.new(
+        :name, :type,
+        keyword_init: true
+      )
+
+      ParsedAccountMeta = Struct.new(
+        :name, :writable, :signer, :address, :relations,
+        keyword_init: true
+      )
+
+      ParsedError = Struct.new(
+        :code, :name, :message,
+        keyword_init: true
+      )
+
+      def self.parse(json_string)
+        new(json_string).parse
+      end
+
+      def self.parse_file(path)
+        parse(File.read(path))
+      end
+
+      def initialize(json_string)
+        @data = JSON.parse(json_string)
+      end
+
+      def parse
+        validate_spec_version!
+
+        ParsedIdl.new(
+          program_id: @data["address"],
+          name: @data.dig("metadata", "name"),
+          version: @data.dig("metadata", "version"),
+          instructions: parse_instructions,
+          accounts: parse_accounts,
+          types: parse_types,
+          errors: parse_errors
+        )
+      end
+
+      private
+
+      def validate_spec_version!
+        spec = @data.dig("metadata", "spec")
+        unless spec == SUPPORTED_SPEC
+          raise UnsupportedVersionError,
+            "Unsupported Anchor IDL spec version '#{spec}'. Expected '#{SUPPORTED_SPEC}'."
+        end
+      end
+
+      def parse_instructions
+        (@data["instructions"] || []).map do |ix|
+          ParsedInstruction.new(
+            name: ix["name"],
+            discriminator: ix["discriminator"]&.pack("C*"),
+            accounts: parse_account_metas(ix["accounts"] || []),
+            args: parse_fields(ix["args"] || [])
+          )
+        end
+      end
+
+      def parse_accounts
+        types_by_name = (@data["types"] || []).each_with_object({}) do |t, h|
+          h[t["name"]] = t
+        end
+
+        (@data["accounts"] || []).map do |acct|
+          type_def = types_by_name[acct["name"]]
+          fields = type_def ? parse_fields(type_def.dig("type", "fields") || []) : []
+
+          ParsedAccount.new(
+            name: acct["name"],
+            discriminator: acct["discriminator"]&.pack("C*"),
+            fields: fields
+          )
+        end
+      end
+
+      def parse_types
+        (@data["types"] || []).map do |t|
+          ParsedType.new(
+            name: t["name"],
+            kind: t.dig("type", "kind"),
+            fields: parse_fields(t.dig("type", "fields") || [])
+          )
+        end
+      end
+
+      def parse_errors
+        (@data["errors"] || []).map do |err|
+          ParsedError.new(
+            code: err["code"],
+            name: err["name"],
+            message: err["msg"]
+          )
+        end
+      end
+
+      def parse_fields(fields)
+        fields.map do |f|
+          ParsedField.new(
+            name: f["name"],
+            type: f["type"]
+          )
+        end
+      end
+
+      def parse_account_metas(accounts)
+        accounts.map do |acct|
+          ParsedAccountMeta.new(
+            name: acct["name"],
+            writable: acct["writable"] || false,
+            signer: acct["signer"] || false,
+            address: acct["address"],
+            relations: acct["relations"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/solrengine/programs/instruction.rb

@@ -0,0 +1,132 @@
+module Solrengine
+  module Programs
+    class Instruction
+      attr_reader :errors
+
+      class << self
+        def program_id(id = nil)
+          if id
+            @program_id = id
+          else
+            @program_id
+          end
+        end
+
+        def argument(name, type)
+          arguments_list << { name: name.to_sym, type: type }
+          attr_accessor name
+        end
+
+        def account(name, signer: false, writable: false, address: nil)
+          accounts_list << {
+            name: name.to_sym,
+            signer: signer,
+            writable: writable,
+            address: address
+          }
+          attr_accessor name unless address
+        end
+
+        def arguments_list
+          @arguments_list ||= []
+        end
+
+        def accounts_list
+          @accounts_list ||= []
+        end
+
+        def discriminator
+          BorshTypes::Discriminator.for_instruction(anchor_instruction_name)
+        end
+
+        # Set the Anchor instruction name used for discriminator computation.
+        # If not set, derives from class name: "LockInstruction" -> "lock"
+        def instruction_name(name_override = nil)
+          if name_override
+            @instruction_name = name_override
+          else
+            @instruction_name
+          end
+        end
+
+        def anchor_instruction_name
+          @instruction_name || begin
+            short_name = name&.split("::")&.last || ""
+            short_name.sub(/Instruction$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+          end
+        end
+      end
+
+      def initialize(attributes = {})
+        @errors = []
+        attributes.each do |key, value|
+          send(:"#{key}=", value) if respond_to?(:"#{key}=")
+        end
+      end
+
+      def valid?
+        @errors = []
+        validate_arguments
+        validate_accounts
+        @errors.empty?
+      end
+
+      # Build the instruction data: 8-byte discriminator + Borsh-encoded arguments
+      def instruction_data
+        data = Borsh::Buffer.open do |buf|
+          # Write discriminator
+          buf.write(self.class.discriminator)
+
+          # Write each argument
+          self.class.arguments_list.each do |arg|
+            value = send(arg[:name])
+            BorshTypes.write_field(buf, arg[:type], value)
+          end
+        end
+
+        data
+      end
+
+      # Build the instruction hash suitable for TransactionBuilder
+      def to_instruction
+        {
+          program_id: self.class.program_id,
+          accounts: build_account_metas,
+          data: instruction_data
+        }
+      end
+
+      private
+
+      def validate_arguments
+        self.class.arguments_list.each do |arg|
+          value = send(arg[:name])
+          if value.nil?
+            @errors << "#{arg[:name]} is required"
+          end
+        end
+      end
+
+      def validate_accounts
+        self.class.accounts_list.each do |acct|
+          next if acct[:address] # static addresses don't need to be set
+          value = send(acct[:name])
+          if value.nil?
+            @errors << "Account #{acct[:name]} is required"
+          end
+        end
+      end
+
+      def build_account_metas
+        self.class.accounts_list.map do |acct|
+          pubkey = acct[:address] || send(acct[:name])
+          {
+            pubkey: pubkey,
+            is_signer: acct[:signer],
+            is_writable: acct[:writable]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/solrengine/programs/pda.rb

@@ -0,0 +1,99 @@
+require "digest"
+require "base58"
+
+module Solrengine
+  module Programs
+    module Pda
+      # Ed25519 curve order
+      ED25519_ORDER = 2**252 + 27742317777372353535851937790883648493
+
+      # Find a valid Program Derived Address by iterating bump seeds from 255 down to 0.
+      # Returns [address_base58, bump].
+      def self.find_program_address(seeds, program_id)
+        255.downto(0) do |bump|
+          address = create_program_address(seeds + [ bump.chr ], program_id)
+          return [ address, bump ] if address
+        end
+
+        raise Error, "Could not find a valid PDA for the given seeds"
+      end
+
+      # Create a program address from seeds. Returns nil if the address is on the Ed25519 curve.
+      def self.create_program_address(seeds, program_id)
+        program_id_bytes = Base58.base58_to_binary(program_id, :bitcoin)
+
+        hash_input = seeds.map { |s| seed_bytes(s) }.join
+        hash_input += program_id_bytes
+        hash_input += "ProgramDerivedAddress"
+
+        hash = Digest::SHA256.digest(hash_input)
+
+        # Reject if the hash is a valid Ed25519 point (on-curve)
+        return nil if on_curve?(hash)
+
+        Base58.binary_to_base58(hash, :bitcoin)
+      end
+
+      # Convert a value to seed bytes based on type
+      def self.to_seed(value, type = :raw)
+        case type
+        when :string
+          value.encode("UTF-8").b
+        when :pubkey
+          Base58.base58_to_binary(value, :bitcoin)
+        when :u8
+          [ value ].pack("C")
+        when :u16
+          [ value ].pack("v")
+        when :u32
+          [ value ].pack("V")
+        when :u64
+          [ value ].pack("Q<")
+        when :raw
+          value.is_a?(String) ? value.b : value
+        else
+          raise Error, "Unknown seed type: #{type}"
+        end
+      end
+
+      # Check if a 32-byte hash is on the Ed25519 curve.
+      # Uses a simplified check: try to decompress the y-coordinate.
+      def self.on_curve?(bytes)
+        # Interpret as little-endian integer (Ed25519 uses little-endian)
+        y = bytes.unpack("C*").each_with_index.sum { |byte, i| byte << (8 * i) }
+        y_squared = y * y
+        p = 2**255 - 19
+
+        # x² = (y² - 1) / (d·y² + 1) mod p
+        # d = -121665/121666 mod p
+        d = (-121665 * mod_inverse(121666, p)) % p
+        numerator = (y_squared - 1) % p
+        denominator = (d * y_squared + 1) % p
+
+        # x² = numerator * denominator^(-1) mod p
+        x_squared = (numerator * mod_inverse(denominator, p)) % p
+
+        # Check if x² has a square root mod p
+        # Using Euler's criterion: x^((p-1)/2) ≡ 1 (mod p) means it's a QR
+        x_squared.pow((p - 1) / 2, p) == 1
+      end
+      private_class_method :on_curve?
+
+      def self.mod_inverse(a, m)
+        a.pow(m - 2, m)
+      end
+      private_class_method :mod_inverse
+
+      def self.seed_bytes(seed)
+        if seed.is_a?(String)
+          seed.b
+        elsif seed.is_a?(Array)
+          seed.pack("C*")
+        else
+          seed.to_s.b
+        end
+      end
+      private_class_method :seed_bytes
+    end
+  end
+end