feat: v4

CLAUDE.md

@@ -74,6 +74,26 @@ When updating documentation values that include GitHub source links:
 - Update the line anchor (`#L`) to match the correct line **in the branch the link points to**
 - When available, use the local platform repository checkout to verify line numbers against the correct branch
 
+## Adding a new doc page
+
+A new page is only visible in the rendered site if it appears in a Sphinx toctree. Sphinx will emit a `document isn't included in any toctree` warning at build time for any orphaned page, and the page won't show up in the sidebar.
+
+Top-level toctrees live in [docs/index.md](docs/index.md), grouped by section caption (`Tutorials`, `Explanations`, `Reference`, `Platform Protocol Reference`, `Resources`). When you add a new page under `docs/<section>/`, add its path (without the `.md` extension) to the matching toctree in `docs/index.md`. After editing the toctree, run `python scripts/sync_sidebar.py` so the custom sidebar template picks up the new entry.
+
+Tutorials and the TUI section use nested `index.md` files with their own toctrees — check the parent `index.md` of the directory you're adding to.
+
+## DAPI endpoint reference
+
+The DAPI endpoint reference is split between an overview page (`docs/reference/dapi-endpoints.md`) and per-section detail pages (`docs/reference/dapi-endpoints-*.md`). The authoritative list of endpoints lives in the platform proto at `https://github.com/dashpay/platform/tree/<branch>/packages/dapi-grpc/protos` — check the proto when adding or modifying entries.
+
+When you add or materially update an entry on a detail page, also update the matching row on `dapi-endpoints.md`:
+
+- Keep the description in sync between the two pages.
+- Prefix the overview row's description with `**Added in Dash Platform vX.Y.Z**` (new endpoints) or `**Updated in Dash Platform vX.Y.Z**` (modified endpoints), followed by `<br>` and the description. Use **bold** for the current release's annotations; older releases use *italics*.
+- For a whole new endpoint group, wrap the new section in a `:::{versionadded} X.Y.Z` admonition above its table — see Security Groups, Tokens, Address System, and Shielded Transactions for the pattern.
+
+For the full per-release endpoint review process (proto diff, example refresh, demoting annotations to italics), see [RELEASE.md](RELEASE.md).
+
 ## File Patterns
 
 - Documentation files: `docs/**/*.md`

RELEASE.md

@@ -0,0 +1,14 @@
+# Release Checklist
+
+Per-release tasks for the docs. For editing conventions, see [CLAUDE.md](CLAUDE.md).
+
+## DAPI endpoint review
+
+1. Diff the platform proto between the previous release tag and the current release branch — that's the source of truth for what changed. Proto source: `https://github.com/dashpay/platform/tree/<branch>/packages/dapi-grpc/protos`.
+2. For each affected endpoint, update both the detail page (`docs/reference/dapi-endpoints-*.md`) and the matching row on the overview page (`docs/reference/dapi-endpoints.md`), with the bold version annotation on the overview row.
+3. Demote the previous release's bold annotations on the overview page to italics.
+4. Re-run example requests against testnet and refresh response examples if necessary. Testnet state may have been wiped, so even unchanged endpoints may have stale data.
+
+## Update "Previous version" links
+
+Several pages (including the DAPI endpoints pages) link to the previous version of the docs. These links are not updated automatically. Search the site for "previous version" and update each link to point to the appropriate version.

_static/dashmint-lite.html

@@ -119,18 +119,24 @@ <h2>Browse cards</h2>
     // package and serves it as a browser-native ES module. Pinned to the same
     // version the React app at ../package.json depends on so both UIs behave
     // identically against the same testnet contract.
-    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@3.1.0-dev.1';
+    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.0.0-rc.2';
 
