DigiDollar Paymaster Network – Send and Receive DigiDollar Without Holding DGB

[Shen]

Concept Proposal: DigiDollar Paymaster Network - Send and Receive DigiDollar Without Holding DGB

Decentralized Fee Sponsorship with Verifiable Liquidity and No Consensus Changes

Status: Technical concept draft for discussion and a regtest prototype
Codebase: DigiByte Core develop, reviewed against v9.26.5
Consensus change: not proposed

1. Summary

The DigiDollar Paymaster Network enables a wallet to send DigiDollar even
though it holds no DGB for the network fee.

A payment remains a normal DD_TX_TRANSFER transaction:

• The user wallet provides and signs its DD inputs.
• The Paymaster provides and signs the DGB fee inputs.
• For fees from 0.01 to 0.99 DD, the Paymaster additionally provides a
  confirmed DD carrier input.
• All inputs and outputs are finalized before the first signature is created.
• The user wallet builds or reconstructs the transaction locally, validates it
  in full, and signs only its own inputs.
• The Paymaster signs last and immediately broadcasts the completed transaction.

Paymasters are not privileged network participants. Participation is
permissionless through signed, short-lived announcements on the normal
DigiByte P2P network. The Core wallet initially displays only providers whose
identity and multiple dedicated admission slots have been verified locally.
For privacy, fresh reachability and endpoint authentication and the operational
payment-slot proof are performed sequentially only after a candidate has been
selected.

The same technical protocol supports three economic variants: public
fee-free community sponsorship, sponsorship restricted to a merchant or
application, and a public user-paid offer with an operator-selected percentage
price in DD. The wallet explicitly separates this funding source from the
technical Paymaster role. It calculates every user fee deterministically and
sorts only providers authorized for the specific request by the user's total
cost.

An extended, idempotent senddigidollar call can automatically select the
lowest-cost usable provider within a hard DD fee cap—either always or only when
a complete funding preflight determines that the direct DGB fee path cannot be
funded. Qt and headless applications use the same persistent Core session for
this purpose.

The network is not inherently anonymous. As a co-signer, the selected provider
must know the complete transaction, and the final transaction remains publicly
analyzable. An optional high-privacy profile therefore minimizes network and
storage metadata without claiming a technically unattainable anonymity
guarantee.

2. Goals and Non-Goals

Goals

1. DD payments without DGB in the user wallet.
2. Non-custodial operation: no Paymaster receives a user key or discretionary
   control over the user's DD.
3. Open competition without fixed provider slots or centralized admission.
4. Mandatory sub-1-DD carrier support for automatically displayed, user-paid
   Paymasters; pure zero-fee sponsors do not need an unused DD carrier pool.
5. Proof of multiple confirmed and mutually distinct DGB slots and, whenever a
   user fee is offered, matching carrier UTXOs.
6. One protocol for public community sponsorship, restricted merchant/app
   sponsorship, and transparent operator-selected percentage fees in DD.
7. Local validation of the complete transaction before every user signature.
8. No changes to the block format, script rules, DD conservation, or
   transaction validity.
9. Data minimization: only the selected provider receives payment data that is
   unavoidable for its signature; public discovery, logs, and persistent
   history contain no additional payment profile.
10. Optional pseudonymous operation through onion endpoints with Tor stream
    isolation and no silent clearnet fallback.

Non-Goals

• No new consensus role for Paymasters.
• No fixed or privileged list of Paymaster keys or operators in chainparams.
• No new transaction type and no special sighash.
• No exception to the minimum amount of a DD output.
• No exception to the existing maximum of 10,000,000 cents, or 100,000 DD, per
  DD output.
• No user balances, prepaid balances, or discretionary custody of user DD at a
  Paymaster.
• No KYC, contractual, or legal role classification in consensus or Core;
  descriptive sponsor labels do not establish legal status.
• No anonymity guarantee against the selected Paymaster or the public
  blockchain.
• No proprietary new encryption protocol in V1; transport confidentiality uses
  the existing onion/proxy and P2P v2 paths.

3. Technical Foundation in the Existing Code

The existing TxBuilderTransferParams already separates DD inputs from DGB
fee inputs:

std::vector<COutPoint> ddUtxos;
std::vector<CAmount> ddAmounts;
std::vector<COutPoint> feeUtxos;
std::vector<CAmount> feeAmounts;
std::optional<CTxDestination> dgbChangeDest;

See src/digidollar/txbuilder.h.
BuildTransferTransaction() adds the DD inputs first and the DGB inputs
afterward (src/digidollar/txbuilder.cpp).

Consensus validation:

• validates every DD output,
• currently requires at least 100 cents, or 1 DD, and at most 10,000,000 cents,
  or 100,000 DD, per DD output,
• requires exact conservation of all DD,
• currently rejects unconfirmed DD inputs,
• contains no rule requiring DD and DGB inputs to have the same owner.

See
src/consensus/digidollar.h and
src/digidollar/validation.cpp,
src/digidollar/validation.cpp.

V1 deliberately limits Paymaster clients and providers to non-pruned nodes
with -prune=0, -txindex=1, and complete DD-creating transaction data. DD
validation preferentially obtains amounts from the creating transaction through
txindex and then tries the block database or metadata registry
(src/digidollar/validation.cpp);
Core makes pruning and txindex incompatible
(src/init.cpp). There is therefore no
sufficiently demonstrated general pruned-node path for every collaborative
PSBT and restart case. Pruned support remains a later, general DD-index
extension with its own reindex/migration strategy and is not a Paymaster
consensus change.

Privacy requires one additional builder extension. The current transfer
parameters have no separate DD change destination
(src/digidollar/txbuilder.h); the
builder currently derives DD change from spenderKey
(src/digidollar/txbuilder.cpp).
The collaborative path therefore adds an explicit ddChangeDest freshly
reserved from the wallet's internal keypool. Fallback attempts in the same
session reuse the already authorized destination.

Today's logging is also unsuitable for Paymaster metadata: the builder writes
fee outpoints, recipients, amounts, and DD change to the general log
(src/digidollar/txbuilder.cpp).
The existing broadcast/Dandelion path also logs TXIDs and precise relay times
(src/node/transaction.cpp).
Before the Paymaster path is enabled, these messages must be removed or reduced
to non-correlatable state and error codes.

The current wallet path is nevertheless not multi-party capable. It selects DD
and DGB from the same wallet, signs the entire transaction, and broadcasts it
immediately
(src/wallet/digidollarwallet.cpp,
src/wallet/digidollarwallet.cpp).
SignDDInputs() also expects all previous transactions to be present in the
same mapWallet. A new wallet path that builds unsigned transactions and signs
selectively is therefore required.

4. Architecture Decision

 Regular DigiByte P2P network
 ┌──────────────────────────────────────────────────────────────┐
 │ signed pmannounce messages + getpmasters pull sync           │
 └──────────────────────────────┬───────────────────────────────┘
                                │
                      local directory/filtering
                                │
                                ▼
 ┌───────────────────┐     direct P2P session     ┌────────────────────┐
 │ User Core Wallet  │◄──────────────────────────►│ Paymaster Core Node│
 │                   │  capacity / quote /        │ + dedicated wallet │
 │ build locally     │  partial transaction      │                    │
 │ validate in full  │                           │ policy signer      │
 │ own inputs only   │                           │ reservations       │
 └─────────┬─────────┘                           └──────────┬─────────┘
           │                                                │
           └────────── fully signed DD_TX_TRANSFER ─────────┘
                                  │
                                  ▼
                          existing DGB network

The security-critical functions remain in Core:

• UTXO resolution and validation,
• deterministic DD builder,
• DD conservation and output validation,
• wallet ownership validation,
• selective signing,
• UTXO reservation,
• mempool validation and broadcast.

For V1, the sender wallet and the Paymaster require an updated Core version.
Recipients, miners, and other full nodes do not need Paymaster functionality to
validate the completed transaction under the existing DD rules. P2P nodes that
cache or relay pmannounce do require the new non-consensus relay
implementation; old nodes ignore these messages.
An operator does not necessarily need the Qt interface; an updated digibyted
with a dedicated wallet is sufficient.

5. Provider Discovery on the P2P Network

5.1 P2P Discovery

Primary discovery uses new, non-consensus messages on the normal DigiByte P2P
network:

namespace NetMsgType {
extern const char* SENDPMASTERS;// "sendpmasters"
extern const char* PMANNOUNCE;  // "pmannounce"
extern const char* GETPMASTERS; // "getpmasters"
extern const char* PMCAPREQ;    // "pmcapreq"
extern const char* PMCAPRESP;   // "pmcapresp"
extern const char* PMQUOTEREQ;  // "pmquotereq"
extern const char* PMQUOTERESP; // "pmquoteresp"
extern const char* PMSUBMIT;    // "pmsubmit"
extern const char* PMRESULT;    // "pmresult"
}

• sendpmasters enables reception and relay; nodes with no interest do not
  need to cache or validate Paymaster proofs.
• pmannounce is gossiped and cached for a limited time.
• getpmasters synchronizes the cache after a new peer connection.
• The client-bound proof for exactly one operational candidate slot, quotes,
  and PSBTs are exchanged exclusively over a direct connection to the selected
  provider and are never gossiped; the announcement contains only the bounded
  admission proof.
• After the direct connection has been established, the provider responds to a
  fresh client nonce using its announcement identity key. Intent data is
  transmitted only after this binding between endpoint and provider ID.
• A clearnet endpoint may exchange intent, quote, or PSBT data only over the
  existing encrypted P2P v2 transport. The codebase can already negotiate this
  transport but does not currently enable it by default
  (src/net.h). A failed v2 setup does not fall back
  to v1 for a Paymaster session.
• In the high-privacy profile, only onion endpoints are permitted. All
  Paymaster connections use the configured proxy with randomized credentials
  per connection; Core already supports this Tor stream isolation through
  -proxyrandomize (src/init.cpp). An onion
  failure must not cause a silent clearnet fallback.
• Unknown messages are ignored by old nodes
  (src/net_processing.cpp).

Cold start uses already connected, updated P2P peers. For tests, private
networks, and early rollout, a provider can additionally be configured directly
with -addpaymaster=<address>. Even then, a provider is displayed only if it
passes cryptographic and local validation. Manual configuration may bypass
only discovery and admission display filters, never quote, slot, signature,
fee, prevout, policy, or full transaction validation.

5.2 Signed Announcement

Every operator has a long-lived identity key that is separate from the funding
keys:

struct PaymasterOfferTerms {
    uint256 offer_id;
    uint256 policy_hash;
    PaymasterFundingModel funding_model;
    SponsorshipScope scope; // PUBLIC; RESTRICTED is never gossiped
    uint32_t fee_rate_bps;
    int64_t min_payment_dd_cents;
    int64_t max_payment_dd_cents;
};

struct PaymasterAnnouncement {
    uint16_t version;
    uint256 genesis_hash;
    XOnlyPubKey identity_key;
    std::string display_name; // optional, policy-limited, max. 32 bytes
    uint64_t sequence;
    int64_t created_at;
    int64_t expires_at;
    CService p2p_endpoint;

    std::vector<PaymasterOfferTerms> offers; // bounded, public offers only
    uint16_t min_confirmations;
    uint32_t capability_flags;
    PaymasterAdmissionProof minimum_liquidity_proof;

    std::vector<unsigned char> identity_signature;
};

offers is limited to at most four entries. Each entry is a complete public
offer identified unambiguously by offer_id and policy_hash. USER_PAID
uses the percentage fee in Section 7; SPONSORED charges the user exactly
0 DD. PUBLIC means any matching request may ask for the offer;
RESTRICTED never appears in this list. Terms such as community, merchant, or
application are only signed display metadata and make no security or legal
assertion.

capability_flags signals, among other things, P2P v2 transport and an onion
service. The display name is optional and contains no URL, email address, or
payment address. Core loads no external logos or other tracking resources.

PaymasterId is the hash of the identity key. The signature is domain-separated
and binds at least the protocol version, genesis hash, display name, endpoint,
policy, complete admission proof, sequence, and expiration time. An endpoint or price change requires a
new sequence and signature. The display name is not unique; the GUI therefore
always also displays a shortened fingerprint of the provider ID.

To prevent gossip from being flooded by identities that can be created at no
cost, every relayable announcement contains a bounded admission proof for
exactly the client-side minimum capacity. Under the proposed default, this
consists of three disjoint DGB admission slots and, for every announced
USER_PAID offer, three associated admission carriers, each with a current
reference block and control signatures. This dedicated admission reserve is
never used in a user payment or as an operational quote slot. The Paymaster ID
therefore remains linked to the minimum reserve, but global gossip publishes no
operational payment UTXOs. Relay nodes validate the proof under strict CPU and
byte limits before caching or forwarding an announcement.

The admission proof's control signatures use a separate domain such as
"DigiByte Paymaster Admission v1" and bind the provider ID, announcement
sequence, reference block, outpoint, and expiration time. They are not
interchangeable with the later, client-bound capacity proofs.

A provider that wants to dissolve an admission reserve first ends its
announcement. Those UTXOs are nevertheless never used in Paymaster payments;
a later spend can still publicly link the source of funding. The design makes
no claim of complete invisibility.

Suggested non-binding limits:

• Announcement TTL: no more than 10 minutes,
• Quote TTL: 30 to 60 seconds,
• strict message and list limits,
• rate limiting per peer and netgroup,
• inexpensive size and time checks before signature validation,
• a bounded cache and monotonically increasing sequences.

Where possible, the directory view is aggregated from multiple outbound peers
in different netgroups. This does not prevent a complete eclipse attack, but it
reduces dependence on a single relay. Automatic direct connections accept only
addresses that are routable under existing Core network policy and respect
proxy and Tor settings. Loopback, private, link-local, and other internal
destinations are permitted only with an explicit local -addpaymaster
configuration.

Public directory synchronization opens no direct connection to every provider
and requests no operational capacity snapshots in advance. Only the locally
selected candidate receives a direct, isolated session. Before the payment
intent, it may prove at most one operational candidate slot; this preliminary
proof does not yet guarantee funding for the unknown final transaction
template. After the intent, the quote checks the actual transaction weight and
proves and reserves exactly that slot with sufficient DGB funding. No client
receives the complete hot-wallet pool.

5.3 Restricted Merchant and Application Sponsorship

A restricted sponsorship offer is not gossiped globally. A payment request,
QR code, or local application instead supplies the wallet with a signed,
short-lived service descriptor containing the provider_id, a routable P2P
endpoint, offer_id, policy_hash, sponsor display name, authorization scheme, chain
binding, and expiration. The descriptor may pin a specific Paymaster. The
wallet then authenticates the endpoint exactly like a publicly discovered
provider and performs the same UTXO, quote, and transaction checks.

struct RestrictedPaymasterServiceDescriptor {
    uint16_t version;
    uint256 genesis_hash;
    PaymasterId provider_id;
    CService p2p_endpoint;
    uint256 offer_id;
    uint256 policy_hash;
    XOnlyPubKey sponsor_authorization_key;
    std::string sponsor_display_name;
    uint16_t authorization_scheme;
    int64_t expires_at;
    PaymasterAdmissionProof minimum_liquidity_proof;
    std::vector<unsigned char> provider_identity_signature;
};

The provider signature approves the endpoint, concrete offer ID, policy, non-gossiped admission
reserve, and permitted sponsor authorization key. The wallet validates this
proof like a public offer. The payment-specific capability is signed by that
sponsor key. A display name and policy hash alone are never accepted as
authorization.

Any sponsorship authorization is an opaque, signed capability bound at least
to the genesis hash, provider ID, offer ID, policy hash, the single V1 recipient, amount,
payment-request nonce, and expiration. The Paymaster protects it against reuse.
Before issuing the quote it persists a SponsorshipAuthorizationRecord with
the capability hash, canonical payment binding, and state RESERVED, but never
the secret capability itself. At final provider commit, the same wallet
database transaction atomically changes it to CONSUMED. The secret
capability is never announced or gossiped, written to debug output, or stored
persistently in plaintext; the intent, quote, and session retain only its hash.
Core accepts no arbitrary web URL from a payment request, only a CService
routable under existing network policy or an explicitly locally permitted
address.

Public community and user-paid offers continue to use the discovery in
Section 5.1. A sponsor may arrange settlement with a merchant or application
outside Core; the user's DD service fee and Paymaster output remain exactly
zero. Core maintains neither sponsor accounts nor prepaid balances.

6. Mandatory Carrier and Liquidity Proof

6.1 Wallet Eligibility Rather Than a Consensus Rule

Multiple confirmed DGB slots are a prerequisite for automatic display in
Core. Sub-1-DD carrier support is additionally mandatory whenever a provider
offers a user-paid DD fee. This is deliberately a wallet policy:

A provider is considered eligible if it currently proves at least three
distinct, confirmed, and controlled DGB admission slots. For USER_PAID,
every admission slot must additionally contain a controlled DD carrier. A
pure SPONSORED provider charging exactly 0 DD may prove DGB-only admission
slots. Before any signature, the concrete quote must independently prove and
reserve a usable operational slot.

The proposed default value is:

MIN_VERIFIED_PAYMASTER_SLOTS = 3
MIN_ADMISSION_DGB_SATOSHIS = 10000000

Local policy may raise, but not lower, the V1 discovery floor of three slots;
it is nevertheless not a consensus constant. Manual sponsorship remains
possible, and transaction validity never depends on this value.

6.2 A Liquidity Slot

A slot is the smallest unit that can be reserved in parallel:

struct PaymasterLiquiditySlot {
    std::optional<VerifiedDDCarrier> carrier;
    std::vector<VerifiedDGBInput> dgb_fee_inputs;
};

struct PaymasterAdmissionSlot {
    std::optional<VerifiedDDCarrier> carrier;
    std::vector<VerifiedDGBInput> dgb_admission_inputs;
};

struct PaymasterAdmissionProof {
    int32_t proof_height;
    uint256 proof_block_hash;
    std::vector<PaymasterAdmissionSlot> minimum_slots;
};

struct UtxoControlProof {
    COutPoint outpoint;
    CScript script_pub_key;
    int64_t expires_at;
    std::vector<unsigned char> schnorr_signature;
};

struct VerifiedDDCarrier {
    COutPoint outpoint;
    CScript p2tr_script_pub_key;
    int64_t dd_cents;
    int32_t confirmation_height;
    CTransactionRef creating_transaction;
    UtxoControlProof control_proof;
};

struct VerifiedDGBInput {
    COutPoint outpoint;
    CScript p2tr_script_pub_key;
    int64_t dgb_satoshis;
    int32_t confirmation_height;
    UtxoControlProof control_proof;
};

For an admission slot, schnorr_signature covers
"DigiByte Paymaster Admission v1" || genesis_hash || provider_id || announcement_sequence || proof_block_hash || outpoint || script_pub_key || amount || confirmation_height || expires_at. The operational capacity proof
instead uses the challenge in Section 6.3. In either case, the outpoint and
script in UtxoControlProof must exactly match the enclosing verified object
and actual prevout, and its expiration may not exceed that of the enclosing
proof.

A user-paid operational slot contains:

• exactly one confirmed DD carrier UTXO between 100 and 10,000,000 cents,
• one or more confirmed, dedicated DGB UTXOs,
• enough DGB for the maximum expected network fee of the requested transfer,
• a fresh proof of control for every outpoint.

verified_parallel_slots is the provider-local number of complete, pairwise
disjoint operational slots. Their outpoints are not published in the
announcement. A large DGB UTXO or a single DD carrier counts as only one slot
because it cannot be reserved for multiple quotes at the same time. Admission
and operational outpoints are completely disjoint. Every DGB admission UTXO
contains at least MIN_ADMISSION_DGB_SATOSHIS; a small dust UTXO does not count
as admission liquidity. In V1, all carrier and provider DGB inputs must be
dedicated P2TR key-path outputs.

6.3 Capacity Challenge

The admission proof limits Sybil and gossip spam but proves neither the
operational pool nor exclusive or second-by-second availability. Before
displaying a provider, the wallet validates the three published admission
slots against its own chain and mempool view. It does not contact every
provider for this purpose. Only after price, policy, and local cooldown select
a candidate does it request from exactly that provider a fresh client-bound
proof for at most one operational candidate slot:

struct PaymasterCapacityRequest {
    uint256 genesis_hash;
    PaymasterId provider_id;
    uint256 client_nonce;
    uint16_t requested_slots; // V1 privacy limit: exactly 1
};

struct PaymasterCapacityProof {
    uint256 genesis_hash;
    PaymasterId provider_id;
    uint256 client_nonce;
    uint256 snapshot_id;
    int64_t created_at;
    int64_t expires_at;
    std::vector<PaymasterLiquiditySlot> slots; // exactly one candidate slot
    std::vector<unsigned char> identity_signature;
};

For every disclosed carrier or DGB UTXO, the operator additionally provides a
domain-separated Schnorr control signature over:

"DigiByte Paymaster Capacity v1"
|| genesis_hash
|| provider_id
|| snapshot_id
|| client_nonce
|| outpoint
|| expires_at

Core constructs the tagged hash to be signed itself from the fully parsed
fields. It must never pass an arbitrary 32-byte hash supplied by the network to
a wallet key for signing. This prevents a capacity request from being abused to
produce a signature for another protocol.

For V1, Paymaster reserve UTXOs must be held on dedicated P2TR keys. Core can
then validate the control signature directly against the x-only output key. The
identity key additionally signs the entire snapshot and binds all UTXO proofs
to the same provider.

The client wallet validates locally that:

1. The outpoint exists, is unspent, and is not spent by any transaction in the
   local mempool.
2. The minimum confirmation requirement is met.
3. The DGB value and script come from the actual prevout.
4. If the slot contains a carrier, its DD amount comes from the transaction
   that created it and that transaction's OP_RETURN, not from a value reported
   by the provider.
5. Every carrier that is present is between 100 and 10,000,000 cents, and every
   DGB admission UTXO contains at least 10,000,000 satoshis.
6. All outpoints in the snapshot are distinct.
7. The control and identity signatures, nonce, chain, and expiration time are
   valid.
8. The same outpoints are not counted multiple times as independent capacity
   across multiple provider identities.

The client enforces at least its own confirmation policy. A lower
min_confirmations value published by the provider can never reduce it.

The proof demonstrates current existence and key control, but neither global
exclusivity nor funding for the final transaction template, which is still
unknown at that point. Only an atomic quote checks its actual weight and
reserves exactly the disclosed slot with sufficient DGB funding. Before that
quote, the UI therefore says "Admission reserve verified"; afterward it
says "Payment slot reserved", never "capacity guaranteed."

7. Fee Model and Ranking

The transaction protocol remains identical for all funding models:

Funding model	Scope	User's DD service fee	Discovery
Community sponsorship	public	0 DD	signed P2P announcement
Merchant/app sponsorship	restricted	0 DD	payment request or local application
User-paid	public	deterministic percentage fee	signed P2P announcement

Protocol fields use only the objective values SPONSORED or USER_PAID and
PUBLIC or RESTRICTED. A restricted offer is usable only after its concrete
sponsorship authorization has been validated and bound to the payment request.
A Paymaster funded externally by a sponsor may not add another DD output or
carrier increase at the user's expense.

enum class PaymasterFundingModel : uint8_t {
    USER_PAID,
    SPONSORED,
};

enum class SponsorshipScope : uint8_t {
    PUBLIC,
    RESTRICTED,
};

7.1 Deterministic Percentage Fee Only

The operator chooses a fee in increments of 0.1 percentage points, for example
0.5%, 1.0%, or 1.2%. The protocol never uses floating-point numbers. The
rate is stored in basis points:

0.5% =  50 bps
1.2% = 120 bps

For V1, MAX_PAYMASTER_RATE_BPS = 10000, and fee_rate_bps must also be a
multiple of 10. The fee is rounded up to the
next whole DD cent using checked integer arithmetic:

bool ComputePaymasterFee(int64_t payment_cents,
                         uint32_t fee_rate_bps,
                         int64_t& fee_cents)
{
    if (payment_cents <= 0 || fee_rate_bps > MAX_PAYMASTER_RATE_BPS ||
        fee_rate_bps % 10 != 0) return false;

    const __int128 numerator =
        static_cast<__int128>(payment_cents) * fee_rate_bps;
    const __int128 rounded = (numerator + 9999) / 10000;
    if (rounded > std::numeric_limits<int64_t>::max()) return false;

    fee_cents = static_cast<int64_t>(rounded);
    return fee_cents <= MAX_DIGIDOLLAR - payment_cents;
}

At 0 bps and for every SPONSORED offer, the user fee is exactly 0. V1 has
no hidden fixed amount and no
undisclosed minimum fee. A user-defined fee cap is local wallet policy, not a
network rule.

Rounding example: 1 DD at 0.5%

Because DD can be accounted for only in whole cents, the result is:

Payment amount:          100 cents = 1.00 DD
Announced rate:           50 bps   = 0.5%
Calculated fee:            0.5 cent
Charged fee:                 1 cent = 0.01 DD
Effective fee rate:                    1.0%
Total user charge:        101 cents = 1.01 DD

The 1-cent fee requires a carrier whose value increases, for example, from
1.00 DD to 1.01 DD. The user wallet must provide suitable DD inputs worth
at least 1.01 DD. As described in Section 8.1, any resulting user change must
be either zero or at least 1.00 DD.

In this case, the wallet displays the announced 0.5% rate, the rounded
0.01 DD fee, the effective 1.0% rate, and the total 1.01 DD charge. This
prevents the unavoidable cent rounding from appearing as a hidden minimum fee.

7.2 Local Ranking

Public announcements contain the rate and supported payment range. The wallet
can therefore calculate the costs locally without sending the amount,
recipient, or user UTXOs to every paymaster:

service_fee_cents = ceil(payment_cents × fee_rate_bps / 10,000)
user_total_cents  = payment_cents + service_fee_cents

The wallet first applies the security filter:

1. valid and fresh announcement,
2. supported protocol version and correct chain,
3. payment within the minimum/maximum range,
4. at least three fresh, fully disjoint admission slots,
5. the announced payment bounds and transport capabilities satisfy local
   policy,
6. a signed endpoint routable under local network policy with acceptable
   transport capabilities; this is not yet a fresh reachability claim,
7. no local blocklist entry or repeated failure status.

Only then are providers sorted in ascending order by user_total_cents. If
prices are equal, the tie-breakers are:

1. local success rate and latency,
2. a fresher admission proof,
3. cryptographically random ordering if they are still tied.

The comparison list is a locally calculated, admission-verified shortlist, not
proof of the operational pool and not yet a UTXO reservation. Exactly one
operational candidate slot and then a specific quote are requested only for
the selected row. If its fee does not exactly match the fee calculated from the currently
ranked signed announcement, or no slot can be reserved, the wallet discards it
and tries the next candidate using the same user input set. This avoids
disclosing the complete payment details to every provider merely to compare
prices.

7.3 Local Reliability Assessment

A provider's reputation is exclusively local wallet policy. It is neither
published nor gossiped and affects neither consensus nor cryptographic
verification. It is stored under the PaymasterId, not under the display name
or endpoint:

struct PaymasterReliabilityBucket {
    int32_t utc_day;
    uint32_t successful_attempts;
    uint32_t provider_failures;
    uint32_t neutral_failures;
    uint32_t availability_timeouts;
    uint64_t successful_latency_sum_ms;
};

struct PaymasterReliabilityRecord {
    PaymasterId provider_id;
    std::array<PaymasterReliabilityBucket, 30> daily_buckets;
    uint32_t consecutive_provider_failures;
    int64_t latency_ewma_ms;
    int64_t last_observation_at;
    int64_t cooldown_until;
};

The reservation manager records at most one terminal outcome per
ProviderAttempt, keyed by its stable attempt ID; a session with several
provider attempts may therefore update several providers. Only locally
verifiable events count as provider failures:

• an invalid signed quote or a deviation from the bound template,
• a reserved provider UTXO that is no longer available after the quote,
• rejection of a demonstrably quote-compliant, validly signed template.

No response is not an unambiguously attributable protocol violation. It only
increments availability_timeouts and may trigger a short local reachability
cooldown; it does not reduce the correctness rate. User cancellation, local
wallet or signing failures, reorganizations, and network or pool failures that
cannot be attributed unambiguously are recorded as neutral. Success is recorded
after local stempool or mempool acceptance; confirmation and reorganization
remain traceable as session states.
latency_ewma_ms measures only successful request/response times within an
authenticated provider session, not confirmation time or general network
latency.

By default, at least five locally assessable sessions are required before a
success rate is displayed. Until then, the UI shows "Insufficient local data
so far." Repeated attributable failures trigger a temporary cooldown with
exponential backoff and a local upper bound. Statistics use 30 UTC daily
buckets; the oldest bucket is discarded on rollover. Older observations thus
lose weight without retaining individual payment records. All thresholds are
wallet configuration, not network parameters.

The selection order remains unambiguous:

1. cryptographic security and liquidity filter,
2. exclusion while a local cooldown is active,
3. sorting by the lowest total DD charge,
4. local success rate and latency only as tie-breakers.

An identity change starts with no local history; positive reputation is never
transferred to a new key. Only aggregate counters, timestamps, and cooldown
state are persisted—never recipients, amounts, user outpoints, or other payment
details. The user can inspect and clear the local history at any time.

A stable provider ID improves reputation and Sybil resistance but also makes
the operator recognizable over time. V1 therefore never transfers reputation
to a new or "rotated" key. An operator may deliberately start with a new
identity and onion service, but then starts without history; a cross-signature
would restore the link that the rotation intended to avoid.

7.4 Automatic Selection for Headless Operation

Automatic selection is a Core function, not merely a matter of calling
getpaymasteroffers and using its first entry. Qt, digibyte-cli, and
third-party software use the same selection routine in PaymasterClient. The
security filters, fee cap, input reservation, and fallback rules therefore
apply identically regardless of the interface.

Among the locally known signed public announcements and explicitly supplied
restricted service descriptors, the lowest-cost usable paymaster is the
provider with the lowest exactly rounded user_total_cents. Core first sorts
without direct contact and then checks candidates strictly sequentially. The
first candidate in cost order that also passes endpoint authentication,
reachability, capacity, and quote validation is the lowest-cost currently
usable provider. The following checks apply to the specific payment:

1. the public announcement or restricted service descriptor, identity, chain,
   endpoint, and admission proof are valid and fresh,
2. the funding model and scope are allowed by local request policy; a
   restricted offer has a valid payment-bound sponsorship authorization,
3. the amount, local cooldown, and admission slots are acceptable; only the
   current candidate then discloses one controlled operational candidate slot,
4. the DD service fee does not exceed the authorized fee cap,
5. the fixed, reserved user input set can represent payment + service_fee
   with valid DD change,
6. a concrete signed quote checks DGB funding against the final transaction
   weight, reserves the suitable provider slot, and passes full revalidation.

Authorized zero-fee offers therefore have the lowest numerical total cost.
Manual selection remains the default in Qt. Only an explicit automatic policy
may choose the lowest-cost usable provider across all accepted models. A
provider pinned by a payment request is not silently replaced by a public one;
that requires the same explicit fallback authorization as any other pinned
provider ID.

The lowest percentage rate alone is insufficient because cent rounding and
transaction constructibility can change the result. When exact total costs are
equal, the tie-breakers in Section 7.2 apply.

getpaymasteroffers returns only a locally sorted snapshot, not a price
guarantee or reservation. If the price, slot, reachability, or chain state
changes before a quote is obtained, Core rejects that candidate and tries the
next eligible provider sequentially. Core never sends parallel quote requests
for the same payment. After an ambiguous timeout, however, an old
provider-local reservation may remain until its short TTL expires while the
next sequential attempt starts; maximum_provider_attempts bounds the number
of such attempts.

7.5 Optional Privacy Selection

lowest_total_cost remains the unambiguous default for automated workflows.
The user may additionally opt into privacy_weighted. Core first determines
the lowest exact total price as before and then forms a group containing only
fully eligible offers up to

lowest_total_cents + privacy_fee_tolerance_cents

Core selects uniformly from that group using its CSPRNG; active cooldowns and
all security filters apply unchanged before selection. The tolerance is a hard
user limit and defaults to 0, making both methods identical. The high-privacy
profile sets maximum_provider_attempts = 1 and disables automatic provider
switching. Every additional attempt requires separate authorization because a
second provider learns the same inputs, recipient, amount, and closely
correlated time.

This option reduces permanent concentration of all payments at the cheapest
provider. It promises no on-chain anonymity and replaces neither Tor nor local
transaction verification.

7.6 Example for 10 DD

Provider	Rate	DD fee	Recipient	Total user charge
Paymaster X	0.5%	0.05 DD	10.00 DD	10.05 DD
Paymaster Y	1.2%	0.12 DD	10.00 DD	10.12 DD
Paymaster Z	2.0%	0.20 DD	10.00 DD	10.20 DD

The DGB miner fee is displayed separately as “paid by the paymaster” and is
never combined with the DD service fee. The current builder uses at least 0.1
DGB for DD transactions
(src/digidollar/txbuilder.cpp); the
quote must check the DGB amount actually required based on the final size.

For USER_PAID, the quote must exactly match the fee calculated
deterministically from the signed terms of the selected offer_id. For
SPONSORED, both the rate and protocol fee in those terms are fixed at zero. A higher or lower rate for the applicable model, an additional fixed amount,
or different rounding causes local rejection. A provider that wants to offer a
lower price first publishes new signed offer terms; the wallet can therefore
determine the complete local ranking without querying every provider for a
price.

8. Sub-1-DD Carriers

8.1 Transaction Model

A separate DD output of 0.05 DD would be invalid. Instead, the paymaster
contributes an existing carrier and receives it back with the fee added.

Example:

User input:               20.00 DD
Paymaster carrier input:   1.00 DD

Outputs:
  Merchant:               10.00 DD
  User change:             9.95 DD
  New paymaster carrier:   1.05 DD

Total input:              21.00 DD
Total output:             21.00 DD
Total user charge:        10.05 DD
Paymaster net revenue:     0.05 DD

All outputs satisfy the 1-DD minimum. The fee is the verifiable difference:

paymaster_fee = carrier_output_amount - carrier_input_amount

The builder selects user DD for payment + service_fee. User change must be
exactly zero or at least 100 cents. A change amount between 1 and 99 cents
makes the template invalid and requires a different input selection. The
recipient, user change, carrier successor, and normal Paymaster fee outputs
must also each be at most 10,000,000 cents. A carrier whose successor would
exceed that limit is unusable for the quote.

8.2 When the Carrier Is Used

• fee = 0: no carrier is required in the payment.
• 1 <= fee < 100 cents: a carrier is mandatory.
• fee >= 100 cents: a normal, separate paymaster DD output is used; no
  carrier is required for this transaction.

Nevertheless, every USER_PAID operator displayed automatically by the wallet
must prove the mandatory carrier pool at all times. A pure SPONSORED operator
charging exactly 0 DD instead proves only the required DGB slots.

8.3 Pool and Concurrency

A spent carrier's successor is initially unconfirmed and therefore cannot be
reused immediately. One carrier consequently represents exactly one parallel
slot. The provider holds multiple confirmed carriers and appropriately split
DGB UTXOs in a dedicated hot wallet.

Sub-1-DD fee revenue remains locked in the carrier until it can be extracted as
a valid output of at least 1 DD during a pool redistribution.

8.4 Limiting On-Chain Clustering

Carrier chains remain publicly traceable; wallet policy can only mitigate this
fundamental property. The operational pool therefore uses a fresh internal
P2TR key for every carrier successor and every DGB change output, selects
confirmed carriers cryptographically at random, and does not reuse a successor
immediately after its first confirmation. Carriers may have different valid
starting values so that every pool does not create the same 1.00 → 1.xx DD
signature.

Each slot preferably holds exactly one sufficiently large DGB fee UTXO;
multiple DGB inputs are allowed only when the concrete network fee cannot
otherwise be funded. The dedicated Paymaster wallet does not mix the
operational pool with private or otherwise used operator funds and does not
deterministically consolidate revenue to the same address after every payment.
These rules make heuristics harder but hide neither the carrier difference nor
the public transaction.

9. Payment-Specific Quote

9.1 Payment Intent

The wallet selects a provider only after local ranking. Only that provider
receives an intent:

struct DDRecipient {
    CTxDestination destination;
    int64_t amount_dd_cents;
};

struct PaymasterPaymentIntent {
    uint16_t version;
    uint256 genesis_hash;
    PaymasterId provider_id;
    uint256 client_nonce;
    std::vector<COutPoint> user_dd_inputs;
    DDRecipient recipient; // V1: exactly one recipient
    CTxDestination user_dd_change;
    uint256 offer_id;
    PaymasterFundingModel funding_model;
    SponsorshipScope sponsorship_scope;
    uint256 policy_hash;
    uint256 sponsorship_authorization_hash;
    int64_t expires_at;
    std::vector<UtxoControlProof> user_input_proofs;
};

V1 permits exactly one recipient per PaymentSession; batch payments are not
part of V1. The payment amount used by the fee formula, quote, display, and
capability is exclusively recipient.amount_dd_cents, so no redundant total
amount field can diverge.

The control proofs prevent an attacker from reserving arbitrary provider slots
using other parties' public DD outpoints. They are domain-separated message
signatures, not transaction signatures. Core first calculates an
intent_core_hash over every intent field except user_input_proofs. Each
proof signature binds
"DigiByte Paymaster User Input v1" || genesis_hash || provider_id || client_nonce || intent_core_hash || outpoint || expires_at; it therefore cannot
be reused with another provider or intent.

accepted_fee_rate_bps and maximum_fee_dd_cents are expressly excluded from
the transmitted intent. Both remain in the local authorized PaymentSession;
the provider does not need the user's willingness to pay in order to apply its
publicly signed rate. Core rejects the quote locally if it violates the rate or
fee cap.

For public community sponsorship, sponsorship_authorization_hash may be
zero; for RESTRICTED, a payment-specific capability is mandatory. In both
cases, policy_hash identifies the sponsorship policy signed by the provider.

9.2 Quote

The provider atomically reserves a specific slot and responds:

struct PaymasterQuote {
    uint16_t version;
    uint256 genesis_hash;
    PaymasterId provider_id;
    uint256 quote_id;
    uint256 intent_hash;
    uint256 offer_id;
    uint256 policy_hash;
    PaymasterFundingModel funding_model;
    SponsorshipScope sponsorship_scope;
    uint256 sponsorship_authorization_hash;
    uint32_t fee_rate_bps;
    int64_t service_fee_dd_cents;

    std::optional<VerifiedDDCarrier> reserved_carrier;
    std::vector<VerifiedDGBInput> reserved_dgb_inputs;
    std::optional<CScript> carrier_return_script;
    std::optional<CScript> provider_fee_script;
    std::optional<CScript> dgb_change_script;

    int64_t network_fee_dgb_satoshis;
    int64_t created_at;
    int64_t expires_at;
    int64_t retry_until;
    CMutableTransaction unsigned_transaction;
    uint256 unsigned_txid;
    uint256 template_commitment;
    std::vector<unsigned char> identity_signature;
};

The quote binds the chain, intent, concrete offer, funding model, scope, policy
and authorization hashes, exact fee, every prevout and provider output, the
complete unsigned transaction, and both expiration times. unsigned_txid is
the hash of that witness-free transaction. template_commitment is a
domain-separated tagged hash over the canonical payment intent or
intent_hash, the canonical quote projection excluding template_commitment
and identity_signature, the canonical unsigned transaction, every actual
prevout value and script, the input roles, and the exclusively permitted
SIGHASH_DEFAULT, plus the creating TXID and verified DD amount for each DD
input. This binds, in particular, the genesis, provider, offer and
quote IDs, policy, funding model, and fee without creating a recursive hash
definition. It is
the only template identifier used by the rest of the protocol. The provider
may assign a given slot to only one active quote.

For a user fee from 1 through 99 cents, reserved_carrier and
carrier_return_script must be present and provider_fee_script absent. At
100 cents or more, the carrier is absent and provider_fee_script contains the
fresh P2TR fee destination. At zero fee, all three fields are absent. A
dgb_change_script is present only when a valid DGB change output is actually
created.

For SPONSORED, fee_rate_bps and service_fee_dd_cents must be zero and
reserved_carrier, carrier_return_script, and provider_fee_script must be
absent. The wallet rejects every sponsored quote
that nevertheless charges a DD service fee or adds a Paymaster DD output. The
actual sponsorship authorization is transferred to the Paymaster only inside
the authenticated direct session; the quote hash then proves which
authorization was checked without exposing the capability in the transaction
or gossip.

10. Secure Signing and Broadcast Flow

1. Prepare intent: The user wallet selects confirmed DD inputs and a new DD
   change address.
2. Compare locally: Public fees and fresh admission proofs are filtered and
   ranked locally without direct provider contact.
3. Request capacity and quote: In the isolated session, the selected
   provider first proves exactly one operational candidate slot. Only that
   provider then receives the intent; the quote checks its actual weight and
   reserves the proved slot with sufficient DGB funding.
4. Build transaction locally: The user wallet builds the complete unsigned
   transaction from the intent and quote itself or reconstructs it
   deterministically byte for byte.
5. Perform full analysis: Prevouts, DD metadata, recipients, user change,
   carrier difference, DGB change, miner fee, locktime, sequences, and unknown
   outputs are checked.
6. Authorize explicitly: The GUI displays the payment, DD fee, total charge,
   provider ID, fee cap, fallback policy, and expiration time. In headless
   operation, the authenticated canonical RPC request with its request_id,
   hard fee cap, and bounded fallback policy replaces the dialog; it authorizes
   only those exact limits.
7. User signs: Only DD inputs actually owned by the wallet are signed with
   Taproot SIGHASH_DEFAULT. No ANYONECANPAY.
8. Provider verifies again: The provider accepts only the stored quote and
   template_commitment, valid user signatures, and UTXOs that remain
   reserved.
9. Provider signs last: Only the reserved carrier and reserved DGB inputs
   are signed.
10. Durable commit before broadcast: The provider signs, runs
    testmempoolaccept, and commits one wallet-database transaction containing
    the ProviderCommitRecord, final raw transaction, TXID and raw-transaction
    hash, quote and idempotency indexes, all provider outpoints, and the atomic
    slot transition from RESERVED to COMMITTED. Where restricted
    sponsorship is used, the same database transaction changes its
    SponsorshipAuthorizationRecord from RESERVED to CONSUMED. Any write
    failure aborts the entire database transaction. Only after a successful
    commit does the provider pass that exact transaction to the existing
    BroadcastTransaction path. This preserves the default-enabled Dandelion stem relay
    (src/net.h,
    src/node/transaction.cpp). The
    user receives the TXID, final raw transaction, and status in PMRESULT.

Why the Provider Signs Last

A transaction signature has no cryptographic expiration date. If the provider
signed first, a client could withhold the partially signed transaction for a
long time and broadcast it later at the provider's expense. Having the
provider sign last minimizes this risk and enables a final check immediately
before broadcast.

This UTXO protocol requires no separate bundler or trusted broadcaster role.
Optionally, the provider may send the already fully signed raw transaction to
a stateless relay service and the normal DGB network at the same time. The
relay may neither add inputs nor alter the quote, signing order, or provider
responsibility and is not a V1 requirement.

The provider treats
provider_id || client_nonce || intent_hash || quote_id || template_commitment as a
unique commit key. retry_same must reserve neither a new slot nor create a new
quote or transaction variant. If a final commit already exists, the provider
returns exactly the same raw transaction and TXID and rebroadcasts it when
needed. If only an earlier state is stored, it reports that state unchanged. A
different request under the same key is rejected.

If no ProviderCommitRecord exists, retry_same may additionally retransmit
the exact user-signed PSBT persisted by the client for that ProviderAttempt.
The provider processes it under an exclusive lock for the commit key and
accepts it only when:

• its unsigned transaction, quote ID, commit key, and template_commitment exactly
  match the persistent attempt,
• user inputs, prevouts, roles, outputs, and sighash types are unchanged,
• only the expected user inputs are signed and every such signature is valid,
• provider inputs remain unsigned,
• no unknown or disallowed proprietary PSBT fields are present,
• and the exact same provider slot remains reserved to the commit key or, if
  its TTL expired, can be atomically rebound to that key without having been
  spent or assigned to another attempt.

After successful verification, the provider atomically persists a
UserAuthorizationRecord containing the commit key, canonical hash of the
user-signed PSBT, and state USER_PSBT_ACCEPTED before signing its inputs. If
that record already exists, the hash must match. A crash before this write is
treated like a first receipt that was never accepted; the retransmitted PSBT
undergoes the same complete verification. A crash afterward resumes exactly
the same attempt.

retry_until defaults to 24 hours after quote creation. Until that time, the
provider retains the quote, slot, and authorization state needed by
retry_same. Afterward, it replaces a non-finalized attempt with a rejecting
idempotency tombstone and accepts no new finalization under that commit key.
This is a provider-retention rule and never evidence that lets the client
wallet release its inputs safely. Only local mempool, stempool, chain, and
input-spend reconciliation can resolve that risk.

Existing Core primitives support this flow: PSBTs can be serialized and
decoded again
(src/external_signer.cpp,
src/psbt.h); underlying transactions can be
compared and input signatures fully checked through
PSBTInputSignedAndVerified()
(src/psbt.cpp,
src/psbt.cpp). The canonical hash is calculated
only after parsing, size checks, and removal or rejection of disallowed
metadata from the canonical normalized protocol projection, never from an
unvalidated network blob. Equality of a retransmitted PSBT means equality of
this canonical projection, not necessarily byte-for-byte equality of an
arbitrary serialization. Before persistence the client finalizes each of its
own inputs individually, leaves every provider input unsigned and unfinalized,
and verifies all user signatures with PSBTInputSignedAndVerified().

Retransmission is not a new authorization, quote, reservation,
ProviderAttempt, or transaction variant and requires no new user signature.
If the original slot is no longer usable, the provider must never replace it
with different outpoints under retry_same; it reports SLOT_UNAVAILABLE, and the client session
remains pending until a safe same-input resolution occurs.

Before a successful ProviderCommitRecord, only the unsigned transaction,
template_commitment, and user signatures are immutable. If the provider has
to sign again after a crash, its witness and therefore the raw-transaction hash
may differ only when no previous final variant was stored or published. From
FINAL_COMMITTED onward, raw transaction, witness, TXID, and raw hash are
immutable and must be returned exactly.

enum class PaymasterResultStatus : uint8_t {
    NO_FINAL_COMMIT,
    USER_PSBT_ACCEPTED,
    FINAL_COMMITTED,
    BROADCAST_ATTEMPTED,
    SLOT_UNAVAILABLE,
    REJECTED,
};

struct PaymasterResult {
    uint16_t version;
    uint256 genesis_hash;
    PaymasterId provider_id;
    uint256 commit_key;
    uint64_t result_sequence;
    PaymasterResultStatus status;
    std::optional<uint256> txid;
    std::optional<uint256> raw_transaction_hash;
    std::optional<CTransaction> final_transaction;
    int64_t updated_at;
    std::vector<unsigned char> identity_signature;
};

PMRESULT is domain-separated and signed with the provider identity key and
binds every field. result_sequence increases monotonically per commit key;
the client ignores regressions. From FINAL_COMMITTED onward, TXID, raw hash,
and the complete final transaction are mandatory. The client accepts them only
after revalidating TXID, template, user and provider signatures, and every
output. raw_transaction_hash is the witness-inclusive GetWitnessHash() of
the final serialized transaction, while txid is its witness-free GetHash().
Size limits apply before signature verification. Provider-reported
status never substitutes for local stempool, mempool, or chain observation; a
bare broadcast claim does not end PENDING_PROVIDER.

Dandelion makes attribution of the first normal P2P relay more difficult, but
it hides the transaction from neither the Paymaster nor the blockchain and
does not replace onion transport for the intent and quote.

Safe Fallback Rule

A user signature already provided does not technically expire with the quote
either. After an ambiguous provider failure, the wallet must therefore not
simply choose new DD inputs for the same payment. All fallback attempts use the
same user input set. Old and new provider variants consequently compete for
the same DD inputs, and no more than one payment can be confirmed.

The reservation manager selects and atomically reserves this user input set in
the wallet database before sending the first payment-specific network request.
Normal, automatically selected, and selected_inputs-preset DD selection paths
must all respect active paymaster reservations. No wallet lock is held during a
P2P or endpoint request. Fallback attempts are strictly sequential; for every
new provider fee, DD funding and valid change are checked again using the same
input set.

Before the first user signature, Core additionally performs a purely local
recovery preflight. Using the already reserved input set and signed public fee
formulas from signed announcements or explicitly supplied service descriptors,
it simulates every permitted fallback variant and rejects candidates
for which payment, service fee, and valid DD change cannot be represented
exactly. It also simulates cancel_to_self and checks whether the wallet can
fund the DGB fee itself. No additional provider is contacted, no operational
slot is requested, and no additional input or signature is reserved.

The result is an advisory snapshot, not an availability guarantee: "Safe
fallback candidates: N" and "Self-funded recovery available/unavailable."
Quotes, UTXOs, and reachability may change later; every actual recovery still
requires complete revalidation and authorization.

A session remains visible as PENDING_PROVIDER until:

• one payment variant is confirmed or accepted into the mempool,
• the user inputs have demonstrably been spent elsewhere on-chain,
• or an explicit conflict/cancellation variant is accepted into the mempool;
  it then moves to CANCEL_MEMPOOL, not yet to CANCELED_SAFE.

The UI must not misrepresent a mere quote timeout as final revocation of an
authorization that has already been signed.

After a user signature has been transmitted, Core reconciles the session,
mempool, chain, and user-input spend status before every further attempt. An
ambiguous state remains PENDING_PROVIDER. When a paymaster_id was explicitly
pinned, Core does not switch identities by default; the caller must expressly
authorize this through the allow_provider_fallback option.

Every fallback discloses the same user input set, recipient, amount, and a
closely correlated time to another operator. Qt explicitly displays this
disclosure before obtaining later authorization. The high-privacy profile
therefore allows only one provider attempt by default; the security-critical
same-input rule is not weakened in favor of new variants that could more
easily produce duplicate payments.

Recovery UX for PENDING_PROVIDER

PENDING_PROVIDER means a wallet reservation caused by a signature that may
still take effect, not a consensus-level lock of the UTXOs. The send view
therefore displays the last contact, affected inputs, current mempool/chain
finding, and three state-dependent actions:

1. Check again: Core queries the previous provider and then reconciles the
   session, local mempool, stempool, chain, and input-spend status again. This
   read-only action requires no new signature.
2. Try another Paymaster: A new sequential attempt must use the same user
   input set, recipient, and recipient amount. New provider components and fees
   are rebuilt and fully analyzed, then authorized and signed again after the
   additional disclosure has been shown. The successfully propagated fallback
   variant is itself the conflict transaction against the old variant.
3. Attempt recovery to own wallet: Core builds a complete alternative DD
   transaction that returns every reserved user DD input to fresh internal DD
   destinations of the same wallet. The return is deterministically split into
   the minimum number of outputs, each between 100 and 10,000,000 DD cents; no
   remainder from 1 through 99 cents is permitted. If the exact amount cannot
   be represented under these rules, recovery preflight rejects that variant.
   It uses the same input set and requires a DGB fee from
   the user's wallet or an explicitly authorized recovery Paymaster. The user
   reviews and signs it like any other payment; Core broadcasts and rebroadcasts
   it through the normal BroadcastTransaction path. If the recovery Paymaster
   charges a DD fee, it is visibly deducted from the returned amount and is
   subject to the same fee cap.

A recovery Paymaster counts as an additional provider attempt and receives the
recovery transaction data. It is therefore not automatically permitted by the
high-privacy profile. Without own DGB, the user must either continue waiting
for the original provider or explicitly authorize the profile change and
additional disclosure; Qt does not present this as a risk-free cancellation.

Release inputs is not an available action after a user signature has been
transmitted. It is offered only when Core can prove that no signature was sent
or a final spend is already known. A cancellation variant in the local mempool
improves practical availability but is not final: remote mempools may know a
competing variant and mempool entries can disappear. Until confirmation, Qt
therefore displays “Cancellation sent—confirmation pending”; only a
confirmed spend of the same inputs leads to CANCELED_SAFE or CONFLICTED.

Core claims neither BIP125 replaceability nor guaranteed displacement of the
old variant. Whichever valid variant confirms first determines the payment
outcome. Before the return transaction is signed, Qt therefore warns explicitly
that the original payment may still confirm. A recovery call is idempotent by
request_id and repeated calls create no additional cancellation variant.

11. PSBT and Wallet Extensions

11.1 New Collaborative Builder

In src/digidollar/txbuilder.h/.cpp:

TxBuilderResult BuildUnsignedCollaborativeTransfer(
    const CollaborativeTransferParams& params,
    const ChainstateManager& chainman);

Requirements:

• no private-key CKey object in the builder,
• fully explicit DD outputs,
• explicit DD and DGB change scripts; the DD script must come from a freshly
  reserved internal ddChangeDest, never implicitly from the signing key,
• verified prevouts instead of trusted parallel amount lists,
• no fallback values for unknown amounts,
• DD minimum for recipients, user change, and carrier successors,
• exact DD conservation,
• checked arithmetic and size/weight limits,
• DGB dust checks via GetDustThreshold() instead of a fixed 1000-satoshi
  value,
• no signing, wallet commit, or broadcast yet,
• no logging of recipients, amounts, user/provider outpoints, change scripts,
  PSBTs, or raw transactions; logs contain only local, non-payment state and
  error codes.

11.2 DD-Capable Partial PSBT Flow

In src/wallet/digidollarwallet.h/.cpp:

CreatePaymasterTransferPSBT(intent, quote);
AnalyzePaymasterTransferPSBT(psbt, expected_intent, quote);
FillDigiDollarPSBT(psbt, SigningRole role);
FinalizePaymasterTransfer(psbt);

Rules:

• An input is signed only after verifying its outpoint, actual prevout, and
  wallet ownership; roles or input positions are never trust sources.
• Inputs owned by other parties and existing signatures remain unchanged.
• complete=false is a normal intermediate state.
• For Taproot, the script and native DGB value of every prevout must be
  available.
• The DD amount of an input is derived from the transaction that actually
  created it.
• Proprietary PSBT fields for the quote ID, display information, or roles are
  transport aids only and are never authoritative.
• The complete unsigned transaction is fixed before the first signature.

The generic combinepsbt, finalizepsbt, and sendrawtransaction RPCs can be
reused. Transactions that created DD inputs, or verified DD metadata, must not
be removed during PSBT size optimization while another participant still
needs them for independent verification.

11.3 Persistent Reservation Manager

New module src/paymaster/reservation.h/.cpp, persisted through the wallet
database:

PaymentSession:
CREATED → INPUTS_RESERVED → AUTHORIZED
  → DGB_COMMITTING → STEMPOOL → MEMPOOL → CONFIRMED
                    ↘ MEMPOOL → CONFIRMED
  → PENDING_PROVIDER[USER_SIGNATURE_SENT | PROVIDER_SIGNED_KNOWN |
                     PENDING_NETWORK | CANCEL_MEMPOOL]
      → STEMPOOL → MEMPOOL → CONFIRMED
       ↘ MEMPOOL → CONFIRMED
      → CANCELED_SAFE (only after confirmed self-recovery)
