docs: platform v4.2 updates

docs/explanations/dapi.md

@@ -22,7 +22,7 @@ To overcome these obstacles, the Dash decentralized API (DAPI) uses Dash's robus
 
 ## Security
 
-DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data.
+DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. TLS is terminated by a gateway that runs in front of the DAPI service on each masternode; the gateway also applies rate limiting. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data.
 
 :::{note}
 See the [Query Capabilities page](./query.md) for more detailed information regarding Platform data
@@ -34,7 +34,7 @@ retrieval.
 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:
+- gRPC endpoints cover both Core and Platform.  They are also served over gRPC-Web on the same port, so browser clients can call masternodes without a separate proxy (subject to the node presenting a browser-trusted TLS certificate):
   - Core endpoints are mostly request/response, plus streaming subscriptions for block headers, transactions, and masternode-list updates
   - Platform endpoints are request/response only.
 

docs/explanations/dashpay.md

@@ -38,10 +38,14 @@ The DashPay contract enables an improved Dash wallet experience with features in
 ## Details
 
 The contract defines three document types: `contactRequest`, `profile` and `contactInfo`.
-ContactRequest documents are the most important. They are used to establish relationships and
-payment channels between Dash identities. Profile documents are used to store public facing
-information about Dash identities including avatars and display names. ContactInfo documents can be
-used to store private information about other Dash identities.
+
+* ContactRequest documents are the most important. They are used to establish relationships and
+payment channels between Dash identities.
+* Profile documents are used to store public facing information about Dash identities including
+avatars and display names. Since Dash Platform v4.2, a profile can also publish optional public
+payment addresses (a Core chain address and/or a Platform address). Unlike contact-based payments,
+payments to these addresses are publicly linkable to the profile.
+* ContactInfo documents can be used to store private information about other Dash identities.
 
 ### Establishing a Contact
 
@@ -75,10 +79,11 @@ used to store private information about other Dash identities.
 ### Implementation
 
 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).
+contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v2/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. Note: as a system data
+enforce additional validation rules related to the `contactRequest` document and, since Dash Platform
+v4.2, the payment address fields of the `profile` document. Note: as a system data
 contract, the version active on a network is determined by that network's active protocol version.
 
 :::{tip}
@@ -156,6 +161,22 @@ information and complete details about the data contract.
         "minLength": 1,
         "maxLength": 25,
         "position": 4
+      },
+      "corePaymentAddress": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 21,
+        "maxItems": 21,
+        "description": "Core chain address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger; clients render the address as Base58Check for the network they are on. Payments to it are publicly linkable to this profile.",
+        "position": 5
+      },
+      "platformPaymentAddress": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 21,
+        "maxItems": 21,
+        "description": "Platform address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger.",
+        "position": 6
       }
     },
     "minProperties": 1,

docs/explanations/dpns.md

@@ -29,7 +29,7 @@ To prevent [front-running](https://en.wikipedia.org/wiki/Domain_name_front_runni
 
 #### Domain pre-order
 
-In the pre-order phase, the domain name is salted to obscure the actual domain name being registered (e.g. `hash('alice.dash' + salt)`) and submitted to platform. This is done to prevent masternodes from seeing the names being registered and "stealing" them for later resale. Once the pre-order receives a sufficient number of confirmations, the registration can proceed.
+In the pre-order phase, a random 32-byte salt is placed in front of the normalized domain name and the pair is hashed with a double SHA-256 (e.g. the hash of the salt followed by `a11ce.dash`). Only that hash is submitted to Platform, preventing observers from identifying the requested name and front-running its registration. Once the pre-order document has been accepted by Platform, the registration can proceed.
 
 #### Domain registration
 
@@ -50,7 +50,7 @@ All other available names can be registered immediately.
 
 #### Timeline
 
-A two-week voting window begins when a name matching the criteria above is requested. Additional identities can request the same name during the first week of the voting window.
+On mainnet, a two-week voting window begins when a name matching the criteria above is requested. Additional identities can request the same name during the first week of the voting window. Test networks use much shorter windows (currently 90 minutes, with a 45-minute join period). Both durations are versioned protocol parameters.
 
 #### Voting details
 
@@ -64,7 +64,7 @@ As with governance voting, evonode votes are worth four, and regular masternode
 
 After voting ends, the name is either awarded to one of the identities or locked. The outcome is based on which item receives the most votes.
 
-Assuming masternodes do not vote to lock, the identity receiving the most votes takes ownership of the name. However, if the vote locks the name, no identity receives it. If only one identity requests the name, they will receive it even if no masternodes vote.
+Assuming masternodes do not vote to lock, the identity receiving the most votes takes ownership of the name. However, if the vote locks the name, no identity receives it. If only one identity requests the name, they will receive it even if no masternodes vote. If lock votes tie with the leading identity, the identity wins; ties between identities are resolved deterministically by the protocol.
 
 :::{note}
 Locked names cannot currently be re-requested or awarded. This policy may be revisited in future Platform releases.

docs/explanations/drive-platform-chain.md

@@ -26,4 +26,4 @@ In order to support Dash Platform's performance requirements, the platform chain
 
 ### Blocks and Transitions
 
-Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among all masternodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by a ⅔ + 1 majority of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations.
+Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among evonodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by more than two-thirds of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations.

docs/explanations/drive.md

@@ -27,7 +27,7 @@ The process of adding or updating data in Drive consists of several steps to ens
 1. [State transitions](../explanations/platform-protocol-state-transition.md) are submitted to the platform via [DAPI](../explanations/dapi.md)
 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
+4. Once the block is committed, each node finalizes it, persisting to Drive the state changes it computed while processing the proposal. Nodes catching up on the chain execute each block the same way before finalizing it
 
 ```{eval-rst}
 .. figure:: ../../img/drive.svg

docs/explanations/fees.md

@@ -58,7 +58,13 @@ 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.
+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 storage era counts and the refund threshold.
+
+## Minimum and Fixed Fees
+
+In addition to the usage-based costs above, most identity- and address-funded transitions require a protocol-defined minimum balance before processing. This is a balance floor rather than a flat charge; the fee actually deducted is still the storage and processing total.
+
+[Shielded pool](../explanations/shielded-pool.md) transitions that pay from the pool (shielded transfers, unshields, and shielded withdrawals) are the exception. Their costs cannot be charged to an address balance, so they pay a fixed schedule from the pool: a proof verification fee, a per-action fee, and a per-action storage allowance. Transitions that shield funds are charged for storage normally and add only the proof verification and per-action components. These constants are versioned protocol parameters and were rebalanced at protocol version 14. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the current values.
 
 ## User Fee Increase
 

docs/explanations/identity.md

@@ -20,7 +20,7 @@ In order to [create an identity](#identity-create-process), a user pays the netw
 
 Once an identity is created, its credit balance is used to pay for activity (e.g. use of applications). The [topup process](#identity-balance-topup-process) provides a way to add additional funds to the balance when necessary.
 
-Locking Dash on layer 1 is the primary funding route, but it is not the only one. An identity can also be created or topped up from credits already held at a [Platform address](../protocol-ref/address-system.md), or created directly from the [shielded pool](./shielded-pool.md) by spending shielded notes. Both routes fund the identity entirely on layer 2, without a Core chain asset lock.
+Locking Dash on layer 1 is the primary funding route, but it is not the only one. An identity can also be created or topped up from credits already held at a [Platform address](../protocol-ref/address-system.md), or created and topped up directly from the [shielded pool](./shielded-pool.md) by spending shielded notes. Both routes fund the identity entirely on layer 2, without a Core chain asset lock.
 
 The processes below describe the Core-chain asset-lock path. For the layer 2 paths, see
 [Identity Create From Addresses](../protocol-ref/address-system.md#identity-create-from-addresses),
@@ -35,7 +35,7 @@ On Testnet, a [test Dash faucet](https://faucet.testnet.networks.dash.org/) is a
 
 First, the user creates an asset lock transaction on the Core chain with one or more outputs that lock Dash funds for use on Platform. An asset lock proof is then obtained for that transaction - either an InstantSend lock proof (for fast confirmation) or a ChainLock-based proof once the transaction is included in a ChainLocked block.
 
-The user then submits an [identity create state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-create-transition) referencing the asset lock proof and the public keys to register for the new identity. The locked value (minus fees) becomes the new identity's initial credit balance.
+The user then submits an [identity create state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-create-transition) referencing the asset lock proof and the public keys to register for the new identity. The locked value, minus fees, is converted to credits and becomes the new identity's initial balance.
 
 Application-layer flows where a third party funds an identity on behalf of another user are possible by having that third party create the asset lock transaction and share the resulting proof, but this is a client-side convention rather than a protocol-level invitation mechanism.
 
@@ -47,6 +47,12 @@ The identity balance topup process works in a similar way to the initial identit
 Since anyone can topup either their own account or any other account, application developers can easily subsidize the cost of using their application by topping up their user's identities.
 :::
 
+### Keys
+
+Each identity key has a purpose, a security level, and a cryptographic key type. Its purpose defines how the key may be used (for example authentication, encryption, decryption, transferring credits, or voting), while its security level indicates how strongly clients should protect it and which signing requirements it can satisfy. A master key controls changes to the identity's keys, while a transfer key controls its credits. More keys can be added later through an identity update.
+
+Data contracts can require a property to refer to an existing identity or, since Dash Platform v4.2, to a specific identity key. See [property references](../reference/data-contracts.md#platform-specific-property-keywords) and the [identity protocol reference](../protocol-ref/identity.md#identity-publickeys) for details.
+
 ### Identity Update Process
 
 Identity owners may find it necessary to update their identity keys periodically for security purposes. The [identity update state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-update-transition) enables users to add new keys and disable existing ones.
@@ -65,12 +71,14 @@ All masternodes can use their identities to vote on Platform polls for contested
 
 #### Reward distribution
 
-Evonodes receive their Platform-specific block rewards and Platform fees with their masternode identity. The credits paid as state transition fees are distributed to masternode-related identities similar to how rewards are currently distributed to masternodes on the core blockchain. Credits are split between owner and operator in the same ratio as on layer 1, and masternode owners have the flexibility to further split their portion between multiple identities to support reward-sharing use cases.
+Evonodes receive their Platform-specific block rewards and Platform fees with their masternode identity. The credits paid as state transition fees are distributed to masternode-related identities similar to how rewards are currently distributed to masternodes on the core blockchain. Each masternode's share of an epoch's fees and rewards is paid to its owner identity. The protocol also defines a reward-sharing mechanism that lets a masternode owner direct portions of that payout to other identities. See the [data trigger reference](../protocol-ref/data-trigger.md#other-system-contract-triggers) for current restrictions on reward share records.
 
 Note: the payout key is associated with the masternode owner identity, so both the owner and payout keys should be controlled by the same party.
 
 ## Credits
 
-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 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, that value is converted to credits and added to their balance, with each duff of locked Dash becoming 1000 credits. 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 are not locked to the identity that holds them: an identity can transfer credits directly to another identity, or to a [Platform address](../protocol-ref/address-system.md), using the corresponding [state transitions](../explanations/platform-protocol-state-transition.md).
 
-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.
+Credits can be converted back to Dash using an identity credit withdrawal state transition. Withdrawals are subject to per-withdrawal and network-wide limits that constrain Platform's net daily outflow. These limits are versioned protocol parameters; see the [protocol constants reference](../protocol-ref/protocol-constants.md#withdrawal-constants) for current values.