solrengine-sdp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb2f00e8f363ed1bacd78cf67bee25acbf50d1dd488b87fa00f8837512dd354b
+  data.tar.gz: 3ba656e022c2dfa6a866345d368e92767d085fa711b813cffa8035a3269c3c2b
+SHA512:
+  metadata.gz: 2ea6942f560cf9bc6fe428fb8a86d60c2658ce01466ca48937454b48639de37477478d76662caae635f9b038176df739f850a9a78895f78513dce487228254b1
+  data.tar.gz: ee990fd2117b0acd96da2cd54953de35b215a7aa16459585e3b1e58b58f52ce3ecaae4417e075dc7195b18e36d607a05b982d67c05cf36ed726ca76b0195b6b8

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jose Ferrer
+
+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,197 @@
+# solrengine-sdp
+
+Rails engine for **Wallet-per-User** custodial Solana wallets backed by the [Solana Developer Platform (SDP)](https://github.com/solana-foundation/solana-developer-platform). Your users sign up with an email — the engine provisions an SDP custody wallet for each of them, persists and tracks every transfer to a renderable terminal state, and pushes live balance updates to the browser when money moves on chain.
+
+It composes the SolRengine family: the [solana-sdp](https://github.com/solrengine/solana-sdp) API client underneath, [solrengine-realtime](https://github.com/solrengine/realtime) for WebSocket account subscriptions, and (optionally) [solrengine-tokens](https://github.com/solrengine/tokens) as a USD price source. This is the "you hold wallets for your users" path; for "your users bring their own wallets", see the rest of the family at [solrengine.org](https://solrengine.org).
+
+## Prerequisites
+
+Honest list — SDP is pre-mainnet and devnet-oriented, and Wallet-per-User has real infrastructure requirements:
+
+| You need | Why | Without it |
+|---|---|---|
+| A running SDP instance (self-hosted dev stack or managed) | The engine talks to SDP's wallets + payments API | Nothing works; boot check fails on a missing key |
+| A **managed custody provider** (e.g. [Privy](https://privy.io)) configured in SDP | Per-user wallet provisioning | Local custody holds a **single root wallet** and rejects `POST /v1/wallets` (`Sdp::ProviderCapabilityError`) |
+| **Kora** as SDP's fee-payment provider (`FEE_PAYMENT_PROVIDER=kora`) | Transfer execution | The native adapter can build and sign transfers but **cannot submit them** (`Sdp::TransferExecutionError`) |
+| An SDP API key with `custody:admin`, `wallets:*`, and `payments:*` scopes | Custody init, provisioning, balances, transfers | 403 `Sdp::InsufficientPermissions` |
+| A non-`async` Action Cable adapter in development | The watcher broadcasts from its own process | The install generator handles this — see [Cable adapter](#cable-adapter) |
+| A Helius-class RPC endpoint (for SPL token balances) | Public devnet RPC lacks the indexing SDP uses for token balances | SOL still works; SPL balance rows may be missing |
+
+## Quickstart
+
+From zero to a confirmed transfer updating the screen live:
+
+```sh
+rails new mywallet
+cd mywallet
+```
+
+Add to the `Gemfile`:
+
+```ruby
+gem "solrengine-sdp"
+gem "dotenv-rails", groups: [ :development, :test ] # or load .env your own way
+```
+
+Then:
+
+```sh
+bundle install
+bin/rails generate solrengine:sdp:install
+bin/rails db:migrate
+```
+
+The generator created migrations, `config/initializers/solrengine_sdp.rb`, `bin/sdp_watcher`, a `Procfile.dev` entry, `.env` keys, and switched development Action Cable to Solid Cable (follow its printed instructions for the `solid_cable_messages` table). Fill in `.env`:
+
+```sh
+SDP_API_KEY=sk_...                      # custody:admin + wallets:* + payments:* scopes
+SDP_API_BASE_URL=http://127.0.0.1:8787  # your SDP instance
+SDP_CUSTODY_PROVIDER=privy              # managed provider — see Prerequisites
+```
+
+Opt in to provisioning on signup — uncomment in `app/models/user.rb`:
+
+```ruby
+after_create_commit :provision_wallet!
+```
+
+Run everything (web + watcher):
+
+```sh
+bin/dev
+```
+
+Sign up a user — `provision_wallet!` drives `pending → provisioning → ready` and fills `wallet_address`. Fund it from the devnet faucet and move money:
+
+```ruby
+user = User.last
+user.wallet_ready? # => true
+
+# Devnet-only faucet (1 SOL). One attempt, never retried.
+Solrengine::Sdp::Faucet.new.request_airdrop(user.wallet_address, 1_000_000_000)
+
+# Persisted, tracked transfer — the returned row is what you render.
+transfer = Solrengine::Sdp::Transfer.execute!(
+  source: user.sdp_wallet_id,
+  destination: "RecipientPublicKeyBase58...",
+  amount: "0.1",
+  memo: "first transfer"
+)
+transfer.status # "processing" → tracked to "confirmed" → "finalized"
+```
+
+With `broadcast_targets` configured (see [Realtime](#realtime)) and a `turbo_stream_from` subscription on the page, the recipient's balance region updates live the moment the transfer lands — that is `bin/sdp_watcher` ringing the doorbell.
+
+## Configuration
+
+`config/initializers/solrengine_sdp.rb` (generated):
+
+```ruby
+Solrengine::Sdp.configure do |config|
+  config.api_key = ENV["SDP_API_KEY"]
+  # ...
+end
+```
+
+| Attribute | Default | Purpose |
+|---|---|---|
+| `api_key` | `ENV["SDP_API_KEY"]` | SDP API key. Missing key fails **at boot** (`ConfigurationError`), not at the first wallet call. |
+| `base_url` | `ENV["SDP_API_BASE_URL"]`, else `http://127.0.0.1:8787` | SDP API base URL. |
+| `custody_provider` | `ENV["SDP_CUSTODY_PROVIDER"]` | Custody provider passed on wallet creation. Must be a managed provider for Wallet-per-User. |
+| `label_namespace` | Rails app name, else `"app"` | Prefix for SDP wallet labels (`"#{namespace}-user-#{id}"`); guards collisions when apps share an SDP project. |
+| `user_class` | `"User"` | The wallet-owner model (the one including `Solrengine::Sdp::WalletOwner`). |
+| `logger` | `Rails.logger` | Engine log sink. |
+| `expired_transfer_deadline` | `900` (seconds) | Transfers stuck in `processing` past this settle as `expired`. |
+| `transfer_poll_interval` | `3` (seconds) | `TrackTransferJob` re-poll cadence. |
+| `broadcast_retries` | `3` | Attempts per doorbell ring (the notification never re-fires). |
+| `broadcast_retry_delay` | `2` (seconds) | Sleep between broadcast attempts (zero it in tests). |
+| `broadcast_targets` | `[]` | Ordered `{name:, fetch:, render:}` hashes — see [Realtime](#realtime). Empty means: log a hint, broadcast nothing. |
+
+## Realtime
+
+The WebSocket account subscription is a **doorbell, not a data feed**: the notification only signals *that* a wallet's account changed. `bin/sdp_watcher` (its own process, in `Procfile.dev`) holds one subscription per wallet-ready user; on any change `Solrengine::Sdp::Broadcaster` re-fetches everything displayed from the authoritative source (SDP) and pushes your configured Turbo Stream updates.
+
+The engine owns the doorbell invariants:
+
+- **All-or-nothing** — every target's `fetch` runs first; any failure (raise or `:unavailable`) means no renders this attempt, so screens never regress from good content to an error state. Last good content stays.
+- **Consumed doorbells retry** — the whole cycle retries `broadcast_retries` times, because a WebSocket notification never re-fires.
+- **Priority order** — renders run in configured order; put money-bearing regions first.
+- **Request-context-free** — lambdas run in the watcher process: no `Current`, no session, partials need explicit locals.
+
+```ruby
+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 }
+      )
+    } }
+]
+```
+
+USD enrichment inside fetch lambdas: `Solrengine::Sdp.usd_value_for(balance)` — SDP's own `usd_value` when present, Jupiter-derived when solrengine-tokens is installed, `nil` otherwise. Price failures never fail a fetch.
+
+**SOL-only doorbell in v0.1**: the system-account subscription sees lamport changes on the wallet address itself. SPL deposits land in Associated Token Accounts this subscription does not see — token balances are correct on page load, they just don't ring the doorbell yet. ATA subscriptions are planned.
+
+**Degradation contract**: if the watcher isn't running, screens are correct on load — they just don't update live.
+
+### Cable adapter
+
+Rails' default `async` Action Cable adapter delivers broadcasts **in-process only** — everything the watcher pushes from its own process is silently dropped: no error, no log, the browser just never updates. The install generator rewrites the development adapter to Solid Cable (or tells you exactly what to do when your cable.yml isn't the stock layout), and `bin/sdp_watcher` performs a boot-time broadcast self-check plus an explicit async-adapter warning so a broken cable backend dies loudly instead of broadcasting into the void.
+
+## Transfers
+
+`Solrengine::Sdp::Transfer` is the engine-owned audit row — created *before* the POST to SDP, so even a crash mid-request leaves evidence to reconcile against. The create POST is **never retried** (SDP has no idempotency key; a blind re-send risks a double-spend); timeouts are reconciled by a unique memo token instead.
+
+| Engine status | From | Terminal? | Meaning |
+|---|---|---|---|
+| `processing` | SDP `pending`/`processing` (and unrecognized statuses) | No | Submitted; `TrackTransferJob` polls until a verdict. |
+| `confirmed` | SDP `confirmed` | No | **User-facing success** — tracking continues to finalized. |
+| `finalized` | SDP `finalized` | Yes | Done. |
+| `failed` | SDP `failed`, SDP rejections, or unreachable-SDP (`sdp_error` prefixed `unsent:`) | Yes | Renderable reason on `sdp_error`. |
+| `expired` | engine-local | Yes | Stuck in `processing` past `expired_transfer_deadline` — verdict, not limbo. |
+| `unknown` | engine-local | No | POST read-timeout: outcome unknown. Reconciled via the memo token through SDP's transfer list — adopted if found, `failed` if provably absent. |
+
+`Transfer.execute!` runs a SOL balance preflight (`amount + 0.000005` fee buffer) and raises `InsufficientBalance` before any row or POST when the wallet provably can't cover it; an unreadable balance never blocks — the POST is the authority.
+
+## Errors
+
+Engine errors (all `< Solrengine::Sdp::Error < StandardError`):
+
+| Error | Raised |
+|---|---|
+| `Solrengine::Sdp::ConfigurationError` | Boot/configure time: missing API key, malformed broadcast targets. |
+| `Solrengine::Sdp::InsufficientBalance` | `Transfer.execute!` preflight — before any row or POST exists. |
+| `Solrengine::Sdp::Faucet::RateLimited` / `TimedOut` / `Unavailable` | Devnet faucet outcomes — `TimedOut` means the airdrop *may* still land; don't double-fund. |
+
+Transport and API errors raised while talking to SDP come from the client gem — `Sdp::Error` and its subclasses, including the two capability gates (`Sdp::ProviderCapabilityError` for local-custody provisioning, `Sdp::TransferExecutionError` for the native fee adapter). See the [solana-sdp error taxonomy](https://github.com/solrengine/solana-sdp#errors).
+
+## SDP compatibility
+
+Tested against SDP **v0.28** (`Solrengine::Sdp::COMPATIBLE_SDP_VERSION`). SDP is pre-1.0 and breaks its API between minors; the compatible version is bumped — and the suite re-verified — on every SDP upgrade rather than claiming an open-ended range.
+
+## Local development
+
+The Gemfile path-sources sibling checkouts: `../solana-sdp`, `../solrengine-realtime` (needs the `feat/subscriber-registry` branch for the 0.2 registry), `../solrengine-rpc`, and `../solrengine-tokens` (optional price source, dev-only — it is not a gemspec dependency). Clone them next to this repo, then:
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+Note: until solana-sdp and the realtime 0.2 branch are pushed to GitHub, CI's sibling-clone steps will fail remotely; local development is unaffected.
+
+## See also
+
+- [solana-sdp](https://github.com/solrengine/solana-sdp) — the plain-Ruby SDP API client this engine builds on (usable without Rails).
+- [solrengine](https://github.com/solrengine/solrengine) — the meta-gem for the connect-your-wallet path; this engine is deliberately not among its dependencies (custodial mode is opt-in).
+- [solrengine.org](https://solrengine.org) — the SolRengine family: the connect-your-wallet stack, and how both custody models compose.
+
+## License
+
+MIT

data/app/jobs/solrengine/sdp/provision_wallet_job.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Provisions an SDP custody wallet for a WalletOwner row, driving the
+    # four-state machine: pending → provisioning → ready | failed.
+    #
+    # Idempotent three ways:
+    #
+    #   1. The row is already ready → return immediately.
+    #   2. Optimistic claim: only the job that flips the row pending/failed →
+    #      provisioning proceeds; a duplicate concurrent job updates 0 rows
+    #      and returns without touching the network. A provisioning row whose
+    #      lease has lapsed (worker died between claim and settle) may be
+    #      taken over — see #claim.
+    #   3. Label adoption: when SDP already has a wallet labeled
+    #      "#{namespace}-user-#{id}" (a previous create succeeded but the
+    #      response was lost, e.g. a read timeout), adopt it instead of
+    #      creating a duplicate.
+    #
+    # Failure posture:
+    #
+    #   - Transport errors (Unavailable/Timeout) retry with backoff; the claim
+    #     stays held across retries (see #claim). Exhaustion lands the row in
+    #     failed with the transport reason — never a silent dead-letter.
+    #   - ProviderCapabilityError (the FL-10 gate: local custody cannot create
+    #     per-user wallets) is terminal: failed immediately, with the
+    #     actionable "use a managed provider" message renderable to the app.
+    #   - Any other Sdp::Error is equally terminal — retrying auth/validation
+    #     bugs changes nothing; the reason is stored, not buried in logs.
+    #
+    # Inherits ActiveJob::Base directly so the engine never depends on the
+    # host app's ApplicationJob being defined or compatible.
+    class ProvisionWalletJob < ActiveJob::Base
+      queue_as :default
+
+      # User deleted between enqueue and perform: nothing to provision.
+      discard_on ActiveJob::DeserializationError
+
+      # Block form fires on exhaustion (after the final attempt): settle the
+      # row in failed with the transport reason so the app can render it and
+      # offer retry_provisioning!.
+      retry_on ::Sdp::Unavailable, ::Sdp::Timeout,
+               wait: :polynomially_longer, attempts: 5 do |job, error|
+        job.mark_provisioning_failed(job.arguments.first, "Retries exhausted: #{error.message}")
+      end
+
+      def perform(user)
+        return if user.wallet_ready?
+        return unless claim(user)
+
+        wallet = existing_wallet_for(user) || create_wallet_for(user)
+        user.update!(
+          sdp_wallet_id: wallet.id,
+          wallet_address: wallet.public_key,
+          sdp_provisioning_state: "ready",
+          sdp_provisioning_error: nil
+        )
+      rescue ::Sdp::Unavailable, ::Sdp::Timeout
+        raise # retry_on handles backoff; the claim stays held for the retry
+      rescue ::Sdp::Error => e
+        # Terminal: capability gates (AE1) and auth/validation errors fail the
+        # same way no matter how often they are retried. Reason is renderable.
+        mark_provisioning_failed(user, e.message)
+      end
+
+      # Settles the row in failed — but only when this job holds the claim
+      # (row is in provisioning), so a stale job can never clobber a row
+      # another job has since taken to ready. Public because the retry_on
+      # exhaustion block runs outside the instance's private context.
+      def mark_provisioning_failed(user, reason)
+        user.class
+            .where(id: user.id, sdp_provisioning_state: "provisioning")
+            .update_all(sdp_provisioning_state: "failed", sdp_provisioning_error: reason)
+      end
+
+      private
+
+      # Optimistic claim: flip pending/failed → provisioning guarded by the
+      # current state; 1 row updated means this job owns the row, 0 means a
+      # concurrent job does — return without any network traffic. Retry
+      # executions (executions > 1) may resume from provisioning, because the
+      # claim was kept across the transient failure that triggered the retry.
+      #
+      # Stale-claim takeover: ANY execution (fresh jobs included, not just
+      # retries) may also take over a provisioning row whose updated_at is
+      # older than Configuration#provisioning_lease — a worker that died
+      # between claim and settle would otherwise strand the row forever.
+      # Takeover is safe because label adoption makes re-running safe: a
+      # completed-but-unrecorded create is adopted by label, so takeover
+      # cannot double-provision. And the lease prevents takeover of a LIVE
+      # job — every claim renews updated_at, and any live job's retries and
+      # settles touch updated_at well within the lease.
+      def claim(user)
+        claimable = %w[pending failed]
+        claimable += [ "provisioning" ] if executions > 1
+
+        lease_cutoff = Time.current - Solrengine::Sdp.configuration.provisioning_lease
+
+        user.class
+            .where(id: user.id, sdp_provisioning_state: claimable)
+            .or(
+              user.class.where(id: user.id, sdp_provisioning_state: "provisioning")
+                        .where(updated_at: ..lease_cutoff)
+            )
+            .update_all(sdp_provisioning_state: "provisioning", updated_at: Time.current) == 1
+      end
+
+      # GET /v1/wallets is not paginated at SDP v0.28 — the full list comes
+      # back in one response. list_wallets already routes through the client
+      # gem's paginating enumerator, so if SDP adds transfers-style pagination
+      # to wallets this scan keeps working unchanged.
+      def existing_wallet_for(user)
+        Solrengine::Sdp.client.list_wallets.find { |wallet| wallet.label == user.sdp_wallet_label }
+      end
+
+      def create_wallet_for(user)
+        Solrengine::Sdp.client.create_wallet(
+          label: user.sdp_wallet_label,
+          provider: Solrengine::Sdp.configuration.custody_provider
+        )
+      end
+    end
+  end
+end

data/app/jobs/solrengine/sdp/track_transfer_job.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Settles every Transfer row into a terminal state (R6). Two modes,
+    # keyed on the row's status:
+    #
+    #   processing/confirmed → poll get_transfer, map per the status table,
+    #     re-enqueue until terminal. A row stuck in processing past
+    #     Configuration#expired_transfer_deadline settles as engine-local
+    #     "expired" (SDP has no such status). confirmed keeps tracking —
+    #     it is user-facing success, but finalized is the terminal verdict.
+    #
+    #   unknown (the create POST read-timed out, the row never got an SDP id,
+    #     or SDP 404ed the id we had) → reconcile: scan the source wallet's
+    #     transfers for the engine memo token. Found → adopt the SDP row and
+    #     keep tracking; not found → re-enqueue and scan again until the
+    #     deadline settles it as failed "unsent (reconcile exhausted)".
+    #
+    # Deadline exhaustion is checked at the top of perform, BEFORE any SDP
+    # I/O, so an SDP outage can never keep a row unsettled past its deadline
+    # (an in-poll check would only fire after a successful GET).
+    #
+    # API errors never orphan a row (mirrors ProvisionWalletJob's posture):
+    # Unavailable/Timeout propagate to retry_on; NotFound flips the row to
+    # "unknown" so the memo token — not a 404 poll loop — decides; any other
+    # Sdp::Error re-enqueues within the deadline and settles the row failed
+    # (message renderable) past it.
+    #
+    # Backoff: a simple fixed wait (Configuration#transfer_poll_interval,
+    # default 3s) rather than exponential — Solana confirmation latency is
+    # bounded at seconds, and expired_transfer_deadline caps total tracking,
+    # so growing waits would only delay the verdict.
+    #
+    # Inherits ActiveJob::Base directly so the engine never depends on the
+    # host app's ApplicationJob (same posture as ProvisionWalletJob).
+    class TrackTransferJob < ActiveJob::Base
+      queue_as :default
+
+      # Transfer row deleted between enqueue and perform: nothing to track.
+      discard_on ActiveJob::DeserializationError
+
+      # Everything this job sends is a GET (get_transfer / list_transfers),
+      # so transport failures are always safe to retry — unlike the create
+      # POST, which is never retried. On exhaustion, hand off to a fresh job
+      # after the normal poll interval instead of orphaning the row: polling
+      # resumes when SDP comes back, and the expired deadline still bounds
+      # how long a processing row can stay unsettled.
+      retry_on ::Sdp::Unavailable, ::Sdp::Timeout,
+               wait: :polynomially_longer, attempts: 5 do |job, _error|
+        job.class.set(wait: job.class.poll_interval).perform_later(job.arguments.first)
+      end
+
+      def self.poll_interval
+        Solrengine::Sdp.configuration.transfer_poll_interval.seconds
+      end
+
+      def perform(transfer)
+        return if transfer.terminal?
+        return if settle_past_deadline(transfer)
+
+        if transfer.unknown?
+          reconcile(transfer)
+        else
+          poll(transfer)
+        end
+      rescue ::Sdp::Unavailable, ::Sdp::Timeout
+        raise # transport: retry_on owns backoff and the exhaustion handoff
+      rescue ::Sdp::NotFound
+        # The id provably doesn't exist at SDP — polling it would 404
+        # forever. Reconcile by memo token instead: it positively identifies
+        # OUR attempt (found → adopt; never found → the deadline settles
+        # the row as unsent).
+        transfer.update!(status: "unknown")
+        reenqueue(transfer)
+      rescue ::Sdp::Error => e
+        # Auth/rate-limit/validation errors must never strand the row in a
+        # dead-letter: within the deadline they read as an API hiccup —
+        # re-enqueue and try again; past it the row settles failed with the
+        # renderable reason.
+        if past_deadline?(transfer)
+          transfer.settle!("failed", sdp_error: e.message)
+        else
+          reenqueue(transfer)
+        end
+      end
+
+      private
+
+      # Deadline exhaustion, decided BEFORE any SDP I/O so the verdict lands
+      # even while SDP is down. Only processing rows expire — a confirmed row
+      # past the deadline is user-facing success already; expiring it would
+      # retract money the user saw move, so it keeps polling for finalized.
+      # Returns true when the row was settled.
+      def settle_past_deadline(transfer)
+        return false unless past_deadline?(transfer)
+
+        if transfer.processing?
+          transfer.settle!("expired")
+        elsif transfer.unknown?
+          # Reuses expired_transfer_deadline as the reconcile deadline: if
+          # the transfer existed, the scan would have found the memo token
+          # by now.
+          transfer.settle!("failed", sdp_error: "unsent (reconcile exhausted)")
+        else
+          return false
+        end
+
+        true
+      end
+
+      def poll(transfer)
+        # A SigningPending 202 whose details carried no id leaves a
+        # processing row with no sdp_transfer_id — there is nothing to GET
+        # (get_transfer(nil) is a malformed URL). Flip to "unknown" and
+        # reconcile by memo token, exactly like a timed-out create.
+        if transfer.sdp_transfer_id.nil?
+          transfer.update!(status: "unknown")
+          return reconcile(transfer)
+        end
+
+        transfer.adopt!(Solrengine::Sdp.client.get_transfer(transfer.sdp_transfer_id))
+        reenqueue(transfer) unless transfer.terminal?
+      end
+
+      def reconcile(transfer)
+        match = find_by_memo_token(transfer)
+
+        if match
+          transfer.adopt!(match)
+          reenqueue(transfer) unless transfer.terminal?
+        else
+          # Deadline exhaustion settles in perform, before any I/O; within
+          # the deadline, scan again next interval.
+          reenqueue(transfer)
+        end
+      end
+
+      # Scans ALL pages of the source wallet's transfers through the lazy
+      # enumerator. Simplest correct option: the match is normally on the
+      # first page (the attempt just happened), SDP exposes no created-at
+      # filter to cut the scan off at submitted_at, and the wallet-scoped
+      # list is small for any one user. The memo token positively identifies
+      # OUR attempt — no amount/recipient/time heuristics, so a concurrent
+      # identical transfer can never be claimed as this one.
+      def find_by_memo_token(transfer)
+        Solrengine::Sdp.client
+                       .list_transfers(wallet: transfer.source_wallet_id)
+                       .find { |row| row.memo.to_s.include?(transfer.memo_token) }
+      end
+
+      def past_deadline?(transfer)
+        Time.current - transfer.submitted_at > Solrengine::Sdp.configuration.expired_transfer_deadline
+      end
+
+      def reenqueue(transfer)
+        self.class.set(wait: self.class.poll_interval).perform_later(transfer)
+      end
+    end
+  end
+end