solrengine-sdp 0.1.0

data/app/models/solrengine/sdp/transfer.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "securerandom"
+
+module Solrengine
+  module Sdp
+    # Engine-owned record of every transfer the app attempts through SDP —
+    # the row IS the audit trail and the thing the app renders (R6: every
+    # transfer settles into a renderable terminal state).
+    #
+    # Status mapping (the HTD table, one-to-one):
+    #
+    #   SDP pending/processing → "processing"  (non-terminal, polled)
+    #   SDP confirmed          → "confirmed"   (user-facing success; tracking
+    #                                           CONTINUES to finalized)
+    #   SDP finalized          → "finalized"   (terminal)
+    #   SDP failed             → "failed"      (terminal; SDP error captured)
+    #   engine-local           → "expired"     (terminal; stuck in processing
+    #                                           past expired_transfer_deadline)
+    #   engine-local           → "unknown"     (POST read-timeout: outcome
+    #                                           unknown; reconciled by memo
+    #                                           token via list_transfers)
+    #
+    # The create POST is NEVER retried — SDP has no idempotency key, so a
+    # blind re-send risks a double-spend (demo TransfersController /
+    # RecurringExecution discipline). The row is created BEFORE the POST so
+    # even a crash mid-request leaves evidence to reconcile against.
+    class Transfer < ActiveRecord::Base
+      self.table_name = "solrengine_sdp_transfers"
+
+      # ~5000 lamports: one signature's network fee, held back from the
+      # spendable balance so a SOL send can pay for its own transaction.
+      FEE_BUFFER = BigDecimal("0.000005")
+
+      # App memo and engine token compose rather than replace each other:
+      # "rent | sdp-1a2b3c4d5e6f7a8b". The token half is what timeout
+      # reconciliation scans for; the app half survives round-trip to chain.
+      MEMO_TOKEN_PREFIX = "sdp-"
+      MEMO_SEPARATOR = " | "
+
+      STATUSES = %w[processing confirmed finalized failed expired unknown].freeze
+      # confirmed is NOT terminal: it is user-facing success, but tracking
+      # continues until SDP reports finalized.
+      TERMINAL_STATUSES = %w[finalized failed expired].freeze
+
+      SDP_STATUS_MAP = {
+        "pending" => "processing",
+        "processing" => "processing",
+        "confirmed" => "confirmed",
+        "finalized" => "finalized",
+        "failed" => "failed"
+      }.freeze
+
+      validates :source_wallet_id, :destination, :token, :amount, :memo_token, presence: true
+      validates :status, inclusion: { in: STATUSES }
+
+      # Rows TrackTransferJob still owes a verdict on — includes confirmed,
+      # which is user-facing success but not yet finalized (tracking continues
+      # until SDP reports finalized).
+      scope :unsettled, -> { where.not(status: TERMINAL_STATUSES) }
+      scope :terminal, -> { where(status: TERMINAL_STATUSES) }
+
+      class << self
+        # Creates the row, runs the balance preflight, POSTs the transfer to
+        # SDP exactly once, and enqueues confirmation tracking. Returns the
+        # row in whatever state the POST left it (the app renders from it).
+        #
+        # Raises InsufficientBalance — before any row or POST — when the
+        # preflight shows the SOL balance can't cover amount + FEE_BUFFER.
+        def execute!(source:, destination:, amount:, token: "SOL", memo: nil)
+          # Normalize to a plain decimal string ("1.5", never "0.15e1"):
+          # stored and sent as a string so no float drift ever touches money.
+          amount = BigDecimal(amount.to_s).to_s("F")
+
+          # Preflight is SOL-only in v0.1 (SPL would need the mint row plus a
+          # separate SOL fee check); for SPL tokens the POST is the authority.
+          ensure_balance_covers!(source, amount) if token == "SOL"
+
+          transfer = create!(
+            source_wallet_id: source,
+            destination: destination,
+            token: token,
+            amount: amount,
+            memo: memo,
+            memo_token: "#{MEMO_TOKEN_PREFIX}#{SecureRandom.hex(8)}",
+            status: "processing",
+            submitted_at: Time.current
+          )
+          transfer.submit_to_sdp!
+          TrackTransferJob.perform_later(transfer) unless transfer.terminal?
+          transfer
+        end
+
+        # Recovery entry point: re-enqueues TrackTransferJob for unsettled
+        # rows nothing is tracking anymore. Closes the crash window between
+        # create!/submit_to_sdp! and the tracking enqueue, and adopts orphans
+        # after queue data loss. The updated_at guard (two poll intervals)
+        # avoids double-enqueueing rows under ACTIVE tracking — every poll
+        # and settle touches the row, so a row untouched for two intervals
+        # has no live tracker. Returns the count enqueued.
+        def resume_tracking!
+          cutoff = Time.current - (Solrengine::Sdp.configuration.transfer_poll_interval * 2)
+          count = 0
+          unsettled.where(updated_at: ..cutoff).find_each do |transfer|
+            TrackTransferJob.perform_later(transfer)
+            count += 1
+          end
+          count
+        end
+
+        def engine_status_for(sdp_status)
+          # Unrecognized SDP statuses map to "processing": non-terminal, keep
+          # polling — safer than inventing a verdict for a status SDP adds in
+          # a later version.
+          SDP_STATUS_MAP.fetch(sdp_status.to_s, "processing")
+        end
+
+        private
+
+        # Never hand SDP a transfer that can't pay for itself — but only
+        # block on a balance we positively read. A nil balance (SOL row
+        # missing or balances unreadable) does NOT block: SDP omits rows on
+        # RPC hiccups, and the POST — not the preflight — is the authority
+        # on whether the transfer can execute.
+        def ensure_balance_covers!(wallet_id, amount)
+          balance = sol_balance(wallet_id)
+          return if balance.nil?
+
+          required = BigDecimal(amount) + FEE_BUFFER
+          return unless required > balance
+
+          raise InsufficientBalance,
+            "Insufficient SOL: wallet #{wallet_id} holds #{balance.to_s("F")} SOL but " \
+            "#{required.to_s("F")} is required (#{amount} + #{FEE_BUFFER.to_s("F")} fee buffer)."
+        end
+
+        # SOL balance as BigDecimal, or nil when unknown — nil is never zero.
+        def sol_balance(wallet_id)
+          row = Solrengine::Sdp.client.wallet_balances(wallet_id).find { |b| b.token == "SOL" }
+          return nil if row.nil? || row.ui_amount.nil?
+
+          BigDecimal(row.ui_amount.to_s)
+        rescue ::Sdp::Error, ArgumentError, TypeError
+          nil
+        end
+      end
+
+      STATUSES.each do |name|
+        define_method("#{name}?") { status == name }
+      end
+
+      def terminal?
+        TERMINAL_STATUSES.include?(status)
+      end
+
+      # The memo actually sent to SDP: app memo (when given) + engine token.
+      def composed_memo
+        [ memo, memo_token ].compact.join(MEMO_SEPARATOR)
+      end
+
+      # The single, never-retried POST. Every outcome lands on the row:
+      #
+      #   success        → adopt SDP's id/status/signature (mapped status)
+      #   SigningPending → stay processing; 202 details noted on sdp_error
+      #   Timeout        → "unknown" (outcome unknown — reconcile by memo token)
+      #   Unavailable    → "failed", "unsent:" prefix (request never processed)
+      #   other Sdp::Error (TransferExecutionError/TransactionFailed/rejections)
+      #                  → "failed" with the renderable message (AE2)
+      def submit_to_sdp!
+        adopt!(
+          Solrengine::Sdp.client.create_transfer(
+            source: source_wallet_id,
+            destination: destination,
+            amount: amount,
+            token: token,
+            memo: composed_memo
+          )
+        )
+      rescue ::Sdp::SigningPending => e
+        # HTTP 202: accepted, awaiting additional signatures. Non-terminal —
+        # tracked like any processing transfer once SDP exposes the id.
+        update!(
+          status: "processing",
+          sdp_transfer_id: e.details.is_a?(Hash) ? (e.details[:transfer_id] || e.details[:id]) : nil,
+          sdp_error: "signing_pending: #{e.message}"
+        )
+      rescue ::Sdp::Timeout
+        # Read timeout on the POST: SDP may or may not have executed it.
+        # NEVER re-POST; TrackTransferJob reconciles via the memo token.
+        update!(status: "unknown")
+      rescue ::Sdp::Unavailable => e
+        # Connection refused/reset or a 5xx without SDP's error shape: the
+        # request was never processed, so no money moved. The "unsent:"
+        # prefix distinguishes this from an on-chain failure.
+        settle!("failed", sdp_error: "unsent: #{e.message}")
+      rescue ::Sdp::Error => e
+        # TransferExecutionError (the Kora/FL-11 gate, AE2), TransactionFailed,
+        # and every other SDP rejection: terminal, message renderable as-is.
+        settle!("failed", sdp_error: e.message)
+      end
+
+      # Maps an Sdp::Transfer struct onto this row per the status table.
+      # Tolerates omitted optional fields (struct members are nil): existing
+      # id/signature are never clobbered with nil.
+      def adopt!(sdp_transfer)
+        mapped = self.class.engine_status_for(sdp_transfer.status)
+        attributes = {
+          sdp_transfer_id: sdp_transfer.id || sdp_transfer_id,
+          sdp_status: sdp_transfer.status,
+          status: mapped,
+          signature: sdp_transfer.signature || signature
+        }
+        attributes[:sdp_error] = sdp_transfer.error if sdp_transfer.error
+        attributes[:settled_at] = Time.current if TERMINAL_STATUSES.include?(mapped) && settled_at.nil?
+        update!(attributes)
+      end
+
+      # Lands the row in a terminal state and timestamps the verdict.
+      def settle!(terminal_status, sdp_error: nil)
+        update!(
+          status: terminal_status,
+          sdp_error: sdp_error || self[:sdp_error],
+          settled_at: Time.current
+        )
+      end
+    end
+  end
+end