Waiting states: AWAITING_WALLET_UNLOCK, AWAITING_USER_SIGNATURE
Terminal states: CONFIRMED, FAILED, CANCELED_SAFE, CONFLICTED

ProviderAttempt (0..N per PaymentSession):
CANDIDATE → QUOTED → USER_SIGNED → USER_PSBT_ACCEPTED
  → PROVIDER_SIGNED → FINAL_COMMITTED → BROADCAST → STEMPOOL → MEMPOOL
                                                   ↘ MEMPOOL
Attempt outcomes: REJECTED, QUOTE_EXPIRED, AMBIGUOUS, CONFLICTED

PENDING_PROVIDER remains the stable external umbrella state but has an
internally persisted phase:

USER_SIGNATURE_SENT   user signature transmitted, final outcome unknown
PROVIDER_SIGNED_KNOWN final raw transaction and TXID known locally
PENDING_NETWORK       final transaction known, but absent from local pools
CANCEL_MEMPOOL        recovery variant accepted locally, unconfirmed

The phase determines permitted recovery. With a known raw transaction, Core
can rebroadcast exactly that variant itself; without a final artifact,
retry_same, same-input fallback, or recovery remain available. No substate
releases inputs merely because time has passed.

STEMPOOL transitions to MEMPOOL at fluff relay; a transaction may also be
accepted directly into the local MEMPOOL. Neither state is final. Eviction
from either pool returns a known final transaction to
PENDING_PROVIDER/PENDING_NETWORK; a reorganization moves a previously
confirmed session back according to local pool and spend observations. If a
payment variant confirms, the session becomes CONFIRMED and every recovery
variant becomes CONFLICTED. If self-recovery confirms, it becomes
CANCELED_SAFE and all payment attempts become CONFLICTED. A confirmed
unrelated spend of the bound user inputs results in CONFLICTED.
CANCEL_MEMPOOL remains a non-final substate of PENDING_PROVIDER until
confirmation.

The unique key within the applicable wallet database is request_id; the
wallet itself already provides the namespace. V1 requires a canonical
lowercase, 36-character representation of a 128-bit UUID.
canonical_request_hash is an immutable value stored in the session record. A
concurrent insert with the same ID atomically joins the existing session when
the hash matches and is rejected otherwise.

At a minimum, the hash binds the genesis hash, the single recipient and amount, any preset
inputs, and all authorization-relevant options after defaults are resolved. It
is calculated from typed, parsed, canonically serialized values, never from raw
JSON; semantically equivalent amount representations therefore produce the
same hash. Internally selected inputs are subsequently bound immutably to the
session as well.

The PaymentSession retains the payment request, authorized effective fee cap,
and user input set selected once. It exists even when auto selects the direct
DGB path. During the safety-relevant lifetime, every contacted provider
receives a separate, append-only ProviderAttempt. State transitions add the provider ID, nonce,
complete signed quote, exact template, user-signed PSBT, and—once available—the
provider-signed final transaction; once set, an artifact is never overwritten.
The user-signed PSBT is persisted before it is transmitted to the provider.

Every fallback builds a new complete transaction variant from the same user
input set, analyzes it again, and requests a new user signature. Because
SIGHASH_DEFAULT is used, a signature must never be transferred to a variant
with different provider inputs, outputs, or fees. Earlier attempts remain
stored until final conflict and duplicate-payment resolution and are not
overwritten by the new attempt during that period.

QUOTE_EXPIRED ends only the individual provider attempt. Once the user
signature has been transmitted, neither quote expiration nor a timeout ends
the user authorization or input reservation; the parent session remains
PENDING_PROVIDER. failed is final only when Core can prove that no signed or
started commit can still take effect. An ambiguous state is never failed and
does not release the user inputs.

The following are reserved atomically:

• user DD inputs on the client side,
• the user DGB fee inputs selected by the direct DGB preflight when
  fee_mode_used: "dgb" is fixed,
• carrier and DGB fee inputs on the provider side,
• quote ID, template_commitment, expiration time, and expected successors.

After the auto preflight, Core atomically transfers the planned inputs into
the session reservation under the same wallet synchronization and persists
fee_mode_used before contacting a provider or starting direct signing. A
resumed session does not run the preflight again and must never switch fee
branches because the wallet balance has changed.

The request_id mapping is persisted before mode selection and before any
transaction side effect. Concurrent calls with the same ID join the same
session even for auto → dgb. Before CommitTransaction(), Core stores the
DGB_COMMITTING state, TXID, reserved inputs, all final outputs and change
scripts, and either the fully signed raw transaction or a fully reproducible
signed PSBT. After a lost RPC response or restart, it reconciles the wallet,
mempool, and chain against this record and returns the same TXID or rebroadcasts
that exact transaction; Core never builds a second payment with new inputs.

lockunspent alone is not sufficient for session management. The manager
requires a TTL, restart recovery, mempool/block reconciliation, and explicit
conflict handling.

11.4 Data Minimization and Retention

Crash safety takes precedence over deletion while an authorization is active
or ambiguous. Once a session is final and reorganization-safe, Core reduces
the additional Paymaster data according to state:

• Attempts that expire before a user signature lose their intent, quote, and
  provider metadata after outcome accounting; only aggregate local reliability
  remains.
• PENDING_PROVIDER, USER_SIGNED, PROVIDER_SIGNED, and ambiguous conflicts
  retain every artifact required for duplicate-payment safety.
• After CONFIRMED, final CONFLICTED, CANCELED_SAFE, or provable FAILED
  and a configurable reorganization-safety period, the provider attempt,
  nonce, quote, PSBT, and provider-related timestamps are removed.
• A minimal idempotency tombstone containing request_id,
  canonical_request_hash, final state, and TXID where applicable remains so
  that the same request ID cannot later create a second payment.
• The normal wallet transaction remains part of the already public wallet
  history; Paymaster code creates no second permanent payment profile beside
  it.

On the provider side, the plaintext capability is never stored. Before the
provider signs, however, the wallet persists the minimal
UserAuthorizationRecord containing commit key, canonical PSBT hash, and
state, and for restricted sponsorship the secret-free
SponsorshipAuthorizationRecord containing capability hash, payment binding,
and RESERVED. Plaintext intent, IP address, and separate recipient or amount
fields remain outside persistent storage except for unavoidable active
reservation data. Once the provider has signed its inputs, crash safety and
idempotency take precedence: one wallet-database transaction writes the
ProviderCommitRecord, exact final raw transaction, TXID, raw hash,
commit/quote/idempotency indexes, provider outpoints, and slot state; where
applicable it simultaneously consumes sponsorship with RESERVED → CONSUMED.
Broadcast starts only afterward. This write-before-broadcast rule follows the existing CWallet::CommitTransaction()
pattern, which calls AddToWallet() before mempool submission
(src/wallet/wallet.cpp).

At source line 2526, the existing path currently writes tx->ToString() to
the wallet log. A Paymaster implementation must therefore audit every path actually
used—the collaborative builder, selective signing, CommitTransaction,
BroadcastTransaction, Qt, and P2P processing—for sensitive logs.
Paymaster-specific logs contain only shortened non-correlatable IDs, states,
and error classes, never TXID, raw transaction, PSBT, intent, capability, outpoints, recipient,
amount, IP address, or peer ID. Where an existing path logs more, the
Paymaster commit uses structured logging or a non-logging persistence
primitive. The ordinary wallet history of the final public transaction is
unaffected.

Existing wallet encryption protects private keys but does not automatically
encrypt transaction history or arbitrary metadata
(src/wallet/crypter.h). V1 therefore does
not falsely describe the commit record as fully encrypted at rest. Beyond the
necessarily retained final transaction, it persists no plaintext intent, IP
address, separate recipient or amount fields, sponsorship capability, or
complete PSBT. After a confirmed spend or final conflict and the replay/reorg
safety period, the additional commit index is reduced to the commit key, final
state, and TXID; ordinary wallet transaction history continues to follow
normal Core policy.

12. Proposed Modules and RPCs

New Core Modules

src/paymaster/types.{h,cpp}
src/paymaster/directory.{h,cpp}
src/paymaster/manager.{h,cpp}
src/paymaster/client.{h,cpp}
src/paymaster/provider.{h,cpp}
src/paymaster/reservation.{h,cpp}
src/paymaster/reputation.{h,cpp}
src/paymaster/validation.{h,cpp}

The new structures use named or strong amount types such as DDCents and
DGBSatoshis. An unqualified CAmount must not represent DD and DGB
interchangeably at any network or quote boundary.

Operator RPCs

createpaymasteridentity
setpaymasterenabled
setpaymasterpolicy
preparepaymasterpool
rebalancepaymasterpool
getpaymasterinfo
getpaymasterpoolinfo
listpaymasterreservations
cancelpaymasterquote
startpaymaster
stoppaymaster

For every enabled operator, setpaymasterpolicy additionally requires
maximum_network_fee_dgb_satoshis, a positive absolute cap on the DGB network
fee paid by the provider per final transaction. The quote,
testmempoolaccept preflight, and final transaction must satisfy both this cap
and the configured fee-rate policy; an estimate can never override the
absolute limit.

Client/Transaction RPCs

listpaymasters
getpaymasteroffers <amount_cents>
getpaymasterreputation [provider_id]
clearpaymasterreputation [provider_id]
getdigidollarsendsession <lookup>
resolvepaymastersession <lookup> <action> [options]
requestpaymasterquote <provider_id> <intent>
createpaymasterdigidollarpsbt <quote_id>
analyzepaymasterdigidollarpsbt <psbt>
walletprocesspaymasterpsbt <psbt>
submitpaymasterdigidollar <psbt>

For PENDING_PROVIDER, resolvepaymastersession accepts the actions refresh,
retry_same, fallback, and cancel_to_self. fallback retains the bound
user input set and enforces provider, fee, and privacy authorization.
cancel_to_self does not locally release inputs; it creates a same-input,
wallet-owned conflict transaction and returns its status and TXID. Every
mutating action uses the same persistent session and request_id; a repeated
call resumes the existing attempt.

The recommended escalation order is refresh → retry_same → fallback →
cancel_to_self. retry_same sends the original commit key to the same
provider and, when no final artifact is known, the exact user-signed PSBT
persisted in the corresponding ProviderAttempt. It accepts only the same
state or the same final raw transaction and TXID and creates no new
ProviderAttempt, quote, authorization, or signature. If the final raw
transaction is already known on the client, Core rebroadcasts it itself instead
of disclosing the payment again.

The current RPC has five positional parameters
(src/rpc/digidollar.cpp) and
immediately invokes the single-wallet
DigiDollarWallet::TransferDigiDollar() path
(src/rpc/digidollar.cpp). For a
backward-compatible extension, options is appended only as a sixth, optional
parameter:

senddigidollar address amount [comment] [fee_rate] [selected_inputs] [options]

fee_rate remains in its current position as an ignored compatibility
parameter. An example options object for fully automated selection is:

