From cf68603fbc1a615ae6f41485e61d77168a50141d Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 21 May 2026 11:13:52 -0400 Subject: [PATCH 1/5] docs(protocol-ref): update for v3.1 PlatformAddress encoding and remove feature-flags contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #3059 renamed the PlatformAddress HRPs (evo/tevo → dash/tdash) and introduced two distinct byte encodings (user-facing bech32m vs. internal GroveDB storage). PR #3522 removed the feature-flags system contract. Refresh source-line anchors against current rs-dpp line numbers. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../platform-protocol-data-trigger.md | 1 - docs/protocol-ref/address-system.md | 19 ++++++++----------- docs/protocol-ref/protocol-constants.md | 8 ++++---- .../connect-to-a-network-dash-masternode.md | 6 ------ 4 files changed, 12 insertions(+), 22 deletions(-) diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index cbb02be66..b3ac7d9b2 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -41,6 +41,5 @@ In addition to DPNS, DPP ships data triggers for a small set of other system con | DashPay | `contactRequest` | [`CREATE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay) | Enforces DashPay-specific rules on outgoing contact requests | | ---- | ---- | ---- | ---- | | Withdrawals | `withdrawal` | [`CREATE`/`REPLACE`/`DELETE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/withdrawals) | Enforces withdrawal status transitions and prevents direct external mutation of withdrawal documents | -| Feature flags | (various) | [Protocol-version updates](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/feature_flags) | Restricts feature flag changes to the authorized feature-flag identity | When document state transitions are received, DPP checks if there is a trigger associated with the document type and action. If a trigger is found, DPP executes the trigger logic. Successful execution of the trigger logic is necessary for the document to be accepted and applied to the [platform state](../explanations/drive-platform-state.md). diff --git a/docs/protocol-ref/address-system.md b/docs/protocol-ref/address-system.md index 55e97c2ae..cd078e609 100644 --- a/docs/protocol-ref/address-system.md +++ b/docs/protocol-ref/address-system.md @@ -27,19 +27,16 @@ There are six address-based state transition types: ### Platform Address -Platform addresses are derived from standard Bitcoin/Dash address formats and encoded using bech32m per [DIP-0018](https://github.com/dashpay/dips/blob/master/dip-0018.md). +Platform addresses are derived from standard Bitcoin/Dash address formats and encoded as bech32m strings per [DIP-0018](https://github.com/dashpay/dips/blob/master/dip-0018.md). The human-readable part (HRP) is `dash` on mainnet and `tdash` on testnet, devnet, and regtest. The 21-byte payload is `type_byte || Hash160(compressed_pubkey)`, where `Hash160 = RIPEMD160(SHA256(x))`. The checksum is bech32m ([BIP-350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki)). -| Variant | Type Byte | Size | Description | -| ------- | ---- | -------- | ---------------------------------------------------- | -| `P2PKH` | 0xb0 | 21 bytes | Pay-to-Public-Key-Hash (1 type byte + 20 hash bytes) | -| `P2SH` | 0x80 | 21 bytes | Pay-to-Script-Hash (1 type byte + 20 hash bytes) | +| Variant | Type Byte | Description | +| ------- | --------- | ----------- | +| `P2PKH` | 0xb0 | Pay-to-Public-Key-Hash | +| `P2SH` | 0x80 | Pay-to-Script-Hash | -**Encoding:** - -- **Mainnet HRP:** `dash` -- **Testnet HRP:** `tdash` (also used for Devnet and Regtest) - -**Derivation:** Standard Bitcoin derivation using `Hash160(compressed_pubkey)` where Hash160 = RIPEMD160(SHA256(x)). +:::{note} +A `PlatformAddress` has two distinct byte encodings depending on context. The type bytes above (`0xb0` / `0x80`) apply to the user-facing bech32m encoding — what appears in address strings like `dash1k...`. Internal GroveDB storage keys use bincode variant indices `0x00` / `0x01` instead. Decoding one through the other's code path will fail. +::: See the [Platform address implementation in rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs). diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 4d0b94995..1ff5e6811 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -253,10 +253,10 @@ These limits apply to token perpetual distribution function parameters. | Constant | Value | Description | Source | |----------|-------|-------------|--------| | Address hash size | 20 bytes | Size of address hash | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L22) | -| Platform HRP (mainnet) | "dash" | Human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L89) | -| Platform HRP (testnet) | "tdash" | Testnet human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L91) | -| P2PKH address type | 0xb0 (176) | Pay-to-public-key-hash encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L95) | -| P2SH address type | 0x80 (128) | Pay-to-script-hash encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L97) | +| Platform HRP (mainnet) | "dash" | Human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L184) | +| Platform HRP (testnet) | "tdash" | Testnet human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L186) | +| P2PKH address type (bech32m) | 0xb0 (176) | Pay-to-public-key-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L190) | +| P2SH address type (bech32m) | 0x80 (128) | Pay-to-script-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L192) | ### Transaction Limits diff --git a/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md b/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md index 3d2f03800..8d007fe21 100644 --- a/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md +++ b/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md @@ -44,12 +44,6 @@ Example (partial) output of the setup wizard showing important information: › Dashpay contract ID: EAv8ePXREdJ719ntcRiKuEYxv9XooMwL1mJmPHMGuW9r ✔ Obtain Dashpay contract commit block height › Dashpay contract block height: 15 - ✔ Register Feature Flags identity - › Feature Flags identity: 8BsvV4RCbW7srWj81kgjJCykRBF2rzyigys8XkBchY96 - ✔ Register Feature Flags contract - › Feature Flags contract ID: JDrDAGVqTWsM9k7KGBsSjcyC11Vd2UdPxPoPf4NzyyrP - ✔ Obtain Feature Flags contract commit block height - › Feature Flags contract block height: 20 ``` From 4aa76f79b674ed20d2aa35bd9132341aa6230eee Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 21 May 2026 11:24:04 -0400 Subject: [PATCH 2/5] docs(explanations): add Proofs explanation page Cover the two-layer proof model (GroveDB Merkle proofs + Tenderdash consensus signatures), what can be proven, the v3.1 aggregate proof primitives (count/sum/average), and asset lock proofs. Wire it into the explanations toctree. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/explanations/proofs.md | 168 ++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 169 insertions(+) create mode 100644 docs/explanations/proofs.md diff --git a/docs/explanations/proofs.md b/docs/explanations/proofs.md new file mode 100644 index 000000000..531cdf524 --- /dev/null +++ b/docs/explanations/proofs.md @@ -0,0 +1,168 @@ +```{eval-rst} +.. _explanations-proofs: +``` + +# Proofs + +## Overview + +Proofs are a fundamental security feature of Dash Platform that enable trustless verification of data. When retrieving information from the network, clients can request cryptographic proofs that allow them to verify the data's authenticity without trusting the individual node that provided it. + +This is particularly important in a decentralized system where any single node could potentially return incorrect or malicious data. With proofs, clients can mathematically verify that: + +- The data exists (or doesn't exist) in the platform state +- The state was agreed upon by the network's validator quorum +- No tampering occurred between the node and the client + +Proofs enable light clients and mobile applications to interact securely with Dash Platform without running a full node or blindly trusting remote servers. + +## How Proofs Work + +Dash Platform uses a two-layer proof architecture that combines Merkle proofs from the storage layer with consensus signatures from the validator network. + +### GroveDB Merkle Proofs + +The first layer of verification uses [GroveDB](https://github.com/dashpay/grovedb), Dash Platform's authenticated data structure. GroveDB organizes all platform data in a tree structure where each piece of data contributes to a cryptographic hash that rolls up to a single root hash. + +When a client requests data with a proof, GroveDB returns: + +- The requested data (or proof of its absence) +- A Merkle path showing how the data connects to the root hash + +This allows clients to independently calculate what the root hash should be and verify it matches. Any modification to the data would produce a different root hash, making tampering detectable. + +### Tenderdash Consensus Signatures + +The second layer connects the GroveDB root hash to the network's consensus. Dash Platform uses [Tenderdash](../explanations/platform-consensus.md), a Byzantine fault-tolerant consensus protocol, where validator quorums sign each block. + +The proof includes: + +- A BLS threshold signature from the validator quorum +- The quorum hash identifying which validators signed +- Block metadata (height, round, timestamp) + +Clients verify that the root hash from the GroveDB proof matches what the quorum signed. Since producing a valid BLS threshold signature requires participation from more than two-thirds of the quorum members, this proves the network agreed on this exact state. + +:::{tip} +BLS threshold signatures are particularly efficient because regardless of how many validators participated, the final signature is always the same compact size. This keeps proofs small even as the validator set scales. +::: + +### Verification Flow + +The complete verification process follows these steps: + +1. Client sends a request to [DAPI](../explanations/dapi.md) with `prove: true` +2. DAPI retrieves the data and generates a proof from [Drive](../explanations/drive.md) +3. Client receives the response containing data, GroveDB proof, and consensus signature +4. Client verifies the GroveDB proof to extract the root hash +5. Client verifies the BLS signature against the root hash using the quorum's public key +6. If both verifications pass, the data is cryptographically confirmed + +## What Can Be Proven + +Dash Platform supports proofs for all core data types: + +**Identities** + +- Identity existence and full details +- Identity balance and revision +- Public keys associated with an identity +- Identity nonces (for replay protection) + +**Data Contracts** + +- Contract existence and contents +- Contract history (for contracts that track changes) + +**Documents** + +- Document existence within a contract +- Document queries with multiple results +- Proof of document absence (data doesn't exist) +- Aggregate values over a document set (count, sum, average) — see [Aggregate Proofs](#aggregate-proofs) below + +**Tokens** + +- Token balances for identities +- Token total supply +- Token status and configuration + +**System State** + +- Current epoch information +- Protocol version and upgrade status +- Contested resource voting state + +## Aggregate Proofs + +Beyond proving the existence and contents of individual documents, Dash Platform can produce verifiable answers to aggregate queries — questions about a *set* of documents, answered with one or more aggregate values instead of a list. This avoids streaming and verifying every matching document just to learn how many there are or what they sum to. + +Three aggregate primitives are supported: + +- **Count** — number of documents matching the query. +- **Sum** — sum of an integer field across matching documents. +- **Average** — average of an integer field across matching documents. + +Some aggregate queries can return either one total or grouped totals, depending on the query shape. + +Aggregate queries use the same two-layer verification as any other proof (GroveDB Merkle proof plus Tenderdash consensus signature), so the result carries the same trust model as other proven Platform responses. + +For the exact request and response shapes, see the [DAPI Platform endpoints reference](../reference/dapi-endpoints-platform-endpoints.md). + +## Requesting and Verifying Proofs + +### DAPI Integration + +The Decentralized API (DAPI) provides the interface for requesting proofs. When making queries, clients can set the `prove` parameter to receive cryptographic proofs alongside the data. + +Without proofs, clients must trust that the DAPI node is returning accurate data. With proofs enabled, clients can verify responses independently, treating DAPI nodes as untrusted data carriers rather than trusted authorities. + +:::{note} +The Dash Platform SDKs handle proof verification automatically when proofs are requested. Developers using the SDK don't need to implement verification logic manually. +::: + +### What Verification Confirms + +When a proof verifies successfully, the client has cryptographic assurance that: + +1. **Data integrity**: The data matches exactly what is stored in platform state +2. **Consensus agreement**: A valid validator quorum signed this state at a specific block height +3. **Temporal accuracy**: The proof is tied to a specific block height and timestamp +4. **Completeness**: For queries, all matching results are included (nothing omitted) + +Proof verification also detects proof-of-absence, confirming when requested data genuinely doesn't exist rather than being withheld by a malicious node. + +## Asset Lock Proofs + +Asset lock proofs are a special category used when creating or funding [identities](../explanations/identity.md). They prove that Dash has been locked on the core blockchain (layer 1) to establish credits on Dash Platform (layer 2). + +### Instant Asset Lock Proof + +Uses Dash's InstantSend feature to prove funds are locked immediately: + +- Contains the InstantSend lock proving transaction finality +- Includes the asset lock special transaction +- Enables immediate identity creation without waiting for block confirmations + +This is the preferred method as it allows near-instant identity creation. + +### Chain Asset Lock Proof + +Uses ChainLocks to prove funds are locked at a specific core blockchain height: + +- References the asset lock transaction by its outpoint +- Specifies the core chain height where the transaction was chain-locked +- Provides finality guarantee through Dash's ChainLock mechanism + +This method is used when InstantSend confirmation is not available. + +:::{attention} +Asset lock proofs are verified by the network during identity creation and topup state transitions. The locked funds cannot be spent on the core chain once used to create platform credits. +::: + +## Related Topics + +- [Platform Consensus](../explanations/platform-consensus.md) - How Tenderdash and validator quorums work +- [Identity](../explanations/identity.md) - Identity creation using asset lock proofs +- [DAPI](../explanations/dapi.md) - The API layer for requesting proofs +- [Drive](../explanations/drive.md) - The storage layer that generates proofs diff --git a/docs/index.md b/docs/index.md index 7c9f81501..e89b33b43 100644 --- a/docs/index.md +++ b/docs/index.md @@ -134,6 +134,7 @@ explanations/dashpay explanations/fees explanations/tokens explanations/nft +explanations/proofs explanations/query ``` From 5ace40398c2ee1f9c2a06b2c3457d1b47ba38566 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 21 May 2026 11:45:22 -0400 Subject: [PATCH 3/5] docs(protocol-ref): document max_asset_lock_transaction_inputs constant Introduced in protocol v3 (#3491) to prevent stuck funds; v1 and v2 had no effective limit. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/protocol-ref/protocol-constants.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 1ff5e6811..481c98715 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -177,6 +177,7 @@ Fees related to contested document voting. | Min top-up balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L21) | | Min address funding balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L22) | | Min identity funding amount | 200,000 credits | Minimum for address-based creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L41) | +| Max asset-lock transaction inputs | 100 | Maximum Core inputs in an asset-lock transaction used to fund an identity or top-up (introduced in protocol v3 to prevent stuck funds; v1/v2 had no effective limit) | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | ## Document & Data Contract Model From 1da2e106e0e88859ea0807898cb939828d81f7f4 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 21 May 2026 11:47:09 -0400 Subject: [PATCH 4/5] chore: sync sidebar --- _templates/sidebar-main.html | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/_templates/sidebar-main.html b/_templates/sidebar-main.html index 8a3287e4c..56fa79b72 100644 --- a/_templates/sidebar-main.html +++ b/_templates/sidebar-main.html @@ -180,6 +180,26 @@ DashMint Lab — NFT marketplace +
  • + + Dashnote + +
    • +
  • + + DashMint Lite + +
    • +
  • + + Dashnote Lite + +
    • +
  • + + DashProof Lite + +
    • @@ -330,6 +350,11 @@ Non-Fungible Tokens (NFTs) +
  • + + Proofs + +
  • Query Capabilities From 428e6dcaadf44d1fdba305a4ee99e58443f39dbe Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 21 May 2026 12:28:34 -0400 Subject: [PATCH 5/5] docs: clarify hrp --- docs/protocol-ref/protocol-constants.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 481c98715..c06962160 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -255,7 +255,7 @@ These limits apply to token perpetual distribution function parameters. |----------|-------|-------------|--------| | Address hash size | 20 bytes | Size of address hash | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L22) | | Platform HRP (mainnet) | "dash" | Human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L184) | -| Platform HRP (testnet) | "tdash" | Testnet human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L186) | +| Platform HRP (non-mainnet) | "tdash" | Human-readable prefix used for testnet, devnet, and regtest | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L186) | | P2PKH address type (bech32m) | 0xb0 (176) | Pay-to-public-key-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L190) | | P2SH address type (bech32m) | 0x80 (128) | Pay-to-script-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L192) |