solrengine-sdp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb2f00e8f363ed1bacd78cf67bee25acbf50d1dd488b87fa00f8837512dd354b
-  data.tar.gz: 3ba656e022c2dfa6a866345d368e92767d085fa711b813cffa8035a3269c3c2b
+  metadata.gz: 15ecef7e5579d87685fb1fe3191d9695a679beeba31fc6df82df0c577477b85e
+  data.tar.gz: 76996291b77994894df747da458b0f017df58163be6d80ec7c20ce670b584259
 SHA512:
-  metadata.gz: 2ea6942f560cf9bc6fe428fb8a86d60c2658ce01466ca48937454b48639de37477478d76662caae635f9b038176df739f850a9a78895f78513dce487228254b1
-  data.tar.gz: ee990fd2117b0acd96da2cd54953de35b215a7aa16459585e3b1e58b58f52ce3ecaae4417e075dc7195b18e36d607a05b982d67c05cf36ed726ca76b0195b6b8
+  metadata.gz: e7ec3f5c1f15b148fbb80a18fd46773a44f5632da32b0de1e17196e08a273bc1335e66c46f28916985a6fe0610ebc311296e933fcad6adcb664d13b58d924d59
+  data.tar.gz: 641edbdf755534bdf0d64b9ecc3ff72c04a979b471a1a84048b96d4880d96eb7ec0a68e0d60d91620fc7742f9234eb2c1eb28a587bb7ff748ff92a75cf3bd1ac

data/README.md