data/lib/generators/solrengine/sdp/install_generator.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "yaml"
+
+module Solrengine
+  module Sdp
+    # `bin/rails generate solrengine:sdp:install`
+    #
+    # One run gives a default Rails app everything Wallet-per-User needs:
+    #
+    #   * two timestamped migrations (WalletOwner columns on users + the
+    #     solrengine_sdp_transfers table) — skipped when a migration of the
+    #     same name already exists, so re-running never duplicates them
+    #   * config/initializers/solrengine_sdp.rb (ENV-backed configuration)
+    #   * `include Solrengine::Sdp::WalletOwner` injected into app/models/user.rb
+    #   * bin/sdp_watcher + a Procfile.dev entry for it
+    #   * SDP_* keys appended to .env
+    #   * a working development cable adapter (see #configure_cable_adapter —
+    #     the default async adapter silently drops the watcher's broadcasts)
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      MIGRATIONS = %w[add_solrengine_sdp_to_users create_solrengine_sdp_transfers].freeze
+
+      # The exact development block `rails new` emits — the only async config
+      # this generator rewrites mechanically. Anything else async-but-custom
+      # gets loud manual instructions instead of risky surgery.
+      ASYNC_DEVELOPMENT_BLOCK = "development:\n  adapter: async\n"
+      SOLID_CABLE_DEVELOPMENT_BLOCK = <<~YAML
+        development:
+          adapter: solid_cable
+          polling_interval: 0.1.seconds
+          message_retention: 1.hour
+      YAML
+
+      def create_migrations
+        base = Time.now.utc
+        MIGRATIONS.each_with_index do |name, offset|
+          if migration_exists?(name)
+            say_status :skip, "db/migrate/*_#{name}.rb already exists", :yellow
+            next
+          end
+
+          # +offset keeps the two versions unique within a single run.
+          version = (base + offset).strftime("%Y%m%d%H%M%S")
+          copy_file "#{name}.rb", "db/migrate/#{version}_#{name}.rb"
+        end
+      end
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/solrengine_sdp.rb"
+      end
+
+      def include_wallet_owner_in_user_model
+        user_model = "app/models/user.rb"
+        unless exists?(user_model)
+          say_status :skip, "#{user_model} not found — add `include Solrengine::Sdp::WalletOwner` " \
+            "to your wallet-owner model and point config.user_class at it", :yellow
+          return
+        end
+        return if read(user_model).include?("Solrengine::Sdp::WalletOwner")
+
+        inject_into_class user_model, "User", <<-RUBY
+  include Solrengine::Sdp::WalletOwner
+
+  # Provision a custody wallet on signup (opt-in — uncomment to enable):
+  # after_create_commit :provision_wallet!
+
+        RUBY
+      end
+
+      def install_watcher
+        copy_file "sdp_watcher", "bin/sdp_watcher"
+        chmod "bin/sdp_watcher", 0o755
+      end
+
+      def update_procfile
+        if exists?("Procfile.dev")
+          unless read("Procfile.dev").include?("sdp_watcher:")
+            append_to_file "Procfile.dev", "sdp_watcher: bin/sdp_watcher\n"
+          end
+        else
+          create_file "Procfile.dev", "web: bin/rails server\nsdp_watcher: bin/sdp_watcher\n"
+        end
+      end
+
+      def append_env_keys
+        return if exists?(".env") && read(".env").include?("SDP_API_KEY")
+
+        if exists?(".env")
+          append_to_file ".env", env_block
+        else
+          create_file ".env", env_block
+        end
+      end
+
+      # The cable adapter is part of this engine's correctness, not a nicety:
+      # the default `async` adapter accepts broadcasts but delivers them
+      # in-process only, so everything bin/sdp_watcher (a separate process)
+      # pushes would be silently dropped — no error, the browser just never
+      # updates. Development must be on a cross-process adapter.
+      #
+      # Decision (documented): the meta-gem's surgery force-replaces
+      # database.yml with its own multi-database layout; this generator stays
+      # single-database and writes a solid_cable development block WITHOUT
+      # connects_to (Solid Cable then uses the primary database) plus loud
+      # instructions for the gem + table. bin/sdp_watcher proves the result
+      # with a boot-time broadcast self-check.
+      def configure_cable_adapter
+        unless exists?("config/cable.yml")
+          copy_file "cable.yml", "config/cable.yml"
+          say_cable_instructions
+          return
+        end
+
+        adapter = development_cable_adapter
+        if adapter == "async"
+          if read("config/cable.yml").include?(ASYNC_DEVELOPMENT_BLOCK)
+            gsub_file "config/cable.yml", ASYNC_DEVELOPMENT_BLOCK, SOLID_CABLE_DEVELOPMENT_BLOCK
+            say_cable_instructions
+          else
+            say_cable_refusal("development uses the async adapter in a non-default layout")
+          end
+        elsif adapter.is_a?(String) && !adapter.empty?
+          say_status :identical, "config/cable.yml development adapter is #{adapter} — cable adapter OK", :blue
+        else
+          say_cable_refusal("could not determine the development adapter")
+        end
+      end
+
+      def show_post_install
+        say "\n  solrengine-sdp installed!", :green
+        say <<~MSG
+
+            Next steps:
+              1. bin/rails db:migrate
+              2. Fill in .env: SDP_API_KEY (needs custody:admin + wallets:* + payments:* scopes),
+                 SDP_API_BASE_URL, SDP_CUSTODY_PROVIDER
+              3. Wallet-per-User needs a MANAGED custody provider (e.g. Privy) and Kora for
+                 transfer execution — see the solrengine-sdp README "Prerequisites"
+              4. To provision wallets on signup, uncomment in app/models/user.rb:
+                   after_create_commit :provision_wallet!
+              5. bin/dev — Procfile.dev now runs bin/sdp_watcher alongside the web server
+
+        MSG
+      end
+
+      private
+
+      # Destination-rooted file helpers: plain File.exist?("Procfile.dev")
+      # would resolve against the process CWD, which differs from the target
+      # app in generator tests.
+      def exists?(relative_path)
+        File.exist?(File.join(destination_root, relative_path))
+      end
+
+      def read(relative_path)
+        File.read(File.join(destination_root, relative_path))
+      end
+
+      def migration_exists?(name)
+        Dir.glob(File.join(destination_root, "db", "migrate", "*_#{name}.rb")).any?
+      end
+
+      def development_cable_adapter
+        config = YAML.safe_load(read("config/cable.yml"), aliases: true)
+        return nil unless config.is_a?(Hash)
+
+        development = config["development"]
+        development.is_a?(Hash) ? development["adapter"] : nil
+      rescue Psych::Exception
+        nil
+      end
+
+      def env_block
+        <<~ENV
+          # Solana Developer Platform (solrengine-sdp). The API key needs the
+          # custody:admin, wallets:* and payments:* scopes. For Wallet-per-User
+          # the SDP project must use a managed custody provider (e.g. privy) —
+          # local custody is a single root wallet and cannot provision per-user
+          # wallets — and Kora for fee payment (FEE_PAYMENT_PROVIDER=kora).
+          SDP_API_KEY=
+          SDP_API_BASE_URL=http://127.0.0.1:8787
+          SDP_CUSTODY_PROVIDER=privy
+        ENV
+      end
+
+      def say_cable_instructions
+        say <<~MSG, :yellow
+
+            config/cable.yml development now uses Solid Cable (the default async
+            adapter delivers in-process only and would silently drop everything
+            bin/sdp_watcher broadcasts). To finish:
+
+              1. Ensure `gem "solid_cable"` is in your Gemfile (Rails 8 apps have it;
+                 older apps: `bundle add solid_cable && bin/rails solid_cable:install`,
+                 then re-check that cable.yml development still says solid_cable).
+              2. Create the solid_cable_messages table in your DEVELOPMENT database
+                 (development runs Solid Cable on the primary database):
+                   bin/rails runner 'load Rails.root.join("db/cable_schema.rb")'
+              3. Restart your web server — a running Puma keeps the old adapter in memory.
+
+            bin/sdp_watcher verifies the cable backend with a broadcast self-check at boot.
+        MSG
+      end
+
+      def say_cable_refusal(reason)
+        say <<~MSG, :red
+
+            NOT touching config/cable.yml: #{reason}.
+            The async adapter delivers broadcasts in-process only — everything
+            bin/sdp_watcher pushes would be silently dropped. Please make the
+            development adapter cross-process yourself (solid_cable or redis), e.g.:
+
+            #{SOLID_CABLE_DEVELOPMENT_BLOCK.gsub(/^/, "    ")}
+            then create the solid_cable_messages table in your development database:
+              bin/rails runner 'load Rails.root.join("db/cable_schema.rb")'
+
+            bin/sdp_watcher verifies the cable backend with a broadcast self-check at boot.
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/solrengine/sdp/templates/add_solrengine_sdp_to_users.rb

