v4.2/beta updates

docs/explanations/dashpay.md

@@ -43,8 +43,11 @@ The contract defines three document types: `contactRequest`, `profile` and `cont
 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.
+payment addresses (a Core chain address, a Platform address, and/or a shielded receiving
+address). Unlike contact-based payments, payments to the Core and Platform addresses are publicly
+linkable to the profile. Publishing a shielded address ties it to the profile, but shielded payments
+still hide the recipient on-chain. Platform checks its schema type and length; wallets must validate
+the shielded address before paying.
 * ContactInfo documents can be used to store private information about other Dash identities.
 
 ### Establishing a Contact
@@ -83,7 +86,7 @@ contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contr
 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 and, since Dash Platform
-v4.2, the payment address fields of the `profile` document. Note: as a system data
+v4.2, the Core and Platform 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}
@@ -177,6 +180,14 @@ information and complete details about the data contract.
         "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
+      },
+      "shieldedAddress": {
+        "type": "array",
+        "byteArray": true,
+        "minItems": 43,
+        "maxItems": 43,
+        "description": "Raw Orchard receiving address: 11-byte diversifier followed by 32-byte diversified transmission key. Clients validate before payment; wallets should use a dedicated tip account.",
+        "position": 7
       }
     },
     "minProperties": 1,

docs/explanations/identity.md

@@ -51,6 +51,8 @@ Since anyone can topup either their own account or any other account, applicatio
 
 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.
 
+From protocol version 14, non-master authentication keys can be bound to a contract, a document type, or a [contract group](../explanations/platform-protocol-data-contract.md#contract-groups), restricting them to batch transitions within those bounds. They can also carry a credit budget and an expiry time. Transitions are rejected once the budget is exhausted or the block time reaches the expiry. Credits moved out of the identity, storage fees, fixed fees, and voluntary fee increases must fit in the remaining budget; metered processing fees may exceed it.
+
 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

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

@@ -39,6 +39,12 @@ Each document type's schema also determines how applications can query and relat
 
 For a practical example, see the [DashPay contract](#example-contract).
 
+### Contract Groups
+
+From protocol version 14, contract groups organize contracts, document types, and tokens into an identity-owned collection. They can scope [authentication keys](../explanations/identity.md#keys) to those members. These are separate from [token groups](../explanations/tokens.md#groups), whose member identities jointly authorize token actions.
+
+When registering a contract, the creation transition can also register a contract group, optionally with admins, and declare memberships for the new contract, its document types, or its tokens in groups the creating identity owns or administers.
+
 ### Registration
 
 Once a [Dash Platform Protocol](../explanations/platform-protocol.md) compliant data contract has been defined, it may be registered on the platform. Registration is completed by submitting a state transition containing the data contract to [DAPI](../explanations/dapi.md).
@@ -71,7 +77,7 @@ Restricted changes include modifications that would break existing stored docume
 
 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.
+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. From protocol version 14, non-master authentication keys can also be bound to a contract, document type, or contract group, restricting them to batch transitions within those bounds. See [Identity keys](../explanations/identity.md#keys).
 
 :::{note}
 For more detailed information, see the [Platform Protocol Reference - Data Contract](../protocol-ref/data-contract.md) page.

docs/explanations/proofs.md

@@ -68,12 +68,14 @@ Dash Platform supports proofs for all core data types:
 - Identity existence and full details
 - Identity balance and revision
 - Public keys associated with an identity
+- Remaining credit budget of identity keys that carry one (from protocol version 14)
 - Identity nonces (for replay protection)
 
 **Data Contracts**
 
 - Contract existence and contents
 - Contract history (for contracts that track changes)
+- Contract version on its own, without the contract contents, so a client can check whether a cached contract is current (from protocol version 14; earlier versions prove the whole contract)
 
 **Documents**
 
@@ -96,6 +98,11 @@ Dash Platform supports proofs for all core data types:
 - Group state and member powers
 - Group action status and the votes recorded against it
 
+**Contract Groups** (from protocol version 14)
+
+- Contract group owner, admins, name, and description
+- The contracts, document types, and tokens in a contract group, and the contract groups a contract belongs to
+
 **Address System**
 
 - [Platform address](../protocol-ref/address-system.md) balances

docs/explanations/shielded-pool.md

@@ -78,6 +78,8 @@ The funding amount cannot be chosen freely: it must be one of a small fixed set
 
 The notes being spent do not have to add up to the chosen denomination exactly - any excess is returned to the pool as a new note, so change stays shielded. If identity creation then fails a stateful check, the denomination still leaves the pool: it lands, less a penalty, at a fallback Platform address named in the transition.
 
+From protocol version 14, keys with a budget, an expiry, or a contract group binding cannot be registered when creating an identity from the pool. Add these keys afterward through an identity update.
+
 ### Shield from identity
 
 Moves credits *into* the pool from an identity's balance, without first moving them to a Platform address. Available from protocol version 14.

docs/explanations/tokens.md

@@ -71,7 +71,7 @@ The initial token implementation includes all actions required to create, use, a
 #### Claim
 
 - Claim tokens that have been allocated to an identity by a [distribution rule](#distribution-rules) but not yet credited to its balance. Claim covers both:
-  - **Perpetual distributions** - tokens continuously emitted on a block or time schedule that recipients must pull in order to take ownership.
+  - **Perpetual distributions** - tokens continuously emitted on a block, time, or epoch schedule that recipients must pull in order to take ownership.
   - **Pre-programmed distributions** - tokens scheduled for specific recipients at specific times that recipients must claim to receive.
 - Each claim collects a bounded number of unclaimed perpetual distribution intervals (128 for variable-rate distribution functions), so recipients with a long backlog may need to claim more than once to collect everything owed.
 

docs/intro/testnet.md

@@ -10,7 +10,7 @@ Testnet is the Dash testing network used for experimentation and evaluation of D
 
 ### Infrastructure
 
-Dash Core Group provides the core Testnet infrastructure consisting of 150 masternodes running Dash Core along with the platform services that provide the [decentralized API (DAPI)](../explanations/dapi.md) and [storage (Drive)](../explanations/drive.md) functionality.
+Dash Core Group provides the core Testnet infrastructure consisting of ~50 masternodes running Dash Core plus ~30 evonodes that also run the platform services that provide the [decentralized API (DAPI)](../explanations/dapi.md) and [storage (Drive)](../explanations/drive.md) functionality.
 
 Testnet also includes a [block explorer](https://insight.testnet.networks.dash.org/insight/) for the core blockchain and a [test Dash faucet](https://faucet.testnet.networks.dash.org/) that dispenses funds to users/developers experimenting on the network.
 

docs/intro/what-is-dash-platform.md

@@ -61,9 +61,9 @@ verification, making it practical for light clients and user-facing applications
 
 ### DAPI - A decentralized API
 
-DAPI is a _decentralized_ HTTP API exposing [gRPC](https://grpc.io/) and [JSON-RPC](https://www.jsonrpc.org/) endpoints. Developers send and retrieve Dash Platform application data over the gRPC endpoints, while the JSON-RPC endpoints expose some layer 1 (Dash Core blockchain) information.
+DAPI is a _decentralized_ HTTP API exposing [gRPC](https://grpc.io/) and [JSON-RPC](https://www.jsonrpc.org/) endpoints. Developers send and retrieve Dash Platform application data over the gRPC endpoints, while the JSON-RPC endpoints expose some Dash Core blockchain information.
 
-DAPI provides developers the same access and security as running their own Dash node without the cost and maintenance overhead. Unlike traditional APIs which have a single point of failure, DAPI allows clients to connect to different instances depending on resource availability in the Dash network.
+DAPI provides access to Dash network services without the cost and maintenance overhead of running a node. Clients can verify supported Platform responses using cryptographic proofs. Unlike traditional APIs which have a single point of failure, DAPI allows clients to connect to different instances depending on resource availability in the Dash network.
 
 Developers can connect to DAPI directly or use higher-level SDKs and client libraries maintained in
 the Dash Platform monorepo. These libraries handle connection management, data serialization, and
@@ -78,7 +78,7 @@ The source for these components is available on GitHub:
 
 Drive is Dash Platform's storage component, allowing for consensus-based verification and validation of user-created data. In order for this to occur, developers create a [data contract](../explanations/platform-protocol-data-contract.md). This data contract describes the data structures that comprise an application, similar to creating a schema for a document-oriented database like MongoDB.
 
-Data created by users of the application is validated and verified against this contract. Upon successful validation/verification, application data is submitted to Drive (via DAPI), where it is stored on the masternode network. Drive uses Dash's purpose-built database, [GroveDB](https://github.com/dashpay/grovedb/), to provide efficient proofs with query responses, so you don't have to trust the API provider to be certain your data is authentic.
+Users submit application data in state transitions through DAPI. The network validates the data against its data contract before storing accepted changes in Drive. Drive uses Dash's purpose-built database, [GroveDB](https://github.com/dashpay/grovedb/), to provide efficient proofs with query responses, so you don't have to trust the API provider to be certain your data is authentic.
 
 The source is available on GitHub:
 

docs/intro/what-is-dash.md

@@ -24,15 +24,15 @@ Most of Dash's technical innovations are described in greater detail elsewhere i
 
 ### Instantly Confirmed Transactions
 
-All transactions are automatically sent and received instantly at no extra cost. Transaction security and decentralization are not compromised, due to the ChainLocks innovation. As a result, using Dash to transact means getting the speed and fungibility of fiat currency, while simultaneously having the lower costs, privacy, and security of funds of a blockchain-based network.
+Dash transactions benefit from automatic, near-instant confirmation through InstantSend at no extra cost. Transaction security and decentralization are not compromised, due to the ChainLocks innovation. As a result, using Dash to transact means getting the speed and fungibility of fiat currency, while simultaneously having the lower costs, privacy, and security of funds of a blockchain-based network.
 
 ## Key Features
 
 ### Masternodes
 
-The most important differentiating feature of the Dash payments network is the concept of a **masternode**. On a traditional p2p network, nodes participate equally in the sharing of data and network resources. These nodes are all compensated equally for their contributions toward preserving the network.
+The most important differentiating feature of the Dash payments network is the concept of a **masternode**. On a traditional p2p network, nodes participate equally in the sharing of data and network resources.
 
-However, the Dash network has a second layer of network participants that provide enhanced functionality in exchange for greater compensation. This second layer of masternodes is the reason why Dash is the most secure payments network, and can provide industry-leading features such as instant transaction settlement and usernames.
+However, the Dash network has a second layer of network participants that provide enhanced functionality in exchange for compensation. This second layer of masternodes is the reason why Dash is the most secure payments network, and can provide industry-leading features such as instant transaction settlement and usernames.
 
 ### Long-Living Masternode Quorums
 

docs/protocol-ref/address-system.md

@@ -214,16 +214,18 @@ Withdraw credits from Platform addresses back to the Core chain.
 | inputs          | map              | Varies   | Map of source [Platform addresses](#platform-address) to (nonce, credits) pairs                                      |
 | output          | tuple            | Varies   | (Optional) Change output as (Platform address, credits)                                                              |
 | feeStrategy     | array            | Varies   | [Fee deduction strategy](#fee-strategy)                                                                              |
-| coreFeePerByte  | unsigned integer | 32 bits  | Core transaction fee per byte (must be a [Fibonacci number](https://en.wikipedia.org/wiki/Fibonacci_sequence) ≥ 1)   |
+| coreFeePerByte  | unsigned integer | 32 bits  | Core transaction fee per byte (must be a [Fibonacci number](https://en.wikipedia.org/wiki/Fibonacci_sequence) ≥ 1; at most 6,765 from protocol version 14)   |
 | pooling         | unsigned integer | 8 bits   | Pooling mode: `0` = Never (required), `1` = IfAvailable, `2` = Standard                                              |
 | outputScript    | array of bytes   | Varies   | Core chain destination script (P2PKH or P2SH only)                                                                   |
 | userFeeIncrease | unsigned integer | 16 bits  | Extra fee to prioritize processing if the mempool is full                                                            |
 | inputWitnesses  | array            | Varies   | [Address witnesses](#address-witness) for each input                                                                 |
 
 :::{note}
-**Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Minimum per input: 100,000 credits. Minimum output: 500,000 credits. Pooling must be `Never` (others not yet implemented). Output script must be P2PKH or P2SH. The withdrawn amount (input sum minus the change output) must be greater than zero and within the [min and max withdrawal amount](protocol-constants.md) limits.
+**Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Minimum per input: 100,000 credits. Minimum output: 500,000 credits. Pooling must be `Never` (others not yet implemented). Output script must be P2PKH or P2SH. The withdrawn amount (input sum minus the change output) must be greater than zero and within the [min and max withdrawal amount](protocol-constants.md) limits. From protocol version 14 the Core fee of the withdrawal transaction (190 bytes x `coreFeePerByte` duffs, or 190,000 x `coreFeePerByte` credits) is taken from the withdrawn amount, so the amount must be at least the minimum withdrawal amount plus that fee (1,190,000 credits at `coreFeePerByte` 1). `coreFeePerByte` above 6,765 is rejected.
 
 **Fee:** 400,000,000 credits + 500,000 per input + 6,000,000 for the change output (if present). Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain.
+
+At `coreFeePerByte` 6,765, the minimum withdrawn amount is 1,286,350,000 credits. The recipient receives the input sum minus the change output and Core fee. A fee rate above the cap is rejected with error `10522`, and an amount below the fee-inclusive minimum with `10818`.
 :::
 
 See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_credit_withdrawal_transition/).