solana-sdp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e006d934cc75d32a431afa36112f78edb06d66dce75632eb3d5247b8c491d29b
-  data.tar.gz: 3766da4b325de50624bb961f60521e07705eb3b70a9115e5be4681152c6083a7
+  metadata.gz: 40f9c383ab53b7693e6e15e12e335c0208d8633cfa8a750ec7d6a3084a4756c0
+  data.tar.gz: 9ecfe4071cf77cf3b8325e1bd3706dd268cc6066b28133609bf93eb855968a32
 SHA512:
-  metadata.gz: e43f33123cccad9386df7844d227861ffa61499d6a873a90629d32273a62e1f7c9b365add4eff823bf504f204e78106d7f3456de4ec823ed8042772912b42e9e
-  data.tar.gz: 245615dd77504bd7a4d5890e9868ad01b0137f5c58d8aba6efd02c5b20dbedb98e64d2fecb36cfd705989bd13481e81767bf7ffbf9db210abf1a022d4f56d319
+  metadata.gz: 82039b60fa7238c66705ea80e82e9c2e885d003e831c802912788332c89add10a8d33a5cfea315d40b4ba5e6d4771ec52040ba9a714ec15bda237eff2cad9c5b
+  data.tar.gz: db82971084b1dad62945fc36539b7be3c354d8cd0049ac45905c26cb1823ba5edc2ac16bb5bd682841b80a82837b12d1f74b38f91a6b4f5d15267cd0beaded48

data/README.md

@@ -1,10 +1,10 @@
 # solana-sdp
 