@@ -0,0 +1,13 @@
+# The four columns Solrengine::Sdp::WalletOwner expects on the wallet-owner
+# model. Using a model other than User? Rename the table below and set
+# `config.user_class` in config/initializers/solrengine_sdp.rb.
+class AddSolrengineSdpToUsers < ActiveRecord::Migration[7.1]
+  def change
+    add_column :users, :sdp_wallet_id, :string            # SDP's walletId once provisioned
+    add_column :users, :wallet_address, :string           # the wallet's Solana public key
+    add_column :users, :sdp_provisioning_state, :string, default: "pending", null: false
+    add_column :users, :sdp_provisioning_error, :string   # renderable failure reason
+
+    add_index :users, :sdp_provisioning_state
+  end
+end

data/lib/generators/solrengine/sdp/templates/cable.yml

@@ -0,0 +1,23 @@
+# Created by solrengine:sdp:install.
+#
+# Rails' default `async` adapter delivers broadcasts IN-PROCESS ONLY:
+# everything bin/sdp_watcher pushes from its own process would be silently
+# dropped. Solid Cable relays through the database and works across
+# processes. With no `connects_to`, development uses the primary database —
+# the solid_cable_messages table must exist there (see the solrengine-sdp
+# README, "Cable adapter").
+development:
+  adapter: solid_cable
+  polling_interval: 0.1.seconds
+  message_retention: 1.hour
+
+test:
+  adapter: test
+
+production:
+  adapter: solid_cable
+  connects_to:
+    database:
+      writing: cable
+  polling_interval: 0.1.seconds
+  message_retention: 1.day

