solrengine-sdp 0.1.0

data/lib/generators/solrengine/sdp/templates/sdp_watcher

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SDP realtime wallet watcher — run as its own process alongside your web
+# server (Procfile.dev: `watcher: bin/sdp_watcher`).
+#
+# Holds one accountSubscribe WebSocket per wallet-ready user. On any account
+# change, Solrengine::Sdp::Broadcaster re-fetches the displayed data from SDP
+# and pushes the app's configured Turbo Stream updates — the doorbell
+# pattern: the WebSocket carries no data, it only signals THAT something
+# changed.
+#
+# SOL-ONLY in v0.1: the system-account subscription sees lamport changes on
+# the wallet address itself. SPL token deposits land in Associated Token
+# Accounts this subscription does NOT see — token balances are still correct
+# on page load, they just don't ring the doorbell. ATA subscriptions are
+# planned follow-up work.
+#
+# Degradation contract: if this process isn't running, screens are correct on
+# load — they just don't update live.
+
+require_relative "../config/environment"
+
+SCAN_INTERVAL = 30 # seconds between wallet-ready re-scans (picks up new wallets)
+
+rpc = Solrengine::Rpc.configuration
+puts "[SdpWatcher] Network: #{rpc.network}"
+puts "[SdpWatcher] WS: #{rpc.ws_url.sub(/api-key=.*/, "api-key=***")}"
+
+# Register the engine's broadcaster on the realtime subscriber registry.
+Solrengine::Sdp.start_realtime!
+puts "[SdpWatcher] Broadcaster subscribed as #{Solrengine::Sdp::REALTIME_SUBSCRIBER_NAME.inspect}"
+
+# --- Boot-time broadcast self-check ------------------------------------------
+# A broadcast that raises here means the cable backend is broken (e.g. the
+# Solid Cable database is missing — run bin/rails db:prepare). Better to die
+# loudly now than to broadcast into the void all session.
+if defined?(Turbo)
+  Turbo::StreamsChannel.broadcast_replace_to(
+    "solrengine_sdp_ping", target: "solrengine_sdp_ping", html: ""
+  )
+  puts "[SdpWatcher] Cable self-check broadcast sent"
+
+  # The async adapter accepts broadcasts but delivers them IN-PROCESS ONLY:
+  # everything this watcher pushes would be silently dropped — no error, no
+  # log, the browser just never updates. Warn as loudly as we can.
+  cable = begin
+    ActionCable.server.config.cable
+  rescue StandardError
+    nil
+  end
+  adapter = cable && (cable["adapter"] || cable[:adapter])
+  if adapter.to_s == "async"
+    warn <<~MSG
+      [SdpWatcher] ################################################################
+      [SdpWatcher] # Action Cable is using the `async` adapter — IN-PROCESS ONLY #
+      [SdpWatcher] ################################################################
+      [SdpWatcher] Cross-process broadcasts from this watcher will be SILENTLY
+      [SdpWatcher] DROPPED: no error, no log, the browser simply never updates.
+      [SdpWatcher] Switch development to solid_cable (or redis) in config/cable.yml
+      [SdpWatcher] and RESTART your web server — a running Puma holds the old
+      [SdpWatcher] adapter in memory. See the solrengine-sdp README.
+    MSG
+  else
+    puts "[SdpWatcher] Cable adapter: #{adapter || "unknown"} (cross-process delivery OK)"
+  end
+else
+  warn "[SdpWatcher] turbo-rails is not loaded — broadcasts are no-ops. Add `gem \"turbo-rails\"`."
+end
+
+monitors = {}
+running = true
+
+%w[INT TERM].each do |signal|
+  trap(signal) { running = false }
+end
+
+user_model = Solrengine::Sdp.configuration.user_model
+
+while running
+  begin
+    addresses = user_model.wallet_ready.pluck(:wallet_address)
+
+    addresses.each do |address|
+      next if monitors[address]
+
+      puts "[SdpWatcher] Subscribing to #{address}"
+      monitor = Solrengine::Realtime::AccountMonitor.new(address)
+      monitor.start
+      monitors[address] = monitor
+
+      # Re-fetch-and-broadcast on every NEW subscription: the wallet may have
+      # changed before we started watching (post-provisioning funding lag, or
+      # this watcher restarting). On its own thread — the broadcaster sleeps
+      # between retries and must not stall the scan loop.
+      Thread.new do
+        Solrengine::Sdp::Broadcaster.call(address)
+      rescue => e
+        puts "[SdpWatcher] Catch-up broadcast for #{address.inspect} failed: #{e.class}: #{e.message}"
+      end
+    rescue ArgumentError => e
+      # One malformed address must not poison the whole scan pass — log it
+      # and keep subscribing the rest (AccountMonitor validates base58).
+      puts "[SdpWatcher] Skipping #{address.inspect}: #{e.message}"
+    end
+
+    (monitors.keys - addresses).each do |address|
+      puts "[SdpWatcher] Unsubscribing from #{address}"
+      monitors.delete(address).stop
+    end
+  rescue => e
+    puts "[SdpWatcher] Scan error: #{e.class}: #{e.message}"
+  end
+
+  # Transfer-tracking recovery: re-enqueue TrackTransferJob for unsettled
+  # rows nothing is polling anymore (a crash between the row's create! and
+  # the tracking enqueue, or queue data loss). Safe to run every pass — the
+  # model's updated_at guard skips rows under active tracking.
+  begin
+    resumed = Solrengine::Sdp::Transfer.resume_tracking!
+    puts "[SdpWatcher] Resumed tracking for #{resumed} unsettled transfer(s)" if resumed > 0
+  rescue => e
+    puts "[SdpWatcher] Transfer recovery error: #{e.class}: #{e.message}"
+  end
+
+  SCAN_INTERVAL.times do
+    break unless running
+    sleep 1
+  end
+end
+
+puts "[SdpWatcher] Shutting down…"
+monitors.each_value(&:stop)
+Solrengine::Sdp.stop_realtime!

data/lib/solrengine/sdp/broadcaster.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Turns a chain-change signal ("this wallet's account changed") into the
+    # app's configured broadcasts — or into silence. The WebSocket
+    # notification is only a doorbell: it carries no data. The broadcaster
+    # re-fetches everything displayed from the authoritative source (SDP) and
+    # broadcasts only when every fetch succeeded, so screens never regress
+    # from good content to an "unavailable" state mid-session; the last good
+    # content simply stays.
+    #
+    # The app supplies broadcast targets — via Solrengine::Sdp.configure or
+    # the targets: argument — as an ordered array of hashes:
+    #
+    #   config.broadcast_targets = [
+    #     { name: :activity,
+    #       fetch:  ->(user) { ActivityFeed.entries_for(user) },
+    #       render: ->(user, entries) {
+    #         Turbo::StreamsChannel.broadcast_update_to(
+    #           user.realtime_stream, target: "activity",
+    #           partial: "activity/feed", locals: { entries: entries })
+    #       } },
+    #     { name: :balance, fetch: ..., render: ... }
+    #   ]
+    #
+    # The ENGINE owns the doorbell invariants; the lambdas own the app
+    # specifics:
+    #
+    #   * All-or-nothing: every target's fetch runs first, in configured
+    #     order. Any fetch raising — or returning :unavailable — means NO
+    #     renders at all this attempt (nil is valid data; signal "I could not
+    #     fetch" with :unavailable or an exception).
+    #   * Consumed doorbells retry: a WebSocket notification never re-fires,
+    #     so a transient SDP hiccup would otherwise permanently miss the
+    #     update. The WHOLE cycle (fetch + render) retries up to
+    #     configuration.broadcast_retries attempts, sleeping
+    #     broadcast_retry_delay seconds between attempts (zero it in tests).
+    #     Safe to sleep: solrengine-realtime invokes subscribers on a
+    #     dedicated per-wallet broadcast thread.
+    #   * Priority order: renders run in the configured array order — put
+    #     fast, money-bearing regions first, decorative ones last.
+    #   * Request-context-free: lambdas run in a watcher process, outside any
+    #     HTTP request. Current.user, session, and request-thread locals are
+    #     nil; partials need explicit locals.
+    #
+    # USD enrichment inside fetch lambdas: Solrengine::Sdp.usd_value_for(balance)
+    # — SDP's usd_value when present, Jupiter-derived when solrengine-tokens
+    # is available, nil otherwise. Price failures never fail a fetch.
+    #
+    # Turbo deliberately never appears in this class: render lambdas do the
+    # actual broadcasting, so the engine core carries no turbo-rails
+    # dependency and the invariants are testable without it.
+    class Broadcaster
+      TARGET_KEYS = %i[name fetch render].freeze
+
+      def self.call(wallet_address, targets: nil)
+        new(wallet_address, targets: targets).call
+      end
+
+      def initialize(wallet_address, targets: nil)
+        @wallet_address = wallet_address
+        @targets = validate_targets(targets || configuration.broadcast_targets)
+      end
+
+      # Resolves the wallet owner and runs the broadcast cycle. Unknown or
+      # not-yet-ready wallets (the fee payer, external counterparties) are a
+      # silent no-op — not ours to broadcast. Returns true when a cycle
+      # completed, false when retries were exhausted, nil on no-op.
+      def call
+        if @targets.empty?
+          logger&.info(
+            "[Solrengine::Sdp::Broadcaster] No broadcast_targets configured — nothing to broadcast. " \
+            "Set config.broadcast_targets in a Solrengine::Sdp.configure block to enable realtime updates."
+          )
+          return
+        end
+
+        # This executes on a long-lived per-wallet broadcast thread
+        # (solrengine-realtime), NOT inside an HTTP request. Rails only
+        # auto-releases AR connections at request boundaries, so a bare
+        # find_by here permanently holds a connection on the thread.  With
+        # a default pool of 5 that means the sixth wallet's broadcast
+        # raises ConnectionTimeoutError — rescued by the realtime registry
+        # and silently dropped. with_connection returns the lease to the
+        # pool as soon as the block exits, before the fetch/render/sleep
+        # cycle starts. App-provided fetch lambdas may also touch the DB;
+        # that is the app's concern and is intentionally out of this scope.
+        user = ActiveRecord::Base.connection_pool.with_connection do
+          configuration.user_model.wallet_ready.find_by(wallet_address: @wallet_address)
+        end
+        return unless user
+
+        attempts = configuration.broadcast_retries
+        attempts.times do |attempt|
+          return true if attempt_broadcast(user)
+
+          sleep configuration.broadcast_retry_delay unless attempt == attempts - 1
+        end
+
+        logger&.warn(
+          "[Solrengine::Sdp::Broadcaster] Giving up on #{@wallet_address}: " \
+          "SDP unavailable — keeping last good content"
+        )
+        false
+      end
+
+      private
+
+      # One fetch-and-broadcast attempt. True when every fetch succeeded and
+      # every render ran; false on any failure so the caller can retry.
+      # Never renders partial data. A render raising also fails the attempt —
+      # the whole cycle re-runs, which is safe because renders re-broadcast
+      # the same regions with fresh data.
+      def attempt_broadcast(user)
+        data = fetch_all(user)
+        return false unless data
+
+        @targets.each { |target| target[:render].call(user, data[target[:name]]) }
+        true
+      rescue StandardError => e
+        logger&.warn(
+          "[Solrengine::Sdp::Broadcaster] Attempt for #{@wallet_address} failed: #{e.class}: #{e.message}"
+        )
+        false
+      end
+
+      # Runs every fetch in configured order. Returns the data keyed by
+      # target name, or nil as soon as any fetch returns :unavailable.
+      def fetch_all(user)
+        @targets.each_with_object({}) do |target, data|
+          value = target[:fetch].call(user)
+          return nil if value == :unavailable
+
+          data[target[:name]] = value
+        end
+      end
+
+      # Misconfigured targets are a programming error, not a transient
+      # failure — fail loudly at construction, outside the retry loop.
+      def validate_targets(targets)
+        targets = Array(targets)
+        targets.each do |target|
+          unless target.respond_to?(:[]) && target[:name] &&
+                 target[:fetch].respond_to?(:call) && target[:render].respond_to?(:call)
+            raise ConfigurationError,
+              "Each broadcast target needs #{TARGET_KEYS.map(&:inspect).join(', ')} " \
+              "with callable fetch/render, got: #{target.inspect}"
+          end
+        end
+        targets
+      end
+
+      def configuration
+        Solrengine::Sdp.configuration
+      end
+
+      def logger
+        configuration.logger
+      end
+    end
+  end
+end

