Issue being fixed or feature implemented

Dash Core's opt-in Platform GUI (DashPay) links dash-sdk-cxx. Five gaps in the binding block it:

• Quorum lookups are two-state. CoreContext::QuorumPublicKey returns a bool, and the binding reads every miss as InvalidQuorum: the proof is bad, and the evonode that sent it is banned. A node that is behind, or that misses commitment data, cannot say "I can't decide yet", so honest evonodes get banned for the embedder's gap.
• Identity funding has no ChainLock-height retry. register_identity and top_up_identity call the plain SDK put and top-up. A ChainLock proof that races Platform's Core height fails with 10506. Resubmitting the same bytes never reaches CheckTx again: the node that refused them keeps their hash, with no time limit. The SDK's retry, submit_with_cl_height_retry, has no fee cap, reports nothing about the attempts it made, and offers no way out once the fee steps are used up.
• Funding failures carry no outcome. A raw 10504 looks the same as the SDK's outpoint-matched "already consumed" report, and Core has no way to derive the identity id it would need to authenticate a registration.
• A top-up's success proves nothing about its lock. The top-up waits with broadcast_and_wait_for_affected_state, which accepts a verified snapshot of the identity's balance and revision.
  • Drive marks IdentityTopUp as not execution-bound, so a valid snapshot of an unchanged balance verifies for a top-up that never ran.
  • A balance change doesn't bind the lock either, since other credits and debits move the same balance.
  • Core has no proved way to tell whether the asset lock it funded was spent.
• register_dpns_name(contest_fund = 0) let the SDK price a contest just before the domain is sent. A contested label could pay more than the user confirmed, and a refusal after the preorder still costs fees.

The policy for funding, settlement and the DPNS contest belongs in the shared SDK, so it lives in rs-sdk as ordinary Rust APIs. The binding only runs them and converts their results.

What was done?

SDK (rs-sdk)

DPNS contest policy:

• New DpnsContestPolicy { Refuse, Cap(credits) } and Sdk::register_dpns_name_under_policy. The policy is applied to the domain the registration itself builds, against the DPNS contract it builds it with. This happens before a pending preorder is looked for, deleted or replaced, so a refused name costs no fee.

  • Refuse returns the new Error::DpnsNameContested when either check finds a contest:

    • is_contested_username names the label contested (DpnsContestPolicy::check_label, before anything is read);
    • the contract puts the domain under a contested index.

    Otherwise it states a contest fund of 0.

  • Cap states its cap, 0 included.

  • The domain always names its fund. An input that states its own contest_fund is refused.

  • register_dpns_name and its contest_fund are unchanged.

• The contest resolution that prefunded_voting_balance_to_join already did moves into Sdk::contested_vote_poll, and both callers use it.

Asset-lock record:

• New Sdk::asset_lock_outpoint_state(out_point). It reads the outpoint's record in SpentAssetLockTransactions with a proof, through the existing getPathElements/KeysInPath fetch, and decodes it into StoredAssetLockInfo with Drive's new drive::util::common::asset_lock::stored_asset_lock_info (built under Drive's verify feature). That helper owns the record's format, and the asset-lock proof verifier now uses it too, each caller keeping its own value decoding; Drive's consensus fetch is unchanged, and a Drive test checks that it and the helper agree on absent, empty and partially consumed records written by Drive's own writer:
  • NotPresent: no transition has used the lock yet;
  • PartiallyConsumed, with the credits left: a failed transition used part of it;
  • FullyConsumed: final, because Drive never removes a record. It does not say which transition used the lock.
  • The invitation docs that said no endpoint surfaces this record now point at the helper.

Bounded funding and refused transitions:

• asset_lock_submission now documents how refused transitions behave ("Refused transitions"):
  • Tenderdash keeps the hash of every transition its CheckTx refused, with no time limit. The hash leaves a node only through cache eviction or a restart.
  • The 24 h ttl-duration covers admitted transactions only.
  • So a submission is the pair (proof, user_fee_increase), and no pair is sent twice.
  • Once a proof's fee steps are used up, the next proof is a ChainLock proof for the same outpoint at a height no earlier proof carried.
• New submit_funding_with_fee_floor(proof, floor, on_attempt, submit):
  • the 10506 retry, starting at the caller's floor;
  • never above MAX_FUNDING_FEE_INCREASE (100), and at most FUNDING_ATTEMPTS (15) builds;
  • it tells the caller each attempt's fee before the attempt is built;
  • a floor above the cap submits nothing (Error::FeeIncreaseFloorAboveCap).
• Failures come as FundingFailure { kind, error }, where the kind is a FundingFailureKind: NeedsChainLockProof, PlatformBehindCore, FeeCapReached, ReportedConsumed, Rejected, Unavailable or Submitted. funding_failure_kind gives the kind for any error. FundingFailure is a standard error type (Display is the SDK error's, and source() returns it), so ? propagates it with its kind intact; for a top-up whose lock record could not be read, the chain continues through Error::AssetLockNotUsedUp and UnsettledLockRecord::Unread to the read's own error.
• New next_chain_lock_proof(out_point, mined_height, last_chain_height, best_chain_locked_height): the next proof for a capped lock, at the mined height or one block above the last ChainLock proof sent, and no higher than the caller's verified ChainLock.
• submit_with_cl_height_retry shares the retry loop and keeps its behaviour, except that it no longer resends user_fee_increase = u16::MAX.
• New TopUpIdentity::top_up_identity_settled, for a signer top-up:
  • it runs the bounded submission, then settles only when asset_lock_outpoint_state shows the lock used up;
  • otherwise the outcome is Submitted, with Error::AssetLockNotUsedUp naming the record or the error that kept it unread;
  • the existing top_up_identity* methods are unchanged, and their docs now say the balance is the wait's snapshot.
• rs-platform-wallet's docs repeated the 24 h claim and are corrected. Its behaviour is unchanged.

Binding (rs-sdk-cxx)

• Quorum lookups. QuorumLookup { Found, Invalid, Unavailable } is defined in callbacks.h and declared to the bridge as an extern enum.
  • Invalid maps to InvalidQuorum: the proof is bad, and the node is banned.
  • Unavailable maps to QuorumSourceUnavailable, which bans no node.
  • A Found key that isn't 48 bytes, an unknown value, a throw and an empty callback all map to Unavailable.
  • The signed Core height, the single byte-order reversal and "no other quorum source" are unchanged.
• Identity funding. register_identity goes through submit_funding_with_fee_floor, and top_up_identity through top_up_identity_settled. Both take user_fee_increase_floor.
  • Each result carries a FundingReport.
    • last_user_fee_increase is the highest fee an attempt started with, as the SDK reported it before building that attempt. A call cut short by shutdown still reports it, and the next call with the same proof starts one above it.
    • FundingOutcome is the SDK's kind in the bridge's numbering:
      • Ok: settled, proved. A registration's strict proof shows the identity the lock creates. A top-up is Ok only when the lock's record reads FullyConsumed after its wait.
      • Submitted (new, top-up only): the snapshot verified, but the lock is not proved used up. There is no record yet, credits are left, or the record couldn't be read. Its status is Unavailable and its balance 0, so a caller that checks only the status never takes it for success. A failed record read keeps its own status (Rejected for a bad proof).
      • FeeCapReached (new): no fee step is left for this proof. Either the floor is above 100, so nothing was submitted, or the attempt at 100 still got 10506. Do not resend this proof at any step. Send a ChainLock proof for the same outpoint at a height it has not carried (the lock's mined height if no ChainLock proof was sent for it, otherwise one above the last; at most the embedder's best ChainLock), from floor 0. PlatformBehindCore now always means a step at or below the cap is left.
      • NeedsChainLockProof: a stale or oversized InstantSend proof.
      • ReportedConsumed: only the SDK's outpoint-matched helper reports it, and it authenticates nothing.
      • Rejected: any other consensus error, a raw 10504 included.
      • Unavailable.
  • A top-up's balance is the wait's snapshot, which need not include this top-up. Ok proves the lock is used up, but the record names no transition, so it does not prove that this identity was credited.
• Asset lock state. asset_lock_state(txid, vout) returns that record (NotPresent, PartiallyConsumed with remaining_credits, or FullyConsumed). Core can then settle a submitted or reported lock, or classify locks it rediscovers after a restore, without resubmitting.
• Identity id. identity_id_from_asset_lock_outpoint(txid, vout) exports dpp's identity-id derivation.
• DPNS contest policy. register_dpns_name takes a ContestPolicy and passes it to register_dpns_name_under_policy.
  • Refuse returns the new StatusKind::Contested before any preorder, delete or domain write.
  • A label refused by its spelling is refused before the identity is even read.
  • The SDK is never left to price the contest.
• ECDH. The ECDH secret buffer the binding owns is zeroized.

How Has This Been Tested?

Linux x86_64, Rust 1.98.1, protoc 32.0 (the CI pins), at b50067d, which this head extends only by the FeeCapReached doc comment, a cfg on a helper and the legacy-retry test below:

• cargo fmt --check --all
• cargo clippy -p dash-sdk-cxx -p dash-sdk --all-targets --all-features --locked -- --no-deps -D warnings
• cargo check -p wasm-sdk --locked: its From<dash_sdk::Error> match is exhaustive and covers the new variants.
• cargo nextest run -p dash-sdk-cxx --all-features --locked: 21 passed.
• cargo nextest run -p dash-sdk --all-features --locked -E 'test(~dpns_usernames) or test(~contest_fund) or test(~asset_lock_submission) or test(~put_identity) or test(~top_up) or test(~invitation)': 148 passed.
• packages/rs-sdk-cxx/scripts/cxx-smoke.sh: covers the C++ side of every mapping. That includes a malformed Found, a throw, an empty callback and an out-of-range answer, Refuse of a contested label with no network, and a floor above the cap reaching no signer.
• cargo machete and the dash-sdk-cxx trust-closure check.
• Each of the first three commits builds and passes on its own: clippy -D warnings, wasm-sdk check, and its own tests.

At this head: cargo fmt --check --all; cargo check -p dash-sdk with default features and with core_key_wallet (no warnings); cargo clippy -p dash-sdk --all-targets --all-features --locked -- --no-deps -D warnings; cargo check of dash-sdk-cxx --all-targets, wasm-sdk, and drive --no-default-features --features verify (as rs-sdk builds it); cargo test -p dash-sdk --lib asset_lock_submission (23 passed, including the record decoding through Drive's helper and FundingFailure propagating through ?); the helper's and the verifier's Drive tests (22 passed: one checking that the consensus fetch and the helper agree on absent, empty and partially consumed records, and one running both ShieldFromAssetLock verifier paths at protocol versions 13, 14 and the latest over empty, encoded, encoded-with-trailing-bytes and absent records); and drive-abci's ShieldFromAssetLock tests (36 passed), which cover both verifier arms that now use the helper.

Refused transitions (asset_lock_submission::refused_transition_tests). A fake network keeps every pair its CheckTx refused, keyed as Tenderdash keys its cache: by the SHA-256 of real top-up bytes, signed deterministically. It answers a held hash in two ways, as Tenderdash 1.8 does through DAPI (Internal) and as later releases do (the cached 10506). For each:

1. Platform is behind: proof height h is refused at every fee from 0 to 100, each pair reaching CheckTx once, and the calls end at FeeCapReached.
2. Platform catches up: the same proof never lands from floor 0, and no held pair reaches CheckTx.
3. The proof next_chain_lock_proof gives, at h+1, lands at its first attempt with fee 0.

A second test shows that the same pair signs the same bytes, while a new fee or a new height signs new ones. The retry loop already behaved this way, so this test pins the contract; it did not fail before the change.

Legacy retry bound (asset_lock_submission::tests::should_retry_past_the_funding_cap_and_stop_at_the_largest_fee). submit_with_cl_height_retry shares the loop but not the cap: from fee 150 it lands at 151, and from 65534 it sends 65534 and 65535 and then returns the 10506 instead of resending the bytes it signed at 65535.

Top-up regression (rs-sdk-cxx client::top_up_tests). It doesn't fabricate an SDK answer:

• A real Drive (setup_drive_with_initial_state_structure) holds an identity, and the SDK's own builder signs the top-up.
• The mock SDK's DAPI answers the broadcast, then the wait with Drive's prove_state_transition proof, then the getPathElements read with Drive's prove_elements proof.
• Both proofs are signed over the proof's root, as a quorum signs a precommit, and the SDK's real path verifies them against the test quorum's key.
• The test runs top_up_identity_settled and the binding's conversion:
  • Not executed: the SDK's plain top-up returns the unchanged balance, so the snapshot verifies. The settled top-up reports Submitted, and asset_lock_state reads NotPresent.
  • After a partial use, written with Drive's own AddUsedAssetLock: still Submitted, with PartiallyConsumed and the credits left.
  • After Drive's own top-up operations ran: Ok, with the new balance and FullyConsumed.
  • A record whose proof fails verification: Submitted, with the Rejected status.

DPNS (dpns_usernames::tests):

• Refuse rejects "Bob" without a single request.
• A 20-character label is ordinary by its spelling. Refuse lets it through to the pending-preorder query under the DPNS v3 the network stores, but refuses it before that query under a contract whose contested index covers it.
• Cap(0) and Cap(5 000 000) on a contested domain go straight to the nonce fetch and never read the contest's vote state.

Each new behaviour was checked to fail its tests when the code for it is reverted. 19 reversions were run:

• Bounded submission:
  • a floor above the cap submitting;
  • no stop at the cap;
  • a 10506 at the cap read as Platform behind;
  • an attempt's fee not reported before the attempt is built;
  • a raw consensus refusal read as Unavailable.
• Legacy retry: given the funding cap as its limit; resending at u16::MAX.
• Proof renewal:
  • the next proof reusing the last height (the old contract), which also fails the refused-transition test;
  • a height past the caller's ChainLock.
• Settlement: an unread record, a partially used lock, or a top-up that never reads its record settling the lock.
• DPNS:
  • Refuse skipping the label check or the contract check;
  • Cap leaving the fund to the SDK.
• Binding:
  • FeeCapReached read as PlatformBehindCore;
  • an unread record's status flattened;
  • the label checked only after the identity is read;
  • an attempt's fee not recorded.

The reversions from earlier review rounds that touch unchanged code (the quorum-callback mappings, the record decoding, the InstantSend fallback, outpoint matching) still apply.

Dash Core's contrib/devtools/platform-bundle.sh was run twice on this head and gave identical archives, which build with cargo --frozen --offline.

Earlier heads of this PR were also exercised:

• Dash Core's depends recipe (build: build the Dash Platform CXX bindings in depends behind PLATFORM_GUI=1 dash#7623) built the staticlib for each host it supports, and every entry point linked.
• Read-only live testnet runs checked asset_lock_state over 1061 outpoints and the quorum callback's three answers.

Neither the bridged functions nor their native-library needs changed since; only the bridge's doc comments did.

Not yet exercised live, and left to Dash Core's end-to-end run once this PR is merged and pinned:

• every write: identity registration, top-up (including Submitted settling through asset_lock_state), username registration and the contest policy, and contact requests;
• a capped lock renewed with the next ChainLock proof on a live network;
• Dash Core's real quorum lookup behind the callback.

Breaking Changes

Nothing here changes consensus, so the title has no !, which the coding conventions reserve for consensus-breaking changes.

The C++ API of dash-sdk-cxx changes:

• CoreContext::QuorumPublicKeyFn and CoreContext::QuorumPublicKey return QuorumLookup instead of bool.
• register_identity and top_up_identity:
  • take user_fee_increase_floor;
  • return RegisterIdentityResult / TopUpIdentityResult;
  • BalanceResult is removed.
• register_dpns_name takes const ContestPolicy& instead of contest_fund.
• New StatusKind::Contested = 6.
• FundingOutcome::Ok for a top-up now requires the lock's record to show it used up. The new FundingOutcome::Submitted = 6 covers a top-up whose snapshot verified without that.
• New FundingOutcome::FeeCapReached = 7 (a floor above 100, or 10506 at 100).
• New asset_lock_state(txid, vout), returning AssetLockStateResult { status, state: AssetLockState, remaining_credits }.
• dash-sdk-cxx gains dev-dependencies on drive and tenderdash-abci (tests only; its normal-edge closure is unchanged), so Cargo.lock lists them.

dash_sdk::Error gains DpnsNameContested, FeeIncreaseFloorAboveCap and AssetLockNotUsedUp. The enum is not #[non_exhaustive], so an exhaustive match outside this repository needs the new arms. wasm-sdk's match is updated in this PR. Everything else in rs-sdk is additive, and so is Drive's new util::common::asset_lock module.

The only consumer of the C++ API is Dash Core's opt-in Platform GUI build, which moves to this API in its own PR train. wasm-sdk, rs-sdk-ffi and rs-platform-wallet keep their current behaviour. Adopting the bounded submission, the settled top-up, the DPNS policy and next_chain_lock_proof there is tracked in #5800.

In-place changes to shipped generations

Drive::verify_state_transition_was_executed_with_proof_v0, both ShieldFromAssetLock arms
(packages/rs-drive/src/verify/state_transition/verify_state_transition_was_executed_with_proof/v0/mod.rs)

• Selected by: every protocol version. Verifier generation 0 (protocol versions 1–13) and generation 1
  (14 onward) both dispatch to this v0 body. ShieldFromAssetLock is admitted from protocol version 12
  (SHIELDED_POOL_INITIAL_PROTOCOL_VERSION), so its proofs exist from 12 on.

• What changed: the surplus-output arm and the outpoint-only arm each read a proved Element::Item inline
  (empty bytes → FullyConsumed, otherwise AssetLockValue::deserialize_from_bytes_untrusted →
  PartiallyConsumed). Both now call drive::util::common::asset_lock::stored_asset_lock_info(Some(&bytes), AssetLockValue::deserialize_from_bytes_untrusted), the record reader the SDK also uses.

• Why no verification result can change: called with Some(bytes), the helper does exactly what the removed
  lines did. It uses the same decoder, which is untrusted and non-exact, so trailing bytes are still ignored. It
  returns the same ProtocolError through the same ?. The paths that never reached the old inline code (a
  non-Item element, an absent outpoint, no proved key, more than one element) keep their own branches and
  messages unchanged. The helper's None → NotPresent case is never reached from the verifier. The verifier
  runs on clients, not in consensus: no node state, fee or validation result depends on it.

• Why not a new generation: the edit is output-identical at every version, so a new generation would copy the
  whole verifier body without changing any behaviour.

• Pinned by: should_read_the_shield_from_asset_lock_record_alike_from_protocol_version_13 (rs-drive). For
  both arms, at protocol versions 13, 14 and the latest, it proves with Drive's prover and verifies through
  verify_state_transition_was_executed_with_proof:

  • an empty record gives FullyConsumed;
  • an encoded value gives PartiallyConsumed;
  • the same value with trailing bytes gives PartiallyConsumed (non-exact decoding kept);
  • an absent record gives CorruptedProof.

  Switching either arm to exact decoding fails it at protocol version 13, and so does accepting an absent record
  as NotPresent in either arm. The edited lines carry a comment saying why they are inert. The existing
  drive-abci round trips (test_shield_from_asset_lock_prove_and_verify,
  test_shield_from_asset_lock_no_surplus_prove_and_verify,
  test_shield_from_asset_lock_padded_proof_is_rejected_by_strict_verify) still pass.

Checklist:

• I have performed a self-review of my own code
• My Rust, FFI, WASM, Swift or Kotlin changes follow the coding conventions
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request
• If I added or changed a system contract's document schemas, I checked the contract viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · 2a28db5

• Bots — thepastaclaw ✓
• Self-review — posted; again after any push
• Reviewer requests paused — your 5 review slots are occupied; this PR is excluded from reviewers' queues. Required approvals still count without a slot.
• Build green
• Approvals
  • files with no dedicated owner (Cargo.lock, packages/rs-sdk-cxx/Cargo.toml, packages/rs-sdk-cxx/include/dash/sdk/callbacks.h and 6 more) — QuantumExplorer or shumkov
  • rs-drive (packages/rs-drive/src/util/common/asset_lock.rs, packages/rs-drive/src/util/common/mod.rs, packages/rs-drive/src/verify/state_transition/verify_state_transition_was_executed_with_proof/v0/mod.rs) — QuantumExplorer or shumkov
  • rs-platform-wallet (packages/rs-platform-wallet/src/wallet/asset_lock/orchestration.rs, packages/rs-platform-wallet/src/wallet/identity/network/registration.rs) — HashEngineering or ZocoLini or llbartekll or romchornyi
  • rust-sdk (packages/rs-sdk/src/error.rs, packages/rs-sdk/src/platform/dashpay/invitation.rs, packages/rs-sdk/src/platform/documents/contest_fund.rs and 4 more) — lklimek or shumkov
  • js-wasm-sdk (packages/wasm-sdk/src/error.rs) — shumkov

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

Summary by CodeRabbit

• New Features
  • Identity registration and top-ups accept a fee-increase floor and report funding outcomes and attempted fees.
  • Added asset-lock state checks and identity ID lookup from an asset-lock outpoint.
  • DPNS registration supports policies to refuse contested names or cap contest funding.
  • Quorum lookup distinguishes found, invalid, and unavailable results.
• Bug Fixes
  • Top-up results distinguish submitted funding from settlement; success requires proof that the asset lock was fully consumed.
  • Contested DPNS names receive a distinct status.
• Documentation
  • Clarified that prospective identity lookups do not confirm whether an asset lock remains usable.
  • Clarified that balance snapshots do not confirm top-up execution and that refused transaction hashes may be retained without a time limit.