data/lib/generators/solrengine/sdp/templates/create_solrengine_sdp_transfers.rb

@@ -0,0 +1,27 @@
+# Engine-owned record of every transfer the app attempts through SDP — the
+# row is the audit trail and the thing the app renders. See
+# Solrengine::Sdp::Transfer for the status state machine.
+class CreateSolrengineSdpTransfers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solrengine_sdp_transfers do |t|
+      t.string :sdp_transfer_id              # nil until SDP responds (POST timeout → reconcile)
+      t.string :source_wallet_id, null: false
+      t.string :destination, null: false
+      t.string :token, null: false, default: "SOL"
+      t.string :amount, null: false          # decimal string — never a float
+      t.string :memo                         # the app's memo (composes with memo_token)
+      t.string :memo_token, null: false      # engine reconcile token
+      t.string :status, null: false, default: "processing"
+      t.string :sdp_status
+      t.string :signature
+      t.string :sdp_error
+      t.datetime :submitted_at
+      t.datetime :settled_at
+
+      t.timestamps
+    end
+
+    add_index :solrengine_sdp_transfers, :memo_token, unique: true
+    add_index :solrengine_sdp_transfers, :status
+  end
+end

data/lib/generators/solrengine/sdp/templates/initializer.rb

@@ -0,0 +1,44 @@
+# solrengine-sdp — custodial Solana wallets via the Solana Developer Platform.
+#
+# api_key, base_url, and custody_provider already fall back to SDP_API_KEY,
+# SDP_API_BASE_URL, and SDP_CUSTODY_PROVIDER from ENV; the explicit
+# assignments below just make the wiring visible. A missing api_key fails
+# loudly at boot (Solrengine::Sdp::ConfigurationError), not at the first
+# wallet call.
+Solrengine::Sdp.configure do |config|
+  config.api_key = ENV["SDP_API_KEY"]
+  config.base_url = ENV.fetch("SDP_API_BASE_URL", "http://127.0.0.1:8787")
+
+  # Wallet-per-User requires a MANAGED custody provider (e.g. "privy") —
+  # SDP's local custody holds a single root wallet and rejects per-user
+  # wallet provisioning (Sdp::ProviderCapabilityError).
+  config.custody_provider = ENV["SDP_CUSTODY_PROVIDER"]
+
+  # Prefix for SDP wallet labels ("#{label_namespace}-user-#{id}") — guards
+  # against collisions when several apps share one SDP project. Defaults to
+  # the Rails application name.
+  # config.label_namespace = "myapp"
+
+  # The wallet-owner model (the one including Solrengine::Sdp::WalletOwner).
+  # Defaults to "User".
+  # config.user_class = "Account"
+
+  # Realtime broadcast targets — what bin/sdp_watcher re-fetches and pushes
+  # when a wallet's account changes on chain. Ordered: put fast,
+  # money-bearing regions first. The lambdas run in the watcher process,
+  # OUTSIDE any HTTP request: Current attributes and the session are
+  # unavailable, so partials must receive explicit locals.
+  #
+  # config.broadcast_targets = [
+  #   { name: :balance,
+  #     fetch: ->(user) { Solrengine::Sdp.client.wallet_balances(user.sdp_wallet_id) },
+  #     render: ->(user, balances) {
+  #       Turbo::StreamsChannel.broadcast_update_to(
+  #         [ user, :wallet ],
+  #         target: "wallet_balance",
+  #         partial: "wallets/balance",
+  #         locals: { balances: balances }
+  #       )
+  #     } }
+  # ]
+end