docs(explanations): correct protocol behavior and fill gaps from audit

docs/explanations/dapi.md

@@ -31,4 +31,11 @@ retrieval.
 
 ## Endpoint Overview
 
-DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). The JSON-RPC endpoints expose some layer 1 information while the gRPC endpoints support layer 2. The layer 1 Core gRPC service additionally provides streaming of events related to blocks, transactions, and masternode-list updates; the layer 2 Platform endpoints are request/response only. For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md).
+DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/).
+
+- JSON-RPC endpoints are a small surface that mostly exposes layer 1 information, with the exception of a Platform status method
+- gRPC endpoints cover both Core and Platform:
+  - Core endpoints are mostly request/response, plus streaming subscriptions for block headers, transactions, and masternode-list updates
+  - Platform endpoints are request/response only.
+
+For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md).

docs/explanations/dashpay.md

@@ -78,7 +78,8 @@ DashPay has many constraints as defined in the [DashPay data
 contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v1/dashpay.schema.json).
 Additionally, the DashPay data triggers defined in
 [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay)
-enforce additional validation rules related to the `contactRequest` document.
+enforce additional validation rules related to the `contactRequest` document. Note: as a system data
+contract, the version active on a network is determined by that network's active protocol version.
 
 :::{tip}
 See the [DashPay Dash Improvement Proposal

docs/explanations/dpns.md

@@ -87,7 +87,8 @@ DPNS names have several constraints as defined in the [DPNS data contract](https
 1. Domain labels are converted to lowercase for case-insensitive uniqueness validation.
 1. To mitigate [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), `o` is replaced with `0` and `i`/`l` are replaced with `1`. For example, "Alice" is normalized to "a11ce".
 
-Additional validation rules related to the `domain` document are enforced by the DPNS [data triggers](../explanations/platform-protocol-data-trigger.md) defined in [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns).
+Additional validation rules related to the `domain` document are enforced by the DPNS [data triggers](../explanations/platform-protocol-data-trigger.md) defined in [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns). Note: as a system data
+contract, the version active on a network is determined by that network's active protocol version.
 
 ```{eval-rst}
 ..

docs/explanations/drive-platform-chain.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-The platform chain is the [Drive](../explanations/drive.md) component responsible for replicating the platform state across all evonodes participating in the network. Evonodes (the high-performance masternode tier) operate this Proof of Service (PoSe) chain to provide layer 2 consensus and support Dash Platform-specific requirements without impacting layer 1 functionality. Although the platform chain can read from the Dash layer 1 core blockchain, the core blockchain is not dependent on it or aware of it.
+The platform chain is the [Drive](../explanations/drive.md) component responsible for replicating the platform state across all evonodes participating in the network. Evonodes (the high-performance masternode tier) operate this chain to provide layer 2 consensus and support Dash Platform-specific requirements without impacting layer 1 functionality. Although the platform chain can read from the Dash layer 1 core blockchain, the core blockchain is not dependent on it or aware of it.
 
 ## Details
 
@@ -18,7 +18,7 @@ Early designs of Drive were based on using on the layer 1 core blockchain and [I
 
 In order to support Dash Platform's performance requirements, the platform chain has the following design characteristics:
 
-- Relies on masternode Proof of Service, not miner Proof of Work (PoW)
+- Secured by evonode quorums anchored to the core chain rather than by mining (Proof of Work)
 - Hosted exclusively on evonodes (the high-performance masternode tier)
 - Uses a [practical Byzantine Fault Tolerance (pBFT)](../reference/glossary.md#practical-byzantine-fault-tolerance-pbft) consensus algorithm
 - Has a deterministic fee structure

docs/explanations/drive-platform-state.md

@@ -27,3 +27,5 @@ Under the [Tenderdash](../explanations/platform-consensus.md) same-block executi
 ## Proofs
 
 Because state is stored in GroveDB, [DAPI](../explanations/dapi.md) queries can return GroveDB proofs alongside the requested data. Clients verify these proofs against the block header's `AppHash` (which itself is signed by the validator quorum), allowing light clients to trustlessly confirm the returned data without re-executing the chain.
+
+For additional detail on the two-layer verification model, see the [Proofs](../explanations/proofs.md) explanation.

docs/explanations/drive.md

@@ -17,18 +17,17 @@ There are a number of components working together to facilitate Drive's overall
 - [Platform chain](../explanations/drive-platform-chain.md) (orders state transitions; creates and propagates blocks of state transitions)
 - Platform state machine (validates data against the [Dash platform protocol](../explanations/platform-protocol.md); applies data to state and storage)
 - [Platform state](../explanations/drive-platform-state.md) (represents current data)
-- Storage (record of state transitions)
+- Storage (persists the current state - identities, data contracts, documents, etc.)
 - GroveDB (authenticated hierarchical storage backend enabling cryptographic proofs returned via [DAPI](../explanations/dapi.md))
 
 ### Data Update Process
 
 The process of adding or updating data in Drive consists of several steps to ensure data is validated, propagated, and stored properly. This description provides a simplified overview of the process:
 
 1. [State transitions](../explanations/platform-protocol-state-transition.md) are submitted to the platform via [DAPI](../explanations/dapi.md)
-2. DAPI broadcasts state transitions to Tenderdash, which validates them and includes them in block proposals
-3. Valid state transitions are applied to the platform state
-4. The platform chain propagates a block containing the state transitions
-5. Receiving nodes update Drive data based on the valid state transitions in the block
+2. DAPI relays state transitions to the platform chain's consensus engine (Tenderdash), which asks the platform state machine to validate them  and speculatively execute them when building or verifying a block proposal
+3. The block is propagated and voted on by validators
+4. Once the block is committed, each node finalizes it — persisting the speculative state changes to Drive, or executing the block if it was received via sync
 
 ```{eval-rst}
 .. figure:: ../../img/drive.svg

docs/explanations/fees.md

@@ -42,7 +42,7 @@ Refer to the [Identity explanation](../explanations/identity.md) section for inf
 
 ## Fee Multiplier
 
-The *Fee Multiplier* provides a mechanism to balance the cost of fees against network hosting requirements as the Dash price fluctuates. It is recorded per epoch and used when distributing collected fees from the credit pools, along with epoch accounting.
+The *Fee Multiplier* provides a mechanism to balance the cost of fees against network hosting requirements as the Dash price fluctuates. It is recorded per epoch and reported alongside epoch accounting information. At the active fee version it is a reserved parameter: it is not applied when distributing collected fees from the credit pools.
 
 The multiplier does not scale the fee a user is charged. The active fee version fixes it at 1.0x,
 and the final fee charged for a state transition is calculated using the complete formula below,
@@ -58,6 +58,8 @@ An in-depth look at the Fee Multiplier can be found at **link**
 
 In an attempt to minimize Dash Platform's storage requirements, users are incentivized to remove data that they no longer want to be stored in the Dash Platform state for a refund. Data storage fees are distributed to masternodes over the data's lifetime which is 50 years for permanent storage. Therefore, at any time before the data's fees are entirely distributed, there will be fees remaining which can be refunded to the user if they decide to delete the data.
 
+Distribution is front-loaded rather than spread evenly across those 50 years, so the refundable remainder falls fastest in the early years. Removals below a small minimum byte threshold are not refunded at all. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the distribution schedule and the refund threshold.
+
 ## User Fee Increase
 
 Platform supports a user fee increase that can be used to incentivize inclusion of a state
@@ -72,6 +74,8 @@ The high level formula for a state transition's fee is:
     fee = storageFee + processingFee + (processingFee * userFeeIncrease / 100) - storageRefund
 ```
 
+The storage refund is netted against the total rather than clamped at zero. A state transition that frees more storage than it consumes produces a net credit to the identity instead of a charge.
+
 <!-- Uncomment once DIP available
 See *DIPXX: Dash Platform Fee System* for a detailed breakdown of each component.
 -->

docs/explanations/identity.md

@@ -73,4 +73,4 @@ Note: the payout key is associated with the masternode owner identity, so both t
 
 Credits provide the mechanism for paying fees that cover the cost of platform usage. Once a user locks Dash on the core blockchain and proves ownership of the locked value in an identity create or topup state transition, their credit balance increases by that amount. Credits can also reach an identity from a [Platform address](../protocol-ref/address-system.md) or the [shielded pool](./shielded-pool.md) without a layer 1 lock. As they perform platform actions, these credits are deducted to pay the associated fees.
 
-Credits can be converted back to Dash using the identity credit withdrawal state transition, subject to a daily network-wide limit. That limit is a proportion of the total credits held on Platform rather than a fixed amount, so it grows and shrinks with the size of the network.
+Credits can be converted back to Dash using the identity credit withdrawal state transition, subject to a daily network-wide limit. That limit is a fixed amount defined by the protocol - currently 2000 Dash per day across the whole network. Because it is a versioned protocol parameter, the value can be changed by a protocol upgrade.

docs/explanations/nft.md

@@ -31,6 +31,8 @@ NFTs can be directly transferred or traded without the need for a marketplace, p
 * Transferring allows the owner to assign a new owner without making the NFT available for purchase.
 * Trading involves a two-step process where the seller sets the NFT's price, and the first buyer that matches this price receives the NFT automatically. Once the transaction is complete, the price is reset to prevent further immediate purchases, ensuring a non-interactive and seamless trading experience.
 
+A document type can also be configured so that each transfer, purchase, and price update is recorded on chain in Platform's document history system contract, giving an NFT a queryable provenance and sale history. Recording is off by default and, like the other document type options, is fixed when the document type is defined in the data contract. See [Document History Flags](../protocol-ref/data-contract-document.md#document-history-flags) in the protocol reference.
+
 ```{eval-rst}
 .. _explanations-nft-create-restrict:
 ```
@@ -77,7 +79,7 @@ Once the data contract design is completed, the contract can be registered on th
 
 ### Minting NFTs
 
-NFTs are minted by creating new documents under the data contract. Each NFT is an instance of one of the document types defined in the contract.
+NFTs are minted by creating new documents under the data contract. Each NFT is an instance of one of the document types defined in the contract. See the [submit documents tutorial](../tutorials/contracts-and-documents/submit-documents.md) for example code.
 
 ```{eval-rst}
 .. _explanations-nft-trade:
@@ -90,3 +92,5 @@ The trading process for Dash Platform NFTs is designed to be user-friendly and e
 Once an NFT is created, the owner can set a sale price to indicate the NFT is available for purchase. Interested buyers can then initiate a purchase by matching this set price. Upon completion of the transaction, the ownership of the NFT is automatically transferred to the buyer, and the sale price is reset to indicate the NFT is no longer available for purchase.
 
 Since the functionality needed to set a price, buy, and transfer ownership of NFTs is part of the protocol, the system handles all necessary trading operations directly. This provides an efficient trading experience that is integrated with the indexing and proof capabilities of Dash Platform.
+
+For example code, see the [set a document price](../tutorials/contracts-and-documents/set-a-document-price.md), [purchase documents](../tutorials/contracts-and-documents/purchase-documents.md), and [transfer documents](../tutorials/contracts-and-documents/transfer-documents.md) tutorials.

docs/explanations/platform-consensus.md

@@ -58,6 +58,7 @@ As with Tendermint, Tenderdash provides Byzantine Fault Tolerant (BFT) State Mac
 - The members of a quorum operate somewhat like validators but do so more efficiently due to the pre-existing BLS threshold signature.
 - BLS threshold signing results in more compact block headers since only a single BLS threshold signature is required instead of individual signatures from each validator. Notably, this means that any client can easily verify the block signatures using the deterministic masternode list.
 - The validators' signature is produced by an LLMQ, which is secured by the core blockchain’s Proof-of-Work (PoW).
+- Validators can attach signatures over additional data to their votes in the same consensus round. Dash Platform uses this to have the quorum collectively sign withdrawal transactions, so funds leaving Platform carry a signature the core chain can verify.
 
 This allows Dash Platform to leverage the best of both worlds - the speed and finality of Tendermint and the security of PoW.
 

docs/explanations/platform-protocol-data-contract.md

@@ -61,14 +61,14 @@ Permitted changes include:
 
 * Adding new document types
 * Adding new optional properties to existing document types
-* Adding non-unique indices for newly added properties
+* Adding non-unique indices on newly added document types
 * Adding new tokens to the contract
 * Adding new groups to the contract
 * Updating contract keywords and description
 
-Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, or altering existing unique indices. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update.
+Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, or altering the index definitions of an existing document type. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update.
 
-A contract update cannot remove or modify an existing token or group. Changing an existing token's configuration is done with a [token configuration update transition](../explanations/tokens.md#configuration-updates), governed by that token's own change control rules, and existing groups are permanently fixed once the contract is registered.
+A contract update cannot remove or modify an existing token or group. Changing an existing token's configuration is done with a [token configuration update transition](../explanations/tokens.md#configuration-updates), governed by that token's own change control rules, and existing groups are immutable once the contract is registered.
 
 Optional contract revision history storage allows contracts to retain a record of their revisions that can be retrieved and verified. Identity key access rules also allow an encryption or decryption key to be bound to a specific contract or document type for more granular key management.
 

docs/explanations/platform-protocol-data-trigger.md

@@ -16,7 +16,7 @@ Given a number of technical considerations (security, masternode processing capa
 
 ## Details
 
-Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action` so separate triggers can be created for the `CREATE`, `REPLACE`, or `DELETE` actions.
+Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action`, so a separate trigger can be created for any [document transition action](../explanations/platform-protocol-document.md#document-submission): `create`, `replace`, `delete`, `transfer`, `purchase`, and `updatePrice`.
 
 Which trigger runs for a given contract, document type, and action is defined in the data trigger [binding list](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v1/mod.rs). The trigger implementations linked in the tables below (for example the shared `reject` trigger) are generic and do not name the contracts that use them - the binding list is what associates each action with its trigger.
 
@@ -31,6 +31,8 @@ As an example, DPP contains several [data triggers for DPNS](https://github.com/
 
 :::{note}
 The `REPLACE` and `DELETE` rows for DPNS both link to the same shared `reject` trigger, which DPNS reuses to disallow those actions on `domain` documents. The DPNS `preorder` document type has no data triggers at all - its immutability comes from the contract schema rather than from trigger logic.
+
+The absence of a trigger matters too: DPNS `domain` documents deliberately have no trigger bound to the `transfer`, `purchase`, or `updatePrice` actions, so those actions fall through to generic document validation. That is what makes [username transfers and sales](../explanations/dpns.md#name-transfers-and-sales) possible, while `REPLACE` and `DELETE` remain rejected so name records stay immutable and permanent.
 :::
 
 In addition to DPNS, DPP ships data triggers for a small set of other system contracts: