Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions docs/dashpay/DIP15_INVITATIONS_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Tracked as the "NEXT" item in the DashPay backlog (dashpay/platform#4020); calle
rejected as a *link* but the funded lock is recorded first and stays reclaimable.
3. **Amounts (amends §5/§8/§9):** `MIN_INVITATION_DUFFS = 300_000` (0.003 DASH — a smaller
voucher can fund neither a claim nor a register-reclaim, discovered by funded e2e),
`MAX_INVITATION_DUFFS = 5_000_000` (0.05 DASH), Swift default **0.03 DASH**.
`MAX_INVITATION_DUFFS = 26_000_000` (0.26 DASH), Swift default **0.03 DASH**.
4. **Persistence as-built (amends §4.2):** the `InvitationChangeSet` flows through
`PlatformWalletPersistence::store()` to each backend — the SQLite backend's
`V003__invitations` table, and on iOS the FFI `on_persist_invitations_fn` bridge into the
Expand Down Expand Up @@ -129,9 +129,10 @@ local guards are fast-fail UX + correct index selection, not theft prevention.

`MIN_INVITATION_DUFFS = 300_000` (0.003 DASH, == Android `DASH_PAY_INVITE_MIN`; a smaller
voucher can fund neither a claim nor a register-reclaim — found by funded e2e).
`MAX_INVITATION_DUFFS = 5_000_000` (0.05 DASH). Swift create default **0.03 DASH** = identity
+ a normal DPNS name (Android `DASH_PAY_FEE`). The contested-name tier (0.25) is **deferred**
until contested registration is wired into the claim flow.
`MAX_INVITATION_DUFFS = 26_000_000` (0.26 DASH). Swift create default **0.03 DASH** = identity
+ a normal DPNS name (Android `DASH_PAY_FEE`). The cap covers the contested/premium tier as
well (0.25, Android `DASH_PAY_FEE_CONTESTED`), with the remaining margin for the create/claim
fees; the claim path is amount-agnostic, so nothing further gates a contested-tier invite.

### 0A.5 Transport

Expand Down Expand Up @@ -605,7 +606,7 @@ The `data=` payload is a **bearer credential**: whoever reads the plaintext link
voucher and can claim (front-run) it. Because the app registers the `dashpay://` **custom URL
scheme**, any other app that also registers `dashpay` can intercept an invite link on the same
device and steal the claim. The load-bearing mitigation is therefore **economic, not transport**:
`MAX_INVITATION_DUFFS` caps the loss at 0.01 DASH, and the inviter can reclaim an unclaimed voucher
`MAX_INVITATION_DUFFS` caps the loss at 0.26 DASH, and the inviter can reclaim an unclaimed voucher
(best-effort race). The advisory expiry does **not** bound a leak (a leaked-link holder ignores it).

A hardened production transport would use **Universal Links** (HTTPS + a hosted
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ import androidx.compose.ui.unit.dp
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import org.dashfoundation.dashsdk.tokens.Dashpay
import org.dashfoundation.example.di.LocalAppContainer
import org.dashfoundation.example.di.LocalAppState
import org.dashfoundation.example.util.generateQrBitmap
Expand All @@ -45,8 +46,10 @@ import org.dashfoundation.example.util.toHex

/**
* Create-invitation sheet — port of `CreateInvitationSheet.swift`. Amount
* entry (default **0.03 DASH**, UI range mirror of the Rust-enforced
* 0.003–0.05) + the "send a contact request back to me" toggle (drives the
* entry (default **0.03 DASH**; the help copy renders the Rust-enforced
* bounds from [Dashpay.minInvitationDuffs] / [Dashpay.maxInvitationDuffs]
* rather than mirroring them) + the "send a contact request back to me"
* toggle (drives the
* optional inviter info; disabled without a DPNS username), then
* `dashpay.createInvitation` → QR + share + copy.
*
Expand Down Expand Up @@ -175,7 +178,8 @@ fun CreateInvitationSheet(
)
Text(
"Funds a one-time voucher your friend uses to register their identity " +
"and a username. Between 0.003 and 0.05 DASH.",
"and a username. Between ${bareDash(Dashpay.minInvitationDuffs)} " +
"and ${bareDash(Dashpay.maxInvitationDuffs)} DASH.",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Expand Down Expand Up @@ -313,3 +317,11 @@ private fun clearClipboardIfLabelMatches(context: Context, label: String): Boole
}
return true
}

/**
* duffs → a bare DASH decimal ("0.26", not "0.26000000" or "0,26") for the
* help copy — [java.math.BigDecimal]-backed like [parseDashToDuffs], so it
* is exact and locale-independent (the amount field parses "." input).
*/
private fun bareDash(duffs: Long): String =
java.math.BigDecimal(duffs).movePointLeft(8).stripTrailingZeros().toPlainString()
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,19 @@ internal object DashpayNative {
// be logged, persisted, or interpolated into an exception message on
// either side of this boundary.

/**
* Rust-enforced cap on an invitation voucher's amount, in duffs.
* ← Swift `ManagedPlatformWallet.maxInvitationDuffs`.
*/
external fun invitationMaxDuffs(): Long

/**
* Rust-enforced floor on an invitation voucher's amount, in duffs — a
* smaller voucher can fund neither a claim nor a reclaim.
* ← Swift `ManagedPlatformWallet.minInvitationDuffs`.
*/
external fun invitationMinDuffs(): Long

/**
* Decode a `dashpay://invite` link into a read-only preview — no
* wallet, no network, no side effects. Returns a JSON object:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -416,9 +416,9 @@ class Dashpay internal constructor(private val walletHandle: Long,
* ← Swift `ManagedPlatformWallet.createInvitation`
* (packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift).
*
* Amount bounds (`MIN_INVITATION_DUFFS = 300_000`,
* `MAX_INVITATION_DUFFS = 5_000_000`) are enforced in Rust — a voucher
* below the floor could fund neither a claim nor a reclaim.
* Amount bounds ([minInvitationDuffs], [maxInvitationDuffs]) are
* enforced in Rust — a voucher below the floor could fund neither a
* claim nor a reclaim.
*
* Pass a non-null [inviterIdentityId] (32 bytes) + [inviterUsername]
* to opt into the contact-bootstrap (the link then carries the
Expand Down Expand Up @@ -560,6 +560,25 @@ class Dashpay internal constructor(private val walletHandle: Long,
}
return out
}

companion object {
/**
* Upper bound, in duffs, on the amount an invitation voucher may
* lock — the Rust-enforced cap [createInvitation] rejects above.
* Read it rather than restating it: Rust owns the value, and a
* client-side copy diverges the moment the constant moves.
* ← Swift `ManagedPlatformWallet.maxInvitationDuffs`.
*/
val maxInvitationDuffs: Long get() = DashpayNative.invitationMaxDuffs()

/**
* Lower bound, in duffs, on the amount an invitation voucher may
* lock — the Rust-enforced floor [createInvitation] rejects below
* (a smaller voucher can fund neither a claim nor a reclaim).
* ← Swift `ManagedPlatformWallet.minInvitationDuffs`.
*/
val minInvitationDuffs: Long get() = DashpayNative.invitationMinDuffs()
}
}

/**
Expand Down
36 changes: 35 additions & 1 deletion packages/rs-platform-wallet-ffi/src/invitation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ use platform_wallet::wallet::identity::crypto::{
};
use rs_sdk_ffi::{MnemonicResolverCoreSigner, MnemonicResolverHandle, SignerHandle, VTableSigner};

use platform_wallet::wallet::identity::network::MAX_INVITATION_TTL_SECS;
use platform_wallet::wallet::identity::network::{
MAX_INVITATION_DUFFS, MAX_INVITATION_TTL_SECS, MIN_INVITATION_DUFFS,
};

use crate::core_wallet_types::OutPointFFI;
use crate::dashpay::resolver_contact_crypto_provider;
Expand All @@ -44,6 +46,28 @@ use crate::identity_registration_with_signer::{decode_identity_pubkeys, Identity
use crate::runtime::block_on_worker;
use crate::{check_ptr, unwrap_option_or_return, unwrap_result_or_return};

/// The maximum amount (duffs) an invitation voucher may lock.
///
/// The cap is enforced Rust-side by [`platform_wallet_create_invitation`] — it
/// bounds the blast radius of a leaked bearer link. Clients read it through
/// this getter to pre-validate and label the amount field; mirroring the value
/// client-side lets the UI reject amounts Rust accepts the moment the constant
/// moves.
#[no_mangle]
pub extern "C" fn platform_wallet_invitation_max_duffs() -> u64 {
MAX_INVITATION_DUFFS
}

/// The minimum amount (duffs) an invitation voucher may lock.
///
/// A voucher below this floor can fund neither a claim nor a register-reclaim,
/// so [`platform_wallet_create_invitation`] rejects it Rust-side. Read through
/// this getter for the same reason as the cap: no client-side mirror to drift.
#[no_mangle]
pub extern "C" fn platform_wallet_invitation_min_duffs() -> u64 {
MIN_INVITATION_DUFFS
}

/// Create a DashPay invitation: fund a one-time asset-lock voucher at the
/// DIP-13 invitation path and return a shareable `dashpay://invite` link.
///
Expand Down Expand Up @@ -793,4 +817,14 @@ mod tests {
assert!(!preview.structurally_valid);
assert!(preview.inviter_username.is_null());
}

/// The amount-bound getters hand back the library constants verbatim. This
/// bridge exists precisely so clients stop mirroring the values, so a drift
/// here would silently reinstate the mirror it replaced.
#[test]
fn invitation_amount_bound_getters_match_library_constants() {
assert_eq!(platform_wallet_invitation_max_duffs(), MAX_INVITATION_DUFFS);
assert_eq!(platform_wallet_invitation_min_duffs(), MIN_INVITATION_DUFFS);
assert!(platform_wallet_invitation_min_duffs() < platform_wallet_invitation_max_duffs());
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -45,15 +45,19 @@ use crate::wallet::identity::network::contact_requests::ContactCryptoProvider;

use super::*;

/// Hard cap on the amount an invitation can lock (0.05 DASH). The voucher is a
/// Hard cap on the amount an invitation can lock (0.26 DASH). The voucher is a
/// bearer credential, so the blast radius of a leaked link is bounded here in
/// Rust — not just in the UI. Sized for onboarding: the invitee spends the
/// voucher on identity creation **plus** a normal DPNS name (~0.03 DASH — the
/// legacy `DASH_PAY_FEE`), so the previous 0.01 cap was actually below a usable
/// invitation and rejected its own onboarding default. The contested/premium-name
/// tier (~0.25 DASH) is deferred until contested-name-via-invite claim exists;
/// raise this cap when it does.
pub const MAX_INVITATION_DUFFS: u64 = 5_000_000;
/// Rust — not just in the UI. Sized for onboarding at BOTH username tiers: the
/// invitee spends the voucher on identity creation **plus** a DPNS name — a
/// normal name (~0.03 DASH, the legacy `DASH_PAY_FEE`) or a contested/premium
/// name (~0.25 DASH, `DASH_PAY_FEE_CONTESTED`), with the 0.01 margin covering
/// the create/claim fees. The earlier 0.05 value deferred the contested tier
/// "until contested-name-via-invite claim exists" — the claim path is
/// amount-agnostic and contested-invite claims are verified working, and the
/// Android wallet has funded contested invitations at 0.25 since 2024, so the
/// deferral is over. (The pre-merge 0.01 iteration was below even a usable
/// non-contested invitation and rejected its own onboarding default.)
pub const MAX_INVITATION_DUFFS: u64 = 26_000_000;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Update clients that still mirror the old invitation cap

This change makes the repository's explicit cap mirrors inconsistent with the Rust source of truth. packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/DashPay/CreateInvitationSheet.swift still defines maxInvitationDuffs as 5_000_000, and its amount parser rejects larger values, so that bundled client cannot create a 0.25 DASH contested invitation even though the corrected Rust API accepts it. The associated Swift text, Kotlin KDoc and example guidance, Info.plist, and docs/dashpay/DIP15_INVITATIONS_SPEC.md also still advertise the old 0.05 DASH limit. Update these mirrors to 26,000,000 duffs so the client behavior and documentation match the newly raised cap.

source: ['codex']

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Add a regression test for the contested invitation amount

No test independently exercises the amount-cap branch or references MAX_INVITATION_DUFFS, so reverting this constant to 5,000,000 would reproduce the reported regression while leaving the existing suite green. Extend the durability-gate harness with independently stated boundaries: 25,000,000 duffs should pass amount validation and reach the expected persistence-capability error, while MAX_INVITATION_DUFFS + 1 should fail immediately with InvalidIdentityData. This directly pins both the contested tier and the upper-bound rejection without broadcasting funds.

source: ['codex']


/// Floor on the amount an invitation can lock (0.003 DASH). A voucher funds a
/// Platform identity operation, and creating an identity — which is what the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,9 @@ mod contact_requests;
mod contacts;
mod dashpay_view;
mod invitation;
pub use invitation::{Invitation, MAX_INVITATION_DUFFS, MAX_INVITATION_TTL_SECS};
pub use invitation::{
Invitation, MAX_INVITATION_DUFFS, MAX_INVITATION_TTL_SECS, MIN_INVITATION_DUFFS,
};
mod payment_handler;
pub(crate) use payment_handler::DashPayPaymentHandler;
// Re-exported for the payments unit tests, which drive the hooks
Expand Down
24 changes: 24 additions & 0 deletions packages/rs-unified-sdk-jni/src/dashpay.rs
Original file line number Diff line number Diff line change
Expand Up @@ -903,6 +903,30 @@ pub extern "system" fn Java_org_dashfoundation_dashsdk_ffi_DashpayNative_sendCon
// interpolated into a thrown exception message, log line, or debug output —
// error text names the argument, never its value.

/// Rust-enforced cap on the amount an invitation voucher may lock, in
/// duffs (bridges `platform_wallet_invitation_max_duffs`). Clients read
/// the bound through this getter to pre-validate and label the amount
/// field — a client-side copy diverges the moment the constant moves.
#[no_mangle]
pub extern "system" fn Java_org_dashfoundation_dashsdk_ffi_DashpayNative_invitationMaxDuffs(
_env: JNIEnv,
_class: JClass,
) -> jlong {
platform_wallet_ffi::platform_wallet_invitation_max_duffs() as jlong
}

/// Rust-enforced floor on the amount an invitation voucher may lock, in
/// duffs (bridges `platform_wallet_invitation_min_duffs`) — a smaller
/// voucher can fund neither a claim nor a reclaim. Read through this
/// getter for the same reason as the cap: no client-side mirror to drift.
#[no_mangle]
pub extern "system" fn Java_org_dashfoundation_dashsdk_ffi_DashpayNative_invitationMinDuffs(
_env: JNIEnv,
_class: JClass,
) -> jlong {
platform_wallet_ffi::platform_wallet_invitation_min_duffs() as jlong
}

/// Decode a `dashpay://invite` link into a read-only preview (bridges
/// `platform_wallet_parse_invitation` — no wallet handle, no network, no
/// side effects). Returns a compact JSON object:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2029,6 +2029,22 @@ extension ManagedPlatformWallet {

// MARK: - DashPay invitations (DIP-13)

/// Upper bound, in duffs, on the amount an invitation voucher may lock —
/// the Rust-enforced cap `createInvitation` rejects above. Read it rather
/// than restating it: Rust owns the value, and a client-side copy diverges
/// the moment the constant moves.
public static var maxInvitationDuffs: UInt64 {
platform_wallet_invitation_max_duffs()
}

/// Lower bound, in duffs, on the amount an invitation voucher may lock —
/// the Rust-enforced floor `createInvitation` rejects below (a smaller
/// voucher can fund neither a claim nor a reclaim). Read it rather than
/// restating it, for the same reason as the cap.
public static var minInvitationDuffs: UInt64 {
platform_wallet_invitation_min_duffs()
}

/// Read-only preview of a `dashpay://invite` link, decoded via
/// `parseInvitation(uri:)` without claiming it. Drives the claim sheet's
/// pre-claim summary + the contact-bootstrap decision.
Expand Down
2 changes: 1 addition & 1 deletion packages/swift-sdk/SwiftExampleApp/Info.plist
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
one-time bearer voucher key, and iOS does NOT grant a custom URL scheme
exclusive ownership — a co-installed app registering "dashpay" could
intercept the link and steal the voucher (blast radius capped by the
Rust-side MAX_INVITATION_DUFFS = 0.05 DASH). The safer transport is the
Rust-side MAX_INVITATION_DUFFS = 0.26 DASH). The safer transport is the
HTTPS universal link (invitations.dashpay.io/applink, already parsed by
the codec), which requires an AASA-verified domain. Adopting it is tracked
for the infra team in dashpay/platform#4096; until then this example app
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,6 @@
- **Step 3–4 (top-up)** the sheet states value returns as credits, never L1 Dash; on success the target identity's credit balance rises by ~the voucher value and the row badge flips to **Reclaimed** (`ZSTATUSRAW=2`). No L1 Dash is returned (the on-chain amount was an `OP_RETURN` burn at create time).
- **Step 5 (register)** a brand-new funded identity lands in Identities and the row flips to **Reclaimed** (`ZSTATUSRAW=2`); no contact request is sent (a reclaim carries no DashPay enc/dec pair).
- **Step 6 (already-consumed)** the terminal decision is the pure, unit-tested `classifyReclaimFailure(error:hadPriorReclaimInFlight:)` seam, split by the persisted `reclaimInFlight` marker (set — with a **required, successful** save — only immediately before the on-chain consume; a failed marker save aborts the reclaim before anything irreversible). A retained local tombstone or Platform rejection maps to typed `AssetLockAlreadyConsumed`: marker **unset** ⇒ the invitee claimed first ⇒ **neutral** "This invitation was already claimed." (claimant **not** named) ⇒ row → **Claimed** (`ZSTATUSRAW=1`); marker **set** ⇒ **explicitly ambiguous** — the consumer could be our own interrupted attempt OR a racing claim, so the row resolves to the conservative terminal **Claimed** (`ZSTATUSRAW=1`, marker cleared) with the ambiguity message. `Reclaimed` (`ZSTATUSRAW=2`) is written **only** by a consume this attempt observed succeeding. A genuinely untracked or foreign-wallet failure remains a plain error and never flips the row. No funds are lost.
- **Step 7 (min guard)** creating below the minimum is blocked in-UI with "Minimum 0.003 DASH — a smaller voucher can't fund identity registration. Maximum 0.05 DASH."; the Rust layer independently rejects a sub-minimum amount (`MIN_INVITATION_DUFFS`), so the floor holds even if the UI guard is bypassed.
- **Step 7 (min guard)** creating below the minimum is blocked in-UI with "Minimum 0.003 DASH — a smaller voucher can't fund identity registration. Maximum 0.26 DASH."; the Rust layer independently rejects a sub-minimum amount (`MIN_INVITATION_DUFFS`), so the floor holds even if the UI guard is bypassed.

Fail the QA if: a reclaim returns L1 Dash instead of credits; a failed or non-consumed reclaim flips the row status (a non-consumed error must leave it `Created`); the already-consumed path names the claimant or shows a raw error instead of the neutral message; or an invitation below `0.003` DASH can be created.
Loading
Loading