Skip to content

docs(platform-wallet): error-code registry for the FFI result space - #4261

Closed
bfoss765 wants to merge 11 commits into
dashpay:v4.2-devfrom
bfoss765:docs/ffi-error-code-registry
Closed

bfoss765 wants to merge 11 commits into
dashpay:v4.2-devfrom
bfoss765:docs/ffi-error-code-registry

Conversation

@bfoss765

@bfoss765 bfoss765 commented Aug 1, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

PlatformWalletFFIResultCode (packages/rs-platform-wallet-ffi/src/error.rs) is public ABI — cbindgen emits the integers into the generated C header, Swift mirrors them in PlatformWalletResultCode, and Kotlin branches on them in fromPlatformWalletNative. Four open PRs are currently allocating adjacent integers in that enum with no shared source of truth.

A duplicate discriminant in two branches produces no textual merge conflict. The second merge just silently misclassifies errors on every host. That is not hypothetical here: 29 is already claimed by two PRs, and review on #4185 had to issue a renumber directive (ErrorReservationWalletMismatch 29 → 30) to resolve it. Three separate PRs now carry hand-written comments trying to reserve ranges on each other's behalf, and one of those reservations is for a variant that no longer exists.

This PR adds a registry so the allocation is decided in one file instead of in four diffs.

What's here

packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md:

  • the merged allocation table (0–26, plus the 98/99 sentinels),
  • the proposed allocations with their owning PRs (27–33),
  • the rule for claiming a new code — next free integer, recorded here in the same PR that adds it, mirrors updated alongside,
  • the ABI-stability rule — never renumber after release; deprecate and allocate a new integer,
  • the contested/pending allocations, written up below as well.

Plus a six-line pointer from the crate README's Error Handling section.

Docs-only. Zero code risk. No enum, no From mapping, no Swift/Kotlin mirror is touched, and nothing is renumbered — that stays the owning PRs' work. This PR only writes down what the branches already say.

Codes claimed by the in-flight PRs

Reconciling in one place, so this is the table to correct:

Code Name Owning PR
27 ErrorStaleReservationToken #4185 (also carried by #4256)
28 ErrorReservationTokenConsumed #4185 (also carried by #4256)
29 ErrorReservationWalletMismatch #4185 — collides, see below
29 ErrorAssetLockInsufficientFunds #4184 — collides, see below
30 unallocated reserved in sibling comments only, see below
31 ErrorSigningKeyUnavailable #4183 (also carried by #4204)
32 ErrorTransactionBuild #4247 (also carried by #4256)
33 ErrorTransactionSigning #4256

Open PRs touching this crate that claim no new code: #4186, #4191, #4194, #4195, #4240, #4251, #4258. Next free integer: 34.

rs-sdk-ffi's DashSDKErrorCode is a separate integer space and is not modified by any of these PRs.

⚠️ Previously unflagged collision: code 26 on #4196

Surveying the branches turned up a second collision that does not appear to have been raised in review.

#4196 branched before 26 = ErrorTransactionBroadcastRejected merged to v4.2-dev (in 9302c62e8b), and its head numbers the reservation trio 26 / 27 / 28:

ErrorStaleReservationToken    = 26   // collides with merged ErrorTransactionBroadcastRejected
ErrorReservationTokenConsumed = 27
ErrorReservationWalletMismatch = 28

So as it stands, #4196 would give 26 two meanings on merge, and it also contradicts #4185 — the PR it is stacked on — which numbers those same three names 27 / 28 / 29. The fix is a rebase onto current v4.2-dev plus adopting whatever numbering #4185 lands with; no new integers are needed. Flagging rather than fixing, per the docs-only scope.

Code 30 is free, despite what three branches say

ErrorAssetLockCrossDomainConsentRequired is named as the holder of 30 in in-tree comments on #4183, #4204, and in #4247/#4256's numbering rationale. It is not defined anywhere — #4184, the PR that would have introduced it, dropped it in a re-scope. 30 is therefore genuinely free, and is the slot the #4185 renumber should take. Those stale comments should be dropped by whichever PR touches them next.

Ambiguity left open for maintainers

Review on #4256 suggested mapping its signing failure onto 31; #4256 declined and took 33, arguing that 31 (ErrorSigningKeyUnavailable, #4183) asserts a narrower contract — the signer holds no usable private key for a requested public key — while BuilderError::SigningFailed also covers unresolved derivation paths, sighash failures, and malformed signature encodings. Both are currently allocated. Collapsing them is a reasonable call, but it belongs to #4183 and #4256 jointly; the registry records the split as-is rather than pre-judging it.

Please correct the table

The merged rows were read straight from v4.2-dev at ed4116b26c. The proposed rows were read from each PR's head commit (SHAs listed in the doc's provenance section) and will go stale as those PRs are updated. If a maintainer has a different intent for any allocation — particularly 30, and the 31/33 split — please say so on this PR and I'll amend, or edit the file directly. The point is that there is now one place where that correction lands.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added an authoritative registry for platform wallet result codes, covering stability guidance, allocation rules, reserved values, conflicts, and historical changes.
    • Documented current and proposed code assignments, including cross-language consistency information.
    • Updated the platform wallet documentation to clarify that result codes are part of the public interface and link to the registry for future additions.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants