docs: add DIP for state transition signing request URI scheme #174

PastaPastaPasta · 2026-01-04T02:37:08Z

Defines the dash-st: URI scheme for requesting signing of Dash Platform state transitions via QR codes or copy-paste. Enables dApp-wallet interoperability for cross-device and air-gapped signing.

Summary by CodeRabbit

Documentation
- Added a comprehensive specification for the Dash State Transition Signing Request URI Scheme (dash-st), including abstract, motivation, URI format and grammar, request/response parameters, state transition encoding, wallet processing behaviors (parse, decode, verify, preview, signing flows, online vs air-gapped handling), examples, and security guidance (cross-network checks, replay protection, consent and high-risk warnings).

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Defines the `dash-st:` URI scheme for requesting signing of Dash Platform state transitions via QR codes or copy-paste. Enables dApp-wallet interoperability for cross-device and air-gapped signing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

coderabbitai · 2026-01-04T02:37:16Z

📝 Walkthrough

Walkthrough

A new specification document introducing the Dash State Transition Signing Request URI Scheme (dash-st), defining the URI format and ABNF, request/response parameters, state transition encoding, wallet processing and signing flows (including online vs air-gapped), examples, and security considerations.

Changes

Cohort / File(s)	Summary
Dash State Transition Signing Request Specification `dip-signing-request.md`	New Markdown specification defining the `dash-st` URI scheme: abstract, motivation, prior work, full specification (URI scheme, URI format, ABNF grammar), request & response parameters, state transition encoding, wallet behavior for parsing/validation/signing (online and air-gapped), examples, security considerations, and license.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a DIP (Dash Improvement Proposal) document for a state transition signing request URI scheme.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 855a9b6 and f14b9a8.

📒 Files selected for processing (1)

dip-signing-request.md

🚧 Files skipped from review as they are similar to previous changes (1)

dip-signing-request.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (5)

dip-signing-request.md (5)

2-2: DIP number not yet assigned.

The DIP field contains a placeholder XXXX. Once this document progresses through review, ensure a proper DIP number is assigned and updated.

103-110: Verify the serialization method reference.

The specification references PlatformSerializable::serialize_to_bytes() but does not clarify whether this is language-agnostic or implementation-specific. To ensure cross-implementation compatibility, consider explicitly stating the serialization format (e.g., CBOR, protobuf, or platform-specific binary) and any versioning scheme.

152-173: Wallet processing flow is comprehensive and logical.

The nine-step flow properly sequences validation, user consent, signing, and response handling. The air-gapped vs. online branching clearly supports the motivating use cases. Network verification upfront prevents cross-network attacks.

Minor clarity improvements for future: step 7 could be more explicit about which validation failures yield s=r (rejection) versus s=e (error), and a timeout mechanism might be valuable for request URIs to prevent stale signing requests lingering.

175-199: Security considerations are well-structured with appropriate use of RFC 2119 language.

The five-point coverage addresses network separation, protocol-level replay protection, user consent, and high-risk transition warnings. The requirement to reject rather than fallback on invalid key IDs (line 199) prevents subtle security bypasses.

Worth considering in future iterations: phishing/origin verification (showing request context), rate limiting wallets to prevent signing request spam, and explicit guidance on signature validation in deserialized transitions. But the current set covers the core risks appropriately for this protocol.

1-203: Document is well-structured and implementable, with solid specification coverage.

The DIP clearly articulates the problem, provides appropriate motivation, and defines a usable URI scheme inspired by proven standards (BIP-0021, EIP-681). The processing flow, parameter definitions, and security considerations are comprehensive and well-reasoned.

Minor gaps to address:

DIP number remains unassigned (XXXX on line 2)

Serialization format reference (line 107) should be more explicit about whether PlatformSerializable::serialize_to_bytes() is language-agnostic or tied to a specific implementation

Response format validation (e.g., verifying signed transition contains valid signatures) could be more explicit

Overall, the document is ready for community review and implementation. These minor clarifications can be addressed as feedback arrives.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between be80e0f and 855a9b6.

📒 Files selected for processing (1)

dip-signing-request.md

🔇 Additional comments (3)

dip-signing-request.md (3)