data/lib/solrengine/sdp/configuration.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Engine configuration: explicit attributes with ENV fallbacks
+    # (rpc/auth family pattern — a real class, not bare mattr_accessor).
+    #
+    #   Solrengine::Sdp.configure do |config|
+    #     config.api_key    = Rails.application.credentials.dig(:sdp, :api_key)
+    #     config.user_class = "Account"
+    #   end
+    class Configuration
+      DEFAULT_BASE_URL = "http://127.0.0.1:8787"
+      DEFAULT_EXPIRED_TRANSFER_DEADLINE = 15 * 60 # seconds
+      DEFAULT_TRANSFER_POLL_INTERVAL = 3 # seconds — confirmation is usually seconds away
+      DEFAULT_PROVISIONING_LEASE = 10 * 60 # seconds — see provisioning_lease below
+
+      attr_writer :api_key, :base_url, :custody_provider, :label_namespace, :logger
+      # provisioning_lease (seconds): how long a wallet-owner row may sit in
+      # "provisioning" untouched before the claim is considered abandoned
+      # (worker died between claim and settle) and another job may take it
+      # over. Any live job renews the row's updated_at well within this
+      # window, so a takeover can only hit a genuinely dead claim.
+      attr_accessor :user_class, :expired_transfer_deadline, :transfer_poll_interval,
+                    :provisioning_lease,
+                    :broadcast_retry_delay, :broadcast_retries, :broadcast_targets
+
+      def initialize
+        @user_class = "User"
+        @expired_transfer_deadline = DEFAULT_EXPIRED_TRANSFER_DEADLINE
+        @transfer_poll_interval = DEFAULT_TRANSFER_POLL_INTERVAL
+        @provisioning_lease = DEFAULT_PROVISIONING_LEASE
+        @broadcast_retry_delay = 2
+        @broadcast_retries = 3
+        # Ordered array of {name:, fetch:, render:} hashes — see Broadcaster.
+        # Empty by default: the Broadcaster logs a hint and broadcasts
+        # nothing until the app configures its targets.
+        @broadcast_targets = []
+      end
+
+      def api_key
+        @api_key || ENV["SDP_API_KEY"]
+      end
+
+      def base_url
+        @base_url || ENV.fetch("SDP_API_BASE_URL", DEFAULT_BASE_URL)
+      end
+
+      def custody_provider
+        @custody_provider || ENV["SDP_CUSTODY_PROVIDER"]
+      end
+
+      # Prefix for SDP wallet labels ("#{label_namespace}-user-#{id}").
+      # Defaults to the Rails application name, else "app".
+      def label_namespace
+        @label_namespace || default_label_namespace
+      end
+
+      # Lazily constantized so the engine can be configured before the app's
+      # user model is loadable (initializer-time safe).
+      def user_model
+        Object.const_get(user_class)
+      end
+
+      # Engine log sink: Rails.logger in a Rails host, $stdout otherwise.
+      # Tests assign a StringIO-backed logger to assert on log lines.
+      def logger
+        @logger ||= default_logger
+      end
+
+      # Boot check used by the engine's after_initialize hook, also callable
+      # directly. A missing key must fail loudly at boot, not at the first
+      # wallet call.
+      def validate!
+        return self unless api_key.to_s.strip.empty?
+
+        raise ConfigurationError,
+          "Solrengine::Sdp api_key is not set. The engine cannot talk to the SDP API without it. " \
+          "Set the SDP_API_KEY environment variable (start the local SDP stack and export the " \
+          "seeded key) or assign config.api_key in a Solrengine::Sdp.configure block. " \
+          "Optionally set SDP_API_BASE_URL (default: #{DEFAULT_BASE_URL})."
+      end
+
+      private
+
+      def default_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          require "logger"
+          ::Logger.new($stdout)
+        end
+      end
+
+      def default_label_namespace
+        name = rails_application_name
+        name.nil? || name.empty? ? "app" : name
+      end
+
+      def rails_application_name
+        return nil unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+        Rails.application.class.name&.split("::")&.first&.downcase
+      end
+    end
+  end
+end

data/lib/solrengine/sdp/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    class Engine < ::Rails::Engine
+      isolate_namespace Solrengine::Sdp
+
+      # A missing API key must fail loudly at boot, not at the first wallet
+      # call. Exemptions:
+      #   - test env: suites stub HTTP and configure explicitly
+      #   - infrastructure rake tasks (assets:, db:, app:, ...): CI and
+      #     Docker image builds run these without production secrets
+      config.after_initialize do
+        next if Rails.env.test?
+        next if Solrengine::Sdp.exempt_rake_context?
+
+        Solrengine::Sdp.configuration.validate!
+      end
+    end
+  end
+end

data/lib/solrengine/sdp/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Engine-level errors. Transport/API errors raised while talking to SDP
+    # live in the solana-sdp client gem (Sdp::Error and subclasses); these
+    # are the errors the ENGINE itself raises.
+    class Error < StandardError; end
+
+    # Raised at boot/configure time when the engine cannot operate
+    # (see Configuration#validate!).
+    class ConfigurationError < Error; end
+
+    # Raised by Transfer.execute! when the balance preflight shows the source
+    # wallet cannot cover amount + fee buffer. Raised BEFORE any row is
+    # created and before any POST is made — there is nothing to reconcile,
+    # the app just renders the message and lets the user adjust the amount.
+    class InsufficientBalance < Error; end
+  end
+end

data/lib/solrengine/sdp/faucet.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Solrengine
+  module Sdp
+    # DEVNET-ONLY faucet client: POSTs JSON-RPC requestAirdrop straight to a
+    # Solana devnet RPC for a wallet's public key. Mainnet has no faucet —
+    # pointing this at a mainnet RPC just yields Unavailable errors. Picking
+    # a devnet/localnet RPC URL is the caller's responsibility (the default
+    # is the public devnet endpoint).
+    #
+    # One attempt, NEVER retried — an airdrop that timed out may still land,
+    # and retrying just burns the per-address faucet allowance. Callers decide
+    # what to do on failure (e.g. fall back to a treasury transfer).
+    class Faucet
+      DEFAULT_RPC_URL = "https://api.devnet.solana.com"
+      OPEN_TIMEOUT = 2 # seconds — fail fast, funding flows are user-facing
+      READ_TIMEOUT = 5 # seconds
+
+      # The faucet reports rate limiting either as HTTP 429 or as a JSON-RPC
+      # error whose message mentions the airdrop/rate limit.
+      RATE_LIMIT_PATTERN = /rate.?limit|too many requests|airdrop limit|limit reached|429/i
+
+      class Error < Solrengine::Sdp::Error; end
+
+      # HTTP 429, or a JSON-RPC error that reads like a rate limit. The caller
+      # should cool down before asking again.
+      class RateLimited < Error; end
+
+      # Connection failure, non-2xx status, or an unusable/erroneous RPC
+      # response — the airdrop definitely did not happen. The faucet may work
+      # again shortly; use a fallback now.
+      class Unavailable < Error; end
+
+      # The request was sent but no response arrived in time. The airdrop MAY
+      # still land — the outcome is unknown, so callers must NOT treat this as
+      # failure and must not double-fund through a fallback.
+      class TimedOut < Error; end
+
+      attr_reader :rpc_url
+
+      def initialize(rpc_url: ENV.fetch("SOLANA_RPC_URL", DEFAULT_RPC_URL),
+                     open_timeout: OPEN_TIMEOUT,
+                     read_timeout: READ_TIMEOUT)
+        @rpc_url = rpc_url
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      # Requests `lamports` for `address`. Returns the airdrop transaction
+      # signature on success; raises RateLimited, TimedOut, or Unavailable
+      # otherwise.
+      def request_airdrop(address, lamports)
+        uri = URI.parse(@rpc_url)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(
+          jsonrpc: "2.0", id: 1, method: "requestAirdrop", params: [ address, lamports ]
+        )
+
+        response = Net::HTTP.start(
+          uri.host, uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: @open_timeout,
+          read_timeout: @read_timeout
+        ) { |http| http.request(request) }
+
+        handle(response)
+      rescue Net::OpenTimeout => e
+        # Connection never opened — the airdrop request was definitely not
+        # sent. Unavailable (not TimedOut) so a funding fallback may run
+        # without any double-funding risk.
+        raise Unavailable, "Faucet unreachable (connect timeout): #{e.message}"
+      rescue Net::ReadTimeout => e
+        raise TimedOut, "Faucet timed out: #{e.message}"
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, SocketError, EOFError => e
+        raise Unavailable, "Faucet unreachable: #{e.message}"
+      end
+
+      private
+
+      def handle(response)
+        status = response.code.to_i
+        raise RateLimited, "Faucet rate limited (HTTP 429)" if status == 429
+        raise Unavailable, "Faucet returned HTTP #{status}" unless (200..299).cover?(status)
+
+        body = parse_json(response.body)
+        raise Unavailable, "Faucet returned an unreadable response" unless body.is_a?(Hash)
+
+        if (error = body["error"])
+          message = error.is_a?(Hash) ? error["message"].to_s : error.to_s
+          raise RateLimited, "Faucet rate limited: #{message}" if message.match?(RATE_LIMIT_PATTERN)
+
+          raise Unavailable, "Faucet error: #{message.empty? ? 'unknown' : message}"
+        end
+
+        signature = body["result"]
+        raise Unavailable, "Faucet response carried no signature" if signature.to_s.empty?
+
+        signature
+      end
+
+      def parse_json(raw)
+        return nil if raw.nil? || raw.empty?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/solrengine/sdp/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    VERSION = "0.1.0"
+
+    # The SDP release this engine version is tested against. SDP breaks its
+    # API between minors; bump this (and re-verify) on every SDP upgrade.
+    COMPATIBLE_SDP_VERSION = "0.28"
+  end
+end

data/lib/solrengine/sdp/wallet_owner.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Solrengine
+  module Sdp
+    # Mixin for the host app's user (wallet-owner) model. Expects four columns
+    # (the install generator adds them):
+    #
+    #   sdp_wallet_id           :string  — SDP's walletId once provisioned
+    #   wallet_address          :string  — the wallet's Solana public key
+    #   sdp_provisioning_state  :string, default: "pending", null: false
+    #   sdp_provisioning_error  :string  — renderable failure reason
+    #
+    # Provisioning is a state machine, not a fire-and-forget job:
+    #
+    #   pending → provisioning → ready | failed
+    #   failed  → pending                          (retry_provisioning!)
+    #   provisioning (stale) → pending             (retry_provisioning! — a
+    #     row whose updated_at is past Configuration#provisioning_lease was
+    #     abandoned by a dead worker, never settled by a live one)
+    #
+    # ProvisionWalletJob drives every transition; "still provisioning" and
+    # "permanently wallet-less" are always distinguishable, and a failure
+    # carries a reason the app can render and re-trigger.
+    #
+    # Provisioning timing is the app's call — the concern deliberately wires
+    # NO callback. To provision on signup, add one line to the host model:
+    #
+    #   after_create_commit :provision_wallet!
+    #
+    # States are plain strings rather than a Rails enum so the mixin cannot
+    # collide with the host model's own enums or generated methods.
+    module WalletOwner
+      extend ActiveSupport::Concern
+
+      PROVISIONING_STATES = %w[pending provisioning ready failed].freeze
+
+      included do
+        # Users whose custody wallet is fully provisioned — the only ones that
+        # can move money or appear in wallet-keyed UI (recipients, feeds).
+        scope :wallet_ready, -> { where(sdp_provisioning_state: "ready") }
+      end
+
+      # Tolerates NULL (rows predating the column default): no state is pending.
+      def wallet_provisioning_state
+        self[:sdp_provisioning_state].presence || "pending"
+      end
+
+      def wallet_pending?
+        wallet_provisioning_state == "pending"
+      end
+
+      def wallet_provisioning?
+        wallet_provisioning_state == "provisioning"
+      end
+
+      def wallet_ready?
+        wallet_provisioning_state == "ready"
+      end
+
+      def wallet_failed?
+        wallet_provisioning_state == "failed"
+      end
+
+      # SDP wallet label this user provisions under. The namespace prefix
+      # guards against cross-app collisions when several apps share one SDP
+      # project (see Configuration#label_namespace).
+      def sdp_wallet_label
+        "#{Solrengine::Sdp.configuration.label_namespace}-user-#{id}"
+      end
+
+      # A provisioning row whose lease has lapsed: no live job has touched it
+      # within Configuration#provisioning_lease (every claim/retry/settle
+      # renews updated_at), so the worker that claimed it died before
+      # settling. Stale rows are re-enqueueable; fresh ones belong to a live
+      # job and must be left alone.
+      def wallet_provisioning_stale?
+        wallet_provisioning? &&
+          updated_at <= Time.current - Solrengine::Sdp.configuration.provisioning_lease
+      end
+
+      # Enqueues provisioning. No-op (with a log line) when the wallet is
+      # already ready or a live job currently owns the row; from failed it
+      # re-enqueues — the job's claim accepts failed rows, so an explicit
+      # reset via retry_provisioning! is equivalent but also clears the error.
+      # A STALE provisioning row (lease lapsed — the claiming worker died
+      # before settling) also re-enqueues: the job's claim takes over expired
+      # leases, and label adoption makes the re-run double-provision-safe.
+      def provision_wallet!
+        if wallet_ready? || (wallet_provisioning? && !wallet_provisioning_stale?)
+          Solrengine::Sdp.configuration.logger&.info(
+            "[Solrengine::Sdp] provision_wallet! no-op for #{self.class.name}##{id}: " \
+            "state is #{wallet_provisioning_state}"
+          )
+          return false
+        end
+
+        ProvisionWalletJob.perform_later(self)
+      end
+
+      # Re-arms a failed row — or a STALE provisioning row abandoned by a
+      # dead worker: clears the stored reason, resets to pending, and
+      # enqueues a fresh job. Anything else (including provisioning rows a
+      # live job still owns) is a no-op returning false.
+      def retry_provisioning!
+        return false unless wallet_failed? || wallet_provisioning_stale?
+
+        update!(sdp_provisioning_state: "pending", sdp_provisioning_error: nil)
+        ProvisionWalletJob.perform_later(self)
+      end
+    end
+  end
+end