solrengine-programs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 241673d21a1e7e5e8df9b93bf9d8ecdefbc7a0721833d5a6e6f0b9b02923a846
+  data.tar.gz: 84dd1fdbf4caba59e9b044b5754af24a035eb71ea5601616248a59f2d5a1eccd
+SHA512:
+  metadata.gz: facd125073ab5a9cfe9b267a9e7457367965263e67e4a6ae1ea1d18226b00e6f9119afa3147cc9544e63740589358673a2e4c01f78350d0b44a3b98d0c81b4aa
+  data.tar.gz: 62f4f89cf129ca4dfee131f6b4694dfc70fea9e99c3c215cfb6394287ad367c31cfed7fc8903d1c2d458cd84a25cdcd7b36f32673c8d7b07234536c009ab97b1

data/README.md

@@ -0,0 +1,130 @@
+# SolRengine Programs
+
+Solana program interaction for Rails. Parse Anchor IDL files to generate Ruby account models, instruction builders, and Stimulus controllers.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "solrengine-programs"
+```
+
+## Usage
+
+### Generate from Anchor IDL
+
+```bash
+rails generate solrengine:program PiggyBank path/to/piggy_bank.json
+```
+
+This creates:
+- `app/models/piggy_bank/lock.rb` — Account model with Borsh decoding
+- `app/services/piggy_bank/lock_instruction.rb` — Instruction builder
+- `app/services/piggy_bank/unlock_instruction.rb` — Instruction builder
+- `app/javascript/controllers/piggy_bank_controller.js` — Stimulus controller
+- `config/idl/piggy_bank.json` — IDL copy
+
+### Query Program Accounts
+
+```ruby
+class PiggyBank::Lock < Solrengine::Programs::Account
+  program_id "ZaU8j7XCKSxmmkMvg7NnjrLNK6eiLZbHsJQAc2rFzEN"
+  account_name "Lock"
+
+  borsh_field :dst, "pubkey"
+  borsh_field :exp, "u64"
+
+  def self.for_wallet(wallet_address)
+    query(filters: [
+      { "memcmp" => { "offset" => 8, "bytes" => wallet_address } }
+    ])
+  end
+
+  def expired?
+    exp < Time.now.to_i
+  end
+end
+
+# Query accounts
+locks = PiggyBank::Lock.for_wallet("YourWalletAddress...")
+locks.each do |lock|
+  puts "#{lock.pubkey}: #{lock.sol_balance} SOL, expires #{Time.at(lock.exp)}"
+end
+```
+
+### Build Instructions (Server-Side)
+
+```ruby
+class PiggyBank::LockInstruction < Solrengine::Programs::Instruction
+  program_id "ZaU8j7XCKSxmmkMvg7NnjrLNK6eiLZbHsJQAc2rFzEN"
+  instruction_name "lock"
+
+  argument :amt, "u64"
+  argument :exp, "u64"
+
+  account :payer, signer: true, writable: true
+  account :dst
+  account :lock, signer: true, writable: true
+  account :system_program, address: "11111111111111111111111111111111"
+end
+
+# Build and send a transaction
+ix = PiggyBank::LockInstruction.new(
+  amt: 100_000_000,
+  exp: (Time.now + 5.minutes).to_i,
+  payer: payer_pubkey,
+  dst: destination_pubkey,
+  lock: lock_keypair_pubkey
+)
+
+builder = Solrengine::Programs::TransactionBuilder.new
+builder.add_instruction(ix)
+builder.add_signer(server_keypair)
+signature = builder.sign_and_send
+```
+
+### PDA Derivation
+
+```ruby
+address, bump = Solrengine::Programs::Pda.find_program_address(
+  ["vault", Solrengine::Programs::Pda.to_seed(user_pubkey, :pubkey)],
+  program_id
+)
+```
+
+### Error Mapping
+
+```ruby
+idl = Solrengine::Programs::IdlParser.parse_file("config/idl/piggy_bank.json")
+mapper = Solrengine::Programs::ErrorMapper.new(idl.errors)
+
+begin
+  builder.sign_and_send
+rescue Solrengine::Programs::TransactionError => e
+  mapper.raise_if_program_error!(e.rpc_error)
+  # Raises: ProgramError "LockNotExpired (6002): Lock has not expired yet"
+end
+```
+
+### Configuration
+
+```ruby
+# config/initializers/solrengine_programs.rb
+Solrengine::Programs.configure do |config|
+  config.keypair_format = :base58  # or :json_array
+end
+```
+
+Set `SOLANA_KEYPAIR` environment variable for server-side transaction signing.
+
+## Dependencies
+
+- [solrengine-rpc](https://github.com/solrengine/rpc) — Solana RPC client
+- [borsh](https://github.com/dryruby/borsh.rb) — Borsh binary serialization
+- [ed25519](https://github.com/RubyCrypto/ed25519) — Transaction signing
+- [base58](https://github.com/dougal/base58) — Address encoding
+
+## License
+
+MIT

data/lib/generators/solrengine/program/program_generator.rb

@@ -0,0 +1,101 @@
+require "rails/generators"
+
+module Solrengine
+  module Generators
+    class ProgramGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :program_name, type: :string, desc: "Program name (e.g., PiggyBank)"
+      argument :idl_path, type: :string, desc: "Path to Anchor IDL JSON file"
+
+      def parse_idl
+        unless File.exist?(idl_path)
+          raise Thor::Error, "IDL file not found: #{idl_path}"
+        end
+
+        @idl = Solrengine::Programs::IdlParser.parse_file(idl_path)
+        say "Parsed IDL: #{@idl.name} (#{@idl.instructions.size} instructions, #{@idl.accounts.size} accounts)"
+      end
+
+      def copy_idl
+        destination = "config/idl/#{program_snake}.json"
+        if File.exist?(File.join(destination_root, destination))
+          say_skipped(destination)
+        else
+          copy_file idl_path, destination
+        end
+      end
+
+      def create_account_models
+        @idl.accounts.each do |account|
+          destination = "app/models/#{program_snake}/#{account.name.underscore}.rb"
+          if File.exist?(File.join(destination_root, destination))
+            say_skipped(destination)
+          else
+            @account = account
+            @program_id = @idl.program_id
+            template "account.rb.erb", destination
+          end
+        end
+      end
+
+      def create_instruction_builders
+        @idl.instructions.each do |instruction|
+          destination = "app/services/#{program_snake}/#{instruction.name}_instruction.rb"
+          if File.exist?(File.join(destination_root, destination))
+            say_skipped(destination)
+          else
+            @instruction = instruction
+            @program_id = @idl.program_id
+            template "instruction.rb.erb", destination
+          end
+        end
+      end
+
+      def create_stimulus_controller
+        destination = "app/javascript/controllers/#{program_snake}_controller.js"
+        if File.exist?(File.join(destination_root, destination))
+          say_skipped(destination)
+        else
+          @idl_instance = @idl
+          template "stimulus_controller.js.erb", destination
+        end
+      end
+
+      def show_summary
+        say ""
+        say "Program '#{program_class}' generated successfully!", :green
+        say ""
+        say "Generated files:"
+        say "  config/idl/#{program_snake}.json"
+        @idl.accounts.each do |acct|
+          say "  app/models/#{program_snake}/#{acct.name.underscore}.rb"
+        end
+        @idl.instructions.each do |ix|
+          say "  app/services/#{program_snake}/#{ix.name}_instruction.rb"
+        end
+        say "  app/javascript/controllers/#{program_snake}_controller.js"
+        say ""
+        say "Next steps:"
+        say "  1. Add custom query methods to your account models"
+        say "  2. Register the Stimulus controller in your index.js"
+        say "  3. Create Rails controller endpoints for instruction building"
+      end
+
+      private
+
+      def program_class
+        program_name.camelize
+      end
+
+      def program_snake
+        program_name.underscore
+      end
+
+      def say_skipped(path)
+        say "  skip  #{path} (already exists)", :yellow
+        say "        Re-run with different name or manually update the file"
+      end
+    end
+  end
+end

data/lib/generators/solrengine/program/templates/account.rb.erb

@@ -0,0 +1,15 @@
+class <%= program_class %>::<%= @account.name %> < Solrengine::Programs::Account
+  program_id "<%= @program_id %>"
+  account_name "<%= @account.name %>"
+
+<% @account.fields.each do |field| -%>
+  borsh_field :<%= field.name %>, <%= field.type.is_a?(String) ? "\"#{field.type}\"" : field.type.inspect %>
+<% end -%>
+
+  # Add custom query methods, e.g.:
+  # def self.for_wallet(wallet_address)
+  #   query(filters: [
+  #     { "memcmp" => { "offset" => 8, "bytes" => wallet_address } }
+  #   ])
+  # end
+end

data/lib/generators/solrengine/program/templates/instruction.rb.erb

@@ -0,0 +1,12 @@
+class <%= program_class %>::<%= @instruction.name.camelize %>Instruction < Solrengine::Programs::Instruction
+  program_id "<%= @program_id %>"
+  instruction_name "<%= @instruction.name %>"
+
+<% @instruction.args.each do |arg| -%>
+  argument :<%= arg.name %>, <%= arg.type.is_a?(String) ? "\"#{arg.type}\"" : arg.type.inspect %>
+<% end -%>
+
+<% @instruction.accounts.each do |acct| -%>
+  account :<%= acct.name %><%= ", signer: true" if acct.signer %><%= ", writable: true" if acct.writable %><%= ", address: \"#{acct.address}\"" if acct.address %>
+<% end -%>
+end

data/lib/generators/solrengine/program/templates/stimulus_controller.js.erb

@@ -0,0 +1,171 @@
+import { Controller } from "@hotwired/stimulus"
+import { getWallets } from "@wallet-standard/app"
+import { SolanaSignAndSendTransaction } from "@solana/wallet-standard-features"
+import {
+  pipe,
+  createTransactionMessage,
+  setTransactionMessageLifetimeUsingBlockhash,
+  setTransactionMessageFeePayer,
+  appendTransactionMessageInstruction,
+  compileTransaction,
+  getBase64EncodedWireTransaction,
+  address
+} from "@solana/kit"
+
+// Generated Stimulus controller for <%= @idl_instance.name %> program
+// Program ID: <%= @idl_instance.program_id %>
+//
+// This controller follows the server-built instruction pattern:
+// 1. User fills form → controller sends params to Rails endpoint
+// 2. Rails builds Borsh-encoded instruction data + fetches blockhash
+// 3. Returns instruction data + account metas + blockhash as JSON
+// 4. Controller constructs transaction, wallet signs and sends
+// 5. Reports signature back to server
+export default class extends Controller {
+  static targets = ["status"]
+  static values = {
+    programId: { type: String, default: "<%= @idl_instance.program_id %>" },
+    chain: { type: String, default: "solana:devnet" }
+  }
+
+  connect() {
+    this.wallet = null
+    this.discoverWallet()
+  }
+
+  discoverWallet() {
+    const { get, on } = getWallets()
+    const wallets = get()
+
+    for (const wallet of wallets) {
+      if (wallet.features[SolanaSignAndSendTransaction]) {
+        this.wallet = wallet
+        return
+      }
+    }
+
+    on("register", (...newWallets) => {
+      for (const wallet of newWallets) {
+        if (wallet.features[SolanaSignAndSendTransaction]) {
+          this.wallet = wallet
+          return
+        }
+      }
+    })
+  }
+
+<% @idl_instance.instructions.each do |ix| -%>
+  // Submit '<%= ix.name %>' instruction
+  async <%= ix.name.camelize(:lower) %>(event) {
+    event?.preventDefault()
+    if (!this.wallet) {
+      this.showStatus("No wallet found", "error")
+      return
+    }
+
+    try {
+      this.showStatus("Building transaction...", "pending")
+
+      // Get instruction data from server
+      const response = await this.buildInstruction("<%= ix.name %>", event?.target)
+      if (!response.ok) {
+        const error = await response.json()
+        this.showStatus(error.message || "Failed to build instruction", "error")
+        return
+      }
+
+      const { instruction_data, accounts, blockhash, last_valid_block_height } = await response.json()
+
+      // Build and sign transaction via wallet
+      const signature = await this.signAndSend({
+        instructionData: instruction_data,
+        accounts,
+        blockhash,
+        lastValidBlockHeight: last_valid_block_height
+      })
+
+      this.showStatus(`Transaction sent: ${signature.slice(0, 8)}...`, "success")
+
+      // Report signature to server for confirmation tracking
+      this.reportSignature("<%= ix.name %>", signature)
+    } catch (error) {
+      this.showStatus(error.message, "error")
+    }
+  }
+
+<% end -%>
+  async buildInstruction(name, form) {
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content
+    const formData = form ? new FormData(form) : new FormData()
+    formData.append("instruction", name)
+
+    return fetch(`/<%= @idl_instance.name %>/instructions`, {
+      method: "POST",
+      headers: { "X-CSRF-Token": csrfToken },
+      body: formData
+    })
+  }
+
+  async signAndSend({ instructionData, accounts, blockhash, lastValidBlockHeight }) {
+    const walletAccount = this.wallet.accounts.find(a =>
+      a.chains.includes(this.chainValue)
+    )
+    if (!walletAccount) throw new Error("No account for chain: " + this.chainValue)
+
+    const feature = this.wallet.features[SolanaSignAndSendTransaction]
+    const instructionBytes = Uint8Array.from(atob(instructionData), c => c.charCodeAt(0))
+
+    const instruction = {
+      programAddress: address(this.programIdValue),
+      accounts: accounts.map(a => ({
+        address: address(a.pubkey),
+        role: this.accountRole(a)
+      })),
+      data: instructionBytes
+    }
+
+    const txMessage = pipe(
+      createTransactionMessage({ version: "legacy" }),
+      m => setTransactionMessageFeePayer(address(walletAccount.address), m),
+      m => setTransactionMessageLifetimeUsingBlockhash(
+        { blockhash: blockhash, lastValidBlockHeight: BigInt(lastValidBlockHeight) },
+        m
+      ),
+      m => appendTransactionMessageInstruction(instruction, m)
+    )
+
+    const compiled = compileTransaction(txMessage)
+    const wireTransaction = getBase64EncodedWireTransaction(compiled)
+
+    const [{ signature }] = await feature.signAndSendTransaction(walletAccount, [
+      { transaction: wireTransaction, chain: this.chainValue }
+    ])
+
+    return typeof signature === "string" ? signature : new TextDecoder().decode(signature)
+  }
+
+  reportSignature(instructionName, signature) {
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content
+    fetch(`/<%= @idl_instance.name %>/signatures`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-CSRF-Token": csrfToken
+      },
+      body: JSON.stringify({ instruction: instructionName, signature })
+    }).catch(() => {}) // Best effort
+  }
+
+  accountRole(account) {
+    if (account.is_signer && account.is_writable) return 0x03 // WRITABLE_SIGNER
+    if (account.is_signer) return 0x02 // READONLY_SIGNER
+    if (account.is_writable) return 0x01 // WRITABLE
+    return 0x00 // READONLY
+  }
+
+  showStatus(message, type) {
+    if (!this.hasStatusTarget) return
+    this.statusTarget.textContent = message
+    this.statusTarget.className = `status-${type}`
+  }
+}

data/lib/solrengine/programs/account.rb

@@ -0,0 +1,157 @@
+require "base64"
+
+module Solrengine
+  module Programs
+    class Account
+      include ActiveModel::Model if defined?(ActiveModel)
+
+      attr_reader :pubkey, :lamports
+
+      class << self
+        def program_id(id = nil)
+          if id
+            @program_id = id
+          else
+            @program_id
+          end
+        end
+
+        # Set the Anchor account name used for discriminator computation.
+        # If not set, defaults to the unqualified Ruby class name.
+        def account_name(name = nil)
+          if name
+            @account_name = name
+          else
+            @account_name || self.name&.split("::")&.last
+          end
+        end
+
+        def borsh_field(name, type, **options)
+          borsh_fields << { name: name.to_sym, type: type, **options }
+
+          # Define attribute accessor
+          attr_accessor name
+        end
+
+        def borsh_fields
+          @borsh_fields ||= []
+        end
+
+        def discriminator
+          BorshTypes::Discriminator.for_account(account_name)
+        end
+
+        # Query program accounts via RPC with memcmp filters.
+        # At least one user-provided filter is required to prevent unbounded queries.
+        def query(filters: [], commitment: "confirmed")
+          if filters.empty?
+            raise Error, "At least one memcmp filter is required to prevent unbounded getProgramAccounts queries"
+          end
+
+          # Build full filter list: dataSize + discriminator + user filters
+          all_filters = build_filters(filters)
+
+          result = Solrengine::Rpc.client.request("getProgramAccounts", [
+            program_id,
+            {
+              "encoding" => "base64",
+              "commitment" => commitment,
+              "filters" => all_filters
+            }
+          ])
+
+          accounts = result.dig("result") || []
+
+          accounts.filter_map do |account_data|
+            pubkey = account_data["pubkey"]
+            data_base64 = account_data.dig("account", "data", 0)
+            lamports = account_data.dig("account", "lamports")
+
+            next unless data_base64
+
+            begin
+              from_account_data(pubkey, data_base64, lamports: lamports)
+            rescue DeserializationError, ArgumentError, RangeError => e
+              if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+                Rails.logger.warn("Skipping malformed account #{pubkey}: #{e.message}")
+              end
+              nil
+            end
+          end
+        end
+
+        # Decode a single account from base64 data
+        def from_account_data(pubkey, data_base64, lamports: 0)
+          raw = Base64.decode64(data_base64)
+
+          # Skip empty/closed accounts
+          if raw.empty? || raw.bytesize < 8
+            raise DeserializationError, "Account data too short (#{raw.bytesize} bytes)"
+          end
+
+          # Skip 8-byte discriminator
+          account_data = raw[8..]
+          buffer = Borsh::Buffer.new(account_data)
+
+          instance = new
+          instance.instance_variable_set(:@pubkey, pubkey)
+          instance.instance_variable_set(:@lamports, lamports)
+
+          borsh_fields.each do |field|
+            value = BorshTypes.read_field(buffer, field[:type])
+            instance.send(:"#{field[:name]}=", value)
+          end
+
+          instance
+        end
+
+        private
+
+        def build_filters(user_filters)
+          filters = []
+
+          # Add dataSize filter if all fields have known sizes
+          data_size = calculate_data_size
+          filters << { "dataSize" => data_size } if data_size
+
+          # Add discriminator memcmp filter
+          disc = discriminator
+          if disc
+            disc_base58 = Base58.binary_to_base58(disc, :bitcoin)
+            filters << {
+              "memcmp" => {
+                "offset" => 0,
+                "bytes" => disc_base58,
+                "encoding" => "base58"
+              }
+            }
+          end
+
+          filters + user_filters
+        end
+
+        def calculate_data_size
+          total = 8 # discriminator
+          borsh_fields.each do |field|
+            size = BorshTypes.field_size(field[:type])
+            return nil unless size # variable-length field makes total unknown
+            total += size
+          end
+          total
+        end
+      end
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          send(:"#{key}=", value) if respond_to?(:"#{key}=")
+        end
+      end
+
+      # SOL balance of this account
+      def sol_balance
+        return 0 unless lamports
+        lamports.to_f / 1_000_000_000
+      end
+    end
+  end
+end