solana_ruby_wallet_adapter 0.1.1

data/lib/solana_wallet_adapter/adapter.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Abstract base class for all wallet adapters.
+  # Mirrors BaseWalletAdapter from @solana/wallet-adapter-base.
+  #
+  # Subclasses MUST implement:
+  #   - name        (String)
+  #   - url         (String)
+  #   - icon        (String)
+  #   - ready_state (WalletReadyState)
+  #   - public_key  (T.nilable(PublicKey))
+  #   - connecting? (Boolean)
+  #   - connect
+  #   - disconnect
+  #   - send_transaction(transaction, rpc_url, options)
+  #
+  # In Rails the adapter is used server-side to:
+  #   1. Supply wallet metadata (name/icon/url) for the frontend.
+  #   2. Verify signatures returned by the front-end wallet.
+  #   3. Facilitate Sign-In-With-Solana flows.
+  class BaseWalletAdapter
+    extend  T::Sig
+    extend  T::Helpers
+    include EventEmitter
+
+    abstract!
+
+    # -------------------------------------------------------------------------
+    # Abstract interface
+    # -------------------------------------------------------------------------
+
+    # Human-readable wallet name.
+    sig { abstract.returns(String) }
+    def name; end
+
+    # URL pointing to the wallet's download / landing page.
+    sig { abstract.returns(String) }
+    def url; end
+
+    # Base64-encoded SVG or PNG data URI for the wallet's icon.
+    sig { abstract.returns(String) }
+    def icon; end
+
+    # Current ready state of this adapter.
+    sig { abstract.returns(WalletReadyState) }
+    def ready_state; end
+
+    # The currently connected public key, or nil when not connected.
+    sig { abstract.returns(T.nilable(PublicKey)) }
+    def public_key; end
+
+    # True while a connection is in progress.
+    sig { abstract.returns(T::Boolean) }
+    def connecting?; end
+
+    # Set of supported transaction versions. nil means all versions.
+    sig { returns(SupportedTransactionVersions) }
+    def supported_transaction_versions
+      nil
+    end
+
+    # Initiate a wallet connection.
+    sig { abstract.void }
+    def connect; end
+
+    # Disconnect the wallet.
+    sig { abstract.void }
+    def disconnect; end
+
+    # Send a transaction to the network via the RPC endpoint.
+    sig do
+      abstract
+        .params(
+          transaction: Transaction,
+          rpc_url:     String,
+          options:     SendTransactionOptions
+        )
+        .returns(String) # transaction signature (base58)
+    end
+    def send_transaction(transaction, rpc_url, options); end
+
+    # -------------------------------------------------------------------------
+    # Concrete helpers
+    # -------------------------------------------------------------------------
+
+    # True when a public key is present (i.e. connected).
+    sig { returns(T::Boolean) }
+    def connected?
+      !public_key.nil?
+    end
+
+    # Serialize adapter metadata as a plain Hash (useful for JSON APIs).
+    sig { returns(T::Hash[String, T.untyped]) }
+    def to_h
+      {
+        "name"        => name,
+        "url"         => url,
+        "icon"        => icon,
+        "readyState"  => ready_state.serialize,
+        "connected"   => connected?,
+        "publicKey"   => public_key&.to_base58,
+      }
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} name=#{name.inspect} ready_state=#{ready_state.serialize}>"
+    end
+  end
+end

data/lib/solana_wallet_adapter/controller_helpers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Helpers mixed into ActionController::Base when the Railtie loads.
+  module ControllerHelpers
+    extend T::Sig
+
+    # Verify a Solana message signature submitted from the browser.
+    # Raises WalletSignMessageError if verification fails.
+    #
+    # Params:
+    #   public_key_b58 – Base58 string of the signer's public key
+    #   message        – the original UTF-8 message string
+    #   signature_b64  – Base64-encoded 64-byte Ed25519 signature
+    sig do
+      params(
+        public_key_b58: String,
+        message:        String,
+        signature_b64:  String
+      ).void
+    end
+    def verify_wallet_signature!(public_key_b58:, message:, signature_b64:)
+      require "base64"
+      public_key = PublicKey.new(public_key_b58)
+      signature  = Base64.strict_decode64(signature_b64)
+      SignatureVerifier.new.verify!(
+        public_key: public_key,
+        message:    message,
+        signature:  signature
+      )
+    end
+
+    # Verify a Sign-In-With-Solana output POSTed from the browser.
+    # Raises WalletSignInError if verification fails.
+    sig do
+      params(
+        input_params:  T::Hash[String, T.untyped],
+        output_params: T::Hash[String, T.untyped]
+      ).void
+    end
+    def verify_sign_in!(input_params:, output_params:)
+      require "base64"
+
+      input = SignInInput.new(
+        domain:          input_params.fetch("domain"),
+        address:         input_params.fetch("address"),
+        statement:       input_params["statement"],
+        uri:             input_params["uri"],
+        version:         input_params.fetch("version", "1"),
+        nonce:           input_params["nonce"],
+        issued_at:       input_params["issued_at"],
+        expiration_time: input_params["expiration_time"],
+        not_before:      input_params["not_before"],
+        request_id:      input_params["request_id"],
+        resources:       Array(input_params["resources"]),
+      )
+
+      output = SignInOutput.new(
+        address:        output_params.fetch("address"),
+        signed_message: output_params.fetch("signed_message"),
+        signature:      Base64.strict_decode64(output_params.fetch("signature")),
+        signature_type: output_params.fetch("signature_type", "ed25519"),
+      )
+
+      SignatureVerifier.new.verify_sign_in!(input: input, output: output)
+    end
+  end
+end

data/lib/solana_wallet_adapter/errors.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Base error for all wallet-adapter errors.
+  # Mirrors WalletError from @solana/wallet-adapter-base.
+  class WalletError < StandardError
+    extend T::Sig
+
+    sig { returns(T.nilable(Exception)) }
+    attr_reader :cause_error
+
+    sig { params(message: T.nilable(String), cause_error: T.nilable(Exception)).void }
+    def initialize(message = nil, cause_error = nil)
+      super(message)
+      @cause_error = cause_error
+    end
+  end
+
+  # Raised when a wallet is not in a ready / installed state.
+  class WalletNotReadyError < WalletError; end
+
+  # Raised when the wallet extension / app fails to load.
+  class WalletLoadError < WalletError; end
+
+  # Raised when the wallet adapter is misconfigured.
+  class WalletConfigError < WalletError; end
+
+  # Raised when the wallet connection attempt fails.
+  class WalletConnectionError < WalletError; end
+
+  # Raised when the wallet disconnects unexpectedly.
+  class WalletDisconnectedError < WalletError; end
+
+  # Raised when an explicit disconnect request fails.
+  class WalletDisconnectionError < WalletError; end
+
+  # Raised when the wallet returns an unexpected account.
+  class WalletAccountError < WalletError; end
+
+  # Raised when the wallet returns an invalid public key.
+  class WalletPublicKeyError < WalletError; end
+
+  # Raised for keypair-level errors.
+  class WalletKeypairError < WalletError; end
+
+  # Raised when an operation requires a connected wallet.
+  class WalletNotConnectedError < WalletError; end
+
+  # Raised when sending a transaction fails.
+  class WalletSendTransactionError < WalletError; end
+
+  # Raised when signing a transaction fails.
+  class WalletSignTransactionError < WalletError; end
+
+  # Raised when signing a message fails.
+  class WalletSignMessageError < WalletError; end
+
+  # Raised when a Sign-In-With-Solana flow fails.
+  class WalletSignInError < WalletError; end
+
+  # Raised when a wallet operation times out.
+  class WalletTimeoutError < WalletError; end
+
+  # Raised when a popup window is blocked.
+  class WalletWindowBlockedError < WalletError; end
+
+  # Raised when the user closes the wallet popup.
+  class WalletWindowClosedError < WalletError; end
+end

data/lib/solana_wallet_adapter/event_emitter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # A simple synchronous event-emitter mixin.
+  # Mirrors the EventEmitter3 interface used by the TypeScript adapters.
+  #
+  # Usage:
+  #   class MyAdapter
+  #     include EventEmitter
+  #     # ...
+  #     def do_something
+  #       emit(:connect, public_key)
+  #     end
+  #   end
+  #
+  #   adapter = MyAdapter.new
+  #   adapter.on(:connect) { |pk| puts "connected: #{pk}" }
+  module EventEmitter
+    extend T::Sig
+    extend T::Helpers
+
+    # @!visibility private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      extend T::Sig
+    end
+
+    # Register a listener for the given event name.
+    # Returns self for chaining.
+    sig { params(event: Symbol, block: T.proc.params(args: T.untyped).void).returns(T.self_type) }
+    def on(event, &block)
+      listeners_for(event) << block
+      self
+    end
+
+    # Register a one-shot listener that auto-removes itself after the first call.
+    sig { params(event: Symbol, block: T.proc.params(args: T.untyped).void).returns(T.self_type) }
+    def once(event, &block)
+      wrapper = T.let(nil, T.nilable(Proc))
+      wrapper = proc do |*args|
+        off(event, T.must(wrapper))
+        block.call(*args)
+      end
+      on(event, &T.must(wrapper))
+      self
+    end
+
+    # Remove a specific listener (or all listeners if block is omitted).
+    sig { params(event: Symbol, block: T.nilable(Proc)).returns(T.self_type) }
+    def off(event, block = nil)
+      if block
+        listeners_for(event).delete(block)
+      else
+        event_listeners.delete(event)
+      end
+      self
+    end
+
+    # Emit an event, calling all registered listeners synchronously.
+    sig { params(event: Symbol, args: T.untyped).void }
+    def emit(event, *args)
+      listeners_for(event).dup.each { |listener| listener.call(*args) }
+    end
+
+    private
+
+    sig { params(event: Symbol).returns(T::Array[Proc]) }
+    def listeners_for(event)
+      event_listeners[event] ||= []
+    end
+
+    sig { returns(T::Hash[Symbol, T::Array[Proc]]) }
+    def event_listeners
+      @event_listeners ||= T.let({}, T.nilable(T::Hash[Symbol, T::Array[Proc]]))
+      T.must(@event_listeners)
+    end
+  end
+end

data/lib/solana_wallet_adapter/message_signer_adapter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Mixin for adapters that can sign arbitrary byte messages.
+  # Mirrors MessageSignerWalletAdapterProps from @solana/wallet-adapter-base.
+  module MessageSignerWalletAdapter
+    extend T::Sig
+    extend T::Helpers
+
+    requires_ancestor { BaseWalletAdapter }
+
+    # Sign an arbitrary message and return the 64-byte Ed25519 signature.
+    sig do
+      abstract
+        .params(message: String) # binary string
+        .returns(String)         # 64-byte binary signature
+    end
+    def sign_message(message); end
+  end
+
+  # Abstract base class combining transaction + message signing.
+  # Mirrors BaseMessageSignerWalletAdapter from @solana/wallet-adapter-base.
+  class BaseMessageSignerWalletAdapter < BaseSignerWalletAdapter
+    extend  T::Sig
+    extend  T::Helpers
+    include MessageSignerWalletAdapter
+
+    abstract!
+  end
+
+  # -------------------------------------------------------------------------
+  # Sign-In-With-Solana (SIWS) support
+  # Mirrors SignInMessageSignerWalletAdapterProps from @solana/wallet-adapter-base.
+  # -------------------------------------------------------------------------
+
+  # Input parameters for a SIWS sign-in request.
+  class SignInInput < T::Struct
+    # The domain presenting the sign-in request (e.g. "example.com").
+    const :domain,      String
+
+    # The Solana address being authenticated.
+    const :address,     String
+
+    # Human-readable statement.
+    const :statement,   T.nilable(String), default: nil
+
+    # URI of the resource that is the subject of the signing.
+    const :uri,         T.nilable(String), default: nil
+
+    # Version of the SIWS message specification.
+    const :version,     String,            default: "1"
+
+    # Unique nonce to prevent replay attacks.
+    const :nonce,       T.nilable(String), default: nil
+
+    # ISO 8601 datetime of when the sign-in was issued.
+    const :issued_at,   T.nilable(String), default: nil
+
+    # ISO 8601 datetime after which the sign-in expires.
+    const :expiration_time, T.nilable(String), default: nil
+
+    # ISO 8601 datetime after which the sign-in is valid.
+    const :not_before, T.nilable(String), default: nil
+
+    # Randomised value for this request (request ID).
+    const :request_id, T.nilable(String), default: nil
+
+    # List of information or references the dapp requests to be included.
+    const :resources,  T::Array[String],  default: []
+
+    # Builds the canonical EIP-4361-like SIWS message string.
+    sig { returns(String) }
+    def to_message
+      lines = ["#{domain} wants you to sign in with your Solana account:"]
+      lines << address
+      lines << "" << (statement || "") << ""
+      lines << "URI: #{uri}"          if uri
+      lines << "Version: #{version}"
+      lines << "Nonce: #{nonce}"      if nonce
+      lines << "Issued At: #{issued_at}" if issued_at
+      lines << "Expiration Time: #{expiration_time}" if expiration_time
+      lines << "Not Before: #{not_before}" if not_before
+      lines << "Request ID: #{request_id}" if request_id
+      resources.each_with_index do |r, i|
+        lines << "Resources:" if i.zero?
+        lines << "- #{r}"
+      end
+      lines.join("\n")
+    end
+  end
+
+  # Output from a completed SIWS sign-in.
+  class SignInOutput < T::Struct
+    # The account that signed in.
+    const :address,   String
+
+    # The signed SIWS message bytes (UTF-8 binary).
+    const :signed_message, String
+
+    # The 64-byte Ed25519 signature.
+    const :signature, String
+
+    # The type of signature (always "ed25519" for Solana).
+    const :signature_type, String, default: "ed25519"
+  end
+
+  # Abstract base class that adds sign-in capability.
+  class BaseSignInMessageSignerWalletAdapter < BaseMessageSignerWalletAdapter
+    extend  T::Sig
+    extend  T::Helpers
+
+    abstract!
+
+    # Perform a SIWS sign-in flow.  Returns a +SignInOutput+.
+    sig do
+      abstract
+        .params(input: T.nilable(SignInInput))
+        .returns(SignInOutput)
+    end
+    def sign_in(input = nil); end
+  end
+end