{
  "fee_mode": "paymaster",
  "selection": "lowest_total_cost",
  "privacy_profile": "standard",
  "privacy_fee_tolerance_cents": 0,
  "paymaster_id": null,
  "accepted_funding_models": ["sponsored", "user_paid"],
  "sponsorship_context": null,
  "maximum_paymaster_fee_cents": 25,
  "allow_provider_fallback": true,
  "maximum_provider_attempts": 3,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

V1 has the following unambiguous semantics:

• Without options, or with fee_mode: "dgb", the current direct path remains
  unchanged: the wallet funds the DGB network fee itself and contacts no
  paymaster. A supplied request_id adds only the idempotent session wrapper,
  not a different transaction-construction path.
• fee_mode: "paymaster" uses a paymaster regardless of the wallet's own DGB
  balance. Without paymaster_id, Core automatically selects the lowest-cost
  usable provider. This directly supports “always use the lowest-cost
  paymaster” in headless applications.
• fee_mode: "auto" first performs a complete, side-effect-free funding
  preflight of the current DGB path, including final fee calculation and actual
  coin selection. This adds a pure planning function with a typed funding
  status to today's Boolean and text-error path. Only
  INSUFFICIENT_DGB_FEE_INPUTS—no DGB fee inputs suitable under the current
  wallet safety policy—triggers paymaster selection. An invalid recipient,
  insufficient DD, or builder or validation failures return an error
  immediately. A locked wallet never triggers Paymaster fallback; it pauses the
  session in AWAITING_WALLET_UNLOCK. Core must not switch to a paymaster after signing or
  commit has started. DGB cost and the DD service fee are not compared because
  no trustworthy exchange rate exists between them.
• A set paymaster_id initially pins exactly that identity. Core does not
  silently switch to another provider on failure unless the caller explicitly
  sets allow_provider_fallback: true. Fallback is enabled by default for
  automatic selection without an ID.
• In V1, selection supports lowest_total_cost and privacy_weighted.
  Without a provider ID, lowest_total_cost is the default. The definitions in
  Sections 7.4 and 7.5 apply, not merely the lowest announced rate.
  privacy_fee_tolerance_cents is valid only for privacy_weighted, must not
  be negative, and is additionally limited by local wallet policy.
• privacy_profile is standard or high. high requires an onion endpoint,
  proxy stream isolation, maximum_provider_attempts: 1,
  allow_provider_fallback: false, disabled IP logging, and disabled P2P
  message capture. There is no silent fallback to clearnet or P2P v1.
  standard permits clearnet only with successfully negotiated P2P v2. Core,
  not merely Qt, enforces these rules.
• On mainnet, both client and operator reject every payment-specific Paymaster
  session while -capturemessages is active. The existing capture path writes
  application payloads together with the peer address to disk
  (src/net.cpp); transport encryption does not
  protect that local plaintext copy. Regtest may override this restriction only
  with explicitly synthetic test data. Although -logips is disabled by
  default (src/logging.h), the high-privacy
  profile additionally treats it as a hard readiness error.
• accepted_funding_models is a non-empty allowlist containing sponsored
  and/or user_paid. When absent, an ordinary user-initiated payment allows
  only user_paid; Qt adds a visible authorized sponsorship offer after user
  confirmation. Headless applications must explicitly accept sponsored.
  A newly received payment request therefore cannot silently change the
  funding source of an existing session.
• sponsorship_context is permitted only for sponsored and contains the
  signed service descriptor and opaque authorization capability. Core validates
  the chain, provider, policy, payment binding, and expiration, transfers the
  capability only in the authenticated provider session, and persists or logs
  only its hash. A descriptor with a provider ID pins that identity unless the
  caller explicitly authorizes a provider change.
• maximum_paymaster_fee_cents is a hard authorization limit. For any
  high-level call in which a paymaster is permitted, it must be set either in
  the request or in persistent wallet policy; “not set” never means
  “unlimited.” Qt sets the limit from the display that the user explicitly
  confirmed. Every concrete quote is checked again against the announcement,
  wallet policy, and this limit.
• When both request and wallet limits exist,
  effective_cap = min(request_cap, wallet_policy_cap). Core persists this
  effective value immutably when creating the session. A later relaxation of
  wallet policy cannot increase it; a later tightening may further limit or
  stop new attempts.
• maximum_provider_attempts limits the strictly sequential provider attempts;
  the contextual default is 1 when fallback is disabled and 3 otherwise. Every
  attempt uses the user input set that was atomically reserved once.
• request_id is mandatory whenever the call may use a paymaster. Qt generates
  it before starting; Core persists it atomically when creating or joining the
  session. An RPC caller supplies it. The same ID with the same canonical
  payment request always returns the same persisted session or existing TXID.
  The same ID with a changed recipient, amount, or options is
  rejected. A transport retry of the same provider attempt with the same
  (provider_id, client_nonce, intent_hash) returns the same quote and does not
  reserve a second slot; the same nonce with a changed intent is rejected. A
  fallback is a new persisted provider attempt with a new client_nonce. The
  request_id remains local wallet and RPC state and is neither gossiped nor
  sent to the provider.
• Unknown options fields and contradictory combinations are rejected, not
  ignored. With fee_mode: "dgb", none of the paymaster fields except
  request_id are valid. When allow_provider_fallback is false,
  maximum_provider_attempts must be 1. A paymaster_id set with auto applies
  only to a possible paymaster fallback.

The fee rate and fee cap are evaluated only in this local session and are not
serialized into PaymasterPaymentIntent. The same applies to selection mode
and privacy tolerance; the provider learns no additional willingness to pay
from them.

The current handler checks the wallet lock before parsing parameters
(src/rpc/digidollar.cpp). The
options-based path deliberately changes this order: Core first parses and
normalizes the values required for request_id and the request hash, then looks
up the session. An identical completed session can therefore return its
existing TXID even if the wallet has since been locked. Only creating a session
or advancing it to a new signature requires the normal wallet unlock. Calls
that must persist a new session before signing, or resume one awaiting a
signature, return structured session_state: "AWAITING_WALLET_UNLOCK",
final: false, and wallet_unlock_required: true; no provider contact or
fallback occurs. Qt requests an unlock. Calls without options retain the
current ordering and error behavior.

The existing precheck against only the recipient amount is insufficient on the
paymaster path. Core checks the confirmed DD balance and any selected_inputs
against payment + service_fee, while continuing to require change of exactly
zero or at least 100 cents. After receiving a quote, it revalidates the
identity, chain, intent, policy hash, expiration, prevouts, slot, template, and
fee; it never trusts the output of getpaymasteroffers as a binding offer.

Existing calls without options retain their result and error behavior. Every
call with a request_id adds the same session and idempotency fields—for
explicit dgb, paymaster payments, and both auto branches. For example, an
unresolved paymaster result is:

{
  "to_address": "DD...",
  "amount": 1000,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "...",
  "requested_fee_mode": "paymaster",
  "fee_mode_used": "paymaster",
  "selection": "lowest_total_cost",
  "privacy_profile": "standard",
  "privacy_fee_tolerance_cents": 0,
  "paymaster_id": "...",
  "funding_model": "user_paid",
  "sponsorship_scope": "public",
  "fee_rate_bps": 50,
  "paymaster_fee_cents": 5,
  "user_total_cents": 1005,
  "provider_attempts": 1,
  "user_dd_inputs_used": 1,
  "provider_dd_inputs_used": 1,
  "provider_dgb_inputs_used": 1,
  "network_fee_paid_by": "paymaster",
  "network_fee_satoshis": 10000000,
  "status": "pending_provider",
  "session_state": "PENDING_PROVIDER",
  "pending_phase": "USER_SIGNATURE_SENT",
  "final": false,
  "broadcast_state": "unknown",
  "confirmation_state": "unconfirmed"
}

status remains the coarse compatibility indicator success,
pending_provider, or failed; for calls with options, session_state,
optional pending_phase, final, broadcast_state, and confirmation_state
are authoritative. final is true only in a terminal state. Stempool or
mempool acceptance, including CANCEL_MEMPOOL, remains unconfirmed and
non-final. broadcast_state distinguishes at least not_attempted, unknown,
accepted_stempool, accepted_mempool, evicted, and rejected;
confirmation_state distinguishes at least unconfirmed,
payment_confirmed, recovery_confirmed, conflicted, and reorged. A
provider report of BROADCAST_ATTEMPTED establishes none of those local
observations. txid may be included once a validated final raw transaction is
known locally and is an optional STR_HEX field in the extended RPCResult.
failed denotes only a persisted session that has demonstrably failed permanently and
additionally contains failure_code and failure_message. An ambiguous state
after a user signature remains pending_provider. Validation, wallet, or
balance errors before session creation remain JSON-RPC errors, as they are
today.

For auto → dgb, the mode fields are requested_fee_mode: "auto" and
fee_mode_used: "dgb"; paymaster fields are absent and
network_fee_paid_by is user. The existing inputs_used remains the count of
all transaction inputs for compatibility. The new unambiguous DD and DGB role
counters prevent applications from misinterpreting it as a DD-only input
count.

The JSON conversion table in
src/rpc/client.cpp is extended with:

{ "senddigidollar", 5, "options" },
{ "getdigidollarsendsession", 0, "lookup" },
{ "resolvepaymastersession", 0, "lookup" },
{ "resolvepaymastersession", 2, "options" },
{ "getpaymasteroffers", 0, "amount_cents" },
{ "setpaymasterpolicy", 0, "policy" },
{ "preparepaymasterpool", 0, "options" },
{ "rebalancepaymasterpool", 0, "options" },
{ "requestpaymasterquote", 1, "intent" },

Index 5 is zero-based and designates the sixth parameter. Existing invocations
with up to five parameters and the current DGB path therefore remain usable
without modification.

getdigidollarsendsession returns any persistent send session without creating
a new payment attempt. lookup is a JSON object containing exactly one of
session_id or request_id; unknown fields, both fields, or neither field are
rejected.

13. Qt and CLI Implementation

13.1 Principle: One Core Backend, Two Interfaces

Qt is an optional user interface, not a technical requirement for operating a
paymaster. Identity, policy, the liquidity pool, reservations, transaction
construction, signing, discovery, and operational state are handled entirely
by digibyted, the wallet, and the Core modules described in Section 12. An
operator can therefore configure and run the system exclusively with
digibyte-cli and a dedicated loaded wallet.

Qt calls the same Core and wallet interfaces asynchronously through
WalletModel. There must be no paymaster configuration stored only in Qt and
no state or signing path that is accessible only through Qt. This makes GUI
and headless operation functionally equivalent. A paymaster started in
digibyted does not require a running Qt process.

13.2 Extending the DD Send Interface

The existing DD send interface currently displays only a fixed DGB fee and
invokes the direct single-wallet path
(src/qt/digidollarsendwidget.cpp,
src/qt/walletmodel.cpp).

The proposed extension lets the user choose between own DGB fee,
paymaster, and automatic fallback when the DGB fee cannot be funded. In
paymaster mode, the user can pin a provider or choose automatically select the
lowest-cost provider; this mode uses a paymaster even when DGB is available.
Manual selection remains the GUI default. The user may optionally enable
Privacy selection with a visible maximum additional fee. The offer list additionally displays
the objective funding type Sponsored or User-paid and, for sponsored
offers, the signed sponsor display name and 0 DD user fee. Restricted
offers appear only for the current valid payment request and are not added to
the public directory. The list also displays the provider, percentage fee, DD
fee, total DD charge, and Admission reserve verified status. Operational
outpoints and claimed total free slots are not displayed before selection. Only
the concrete quote shows Payment slot reserved. After at least five assessable local sessions,
it additionally shows the success rate, sample size, and typical latency.
Sorting still prioritizes the lowest total charge; offers under an active local
cooldown are not shown.

The confirmation dialog must display:

• the recipient and exact recipient amount,
• the paymaster ID and signed display name,
• the funding model, scope, and, for sponsorship, the signed sponsor display
  name and bound policy hash,
• the announced percentage rate, exact rounded DD fee, and the effective
  percentage rate when rounding changes it,
• the total DD charge,
• the DD change,
• “DGB network fee paid by the paymaster,”
• the authorized DD fee cap and whether fallback may switch provider identity,
• the privacy profile, selection method, maximum privacy premium, and, for
  every additional attempt, a warning that another operator receives the same
  payment data,
• the quote expiration and capacity status,
• a warning if the price or provider has changed since selection.

If the price or provider changes before signing, the user reconfirms the
updated values. A later automatic fallback signature is permitted only if the
original dialog expressly authorized both the identity change and the displayed
hard fee cap.

All discovery and quote requests run asynchronously. No P2P, RPC, or
chainstate access may block the GUI thread.

The existing synchronous WalletModel::sendDigiDollar() method remains for the
compatible direct call. A new asynchronous start call with
PaymasterSendOptions creates the same persistent PaymentSession as the
high-level RPC and returns a new DigiDollarSendStartResult containing either a
session handle or an immediate validation error. The existing
DigiDollarSendResult
(src/qt/walletmodel.h) remains dedicated
to the synchronous legacy path. Changes are reported through a
paymentSessionChanged(session_id) signal; a separate PaymentSessionView with
its own PaymentSessionState supplies the mode, provider, exact costs, attempt
count, and pending, success, or failure state.

Because today's WalletModel::UnlockContext
(src/qt/walletmodel.h) covers only the
synchronous call, it is never retained or captured across an asynchronous
network phase. The session enters AWAITING_WALLET_UNLOCK or
AWAITING_USER_SIGNATURE immediately before each user signature. Qt then
requests an unlock and retains the context only for the short signing step.
Cancellation or failure to unlock pauses the session and is not a provider
failure; neither the passphrase nor unlock context is persisted.

The common backend path invokes the existing wallet builder for dgb and
PaymasterClient for paymaster or a triggered auto fallback. Qt implements
neither its own ranking nor a second fallback or signing path.

For PENDING_PROVIDER, Qt replaces a misleading generic Cancel button with
a recovery panel containing Check again, Try another Paymaster, and
Attempt recovery to own wallet. It clearly distinguishes inputs that are merely
reserved inside the wallet, a variant detected in the mempool, and a confirmed
spend. Before fallback or return, Qt displays the new fee, disclosure to an
additional provider, and the warning that the original variant may still take
effect until a conflicting spend confirms. Qt calls only
resolvepaymastersession; the same functions remain available to headless
applications.

13.3 Dedicated Qt Area for Paymaster Operators

A dedicated Paymaster entry in the wallet navigation is proposed for
operators. It always shows exactly which currently selected wallet it applies
to. Operation is disabled for a watch-only wallet or a wallet without private
keys; this does not affect normal paymaster selection for outgoing payments.

The area consists of four views:

1. Overview: state OFFLINE, STARTING, ONLINE, or DEGRADED, provider
   ID, signed display name, endpoint, latest announcement, P2P reachability,
   wallet lock state, and specific readiness errors.
2. Configuration: display name, offered funding models, public or
   restricted scope, percentage fee for USER_PAID, minimum and maximum
   amounts, the absolute DGB network-fee cap per transaction, maximum
   concurrent quotes, quote TTL, minimum confirmations, and optional automatic
   start after the wallet is unlocked. Percentage pricing,
   zero-fee sponsorship, and example costs are displayed separately before
   settings are saved. Sponsor settlement and user accounts are not part of
   this Core configuration.
3. Liquidity: strictly separated admission reserve and operational pool;
   confirmed, unconfirmed, and reserved DD carrier and DGB slots; locally
   available DD and DGB liquidity; the minimum threshold of three disjoint
   admission slots; and actions to prepare and repartition the pool. Before
   execution, every action displays the outputs it will create and the
   operator's own DGB network fee, and requires confirmation.
4. Activity: shortened local quote ID, state, the provider's own reserved
   slot, its own DD fee revenue, expiration time, and TXID where applicable.
   Recipient, user amount, user outpoints, IP/peer ID, intent, and capability
   are not retained as an additional Paymaster activity profile. Ordinary
   wallet history still contains the final public transaction and its publicly
   observable outputs.
   Cancellation is
   allowed only in a protocol state in which no signature from another party
   has yet been bound; Core enforces this rule independently of Qt.

Security warnings are shown directly on the overview rather than only in a
log: a locked wallet, missing carriers, insufficient DGB, unconfirmed pool
transactions, a stale announcement, an unreachable endpoint, conflicts, or a
node that is not fully synchronized. Private keys and wallet passphrases are
never displayed or stored in the paymaster configuration.

The Qt view can be implemented in src/qt/paymasterpage.{h,cpp} and connected
through WalletModel. It contains only presentation and user input.
Validation and state transitions remain in src/paymaster/ and the wallet so
that Qt does not acquire a second, divergent protocol implementation.

13.4 Setup Wizard in Qt

The optional wizard guides an operator through the following steps:

1. select or create and encrypt a dedicated paymaster wallet,
2. create the provider identity and record its provider-ID fingerprint,
3. set the optional display name, percentage fee, privacy profile, and
   operating limits,
4. prepare a separate admission reserve with at least three DGB slots and, for
   every user-paid offer, three DD carriers,
5. prepare the disjoint operational carrier/DGB pool,
6. wait for confirmations and node synchronization,
7. verify the P2P v2 or onion endpoint, proxy isolation, and reachability,
8. confirm the summary and start the paymaster.

UTXOs must never be created or repartitioned without explicit approval. Before
approval, the wizard displays the DD outputs, DGB outputs, expected network
fee, and remaining wallet balances. After each step, the operator can close
Qt and continue with the CLI; progress persists as Core and wallet state.

The start button is enabled only after Core reports ready: true. This
requires, at a minimum, an identity, a synchronized node, -prune=0,
-txindex=1, complete DD transaction data, an unlocked
signing-capable wallet, a valid endpoint, and three confirmed disjoint DGB
admission slots. USER_PAID additionally requires three matching admission
carriers; every admission outpoint is separate from the operational pool. At
least one complete operational slot must also be available for ONLINE. The
same readiness check covers the selected privacy profile, -capturemessages,
-logips, transport type, and proxy isolation.
startpaymaster performs the same check and
returns structured error reasons when invoked through the CLI; the restriction
is therefore not merely a GUI safeguard.

13.5 Full CLI Parity

Every Qt action uses the Core interfaces defined in Section 12. Identity,
policy, pool, readiness, reservations, start, and stop are therefore fully
accessible through RPC; user functions are likewise available through
getpaymasteroffers and the extended senddigidollar.

For example, a fully headless setup can be operated as follows; the exact JSON
quoting depends on the shell in use:

digibyte-cli -rpcwallet=paymaster createpaymasteridentity "Community PM"
digibyte-cli -rpcwallet=paymaster setpaymasterpolicy '{"funding_models":["sponsored","user_paid"],"sponsorship_scope":"public","fee_rate_bps":50,"min_amount_cents":100,"max_amount_cents":100000,"quote_ttl":60,"maximum_network_fee_dgb_satoshis":20000000}'
digibyte-cli -rpcwallet=paymaster preparepaymasterpool '{"admission_carrier_slots":3,"admission_dgb_slots":3,"operational_carrier_slots":5,"operational_dgb_slots":5}'
digibyte-cli -rpcwallet=paymaster getpaymasterinfo
digibyte-cli -rpcwallet=paymaster getpaymasterpoolinfo
digibyte-cli -rpcwallet=paymaster startpaymaster

A user payment can likewise be automated safely and idempotently without Qt.
Named arguments avoid passing empty placeholders for the existing optional
positional parameters:

# Always use the lowest-cost eligible paymaster
digibyte-cli -rpcwallet=user -named senddigidollar address="DD..." amount=1000 options='{"fee_mode":"paymaster","selection":"lowest_total_cost","maximum_paymaster_fee_cents":25,"maximum_provider_attempts":3,"request_id":"550e8400-e29b-41d4-a716-446655440000"}'

# Use the lowest-cost paymaster only when the concrete DGB fee cannot be funded
digibyte-cli -rpcwallet=user -named senddigidollar address="DD..." amount=1000 options='{"fee_mode":"auto","selection":"lowest_total_cost","maximum_paymaster_fee_cents":25,"maximum_provider_attempts":3,"request_id":"550e8400-e29b-41d4-a716-446655440001"}'

Third-party software may use getpaymasteroffers to build a custom interface
or additional local policy and then pass an explicit paymaster_id. The
idempotent high-level call is nevertheless recommended for unattended
payments: Core revalidates the snapshot and keeps selection, quoting, input
reservation, signing, and safe fallback together in one persistent session.

A sponsorship capability is secret and must not appear as a visible command
line argument or in shell history. digibyte-cli already supports -stdin for
reading additional arguments line by line from standard input
(src/digibyte-cli.cpp,
src/digibyte-cli.cpp). Headless
integrations use that path or a locally authenticated RPC client with protected
process memory; concept examples never contain a real capability.

For unattended operation, the paymaster wallet is loaded using the existing
Core wallet configuration; activation and policy are stored persistently in
that wallet. A passphrase, seed, or private identity key must not be supplied
in digibyte.conf or as a command-line argument. An encrypted paymaster
enables signing only after an authorized wallet unlock and safely falls back
to OFFLINE or DEGRADED when the wallet is locked.

14. Security Model

14.1 Non-Negotiable Invariants

1. User and provider private keys never leave their respective wallets.
2. The user wallet does not trust any provider-supplied amount without
   verifying it against the chain.
3. The user wallet constructs or reconstructs the complete transaction
   locally.
4. The user does not sign before the quote and all outputs have been fully
   verified.
5. SIGHASH_DEFAULT, with no ANYONECANPAY in the MVP.
6. Exactly one V1 recipient and no unknown or subsequently mutable outputs.
7. The provider signs only the stored quote with the matching
   template_commitment.
8. The provider signs last, durably commits the final transaction, and
   broadcasts it immediately afterward.
9. Announcements, capacity proofs, and quotes are domain-separated and bound
   to the active chain.
10. Discovery information never affects consensus validation.
11. Global announcements contain admission outpoints only, never operational
    payment outpoints.
12. Recipients, amounts, user outpoints, capabilities, TXIDs, and complete
    transaction artifacts appear in no Paymaster production log.
13. DD and DGB change use fresh internal destinations that the session binds
    immutably before the first signature.
14. Only the selected provider receives the payment intent; only that provider
    discloses an operational slot proof to the selected client.
15. A provider commit key creates at most one final transaction; retry_same
    continues with at most the same user-signed PSBT and returns or rebroadcasts
    only that transaction.

14.2 Principal Attacks and Countermeasures

Attack	Countermeasure
Paymaster replaces the recipient or user change	Local reconstruction, complete output verification, SIGHASH_DEFAULT
Hidden or increased DD fee	Deterministic formula, announcement limit, signed quote, user-defined maximum
Fabricated DGB or carrier liquidity	Specific outpoints, chain verification, control proofs, fresh challenge
Same UTXO used for multiple identities	Outpoint deduplication; do not count it as independent capacity
Multiple quotes for the same slot	Atomic reservation in the provider database; recheck before signing
Provider crash after final signature	Atomic ProviderCommitRecord before broadcast; signed PMRESULT; exact recovery through retry_same
Provider crash after PSBT receipt but before final commit	Client persists the user-signed PSBT; retry_same retransmits exactly that artifact; atomic UserAuthorizationRecord prevents a divergent continuation
Reservation spam	User DD control proof, short TTL, limits per peer/netgroup and identity
Replay from another chain	Genesis hash and protocol domain in every signature
Stale price or endpoint	Sequence, TTL, policy hash, new signed announcement
Cheap Sybil or gossip spam	Size limits before cryptographic verification, rate limits, cache limit, minimum liquidity
Excessive DGB miner fee	Provider verifies actual prevouts, absolute fee, and fee rate before signing
Provider refuses after the user signs	Persistent pending state, fallback with the same DD input set, and a local reliability cooldown
Privacy leak through price comparison	Public pricing formula and admission proofs; no operational snapshots in advance; intent sent only to the selected provider
Global mapping of operational UTXOs	Strictly separated admission reserve never used in payments; at most one operational candidate slot per selected client
User IP linked to payment	High-privacy onion-only profile with stream isolation and no clearnet fallback; clearnet only over P2P v2
Sensitive data in debug.log	Structured state/error codes without recipient, amount, outpoints, TXID, PSBT, or raw transaction
Plaintext payload in message capture	No mainnet Paymaster session while -capturemessages is active
DD change address reuse	Explicit fresh ddChangeDest bound locally before signing
Forged or replayed sponsorship proof	Signed service descriptor; binding to chain, provider, policy, payment, nonce, and expiration; provider-side replay protection
Sponsorship capability leak	Never in gossip, announcements, logs, or persistent plaintext; authenticated direct transfer and a persisted hash only
Hidden fee in a sponsored payment	Quote and complete transaction must contain fee_rate_bps = 0, a zero DD fee, and no Paymaster DD output
SSRF or unsafe web endpoints	Quote protocol over existing P2P connections; no arbitrary URLs in Core

14.3 Limits of Protection

Without a consensus change, no protocol can force a voluntary operator to
respond or actually sign a reserved quote. A malicious paymaster can pretend
to be available, abort, or promise the same liquidity to multiple clients.
Provided the invariants above are maintained, however, it cannot:

• redirect DD to another recipient,
• debit more DD than was confirmed,
• steal the user's change,
• add new inputs or outputs after the user signs.

The remaining risks primarily concern availability, timing, and privacy, not
unrestricted control over user funds.

14.4 Privacy Boundaries

The selected Paymaster necessarily sees the complete transaction that it must
validate before signing: user inputs, recipient, user change, amount, and time.
Tor hides the ordinary source IP, not this transaction data. A malicious
provider can store received data outside the reference software; the protocol
cannot cryptographically prevent that behavior.

On-chain, the carrier input and successor, DGB fee inputs, change, and later
spends remain publicly analyzable. A long-lived Paymaster ID and stable onion
endpoint are pseudonyms, not proofs of anonymity. The precise protection goal
is therefore:

Non-custodial, permissionless, strongly pseudonymizable operation with
minimized disclosure and storage, but no promise of complete anonymity or
unlinkability.

15. Why No Consensus Change Is Required

The following remain unchanged:

• DD_TX_TRANSFER and its version value,
• the existing OP_RETURN metadata format,
• Taproot key-path signatures,
• the 1 DD minimum per DD output,
• the 100,000 DD maximum per DD output,
• exact DD conservation,
• the requirement for confirmed DD inputs,
• normal DGB input, output, and fee rules,
• block and mempool validation of the final transaction.

The paymaster function changes only:

• who supplies individual inputs that are already valid,
• how wallets jointly construct a complete transaction,
• how partial signatures are transported,
• how voluntary providers are discovered, verified, and presented.

New P2P messages, wallet database states, builder, PSBT, RPC, and Qt functions
are not consensus-critical. Recipients, miners, and ordinary validators check
only the final standard transaction and need no Paymaster upgrade. P2P nodes,
however, must be upgraded to understand or relay the new announcements and
direct protocol messages. The boundary would be crossed only if provider
IDs, special admission rules, or fee exemptions became part of transaction or
block validity. Such changes are explicitly outside the scope of this
proposal.

16. Test Strategy

Phase 0: Mandatory Regtest Proof of Feasibility

Three separate wallets:

Alice:     confirmed DD, no DGB
Paymaster: at least 3 confirmed DD carriers + separate DGB UTXOs
Bob:       DD recipient

The test creates a transaction with Alice's DD, a paymaster carrier, and
paymaster DGB, combines both partial signatures, runs testmempoolaccept,
mines the transaction, and verifies all wallet states after a restart.

Unit and Wallet Tests

• percentage calculation, including the 1 DD × 0.5% → 0.01 DD rounding
  case, overflow, and the local fee cap,
• SPONSORED enforces exactly fee_rate_bps = 0, a zero DD fee, and no
  provider DD output regardless of external sponsor metadata,
• the service descriptor and sponsorship capability are bound to the chain,
  provider, policy, recipient, amount, request nonce, and expiration; replay,
  manipulation, and plaintext persistence are rejected,
• DD conservation and minimum outputs, including user change,
• exactly one recipient per V1 session and rejection of redundant or
  contradictory amount fields,
• the 100-cent minimum and 10,000,000-cent maximum for recipients, carrier
  successors, ordinary provider fees, user change, and recovery outputs;
  carrier overflow and deterministic splitting of large recovery amounts,
• every DD and DGB change destination comes from a fresh internal keypool
  entry; all fallbacks in the same session retain the bound destinations,
• log-capture tests prove that recipients, amounts, outpoints, intents,
  capabilities, TXIDs, PSBTs, and raw transactions appear in no Paymaster
  production log,
• carrier 100 → 101...199 cents,
• a fee of at least 100 cents without a carrier,
• inputs belonging to another party remain unsigned,
• manipulated prevouts, roles, amounts, and scripts,
• canonical PSBT normalization, individually finalized user inputs,
  unfinalized provider inputs, disallowed fields, and modified prevouts, roles,
  or sighash types; before durable commit only a provider witness that was
  never stored may vary, while afterward witness and raw transaction must be
  exactly identical,
• quote signature, domain, chain, nonce, sequence, and expiration,
• three genuine, disjoint admission slots, complete separation from the
  operational pool, and exactly one disclosed operational candidate slot,
• duplicate UTXOs in one or more provider snapshots,
• atomic provider-slot reservation under concurrent quotes and restart
  recovery,
• a PaymentSession with multiple append-only ProviderAttempt records and
  immutable artifacts once set; quote expiration after a user signature does
  not release the user inputs,
• recovery actions are idempotent by request_id; cancel_to_self uses the
  exact bound input set and a fresh internal DD destination, and an RPC retry
  creates no second conflict variant,
• the atomic ProviderCommitRecord survives crashes before and after
  broadcast; retry_same always returns the same raw transaction and TXID and
  reserves neither a second slot nor creates a second quote,
• a crash after PSBT receipt and before final commit resumes through
  retransmission of the exact client-persisted user-signed PSBT; changed hashes,
  templates, signatures, fields, or provider slots are rejected,
• sponsorship-capability replay, restart without a plaintext capability, and
  the atomic transition of the secret-free record from RESERVED to
  CONSUMED,
• state-dependent reduction of completed sessions removes provider-attempt
  payloads while retaining the minimal idempotency tombstone and continuing to
  prevent a second payment for the same request_id,
• idempotent outcome recording exactly once per ProviderAttempt, a neutral
  availability-timeout class, 30-day buckets, aging, and a short cooldown for
  local provider reputation,
• operator policy rejects a missing, non-positive, or exceeded absolute DGB
  network-fee cap,
• mode and option validation, the hard fee cap, and idempotent request_id
  handling, including rejection when an ID is reused with a changed payment
  request,
• UUID format and a canonical request hash from typed values; equivalent amount
  representations produce the same hash,
• unknown or contradictory options, the effective minimum of the request and
  wallet fee caps, and an immutable session cap,
• encrypted descriptor wallet and rejected watch-only wallet.

Functional and P2P Tests

• two competing paymasters and correct cost sorting,
• directory synchronization directly contacts no provider and publishes only
  admission outpoints; only the selected candidate receives an isolated
  session and discloses at most one operational slot,
• public community sponsorship sorts ahead of an eligible user-paid offer with
  a 0 DD user fee; manual Qt selection and the headless request allowlist remain
  authoritative,
• restricted sponsorship appears only through the concrete signed payment
  request; it is not gossiped, and a pinned sponsor is not replaced without
  explicit fallback authorization,
• a pure zero-fee sponsor is automatically usable with three DGB-only admission
  slots, while USER_PAID is ineligible without three admission carriers;
  both require a disjoint operational slot for a quote,
• paymaster without a provider ID selects the lowest exactly rounded eligible
  total cost, not merely the lowest rate,
• privacy_weighted uses a controlled test RNG and selects only within the
  authorized cent tolerance; tolerance 0 is equivalent to
  lowest_total_cost,
• high privacy rejects clearnet, P2P v1, disabled proxy isolation, -logips,
  -capturemessages, fallback, and more than one attempt; standard clearnet
  requires successful P2P v2,
• auto remains on the direct path when the DGB fee can be fully funded and
  switches only on INSUFFICIENT_DGB_FEE_INPUTS under the current wallet safety
  policy; other errors, or signing or commit already having started, do not
  trigger fallback,
• cheapest provider offline, with safe fallback using the same user inputs,
• a silent provider after the user signature leaves the session in
  PENDING_PROVIDER; refresh, same-input fallback, and cancel_to_self
  produce the specified state transitions while mere local release is rejected,
• all internal pending phases survive restarts and correctly select status
  reconciliation, exact rebroadcast, or a new same-input variant,
• the local recovery preflight identifies constructible fallback candidates
  and self-funded recovery without provider contact; its result remains marked
  as a non-binding snapshot,
• competing original, fallback, and cancellation variants confirm at most one
  spend; cancellation mempool acceptance remains non-final before confirmation
  and is reconciled again after eviction or reorganization,
• explicit transitions for stempool, mempool, eviction, reorganization,
  payment conflict, and self-recovery; CONFIRMED applies only to the confirmed
  payment and CANCELED_SAFE only to confirmed self-recovery,
• every fallback variant is rebuilt, analyzed, and signed again; earlier
  provider attempts remain until final safety resolution,
• a pinned provider, explicit fallback authorization, and a bounded number of
  sequential attempts,
• every quote fee above or below the fee calculated exactly from the selected,
  signed PaymasterOfferTerms, and any price, slot, or chain-state change, is
  detected before the user signs,
• a lost RPC response and sequential or concurrent retries with the same
  request_id create neither a second payment nor a duplicate provider-attempt
  reservation for either auto → dgb or auto → paymaster,
• a crash before or after CommitTransaction() recovers the same persisted raw
  transaction; a resumed auto request does not switch its fixed fee branch
  when the balance has changed,
• deterministic crash injection before PSBT receipt, after receipt but before
  UserAuthorizationRecord, after that record but before ProviderCommitRecord,
  after final commit but before broadcast, and after broadcast but before
  PMRESULT; every stage resumes only the same attempt and can confirm at most
  the same transaction variant,
• PMRESULT signature, monotonic result_sequence, mandatory final raw
  transaction from FINAL_COMMITTED, and proof that provider status does not
  substitute for a local pool or chain observation,
• a carrier that is double-reserved or has since been spent,
• a quote expires before or after the user signs,
• mempool rejection, conflict, reorganization, and abandonment,
• provider broadcast uses the existing Dandelion-capable
  BroadcastTransaction path,
• readiness rejects -prune!=0, missing txindex, and incomplete DD transaction
  data; general pruned support remains outside V1,
• mixed old and upgraded relay nodes: old nodes ignore the new commands,
  upgraded nodes relay announcements, and only the sequentially selected
  provider receives payment data,
• malformed, oversized, replayed, and signature-invalid paymaster messages,
• rate limits and cache eviction,
• fuzzing of all announcement, capacity, quote, and PSBT parsers.

Qt Tests

• no DGB available → paymaster suggestion,
• manual selection remains the Qt default; automatic selection activates only
  after an explicit choice,
• “Paymaster” can automatically choose the lowest-cost eligible provider even
  when DGB is available, while “Auto” falls back only when the DGB fee cannot
  be funded,
• no verified admission reserve → no misleading display; operational capacity
  is claimed only after concrete reservation,
• exact rounded fee, effective rate, and total charge,
• sponsored offers display sponsor, scope, policy, and exactly 0 DD user fee;
  restricted offers disappear when the payment request expires,
• success rate only after a sufficient local sample; active cooldowns are
  displayed unambiguously,
• quote changes or expires while the dialog is open,
• a provider or price change is reconfirmed or was expressly pre-authorized
  with a visible fee cap and attempt count,
• privacy profile, random selection, additional-fee limit, and disclosure to
  another provider are displayed unambiguously,
• asynchronous session signals update pending, success, and failure state
  without blocking the GUI thread,
• PENDING_PROVIDER displays all three recovery actions, distinguishes wallet
  reservation, mempool, and confirmation, and warns that the original variant
  may still confirm,
• before the first signature, Qt displays fallback candidates and self-funded
  recovery as a non-binding preflight; the action is labeled "Attempt
  recovery to own wallet,"
• relocking before signing enters AWAITING_WALLET_UNLOCK; canceling the unlock
  remains neutral and creates no new session,
• start remains disabled for a locked, watch-only, or unready wallet,
• readiness errors for carriers, DGB, the absolute DGB fee cap, -prune=0,
  -txindex=1, complete DD data, synchronization, and endpoint are shown
  clearly,
• pool preview and user confirmation occur before every UTXO repartitioning,
• switching between wallets cannot execute an action in the wrong wallet,
• no network access on the GUI thread.

CLI and Qt Parity Tests

• every state transition available in the operator area can also be performed
  using RPC alone,
• existing senddigidollar calls with up to five parameters retain the direct
  DGB path; the sixth options object works both positionally and with named
  CLI arguments,
• complete JSON conversion for senddigidollar/options,
  getdigidollarsendsession/lookup, resolvepaymastersession/lookup and
  /options, getpaymasteroffers/amount_cents, setpaymasterpolicy, both pool
  RPCs, and requestpaymasterquote/intent,
• Qt, CLI, and third-party callers receive the same filtered selection and
  result fields for the same request,
• auto → dgb and auto → paymaster return the same session and idempotency
  fields; session_state, optional pending_phase, final,
  broadcast_state, confirmation_state, final failed, and an optional TXID
  are unambiguous,
• a locked wallet triggers no Paymaster fallback; RPC returns
  AWAITING_WALLET_UNLOCK, Qt requests an unlock, and both resume the same
  session afterward,
• retrying an already successful session returns the same TXID even when the
  wallet has since been locked; session lookup accepts exactly one session_id
  or request_id,
• identical validation and readiness errors for Qt and CLI,
• configuration, pool reservations, and operating state survive Qt and node
  restarts,
• complete headless end-to-end test from identity and pool setup through a
  confirmed user payment,
• confidential CLI arguments can be supplied through -stdin instead of a
  process argument or shell history,
• stoppaymaster stops accepting new quotes in a controlled manner without
  leaving existing signed transactions or reservations inconsistent.

17. Implementation Steps

1. Regtest PoC: multi-wallet DD PSBT with a carrier and DGB sponsor.
2. Deterministic builder: explicit outputs, fresh DD/DGB change, verified
   prevouts, and complete reduction of sensitive logs.
3. Selective signing: DD-capable PSBT and analysis path.
4. Reservation manager: persistent user, carrier, and DGB locks, pending
   subphases, and recovery preflight.
5. Manually configured provider: RPC-based end-to-end MVP with atomic
   provider commit, UserAuthorizationRecord, and idempotent PSBT
   retransmission through retry_same.
6. Provider identity and admission proof: at least three dedicated
   admission slots that are never used operationally.
7. P2P discovery and direct quote session: gossip only for announcements;
   at most one operational slot disclosed to the selected client.
8. Sponsorship policy: public zero-fee offers and signed, payment-bound
   service descriptors for restricted merchant and application sponsors.
9. CLI and Qt integration: complete operator RPCs, an idempotent high-level
   send call with automatic selection, an optional Qt operator area, security
   filters, cost comparison, and confirmation.
10. Privacy hardening: onion/P2P-v2 policy, stream isolation, capture
    guards, privacy selection, and state-dependent data reduction.
11. Hardening: fuzzing, DoS, privacy, restart, and reorganization tests.

This sequence proves the builder and signing mechanisms before expanding the
public P2P attack surface.

18. V1 Acceptance Criteria

V1 is considered successful when:

1. A user without DGB can execute a confirmed DD payment.
2. No private key or seed is transferred between the parties.
3. A paymaster is displayed automatically only after proving at least three
   disjoint, confirmed DGB admission slots; every user-paid offer additionally
   proves at least three admission carriers, and operational payment outpoints
   never appear in global gossip.
4. A fee between 0.01 and 0.99 DD can be accounted for in a valid transaction
   using a carrier.
5. The percentage fee and total charge are calculated and sorted correctly
   locally.
6. The user and provider wallets sign only their own inputs.
7. Within a given ProviderAttempt, any change to the recipient, amount,
   change, fee, or inputs after its user signature causes rejection. A fallback
   keeps the recipient, recipient amount, and user input set unchanged;
   provider-dependent components may change only in a new, fully verified and
   newly signed attempt.
8. Provider failure causes at most a controlled fallback, but no duplicate
   confirmed payment.
9. Existing nodes can validate the resulting transaction without an upgrade.
10. No change to consensus parameters, script rules, or DD validation is
    required.
11. Provider reputation is stored only locally, does not penalize neutral
    failures, and never replaces security or liquidity verification.
12. An unattended call can select the lowest-cost usable paymaster through a
    persistent Core session, enforce a hard DD fee cap, and avoid creating a
    second payment when the same request_id is retried.
13. Existing senddigidollar calls without options continue to use the
    wallet's own DGB fee path unchanged.
14. Public and restricted sponsorship use the same transaction protocol,
    charge the user exactly 0 DD service fee, and require no user balance at the
    Paymaster.
15. Restricted sponsorship authorizations are neither gossiped nor persisted
    in plaintext and are cryptographically bound to the concrete payment.
16. DD and DGB change are created from fresh internal destinations and no
    payment details are written to production logs.
17. The high-privacy profile has Core enforce onion-only operation, Tor stream
    isolation, exactly one provider attempt, and no clearnet/P2P-v1 fallback.
18. Only the selected provider receives the unavoidable payment intent and
    discloses at most one operational slot exclusively to that client; the fee
    cap and privacy tolerance remain local.
19. Completed sessions reduce provider-related detail after the safety period
    without losing idempotency or duplicate-payment protection.
20. Documentation and UI explicitly distinguish pseudonymity from
    non-guaranteed anonymity.
21. A session that becomes ambiguous after the user signature offers safe,
    idempotent recovery through another check, same-input fallback, or a
    same-input return to the user's wallet; timeout never releases the inputs,
    and a cancellation variant is treated as final only after a confirmed
    spend.
22. The provider can durably commit the final transaction before broadcast and
    restore it exactly on retry_same; pending subphases and the local
    constructibility preflight select the appropriate recovery after a crash or
    connection loss without contacting additional providers in advance.
23. A crash after receipt of the user signatures but before final commit is
    resumed by retransmitting the exact same persisted user-signed PSBT without
    creating a new quote, reservation, authorization, signature, transaction
    variant, or ProviderAttempt.
24. V1 accepts exactly one recipient per session, and every DD output—including
    a carrier successor, provider fee, change, and split recovery—is between
    100 and 10,000,000 cents.
25. Client and provider enforce -prune=0, -txindex=1, and complete DD
    transaction data as readiness requirements; recipients, miners, and normal
    validators need no Paymaster feature, while only upgraded P2P nodes relay
    Paymaster announcements.
26. PMRESULT is monotonic, signed, and from FINAL_COMMITTED bound to exactly
    one final raw transaction; the atomic wallet-database commit writes every
    record, outpoint, index, and any RESERVED → CONSUMED transition together
    before broadcast begins.
27. Pool acceptance never counts as final confirmation, CANCEL_MEMPOOL
    remains under PENDING_PROVIDER, and RPC/Qt expose identical finality
    through session_state, pending_phase, final, broadcast_state, and
    confirmation_state.
28. A locked wallet triggers no Paymaster fallback but pauses the same session
    in AWAITING_WALLET_UNLOCK, and operator policy enforces a positive
    absolute DGB network-fee cap.

[Shen]

Update: The proposal now includes a detailed local reputation system for Paymasters. Wallets track provider success rates, attributable failures, response latency, and temporary cooldowns locally. Neutral network or user-side failures do not affect a provider’s score, and no payment details or reputation data are shared publicly. Security and liquidity checks remain mandatory, while reputation is used only for local filtering and as a tie-breaker between equally priced offers.

[Shen]

Update 2: The proposal now clearly defines automatic paymaster selection for headless workflows while keeping manual selection as the default. It also specifies backward-compatible RPC options, fee caps, idempotent payment sessions, safe fallback handling, Qt/CLI parity, and crash recovery. Feedback is welcome!

[Shen]

Update 3: Improved Paymaster Privacy and Capacity Verification
The proposal has been updated with stronger privacy protections, minimized disclosure of wallet and transaction data, and a clearer two-stage capacity check. A Paymaster now proves control of only one candidate slot before receiving the payment intent; sufficient DGB funding is verified and atomically reserved only after the final transaction size is known.

[Shen]

WiP:
https://github.com/Shen/digibyte/tree/feature/digidollar-paymaster-v1