-    // The "card" data contract is already published on testnet by the React app.
-    // Anyone querying with the same contract id hits the same documents.
-    const CONTRACT_ID = '4eJR4pgV9mQdyoodfTTwFUp3SYBRJbUrJ5X1ViN2zBhY';
+    // The token-enabled "card" data contract is already published on testnet by
+    // the React app. Anyone querying with the same contract id hits the same
+    // documents.
+    const CONTRACT_ID = '5hK6SMfN4m2vU1t9qhvngUUQjsXeMNwr8MZdFeGBH8Aa';
     const DOC_TYPE = 'card';
 
     // Connect to testnet. testnetTrusted() uses the SDK's bundled list of trusted
     // nodes — no node URL or config needed. connect() does the gRPC handshake
     // + initial sync. No identity or signing is required for read-only queries.
+    //
+    // Workaround: pin the platform protocol version for evo-sdk dev.6 so the
+    // SDK doesn't ask testnet for a newer protocol it can't decode. Mirrors
+    // PLATFORM_VERSION_OVERRIDE in setupDashClient-core.mjs. Remove once a
+    // fixed SDK release lands.
     async function connectSdk() {
-      const sdk = EvoSDK.testnetTrusted();
+      const sdk = EvoSDK.testnetTrusted({ version: 11 });
       await sdk.connect();
       return sdk;
     }

_static/dashnote-lite.html

@@ -129,7 +129,7 @@ <h2>Get note by ID</h2>
     // package and serves it as a browser-native ES module. Pinned to the same
     // version the React app at ../package.json depends on so both UIs behave
     // identically against the same testnet contract.
-    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@3.1.0-dev.1';
+    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.0.0-rc.2';
 
     // The "note" data contract is already published on testnet by the React app.
     // Anyone querying with the same contract id hits the same documents.

_static/dashproof-lite.html

@@ -120,7 +120,7 @@ <h2>History by chainId</h2>
     // package and serves it as a browser-native ES module. Pinned to the same
     // version the React app at ../package.json depends on so both UIs behave
     // identically against the same testnet contract.
-    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@3.1.0-dev.1';
+    import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.0.0-rc.2';
 
     // The "anchor" data contract is already published on testnet by the React app.
     // Anyone querying with the same contract id hits the same documents.

_templates/sidebar-main.html

@@ -180,6 +180,26 @@
           DashMint Lab — NFT marketplace
          </a>
         </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/example-apps/dashnote.html">
+          Dashnote
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/example-apps/dashmint-lite.html">
+          DashMint Lite
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/example-apps/dashnote-lite.html">
+          Dashnote Lite
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/example-apps/dashproof-lite.html">
+          DashProof Lite
+         </a>
+        </li>
        </ul>
       </details>
      </li>
@@ -315,6 +335,11 @@
        DashPay
       </a>
      </li>
+     <li class="toctree-l1">
+      <a class="reference internal" href="docs/explanations/shielded-pool.html">
+       Shielded Pool
+      </a>
+     </li>
      <li class="toctree-l1">
       <a class="reference internal" href="docs/explanations/fees.html">
        Fees
@@ -330,6 +355,11 @@
        Non-Fungible Tokens (NFTs)
       </a>
      </li>
+     <li class="toctree-l1">
+      <a class="reference internal" href="docs/explanations/proofs.html">
+       Proofs
+      </a>
+     </li>
      <li class="toctree-l1">
       <a class="reference internal" href="docs/explanations/query.html">
        Query Capabilities
@@ -459,6 +489,11 @@
        Platform Address System
       </a>
      </li>
+     <li class="toctree-l1">
+      <a class="reference internal" href="docs/protocol-ref/shielded-pool.html">
+       Shielded Pool
+      </a>
+     </li>
      <li class="toctree-l1">
       <a class="reference internal" href="docs/protocol-ref/protocol-constants.html">
        Protocol Constants

conf.py

@@ -41,6 +41,7 @@
     '.DS_Store',
     'README.md',
     'CLAUDE.md',
+    'RELEASE.md',
     '.devcontainer',
     '.codex',
     '.local',

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).

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