-Ruby SDK for the [Solana Developer Platform](https://github.com/solana-foundation/solana-developer-platform) (SDP) wallets and payments API.
+Ruby SDK for the [Solana Developer Platform](https://github.com/solana-foundation/solana-developer-platform) (SDP) wallets, payments, token-issuance, and ramp APIs.
 
 Plain Ruby, zero runtime dependencies (`Net::HTTP`), typed rescuable errors that mirror SDP's real failure modes, and a retry posture that never re-sends a transfer.
 
-> SDP is pre-mainnet, unaudited, and devnet-oriented — so is this gem. Tested against SDP **v0.28** (see [Version pin](#version-pin) below).
+> SDP is pre-mainnet, unaudited, and devnet-oriented — so is this gem. Tested against SDP **v0.31** (see [Version pin](#version-pin) below).
 
 ## Install
 
@@ -67,7 +67,28 @@ end
 
 Also available: `prepare_transfer` (build but don't sign/send, for non-custodial flows), `get_transfer`, `list_wallets`.
 
-`list_wallets` returns an **Array** (`[Sdp::Wallet, ...]`) today — SDP does not paginate `/v1/wallets` at v0.28, so the result is fetched eagerly. When SDP adds pagination this will become a lazy Enumerator (matching `list_transfers`). Use Enumerable methods (`.find`, `.each`, `.map`) rather than array indexing or `.length` to stay forward-compatible.
+`list_wallets` returns an **Array** (`[Sdp::Wallet, ...]`) today — SDP does not paginate `/v1/wallets` at v0.31, so the result is fetched eagerly. When SDP adds pagination this will become a lazy Enumerator (matching `list_transfers`). Use Enumerable methods (`.find`, `.each`, `.map`) rather than array indexing or `.length` to stay forward-compatible.
+
+## Custody providers
+
+SDP wallets are created under a custody provider. Configure it once — on the client or via `SDP_CUSTODY_PROVIDER` — and every wallet operation (`initialize_custody`, `create_wallet`, `list_wallets`) uses it unless you pass an explicit `provider:`:
+
+```ruby
+client = Sdp::Client.new(custody_provider: "privy")   # or set SDP_CUSTODY_PROVIDER
+client.custody_provider          # => "privy"
+client.create_wallet(label: "user-42")                # uses "privy"
+client.create_wallet(label: "x", provider: "turnkey") # per-call override
+```
+
+Provider matrix (v0.2):
+
+| Provider | Wallet-per-User | Status |
+|---|---|---|
+| **Privy** (managed) | Yes | **Verified** end-to-end on devnet |
+| Other managed providers (e.g. Turnkey) | Yes (per SDP) | Pass-through — forwarded to SDP, not independently verified here |
+| **Local** custody | **No** | Holds a single root wallet; `create_wallet` raises `Sdp::ProviderCapabilityError` |
+
+Wallet-per-User requires a **managed** provider. With local custody, SDP exposes one root wallet and rejects `POST /v1/wallets` — the gem turns that into a typed `Sdp::ProviderCapabilityError` whose message tells you to set a managed provider (see below). The gem does **not** maintain an allow-list of provider names — `provider:` is forwarded to SDP, which is the authority on what it supports, so new SDP providers work without a gem release.
 
 ## Error taxonomy
 
@@ -90,7 +111,7 @@ Everything raised by this gem subclasses `Sdp::Error`, which carries `#code`, `#
 | `Sdp::Unavailable` | Connection refused/reset, connect timeout, or a 5xx that isn't a recognized capability gate | Yes — the request wasn't processed |
 | `Sdp::TransferExecutionError` (< `Sdp::Error`) | 502 `SOLANA_RPC_ERROR` carrying SDP's NativeAdapter signature — the fee-payment provider cannot submit transactions. **Not caught by `rescue Sdp::Unavailable`** — it is not a transient error | No — configuration fix |
 
-Two of these encode SDP capability gates that otherwise surface as cryptic generic errors (discriminator strings verified against SDP v0.28, documented in `lib/sdp/errors.rb`):
+Two of these encode SDP capability gates that otherwise surface as cryptic generic errors (discriminator strings verified against SDP v0.31, documented in `lib/sdp/errors.rb`):
 
 - **`Sdp::ProviderCapabilityError`** — with local custody, SDP holds a single root wallet and `POST /v1/wallets` is rejected ("Wallet provisioning not supported for provider: local"). Wallet-per-User requires a managed provider (e.g. privy): pass `provider:` to `create_wallet` or set `SDP_CUSTODY_PROVIDER`. Also raised when `initialize_custody` is called twice for the same org+project (409) — initialization is one-time.
 - **`Sdp::TransferExecutionError`** — with `FEE_PAYMENT_PROVIDER=native`, SDP can build and sign transfers but cannot submit them; the 502 message contains the `NativeAdapter` signature. Fix: run Kora and set `FEE_PAYMENT_PROVIDER=kora`. A 502 that does *not* match this signature stays `Sdp::Unavailable` — a real RPC outage is never mislabeled as a configuration problem.
@@ -98,7 +119,7 @@ Two of these encode SDP capability gates that otherwise surface as cryptic gener
 ## Retry posture
 
 - **GETs retry exactly once** on `Sdp::Timeout` / `Sdp::Unavailable` (transport-level failures), then raise.
-- **POSTs never retry.** SDP has no idempotency key at v0.28: re-sending a transfer after a read timeout risks a double-spend, because the first attempt may have landed on-chain. On `Sdp::Timeout` from a write, reconcile first (e.g. `list_transfers` filtered by wallet, or match a memo) before re-submitting.
+- **POSTs never retry.** SDP has no idempotency key at v0.31: re-sending a transfer after a read timeout risks a double-spend, because the first attempt may have landed on-chain. On `Sdp::Timeout` from a write, reconcile first (e.g. `list_transfers` filtered by wallet, or match a memo) before re-submitting.
 - `Sdp::TransactionFailed` is never retried blindly — it reports an on-chain outcome, not a transport failure.
 - `Sdp::Unavailable` means the request was not processed (connection never opened, or a 5xx without SDP's error envelope), so it is safe to retry — with backoff for `Sdp::RateLimited`.
 
@@ -109,16 +130,25 @@ Wallet-scoped API keys return **404 (not 403)** for wallets outside their scope.
 ## Version pin
 
 ```ruby
-Sdp::COMPATIBLE_SDP_VERSION # => "0.28"
+Sdp::COMPATIBLE_SDP_VERSION # => "0.31"
 ```
 
-SDP breaks its API between minor versions. Every release of this gem names the SDP version it was tested against, both here and in the `Sdp::COMPATIBLE_SDP_VERSION` constant. The covered API surface is pinned to a vendored copy of SDP's OpenAPI spec (`spec/openapi-v0.28.json`); contract tests assert every field this gem reads exists in that spec, and `rake "sdp:drift[path/to/newer/openapi.json]"` diffs a newer SDP spec against the pin to report exactly which covered endpoints changed. On an SDP version bump: re-vendor the spec, re-run the contract tests, update `COMPATIBLE_SDP_VERSION`.
+SDP breaks its API between minor versions. Every release of this gem names the SDP version it was tested against, both here and in the `Sdp::COMPATIBLE_SDP_VERSION` constant. The covered API surface is pinned to a vendored copy of SDP's OpenAPI spec (`spec/openapi-v0.31.json`); contract tests assert every field this gem reads exists in that spec, and `rake "sdp:drift[path/to/newer/openapi.json]"` diffs a newer SDP spec against the pin to report exactly which covered endpoints changed. On an SDP version bump: re-vendor the spec, re-run the contract tests, update `COMPATIBLE_SDP_VERSION`.
 
 Running against a different SDP version may work, but field shapes (e.g. `usdValue` on balances) are known to change between minors.
 
 ## Scope
 
-This gem covers SDP's wallets and payments surface: custody initialization, wallet provisioning and listing, balances, and transfers (create/prepare/list/get). Ramps, issuance, and the dashboard APIs are out of scope.
+This gem covers SDP's wallets, payments, token-issuance, and ramp surface:
+
+- **Wallets** — custody initialization, wallet provisioning and listing, balances.
+- **Payments** — transfers (create / prepare / list / get).
+- **Issuance** (token lifecycle) — tokens (list / get / create / deploy) and supply actions (mint / burn), each action with a `prepare` variant for caller-signed flows.
+- **Ramps** *(sandbox-only)* — fiat on/off-ramps: currency discovery, on-ramp quote, on/off-ramp execute, and the sandbox `simulate` hook. **Wired against SDP's ramp surface and verified against the sandbox, not live fiat rails** — treat as preview in v0.2.
+
+The issuance compliance actions (freeze/unfreeze, pause, authority, allowlist, seize, force-burn) and the dashboard APIs are out of scope.
+
+> **Custodial issuance needs Kora.** `deploy_token`, `mint_token`, and `burn_token` are custodial sign-and-send and route through SDP's fee-payment adapter — like transfers, they require `FEE_PAYMENT_PROVIDER=kora` on a self-hosted SDP (the `native` adapter cannot submit transactions and returns a typed `Sdp::TransferExecutionError`). The `prepare_*` variants build an unsigned transaction and are unaffected.
 
 A Rails engine builds on this client — Wallet-per-User provisioning, transfer persistence, and realtime balance updates — as [solrengine-sdp](https://github.com/solrengine/sdp).
 

data/lib/sdp/client.rb

@@ -4,11 +4,14 @@ require "net/http"
 require "openssl"
 require "json"
 require "uri"
+require "bigdecimal"
 
 require_relative "errors"
 require_relative "pagination"
 require_relative "resources/wallets"
 require_relative "resources/payments"
+require_relative "resources/issuance"
+require_relative "resources/ramps"
 
 module Sdp
   # Zero-dependency Net::HTTP request core for the SDP API.
@@ -25,6 +28,8 @@ module Sdp
   class Client
     include Resources::Wallets
     include Resources::Payments
+    include Resources::Issuance
+    include Resources::Ramps
 
     DEFAULT_BASE_URL = "http://127.0.0.1:8787"
     OPEN_TIMEOUT = 2  # seconds — fail fast when the stack isn't up
@@ -40,10 +45,11 @@ module Sdp
     # meta (hasMore/page), so the request layer always carries both.
     Response = Struct.new(:data, :meta, keyword_init: true)
 
-    attr_reader :base_url
+    attr_reader :base_url, :custody_provider
 
     def initialize(base_url: ENV.fetch("SDP_API_BASE_URL", DEFAULT_BASE_URL),
                    api_key: ENV["SDP_API_KEY"],
+                   custody_provider: ENV["SDP_CUSTODY_PROVIDER"],
                    open_timeout: OPEN_TIMEOUT,
                    read_timeout: READ_TIMEOUT)
       # Strip first, then guard: an ENV key with a trailing newline passes a
@@ -69,6 +75,13 @@ module Sdp
           "host, got #{@base_url.inspect}. Pass base_url: or set the SDP_API_BASE_URL environment variable."
       end
 
+      # The default custody provider for wallet operations, configured once here
+      # (or via SDP_CUSTODY_PROVIDER) so callers don't repeat provider: on every
+      # create_wallet/initialize_custody. Blank → nil (fall through to SDP's own
+      # default). This is what makes the ProviderCapabilityError hint actionable.
+      provider = custody_provider.to_s.strip
+      @custody_provider = provider.empty? ? nil : provider
+
       @open_timeout = open_timeout
       @read_timeout = read_timeout
     end
@@ -225,7 +238,7 @@ module Sdp
 
     # FL-10/FL-11: SDP reports custody/fee-payment capability gates as
     # generic 400/409/502 responses. Discriminators verified against SDP
-    # v0.28 (pattern constants documented in errors.rb). The upstream
+    # v0.31 (pattern constants documented in errors.rb). The upstream
     # message is preserved and the fix is appended, so logs keep the
     # original evidence.
     def capability_gate(klass, status, code, message, path)
@@ -289,5 +302,24 @@ module Sdp
     def underscore_key(key)
       key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
     end
+
+    # Shared resource helpers — defined once on the HTTP layer the resource
+    # modules mix into, rather than duplicated per module.
+
+    # Percent-encode a caller-supplied id before interpolating it into a path.
+    def encode_path_segment(segment)
+      URI.encode_uri_component(segment.to_s)
+    end
+
+    # Serialize a money amount to a plain decimal string. Integer/String pass
+    # through unchanged (Integer#to_s never uses scientific notation); a Float
+    # is routed through BigDecimal so a small value like 1e-07 serializes as
+    # "0.0000001" rather than "1.0e-07", which SDP rejects. Prefer passing
+    # base-unit amounts as strings — Floats are lossy.
+    def amount_string(amount)
+      return amount.to_s unless amount.is_a?(Float)
+
+      BigDecimal(amount.to_s).to_s("F")
+    end
   end
 end

data/lib/sdp/coverage.rb

@@ -2,7 +2,7 @@
 
 module Sdp
   # The curated SDP surface this gem covers, pinned against the vendored
-  # OpenAPI spec (spec/openapi-v0.28.json). Consumed by the contract tests
+  # OpenAPI spec (spec/openapi-v0.31.json). Consumed by the contract tests
   # (test/sdp/contract_test.rb) and the sdp:drift rake task.
   #
   # Path templates use the {param} style of SDP's generated spec. When a
@@ -21,9 +21,25 @@ module Sdp
     BALANCE_FIELDS = %w[token mint amount uiAmount decimals usdValue].freeze
     # Fields read by Sdp::Transfer.from_hash.
     TRANSFER_FIELDS = %w[id direction status signature token amount source destination memo error createdAt].freeze
+    # Fields read by Sdp::Token.from_hash. extensions is passed through untyped.
+    TOKEN_FIELDS = %w[id projectId signingWalletId mintAddress mintAuthority freezeAuthority name symbol
+                      decimals description uri imageUrl template extensions totalSupply maxSupply isMintable
+                      isFreezable requiresAllowlist status deployedAt createdAt updatedAt].freeze
+    # Fields read by Sdp::TokenTransaction.from_hash (the mint/burn action record).
+    TOKEN_TX_FIELDS = %w[id tokenId type status signature serializedTx params slot blockTime fee error
+                         createdAt updatedAt].freeze
+    # The unsigned-transaction envelope shared by the .../prepare responses.
+    PREPARED_TX_FIELDS = %w[serialized blockhash lastValidBlockHeight].freeze
+    # Fields read by Sdp::RampQuote.from_hash. The *Currency members are passed
+    # through untyped, so only their presence at data.quote is pinned.
+    RAMP_QUOTE_FIELDS = %w[id provider status deliveryMode hostedUrl paymentInstructions exchangeRate
+                           totalSendingAmount sendingCurrency totalReceivingAmount receivingCurrency
+                           feesIncluded feeCurrency expiresAt].freeze
+    # Fields read by Sdp::RampExecution.from_hash.
+    RAMP_EXECUTION_FIELDS = %w[id provider status redirectUrl paymentInstructions reference].freeze
 
     COVERED_ENDPOINTS = [
-      # NOTE: at v0.28 the initialize 201 response has NO data envelope —
+      # NOTE: at v0.31 the initialize 201 response has NO data envelope —
       # configId/publicKey/walletId sit at the schema root.
       Endpoint.new(method: "post", path: "/v1/wallets/initialize", success_status: "201",
                    reads: { [] => %w[configId publicKey walletId] }),
@@ -43,7 +59,59 @@ module Sdp
       Endpoint.new(method: "get", path: "/v1/payments/transfers", success_status: "200",
                    reads: { [ "data", "[]" ] => TRANSFER_FIELDS }),
       Endpoint.new(method: "get", path: "/v1/payments/transfers/{transferId}", success_status: "200",
-                   reads: { %w[data transfer] => TRANSFER_FIELDS })
+                   reads: { %w[data transfer] => TRANSFER_FIELDS }),
+
+      # Issuance — token lifecycle + supply actions (v0.2). list returns a bare
+      # data array; create/get/deploy wrap the token in data.token. mint/burn
+      # return the action record at data.transaction; mint also carries
+      # data.tokenAccount. The prepare variants differ: deploy/prepare puts the
+      # unsigned tx at data.transaction with a sibling data.mint, while
+      # mint/burn prepare keep the record at data.transaction and the unsigned
+      # tx at data.preparedTransaction.
+      Endpoint.new(method: "get", path: "/v1/issuance/tokens", success_status: "200",
+                   reads: { [ "data", "[]" ] => TOKEN_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens", success_status: "201",
+                   reads: { %w[data token] => TOKEN_FIELDS }),
+      Endpoint.new(method: "get", path: "/v1/issuance/tokens/{tokenId}", success_status: "200",
+                   reads: { %w[data token] => TOKEN_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/deploy", success_status: "200",
+                   reads: { %w[data token] => TOKEN_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/deploy/prepare", success_status: "200",
+                   reads: { %w[data] => %w[transaction mint simulation],
+                            %w[data transaction] => PREPARED_TX_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/mint", success_status: "200",
+                   reads: { %w[data] => %w[transaction tokenAccount],
+                            %w[data transaction] => TOKEN_TX_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/mint/prepare", success_status: "200",
+                   reads: { %w[data] => %w[transaction preparedTransaction tokenAccount simulation],
+                            %w[data transaction] => TOKEN_TX_FIELDS,
+                            %w[data preparedTransaction] => PREPARED_TX_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/burn", success_status: "200",
+                   reads: { %w[data transaction] => TOKEN_TX_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/issuance/tokens/{tokenId}/burn/prepare", success_status: "200",
+                   reads: { %w[data] => %w[transaction preparedTransaction simulation],
+                            %w[data transaction] => TOKEN_TX_FIELDS,
+                            %w[data preparedTransaction] => PREPARED_TX_FIELDS }),
+
+      # Ramps (v0.2, sandbox-only). currency endpoints return nested discovery
+      # data; quote wraps the record in data.quote, execute in data.ramp; the
+      # sandbox hook returns data.transaction (untyped passthrough).
+      Endpoint.new(method: "get", path: "/v1/payments/ramps/onramp/currency", success_status: "200",
+                   reads: { %w[data] => %w[currencies pairs supportHash],
+                            %w[data currencies] => %w[sources destinations],
+                            [ "data", "pairs", "[]" ] => %w[source dest providers] }),
+      Endpoint.new(method: "get", path: "/v1/payments/ramps/offramp/currency", success_status: "200",
+                   reads: { %w[data] => %w[currencies pairs supportHash],
+                            %w[data currencies] => %w[sources destinations],
+                            [ "data", "pairs", "[]" ] => %w[source dest providers] }),
+      Endpoint.new(method: "post", path: "/v1/payments/ramps/onramp/quote", success_status: "200",
+                   reads: { %w[data quote] => RAMP_QUOTE_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/payments/ramps/onramp/execute", success_status: "200",
+                   reads: { %w[data ramp] => RAMP_EXECUTION_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/payments/ramps/offramp/execute", success_status: "200",
+                   reads: { %w[data ramp] => RAMP_EXECUTION_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/payments/ramps/sandbox/simulate", success_status: "200",
+                   reads: { %w[data] => %w[transaction] })
     ].freeze
 
     class << self
@@ -69,7 +137,7 @@ module Sdp
 
       # Follows "$ref": "#/components/schemas/X" pointers (recursively, with
       # a depth guard). SDP's generated spec is fully inlined today (zero
-      # $refs at v0.28) — this keeps the guard working if that changes.
+      # $refs at v0.31) — this keeps the guard working if that changes.
       def resolve(spec, node, depth = 0)
         return node unless node.is_a?(Hash) && node["$ref"].is_a?(String)
         return nil if depth > 10

data/lib/sdp/errors.rb

@@ -38,7 +38,7 @@ module Sdp
   # Subclasses BadRequest so existing rescues keep working; never retryable —
   # the same request fails until the provider configuration changes.
   class ProviderCapabilityError < BadRequest
-    # Verified against SDP v0.28: assertCustodyProviderCanCreateWallet
+    # Verified against SDP v0.31: assertCustodyProviderCanCreateWallet
     # (apps/sdp-api/src/services/custody-provider-lifecycle.service.ts) and
     # createProviderWallet (services/domain/signing/provider-wallet-lifecycle.ts)
     # both throw:
@@ -54,7 +54,7 @@ module Sdp
   # mislabeling an RPC outage as "configure Kora" would be worse than a
   # generic error.
   class TransferExecutionError < Error
-    # Verified against SDP v0.28: NativeAdapter#signAndSend
+    # Verified against SDP v0.31: NativeAdapter#signAndSend
     # (apps/sdp-api/src/services/adapters/fee-payment/native/native.adapter.ts)
     # throws:
     #   "NativeAdapter.signAndSend not supported - use KoraAdapter for gasless transactions"

data/lib/sdp/pagination.rb

@@ -16,12 +16,12 @@ module Sdp
   # :pageSize is clamped client-side to MAX_PAGE_SIZE — SDP rejects larger
   # values, and a clamped request is more useful than a guaranteed 400.
   #
-  # Non-paginated list endpoints (GET /v1/wallets at v0.28) flow through the
+  # Non-paginated list endpoints (GET /v1/wallets at v0.31) flow through the
   # same helper: their meta carries no hasMore, so enumeration stops after a
   # single fetch — and they pick up auto-pagination for free if SDP paginates
   # them in a later version.
   module Pagination
-    MAX_PAGE_SIZE = 100    # SDP's pageSize ceiling (v0.28)
+    MAX_PAGE_SIZE = 100    # SDP's pageSize ceiling (v0.31)
     MAX_PAGES     = 10_000 # defensive ceiling; empty-page + hasMore guards are the primary stop
 
     # client — anything exposing #get(path, query:) → Client::Response

data/lib/sdp/resources/issuance.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Sdp
+  # A token as SDP's issuance API reports it. Like every SDP resource, optional
+  # fields are OMITTED (absent, not null), so each member is nil when SDP didn't
+  # send it. extensions is passed through as the raw snake_cased hash — the
+  # Token-2022 extension set is large and provider-shaped, so this gem surfaces
+  # it untyped rather than modelling it.
+  Token = Struct.new(:id, :project_id, :signing_wallet_id, :mint_address,
+                     :mint_authority, :freeze_authority, :name, :symbol, :decimals,
+                     :description, :uri, :image_url, :template, :extensions,
+                     :total_supply, :max_supply, :mintable, :freezable,
+                     :requires_allowlist, :status, :deployed_at, :created_at, :updated_at,
+                     keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        id: hash[:id],
+        project_id: hash[:project_id],
+        signing_wallet_id: hash[:signing_wallet_id],
+        mint_address: hash[:mint_address],
+        mint_authority: hash[:mint_authority],
+        freeze_authority: hash[:freeze_authority],
+        name: hash[:name],
+        symbol: hash[:symbol],
+        decimals: hash[:decimals],
+        description: hash[:description],
+        uri: hash[:uri],
+        image_url: hash[:image_url],
+        template: hash[:template],
+        extensions: hash[:extensions],
+        total_supply: hash[:total_supply],
+        max_supply: hash[:max_supply],
+        mintable: hash[:is_mintable],
+        freezable: hash[:is_freezable],
+        requires_allowlist: hash[:requires_allowlist],
+        status: hash[:status],
+        deployed_at: hash[:deployed_at],
+        created_at: hash[:created_at],
+        updated_at: hash[:updated_at]
+      )
+    end
+  end
+
+  # An issuance transaction — the action record SDP returns for mint/burn —
+  # distinct from a payments Transfer (different shape, different endpoints).
+  # token_account is the associated token account SDP returns alongside a mint
+  # (a sibling of the transaction in the envelope, folded in here); nil when SDP
+  # didn't send one (e.g. burn).
+  TokenTransaction = Struct.new(:id, :token_id, :type, :status, :signature,
+                                :serialized_tx, :params, :slot, :block_time, :fee,
+                                :error, :token_account, :created_at, :updated_at,
+                                keyword_init: true) do
+    def self.from_hash(hash, token_account: nil)
+      hash ||= {}
+      new(
+        id: hash[:id],
+        token_id: hash[:token_id],
+        type: hash[:type],
+        status: hash[:status],
+        signature: hash[:signature],
+        serialized_tx: hash[:serialized_tx],
+        params: hash[:params],
+        slot: hash[:slot],
+        block_time: hash[:block_time],
+        fee: hash[:fee],
+        error: hash[:error],
+        token_account: token_account,
+        created_at: hash[:created_at],
+        updated_at: hash[:updated_at]
+      )
+    end
+  end
+
+  # Result of a .../prepare issuance call: the unsigned transaction the caller
+  # must sign and submit before blockhash expiry, plus context. SDP nests this
+  # two different ways and from_action/from_deploy normalize both:
+  #
+  # - mint/burn prepare → the provisional record under :transaction, the
+  #   unsigned tx under :prepared_transaction (transaction is a TokenTransaction).
+  # - deploy prepare → :transaction IS the unsigned tx envelope and the new
+  #   mint address rides alongside under :mint (transaction is nil — there is no
+  #   action record yet).
+  # The mint/burn associated token account lives on #transaction (TokenTransaction)
+  # when SDP returns one; deploy carries no action record. There is deliberately
+  # no top-level token_account — it would only ever duplicate transaction.token_account.
+  PreparedTokenTransaction = Struct.new(:transaction, :serialized, :blockhash,
+                                        :last_valid_block_height, :mint, :simulation,
+                                        keyword_init: true) do
+    def self.from_action(hash)
+      hash ||= {}
+      prepared = hash[:prepared_transaction] || {}
+      new(
+        transaction: TokenTransaction.from_hash(hash[:transaction], token_account: hash[:token_account]),
+        serialized: prepared[:serialized],
+        blockhash: prepared[:blockhash],
+        last_valid_block_height: prepared[:last_valid_block_height],
+        mint: nil,
+        simulation: hash[:simulation]
+      )
+    end
+
+    def self.from_deploy(hash)
+      hash ||= {}
+      tx = hash[:transaction] || {}
+      new(
+        transaction: nil,
+        serialized: tx[:serialized],
+        blockhash: tx[:blockhash],
+        last_valid_block_height: tx[:last_valid_block_height],
+        mint: hash[:mint],
+        simulation: hash[:simulation]
+      )
+    end
+  end
+
+  module Resources
+    # Token issuance: the core lifecycle (list / get / create / deploy) and the
+    # supply actions (mint / burn), each action with a prepare variant for
+    # caller-signed (non-custodial) flows. Mint/burn/deploy are money-path and
+    # follow the same never-retry-on-write posture as transfers.
+    #
+    # Out of scope at v0.2: the compliance actions (freeze/unfreeze, pause,
+    # authority, allowlist, seize, force-burn) — they roughly double the surface
+    # and target stablecoin issuers, not the general dev-tool path.
+    module Issuance
+      # GET /v1/issuance/tokens → Enumerator yielding Sdp::Token.
+      # Auto-paginates on meta.hasMore (see Pagination); re-sends filters per
+      # page. Filters (camelCased on the wire): status:, page:, page_size:.
+      # (SDP v0.31 documents no other query filters on this endpoint.)
+      def list_tokens(status: nil, page: nil, page_size: nil)
+        query = { status: status, page: page, pageSize: page_size }.compact
+        Pagination.enumerate(self, "/v1/issuance/tokens", query) do |response|
+          rows = response.data.is_a?(Array) ? response.data : []
+          rows.map { |token| Token.from_hash(token) }
+        end
+      end
+
+      # GET /v1/issuance/tokens/:id → Sdp::Token
+      def get_token(token_id)
+        Token.from_hash(token_node(get("/v1/issuance/tokens/#{encode_path_segment(token_id)}")))
+      end
+
+      # POST /v1/issuance/tokens → Sdp::Token.
+      # Registers the token record; it is NOT on-chain until #deploy_token.
+      # Never retried (write). maxSupply is a DECIMAL token-amount string (whole
+      # tokens, e.g. "1000000" = one million tokens) — SDP applies the token's
+      # decimals, same convention as transfer amounts. NOT base units.
+      def create_token(name:, symbol:, signing_wallet_id:, decimals: nil, max_supply: nil,
+                       description: nil, uri: nil, image_url: nil, template: nil,
+                       mintable: nil, freezable: nil, requires_allowlist: nil)
+        payload = {
+          name: name, symbol: symbol, signingWalletId: signing_wallet_id,
+          decimals: decimals, maxSupply: max_supply, description: description,
+          uri: uri, imageUrl: image_url, template: template,
+          isMintable: mintable, isFreezable: freezable, requiresAllowlist: requires_allowlist
+        }.compact
+        Token.from_hash(token_node(post("/v1/issuance/tokens", payload)))
+      end
+
+      # POST /v1/issuance/tokens/:id/deploy → Sdp::Token (now on-chain).
+      # Custodial sign-and-send; never retried.
+      def deploy_token(token_id)
+        Token.from_hash(token_node(post(deploy_path(token_id))))
+      end
+
+      # POST /v1/issuance/tokens/:id/deploy/prepare → Sdp::PreparedTokenTransaction
+      # Builds — does not send — the deploy tx for caller-signed flows; the new
+      # mint address is on #mint.
+      def prepare_deploy_token(token_id)
+        PreparedTokenTransaction.from_deploy(post("#{deploy_path(token_id)}/prepare").data)
+      end
+
+      # POST /v1/issuance/tokens/:id/mint → Sdp::TokenTransaction.
+      # Custodial sign-and-send mint to destination; never retried. amount is a
+      # DECIMAL token-amount string (whole tokens, e.g. "1.5") — SDP scales it by
+      # the token's decimals, NOT base units. The associated token account is on
+      # #token_account.
+      # (Noun-suffixed to match create_token/deploy_token and to leave room for a
+      # future #freeze_token without colliding with Ruby's Object#freeze.)
+      def mint_token(token_id, signing_wallet_id:, destination:, amount:, memo: nil)
+        action_result(post(mint_path(token_id), mint_payload(signing_wallet_id, destination, amount, memo)))
+      end
+
+      # POST /v1/issuance/tokens/:id/mint/prepare → Sdp::PreparedTokenTransaction
+      # Builds — does not sign or send — the mint tx for caller-signed flows.
+      def prepare_mint_token(token_id, signing_wallet_id:, destination:, amount:, memo: nil)
+        PreparedTokenTransaction.from_action(
+          post("#{mint_path(token_id)}/prepare", mint_payload(signing_wallet_id, destination, amount, memo)).data
+        )
+      end
+
+      # POST /v1/issuance/tokens/:id/burn → Sdp::TokenTransaction.
+      # Custodial sign-and-send burn from source; never retried. amount is a
+      # DECIMAL token-amount string, same as #mint_token (NOT base units).
+      def burn_token(token_id, signing_wallet_id:, source:, amount:, memo: nil)
+        action_result(post(burn_path(token_id), burn_payload(signing_wallet_id, source, amount, memo)))
+      end
+
+      # POST /v1/issuance/tokens/:id/burn/prepare → Sdp::PreparedTokenTransaction
+      # Builds — does not sign or send — the burn tx for caller-signed flows.
+      def prepare_burn_token(token_id, signing_wallet_id:, source:, amount:, memo: nil)
+        PreparedTokenTransaction.from_action(
+          post("#{burn_path(token_id)}/prepare", burn_payload(signing_wallet_id, source, amount, memo)).data
+        )
+      end
+
+      private
+
+      # create/get/deploy wrap the token in a data.token envelope; stay tolerant
+      # of a bare token (or empty body → {}) so the struct degrades to all-nil.
+      def token_node(response)
+        data = response.data
+        data.is_a?(Hash) ? (data[:token] || data) : data
+      end
+
+      # mint/burn wrap the action record in data.transaction (mint also carries a
+      # sibling data.tokenAccount). Guard the envelope to a Hash so a money-path
+      # response that comes back off-shape or empty degrades to an all-nil struct
+      # rather than raising a raw TypeError mid-reconcile.
+      def action_result(response)
+        data = response.data
+        data = {} unless data.is_a?(Hash)
+        TokenTransaction.from_hash(data[:transaction], token_account: data[:token_account])
+      end
+
+      def mint_payload(signing_wallet_id, destination, amount, memo)
+        mint = { destination: destination, amount: amount_string(amount) }
+        mint[:memo] = memo if memo
+        { signingWalletId: signing_wallet_id, mint: mint }
+      end
+
+      def burn_payload(signing_wallet_id, source, amount, memo)
+        burn = { source: source, amount: amount_string(amount) }
+        burn[:memo] = memo if memo
+        { signingWalletId: signing_wallet_id, burn: burn }
+      end
+
+      def deploy_path(token_id)
+        "/v1/issuance/tokens/#{encode_path_segment(token_id)}/deploy"
+      end
+
+      def mint_path(token_id)
+        "/v1/issuance/tokens/#{encode_path_segment(token_id)}/mint"
+      end
+
+      def burn_path(token_id)
+        "/v1/issuance/tokens/#{encode_path_segment(token_id)}/burn"
+      end
+    end
+  end
+end

data/lib/sdp/resources/payments.rb

@@ -115,10 +115,6 @@ module Sdp
         payload[:memo] = memo if memo
         payload
       end
-
-      def encode_path_segment(segment)
-        URI.encode_uri_component(segment.to_s)
-      end
     end
   end
 end

data/lib/sdp/resources/ramps.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Sdp
+  # Currency discovery for a ramp direction: which fiat/crypto SDP can move
+  # between and which providers serve each pair. Passed through close to how SDP
+  # reports it — pairs is an array of { source, dest, providers } hashes.
+  RampCurrencies = Struct.new(:sources, :destinations, :pairs, :support_hash, keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      currencies = hash[:currencies] || {}
+      new(
+        sources: currencies[:sources] || [],
+        destinations: currencies[:destinations] || [],
+        pairs: hash[:pairs] || [],
+        support_hash: hash[:support_hash]
+      )
+    end
+  end
+
+  # A ramp quote: indicative pricing plus a hosted checkout URL for an on-ramp.
+  # SDP omits optional fields, so each member is nil when absent. The *_currency
+  # members are passed through as { code, decimals, name, symbol } hashes;
+  # amounts are numbers as SDP sends them.
+  RampQuote = Struct.new(:id, :provider, :status, :delivery_mode, :hosted_url, :payment_instructions,
+                         :exchange_rate, :total_sending_amount, :sending_currency,
+                         :total_receiving_amount, :receiving_currency, :fees_included, :fee_currency,
+                         :expires_at, keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        id: hash[:id],
+        provider: hash[:provider],
+        status: hash[:status],
+        delivery_mode: hash[:delivery_mode],
+        hosted_url: hash[:hosted_url],
+        payment_instructions: hash[:payment_instructions],
+        exchange_rate: hash[:exchange_rate],
+        total_sending_amount: hash[:total_sending_amount],
+        sending_currency: hash[:sending_currency],
+        total_receiving_amount: hash[:total_receiving_amount],
+        receiving_currency: hash[:receiving_currency],
+        fees_included: hash[:fees_included],
+        fee_currency: hash[:fee_currency],
+        expires_at: hash[:expires_at]
+      )
+    end
+  end
+
+  # The result of executing a ramp: SDP's ramp record with the redirect/checkout
+  # URL and a provider reference for reconciliation.
+  RampExecution = Struct.new(:id, :provider, :status, :redirect_url, :payment_instructions, :reference,
+                             keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        id: hash[:id],
+        provider: hash[:provider],
+        status: hash[:status],
+        redirect_url: hash[:redirect_url],
+        payment_instructions: hash[:payment_instructions],
+        reference: hash[:reference]
+      )
+    end
+  end
+
+  module Resources
+    # Fiat on/off-ramps (SDP payments/ramps).
+    #
+    # SANDBOX-ONLY at v0.2: wired against SDP's ramp surface and the sandbox
+    # simulate hook, NOT verified against live fiat rails. The execute calls are
+    # POSTs and follow the same never-retry-on-write posture as transfers (a ramp
+    # moves money). #simulate_ramp drives a sandbox ramp to a terminal state.
+    #
+    # The execute/quote requests carry a large provider KYC/compliance payload
+    # (SDP's bvnkCompliance). Rather than model that nested blob, the core fields
+    # are keyword args and the compliance object is passed through via compliance:.
+    module Ramps
+      # GET /v1/payments/ramps/onramp/currency → Sdp::RampCurrencies
+      # Filters (camelCased on the wire): source:, dest:, provider:.
+      def onramp_currencies(source: nil, dest: nil, provider: nil)
+        RampCurrencies.from_hash(ramp_currencies("onramp", source, dest, provider))
+      end
+
+      # GET /v1/payments/ramps/offramp/currency → Sdp::RampCurrencies
+      def offramp_currencies(source: nil, dest: nil, provider: nil)
+        RampCurrencies.from_hash(ramp_currencies("offramp", source, dest, provider))
+      end
+
+      # POST /v1/payments/ramps/onramp/quote → Sdp::RampQuote.
+      # Indicative pricing for a fiat→crypto on-ramp. Never retried (write).
+      def onramp_quote(provider:, counterparty_id:, destination_wallet:, crypto_token:,
+                       fiat_currency:, fiat_amount:, redirect_url: nil, collected_data: nil)
+        payload = {
+          provider: provider, counterpartyId: counterparty_id, destinationWallet: destination_wallet,
+          cryptoToken: crypto_token, fiatCurrency: fiat_currency, fiatAmount: amount_string(fiat_amount),
+          redirectUrl: redirect_url, collectedData: collected_data
+        }.compact
+        RampQuote.from_hash(ramp_record(post("/v1/payments/ramps/onramp/quote", payload).data, :quote))
+      end
+
+      # POST /v1/payments/ramps/onramp/execute → Sdp::RampExecution.
+      # Custodial money movement; never retried. compliance: maps to SDP's
+      # bvnkCompliance payload.
+      def onramp_execute(provider:, counterparty_id:, destination_wallet:, crypto_token:,
+                         fiat_currency:, fiat_amount:, kyc_reference: nil, redirect_url: nil, compliance: nil)
+        payload = {
+          provider: provider, counterpartyId: counterparty_id, destinationWallet: destination_wallet,
+          cryptoToken: crypto_token, fiatCurrency: fiat_currency, fiatAmount: amount_string(fiat_amount),
+          kycReference: kyc_reference, redirectUrl: redirect_url, bvnkCompliance: compliance
+        }.compact
+        RampExecution.from_hash(ramp_record(post("/v1/payments/ramps/onramp/execute", payload).data, :ramp))
+      end
+
+      # POST /v1/payments/ramps/offramp/execute → Sdp::RampExecution.
+      # Custodial money movement (crypto→fiat); never retried.
+      def offramp_execute(provider:, counterparty_id:, source_wallet:, crypto_token:,
+                          fiat_currency:, crypto_amount:, kyc_reference: nil, redirect_url: nil, compliance: nil)
+        payload = {
+          provider: provider, counterpartyId: counterparty_id, sourceWallet: source_wallet,
+          cryptoToken: crypto_token, fiatCurrency: fiat_currency, cryptoAmount: amount_string(crypto_amount),
+          kycReference: kyc_reference, redirectUrl: redirect_url, bvnkCompliance: compliance
+        }.compact
+        RampExecution.from_hash(ramp_record(post("/v1/payments/ramps/offramp/execute", payload).data, :ramp))
+      end
+
+      # POST /v1/payments/ramps/sandbox/simulate → the simulated transaction (Hash passthrough, nil if absent).
+      # Sandbox-only test hook: advances a sandbox ramp to a terminal state.
+      # Keyword args are forwarded verbatim (no camelCase conversion) — SDP
+      # leaves the body provider-shaped, so pass the keys SDP expects.
+      def simulate_ramp(**payload)
+        data = post("/v1/payments/ramps/sandbox/simulate", payload).data
+        data.is_a?(Hash) ? data[:transaction] : nil
+      end
+
+      private
+
+      def ramp_currencies(direction, source, dest, provider)
+        query = { source: source, dest: dest, provider: provider }.compact
+        get("/v1/payments/ramps/#{direction}/currency", query: query).data
+      end
+
+      # quote/execute wrap the record in data.quote / data.ramp; stay tolerant of
+      # a bare record (or empty body → {}) so the struct degrades to all-nil.
+      def ramp_record(data, key)
+        data.is_a?(Hash) ? (data[key] || data) : {}
+      end
+    end
+  end
+end

data/lib/sdp/resources/wallets.rb

@@ -47,17 +47,22 @@ module Sdp
     module Wallets
       # POST /v1/wallets/initialize — one-time project custody setup.
       # Both fields are optional; the request is sent without a body when
-      # neither is given. Returns the snake_cased data hash exactly as SDP
-      # sent it (custody config + root wallet fields incl. :public_key) —
-      # kept tolerant because the shape varies by custody provider.
+      # neither is given. provider falls back to the client's configured
+      # custody_provider (SDP_CUSTODY_PROVIDER) when not passed. Returns the
+      # snake_cased data hash exactly as SDP sent it (custody config + root
+      # wallet fields incl. :public_key) — kept tolerant because the shape
+      # varies by custody provider.
       def initialize_custody(provider: nil, wallet_label: nil)
-        payload = { provider: provider, walletLabel: wallet_label }.compact
+        payload = { provider: provider || custody_provider, walletLabel: wallet_label }.compact
         post("/v1/wallets/initialize", payload.empty? ? nil : payload).data
       end
 
       # POST /v1/wallets → Sdp::Wallet. Wallet#id is SDP's walletId.
+      # provider falls back to the client's configured custody_provider. A
+      # managed provider (e.g. privy) is required for Wallet-per-User — local
+      # custody holds a single root wallet and raises Sdp::ProviderCapabilityError.
       def create_wallet(label:, provider: nil)
-        response = post("/v1/wallets", { label: label, provider: provider }.compact)
+        response = post("/v1/wallets", { label: label, provider: provider || custody_provider }.compact)
         data = response.data
         src = data.is_a?(Hash) ? (data[:wallet] || data) : data
         Wallet.from_hash(src)
@@ -65,11 +70,12 @@ module Sdp
 
       # GET /v1/wallets → [Sdp::Wallet, ...]
       # Filters (camelCased on the wire): provider:, project_id:,
-      # include_balances:. Not paginated at v0.28 — the whole list comes back
+      # include_balances:. Not paginated at v0.31 — the whole list comes back
       # in one response — but routed through Pagination.enumerate so a
       # paginated upstream upgrade is a one-line change here.
       def list_wallets(provider: nil, project_id: nil, include_balances: nil)
-        query = { provider: provider, projectId: project_id, includeBalances: include_balances }.compact
+        query = { provider: provider || custody_provider, projectId: project_id,
+                  includeBalances: include_balances }.compact
         Pagination.enumerate(self, "/v1/wallets", query) do |response|
           rows =
             case response.data
@@ -89,12 +95,6 @@ module Sdp
         container = data.is_a?(Hash) ? (data[:wallet_balances] || data) : {}
         (container[:balances] || []).map { |balance| Balance.from_hash(balance) }
       end
-
-      private
-
-      def encode_path_segment(segment)
-        URI.encode_uri_component(segment.to_s)
-      end
     end
   end
 end

data/lib/sdp/version.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Sdp
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 
   # The SDP release this gem version is tested against. SDP breaks its API
   # between minors, so every gem release names its verified upstream version.
-  COMPATIBLE_SDP_VERSION = "0.28"
+  COMPATIBLE_SDP_VERSION = "0.31"
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: solana-sdp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jose Ferrer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies: []
-description: 'Zero-dependency Net::HTTP client for SDP''s wallets and payments API:
-  typed errors, envelope unwrapping, and a safe retry posture.'
+description: 'Zero-dependency Net::HTTP client for SDP''s wallets, payments, token-issuance,
+  and ramp APIs: typed errors, envelope unwrapping, and a safe retry posture.'
 email:
 - estoy@moviendo.me
 executables: []
@@ -26,7 +26,9 @@ files:
 - lib/sdp/drift.rb
 - lib/sdp/errors.rb
 - lib/sdp/pagination.rb
+- lib/sdp/resources/issuance.rb
 - lib/sdp/resources/payments.rb
+- lib/sdp/resources/ramps.rb
 - lib/sdp/resources/wallets.rb
 - lib/sdp/version.rb
 - lib/solana-sdp.rb