solana-studio 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39e8967f873b252f8204b4ff0be0a011b813f3744b2ee9c308b1e73740e9ca2a
+  data.tar.gz: 769171e5fd595cba388702be0e4dd6b1f9f46545451624393543ef329b2cc402
+SHA512:
+  metadata.gz: '00851cd448aecb996b636f91ab2bf19192a0d64966223a06633b52584c38116ff32f3a163433a50a4299d15a72196426d14e65cb5aee599a0b71a98728f340ab'
+  data.tar.gz: 7fcbc86d1194c63055bf14f7fd3c23f1d117c872e295a9e20557fbf8528f20b88be991ac4daae0d276ac10b790037b98c52315170d8323d1082b2b072ce96136

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.4.1 (2026-05-17)
+
+Pre-public-release security hardening per `SECURITY-AUDIT-2026-05-17.md`.
+
+### Fixed (security)
+- **TLS enforcement in `Solana::Client`** — explicit `OpenSSL::SSL::VERIFY_PEER` and `TLS1_2_VERSION` minimum on every HTTPS RPC connection. Belt-and-suspenders against future downstream Net::HTTP regressions.
+- **HTTPS-only RPC URL validation** — `Solana::Client` constructor now raises `Solana::Client::InsecureRpcUrlError` on `http://` URLs unless the host is `localhost`/`127.0.0.1`/`::1`. Prevents cleartext RPC traffic to public providers.
+- **Borsh allocation-bomb guard** — `Solana::Borsh::MAX_DECODED_FIELD_BYTES = 10MB`. New `decode_string` + `decode_vec` helpers check the length prefix before allocating; raise `Solana::Borsh::DecodedFieldTooLarge` on overage. Protects callers from corrupt or malicious RPC responses.
+- **Constant-time nonce compare in `Solana::AuthVerifier`** — `OpenSSL.fixed_length_secure_compare` replaces Ruby string `==`. Removes a (low-practical-impact) timing side channel.
+- **Pubkey + signature length validation in `Solana::AuthVerifier.verify!`** — explicit checks before `Ed25519::VerifyKey.new` so malformed inputs raise `VerificationError("Public key must be 32 bytes...")` instead of being masked by the generic `"Signature verification failed"` catch-all.
+- **Base58 input validation in `Solana::Keypair.decode_base58`** — explicit alphabet check raises `ArgumentError` with a clear message on invalid chars (`0`, `O`, `I`, `l`) instead of producing a confusing `TypeError` deep in the multiplication loop.
+
+### Changed
+- `Solana::AuthVerifier` docstring now loudly states caller's responsibility for nonce invalidation (delete-before-verify pattern) and links to the canonical Rails session-adapter at `turf-monster/app/controllers/concerns/solana/session_auth.rb`.
+- Gemspec author email changed from `alex@mcritchie.studio` (personal) to `solana-studio@mcritchie.studio` (project alias).
+
+## v0.4.0 (2026-05-17)
+
+### Changed (breaking)
+- **Gem renamed from `solana_studio` to `solana-studio`.** Repo URL is now `github.com/amcritchie/solana-studio` (was `.../solana_studio`). Consumers must update their `Gemfile`:
+  ```ruby
+  # Before:
+  gem "solana_studio", git: "https://github.com/amcritchie/solana_studio.git", tag: "v0.3.0"
+  # After:
+  gem "solana-studio", git: "https://github.com/amcritchie/solana-studio.git", tag: "v0.4.0"
+  ```
+- The Ruby `SolanaStudio` module name and the `Solana::*` namespace are **unchanged** — all call sites keep working without code changes.
+- Gem entry point at `lib/solana-studio.rb` (a thin `require_relative "solana_studio"` shim) ensures `gem "solana-studio"` auto-requires correctly without a `require:` option in the Gemfile.
+
+### Added
+- gemspec `metadata` (homepage / source / bugs / changelog URIs) — getting ready for RubyGems publishing.
+
+## v0.3.0 (2026-05-17)
+
+### Added
+- **`Solana::AuthVerifier`** — pure module for verifying Phantom wallet signatures against an externally-stored nonce. Extracted from turf-monster's `app/services/solana/auth_verifier.rb`. Host apps keep a thin session adapter that delegates to `Solana::AuthVerifier.verify!`.
+- `Solana::AuthVerifier::VerificationError`, `Solana::AuthVerifier::NONCE_MAX_AGE` constants now live in the gem.
+- Updated CLAUDE.md with the gem-vs-app split rule for Solana code.
+
+### Fixed
+- gemspec `spec.version` was bumped to "0.3.0" after the initial release (had been mistakenly left at "0.2.0").
+
+## v0.2.0 (2026-04-03)
+
+- SPL Token instruction builders (`create_associated_token_account`, `mint_to`, `transfer`)
+- Test suite: Keypair, Borsh, and Transaction tests (9 tests)
+- Updated CLAUDE.md with test documentation
+
+## v0.1.0 (2026-04-02)
+
+- Initial release
+- `Solana::Client` — JSON-RPC over HTTP with retry logic
+- `Solana::Keypair` — Ed25519 keygen, base58, sign, `from_base58` for env var loading
+- `Solana::Borsh` — encode/decode primitives (u8, u16, u32, u64, i64, pubkey, string, vec, bool)
+- `Solana::Transaction` — transaction builder, PDA derivation, Anchor discriminators, on_curve? check

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex McRitchie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# SolanaStudio
+
+Ruby primitives for building on Solana — JSON-RPC client, Ed25519 keypairs, Borsh serialization, and transaction builder with PDA derivation.
+
+> **Part of the McRitchie ecosystem** — see [`ECOSYSTEM.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/ECOSYSTEM.md) for the 5-repo map; [`house-burn-down.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/agents/system/house-burn-down.md) for fresh-Mac recovery.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "solana-studio", git: "https://github.com/amcritchie/solana-studio.git"
+```
+
+## Usage
+
+### Keypair
+
+```ruby
+require "solana-studio"
+
+# Generate a new keypair
+kp = Solana::Keypair.generate
+kp.address          # => "9Fy8P3DvKBh3awt1wr27g4CDh47oDqmJR2FAAQ1bc69D"
+kp.to_bytes         # => 64-byte Solana format
+
+# Load from file or env
+kp = Solana::Keypair.from_json_file("~/.config/solana/id.json")
+kp = Solana::Keypair.from_base58(ENV["SOLANA_ADMIN_KEY"])
+
+# Sign a message
+signature = kp.sign("hello".b)
+```
+
+### Client (JSON-RPC)
+
+```ruby
+client = Solana::Client.new(rpc_url: "https://api.devnet.solana.com")
+
+client.get_balance("9Fy8P3DvKBh3awt...")
+client.get_latest_blockhash
+client.request_airdrop("9Fy8P3DvKBh3awt...", 1_000_000_000)
+client.send_and_confirm(signed_tx_base64)
+```
+
+### Borsh Serialization
+
+```ruby
+data = Solana::Borsh.encode_u64(1_000_000) +
+       Solana::Borsh.encode_string("hello") +
+       Solana::Borsh.encode_pubkey(kp.public_key_bytes)
+```
+
+### Transaction Builder
+
+```ruby
+tx = Solana::Transaction.new
+tx.set_recent_blockhash(client.get_latest_blockhash)
+tx.add_signer(keypair)
+tx.add_instruction(
+  program_id: "YourProgramId...",
+  accounts: [
+    { pubkey: keypair.public_key_bytes, is_signer: true, is_writable: true },
+    { pubkey: pda, is_signer: false, is_writable: true }
+  ],
+  data: Solana::Transaction.anchor_discriminator("your_instruction") + payload
+)
+
+signature = client.send_and_confirm(tx.serialize_base64)
+```
+
+### PDA Derivation
+
+```ruby
+pda, bump = Solana::Transaction.find_pda(
+  ["vault".b, wallet_pubkey_bytes],
+  program_id_bytes
+)
+```
+
+## Dependencies
+
+- `ed25519` (~> 1.3) — Ed25519 signing
+- Ruby stdlib only (net/http, json, digest, securerandom)
+
+## Development Notes
+
+See [CLAUDE.md](./CLAUDE.md) for detailed development context including the full API reference, design decisions, and AI agent instructions.
+
+## License
+
+MIT

data/lib/solana/auth_verifier.rb

@@ -0,0 +1,90 @@
+require "ed25519"
+require "openssl"
+
+module Solana
+  # Verifies a Solana wallet signature against an externally-stored nonce.
+  # Pure module — no Rails / no session coupling. Host apps adapt their
+  # session storage and call `Solana::AuthVerifier.verify!`.
+  #
+  # **IMPORTANT — caller is responsible for replay prevention.** The host
+  # MUST invalidate `stored_nonce` immediately after this method returns
+  # (success OR failure). The canonical Rails-session adapter pattern is:
+  #
+  #     stored_nonce = session.delete(:solana_nonce)
+  #     nonce_at     = session.delete(:solana_nonce_at)
+  #     Solana::AuthVerifier.verify!(
+  #       message: ..., signature_b58: ..., pubkey_b58: ...,
+  #       stored_nonce: stored_nonce, nonce_at: nonce_at
+  #     )
+  #
+  # The `session.delete(...)` BEFORE the verify! call is what prevents
+  # replay — once consumed, the nonce can never satisfy verify! again.
+  # See turf-monster `app/controllers/concerns/solana/session_auth.rb`
+  # for the production adapter.
+  module AuthVerifier
+    class VerificationError < StandardError; end
+
+    # Default max nonce age in seconds (5 minutes).
+    NONCE_MAX_AGE = 300
+
+    ED25519_PUBKEY_BYTES = 32
+    ED25519_SIGNATURE_BYTES = 64
+
+    # Verifies that `signature_b58` is a valid Ed25519 signature over
+    # `message` made by `pubkey_b58`, AND that the `Nonce: ...` field in
+    # the message matches `stored_nonce`, AND that the nonce is not stale.
+    #
+    # Returns the verified public key (base58 string) on success.
+    # Raises Solana::AuthVerifier::VerificationError on any failure.
+    #
+    # @param message [String] the signed message (must contain `Nonce: <value>`)
+    # @param signature_b58 [String] base58-encoded Ed25519 signature
+    # @param pubkey_b58 [String] base58-encoded public key
+    # @param stored_nonce [String, nil] the nonce the host issued + remembers
+    # @param nonce_at [Integer, nil] Unix timestamp when the nonce was issued
+    # @param max_age [Integer] seconds before a nonce expires (default 300)
+    def self.verify!(message:, signature_b58:, pubkey_b58:, stored_nonce:, nonce_at: nil, max_age: NONCE_MAX_AGE)
+      raise VerificationError, "No nonce provided" if stored_nonce.nil? || stored_nonce.empty?
+
+      if nonce_at && (Time.now.to_i - nonce_at.to_i) > max_age
+        raise VerificationError, "Nonce expired"
+      end
+
+      sig_bytes = Solana::Keypair.decode_base58(signature_b58)
+      pub_bytes = Solana::Keypair.decode_base58(pubkey_b58)
+
+      # Length-check BEFORE handing to Ed25519::VerifyKey to surface a clean
+      # error (instead of letting the library raise ArgumentError, which the
+      # rescue below would convert into a misleading "Signature verification
+      # failed" message).
+      unless pub_bytes.bytesize == ED25519_PUBKEY_BYTES
+        raise VerificationError, "Public key must be #{ED25519_PUBKEY_BYTES} bytes, got #{pub_bytes.bytesize}"
+      end
+      unless sig_bytes.bytesize == ED25519_SIGNATURE_BYTES
+        raise VerificationError, "Signature must be #{ED25519_SIGNATURE_BYTES} bytes, got #{sig_bytes.bytesize}"
+      end
+
+      verify_key = Ed25519::VerifyKey.new(pub_bytes)
+      verify_key.verify(sig_bytes, message)
+
+      claimed_nonce = message.match(/Nonce: (\w+)/)&.captures&.first
+      unless claimed_nonce && constant_time_eq?(claimed_nonce, stored_nonce)
+        raise VerificationError, "Invalid nonce"
+      end
+
+      pubkey_b58
+    rescue Ed25519::VerifyError => e
+      raise VerificationError, "Signature verification failed: #{e.message}"
+    end
+
+    # Constant-time string equality, sourced from OpenSSL's fixed_length_secure_compare
+    # (available since Ruby 2.5+). Returns false (not raise) if lengths differ.
+    # Used for nonce comparison so attackers can't time-leak match progress.
+    def self.constant_time_eq?(a, b)
+      a = a.to_s
+      b = b.to_s
+      return false unless a.bytesize == b.bytesize
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end

data/lib/solana/borsh.rb

@@ -0,0 +1,116 @@
+module Solana
+  module Borsh
+    # Cap on the bytes any single length-prefixed decode (vec, string) can
+    # claim. Malicious / corrupt RPC responses can carry a length field of
+    # e.g. 4_000_000_000, which without this guard would OOM the process
+    # when the caller allocates accordingly. 10MB is more than any sane
+    # Solana account / instruction payload — adjust per consumer needs.
+    MAX_DECODED_FIELD_BYTES = 10 * 1024 * 1024
+
+    class DecodedFieldTooLarge < StandardError; end
+
+    module_function
+
+    def encode_u8(value)
+      [value].pack("C")
+    end
+
+    def encode_u16(value)
+      [value].pack("v") # little-endian u16
+    end
+
+    def encode_u32(value)
+      [value].pack("V") # little-endian u32
+    end
+
+    def encode_u64(value)
+      [value].pack("Q<") # little-endian u64
+    end
+
+    def encode_i64(value)
+      [value].pack("q<") # little-endian i64
+    end
+
+    def encode_pubkey(pubkey_bytes)
+      pubkey_bytes = Keypair.decode_base58(pubkey_bytes) if pubkey_bytes.is_a?(String) && pubkey_bytes.length != 32
+      pubkey_bytes = pubkey_bytes.b if pubkey_bytes.is_a?(String)
+      raise "Pubkey must be 32 bytes, got #{pubkey_bytes.bytesize}" unless pubkey_bytes.bytesize == 32
+      pubkey_bytes
+    end
+
+    def encode_bytes32(bytes)
+      bytes = bytes.b if bytes.is_a?(String)
+      raise "Expected 32 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 32
+      bytes
+    end
+
+    def encode_vec(items, &block)
+      encoded_items = items.map { |item| block.call(item) }.join
+      encode_u32(items.length) + encoded_items
+    end
+
+    def encode_string(str)
+      bytes = str.encode("UTF-8").b
+      encode_u32(bytes.bytesize) + bytes
+    end
+
+    def encode_bool(value)
+      encode_u8(value ? 1 : 0)
+    end
+
+    # Decode helpers
+
+    def decode_u8(bytes, offset = 0)
+      [bytes.byteslice(offset, 1).unpack1("C"), offset + 1]
+    end
+
+    def decode_u16(bytes, offset = 0)
+      [bytes.byteslice(offset, 2).unpack1("v"), offset + 2]
+    end
+
+    def decode_u32(bytes, offset = 0)
+      [bytes.byteslice(offset, 4).unpack1("V"), offset + 4]
+    end
+
+    def decode_u64(bytes, offset = 0)
+      [bytes.byteslice(offset, 8).unpack1("Q<"), offset + 8]
+    end
+
+    def decode_pubkey(bytes, offset = 0)
+      [bytes.byteslice(offset, 32), offset + 32]
+    end
+
+    # Length-prefixed string. Reads u32 length then `length` bytes of UTF-8.
+    # Raises DecodedFieldTooLarge if the declared length exceeds the cap —
+    # protects callers from allocation-bomb DoS via crafted RPC responses.
+    def decode_string(bytes, offset = 0)
+      length, offset = decode_u32(bytes, offset)
+      check_field_length!(length, "string")
+      str = bytes.byteslice(offset, length).to_s.force_encoding("UTF-8")
+      [str, offset + length]
+    end
+
+    # Length-prefixed array. block is called per element with (bytes, offset)
+    # and must return [value, new_offset]. Bounded by MAX_DECODED_FIELD_BYTES
+    # on the declared count to prevent allocation-bomb DoS.
+    def decode_vec(bytes, offset = 0, &block)
+      length, offset = decode_u32(bytes, offset)
+      check_field_length!(length, "vec")
+      items = []
+      length.times do
+        item, offset = block.call(bytes, offset)
+        items << item
+      end
+      [items, offset]
+    end
+
+    def check_field_length!(length, kind)
+      if length > MAX_DECODED_FIELD_BYTES
+        raise DecodedFieldTooLarge,
+              "Borsh #{kind} declared length #{length} exceeds cap " \
+              "(MAX_DECODED_FIELD_BYTES=#{MAX_DECODED_FIELD_BYTES}). " \
+              "Likely a corrupt or malicious RPC response."
+      end
+    end
+  end
+end

data/lib/solana/client.rb

@@ -0,0 +1,182 @@
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module Solana
+  class Client
+    class RpcError < StandardError
+      attr_reader :code
+      def initialize(message, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+
+    class InsecureRpcUrlError < ArgumentError; end
+
+    MAX_RETRIES = 3
+    RETRY_DELAY = 1 # seconds
+
+    DEFAULT_RPC_URL = "https://api.devnet.solana.com"
+
+    # Hostnames where plain http:// is permitted (local testing only).
+    HTTP_OK_HOSTS = %w[localhost 127.0.0.1 ::1 0.0.0.0].freeze
+
+    def initialize(rpc_url: nil)
+      @rpc_url = rpc_url || ENV.fetch("SOLANA_RPC_URL", DEFAULT_RPC_URL)
+      @uri = URI.parse(@rpc_url)
+      validate_rpc_scheme!
+      @request_id = 0
+    end
+
+    def get_account_info(pubkey, encoding: "base64", commitment: nil)
+      config = { encoding: encoding }
+      config[:commitment] = commitment if commitment
+      call("getAccountInfo", [pubkey, config])
+    end
+
+    def get_token_account_balance(pubkey)
+      call("getTokenAccountBalance", [pubkey])
+    end
+
+    def get_latest_blockhash(commitment: "finalized")
+      result = call("getLatestBlockhash", [{ commitment: commitment }])
+      result.dig("value", "blockhash")
+    end
+
+    def get_minimum_balance_for_rent_exemption(size)
+      call("getMinimumBalanceForRentExemption", [size])
+    end
+
+    def send_transaction(signed_tx_base64, skip_preflight: false)
+      opts = { encoding: "base64", skipPreflight: skip_preflight }
+      call("sendTransaction", [signed_tx_base64, opts])
+    end
+
+    def confirm_transaction(signature, commitment: "confirmed")
+      call("getSignatureStatuses", [[signature], { searchTransactionHistory: true }])
+    end
+
+    def send_and_confirm(signed_tx_base64, timeout: 30, skip_preflight: false)
+      signature = send_transaction(signed_tx_base64, skip_preflight: skip_preflight)
+
+      deadline = Time.now + timeout
+      loop do
+        sleep 1
+        result = confirm_transaction(signature)
+        status = result.dig("value", 0)
+
+        if status
+          if status["err"]
+            raise RpcError.new("Transaction failed: #{status['err']}")
+          end
+          return signature if status["confirmationStatus"] == "confirmed" || status["confirmationStatus"] == "finalized"
+        end
+
+        raise RpcError.new("Transaction confirmation timeout") if Time.now > deadline
+      end
+    end
+
+    def request_airdrop(pubkey, lamports)
+      call("requestAirdrop", [pubkey, lamports])
+    end
+
+    def get_balance(pubkey)
+      call("getBalance", [pubkey])
+    end
+
+    def get_transaction(signature, commitment: "confirmed")
+      call("getTransaction", [signature, { encoding: "json", commitment: commitment }])
+    end
+
+    def get_token_accounts_by_owner(owner_pubkey)
+      call("getTokenAccountsByOwner", [
+        owner_pubkey,
+        { programId: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
+        { encoding: "jsonParsed" }
+      ])
+    end
+
+    private
+
+    def call(method, params = [])
+      @request_id += 1
+      body = {
+        jsonrpc: "2.0",
+        id: @request_id,
+        method: method,
+        params: params
+      }
+
+      retries = 0
+      begin
+        response = http_post(body)
+        parsed = JSON.parse(response.body)
+
+        if parsed["error"]
+          error = parsed["error"]
+          raise RpcError.new(error["message"], code: error["code"])
+        end
+
+        parsed["result"]
+      rescue RpcError => e
+        # Retry on rate limit (429) or blockhash expiry
+        if retries < MAX_RETRIES && retryable_error?(e)
+          retries += 1
+          sleep RETRY_DELAY * retries
+          retry
+        end
+        raise
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET => e
+        if retries < MAX_RETRIES
+          retries += 1
+          sleep RETRY_DELAY * retries
+          retry
+        end
+        raise RpcError.new("Network error: #{e.message}")
+      end
+    end
+
+    def http_post(body)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      if @uri.scheme == "https"
+        http.use_ssl = true
+        # Belt-and-suspenders: Net::HTTP defaults to VERIFY_PEER in modern Ruby
+        # but a) some older builds have shipped with weaker defaults and b)
+        # being explicit here protects against future regressions or downstream
+        # monkey-patches.
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.min_version = OpenSSL::SSL::TLS1_2_VERSION
+      end
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      request = Net::HTTP::Post.new(@uri.path.empty? ? "/" : @uri.path)
+      request["Content-Type"] = "application/json"
+      request.body = body.to_json
+
+      http.request(request)
+    end
+
+    def retryable_error?(error)
+      return true if error.code == 429 # rate limited
+      return true if error.message.include?("Blockhash not found")
+      false
+    end
+
+    # Reject plain http:// RPC URLs unless the host is local. Prevents
+    # accidental cleartext communication with public RPC providers.
+    def validate_rpc_scheme!
+      return if @uri.scheme == "https"
+      if @uri.scheme == "http" && HTTP_OK_HOSTS.include?(@uri.host.to_s.downcase)
+        return
+      end
+      raise InsecureRpcUrlError,
+            "Solana::Client requires an https:// RPC URL (got #{@rpc_url.inspect}). " \
+            "Plain http:// is only allowed for localhost. Set SOLANA_RPC_URL to a " \
+            "TLS endpoint (e.g. https://api.mainnet-beta.solana.com or your " \
+            "paid provider's HTTPS endpoint)."
+    end
+  end
+end

data/lib/solana/keypair.rb

@@ -0,0 +1,106 @@
+require "ed25519"
+require "securerandom"
+require "json"
+
+module Solana
+  class Keypair
+    BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+    attr_reader :signing_key, :verify_key
+
+    def initialize(signing_key)
+      @signing_key = signing_key
+      @verify_key = signing_key.verify_key
+    end
+
+    # Generate a new random keypair
+    def self.generate
+      new(Ed25519::SigningKey.generate)
+    end
+
+    # Load from raw 64-byte secret key (Solana format: 32-byte private + 32-byte public)
+    def self.from_bytes(bytes)
+      bytes = bytes.pack("C*") if bytes.is_a?(Array)
+      private_key = bytes[0, 32]
+      new(Ed25519::SigningKey.new(private_key))
+    end
+
+    # Load from Solana CLI keypair JSON file (array of 64 bytes)
+    def self.from_json_file(path)
+      bytes = JSON.parse(File.read(path))
+      from_bytes(bytes)
+    end
+
+    # Load from base58-encoded secret key (e.g. from env var)
+    def self.from_base58(secret_key_base58)
+      bytes = decode_base58(secret_key_base58)
+      from_bytes(bytes)
+    end
+
+    # Public key as 32 bytes
+    def public_key_bytes
+      @verify_key.to_bytes
+    end
+
+    # Public key as base58 string (Solana address)
+    def to_base58
+      self.class.encode_base58(public_key_bytes)
+    end
+    alias_method :address, :to_base58
+
+    # Sign a message
+    def sign(message)
+      message = message.pack("C*") if message.is_a?(Array)
+      @signing_key.sign(message)
+    end
+
+    # Full 64-byte secret key (Solana format)
+    def to_bytes
+      @signing_key.to_bytes + public_key_bytes
+    end
+
+    # --- Base58 utilities ---
+
+    def self.encode_base58(bytes)
+      bytes = bytes.b if bytes.is_a?(String)
+      num = bytes.unpack1("H*").to_i(16)
+
+      result = ""
+      while num > 0
+        num, remainder = num.divmod(58)
+        result = BASE58_ALPHABET[remainder] + result
+      end
+
+      # Preserve leading zero bytes
+      bytes.each_byte do |byte|
+        break unless byte == 0
+        result = "1" + result
+      end
+
+      result
+    end
+
+    def self.decode_base58(string)
+      raise ArgumentError, "decode_base58 requires a non-empty String, got #{string.inspect}" if string.nil? || string.empty?
+
+      num = 0
+      string.each_char do |c|
+        idx = BASE58_ALPHABET.index(c)
+        raise ArgumentError, "Invalid base58 character #{c.inspect} (not in alphabet: 0OIl excluded)" unless idx
+        num = num * 58 + idx
+      end
+
+      hex = num.to_s(16)
+      hex = "0" + hex if hex.length.odd?
+
+      # Count leading '1's (zero bytes)
+      leading_zeros = string.chars.take_while { |c| c == "1" }.length
+      bytes = [("00" * leading_zeros) + hex].pack("H*")
+      bytes
+    end
+
+    def self.pubkey_from_base58(address)
+      decode_base58(address)
+    end
+  end
+end

data/lib/solana/spl_token.rb

@@ -0,0 +1,93 @@
+module Solana
+  module SplToken
+    module_function
+
+    # Derive the Associated Token Address for a wallet + mint
+    # Returns [ata_bytes, bump]
+    def find_associated_token_address(wallet, mint)
+      wallet_bytes = normalize(wallet)
+      mint_bytes = normalize(mint)
+
+      Transaction.find_pda(
+        [wallet_bytes, Transaction::TOKEN_PROGRAM_ID, mint_bytes],
+        Transaction::ASSOCIATED_TOKEN_PROGRAM_ID
+      )
+    end
+
+    # Build a CreateAssociatedTokenAccount instruction
+    # Returns hash compatible with Transaction#add_instruction
+    def create_associated_token_account_instruction(payer:, wallet:, mint:)
+      payer_bytes = normalize(payer)
+      wallet_bytes = normalize(wallet)
+      mint_bytes = normalize(mint)
+      ata_bytes, _ = find_associated_token_address(wallet_bytes, mint_bytes)
+
+      {
+        program_id: Transaction::ASSOCIATED_TOKEN_PROGRAM_ID,
+        accounts: [
+          { pubkey: payer_bytes, is_signer: true, is_writable: true },
+          { pubkey: ata_bytes, is_signer: false, is_writable: true },
+          { pubkey: wallet_bytes, is_signer: false, is_writable: false },
+          { pubkey: mint_bytes, is_signer: false, is_writable: false },
+          { pubkey: Transaction::SYSTEM_PROGRAM_ID, is_signer: false, is_writable: false },
+          { pubkey: Transaction::TOKEN_PROGRAM_ID, is_signer: false, is_writable: false }
+        ],
+        data: "".b
+      }
+    end
+
+    # Build a SPL Token MintTo instruction (discriminator byte 7)
+    # Returns hash compatible with Transaction#add_instruction
+    def mint_to_instruction(mint:, destination:, authority:, amount:)
+      mint_bytes = normalize(mint)
+      dest_bytes = normalize(destination)
+      auth_bytes = normalize(authority)
+
+      data = [7].pack("C") + [amount].pack("Q<")
+
+      {
+        program_id: Transaction::TOKEN_PROGRAM_ID,
+        accounts: [
+          { pubkey: mint_bytes, is_signer: false, is_writable: true },
+          { pubkey: dest_bytes, is_signer: false, is_writable: true },
+          { pubkey: auth_bytes, is_signer: true, is_writable: false }
+        ],
+        data: data
+      }
+    end
+
+    # Build a SPL Token Transfer instruction (discriminator byte 3)
+    # Returns hash compatible with Transaction#add_instruction
+    def transfer_instruction(from:, to:, authority:, amount:)
+      from_bytes = normalize(from)
+      to_bytes = normalize(to)
+      auth_bytes = normalize(authority)
+
+      data = [3].pack("C") + [amount].pack("Q<")
+
+      {
+        program_id: Transaction::TOKEN_PROGRAM_ID,
+        accounts: [
+          { pubkey: from_bytes, is_signer: false, is_writable: true },
+          { pubkey: to_bytes, is_signer: false, is_writable: true },
+          { pubkey: auth_bytes, is_signer: true, is_writable: false }
+        ],
+        data: data
+      }
+    end
+
+    # Normalize base58 strings, Keypair objects, or raw bytes to 32-byte binary
+    def normalize(value)
+      if value.is_a?(Keypair)
+        value.public_key_bytes
+      elsif value.is_a?(String) && value.bytesize == 32
+        value.b
+      elsif value.is_a?(String)
+        Keypair.decode_base58(value)
+      else
+        value
+      end
+    end
+    private_class_method :normalize
+  end
+end

data/lib/solana/transaction.rb

@@ -0,0 +1,288 @@
+require "digest"
+
+module Solana
+  class Transaction
+    SYSTEM_PROGRAM_ID = "\x00" * 32
+    TOKEN_PROGRAM_ID = Keypair.decode_base58("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
+    ASSOCIATED_TOKEN_PROGRAM_ID = Keypair.decode_base58("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
+    SYSVAR_RENT_PUBKEY = Keypair.decode_base58("SysvarRent111111111111111111111111111111111")
+
+    attr_reader :instructions, :signers
+
+    def initialize
+      @instructions = []
+      @signers = []
+      @recent_blockhash = nil
+    end
+
+    # Compute Anchor instruction discriminator: SHA256("global:<name>")[0..7]
+    def self.anchor_discriminator(name)
+      Digest::SHA256.digest("global:#{name}")[0, 8]
+    end
+
+    # Derive PDA (Program Derived Address)
+    def self.find_pda(seeds, program_id_bytes)
+      program_id_bytes = Keypair.decode_base58(program_id_bytes) if program_id_bytes.is_a?(String) && program_id_bytes.length != 32
+
+      255.downto(0) do |bump|
+        candidate_seeds = seeds + [[bump].pack("C")]
+        begin
+          hash_input = candidate_seeds.map { |s| s.is_a?(String) ? s.b : s.pack("C*") }.join
+          hash_input += program_id_bytes.b
+          hash_input += "ProgramDerivedAddress".b
+
+          candidate = Digest::SHA256.digest(hash_input)
+
+          # Check if the point is on the Ed25519 curve — PDA must NOT be on curve
+          unless on_curve?(candidate)
+            return [candidate, bump]
+          end
+        rescue
+          next
+        end
+      end
+      raise "Could not find PDA"
+    end
+
+    def set_recent_blockhash(blockhash)
+      @recent_blockhash = Keypair.decode_base58(blockhash)
+      self
+    end
+
+    def add_signer(keypair)
+      @signers << keypair
+      self
+    end
+
+    def add_instruction(program_id:, accounts:, data:)
+      program_id_bytes = normalize_pubkey(program_id)
+      @instructions << {
+        program_id: program_id_bytes,
+        accounts: accounts.map { |a|
+          {
+            pubkey: normalize_pubkey(a[:pubkey]),
+            is_signer: a[:is_signer] || false,
+            is_writable: a[:is_writable] || false
+          }
+        },
+        data: data.is_a?(String) ? data.b : data.pack("C*")
+      }
+      self
+    end
+
+    # Serialize and sign the transaction
+    def serialize
+      raise "No blockhash set" unless @recent_blockhash
+      raise "No signers" if @signers.empty?
+      raise "No instructions" if @instructions.empty?
+
+      # Collect all unique accounts in order
+      account_keys = collect_account_keys
+      num_required_signatures = count_required_signatures(account_keys)
+      num_readonly_signed = count_readonly_signed(account_keys)
+      num_readonly_unsigned = count_readonly_unsigned(account_keys)
+
+      # Build message
+      message = build_message(account_keys, num_required_signatures, num_readonly_signed, num_readonly_unsigned)
+
+      # Sign message
+      signatures = @signers.map { |signer| signer.sign(message) }
+
+      # Compact-array encode signature count + signatures + message
+      compact_u16(signatures.length) + signatures.join.b + message
+    end
+
+    def serialize_base64
+      require "base64"
+      Base64.strict_encode64(serialize)
+    end
+
+    # Serialize with partial signing — signs with available signers, leaves
+    # zero-byte placeholders for additional_signers that must sign client-side.
+    # additional_signers: array of pubkey bytes (32-byte strings) that will sign later.
+    def serialize_partial(additional_signers: [])
+      raise "No blockhash set" unless @recent_blockhash
+      raise "No signers" if @signers.empty?
+      raise "No instructions" if @instructions.empty?
+
+      # Mark additional signers so they appear in the account keys
+      additional_signers.each do |pubkey_bytes|
+        pk = normalize_pubkey(pubkey_bytes)
+        @_additional_signers ||= []
+        @_additional_signers << pk
+      end
+
+      account_keys = collect_account_keys
+      num_required_signatures = count_required_signatures(account_keys)
+      num_readonly_signed = count_readonly_signed(account_keys)
+      num_readonly_unsigned = count_readonly_unsigned(account_keys)
+
+      message = build_message(account_keys, num_required_signatures, num_readonly_signed, num_readonly_unsigned)
+
+      # Build ordered signature slots matching the account key order
+      signer_map = {}
+      @signers.each { |s| signer_map[s.public_key_bytes] = s.sign(message) }
+
+      signatures = account_keys.select { |_, meta| meta[:is_signer] }.map do |pk, _|
+        signer_map[pk] || ("\x00" * 64).b  # zero placeholder for unsigned slots
+      end
+
+      compact_u16(signatures.length) + signatures.join.b + message
+    ensure
+      @_additional_signers = nil
+    end
+
+    def serialize_partial_base64(additional_signers: [])
+      require "base64"
+      Base64.strict_encode64(serialize_partial(additional_signers: additional_signers))
+    end
+
+    private
+
+    def normalize_pubkey(key)
+      if key.is_a?(String) && key.bytesize == 32
+        key.b
+      elsif key.is_a?(String)
+        Keypair.decode_base58(key)
+      elsif key.is_a?(Keypair)
+        key.public_key_bytes
+      else
+        key
+      end
+    end
+
+    def collect_account_keys
+      keys = {}
+
+      # Fee payer (first signer) is always first
+      fee_payer = @signers.first.public_key_bytes
+      keys[fee_payer] = { is_signer: true, is_writable: true }
+
+      # Other signers
+      @signers[1..].each do |signer|
+        pk = signer.public_key_bytes
+        keys[pk] ||= { is_signer: true, is_writable: false }
+        keys[pk][:is_signer] = true
+      end
+
+      # Additional signers (for partial signing — not in @signers but must be marked as signer)
+      if @_additional_signers
+        @_additional_signers.each do |pk|
+          keys[pk] ||= { is_signer: true, is_writable: false }
+          keys[pk][:is_signer] = true
+        end
+      end
+
+      # Instruction accounts
+      @instructions.each do |ix|
+        ix[:accounts].each do |account|
+          pk = account[:pubkey]
+          keys[pk] ||= { is_signer: false, is_writable: false }
+          keys[pk][:is_signer] ||= account[:is_signer]
+          keys[pk][:is_writable] ||= account[:is_writable]
+        end
+        # Program ID (always readonly, unsigned)
+        keys[ix[:program_id]] ||= { is_signer: false, is_writable: false }
+      end
+
+      # Sort: signer+writable, signer+readonly, non-signer+writable, non-signer+readonly
+      # Fee payer stays first
+      sorted = keys.to_a.sort_by do |pk, meta|
+        if pk == fee_payer
+          [0, 0, 0]
+        elsif meta[:is_signer] && meta[:is_writable]
+          [0, 0, 1]
+        elsif meta[:is_signer]
+          [0, 1, 0]
+        elsif meta[:is_writable]
+          [1, 0, 0]
+        else
+          [1, 1, 0]
+        end
+      end
+
+      sorted
+    end
+
+    def count_required_signatures(account_keys)
+      account_keys.count { |_, meta| meta[:is_signer] }
+    end
+
+    def count_readonly_signed(account_keys)
+      account_keys.count { |_, meta| meta[:is_signer] && !meta[:is_writable] }
+    end
+
+    def count_readonly_unsigned(account_keys)
+      account_keys.count { |_, meta| !meta[:is_signer] && !meta[:is_writable] }
+    end
+
+    def build_message(account_keys, num_required_signatures, num_readonly_signed, num_readonly_unsigned)
+      msg = "".b
+
+      # Header
+      msg << [num_required_signatures, num_readonly_signed, num_readonly_unsigned].pack("CCC")
+
+      # Account keys (compact array)
+      msg << compact_u16(account_keys.length)
+      account_keys.each { |pk, _| msg << pk.b }
+
+      # Recent blockhash
+      msg << @recent_blockhash.b
+
+      # Instructions (compact array)
+      msg << compact_u16(@instructions.length)
+      key_index = account_keys.map { |pk, _| pk }.each_with_index.to_h
+
+      @instructions.each do |ix|
+        msg << [key_index[ix[:program_id]]].pack("C")
+        msg << compact_u16(ix[:accounts].length)
+        ix[:accounts].each do |account|
+          msg << [key_index[account[:pubkey]]].pack("C")
+        end
+        msg << compact_u16(ix[:data].bytesize)
+        msg << ix[:data]
+      end
+
+      msg
+    end
+
+    def compact_u16(value)
+      bytes = []
+      loop do
+        byte = value & 0x7F
+        value >>= 7
+        byte |= 0x80 if value > 0
+        bytes << byte
+        break if value == 0
+      end
+      bytes.pack("C*")
+    end
+
+    # Check if 32 bytes represent a valid Ed25519 public key (point on curve).
+    # PDA addresses must NOT be on the curve.
+    ED25519_P = (2**255) - 19
+    ED25519_D = (-121_665 * 121_666.pow(ED25519_P - 2, ED25519_P)) % ED25519_P
+
+    def self.on_curve?(bytes)
+      bytes = bytes.b
+      # Decode y-coordinate (little-endian, clear high bit)
+      y = bytes.unpack("C*").each_with_index.sum { |b, i| b * (256**i) }
+      y &= (2**255) - 1 # clear sign bit
+      return false if y >= ED25519_P
+
+      # Check if x^2 = (y^2 - 1) / (d*y^2 + 1) has a square root mod p
+      y2 = y.pow(2, ED25519_P)
+      u = (y2 - 1) % ED25519_P
+      v = (ED25519_D * y2 + 1) % ED25519_P
+
+      # Compute candidate: x = (u/v)^((p+3)/8) mod p
+      v_inv = v.pow(ED25519_P - 2, ED25519_P)
+      x2 = (u * v_inv) % ED25519_P
+      x = x2.pow((ED25519_P + 3) / 8, ED25519_P)
+
+      # Verify: v * x^2 must equal u or -u mod p
+      vx2 = (v * x.pow(2, ED25519_P)) % ED25519_P
+      vx2 == u % ED25519_P || vx2 == (ED25519_P - u) % ED25519_P
+    end
+  end
+end

data/lib/solana-studio.rb

@@ -0,0 +1,6 @@
+# Entry point for the `solana-studio` gem. The actual code lives in
+# `lib/solana_studio.rb` (which exports the `SolanaStudio` module + the
+# `Solana::*` namespace). This shim exists so `gem "solana-studio"` in
+# a Gemfile loads correctly without consumers needing to add
+# `require: "solana_studio"`.
+require_relative "solana_studio"

data/lib/solana_studio.rb

@@ -0,0 +1,10 @@
+require_relative "solana/keypair"
+require_relative "solana/borsh"
+require_relative "solana/client"
+require_relative "solana/transaction"
+require_relative "solana/spl_token"
+require_relative "solana/auth_verifier"
+
+module SolanaStudio
+  VERSION = "0.4.1"
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: solana-studio
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- Alex McRitchie
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A lightweight Ruby gem providing generic Solana building blocks — JSON-RPC
+  client with retry, Ed25519 keypair management, Borsh encoding/decoding, transaction
+  builder with PDA derivation and Anchor discriminators, SPL Token instruction helpers,
+  and a pure-Ruby wallet-signature verifier (Solana::AuthVerifier).
+email:
+- solana-studio@mcritchie.studio
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/solana-studio.rb
+- lib/solana/auth_verifier.rb
+- lib/solana/borsh.rb
+- lib/solana/client.rb
+- lib/solana/keypair.rb
+- lib/solana/spl_token.rb
+- lib/solana/transaction.rb
+- lib/solana_studio.rb
+homepage: https://github.com/amcritchie/solana-studio
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/amcritchie/solana-studio
+  source_code_uri: https://github.com/amcritchie/solana-studio
+  bug_tracker_uri: https://github.com/amcritchie/solana-studio/issues
+  changelog_uri: https://github.com/amcritchie/solana-studio/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: 'Ruby primitives for Solana: JSON-RPC client, Ed25519 keypairs, Borsh serialization,
+  transaction builder, wallet signature verifier'
+test_files: []