data/lib/solana_wallet_adapter/network.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Mirrors WalletAdapterNetwork from @solana/wallet-adapter-base.
+  class Network < T::Enum
+    extend T::Sig
+
+    enums do
+      MainnetBeta = new("mainnet-beta")
+      Testnet     = new("testnet")
+      Devnet      = new("devnet")
+    end
+
+    # The RPC cluster URL commonly associated with each network.
+    RPC_URLS = T.let(
+      {
+        MainnetBeta => "https://api.mainnet-beta.solana.com",
+        Testnet     => "https://api.testnet.solana.com",
+        Devnet      => "https://api.devnet.solana.com",
+      }.freeze,
+      T::Hash[Network, String]
+    )
+
+    sig { returns(String) }
+    def rpc_url
+      RPC_URLS.fetch(self)
+    end
+  end
+end

data/lib/solana_wallet_adapter/public_key.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "base58"
+
+module SolanaWalletAdapter
+  # Lightweight representation of a Solana public key.
+  # A Solana public key is a 32-byte Ed25519 public key encoded as Base58.
+  class PublicKey
+    extend T::Sig
+
+    BYTE_LENGTH = T.let(32, Integer)
+
+    sig { returns(String) }
+    attr_reader :bytes # raw 32-byte binary string
+
+    # Accepts a Base58-encoded string, a raw 32-byte binary string, or a
+    # 32-element Integer array (matching the JS Uint8Array constructor).
+    sig { params(value: T.any(String, T::Array[Integer])).void }
+    def initialize(value)
+      @bytes = T.let(decode(value), String)
+      raise ArgumentError, "Public key must be #{BYTE_LENGTH} bytes" unless @bytes.bytesize == BYTE_LENGTH
+    end
+
+    sig { returns(String) }
+    def to_base58
+      Base58.binary_to_base58(@bytes, :bitcoin)
+    end
+
+    alias to_s to_base58
+
+    sig { returns(T::Array[Integer]) }
+    def to_bytes
+      @bytes.bytes
+    end
+
+    sig { params(other: PublicKey).returns(T::Boolean) }
+    def ==(other)
+      other.is_a?(PublicKey) && bytes == other.bytes
+    end
+
+    sig { returns(Integer) }
+    def hash
+      bytes.hash
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} #{to_base58}>"
+    end
+
+    private
+
+    sig { params(value: T.any(String, T::Array[Integer])).returns(String) }
+    def decode(value)
+      case value
+      when Array
+        value.pack("C*")
+      when String
+        # Detect binary vs Base58: binary strings are 32 bytes, Base58 strings
+        # are 32–44 ASCII characters.
+        if value.encoding == Encoding::BINARY || value.bytesize == BYTE_LENGTH
+          value.b
+        else
+          Base58.base58_to_binary(value, :bitcoin)
+        end
+      else
+        T.absurd(value)
+      end
+    end
+  end
+end

data/lib/solana_wallet_adapter/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# typed: strict
+
+module SolanaWalletAdapter
+  # Hooks into Rails to auto-load configuration from
+  # config/initializers/solana_wallet_adapter.rb (if present) and to expose
+  # a controller helper module.
+  class Railtie < Rails::Railtie
+    # Expose helper methods in ActionController and ActionView.
+    initializer "solana_wallet_adapter.action_controller" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include SolanaWalletAdapter::ControllerHelpers
+      end
+    end
+
+    initializer "solana_wallet_adapter.action_view" do
+      ActiveSupport.on_load(:action_view) do
+        include SolanaWalletAdapter::ViewHelpers
+      end
+    end
+  end
+end

data/lib/solana_wallet_adapter/signature_verifier.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "ed25519"
+
+module SolanaWalletAdapter
+  # Server-side Ed25519 signature verification for Solana.
+  #
+  # Usage:
+  #   verifier = SolanaWalletAdapter::SignatureVerifier.new
+  #
+  #   # Verify a raw message + signature
+  #   verifier.verify!(
+  #     public_key: PublicKey.new("..."),
+  #     message:    "hello world",
+  #     signature:  Base64.decode64("...") # 64-byte binary
+  #   )
+  #
+  #   # Verify a SIWS sign-in output
+  #   verifier.verify_sign_in!(input: sign_in_input, output: sign_in_output)
+  class SignatureVerifier
+    extend T::Sig
+
+    # Verify that +signature+ was produced by the holder of +public_key+
+    # over +message+.  Raises +WalletSignMessageError+ on failure.
+    sig do
+      params(
+        public_key: PublicKey,
+        message:    String,   # arbitrary binary / UTF-8 bytes
+        signature:  String    # 64-byte binary Ed25519 signature
+      ).returns(T::Boolean)
+    end
+    def verify(public_key:, message:, signature:)
+      vk = Ed25519::VerifyKey.new(public_key.bytes)
+      vk.verify(signature, message)
+      true
+    rescue Ed25519::VerifyError
+      false
+    end
+
+    # Same as +verify+ but raises +WalletSignMessageError+ on failure.
+    sig do
+      params(
+        public_key: PublicKey,
+        message:    String,
+        signature:  String
+      ).void
+    end
+    def verify!(public_key:, message:, signature:)
+      return if verify(public_key: public_key, message: message, signature: signature)
+
+      raise WalletSignMessageError, "Signature verification failed for public key #{public_key}"
+    end
+
+    # Verify a complete SIWS sign-in output against its input.
+    # Raises +WalletSignInError+ on failure.
+    sig do
+      params(
+        input:  SignInInput,
+        output: SignInOutput
+      ).void
+    end
+    def verify_sign_in!(input:, output:)
+      unless output.address == input.address
+        raise WalletSignInError,
+              "Sign-in address mismatch: expected #{input.address}, got #{output.address}"
+      end
+
+      expected_message = input.to_message
+      unless output.signed_message == expected_message
+        raise WalletSignInError, "Sign-in message does not match the expected SIWS message"
+      end
+
+      public_key = PublicKey.new(output.address)
+      verify!(
+        public_key: public_key,
+        message:    output.signed_message,
+        signature:  output.signature
+      )
+    rescue WalletError
+      raise
+    rescue => e
+      raise WalletSignInError.new(e.message, e)
+    end
+  end
+end