@@ -158,6 +158,36 @@ Rails' default `async` Action Cable adapter delivers broadcasts **in-process onl
 
 `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.
 
+## Issuance
+
+`Solrengine::Sdp::Token` issues a fungible SPL token through SDP and records every supply action as an engine-owned audit row. Mint authority is a custodial signing wallet (`signing_wallet_id`).
+
+```ruby
+token = Solrengine::Sdp::Token.register!(           # off-chain record (create_token)
+  name: "Kudos Points", symbol: "KUDO", decimals: 0,
+  signing_wallet_id: treasury_wallet_id
+)
+token.deploy!                                       # on-chain mint (deploy_token)
+
+token.mint!(destination: user.wallet_address, amount: 10)  # credit — async, MintJob
+token.burn!(source: user.wallet_address,                   # debit  — async, BurnJob
+            signing_wallet_id: user.sdp_wallet_id, amount: 10)
+```
+
+`amount` is a **decimal token amount** — SDP scales it by the token's `decimals`, so `10` on a 0-decimal token is 10 whole tokens (it is **not** base units). Whole amounts are sent without a trailing `.0` (which SDP rejects for a 0-decimal token as "too many decimal places").
+
+Each `mint!`/`burn!` persists a `TokenMint`/`TokenBurn` row, then enqueues a single **never-retried** POST. The atomic claim (`minting → in_flight`) guarantees a mint/burn is never sent twice (SDP has no idempotency key); unlike a transfer there is no mint-transaction list to reconcile against, so a read-timeout lands `unknown` and is surfaced, never auto-re-sent.
+
+| Mint / Burn status | Terminal? | Meaning |
+|---|---|---|
+| `minting` / `burning` | No | Recorded, not yet sent. |
+| `in_flight` | No | Claimed; the POST is in flight. A crash here is left for manual reconcile, never re-sent. |
+| `minted` / `burned` | Yes | Confirmed on-chain. |
+| `failed` | Yes | SDP rejected it, or it was never sent — reason on `sdp_error`. |
+| `unknown` | No | POST read-timeout: outcome uncertain. Never re-sent; surfaced for review. |
+
+App-initiated issuance is its own doorbell: on settle, `MintJob`/`BurnJob` ring the balance broadcast (the configured `broadcast_targets`) for the affected wallet, so an earn/redeem updates the UI live — including the first — without relying on the chain-WebSocket watcher, which sees a wallet's native account, not the token ATA a mint credits.
+
 ## Errors
 
 Engine errors (all `< Solrengine::Sdp::Error < StandardError`):
@@ -172,7 +202,7 @@ Transport and API errors raised while talking to SDP come from the client gem
 
 ## 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.
+Tested against SDP **v0.31** (`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
 

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Sends a single burn to SDP, off the web request. The burn POST is NEVER
+    # retried; the atomic claim (burning → in_flight) guarantees a burn is
+    # never sent twice. Counterpart to MintJob — see it for the full rationale.
+    class BurnJob < ActiveJob::Base
+      queue_as :default
+
+      discard_on ActiveJob::DeserializationError
+
+      def perform(burn)
+        return unless burn.claim! # false → already attempted; never re-send
+
+        burn.submit_to_sdp!
+        # See MintJob: the burn is its own doorbell, so ring the source
+        # wallet's balance broadcast directly when the burn settles.
+        broadcast_balance(burn.source) if burn.burned?
+      end
+
+      private
+
+      def broadcast_balance(wallet_address)
+        Broadcaster.call(wallet_address)
+      rescue StandardError => e
+        Rails.logger&.warn("[Solrengine::Sdp::BurnJob] post-burn broadcast failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Sends a single mint to SDP, off the web request. The mint POST is NEVER
+    # retried — SDP has no idempotency key, so a blind re-send risks a
+    # double-mint. The atomic claim (minting → in_flight) means a crash +
+    # queue-retry, or two workers racing the same row, can never send twice:
+    # only the claim winner POSTs; a row already claimed is left as-is.
+    #
+    # Transport failures are handled INSIDE TokenMint#submit_to_sdp!
+    # (Timeout → unknown, Unavailable → failed), so this job never raises for
+    # an automatic retry to catch.
+    #
+    # Inherits ActiveJob::Base directly so the engine never depends on the
+    # host app's ApplicationJob (same posture as ProvisionWalletJob).
+    class MintJob < ActiveJob::Base
+      queue_as :default
+
+      # Row deleted between enqueue and perform: nothing to mint.
+      discard_on ActiveJob::DeserializationError
+
+      def perform(mint)
+        return unless mint.claim! # false → already attempted; never re-send
+
+        mint.submit_to_sdp!
+        # App-initiated issuance is its own doorbell. The chain-WebSocket
+        # watcher only sees a wallet's native account, not the token ATA a
+        # mint credits, so it never rings for an earn — but WE know the mint
+        # just landed. Ring the balance broadcast directly (every earn,
+        # including the first). A broadcast failure must never fail a settled
+        # mint: the money already moved.
+        broadcast_balance(mint.destination) if mint.minted?
+      end
+
+      private
+
+      def broadcast_balance(wallet_address)
+        Broadcaster.call(wallet_address)
+      rescue StandardError => e
+        Rails.logger&.warn("[Solrengine::Sdp::MintJob] post-mint broadcast failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "securerandom"
+
+module Solrengine
+  module Sdp
+    # Engine-owned record of a token issued through SDP: registered off-chain
+    # (create_token), then deployed on-chain (deploy_token), then minted/burned
+    # via supply actions. Mirrors Transfer's "the row is the audit trail"
+    # posture. Mint authority is signing_wallet_id (a custodial treasury wallet).
+    class Token < ActiveRecord::Base
+      self.table_name = "solrengine_sdp_tokens"
+
+      STATUSES = %w[created deployed failed].freeze
+
+      has_many :mints, class_name: "Solrengine::Sdp::TokenMint", dependent: :destroy
+      has_many :burns, class_name: "Solrengine::Sdp::TokenBurn", dependent: :destroy
+
+      validates :name, :symbol, :signing_wallet_id, presence: true
+      validates :decimals, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+      validates :status, inclusion: { in: STATUSES }
+
+      def deployed?
+        mint_address.present?
+      end
+
+      class << self
+        # Registers the token with SDP (off-chain record) and persists it.
+        # Raises Sdp::Error if SDP rejects it (no row is created).
+        def register!(name:, symbol:, signing_wallet_id:, decimals: 0)
+          sdp = Solrengine::Sdp.client.create_token(
+            name: name, symbol: symbol, decimals: decimals, signing_wallet_id: signing_wallet_id
+          )
+          create!(
+            name: name, symbol: symbol, decimals: decimals,
+            signing_wallet_id: signing_wallet_id, sdp_token_id: sdp.id, status: "created"
+          )
+        end
+      end
+
+      # Custodial sign-and-send deploy → on-chain mint. Records the mint
+      # address; on failure the row is marked failed and the error re-raised
+      # for the caller to render. Never retried (money-path).
+      def deploy!
+        sdp = Solrengine::Sdp.client.deploy_token(sdp_token_id)
+        update!(mint_address: sdp.mint_address, status: "deployed")
+        self
+      rescue ::Sdp::Error => e
+        update!(status: "failed", sdp_error: e.message)
+        raise
+      end
+
+      # Records a mint and enqueues MintJob (the mint POST runs off the web
+      # request, never retried). amount is a DECIMAL token amount — SDP scales
+      # it by the token's decimals (whole numbers for a 0-decimal token).
+      # Returns the TokenMint row.
+      def mint!(destination:, amount:, memo: nil)
+        mint = mints.create!(
+          destination: destination,
+          amount: normalize_amount(amount),
+          memo: memo,
+          memo_token: "#{TokenMint::MEMO_TOKEN_PREFIX}#{SecureRandom.hex(8)}",
+          status: "minting",
+          submitted_at: Time.current
+        )
+        MintJob.perform_later(mint)
+        mint
+      end
+
+      # Records a burn and enqueues BurnJob (never retried). A burn is signed
+      # by the source wallet's owner, so signing_wallet_id is the holder's
+      # custodial wallet (the user), NOT the treasury. Returns the TokenBurn.
+      def burn!(source:, signing_wallet_id:, amount:, memo: nil)
+        burn = burns.create!(
+          source: source,
+          signing_wallet_id: signing_wallet_id,
+          amount: normalize_amount(amount),
+          memo: memo,
+          memo_token: "#{TokenBurn::MEMO_TOKEN_PREFIX}#{SecureRandom.hex(8)}",
+          status: "burning",
+          submitted_at: Time.current
+        )
+        BurnJob.perform_later(burn)
+        burn
+      end
+
+      private
+
+      # BigDecimal#to_s("F") always renders a trailing ".0" — so a whole "10"
+      # becomes "10.0", which a 0-decimal token refuses ("Amount has too many
+      # decimal places"). Drop trailing fractional zeros (and the now-bare
+      # decimal point) so whole amounts go out as "10". SDP still enforces the
+      # token's decimals, so an over-precise amount surfaces as a failed write.
+      def normalize_amount(value)
+        BigDecimal(value.to_s).to_s("F").sub(/\.?0+\z/, "")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Engine-owned record of every burn attempted through SDP — the redeem-path
+    # counterpart to TokenMint, with the same never-double-* discipline.
+    #
+    # Status: burning → in_flight → burned | failed | unknown (see TokenMint
+    # for the rationale; a timed-out burn stays `unknown` — never re-sent, no
+    # listing to reconcile against).
+    #
+    # Unlike a mint (signed by the token's mint authority), a burn is signed by
+    # the SOURCE wallet's owner: signing_wallet_id is the user's custodial
+    # wallet, not the treasury.
+    class TokenBurn < ActiveRecord::Base
+      self.table_name = "solrengine_sdp_token_burns"
+
+      MEMO_TOKEN_PREFIX = "sdpburn-"
+      MEMO_SEPARATOR = " | "
+
+      STATUSES = %w[burning in_flight burned failed unknown].freeze
+      TERMINAL_STATUSES = %w[burned failed unknown].freeze
+
+      belongs_to :token, class_name: "Solrengine::Sdp::Token"
+
+      validates :source, :signing_wallet_id, :amount, :memo_token, presence: true
+      validates :status, inclusion: { in: STATUSES }
+
+      STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+      scope :unsettled, -> { where.not(status: TERMINAL_STATUSES) }
+
+      def pending?
+        %w[burning in_flight].include?(status)
+      end
+
+      # Atomic claim: burning → in_flight in one UPDATE, so a crash + retry or
+      # two workers can never send the same burn twice.
+      def claim!
+        won = self.class.where(id: id, status: "burning").update_all(status: "in_flight", updated_at: Time.current)
+        reload if won == 1
+        won == 1
+      end
+
+      # The single, never-retried burn POST.
+      def submit_to_sdp!
+        tx = Solrengine::Sdp.client.burn_token(
+          token.sdp_token_id,
+          signing_wallet_id: signing_wallet_id,
+          source: source,
+          amount: amount,
+          memo: composed_memo
+        )
+        update!(
+          status: terminal_for(tx.status),
+          signature: tx.signature,
+          sdp_transaction_id: tx.id,
+          sdp_error: tx.error,
+          settled_at: Time.current
+        )
+      rescue ::Sdp::Timeout
+        update!(status: "unknown")
+      rescue ::Sdp::Unavailable => e
+        update!(status: "failed", sdp_error: "unsent: #{e.message}", settled_at: Time.current)
+      rescue ::Sdp::Error => e
+        update!(status: "failed", sdp_error: e.message, settled_at: Time.current)
+      end
+
+      def composed_memo
+        [ memo, memo_token ].compact.join(MEMO_SEPARATOR)
+      end
+
+      private
+
+      def terminal_for(sdp_status)
+        case sdp_status.to_s
+        when "confirmed", "finalized" then "burned"
+        when "failed" then "failed"
+        else "unknown"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Engine-owned record of every mint attempted through SDP — the audit
+    # trail and the never-double-mint guard.
+    #
+    # Status machine:
+    #   minting   → just recorded, not yet sent (created before the POST)
+    #   in_flight → claimed by MintJob; the POST is being sent (atomic claim
+    #               so a crash + queue-retry never re-sends the same mint)
+    #   minted    → confirmed on-chain (terminal)
+    #   failed    → SDP rejected it, or it was never sent (terminal)
+    #   unknown   → the POST read-timed out: outcome uncertain. NEVER re-sent
+    #               (double-mint risk), and SDP exposes no mint-transaction
+    #               listing to reconcile against — surfaced for manual review.
+    #
+    # The mint POST is NEVER retried (SDP has no idempotency key). Unlike a
+    # Transfer there is no memo-token reconcile path (no list endpoint for
+    # mint transactions), so a timed-out mint stays `unknown` rather than
+    # auto-resolving.
+    class TokenMint < ActiveRecord::Base
+      self.table_name = "solrengine_sdp_token_mints"
+
+      MEMO_TOKEN_PREFIX = "sdpmint-"
+      MEMO_SEPARATOR = " | "
+
+      STATUSES = %w[minting in_flight minted failed unknown].freeze
+      TERMINAL_STATUSES = %w[minted failed unknown].freeze
+
+      belongs_to :token, class_name: "Solrengine::Sdp::Token"
+
+      validates :destination, :amount, :memo_token, presence: true
+      validates :status, inclusion: { in: STATUSES }
+
+      STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+      scope :unsettled, -> { where.not(status: TERMINAL_STATUSES) }
+
+      def pending?
+        %w[minting in_flight].include?(status)
+      end
+
+      # Atomic claim: minting → in_flight in one UPDATE. Returns true only for
+      # the caller that won the claim, so a crash + queue-retry (or two workers)
+      # can never send the same mint twice. A row stuck in_flight is a
+      # crashed-mid-send and is left for manual reconcile, never auto-re-sent.
+      def claim!
+        won = self.class.where(id: id, status: "minting").update_all(status: "in_flight", updated_at: Time.current)
+        reload if won == 1
+        won == 1
+      end
+
+      # The single, never-retried mint POST. Every outcome lands on the row.
+      def submit_to_sdp!
+        tx = Solrengine::Sdp.client.mint_token(
+          token.sdp_token_id,
+          signing_wallet_id: token.signing_wallet_id,
+          destination: destination,
+          amount: amount,
+          memo: composed_memo
+        )
+        update!(
+          status: terminal_for(tx.status),
+          signature: tx.signature,
+          sdp_transaction_id: tx.id,
+          token_account: tx.token_account,
+          sdp_error: tx.error,
+          settled_at: Time.current
+        )
+      rescue ::Sdp::Timeout
+        # Outcome unknown — NEVER re-send. No mint-tx listing to reconcile.
+        update!(status: "unknown")
+      rescue ::Sdp::Unavailable => e
+        # Request never processed — safe to mark failed (no money moved).
+        update!(status: "failed", sdp_error: "unsent: #{e.message}", settled_at: Time.current)
+      rescue ::Sdp::Error => e
+        update!(status: "failed", sdp_error: e.message, settled_at: Time.current)
+      end
+
+      def composed_memo
+        [ memo, memo_token ].compact.join(MEMO_SEPARATOR)
+      end
+
+      private
+
+      # mint_token returns a confirmed TokenTransaction on success. A non-
+      # confirmed status can't be polled (no get-mint endpoint), so anything
+      # that isn't clearly confirmed/finalized or failed lands as unknown.
+      def terminal_for(sdp_status)
+        case sdp_status.to_s
+        when "confirmed", "finalized" then "minted"
+        when "failed" then "failed"
+        else "unknown"
+        end
+      end
+    end
+  end
+end

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

@@ -21,7 +21,13 @@ module Solrengine
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      MIGRATIONS = %w[add_solrengine_sdp_to_users create_solrengine_sdp_transfers].freeze
+      MIGRATIONS = %w[
+        add_solrengine_sdp_to_users
+        create_solrengine_sdp_transfers
+        create_solrengine_sdp_tokens
+        create_solrengine_sdp_token_mints
+        create_solrengine_sdp_token_burns
+      ].freeze
 
       # The exact development block `rails new` emits — the only async config
       # this generator rewrites mechanically. Anything else async-but-custom

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

@@ -0,0 +1,25 @@
+# Engine-owned record of every burn attempted through SDP — the audit trail
+# and the never-double-burn guard. See Solrengine::Sdp::TokenBurn.
+class CreateSolrengineSdpTokenBurns < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solrengine_sdp_token_burns do |t|
+      t.references :token, null: false, foreign_key: { to_table: :solrengine_sdp_tokens }
+      t.string :source, null: false            # wallet (pubkey) the tokens are burned from
+      t.string :signing_wallet_id, null: false # SDP wallet that signs (the source's owner)
+      t.string :amount, null: false            # decimal token amount — never a float
+      t.string :memo
+      t.string :memo_token, null: false        # engine reconcile token
+      t.string :status, null: false, default: "burning" # burning -> burned | failed | unknown
+      t.string :signature
+      t.string :sdp_transaction_id
+      t.string :sdp_error
+      t.datetime :submitted_at
+      t.datetime :settled_at
+
+      t.timestamps
+    end
+
+    add_index :solrengine_sdp_token_burns, :memo_token, unique: true
+    add_index :solrengine_sdp_token_burns, :status
+  end
+end

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

@@ -0,0 +1,25 @@
+# Engine-owned record of every mint attempted through SDP — the audit trail
+# and the never-double-mint guard. See Solrengine::Sdp::TokenMint.
+class CreateSolrengineSdpTokenMints < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solrengine_sdp_token_mints do |t|
+      t.references :token, null: false, foreign_key: { to_table: :solrengine_sdp_tokens }
+      t.string :destination, null: false
+      t.string :amount, null: false          # decimal token amount — never a float
+      t.string :memo                         # app memo (composes with memo_token)
+      t.string :memo_token, null: false      # engine reconcile token
+      t.string :status, null: false, default: "minting" # minting -> minted | failed | unknown
+      t.string :signature
+      t.string :sdp_transaction_id
+      t.string :token_account
+      t.string :sdp_error
+      t.datetime :submitted_at
+      t.datetime :settled_at
+
+      t.timestamps
+    end
+
+    add_index :solrengine_sdp_token_mints, :memo_token, unique: true
+    add_index :solrengine_sdp_token_mints, :status
+  end
+end

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

@@ -0,0 +1,20 @@
+# Engine-owned record of a token issued through SDP — created off-chain, then
+# deployed on-chain. See Solrengine::Sdp::Token for the lifecycle.
+class CreateSolrengineSdpTokens < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solrengine_sdp_tokens do |t|
+      t.string :sdp_token_id           # SDP token record id (set on create)
+      t.string :mint_address           # on-chain mint (set on deploy)
+      t.string :name, null: false
+      t.string :symbol, null: false
+      t.integer :decimals, null: false, default: 0
+      t.string :signing_wallet_id, null: false # mint authority (treasury)
+      t.string :status, null: false, default: "created" # created -> deployed -> failed
+      t.string :sdp_error
+
+      t.timestamps
+    end
+
+    add_index :solrengine_sdp_tokens, :sdp_token_id, unique: true
+  end
+end

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

@@ -19,6 +19,11 @@ Solrengine::Sdp.configure do |config|
   # the Rails application name.
   # config.label_namespace = "myapp"
 
+  # Default fiat ramp provider (e.g. "bvnk"). The ramps helper injects it so
+  # you don't repeat `provider:` on every call: Solrengine::Sdp.ramps.onramp_quote(...).
+  # Leave unset to pass `provider:` per call instead.
+  # config.ramp_provider = ENV["SDP_RAMP_PROVIDER"]
+
   # The wallet-owner model (the one including Solrengine::Sdp::WalletOwner).
   # Defaults to "User".
   # config.user_class = "Account"
@@ -42,3 +47,14 @@ Solrengine::Sdp.configure do |config|
   #     } }
   # ]
 end
+
+# Token issuance and fiat ramps (new in v0.2) need no extra config — reach them
+# through the client and the ramps helper:
+#
+#   Solrengine::Sdp.client.create_token(name: "...", symbol: "...", signing_wallet_id: "...")
+#   Solrengine::Sdp.client.mint_token(token_id, signing_wallet_id: "...", destination: "...", amount: "...")
+#   Solrengine::Sdp.ramps.onramp_quote(counterparty_id: "...", destination_wallet: "...",
+#                                      crypto_token: "SOL", fiat_currency: "USD", fiat_amount: "100")
+#
+# Ramps are SANDBOX-ONLY in v0.2 (preview). Mint/burn/deploy are money-path:
+# like transfers they need FEE_PAYMENT_PROVIDER=kora on a self-hosted SDP.

data/lib/solrengine/sdp/configuration.rb

@@ -15,7 +15,7 @@ module Solrengine
       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
+      attr_writer :api_key, :base_url, :custody_provider, :ramp_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
@@ -50,6 +50,13 @@ module Solrengine
         @custody_provider || ENV["SDP_CUSTODY_PROVIDER"]
       end
 
+      # Default fiat ramp provider (e.g. "bvnk") for the ramps helper, so apps
+      # don't repeat `provider:` on every on/off-ramp call. nil is fine — the
+      # caller can pass `provider:` per call instead. Sandbox-only in v0.2.
+      def ramp_provider
+        @ramp_provider || ENV["SDP_RAMP_PROVIDER"]
+      end
+
       # Prefix for SDP wallet labels ("#{label_namespace}-user-#{id}").
       # Defaults to the Rails application name, else "app".
       def label_namespace

data/lib/solrengine/sdp/ramps.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Solrengine
+  module Sdp
+    # Thin engine wrapper over solana-sdp's ramps surface (SDP fiat on/off-ramps).
+    # Its only job is to default `provider:` from config.ramp_provider so apps
+    # don't repeat it on every call — the same convenience custody_provider gives
+    # wallet calls. Everything else passes straight through to the client; there
+    # is no model and no extra state.
+    #
+    # SANDBOX-ONLY in v0.2: wired against SDP's ramp surface and verified against
+    # the sandbox, not live fiat rails. Treat as preview.
+    class Ramps
+      # provider may be nil (no configured default) — then callers must pass
+      # `provider:` per call, and the client validates it.
+      def initialize(client:, provider: nil)
+        @client = client
+        @provider = provider
+      end
+
+      def onramp_currencies(**kwargs)
+        @client.onramp_currencies(**with_provider(kwargs))
+      end
+
+      def offramp_currencies(**kwargs)
+        @client.offramp_currencies(**with_provider(kwargs))
+      end
+
+      def onramp_quote(**kwargs)
+        @client.onramp_quote(**with_provider(kwargs))
+      end
+
+      def onramp_execute(**kwargs)
+        @client.onramp_execute(**with_provider(kwargs))
+      end
+
+      def offramp_execute(**kwargs)
+        @client.offramp_execute(**with_provider(kwargs))
+      end
+
+      # The sandbox event hook — no provider involved; pure passthrough.
+      def simulate_ramp(**payload)
+        @client.simulate_ramp(**payload)
+      end
+
+      private
+
+      # Inject the configured provider unless the caller named one explicitly
+      # (an explicit `provider: nil` is honored — it means "don't scope").
+      def with_provider(kwargs)
+        return kwargs if kwargs.key?(:provider) || @provider.nil?
+
+        kwargs.merge(provider: @provider)
+      end
+    end
+  end
+end

data/lib/solrengine/sdp/version.rb

@@ -2,10 +2,10 @@
 
 module Solrengine
   module Sdp
-    VERSION = "0.1.0"
+    VERSION = "0.3.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"
+    COMPATIBLE_SDP_VERSION = "0.31"
   end
 end

data/lib/solrengine/sdp.rb

@@ -10,6 +10,7 @@ require_relative "sdp/configuration"
 require_relative "sdp/wallet_owner"
 require_relative "sdp/broadcaster"
 require_relative "sdp/faucet"
+require_relative "sdp/ramps"
 require_relative "sdp/engine" if defined?(Rails::Engine)
 
 module Solrengine
@@ -33,6 +34,7 @@ module Solrengine
       def configure
         yield(configuration)
         @client = nil
+        @ramps = nil
         configuration
       end
 
@@ -41,13 +43,22 @@ module Solrengine
       def client
         @client ||= ::Sdp::Client.new(
           api_key: configuration.validate!.api_key,
-          base_url: configuration.base_url
+          base_url: configuration.base_url,
+          custody_provider: configuration.custody_provider
         )
       end
 
+      # Thin ramps helper bound to the configured client + default ramp
+      # provider. Reset alongside the client whenever configure runs.
+      # Sandbox-only in v0.2 (see Solrengine::Sdp::Ramps).
+      def ramps
+        @ramps ||= Ramps.new(client: client, provider: configuration.ramp_provider)
+      end
+
       def reset_configuration!
         @configuration = nil
         @client = nil
+        @ramps = nil
       end
 
       # Pure function over rake task names so the exemption logic is

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solrengine-sdp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jose Ferrer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: solrengine-realtime
   requirement: !ruby/object:Gem::Requirement
@@ -63,12 +63,20 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- app/jobs/solrengine/sdp/burn_job.rb
+- app/jobs/solrengine/sdp/mint_job.rb
 - app/jobs/solrengine/sdp/provision_wallet_job.rb
 - app/jobs/solrengine/sdp/track_transfer_job.rb
+- app/models/solrengine/sdp/token.rb
+- app/models/solrengine/sdp/token_burn.rb
+- app/models/solrengine/sdp/token_mint.rb
 - app/models/solrengine/sdp/transfer.rb
 - lib/generators/solrengine/sdp/install_generator.rb
 - lib/generators/solrengine/sdp/templates/add_solrengine_sdp_to_users.rb
 - lib/generators/solrengine/sdp/templates/cable.yml
+- lib/generators/solrengine/sdp/templates/create_solrengine_sdp_token_burns.rb
+- lib/generators/solrengine/sdp/templates/create_solrengine_sdp_token_mints.rb
+- lib/generators/solrengine/sdp/templates/create_solrengine_sdp_tokens.rb
 - lib/generators/solrengine/sdp/templates/create_solrengine_sdp_transfers.rb
 - lib/generators/solrengine/sdp/templates/initializer.rb
 - lib/generators/solrengine/sdp/templates/sdp_watcher
@@ -79,6 +87,7 @@ files:
 - lib/solrengine/sdp/engine.rb
 - lib/solrengine/sdp/errors.rb
 - lib/solrengine/sdp/faucet.rb
+- lib/solrengine/sdp/ramps.rb
 - lib/solrengine/sdp/version.rb
 - lib/solrengine/sdp/wallet_owner.rb
 homepage: https://github.com/solrengine/sdp