53-80: URI scheme and grammar look well-defined.

The dash-st: scheme naming is clear and consistent with BIP-0021 and EIP-681 precedents. The ABNF grammar properly specifies Base58 character constraints (excluding 0, I, O, l), matching Dash's existing conventions.

82-101: Parameter set is well-chosen for the core use case.

The minimal parameter set supports QR code encoding efficiency while providing essential hints (id, k, l) for wallet UX. The binary status values (1, r, e) keep response URIs compact.

A few design notes to consider in future iterations: no timeout/expiry mechanism is specified, and responses lack structured error codes (only free-form text in e). For now, these are reasonable trade-offs favoring simplicity.

120-150: Examples are clear and cover key scenarios.

The five examples effectively illustrate request URIs with and without hints, successful signing, user rejection, and error cases. The query parameter formatting is correct throughout. Placeholder Base58 data is appropriate for a specification document.

HashEngineering

Only a few observations.

HashEngineering · 2026-01-04T05:53:09Z

dip-signing-request.md

+
+Where:
+
+* `<state-transition-data>` is the Base58-encoded state transition bytes


st-data is used below

HashEngineering · 2026-01-04T05:59:39Z

dip-signing-request.md

+## URI Format
+
+```text
+dash-st:<state-transition-data>[?<parameters>]


The QR-Code standard says that the max data size is 2950 (binary) or 4296 alpha numeric characters. This would be for the entire URI. There is an upper limit on state transition sizes rendered as a QR-code.

yes; this is a valid concern, the implementation layer should be aware of this. I don't think we need to define it here, since we are mostly just defining a URI scheme

Use `st-data` and `parameters` to match the ABNF grammar definition. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

thephez · 2026-01-06T15:58:54Z

dip-signing-request.md

+                  ; 1-9, A-H, J-N, P-Z, a-k, m-z (excludes 0, I, O, l)
+```
+
+## Parameters


I'd prefer more descriptive response statuses and param names (e.g., label) like BIP21 uses. Was it necessary to use single char param names to minimize qr code complexity or something?

thephez · 2026-01-06T16:00:56Z

dip-signing-request.md

+
+The state transition bytes are encoded using Base58. This encoding is consistent with how Dash Platform Identifiers are encoded and is URL-safe.
+
+The bytes represent the state transition serialized via `PlatformSerializable::serialize_to_bytes()`:


PlatformSerializable::serialize_to_bytes() is a pretty detailed implementation thing. If necessary, maybe add a link to code?

coderabbitai bot reviewed Jan 4, 2026

View reviewed changes

HashEngineering reviewed Jan 4, 2026

View reviewed changes

docs: use consistent st-data terminology in URI format

f14b9a8

Use `st-data` and `parameters` to match the ABNF grammar definition. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

thephez reviewed Jan 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add DIP for state transition signing request URI scheme #174

docs: add DIP for state transition signing request URI scheme #174

Uh oh!

PastaPastaPasta commented Jan 4, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jan 4, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Uh oh!

HashEngineering left a comment

Uh oh!

HashEngineering Jan 4, 2026

Uh oh!

HashEngineering Jan 4, 2026 •

edited

Loading

Uh oh!

PastaPastaPasta Jan 4, 2026

Uh oh!

thephez Jan 6, 2026

Uh oh!

thephez Jan 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Where:

		* `<state-transition-data>` is the Base58-encoded state transition bytes


		The state transition bytes are encoded using Base58. This encoding is consistent with how Dash Platform Identifiers are encoded and is URL-safe.

		The bytes represent the state transition serialized via `PlatformSerializable::serialize_to_bytes()`:

docs: add DIP for state transition signing request URI scheme #174

Are you sure you want to change the base?

docs: add DIP for state transition signing request URI scheme #174

Uh oh!

Conversation

PastaPastaPasta commented Jan 4, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Pre-merge checks

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

HashEngineering left a comment

Choose a reason for hiding this comment

Uh oh!

HashEngineering Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

HashEngineering Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PastaPastaPasta Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

thephez Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

thephez Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PastaPastaPasta commented Jan 4, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 4, 2026 •

edited

Loading

HashEngineering Jan 4, 2026 •

edited

Loading