From 2db355c7bce9aff129ff16926f501ea5c12dd37b Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 5 Aug 2026 09:06:58 -0400 Subject: [PATCH 01/17] docs(explanations): apply v4.1.0 audit findings across explanation pages DPNS domain documents no longer reject TRANSFER, PURCHASE and UPDATE_PRICE as of protocol version 13. Add a concept-level "Name transfers and sales" section to the DPNS page covering transfer and sale, resolution to the new owner, the name record staying immutable, and recorded ownership and pricing history. Repoint both DPNS contract schema links to schema/v2. Note on the data contract page that a document type's history-recording choice is fixed at creation and cannot be changed by a later contract update. Add an Aggregate Queries section to the query explanation so the explanation layer has an entry point to count, total and average queries, cross-referencing the query syntax reference. Repin the token configuration source links from v4.0.0 to v4.1.0, updating the base supply anchor from #L498 to #L606. Co-Authored-By: Claude Opus 5 --- docs/explanations/dpns.md | 10 ++++++++-- docs/explanations/platform-protocol-data-contract.md | 2 +- docs/explanations/platform-protocol-data-trigger.md | 7 ++----- docs/explanations/query.md | 11 +++++++++++ docs/explanations/tokens.md | 4 ++-- 5 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index f64bbc886..145771aee 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -70,14 +70,20 @@ Assuming masternodes do not vote to lock, the identity receiving the most votes Locked names cannot currently be re-requested or awarded. This policy may be revisited in future Platform releases. ::: +### Name transfers and sales + +Registering a name is not necessarily the end of its lifecycle. Since Dash Platform v4.1, a registered name can be transferred to another identity or offered for sale and bought by another identity. Once ownership changes, the name resolves to its new owner, and that identity's private keys are what prove ownership from then on. + +The name record itself remains immutable and permanent: it cannot be edited or deleted, only transferred or sold. A name's transfer, purchase, and listing history is recorded, so the chain of ownership and the prices it was offered at can be retrieved and verified. + ### Implementation -DPNS names have several constraints as defined in the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json). The constraints provide compatibility with DNS and protection from homograph attacks: +DPNS names have several constraints as defined in the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json). The constraints provide compatibility with DNS and protection from homograph attacks: 1. Minimum length - 3 characters 1. Maximum length - 63 characters 1. Usable characters - `0-9`, `-` (hyphen), `a-z`, and `A-Z` (case sensitive) - * Note: Use of `-` as a prefix/suffix to a name is _not_ allowed (e.g. `-name` or `name-`). This constraint is defined by this JSON-Schema [pattern](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L44) in the DPNS data contract: `"^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$"` + * Note: Use of `-` as a prefix/suffix to a name is _not_ allowed (e.g. `-name` or `name-`). This constraint is defined by this JSON-Schema [pattern](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json#L47) in the DPNS data contract: `"^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$"` 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". diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md index 0d5ffb58f..f539e47ac 100644 --- a/docs/explanations/platform-protocol-data-contract.md +++ b/docs/explanations/platform-protocol-data-contract.md @@ -65,7 +65,7 @@ Permitted changes include: * Updating token configuration where the contract's rules authorize changes (for example via the configured main control group) * 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. +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. 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. diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index 69aaa37d7..c0e9263b8 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -20,7 +20,7 @@ Since all application data is submitted in the form of documents, data triggers 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/v0/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. -As an example, DPP contains several [data triggers for DPNS](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns). The `domain` document has added constraints for creation, replacing, deleting, transferring, purchasing, and updating prices: +As an example, DPP contains several [data triggers for DPNS](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns). The `domain` document has added constraints for creation, replacing, and deleting: | Data Contract | Document | Action(s) | Trigger Description | | - | - | - | - | @@ -28,12 +28,9 @@ As an example, DPP contains several [data triggers for DPNS](https://github.com/ | ---- | ----| ---- | ---- | | DPNS | `domain` | [`REPLACE`](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs) | Prevents updates to any DPNS document type | | DPNS | `domain` | [`DELETE`](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs) | Prevents deletion of any DPNS document type | -| DPNS | `domain` | [`TRANSFER`](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs) | Prevents transfer of any DPNS document type | -| DPNS | `domain` | [`PURCHASE`](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs) | Prevents purchase of any DPNS document type | -| DPNS | `domain` | [`UPDATE_PRICE`](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs) | Prevents price updates on any DPNS document type | :::{note} -The `REPLACE`, `DELETE`, `TRANSFER`, `PURCHASE`, and `UPDATE_PRICE` rows for DPNS all link to the same shared `reject` trigger, which DPNS reuses to disallow those actions on `domain` documents. +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. ::: In addition to DPNS, DPP ships data triggers for a small set of other system contracts: diff --git a/docs/explanations/query.md b/docs/explanations/query.md index 26b6011bd..b1df3eb48 100644 --- a/docs/explanations/query.md +++ b/docs/explanations/query.md @@ -63,3 +63,14 @@ Benefits of indexed querying include: Indexes should be planned during contract design since there are [limited index update options](./platform-protocol-data-contract.md#updates) for already registered contracts. ::: + +## Aggregate Queries + +Beyond returning whole documents, Dash Platform can compute a value over the set of documents a query +matches - how many there are, their total, or their average - and return that instead of the documents +themselves. Results can optionally be grouped, so a single query returns one value per group. + +Aggregates are not available on every document type. The contract must opt in for the document type +being queried, which means this is another decision to make during contract design. See the +[query syntax reference](../reference/query-syntax.md#aggregate-queries) for the supported aggregates +and how to request them. diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index 812dd6ec7..322e296b1 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -107,8 +107,8 @@ When creating a token, you define its configuration using the following paramete |:------------------------|:------------------|:--------| | Description | Yes | None | | [Conventions](#display-conventions) | Yes | N/A. Depends on implementation | -| [Decimal precision](#display-conventions)| Yes | [8](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs#L47) | -| [Base supply](#token-supply) | **No** | [100000](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L498) | +| [Decimal precision](#display-conventions)| Yes | [8](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs#L47) | +| [Base supply](#token-supply) | **No** | [100000](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L606) | | [Maximum supply](#token-supply) | Yes | None | | [Keep history](#history) | Yes | True (all history types) | | [Start paused](#initial-state) | Yes | False | From bda9970cc1208ee173c20bcc71797957bd0de919 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 5 Aug 2026 09:27:22 -0400 Subject: [PATCH 02/17] docs(tutorials): apply v4.1.0 audit findings to node and build tutorials Update the build prerequisites to match the platform workspace at v4.1.0. Correct the local devnet quorum sidecar port from 2444 to 22444. The dashmate local config overrides the base-config default, and the wasm-sdk local context provider uses 22444. Drop the claim that Testnet operates on Dash Core v19.3.0. Replace the deprecated js-dash-sdk local connection snippet on the masternode page with EvoSDK.localTrusted(), matching the rest of the tutorials, and link to the local devnet section. Point node operators at the platform release notes for per-release upgrade steps and breaking changes. Co-Authored-By: Claude Opus 5 (1M context) --- docs/tutorials/building-platform.md | 12 ++++++++---- docs/tutorials/connecting-to-testnet.md | 2 +- .../connect-to-a-network-dash-core-full-node.md | 2 +- .../connect-to-a-network-dash-masternode.md | 14 ++++++++------ 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/tutorials/building-platform.md b/docs/tutorials/building-platform.md index d01215c4b..e44a9b434 100644 --- a/docs/tutorials/building-platform.md +++ b/docs/tutorials/building-platform.md @@ -35,7 +35,7 @@ nvm install 20.18 ### Docker :::{warning} -Only complete the following steps if you do not already have Docker installed. Otherwise, just make sure you have a version that meets the requirements in the [Platform repository README](https://github.com/dashpay/platform?tab=readme-ov-file#how-to-build-and-set-up-a-node-from-the-code-in-this-repo). +Only complete the following steps if you do not already have Docker installed. Otherwise, just make sure you have a version that meets the requirements in the [Platform book's Getting Started section](https://github.com/dashpay/platform/blob/master/book/src/getting-started.md). ::: ``` shell @@ -54,7 +54,7 @@ newgrp docker ### Protocol buffers ``` shell -wget https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-linux-x86_64.zip +wget https://github.com/protocolbuffers/protobuf/releases/download/v32.0/protoc-32.0-linux-x86_64.zip sudo unzip protoc-*-linux-x86_64.zip -d /usr/local ``` @@ -65,15 +65,19 @@ Execute the following script to install Rust. Use the default options during the ``` shell curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh . "$HOME/.cargo/env" -rustup default 1.85.0 +rustup default 1.92 ``` ### WASM CLI ``` shell -cargo install wasm-bindgen-cli@0.2.100 +cargo install wasm-bindgen-cli@0.2.108 ``` +:::{note} +The `wasm-bindgen-cli` version must match the `wasm-bindgen` version in the platform repository's `Cargo.lock`, or the build will stop at a version check. Confirm the required version with `grep 'name = "wasm-bindgen"' -A1 Cargo.lock`. +::: + ### Check versions Run the following commands to see what version of each package is installed: diff --git a/docs/tutorials/connecting-to-testnet.md b/docs/tutorials/connecting-to-testnet.md index 6074bcf30..4fa78d6ed 100644 --- a/docs/tutorials/connecting-to-testnet.md +++ b/docs/tutorials/connecting-to-testnet.md @@ -51,7 +51,7 @@ Once this returns successfully, you're ready to begin developing! See the [Quick ## Connect to a Local Devnet -The SDK supports connecting to a local development network managed by [dashmate](https://github.com/dashpay/platform/tree/master/packages/dashmate). The `local` factory methods expect a dashmate-managed environment with a quorum sidecar running at `127.0.0.1:2444`. +The SDK supports connecting to a local development network managed by [dashmate](https://github.com/dashpay/platform/tree/master/packages/dashmate). The `local` factory methods expect a dashmate-managed environment with a quorum sidecar running at `127.0.0.1:22444`. ```{code-block} javascript :caption: localConnect.mjs diff --git a/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md b/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md index 8db9f5a4c..7206f6681 100644 --- a/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md +++ b/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md @@ -8,7 +8,7 @@ Since Dash Platform is fully accessible via DAPI, running a full node is unneces ## Config File - The config file shown below may be used to connect a Dash Core node to Testnet. Testnet currently operates using [Dash Core v19.3.0](https://github.com/dashpay/dash/releases/tag/v19.3.0). + The config file shown below may be used to connect a Dash Core node to Testnet. ```ini dash-testnet.conf # dash-testnet.conf 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 8d007fe21..e68f8c763 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 @@ -116,23 +116,25 @@ Example output of `dashmate wallet mint 10 --address=yYqfdpePzn2kWtMxr9nz22HBFM7 Once the address is funded, you can begin creating identities, data contracts, etc. and experimenting with Dash Platform. The [other tutorials](../../tutorials/introduction.md) in this section will help you get started. -To make the Dash SDK connect to your local network, set the `network` option to `'local'`: +To make the Dash SDK connect to your local network, use the `localTrusted()` factory method: ```javascript -const clientOpts = { - network: 'local', - ... -}; +import { EvoSDK } from '@dashevo/evo-sdk'; -const client = new Dash.Client(clientOpts); +const sdk = EvoSDK.localTrusted(); +await sdk.connect(); ``` +See [Connect to a Local Devnet](../connecting-to-testnet.md#connect-to-a-local-devnet) for more detail. + ## Testnet Masternode Setup :::{important} Running a masternode requires familiarity with Dash Platform services. Improper configuration may impact testing so please exercise caution if running a masternode. ::: +When upgrading an existing node, check the [platform release notes](https://github.com/dashpay/platform/releases) for per-release upgrade steps and breaking changes. + To setup a testnet masternode, please refer to the comprehensive documentation of the process as described [here](https://docs.dash.org/en/stable/masternodes/setup-testnet.html#dashmate-installation). The following video also details how to complete the process. ```{eval-rst} From 52c60aefe8fc3fcddf4ffed8c4dda89e7eeec049 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 5 Aug 2026 16:48:45 -0400 Subject: [PATCH 03/17] docs(protocol-ref): document protocol v13 behavior changes Add document history opt-in flags (keepsTransferHistory, keepsPurchaseHistory, keepsPricingHistory) to the document configuration table and full property dropdown, with a new Document History Flags section covering the meta-schema v2 gate and immutability on contract update. Note the distinction from the identically named token-level flag. Scope the DPNS domain TRANSFER, PURCHASE and UPDATE_PRICE reject triggers to protocol version 12 and earlier, since bindings list v1 drops them, and document the records.identity rewrite applied on transfer and purchase. Add a section on address balance changes originating from shielded pool activity and the protocol version 13 expansion of the recent per-block balance change set. Repoint source links on these pages to v4.1.0, including the bindings list v1 path. --- docs/protocol-ref/address-system.md | 32 +++++++---- docs/protocol-ref/data-contract-document.md | 59 ++++++++++++++------- docs/protocol-ref/data-trigger.md | 26 +++++---- 3 files changed, 79 insertions(+), 38 deletions(-) diff --git a/docs/protocol-ref/address-system.md b/docs/protocol-ref/address-system.md index c45056f93..68776fe47 100644 --- a/docs/protocol-ref/address-system.md +++ b/docs/protocol-ref/address-system.md @@ -5,7 +5,7 @@ # Platform Address System :::{attention} -Address-based state transitions were [enabled in Protocol Version 11](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs). These transitions enable direct operations using Platform addresses without requiring a pre-existing identity for some operations. +Address-based state transitions were [enabled in Protocol Version 11](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs). These transitions enable direct operations using Platform addresses without requiring a pre-existing identity for some operations. ::: ## Overview @@ -38,7 +38,7 @@ Platform addresses are derived from standard Bitcoin/Dash address formats and en 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/v4.0.0/packages/rs-dpp/src/address_funds/platform_address.rs). +See the [Platform address implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/platform_address.rs). ### Address Witness @@ -63,7 +63,7 @@ Witnesses provide cryptographic proof of address ownership. Each input in an add 3. Double-SHA256 hash the signable bytes (reused for all signatures) 4. Match M signatures to N public keys in order -See the [witness implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/address_funds/witness.rs). +See the [witness implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/witness.rs). ### Fee Strategy @@ -78,7 +78,7 @@ The fee strategy specifies how transaction fees are deducted from inputs or outp Fee strategy cannot be empty. Maximum steps: 4 (`max_address_fee_strategies`). No duplicate steps allowed. Steps are processed in sequence until the fee is fully covered. ::: -See the [fee strategy implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/address_funds/fee_strategy/mod.rs). +See the [fee strategy implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/fee_strategy/mod.rs). ### Common Type Aliases @@ -107,7 +107,7 @@ Transfer credits from an existing identity to one or more Platform addresses. Minimum recipients: 1. Maximum recipients: `max_address_outputs`. Minimum per recipient: 500,000 credits. Fee: 500,000 credits base + 6,000,000 credits per recipient (example: 1 recipient = 6,500,000 credits minimum fee). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_to_addresses_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_to_addresses_transition/). ### Identity Create from Addresses @@ -128,7 +128,7 @@ Create a new identity funded from Platform address balances. **Cost:** Base cost 2,000,000 + 6,500,000 per key. Example: 2 keys = 15,000,000 credits. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_from_addresses_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_from_addresses_transition/). ### Identity Top-Up from Addresses @@ -149,7 +149,7 @@ Add credits to an existing identity from Platform address balances. **Fee:** Base top-up cost: 500,000 credits. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_from_addresses_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_from_addresses_transition/). ### Address Funds Transfer @@ -173,7 +173,7 @@ Unlike other address transitions, fund transfers enforce strict balance preserva **Fee:** 500,000 credits per input + 6,000,000 credits per output. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funds_transfer_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funds_transfer_transition/). ### Address Funding from Asset Lock @@ -199,7 +199,7 @@ Exactly one output must have a `None` value. This remainder output receives what **Constraints:** Minimum outputs: 1. Maximum inputs: `max_address_inputs`. Maximum outputs: `max_address_outputs`. Minimum per input: 100,000 credits. Minimum per explicit output: 500,000 credits. No output can also be an input. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funding_from_asset_lock_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funding_from_asset_lock_transition/). ### Address Credit Withdrawal @@ -222,7 +222,7 @@ Withdraw credits from Platform addresses back to the Core chain. **Fee:** 400,000,000 credits. Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_credit_withdrawal_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_credit_withdrawal_transition/). ### Address State Transition Signing @@ -234,6 +234,18 @@ Address-based state transitions use different signing methods depending on the t | Address-witness-signed | Types 10, 11, 12, 14 | Address owner(s) | | Dual (Asset lock + Address) | Type 13 | Asset lock owner + optional address owners | +### Other Sources of Address Balance Changes + +Platform address balances do not change only through the address transitions above. [Shielded pool](shielded-pool.md) activity can also credit an address: + +- An [Unshield](shielded-pool.md#unshield) net output +- A [Shield from Asset Lock](shielded-pool.md#shield-from-asset-lock) surplus +- The [Identity Create From Shielded Pool](shielded-pool.md#identity-create-from-shielded-pool) fallback credit, paid to `sendToAddressOnCreationFailure` when identity creation fails a stateful check + +Since protocol version 13, these shielded-origin credits, along with the balance effects of paid-but-invalid state transitions, are recorded in the recent per-block address balance change set that incremental client sync reads. Because the recorded set feeds the committed state root, the expansion was not in effect before protocol version 13. + +The recent per-block set is served by the [`getRecentAddressBalanceChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentaddressbalancechanges) and [`getRecentCompactedAddressBalanceChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentcompactedaddressbalancechanges) endpoints. + ## Related Constants For complete constants reference, see [Protocol Constants](protocol-constants.md). diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index c0df7bc76..898a22292 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -5,7 +5,7 @@ The `documents` object defines each type of document in the data contract. At a minimum, a document must consist of 1 or more properties. The `additionalProperties` properties keyword must be included as described in the [constraints](./data-contract.md#additional-properties) section and each property must be [assigned a position](#assigning-position). :::{note} -The `$schema` property is required for each document type but is automatically injected by the platform during [contract enrichment](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/schema/enrich_with_base_schema/v0/mod.rs). Do not include it in user-submitted document type definitions — providing it will result in a validation error. +The `$schema` property is required for each document type but is automatically injected by the platform during [contract enrichment](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/schema/enrich_with_base_schema/v0/mod.rs). Do not include it in user-submitted document type definitions — providing it will result in a validation error. ::: The following example shows a minimal `documents` object defining a single document (`note`) with one property (`message`). @@ -121,10 +121,10 @@ There are a variety of constraints currently defined for performance and securit | Description | Value | | ----------- | ----- | -| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L23) | -| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L24) | -| Minimum property name length | [1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L21) | -| Maximum property name length | [64](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L21) | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L23) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L24) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L21) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L21) | | Property name characters | Alphanumeric (`A-Z`, `a-z`, `0-9`)
Hyphen (`-`)
Underscore (`_`) | ## Document Indices @@ -213,15 +213,15 @@ For performance and security reasons, indices have the following constraints. Th | Description | Value | | ----------- | ----- | -| Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L358) / [32](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L359) | -| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L482) | -| Maximum number of unique indices | [10](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L27) | -| Maximum number of contested indices | [1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L26) | -| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json#L378) | -| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L24) | +| Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L358) / [32](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L359) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L482) | +| Maximum number of unique indices | [10](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L27) | +| Maximum number of contested indices | [1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L26) | +| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L378) | +| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L24) | | Usage of `$id` in an index [disallowed](https://github.com/dashpay/platform/pull/178) | N/A | -| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | -| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L26) | +| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | +| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L26) | :::{seealso} For all protocol constants, see [Protocol Constants](protocol-constants.md). @@ -256,6 +256,9 @@ Documents support the following configuration options to provide flexibility in | `transferable` | integer | Transferable without a marketplace sell:
`0` - Never
`1` - Always
See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details | | `tradeMode` | integer | Built-in marketplace system:
`0` - None
`1` - Direct purchase (the purchaser can buy the item without requiring approval)
See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details | | `creationRestrictionMode` | integer | Restriction of document creation:
`0` - No restrictions
`1` - Contract owner only
`2` - No Creation Allowed
See the [NFT page](../explanations/nft.md#creation-restrictions) for more details | +| `keepsTransferHistory` | boolean | If true, transfers of these documents are recorded in the [document history contract](#document-history-flags). Default: false. | +| `keepsPurchaseHistory` | boolean | If true, purchases of these documents are recorded in the [document history contract](#document-history-flags). Default: false. | +| `keepsPricingHistory` | boolean | If true, price updates on these documents are recorded in the [document history contract](#document-history-flags). Default: false. | | Security option | Type | Description | |-----------------|------|-------------| @@ -265,7 +268,7 @@ Documents support the following configuration options to provide flexibility in ### Token Costs -The `tokenCost` option allows document types to require token payment for operations. When configured, users must pay a specified amount of tokens to perform each operation type. Each operation cost is defined as a [documentActionTokenCost](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L294-L337) object with the following properties: +The `tokenCost` option allows document types to require token payment for operations. When configured, users must pay a specified amount of tokens to perform each operation type. Each operation cost is defined as a [documentActionTokenCost](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L294-L337) object with the following properties: | Property | Type | Required | Description | |----------|------|----------|-------------| @@ -288,7 +291,7 @@ The following operation types can each have an independent cost configuration: :::{dropdown} List of all usable document properties - This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) and the [document meta-schema](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json). + This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L43) and the [document meta-schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). | Property Name | Type | Description | |---------------|------|-------------| @@ -314,6 +317,9 @@ The following operation types can each have an independent cost configuration: | [`rangeSummable`](#aggregate-query-flags) | boolean | Per-index range sums. See [Aggregate Query Flags](#aggregate-query-flags). | | [`documentsAverageable`](#aggregate-query-flags) | string | Doctype-wide averages of the named integer property. See [Aggregate Query Flags](#aggregate-query-flags). | | [`rangeAverageable`](#aggregate-query-flags) | boolean | Per-index range averages. See [Aggregate Query Flags](#aggregate-query-flags). | + | [`keepsTransferHistory`](#document-history-flags) | boolean | Records transfers in the document history contract. See [Document History Flags](#document-history-flags). | + | [`keepsPurchaseHistory`](#document-history-flags) | boolean | Records purchases in the document history contract. See [Document History Flags](#document-history-flags). | + | [`keepsPricingHistory`](#document-history-flags) | boolean | Records price updates in the document history contract. See [Document History Flags](#document-history-flags). | | `required` | array | Standard JSON Schema keyword listing required property names. | | `description` | string | Standard JSON Schema keyword describing the document type. | | `$comment` | string | Standard JSON Schema keyword for a schema comment. | @@ -363,16 +369,33 @@ There are two axes: The averageable flags desugar to the underlying count + sum flags during contract parsing — same on-disk layout — so authors who think in terms of averages get a single flag and downstream code paths (insert, query, estimation) stay unchanged. If both `documentsAverageable` and `documentsSummable` are set, they must name the same property. -These flags are validated against the v1 document meta-schema and are rejected when applied to pre-v12 contracts. The full v1 meta-schema, including these flags, is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json). +These flags were introduced in the v1 document meta-schema and carry forward unchanged into v2. They are rejected when applied to pre-v12 contracts. The full v2 meta-schema, including these flags, is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). See the [`getDocuments` reference](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) for the request/response shapes that consume these flags. +## Document History Flags + +:::{versionadded} 4.1.0 +::: + +Document types can opt into recording ownership and pricing events in the [document history system contract](./data-contract.md#document-history-system-contract) by setting flags at the document-type level. Each flag is a boolean defaulting to false, set at the document type root alongside other doctype options like `documentsKeepHistory`. These are distinct from the token-level [token history properties](./data-contract-token.md#history-properties), which share the `keepsTransferHistory` name but default to true and record into token history. + +| Flag | Type | Purpose | +| - | - | - | +| `keepsTransferHistory` | Boolean | Records each transfer of these documents. | +| `keepsPurchaseHistory` | Boolean | Records each purchase of these documents. | +| `keepsPricingHistory` | Boolean | Records each price update on these documents. | + +Like the [aggregate query flags](#aggregate-query-flags), these cannot be changed by a contract update once set on a published contract. + +The flags are read only when the contract validates against the v2 document meta-schema (protocol version 13 or later). Under earlier meta-schema versions they are treated as false. The full v2 meta-schema is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). + ## Keyword Constraints There are a variety of keyword constraints currently defined for performance and security reasons. The following constraints apply to document definitions. Unless otherwise noted, these constraints are defined in the platform's JSON Schema rules (e.g., [rs-dpp document meta -schema](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json)). +schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json)). | Keyword | Constraint | | ------- | ---------- | @@ -443,4 +466,4 @@ This example syntax shows the structure of a documents object that defines two d ## Document Schema -See full document schema details in the [rs-dpp document meta schema](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json). +See full document schema details in the [rs-dpp document meta schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). diff --git a/docs/protocol-ref/data-trigger.md b/docs/protocol-ref/data-trigger.md index 5b4698c06..b9c854e0b 100644 --- a/docs/protocol-ref/data-trigger.md +++ b/docs/protocol-ref/data-trigger.md @@ -18,17 +18,19 @@ When document state transitions are received, DPP checks if there is a trigger a ### Example -As an example, DPP contains several data triggers for DPNS as defined in the [data trigger bindings](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v0/mod.rs). The `domain` document has added constraints for creation, replacement or deletion: +As an example, DPP contains several data triggers for DPNS as defined in the [data trigger bindings](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v1/mod.rs). The `domain` document has added constraints for creation, replacement or deletion: | Data Contract | Document | Action(s) | Trigger Description | | ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -| DPNS | `domain` | [`CREATE`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns/v1/mod.rs#L48) | Enforces DNS compatibility, validates provided hashes, and restricts top-level domain (TLD) registration | +| DPNS | `domain` | [`CREATE`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dpns/v1/mod.rs#L48) | Enforces DNS compatibility, validates provided hashes, and restricts top-level domain (TLD) registration | | ---- | ---- | ---- | ---- | -| DPNS | `domain` | [`REPLACE`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents updates to existing documents | -| DPNS | `domain` | [`DELETE`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents deletion of existing documents | -| DPNS | `domain` | [`TRANSFER`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents transfer of existing documents | -| DPNS | `domain` | [`PURCHASE`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents purchase of existing documents | -| DPNS | `domain` | [`UPDATE_PRICE`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents updating price of existing documents | +| DPNS | `domain` | [`REPLACE`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents updates to existing documents | +| DPNS | `domain` | [`DELETE`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents deletion of existing documents | +| DPNS | `domain` | [`TRANSFER`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents transfer of existing documents (protocol version 12 and earlier only) | +| DPNS | `domain` | [`PURCHASE`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents purchase of existing documents (protocol version 12 and earlier only) | +| DPNS | `domain` | [`UPDATE_PRICE`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/reject/v0/mod.rs#L25) | Prevents updating price of existing documents (protocol version 12 and earlier only) | + +Starting in protocol version 13, the `TRANSFER`, `PURCHASE` and `UPDATE_PRICE` actions have no DPNS trigger binding. They are validated by the generic document validation paths, which permit them because the DPNS data contract declares `transferable: 1` and `tradeMode: 1`. `REPLACE` and `DELETE` remain rejected. **DPNS Trigger Constraints** @@ -47,9 +49,9 @@ The following table details the DPNS constraints applied via data triggers. Thes | `domain` | `CREATE` | Referenced `preorder` document must exist | | `domain` | `REPLACE` | Action not allowed | | `domain` | `DELETE` | Action not allowed | -| `domain` | `TRANSFER` | Action not allowed | -| `domain` | `PURCHASE` | Action not allowed | -| `domain` | `UPDATE_PRICE` | Action not allowed | +| `domain` | `TRANSFER` | Action not allowed (protocol version 12 and earlier only) | +| `domain` | `PURCHASE` | Action not allowed (protocol version 12 and earlier only) | +| `domain` | `UPDATE_PRICE` | Action not allowed (protocol version 12 and earlier only) | :::{note} The trigger for `domain` `CREATE` attempts to validate that `ownerId` matches @@ -60,6 +62,10 @@ therefore permanent no-ops and `records.identity` is not validated against `ownerId` at the trigger level. ::: +:::{note} +Starting in protocol version 13, when a DPNS `domain` document is transferred or purchased platform rewrites the document's `records.identity` to the new owner's identity ID as part of applying the transition. Name resolution and `records.identity` queries therefore follow the ownership change. This rewrite is applied outside the data trigger system and is scoped to the DPNS `domain` document type. +::: + ### Other System Contract Triggers In addition to DPNS, the following system contracts have registered data triggers: From 9679b8ef32dc773970762f0c8f23a297a171141a Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 09:58:34 -0400 Subject: [PATCH 04/17] docs(protocol-ref): refresh source links to v4.1.0 and add v13 details Update rs-dpp and rs-platform-version permalinks from v4.0.0 to v4.1.0 across the data contract, document, token, state transition, and errors pages, correcting line anchors that shifted upstream. The state transition size and batch limits now point at system_limits/v3.rs. Document the v2 document meta-schema introduced by protocol version 13, including the keepsTransferHistory, keepsPurchaseHistory, and keepsPricingHistory document type flags and the document history system contract that records them. Add the protocol version 13 requirement that group-valued authorized parties resolve at contract registration, and document the tagged singlePrice and setPrices forms of the token pricing schedule. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/data-contract-token.md | 38 ++++++++----- docs/protocol-ref/data-contract.md | 72 +++++++++++++++++++----- docs/protocol-ref/document.md | 24 ++++---- docs/protocol-ref/errors.md | 2 +- docs/protocol-ref/state-transition.md | 36 ++++++------ docs/protocol-ref/token.md | 69 +++++++++++++++-------- 6 files changed, 158 insertions(+), 83 deletions(-) diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md index a1a087502..6f4d3a60d 100644 --- a/docs/protocol-ref/data-contract-token.md +++ b/docs/protocol-ref/data-contract-token.md @@ -48,10 +48,10 @@ Token creation incurs specific fees based on which token features are used: | Operation | Fee (DASH)| Description | |-----------|-----------|-------------| -| Token registration | [0.1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L11)| Base fee for adding a token to a contract | -| Perpetual distribution | [0.1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L12) | Fee for enabling perpetual distribution | -| Pre-programmed distribution | [0.1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L13) | Fee for enabling pre-programmed distribution | -| Search keyword fee | [0.1](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L14) | Per keyword fee for including search keywords | +| Token registration | [0.1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L11)| Base fee for adding a token to a contract | +| Perpetual distribution | [0.1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L12) | Fee for enabling perpetual distribution | +| Pre-programmed distribution | [0.1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L13) | Fee for enabling pre-programmed distribution | +| Search keyword fee | [0.1](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L14) | Per keyword fee for including search keywords | ## Assigning Position @@ -165,7 +165,7 @@ Change control rules define authorization requirements for modifying various asp ### Authorized Parties -Rules can authorize no one, specific identities, or multiparty groups. The complete set of options [defined by DPP](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/change_control_rules/authorized_action_takers.rs#L15-L22) is: +Rules can authorize no one, specific identities, or multiparty groups. The complete set of options [defined by DPP](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/change_control_rules/authorized_action_takers.rs#L26-L33) is: | Authorized Party | Description | |----------------------|-------------| @@ -175,9 +175,15 @@ Rules can authorize no one, specific identities, or multiparty groups. The compl | `MainGroup` | Only the [main control group](../explanations/tokens.md#main-control-group) is authorized | | `Group()` | Only the specific group based in contract position "x" is authorized | +:::{note} +Starting in protocol version 13, group-valued authorized parties must resolve when the contract is registered. `Group()` requires a group defined at contract position `x`, otherwise registration fails with `GroupPositionDoesNotExistError`. `MainGroup` requires `mainControlGroup` to be set, otherwise registration fails with `MainGroupIsNotDefinedError`. This applies to both `authorized_to_make_change` and `admin_action_takers` across every change control rule family. + +At action time, a group action authorized by `MainGroup` succeeds only when the group submitting it is at the same contract position as the token's configured `mainControlGroup`. An unset `mainControlGroup` authorizes no group, and the action is rejected with `UnauthorizedTokenActionError`. +::: + ### Change Rule Structure -Each rule consists of the following parameters [defined in DPP](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/change_control_rules/v0/mod.rs) that control its behavior: +Each rule consists of the following parameters [defined in DPP](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/change_control_rules/v0/mod.rs) that control its behavior: | Field | Description | | - | - | @@ -526,6 +532,8 @@ Direct purchase pricing enables tokens to be [purchased directly using Platform] Token history tracking controls which operations are recorded in Platform's historical records. This provides audit trails and transparency for token operations. +The properties below are token-level and are nested under the token's `keepsHistory` object. Document types have a separate set of [document history flags](./data-contract-document.md#document-history-flags) set at the document type root, including a distinct `keepsTransferHistory` flag that defaults to false and records into the document history system contract. + ### History Properties | Property | Type | Default | Description | @@ -625,27 +633,27 @@ For performance and security reasons, tokens have the following constraints: | Parameter | Value | |-----------|-------| -| Maximum number of keywords | [50](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L272-L277) | -| Keyword length | [3 to 50 characters](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L279-L287) | -| Description length | [3 to 100 characters](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L312-L323) | -| Maximum note length | [2048 bytes](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L19) | +| Maximum number of keywords | [50](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L272-L277) | +| Keyword length | [3 to 50 characters](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L279-L287) | +| Description length | [3 to 100 characters](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L312-L323) | +| Maximum note length | [2048 bytes](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L19) | | Maximum number of tokens per contract | Only limited by [maximum contract size](./data-contract.md#data-size) | ### Convention Constraints | Parameter | Value | |-----------|-------| -| Language code length | [2 to 12 characters](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L97-L101) | -| Token name length (singular) | [3 to 25 characters](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L84-L89) | -| Token name length (plural) | [3 to 25 characters](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L90-L95) | -| Decimal places | [0 to 16](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L31-L36) | +| Language code length | [2 to 12 characters](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L97-L101) | +| Token name length (singular) | [3 to 25 characters](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L84-L89) | +| Token name length (plural) | [3 to 25 characters](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L90-L95) | +| Decimal places | [0 to 16](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/methods/validate_localizations/v0/mod.rs#L31-L36) | | Maximum localization entries | Only limited by [maximum contract size](./data-contract.md#data-size) | ### Supply Constraints | Parameter | Value | |-----------|-------| -| Maximum token amount | [i64::MAX (2^63 - 1 = 9,223,372,036,854,775,807)](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/errors/consensus/basic/data_contract/invalid_token_base_supply_error.rs#L12-L16) | +| Maximum token amount | [i64::MAX (2^63 - 1 = 9,223,372,036,854,775,807)](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/errors/consensus/basic/data_contract/invalid_token_base_supply_error.rs#L12-L16) | ## Example Syntax diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index 203968f1c..cdff3c042 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -45,9 +45,9 @@ There are a variety of constraints currently defined for performance and securit | Parameter | Size | | - | - | -| Estimated maximum serialized data contract size | [16384 bytes (16 KB)](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L4) | -| Maximum field value size | [5120 bytes (5 KB)](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L5) | -| Maximum state transition size | [20480 bytes (20 KB)](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L6) | +| Estimated maximum serialized data contract size | [16384 bytes (16 KB)](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L4) | +| Maximum field value size | [5120 bytes (5 KB)](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L5) | +| Maximum state transition size | [20480 bytes (20 KB)](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L7) | A document cannot exceed the maximum state transition size in any case. For example, although it is possible to define a data contract with 10 document fields that each support the maximum field size @@ -67,7 +67,7 @@ Include the following at the same level as the `properties` keyword to ensure pr ## Data Contract Object -The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L77-L121)): +The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L77-L121)): | Property | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | @@ -92,7 +92,15 @@ The data contract object consists of the following fields as defined in the Rust ### Document type meta-schema -Each document type defined within a data contract is validated against the document meta-schema. This page reflects the v1 meta-schema used since protocol version 12 (Dash Platform v4.0.0); earlier protocol versions validated against the v0 meta-schema. The full schema is [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json), hosted on [GitHub](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json), and can be viewed by expanding this dropdown: +Each document type defined within a data contract is validated against the document meta-schema. The meta-schema version is determined by the protocol version in effect: + +| Meta-schema | Protocol version | +| - | - | +| v2 | 13 and later | +| v1 | 12 | +| v0 | 11 and earlier | + +This page reflects the v2 meta-schema, which adds [document history flags](./data-contract-document.md#document-history-flags). The full schema is [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json) and can be viewed by expanding this dropdown: ::: {dropdown} Full schema @@ -100,7 +108,7 @@ Each document type defined within a data contract is validated against the docum { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json", - "$comment": "EDITABLE UNTIL 3.1 RELEASE — FROZEN AFTER. This v1 document meta-schema activates with protocol v12 (CONTRACT_VERSIONS_V4) and admits every v12+ contract written to disk. Once Platform 3.1 ships, mutating it would change historical validation results and break consensus replay. After release, any new top-level property or rule MUST go in a newer meta-schema version (v2+).", + "$comment": "EDITABLE UNTIL 4.1 RELEASE — FROZEN AFTER. This v2 document meta-schema activates with protocol v13 (CONTRACT_VERSIONS_V5). It is v1 plus the keepsTransferHistory, keepsPurchaseHistory and keepsPricingHistory document type configuration flags, and admits every v13+ contract written to disk. Once the release carrying protocol v13 ships, mutating it would change historical validation results and break consensus replay. After release, any new top-level property or rule MUST go in a newer meta-schema version (v3+).", "type": "object", "$defs": { "documentProperties": { @@ -593,6 +601,18 @@ Each document type defined within a data contract is validated against the docum "type": "boolean", "description": "True if the documents keep all their history, default is false" }, + "keepsTransferHistory": { + "type": "boolean", + "description": "True if transfers of these documents are recorded in the document history system contract, default is false" + }, + "keepsPurchaseHistory": { + "type": "boolean", + "description": "True if purchases of these documents are recorded in the document history system contract, default is false" + }, + "keepsPricingHistory": { + "type": "boolean", + "description": "True if price updates on these documents are recorded in the document history system contract, default is false" + }, "documentsMutable": { "type": "boolean", "description": "True if the documents are mutable, default is true" @@ -813,7 +833,7 @@ Each document type defined within a data contract is validated against the docum ### Data Contract id -The data contract `id` is a hash of the `ownerId` and `identity_nonce` as shown in the [rs-dpp implementation](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/generate_data_contract.rs). +The data contract `id` is a hash of the `ownerId` and `identity_nonce` as shown in the [rs-dpp implementation](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/generate_data_contract.rs). ```rust // From the Rust reference implementation (rs-dpp) @@ -841,7 +861,7 @@ See the [data contract documents](./data-contract-document.md) page for details, ### Data Contract config -The data contract config defines configuration options for data contracts, controlling their lifecycle, mutability, history management, and encryption requirements. Data contracts support three categories of configuration options to provide flexibility in contract design. It is only necessary to include them in a data contract when non-default values are used. The default values for these configuration options are defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/config/fields.rs). +The data contract config defines configuration options for data contracts, controlling their lifecycle, mutability, history management, and encryption requirements. Data contracts support three categories of configuration options to provide flexibility in contract design. It is only necessary to include them in a data contract when non-default values are used. The default values for these configuration options are defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/config/fields.rs). | Contract option | Default | Description | |-----------------------------------------|---------|-------------| @@ -871,7 +891,7 @@ These security options can be set at the root level of the data contract or the **Example** -The following example (from the [DashPay contract's `contactRequest` document](https://github.com/dashpay/platform/blob/v4.0.0/packages/dashpay-contract/schema/v1/dashpay.schema.json#L142-L146)) demonstrates the use of both key-related options at the document level: +The following example (from the [DashPay contract's `contactRequest` document](https://github.com/dashpay/platform/blob/v4.1.0/packages/dashpay-contract/schema/v1/dashpay.schema.json#L142-L146)) demonstrates the use of both key-related options at the document level: ``` json "contactRequest": { @@ -880,7 +900,7 @@ The following example (from the [DashPay contract's `contactRequest` document](h } ``` -See the data contract [config implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/config/v1/mod.rs#L21-L48) for more details. +See the data contract [config implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/config/v1/mod.rs#L21-L48) for more details. ### Data Contract groups @@ -897,9 +917,9 @@ Groups can be used to distribute contract configuration and update authorization | Constant | Value | Description | |----------|-------|-------------| -| Minimum group size | [2](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L107-L110) | Minimum members per group | +| Minimum group size | [2](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L107-L110) | Minimum members per group | | `max_contract_group_size` | 256 | Maximum members per group | -| Maximum member power | 65,535 (u32; cap enforced at u16::MAX) | Maximum voting power per member. Each member's power must also not exceed the group's [`requiredPower`](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L129-L134) value. | +| Maximum member power | 65,535 (u32; cap enforced at u16::MAX) | Maximum voting power per member. Each member's power must also not exceed the group's [`requiredPower`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L129-L134) value. | | Maximum required power | 65,535 (u32; cap enforced at u16::MAX) | Maximum threshold power | #### Group Action Info @@ -937,7 +957,7 @@ When submitting a group-authorized action, the transition includes: In this example, any two of the three members can authorize an action. -See the [groups implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L36-L39) for more details. +See the [groups implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L36-L39) for more details. ### Data Contract tokens @@ -948,6 +968,28 @@ See the [groups implementation in rs-dpp](https://github.com/dashpay/platform/bl - Token configurations include change control rules, ensuring proper governance for modifying supply limits and token-related settings. - This enables contracts to define and manage tokens while ensuring compliance with governance rules (e.g., who can mint or burn tokens). +### Document history system contract + +:::{versionadded} 4.1.0 +::: + +The document history contract is a [system data contract](https://github.com/dashpay/platform/blob/v4.1.0/packages/data-contracts/src/lib.rs) that records document transfers, purchases and price updates for document types that opt in via the [document history flags](./data-contract-document.md#document-configuration). + +| Property | Value | +| - | - | +| Contract ID | `6voHRaoiPcfmMhbqCA9dixH98xcgPQ9UEcuaXjpVu3LD` | +| Owner ID | `11111111111111111111111111111111` | + +Its documents are written by the protocol while applying the corresponding document transition; they cannot be created directly (`creationRestrictionMode` 2). All three document types are immutable (`documentsMutable` false) and cannot be deleted (`canBeDeleted` false). + +| Document type | Recorded properties | +| - | - | +| `transfer` | `dataContractId`, `documentTypeName`, `documentId`, `toIdentityId` | +| `purchase` | `dataContractId`, `documentTypeName`, `documentId`, `sellerId`, `price` | +| `priceUpdate` | `dataContractId`, `documentTypeName`, `documentId`, `price` | + +See the [contract schema in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/document-history-contract/schema/v1/document-history-contract-documents.json). + ## Data Contract State Transition Details There are two data contract-related state transitions: [data contract create](#data-contract-create) and [data contract update](#data-contract-update). Details are provided in this section. @@ -966,7 +1008,7 @@ Data contracts are created on the platform by submitting the [data contract obje | signaturePublicKeyId | unsigned integer | 32 bits | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition (`=> 0`) | | signature | array of bytes | 65 bytes | Signature of state transition data | -See the [data contract create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L40-L48) for more details. +See the [data contract create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L36-L44) for more details. ### Data Contract Update @@ -990,7 +1032,7 @@ object](#data-contract-object) in a data contract update state transition consis | signaturePublicKeyId | unsigned integer | 32 bits | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition (`=> 0`) | | signature | array of bytes | 65 bytes | Signature of state transition data | -See the [data contract update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_update_transition/v0/mod.rs#L35-L47) for more details. +See the [data contract update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_update_transition/v0/mod.rs#L31-L43) for more details. ### Data Contract State Transition Signing diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 0e0b5f679..8ce0317fd 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -24,11 +24,11 @@ The following fields are included in all document transitions. Note that `$actio | $dataContractId | array | 32 bytes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `identity nonce` | | [$tokenPaymentInfo](#token-payment-info) | object | Varies | (Optional, V1+) Token-based fee payment information for this transition | -Each document transition must comply with the [document base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_base_transition/v1/mod.rs#L38-L56). +Each document transition must comply with the [document base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_base_transition/v1/mod.rs#L40-L58). #### Document id -The document `$id` is created by double sha256 hashing the document's `dataContractId`, `ownerId`, `type`, and `entropy` as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/document/generate_document_id.rs). +The document `$id` is created by double sha256 hashing the document's `dataContractId`, `ownerId`, `type`, and `entropy` as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/document/generate_document_id.rs). ```rust // From the Rust reference implementation (rs-dpp) @@ -52,7 +52,7 @@ pub fn generate_document_id_v0( #### Token Payment Info -When a document type requires token payment (configured via [`tokenCost`](./data-contract-document.md#token-costs) in the data contract), the `$tokenPaymentInfo` object specifies which token to use and the cost limits the client is willing to accept. The object is defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/token_payment_info/v0/mod.rs#L36-L56). +When a document type requires token payment (configured via [`tokenCost`](./data-contract-document.md#token-costs) in the data contract), the `$tokenPaymentInfo` object specifies which token to use and the cost limits the client is willing to accept. The object is defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/token_payment_info/v0/mod.rs#L34-L54). | Field | Type | Size | Description | | - | - | - | - | @@ -68,7 +68,7 @@ The `gasFeesPaidBy` value must match what the data contract's `tokenCost` config #### Entropy Generation -Dash Platform uses the following entropy generator found in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/util/entropy_generator.rs#L9-L14): +Dash Platform uses the following entropy generator found in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/util/entropy_generator.rs#L9-L14): ```rust // From the Rust reference implementation (rs-dpp) @@ -83,7 +83,7 @@ fn generate(&self) -> anyhow::Result<[u8; 32]> { #### Document Transition Action -Document transition actions indicate what operation platform should perform with the provided transition data. Documents provide CRUD functionality, ownership transfer, and NFT features as [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transition_action_type.rs#L6-L14). +Document transition actions indicate what operation platform should perform with the provided transition data. Documents provide CRUD functionality, ownership transfer, and NFT features as [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transition_action_type.rs#L6-L14). | Action | Name | Description | | :-: | - | - | @@ -105,7 +105,7 @@ The document create transition extends the [base transition](#document-base-tran | data | | Varies | Document data being submitted. | | $prefundedVotingBalance | | Varies | (Optional) Prefunded amount of credits reserved for unique index conflict resolution voting (e.g., [premium DPNS name](../explanations/dpns.md#conflict-resolution)).| -Each document create transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/v0/mod.rs#L57-L78) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +Each document create transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/v0/mod.rs#L70-L99) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). ::: {note} The document create transition data field must include all [required document properties](./data-contract-document.md#required-properties) specified in the data contract. @@ -143,7 +143,7 @@ The document replace transition extends the [base transition](#document-base-tra | $revision | unsigned integer | 64 bits | Document revision (=> 1) | | data | | Varies | Document data being updated | -Each document replace transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_replace_transition/v0/mod.rs#L35-L42) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +Each document replace transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_replace_transition/v0/mod.rs#L39-L46) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). ::: {note} The document replace transition data field must include all [required document properties](./data-contract-document.md#required-properties) specified in the data contract. @@ -174,7 +174,7 @@ The following example document replace transition and subsequent table demonstra ### Document Delete Transition -The document delete transition only requires the fields found in the [base document transition](#document-base-transition). See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/v0/mod.rs#L21-L24) for details. +The document delete transition only requires the fields found in the [base document transition](#document-base-transition). See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/v0/mod.rs#L24-L27) for details. ### Document Transfer Transition @@ -185,7 +185,7 @@ The document transfer transition allows a document owner to transfer document ow | $revision | unsigned integer | 64 bits | Document revision (=> 1) | | recipientOwnerId | array of bytes | 32 bytes | Identifier of the recipient (new owner). See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details. | -Each document transfer transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transfer_transition/v0/mod.rs#L33-L40) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +Each document transfer transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transfer_transition/v0/mod.rs#L34-L41) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). ### Document Purchase Transition @@ -196,7 +196,7 @@ The document purchase transition allows an identity to purchase a document previ | $revision | unsigned integer | 64 bits | Document revision (=> 1) | | price | unsigned integer | 64 bits | Number of credits being offered for the purchase. See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details. | -Each document purchase transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_purchase_transition/v0/mod.rs#L23-L30) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +Each document purchase transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_purchase_transition/v0/mod.rs#L24-L31) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). ### Document Update Price Transition @@ -207,11 +207,11 @@ The document update price transition allows a document owner to set or update th | $revision | unsigned integer | 64 bits | Document revision (=> 1) | | $price | unsigned integer | 64 bits | Updated price for the document. Can only be set by the current document owner. See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details. | -Each document update price transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_update_price_transition/v0/mod.rs#L27-L34) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +Each document update price transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_update_price_transition/v0/mod.rs#L28-L35) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). ## Document Object -The document object represents the data provided by the platform in response to a query. Responses consist of an array of these objects containing the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/document/v0/mod.rs#L39-L124)): +The document object represents the data provided by the platform in response to a query. Responses consist of an array of these objects containing the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/document/v0/mod.rs#L37-L101)): | Property | Type | Required | Description | | - | - | - | - | diff --git a/docs/protocol-ref/errors.md b/docs/protocol-ref/errors.md index 9b865ea7a..86f03f656 100644 --- a/docs/protocol-ref/errors.md +++ b/docs/protocol-ref/errors.md @@ -6,7 +6,7 @@ ## Platform Error Codes -Dash Platform Protocol implements a comprehensive set of consensus error codes. Refer to the tables below for a list of the codes as specified in [codes.rs](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/errors/consensus/codes.rs) of the consensus source code. +Dash Platform Protocol implements a comprehensive set of consensus error codes. Refer to the tables below for a list of the codes as specified in [codes.rs](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/errors/consensus/codes.rs) of the consensus source code. Platform error codes are organized into four categories. Each category may be further divided into sub-categories. The four categories and their error code ranges are: diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index 74d9b82f7..f46d957b6 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -13,20 +13,20 @@ ### Fees -State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of [1000 credits/satoshi](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/balances/credits.rs#L42). Fees for actions vary based on parameters related to storage and computational effort that are defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs). +State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of [1000 credits/satoshi](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/balances/credits.rs#L42). Fees for actions vary based on parameters related to storage and computational effort that are defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs). ### Size -State transitions are limited to a maximum size of [20 KiB / 20,480 bytes](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L6). +State transitions are limited to a maximum size of [20 KiB / 20,480 bytes](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L15). ### Common Fields -The list of common fields used by multiple state transitions is defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/common_fields.rs). All state transitions include the following fields: +The list of common fields used by multiple state transitions is defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/common_fields.rs). All state transitions include the following fields: | Field | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | | $version | unsigned integer | 16 bits | The state transition format version (FeatureVersion). Currently `0` for most transitions, `1` for Batch. This is not the global platform protocol version, which is negotiated separately. | -| type | unsigned integer | 8 bits | State transition type discriminator (defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21)). See [State Transition Types](#state-transition-types) for the full list. | +| type | unsigned integer | 8 bits | State transition type discriminator (defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21)). See [State Transition Types](#state-transition-types) for the full list. | | userFeeIncrease | unsigned integer | 16 bits | Extra fee to prioritize processing if the mempool is full. Typically set to zero. | | signature | array of bytes | 65 bytes |Signature of state transition data | @@ -42,7 +42,7 @@ Additionally, all state transitions except the identity create and topup state t ## State Transition Types -Dash Platform Protocol defines the following [state transition types](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21-L44). Most are documented in detail on the protocol reference page for the feature they operate on. Batch and Masternode Vote do not have a dedicated feature page; their formats are documented inline below. +Dash Platform Protocol defines the following [state transition types](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21-L44). Most are documented in detail on the protocol reference page for the feature they operate on. Batch and Masternode Vote do not have a dedicated feature page; their formats are documented inline below. | Type | Name | Documented in | | --- | --- | --- | @@ -73,9 +73,9 @@ Dash Platform Protocol defines the following [state transition types](https://gi | Field | Type | Size | Description | | ----------- | -------------- | ---- | ----------- | | ownerId | array of bytes | 32 bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) or token action(s) | -| transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-overview) or token actions (currently limited to [1 object per batch](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L20)) | +| transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-overview) or token actions (currently limited to [1 object per batch](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L16)) | -More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L31-L39). +More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L30-L38). ### Masternode Vote @@ -83,10 +83,10 @@ More detailed information about the `transitions` array can be found in the [doc | --------------- | -------------- | ---- | ----------- | | proTxHash | array of bytes | 32 bytes | An identifier based on a masternode or evonode's [provider registration transaction](inv:user:std#ref-txs-proregtx) hash | | voterIdentityId | array of bytes | 32 bytes | The voter's [Identity ID](../protocol-ref/identity.md#identity-id). This will be a masternode identity based on the protx hash. | -| vote | [Vote](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/voting/votes/mod.rs#L25-L27) | Varies | Vote information | +| vote | [Vote](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/voting/votes/mod.rs#L28-L30) | Varies | Vote information | | nonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks | -See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L43-L53). +See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L39-L49). ## State Transition Signing @@ -195,15 +195,15 @@ This table shows the fields that must be excluded when creating state transition | State transition | Signature | Signature public key ID | Identity ID | Identity public key signature(s) | | - | :-: | :-: | :-: | :-: | -| [Batch](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L35-L38) | Exclude | Exclude | N/A | N/A | -| [Contract create](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L44-L47) | Exclude | Exclude | N/A | N/A | -| [Contract update](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_update_transition/v0/mod.rs#L43-L46) | Exclude | Exclude | N/A | N/A | -| [Identity create](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L53-L57) | Exclude | N/A | Exclude | [Exclude](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L50-L51) | -| [Identity topup](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L48-L49) | Exclude | N/A | N/A | N/A | -| [Identity update](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L67-L71) | Exclude | Exclude | N/A | [Exclude for any keys being added by the state transition](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L50-L51) | -| [Identity credit transfer](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L49-L52) | Exclude | Exclude | N/A | N/A | -| [Identity credit withdrawal](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/v1/mod.rs#L48-L51) | Exclude | Exclude | N/A | N/A | -| [Masternode vote](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L49-L52) | Exclude | Exclude | N/A | N/A | +| [Batch](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L34-L37) | Exclude | Exclude | N/A | N/A | +| [Contract create](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L40-L43) | Exclude | Exclude | N/A | N/A | +| [Contract update](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_update_transition/v0/mod.rs#L39-L42) | Exclude | Exclude | N/A | N/A | +| [Identity create](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L49-L53) | Exclude | N/A | Exclude | [Exclude](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L46-L47) | +| [Identity topup](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L44-L45) | Exclude | N/A | N/A | N/A | +| [Identity update](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L63-L67) | Exclude | Exclude | N/A | [Exclude for any keys being added by the state transition](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L46-L47) | +| [Identity credit transfer](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L45-L48) | Exclude | Exclude | N/A | N/A | +| [Identity credit withdrawal](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/v1/mod.rs#L44-L47) | Exclude | Exclude | N/A | N/A | +| [Masternode vote](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L45-L48) | Exclude | Exclude | N/A | N/A | :::{note} The table above does not cover shielded transitions, which do not carry transition-level `signature` or `signaturePublicKeyId` fields. See [Signing Shielded Transitions](#signing-shielded-transitions). diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 6e214d961..18dcd61bb 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -39,13 +39,13 @@ The following fields are included in all token transitions: | $tokenContractPosition | unsigned integer | 16 bits | Position of the token within the contract | | $dataContractId | array | 32 bytes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` | | [$tokenId](#token-id) | array | 32 bytes | Token ID generated from the data contract ID and the token position | -| usingGroupInfo | [GroupStateTransitionInfo object](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/group/mod.rs#L42-L50) | Varies | Optional field indicating group multi-party authentication rules | +| usingGroupInfo | [GroupStateTransitionInfo object](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/group/mod.rs#L45-L54) | Varies | Optional field indicating group multi-party authentication rules. Since protocol version 13, a transition confirming an existing group action must carry the same `$dataContractId` and `$tokenContractPosition` as the original proposal; deviation is rejected. | -Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L42-L60). +Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L63). #### Token id -The `$tokenId` is created by double sha256 hashing the token `$dataContractId` and `$tokenContractPosition` with a byte vector of the string "dash_token" as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L27-L32). +The `$tokenId` is created by double sha256 hashing the token `$dataContractId` and `$tokenContractPosition` with a byte vector of the string "dash_token" as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L27-L32). ```rust // From the Rust reference implementation (rs-dpp) @@ -60,7 +60,7 @@ pub fn calculate_token_id(contract_id: &[u8; 32], token_pos: TokenContractPositi #### Token Transition Action -The token transition actions [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transition_action_type.rs#L15-L48) indicate what operation platform should perform with the provided transition data. +The token transition actions [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transition_action_type.rs#L15-L48) indicate what operation platform should perform with the provided transition data. | Action | Name | Description | | :-: | - | - | @@ -82,7 +82,7 @@ The numeric action codes above are for client-side reference ordering only. `Tok ### Token Notes -Some token transitions include optional notes fields. The maximum note length for these fields is [2048 bytes](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L19). +Some token transitions include optional notes fields. The maximum note length for these fields is [2048 bytes](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L19). ### Token Burn Transition @@ -93,7 +93,7 @@ The token burn transition extends the [base transition](#token-base-transition) | burnAmount | unsigned integer | 64 bits | Number of tokens to be burned | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token burn transition must comply with the [token burn transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L32). +Each token burn transition must comply with the [token burn transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L23-L33). ### Token Mint Transition @@ -105,7 +105,7 @@ The token mint transition extends the [base transition](#token-base-transition) | amount | unsigned integer | 64 bits | Number of tokens to mint | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token mint transition must comply with the [token mint transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L37). +Each token mint transition must comply with the [token mint transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L25-L39). ### Token Transfer Transition @@ -116,10 +116,10 @@ The token transfer transition extends the [base transition](#token-base-transiti | amount | unsigned integer | 64 bits | Number of tokens to transfer | | recipientId | array | 32 bytes | Identity ID of the recipient | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L20) | [<= 2048 bytes](#token-notes) | Optional shared encrypted note | -| privateEncryptedNote | [PrivateEncryptedNote object](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L21-L25) | [<= 2048 bytes](#token-notes) | Optional private encrypted note | +| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L20) | [<= 2048 bytes](#token-notes) | Optional shared encrypted note | +| privateEncryptedNote | [PrivateEncryptedNote object](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L21-L25) | [<= 2048 bytes](#token-notes) | Optional private encrypted note | -Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L46). +Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L39-L55). ### Token Freeze Transition @@ -130,7 +130,7 @@ The token freeze transition extends the [base transition](#token-base-transition | frozenIdentityId | array | 32 bytes | Identity ID of the account to be frozen | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token freeze transition must comply with the [token freeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L29). +Each token freeze transition must comply with the [token freeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L22-L32). ### Token Unfreeze Transition @@ -141,7 +141,7 @@ The token unfreeze transition extends the [base transition](#token-base-transiti | frozenIdentityId | array | 32 bytes | Identity ID of the account to be unfrozen | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token unfreeze transition must comply with the [token unfreeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L29). +Each token unfreeze transition must comply with the [token unfreeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L22-L32). ### Token Destroy Frozen Funds Transition @@ -152,7 +152,7 @@ The token destroy frozen funds transition extends the [base transition](#token-b | frozenIdentityId | array | 32 bytes | Identity ID of the account whose frozen balance should be destroyed | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token destroy frozen funds transition must comply with the [token destroy frozen funds transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25). +Each token destroy frozen funds transition must comply with the [token destroy frozen funds transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L20-L28). ### Token Claim Transition @@ -160,10 +160,10 @@ The token claim transition extends the [base transition](#token-base-transition) | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| distributionType | [TokenDistributionType enum](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_distribution_key.rs#L18-L25) | Varies | Type of [token distribution](../explanations/tokens.md#distribution-rules) targeted (`0` = PreProgrammed, `1` = Perpetual) | +| distributionType | [TokenDistributionType enum](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_distribution_key.rs#L18-L25) | Varies | Type of [token distribution](../explanations/tokens.md#distribution-rules) targeted (`0` = PreProgrammed, `1` = Perpetual) | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note (only saved for historical contracts) | -Each token claim transition must comply with the [token claim transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L18-L26). +Each token claim transition must comply with the [token claim transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L21-L29). ### Token Emergency Action Transition @@ -171,10 +171,10 @@ The token emergency action transition extends the [base transition](#token-base- | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| emergencyAction | [TokenEmergencyAction enum](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/emergency_action.rs#L14-L18) | Varies | The emergency action to be executed (`0` = Pause, `1` = Resume) | +| emergencyAction | [TokenEmergencyAction enum](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/emergency_action.rs#L14-L18) | Varies | The emergency action to be executed (`0` = Pause, `1` = Resume) | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token emergency action transition must comply with the [token emergency action transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24). +Each token emergency action transition must comply with the [token emergency action transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L19-L27). ### Token Config Update Transition @@ -182,10 +182,10 @@ The token config update transition extends the [base transition](#token-base-tra | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| updateTokenConfigurationItem | [TokenConfigurationChangeItem object](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L33-L67) | Varies | Updated token configuration item | +| updateTokenConfigurationItem | [TokenConfigurationChangeItem object](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L36-L70) | Varies | Updated token configuration item | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token configuration update transition must comply with the [token config update transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27). +Each token configuration update transition must comply with the [token config update transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L22-L30). ### Token Set Purchase Price Transition @@ -197,10 +197,35 @@ This transition extends the [base transition](#token-base-transition) to include | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| price | Optional [TokenPricingSchedule](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/token_pricing_schedule.rs#L29-L45) | Variable | (Optional) Set the fixed price or tiered price. Tiered pricing entries consists of a *minimum token amount* (unsigned 64-bit) and a *price in credits* (unsigned 64-bit) applicable for purchases of that size or greater. The smallest amount tier also defines the *minimum purchasable amount*. If the lowest tier has amount > 1, users cannot buy less than that amount in a single purchase. If multiple tiers are provided, they should be ordered by ascending minimum amount.
**Note:** Setting price to null disables direct purchases for the token. | +| price | Optional [TokenPricingSchedule](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/token_pricing_schedule.rs#L33-L49) | Variable | (Optional) Set the fixed price or tiered price. Tiered pricing entries consists of a *minimum token amount* (unsigned 64-bit) and a *price in credits* (unsigned 64-bit) applicable for purchases of that size or greater. The smallest amount tier also defines the *minimum purchasable amount*. If the lowest tier has amount > 1, users cannot buy less than that amount in a single purchase. If multiple tiers are provided, they should be ordered by ascending minimum amount.
**Note:** Setting price to null disables direct purchases for the token. | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | -Each token set purchase price transition must comply with the [token set purchase price transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_set_price_for_direct_purchase_transition/v0/mod.rs#L18-L29). +The pricing schedule is tagged by a `$type` field naming the form. A single fixed price uses `singlePrice`: + +```json +{ + "$type": "singlePrice", + "price": 100 +} +``` + +Tiered pricing uses `setPrices`, keyed by minimum token amount: + +```json +{ + "$type": "setPrices", + "prices": { + "1": 100, + "10": 90 + } +} +``` + +:::{note} +In human-readable JSON, credit and token amount values above `Number.MAX_SAFE_INTEGER` are serialized as strings. This affects JSON representations only; the bincode serialization used for consensus is unaffected. +::: + +Each token set purchase price transition must comply with the [token set purchase price transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_set_price_for_direct_purchase_transition/v0/mod.rs#L21-L32). ### Token Purchase Transition @@ -215,4 +240,4 @@ This transition extends the [base transition](#token-base-transition) to include | tokenCount | unsigned integer | 64 bits | Number of tokens the user is purchasing. Must be at least the minimum purchase amount defined by the current pricing and cannot exceed any available supply limits. | | totalAgreedPrice | unsigned integer | 64 bits | Maximum total price (in credits) the purchaser agrees to pay. Must be at least the unit price (or tiered price) times `tokenCount` according to the current pricing schedule. | -Each token purchase transition must comply with the [token direct purchase transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_direct_purchase_transition/v0/mod.rs#L20-L31). +Each token purchase transition must comply with the [token direct purchase transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_direct_purchase_transition/v0/mod.rs#L23-L34). From 7469d24de4bc9c131337192ca90aebf5af4fad5e Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 11:04:15 -0400 Subject: [PATCH 05/17] docs(protocol-ref): refresh identity and shielded pool links to v4.1.0 Update rs-dpp and rs-platform-value permalinks from v4.0.0 to v4.1.0 across the identity and shielded pool pages, correcting line anchors that shifted upstream. Shielded transition references now point at the specific v0/mod.rs definitions instead of the containing directory. Document the exit denominations accepted by the Identity Create From Shielded Pool transition, including the protocol version 13 set that adds 0.03 and 0.25 DASH and retires 0.3 DASH, and the version 12 set retained for chain replay. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/identity.md | 30 ++++++++++++------------ docs/protocol-ref/shielded-pool.md | 37 +++++++++++++++++++++--------- 2 files changed, 41 insertions(+), 26 deletions(-) diff --git a/docs/protocol-ref/identity.md b/docs/protocol-ref/identity.md index 4b4df2ae8..52b725e7f 100644 --- a/docs/protocol-ref/identity.md +++ b/docs/protocol-ref/identity.md @@ -17,7 +17,7 @@ Identities consist of multiple objects that are described in the following secti | [balance](#identity-balance) | unsigned integer (64-bit) | Credit balance associated with the identity | | revision | integer | Identity update revision | -See the [identity implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/v0/mod.rs#L36-L45) for more details. +See the [identity implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/v0/mod.rs#L38-L44) for more details. **Example Identity** @@ -46,17 +46,17 @@ The identity `id` is a unique identifier created from the double sha256 hash of `id = base58(sha256(sha256()))` :::{note} -The identity `id` uses the Dash Platform specific `application/x.dash.dpp.identifier` content media type. For additional information, please refer to the [js-dpp PR 252](https://github.com/dashevo/js-dpp/pull/252) that introduced it and [identifier.rs](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-value/src/types/identifier.rs). +The identity `id` uses the Dash Platform specific `application/x.dash.dpp.identifier` content media type. For additional information, please refer to the [js-dpp PR 252](https://github.com/dashevo/js-dpp/pull/252) that introduced it and [identifier.rs](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-value/src/types/identifier.rs). ::: -See rs-dpp for examples of using [InstantSend](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs#L146) or [ChainLocks](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs#L54) to create the identity id. +See rs-dpp for examples of using [InstantSend](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs#L142) or [ChainLocks](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs#L47) to create the identity id. ### Identity publicKeys The identity `publicKeys` array stores information regarding each public key associated with the identity. Multiple identities may use the same public key. :::{note} -Each identity must have exactly one master key ([security level](#public-key-securitylevel) `0`) used for updating the identity. Having an additional key ([security level](#public-key-securitylevel) `1` or `2`) for signing state transitions is strongly recommended but not enforced by the protocol. The maximum number of keys is 15000 as [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/fields.rs#L7). +Each identity must have exactly one master key ([security level](#public-key-securitylevel) `0`) used for updating the identity. Having an additional key ([security level](#public-key-securitylevel) `1` or `2`) for signing state transitions is strongly recommended but not enforced by the protocol. The maximum number of keys is 15000 as [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/fields.rs#L7). ::: Each item in the `publicKeys` array consists of an object containing: @@ -73,7 +73,7 @@ Each item in the `publicKeys` array consists of an object containing: | [disabledAt](#public-key-disabledat) | integer | Timestamp indicating that the key was disabled at a specified time | | signature | array of bytes | Signature of the signable identity create or topup state transition by the private key associated with this public key | -See the [public key implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/identity_public_key/v0/mod.rs#L42-L53) for more details. +See the [public key implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_public_key/v0/mod.rs#L42-L60) for more details. #### Public Key `id` @@ -81,7 +81,7 @@ Each public key in an identity's `publicKeys` array must be assigned a unique in #### Public Key `type` -The `type` field indicates the algorithm used to derive the key. Available key types [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/identity_public_key/key_type.rs#L46-L53) include: +The `type` field indicates the algorithm used to derive the key. Available key types [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_public_key/key_type.rs#L46-L53) include: | Type | Size (bytes) | Description | | :--: | :----------: | ----------- | @@ -97,7 +97,7 @@ The `data` field contains the compressed public key. #### Public Key `purpose` -The `purpose` field describes which operations are supported by the key. Please refer to [DIP11 - Identities](https://github.com/dashpay/dips/blob/master/dip-0011.md#keys) for additional information regarding this. Keys for some purposes must meet certain the security level criteria [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/methods/validate_identity_public_keys_structure/v0/mod.rs#L22-L37) as detailed below: +The `purpose` field describes which operations are supported by the key. Please refer to [DIP11 - Identities](https://github.com/dashpay/dips/blob/master/dip-0011.md#keys) for additional information regarding this. Keys for some purposes must meet certain the security level criteria [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/methods/validate_identity_public_keys_structure/v0/mod.rs#L22-L37) as detailed below: | Type | Description | Allowed Security Level(s) | | :--: | -------------- | ------------------------- | @@ -205,7 +205,7 @@ Identities are created on the platform by submitting the identity information in | signature | array of bytes | Signature of state transition data by the single-use key from the asset lock (65 bytes) | | identityId | array of bytes | An [identity id](#identity-id) for the identity being created (32 bytes). Computed from the asset lock proof outpoint and excluded from the serialized payload. | -See the [identity create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L47-L58) for more details. +See the [identity create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L43-L54) for more details. ### Identity TopUp @@ -220,7 +220,7 @@ Identity credit balances are increased by submitting the topup information in an | userFeeIncrease | integer | Extra fee to prioritize processing if the mempool is full. Typically set to zero. | | signature | array of bytes | Signature of state transition data by the single-use key from the asset lock (65 bytes) | -See the [identity topup implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L43-L50) for more details. +See the [identity topup implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L39-L46) for more details. ### Identity Update @@ -239,7 +239,7 @@ Identities are updated on the platform by submitting the identity information in | signaturePublicKeyId | integer | The ID of public key used to sign the state transition | | signature | array of bytes | Signature of state transition data (65 bytes) | -See the [identity update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L43-L72) for more details. +See the [identity update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L39-L68) for more details. ### Identity Credit Transfer @@ -257,7 +257,7 @@ Identities can transfer credits on the platform by submitting an identity credit | signaturePublicKeyId | integer | The ID of public key used to sign the state transition | | signature | array of bytes | Signature of state transition data (65 bytes) | -See the [identity credit transfer implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L42-L53) for more details. +See the [identity credit transfer implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L38-L49) for more details. ### Identity Credit Withdrawal @@ -277,17 +277,17 @@ Credits can be withdrawn from an identity to an external Core wallet using an id | signaturePublicKeyId | integer | The ID of public key used to sign the state transition | | signature | array of bytes | Signature of state transition data (65 bytes) | -See the [identity credit withdrawal implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/v1/mod.rs#L35-L52) for more details. +See the [identity credit withdrawal implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/v1/mod.rs#L31-L48) for more details. ### Asset Lock The [identity create](#identity-create) and [identity topup](#identity-topup) state transitions both include an asset lock proof object. This object references the Core chain [asset lock transaction](inv:user:std#ref-txs-assetlocktx) and includes proof that the transaction is locked. -Currently there are two types of asset lock proofs [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/mod.rs#L40-L43): InstantSend and ChainLock. Transactions almost always receive InstantSend locks, so the InstantSend asset lock proof is the predominate type. See rs-dpp for examples of using [InstantSend](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs) or [ChainLocks](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs) as the asset lock proof. +Currently there are two types of asset lock proofs [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/mod.rs#L40-L43): InstantSend and ChainLock. Transactions almost always receive InstantSend locks, so the InstantSend asset lock proof is the predominate type. See rs-dpp for examples of using [InstantSend](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs) or [ChainLocks](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs) as the asset lock proof. #### InstantSend Asset Lock Proof -The InstantSend asset lock proof is used for transactions that have received an InstantSend lock. Asset locks using an InstantSend lock as proof must comply with this structure established in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs#L38-L45). +The InstantSend asset lock proof is used for transactions that have received an InstantSend lock. Asset locks using an InstantSend lock as proof must comply with this structure established in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs#L38-L45). | Field | Type | Description | | ----------- | -------------- | ----------- | @@ -298,7 +298,7 @@ The InstantSend asset lock proof is used for transactions that have received an #### ChainLock Asset Lock Proof -The ChainLock asset lock proof is used for transactions that have not received an InstantSend lock, but have been included in a block that has received a ChainLock. Asset locks using a ChainLock as proof must comply with this structure established in [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs#L24-L29). +The ChainLock asset lock proof is used for transactions that have not received an InstantSend lock, but have been included in a block that has received a ChainLock. Asset locks using a ChainLock as proof must comply with this structure established in [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/chain/chain_asset_lock_proof.rs#L24-L29). | Field | Type | Description | | --------------------- | -------------- | ----------- | diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index a43b6f802..1d8e3ccfc 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -5,7 +5,7 @@ # Shielded Pool :::{attention} -Shielded state transitions were [enabled in Protocol Version 12](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs#L4). They use the [Orchard](https://zips.z.cash/protocol/protocol.pdf) shielded protocol to move credits into, within, and out of a pool that hides amounts, senders, and recipients. +Shielded state transitions were [enabled in Protocol Version 12](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs#L4). They use the [Orchard](https://zips.z.cash/protocol/protocol.pdf) shielded protocol to move credits into, within, and out of a pool that hides amounts, senders, and recipients. For the conceptual overview of how the pool works and when to use it, see [Shielded Pool](../explanations/shielded-pool.md). ::: @@ -38,7 +38,7 @@ Every shielded transition includes an Orchard bundle proving that a set of note | proof | array of bytes | Varies | Halo 2 zero-knowledge proof that the actions are valid | | bindingSignature | array of bytes | 64 bytes | RedPallas signature binding the bundle's actions to its net value balance | -See the [Orchard bundle primitives in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/shielded/mod.rs). +See the [Orchard bundle primitives in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/mod.rs). ### Actions @@ -55,9 +55,9 @@ Each action publishes: | cvNet | array of bytes | 32 bytes | Net value commitment (Pedersen commitment to the action's value contribution) | | spendAuthSig | array of bytes | 64 bytes | Per-action spend authorization signature — see [Shielded Transition Signing](#shielded-transition-signing) | -Permanent storage cost per action is [344 bytes](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/shielded/mod.rs#L32-L58) (312 bytes in the note commitment tree + 32 bytes in the nullifier tree). +Permanent storage cost per action is [344 bytes](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/mod.rs#L32-L58) (312 bytes in the note commitment tree + 32 bytes in the nullifier tree). -See the [serialized action implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/shielded/mod.rs). +See the [serialized action implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/mod.rs). ### Anchors @@ -71,7 +71,7 @@ Transitions with transparent fields (Unshield, Shielded Withdrawal, etc.) bind t SHA-256(SIGHASH_DOMAIN || bundle_commitment || extra_data) ``` -This prevents replay attacks where an attacker substitutes transparent fields while reusing a valid Orchard bundle. See the [platform sighash implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/shielded/sighash.rs#L21-L41). +This prevents replay attacks where an attacker substitutes transparent fields while reusing a valid Orchard bundle. See the [platform sighash implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/sighash.rs#L21-L41). ## Shielded State Transition Details @@ -95,7 +95,7 @@ Move credits from one or more [Platform addresses](address-system.md#platform-ad Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). Address witness signatures are excluded from the signable bytes used by the platform sighash. ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_transition/v0/mod.rs#L37-L63). ### Shielded Transfer @@ -113,7 +113,7 @@ Move credits within the pool between notes. There is no transparent surface — Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_transfer_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_transfer_transition/v0/mod.rs#L31-L42). ### Unshield @@ -132,7 +132,7 @@ Move credits from the pool to a [Platform address](address-system.md#platform-ad The `outputAddress` is bound to the Orchard bundle through the [platform sighash](#platform-sighash) to prevent substitution attacks. Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/unshield_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/unshield_transition/v0/mod.rs#L32-L45). ### Shield from Asset Lock @@ -153,7 +153,7 @@ Move credits from a Dash Core (L1) asset-lock transaction directly into the shie `valueBalance` must be greater than zero and at most `i64::MAX`. The ECDSA signature is excluded from the signable bytes used by the platform sighash. Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_asset_lock_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_asset_lock_transition/v0/mod.rs#L35-L60). ### Shielded Withdrawal @@ -174,7 +174,7 @@ Move credits from the pool back to Dash Core (L1). The funds leave Platform enti Transparent fields (`coreFeePerByte`, `pooling`, `outputScript`) are bound to the Orchard bundle through the [platform sighash](#platform-sighash). Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_withdrawal_transition/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_withdrawal_transition/v0/mod.rs#L33-L54). ### Identity Create From Shielded Pool @@ -195,7 +195,22 @@ Create a new identity funded directly from the shielded pool. The spend nullifie The new identity's id is derived from the sorted set of spend nullifiers, making it unique and single-use. The public keys, `denomination`, `sendToAddressOnCreationFailure`, and `identityId` are committed into the Orchard bundle (via `extra_sighash_data`), so the bundle cannot be redirected to a different identity. Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). ::: -See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/identity_create_from_shielded_pool_transition/). +#### Exit denominations + +:::{versionchanged} 4.1.0 +Protocol version 13 revised the exit denomination set. +::: + +The `denomination` field must exactly match one of the values accepted by the active protocol version. The set is replaced per protocol version rather than extended, so a denomination valid under one version may not be valid under the next. A denomination outside the active set is rejected with [`ShieldedInvalidDenominationError`](errors.md) (code 10827). + +| Protocol version | Accepted denominations | +| --- | --- | +| 13 | 0.03 DASH (3,000,000,000 credits), 0.1 DASH (10,000,000,000), 0.25 DASH (25,000,000,000), 0.5 DASH (50,000,000,000), 1 DASH (100,000,000,000) | +| 12 | 0.1 DASH (10,000,000,000 credits), 0.3 DASH (30,000,000,000), 0.5 DASH (50,000,000,000), 1 DASH (100,000,000,000) | + +Protocol version 13 added 0.03 and 0.25 DASH and retired 0.3 DASH. The protocol version 12 set is retained for chain replay. See the [denomination set in rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v9.rs#L336-L342). + +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/identity_create_from_shielded_pool_transition/v0/mod.rs#L31-L64). ## Shielded Transition Signing From 79d29d3dfa87f4093209848ec3a15b9cb2c34cae Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 11:57:49 -0400 Subject: [PATCH 06/17] docs(protocol-ref): refresh protocol constants to v4.1.0 system limits Update rs-dpp and rs-platform-version permalinks from v4.0.0 to v4.1.0, correcting line anchors that shifted upstream. System limit sources now point at system_limits/v3.rs, which supersedes v1.rs. Correct the minimum withdrawal amount to 1,000,000 credits (1,000 duffs), raised from 190,000 credits in protocol version 12, and source it from system limits rather than the withdrawal transition module. Add the maximum document value depth of 256 nested containers, introduced in protocol version 13 and unbounded in earlier versions. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/protocol-constants.md | 261 ++++++++++++------------ 1 file changed, 131 insertions(+), 130 deletions(-) diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 404ada52d..62e827c70 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -12,18 +12,19 @@ Maximum sizes and limits for various platform components. | Limit | Value | Description | Source | |-------|-------|-------------|--------| -| Max contract size | 16,384 bytes (16 KiB) | Maximum serialized data contract | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L4) | -| Max field value size | 5,120 bytes (5 KiB) | Maximum single field value | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L5) | -| Max state transition size | 20,480 bytes (20 KiB) | Maximum serialized state transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L6) | -| Max transitions in documents batch | 1 | Maximum document transitions per batch | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L20) | -| Withdrawals per block | 4 | Maximum withdrawal transactions per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L21) | -| Retry signing expired withdrawals per block | 1 | Max expired withdrawal retries per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L22) | -| Max withdrawal amount | 50,000,000,000,000 credits | 500 Dash maximum per withdrawal | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L23) | -| Max contract group size | 256 | Maximum members per group | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L27) | -| Max token redemption cycles | 128 | Maximum redemption cycles | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L28) | -| Max shielded transition actions | 16 | Maximum [actions](shielded-pool.md#actions) per shielded transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/system_limits/v1.rs#L36) | -| Max CBOR encoded length | 16,384 bytes (16 KiB) | Maximum CBOR encoding size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/util/cbor_serializer.rs#L8) | -| Contract deserialization limit | 15,000 | Maximum contract deserialization | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/serialized_version/mod.rs#L38) | +| Max contract size | 16,384 bytes (16 KiB) | Maximum serialized data contract | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L10) | +| Max field value size | 5,120 bytes (5 KiB) | Maximum single field value | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L11) | +| Max document value depth | 256 nested containers | Maximum nesting depth within a document property value (protocol version 13 and later; unbounded earlier) | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L14) | +| Max state transition size | 20,480 bytes (20 KiB) | Maximum serialized state transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L15) | +| Max transitions in documents batch | 1 | Maximum document transitions per batch | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L16) | +| Withdrawals per block | 4 | Maximum withdrawal transactions per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L17) | +| Retry signing expired withdrawals per block | 1 | Max expired withdrawal retries per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L18) | +| Max withdrawal amount | 50,000,000,000,000 credits | 500 Dash maximum per withdrawal | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L19) | +| Max contract group size | 256 | Maximum members per group | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L21) | +| Max token redemption cycles | 128 | Maximum redemption cycles | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L22) | +| Max shielded transition actions | 16 | Maximum [actions](shielded-pool.md#actions) per shielded transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L30) | +| Max CBOR encoded length | 16,384 bytes (16 KiB) | Maximum CBOR encoding size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/util/cbor_serializer.rs#L8) | +| Contract deserialization limit | 15,000 | Maximum contract deserialization | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/serialized_version/mod.rs#L40) | ## Credit System @@ -31,8 +32,8 @@ Credits are the unit of account for fees on Dash Platform. They are created from | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| `CREDITS_PER_DUFF` | 1,000 | Credits created per duff (satoshi) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/balances/credits.rs#L42) | -| `MAX_CREDITS` | 9,223,372,036,854,775,807 | Maximum credit value (i64::MAX) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/balances/credits.rs#L40) | +| `CREDITS_PER_DUFF` | 1,000 | Credits created per duff (satoshi) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/balances/credits.rs#L42) | +| `MAX_CREDITS` | 9,223,372,036,854,775,807 | Maximum credit value (i64::MAX) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/balances/credits.rs#L40) | **Conversion:** 1 Dash = 100,000,000 duffs = 100,000,000,000 credits @@ -44,13 +45,13 @@ These constants define the base costs for state transition processing. | Constant | Value (Credits) | Description | Source | |----------|-----------------|-------------|--------| -| `BASE_ST_PROCESSING_FEE` | 10,000 | Base state transition processing fee | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L3) | -| `DEFAULT_USER_TIP` | 0 | Default priority tip | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L4) | -| `STORAGE_CREDIT_PER_BYTE` | 5,000 | Storage cost per byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L5) | -| `PROCESSING_CREDIT_PER_BYTE` | 12 | Processing cost per byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L6) | -| `DELETE_BASE_PROCESSING_COST` | 2,000 | Base deletion cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L7) | -| `READ_BASE_PROCESSING_COST` | 8,400 | Base read cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L8) | -| `WRITE_BASE_PROCESSING_COST` | 6,000 | Base write cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L9) | +| `BASE_ST_PROCESSING_FEE` | 10,000 | Base state transition processing fee | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L3) | +| `DEFAULT_USER_TIP` | 0 | Default priority tip | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L4) | +| `STORAGE_CREDIT_PER_BYTE` | 5,000 | Storage cost per byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L5) | +| `PROCESSING_CREDIT_PER_BYTE` | 12 | Processing cost per byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L6) | +| `DELETE_BASE_PROCESSING_COST` | 2,000 | Base deletion cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L7) | +| `READ_BASE_PROCESSING_COST` | 8,400 | Base read cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L8) | +| `WRITE_BASE_PROCESSING_COST` | 6,000 | Base write cost | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/default_costs/constants.rs#L9) | ### State Transition Pricing @@ -58,20 +59,20 @@ These constants define minimum values required for a state transition to be cons | State Transition | Min Fee (Credits) | Min Fee (Dash) | Source | |------------------|-------------------|----------------|--------| -| Credit Transfer | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L4) | -| Credit Transfer to Addresses | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L5) | -| Credit Withdrawal | 400,000,000 | 0.004 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L6) | -| Identity Update | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L7) | -| Document Batch (per sub-transition) | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L8) | -| Contract Create | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L9) | -| Contract Update | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L10) | -| Masternode Vote | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L11) | -| Address Credit Withdrawal | 400,000,000 | 0.004 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L13) | -| Address Funds Transfer (per input) | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L14) | -| Address Funds Transfer (per output) | 6,000,000 | 0.00006 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L15) | -| Identity Create (base) | 2,000,000 | 0.00002 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L16) | -| Identity Key (per key at creation) | 6,500,000 | 0.000065 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L17) | -| Identity TopUp (base) | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L18) | +| Credit Transfer | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L4) | +| Credit Transfer to Addresses | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L5) | +| Credit Withdrawal | 400,000,000 | 0.004 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L6) | +| Identity Update | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L7) | +| Document Batch (per sub-transition) | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L8) | +| Contract Create | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L9) | +| Contract Update | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L10) | +| Masternode Vote | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L11) | +| Address Credit Withdrawal | 400,000,000 | 0.004 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L13) | +| Address Funds Transfer (per input) | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L14) | +| Address Funds Transfer (per output) | 6,000,000 | 0.00006 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L15) | +| Identity Create (base) | 2,000,000 | 0.00002 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L16) | +| Identity Key (per key at creation) | 6,500,000 | 0.000065 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L17) | +| Identity TopUp (base) | 500,000 | 0.000005 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L18) | ### Execution and Resource Pricing @@ -83,16 +84,16 @@ Fees for specific operations during state transition processing. | Operation | Fee (Credits) | Source | |-----------|---------------|--------| -| Fetch identity balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L4) | -| Fetch identity revision | 9,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L5) | -| Fetch identity balance and revision | 15,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L6) | -| Fetch identity key by ID | 9,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L7) | -| Fetch identity token balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L8) | -| Fetch prefunded specialized balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L9) | -| Fetch key with type, nonce and balance | 12,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L10) | -| Fetch single identity key | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L11) | -| Network threshold signing | 100,000,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L12) | -| Validate key structure | 50 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L13) | +| Fetch identity balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L4) | +| Fetch identity revision | 9,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L5) | +| Fetch identity balance and revision | 15,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L6) | +| Fetch identity key by ID | 9,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L7) | +| Fetch identity token balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L8) | +| Fetch prefunded specialized balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L9) | +| Fetch key with type, nonce and balance | 12,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L10) | +| Fetch single identity key | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L11) | +| Network threshold signing | 100,000,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L12) | +| Validate key structure | 50 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/processing/v1.rs#L13) | #### Storage @@ -100,11 +101,11 @@ Fees related to data storage operations. | Operation | Fee (Credits) | Source | |-----------|---------------|--------| -| Storage disk usage (per byte) | 27,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | -| Storage processing (per byte) | 400 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | -| Storage load (per byte) | 20 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | -| Non-storage load (per byte) | 10 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | -| Storage seek | 2,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Storage disk usage (per byte) | 27,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Storage processing (per byte) | 400 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Storage load (per byte) | 20 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Non-storage load (per byte) | 10 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Storage seek | 2,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/storage/v1.rs) | #### Cryptographic Operations @@ -114,11 +115,11 @@ Fees for verifying different signature types. | Key Type | Verification Fee (Credits) | Source | |----------|----------------------------|--------| -| ECDSA Secp256k1 | 15,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | -| BLS 12-381 | 300,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | -| ECDSA Hash160 | 15,500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | -| BIP13 Script Hash | 300,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | -| EdDSA 25519 Hash160 | 3,500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| ECDSA Secp256k1 | 15,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| BLS 12-381 | 300,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| ECDSA Hash160 | 15,500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| BIP13 Script Hash | 300,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| EdDSA 25519 Hash160 | 3,500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/signature/v1.rs) | ##### Hashing @@ -126,13 +127,13 @@ Fees for cryptographic hash operations. | Operation | Fee (Credits) | Source | |-----------|---------------|--------| -| Single SHA256 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| Blake3 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| SHA256 + RIPEMD160 (base) | 6,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| SHA256 (per block) | 5,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| Blake3 (per block) | 300 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| RIPEMD160 (per block) | 5,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | -| Sinsemilla (base) | 40,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Single SHA256 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Blake3 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| SHA256 + RIPEMD160 (base) | 6,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| SHA256 (per block) | 5,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Blake3 (per block) | 300 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| RIPEMD160 (per block) | 5,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Sinsemilla (base) | 40,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | #### Data Contract Validation @@ -140,13 +141,13 @@ Fees for validating data contract structure during state transition processing. | Fee Type | Amount (Credits) | Source | |----------|------------------|--------| -| Document type base fee | 500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L5) | -| Schema size fee (per byte) | 10 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L6) | -| Per property fee | 40 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L7) | -| Non-unique index base fee | 50 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L8) | -| Non-unique index per property fee | 30 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L9) | -| Unique index base fee | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L10) | -| Unique index per property fee | 60 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L11) | +| Document type base fee | 500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L5) | +| Schema size fee (per byte) | 10 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L6) | +| Per property fee | 40 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L7) | +| Non-unique index base fee | 50 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L8) | +| Non-unique index per property fee | 30 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L9) | +| Unique index base fee | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L10) | +| Unique index per property fee | 60 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L11) | ### Voting @@ -154,9 +155,9 @@ Fees related to contested document voting. | Fee Type | Amount (Credits) | Amount (Dash) | Source | |----------|------------------|---------------|--------| -| Contested document vote resolution fund | 20,000,000,000 | 0.2 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | -| Contested document unlock fund | 400,000,000,000 | 4.0 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | -| Single vote cost | 10,000,000 | 0.0001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | +| Contested document vote resolution fund | 20,000,000,000 | 0.2 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | +| Contested document unlock fund | 400,000,000,000 | 4.0 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | +| Single vote cost | 10,000,000 | 0.0001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | ## Identity Model @@ -164,20 +165,20 @@ Fees related to contested document voting. | Limit | Value | Description | Source | |-------|-------|-------------|--------| -| Max public keys per identity | 15,000 | Maximum keys an identity can have | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/fields.rs#L7) | -| Max keys in creation | 6 | Keys allowed at identity creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L18) | -| Identity nonce value filter | 0xFFFFFFFFFF | 40-bit nonce filter | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/identity_nonce.rs#L13) | -| Max missing identity revisions | 24 | Maximum revision gaps | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/identity/identity_nonce.rs#L15) | +| Max public keys per identity | 15,000 | Maximum keys an identity can have | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/fields.rs#L7) | +| Max keys in creation | 6 | Keys allowed at identity creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L18) | +| Identity nonce value filter | 0xFFFFFFFFFF | 40-bit nonce filter | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_nonce.rs#L13) | +| Max missing identity revisions | 24 | Maximum revision gaps | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_nonce.rs#L15) | ### Identity Create Fees | Requirement | Value | Description | Source | |-------------|-------|-------------|--------| -| Min asset lock balance | 200,000 duffs | 0.002 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L20) | -| Min top-up balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/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/v4.0.0/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/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L42) | -| 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/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | +| Min asset lock balance | 200,000 duffs | 0.002 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L20) | +| Min top-up balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/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/v4.1.0/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/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L42) | +| 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/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | ## Document & Data Contract Model @@ -185,20 +186,20 @@ Fees related to contested document voting. | Limit | Value | Description | Source | |-------|-------|-------------|--------| -| Max indexed string length | 63 characters | Maximum indexable string | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L24) | -| Max indexed byte array length | 255 bytes | Maximum indexable byte array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | -| Max indexed array items | 1,024 | Maximum items in indexed array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L26) | -| Max index size | 255 bytes | Maximum total index size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L40) | -| Default hash size | 32 bytes | Standard hash size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L37) | -| Default float size | 8 bytes | Standard float size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L38) | -| Empty tree storage size | 33 bytes | Storage for empty tree | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L39) | -| Storage flags size | 2 bytes | Size of storage flags | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) | +| Max indexed string length | 63 characters | Maximum indexable string | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L24) | +| Max indexed byte array length | 255 bytes | Maximum indexable byte array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | +| Max indexed array items | 1,024 | Maximum items in indexed array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L26) | +| Max index size | 255 bytes | Maximum total index size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L40) | +| Default hash size | 32 bytes | Standard hash size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L37) | +| Default float size | 8 bytes | Standard float size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L38) | +| Empty tree storage size | 33 bytes | Storage for empty tree | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L39) | +| Storage flags size | 2 bytes | Size of storage flags | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) | ### Data Contract Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| Initial contract version | 1 | Starting version number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/mod.rs#L76) | +| Initial contract version | 1 | Starting version number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/mod.rs#L76) | ### Data Contract Registration Fees @@ -206,15 +207,15 @@ One-time fees for registering data contracts and their components. | Component | Fee (Credits) | Fee (Dash) | Source | |-----------|---------------|------------|--------| -| Base contract registration | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Document type registration | 2,000,000,000 | 0.02 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Non-unique index registration | 1,000,000,000 | 0.01 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Unique index registration | 1,000,000,000 | 0.01 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Contested index registration | 100,000,000,000 | 1.0 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Token registration | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Token perpetual distribution | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Token pre-programmed distribution | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | -| Search keyword (per keyword) | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Base contract registration | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Document type registration | 2,000,000,000 | 0.02 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Non-unique index registration | 1,000,000,000 | 0.01 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Unique index registration | 1,000,000,000 | 0.01 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Contested index registration | 100,000,000,000 | 1.0 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Token registration | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Token perpetual distribution | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Token pre-programmed distribution | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | +| Search keyword (per keyword) | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | ### Tokens @@ -224,7 +225,7 @@ Tokens are defined within data contracts and share the same lifecycle, versionin | Limit | Value | Description | Source | |-------|-------|-------------|--------| -| Max token note length | 2,048 bytes | Maximum note/memo length | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/tokens/mod.rs#L19) | +| Max token note length | 2,048 bytes | Maximum note/memo length | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L19) | #### Token Distribution Function Limits @@ -232,17 +233,17 @@ These limits apply to token perpetual distribution function parameters. | Parameter | Min | Max | Source | |-----------|-----|-----|--------| -| `MAX_DISTRIBUTION_PARAM` | 1 | 281,474,976,710,655 (2^48 - 1) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L14) | -| `MAX_DISTRIBUTION_CYCLES_PARAM` | 1 | 32,767 (2^(63-48) - 1) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L20) | -| Linear slope A | -255 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Polynomial M | -8 | 8 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Polynomial N | 0 | 32 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Polynomial A | -255 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Log A | -32,766 | 32,767 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Exponential A | 1 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Exponential M | -8 | 8 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Exponential N | 0 | 32 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | -| Default step decreasing max cycles | 128 | 128 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L22) | +| `MAX_DISTRIBUTION_PARAM` | 1 | 281,474,976,710,655 (2^48 - 1) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L14) | +| `MAX_DISTRIBUTION_CYCLES_PARAM` | 1 | 32,767 (2^(63-48) - 1) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L20) | +| Linear slope A | -255 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Polynomial M | -8 | 8 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Polynomial N | 0 | 32 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Polynomial A | -255 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Log A | -32,766 | 32,767 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Exponential A | 1 | 256 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Exponential M | -8 | 8 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Exponential N | 0 | 32 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs) | +| Default step decreasing max cycles | 128 | 128 | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L22) | ## Address System @@ -253,42 +254,42 @@ 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/v4.0.0/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/v4.0.0/packages/rs-dpp/src/address_funds/platform_address.rs#L184) | -| Platform HRP (non-mainnet) | "tdash" | Human-readable prefix used for testnet, devnet, and regtest | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/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/v4.0.0/packages/rs-dpp/src/address_funds/platform_address.rs#L205) | -| P2SH address type (bech32m) | 0x80 (128) | Pay-to-script-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/address_funds/platform_address.rs#L207) | +| Address hash size | 20 bytes | Size of address hash | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/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/v4.1.0/packages/rs-dpp/src/address_funds/platform_address.rs#L255) | +| Platform HRP (non-mainnet) | "tdash" | Human-readable prefix used for testnet, devnet, and regtest | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/platform_address.rs#L257) | +| P2PKH address type (bech32m) | 0xb0 (176) | Pay-to-public-key-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/platform_address.rs#L276) | +| P2SH address type (bech32m) | 0x80 (128) | Pay-to-script-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/address_funds/platform_address.rs#L278) | ### Transaction Limits | Limit | Value | Description | Source | |-------|-------|-------------|--------| -| Min output amount | 500,000 credits | Minimum output per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L40) | -| Min input amount | 100,000 credits | Minimum input per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L41) | -| Max fee strategies | 4 | Maximum fee strategy steps | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L46) | -| Max address inputs | 16 | Maximum input addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L44) | -| Max address outputs | 128 | Maximum output addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L45) | -| Max asset lock transaction inputs | 100 | Maximum L1 transaction inputs in an asset lock proof | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | +| Min output amount | 500,000 credits | Minimum output per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L40) | +| Min input amount | 100,000 credits | Minimum input per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L41) | +| Max fee strategies | 4 | Maximum fee strategy steps | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L46) | +| Max address inputs | 16 | Maximum input addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L44) | +| Max address outputs | 128 | Maximum output addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L45) | +| Max asset lock transaction inputs | 100 | Maximum L1 transaction inputs in an asset lock proof | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | ## Epoch and Time Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| Genesis epoch index | 0 | First epoch number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/epoch/mod.rs#L45) | -| Perpetual storage eras | 50 | Number of storage eras (~50 years) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/epoch/mod.rs#L49) | -| Default epochs per era | 40 | Epochs in each era (~1 year) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/epoch/mod.rs#L51) | -| Epoch key offset | 256 | Offset for epoch keys | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/block/epoch/mod.rs#L6) | -| Max epoch | 65,279 | Maximum epoch number (u16::MAX - 256) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/block/epoch/mod.rs#L9) | +| Genesis epoch index | 0 | First epoch number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/epoch/mod.rs#L45) | +| Perpetual storage eras | 50 | Number of storage eras (~50 years) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/epoch/mod.rs#L49) | +| Default epochs per era | 40 | Epochs in each era (~1 year) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/epoch/mod.rs#L51) | +| Epoch key offset | 256 | Offset for epoch keys | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/block/epoch/mod.rs#L6) | +| Max epoch | 65,279 | Maximum epoch number (u16::MAX - 256) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/block/epoch/mod.rs#L9) | ## Refund Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| Min refund limit | 32 bytes | Minimum bytes for refund | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/fee/fee_result/refunds.rs#L23) | +| Min refund limit | 32 bytes | Minimum bytes for refund | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/fee/fee_result/refunds.rs#L23) | ## Withdrawal Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| Min withdrawal amount | 190,000 credits | ASSET_UNLOCK_TX_SIZE (190) × MIN_CORE_FEE_PER_BYTE (1) × CREDITS_PER_DUFF (1,000) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L48-L49) | -| Min core fee per byte | 1 | Must be Fibonacci number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.0.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L41) | +| Min withdrawal amount | 1,000,000 credits | 1,000 duffs minimum per withdrawal (protocol version 12 and later; raised from 190,000 credits in earlier versions) | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L20) | +| Min core fee per byte | 1 | Must be Fibonacci number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L37) | From 5081bafb2ff4a5786d5e7ec237a10fef125db9e7 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 14:17:56 -0400 Subject: [PATCH 07/17] docs(reference): document v4.1.0 request bounds and query limit semantics Document the aggregate query limit contract, including the omit-for-default sentinel convention and the prove-versus-no-proof handling of an oversized limit, plus how a cursor composes with a range operator. Add the new request bounds across the Platform and Core gRPC endpoints, the page-wide Platform request cap, and a stream termination and backpressure section covering RESOURCE_EXHAUSTED as a resumable signal. Scope getShieldedAnchors to the anchors a node retains, and document the two-proof envelope used for compacted address balance proofs at protocol version 13. Add glossary entries distinguishing the three history mechanisms, and repoint the DAPI code reference to rs-dapi. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/shielded-pool.md | 2 + .../dapi-endpoints-core-grpc-endpoints.md | 40 ++++++++++---- .../reference/dapi-endpoints-grpc-overview.md | 13 +++++ .../dapi-endpoints-platform-endpoints.md | 54 +++++++++++++++---- docs/reference/glossary.md | 12 +++++ docs/reference/platform-proofs.md | 26 ++++++++- docs/reference/query-syntax.md | 45 +++++++++++++++- .../retrieve-data-contract-history.md | 7 +++ 8 files changed, 175 insertions(+), 24 deletions(-) diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index 1d8e3ccfc..1392bab73 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -63,6 +63,8 @@ See the [serialized action implementation in rs-dpp](https://github.com/dashpay/ An **anchor** is the Sinsemilla root of the note commitment tree at the time the bundle was constructed. Each shielded transition specifies the anchor it was built against; the platform validates that the anchor was previously published. Clients fetch anchors using [`getShieldedAnchors`](../reference/dapi-endpoints-platform-endpoints.md#getshieldedanchors) or [`getMostRecentShieldedAnchor`](../reference/dapi-endpoints-platform-endpoints.md#getmostrecentshieldedanchor). +Anchors are not retained indefinitely. Nodes keep a rolling window governed by [`shielded_anchor_retention_blocks` and `shielded_anchor_pruning_interval`](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v1.rs#L275-L276), pruning anchors older than the retention window at each pruning boundary. A prover selecting an anchor must therefore choose one from the current window, not from arbitrary history. + ### Platform Sighash Transitions with transparent fields (Unshield, Shielded Withdrawal, etc.) bind those fields to the Orchard signatures via a platform sighash computed as: diff --git a/docs/reference/dapi-endpoints-core-grpc-endpoints.md b/docs/reference/dapi-endpoints-core-grpc-endpoints.md index 58ff793cd..0efdd6957 100644 --- a/docs/reference/dapi-endpoints-core-grpc-endpoints.md +++ b/docs/reference/dapi-endpoints-core-grpc-endpoints.md @@ -15,9 +15,13 @@ Please refer to the [gRPC Overview](../reference/dapi-endpoints-grpc-overview.md | Name | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------ | -| `transaction` | Bytes | Yes | A raw transaction | -| `allow_high_fees` | Boolean | No | Enables bypassing the high fee check | -| `bypass_limits` | Boolean | No | | +| `transaction` | Bytes | Yes | A raw transaction. Must be non-empty and must not exceed the standard transaction weight limit (400,000). | +| `allow_high_fees` | Boolean | No | Enables bypassing the high fee check. Currently ignored by the node. | +| `bypass_limits` | Boolean | No | Currently ignored by the node. | + +:::{versionadded} 4.1.0 +Two size checks were added. Raw transaction bytes exceeding the standard transaction weight limit are rejected with `RESOURCE_EXHAUSTED` before parsing, and a transaction whose computed weight exceeds that limit once parsed is rejected with `INVALID_ARGUMENT`. An empty or malformed transaction is also rejected with `INVALID_ARGUMENT`. +::: #### Example Request and Response @@ -399,12 +403,18 @@ This endpoint helps support simplified payment verification ([SPV](https://docs. | Name | Type | Required | Description | | ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- | | ---------- | | | | -| **One of the following:** | | | | -| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided | -| `from_block_height` | Integer | No | Return records beginning with the block height provided | +| **Exactly one of the following is required:** | | | | +| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided. Must be exactly 32 bytes. | +| `from_block_height` | Integer | No | Return records beginning with the block height provided. Minimum value is 1. | | ---------- | | | | | `count` | Integer | No | Number of blocks to sync. If set to 0 syncing is continuously sends new data as well (default: 0) | +:::{versionadded} 4.1.0 +`from_block_height` must be at least 1 and `from_block_hash` must be exactly 32 bytes; other values are rejected with `INVALID_ARGUMENT`. Omitting both is also rejected. + +A node accepts at most 64 concurrent streams on this endpoint. A subscribe attempt beyond that returns `RESOURCE_EXHAUSTED` — back off and retry, or connect to a different node. An established stream can also be terminated with `RESOURCE_EXHAUSTED`; see [stream termination and backpressure](dapi-endpoints-grpc-overview.md#stream-termination-and-backpressure). +::: + **Example Request and Response** ::::{tab-set} @@ -453,6 +463,10 @@ message and then streams masternode list updates with every new block. **Parameters**: None +:::{versionadded} 4.1.0 +A node accepts at most 64 concurrent streams on this endpoint. A subscribe attempt beyond that returns `RESOURCE_EXHAUSTED` — back off and retry, or connect to a different node. +::: + #### Example Request and Response ::::{tab-set} @@ -493,13 +507,19 @@ the update messages following a new block. | `bloom_filter.n_tweak` | Integer | Yes | A random value to add to the seed value in the hash function used by the bloom filter | | `bloom_filter.n_flags` | Integer | Yes | A set of flags that control how matched items are added to the filter | | ---------- | | | | -| **One of the following:** | | | | -| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided | -| `from_block_height` | Integer | No | Return records beginning with the block height provided | +| **Exactly one of the following is required:** | | | | +| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided. Must be exactly 32 bytes. | +| `from_block_height` | Integer | No | Return records beginning with the block height provided. Minimum value is 1. | | ---------- | | | | | `count` | Integer | No | Number of blocks to sync. If set to 0, syncing continuously sends new data as well (default: 0) | | `send_transaction_hashes` | Boolean | No | When `true`, includes transaction hashes in the response stream | +:::{versionadded} 4.1.0 +`from_block_height` must be at least 1 and `from_block_hash` must be exactly 32 bytes; other values are rejected with `INVALID_ARGUMENT`. Omitting both is also rejected. + +A node accepts at most 64 concurrent streams on this endpoint. A subscribe attempt beyond that returns `RESOURCE_EXHAUSTED` — back off and retry, or connect to a different node. An established stream can also be terminated with `RESOURCE_EXHAUSTED`; see [stream termination and backpressure](dapi-endpoints-grpc-overview.md#stream-termination-and-backpressure). +::: + **Example Request and Response** :::{note} @@ -990,5 +1010,5 @@ Note: The gRPCurl response `bestBlockHash`, `chainWork`, and `proTxHash` data is Implementation details related to the information on this page can be found in: -- The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/dapi) `packages/dapi/lib/grpcServer/handlers/core` folder +- The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/rs-dapi/src/services) `packages/rs-dapi/src/services` folder, which contains the DAPI implementation deployed by dashmate - The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/dapi-grpc) `packages/dapi-grpc/protos/core` folder diff --git a/docs/reference/dapi-endpoints-grpc-overview.md b/docs/reference/dapi-endpoints-grpc-overview.md index 5ad55f548..a9ee7d52e 100644 --- a/docs/reference/dapi-endpoints-grpc-overview.md +++ b/docs/reference/dapi-endpoints-grpc-overview.md @@ -35,3 +35,16 @@ The [gRPC UI](https://github.com/fullstorydev/grpcui) tool provides a way to int # Use Core gRPC grpcui -insecure -open-browser -proto protos/core/v0/core.proto seed-1.testnet.networks.dash.org:1443 ``` + +## Stream termination and backpressure + +:::{versionadded} 4.1.0 +::: + +Streaming endpoints apply per-stream delivery bounds, so a stream that has already been established can be terminated by the server with `RESOURCE_EXHAUSTED`. This happens when: + +- The client cannot keep up with delivery and the stream's pending-event or pending-byte budget is exceeded. +- The initial mempool snapshot exceeds the per-stream transaction count or byte budget. +- The handover from replaying historical data to live delivery does not complete within 180 seconds. + +Treat this status as a resumable backpressure signal rather than a fatal error: reconnect and resume from the last block your client finished processing. A `RESOURCE_EXHAUSTED` returned when *opening* a stream means the node's concurrent-stream limit for that endpoint is reached — back off and retry, or connect to a different node. diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index c16dc8d20..c1301fce5 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -13,6 +13,12 @@ Please refer to the [gRPC Overview](../reference/dapi-endpoints-grpc-overview.md All Dash Platform endpoints are versioned so future updates can be done without creating significant issues for API consumers. +### Request size limit + +:::{versionadded} 4.1.0 +Platform gRPC requests are capped at 128 KiB encoded, reduced from 64 MiB. A larger request is rejected by the transport before it reaches the endpoint. The limit sits above every per-endpoint budget — the largest are [`getPathElements`](#getpathelements) at 64 KiB of path and key components and [`broadcastStateTransition`](#broadcaststatetransition) at 20 KiB — so requests within those bounds are unaffected. +::: + ### Data Proofs and Metadata Platform gRPC endpoints can provide [proofs](https://github.com/dashpay/platform/blob/master/packages/dapi-grpc/protos/platform/v0/platform.proto#L142-L149) so the data returned for a request can be verified as being valid. When requesting proofs, the data requested will be encoded as part of the proof in the response. Proofs are supported in the [js-evo-sdk](https://github.com/dashpay/platform/tree/master/packages/js-evo-sdk) and via the low-level [dapi-grpc library](https://github.com/dashpay/platform/tree/master/packages/dapi-grpc). @@ -1197,7 +1203,7 @@ Returns one aggregate count, or per-group counts when `group_by` is set. Require | `selects` | `[Select{ function: COUNT }]` | Yes | Projection. | | `group_by` | Repeated string | No | `[]`, `[in_field]`, `[range_field]`, or `[in_field, range_field]`. | -`limit` is rejected for `group_by=[]` and `group_by=[in_field]` (the result is bounded by construction). `start_at` / `start_after` are not valid in this mode — paginate by narrowing the where clause. +`limit` is rejected for `group_by=[]` and `group_by=[in_field]` (the result is bounded by construction). `limit: 0` is rejected with `InvalidLimit` in every mode — omit the field to request the server default (SDK bindings that require a numeric argument use `-1`). `start_at` / `start_after` are not valid in this mode — paginate by narrowing the where clause. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries) for the full per-mode contract. **Response shape** @@ -1265,7 +1271,7 @@ Returns the sum of an integer field across matched documents, or per-group sums | `selects` | `[Select{ function: SUM, field: "" }]` | Yes | `field` must name the summable property. | | `group_by` | Repeated string | No | Same shape rules as Count above. | -`start_at` / `start_after` are not valid. +`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries). **Response shape** @@ -1331,7 +1337,7 @@ Why `(count, sum)` instead of a single `average`? Returning the pair preserves f | `selects` | `[Select{ function: AVG, field: "" }]` | Yes | `field` must name the averageable property. | | `group_by` | Repeated string | No | Same shape rules as Count above. | -`start_at` / `start_after` are not valid. +`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries). **Response shape** @@ -2682,7 +2688,11 @@ The [`waitForStateTransitionResult` endpoint](#waitforstatetransitionresult) sho | Name | Type | Required | Description | | ------------------ | -------------- | -------- | -------------------------------------------------------------------- | -| `state_transition` | Bytes (Base64) | Yes | A [state transition](../explanations/platform-protocol-state-transition.md) | +| `state_transition` | Bytes (Base64) | Yes | A [state transition](../explanations/platform-protocol-state-transition.md). Must be non-empty and no larger than the maximum state transition size (20 KiB at protocol version 13). | + +:::{versionadded} 4.1.0 +DAPI now rejects an oversized state transition with `INVALID_ARGUMENT` before attempting to broadcast it. An empty payload is rejected the same way. The DAPI-side check is a static upper bound; Drive enforces the active protocol version's limit authoritatively, so a state transition that passes this check can still be rejected later. +::: ```{eval-rst} .. @@ -2703,9 +2713,15 @@ The [`waitForStateTransitionResult` endpoint](#waitforstatetransitionresult) sho | Name | Type | Required | Description | | ----------------------- | ------- | -------- | -------------------------------- | -| `state_transition_hash` | Bytes | Yes | Hash of the state transition | +| `state_transition_hash` | Bytes | Yes | Hash of the state transition. Must be exactly 32 bytes (the SHA-256 of the serialized state transition). | | `prove` | Boolean | Yes | Set to `true` to request a proof. The data requested will be encoded as part of the proof in the response. | +:::{versionadded} 4.1.0 +A `state_transition_hash` of any length other than 32 bytes is now rejected with `INVALID_ARGUMENT`. Previously only an empty hash was rejected, so a truncated or differently derived hash was accepted and simply never matched, causing the call to wait until it timed out. + +A node also serves a bounded number of concurrent pending waits (1,024). Once saturated, further calls return `RESOURCE_EXHAUSTED`; clients should back off and retry, or connect to a different node. +::: + **Example Request** ```{eval-rst} @@ -3046,12 +3062,18 @@ Retrieves finalized epoch information within a specified index range. | Name | Type | Required | Description | | ---------------------------- | ------- | -------- | ----------- | -| `start_epoch_index` | Integer | No | Starting epoch index for the query | +| `start_epoch_index` | Integer | No | Starting epoch index for the query. Must not exceed 65,279. | | `start_epoch_index_included` | Boolean | No | Whether to include the `start_epoch_index` in the results | -| `end_epoch_index` | Integer | No | Ending epoch index for the query | +| `end_epoch_index` | Integer | No | Ending epoch index for the query. Must not exceed 65,279. | | `end_epoch_index_included` | Boolean | No | Whether to include the `end_epoch_index` in the results | | `prove` | Boolean | No | Set to `true` to receive a cryptographic proof instead of epoch data | +:::{versionadded} 4.1.0 +The requested range may contain at most 100 epochs, and each index must be no greater than 65,279. Exceeding either bound returns `InvalidArgument`. The `*_included` flags count toward the range size, so callers requesting a wider window must page through it in successive requests of at most 100 epochs each. + +When `start_epoch_index` and `end_epoch_index` are equal, both boundaries must be included or the request is rejected, since the range would otherwise be empty. +::: + **Example Request and Response** ::::{tab-set} @@ -3199,10 +3221,14 @@ Retrieves elements for a specified path in the platform. | Name | Type | Required | Description | | ------- | -------- | -------- | ----------- | -| `path` | Array | Yes | The path for which elements are being requested | -| `keys` | Array | No | The keys associated with the elements being requested | +| `path` | Array | Yes | The path for which elements are being requested. At most 256 components, each no larger than 255 bytes. | +| `keys` | Array | No | The keys associated with the elements being requested. At most 100 entries, each no larger than 255 bytes. | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested elements | +:::{versionadded} 4.1.0 +Requests are now bounded: at most 256 path components, at most 100 keys, at most 255 bytes per component, and at most 64 KiB for the combined byte length of all path and key components. Exceeding any of these returns `RESOURCE_EXHAUSTED`. +::: + **Example Request and Response** ::::{tab-set} @@ -4654,7 +4680,7 @@ grpcurl -proto protos/platform/v0/platform.proto \ ### getShieldedAnchors -Returns all commitment tree anchors for the shielded pool. Anchors are used by shielded transaction provers to reference a valid state of the commitment tree. +Returns the commitment tree anchors currently retained by the node for the shielded pool. Anchors are used by shielded transaction provers to reference a valid state of the commitment tree. **Returns**: A list of commitment tree anchors or a cryptographic proof. @@ -4664,6 +4690,12 @@ Returns all commitment tree anchors for the shielded pool. Anchors are used by s |---------|---------|----------|-------------| | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested anchors | +The response covers the [node's retention window](../protocol-ref/shielded-pool.md#anchors) rather than the full history of the pool: older anchors are pruned, so the retained set is bounded by the retention and pruning policy. + +:::{versionadded} 4.1.0 +If the retained anchor set exceeds what this unpaginated response can enumerate, the call returns `RESOURCE_EXHAUSTED` instead of doing unbounded work. Treat it as retryable rather than fatal. +::: + **Example Request and Response** ::::{tab-set} @@ -4930,5 +4962,5 @@ A nullifier's `is_spent` field is omitted from the response when `false` (proto3 Implementation details related to the information on this page can be found in: -* The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/dapi) `packages/dapi/lib/grpcServer/handlers/core` folder +* The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/rs-dapi/src/services) `packages/rs-dapi/src/services` folder, which contains the DAPI implementation deployed by dashmate * The [Platform repository](https://github.com/dashpay/platform/tree/master/packages/dapi-grpc) `packages/dapi-grpc/protos` folder diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index d19e2b896..dabeada8b 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -118,6 +118,18 @@ An epoch is a fixed time period used to organize and manage blockchain operation An era consists of 40 [epochs](#epoch) and equals approximately one year. At the end of an era, Dash Platform may optionally do additional accounting or reconfiguration. +## History (contract revision) + +The record of successive revisions of a [data contract](#data-contract), retained when the contract sets `keepsHistory` at creation. Retrieved with [`getDataContractHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracthistory). This tracks changes to the contract definition itself, not to the documents stored under it. See [Retrieve data contract history](../tutorials/contracts-and-documents/retrieve-data-contract-history.md). + +## History (document revision) + +The record of successive revisions of an individual [document](#document), retained when its document type sets `documentsKeepHistory`. Retrieved with [`getDocumentHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdocumenthistory). This tracks edits to a document's own fields, not its transfers or sales. + +## History (document ownership and pricing) + +The record of transfers, purchases and price updates for documents, written to the [document history system contract](../protocol-ref/data-contract.md#document-history-system-contract). Document types opt in with the [document history flags](../protocol-ref/data-contract-document.md#document-history-flags) `keepsTransferHistory`, `keepsPurchaseHistory` and `keepsPricingHistory`. This is separate from both revision histories above: it records ownership and pricing events rather than changes to contract or document content. + ## Layer (1, 2, 3) - Layer 1: Core blockchain and [Dash Core](#dash-core) diff --git a/docs/reference/platform-proofs.md b/docs/reference/platform-proofs.md index 2061862de..41457ecf3 100644 --- a/docs/reference/platform-proofs.md +++ b/docs/reference/platform-proofs.md @@ -19,8 +19,9 @@ flow, what can be proven, and asset lock proofs -- see [Proofs](../explanations/ ## Proof structure -A `Proof` is a single unified [GroveDB](https://github.com/dashpay/grovedb) proof plus the -consensus signature that authenticates it. It has six fields: +A `Proof` is normally a single unified [GroveDB](https://github.com/dashpay/grovedb) proof plus the +consensus signature that authenticates it. One response type is an exception: see [compacted +address balance proofs](#compacted-address-balance-proofs) below. A `Proof` has six fields: | Field | Type | Description | | - | - | - | @@ -62,6 +63,27 @@ is documented in the [GroveDB Proof System documentation](https://dashpay.github.io/grovedb/proof-system.html). Clients that use an SDK do not need to work at this level. +### Compacted address balance proofs + +:::{versionchanged} 4.1.0 +At protocol version 13 and above, the `grovedbProof` returned by +[`getRecentCompactedAddressBalanceChanges`](../reference/dapi-endpoints-platform-endpoints.md#getrecentcompactedaddressbalancechanges) +is not a single GroveDB proof. It is a [bincode envelope carrying two independent GroveDB +proofs](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/verify/address_funds/verify_compacted_address_balance_changes/mod.rs#L21-L30): + +- a **predecessor proof**, which authenticates which compacted range contains the requested start height, and +- a **forward proof**, verified against a query derived only from that authenticated result. + +Both proofs must commit to the same state root hash. Binding the forward query's start key to an +independently verified predecessor result makes this trust model slightly stronger than the +single-proof case. Protocol version 12 and below use the legacy single-proof format for this +response. + +A verifier written for the single-proof model will fail to decode a protocol version 13 compacted +proof, so clients implementing verification outside the provided SDKs must handle both formats and +select by protocol version. +::: + ## Related topics - [Proofs](../explanations/proofs.md) -- the conceptual trust model, verification flow, and asset lock proofs diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index 63d2b35b3..cf9061168 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -157,7 +157,7 @@ The query modifiers described here determine how query results will be sorted an | Modifier | Effect | Example | | - | - | - | -| `limit` | Restricts the number of results returned (maximum: 100) | `limit: 10` | +| `limit` | Restricts the number of results returned. Defaults to 100 when omitted, and the [maximum is also 100](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/config.rs#L16-L18). Both values come from Drive's `default_query_limit` / `max_query_limit` node configuration rather than from the protocol, so an operator can tune them. | `limit: 10` | | `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: ''` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: ''` | @@ -167,6 +167,17 @@ The query modifiers described here determine how query results will be sorted an For indices composed of multiple fields ([example from the DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)), the sort order in an `orderBy` must either match the order defined in the data contract OR be the inverse order. ::: +### Combining a cursor with a range operator + +When a `startAt` / `startAfter` cursor is combined with a range operator (`>`, `>=`, `<`, `<=`), the cursor narrows the effective range in the direction of the `orderBy` sort: + +- Ascending order — the cursor is the lower bound and the range clause's value is the upper bound. `startAfter` excludes the cursor row itself. +- Descending order — the roles invert: the range clause's value is the lower bound and the cursor is the upper bound. + +:::{versionchanged} 4.1.0 +Ascending queries that combined a cursor with a `<` or `<=` clause previously [built their range backwards](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/query/conditions.rs#L944-L990), returning incorrect or empty results. Paginating a bounded range now returns the expected results, so a query written against the earlier behavior may return different results after upgrading. +::: + ## Aggregate Queries :::{versionadded} 4.0.0 @@ -187,6 +198,38 @@ Aggregate queries impose extra schema requirements on the document type — `COU `SUM` / `AVG` integer values are returned as JS strings so JavaScript clients don't lose precision on values larger than `Number.MAX_SAFE_INTEGER`. +### Limits on aggregate queries + +The `limit` modifier behaves differently on the aggregate surface than it does when returning documents, and in some `select` × `groupBy` combinations it is rejected outright. On the wire, [`limit` is an optional field](https://github.com/dashpay/platform/blob/v4.1.0/packages/dapi-grpc/protos/platform/v0/platform.proto#L958-L1002): + +- Omit `limit` to request the server's default. +- Send a positive value to request an explicit cap. +- `limit: 0` is rejected with `InvalidLimit` in every `select` mode. A zero cap is structurally meaningless, so it is never treated as "no limit". + +SDK bindings that must pass a numeric argument use `-1` as the server-default sentinel; any other negative value is rejected. + +:::{versionadded} 4.1.0 +An effective limit of zero is now rejected with `InvalidLimit` rather than walking storage with a zero bound, which previously surfaced as an empty result set. +::: + +How a positive `limit` is interpreted depends on `groupBy`: + +| `select` / `groupBy` | Effect of `limit` | +| - | - | +| `DOCUMENTS` | Caps the number of matched documents, as described under [Query Modifiers](#query-modifiers). | +| `COUNT` with an empty `groupBy` | Rejected with `InvalidLimit`. An aggregate count is a single row by construction. | +| `COUNT` grouped by an `In` field | Rejected with `InvalidLimit`. The `In` array is already capped at 100 entries, so the result is bounded. Narrow the `In` array instead. | +| `COUNT` grouped by a range field | Caps the distinct-range walk, so the response carries at most `limit` groups. | +| `COUNT` grouped by an `In` field and a range field | A global cap over the emitted stream, not a per-branch cap. With three `In` values and `limit: 5`, the response carries at most 5 entries in total across all branches. | + +`SUM` and `AVG` follow the same policy as `COUNT`: distinct walks apply the default/cap/reject-zero rules, and a zero limit is rejected. + +:::{attention} +On range-grouped aggregates, an oversized `limit` is handled differently depending on whether a proof is requested. With `prove: true`, a `limit` above the node's maximum (100 by default) is rejected with `InvalidLimit` so that proof bytes stay deterministic. With `prove: false`, the limit is silently clamped to the maximum instead — a caller requesting 500 groups receives at most 100 with no error, which can look like missing data. +::: + +Compound carrier-aggregate shapes that pair an `In` field with a range field and request a proof cap the outer range walk at [10 entries](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/query/drive_document_count_query/mod.rs#L127). This is a hard ceiling: a `limit` above it is rejected, and callers needing more results issue repeated queries over disjoint outer-range windows. + :::{note} `HAVING`, `OFFSET`, `COUNT()`, `MIN`, `MAX`, and multi-projection `SELECT` are present on the wire but currently return `Unsupported`. Callers can encode them in builders ahead of server support landing, but evaluation rejects them today. ::: diff --git a/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md b/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md index d3824afcf..c5918c5c2 100644 --- a/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md +++ b/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md @@ -9,6 +9,13 @@ Contract tutorial](../../tutorials/contracts-and-documents/register-a-data-contr contracts that have enabled the `keepsHistory` option during contract creation will store revision information. +:::{note} +This retrieves revisions of the contract definition. It does not return the revision history of +individual documents (see [`getDocumentHistory`](../../reference/dapi-endpoints-platform-endpoints.md#getdocumenthistory)) +or records of document transfers and sales (see [document ownership and pricing +history](../../reference/glossary.md#history-document-ownership-and-pricing)). +::: + ## Prerequisites * [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) From 324135b13b16def763527fabc3ecb2f2a0128525 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 15:24:46 -0400 Subject: [PATCH 08/17] docs: point previous-version links at 4.0.0 Update the archived docs links in the index and DAPI endpoint reference from 2.0.0 to 4.0.0, and clarify in CLAUDE.md that endpoint version annotations are bolded/italicized by major release. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 2 +- docs/index.md | 2 +- docs/reference/dapi-endpoints.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9760866d1..9f614f5ce 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -89,7 +89,7 @@ The DAPI endpoint reference is split between an overview page (`docs/reference/d 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 `
` and the description. Use **bold** for the current release's annotations; older releases use *italics*. +- 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 `
` and the description. Use **bold** for the current major release's annotations; older major 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). diff --git a/docs/index.md b/docs/index.md index 8b898e7f4..de23c7bca 100644 --- a/docs/index.md +++ b/docs/index.md @@ -187,7 +187,7 @@ Testnet Block Explorer Testnet Faucet Evo SDK Playground Dash Platform Book -Previous Version of Docs +Previous Version of Docs ``` ```{toctree} diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index 188789b23..bac983b87 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -175,7 +175,7 @@ The following endpoints provide information about the Core chain. :::{note} The previous version of documentation can be [viewed -here](https://docs.dash.org/projects/platform/en/2.0.0/docs/reference/dapi-endpoints.html). +here](https://docs.dash.org/projects/platform/en/4.0.0/docs/reference/dapi-endpoints.html). ::: ```{toctree} From 2788e5bd55ce354afcd64582ef8eaf0b4471c133 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 15:42:16 -0400 Subject: [PATCH 09/17] docs: correct FAQ username transfer answer and note proof height anchoring Add a verification step to the proofs explanation noting that a client checks the block height a response is anchored to, rejecting responses that have fallen too far behind the most recent height seen or that omit the information entirely. This is enforced by verify_metadata_height in rs-sdk, which the previous root-hash and signature steps did not cover. Co-Authored-By: Claude Opus 5 --- docs/explanations/proofs.md | 3 ++- docs/resources/faq.md | 5 ++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/explanations/proofs.md b/docs/explanations/proofs.md index 531cdf524..90618055a 100644 --- a/docs/explanations/proofs.md +++ b/docs/explanations/proofs.md @@ -56,7 +56,8 @@ The complete verification process follows these steps: 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 +6. Client checks that the response is anchored to an acceptable block height, rejecting responses whose height has fallen too far behind the most recent one seen and responses that omit this information entirely +7. If these verifications pass, the data is cryptographically confirmed ## What Can Be Proven diff --git a/docs/resources/faq.md b/docs/resources/faq.md index 1f3b0fa72..be4c6d53f 100644 --- a/docs/resources/faq.md +++ b/docs/resources/faq.md @@ -159,7 +159,10 @@ identity and votes to lock the name, the identity receives the name. :::{dropdown} Can usernames be transferred? -Currently, usernames are non-transferrable. Future updates may enable transfers. +Yes. Since Dash Platform v4.1, a username can be transferred to another identity, or listed for sale +and purchased by another identity. After a transfer or sale, the name resolves to its new owner. The +name record itself remains immutable and permanent - it cannot be edited or deleted, only transferred +or sold. See [Name transfers and sales](../explanations/dpns.md#name-transfers-and-sales) for details. ::: From b05050740065e32623185c7caeda8159a24f04c4 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 6 Aug 2026 17:10:01 -0400 Subject: [PATCH 10/17] docs(explanations): correct v4.1.0 drift across explanation pages Apply the v4.1.0 explanation audit. The largest cluster is immutability: token configuration marked Description, keep history, start paused, allow transfer to frozen balance, and main control group modification as mutable when they are fixed at registration, and the data contract page listed token configuration changes as a permitted contract update that validation always rejects. Correct outright-wrong mechanics: document create and replace no longer list platform-assigned timestamps as caller-supplied fields, token fees are scoped per document type and per action rather than contract-wide, the fee multiplier no longer claims to scale user-paid fees, and query.md no longer denies the history queries that ship in v4.1.0. Document the shielded pool constraints that reject otherwise-valid transitions - the minimum pool notes gate on exits, anchor expiry, and the fixed identity-creation denominations - and propagate the address system and shielded pool into the protocol overview, state transition authorization, and proofs coverage. Also split the withdrawals data trigger rows, add the masternode rewards bindings, point the binding list at the active version, attribute Drive and platform chain hosting to evonodes, and fix the DPNS contested name criteria. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanations/dapi.md | 2 +- docs/explanations/dpns.md | 6 +-- docs/explanations/drive-platform-chain.md | 4 +- docs/explanations/drive.md | 2 +- docs/explanations/fees.md | 8 ++-- docs/explanations/identity.md | 10 +++-- docs/explanations/nft.md | 6 +-- docs/explanations/platform-consensus.md | 10 ++--- .../platform-protocol-data-contract.md | 5 ++- .../platform-protocol-data-trigger.md | 13 +++--- .../platform-protocol-document.md | 16 ++++--- .../platform-protocol-state-transition.md | 6 ++- docs/explanations/platform-protocol.md | 29 +++++++++---- docs/explanations/proofs.md | 16 ++++++- docs/explanations/query.md | 4 +- docs/explanations/shielded-pool.md | 7 ++++ docs/explanations/tokens.md | 42 ++++++++++++------- 17 files changed, 123 insertions(+), 63 deletions(-) diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md index b5cc9eeac..9c50e1cfe 100644 --- a/docs/explanations/dapi.md +++ b/docs/explanations/dapi.md @@ -31,4 +31,4 @@ 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 as well as streaming of events related to blocks, transactions/transitions, and masternode-list updates. 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/). 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). diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index 145771aee..ea247c9cc 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -42,8 +42,8 @@ Since some names may be popular, the registration process includes a voting mech :::{note} This process only applies to valid names that meet the following conditions: -* Less than 20 characters long (i.e. "alice", "quantumexplorer") AND -* Contain no numbers or only contain the number(s) 0 and/or 1 (i.e. "bob", "carol01") +* Between 3 and 19 characters long (i.e. "alice", "quantumexplorer") AND +* Contain no numbers other than 0 and/or 1, and no characters besides letters and hyphens (i.e. "bob", "carol01", "quantum-explorer") All other available names can be registered immediately. ::: @@ -72,7 +72,7 @@ Locked names cannot currently be re-requested or awarded. This policy may be rev ### Name transfers and sales -Registering a name is not necessarily the end of its lifecycle. Since Dash Platform v4.1, a registered name can be transferred to another identity or offered for sale and bought by another identity. Once ownership changes, the name resolves to its new owner, and that identity's private keys are what prove ownership from then on. +Registering a name is not necessarily the end of its lifecycle. A registered name can be transferred to another identity or offered for sale and bought by another identity. The DPNS contract has always declared names transferable and available for direct purchase, but Platform's validation rules rejected those operations until protocol version 13 (introduced in Dash Platform v4.1) lifted the restriction. Once ownership changes, the name resolves to its new owner, and that identity's private keys are what prove ownership from then on. The name record itself remains immutable and permanent: it cannot be edited or deleted, only transferred or sold. A name's transfer, purchase, and listing history is recorded, so the chain of ownership and the prices it was offered at can be retrieved and verified. diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md index b81b00d1d..50b698db1 100644 --- a/docs/explanations/drive-platform-chain.md +++ b/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 masternodes participating in the network. Masternodes 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 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. ## Details @@ -19,7 +19,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) -- Hosted exclusively on masternodes +- 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 - Provides fast (~5 second target block spacing) and absolute block finality (no reorgs) diff --git a/docs/explanations/drive.md b/docs/explanations/drive.md index f4dadeebe..27a0168ee 100644 --- a/docs/explanations/drive.md +++ b/docs/explanations/drive.md @@ -6,7 +6,7 @@ ## Overview -Using the traditional, layer 1 blockchain for data storage is widely known to be expensive and inefficient. Consequently, data for Dash Platform applications is stored in Drive, a layer 2 component that provides decentralized storage hosted by masternodes. As data changes over time, Drive maintains a record of the current state of each item to support easy retrieval using [DAPI](../explanations/dapi.md). +Using the traditional, layer 1 blockchain for data storage is widely known to be expensive and inefficient. Consequently, data for Dash Platform applications is stored in Drive, a layer 2 component that provides decentralized storage hosted by evonodes. As data changes over time, Drive maintains a record of the current state of each item to support easy retrieval using [DAPI](../explanations/dapi.md). ## Details diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index 7987584cb..6bd7e113f 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -42,13 +42,11 @@ Refer to the [Identity explanation](../explanations/identity.md) section for inf ## Fee Multiplier -Given fluctuations of the Dash price, a variable *Fee Multiplier* provides a way to balance the cost of fees with network hosting requirements. All fees are multiplied by the 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. -```text - feePaid = initialFee * feeMultiplier -``` +The multiplier does not scale the fee a user is charged. The active fee version fixes it at 1.0x, and the fee charged for a state transition is the sum of its storage and per-operation processing costs as described above. -The Fee Multiplier is subject to change at any time via network governance and protocol updates. +Fee parameters, including the multiplier, are fixed by the active fee version. They change only when the network activates a new protocol version, which happens once enough evonodes signal the newer version and the threshold is met at an epoch change. \n" - } - [/block] + Response shape: { "fee": } ``` ## Deprecated Endpoints @@ -859,7 +874,10 @@ The following endpoints were recently deprecated. See the [previous version of d ### getStatus :::{attention} -Deprecated in Dash Platform v1.0.0 +Deprecated in Dash Platform v1.0.0. Replaced by [`getBlockchainStatus`](#getblockchainstatus) and +[`getMasternodeStatus`](#getmasternodestatus). This is distinct from the Platform +[`getStatus`](../reference/dapi-endpoints-platform-endpoints.md#getstatus) endpoint, which remains +available. ::: **Returns**: Status information from the Core chain diff --git a/docs/reference/dapi-endpoints-json-rpc-endpoints.md b/docs/reference/dapi-endpoints-json-rpc-endpoints.md index 53095b021..f794b6290 100644 --- a/docs/reference/dapi-endpoints-json-rpc-endpoints.md +++ b/docs/reference/dapi-endpoints-json-rpc-endpoints.md @@ -222,6 +222,64 @@ puts response.read_body } ``` +### getStatus + +**Returns**: Platform status information. This is the JSON-RPC equivalent of the Platform +[`getStatus`](../reference/dapi-endpoints-platform-endpoints.md#getstatus) gRPC endpoint, and returns +the same response object. + +**Parameters**: none + +#### Example Request and Response + +::::{tab-set} +:::{tab-item} Curl +:sync: curl +```shell +curl -k --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{ + "method":"getStatus", + "id":1, + "jsonrpc":"2.0", + "params":{} + }' +``` +::: +:::: + +### sendRawTransaction + +**Returns**: the transaction id (TXID) of the submitted transaction + +**Parameters**: + +| Name | Type | Required | Description | +| ---------------- | ------- | -------- | ------------------------------------------------------------------ | +| `transaction` | String | Yes | The raw transaction, hex-encoded | +| `allowHighFees` | Boolean | No | Set to `true` to bypass the high-fee rejection check (default: `false`) | +| `bypassLimits` | Boolean | No | Set to `true` to bypass mempool rate limits (default: `false`) | + +#### Example Request and Response + +::::{tab-set} +:::{tab-item} Curl +:sync: curl +```shell +curl -k --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{ + "method":"sendRawTransaction", + "id":1, + "jsonrpc":"2.0", + "params": ["03000000019a2b1b2b...", false, false] + }' +``` +::: +:::: + ## Deprecated Endpoints The following endpoints were recently deprecated. See the [previous version of this @@ -368,4 +426,4 @@ puts response.read_body Implementation details related to the information on this page can be found in: -- The [DAPI repository](https://github.com/dashpay/platform/tree/master/packages/dapi) `lib/rpcServer/commands` folder \ No newline at end of file +- The [rs-dapi package](https://github.com/dashpay/platform/tree/master/packages/rs-dapi) `src/protocol/jsonrpc_translator` module diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index bac983b87..1942e1ec3 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -35,6 +35,7 @@ without introducing issues for endpoint consumers. | [`getDataContracts`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracts) | Returns the requested data contracts | | [`getDataContractHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracthistory) | Returns the requested data contract history | | [`getDocuments`](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) | **Updated in Dash Platform v4.0.0**
Returns the requested document(s), or an aggregate count/sum/average over the matched document set. | +| [`getDocumentHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdocumenthistory) | **Added in Dash Platform v4.0.0**
Returns the revision history for a single document on a contract that keeps document history | ### Identities @@ -158,6 +159,8 @@ The following endpoints provide information about the Core chain. | -------- | ----------- | | [`getBestBlockHash`](../reference/dapi-endpoints-json-rpc-endpoints.md#getbestblockhash) | Returns block hash of the chaintip | | [`getBlockHash`](../reference/dapi-endpoints-json-rpc-endpoints.md#getblockhash) | Returns block hash of the requested block | +| [`getStatus`](../reference/dapi-endpoints-json-rpc-endpoints.md#getstatus) | Returns Platform status information | +| [`sendRawTransaction`](../reference/dapi-endpoints-json-rpc-endpoints.md#sendrawtransaction) | Submits a raw transaction to the network | ### gRPC Endpoints @@ -165,9 +168,9 @@ The following endpoints provide information about the Core chain. | -------- | ----------- | | [`broadcastTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#broadcasttransaction) | Broadcasts the provided transaction | | [`getBestBlockHeight`](../reference/dapi-endpoints-core-grpc-endpoints.md#getbestblockheight) | *Added in Dash Platform v1.0.0*
Return the best block height| -| [`getBlock`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblock) | **Disabled in Dash Platform v1.0.0**
Returns information for the requested block | +| [`getBlock`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblock) | Returns information for the requested block | | [`getBlockchainStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblockchainstatus) | *Added in Dash Platform v1.0.0*
Returns blockchain status information | -| [`getMasternodeStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getmasternodestatus) | **Disabled in Dash Platform v1.0.0**
Returns masternode status information | +| [`getMasternodeStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getmasternodestatus) | Returns masternode status information | | [`getTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#gettransaction) | Returns details for the requested transaction | | [`subscribeTo` `BlockHeadersWithChainLocks`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetoblockheaderswithchainlocks) | Returns the requested block headers along with the associated ChainLocks. | | [`subscribeToMasternodeList`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetomasternodelist) | *Added in Dash Platform v1.0.0*
Returns the full masternode list from the genesis block to the chain tip as the first message and provides update messages with every new block | From d3a0f7a1ab4d68d94033496b7b1ee5b75509dac4 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 10 Aug 2026 14:40:40 -0400 Subject: [PATCH 13/17] docs(reference): correct schema keyword, query syntax, and proof details for v4.1.0 Correct the JSON Schema keyword restrictions on both the protocol reference and data contracts pages: $ref allows internal references beginning with # rather than being disabled outright, dependentSchemas is not supported, arrays are limited to byte arrays requiring byteArray: true, and per-item array schemas are unavailable. Drop the uniqueItems/maxItems row and the stale dependentSchema and prefixItems advice. Document the sized_integer_types and tokens contract configuration keys and the keepsTransferHistory, keepsPurchaseHistory, and keepsPricingHistory document options, and point the DPNS and document meta-schema links at the v2 schemas. Replace the 16 KB serialized data limit with the v4.1.0 system limits: 20 KiB per state transition and 5 KiB per document field value. Correct query syntax: offset is not supported for document queries in v4.1.0, the in clause requires 1 to 100 unique values, the limit maximum is node-configurable, and operator names match a fixed alias set. Restructure the range operator, compound index ordering, and aggregate query notes from admonitions into headed subsections so they are linkable. Document the address tree sync proofs on the platform proofs page: neither getAddressesTrunkState nor getAddressesBranchState takes a prove parameter, trunk proofs are served from a checkpoint whose height trails the tip and whose quorum must be resolved at that height, and branch responses carry only a bare merkProof. Also describe proof verification in terms of rs-drive-proof-verifier and the WebAssembly bindings rather than naming a specific package. Add Evonode and Group glossary entries, expand Credits with the conversion table reference, and extend the DAPI Client, Platform state, and State transition entries to cover the address system and shielded pool. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/data-contract-document.md | 9 ++-- docs/reference/data-contracts.md | 32 ++++++++---- docs/reference/glossary.md | 19 +++++-- docs/reference/platform-proofs.md | 31 +++++++++-- docs/reference/query-syntax.md | 58 +++++++++++++-------- 5 files changed, 106 insertions(+), 43 deletions(-) diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 898a22292..44a052dfa 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -401,13 +401,14 @@ schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/m | ------- | ---------- | | `default` | Restricted - cannot be used (defined in DPP logic) | | `propertyNames` | Restricted - cannot be used (defined in DPP logic) | -| `uniqueItems: true` | `maxItems` must be defined (maximum: 100000) | | `pattern: ` | `maxLength` must be defined (maximum: 50000) | | `format: ` | `maxLength` must be defined (maximum: 50000) | -| `$ref: ` | **Disabled**
`$ref` can only reference `$defs`. Remote references not supported. | +| `$ref: ` | Internal references only - the value must begin with `#` (e.g. `#/$defs/myType`). External and remote references, and reference cycles, are rejected | | `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` | Disabled for data contracts | -| `dependencies` | Not supported. Use `dependentRequired` and `dependentSchema` instead | -| `additionalItems` | Not supported. Use `items: false` and `prefixItems` instead | +| `dependencies` | Not supported. Use `dependentRequired` instead | +| `dependentSchemas` | Not supported. Schema-based dependencies are not available in document schemas; use `dependentRequired` for property-presence dependencies | +| `type: array` | Only byte arrays are supported. `byteArray: true` must be defined; schemas for individual array items are not available | +| `additionalItems` | Not supported. Per-item array schemas (`items` / `prefixItems`) are not available in document schemas; constrain arrays with `minItems`, `maxItems`, `uniqueItems`, `contains`, and `byteArray` | | `patternProperties` | Restricted - cannot be used for data contracts | | `pattern` | Accept only [RE2](https://github.com/google/re2/wiki/Syntax) compatible regular expressions (defined in DPP logic) | diff --git a/docs/reference/data-contracts.md b/docs/reference/data-contracts.md index 4302afb7d..9ba217a7a 100644 --- a/docs/reference/data-contracts.md +++ b/docs/reference/data-contracts.md @@ -35,6 +35,7 @@ Data contracts support three categories of configuration options to provide flex | `canBeDeleted` | `false` | Determines if the contract can be deleted | | `readonly` | `false` | Determines if the contract is read-only. Read-only contracts cannot be updated. | | `keepsHistory` | `false` | Enables or disables the storing of contract update history | +| `sized_integer_types` | `true` | Use sized integer types for `integer` properties based on their validation rules. Note that this key is snake_case, unlike the other contract configuration keys. | | Document default option | Default | Description | |-----------------------------------------|---------|-------------| @@ -46,6 +47,7 @@ Data contracts may also define the following top-level fields: | Contract field | Type | Description | |----------------|------|-------------| +| `tokens` | object | (Optional) Token definitions keyed by token contract position. Each entry configures base supply, maximum supply, minting and burning rules, and change control. See [Contract Tokens](../protocol-ref/data-contract-token.md). | | `groups` | object | (Optional) Groups that allow for specific multiparty actions on the contract. See [Data Contract groups](../protocol-ref/data-contract.md#data-contract-groups). | | `keywords` | array of strings | (Optional) Keywords associated with the contract to improve searchability via the `search` system contract. Maximum of 50 unique keywords. | | `description` | string | (Optional) Brief human-readable description of the contract (3-100 characters). Also added to the `search` system contract. | @@ -106,6 +108,9 @@ Documents support the following configuration options to provide flexibility in | `transferable` | integer | Transferable without a marketplace sell:
`0` - Never
`1` - Always
See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details | | `tradeMode` | integer | Built-in marketplace system:
`0` - None
`1` - Direct purchase (the purchaser can buy the item without requiring approval)
See the [NFT page](../explanations/nft.md#transfer-and-trade) for more details | | `creationRestrictionMode` | integer | Restriction of document creation:
`0` - No restrictions
`1` - Contract owner only
`2` - No Creation Allowed
See the [NFT page](../explanations/nft.md#creation-restrictions) for more details | +| `keepsTransferHistory` | boolean | If true, transfers of these documents are recorded in the document history system contract. Default: false. | +| `keepsPurchaseHistory` | boolean | If true, purchases of these documents are recorded in the document history system contract. Default: false. | +| `keepsPricingHistory` | boolean | If true, price updates on these documents are recorded in the document history system contract. Default: false. | | Security option | Type | Description | |-----------------|------|-------------| @@ -121,7 +126,7 @@ Document types can opt into aggregate queries with the flags `documentsCountable :::{dropdown} List of all usable document properties - This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/mod.rs#L31) and the [document meta-schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json). + This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/mod.rs#L31) and the [document meta-schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). | Property Name | Type | Description | |---------------|------|-------------| @@ -136,6 +141,9 @@ Document types can opt into aggregate queries with the flags `documentsCountable | `transferable` | integer | Transferable without a marketplace sell:
`0` - Never
`1` - Always | | `tradeMode` | integer | Built-in marketplace system:
`0` - None
`1` - Direct purchase (the purchaser can buy the item without requiring approval) | | `creationRestrictionMode` | integer | Restriction of document creation:
`0` - No restrictions
`1` - Contract owner only
`2` - No Creation Allowed. | + | `keepsTransferHistory` | boolean | If true, transfers of these documents are recorded in the document history system contract. Default: false. | + | `keepsPurchaseHistory` | boolean | If true, purchases of these documents are recorded in the document history system contract. Default: false. | + | `keepsPricingHistory` | boolean | If true, price updates on these documents are recorded in the document history system contract. Default: false. | | [`requiresIdentity`
`EncryptionBoundedKey`](#key-management) | integer | Key requirements for identity encryption:
`0` - Unique non-replaceable
`1` - Multiple
`2` - Multiple with reference to latest key | | [`requiresIdentity`
`DecryptionBoundedKey`](#key-management) | integer | Key requirements for identity decryption:
`0` - Unique non-replaceable
`1` - Multiple
`2` - Multiple with reference to latest key | | [`properties`](#document-properties) | object | Defines the properties of the document. | @@ -152,7 +160,7 @@ Document types can opt into aggregate queries with the flags `documentsCountable **Example** -The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates the use of several configuration options: +The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates the use of several configuration options: ```json { @@ -161,6 +169,9 @@ The following example (from the [DPNS contract's `domain` document](https://gith "canBeDeleted": true, "transferable": 1, "tradeMode": 1, + "keepsTransferHistory": true, + "keepsPurchaseHistory": true, + "keepsPricingHistory": true, "..." } } @@ -245,7 +256,7 @@ Each document may have transient fields that require validation but do not need **Example** -The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates a document that has 1 transient field: +The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates a document that has 1 transient field: ```json "transient": [ @@ -318,7 +329,7 @@ The table below describes the properties used to configure a contested index: **Example** -This example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates the use of a contested index: +This example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates the use of a contested index: ``` json "contested": { @@ -449,13 +460,14 @@ There are a variety of constraints currently defined for performance and securit | ------- | ---------- | | `default` | Restricted - cannot be used (defined in DPP logic) | | `propertyNames` | Restricted - cannot be used (defined in DPP logic) | -| `uniqueItems: true` | `maxItems` must be defined (maximum: 100000) | | `pattern: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L187)) | | `format: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L200)) | -| `$ref: ` | Disabled for data contracts | +| `$ref: ` | Internal references only - the value must begin with `#` (e.g. `#/$defs/myType`). External and remote references, and reference cycles, are rejected | | `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` | Disabled for data contracts | -| `dependencies` | Not supported. Use `dependentRequired` and `dependentSchema` instead | -| `additionalItems` | Not supported. Use `items: false` and `prefixItems` instead | +| `dependencies` | Not supported. Use `dependentRequired` instead | +| `dependentSchemas` | Not supported. Schema-based dependencies are not available in document schemas; use `dependentRequired` for property-presence dependencies | +| `type: array` | Only byte arrays are supported. `byteArray: true` must be defined; schemas for individual array items are not available | +| `additionalItems` | Not supported. Per-item array schemas (`items` / `prefixItems`) are not available in document schemas; constrain arrays with `minItems`, `maxItems`, `uniqueItems`, `contains`, and `byteArray` | | `patternProperties` | Restricted - cannot be used for data contracts | | `pattern` | Accept only [RE2](https://github.com/google/re2/wiki/Syntax) compatible regular expressions (defined in DPP logic) | @@ -463,7 +475,9 @@ There are a variety of constraints currently defined for performance and securit **Note:** These constraints are defined in the Dash Platform Protocol logic (not in JSON Schema). -All serialized data (including state transitions) is limited to a maximum size of [16 KB](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/util/cbor_serializer.rs#L8). +A state transition is limited to a maximum size of [20 KiB](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs) (`max_state_transition_size`). Oversized transitions are rejected. + +An individual document field value is limited to [5 KiB](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs) (`max_field_value_size`). ### Additional Properties diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index dabeada8b..955b83373 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -38,7 +38,9 @@ Layer 1 blockchain used for payments, governance, and providing the foundation f ## Credits -Means of paying fees on the layer 2 platform +Means of paying fees on the layer 2 platform. Credits are the smallest unit of account on Platform: +1 duff = 1,000 credits, and 1 Dash = 100,000,000,000 credits. See [Protocol +constants](../protocol-ref/protocol-constants.md#credit-system) for the full conversion table. ## DAPI @@ -46,7 +48,8 @@ Dash's decentralized API for interacting with the core blockchain (layer 1) and ## DAPI Client -An HTTP Client that connects to DAPI to enable users to read and write data to the Dash platform +A client that connects to DAPI to read and write Platform data or access Core chain information. +DAPI exposes gRPC services for Platform and Core, plus JSON-RPC for selected Core information. ## DashPay @@ -118,6 +121,14 @@ An epoch is a fixed time period used to organize and manage blockchain operation An era consists of 40 [epochs](#epoch) and equals approximately one year. At the end of an era, Dash Platform may optionally do additional accounting or reconfiguration. +## Evonode + +An evolution masternode: a [masternode](#masternode) that meets the additional collateral and hardware requirements to run Dash Platform services alongside Dash Core. Only evonodes participate in the [validator set](#validator-set) that produces Platform blocks, and evonode operators receive Platform block rewards for that participation. + +## Group (data contract) + +A set of identities defined in a [data contract](#data-contract) that jointly authorize actions on that contract, such as token minting or configuration changes. Each member is assigned a voting power, and an action executes once the members approving it reach the group's required power threshold. Distinct from a [quorum](#quorum), which is a set of masternodes selected by the network to sign protocol-level actions. + ## History (contract revision) The record of successive revisions of a [data contract](#data-contract), retained when the contract sets `keepsHistory` at creation. Retrieved with [`getDataContractHistory`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontracthistory). This tracks changes to the contract definition itself, not to the documents stored under it. See [Retrieve data contract history](../tutorials/contracts-and-documents/retrieve-data-contract-history.md). @@ -158,7 +169,7 @@ Layer 2 blockchain that propagates platform data among masternodes, propagates p ## Platform State -All layer 2 data including contracts, documents (user data), tokens, groups, credit balance, identity (username), and masternode voting/contested resource state +All layer 2 data including contracts, documents (user data), tokens, groups, credit balance, identity (username), address balances, shielded pool state, and masternode voting/contested resource state ## practical Byzantine Fault Tolerance (pBFT) @@ -198,7 +209,7 @@ The application that validates state transitions and updates state in Drive ## State Transition -A signed change to platform state submitted by an identity. State transitions cover a range of operations, including data contract creation and updates, document and token changes (batched), identity lifecycle operations (create, top-up, update), credit transfers and withdrawals, and masternode voting (cast by masternode and evonode operators) +A signed change to platform state. Most state transitions are submitted by an identity, but some are not owned by one - the address-system and shielded-pool transitions carry no owner identity. State transitions cover a range of operations, including data contract creation and updates, document and token changes (batched), identity lifecycle operations (create, top-up, update), credit transfers and withdrawals, address-system and shielded-pool operations, and masternode voting (cast by masternode and evonode operators) ## Tenderdash diff --git a/docs/reference/platform-proofs.md b/docs/reference/platform-proofs.md index 41457ecf3..657048932 100644 --- a/docs/reference/platform-proofs.md +++ b/docs/reference/platform-proofs.md @@ -11,8 +11,10 @@ agreed upon by the validator network -- without trusting whoever supplied the da The most common way to obtain a proof is to request one over [DAPI](../explanations/dapi.md): set the optional `"prove": true` parameter on a [Platform gRPC endpoint](../reference/dapi-endpoints-platform-endpoints.md) and the response carries a `Proof` -message instead of the plain result. A proof does not depend on how it was retrieved, though -- -it can be verified independently by any party that holds it. +message instead of the plain result. Most Platform endpoints work this way. The two address-tree +sync endpoints are different: they have no `prove` parameter and always return proof data. See +[address tree sync proofs](#address-tree-sync-proofs) below. A proof does not depend on how it was +retrieved, though -- it can be verified independently by any party that holds it. For the concepts behind proofs -- the two-layer GroveDB + consensus trust model, the verification flow, what can be proven, and asset lock proofs -- see [Proofs](../explanations/proofs.md). @@ -50,8 +52,9 @@ address balance proofs](#compacted-address-balance-proofs) below. A `Proof` has Clients do not parse proofs manually. Verification is performed by the `rs-drive-proof-verifier` crate, which checks the quorum's BLS threshold signature (the Tenderdash consensus half) and decodes the unified `grovedbProof` to recover the requested data -and the state root hash. This logic is exposed to JavaScript and browser clients through the -`wasm-drive-verify` package, so the SDKs verify proofs automatically whenever one is requested. +and the state root hash. Dash Platform SDKs verify requested proofs automatically. Applications +performing verification directly can use `rs-drive-proof-verifier`; JavaScript and browser +applications can use the available WebAssembly bindings. See the [Proofs](../explanations/proofs.md) explanation for the step-by-step verification flow. @@ -84,6 +87,26 @@ proof, so clients implementing verification outside the provided SDKs must handl select by protocol version. ::: +### Address tree sync proofs + +The two address-tree sync endpoints used for incremental address balance sync differ from the rest +of the Platform surface. Neither takes a `prove` parameter; both always return proof data. + +[`getAddressesTrunkState`](../reference/dapi-endpoints-platform-endpoints.md#getaddressestrunkstate) +returns a standard `Proof` message plus response metadata. Unlike every other proof-bearing +endpoint, its proof is served from the latest available **checkpoint** rather than from current +state. The returned `metadata.height` is therefore a checkpoint height that generally trails the +chain tip, and the `quorumHash`, `signature`, `blockIdHash`, and `round` all correspond to that +checkpoint height. A verifier must resolve the signing quorum at the checkpoint height rather than +at the tip, or signature verification will fail. + +[`getAddressesBranchState`](../reference/dapi-endpoints-platform-endpoints.md#getaddressesbranchstate) +is the further exception: its response carries neither a `Proof` message nor a `metadata` block, +only a bare `merkProof` byte string. Consistency with the trunk proof is established by passing the +trunk's `metadata.height` back as the request's `checkpoint_height`, rather than by anything in the +response itself. Branch proofs are served only from checkpoints, so a height that no longer has a +checkpoint returns an error. + ## Related topics - [Proofs](../explanations/proofs.md) -- the conceptual trust model, verification flow, and asset lock proofs diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index cf9061168..1c0bdb283 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -26,12 +26,12 @@ The Where clause is an optional array of conditions. If omitted or empty, all do ### Fields -Valid fields consist of the indices defined for the document being queried. For example, the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json) defines two indices for domain documents: +Valid fields consist of the indices defined for the document being queried. For example, the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json) defines two indices for domain documents: | Index Field(s) | Index Type | Unique | | - | - | :-: | -| [normalizedParentDomainName, normalizedLabel](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L11-L18) | Compound | Yes | -| [records.identity](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L31-L39) | Single Field | No | +| [normalizedParentDomainName, normalizedLabel](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json#L12-L33) | Compound | Yes | +| [records.identity](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json#L34-L42) | Single Field | No | ```{eval-rst} .. @@ -59,25 +59,38 @@ Valid fields consist of the indices defined for the document being queried. For | <= | Matches values that are less than or equal to a specified value | | >= | Matches values that are greater than or equal to a specified value | | > | Matches values that are greater than a specified value | -| in | Matches all document(s) where the value of the field equals any value in the specified array
Array may include up to 100 (unique) elements | +| in | Matches all document(s) where the value of the field equals any value in the specified array
The array must contain between 1 and 100 values, with no duplicates. Empty arrays, oversized arrays, and duplicate values are rejected with `InvalidInClause` | | Between | Matches values between two bounds (inclusive on both sides) — value must be a two-element array `[lower, upper]` with `lower < upper` | | BetweenExcludeBounds | Matches values strictly between two bounds (exclusive on both sides) | | BetweenExcludeLeft | Matches values between two bounds, excluding the lower bound | | BetweenExcludeRight | Matches values between two bounds, excluding the upper bound | -:::{tip} -- Only one range operator is allowed in a query. `Between` and its variants are single operators that replace a `>=`/`<=` pair — the engine also normalizes two range operators on the same field into the equivalent `Between*` form automatically +##### Range operator constraints + +- A query can have only one effective range clause. Use `Between` or one of its variants to express both bounds, or supply two complementary range clauses on the same field; Platform normalizes the pair to the equivalent `Between*` form - The `in` operator is only allowed for last two indexed properties - Range operators apply to an indexed field that follows any `==` and `in` clauses in the index. A standalone range (with no preceding `==`/`in` clause) is valid when a matching index exists - Range operators are only allowed for the last two fields used in the where condition - Queries using range operators (including `in`, which is treated as a range) must also include an `orderBy` statement -::: + +##### Operator aliases + +Operator names are matched against a fixed set of aliases: + +| Operator | Accepted aliases | +| - | - | +| `==` | `=` | +| `in` | `In` | +| `Between` | `between` | +| `BetweenExclude*` | CamelCase, lowercase, and snake_case variants, such as `betweenExcludeLeft`, `betweenexcludeleft`, and `between_exclude_left` | + +Any other spelling is rejected. ### Evaluation Operators | Name | Description | | :-: | - | -| startsWith | Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement. | +| startsWith | Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement. Also accepted as `StartsWith`, `startswith`, and `starts_with` | ### Operator Examples @@ -157,15 +170,15 @@ The query modifiers described here determine how query results will be sorted an | Modifier | Effect | Example | | - | - | - | -| `limit` | Restricts the number of results returned. Defaults to 100 when omitted, and the [maximum is also 100](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/config.rs#L16-L18). Both values come from Drive's `default_query_limit` / `max_query_limit` node configuration rather than from the protocol, so an operator can tune them. | `limit: 10` | +| `limit` | Restricts the number of results returned. Defaults to 100 when omitted. The [maximum is also 100](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/config.rs#L16-L18) by default, although node operators may configure a different limit. | `limit: 10` | | `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: ''` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: ''` | -| `offset` | Skips the first N matching results (available at the CBOR/DAPI layer; not exposed in the JS SDK) | `offset: 10` | +| `offset` | Not supported for document queries in v4.1.0. Use `startAt` or `startAfter` for pagination. | n/a | -:::{attention} -For indices composed of multiple fields ([example from the DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)), the sort order in an `orderBy` must either match the order defined in the data contract OR be the inverse order. -::: +### Ordering compound indexes + +For indices composed of multiple fields ([example from the DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)), the sort order in an `orderBy` must either match the order defined in the data contract OR be the inverse order. ### Combining a cursor with a range operator @@ -180,10 +193,7 @@ Ascending queries that combined a cursor with a `<` or `<=` clause previously [b ## Aggregate Queries -:::{versionadded} 4.0.0 -::: - -The [getDocuments](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) v1 surface adds an aggregate-query mode. The same `where` / `orderBy` clauses described above still apply; an additional `select` projection (and optional `groupBy`) determines whether the request returns documents or aggregate values over the matched set. +Available since Platform 4.0.0, the [getDocuments](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) v1 surface adds an aggregate-query mode. The same `where` / `orderBy` clauses described above still apply; an additional `select` projection (and optional `groupBy`) determines whether the request returns documents or aggregate values over the matched set. | `select` | Returns | | ---------------- | ------- | @@ -208,7 +218,7 @@ The `limit` modifier behaves differently on the aggregate surface than it does w SDK bindings that must pass a numeric argument use `-1` as the server-default sentinel; any other negative value is rejected. -:::{versionadded} 4.1.0 +:::{versionchanged} 4.1.0 An effective limit of zero is now rejected with `InvalidLimit` rather than walking storage with a zero bound, which previously surfaced as an empty result set. ::: @@ -224,15 +234,19 @@ How a positive `limit` is interpreted depends on `groupBy`: `SUM` and `AVG` follow the same policy as `COUNT`: distinct walks apply the default/cap/reject-zero rules, and a zero limit is rejected. -:::{attention} +### Aggregate cursors + +`startAt` and `startAfter` are supported only with `DOCUMENTS`. Aggregate queries reject cursors; narrow the `where` range to query a different group range. + +### Proof limits + On range-grouped aggregates, an oversized `limit` is handled differently depending on whether a proof is requested. With `prove: true`, a `limit` above the node's maximum (100 by default) is rejected with `InvalidLimit` so that proof bytes stay deterministic. With `prove: false`, the limit is silently clamped to the maximum instead — a caller requesting 500 groups receives at most 100 with no error, which can look like missing data. -::: Compound carrier-aggregate shapes that pair an `In` field with a range field and request a proof cap the outer range walk at [10 entries](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/query/drive_document_count_query/mod.rs#L127). This is a hard ceiling: a `limit` above it is rejected, and callers needing more results issue repeated queries over disjoint outer-range windows. -:::{note} +### Unsupported aggregate operations + `HAVING`, `OFFSET`, `COUNT()`, `MIN`, `MAX`, and multi-projection `SELECT` are present on the wire but currently return `Unsupported`. Callers can encode them in builders ahead of server support landing, but evaluation rejects them today. -::: ## Example query From 685c168d11fd0ffc99da2e473b2fe7e413492c04 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 10 Aug 2026 17:29:10 -0400 Subject: [PATCH 14/17] docs(reference): clarify aggregate query limits and address tree proof detail Rename the "Limits on aggregate queries" section to "Aggregate query limits" and update the three getDocuments cross-references. Fold the separate aggregate cursor and unsupported operation sections into a single "Other aggregate restrictions" list, and move the oversized-limit proof behavior under a subheading. Distinguish aggregate result modes from DOCUMENTS throughout the limit discussion: `limit: 0` is rejected only in aggregate modes and uses the configured default when returning documents, cursors apply only to DOCUMENTS, and the configured maximum is described as a default rather than a fixed value. Correct offset to say it is present on the wire but rejected with `Unsupported`, and give operator aliases their own table so the evaluation operator table stays readable. Trim the address tree sync section on the platform proofs page to the verification consequences and defer request/response mechanics to the endpoint reference, and note the two departures from the standard Proof structure where that structure is introduced rather than in the overview. Add a note on the getAddressesTrunkState example that protocol version 13 and above use the compacted proof encoding. Add an Evo SDK tab to the aggregate query example showing count/sum/average in place of a select projection, including the hex-encoded index keys returned by grouped counts and the schema flags an aggregate requires. Co-Authored-By: Claude Opus 5 (1M context) --- .../dapi-endpoints-platform-endpoints.md | 9 +- docs/reference/platform-proofs.md | 33 +++---- docs/reference/query-syntax.md | 98 +++++++++++++------ 3 files changed, 89 insertions(+), 51 deletions(-) diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index 55cd8d9eb..5b482b563 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -1275,7 +1275,7 @@ Returns one aggregate count, or per-group counts when `group_by` is set. Require | `selects` | `[Select{ function: COUNT }]` | Yes | Projection. | | `group_by` | Repeated string | No | `[]`, `[in_field]`, `[range_field]`, or `[in_field, range_field]`. | -`limit` is rejected for `group_by=[]` and `group_by=[in_field]` (the result is bounded by construction). `limit: 0` is rejected with `InvalidLimit` in every mode — omit the field to request the server default (SDK bindings that require a numeric argument use `-1`). `start_at` / `start_after` are not valid in this mode — paginate by narrowing the where clause. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries) for the full per-mode contract. +`limit` is rejected for `group_by=[]` and `group_by=[in_field]` (the result is bounded by construction). `limit: 0` is rejected with `InvalidLimit` in every mode — omit the field to request the server default (SDK bindings that require a numeric argument use `-1`). `start_at` / `start_after` are not valid in this mode — paginate by narrowing the where clause. See [aggregate query limits](query-syntax.md#aggregate-query-limits) for the full per-mode contract. **Response shape** @@ -1343,7 +1343,7 @@ Returns the sum of an integer field across matched documents, or per-group sums | `selects` | `[Select{ function: SUM, field: "" }]` | Yes | `field` must name the summable property. | | `group_by` | Repeated string | No | Same shape rules as Count above. | -`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries). +`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [aggregate query limits](query-syntax.md#aggregate-query-limits). **Response shape** @@ -1409,7 +1409,7 @@ Why `(count, sum)` instead of a single `average`? Returning the pair preserves f | `selects` | `[Select{ function: AVG, field: "" }]` | Yes | `field` must name the averageable property. | | `group_by` | Repeated string | No | Same shape rules as Count above. | -`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [limits on aggregate queries](query-syntax.md#limits-on-aggregate-queries). +`limit` follows the same rules as Count: rejected for `group_by=[]` and `group_by=[in_field]`, and `limit: 0` is rejected with `InvalidLimit` in every mode. `start_at` / `start_after` are not valid. See [aggregate query limits](query-syntax.md#aggregate-query-limits). **Response shape** @@ -4702,6 +4702,9 @@ their size limit. If the response contains 25 entries, page forward by re-issuin **Example Request and Response** +The example response below was captured at protocol version 11. At protocol version 13 and above, +proof responses use the [compacted proof encoding described in Platform Proofs](platform-proofs.md#compacted-address-balance-proofs). + ::::{tab-set} :::{tab-item} gRPCurl ```shell diff --git a/docs/reference/platform-proofs.md b/docs/reference/platform-proofs.md index 657048932..b3def1dd9 100644 --- a/docs/reference/platform-proofs.md +++ b/docs/reference/platform-proofs.md @@ -11,19 +11,16 @@ agreed upon by the validator network -- without trusting whoever supplied the da The most common way to obtain a proof is to request one over [DAPI](../explanations/dapi.md): set the optional `"prove": true` parameter on a [Platform gRPC endpoint](../reference/dapi-endpoints-platform-endpoints.md) and the response carries a `Proof` -message instead of the plain result. Most Platform endpoints work this way. The two address-tree -sync endpoints are different: they have no `prove` parameter and always return proof data. See -[address tree sync proofs](#address-tree-sync-proofs) below. A proof does not depend on how it was -retrieved, though -- it can be verified independently by any party that holds it. +message instead of the plain result. A proof does not depend on how it was retrieved. It +can be verified independently by any party that holds it. For the concepts behind proofs -- the two-layer GroveDB + consensus trust model, the verification flow, what can be proven, and asset lock proofs -- see [Proofs](../explanations/proofs.md). ## Proof structure -A `Proof` is normally a single unified [GroveDB](https://github.com/dashpay/grovedb) proof plus the -consensus signature that authenticates it. One response type is an exception: see [compacted -address balance proofs](#compacted-address-balance-proofs) below. A `Proof` has six fields: +A `Proof` is a unified [GroveDB](https://github.com/dashpay/grovedb) proof plus the consensus +signature that authenticates it. It has six fields: | Field | Type | Description | | - | - | - | @@ -47,6 +44,11 @@ address balance proofs](#compacted-address-balance-proofs) below. A `Proof` has } ``` +Two endpoint families depart from this standard structure: compacted address balance proofs use a +version-dependent `grovedbProof` encoding, while address-tree sync endpoints use different +proof-bearing response shapes. See [Proof internals](#proof-internals) and [Address tree sync +verification](#address-tree-sync-verification), respectively. + ## Verifying proofs Clients do not parse proofs manually. Verification is performed by the @@ -87,25 +89,20 @@ proof, so clients implementing verification outside the provided SDKs must handl select by protocol version. ::: -### Address tree sync proofs +## Address tree sync verification The two address-tree sync endpoints used for incremental address balance sync differ from the rest of the Platform surface. Neither takes a `prove` parameter; both always return proof data. [`getAddressesTrunkState`](../reference/dapi-endpoints-platform-endpoints.md#getaddressestrunkstate) -returns a standard `Proof` message plus response metadata. Unlike every other proof-bearing -endpoint, its proof is served from the latest available **checkpoint** rather than from current -state. The returned `metadata.height` is therefore a checkpoint height that generally trails the -chain tip, and the `quorumHash`, `signature`, `blockIdHash`, and `round` all correspond to that -checkpoint height. A verifier must resolve the signing quorum at the checkpoint height rather than -at the tip, or signature verification will fail. +returns a standard `Proof` message plus response metadata. Because the proof is anchored to the +returned checkpoint height rather than the chain tip, a verifier must resolve the signing quorum +at that checkpoint height or signature verification will fail. [`getAddressesBranchState`](../reference/dapi-endpoints-platform-endpoints.md#getaddressesbranchstate) is the further exception: its response carries neither a `Proof` message nor a `metadata` block, -only a bare `merkProof` byte string. Consistency with the trunk proof is established by passing the -trunk's `metadata.height` back as the request's `checkpoint_height`, rather than by anything in the -response itself. Branch proofs are served only from checkpoints, so a height that no longer has a -checkpoint returns an error. +only a bare `merkProof` byte string with no signature of its own. See the endpoint references for +the checkpoint workflow and request/response details. ## Related topics diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index 1c0bdb283..c3a4e6dc9 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -65,7 +65,7 @@ Valid fields consist of the indices defined for the document being queried. For | BetweenExcludeLeft | Matches values between two bounds, excluding the lower bound | | BetweenExcludeRight | Matches values between two bounds, excluding the upper bound | -##### Range operator constraints +**Range operator constraints** - A query can have only one effective range clause. Use `Between` or one of its variants to express both bounds, or supply two complementary range clauses on the same field; Platform normalizes the pair to the equivalent `Between*` form - The `in` operator is only allowed for last two indexed properties @@ -73,7 +73,13 @@ Valid fields consist of the indices defined for the document being queried. For - Range operators are only allowed for the last two fields used in the where condition - Queries using range operators (including `in`, which is treated as a range) must also include an `orderBy` statement -##### Operator aliases +### Evaluation Operators + +| Name | Description | +| :-: | - | +| startsWith | Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement. | + +### Operator aliases Operator names are matched against a fixed set of aliases: @@ -83,15 +89,10 @@ Operator names are matched against a fixed set of aliases: | `in` | `In` | | `Between` | `between` | | `BetweenExclude*` | CamelCase, lowercase, and snake_case variants, such as `betweenExcludeLeft`, `betweenexcludeleft`, and `between_exclude_left` | +| `startsWith` | `StartsWith`, `startswith`, `starts_with` | Any other spelling is rejected. -### Evaluation Operators - -| Name | Description | -| :-: | - | -| startsWith | Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement. Also accepted as `StartsWith`, `startswith`, and `starts_with` | - ### Operator Examples :::::{tab-set} @@ -170,11 +171,11 @@ The query modifiers described here determine how query results will be sorted an | Modifier | Effect | Example | | - | - | - | -| `limit` | Restricts the number of results returned. Defaults to 100 when omitted. The [maximum is also 100](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/config.rs#L16-L18) by default, although node operators may configure a different limit. | `limit: 10` | +| `limit` | Restricts the number of documents returned. An omitted value or `0` uses the configured default (100 by default). Positive values cannot exceed the configured maximum (also 100 by default). See [Aggregate query limits](#aggregate-query-limits) for aggregate result modes. | `limit: 10` | | `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: ''` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: ''` | -| `offset` | Not supported for document queries in v4.1.0. Use `startAt` or `startAfter` for pagination. | n/a | +| `offset` | Present on the wire but currently rejected with `Unsupported`. Use `startAt` or `startAfter` for pagination. | n/a | ### Ordering compound indexes @@ -182,6 +183,8 @@ For indices composed of multiple fields ([example from the DPNS data contract](h ### Combining a cursor with a range operator +This behavior applies when returning `DOCUMENTS`; aggregate result modes do not support cursors. + When a `startAt` / `startAfter` cursor is combined with a range operator (`>`, `>=`, `<`, `<=`), the cursor narrows the effective range in the direction of the `orderBy` sort: - Ascending order — the cursor is the lower bound and the range clause's value is the upper bound. `startAfter` excludes the cursor row itself. @@ -193,14 +196,17 @@ Ascending queries that combined a cursor with a `<` or `<=` clause previously [b ## Aggregate Queries -Available since Platform 4.0.0, the [getDocuments](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) v1 surface adds an aggregate-query mode. The same `where` / `orderBy` clauses described above still apply; an additional `select` projection (and optional `groupBy`) determines whether the request returns documents or aggregate values over the matched set. +:::{versionadded} 4.0.0 +::: + +The [getDocuments](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) v1 surface adds an aggregate-query mode. The same `where` / `orderBy` clauses described above still apply; an additional `select` projection (and optional `groupBy`) determines whether the request returns documents or aggregate values over the matched set. -| `select` | Returns | -| ---------------- | ------- | -| `DOCUMENTS` | Matched documents (same as v0). | -| `COUNT(*)` | Number of documents matching the query. | -| `SUM()` | Sum of `` across matching documents. | -| `AVG()` | `(count, sum)` pair the client divides to compute the average. | +| `select` | Returns | +| - | - | +| `DOCUMENTS` | Matched documents (same as v0). | +| `COUNT(*)` | Number of documents matching the query. | +| `SUM()` | Sum of `` across matching documents. | +| `AVG()` | `(count, sum)` pair the client divides to compute the average. | `groupBy` is optional. With an empty `groupBy`, the response carries a single aggregate value; with a `groupBy` of one or two fields, the response carries one entry per group. @@ -208,25 +214,25 @@ Aggregate queries impose extra schema requirements on the document type — `COU `SUM` / `AVG` integer values are returned as JS strings so JavaScript clients don't lose precision on values larger than `Number.MAX_SAFE_INTEGER`. -### Limits on aggregate queries +### Aggregate query limits -The `limit` modifier behaves differently on the aggregate surface than it does when returning documents, and in some `select` × `groupBy` combinations it is rejected outright. On the wire, [`limit` is an optional field](https://github.com/dashpay/platform/blob/v4.1.0/packages/dapi-grpc/protos/platform/v0/platform.proto#L958-L1002): +The `limit` modifier behaves differently in aggregate result modes than it does when returning `DOCUMENTS`, and some `select` × `groupBy` combinations reject it outright. On the wire, [`limit` is an optional field](https://github.com/dashpay/platform/blob/v4.1.0/packages/dapi-grpc/protos/platform/v0/platform.proto#L958-L1002): - Omit `limit` to request the server's default. - Send a positive value to request an explicit cap. -- `limit: 0` is rejected with `InvalidLimit` in every `select` mode. A zero cap is structurally meaningless, so it is never treated as "no limit". +- In aggregate result modes, `limit: 0` is rejected with `InvalidLimit`. When returning `DOCUMENTS`, `0` uses the configured default as described under [Query Modifiers](#query-modifiers). SDK bindings that must pass a numeric argument use `-1` as the server-default sentinel; any other negative value is rejected. :::{versionchanged} 4.1.0 -An effective limit of zero is now rejected with `InvalidLimit` rather than walking storage with a zero bound, which previously surfaced as an empty result set. +In aggregate result modes, an effective limit of zero is now rejected with `InvalidLimit` rather than walking storage with a zero bound, which previously surfaced as an empty result set. ::: How a positive `limit` is interpreted depends on `groupBy`: | `select` / `groupBy` | Effect of `limit` | | - | - | -| `DOCUMENTS` | Caps the number of matched documents, as described under [Query Modifiers](#query-modifiers). | +| `DOCUMENTS` | Uses the general behavior described under [Query Modifiers](#query-modifiers). | | `COUNT` with an empty `groupBy` | Rejected with `InvalidLimit`. An aggregate count is a single row by construction. | | `COUNT` grouped by an `In` field | Rejected with `InvalidLimit`. The `In` array is already capped at 100 entries, so the result is bounded. Narrow the `In` array instead. | | `COUNT` grouped by a range field | Caps the distinct-range walk, so the response carries at most `limit` groups. | @@ -234,19 +240,16 @@ How a positive `limit` is interpreted depends on `groupBy`: `SUM` and `AVG` follow the same policy as `COUNT`: distinct walks apply the default/cap/reject-zero rules, and a zero limit is rejected. -### Aggregate cursors - -`startAt` and `startAfter` are supported only with `DOCUMENTS`. Aggregate queries reject cursors; narrow the `where` range to query a different group range. +#### Oversized limits with and without proofs -### Proof limits - -On range-grouped aggregates, an oversized `limit` is handled differently depending on whether a proof is requested. With `prove: true`, a `limit` above the node's maximum (100 by default) is rejected with `InvalidLimit` so that proof bytes stay deterministic. With `prove: false`, the limit is silently clamped to the maximum instead — a caller requesting 500 groups receives at most 100 with no error, which can look like missing data. +On range-grouped aggregates, an oversized `limit` is handled differently depending on whether a proof is requested. With `prove: true`, a `limit` above the node's configured maximum is rejected with `InvalidLimit` so that proof bytes stay deterministic. With `prove: false`, the limit is silently clamped to that maximum instead. With the default maximum of 100, for example, a caller requesting 500 groups receives at most 100 with no error, which can look like missing data. Compound carrier-aggregate shapes that pair an `In` field with a range field and request a proof cap the outer range walk at [10 entries](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-drive/src/query/drive_document_count_query/mod.rs#L127). This is a hard ceiling: a `limit` above it is rejected, and callers needing more results issue repeated queries over disjoint outer-range windows. -### Unsupported aggregate operations +### Other aggregate restrictions -`HAVING`, `OFFSET`, `COUNT()`, `MIN`, `MAX`, and multi-projection `SELECT` are present on the wire but currently return `Unsupported`. Callers can encode them in builders ahead of server support landing, but evaluation rejects them today. +- `startAt` and `startAfter` are supported only with `DOCUMENTS`. Aggregate result modes reject cursors; narrow the `where` range to query a different group range. +- `HAVING`, `OFFSET`, `COUNT()`, `MIN`, `MAX`, and multi-projection `SELECT` are present on the wire but currently return `Unsupported`. Callers can encode them in builders ahead of server support landing, but evaluation rejects them today. ## Example query @@ -295,4 +298,39 @@ for (const [id, doc] of results) { } ``` ::: + +:::{tab-item} Evo SDK aggregate example +The Evo SDK does not expose `select` directly. Each aggregate mode has its own method — `documents.count()`, `documents.sum(query, property)`, and `documents.average(query, property)`. `groupBy` is passed as part of the query. + +```javascript +import { EvoSDK } from '@dashevo/evo-sdk'; + +const sdk = EvoSDK.testnetTrusted(); +await sdk.connect(); + +// COUNT grouped by a range field: one entry per distinct rating. +// The `rating` range clause is what puts the query in grouped mode. +const counts = await sdk.documents.count({ + dataContractId: 'BdgTqaTAPYMyhp1WdeWdcvYSgoD7AuJ7tVCaCSXyQgyP', + documentTypeName: 'review', + where: [ + ['resourceId', '==', 'dashnote'], + ['rating', 'between', [1, 5]], + ], + orderBy: [ + ['rating', 'asc'], + ], + groupBy: ['rating'], +}); + +// Keys are hex-encoded index keys, not the raw field values, and +// counts are BigInt. A small positive integer encodes as `0x80 | value`, +// so rating 5 is the key "85". +for (const [key, count] of counts) { + console.log(`${key - 80} stars: ${count.toString()} review(s)`); +} +``` + +Both the document type's schema flags and the query's index must support the aggregate — this example needs `documentsCountable` plus `rangeCountable`, and a `[resourceId, rating]` index. An ungrouped `count()` returns a single-entry map keyed by the empty string, so read it with `counts.values().next().value`. +::: :::: From cae0a2866cee68a7e24f2359119c6d5e2da5337f Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 11 Aug 2026 12:29:17 -0400 Subject: [PATCH 15/17] docs(protocol-ref): correct wire formats and constraint gaps for v4.1.0 Fix the token JSON examples, which were non-functional in four ways: the discriminator is `$formatVersion`, change control rules are internally tagged so the `{"V0": {...}}` wrapper does not exist on the wire, rule fields serialize in camelCase, and authorized action takers are `{"$type": ...}` maps rather than bare strings. Add the JSON values to the authorized parties and distribution tables. Correct the asset lock proof discriminator to `$type` with string values `"instant"` and `"chain"`, and rename the token transfer `amount` field to `$amount`. Document effective limits that differ from the documented ones: shielded transitions cap at 6 actions rather than 16 because the Halo 2 proof grows per action, and address credit withdrawals enforce a withdrawal amount floor above the documented per-input minimum. Add the consensus constraints omitted from the shield and shielded withdrawal transitions. Expand the data contract update section to cover tokens, groups, keywords, description, and the one-way `sizedIntegerTypes` transition, and restate the index rule as tree compatibility plus aggregate flag immutability. Add the keyword constraints and the byte-versus-character description bound. Split the aggregate query flags into document-type and index-level subsections, and add the index-level flags to the document indices reference. Reword the `pattern` restriction to name the Rust regex engine, since RE2 validation is not performed. Point the DPNS examples at the v2 schema active under protocol version 13. Repoint five identity constant links to the v3 state transition versions file and correct the document state error code range to 40100-40199. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/address-system.md | 2 +- docs/protocol-ref/data-contract-document.md | 58 +++- docs/protocol-ref/data-contract-token.md | 345 ++++++++++---------- docs/protocol-ref/data-contract.md | 13 +- docs/protocol-ref/errors.md | 2 +- docs/protocol-ref/identity.md | 6 +- docs/protocol-ref/protocol-constants.md | 14 +- docs/protocol-ref/shielded-pool.md | 6 +- docs/protocol-ref/token.md | 2 +- 9 files changed, 234 insertions(+), 214 deletions(-) diff --git a/docs/protocol-ref/address-system.md b/docs/protocol-ref/address-system.md index 68776fe47..761ed89af 100644 --- a/docs/protocol-ref/address-system.md +++ b/docs/protocol-ref/address-system.md @@ -217,7 +217,7 @@ Withdraw credits from Platform addresses back to the Core chain. | 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. +**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. **Fee:** 400,000,000 credits. Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain. ::: diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 44a052dfa..5166edcee 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -107,7 +107,7 @@ Each document may have transient fields that require validation but do not need **Example** -The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates a document that has 1 transient field: +The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates a document that has 1 transient field: ```json "transient": [ @@ -143,6 +143,9 @@ The `indices` array consists of one or more objects that each contain: * An optional `unique` element that determines if duplicate values are allowed for the document * An optional `nullSearchable` element that indicates whether the index allows searching for NULL values. If nullSearchable is false (default: true) and all properties of the index are null then no reference is added. * An optional `contested` element that determines if duplicate values are allowed for the document +* Optional [aggregate query flags](#aggregate-query-flags) - `countable`, `rangeCountable`, `summable`, `rangeSummable`, `averageable`, and `rangeAverageable` - that enable count, sum, and average fast paths on the index + +Index objects do not accept any properties beyond those listed above. :::{code-block} json :force: @@ -171,6 +174,12 @@ The `indices` array consists of one or more objects that each contain: "properties": [ { "": "asc" }, ], + "countable": "countable"|"countableAllowingOffset"|"notCountable", + "rangeCountable": true|false, + "summable": "", + "rangeSummable": true|false, + "averageable": "", + "rangeAverageable": true|false } ] ::: @@ -192,7 +201,7 @@ The table below describes the properties used to configure a contested index: **Example** -This example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates the use of a contested index: +This example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates the use of a contested index: ``` json "contested": { @@ -332,7 +341,7 @@ The following operation types can each have an independent cost configuration: **Example** -The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)) demonstrates the use of several configuration options: +The following example (from the [DPNS contract's `domain` document](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v2/dpns-contract-documents.json)) demonstrates the use of several configuration options: ```json { @@ -341,6 +350,9 @@ The following example (from the [DPNS contract's `domain` document](https://gith "canBeDeleted": true, "transferable": 1, "tradeMode": 1, + "keepsTransferHistory": true, + "keepsPurchaseHistory": true, + "keepsPricingHistory": true, "..." } } @@ -351,21 +363,35 @@ The following example (from the [DPNS contract's `domain` document](https://gith :::{versionadded} 4.0.0 ::: -Document types can opt into aggregate query support (count / sum / average) by setting flags at the document-type level. These flags control the underlying storage layout — once set on a published contract they cannot be changed by a contract update. +Document types can opt into aggregate query support (count / sum / average) through flags at the document-type root and on individual [index objects](#document-indices). These flags control the underlying storage layout — once set on a published contract they cannot be changed by a contract update. + +### Document-type flags + +Document-type flags configure aggregates on the primary-key tree and are set at the document-type root alongside options such as `documentsKeepHistory`. -There are two axes: +| Flag | Type | Purpose | +| - | - | - | +| `documentsCountable` | Boolean | Enables total document counts on the primary-key tree. | +| `rangeCountable` | Boolean | Enables range counts on the primary-key tree and implies `documentsCountable`. | +| `documentsSummable` | String | Enables total sums of the named integer property. | +| `rangeSummable` | Boolean | Enables range sums on the primary-key tree. Requires `documentsSummable`. | +| `documentsAverageable` | String | Syntactic sugar for `documentsCountable: true` plus `documentsSummable: ""`. | +| `rangeAverageable` | Boolean | Syntactic sugar for root-level `rangeCountable: true` plus `rangeSummable: true`. Requires `documentsAverageable`. | -* **Doctype-wide** (`documents*`) — applies the aggregate over the entire document type. Set at the document type root, alongside other doctype options like `documentsKeepHistory`. -* **Per-index range** (`range*`) — extends the corresponding aggregate to range queries on indexed properties. Set on the index object (alongside `name`, `properties`, `unique`, and `contested`), using the index-level `countable`/`summable`/`averageable` flags and their `range*` variants — not on the individual `{ "field": "asc" }` property entry. Requires the matching base flag. +### Index-level flags + +Index-level flags configure aggregates along a specific index path. Set them on the index object alongside `name`, `properties`, `unique`, and `contested`, not on an individual `{ "field": "asc" }` property entry. + +| Flag | Type | Purpose | +| - | - | - | +| `countable` | Boolean or string | Enables count fast paths for the index. String values are `notCountable`, `countable`, and `countableAllowingOffset`; the last uses a provable count tree that also supports future range and offset queries. | +| `rangeCountable` | Boolean | Enables range counts over the indexed property. Requires `countable` to be enabled on the same index. | +| `summable` | String | Enables sums of the named integer document property through the index. | +| `rangeSummable` | Boolean | Enables range sums over the indexed property. Requires `summable` on the same index. | +| `averageable` | String | Syntactic sugar for index-level `countable: "countable"` plus `summable: ""`. | +| `rangeAverageable` | Boolean | Syntactic sugar for index-level `rangeCountable: true` plus `rangeSummable: true`. Requires `averageable` on the same index. | -| Flag | Type | Purpose | Required for | -| - | - | - | - | -| `documentsCountable` | Boolean | Doctype-wide counts (empty `where` or `==`/`IN` clauses on indexed fields). | `SELECT COUNT(*)` without a range clause. | -| `rangeCountable` | Boolean | Per-index counts over a range. Requires `documentsCountable`. | `SELECT COUNT(*)` with a range clause or `GROUP BY `. | -| `documentsSummable` | String | Doctype-wide sums of the named integer property. | `SELECT SUM()`. | -| `rangeSummable` | Boolean | Per-index sums over a range. Requires `documentsSummable`. | `SELECT SUM()` with a range clause. | -| `documentsAverageable` | String | Syntactic sugar for `documentsCountable: true` + `documentsSummable: ""`. | `SELECT AVG()`. | -| `rangeAverageable` | Boolean | Syntactic sugar for `rangeCountable: true` + `rangeSummable: true`. Requires `documentsAverageable`. | `SELECT AVG()` with a range clause. | +Properties named by `documentsSummable`, `documentsAverageable`, `summable`, or `averageable` must exist on the document type, be listed in `required`, and have an integer type. The averageable flags desugar to the underlying count + sum flags during contract parsing — same on-disk layout — so authors who think in terms of averages get a single flag and downstream code paths (insert, query, estimation) stay unchanged. If both `documentsAverageable` and `documentsSummable` are set, they must name the same property. @@ -410,7 +436,7 @@ schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/m | `type: array` | Only byte arrays are supported. `byteArray: true` must be defined; schemas for individual array items are not available | | `additionalItems` | Not supported. Per-item array schemas (`items` / `prefixItems`) are not available in document schemas; constrain arrays with `minItems`, `maxItems`, `uniqueItems`, `contains`, and `byteArray` | | `patternProperties` | Restricted - cannot be used for data contracts | -| `pattern` | Accept only [RE2](https://github.com/google/re2/wiki/Syntax) compatible regular expressions (defined in DPP logic) | +| `pattern` | Patterns are compiled with the Rust [`regex`](https://docs.rs/regex/latest/regex/) crate, whose semantics match [RE2](https://github.com/google/re2/wiki/Syntax) (no backtracking, lookaround, or backreferences), with a 5 MiB compiled-pattern size limit. Patterns using unsupported constructs or exceeding the size limit are rejected as JSON schema compilation errors | ## Example Syntax diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md index 6f4d3a60d..f9f208292 100644 --- a/docs/protocol-ref/data-contract-token.md +++ b/docs/protocol-ref/data-contract-token.md @@ -14,12 +14,12 @@ The following example shows a minimal `tokens` object defining a single token wi { "tokens": { "0": { - "$format_version": "0", + "$formatVersion": "0", "conventions": { - "$format_version": "0", + "$formatVersion": "0", "localizations": { "en": { - "$format_version": "0", + "$formatVersion": "0", "shouldCapitalize": false, "singularForm": "credit-token", "pluralForm": "credit-tokens" @@ -77,7 +77,7 @@ The `localizations` object contains language-specific display properties using [ | Property | Type | Description | |----------|------|-------------| -| `$format_version` | string | Version of the localization format (currently "0") | +| `$formatVersion` | string | Version of the localization format (currently "0") | | `shouldCapitalize` | boolean | Whether the token name should be capitalized when displayed | | `singularForm` | string | Singular form of the token name | | `pluralForm` | string | Plural form of the token name | @@ -85,13 +85,13 @@ The `localizations` object contains language-specific display properties using [ ```json "localizations": { "en": { - "$format_version": "0", + "$formatVersion": "0", "shouldCapitalize": true, "singularForm": "loyalty-point", "pluralForm": "loyalty-points" }, "es": { - "$format_version": "0", + "$formatVersion": "0", "shouldCapitalize": false, "singularForm": "punto-de-lealtad", "pluralForm": "puntos-de-lealtad" @@ -109,7 +109,7 @@ The `decimals` property specifies the number of decimal places for token amounts ```json "conventions": { - "$format_version": "0", + "$formatVersion": "0", "localizations": { /* ... */ }, "decimals": 8 // 8 decimal places (default) } @@ -144,7 +144,7 @@ Token configuration controls behavioral aspects of token operations, including s | Property | Type | Description | |----------|------|-------------| | `mainControlGroup` | unsigned integer | Position assigned to the main control group | -| `mainControlGroupCanBeModified` | string | Who is authorized to modify the main control group. Valid values are listed in the [authorized parties table](#authorized-parties). | +| `mainControlGroupCanBeModified` | object | Who is authorized to modify the main control group, given as a `$type` map. Valid values are listed in the [authorized parties table](#authorized-parties). | **Example:** @@ -155,7 +155,7 @@ Token configuration controls behavioral aspects of token operations, including s "startAsPaused": false, "allowTransferToFrozenBalance": true, "mainControlGroup": null, - "mainControlGroupCanBeModified": "NoOne" + "mainControlGroupCanBeModified": {"$type": "noOne"} } ``` @@ -167,16 +167,18 @@ Change control rules define authorization requirements for modifying various asp Rules can authorize no one, specific identities, or multiparty groups. The complete set of options [defined by DPP](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/change_control_rules/authorized_action_takers.rs#L26-L33) is: -| Authorized Party | Description | -|----------------------|-------------| -| `NoOne` | No one is authorized | -| `ContractOwner` | Only the contract owner is authorized | -| `Identity(Identifier)` | Only an identity is authorized | -| `MainGroup` | Only the [main control group](../explanations/tokens.md#main-control-group) is authorized | -| `Group()` | Only the specific group based in contract position "x" is authorized | +| Authorized Party | JSON value | Description | +| - | - | - | +| `NoOne` | `{"$type": "noOne"}` | No one is authorized | +| `ContractOwner` | `{"$type": "contractOwner"}` | Only the contract owner is authorized | +| `Identity(Identifier)` | `{"$type": "identity", "identity": ""}` | Only an identity is authorized | +| `MainGroup` | `{"$type": "mainGroup"}` | Only the [main control group](../explanations/tokens.md#main-control-group) is authorized | +| `Group()` | `{"$type": "group", "position": }` | Only the specific group based in contract position "x" is authorized | + +Authorized parties are encoded as objects carrying a `$type` discriminator. Bare strings such as `"ContractOwner"` are not accepted. :::{note} -Starting in protocol version 13, group-valued authorized parties must resolve when the contract is registered. `Group()` requires a group defined at contract position `x`, otherwise registration fails with `GroupPositionDoesNotExistError`. `MainGroup` requires `mainControlGroup` to be set, otherwise registration fails with `MainGroupIsNotDefinedError`. This applies to both `authorized_to_make_change` and `admin_action_takers` across every change control rule family. +Starting in protocol version 13, group-valued authorized parties must resolve when the contract is registered. `Group()` requires a group defined at contract position `x`, otherwise registration fails with `GroupPositionDoesNotExistError`. `MainGroup` requires `mainControlGroup` to be set, otherwise registration fails with `MainGroupIsNotDefinedError`. This applies to both `authorizedToMakeChange` and `adminActionTakers` across every change control rule family. At action time, a group action authorized by `MainGroup` succeeds only when the group submitting it is at the same contract position as the token's configured `mainControlGroup`. An unset `mainControlGroup` authorizes no group, and the action is rejected with `UnauthorizedTokenActionError`. ::: @@ -187,23 +189,22 @@ Each rule consists of the following parameters [defined in DPP](https://github.c | Field | Description | | - | - | -| `authorized_to`
`_make_change` | This is who is authorized to make such a change. Valid values are listed in the [authorized parties table](#authorized-parties). | -| `admin_action_takers` | This is who is authorized to make such a change to the people authorized to make a change. Valid values are listed in the [authorized parties table](#authorized-parties). | -| `changing_authorized`
`_action_takers_to`
`_no_one_allowed` | Are we allowed to change to `NoOne` in the future (default: false) | -| `changing_admin_action`
`_takers_to_no_one_allowed` | Are we allowed to change the admin action takers to `NoOne` in the future (default: false) | -| `self_changing_admin_`
`action_takers_allowed` | Can the admin action takers change themselves (default: false) | +| `authorizedTo`
`MakeChange` | This is who is authorized to make such a change. Valid values are listed in the [authorized parties table](#authorized-parties). | +| `adminActionTakers` | This is who is authorized to make such a change to the people authorized to make a change. Valid values are listed in the [authorized parties table](#authorized-parties). | +| `changingAuthorized`
`ActionTakersTo`
`NoOneAllowed` | Are we allowed to change to no one in the future (default: false) | +| `changingAdminAction`
`TakersToNoOneAllowed` | Are we allowed to change the admin action takers to no one in the future (default: false) | +| `selfChangingAdmin`
`ActionTakersAllowed` | Can the admin action takers change themselves (default: false) | **Example** ```json "": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } ``` @@ -231,13 +232,12 @@ Tokens support the following change control rules: ```json "manualMintingRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } ``` @@ -264,18 +264,16 @@ Perpetual distribution enables ongoing token allocation. The following configura ```json "perpetualDistribution": { - "$format_version": "0", + "$formatVersion": "0", "distributionType": { - "TimeBasedDistribution": { - "interval": 3600000, - "function": { - "FixedAmount": { - "amount": 100 - } - } + "$type": "timeBasedDistribution", + "interval": 3600000, + "function": { + "$type": "fixedAmount", + "amount": 100 } }, - "distributionRecipient": "ContractOwner" + "distributionRecipient": {"$type": "contractOwner"} } ``` @@ -283,11 +281,11 @@ Perpetual distribution enables ongoing token allocation. The following configura The `distributionType` field accepts one of three schedule types: -| Type | Interval Unit | Description | -|------|---------------|-------------| -| `BlockBasedDistribution` | Block height | Emits tokens every N blocks. By default begins at the block when the data contract is registered. | -| `TimeBasedDistribution` | Milliseconds | Emits tokens every N milliseconds. By default begins at the time of the block when the data contract is registered. | -| `EpochBasedDistribution` | Epochs | Emits tokens every N epochs. By default begins at the epoch of the block when the data contract is registered. Distribution happens at the start of the following epoch. Required when using `EvonodesByParticipation` as the distribution recipient. | +| Type | JSON `$type` value | Interval Unit | Description | +| - | - | - | - | +| `BlockBasedDistribution` | `blockBasedDistribution` | Block height | Emits tokens every N blocks. By default begins at the block when the data contract is registered. | +| `TimeBasedDistribution` | `timeBasedDistribution` | Milliseconds | Emits tokens every N milliseconds. By default begins at the time of the block when the data contract is registered. | +| `EpochBasedDistribution` | `epochBasedDistribution` | Epochs | Emits tokens every N epochs. By default begins at the epoch of the block when the data contract is registered. Distribution happens at the start of the following epoch. Required when using `EvonodesByParticipation` as the distribution recipient. | Each type wraps an `interval` (the period length) and a `function` (the emission pattern from the options below). There is no separate `start` field on the distribution type; the schedule begins at contract registration by default and a later start can be set through the function's start offset parameter (`start_step`, `start_moment`, or `start_decreasing_offset`, depending on the function). @@ -295,17 +293,17 @@ Each type wraps an `interval` (the period length) and a `function` (the emission A wide variety of emission patterns are provided to cover most common scenarios. The following table summarizes the options and links to further details. -| Name | Description | -| - | - | -| [Fixed Amount](#fixed-amount) | Emits a constant number of tokens per period | -| [Random](#random) | Emits a random amount between `min` and `max`, using a PRF | -| [Step Decreasing Amount](#step-decreasing-amount) | Emits tokens that decrease in discrete steps at fixed intervals | -| [Linear](#linear) | Linear growth/decay with integer or fractional precision | -| [Polynomial](#polynomial) | Polynomial with integer or fractional exponents or coefficients | -| [Exponential](#exponential) | Emits tokens following an exponential function | -| [Logarithmic](#logarithmic) | Slows emission over time | -| [Inverted Logarithmic](#inverted-logarithmic) | Slows emission over time | -| [Stepwise](#stepwise) | Emits constant values within predefined steps | +| Name | JSON `$type` value | Description | +| - | - | - | +| [Fixed Amount](#fixed-amount) | `fixedAmount` | Emits a constant number of tokens per period | +| [Random](#random) | `random` | Emits a random amount between `min` and `max`, using a PRF | +| [Step Decreasing Amount](#step-decreasing-amount) | `stepDecreasingAmount` | Emits tokens that decrease in discrete steps at fixed intervals | +| [Linear](#linear) | `linear` | Linear growth/decay with integer or fractional precision | +| [Polynomial](#polynomial) | `polynomial` | Polynomial with integer or fractional exponents or coefficients | +| [Exponential](#exponential) | `exponential` | Emits tokens following an exponential function | +| [Logarithmic](#logarithmic) | `logarithmic` | Slows emission over time | +| [Inverted Logarithmic](#inverted-logarithmic) | `invertedLogarithmic` | Slows emission over time | +| [Stepwise](#stepwise) | `stepwise` | Emits constant values within predefined steps | ##### Fixed Amount @@ -497,7 +495,7 @@ Pre-programmed distribution allows scheduling specific token allocations at pred ```json "preProgrammedDistribution": { - "$format_version": "0", + "$formatVersion": "0", "distributions": { "1749662152621": { "2yZbE3TAZAhLwNVQk7JMUUuBXgrVt1NG172PGjeUfjUo": 100 @@ -518,13 +516,12 @@ Direct purchase pricing enables tokens to be [purchased directly using Platform] ```json "changeDirectPurchasePricingRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } ``` @@ -549,7 +546,7 @@ The properties below are token-level and are nested under the token's `keepsHist ```json "keepsHistory": { - "$format_version": "0", + "$formatVersion": "0", "keepsTransferHistory": true, "keepsFreezingHistory": true, "keepsMintingHistory": true, @@ -573,16 +570,15 @@ Marketplace rules define how tokens can be traded within Platform's built-in mar ```json "marketplaceRules": { - "$format_version": "0", + "$formatVersion": "0", "tradeMode": "NotTradeable", "tradeModeChangeRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } } ``` @@ -615,11 +611,11 @@ The **Default** column shows typical values rather than code-enforced defaults. ### Distribution Recipients -| Recipient | Description | -|-----------|-------------| -| `ContractOwner` | Tokens sent to the contract owner | -| `Identity(Identifier)` | Tokens sent to a specific identity | -| `EvonodesByParticipation` | Tokens distributed to evonodes proportional to their participation (only valid with `EpochBasedDistribution`) | +| Recipient | JSON value | Description | +| - | - | - | +| `ContractOwner` | `{"$type": "contractOwner"}` | Tokens sent to the contract owner | +| `Identity(Identifier)` | `{"$type": "identity", "identity": ""}` | Tokens sent to a specific identity | +| `EvonodesByParticipation` | `{"$type": "evonodesByParticipation"}` | Tokens distributed to evonodes proportional to their participation (only valid with `EpochBasedDistribution`) | :::{seealso} For all protocol constants, see [Protocol Constants](protocol-constants.md). @@ -663,12 +659,12 @@ This example shows the complete structure of a token definition with all major c { "tokens": { "0": { - "$format_version": "0", + "$formatVersion": "0", "conventions": { - "$format_version": "0", + "$formatVersion": "0", "localizations": { "en": { - "$format_version": "0", + "$formatVersion": "0", "shouldCapitalize": true, "singularForm": "reward-token", "pluralForm": "reward-tokens" @@ -677,18 +673,17 @@ This example shows the complete structure of a token definition with all major c "decimals": 8 }, "conventionsChangeRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "baseSupply": 1000000, "maxSupply": 10000000, "keepsHistory": { - "$format_version": "0", + "$formatVersion": "0", "keepsTransferHistory": true, "keepsFreezingHistory": true, "keepsMintingHistory": true, @@ -699,126 +694,114 @@ This example shows the complete structure of a token definition with all major c "startAsPaused": false, "allowTransferToFrozenBalance": true, "maxSupplyChangeRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "distributionRules": { - "$format_version": "0", + "$formatVersion": "0", "perpetualDistribution": null, "perpetualDistributionRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "preProgrammedDistribution": null, "newTokensDestinationIdentity": null, "newTokensDestinationIdentityRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "mintingAllowChoosingDestination": true, "mintingAllowChoosingDestinationRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "changeDirectPurchasePricingRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } }, "marketplaceRules": { - "$format_version": "0", + "$formatVersion": "0", "tradeMode": "NotTradeable", "tradeModeChangeRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false } }, "manualMintingRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "manualBurningRules": { - "V0": { - "authorized_to_make_change": "ContractOwner", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "contractOwner"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "freezeRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "unfreezeRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "destroyFrozenFundsRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "emergencyActionRules": { - "V0": { - "authorized_to_make_change": "NoOne", - "admin_action_takers": "NoOne", - "changing_authorized_action_takers_to_no_one_allowed": false, - "changing_admin_action_takers_to_no_one_allowed": false, - "self_changing_admin_action_takers_allowed": false - } + "$formatVersion": "0", + "authorizedToMakeChange": {"$type": "noOne"}, + "adminActionTakers": {"$type": "noOne"}, + "changingAuthorizedActionTakersToNoOneAllowed": false, + "changingAdminActionTakersToNoOneAllowed": false, + "selfChangingAdminActionTakersAllowed": false }, "mainControlGroup": null, - "mainControlGroupCanBeModified": "NoOne", + "mainControlGroupCanBeModified": {"$type": "noOne"}, "description": "Reward token for customer loyalty program" } } diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index cdff3c042..759953851 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -79,8 +79,8 @@ The data contract object consists of the following fields as defined in the Rust | $defs | object | Varies | (Optional) Definitions for `$ref` references used in the `documents` object (if present, must be a non-empty object with \<= 100 valid properties) | | [groups](#data-contract-groups) | Group | Varies | (Optional) Groups that allow for specific multiparty actions on the contract. | | [tokens](./data-contract-token.md) | object | Varies | (Optional \*) Token definitions (see [Contract Tokens](./data-contract-token.md) for details) | -| keywords | array of strings | Varies | (Optional) Keywords associated with the contract to improve searchability. Maximum of 50 keywords. | -| description | string | 3-100 characters | (Optional) Brief description of the contract. | +| keywords | array of strings | Varies | (Optional) Keywords associated with the contract to improve searchability. Maximum of 50 keywords. Each keyword must be 3-50 bytes, must not contain control or whitespace characters, and must be unique within the array. | +| description | string | 3-100 bytes on create
3-100 characters on update | (Optional) Brief description of the contract. The length limit is measured in bytes at registration and in characters on update, so the two bounds differ for non-ASCII text. | | createdAt | unsigned integer | 64 bits | (Read-only) Timestamp in milliseconds when the contract was created. Set by platform. | | updatedAt | unsigned integer | 64 bits | (Read-only) Timestamp in milliseconds when the contract was last updated. Set by platform. | | createdAtBlockHeight | unsigned integer | 64 bits | (Read-only) Block height at contract creation. Set by platform. | @@ -1017,7 +1017,14 @@ of a data contract can be updated: - Adding a new document - Adding a new optional property to an existing document -- Adding non-unique indices for properties added in the update +- Adding an index, as long as the index tree remains structurally compatible. Existing index definitions are immutable, and the aggregate flags (`countable`, `rangeCountable`, `summable`, `rangeSummable`, `averageable`, `rangeAverageable`) on an existing index cannot be changed +- Adding a new token at a previously unused position +- Adding a new group at a previously unused position +- Changing the `keywords` array +- Changing the `description` +- Enabling `sizedIntegerTypes`. This is a one-way change; it cannot be disabled once enabled + +Existing tokens and groups cannot be removed or modified once the contract is registered. Data contracts are updated on the platform by submitting the modified [data contract object](#data-contract-object) in a data contract update state transition consisting of: diff --git a/docs/protocol-ref/errors.md b/docs/protocol-ref/errors.md index 86f03f656..e3b57cecf 100644 --- a/docs/protocol-ref/errors.md +++ b/docs/protocol-ref/errors.md @@ -332,7 +332,7 @@ Code range: 40000-40099 ### Document State -Code range: 40100-40149 +Code range: 40100-40199 | Code | Error Description | Comment | | :---: | ------------------------------------------------------ | ------- | diff --git a/docs/protocol-ref/identity.md b/docs/protocol-ref/identity.md index 52b725e7f..8fa0dc0cd 100644 --- a/docs/protocol-ref/identity.md +++ b/docs/protocol-ref/identity.md @@ -291,7 +291,7 @@ The InstantSend asset lock proof is used for transactions that have received an | Field | Type | Description | | ----------- | -------------- | ----------- | -| type | integer | The asset lock proof type (`0` for InstantSend locks) | +| $type | string | The asset lock proof type (`"instant"` for InstantSend locks) | | instantLock | array of bytes | The InstantSend lock ([`islock`](https://docs.dash.org/en/stable/docs/core/reference/p2p-network-instantsend-messages.html#islock)) | | transaction | array of bytes | The asset lock transaction | | outputIndex | integer | Index of the transaction output to be used | @@ -302,9 +302,9 @@ The ChainLock asset lock proof is used for transactions that have not received a | Field | Type | Description | | --------------------- | -------------- | ----------- | -| type | integer | The type of asset lock proof (`1` for ChainLocks) | +| $type | string | The asset lock proof type (`"chain"` for ChainLocks) | | coreChainLockedHeight | integer | Height of the ChainLocked Core block containing the transaction | -| outPoint | object | The [outpoint](https://docs.dash.org/en/stable/docs/core/resources/glossary.html#outpoint) being used as the asset lock | +| outPoint | string | The [outpoint](https://docs.dash.org/en/stable/docs/core/resources/glossary.html#outpoint) being used as the asset lock. JSON encodes it as `":"`. The `platform_value` representation is an object containing `txid` as 32 bytes and `vout` as an unsigned 32-bit integer. | ### Identity State Transition Signing diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 62e827c70..89ae2da75 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -22,8 +22,8 @@ Maximum sizes and limits for various platform components. | Max withdrawal amount | 50,000,000,000,000 credits | 500 Dash maximum per withdrawal | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L19) | | Max contract group size | 256 | Maximum members per group | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L21) | | Max token redemption cycles | 128 | Maximum redemption cycles | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L22) | -| Max shielded transition actions | 16 | Maximum [actions](shielded-pool.md#actions) per shielded transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L30) | -| Max CBOR encoded length | 16,384 bytes (16 KiB) | Maximum CBOR encoding size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/util/cbor_serializer.rs#L8) | +| Max shielded transition actions | 16 | Consensus cap on [actions](shielded-pool.md#actions) per shielded transition. The effective limit is 6 - the Halo 2 proof grows ~2,681 bytes per action, so larger transitions exceed the max state transition size | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L30) | +| Max CBOR encoded length | 16,384 bytes (16 KiB) | Maximum CBOR encoding size (defined as `MAX_ENCODED_KBYTE_LENGTH = 16` kibibytes) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/util/cbor_serializer.rs#L8) | | Contract deserialization limit | 15,000 | Maximum contract deserialization | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/serialized_version/mod.rs#L40) | ## Credit System @@ -166,7 +166,7 @@ Fees related to contested document voting. | Limit | Value | Description | Source | |-------|-------|-------------|--------| | Max public keys per identity | 15,000 | Maximum keys an identity can have | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/fields.rs#L7) | -| Max keys in creation | 6 | Keys allowed at identity creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L18) | +| Max keys in creation | 6 | Keys allowed at identity creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L18) | | Identity nonce value filter | 0xFFFFFFFFFF | 40-bit nonce filter | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_nonce.rs#L13) | | Max missing identity revisions | 24 | Maximum revision gaps | [rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/identity/identity_nonce.rs#L15) | @@ -174,10 +174,10 @@ Fees related to contested document voting. | Requirement | Value | Description | Source | |-------------|-------|-------------|--------| -| Min asset lock balance | 200,000 duffs | 0.002 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L20) | -| Min top-up balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/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/v4.1.0/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/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L42) | +| Min asset lock balance | 200,000 duffs | 0.002 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L20) | +| Min top-up balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L21) | +| Min address funding balance | 50,000 duffs | 0.0005 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L22) | +| Min identity funding amount | 200,000 credits | Minimum for address-based creation | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L42) | | 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/v4.1.0/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | ## Document & Data Contract Model diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index 1392bab73..bdbc47406 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -33,7 +33,7 @@ Every shielded transition includes an Orchard bundle proving that a set of note | Field | Type | Size | Description | | --- | --- | --- | --- | -| actions | array | Varies | Orchard [actions](#actions) (spend-output pairs). Limited to [`max_shielded_transition_actions`](protocol-constants.md) per transition. | +| actions | array | Varies | Orchard [actions](#actions) (spend-output pairs). Limited to [`max_shielded_transition_actions`](protocol-constants.md) per transition. In practice the effective limit is 6, since the Halo 2 proof grows with each action and the serialized transition must stay within the [maximum state transition size](protocol-constants.md). | | anchor | array of bytes | 32 bytes | Sinsemilla root of the note commitment tree at bundle creation time. Must match an [anchor](#anchors) the platform has previously recorded | | proof | array of bytes | Varies | Halo 2 zero-knowledge proof that the actions are valid | | bindingSignature | array of bytes | 64 bytes | RedPallas signature binding the bundle's actions to its net value balance | @@ -95,6 +95,8 @@ Move credits from one or more [Platform addresses](address-system.md#platform-ad :::{note} Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). Address witness signatures are excluded from the signable bytes used by the platform sighash. + +**Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Minimum per input: 100,000 credits. One witness per input. `amount` must be greater than zero and at most `i64::MAX`, and the input sum must cover the amount plus the minimum shielded fee. The fee strategy must be non-empty, contain no duplicate steps, and have at most `max_address_fee_strategies` steps. ::: See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_transition/v0/mod.rs#L37-L63). @@ -174,6 +176,8 @@ Move credits from the pool back to Dash Core (L1). The funds leave Platform enti :::{note} Transparent fields (`coreFeePerByte`, `pooling`, `outputScript`) are bound to the Orchard bundle through the [platform sighash](#platform-sighash). Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). + +**Constraints:** Pooling must be `Never` (others not yet implemented). `coreFeePerByte` must be a non-zero Fibonacci number. Output script must be P2PKH or P2SH. ::: See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_withdrawal_transition/v0/mod.rs#L33-L54). diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 18dcd61bb..2aee6cfc4 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -113,7 +113,7 @@ The token transfer transition extends the [base transition](#token-base-transiti | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| amount | unsigned integer | 64 bits | Number of tokens to transfer | +| $amount | unsigned integer | 64 bits | Number of tokens to transfer. Note the `$` prefix, which is specific to the transfer transition - the mint transition uses a plain `amount` field | | recipientId | array | 32 bytes | Identity ID of the recipient | | publicNote | string | [<= 2048 bytes](#token-notes) | Optional public note | | sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/tokens/mod.rs#L20) | [<= 2048 bytes](#token-notes) | Optional shared encrypted note | From bd1696769229c1154d57e5c85d7c9f894079d31c Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 11 Aug 2026 12:42:21 -0400 Subject: [PATCH 16/17] chore: sync tutorial code with tutorials repo Ran `python3 scripts/tutorial-sync/sync_tutorial_code.py --source ...` --- _static/dashmint-lite.html | 11 +++++------ _static/dashnote-lite.html | 2 +- _static/dashproof-lite.html | 2 +- docs/tutorials/example-apps/dashnote.md | 3 +-- docs/tutorials/setup-sdk-client.md | 19 +++++++++++-------- 5 files changed, 19 insertions(+), 18 deletions(-) diff --git a/_static/dashmint-lite.html b/_static/dashmint-lite.html index 084c924ed..841166c65 100644 --- a/_static/dashmint-lite.html +++ b/_static/dashmint-lite.html @@ -119,7 +119,7 @@

Browse cards

// 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@4.0.0'; + import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.1.0'; // 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 @@ -131,12 +131,11 @@

Browse cards

// 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. + // The platform protocol version is left unset on purpose: the SDK negotiates + // it with the network. Passing `version` pins it and disables that, so a + // hardcoded value silently goes stale at the next network upgrade. async function connectSdk() { - const sdk = EvoSDK.testnetTrusted({ version: 11 }); + const sdk = EvoSDK.testnetTrusted(); await sdk.connect(); return sdk; } diff --git a/_static/dashnote-lite.html b/_static/dashnote-lite.html index 809a7f867..e1241e054 100644 --- a/_static/dashnote-lite.html +++ b/_static/dashnote-lite.html @@ -129,7 +129,7 @@

Get note by ID

// 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@4.0.0'; + import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.1.0'; // The "note" data contract is already published on testnet by the React app. // Anyone querying with the same contract id hits the same documents. diff --git a/_static/dashproof-lite.html b/_static/dashproof-lite.html index dfa6ae06f..8898daed1 100644 --- a/_static/dashproof-lite.html +++ b/_static/dashproof-lite.html @@ -120,7 +120,7 @@

History by chainId

// 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@4.0.0'; + import { EvoSDK } from 'https://esm.sh/@dashevo/evo-sdk@4.1.0'; // The "anchor" data contract is already published on testnet by the React app. // Anyone querying with the same contract id hits the same documents. diff --git a/docs/tutorials/example-apps/dashnote.md b/docs/tutorials/example-apps/dashnote.md index 19884fe1c..ce26db03a 100644 --- a/docs/tutorials/example-apps/dashnote.md +++ b/docs/tutorials/example-apps/dashnote.md @@ -262,7 +262,6 @@ Each operation file is intentionally small. The app-level pattern is: validate i * SDK method: sdk.documents.create({ document, identityKey, signer }) */ import type { Logger } from "../lib/logger"; -import { PLATFORM_VERSION_OVERRIDE } from "../../../../platformVersion.mjs"; import { loadSdkModule } from "./sdkModule"; import type { DashKeyManager, DashSdk } from "./types"; @@ -305,7 +304,7 @@ export async function createNote({ const json = typeof document.toJSON === "function" - ? (document.toJSON(PLATFORM_VERSION_OVERRIDE) as Record) + ? (document.toJSON(sdk.version()) as Record) : {}; const noteId = String(json.$id ?? json.id ?? ""); if (!noteId) { diff --git a/docs/tutorials/setup-sdk-client.md b/docs/tutorials/setup-sdk-client.md index b01d38591..f4ff350d8 100644 --- a/docs/tutorials/setup-sdk-client.md +++ b/docs/tutorials/setup-sdk-client.md @@ -60,7 +60,6 @@ import { SecurityLevel, wallet, } from '@dashevo/evo-sdk'; -import { PLATFORM_VERSION_OVERRIDE } from './platformVersion.mjs'; /** @typedef {import('@dashevo/evo-sdk').Identity} Identity */ /** @typedef {import('@dashevo/evo-sdk').IdentityPublicKey} IdentityPublicKey */ @@ -138,21 +137,25 @@ export async function dip13KeyPath(network, identityIndex, keyIndex) { // SDK client helpers // --------------------------------------------------------------------------- -export { PLATFORM_VERSION_OVERRIDE }; - /** * Create and connect an EvoSDK client for the selected network. * + * The platform protocol version is deliberately left unset so the SDK + * negotiates it with the network: it starts from a conservative version and + * ratchets up to whatever the network reports, capped at the newest version + * the SDK itself understands. Pinning it via the `version` option disables + * that negotiation outright, so a hardcoded value silently goes stale the + * next time the network upgrades. Use `sdk.version()` when you need the + * negotiated value. + * * @param {string} [network='testnet'] * @returns {Promise} */ export async function createClient(network = 'testnet') { const factories = /** @type {Record EvoSDK>} */ ({ - testnet: () => - EvoSDK.testnetTrusted({ version: PLATFORM_VERSION_OVERRIDE }), - mainnet: () => - EvoSDK.mainnetTrusted({ version: PLATFORM_VERSION_OVERRIDE }), - local: () => EvoSDK.localTrusted({ version: PLATFORM_VERSION_OVERRIDE }), + testnet: () => EvoSDK.testnetTrusted(), + mainnet: () => EvoSDK.mainnetTrusted(), + local: () => EvoSDK.localTrusted(), }); const factory = factories[network]; From ea1ef141d419b6d9202643692380f9715668e46a Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 11 Aug 2026 16:05:06 -0400 Subject: [PATCH 17/17] docs: resolve review feedback on the v4.1.0 audit updates Correct the shielded authorization description on both protocol explanation pages. Shielded transitions omit the generic identity signature but retain Orchard `spendAuthSig` and `bindingSignature`, and applicable transitions also carry address witnesses or an asset-lock signature. Add `in` to the operators listed for `orderBy`, matching the range operator section and the `is_range` classification in rs-drive. Note that JSON-RPC `getStatus` returns Platform status rather than Core information, on both the endpoint listing and the DAPI Client glossary entry. Document that an interrupted mempool snapshot has no resume cursor on `subscribeToTransactionsWithProofs`, and point the streaming overview at that endpoint rather than describing mempool recovery generically. Replace the unconditional retry advice on `getShieldedAnchors` with backoff and alternate-node guidance. Link the layer 2 identity funding paths from the identity explanation and label the existing procedures as the Core-chain path. Clarify that the fee multiplier does not scale the base fee while the final fee still follows the complete formula, and that SDKs verify standard proofs automatically while direct clients handle the compacted envelope and bare `merkProof` paths. Point the data contract meta-schema references at the v2 schema and recompute the line anchors. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanations/fees.md | 4 +++- docs/explanations/identity.md | 7 ++++++- .../platform-protocol-state-transition.md | 4 ++-- docs/explanations/platform-protocol.md | 4 ++-- .../dapi-endpoints-core-grpc-endpoints.md | 4 ++++ .../reference/dapi-endpoints-grpc-overview.md | 6 ++++-- .../dapi-endpoints-platform-endpoints.md | 2 +- docs/reference/dapi-endpoints.md | 3 +++ docs/reference/data-contracts.md | 20 +++++++++---------- docs/reference/glossary.md | 3 ++- docs/reference/platform-proofs.md | 13 ++++++------ docs/reference/query-syntax.md | 2 +- 12 files changed, 45 insertions(+), 27 deletions(-) diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index 6bd7e113f..19373223a 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -44,7 +44,9 @@ Refer to the [Identity explanation](../explanations/identity.md) section for inf 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 multiplier does not scale the fee a user is charged. The active fee version fixes it at 1.0x, and the fee charged for a state transition is the sum of its storage and per-operation processing costs as described above. +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, +including any user fee increase and storage refund. Fee parameters, including the multiplier, are fixed by the active fee version. They change only when the network activates a new protocol version, which happens once enough evonodes signal the newer version and the threshold is met at an epoch change. diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index 9f4525279..8f0d173fd 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -16,12 +16,17 @@ The [Identities Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips ## Identity Management -In order to [create an identity](#identity-create-process), a user pays the network to store their public key(s) on the platform chain. This is done by locking Dash on the Core chain in an asset lock transaction and then submitting an identity create state transition that references a proof of that lock. +In order to [create an identity](#identity-create-process), a user pays the network to store their public key(s) on the platform chain. On the Core-chain path, this is done by locking Dash in an asset lock transaction and then submitting an identity create state transition that references a proof of that lock. 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. +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), +[Identity Top Up From Addresses](../protocol-ref/address-system.md#identity-top-up-from-addresses), +and [Identity Create From Shielded Pool](../protocol-ref/shielded-pool.md#identity-create-from-shielded-pool). + ### Identity Create Process :::{note} diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md index 330c1b6f9..f2338cddd 100644 --- a/docs/explanations/platform-protocol-state-transition.md +++ b/docs/explanations/platform-protocol-state-transition.md @@ -30,9 +30,9 @@ To support the various data types used on the platform and enable future updates 1. Header - version and payload type 2. Payload - contents vary depending on payload type -3. Signature - authorization for the header/payload +3. Authorization - authorization data for the header/payload -Authorization varies by transition family. Transitions submitted by an identity carry a signature made with one of that identity's keys. Transitions that spend from [Platform addresses](../protocol-ref/address-system.md) are instead authorized by a witness signature on each address input, since the funds belong to the addresses rather than to an identity. [Shielded pool](../explanations/shielded-pool.md) spends carry no signature at all - a zero-knowledge proof authorizes them without revealing who made them. +Authorization varies by transition family. Transitions submitted by an identity carry a signature made with one of that identity's keys. Transitions that spend from [Platform addresses](../protocol-ref/address-system.md) are instead authorized by a witness signature on each address input, since the funds belong to the addresses rather than to an identity. [Shielded pool](../explanations/shielded-pool.md) transitions omit the generic identity transition signature but retain Orchard `spendAuthSig` and `bindingSignature` authorization. Applicable shielded transitions also carry address witnesses or an asset-lock signature. The following table contains a list of currently defined payload types: diff --git a/docs/explanations/platform-protocol.md b/docs/explanations/platform-protocol.md index b21ae40f6..0e36b9fc6 100644 --- a/docs/explanations/platform-protocol.md +++ b/docs/explanations/platform-protocol.md @@ -38,11 +38,11 @@ A state transition represents a change made by a user to the application and pla * A header (version and payload type) * A payload -* The user's signature +* Authorization data The payload varies by type and covers a range of operations including document and token updates, data contract creation, identity management, credit transfers, masternode voting, [Platform address](../protocol-ref/address-system.md) funding and transfers, and [shielded pool](../explanations/shielded-pool.md) operations. -How a transition is authorized depends on its family. Identity-owned transitions carry a signature made for the binary representation of the state transition using a private key associated with an [identity](../explanations/identity.md). Platform address transitions are instead authorized by a witness signature on each input, and shielded pool transitions by a zero-knowledge proof rather than any signature at all. A state transition is constructed by a client-side library when the user creates documents and submits them to the platform API. +How a transition is authorized depends on its family. Identity-owned transitions carry a signature made for the binary representation of the state transition using a private key associated with an [identity](../explanations/identity.md). Platform address transitions are instead authorized by a witness signature on each input. Shielded pool transitions omit the generic identity transition signature but retain Orchard `spendAuthSig` and `bindingSignature` authorization; applicable transitions also carry address witnesses or an asset-lock signature. A state transition is constructed by a client-side library when the user creates documents and submits them to the platform API. For additional detail, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. diff --git a/docs/reference/dapi-endpoints-core-grpc-endpoints.md b/docs/reference/dapi-endpoints-core-grpc-endpoints.md index 85e9274f7..40aa6461a 100644 --- a/docs/reference/dapi-endpoints-core-grpc-endpoints.md +++ b/docs/reference/dapi-endpoints-core-grpc-endpoints.md @@ -706,6 +706,10 @@ The `bloom_filter` message is optional. Omitting it streams all transactions. Wh :::{versionadded} 4.1.0 `from_block_height` must be at least 1 and `from_block_hash` must be exactly 32 bytes; other values are rejected with `INVALID_ARGUMENT`. Omitting both is also rejected. +An interrupted mempool snapshot has no equivalent cursor because the request specifies only a +starting block. A reconnecting client therefore requests the snapshot in full and should reconcile +mempool state rather than assume the interrupted snapshot completed. + A node accepts at most 64 concurrent streams on this endpoint. A subscribe attempt beyond that returns `RESOURCE_EXHAUSTED` — back off and retry, or connect to a different node. An established stream can also be terminated with `RESOURCE_EXHAUSTED`; see [stream termination and backpressure](dapi-endpoints-grpc-overview.md#stream-termination-and-backpressure). ::: diff --git a/docs/reference/dapi-endpoints-grpc-overview.md b/docs/reference/dapi-endpoints-grpc-overview.md index a9ee7d52e..f1fdd6b2c 100644 --- a/docs/reference/dapi-endpoints-grpc-overview.md +++ b/docs/reference/dapi-endpoints-grpc-overview.md @@ -44,7 +44,9 @@ grpcui -insecure -open-browser -proto protos/core/v0/core.proto seed-1.testnet Streaming endpoints apply per-stream delivery bounds, so a stream that has already been established can be terminated by the server with `RESOURCE_EXHAUSTED`. This happens when: - The client cannot keep up with delivery and the stream's pending-event or pending-byte budget is exceeded. -- The initial mempool snapshot exceeds the per-stream transaction count or byte budget. +- The initial mempool snapshot exceeds the per-stream transaction count or byte budget. See + [`subscribeToTransactionsWithProofs`](dapi-endpoints-core-grpc-endpoints.md#subscribetotransactionswithproofs) + for endpoint-specific recovery guidance. - The handover from replaying historical data to live delivery does not complete within 180 seconds. -Treat this status as a resumable backpressure signal rather than a fatal error: reconnect and resume from the last block your client finished processing. A `RESOURCE_EXHAUSTED` returned when *opening* a stream means the node's concurrent-stream limit for that endpoint is reached — back off and retry, or connect to a different node. +Treat this status as a resumable backpressure signal rather than a fatal error. For confirmed block data, reconnect and resume from the last block your client finished processing. A `RESOURCE_EXHAUSTED` returned when *opening* a stream means the node's concurrent-stream limit for that endpoint is reached — back off and retry, or connect to a different node. diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index 5b482b563..d27c15d6a 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -4846,7 +4846,7 @@ Returns the commitment tree anchors currently retained by the node for the shiel The response covers the [node's retention window](../protocol-ref/shielded-pool.md#anchors) rather than the full history of the pool: older anchors are pruned, so the retained set is bounded by the retention and pruning policy. :::{versionadded} 4.1.0 -If the retained anchor set exceeds what this unpaginated response can enumerate, the call returns `RESOURCE_EXHAUSTED` instead of doing unbounded work. Treat it as retryable rather than fatal. +If the retained anchor set exceeds what this unpaginated response can enumerate, the call returns `RESOURCE_EXHAUSTED` instead of doing unbounded work. Retry with backoff; if the condition persists, try another node rather than repeatedly retrying the same one. ::: **Example Request and Response** diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index 1942e1ec3..04790916d 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -155,6 +155,9 @@ The following endpoints provide information about the Core chain. ### JSON-RPC Endpoints +These endpoints historically expose Core information; `getStatus` is the exception and returns +Platform status. + | Endpoint | Description | | -------- | ----------- | | [`getBestBlockHash`](../reference/dapi-endpoints-json-rpc-endpoints.md#getbestblockhash) | Returns block hash of the chaintip | diff --git a/docs/reference/data-contracts.md b/docs/reference/data-contracts.md index 9ba217a7a..c82c78f3c 100644 --- a/docs/reference/data-contracts.md +++ b/docs/reference/data-contracts.md @@ -189,10 +189,10 @@ There are a variety of constraints currently defined for performance and securit | Description | Value | | ----------- | ----- | -| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L22) | -| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L23) | -| Minimum property name length | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L9) | -| Maximum property name length | [64](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L9) | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L23) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L24) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L21) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L21) | | Property name characters | Alphanumeric (`A-Z`, `a-z`, `0-9`)
Hyphen (`-`)
Underscore (`_`) | #### Assigning property `position` @@ -350,10 +350,10 @@ For performance and security reasons, indices have the following constraints. Th | Description | Value | | ----------- | ----- | -| Minimum / maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L311) / [32](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L312) | -| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L390) | +| Minimum / maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L358) / [32](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L359) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L482) | | Maximum number of unique indices | [10](https://github.com/dashpay/platform/blob/master/packages/rs-platform-version/src/version/v1.rs#L989) | -| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L331) | +| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L378) | | Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L72) | | Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L73) | | Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L74) | @@ -452,7 +452,7 @@ This example syntax shows the structure of a document object including all optio ## General Constraints -There are a variety of constraints currently defined for performance and security reasons. The following constraints are applicable to all aspects of data contracts. Unless otherwise noted, these constraints are defined in the platform's JSON Schema rules (e.g. [rs-dpp document meta schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json)). +There are a variety of constraints currently defined for performance and security reasons. The following constraints are applicable to all aspects of data contracts. Unless otherwise noted, these constraints are defined in the platform's JSON Schema rules (e.g. [rs-dpp document meta schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json)). ### Keyword @@ -460,8 +460,8 @@ There are a variety of constraints currently defined for performance and securit | ------- | ---------- | | `default` | Restricted - cannot be used (defined in DPP logic) | | `propertyNames` | Restricted - cannot be used (defined in DPP logic) | -| `pattern: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L187)) | -| `format: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L200)) | +| `pattern: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L188)) | +| `format: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L201)) | | `$ref: ` | Internal references only - the value must begin with `#` (e.g. `#/$defs/myType`). External and remote references, and reference cycles, are rejected | | `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` | Disabled for data contracts | | `dependencies` | Not supported. Use `dependentRequired` instead | diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 955b83373..395c2036d 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -49,7 +49,8 @@ Dash's decentralized API for interacting with the core blockchain (layer 1) and ## DAPI Client A client that connects to DAPI to read and write Platform data or access Core chain information. -DAPI exposes gRPC services for Platform and Core, plus JSON-RPC for selected Core information. +DAPI exposes gRPC services for Platform and Core, plus JSON-RPC for selected Core information and +Platform status. ## DashPay diff --git a/docs/reference/platform-proofs.md b/docs/reference/platform-proofs.md index b3def1dd9..226563926 100644 --- a/docs/reference/platform-proofs.md +++ b/docs/reference/platform-proofs.md @@ -51,12 +51,13 @@ verification](#address-tree-sync-verification), respectively. ## Verifying proofs -Clients do not parse proofs manually. Verification is performed by the -`rs-drive-proof-verifier` crate, which checks the quorum's BLS threshold signature (the -Tenderdash consensus half) and decodes the unified `grovedbProof` to recover the requested data -and the state root hash. Dash Platform SDKs verify requested proofs automatically. Applications -performing verification directly can use `rs-drive-proof-verifier`; JavaScript and browser -applications can use the available WebAssembly bindings. +Dash Platform SDKs parse and verify standard requested proofs automatically. Verification is +performed by the `rs-drive-proof-verifier` crate, which checks the quorum's BLS threshold +signature (the Tenderdash consensus half) and decodes the unified `grovedbProof` to recover the +requested data and the state root hash. Direct clients must also handle the protocol-specific +compacted proof envelope and bare `merkProof` paths described below. Applications performing +verification directly can use `rs-drive-proof-verifier`; JavaScript and browser applications can +use the available WebAssembly bindings. See the [Proofs](../explanations/proofs.md) explanation for the step-by-step verification flow. diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index c3a4e6dc9..0fb18ffab 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -172,7 +172,7 @@ The query modifiers described here determine how query results will be sorted an | Modifier | Effect | Example | | - | - | - | | `limit` | Restricts the number of documents returned. An omitted value or `0` uses the configured default (100 by default). Positive values cannot exceed the configured maximum (also 100 by default). See [Aggregate query limits](#aggregate-query-limits) for aggregate result modes. | `limit: 10` | -| `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | +| `orderBy` | Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index's properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Can only be used with `>`, `<`, `>=`, `<=`, `in`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: ''` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: ''` | | `offset` | Present on the wire but currently rejected with `Unsupported`. Use `startAt` or `startAfter` for pagination. | n/a |