From 9d171cbb5d7f61739f4393be1b1363ecd8920ab9 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 10 Sep 2026 10:54:11 -0400 Subject: [PATCH 1/8] docs(reference): update for Dash Platform 4.2 and correct stale behavior Document the protocol v14 getDocuments query surface. Correct two claims that no longer hold. OFFSET is consumed in ranked mode rather than always rejected, and HAVING is served in having-range mode. Retarget data-contracts to the v3 document meta-schema and add the keywords it introduces. Fix the index example, and drop a required-field count that disagreed with the list beneath it. Document error codes and response semantics for getBlock, getTransaction, getBlockchainStatus, and getMasternodeStatus; correct the sendRawTransaction parameters to positional and note that allowHighFees and bypassLimits are parsed but not forwarded to Core; add the params member to the JSON-RPC request table. Add glossary entries. Apply the release annotation pass: mark getDocuments as updated in 4.2.0, demote the 4.0.0 annotations to italics, and point the previous-version link at 4.1.0. Co-Authored-By: Claude Opus 5 --- .../dapi-endpoints-core-grpc-endpoints.md | 8 + .../dapi-endpoints-json-rpc-endpoints.md | 19 +- .../dapi-endpoints-platform-endpoints.md | 104 ++++++++++- docs/reference/dapi-endpoints.md | 6 +- docs/reference/data-contracts.md | 142 +++++++++++++-- docs/reference/glossary.md | 38 +++- docs/reference/query-syntax.md | 168 ++++++++++++++++-- 7 files changed, 439 insertions(+), 46 deletions(-) diff --git a/docs/reference/dapi-endpoints-core-grpc-endpoints.md b/docs/reference/dapi-endpoints-core-grpc-endpoints.md index 40aa6461a..aef2c5697 100644 --- a/docs/reference/dapi-endpoints-core-grpc-endpoints.md +++ b/docs/reference/dapi-endpoints-core-grpc-endpoints.md @@ -164,6 +164,8 @@ grpcurl -proto protos/core/v0/core.proto \ | `hash` | String | No | Return the block matching the hex-encoded block hash provided | | `height` | Integer | No | Return the block matching the block height provided | +One of `hash` or `height` must be provided; the request carries them as a `oneof`, so supplying both is not possible on the wire. Omitting both, or sending a blank `hash`, returns `INVALID_ARGUMENT`. A `height` above the chain tip also returns `INVALID_ARGUMENT`, passing through Core's own message, while a correctly formatted but unknown `hash` returns `NOT_FOUND` ("Block not found"). + #### Example Request and Response ::::{tab-set} @@ -258,6 +260,8 @@ Note: The gRPCurl response `block` data is Base64 encoded **Returns**: Blockchain status information from the Core chain **Parameters**: None +The response `status` is one of `NOT_STARTED`, `SYNCING`, `READY`, or `ERROR`, derived from Core: `ERROR` when Core reports any warning, `READY` when verification progress reaches at least 0.9999, and `SYNCING` otherwise. `NOT_STARTED` is defined on the wire but is not currently emitted, and `status` falls back to `ERROR` if the Core query itself fails. `chain.is_synced` is simply `status == READY`. + #### Example Request and Response ::::{tab-set} @@ -390,6 +394,8 @@ Note: The gRPCurl response `bestBlockHash` and `chainWork` data is Base64 encode **Parameters**: None +The response `status` is one of `UNKNOWN`, `WAITING_FOR_PROTX`, `POSE_BANNED`, `REMOVED`, `OPERATOR_KEY_CHANGED`, `PROTX_IP_CHANGED`, `READY`, or `ERROR`. Note two caveats: `pose_penalty` returns `0` both when there is no penalty and when the lookup fails, and `sync_progress` here is quantized to `0`, `1/3`, `2/3`, or `1`, unlike the continuous [`getBlockchainStatus`](#getblockchainstatus) `sync_progress`. + #### Example Request and Response ::::{tab-set} @@ -478,6 +484,8 @@ Note: The gRPCurl response `proTxHash` data is Base64 encoded. | ---- | ------ | -------- | ----------------------- | | `id` | String | Yes | A transaction id (TXID) | +An empty or whitespace-only `id` returns `INVALID_ARGUMENT` ("id is not specified"). An unknown transaction returns `NOT_FOUND` ("Transaction not found"). + #### Example Request and Response ::::{tab-set} diff --git a/docs/reference/dapi-endpoints-json-rpc-endpoints.md b/docs/reference/dapi-endpoints-json-rpc-endpoints.md index f794b6290..e21df0906 100644 --- a/docs/reference/dapi-endpoints-json-rpc-endpoints.md +++ b/docs/reference/dapi-endpoints-json-rpc-endpoints.md @@ -17,6 +17,9 @@ All valid JSON-RPC requests require the inclusion the parameters listed in the f | `method` | String | Name of the endpoint | | `id` | Integer | Request id (returned in the response to differentiate results from the same endpoint) | | `jsonrpc` | String | JSON-RPC version ("2.0") | +| `params` | Object, array, or string | Endpoint arguments. Optional for endpoints that take none. | + +The shape `params` accepts varies by endpoint: [`getBlockHash`](#getblockhash) takes an object, while [`sendRawTransaction`](#sendrawtransaction) takes an array or a bare hex string. See each endpoint's parameters below. Additional information may be found in the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object). @@ -255,11 +258,17 @@ curl -k --request POST \ **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`) | +This method takes **positional** parameters. `params` must be either an array of the values below or a bare hex string carrying the raw transaction. An object such as `{"transaction": "..."}` is rejected with `-32602`. + +Positional parameters have no names on the wire; the names below are for reference only. + +| Position | Name | Type | Required | Description | +|-|-|-|-|-| +| 0 | `transaction` | String | Yes | The raw transaction, hex-encoded | +| 1 | `allowHighFees` | Boolean | No | Set to `true` to bypass the high-fee rejection check (default: `false`). Parsed but not forwarded to Core. | +| 2 | `bypassLimits` | Boolean | No | Set to `true` to bypass mempool rate limits (default: `false`). Parsed but not forwarded to Core. | + +The transaction is validated before broadcast: it must be non-empty, must not exceed the standard transaction weight limit as a raw byte count on the wire, and must not exceed that same weight limit once parsed. All three are reported as `-32602` over JSON-RPC; the [gRPC equivalent](../reference/dapi-endpoints-core-grpc-endpoints.md#broadcasttransaction) returns `RESOURCE_EXHAUSTED` for the wire-size check and `INVALID_ARGUMENT` for the other two. #### Example Request and Response diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md index d27c15d6a..f1b12757d 100644 --- a/docs/reference/dapi-endpoints-platform-endpoints.md +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -326,8 +326,8 @@ Retrieves the voters for a specific identity associated with a contested resourc | ---------------------- | -------- | -------- | --------------------------------------------------------------------------- | | `contract_id` | Bytes | Yes | The ID of the data contract associated with the contested resource | | `document_type_name` | String | Yes | The name of the document type associated with the contested resource | -| `index_name` | String | Yes | The name of the index used to query the contested resource | -| `index_values` | Array | Yes | The values used to query the contested resource | +| `index_name` | String | Yes | The name of the document type's contested index. A document type has at most one contested index; naming any other index is rejected with `InvalidArgument` | +| `index_values` | Array | Yes | The values used to query the contested resource. Must contain exactly one value per contested index property; supplying more returns `InvalidArgument`, and supplying fewer surfaces as an `InvalidParameter` error from Drive. | | `contestant_id` | Bytes | Yes | The ID of the identity for which to retrieve voters | | `start_at_identifier_info` | Object | No | Start identifier information for pagination | | `count` | Integer | No | Number of results to return. See [Result limits and pagination](#result-limits-and-pagination) | @@ -1064,6 +1064,10 @@ grpcurl -proto protos/platform/v0/platform.proto \ Adds a typed v1 request surface (`WhereClause` / `OrderClause` / `Select`) and four aggregate modes — `DOCUMENTS`, `COUNT`, `SUM`, `AVG`. The legacy v0 CBOR surface is still supported. ::: +:::{versionchanged} 4.2.0 +Protocol version 14 adds [ranked](#ranked-documents), [having-range](#having-range-documents), [chained](#chained-documents), and [composite](#composite-documents) query modes, plus the `IN_TIME_RANGE` where operator. `offset` is now consumed in ranked mode, and `having` is served in having-range mode. +::: + **Returns**: [Document](../explanations/platform-protocol-document.md) information for the requested document(s), or an aggregate count/sum/average over the matched document set. The request envelope is `oneof version { v0; v1; }`. Pick a version per call: @@ -1077,11 +1081,11 @@ The request envelope is `oneof version { v0; v1; }`. Pick a version per call: | ---- | ---- | -------- | ----------- | | `data_contract_id` | Bytes | Yes | A data contract `id`. | | `document_type` | String | Yes | A document type defined by the data contract. | -| `where_clauses` (v1) / `where` (v0) | Typed (v1) or CBOR bytes (v0) | No | Filter clauses. See [Query Syntax](../reference/query-syntax.md). | +| `where_clauses` (v1) / `where` (v0) | Typed (v1) or CBOR bytes (v0) | No | Filter clauses. A v1 clause carries `field`, `operator`, and exactly one operand: `IN_TIME_RANGE` clauses set `time_range` and leave `value` unset, every other operator sets `value` and leaves `time_range` unset. Either mismatch is rejected. See [Query Syntax](../reference/query-syntax.md) and [Time-range selection](../reference/query-syntax.md#time-range-selection). | | `order_by` | Typed (v1) or CBOR bytes (v0) | No | Sort order. See [Query Syntax](../reference/query-syntax.md). | | `prove` | Boolean | No | Return a proof instead of data. See [Platform proofs](../reference/platform-proofs.md). | -| `having` (v1) | Typed | No | Aggregate filters on grouped results. Present on the wire but currently rejected with `Unsupported`. See [Query Syntax](../reference/query-syntax.md). | -| `offset` (v1) | Integer | No | Row-based pagination offset. Present on the wire but currently rejected with `Unsupported`. Use `start_at` / `start_after` instead. See [Query Syntax](../reference/query-syntax.md). | +| `having` (v1) | Typed | No | Aggregate filters on grouped results. From protocol version 14, a single clause naming the selected aggregate alongside one `group_by` property is served as a [having-range query](../reference/query-syntax.md#having-range-queries). Other shapes, and every request on protocol version 13 or earlier, are rejected - usually with `Unsupported`, though a bad limit gives `InvalidLimit` and a missing `group_by` gives `InvalidParameter`. See [Query Syntax](../reference/query-syntax.md). | +| `offset` (v1) | Integer | No | Row-based pagination offset. Consumed only by [ranked queries](../reference/query-syntax.md#ranked-aggregate-queries), where it skips that many ranks before the returned page and the response reports the skip performed. Rejected with `Unsupported` on every other v1 route; use `start_at` / `start_after` instead. See [Query Syntax](../reference/query-syntax.md). | For v1, see also the [doctype-level aggregate flags](../protocol-ref/data-contract-document.md#aggregate-query-flags), which control whether a document type supports the `COUNT` / `SUM` / `AVG` modes below. @@ -1464,6 +1468,90 @@ grpcurl -proto protos/platform/v0/platform.proto \ Client computes `avg = 215 / 50 = 4.3`. +#### Ranked documents + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +Returns the top or bottom groups by their aggregate value. A request routes here when it carries an aggregate `selects` projection, exactly one `group_by` property, and exactly one `order_by` clause naming the selected aggregate - the reserved `$count` sentinel for `COUNT(*)`, otherwise the aggregated field. + +**Mode-specific request fields** + +| Name | Type | Required | Description | +| ---- | ---- | -------- | ----------- | +| `limit` | Integer | Yes | Number of groups to return, between 1 and 100. A larger value is rejected with `InvalidLimit` rather than clamped. | +| `offset` | Integer | No | Number of ranks to skip before the returned page. Counted rather than walked, so there is no ceiling. Combining a non-zero offset with a multi-element `in` prefix pin is rejected with `InvalidLimit`. | + +The covering index must declare the matching ranking axis (`rankedCountable`, `rankedSummable`, or `rankedAverageable`). Cursors are rejected, so `offset` is the only ranked pagination. See [Ranked aggregate queries](../reference/query-syntax.md#ranked-aggregate-queries). + +The response is carried in `result.data.ranked`, which reports the entries and the skip actually performed - potentially smaller than the requested offset when the groups run out. + +#### Having-range documents + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +Returns the groups whose aggregate value falls in a bounded range. A request routes here when it carries an aggregate projection, exactly one `group_by` property, and exactly one `having` clause naming the selected aggregate. + +The clause's operator must describe one contiguous range - `EQUAL`, `GREATER_THAN[_OR_EQUALS]`, `LESS_THAN[_OR_EQUALS]`, or a `BETWEEN` variant. `NOT_EQUAL` and `IN` are rejected, as is a multi-clause `having`. `limit` must be between 1 and 100 (`InvalidLimit` otherwise), a missing `group_by` is rejected with `InvalidParameter`, and neither `offset` nor cursors are supported. An `order_by` on the selected aggregate is accepted and flips the walk direction. See [Having-range queries](../reference/query-syntax.md#having-range-queries). + +The response is carried in `result.data.ranked`, with no skip reported. + +#### Chained documents + +:::{versionadded} 4.2.0 +No protocol-version gate of its own, but depends in practice on protocol version 14, which admits the `indexOnly` and `refersTo` keywords it requires. +::: + +Performs a provable semi-join. Presence of the `chained` message selects this mode: the request's own `document_type`, `where_clauses`, `order_by`, and `limit` describe the **inner** query, and the outer half is derived from the proven inner results rather than sent. + +**Mode-specific request fields** + +| Name | Type | Required | Description | +| ---- | ---- | -------- | ----------- | +| `chained.join_property` | String | Yes | The inner property whose proven values become the outer documents' `$id`s. | +| `chained.outer_document_type` | String | Yes | The joined document type - the `refersTo` target. | +| `limit` | Integer | Yes | Bounds the derived outer query, so there is no server-default fallback. A value outside 1 to 100 is rejected with `InvalidLimit` rather than clamped. | + +The inner document type must be `indexOnly` and resolve to an index carrying the join property; the outer type must not be `indexOnly`. The join property must declare a same-contract `refersTo: permanentDocument` targeting the outer document type, and `selects` must be empty or a single `DOCUMENTS` projection. `group_by`, `having`, time-range clauses, cursors, and `offset` are rejected; paginate with a range clause on the join property. See [Chained queries](../reference/query-syntax.md#chained-queries). + +The response is carried in `result.data.chained` as `inner_documents` and `outer_documents`. + +A node predating this field ignores it and serves the plain inner query, which fails closed on the client: an inner-only proof cannot satisfy the re-derived merged query. + +#### Composite documents + +:::{versionadded} 4.2.0 +::: + +Returns a page plus sub-queries derived from it, answered as one merged proof over a single state root. Presence of any `sub_queries` selects this mode: the request's own contract, document type, clauses, and `limit` describe the **page**, and each sub-query's `IN` clause is derived by the node from the page's - or an earlier sub-query's - proven documents. + +**Sub-query fields** + +| Name | Type | Required | Description | +| ---- | ---- | -------- | ----------- | +| `data_contract_id` | Bytes | No | The contract targeted. Empty means the page's own contract. | +| `document_type` | String | Yes | The document type queried. | +| `where_clauses` | Typed | No | The fixed clauses - everything but the derived `IN`, which must not be named here. | +| `order_by` | Typed | No | Ordering, documents only. Must agree with the page's direction. | +| `limit` | Integer | No | Required unless the lookup is already value-bounded. A unique index, an `indexOnly` terminal with every prefix fixed, a by-ID join, and a count must not carry one; every other lookup, siblings included, must. | +| `kind` | Enum | Yes | `DOCUMENTS` (the matching documents) or `COUNT` (one count per derived value). | +| `bind` | Typed | No | Where the derived values come from. Absent makes the sub-query a sibling: an independent query proven under the same root. | + +**Binding fields** + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `source` | Integer | `0` is the page; `n` is `sub_queries[n - 1]`, which must precede this one and be a `DOCUMENTS` sub-query. | +| `source_property` | String | The property read off each source document - `$id`, `$ownerId`, or an identifier-typed property. Dotted paths reach nested properties. | +| `field` | String | The sub-query field receiving the `IN` clause. `$id` makes this a by-ID join, requiring the source property to declare `refersTo: permanentDocument` targeting this document type. | + +The page's `limit` is required, and a value outside 1 to 100 is rejected with `InvalidLimit` rather than clamped. `group_by`, `having`, time-range clauses, cursors, and `offset` are rejected, `chained` and `sub_queries` are mutually exclusive, and a request may carry at most 10 sub-queries. See [Composite queries](../reference/query-syntax.md#composite-queries). + +The response is carried in `result.data.composite` as `page_documents` plus one `sub_results` entry per sub-query, in request order. + ### getDocumentHistory **Returns**: The revision history for a single document on a contract that keeps document history @@ -1474,9 +1562,9 @@ Client computes `avg = 215 / 50 = 4.3`. | `data_contract_id` | Bytes | Yes | A data contract `id` | | `document_type_name` | String | Yes | A document type defined by the data contract | | `document_id` | Bytes | Yes | The `id` of the document whose history is requested | -| `limit` | Integer | No | The maximum number of history entries to return | -| `offset` | Integer | No | The offset for pagination through the document history | -| `start_at_ms` | Integer | No | Only return results starting at this time in milliseconds | +| `limit` | Integer | No | Maximum number of history entries to return, between 1 and 10. Omitting the field uses the maximum (10); an explicit `0` or a value above 10 is rejected with `InvalidArgument`. | +| `offset` | Integer | No | Number of history entries to skip. Omitted and explicit `0` both start at the first entry. | +| `start_at_ms` | Integer | No | Only return results *after* this time in milliseconds; the bound is exclusive. | | `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested document history. The data requested will be encoded as part of the proof in the response.| **Example Request** diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md index 04790916d..a2923e3a5 100644 --- a/docs/reference/dapi-endpoints.md +++ b/docs/reference/dapi-endpoints.md @@ -34,8 +34,8 @@ without introducing issues for endpoint consumers. | [`getDataContract`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontract) | Returns the requested data contract | | [`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 | +| [`getDocuments`](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) | **Updated in Dash Platform v4.2.0**
Returns the requested document(s), or an aggregate count/sum/average over the matched document set. Includes ranked, having-range, chained, and composite query modes and the `IN_TIME_RANGE` operator. | +| [`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 @@ -181,7 +181,7 @@ Platform status. :::{note} The previous version of documentation can be [viewed -here](https://docs.dash.org/projects/platform/en/4.0.0/docs/reference/dapi-endpoints.html). +here](https://docs.dash.org/projects/platform/en/4.1.0/docs/reference/dapi-endpoints.html). ::: ```{toctree} diff --git a/docs/reference/data-contracts.md b/docs/reference/data-contracts.md index c82c78f3c..9197a74ed 100644 --- a/docs/reference/data-contracts.md +++ b/docs/reference/data-contracts.md @@ -111,6 +111,7 @@ Documents support the following configuration options to provide flexibility in | `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. | +| `indexOnly` | boolean | If true, documents are never written to primary storage - the index entries are the rows. Requires protocol version 14; see [indexOnly document types](#indexonly-document-types). Default: false. | | Security option | Type | Description | |-----------------|------|-------------| @@ -126,7 +127,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/v2/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#L48) and the [document meta-schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json). | Property Name | Type | Description | |---------------|------|-------------| @@ -177,22 +178,63 @@ The following example (from the [DPNS contract's `domain` document](https://gith } ``` +#### indexOnly document types + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +An `indexOnly` document type is never written to primary storage. Its index entries *are* the rows: each terminates in a value keyed by the index's [`terminal`](#indexonly-index-keywords) property rather than a reference keyed by a document ID. Only what the indices hold exists and is recoverable, which makes the type cheaper to store at the cost of being queryable only along its declared indices. + +Declaring `indexOnly: true` carries co-requirements: + +* Every property must be required and appear in at least one index. The single exception is the optional first property of a [`skipIfAbsent`](#indexonly-index-keywords) index. +* Every index must include `$ownerId`, either as one of its properties or as its `terminal`. +* `documentsMutable` must be false. +* Transfers, trading, history, and transient properties are not allowed. +* Document-type-level aggregate keywords are not allowed; use the [index-level flags](#aggregate-index-flags) instead. +* Indices cannot be `unique`, contested, or `nullSearchable: false`, and only the `$ownerId` and `$createdAt` system properties may be indexed. +* At least one index must be free of `$createdAt` and not `skipIfAbsent` - the index the executed-transition proof relies on. + +`indexOnly` types are the inner half of a [chained query](../reference/query-syntax.md#chained-queries). + ### Document Properties The `properties` object defines each field that a document will use. Each field consists of an object that, at a minimum, must define its data `type` (`string`, `number`, `integer`, `boolean`, `array`, `object`) and a [`position`](#assigning-property-position). Fields may also apply a variety of optional JSON Schema constraints related to the format, range, length, etc. of the data. A full explanation of JSON Schema capabilities is beyond the scope of this document. For more information regarding its data types and the constraints that can be applied, please refer to the [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference/index.html) documentation. +#### Platform-specific property keywords + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +Beyond the standard JSON Schema constraints, two Dash Platform keywords may be applied to a property. + +**`refersTo`** declares that an identifier-typed property points at another Platform object, so consensus can enforce that the target exists and stays consistent. It is an object whose required `type` names what is referenced - `identity`, `contract`, `token`, `permanentDocument`, or `identityPublicKey` - alongside these type-dependent members: + +| Member | Type | Applies to | Description | +|-|-|-|-| +| contractId | string or array | `permanentDocument` only | The contract the referenced document lives in, as a base58 string or 32-byte array. When absent, the reference targets the declaring contract. Forbidden on every other type. | +| documentType | string | `permanentDocument` (required) | The referenced document type. It must forbid deletion (`canBeDeleted: false`). Forbidden on every other type. | +| keyIdProperty | string | `identityPublicKey` (required) | The property of the same document type carrying the referenced key ID; the reference property's own value then carries the identity ID. Forbidden on every other type. | +| propertyAgreement | object | `permanentDocument` only | 1 to 10 `{referring property: referenced property}` pairs, each of which must hold as an equality between the two documents, enforced by consensus at write time. Both properties must exist and share a type, validated at contract registration. | + +A `permanentDocument` `refersTo` is what makes a property usable as the join property of a [chained query](../reference/query-syntax.md#chained-queries) or the by-ID binding of a [composite query](../reference/query-syntax.md#composite-queries). + +**`requiredSince`** is an integer naming the contract version from which the property is required, letting a later contract version add a required property without invalidating documents written under earlier versions. On a contract update, a newly required property must carry a `requiredSince` equal to the new contract version; an existing property cannot become required. + #### Property Constraints There are a variety of constraints currently defined for performance and security reasons. | Description | Value | | ----------- | ----- | -| 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) | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L23) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L24) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L21) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L21) | | Property name characters | Alphanumeric (`A-Z`, `a-z`, `0-9`)
Hyphen (`-`)
Underscore (`_`) | #### Assigning property `position` @@ -234,7 +276,7 @@ const contractDocuments = { Each document may have some fields that are required for the document to be valid and other optional fields. Required fields are defined via the `required` array, which contains a list of the field names that must be present in the document. The `required` object should only be included for documents with at least one required property. **Example** -The following example (excerpt from the DPNS contract's `domain` document) demonstrates a document that has 6 required fields: +The following example (excerpt from the DPNS contract's `domain` document) demonstrates a document that has defined required fields: ```json "required": [ @@ -280,6 +322,8 @@ 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 configures a masternode-voting contest over documents whose field values match a defined pattern (see [Contested indices](#contested-indices)). It is an object composed of `fieldMatches` (field and `regexPattern` conditions) and a `resolution` method. +* Optional aggregate flags that let the index answer `COUNT` / `SUM` / `AVG` queries without walking every document (see [Aggregate index flags](#aggregate-index-flags)). +* Optional ranked, time-range, and `indexOnly` keywords added at protocol version 14 (see [Ranked index flags](#ranked-index-flags) and [indexOnly index keywords](#indexonly-index-keywords)). :::{code-block} json :force: @@ -293,6 +337,19 @@ The `indices` array consists of one or more objects that each contain: ], "unique": true|false, "nullSearchable": true|false, + "countable": "countable"|"countableAllowingOffset", + "rangeCountable": true|false, + "summable": "", + "rangeSummable": true|false, + "averageable": "", + "rangeAverageable": true|false, + "rankedCountable": true|false|{ "at": "" }, + "rankedSummable": true|false, + "rankedAverageable": true|false, + "timeRange": { "on": "<$createdAt|$updatedAt|$transferredAt>", "range": , "step": , "phase": }, + "terminal": "$ownerId"|"", + "preallocated": true|false, + "skipIfAbsent": true|false, "contested": { "fieldMatches": [ { @@ -344,16 +401,68 @@ This example (from the [DPNS contract's `domain` document](https://github.com/da } ``` +#### Aggregate index flags + +An index can carry aggregate flags so the node answers `COUNT`, `SUM`, and `AVG` queries from the index itself rather than by walking every matching document. See [Aggregate Queries](../reference/query-syntax.md#aggregate-queries) for the query side. + +| Keyword | Type | Description | +|-|-|-| +| countable | string or boolean | Whether and how the index supports count fast paths - `notCountable`, `countable`, or `countableAllowingOffset`. Legacy booleans are accepted (`true` means `countable`). Adds storage cost for non-default values. | +| rangeCountable | boolean | Makes range-count queries on the indexed property O(log n). Requires `countable`. | +| summable | string | Names an integer document property whose values are aggregated into a sum at the index. The property must exist on the document type, be listed in `required`, and have a signed-or-unsigned integer type other than `u64` - values above `i64::MAX` cannot be represented in the sum tree. Every `summable` declaration on a document type must name the same property. | +| rangeSummable | boolean | Makes range-sum queries on the indexed property O(log n). Requires `summable`. | +| averageable | string | Shorthand for `countable: "countable"` plus `summable: ""`, enabling average queries. If both `averageable` and `summable` are set they must name the same property. | +| rangeAverageable | boolean | Shorthand for `rangeCountable: true` plus `rangeSummable: true`. Requires `averageable`. | + +#### Ranked index flags + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +Ranking axes let an index answer "top / bottom K groups by aggregate" queries with proofs. Each axis adds its own ordered secondary tree keyed by the group's aggregate, and each is opted into separately - none implies another. See [Ranked aggregate queries](../reference/query-syntax.md#ranked-aggregate-queries). + +| Keyword | Type | Description | +|-|-|-| +| rankedCountable | boolean or object | Adds the Count ranking axis. Requires `rangeCountable: true`. The level-addressed form, `{"at": ""}` or `{"at": ["", ...]}`, places rankings at the named properties' levels instead of the terminal one; it cannot combine with `rankedSummable` or `rankedAverageable` when a non-terminal level is named. | +| rankedSummable | boolean | Adds the Sum ranking axis. Requires `rangeSummable: true`. | +| rankedAverageable | boolean | Adds the Avg ranking axis. Requires `rangeAverageable: true`. | + +An index may also declare a `timeRange` transform, which buckets the first index property's timestamp into fixed-length, regularly spaced (possibly overlapping) windows: + +| Property | Type | Required | Description | +|-|-|-|-| +| on | string | Yes | The timestamp property to bucket. Must be the index's first property and name one of `$createdAt`, `$updatedAt`, or `$transferredAt`. | +| range | integer | Yes | Window length in seconds. Must be an exact multiple of `step`. | +| step | integer | Yes | Spacing between consecutive window starts, in seconds. When `range` is greater than `step` the windows overlap. | +| phase | integer | No | Offset of the grid's origin, in seconds. Must be less than `step` and less than one year. Defaults to 0. | + +The stored key is each window's start as a millisecond timestamp. Several indices may bucket the same timestamp with different grids; each grid gets its own subtree. At most 24 windows may overlap a single timestamp at protocol version 14. A time-range index may be unique only when `range` equals `step` and `on` is `$createdAt`, and it cannot be contested. A single-property time-range index cannot be ranked, because its only level is the bucketed one, and a time-range index cannot declare `preallocated`. Query these windows with the [`inTimeRange` operator](../reference/query-syntax.md#time-range-selection). + +#### indexOnly index keywords + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +These keywords apply only to [`indexOnly` document types](#document-configuration). + +| Keyword | Type | Description | +|-|-|-| +| terminal | string | Names the property supplying this index entry's member key, the analog of a document ID under the index's storage marker. Either `$ownerId` (the default) or an identifier property carrying a `refersTo` declaration targeting an identity, contract, token, or permanent document - `identityPublicKey` references are not admitted. Must not repeat one of the index's listed properties. | +| preallocated | boolean | When true, creating a referenced document also creates this index's dynamic trees for entries referencing it, paid by the referenced document's creator, so every entry insert costs the same as the first. Only valid when the index path is fully determined by a same-contract `permanentDocument` `refersTo` declaration. | +| skipIfAbsent | boolean | When true, a document omitting this index's first property writes no entry, so the index holds only documents carrying it. The first property is the skip trigger and must be a top-level property not listed in `required` - the only way an `indexOnly` property may be optional. An absent trigger is distinct from an empty value: absence skips the index, while any present value indexes normally. | + #### Index Constraints For performance and security reasons, indices have the following constraints. These constraints are subject to change over time. | Description | Value | | ----------- | ----- | -| 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) | +| Minimum / maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L489) / [32](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L490) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L730) | | 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/v2/document-meta.json#L378) | +| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L509) | | 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) | @@ -365,6 +474,7 @@ The following example (excerpt from the DPNS contract's `preorder` document) cre ```json "indices": [ { + "name": "saltedHash", "properties": [ { "saltedDomainHash": "asc" } ], @@ -375,7 +485,9 @@ The following example (excerpt from the DPNS contract's `preorder` document) cre ### Full Document Syntax -This example syntax shows the structure of a document object including all optional properties. +This example syntax shows the structure of a document object including the most commonly used optional properties. + +It is not exhaustive. The [aggregate index flags](#aggregate-index-flags), and the keywords added at protocol version 14 - [`indexOnly`](#indexonly-document-types), the [ranked and time-range index flags](#ranked-index-flags), the [`indexOnly` index keywords](#indexonly-index-keywords), and the [`refersTo` and `requiredSince`](#platform-specific-property-keywords) property keywords - are documented in their own sections above. For the authoritative set, see the [document meta-schema](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json). ::::{dropdown} Document schema :open: @@ -452,7 +564,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/v2/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/v3/document-meta.json)). ### Keyword @@ -460,8 +572,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/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)) | +| `pattern: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L292)) | +| `format: ` | `maxLength` must be defined (maximum: [50000](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json#L332)) | | `$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 | @@ -475,9 +587,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). -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. +A state transition is limited to a maximum size of [20 KiB](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.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`). +An individual document field value is limited to [5 KiB](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs) (`max_field_value_size`). ### Additional Properties diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 395c2036d..41ef48a2b 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -120,7 +120,7 @@ An epoch is a fixed time period used to organize and manage blockchain operation ## Era -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. +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. Document storage is prepaid for 50 eras. ## Evonode @@ -142,10 +142,18 @@ The record of successive revisions of an individual [document](#document), retai 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. +## Identity + +A Platform entity identified by a 32-byte identifier. An identity holds a set of public keys and a [credit](#credits) balance, and signs most [state transitions](#state-transition). Documents, tokens, and contracts are all created and updated on behalf of one. See [Identity](../explanations/identity.md). + +## Index-Only Document Type + +A [document](#document) type whose documents are never written to primary storage - its index entries are the rows. Only what the indices hold exists and is recoverable, which makes the type cheaper to store but queryable only along its declared indices. Introduced at protocol version 14. See [indexOnly document types](../reference/data-contracts.md#indexonly-document-types). + ## Layer (1, 2, 3) - Layer 1: Core blockchain and [Dash Core](#dash-core) -- Layer2: Drive and DAPI +- Layer 2: Drive and DAPI - Layer 3: DAPI clients ## Local network @@ -158,19 +166,23 @@ Deterministic subset of the global deterministic masternode list used to perform ## Mainnet -The original and main network for Dash transactions, where transaction have real economic value. +The original and main network for Dash transactions, where transactions have real economic value. ## Masternode 2nd-tier collateralized Node in the Dash P2P network, performing additional functions and forming a provision layer +## Platform Address + +An account in Platform's address system, holding a credit balance that is not tied to an [identity](#identity). Address-system [state transitions](#state-transition) carry no owner identity. See [Address system](../protocol-ref/address-system.md). + ## Platform Chain Layer 2 blockchain that propagates platform data among masternodes, propagates platform blocks among masternodes, applies Layer 2 consensus, authoritatively orders state transitions, and controls platform state consistency ## Platform 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 +All Platform data including contracts, documents (user data), [tokens](#token), groups, credit balance, [identity](#identity) (username), [address](#platform-address) balances, [shielded pool](#shielded-pool) state, and masternode voting/contested resource state. Platform state also includes protocol bookkeeping such as fee and epoch pools, pre-funded specialized balances, spent asset lock transactions, saved block transactions, withdrawal transactions, and proposer-desired protocol versions. ## practical Byzantine Fault Tolerance (pBFT) @@ -186,16 +198,24 @@ Ability to trustlessly prove that a node completed a certain amount of work duri ## Quorum -Group of masternodes signing some action, formation of the group determined by via some determination algorithm +Group of masternodes signing some action, formation of the group determined by some determination algorithm ## Quorum Signature BLS signature resulting from some agreement within a masternode quorum +## Ranked Index + +An [index](../reference/data-contracts.md#document-indices) carrying a ranking axis, letting Platform answer "top or bottom K groups by aggregate value" queries with proofs. Each axis - count, sum, or average - adds its own ordered secondary tree and is opted into separately. Introduced at protocol version 14. See [Ranked index flags](../reference/data-contracts.md#ranked-index-flags) and [Ranked aggregate queries](../reference/query-syntax.md#ranked-aggregate-queries). + ## Regtest A local regression testing environment in which developers can almost instantly generate blocks on demand for testing events, and can create private Dash with no real-world value. See the Testing Applications page for a more detailed description of network types. +## Shielded Pool + +Platform's privacy pool, holding value whose ownership and amounts are hidden from public state. Shielded-pool [state transitions](#state-transition) carry no owner identity. See [Shielded pool](../explanations/shielded-pool.md). + ## Simple Payment Verification A method for verifying if transactions are part of a block without downloading the whole block. This is useful for lightweight clients which don't run continuously and which don't have the storage space or bandwidth for a full copy of the blockchain. @@ -222,6 +242,14 @@ A global testing environment in which developers can obtain and spend Dash that See: [Intro to Testnet](../intro/testnet.md) for more information +## Time-Range Index + +An [index](../reference/data-contracts.md#document-indices) that buckets a timestamp property into fixed-length, regularly spaced windows, enabling trending and leaderboard queries scoped to a time window. Introduced at protocol version 14. See [Ranked index flags](../reference/data-contracts.md#ranked-index-flags) and [Time-range selection](../reference/query-syntax.md#time-range-selection). + +## Token + +A fungible asset defined by a [data contract](#data-contract) and tracked in [platform state](#platform-state). A contract may define multiple tokens, each with its own supply rules, distribution schedule, and authorization - which may be delegated to a [group](#group-data-contract). See [Tokens](../explanations/tokens.md). + ## Validator Set The group of masternodes responsible for the layer 2 blockchain (platform chain) consensus at a given time. They vote on the content of each platform chain block and are analogous to miners on the layer 1's core blockchain diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index 0fb18ffab..0255af6c6 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -68,7 +68,7 @@ Valid fields consist of the indices defined for the document being queried. For **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 +- A single `in` clause is only allowed for the last two indexed properties. This applies to ordinary document queries and grouped aggregates; [ranked](#ranked-aggregate-queries) and [having-range](#having-range-queries) queries instead pin each leading index property with one clause, at most one of which may be an `in` of 2 to 10 elements - 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 @@ -78,6 +78,27 @@ Valid fields consist of the indices defined for the document being queried. For | Name | Description | | :-: | - | | startsWith | Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement. | +| inTimeRange | Selects documents falling in one window of a `timeRange` index grid. See [Time-range selection](#time-range-selection). Available on the v1 query surface only. | + +#### Time-range selection + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +The `inTimeRange` operator selects one window of a time grid rather than comparing against a value. The clause's field must name a timestamp covered by a [`timeRange` index](../reference/data-contracts.md#document-indices), and the operand is a typed selection rather than an ordinary value: + +| Selector | Selects | +| - | - | +| `NEWEST` | The freshest started window - the largest grid start at or before block time, so the latest partial slice of history. | +| `OLDEST` | The oldest window still active at block time, a near-full trailing window. Best for "trending over the last window" reads. | +| `BY_START` | A named window, current or historic, identified by its start timestamp. | + +The relative selectors (`NEWEST` and `OLDEST`) are resolved server-side from the current block time, and a proof verifier re-derives the same window from the quorum-signed response metadata time, so neither side has to trust the other's clock. They must not carry a start timestamp. + +`BY_START` requires a start timestamp in milliseconds, and it must lie on the grid (`start_ms == phase + k * step`). An unaligned start is rejected rather than snapped to the nearest window. A window holding no documents - including one that has not started yet - is a provable empty answer, not an error. + +A query may carry at most one `inTimeRange` clause. When more than one `timeRange` grid buckets the field, the clause must also name the grid (its `range`, `step`, and `phase`, in the contract's own seconds); a bare selector is ambiguous there and rejected. Naming the grid is optional when exactly one grid covers the field. ### Operator aliases @@ -172,10 +193,10 @@ 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 `>`, `<`, `>=`, `<=`, `in`, `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). Required for `>`, `<`, `>=`, `<=`, `in`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. Can also be used with equality-only queries to sort by a trailing field of the matched index. | `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 | +| `offset` | On the v1 `getDocuments` wire, consumed only in [ranked aggregate mode](#ranked-aggregate-queries), where it skips that many ranks before the returned page and the response reports the skip performed; every other v1 path rejects it with `Unsupported`, so use `startAt` or `startAfter` for pagination there. | `offset: 20` | ### Ordering compound indexes @@ -199,6 +220,10 @@ Ascending queries that combined a cursor with a `<` or `<=` clause previously [b :::{versionadded} 4.0.0 ::: +:::{versionchanged} 4.2.0 +Protocol version 14 adds [ranked](#ranked-aggregate-queries) and [having-range](#having-range-queries) query modes, and relaxes the blanket rejection of `HAVING` and `OFFSET` accordingly. +::: + 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,11 +233,11 @@ The [getDocuments](../reference/dapi-endpoints-platform-endpoints.md#getdocument | `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. +`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. Each `groupBy` field must be constrained by the query's where clause: a single field must carry an `in` or range clause (`startsWith` counts as a range here), and two fields must be an (`in` field, range field) pair. Any other `groupBy` shape is currently rejected with `Unsupported`. -Aggregate queries impose extra schema requirements on the document type — `COUNT` needs `documentsCountable`, `SUM` needs `documentsSummable`, `AVG` needs `documentsAverageable` (or both base flags). Range-grouped aggregates additionally need the `range*` variants. See the [doctype-level aggregate flags](../protocol-ref/data-contract-document.md#aggregate-query-flags) for the schema annotations and the [`getDocuments` reference](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) for the full `select` × `groupBy` shape table. +Aggregate queries impose extra schema requirements. For unfiltered doctype-wide aggregates, the document type must set the doctype-level flags — `COUNT` needs `documentsCountable`, `SUM` needs `documentsSummable`, `AVG` needs `documentsAverageable` (or both base flags). An aggregate with a `where` clause or `groupBy` instead requires an index covering the queried fields that carries the corresponding index-level flags (`countable`, `summable`, `averageable`). Range-grouped aggregates additionally need the `range*` variants, and [ranked](#ranked-aggregate-queries) and [having-range](#having-range-queries) queries need the matching ranked axis (`rankedCountable`, `rankedSummable`, or `rankedAverageable`), each of which costs its own secondary tree and is opted into separately. See the [aggregate query flags](../protocol-ref/data-contract-document.md#aggregate-query-flags) for the schema annotations and the [`getDocuments` reference](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) for the full `select` × `groupBy` shape table. -`SUM` / `AVG` integer values are returned as JS strings so JavaScript clients don't lose precision on values larger than `Number.MAX_SAFE_INTEGER`. +On the raw gRPC layer, `SUM` / `AVG` integer values are delivered to JavaScript clients as strings so they don't lose precision on values larger than `Number.MAX_SAFE_INTEGER`. ### Aggregate query limits @@ -220,7 +245,7 @@ The `limit` modifier behaves differently in aggregate result modes than it does - Omit `limit` to request the server's default. - Send a positive value to request an explicit cap. -- 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). +- An explicit `limit: 0` is rejected with `InvalidLimit` in every `select` mode, including `DOCUMENTS`. On this wire `0` is never a "use the default" sentinel; that behavior applies to SDK query objects and the v0 `getDocuments` wire, where the limit field has no unset state and `0` means omitted (see [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. @@ -246,10 +271,133 @@ On range-grouped aggregates, an oversized `limit` is handled differently dependi 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. +### Ranked aggregate queries + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +A ranked query returns the top or bottom groups by their aggregate value - a provable "leaderboard" read - instead of every matching group. A request routes to the ranked executor when it combines an aggregate `select` with exactly one `groupBy` property and exactly one `orderBy` clause naming the selected aggregate: + +| `select` | `orderBy` names | +| - | - | +| `COUNT(*)` | The reserved `$count` sentinel. | +| `SUM()` | ``, the summed property. | +| `AVG()` | ``, the averaged property. | + +The `orderBy` clause must use the field spelling shown above; naming the aggregate function itself is rejected. + +`desc` walks the axis from the largest aggregate down (the "top n" reading); `asc` walks from the smallest up (the "bottom n" reading). Groups holding equal aggregate values are returned in group-key order in the direction of the walk. + +`limit` is required and must be between 1 and [100](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-drive/src/query/drive_document_ranked_query/mod.rs#L136). This is a hard ceiling rather than a clamp: a larger limit is rejected with `InvalidLimit`, because the limit is part of the traversal a client re-executes when verifying the proof. + +`offset` skips that many ranks before the returned page, so `limit: 1, offset: 4` returns the fifth-ranked group. The skip is counted from subtree aggregates rather than walked, so there is deliberately no ceiling on it. The response reports the skip actually performed, which can be smaller than the requested offset when the groups run out. Cursors (`startAt` / `startAfter`) are rejected in ranked mode, which makes `offset` the only way to page a ranked result. + +Where clauses are optional. When present, each pins one leading property of a covering compound ranked index with an equality, except that at most one may be an `in` clause of 2 to 10 distinct elements (a single-element `in` normalizes to an equality pin). A multi-element `in` fans the read out into one branch per element, and combining it with a non-zero `offset` is rejected with `InvalidLimit`, because the counted rank-skip is attested per-branch and cannot span the union. + +The covering index must declare the matching ranking axis - `rankedCountable` for `COUNT(*)`, `rankedSummable` for `SUM`, `rankedAverageable` for `AVG`. Each axis is opted into separately and costs its own secondary tree; none implies another. See [Document Indices](../reference/data-contracts.md#document-indices) for the schema keywords. + +### Having-range queries + +:::{versionadded} 4.2.0 +Requires protocol version 14. +::: + +A having-range query filters grouped aggregates by their aggregate value, returning the groups whose aggregate falls in a bounded range. A request routes to the having-range executor when it combines an aggregate `select` with exactly one `groupBy` property and exactly one `having` clause whose aggregate is the selected aggregate. + +The operator must describe one contiguous range - `==`, `>`, `>=`, `<`, `<=`, `Between`, or a `BetweenExclude*` variant. `!=` and `in` are rejected, because neither describes a contiguous range of the axis. Multi-clause `having` is also rejected. + +As with ranked queries, `limit` must be between 1 and [100](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-drive/src/query/drive_document_having_query/mod.rs#L119), and the same ranking-axis index flags apply. + +Having-range queries support neither `offset` nor cursors. To continue past a page cut short by the limit, tighten the `having` bound past the last aggregate value seen. This cannot cross a tie: several groups sharing the boundary aggregate value must fit inside one limit. + +An `orderBy` on the selected aggregate is accepted and flips the walk direction. + +On protocol version 13 and earlier, and for every other `having` shape at v14, `having` is rejected with `Unsupported`. A shape that routes here but carries a bad limit is rejected with `InvalidLimit`, and one with no `groupBy` with `InvalidParameter`. + ### Other aggregate restrictions -- `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. +- `startAt` and `startAfter` are supported only with `DOCUMENTS`; every aggregate result mode rejects cursors. How to page instead depends on the mode: + - Grouped `COUNT` / `SUM` / `AVG` - narrow the `where` range to query a different group range. + - [Ranked](#ranked-aggregate-queries) - use `offset`, which is counted rather than walked and so stays cheap at any depth. + - [Having-range](#having-range-queries) - neither cursors nor `offset` are available. Tighten the `having` bound past the last aggregate value seen. A page cut inside a tie cannot be continued, so size `limit` above the widest expected tie. +- `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. +- On the v1 wire, `OFFSET` is evaluated only in [ranked aggregate mode](#ranked-aggregate-queries). On the grouped `COUNT` / `SUM` / `AVG` paths, on having-range queries, and when returning `DOCUMENTS`, it still returns `Unsupported`. +- `HAVING` is evaluated only in [having-range mode](#having-range-queries). Every other `HAVING` shape returns `Unsupported`. + +## Chained queries + +:::{versionadded} 4.2.0 +Chained queries have no protocol-version gate of their own, but depend in practice on protocol version 14, which is what admits the `indexOnly` and `refersTo` keywords they require. +::: + +A chained query is a provable semi-join: it returns the documents of one type whose IDs appear as a property value on the documents of another type. Conceptually: + +```text +SELECT * FROM WHERE $id IN (SELECT FROM WHERE ...) +``` + +The request's own document type, where clauses, `orderBy`, and `limit` describe the **inner** query. The outer half is derived from the inner results rather than sent, and a proof verifier re-derives it from the proven inner values - so the join cannot be steered by the node that answers it. The chained request names only the join property and the outer document type. + +Chained mode has strict prerequisites: + +- The inner document type must be [`indexOnly`](../reference/data-contracts.md#document-configuration), and must resolve to an index carrying the join property. +- The join property must declare a same-contract `refersTo: permanentDocument` targeting the outer document type. +- `limit` is required - it bounds the derived outer query, so there is no server-default fallback. A value outside 1 to 100 (the configured `max_query_limit`, 100 by default) is rejected with `InvalidLimit` rather than clamped. +- The outer document type must **not** be `indexOnly`, and `selects` must be empty or a single `DOCUMENTS` projection. +- `groupBy`, `having`, time-range clauses, cursors, and `offset` are all rejected. Paginate with a range clause on the join property. + +The response carries both halves: the inner documents in query order, and the outer documents ordered by the first appearance of their ID among the inner results, deduplicated. + +A node predating this feature ignores the chained field and serves the plain inner query. That fails closed on the client: an inner-only proof cannot satisfy the re-derived merged query. + +## Composite queries + +:::{versionadded} 4.2.0 +::: + +A composite query returns a page of documents plus one or more sub-queries derived from that page, answered as a single merged proof over one state root. This replaces a round-trip-per-lookup pattern - fetch a page, then fetch each referenced profile - with one provable request. Conceptually: + +```text +-- Page +SELECT * FROM WHERE ... ORDER BY ... LIMIT + +-- Sub-query bound to the page: the IN values are read off the proven page documents +SELECT * FROM WHERE IN (SELECT FROM ) + +-- Sub-query bound to an earlier sub-query +SELECT * FROM WHERE IN (SELECT FROM ) + +-- Sibling sub-query: unbound, proven under the same state root +SELECT * FROM WHERE ... LIMIT +``` + +For example, a page of `post` documents, a by-ID join fetching each author's `profile` (`$id IN` the posts' `authorId` values), and a `COUNT` sub-query tallying `like` documents per post (`postId IN` the posts' `$id` values) are answered together as one proof. + +The request's own contract, document type, where clauses, `orderBy`, and `limit` describe the **page**. Each sub-query carries its own fixed clauses, and its `IN` clause is derived by the node from the proven documents of the page or of an earlier sub-query. As with chained queries, the verifier re-derives every sub-query from the proven page and re-checks the whole composition. + +Each sub-query names a document type and optionally a different contract (empty means the page's own), plus a kind: + +| Kind | Returns | +| - | - | +| `DOCUMENTS` | The matching documents. | +| `COUNT` | One count per derived value, read from the `countable` index covering the fixed clauses plus the bound field. A value with no entry counts zero. | + +A sub-query may declare a binding describing where its derived `IN` values come from: + +| Binding field | Meaning | +| - | - | +| `source` | Whose proven documents supply the values: `0` is the page, `n` is the preceding sub-query `n - 1`, which must be a `DOCUMENTS` sub-query. | +| `source_property` | The property read off each source document - `$id`, `$ownerId`, or an identifier-typed property. Dotted paths reach nested properties, and documents lacking the property contribute nothing. | +| `field` | The sub-query field receiving the derived `IN` clause. | + +Setting `field` to `$id` makes the sub-query a by-ID join, which requires the source property to declare `refersTo: permanentDocument` targeting the sub-query's document type - every derived ID must resolve, and a missing document invalidates the proof. Any other field is a lookup, where absence is itself a proven fact. A sub-query with no binding is a sibling: an independent query proven under the same state root. + +Composite mode has the same gates as chained mode: the page's `limit` is required, and a value outside 1 to 100 is rejected with `InvalidLimit` rather than clamped. A page addressed by IDs is proven without its limit, so that limit must be at least as large as the number of IDs it addresses. `groupBy`, `having`, time-range clauses, cursors, and `offset` are rejected, and chained and composite modes are mutually exclusive. A request may carry at most 10 sub-queries. + +Whether a sub-query takes its own `limit` depends on whether its lookup is already bounded by its values. A value-bounded lookup - a unique index, or an `indexOnly` terminal with every prefix fixed - must not carry one, and neither must a by-ID join or a count. Every other lookup, siblings included, requires one. + +The response carries the page exactly as the page query alone would return it, followed by one result per sub-query in request order. ## Example query @@ -331,6 +479,6 @@ for (const [key, count] of counts) { } ``` -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`. +The query's index must support the aggregate: this example needs a `[resourceId, rating]` index carrying the index-level `countable` and `rangeCountable` flags. An ungrouped `count()` returns a single-entry map keyed by the empty string, so read it with `counts.values().next().value`. ::: :::: From 31405c0c610e65e27e6554c033b185564ec807f5 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 10 Sep 2026 13:03:53 -0400 Subject: [PATCH 2/8] docs(explanations): update for Dash Platform 4.2 and correct stale behavior Add a Minimum and Fixed Fees section to fees.md covering the minimum-balance pre-check and the fixed fee schedule for shielded pool transitions. Clarify NFT deletion rules, including the legacy correction for history-keeping document types and the restriction on consensus-validated references to deletable NFTs. Simplify the Batch payload row in the state transition table and move the action list to a new Batch transitions subsection. Document the DashPay v2 profile payment address fields, DAPI gateway TLS termination and gRPC-Web support, DPNS testnet voting windows and tie resolution, validator set rotation targets, and asset-lock surplus handling for shield transitions. Correct the Drive block finalization description, the Tenderdash maintenance note, the two-thirds validator threshold wording, and add token localization, decimal, and group threshold constraints. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanations/dapi.md | 4 +-- docs/explanations/dashpay.md | 33 +++++++++++++++---- docs/explanations/dpns.md | 6 ++-- docs/explanations/drive-platform-chain.md | 2 +- docs/explanations/drive.md | 2 +- docs/explanations/fees.md | 6 ++++ docs/explanations/nft.md | 8 +++-- docs/explanations/platform-consensus.md | 6 ++-- .../platform-protocol-state-transition.md | 9 ++++- docs/explanations/shielded-pool.md | 4 +-- docs/explanations/tokens.md | 5 ++- 11 files changed, 64 insertions(+), 21 deletions(-) diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md index 5e51ad78e..0b57dfe32 100644 --- a/docs/explanations/dapi.md +++ b/docs/explanations/dapi.md @@ -22,7 +22,7 @@ To overcome these obstacles, the Dash decentralized API (DAPI) uses Dash's robus ## Security -DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data. +DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. TLS is terminated by a gateway that runs in front of the DAPI service on each masternode; the gateway also applies rate limiting. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data. :::{note} See the [Query Capabilities page](./query.md) for more detailed information regarding Platform data @@ -34,7 +34,7 @@ retrieval. DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). - JSON-RPC endpoints are a small surface that mostly exposes layer 1 information, with the exception of a Platform status method -- gRPC endpoints cover both Core and Platform: +- gRPC endpoints cover both Core and Platform. They are also served over gRPC-Web on the same port, so browser clients can call masternodes without a separate proxy (subject to the node presenting a browser-trusted TLS certificate): - Core endpoints are mostly request/response, plus streaming subscriptions for block headers, transactions, and masternode-list updates - Platform endpoints are request/response only. diff --git a/docs/explanations/dashpay.md b/docs/explanations/dashpay.md index 424b450c5..fcfb98c70 100644 --- a/docs/explanations/dashpay.md +++ b/docs/explanations/dashpay.md @@ -38,10 +38,14 @@ The DashPay contract enables an improved Dash wallet experience with features in ## Details The contract defines three document types: `contactRequest`, `profile` and `contactInfo`. -ContactRequest documents are the most important. They are used to establish relationships and -payment channels between Dash identities. Profile documents are used to store public facing -information about Dash identities including avatars and display names. ContactInfo documents can be -used to store private information about other Dash identities. + +* ContactRequest documents are the most important. They are used to establish relationships and +payment channels between Dash identities. +* Profile documents are used to store public facing information about Dash identities including +avatars and display names. Since Dash Platform v4.2, a profile can also publish optional public +payment addresses (a Core chain address and/or a Platform address). Unlike contact-based payments, +payments to these addresses are publicly linkable to the profile. +* ContactInfo documents can be used to store private information about other Dash identities. ### Establishing a Contact @@ -75,10 +79,11 @@ used to store private information about other Dash identities. ### Implementation DashPay has many constraints as defined in the [DashPay data -contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v1/dashpay.schema.json). +contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v2/dashpay.schema.json). Additionally, the DashPay data triggers defined in [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay) -enforce additional validation rules related to the `contactRequest` document. Note: as a system data +enforce additional validation rules related to the `contactRequest` document and, since Dash Platform +v4.2, the payment address fields of the `profile` document. Note: as a system data contract, the version active on a network is determined by that network's active protocol version. :::{tip} @@ -156,6 +161,22 @@ information and complete details about the data contract. "minLength": 1, "maxLength": 25, "position": 4 + }, + "corePaymentAddress": { + "type": "array", + "byteArray": true, + "minItems": 21, + "maxItems": 21, + "description": "Core chain address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger; clients render the address as Base58Check for the network they are on. Payments to it are publicly linkable to this profile.", + "position": 5 + }, + "platformPaymentAddress": { + "type": "array", + "byteArray": true, + "minItems": 21, + "maxItems": 21, + "description": "Platform address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger.", + "position": 6 } }, "minProperties": 1, diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index 16e782bf4..696824101 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -29,7 +29,7 @@ To prevent [front-running](https://en.wikipedia.org/wiki/Domain_name_front_runni #### Domain pre-order -In the pre-order phase, the domain name is salted to obscure the actual domain name being registered (e.g. `hash('alice.dash' + salt)`) and submitted to platform. This is done to prevent masternodes from seeing the names being registered and "stealing" them for later resale. Once the pre-order receives a sufficient number of confirmations, the registration can proceed. +In the pre-order phase, the domain name is salted to obscure the actual domain name being registered (e.g. `hash('alice.dash' + salt)`) and submitted to platform. This is done to prevent masternodes from seeing the names being registered and "stealing" them for later resale. Once the pre-order document has been accepted by Platform, the registration can proceed. #### Domain registration @@ -50,7 +50,7 @@ All other available names can be registered immediately. #### Timeline -A two-week voting window begins when a name matching the criteria above is requested. Additional identities can request the same name during the first week of the voting window. +On mainnet, a two-week voting window begins when a name matching the criteria above is requested. Additional identities can request the same name during the first week of the voting window. Test networks use much shorter windows (currently 90 minutes, with a 45-minute join period). Both durations are versioned protocol parameters. #### Voting details @@ -64,7 +64,7 @@ As with governance voting, evonode votes are worth four, and regular masternode After voting ends, the name is either awarded to one of the identities or locked. The outcome is based on which item receives the most votes. -Assuming masternodes do not vote to lock, the identity receiving the most votes takes ownership of the name. However, if the vote locks the name, no identity receives it. If only one identity requests the name, they will receive it even if no masternodes vote. +Assuming masternodes do not vote to lock, the identity receiving the most votes takes ownership of the name. However, if the vote locks the name, no identity receives it. If only one identity requests the name, they will receive it even if no masternodes vote. If lock votes tie with the leading identity, the identity wins; ties between identities are resolved deterministically by the protocol. :::{note} Locked names cannot currently be re-requested or awarded. This policy may be revisited in future Platform releases. diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md index b34be1941..0725c32f2 100644 --- a/docs/explanations/drive-platform-chain.md +++ b/docs/explanations/drive-platform-chain.md @@ -26,4 +26,4 @@ In order to support Dash Platform's performance requirements, the platform chain ### Blocks and Transitions -Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among all masternodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by a ⅔ + 1 majority of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations. +Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among all masternodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by more than two-thirds of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations. diff --git a/docs/explanations/drive.md b/docs/explanations/drive.md index 5edc1acd3..05d58ab3c 100644 --- a/docs/explanations/drive.md +++ b/docs/explanations/drive.md @@ -27,7 +27,7 @@ The process of adding or updating data in Drive consists of several steps to ens 1. [State transitions](../explanations/platform-protocol-state-transition.md) are submitted to the platform via [DAPI](../explanations/dapi.md) 2. DAPI relays state transitions to the platform chain's consensus engine (Tenderdash), which asks the platform state machine to validate them and speculatively execute them when building or verifying a block proposal 3. The block is propagated and voted on by validators -4. Once the block is committed, each node finalizes it — persisting the speculative state changes to Drive, or executing the block if it was received via sync +4. Once the block is committed, each node finalizes it, persisting to Drive the state changes it computed while processing the proposal. Nodes catching up on the chain execute each block the same way before finalizing it ```{eval-rst} .. figure:: ../../img/drive.svg diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index 19b066325..f1bb2a6d4 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -60,6 +60,12 @@ In an attempt to minimize Dash Platform's storage requirements, users are incent Distribution is front-loaded rather than spread evenly across those 50 years, so the refundable remainder falls fastest in the early years. Removals below a small minimum byte threshold are not refunded at all. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the distribution schedule and the refund threshold. +## Minimum and Fixed Fees + +In addition to the usage-based costs above, most identity- and address-funded transitions require a protocol-defined minimum balance before processing. This is a balance floor rather than a flat charge; the fee actually deducted is still the storage and processing total. + +[Shielded pool](../explanations/shielded-pool.md) transitions that pay from the pool (shielded transfers, unshields, and shielded withdrawals) are the exception. Their costs cannot be charged to an address balance, so they pay a fixed schedule from the pool: a proof verification fee, a per-action fee, and a per-action storage allowance. Transitions that shield funds are charged for storage normally and add only the proof verification and per-action components. These constants are versioned protocol parameters and were rebalanced at protocol version 14. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the current values. + ## User Fee Increase Platform supports a user fee increase that can be used to incentivize inclusion of a state diff --git a/docs/explanations/nft.md b/docs/explanations/nft.md index b2748b545..1dc7b3a9a 100644 --- a/docs/explanations/nft.md +++ b/docs/explanations/nft.md @@ -59,7 +59,11 @@ NFTs can be immutable or mutable, depending on their intended use. Immutable NFT ### Delete -Since some NFTs may represent transient or consumable things, Dash Platform allows NFTs to be deleted. This is more efficient than the "burn" mechanism many projects use to make an NFT unusable and provides flexibility in managing assets that may no longer be needed or valid. Whether deletion is permitted is fixed when the document type is defined in the data contract. +Since some NFTs may represent transient or consumable things, Dash Platform allows NFTs to be deleted. This is more efficient than the "burn" mechanism many projects use to make an NFT unusable and provides flexibility in managing assets that may no longer be needed or valid. + +Whether deletion is permitted is set when the document type is defined in the data contract and cannot be changed afterward. Document types that keep revision history cannot allow deletion. The one exception is a legacy correction: a contract registered before this rule was enforced may update a history-keeping document type to turn deletion off, since it was never actually possible for that type. + +Deletable NFTs cannot be the target of consensus-validated references from other documents. See [property references](../reference/data-contracts.md#platform-specific-property-keywords). ```{eval-rst} .. _explanations-nft-create: @@ -73,7 +77,7 @@ Creating an NFT on Dash Platform consists of creating a data contract, registeri Structurally, there is no difference between an NFT contract and a non-NFT contract. While an NFT contract may set options that other contracts are unlikely to use, there is no other difference. -NFT contracts will often set document creation restrictions and enable document transfers. Default options for modifying, deleting, and transferring documents can be specified at the contract level and overridden as needed for specific document types. +NFT contracts will often set document creation restrictions and enable document transfers. Default options for modifying and deleting documents can be specified at the contract level and overridden as needed for specific document types. Transfer and trade options are enabled per document type and are off by default. Once the data contract design is completed, the contract can be registered on the network in preparation for NFT document creation. See the [contract registration tutorial](../tutorials/contracts-and-documents/register-a-data-contract.md) for example code. diff --git a/docs/explanations/platform-consensus.md b/docs/explanations/platform-consensus.md index d37b951fb..a77e62725 100644 --- a/docs/explanations/platform-consensus.md +++ b/docs/explanations/platform-consensus.md @@ -68,7 +68,9 @@ Rather than having a static validator set, Tenderdash periodically changes to a The validator set is assigned to a currently active masternode quorum. Rotation to a new quorum happens when the current quorum completes a proposer cycle (proposer duty reaches the last member), when the current quorum is no longer in the active set, or when the proposer sequence wraps within the current quorum while more than one quorum is active. The last trigger exists so that quorums rotating out do not give a small advantage to proposers that sort earlier in the sequence. -There are many advantages to adopting this dynamic rotation approach: +When a rotation is triggered, the validator set moves to the next quorum in the ordered list of active quorums (wrapping around, and on large networks skipping the oldest quorums so a set about to expire is not chosen). If only one quorum is active, no rotation occurs. + +Advantages to this dynamic rotation approach include: - The validator set is less predictable, which reduces the window for attacks like DoS. - The process balances the performance and security of platform chains like InstantSend and ChainLock quorum changes on the core chain. @@ -82,4 +84,4 @@ Here are the differences between Tenderdash and Tendermint: - **Execution Timing**: Tenderdash facilitates same-block execution, optimizing transaction processing, whereas Tendermint traditionally relies on next-block execution. - **Consensus Module Refactoring**: Tenderdash has undergone a complete overhaul of its vote-extensions and consensus module, working diligently to eliminate deadlocks and increase stability. - **Dynamic Validator Management**: Tenderdash incorporates logic to actively connect with new validators in a set and disconnect those that are no longer in the validator set, thereby ensuring an adaptable and efficient network. -- **Maintenance**: Tenderdash is maintained as part of the Dash Platform release process, so consensus-layer changes ship alongside the Platform releases that depend on them. +- **Maintenance**: Tenderdash is maintained by Dash as a separate project with its own releases; each Dash Platform release pins a compatible Tenderdash version. diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md index f2338cddd..ff2a1d8e3 100644 --- a/docs/explanations/platform-protocol-state-transition.md +++ b/docs/explanations/platform-protocol-state-transition.md @@ -39,7 +39,7 @@ The following table contains a list of currently defined payload types: | Payload Type | Payload Description | | - | - | | [Data Contract Create](../protocol-ref/data-contract.md#data-contract-create) (`0`) | [Database schema](../explanations/platform-protocol-data-contract.md) for a single application | -| [Batch](../protocol-ref/document.md#document-overview) (`1`) | An array of 1 or more [document](../explanations/platform-protocol-document.md) (`create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`) or [token](../explanations/tokens.md) (mint, burn, transfer, freeze/unfreeze, claim, direct purchase, set price, plus the administrative actions destroy frozen funds, emergency action, and config update) transition objects | +| [Batch](../protocol-ref/document.md#document-overview) (`1`) | An array of 1 or more (currently limited to exactly one per batch) transition objects acting on [documents](../explanations/platform-protocol-document.md) or [tokens](../explanations/tokens.md). See [Batch transitions](#batch-transitions) below for the available actions. | | [Identity Create](../protocol-ref/identity.md#identity-create) (`2`) | Information including the public keys required to create a new [Identity](../explanations/identity.md) | | [Identity Topup](../protocol-ref/identity.md#identity-topup) (`3`) | Information including proof of a transaction containing an amount to add to the provided identity's balance | | [Data Contract Update](../protocol-ref/data-contract.md#data-contract-update) (`4`) | An updated [database schema](../explanations/platform-protocol-data-contract.md) to modify an existing application | @@ -60,6 +60,13 @@ The following table contains a list of currently defined payload types: | [Shielded Withdrawal](../protocol-ref/shielded-pool.md#shielded-withdrawal) (`19`) | Withdraw funds from the shielded pool to Dash Core (L1) | | [Identity Create From Shielded Pool](../protocol-ref/shielded-pool.md#identity-create-from-shielded-pool) (`20`) | Create a new identity funded from the shielded pool | +### Batch transitions + +Batch transitions (payload type `1`) carry either document or token actions: + +- **Document actions** — create, replace, delete, transfer, purchase, and update price. See [Document](../explanations/platform-protocol-document.md) for details. +- **Token actions** — mint, burn, transfer, freeze/unfreeze, claim, direct purchase, and set price, along with administrative actions. See [Tokens](../explanations/tokens.md) for details. + ### Application Usage State transitions are constructed by client-side libraries and then submitted to the platform via [DAPI](../explanations/dapi.md). Based on the validation rules described in [DPP](../explanations/platform-protocol.md) (and an application [data contract](../explanations/platform-protocol-data-contract.md) where relevant), Dash Platform first validates the state transition. diff --git a/docs/explanations/shielded-pool.md b/docs/explanations/shielded-pool.md index ac02a0381..a7c37b4d0 100644 --- a/docs/explanations/shielded-pool.md +++ b/docs/explanations/shielded-pool.md @@ -12,7 +12,7 @@ The pool uses the [Orchard](https://zips.z.cash/protocol/protocol.pdf) shielded ## When to use the shielded pool -Shielded transitions cost more than transparent ones — they carry a zero-knowledge proof and produce permanent on-chain artifacts (note commitments, nullifiers, and encrypted note ciphertexts). Use the pool when you need confidentiality for a specific payment, transfer, or balance. Use transparent transitions for everyday activity where privacy is not a requirement. +Shielded transitions cost more than transparent ones — they carry a zero-knowledge proof and produce permanent on-chain artifacts (note commitments, nullifiers, and encrypted note ciphertexts). The fee includes a fixed proof-verification component plus a per-action component, so transitions that consume more notes cost more. Use the pool when you need confidentiality for a specific payment, transfer, or balance. Use transparent transitions for everyday activity where privacy is not a requirement. The pool is well-suited to: @@ -56,7 +56,7 @@ Moves credits *into* the pool from one or more [Platform addresses](../protocol- ### Shield from asset lock -Moves credits *into* the pool directly from a Dash Core (L1) asset-lock transaction. This avoids first funding a Platform address and lets users enter the pool in a single Platform transition tied to an L1 lock proof. +Moves credits *into* the pool directly from a Dash Core (L1) asset-lock transaction. This avoids first funding a Platform address and lets users enter the pool in a single Platform transition tied to an L1 lock proof. Any asset-lock value beyond the shielded amount and fee is credited to a Platform address the sender designates. If no surplus address is given, the remainder is donated to the fee pools, but only up to a small cap; a transition that would forfeit more than the cap is rejected so users cannot donate a large remainder by accident. ### Shielded transfer diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index f48f61284..f0c0eafb9 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -125,7 +125,8 @@ When creating a token, you define its configuration using the following paramete #### Display Conventions - The token name in multiple languages, how to capitalize it, singular vs. plural form, etc. -- How many decimal places the token uses +- An English (`en`) localization is required and serves as the fallback for languages the token does not define. Singular and plural names must be 3-25 characters. +- How many decimal places the token uses (limited to 16) #### Token Supply @@ -246,6 +247,8 @@ Groups can be used to distribute token configuration and update authorization ac - The group itself has a required power threshold to authorize an action. - A group must have at least two members. - No member's power may exceed the group's required threshold, so no single member can be given more weight than the threshold itself. +- The required threshold must be between 1 and 65535, and the members' combined power must be able to reach it. +- If some members have power equal to the threshold (and so can act alone), the remaining members must still be able to reach the threshold together. - Groups can currently have up to 256 members, each with a maximum power of 65535 (2^16 - 1). - Changes to a token (e.g., mint, burn, freeze) can be configured so they require group authorization. This is done by assigning the group under the [token rule configuration](#rules). From 9ba12c92479502bae3e8c147b97f5f9591cdb412 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 10 Sep 2026 14:06:22 -0400 Subject: [PATCH 3/8] docs(explanations): document protocol v14 query, document, and token behavior Add index-only document types across the document, data contract, and query explanations, covering their storage model, the indexOnlyDelete action, and the restrictions they trade for compactness. Document the $contractVersion base field and the related change that lets a contract update add a required property without invalidating older documents. Expand the query and proofs pages with ranked aggregates, having-range filters, time-range selection, and chained and composite queries, and add a contract design section covering the declarations those capabilities require. Note gap-free index matching and multi-property set membership. Add an identity Keys section, document credit transfers to identities and Platform addresses, and correct the withdrawal limit and masternode reward sharing descriptions. Attribute data triggers to Drive rather than DPP, add the DashPay profile payment address trigger, and point the binding list link at v2. Correct the token base supply default, mark the main control group as immutable, note the per-claim distribution interval bound, and drop the contract-side price bounds that do not exist. Reference the DashPay v2 schema and trim a trailing space. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanations/dashpay.md | 2 +- docs/explanations/identity.md | 12 +++++-- .../platform-protocol-data-contract.md | 29 ++++++++++++---- .../platform-protocol-data-trigger.md | 17 +++++----- .../platform-protocol-document.md | 15 +++++--- docs/explanations/proofs.md | 17 +++++++--- docs/explanations/query.md | 34 ++++++++++++++++--- docs/explanations/tokens.md | 11 +++--- 8 files changed, 101 insertions(+), 36 deletions(-) diff --git a/docs/explanations/dashpay.md b/docs/explanations/dashpay.md index fcfb98c70..e7aa40a07 100644 --- a/docs/explanations/dashpay.md +++ b/docs/explanations/dashpay.md @@ -44,7 +44,7 @@ payment channels between Dash identities. * Profile documents are used to store public facing information about Dash identities including avatars and display names. Since Dash Platform v4.2, a profile can also publish optional public payment addresses (a Core chain address and/or a Platform address). Unlike contact-based payments, -payments to these addresses are publicly linkable to the profile. +payments to these addresses are publicly linkable to the profile. * ContactInfo documents can be used to store private information about other Dash identities. ### Establishing a Contact diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index 697e3a991..9c8b95d1d 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -47,6 +47,12 @@ The identity balance topup process works in a similar way to the initial identit Since anyone can topup either their own account or any other account, application developers can easily subsidize the cost of using their application by topping up their user's identities. ::: +### Keys + +Each identity key has a purpose, a security level, and a cryptographic key type. Its purpose defines how the key may be used (for example authentication, encryption, decryption, transferring credits, or voting), while its security level indicates how strongly clients should protect it and which signing requirements it can satisfy. A master key controls changes to the identity's keys, while a transfer key controls its credits. More keys can be added later through an identity update. + +Data contracts can require a property to refer to an existing identity or, since Dash Platform v4.2, to a specific identity key. See [property references](../reference/data-contracts.md#platform-specific-property-keywords) and the [identity protocol reference](../protocol-ref/identity.md#identity-publickeys) for details. + ### Identity Update Process Identity owners may find it necessary to update their identity keys periodically for security purposes. The [identity update state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-update-transition) enables users to add new keys and disable existing ones. @@ -65,7 +71,7 @@ All masternodes can use their identities to vote on Platform polls for contested #### Reward distribution -Evonodes receive their Platform-specific block rewards and Platform fees with their masternode identity. The credits paid as state transition fees are distributed to masternode-related identities similar to how rewards are currently distributed to masternodes on the core blockchain. Credits are split between owner and operator in the same ratio as on layer 1, and masternode owners have the flexibility to further split their portion between multiple identities to support reward-sharing use cases. +Evonodes receive their Platform-specific block rewards and Platform fees with their masternode identity. The credits paid as state transition fees are distributed to masternode-related identities similar to how rewards are currently distributed to masternodes on the core blockchain. Each masternode's share of an epoch's fees and rewards is paid to its owner identity. The protocol also defines a reward-sharing mechanism that lets a masternode owner direct portions of that payout to other identities. See the [data trigger reference](../protocol-ref/data-trigger.md#other-system-contract-triggers) for current restrictions on reward share records. Note: the payout key is associated with the masternode owner identity, so both the owner and payout keys should be controlled by the same party. @@ -73,4 +79,6 @@ Note: the payout key is associated with the masternode owner identity, so both t Credits provide the mechanism for paying fees that cover the cost of platform usage. Once a user locks Dash on the core blockchain and proves ownership of the locked value in an identity create or topup state transition, their credit balance increases by that amount. Credits can also reach an identity from a [Platform address](../protocol-ref/address-system.md) or the [shielded pool](./shielded-pool.md) without a layer 1 lock. As they perform platform actions, these credits are deducted to pay the associated fees. -Credits can be converted back to Dash using the identity credit withdrawal state transition, subject to a daily network-wide limit. That limit is a fixed amount defined by the protocol - currently 2000 Dash per day across the whole network. Because it is a versioned protocol parameter, the value can be changed by a protocol upgrade. +Credits are not locked to the identity that holds them: an identity can transfer credits directly to another identity, or to a [Platform address](../protocol-ref/address-system.md), using the corresponding [state transitions](../explanations/platform-protocol-state-transition.md). + +Credits can be converted back to Dash using an identity credit withdrawal state transition. Withdrawals are subject to per-withdrawal and network-wide limits that constrain Platform's net daily outflow. These limits are versioned protocol parameters; see the [protocol constants reference](../protocol-ref/protocol-constants.md#withdrawal-constants) for current values. diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md index f8c4fa80e..640a22ba5 100644 --- a/docs/explanations/platform-protocol-data-contract.md +++ b/docs/explanations/platform-protocol-data-contract.md @@ -29,12 +29,14 @@ Data contracts are owned by the [identity](../explanations/identity.md) that reg Each data contract must define several fields. When using the [reference implementation](https://github.com/dashpay/platform/tree/master/packages/rs-dpp) of the Dash Platform Protocol, some of these fields are automatically set to a default value and do not have to be explicitly provided. These include: * The platform protocol schema it uses -* A contract ID (generated from a hash of the data contract's owner identity plus some entropy) +* A contract ID (generated from a hash of the data contract's owner identity and the identity nonce) * One or more [documents](../explanations/platform-protocol-document.md) * Optional [tokens](../explanations/tokens.md) with their own configuration, distribution, and authorization rules * Optional groups (sets of identities with assigned power) used to jointly authorize privileged contract actions such as token minting, burning, or configuration changes * Optional keywords used to surface the contract through discovery features, plus an optional contract description +Each document type's schema also determines how applications can query and relate its documents. Contracts declare indexes for efficient queries and can opt into capabilities such as aggregation, ranking, time-range selection, and relationships to other Platform objects. They can also define index-only document types for compact, immutable relationship data such as likes, follows, or memberships. Because these choices affect how data is stored and queried, they should be planned during contract design. See [Query Capabilities](./query.md), [Document Indices](../reference/data-contracts.md#document-indices), and [Platform-specific property keywords](../reference/data-contracts.md#platform-specific-property-keywords). + For a practical example, see the [DashPay contract](#example-contract). ### Registration @@ -59,14 +61,13 @@ Existing data contracts can be updated by their owner in backwards-compatible wa Permitted changes include: -* Adding new document types -* Adding new optional properties to existing document types -* Adding non-unique indices on newly added document types +* Adding new document types, including their indices +* Adding new properties to existing document types. New properties are normally optional; from protocol version 14 a new property may be marked as required starting with the contract version that introduces it, without invalidating documents created under earlier versions * Adding new tokens to the contract * Adding new groups to the contract * Updating contract keywords and description -Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, or altering the index definitions of an existing document type. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update. +Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, making an existing property required, or altering the index definitions of an existing document type. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update. One narrow exception exists: a document type that keeps revision history cannot allow deletion, and an existing history-keeping type that was registered with deletion allowed may be updated to forbid it. A contract update cannot remove or modify an existing token or group. Changing an existing token's configuration is done with a [token configuration update transition](../explanations/tokens.md#configuration-updates), governed by that token's own change control rules, and existing groups are immutable once the contract is registered. @@ -78,7 +79,7 @@ For more detailed information, see the [Platform Protocol Reference - Data Contr ## Example Contract -The [DashPay contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v1/dashpay.schema.json) is included below for reference. It defines a `contactRequest` document, a `profile` document, and a `contactInfo` document. Each of these documents then defines the properties and indices they require: +The [DashPay contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v2/dashpay.schema.json) is included below for reference. It defines a `contactRequest` document, a `profile` document, and a `contactInfo` document. Each of these documents then defines the properties and indices they require: :::{dropdown} DashPay contract ```json @@ -142,6 +143,22 @@ The [DashPay contract](https://github.com/dashpay/platform/blob/master/packages/ "minLength": 1, "maxLength": 25, "position": 4 + }, + "corePaymentAddress": { + "type": "array", + "byteArray": true, + "minItems": 21, + "maxItems": 21, + "description": "Core chain address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger; clients render the address as Base58Check for the network they are on. Payments to it are publicly linkable to this profile.", + "position": 5 + }, + "platformPaymentAddress": { + "type": "array", + "byteArray": true, + "minItems": 21, + "maxItems": 21, + "description": "Platform address in storage form (type byte 0x00 P2PKH / 0x01 P2SH followed by the 20-byte HASH160, i.e. RIPEMD160 of SHA256, of the public key or redeem script) for public payments. The type byte is consensus-enforced by a data trigger.", + "position": 6 } }, "minProperties": 1, diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index f40ef231d..1842c7bfc 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -4,23 +4,23 @@ # Data Trigger -This page is intended to provide a brief description of how data triggers work in the initial version of Dash Platform. The design will likely undergo changes in the future. +This page is intended to provide a brief description of how data triggers work in Dash Platform. ## Overview -Although [data contracts](../explanations/platform-protocol-data-contract.md) provide much needed constraints on the structure of the data being stored on Dash Platform, there are limits to what they can do. Certain system data contracts may require server-side validation logic to operate effectively. For example, [DPNS](../explanations/dpns.md) must enforce some rules to ensure names remain DNS compatible. [Dash Platform Protocol](../explanations/platform-protocol.md) (DPP) supports this application-specific custom logic using Data Triggers. +Although [data contracts](../explanations/platform-protocol-data-contract.md) provide much needed constraints on the structure of the data being stored on Dash Platform, there are limits to what they can do. Certain system data contracts may require server-side validation logic to operate effectively. For example, [DPNS](../explanations/dpns.md) must enforce some rules to ensure names remain DNS compatible. Dash Platform supports this application-specific custom logic using Data Triggers, which are executed by the node's execution layer ([Drive](../explanations/drive.md)) as part of state transition validation. :::{attention} -Given a number of technical considerations (security, masternode processing capacity, etc.), data triggers are not considered a platform feature at this time. They are currently hard-coded in Dash Platform Protocol and only used in system data contracts. +Given a number of technical considerations (security, masternode processing capacity, etc.), data triggers are not considered a platform feature at this time. They are currently hard-coded in the Drive execution layer, versioned with the protocol, and only used in system data contracts. ::: ## Details -Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action`, so a separate trigger can be created for any [document transition action](../explanations/platform-protocol-document.md#document-submission): `create`, `replace`, `delete`, `transfer`, `purchase`, and `updatePrice`. +Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action`, so a separate trigger can be created for any [document transition action](../explanations/platform-protocol-document.md#document-submission): `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`, and (from protocol version 14) `indexOnlyDelete`. -Which trigger runs for a given contract, document type, and action is defined in the data trigger [binding list](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v1/mod.rs). The trigger implementations linked in the tables below (for example the shared `reject` trigger) are generic and do not name the contracts that use them - the binding list is what associates each action with its trigger. +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/v2/mod.rs). The binding list is versioned with the protocol, so the set of active triggers can change when a new protocol version activates. 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, and deleting: +As an example, Drive 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 | | - | - | - | - | @@ -35,15 +35,16 @@ The `REPLACE` and `DELETE` rows for DPNS both link to the same shared `reject` t The absence of a trigger matters too: DPNS `domain` documents deliberately have no trigger bound to the `transfer`, `purchase`, or `updatePrice` actions, so those actions fall through to generic document validation. That is what makes [username transfers and sales](../explanations/dpns.md#name-transfers-and-sales) possible, while `REPLACE` and `DELETE` remain rejected so name records stay immutable and permanent. ::: -In addition to DPNS, DPP ships data triggers for a small set of other system contracts: +In addition to DPNS, Drive ships data triggers for a small set of other system contracts: | Data Contract | Document | Action(s) | Trigger Description | | - | - | - | - | | DashPay | `contactRequest` | [`CREATE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay) | Enforces DashPay-specific rules on outgoing contact requests | +| DashPay | `profile` | [`CREATE`/`REPLACE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay) | Validates that the optional core and Platform payment address fields carry a supported address type byte (P2PKH or P2SH), a rule the schema alone cannot express (protocol version 14+) | | ---- | ---- | ---- | ---- | | Masternode Rewards | `rewardShare` | [`CREATE`/`REPLACE`/`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) | Rejects all three actions so ordinary identities cannot write reward share records | | ---- | ---- | ---- | ---- | | Withdrawals | `withdrawal` | [`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 direct external mutation of withdrawal documents | | Withdrawals | `withdrawal` | [`DELETE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/withdrawals) | Allows deletion only once the withdrawal has reached `COMPLETE` status | -When document state transitions are received, DPP checks if there is a trigger associated with the document type and action. If a trigger is found, DPP executes the trigger logic. Successful execution of the trigger logic is necessary for the document to be accepted and applied to the [platform state](../explanations/drive-platform-state.md). +When document state transitions are received, Drive checks if there is a trigger associated with the document type and action. If a trigger is found, Drive executes the trigger logic. Successful execution of the trigger logic is necessary for the document to be accepted and applied to the [platform state](../explanations/drive-platform-state.md). diff --git a/docs/explanations/platform-protocol-document.md b/docs/explanations/platform-protocol-document.md index 373b9b8af..cfb69d21a 100644 --- a/docs/explanations/platform-protocol-document.md +++ b/docs/explanations/platform-protocol-document.md @@ -12,6 +12,8 @@ Documents are defined in an application's [Data Contract](../explanations/platfo ## Details +Most document types store each document as a JSON body with the base fields described below. Since protocol version 14, a data contract can instead declare a document type as index-only: its documents are never stored as a body and exist only as entries in the type's indices, with reads reconstructed from those entries. In exchange, index-only documents are immutable, cannot be transferred or traded, keep no history, and have no revision. See the [data contract explanation](../explanations/platform-protocol-data-contract.md#structure) and [indexOnly document types](../reference/data-contracts.md#indexonly-document-types) in the data contract reference. + ### Base Fields Dash Platform Protocol (DPP) defines a set of base fields that must be present in all documents. For the [reference implementation](https://github.com/dashpay/platform/tree/master/packages/rs-dpp), the base fields shown below are defined in the [document base fields](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/document/fields.rs). @@ -33,6 +35,7 @@ Dash Platform Protocol (DPP) defines a set of base fields that must be present i | $updatedAtCoreBlockHeight | Core block height when the document was last updated | | $transferredAtCoreBlockHeight | Core block height when the document was last transferred | | $creatorId | [Identity](../explanations/identity.md) that originally created the document (32 bytes). Present on document types that are transferable or have a trade mode set, and preserved when ownership changes | +| $contractVersion | Version of the data contract the document was last written under, used to determine which properties were required at that time. Present on documents written since protocol version 14; this is what allows a contract update to add a required property without invalidating older documents | :::{attention} The timestamp and block height fields will only be present in documents that add them to the list of [required properties](../reference/data-contracts.md#required-properties). @@ -50,7 +53,7 @@ Each application defines its own fields via document definitions in its data con | domain | normalizedLabel | string | | domain | parentDomainName | string | | domain | normalizedParentDomainName | string | -| domain | preorderSalt | array (bytes) | +| domain | preorderSalt | array (bytes), [transient](../reference/data-contracts.md#transient-properties) (validated on submission but not stored) | | domain | records | object | | domain | records.identity | array (32 bytes) | | domain | subdomainRules | object | @@ -58,7 +61,7 @@ Each application defines its own fields via document definitions in its data con ### Example Document -The following example shows the structure of a DPNS `domain` document as output from `JSON.stringify()`. Note the `$` prefix indicating the base fields. +The following example shows the structure of a DPNS `domain` document as output from `JSON.stringify()`. Note the `$` prefix indicating the base fields. The `preorderSalt` property is transient, so it is submitted with the document but does not appear when the document is fetched. ```json { @@ -66,6 +69,7 @@ The following example shows the structure of a DPNS `domain` document as output "$type": "domain", "$dataContractId": "GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec", "$ownerId": "6TGHW8WBcNzFrWwAueGtqtAah7w98EELFZ7xdTHegnvH", + "$creatorId": "6TGHW8WBcNzFrWwAueGtqtAah7w98EELFZ7xdTHegnvH", "$revision": 1, "$createdAt": 1712872800000, "$updatedAt": 1712872800000, @@ -74,7 +78,6 @@ The following example shows the structure of a DPNS `domain` document as output "normalizedLabel": "dq-jasen-82083", "normalizedParentDomainName": "dash", "parentDomainName": "dash", - "preorderSalt": "bcCSdtGqqZdXBQB4DDBIU2RPAwFDFt9tMr0LX6m5qCQ=", "records": { "identity": "UQTRY+wqPyL27V7YjJadJdyXVBETj6CfzvqUg5aY5E4=" }, @@ -86,13 +89,13 @@ The following example shows the structure of a DPNS `domain` document as output ## Document Submission -Once a document has been created, it must be encapsulated in a Batch state transition to be sent to the platform. Batch state transitions (type `1`) bundle one or more document and/or token transitions submitted together by the same identity. For additional details, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. +Once a document has been created, it must be encapsulated in a Batch state transition to be sent to the platform. Batch state transitions (type `1`) bundle document and/or token transitions submitted together by the same identity. Although the format allows one or more transitions, Platform currently accepts exactly one transition per batch. For additional details, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. | Field Name | Description | | - | - | | type | State transition type (`1` for a Batch) | | ownerId | Identity submitting the batch | -| transitions | Document and token transitions bundled in the batch (e.g. document `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`) | +| transitions | Document and token transitions bundled in the batch (e.g. document `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`, and, from protocol version 14, `indexOnlyDelete`) | | userFeeIncrease | Optional amount the submitter adds to the fee to raise the priority of the batch and improve its chance of timely inclusion | | signaturePublicKeyId | The `id` of the identity public key that signed the state transition | | signature | Signature of state transition data | @@ -135,6 +138,8 @@ If the data contract sets the updated at timestamp as required for the document The document delete transition is used to delete an existing Dash Platform document. It only requires the fields found in the [transition base](#document-transition-base). +Documents of [index-only document types](#details) have no stored body to reference by ID. Since protocol version 14 they are instead removed with an index-only delete transition (`indexOnlyDelete`) that carries the property values identifying the index entry to remove. + ### Document Transfer The document transfer transition is used to transfer ownership of an existing document to another identity. It extends the [transition base](#document-transition-base) with the recipient identifier: diff --git a/docs/explanations/proofs.md b/docs/explanations/proofs.md index 8a5fbdf6e..dd67ba13f 100644 --- a/docs/explanations/proofs.md +++ b/docs/explanations/proofs.md @@ -53,8 +53,8 @@ The complete verification process follows these steps: 1. Client sends a request to [DAPI](../explanations/dapi.md) with `prove: true` 2. DAPI retrieves the data and generates a proof from [Drive](../explanations/drive.md) -3. Client receives the response containing data, GroveDB proof, and consensus signature -4. Client verifies the GroveDB proof to extract the root hash +3. Client receives the proof envelope (GroveDB proof plus consensus signature and block metadata) in place of the plain data +4. Client verifies the GroveDB proof, extracting both the requested data and the root hash 5. Client verifies the BLS signature against the root hash using the quorum's public key 6. Client checks freshness on two independent axes: the signed response timestamp against its own local clock, and the block height the response is anchored to, rejecting responses whose height has fallen too far behind the most recent one seen and responses that omit this information entirely. The timestamp check matters because the height high-water mark is itself derived from responses, so height alone cannot detect a server replaying an old but internally consistent signed response 7. If these verifications pass, the data is cryptographically confirmed @@ -80,7 +80,10 @@ Dash Platform supports proofs for all core data types: - Document existence within a contract - Document queries with multiple results - Proof of document absence (data doesn't exist) +- Document history (for document types that retain history) - Aggregate values over a document set (count, sum, average) — see [Aggregate Proofs](#aggregate-proofs) below +- Ranked and value-filtered aggregate results (the top groups by an aggregate, or the groups whose aggregate falls within a range) +- Composed results of dependent queries answered together — see [Composed Proofs](#composed-proofs) below **Tokens** @@ -118,17 +121,23 @@ Three aggregate primitives are supported: - **Sum** — sum of an integer field across matching documents. - **Average** — average of an integer field across matching documents. -Some aggregate queries can return either one total or grouped totals, depending on the query shape. +Some aggregate queries can return either one total or grouped totals, depending on the query shape. Since protocol version 14, grouped results can also be [ranked](../reference/query-syntax.md#ranked-aggregate-queries) (returning only the top or bottom groups by their aggregate) or [filtered by value](../reference/query-syntax.md#having-range-queries) (returning only the groups whose aggregate falls within a range), and each of these results is provable in the same way. Aggregate queries use the same two-layer verification as any other proof (GroveDB Merkle proof plus Tenderdash consensus signature), so the result carries the same trust model as other proven Platform responses. For the exact request and response shapes, see the [DAPI Platform endpoints reference](../reference/dapi-endpoints-platform-endpoints.md). +## Composed Proofs + +With the query capabilities available in protocol version 14, multiple related reads can be answered with a single merged proof. A [chained query](../reference/query-syntax.md#chained-queries) uses the results of one query to select documents returned by another, while a [composite query](../reference/query-syntax.md#composite-queries) returns a page together with related documents, counts, or independent sibling results. + +All result sets are proven against the same quorum-signed state root. For dependent reads, the client reconstructs the derived query from the proven source results and verifies that the complete response matches the requested composition. This enables applications to verify multi-step reads in one round trip instead of requesting and joining separately proven results. + ## Requesting and Verifying Proofs ### DAPI Integration -The Decentralized API (DAPI) provides the interface for requesting proofs. When making queries, clients can set the `prove` parameter to receive cryptographic proofs alongside the data. +The Decentralized API (DAPI) provides the interface for requesting proofs. When making queries, clients can set the `prove` parameter to receive a cryptographic proof in place of the unverified data; the data itself is recovered from the proof during verification. Without proofs, clients must trust that the DAPI node is returning accurate data. With proofs enabled, clients can verify responses independently, treating DAPI nodes as untrusted data carriers rather than trusted authorities. diff --git a/docs/explanations/query.md b/docs/explanations/query.md index eb7c11945..35d3e519a 100644 --- a/docs/explanations/query.md +++ b/docs/explanations/query.md @@ -54,16 +54,15 @@ type. If a field is not indexed, it cannot be used for filtering or sorting. System fields are recognized by the query engine without being declared as normal schema properties. `$id` is implicitly queryable as the primary key. Other system fields like `$ownerId`, `$createdAt`, `$updatedAt`, and `$transferredAt` are built-in field names, but document queries still need to match an appropriate contract index. Querying and sorting on indexed fields also follows compound-index prefix and range/`orderBy` rules - see the [query syntax reference](../reference/query-syntax.md) for details. +A query is served only when its filters line up with a leading, gap-free run of an index's properties. Since protocol version 14, a query that skips a property in the middle of an index is rejected rather than served from a partial match. Set-membership filters can also be applied to more than one adjacent index property in a single query. + +Some document types can be declared index-only in the data contract. Their documents are never stored as a body, so queries return documents reconstructed from the index entries themselves. This suits cheap relation-style rows such as likes or follows, and these types are what the chained queries described below are built on. See [indexOnly document types](../reference/data-contracts.md#indexonly-document-types) in the data contract reference. + Benefits of indexed querying include: - Predictable performance - Consistent execution across nodes -:::{important} -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 @@ -74,3 +73,28 @@ Aggregates are not available on every document type. The contract must opt in fo 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. + +## Ranked, Windowed, and Composed Queries + +Since protocol version 14, Platform can answer several further kinds of question in a single verifiable +round trip: + +- **Which groups rank highest?** [Ranked queries](../reference/query-syntax.md#ranked-aggregate-queries) + return the top (or bottom) groups by a count, sum, or average, such as a leaderboard. +- **Which groups fall in a value band?** [Having-range queries](../reference/query-syntax.md#having-range-queries) + return only the groups whose aggregate falls within a given range. +- **What happened in this time window?** [Time-range selection](../reference/query-syntax.md#time-range-selection) + reads documents bucketed into fixed time windows, for trending-style views. +- **Which documents does this page refer to?** [Chained queries](../reference/query-syntax.md#chained-queries) + use the results of one query to select the documents returned by a second, and + [composite queries](../reference/query-syntax.md#composite-queries) return a page of documents together + with related documents or counts derived from that page. + +## Contract Design Considerations + +An application's expected queries shape its data contract. Fields used for filtering and sorting need +suitable indexes, while capabilities such as aggregation, ranking, time-range selection, and composed +queries require additional contract declarations. These choices should be made before registering the +contract because [updates are limited](./platform-protocol-data-contract.md#updates). See the +[data contract reference](../reference/data-contracts.md#document-indices) and +[query syntax reference](../reference/query-syntax.md) for the exact configuration and query rules. diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index f0c0eafb9..e14f18296 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -72,7 +72,8 @@ The initial token implementation includes all actions required to create, use, a - Claim tokens that have been allocated to an identity by a [distribution rule](#distribution-rules) but not yet credited to its balance. Claim covers both: - **Perpetual distributions** - tokens continuously emitted on a block or time schedule that recipients must pull in order to take ownership. - - **Pre-programmed distributions** - tokens scheduled for specific recipients at specific heights or times that recipients must claim to receive. + - **Pre-programmed distributions** - tokens scheduled for specific recipients at specific times that recipients must claim to receive. +- Each claim collects a bounded number of unclaimed perpetual distribution intervals (128 for variable-rate distribution functions), so recipients with a long backlog may need to claim more than once to collect everything owed. #### Emergency Action @@ -110,9 +111,9 @@ When creating a token, you define its configuration using the following paramete | Configuration Parameter | Mutable | Default | |:------------------------|:------------------|:--------| | Description | **No** | None | -| [Conventions](#display-conventions) | Yes | N/A. Depends on implementation | +| [Conventions](#display-conventions) | Yes | Required; must include English | | [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) | +| [Base supply](#token-supply) | **No** | [0](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L48) | | [Maximum supply](#token-supply) | Yes | None | | [Keep history](#history) | **No** | True (all history types) | | [Start paused](#initial-state) | **No** | False | @@ -185,7 +186,7 @@ following table summarizes the configurable rules and their default authorized p |:--------------------------------------|:----------------|:-------------------------| | Conventions change rules | Yes | NoOne | | Max supply change rules | Yes | NoOne | -| Main control group can be modified | Yes | NoOne | +| Main control group can be modified | No | NoOne | | Marketplace trade mode change rules | Yes | NoOne | ###### Minting and Burning @@ -281,7 +282,7 @@ This allows for: - Shared-currency ecosystems, by pricing document actions in a token that belongs to another contract. Such external-token payments transfer to the contract owner; burning is only permitted for a contract's own token. - A gasless user experience, by having the contract owner rather than the document owner pay the Platform credit cost of the action -Alongside the amount and its effect, each cost in the contract specifies who pays the Platform gas fees and may set minimum and maximum bounds. Separately, the client submitting the action can attach its own minimum and maximum bounds on what it is willing to pay. Clients should generally set a maximum: without one, a contract whose rules allow the price to change could charge more than the user expected between signing and execution. +Alongside the amount and its effect, each cost in the contract specifies who pays the Platform gas fees. Separately, the client submitting the action can attach its own minimum and maximum bounds on what it is willing to pay. Clients should generally set a maximum: without one, a contract whose rules allow the price to change could charge more than the user expected between signing and execution. ## Token Creation From 144ad3a5279c68f68219ba7ca880e36bf02ecd69 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 14 Sep 2026 11:52:36 -0400 Subject: [PATCH 4/8] docs(protocol-ref): update for Dash Platform 4.2 and correct stale behavior Document the protocol v14 additions: the v3 document meta-schema and its new contract keywords, index-only document types and their delete transition, the $contractVersion base field, and the new constants and error codes. Correct stale behavior across the section, including address system fees and witnesses, identity key signature requirements, the token base transition group fields, token purchase payment, and the common state transition field table. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/address-system.md | 20 +- docs/protocol-ref/data-contract-document.md | 61 ++++- docs/protocol-ref/data-contract-token.md | 23 +- docs/protocol-ref/data-contract.md | 269 +++++++++++++++++++- docs/protocol-ref/data-trigger.md | 2 + docs/protocol-ref/document.md | 33 ++- docs/protocol-ref/errors.md | 11 + docs/protocol-ref/identity.md | 16 +- docs/protocol-ref/protocol-constants.md | 2 + docs/protocol-ref/shielded-pool.md | 2 +- docs/protocol-ref/state-transition.md | 8 +- docs/protocol-ref/token.md | 8 +- 12 files changed, 420 insertions(+), 35 deletions(-) diff --git a/docs/protocol-ref/address-system.md b/docs/protocol-ref/address-system.md index 761ed89af..137ecac6b 100644 --- a/docs/protocol-ref/address-system.md +++ b/docs/protocol-ref/address-system.md @@ -42,12 +42,14 @@ See the [Platform address implementation in rs-dpp](https://github.com/dashpay/p ### Address Witness -Witnesses provide cryptographic proof of address ownership. Each input in an address-based transition requires a corresponding witness. +Witnesses provide cryptographic proof of address ownership. Each input in an address-based transition requires a corresponding witness at the same position in the `inputWitnesses` array. -| Variant | Size | Fields | Description | -|----------|----------|--------------------------|------------------------------------------------ | -| `P2pkh` | 65 bytes | signature | Recoverable ECDSA signature | -| `P2sh` | Varies | signatures, redeemScript | Multiple signatures with multisig redeem script | +| Variant | JSON `$type` | Fields | Description | +|---------|--------------|--------|-------------| +| `P2pkh` | `p2pkh` | `signature` | Recoverable ECDSA signature. A valid signature is 65 bytes, but the field is variable-length `BinaryData`; an invalid length fails during signature verification rather than structural decoding. | +| `P2sh` | `p2sh` | `signatures`, `redeemScript` | Multiple signatures with a multisig redeem script. Bincode decoding permits at most 17 entries in `signatures`: 16 keys plus the `CHECKMULTISIG` dummy entry. The JSON/Value deserialization path does not enforce this cap. | + +The `$type` discriminator and camelCase `redeemScript` field name apply to the JSON representation. Bincode instead encodes the variants with numeric discriminants (`0` for `P2pkh`, `1` for `P2sh`) and does not contain the `$type` string. **P2PKH Verification:** @@ -125,7 +127,7 @@ Create a new identity funded from Platform address balances. :::{note} **Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Maximum public keys: 6. Minimum per input: 100,000 credits. Minimum output: 500,000 credits. Minimum funding: input sum ≥ output sum + 200,000 credits. -**Cost:** Base cost 2,000,000 + 6,500,000 per key. Example: 2 keys = 15,000,000 credits. +**Cost:** Base cost 2,000,000 + 6,500,000 per key + 500,000 per input + 6,000,000 for the change output (if present). Example: 2 keys, 1 input, no change output = 15,500,000 credits. ::: 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/). @@ -146,7 +148,7 @@ Add credits to an existing identity from Platform address balances. :::{note} **Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Minimum per input: 100,000 credits. Minimum output: 500,000 credits. Minimum top-up: input sum ≥ output sum + 200,000 credits. -**Fee:** Base top-up cost: 500,000 credits. +**Fee:** Base top-up cost 500,000 credits + 500,000 per input + 6,000,000 for the change output (if present). ::: 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/). @@ -197,6 +199,8 @@ Exactly one output must have a `None` value. This remainder output receives what :::{note} **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. + +**Fee:** 50,000,000 credits (asset lock base) + 500,000 per input + 6,000,000 per output (at least one output is counted). Example: 1 output, no inputs = 56,000,000 credits. ::: 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/). @@ -219,7 +223,7 @@ Withdraw credits from Platform addresses back to the Core chain. :::{note} **Constraints:** Minimum inputs: 1. Maximum inputs: `max_address_inputs`. Minimum per input: 100,000 credits. Minimum output: 500,000 credits. Pooling must be `Never` (others not yet implemented). Output script must be P2PKH or P2SH. The withdrawn amount (input sum minus the change output) must be greater than zero and within the [min and max withdrawal amount](protocol-constants.md) limits. -**Fee:** 400,000,000 credits. Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain. +**Fee:** 400,000,000 credits + 500,000 per input + 6,000,000 for the change output (if present). Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain. ::: 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/). diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 5166edcee..4d0a78b8e 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -101,6 +101,24 @@ The following example (excerpt from the DPNS contract's `domain` document) demon ] ``` +#### Adding required properties in a contract update + +:::{versionadded} 4.2.0 +::: + +A contract update may add a property to `required` only if the property also sets `requiredSince` to the contract version from which it is required. The value is an integer from 1 to 4294967295 and may not exceed the version of the contract that carries it. `requiredSince` is allowed only on top-level properties that are listed in `required`. + +```json +"properties": { + "avatarUrl": { + "type": "string", + "maxLength": 2048, + "position": 3, + "requiredSince": 2 + } +} +``` + ### Transient Properties Each document may have transient fields that require validation but do not need to be stored by the system once validated. Transient fields are defined in the `transient` array. Only include the `transient` object for documents with at least one transient property. @@ -115,6 +133,23 @@ The following example (from the [DPNS contract's `domain` document](https://gith ] ``` +### Property References + +:::{versionadded} 4.2.0 +::: + +An identifier property (`type: array`, `byteArray: true`, `contentMediaType: application/x.dash.dpp.identifier`, `minItems` and `maxItems` of 32) may declare a `refersTo` object. Platform then checks at document write time that the referenced entity exists. Setting `refersTo` on any other property type is rejected. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `identity`, `contract`, `token`, `permanentDocument`, or `identityPublicKey` | +| `contractId` | string or array (32 bytes) | No | `permanentDocument` only. Contract holding the referenced document type. Defaults to the declaring contract. | +| `documentType` | string (1-64 chars) | `permanentDocument` only | Name of the referenced document type. The referenced type must set `canBeDeleted: false`. | +| `propertyAgreement` | object (1-10 entries) | No | `permanentDocument` only. Maps a property of this document to a property of the referenced document. Both values must be equal when the document is written, and both properties must have the same type. | +| `keyIdProperty` | string (1-256 chars) | `identityPublicKey` only | Property of this document that holds the referenced key id. The `refersTo` property itself holds the identity id. | + +`contractId`, `documentType`, and `propertyAgreement` are rejected unless `type` is `permanentDocument`; `keyIdProperty` is rejected unless `type` is `identityPublicKey`. + ### Property Constraints There are a variety of constraints currently defined for performance and security reasons. @@ -142,10 +177,15 @@ 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 +* An optional `contested` element that makes matching values on a unique index subject to a masternode vote instead of first-come ownership. See [Contested Indices](#contested-indices) * 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 +* Optional ranked aggregate flags (added in 4.2.0) - `rankedCountable`, `rankedSummable`, and `rankedAverageable` - that enable top or bottom K queries on the index. See [Index-level flags](#index-level-flags). +* An optional `timeRange` object (added in 4.2.0) that buckets the index's first property into fixed-length time windows. Fields: `on` (required; the first index property, which must be `$createdAt`, `$updatedAt`, or `$transferredAt` and be listed in `required`), `range` (required; window length in seconds), `step` (required; seconds between window starts; `range` must be a multiple of `step`), and `phase` (optional; grid offset in seconds, less than `step` and less than 31536000; default 0). A `timeRange` index may be `unique` only when `range` equals `step` and `on` is `$createdAt`. It cannot be `contested` or set `nullSearchable: false`. +* An optional `skipIfAbsent` element (added in 4.2.0), only on `indexOnly` document types. When true, a document that omits the index's first property writes no entry into this index. That first property must be a top-level property that is not in `required`; every index that includes an optional property must be `skipIfAbsent` with that property first; every other property must still appear in at least one index that is not `skipIfAbsent`; and at least one index without `$createdAt` must not be `skipIfAbsent`. +* An optional `terminal` element, only on `indexOnly` document types, naming the property whose value keys each index entry: `$ownerId` (default) or an identifier property with a `refersTo` of type `identity`, `contract`, `token`, or `permanentDocument`. It must not repeat one of the index's listed properties. +* An optional `preallocated` element, only on `indexOnly` document types whose index properties are all either the referring property of a same-contract `permanentDocument` reference or a key of its `propertyAgreement`. When true, the index trees for entries referencing a document are created when that document is created. It cannot be combined with `timeRange`. -Index objects do not accept any properties beyond those listed above. +Index objects do not accept any properties beyond those listed above. Starting with Dash Platform 4.2.0 (protocol version 14), index objects also accept the ranked aggregate keywords, `timeRange`, and the `indexOnly`-specific keywords `terminal`, `preallocated`, and `skipIfAbsent`. Under earlier protocol versions those keywords are rejected. :::{code-block} json :force: @@ -198,6 +238,7 @@ The table below describes the properties used to configure a contested index: | fieldMatches.field | string | Name of the field to check for matches | | fieldMatches.regexPattern | string | Regex used to check for matches | | resolution | integer | Method to resolve the contest:
`0` - masternode voting | +| description | string | Optional free-text note (1-256 characters) | **Example** @@ -227,6 +268,7 @@ For performance and security reasons, indices have the following constraints. Th | 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 `timeRange` overlap factor (`range / step`) (added in 4.2.0) | 24 | | 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.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | @@ -268,6 +310,7 @@ Documents support the following configuration options to provide flexibility in | `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. | +| `indexOnly` | boolean | **Added in 4.2.0.** If true, documents of this type are stored only as index entries; there is no primary document row. Requires `documentsMutable: false`, `transferable: 0`, `tradeMode: 0`, no history flags, no `transient` properties, no document-type aggregate flags, at least one index, and every property required and indexed (see `skipIfAbsent` for the one exception). Indices on such a type cannot be `unique`, `contested`, or set `nullSearchable: false`, and every index must include `$ownerId` as a property or as its terminal. Default: false. | | Security option | Type | Description | |-----------------|------|-------------| @@ -275,6 +318,10 @@ Documents support the following configuration options to provide flexibility in | [`requiresIdentity`
`DecryptionBoundedKey`](./data-contract.md#key-management) | integer | Key requirements for identity decryption:
`0` - Unique non-replaceable
`1` - Multiple
`2` - Multiple with reference to latest key | | `signatureSecurity`
`LevelRequirement` | integer | Public key security level:
`1` - Critical
`2` - High
`3` - Medium. Default is High if none specified. | +:::{versionchanged} 4.2.0 +A document type with `documentsKeepHistory: true` must also set `canBeDeleted: false`. Since `canBeDeleted` defaults to true, leaving it unset on a keep-history type is rejected when the contract is validated. +::: + ### 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.1.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L294-L337) object with the following properties: @@ -329,6 +376,7 @@ The following operation types can each have an independent cost configuration: | [`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). | + | `indexOnly` | boolean | If true, index entries are the only storage for this document type. See [Document Configuration](#document-configuration). | | `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. | @@ -390,12 +438,15 @@ Index-level flags configure aggregates along a specific index path. Set them on | `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. | +| `rankedCountable` | Boolean or object | **Added in 4.2.0.** Ranks groups by document count for top or bottom K queries. `true` ranks the last index property. The object form `{"at": ""}` or `{"at": ["", ...]}` (1-10 unique names, each an index property) places a count ranking at the named level(s); a non-terminal level ranks its values by whole-subtree count. Requires `rangeCountable: true`. A non-terminal `at` cannot be combined with `rankedSummable` or `rankedAverageable`, and no other index of the type may share that level. | +| `rankedSummable` | Boolean | **Added in 4.2.0.** Ranks groups by the sum of the `summable` property. Requires `rangeSummable: true`. | +| `rankedAverageable` | Boolean | **Added in 4.2.0.** Ranks groups by the average of the `averageable` property. Requires `rangeAverageable: true`. Does not imply `rankedCountable` or `rankedSummable`. | 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. -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). +These flags were introduced in the v1 document meta-schema and carry forward unchanged into v2 and v3. 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. @@ -414,7 +465,7 @@ Document types can opt into recording ownership and pricing events in the [docum 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). +The flags are read only when the contract validates against the v2 or later 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 @@ -493,4 +544,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.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). +See full document schema details in the rs-dpp document meta schema. Protocol version 13 (Dash Platform 4.1) validates against the [v2 meta-schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). Protocol version 14 (Dash Platform 4.2.0) validates against the [v3 meta-schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json), which adds the ranked index keywords, `refersTo`, `requiredSince`, `timeRange`, and the `indexOnly` keywords. diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md index f9f208292..92d3b9733 100644 --- a/docs/protocol-ref/data-contract-token.md +++ b/docs/protocol-ref/data-contract-token.md @@ -123,7 +123,7 @@ Token configuration controls behavioral aspects of token operations, including s | Property | Type | Description | |----------|------|-------------| -| `description` | string | Optional text describing the token's purpose or behavior (3–100 characters) | +| `description` | string | Optional text describing the token's purpose or behavior | ### Supply Management @@ -289,6 +289,8 @@ The `distributionType` field accepts one of three schedule types: 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). +The `interval` has a network specific minimum, checked when the contract is registered or updated. Block based intervals must be at least 100 blocks on mainnet (5 on testnet, 2 on devnet, 1 on regtest). Time based intervals must be at least 3,600,000 ms (1 hour) on mainnet (600,000 ms on testnet, 60,000 ms on devnet and regtest) and must be a multiple of 60,000 ms. Epoch based intervals have no minimum. + #### Perpetual Distribution Options A wide variety of emission patterns are provided to cover most common scenarios. The following table summarizes the options and links to further details. @@ -609,6 +611,21 @@ Parameter sign types vary by function: `a` is unsigned (u64) for `Exponential` b The **Default** column shows typical values rather than code-enforced defaults. In the underlying structs, `a`, `b`, `d`, `m`, `n`, and `o` are required fields with no default — they must be supplied for the functions that use them. Only the start offset (`s`) and the emission bounds (`min_value`, `max_value`) are optional; the start offset defaults to contract registration. ::: +### Parameter Bounds + +Contract registration validates each function's parameters. Where a bound applies, the largest allowed value is 281,474,976,710,655 (2^48 - 1); this caps the emitted amounts, the start offset (`s`), the offset `o` (as an absolute value), `max_value`, and the constant term `b` for the exponential, logarithmic, and inverted logarithmic functions. Divisors (`d`, `n`, `decrease_per_interval_denominator`, `step_count`) may not be zero, and `min_value` may not exceed `max_value`. + +| Function | Enforced bounds | +| - | - | +| `fixedAmount` | `amount` from 1 to 2^48 - 1 | +| `stepDecreasingAmount` | `distribution_start_amount` from 1 to 2^48 - 1 and at least `min_value`; `trailing_distribution_interval_amount` <= `distribution_start_amount`; `decrease_per_interval_numerator` > 0 and < `decrease_per_interval_denominator`; `max_interval_count` from 2 to 1024 when set | +| `stepwise` | at least 2 steps | +| `linear` | `a` from -255 to 256, not 0 | +| `polynomial` | `a` from -32766 to 32767, not 0; `m` from -8 to 8, not 0; `n` from 1 to 32; `n` may not equal `m` when `m` > 0 | +| `exponential` | `a` from 1 to 256; `m` from -8 to 8, not 0; `n` from 1 to 32; `max_value` required when `m` > 0 | +| `logarithmic` | `a` from -32766 to 32767, not 0; `m` from 1 to 2^48 - 1; `(x - s + o)` must be greater than 0 at the start | +| `invertedLogarithmic` | `a` from -32766 to 32767, not 0; `m` greater than 0; `n` greater than 0; `(x - s + o)` must be greater than 0 at the start | + ### Distribution Recipients | Recipient | JSON value | Description | @@ -627,10 +644,12 @@ For performance and security reasons, tokens have the following constraints: ### General Constraints +The keyword and description limits below apply to the data contract that holds the tokens, not to each token. + | Parameter | Value | |-----------|-------| | 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) | +| Keyword length | [3 to 50 bytes](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) | diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index 759953851..91316cce5 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -96,11 +96,12 @@ Each document type defined within a data contract is validated against the docum | Meta-schema | Protocol version | | - | - | -| v2 | 13 and later | +| v3 | 14 and later | +| v2 | 13 | | 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: +This page reflects the v3 meta-schema, which adds the `refersTo` and `requiredSince` property keywords, the `indexOnly` document type flag, and the `rankedCountable`, `rankedSummable`, `rankedAverageable`, `skipIfAbsent`, `preallocated`, `terminal` and `timeRange` index keywords on top of the v2 [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.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json) and can be viewed by expanding this dropdown: ::: {dropdown} Full schema @@ -108,7 +109,7 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat { "$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 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+).", + "$comment": "EDITABLE UNTIL THE RELEASE CARRYING PROTOCOL V14 SHIPS — FROZEN AFTER. This v3 document meta-schema activates with protocol v14 (CONTRACT_VERSIONS_V6). It is v2 plus the ranked index keywords (rankedCountable, rankedSummable, rankedAverageable), the refersTo reference keyword on identifier properties, the requiredSince property keyword (the contract version a property is required from), and the timeRange index transform, and admits every v14+ contract written to disk. v2 stays in place for protocol v13, where those keys still fail an index entry's `additionalProperties: false`. Once the release carrying protocol v14 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 (v4+). The $id above deliberately still names the v1 path: v1, v2 and v3 all share that identity, and it is the exact string `enrich_with_base_schema` injects as every PV12+ document schema's `$schema`, so bumping it here would be a wire-visible change rather than a documentation fix.", "type": "object", "$defs": { "documentProperties": { @@ -198,6 +199,105 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "uniqueItems": { "$ref": "https://json-schema.org/draft/2020-12/meta/validation#/properties/uniqueItems" }, + "refersTo": { + "type": "object", + "properties": { + "type": { + "enum": [ + "identity", + "contract", + "token", + "permanentDocument", + "identityPublicKey" + ] + }, + "contractId": { + "description": "The id of the data contract the referenced document lives in, as a base58 string or a 32-byte array; when absent the reference targets the declaring contract itself", + "oneOf": [ + { + "type": "string", + "minLength": 32, + "maxLength": 44, + "pattern": "^[123456789A-HJ-NP-Za-km-z]{32,44}$" + }, + { + "type": "array", + "minItems": 32, + "maxItems": 32, + "items": { + "type": "integer", + "minimum": 0, + "maximum": 255 + } + } + ] + }, + "documentType": { + "description": "The name of the referenced document type; it must forbid deletion (canBeDeleted: false)", + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-zA-Z0-9-_]{1,64}$" + }, + "keyIdProperty": { + "description": "The property of the same document type whose value carries the referenced key id; the reference property's value carries the identity id", + "type": "string", + "minLength": 1, + "maxLength": 256, + "pattern": "^[a-zA-Z0-9-_]{1,64}(\\.[a-zA-Z0-9-_]{1,64})*$" + }, + "propertyAgreement": { + "description": "permanentDocument references only: each { referring property: referenced property } pair must hold as an equality between the referring document's value and the referenced document's value, enforced by consensus at document write time; both properties must exist and share one property type, validated at contract registration", + "type": "object", + "minProperties": 1, + "maxProperties": 10, + "propertyNames": { + "pattern": "^[a-zA-Z0-9-_]{1,64}(\\.[a-zA-Z0-9-_]{1,64})*$" + }, + "additionalProperties": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "pattern": "^[a-zA-Z0-9-_]{1,64}(\\.[a-zA-Z0-9-_]{1,64})*$" + } + } + }, + "required": [ + "type" + ], + "additionalProperties": false, + "allOf": [ + { + "if": { + "properties": { "type": { "const": "permanentDocument" } }, + "required": ["type"] + }, + "then": { + "required": ["type", "documentType"] + }, + "else": { + "properties": { + "contractId": false, + "documentType": false + } + } + }, + { + "if": { + "properties": { "type": { "const": "identityPublicKey" } }, + "required": ["type"] + }, + "then": { + "required": ["type", "keyIdProperty"] + }, + "else": { + "properties": { + "keyIdProperty": false + } + } + } + ] + }, "contains": { "$ref": "https://json-schema.org/draft/2020-12/meta/applicator#/properties/contains" }, @@ -247,6 +347,11 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "position": { "type": "integer", "minimum": 0 + }, + "requiredSince": { + "type": "integer", + "minimum": 1, + "maximum": 4294967295 } }, "dependentSchemas": { @@ -299,6 +404,33 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "maxLength" ] }, + "refersTo": { + "description": "refersTo is only allowed on identifier properties", + "properties": { + "type": { + "const": "array" + }, + "byteArray": { + "const": true + }, + "contentMediaType": { + "const": "application/x.dash.dpp.identifier" + }, + "minItems": { + "const": 32 + }, + "maxItems": { + "const": 32 + } + }, + "required": [ + "type", + "byteArray", + "contentMediaType", + "minItems", + "maxItems" + ] + }, "format": { "description": "prevent slow format validation of large strings", "properties": { @@ -572,6 +704,100 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "rangeAverageable": { "type": "boolean", "description": "Syntactic sugar: `rangeAverageable: true` is shorthand for `rangeCountable: true` + `rangeSummable: true`. Requires `averageable` to be set." + }, + "rankedCountable": { + "oneOf": [ + { + "type": "boolean", + "description": "When true, the index's terminal property-name tree also carries an ordered secondary tree keyed by each group's document count, so \"top / bottom K groups by count\" queries are O(log n + k) with proofs." + }, + { + "type": "object", + "properties": { + "at": { + "oneOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "minItems": 1, + "maxItems": 10, + "uniqueItems": true + } + ], + "description": "Name of the index property (or array of properties) whose levels carry Count rankings. Each must be one of the index's properties (an index has at most 10, hence maxItems); naming the last property is equivalent to the boolean form. A non-terminal property places a ranking at that prefix level: its values are ranked by whole-subtree document count (e.g. on [hashtag, postId], at: \"hashtag\" ranks hashtags by total count across all their posts), and every level from the shallowest ranked one down to the terminal is laid out count-bearing so each write's delta propagates up through the chain. ANY subset of levels may be named — e.g. [\"hashtag\", \"postId\"] declares both rankings on one index, and a fully ranked index ranks every level." + } + }, + "required": ["at"], + "additionalProperties": false, + "description": "Level-addressed form: places Count rankings at the named properties' levels. Cannot be combined with rankedSummable or rankedAverageable when a non-terminal level is named, and no other index of the document type may share a non-terminal ranked level or any level below it." + } + ], + "description": "Count ranking axis. Requires `rangeCountable: true`. Independent of the Sum and Avg axes (`rankedSummable` / `rankedAverageable`), which stay terminal-level booleans." + }, + "rankedSummable": { + "type": "boolean", + "description": "When true, the index's terminal property-name tree also carries an ordered secondary tree keyed by each group's sum of the `summable` property, so \"top / bottom K groups by sum\" queries are O(log n + k) with proofs. Requires `rangeSummable: true`. Adds the Sum ranking axis only." + }, + "rankedAverageable": { + "type": "boolean", + "description": "When true, the index's terminal property-name tree also carries an ordered secondary tree keyed by each group's average (count + sum pair) of the `averageable` property, so \"top / bottom K groups by average\" queries are O(log n + k) with proofs. Requires `rangeAverageable: true` (which itself implies `rangeCountable` + `rangeSummable`). Adds the Avg ranking axis only — it does NOT imply `rankedCountable` or `rankedSummable`; each ranking axis costs its own secondary tree and is opted into separately." + }, + "timeRange": { + "type": "object", + "properties": { + "on": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "Name of the timestamp index property to bucket. Must be this index's first property and name one of the system timestamps ($createdAt, $updatedAt or $transferredAt). A timeRange index may be unique only when range equals step (non-overlapping windows) and `on` is $createdAt." + }, + "range": { + "type": "integer", + "minimum": 1, + "description": "Length of each time range window, in seconds. Must be an exact multiple of `step`." + }, + "step": { + "type": "integer", + "minimum": 1, + "description": "Interval between successive range starts, in seconds. When `range` > `step` the ranges overlap and a document is indexed under `range / step` bucket-start values, bounded by a protocol-versioned cap (24 at protocol version 14)." + }, + "phase": { + "type": "integer", + "minimum": 0, + "description": "Grid alignment phase, in seconds. Range starts are `phase + k * step`; must be strictly less than `step` (a larger value would be a redundant spelling of `phase % step`) and strictly less than one year (31536000 — a phase further out could sit past current block time on a huge step, leaving valid timestamps before the grid's first bucket). A pure alignment offset — it moves where window boundaries fall (e.g. daily windows cut at 06:00 UTC instead of midnight) and never excludes any real timestamp. Defaults to 0." + }, + "ttl": { + "type": "integer", + "minimum": 1, + "description": "Time to live, in seconds: entries under this index exist for at most this long past their bucket's start, plus a bounded drainage lag — every write into the index continues draining the oldest expired bucket under a per-write operation budget, and expired windows are not queryable (a byStart selection past the horizon is rejected), so every queryable window is complete. Must be at least `range` (a window still able to receive consensus-timestamped writes can never expire) and at most a protocol-versioned cap (604800 — one week — at protocol version 14). Indexes bucketing one field with the same grid share its storage level and must declare the same ttl. Bytes written under a TTL'd index bill to processing at an ephemeral-bytes rate instead of to storage, carry no storage flags, and refund nothing on removal. Omitted means entries live forever. Available from protocol version 14." + } + }, + "required": ["on", "range", "step"], + "additionalProperties": false, + "description": "Buckets the first index property's timestamp into fixed-length, regularly-spaced (possibly overlapping) time ranges. The window parameters (`range`, `step`, `phase`) are declared in seconds, since a bucket is selected from block time and the target block interval is five seconds; the stored key is the range start as a u64 millisecond timestamp, so it stays directly comparable to the source timestamp it buckets. Enables trending/leaderboard queries within the newest/oldest active range. A system-timestamp source must be listed in the document type's required fields. Several indexes may bucket the same timestamp with different grids — each grid gets its own index subtree, keyed by the property name qualified with the grid parameters. Available from protocol version 14." + }, + "terminal": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "Only on indexOnly document types: names the property whose value is this index entry's member key — the docId-analog terminal key under the index's storage marker, stored as an Item instead of a Reference because there is no primary-storage row. Either \"$ownerId\" (the default when omitted) or an identifier property carrying a refersTo declaration (identity, contract, token, or permanentDocument). Must not repeat one of the index's listed properties. Available from protocol version 14." + }, + "preallocated": { + "type": "boolean", + "description": "Only on indexOnly document types whose index path is fully determined by a same-contract permanentDocument refersTo declaration: every index property must be either the referring property itself (its value is the referenced document's $id) or a key of that declaration's propertyAgreement (consensus-equal to a referenced-document property). When true, creating a referenced document also creates this index's dynamic trees for entries referencing it — paid by the referenced document's creator — and deleting the last entry keeps them, so every entry insert costs the same as the first. Available from protocol version 14." + }, + "skipIfAbsent": { + "type": "boolean", + "description": "Only on indexOnly document types: when true, a document that omits this index's first property writes no entry into this index (and a delete recomputes the same skip), so the index holds only documents carrying the property. The first property is the skip trigger: it must be a top-level schema property NOT listed in `required` (making it the only way an indexOnly property may be optional), and every index involving an optional property must be skipIfAbsent with that property first. Every other property that is not a skip trigger must still appear in at least one non-skipIfAbsent index, and at least one $createdAt-free index must remain non-skipIfAbsent (the executed-transition proof index). An absent trigger is distinct from an empty value: absence skips the index, while any present value — empty included — indexes normally. Available from protocol version 14." } }, "required": [ @@ -583,6 +809,34 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "rangeSummable": ["summable"], "rangeAverageable": ["averageable"] }, + "$comment": "The ranked prerequisites are value-sensitive, unlike the range* rows above: `dependentRequired` fires on key *presence*, so listing them there would make an explicit `\"rankedCountable\": false` — a written-out opt-out, which the structural parser accepts as such — demand a `rangeCountable` the index does not need. The range* rows keep presence semantics because that is what they shipped with in v2 and changing them would move historical validation results.", + "allOf": [ + { + "if": { + "properties": { + "rankedCountable": { + "anyOf": [{ "const": true }, { "type": "object" }] + } + }, + "required": ["rankedCountable"] + }, + "then": { "required": ["rangeCountable"] } + }, + { + "if": { + "properties": { "rankedSummable": { "const": true } }, + "required": ["rankedSummable"] + }, + "then": { "required": ["rangeSummable"] } + }, + { + "if": { + "properties": { "rankedAverageable": { "const": true } }, + "required": ["rankedAverageable"] + }, + "then": { "required": ["rangeAverageable"] } + } + ], "additionalProperties": false }, "minItems": 1, @@ -692,6 +946,10 @@ This page reflects the v2 meta-schema, which adds [document history flags](./dat "type": "boolean", "description": "Syntactic sugar: `rangeAverageable: true` is shorthand for `rangeCountable: true` + `rangeSummable: true`. Requires `documentsAverageable` to be set. Same caveat as `rangeSummable` — rarely useful on the primary key; per-index `rangeAverageable` is what most callers want." }, + "indexOnly": { + "type": "boolean", + "description": "When true, documents of this type are never written to primary storage: the index entries are the rows, each terminating in an Item keyed by the index's `terminal` property instead of a Reference keyed by the document id. Only what is in the indexes exists and is recoverable. Requires: every property required and appearing in at least one index (except a `skipIfAbsent` index's optional first property), $ownerId in at least one index (as a property or terminal), documentsMutable: false, no transfers/trading/history/transient properties, and no doctype-level aggregate keywords (use the index-level count flags). Available from protocol version 14." + }, "tokenCost": { "type": "object", "properties": { @@ -1016,13 +1274,14 @@ Existing data contracts can be updated in certain backwards-compatible ways. The of a data contract can be updated: - Adding a new document -- Adding a new optional property to an existing document -- 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 property to an existing document type. The property may be optional, or required if it carries a `requiredSince` value equal to the contract version the update creates. Existing properties and system (`$`-prefixed) fields cannot become required, and required fields cannot be removed. Document types added by the update must set `requiredSince` to that same version on any required property, and on contract creation `requiredSince` may only be `1`. +- Reordering the `indices` array. Index definitions are immutable once the document type is registered: an index cannot be added, removed, or changed (including its `unique`, `properties`, aggregate, or ranked flags). - 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 +- Changing `canBeDeleted` from `true` to `false` on a document type whose `documentsKeepHistory` is `true`. This is the only document type config change allowed after registration Existing tokens and groups cannot be removed or modified once the contract is registered. diff --git a/docs/protocol-ref/data-trigger.md b/docs/protocol-ref/data-trigger.md index b9c854e0b..959ddd2c3 100644 --- a/docs/protocol-ref/data-trigger.md +++ b/docs/protocol-ref/data-trigger.md @@ -75,6 +75,8 @@ In addition to DPNS, the following system contracts have registered data trigger | Document | Action | Trigger Description | | ---------------- | -------- | ------------------------------------------------ | | `contactRequest` | `CREATE` | Validates contact request fields and permissions | +| `profile` | `CREATE` | Rejects `corePaymentAddress` or `platformPaymentAddress` values whose first byte is not `0x00` (P2PKH) or `0x01` (P2SH) (protocol version 14+) | +| `profile` | `REPLACE` | Same payment address type byte check as `CREATE` (protocol version 14+) | **Masternode Rewards** diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 8ce0317fd..52b447051 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -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.1.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). The Action column is the enum index. In the JSON form, `$action` carries the camelCase name instead: `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`, or `indexOnlyDelete`. | Action | Name | Description | | :-: | - | - | @@ -94,6 +94,7 @@ Document transition actions indicate what operation platform should perform with | 4 | [Purchase](#document-purchase-transition) | Purchase the referenced document | | 5 | [Update price](#document-update-price-transition) | Update the price for the document | | 6 | IgnoreWhileBumpingRevision | Internal action type used to bypass revision bump | +| 7 | [Index-only delete](#document-index-only-delete-transition) | Delete an [indexOnly](../reference/data-contracts.md#indexonly-document-types) document by its property values. Only valid for document types with `indexOnly` set (protocol version 14+). JSON `$action` value: `indexOnlyDelete`. | ### Document Create Transition @@ -115,7 +116,7 @@ The following example document create transition and subsequent table demonstrat ```json { - "$action": 0, + "$action": "create", "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8", "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP", "$type": "note", @@ -153,7 +154,7 @@ The following example document replace transition and subsequent table demonstra ```json { - "$action": 1, + "$action": "replace", "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8", "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP", "$type": "note", @@ -209,6 +210,31 @@ The document update price transition allows a document owner to set or update th 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 Index-Only Delete Transition + +:::{versionadded} 4.2.0 +::: + +The document index-only delete transition deletes a document of an [indexOnly](../reference/data-contracts.md#indexonly-document-types) document type. These documents have no stored row to look up by id, so the transition carries the document's property values instead. Platform recomputes every index entry from those values and the signer's identity as owner, then removes the entries. + +In JSON, the document's property values are flattened into the transition object alongside the [document base transition](#document-base-transition) fields; there is no enclosing `data` property. Internally, rs-dpp collects the property values in a `data` map. The supplied values must match those used when the document was created. + +```json +{ + "$action": "indexOnlyDelete", + "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8", + "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP", + "$identityContractNonce": 1, + "$type": "like", + "postId": "BwW4XJHcVsfRbqdMUK5hWaz2WYLxVjVQFzXyWj6YV2R", + "hashtag": "dash" +} +``` + +The transition has no `$revision` or `$entropy` field. It is rejected for document types without `indexOnly`; those are deleted with the [delete transition](#document-delete-transition). + +Each document index-only delete transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_index_only_delete_transition/v0/mod.rs#L37-L45) (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.1.0/packages/rs-dpp/src/document/v0/mod.rs#L37-L101)): @@ -230,6 +256,7 @@ The document object represents the data provided by the platform in response to | $updatedAt
CoreBlockHeight | unsigned integer (32 bits) | No |Core block height at the document's last update, if required by the schema | | $transferredAt
CoreBlockHeight | unsigned integer (32 bits) | No |Core block height when document was last transferred, if required by the schema | | $creatorId | array | No | Identity of the document creator (32 bytes), if required by the document type schema | +| $contractVersion | unsigned integer (32 bits) | No | Data contract version the document's stored bytes conform to. Set by platform on create and replace and kept on transfer and purchase. Present when the document type uses `requiredSince`; absent for documents stored before this field existed. | ### Example Document Object diff --git a/docs/protocol-ref/errors.md b/docs/protocol-ref/errors.md index e3b57cecf..f00fb1383 100644 --- a/docs/protocol-ref/errors.md +++ b/docs/protocol-ref/errors.md @@ -128,6 +128,7 @@ Code range: 10200-10349 | 10273 | InvalidTokenDistributionTimeIntervalTooShortError | | | 10274 | InvalidTokenDistributionTimeIntervalNotMinuteAlignedError | | | 10275 | RedundantDocumentPaidForByTokenWithContractId | | +| 10276 | DataContractInvalidRequiredFieldsUpdateError | | ### Group @@ -354,6 +355,16 @@ Code range: 40100-40199 | 40115 | RequiredTokenPaymentInfoNotSetError | | | 40116 | IdentityHasNotAgreedToPayRequiredTokenAmountError | | | 40117 | IdentityTryingToPayWithWrongTokenError | | +| 40118 | DocumentContestIndexMismatchError | | +| 40119 | DocumentContestNotRequiredError | | +| 40120 | ReferencedEntityNotFoundError | | +| 40121 | ReferencedDocumentTypeNotFoundError | | +| 40122 | ReferencedDocumentTypeDeletableError | | +| 40123 | ReferencedIdentityKeyNotFoundError | | +| 40124 | ReferencedIdentityKeyDisabledError | | +| 40125 | ReferencedKeyIdPropertyInvalidError | | +| 40126 | ReferencedDocumentPropertyAgreementInvalidError | | +| 40127 | ReferencedDocumentPropertyMismatchError | | ### Token State diff --git a/docs/protocol-ref/identity.md b/docs/protocol-ref/identity.md index 8fa0dc0cd..c9380fc16 100644 --- a/docs/protocol-ref/identity.md +++ b/docs/protocol-ref/identity.md @@ -68,10 +68,10 @@ Each item in the `publicKeys` array consists of an object containing: | [securityLevel](#public-key-securitylevel) | integer | Public key security level (`0` - Master, `1` - Critical, `2` - High, `3` - Medium) | | contractBounds | object (optional) | Restricts this key to a specific data contract or document type context | | [type](#public-key-type) | integer | Type of key (default: `0` - ECDSA) | -| [readonly](#public-key-readonly) | boolean | Identity public key can’t be modified with `readOnly` set to `true`. This can’t be changed after adding a key. | +| [readOnly](#public-key-readonly) | boolean | Identity public key can’t be modified with `readOnly` set to `true`. This can’t be changed after adding a key. | | [data](#public-key-data) | array of bytes | Public key (`0` - ECDSA: 33 bytes, `1` - BLS: 48 bytes, `2` - ECDSA Hash160: 20 bytes, `3` - [BIP13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) Hash160: 20 bytes, `4` - EDDSA_25519_HASH160: 20 bytes) | | [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 | +| signature | array of bytes | Signature of the signable state transition adding the key (identity create, identity update, or identity create from addresses) by the private key for this public key. Must be empty for key types `2`, `3`, and `4`. | 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. @@ -251,12 +251,16 @@ Identities can transfer credits on the platform by submitting an identity credit | type | integer | State transition type (`7` for identity credit transfer) | | identityId | array of bytes | The [identity id](#identity-id) of the sender (32 bytes) | | recipientId | array of bytes | The [identity id](#identity-id) of the recipient (32 bytes) | -| amount | integer | The credit amount to transfer | +| amount | integer | The credit amount to transfer (minimum 100,000 credits) | | nonce | unsigned integer (64 bits) | Identity nonce for this transition to prevent replay attacks | | userFeeIncrease | integer | Extra fee to prioritize processing if the mempool is full. Typically set to zero. | | signaturePublicKeyId | integer | The ID of public key used to sign the state transition | | signature | array of bytes | Signature of state transition data (65 bytes) | +:::{note} +The `recipientId` must differ from `identityId`; transfers to the sending identity are rejected. +::: + 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,6 +281,10 @@ 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) | +:::{note} +**Constraints:** `pooling` must be `0` (Never); `1` (IfAvailable) and `2` (Standard) are not yet implemented. `coreFeePerByte` must be a non-zero [Fibonacci number](https://en.wikipedia.org/wiki/Fibonacci_sequence). `outputScript`, when set, must be P2PKH or P2SH. `amount` must be within the [min and max withdrawal amount](protocol-constants.md) limits. +::: + 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 @@ -320,5 +328,5 @@ The process to sign an identity create state transition consists of the followin - `signature` for the overall state transition 2. Calculate the double SHA-256 hash of the encoded signable state transition 3. Sign the hash from the previous step using the private key associated with the asset lock transaction, then add the result to the state transition's `signature` field -4. For each public key being added to the identity, sign the hash from step 2 using the respective private key and add the result to the public key's `signature` field +4. For each public key of type `0` or `1` being added to the identity, sign the hash from step 2 using the respective private key and add the result to the public key's `signature` field. Keys of type `2`, `3`, or `4` must have an empty `signature`. 5. Use Bincode to re-encode the state transition with all signatures and the identity id included diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 89ae2da75..2a5dabe6c 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -20,9 +20,11 @@ Maximum sizes and limits for various platform components. | 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) | +| Daily withdrawal limit | Protocol versions 8-13: 200,000,000,000,000 credits (2000 Dash)
Protocol version 14+: 15% of the credits Platform held one day earlier, with a 500-Dash floor and 4000-Dash cap | The relative limit added in 4.2.0 is `min(max(day-old total × 15%, max withdrawal amount), 4000 Dash)`. Until a full day of credit history is available after activation, the previous 2000-Dash limit remains in effect. | [v8-v13](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/v1/mod.rs), [v14+](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/v2/mod.rs) | | 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 | 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 time-range overlap factor | 24 | **Added in 4.2.0.** Maximum `range / step` for a [timeRange](data-contract-document.md#document-indices) index, so at most 24 windows overlap at any timestamp | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L43) | | 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) | diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index bdbc47406..07febb53f 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -55,7 +55,7 @@ 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.1.0/packages/rs-dpp/src/shielded/mod.rs#L32-L58) (312 bytes in the note commitment tree + 32 bytes in the nullifier tree). +Each action permanently stores [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). The minimum shielded fee charges a per-action storage allowance of `shielded_storage_bytes_per_action` bytes at the storage rate: 344 bytes through protocol version 13, and 550 bytes from protocol version 14 to cover tree framing overhead. See the [serialized action implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/mod.rs). diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index f46d957b6..e70d49518 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -21,20 +21,22 @@ State transitions are limited to a maximum size of [20 KiB / 20,480 bytes](https ### Common 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: +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). State transitions draw from the following common 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.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 | +| signature | array of bytes | 65 or 96 bytes | Signature of state transition data. Present on identity-signed and asset-lock-signed transitions (types 0-9, 13, and 18): 65 bytes for ECDSA signatures or 96 bytes for BLS signatures. | +| inputWitnesses | array | Varies | Address-ownership witnesses. Present on address-authorized transitions (types 10-15); may be empty when the transition has no address inputs. | +| spendAuthSig
bindingSignature | array of bytes | 64 bytes each | Orchard authorization carried by shielded transitions (types 15-20). `spendAuthSig` appears on each action; `bindingSignature` appears at the transition level. See [Shielded Transition Signing](shielded-pool.md#shielded-transition-signing). | :::{note} The [masternode vote](#masternode-vote) transition does not include the `userFeeIncrease` field. ::: -Additionally, all state transitions except the identity create and topup state transitions include: +Additionally, the identity-signed state transitions (types 0, 1, and 4-9) include: | Field | Type | Size | Description | | --------------- | -------------- | ---- |----------- | diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 2aee6cfc4..e8e0222f5 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -39,7 +39,7 @@ 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.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. | +| $groupContractPosition
$groupActionId
$groupActionIsProposer | unsigned integer
array
boolean | 16 bits
32 bytes
- | Optional group multi-party authentication info, flattened from [GroupStateTransitionInfo](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/group/mod.rs#L45-L54) so the three fields appear at the top level of the transition. All three are present together or absent together. Since protocol version 13, a transition confirming an existing group action must carry the same `$dataContractId` and `$tokenContractPosition` as the original proposal. | 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). @@ -160,7 +160,7 @@ 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.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) | +| 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 (binary `0` = PreProgrammed, `1` = Perpetual; JSON `"PreProgrammed"` or `"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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L21-L29). @@ -171,7 +171,7 @@ 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.1.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 (binary `0` = Pause, `1` = Resume; JSON `"pause"` or `"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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L19-L27). @@ -229,7 +229,7 @@ Each token set purchase price transition must comply with the [token set purchas ### Token Purchase Transition -The token purchase transition transfers a specified number of tokens to the purchasing identity. Platform simultaneously deducts the corresponding purchase cost in credits from the buyer’s balance as part of the state transition. A purchase must be accompanied by a credit transfer to the token seller’s identity in the same batch. If direct purchase history is enabled for the token, platform will create a record of this sale in the token’s history. +The token purchase transition mints the requested number of tokens to the purchasing identity. Platform simultaneously deducts the corresponding purchase cost in credits from the buyer’s balance as part of the state transition. The credits are moved from the purchaser to the contract owner by the purchase transition itself; no separate credit transfer is needed. Purchases that would push the total supply above `maxSupply` are rejected. If direct purchase history is enabled for the token, platform will create a record of this sale in the token’s history. Attempts to purchase tokens when no price is set, when providing insufficient payment, or below the minimum amount will be rejected by platform consensus. From c954cb5e58bdb60ed8d50129872261ecba199c67 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 14 Sep 2026 16:06:04 -0400 Subject: [PATCH 5/8] docs(protocol-ref): document protocol v14 shielded, index, and fee changes Add the Shield from Identity (type 21) and Identity Top Up From Shielded Pool (type 22) state transitions, along with their signing model and the identity transition type table. Document the timeRange `ttl` index option and its ephemeral fee rate, the FAILED withdrawal status for dust-threshold withdrawals, the portable math used for token distribution functions, and the reduced contested vote resolution fund. Add the new protocol constants and correct stale v4.2-dev line anchors. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/data-contract-document.md | 5 +- docs/protocol-ref/data-contract-token.md | 4 ++ docs/protocol-ref/data-trigger.md | 2 +- docs/protocol-ref/identity.md | 24 ++++--- docs/protocol-ref/protocol-constants.md | 9 ++- docs/protocol-ref/shielded-pool.md | 69 +++++++++++++++++++-- docs/protocol-ref/state-transition.md | 21 ++++--- 7 files changed, 105 insertions(+), 29 deletions(-) diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 4d0a78b8e..c9a3f59a7 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -180,7 +180,7 @@ The `indices` array consists of one or more objects that each contain: * An optional `contested` element that makes matching values on a unique index subject to a masternode vote instead of first-come ownership. See [Contested Indices](#contested-indices) * 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 * Optional ranked aggregate flags (added in 4.2.0) - `rankedCountable`, `rankedSummable`, and `rankedAverageable` - that enable top or bottom K queries on the index. See [Index-level flags](#index-level-flags). -* An optional `timeRange` object (added in 4.2.0) that buckets the index's first property into fixed-length time windows. Fields: `on` (required; the first index property, which must be `$createdAt`, `$updatedAt`, or `$transferredAt` and be listed in `required`), `range` (required; window length in seconds), `step` (required; seconds between window starts; `range` must be a multiple of `step`), and `phase` (optional; grid offset in seconds, less than `step` and less than 31536000; default 0). A `timeRange` index may be `unique` only when `range` equals `step` and `on` is `$createdAt`. It cannot be `contested` or set `nullSearchable: false`. +* An optional `timeRange` object (added in 4.2.0) that buckets the index's first property into fixed-length time windows. Fields: `on` (required; the first index property, which must be `$createdAt`, `$updatedAt`, or `$transferredAt` and be listed in `required`), `range` (required; window length in seconds), `step` (required; seconds between window starts; `range` must be a multiple of `step`), and `phase` (optional; grid offset in seconds, less than `step` and less than 31536000; default 0). An optional `ttl` (seconds) makes entries expire: an entry lives at most `ttl` seconds past the start of its window, plus a bounded cleanup lag, and expired windows cannot be queried. `ttl` must be at least `range` and at most 604,800 (one week) under protocol version 14; indexes that bucket the same field on the same grid must declare the same `ttl` or none. Bytes written under a `ttl` index are charged as processing at the [TTL ephemeral rate](protocol-constants.md#storage) instead of storage and are not refunded on removal. Omitted means entries live forever. A `timeRange` index may be `unique` only when `range` equals `step` and `on` is `$createdAt`. It cannot be `contested` or set `nullSearchable: false`. * An optional `skipIfAbsent` element (added in 4.2.0), only on `indexOnly` document types. When true, a document that omits the index's first property writes no entry into this index. That first property must be a top-level property that is not in `required`; every index that includes an optional property must be `skipIfAbsent` with that property first; every other property must still appear in at least one index that is not `skipIfAbsent`; and at least one index without `$createdAt` must not be `skipIfAbsent`. * An optional `terminal` element, only on `indexOnly` document types, naming the property whose value keys each index entry: `$ownerId` (default) or an identifier property with a `refersTo` of type `identity`, `contract`, `token`, or `permanentDocument`. It must not repeat one of the index's listed properties. * An optional `preallocated` element, only on `indexOnly` document types whose index properties are all either the referring property of a same-contract `permanentDocument` reference or a key of its `propertyAgreement`. When true, the index trees for entries referencing a document are created when that document is created. It cannot be combined with `timeRange`. @@ -228,7 +228,7 @@ Index objects do not accept any properties beyond those listed above. Starting w Contested unique indices provide a way for multiple identities to compete for ownership when a new document field matches a predefined pattern. This system enables fair distribution of valuable documents, such as [premium DPNS names](../explanations/dpns.md#conflict-resolution), through community-driven decision-making. -A two week contest begins when a match occurs. For the first week, additional contenders can join by paying a fee of 0.2 Dash. During this period, masternodes and evonodes vote on the outcome. The contest can result in the awarding of the document to the winner, a locked vote where no document is awarded, or potentially a restart of the contest if specific conditions are met. +A two week contest begins when a match occurs. For the first week, additional contenders can join by paying the [contested document vote resolution fund](protocol-constants.md#voting) fee (0.1 Dash from protocol version 14; 0.2 Dash in earlier versions). During this period, masternodes and evonodes vote on the outcome. The contest can result in the awarding of the document to the winner, a locked vote where no document is awarded, or potentially a restart of the contest if specific conditions are met. The table below describes the properties used to configure a contested index: @@ -269,6 +269,7 @@ For performance and security reasons, indices have the following constraints. Th | 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 `timeRange` overlap factor (`range / step`) (added in 4.2.0) | 24 | +| Maximum `timeRange` `ttl` (added in 4.2.0) | 604,800 seconds (1 week) | | 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.1.0/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L25) | diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md index 92d3b9733..4693f2418 100644 --- a/docs/protocol-ref/data-contract-token.md +++ b/docs/protocol-ref/data-contract-token.md @@ -491,6 +491,10 @@ Emits tokens in fixed amounts for specific intervals. - **Use Case:** Adjust rewards at specific milestones - **Example:** 100 tokens per block for first 1000 blocks, then 50 tokens thereafter +:::{note} +Starting with protocol version 14 (Dash Platform 4.2.0), the logarithmic, inverted logarithmic, exponential, and polynomial functions are evaluated with a fixed portable math library so every node computes the same reward. A client that predicts rewards with its own platform's math library may differ from the consensus amount by one unit on boundary inputs. +::: + ### Pre-Programmed Distribution Pre-programmed distribution allows scheduling specific token allocations at predetermined times. The following configuration distributes 3 sets of tokens to the same identity at the defined timestamps: diff --git a/docs/protocol-ref/data-trigger.md b/docs/protocol-ref/data-trigger.md index 959ddd2c3..b77ac2639 100644 --- a/docs/protocol-ref/data-trigger.md +++ b/docs/protocol-ref/data-trigger.md @@ -91,4 +91,4 @@ In addition to DPNS, the following system contracts have registered data trigger | Document | Action | Trigger Description | | ------------ | --------- | ------------------- | | `withdrawal` | `REPLACE` | Rejected by data trigger (withdrawal documents cannot be updated) | -| `withdrawal` | `DELETE` | Rejected unless status is `COMPLETE` | +| `withdrawal` | `DELETE` | Rejected unless status is `COMPLETE` or, from protocol version 14, `FAILED` (an expired withdrawal whose amount is below Core's dust threshold) | diff --git a/docs/protocol-ref/identity.md b/docs/protocol-ref/identity.md index c9380fc16..595d2cd7e 100644 --- a/docs/protocol-ref/identity.md +++ b/docs/protocol-ref/identity.md @@ -181,15 +181,21 @@ For all protocol constants, see [Protocol Constants](protocol-constants.md). ## Identity State Transition Details -There are five identity-related state transitions: [identity create](#identity-create), [identity topup](#identity-topup), [identity update](#identity-update), [identity credit transfer](#identity-credit-transfer), and [identity credit withdrawal](#identity-credit-withdrawal). Details are provided in this section including information about [asset locking](#asset-lock) and [signing](#identity-state-transition-signing) required for these state transitions. - -:::{note} -Protocol Version 11 introduced additional address-based identity operations. See [Address-Based State Transitions](address-system.md) for: - -- Identity Credit Transfer to Addresses (type 9) -- Identity Create from Addresses (type 10) -- Identity Top-Up from Addresses (type 11) -::: +The following state transitions create, fund, update, or transfer credits to or from identities. Five are documented on this page; this section also covers the relevant [asset-lock](#asset-lock) and [signing](#identity-state-transition-signing) mechanisms. The remaining transitions are documented with the feature they belong to. + +| Type | Name | Supported protocol versions | +| --- | --- | --- | +| 2 | [Identity Create](#identity-create) | ≥ 1 | +| 3 | [Identity Top-Up](#identity-topup) | ≥ 1 | +| 5 | [Identity Update](#identity-update) | ≥ 1 | +| 6 | [Identity Credit Withdrawal](#identity-credit-withdrawal) | ≥ 1 | +| 7 | [Identity Credit Transfer](#identity-credit-transfer) | ≥ 1 | +| 9 | [Identity Credit Transfer to Addresses](address-system.md#identity-credit-transfer-to-addresses) | ≥ 11 | +| 10 | [Identity Create from Addresses](address-system.md#identity-create-from-addresses) | ≥ 11 | +| 11 | [Identity Top-Up from Addresses](address-system.md#identity-top-up-from-addresses) | ≥ 11 | +| 20 | [Identity Create from Shielded Pool](shielded-pool.md#identity-create-from-shielded-pool) | ≥ 12 | +| 21 | [Shield from Identity](shielded-pool.md#shield-from-identity) | ≥ 14 | +| 22 | [Identity Top-Up from Shielded Pool](shielded-pool.md#identity-top-up-from-shielded-pool) | ≥ 14 | ### Identity Create diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 2a5dabe6c..3e4893f58 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -24,7 +24,11 @@ Maximum sizes and limits for various platform components. | 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 | 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 time-range overlap factor | 24 | **Added in 4.2.0.** Maximum `range / step` for a [timeRange](data-contract-document.md#document-indices) index, so at most 24 windows overlap at any timestamp | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L43) | +| Max time-range overlap factor | 24 | **Added in 4.2.0.** Maximum `range / step` for a [timeRange](data-contract-document.md#document-indices) index, so at most 24 windows overlap at any timestamp | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L65) | +| Max time-range TTL | 604,800 seconds (1 week) | **Added in 4.2.0.** Maximum `ttl` a [timeRange](data-contract-document.md#document-indices) index may declare | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L66) | +| Min time-range TTL drop operations per write | 32 | **Added in 4.2.0.** Minimum expired-entry cleanup operations Drive performs on each write into a `ttl` index | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L67) | +| Core dust relay fee | 3,000 duffs/kB | **Added in 4.2.0.** Used to compute the Core dust threshold of a withdrawal's output script (546 duffs for P2PKH). An expired withdrawal whose whole amount is below it is marked `FAILED` instead of being re-signed | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L54) | +| Min GroveDB proof envelope version | 1 | **Added in 4.2.0.** Clients verifying with protocol version 14 tables reject the legacy V0 proof envelope | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L68) | | 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) | @@ -108,6 +112,7 @@ Fees related to data storage operations. | 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) | +| TTL ephemeral disk usage (per byte) | 270 | **Added in 4.2.0.** Charged as processing for bytes written under a [timeRange `ttl`](data-contract-document.md#document-indices) index instead of the storage rate; not refunded on removal. [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/storage/v1.rs#L23) | #### Cryptographic Operations @@ -157,7 +162,7 @@ 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.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | +| Contested document vote resolution fund | **Updated in 4.2.0.**
Through protocol version 13: 20,000,000,000
Protocol version 14+: 10,000,000,000 | 0.2
0.1 | [through v13](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs), [v14+](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v2.rs#L6) | | 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) | diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index 07febb53f..1b397fd1d 100644 --- a/docs/protocol-ref/shielded-pool.md +++ b/docs/protocol-ref/shielded-pool.md @@ -22,8 +22,10 @@ The shielded pool is implemented through state transition types that share a com | 18 | [Shield from Asset Lock](#shield-from-asset-lock) | Move credits from an L1 asset lock directly into the pool | | 19 | [Shielded Withdrawal](#shielded-withdrawal) | Move credits from the pool back to Dash Core (L1) | | 20 | [Identity Create From Shielded Pool](#identity-create-from-shielded-pool) | Create a new identity funded from the shielded pool | +| 21 | [Shield from Identity](#shield-from-identity) | Move credits from an identity balance into the shielded pool (protocol version 14+) | +| 22 | [Identity Top Up From Shielded Pool](#identity-top-up-from-shielded-pool) | Move credits from the shielded pool to an existing identity's balance (protocol version 14+) | -All transitions share a common Orchard bundle (anchor, actions, proof, binding signature). Transitions that touch the transparent side (Shield, Unshield, Shield from Asset Lock, Shielded Withdrawal, Identity Create From Shielded Pool) layer the transparent fields on top of that bundle. Shielded Transfer has no transparent surface beyond the bundle itself. +All transitions share a common Orchard bundle (anchor, actions, proof, binding signature). Transitions that touch the transparent side (Shield, Unshield, Shield from Asset Lock, Shielded Withdrawal, Identity Create From Shielded Pool, Shield from Identity, Identity Top Up From Shielded Pool) layer the transparent fields on top of that bundle. Shielded Transfer has no transparent surface beyond the bundle itself. ## Common Components @@ -218,9 +220,63 @@ Protocol version 13 added 0.03 and 0.25 DASH and retired 0.3 DASH. The protocol 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). +### Shield from Identity + +:::{versionadded} 4.2.0 +Protocol version 14 added this transition. +::: + +Move credits from an identity's balance directly into the shielded pool. The transition is signed by the funding identity, like an [identity credit transfer](identity.md#identity-credit-transfer), and carries an outputs-only Orchard bundle like [Shield](#shield). The identity pays the fee plus the shielded amount. + +| Field | Type | Size | Description | +| --- | --- | --- | --- | +| identityId | array of bytes | 32 bytes | The [identity](identity.md#identity-id) whose balance funds the shield | +| amount | unsigned integer | 64 bits | Credits leaving the identity balance and entering the pool (the absolute value of the bundle's value balance) | +| actions | array | Varies | Orchard [actions](#actions). Spends are disabled; the actions create new notes | +| anchor | array of bytes | 32 bytes | [Anchor](#anchors) | +| proof | array of bytes | Varies | Halo 2 proof | +| bindingSignature | array of bytes | 64 bytes | RedPallas binding signature | +| nonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks | +| userFeeIncrease | unsigned integer | 16 bits | Extra fee to prioritize processing if the mempool is full | +| signaturePublicKeyId | unsigned integer | 32 bits | The `id` of the identity public key that signed the transition. Must be a CRITICAL key with the transfer purpose | +| signature | array of bytes | 65 or 96 bytes | Identity signature over the signable bytes: 65 bytes for ECDSA keys or 96 bytes for BLS keys | + +:::{note} +`signature` and `signaturePublicKeyId` are the only fields excluded from the signable bytes. The Orchard bundle uses empty `extra_sighash_data`; the identity signature binds the bundle to this identity and nonce. Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). + +**Constraints:** `amount` must be greater than zero and at most `i64::MAX`. The identity balance must cover `amount` plus the minimum shielded fee for the action count plus a 20-byte balance write at the storage rate. At execution the identity pays the metered fee plus the shielded compute fee (proof verification and per-action processing). A bundle that fails verification charges the proof failure penalty and bumps the identity nonce. +::: + +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_identity_transition/v0/mod.rs#L48-L69). + +### Identity Top Up From Shielded Pool + +:::{versionadded} 4.2.0 +Protocol version 14 added this transition. +::: + +Move credits from the shielded pool to an existing identity's balance. The spends consume shielded notes like [Unshield](#unshield), and the identity receives `topUpAmount` minus the fee. The fee is paid from the pool; there is no transition-level signature. + +| Field | Type | Size | Description | +| --- | --- | --- | --- | +| identityId | array of bytes | 32 bytes | The existing [identity](identity.md#identity-id) whose balance receives the top-up | +| actions | array | Varies | Orchard [actions](#actions) (spends consume shielded notes) | +| topUpAmount | unsigned integer | 64 bits | Gross credits leaving the pool (the bundle's value balance). The identity is credited `topUpAmount` minus the fee | +| anchor | array of bytes | 32 bytes | [Anchor](#anchors) | +| proof | array of bytes | Varies | Halo 2 proof | +| bindingSignature | array of bytes | 64 bytes | RedPallas binding signature | + +:::{note} +`identityId` and `topUpAmount` are bound to the Orchard bundle through the [platform sighash](#platform-sighash), so the top-up cannot be redirected to another identity. Maximum actions per transition: [`max_shielded_transition_actions`](protocol-constants.md). + +**Constraints:** `topUpAmount` must be greater than zero and at most `i64::MAX`, and the pool balance must cover it. The identity must exist; otherwise the transition fails with [`IdentityNotFoundError`](errors.md) (code 20000). The fee is the minimum shielded fee for the action count plus an 8-byte balance write at the storage rate. +::: + +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/identity_top_up_from_shielded_pool_transition/v0/mod.rs#L41-L54). + ## Shielded Transition Signing -Shielded transitions are not signed by an identity public key. The identity-signed `signature` and `signaturePublicKeyId` fields listed in the [common fields](state-transition.md#common-fields) for identity-signed transitions do not appear on any shielded transition. Authorization is instead carried by cryptographic primitives attached to the Orchard bundle and, where applicable, to the transparent side of the transition. This includes the asset-lock ECDSA `signature` carried by [Shield from Asset Lock](#shield-from-asset-lock) described below. +With one exception, shielded transitions are not signed by an identity public key, and the identity-signed `signature` and `signaturePublicKeyId` fields listed in the [common fields](state-transition.md#common-fields) do not appear on them. The exception is [Shield from Identity](#shield-from-identity), which the funding identity signs with a CRITICAL transfer key. Authorization is instead carried by cryptographic primitives attached to the Orchard bundle and, where applicable, to the transparent side of the transition. This includes the asset-lock ECDSA `signature` carried by [Shield from Asset Lock](#shield-from-asset-lock) described below. ### Orchard bundle signatures @@ -231,16 +287,17 @@ Every shielded transition includes: ### Platform sighash -Unshield, Shielded Withdrawal, and Identity Create From Shielded Pool bind their transparent fields to the Orchard bundle through the [platform sighash](#platform-sighash) (non-empty `extra_sighash_data`). Any modification to those transparent fields invalidates the Orchard signatures, preventing replay attacks that substitute transparent fields while reusing a valid bundle. Shield and Shield from Asset Lock use empty `extra_sighash_data`; their transparent side is authorized by address witnesses (Shield) or the asset-lock ECDSA signature (Shield from Asset Lock) over the signable bytes instead. +Unshield, Shielded Withdrawal, Identity Create From Shielded Pool, and Identity Top Up From Shielded Pool bind their transparent fields to the Orchard bundle through the [platform sighash](#platform-sighash) (non-empty `extra_sighash_data`). Any modification to those transparent fields invalidates the Orchard signatures, preventing replay attacks that substitute transparent fields while reusing a valid bundle. Shield, Shield from Asset Lock, and Shield from Identity use empty `extra_sighash_data`; their transparent side is authorized by address witnesses (Shield), the asset-lock ECDSA signature (Shield from Asset Lock), or the identity signature (Shield from Identity) over the signable bytes instead. -### Transparent signatures (Shield, Shield from Asset Lock) +### Transparent signatures -Two shielded transitions also carry transparent signatures over the transparent side of the transition: +Several shielded transitions also carry transparent signatures over the transparent side of the transition: - **Shield** includes an array of [address witnesses](address-system.md#address-witness) (`inputWitnesses`) — one per address input. Each witness proves control of its corresponding Platform address. Address witness signatures are excluded from the bytes that feed the platform sighash (they sign the platform sighash output, not vice-versa). - **Shield from Asset Lock** includes a 65-byte ECDSA `signature` proving control of the L1 asset-locked output, in the same form used by [Identity Create](identity.md#identity-create). The signature is excluded from the bytes that feed the platform sighash. +- **Shield from Identity** includes an identity `signature` and `signaturePublicKeyId`, in the same form used by [identity credit transfer](identity.md#identity-credit-transfer). Both are excluded from the signable bytes; the signature binds the Orchard bundle to the identity and nonce. -Shielded Transfer, Unshield, and Shielded Withdrawal have no transparent signatures; the Orchard bundle signatures plus the platform sighash provide full authorization. +Shielded Transfer, Unshield, Shielded Withdrawal, and Identity Top Up From Shielded Pool have no transparent signatures; the Orchard bundle signatures plus the platform sighash provide full authorization. ## Querying shielded state diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index e70d49518..8b977c608 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -28,15 +28,15 @@ The list of common fields used by multiple state transitions is defined in [rs-d | $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.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 or 96 bytes | Signature of state transition data. Present on identity-signed and asset-lock-signed transitions (types 0-9, 13, and 18): 65 bytes for ECDSA signatures or 96 bytes for BLS signatures. | +| signature | array of bytes | 65 or 96 bytes | Signature of state transition data. Present on identity-signed and asset-lock-signed transitions (types 0-9, 13, 18, and 21): 65 bytes for ECDSA signatures or 96 bytes for BLS signatures. | | inputWitnesses | array | Varies | Address-ownership witnesses. Present on address-authorized transitions (types 10-15); may be empty when the transition has no address inputs. | -| spendAuthSig
bindingSignature | array of bytes | 64 bytes each | Orchard authorization carried by shielded transitions (types 15-20). `spendAuthSig` appears on each action; `bindingSignature` appears at the transition level. See [Shielded Transition Signing](shielded-pool.md#shielded-transition-signing). | +| spendAuthSig
bindingSignature | array of bytes | 64 bytes each | Orchard authorization carried by shielded transitions (types 15-22). `spendAuthSig` appears on each action; `bindingSignature` appears at the transition level. See [Shielded Transition Signing](shielded-pool.md#shielded-transition-signing). | :::{note} The [masternode vote](#masternode-vote) transition does not include the `userFeeIncrease` field. ::: -Additionally, the identity-signed state transitions (types 0, 1, and 4-9) include: +Additionally, the identity-signed state transitions (types 0, 1, 4-9, and 21) include: | Field | Type | Size | Description | | --------------- | -------------- | ---- |----------- | @@ -69,6 +69,8 @@ Dash Platform Protocol defines the following [state transition types](https://gi | 18 | Shield from Asset Lock | [Shield from Asset Lock](shielded-pool.md#shield-from-asset-lock) | | 19 | Shielded Withdrawal | [Shielded Withdrawal](shielded-pool.md#shielded-withdrawal) | | 20 | Identity Create From Shielded Pool | [Identity Create From Shielded Pool](shielded-pool.md#identity-create-from-shielded-pool) | +| 21 | Shield from Identity | [Shield from Identity](shielded-pool.md#shield-from-identity) (added in 4.2.0) | +| 22 | Identity Top Up From Shielded Pool | [Identity Top Up From Shielded Pool](shielded-pool.md#identity-top-up-from-shielded-pool) (added in 4.2.0) | ### Batch @@ -99,14 +101,14 @@ transition type: | Signing Method | State Transitions | | -------------- | ----------------- | -| [Identity](#signing-with-identity) | Batch, Contract create, Contract update, Identity update, Identity credit transfer, Identity credit transfer to addresses, Identity credit withdrawal, Masternode vote | +| [Identity](#signing-with-identity) | Batch, Contract create, Contract update, Identity update, Identity credit transfer, Identity credit transfer to addresses, Identity credit withdrawal, Masternode vote, Shield from identity\*\* | | [Asset lock](#signing-with-asset-lock) | Identity create, Identity topup, Address funding from asset lock\*, Shield from asset lock\*\* | | [Address witness](#signing-with-address-witness) | Identity create from addresses, Identity topup from addresses, Address funds transfer, Address credit withdrawal, Address funding from asset lock\*, Shield\*\* | -| [Shielded (Orchard)](shielded-pool.md#shielded-transition-signing) | Shield\*\*, Shielded transfer, Unshield, Shield from asset lock\*\*, Shielded withdrawal, Identity create from shielded pool | +| [Shielded (Orchard)](shielded-pool.md#shielded-transition-signing) | Shield\*\*, Shielded transfer, Unshield, Shield from asset lock\*\*, Shielded withdrawal, Identity create from shielded pool, Shield from identity\*\*, Identity top up from shielded pool | \* Address funding from asset lock requires both an asset lock signature and address witnesses (`input_witnesses`). -\*\* Shielded transitions are always authorized by Orchard bundle signatures (per-action `spendAuthSig` plus the transition-level `bindingSignature`). Shield additionally carries address witnesses for its transparent address inputs; Shield from asset lock additionally carries an asset-lock ECDSA signature. +\*\* Shielded transitions are always authorized by Orchard bundle signatures (per-action `spendAuthSig` plus the transition-level `bindingSignature`). Shield additionally carries address witnesses for its transparent address inputs; Shield from asset lock additionally carries an asset-lock ECDSA signature; Shield from identity additionally carries an identity signature (`signature` and `signaturePublicKeyId`) made with a CRITICAL transfer key. :::{note} Address-based state transitions (types 9-14) were introduced in Protocol Version 11. For detailed information on these transitions, see [Address-Based State Transitions](address-system.md). @@ -137,7 +139,7 @@ requires at least a CRITICAL key (level `1`). | State transition | Accepted security level(s) | | ---------------- | -------------------------- | | Identity update | MASTER (`0`) | -| Identity credit transfer, Identity credit withdrawal, Data contract update | CRITICAL (`1`) | +| Identity credit transfer, Identity credit withdrawal, Data contract update, Shield from identity | CRITICAL (`1`) | | Data contract create | CRITICAL or HIGH (`1`-`2`) | | Batch (document/token), Masternode vote | CRITICAL, HIGH, or MEDIUM (`1`-`3`) | @@ -187,7 +189,7 @@ Public keys can be added to an identity by the identity create or identity updat ### Signing Shielded Transitions -Shielded transitions are not signed by an identity public key or an address private key at the transition level — they do not include `signature` or `signaturePublicKeyId` fields. Authorization is carried instead by Orchard primitives attached to each action and to the bundle as a whole. Shield additionally carries [address witnesses](#signing-with-address-witness) over its address inputs, and Shield from asset lock additionally carries an [asset-lock ECDSA signature](#signing-with-asset-lock). Both `input_witnesses` (on Shield) and `signature` (on Shield from asset lock) are omitted from the bytes that feed the platform sighash. +With one exception, shielded transitions are not signed by an identity public key or an address private key at the transition level and do not include `signature` or `signaturePublicKeyId` fields. The exception is Shield from identity, which is signed by the funding identity like an identity credit transfer; only its `signature` and `signaturePublicKeyId` are excluded from the signable bytes. Authorization is carried instead by Orchard primitives attached to each action and to the bundle as a whole. Shield additionally carries [address witnesses](#signing-with-address-witness) over its address inputs, and Shield from asset lock additionally carries an [asset-lock ECDSA signature](#signing-with-asset-lock). Both `input_witnesses` (on Shield) and `signature` (on Shield from asset lock) are omitted from the bytes that feed the platform sighash. See [Shielded Transition Signing](shielded-pool.md#shielded-transition-signing) for the full signing model. @@ -206,7 +208,8 @@ This table shows the fields that must be excluded when creating state transition | [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 | +| [Shield from identity](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_identity_transition/v0/mod.rs#L66-L69) | 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). +The table above does not cover the shielded transitions other than Shield from identity, which do not carry transition-level `signature` or `signaturePublicKeyId` fields. See [Signing Shielded Transitions](#signing-shielded-transitions). ::: From ab229a0e3c6ef7a434422225c26a027719f35941 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 14 Sep 2026 16:18:14 -0400 Subject: [PATCH 6/8] docs(protocol-ref): restructure the document indices section Split the index field bullet list into required and optional field tables, and move the longer options into their own subsections: time-range indices, index-only options, and contested indices. Relocate the DPNS example to follow the JSON template instead of trailing the constraints table. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/data-contract-document.md | 122 ++++++++++++++------ 1 file changed, 84 insertions(+), 38 deletions(-) diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index c9a3f59a7..0fe95fba0 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -164,29 +164,42 @@ There are a variety of constraints currently defined for performance and securit ## Document Indices -Document indices may be defined if indexing on document fields is required. The `indices` object should only be included for documents with at least one index. - -The `indices` array consists of one or more objects that each contain: - -* A unique `name` for the index -* A `properties` array composed of a `` object for each document field that is part of the index (only `asc` is currently supported) - - :::{admonition} Compound Indices - :class: attention - When defining an index with multiple properties, the ordering of properties is important. Refer to the [mongoDB documentation](https://docs.mongodb.com/manual/core/index-compound/#prefixes) for details. Dash uses [GroveDB](https://github.com/dashpay/grovedb), which works similarly but requires listing all the index's fields in query order by statements. - ::: -* 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 makes matching values on a unique index subject to a masternode vote instead of first-come ownership. See [Contested Indices](#contested-indices) -* 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 -* Optional ranked aggregate flags (added in 4.2.0) - `rankedCountable`, `rankedSummable`, and `rankedAverageable` - that enable top or bottom K queries on the index. See [Index-level flags](#index-level-flags). -* An optional `timeRange` object (added in 4.2.0) that buckets the index's first property into fixed-length time windows. Fields: `on` (required; the first index property, which must be `$createdAt`, `$updatedAt`, or `$transferredAt` and be listed in `required`), `range` (required; window length in seconds), `step` (required; seconds between window starts; `range` must be a multiple of `step`), and `phase` (optional; grid offset in seconds, less than `step` and less than 31536000; default 0). An optional `ttl` (seconds) makes entries expire: an entry lives at most `ttl` seconds past the start of its window, plus a bounded cleanup lag, and expired windows cannot be queried. `ttl` must be at least `range` and at most 604,800 (one week) under protocol version 14; indexes that bucket the same field on the same grid must declare the same `ttl` or none. Bytes written under a `ttl` index are charged as processing at the [TTL ephemeral rate](protocol-constants.md#storage) instead of storage and are not refunded on removal. Omitted means entries live forever. A `timeRange` index may be `unique` only when `range` equals `step` and `on` is `$createdAt`. It cannot be `contested` or set `nullSearchable: false`. -* An optional `skipIfAbsent` element (added in 4.2.0), only on `indexOnly` document types. When true, a document that omits the index's first property writes no entry into this index. That first property must be a top-level property that is not in `required`; every index that includes an optional property must be `skipIfAbsent` with that property first; every other property must still appear in at least one index that is not `skipIfAbsent`; and at least one index without `$createdAt` must not be `skipIfAbsent`. -* An optional `terminal` element, only on `indexOnly` document types, naming the property whose value keys each index entry: `$ownerId` (default) or an identifier property with a `refersTo` of type `identity`, `contract`, `token`, or `permanentDocument`. It must not repeat one of the index's listed properties. -* An optional `preallocated` element, only on `indexOnly` document types whose index properties are all either the referring property of a same-contract `permanentDocument` reference or a key of its `propertyAgreement`. When true, the index trees for entries referencing a document are created when that document is created. It cannot be combined with `timeRange`. +Document indices may be defined if indexing on document fields is required. The `indices` array should only be included for documents with at least one index. + +### Required Index Fields + +Each object in the `indices` array requires two fields: + +| Field | Description | +| --- | --- | +| `name` | A unique name for the index. | +| `properties` | An ordered array containing one `` object for each indexed document field. Only `asc` is currently supported. | + +:::{admonition} Compound Indices +:class: attention +When defining an index with multiple properties, the ordering of properties is important. Refer to the [mongoDB documentation](https://docs.mongodb.com/manual/core/index-compound/#prefixes) for details. Dash uses [GroveDB](https://github.com/dashpay/grovedb), which works similarly but requires listing all the index's fields in query order by statements. +::: + +### Optional Index Fields + +In addition to `name` and `properties`, an index may contain the following optional fields: + +| Option | Purpose | Details | +| --- | --- | --- | +| `unique` | Determines whether duplicate values are allowed. | Defaults to `false`. | +| `nullSearchable` | Determines whether the index includes entries whose properties are all null. | Defaults to `true`. When `false`, no reference is added if all indexed properties are null. | +| `contested` | Makes matching values on a unique index subject to a masternode vote instead of first-come ownership. | See [Contested Indices](#contested-indices). | +| Aggregate flags | Enable count, sum, and average fast paths. | `countable`, `rangeCountable`, `summable`, `rangeSummable`, `averageable`, and `rangeAverageable`. See [Aggregate Query Flags](#aggregate-query-flags). | +| Ranked aggregate flags | Enable top or bottom K queries. Added in 4.2.0. | `rankedCountable`, `rankedSummable`, and `rankedAverageable`. See [Index-level Flags](#index-level-flags). | +| `timeRange` | Buckets the first index property into fixed-length time windows. Added in 4.2.0. | See [Time-Range Indices](#time-range-indices). | +| `skipIfAbsent` | Omits an index entry when the first property is absent. Added in 4.2.0. | Available only on `indexOnly` document types. See [Index-Only Options](#index-only-options). | +| `terminal` | Selects the value that keys each index entry. Added in 4.2.0. | Available only on `indexOnly` document types. See [Index-Only Options](#index-only-options). | +| `preallocated` | Creates index trees before referenced documents produce entries. Added in 4.2.0. | Available only on `indexOnly` document types. See [Index-Only Options](#index-only-options). | Index objects do not accept any properties beyond those listed above. Starting with Dash Platform 4.2.0 (protocol version 14), index objects also accept the ranked aggregate keywords, `timeRange`, and the `indexOnly`-specific keywords `terminal`, `preallocated`, and `skipIfAbsent`. Under earlier protocol versions those keywords are rejected. +The following template shows the required shape and commonly used optional fields: + :::{code-block} json :force: @@ -224,7 +237,57 @@ Index objects do not accept any properties beyond those listed above. Starting w ] ::: -### Contested Indices +**Example** + +The following example (excerpt from the DPNS contract's `preorder` document) creates an index named `saltedHash` on the `saltedDomainHash` property and enforces uniqueness across all documents of that type: + +```json +"indices": [ + { + "name": "saltedHash", + "properties": [ + { + "saltedDomainHash": "asc" + } + ], + "unique": true + } +] +``` + +#### Time-Range Indices + +:::{versionadded} 4.2.0 +Protocol version 14 added time-range indices. +::: + +The optional `timeRange` object buckets an index's first property into fixed-length time windows. It contains the following fields: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `on` | string | Yes | The first index property. It must be `$createdAt`, `$updatedAt`, or `$transferredAt` and must be listed in the document type's `required` array. | +| `range` | integer | Yes | Window length in seconds. It must be a multiple of `step`. | +| `step` | integer | Yes | Number of seconds between window starts. | +| `phase` | integer | No | Grid offset in seconds. It must be less than `step` and less than 31,536,000. Defaults to `0`. | +| `ttl` | integer | No | Entry lifetime in seconds, measured from the start of its window. It must be at least `range` and, under protocol version 14, at most 604,800 (one week). Omit it for entries that live forever. | + +When `ttl` is set, an entry lives at most `ttl` seconds past the start of its window, plus a bounded cleanup lag. Expired windows cannot be queried. Indexes that bucket the same field on the same grid must all declare the same `ttl`, or all omit it. + +Bytes written under a `ttl` index are charged as processing at the [TTL ephemeral rate](protocol-constants.md#storage) instead of storage and are not refunded on removal. + +A time-range index may be `unique` only when `range` equals `step` and `on` is `$createdAt`. It cannot be `contested`, set `nullSearchable` to `false`, or be combined with `preallocated`. + +#### Index-Only Options + +The following options are available only on document types with [`indexOnly: true`](#document-configuration): + +| Option | Behavior and constraints | +| --- | --- | +| `skipIfAbsent` | When true, a document that omits the index's first property writes no entry into this index. The first property must be a top-level property that is not in `required`, and every index containing an optional property must place that property first and set `skipIfAbsent`. Every other property must still appear in at least one index without `skipIfAbsent`, and at least one index without `$createdAt` must not use `skipIfAbsent`. | +| `terminal` | Names the property whose value keys each index entry. It may be `$ownerId` (the default) or an identifier property with a `refersTo` type of `identity`, `contract`, `token`, or `permanentDocument`. It must not repeat an index property. | +| `preallocated` | Creates the index trees for entries referencing a document when that document is created. Every index property must be either the referring property of a same-contract `permanentDocument` reference or a key of its `propertyAgreement`. It cannot be combined with `timeRange`. | + +#### Contested Indices Contested unique indices provide a way for multiple identities to compete for ownership when a new document field matches a predefined pattern. This system enables fair distribution of valuable documents, such as [premium DPNS names](../explanations/dpns.md#conflict-resolution), through community-driven decision-making. @@ -279,23 +342,6 @@ For performance and security reasons, indices have the following constraints. Th For all protocol constants, see [Protocol Constants](protocol-constants.md). ::: -**Example** -The following example (excerpt from the DPNS contract's `preorder` document) creates an index named `saltedHash` on the `saltedDomainHash` property that also enforces uniqueness across all documents of that type: - -```json -"indices": [ - { - "name": "saltedHash", - "properties": [ - { - "saltedDomainHash": "asc" - } - ], - "unique": true - } -] -``` - ## Document Configuration Documents support the following configuration options to provide flexibility in contract design. Only include configuration options in a data contract when using non-default values. From 467801e62671f6357d6f06684b85e0cd70907961 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 15 Sep 2026 12:14:00 -0400 Subject: [PATCH 7/8] docs(explanations): correct protocol behavior and document v14 additions Fix stale or imprecise descriptions of DPNS pre-orders, credit conversion, read-only contracts, asset lock proofs, and token configuration defaults. Document the shielded pool identity transitions, index-only document delete, and the $price base field added in protocol version 14. Co-Authored-By: Claude Opus 5 (1M context) --- docs/explanations/dpns.md | 2 +- docs/explanations/drive-platform-chain.md | 2 +- docs/explanations/fees.md | 2 +- docs/explanations/identity.md | 6 +++--- .../platform-protocol-data-contract.md | 2 +- .../platform-protocol-data-trigger.md | 2 +- .../platform-protocol-document.md | 19 +++++++++++++------ .../platform-protocol-state-transition.md | 6 ++++-- docs/explanations/proofs.md | 4 ++-- docs/explanations/shielded-pool.md | 12 ++++++++++-- docs/explanations/tokens.md | 12 ++++++------ 11 files changed, 43 insertions(+), 26 deletions(-) diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index 696824101..89e5df04c 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -29,7 +29,7 @@ To prevent [front-running](https://en.wikipedia.org/wiki/Domain_name_front_runni #### Domain pre-order -In the pre-order phase, the domain name is salted to obscure the actual domain name being registered (e.g. `hash('alice.dash' + salt)`) and submitted to platform. This is done to prevent masternodes from seeing the names being registered and "stealing" them for later resale. Once the pre-order document has been accepted by Platform, the registration can proceed. +In the pre-order phase, a random 32-byte salt is placed in front of the normalized domain name and the pair is hashed with a double SHA-256 (e.g. the hash of the salt followed by `a11ce.dash`). Only that hash is submitted to Platform, preventing observers from identifying the requested name and front-running its registration. Once the pre-order document has been accepted by Platform, the registration can proceed. #### Domain registration diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md index 0725c32f2..0217faba1 100644 --- a/docs/explanations/drive-platform-chain.md +++ b/docs/explanations/drive-platform-chain.md @@ -26,4 +26,4 @@ In order to support Dash Platform's performance requirements, the platform chain ### Blocks and Transitions -Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among all masternodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by more than two-thirds of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations. +Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among evonodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by more than two-thirds of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations. diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index f1bb2a6d4..fc22ff06b 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -58,7 +58,7 @@ An in-depth look at the Fee Multiplier can be found at **link** In an attempt to minimize Dash Platform's storage requirements, users are incentivized to remove data that they no longer want to be stored in the Dash Platform state for a refund. Data storage fees are distributed to masternodes over the data's lifetime which is 50 years for permanent storage. Therefore, at any time before the data's fees are entirely distributed, there will be fees remaining which can be refunded to the user if they decide to delete the data. -Distribution is front-loaded rather than spread evenly across those 50 years, so the refundable remainder falls fastest in the early years. Removals below a small minimum byte threshold are not refunded at all. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the distribution schedule and the refund threshold. +Distribution is front-loaded rather than spread evenly across those 50 years, so the refundable remainder falls fastest in the early years. Removals below a small minimum byte threshold are not refunded at all. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the storage era counts and the refund threshold. ## Minimum and Fixed Fees diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index 9c8b95d1d..2fca4a35d 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -20,7 +20,7 @@ In order to [create an identity](#identity-create-process), a user pays the netw Once an identity is created, its credit balance is used to pay for activity (e.g. use of applications). The [topup process](#identity-balance-topup-process) provides a way to add additional funds to the balance when necessary. -Locking Dash on layer 1 is the primary funding route, but it is not the only one. An identity can also be created or topped up from credits already held at a [Platform address](../protocol-ref/address-system.md), or created directly from the [shielded pool](./shielded-pool.md) by spending shielded notes. Both routes fund the identity entirely on layer 2, without a Core chain asset lock. +Locking Dash on layer 1 is the primary funding route, but it is not the only one. An identity can also be created or topped up from credits already held at a [Platform address](../protocol-ref/address-system.md), or created and topped up directly from the [shielded pool](./shielded-pool.md) by spending shielded notes. Both routes fund the identity entirely on layer 2, without a Core chain asset lock. The processes below describe the Core-chain asset-lock path. For the layer 2 paths, see [Identity Create From Addresses](../protocol-ref/address-system.md#identity-create-from-addresses), @@ -35,7 +35,7 @@ On Testnet, a [test Dash faucet](https://faucet.testnet.networks.dash.org/) is a First, the user creates an asset lock transaction on the Core chain with one or more outputs that lock Dash funds for use on Platform. An asset lock proof is then obtained for that transaction - either an InstantSend lock proof (for fast confirmation) or a ChainLock-based proof once the transaction is included in a ChainLocked block. -The user then submits an [identity create state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-create-transition) referencing the asset lock proof and the public keys to register for the new identity. The locked value (minus fees) becomes the new identity's initial credit balance. +The user then submits an [identity create state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-create-transition) referencing the asset lock proof and the public keys to register for the new identity. The locked value, minus fees, is converted to credits and becomes the new identity's initial balance. Application-layer flows where a third party funds an identity on behalf of another user are possible by having that third party create the asset lock transaction and share the resulting proof, but this is a client-side convention rather than a protocol-level invitation mechanism. @@ -77,7 +77,7 @@ Note: the payout key is associated with the masternode owner identity, so both t ## Credits -Credits provide the mechanism for paying fees that cover the cost of platform usage. Once a user locks Dash on the core blockchain and proves ownership of the locked value in an identity create or topup state transition, their credit balance increases by that amount. Credits can also reach an identity from a [Platform address](../protocol-ref/address-system.md) or the [shielded pool](./shielded-pool.md) without a layer 1 lock. As they perform platform actions, these credits are deducted to pay the associated fees. +Credits provide the mechanism for paying fees that cover the cost of platform usage. Once a user locks Dash on the core blockchain and proves ownership of the locked value in an identity create or topup state transition, that value is converted to credits and added to their balance, with each duff of locked Dash becoming 1000 credits. Credits can also reach an identity from a [Platform address](../protocol-ref/address-system.md) or the [shielded pool](./shielded-pool.md) without a layer 1 lock. As they perform platform actions, these credits are deducted to pay the associated fees. Credits are not locked to the identity that holds them: an identity can transfer credits directly to another identity, or to a [Platform address](../protocol-ref/address-system.md), using the corresponding [state transitions](../explanations/platform-protocol-state-transition.md). diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md index 640a22ba5..6c638ff24 100644 --- a/docs/explanations/platform-protocol-data-contract.md +++ b/docs/explanations/platform-protocol-data-contract.md @@ -57,7 +57,7 @@ The drawing below illustrates the steps an application developer follows to comp ### Updates -Existing data contracts can be updated by their owner in backwards-compatible ways. Updates are applied by submitting a data contract update state transition and are validated to preserve compatibility with previously stored documents. +Existing data contracts can be updated by their owner in backwards-compatible ways, unless they were registered as read-only. Read-only status is permanent and can only be set at registration. See [Contract Configuration](../reference/data-contracts.md#contract-configuration) for details. Updates are applied by submitting a data contract update state transition and are validated to preserve compatibility with previously stored documents. Permitted changes include: diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index 1842c7bfc..8d8ddccef 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -45,6 +45,6 @@ In addition to DPNS, Drive ships data triggers for a small set of other system c | Masternode Rewards | `rewardShare` | [`CREATE`/`REPLACE`/`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) | Rejects all three actions so ordinary identities cannot write reward share records | | ---- | ---- | ---- | ---- | | Withdrawals | `withdrawal` | [`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 direct external mutation of withdrawal documents | -| Withdrawals | `withdrawal` | [`DELETE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/withdrawals) | Allows deletion only once the withdrawal has reached `COMPLETE` status | +| Withdrawals | `withdrawal` | [`DELETE`](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/withdrawals) | Allows deletion in `COMPLETE` status, and from protocol version 14 also in terminal `FAILED` status | When document state transitions are received, Drive checks if there is a trigger associated with the document type and action. If a trigger is found, Drive executes the trigger logic. Successful execution of the trigger logic is necessary for the document to be accepted and applied to the [platform state](../explanations/drive-platform-state.md). diff --git a/docs/explanations/platform-protocol-document.md b/docs/explanations/platform-protocol-document.md index cfb69d21a..035008755 100644 --- a/docs/explanations/platform-protocol-document.md +++ b/docs/explanations/platform-protocol-document.md @@ -16,7 +16,7 @@ Most document types store each document as a JSON body with the base fields desc ### Base Fields -Dash Platform Protocol (DPP) defines a set of base fields that must be present in all documents. For the [reference implementation](https://github.com/dashpay/platform/tree/master/packages/rs-dpp), the base fields shown below are defined in the [document base fields](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/document/fields.rs). +Dash Platform Protocol (DPP) defines a set of base fields that may appear on documents. For the [reference implementation](https://github.com/dashpay/platform/tree/master/packages/rs-dpp), the base fields shown below are defined in the [document base fields](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/document/fields.rs). | Field Name | Description | | - | - | @@ -34,12 +34,19 @@ Dash Platform Protocol (DPP) defines a set of base fields that must be present i | $createdAtCoreBlockHeight | Core block height when the document was created | | $updatedAtCoreBlockHeight | Core block height when the document was last updated | | $transferredAtCoreBlockHeight | Core block height when the document was last transferred | -| $creatorId | [Identity](../explanations/identity.md) that originally created the document (32 bytes). Present on document types that are transferable or have a trade mode set, and preserved when ownership changes | -| $contractVersion | Version of the data contract the document was last written under, used to determine which properties were required at that time. Present on documents written since protocol version 14; this is what allows a contract update to add a required property without invalidating older documents | +| $price | Current listing price in credits | +| $creatorId | [Identity](../explanations/identity.md) that originally created the document (32 bytes) | +| $contractVersion | Version of the data contract the document was last written under | -:::{attention} -The timestamp and block height fields will only be present in documents that add them to the list of [required properties](../reference/data-contracts.md#required-properties). -::: +#### Field availability + +Timestamp and block height fields are present only when included in the document type's [required properties](../reference/data-contracts.md#required-properties). + +`$price` is present only while a document whose trade mode supports seller-set pricing is listed, and is cleared when the document is purchased or transferred. `$creatorId` is present on transferable or tradeable document types and is preserved when ownership changes. + +Since protocol version 14, `$contractVersion` records which contract version supplied the document's required properties. This allows contract updates to add required properties without invalidating older documents. + +`$type` and `$dataContractId` identify the document rather than being stored with its data. Platform supplies them when the document is fetched. ### Data Contract Fields diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md index ff2a1d8e3..91b37e431 100644 --- a/docs/explanations/platform-protocol-state-transition.md +++ b/docs/explanations/platform-protocol-state-transition.md @@ -32,7 +32,7 @@ To support the various data types used on the platform and enable future updates 2. Payload - contents vary depending on payload type 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) 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. +Authorization varies by transition family. Transitions submitted by an identity are signed with one of that identity's keys. Transitions that spend from [Platform addresses](../protocol-ref/address-system.md) instead use a witness signature for each address input. [Shielded pool](../explanations/shielded-pool.md) transitions use the authorization included in their shielded actions and, where applicable, address witnesses or an asset-lock signature. Shield from Identity is also signed by the identity whose balance supplies the credits. The following table contains a list of currently defined payload types: @@ -59,12 +59,14 @@ The following table contains a list of currently defined payload types: | [Shield From Asset Lock](../protocol-ref/shielded-pool.md#shield-from-asset-lock) (`18`) | Fund the shielded pool directly from an asset lock proof | | [Shielded Withdrawal](../protocol-ref/shielded-pool.md#shielded-withdrawal) (`19`) | Withdraw funds from the shielded pool to Dash Core (L1) | | [Identity Create From Shielded Pool](../protocol-ref/shielded-pool.md#identity-create-from-shielded-pool) (`20`) | Create a new identity funded from the shielded pool | +| [Shield from Identity](../protocol-ref/shielded-pool.md#shield-from-identity) (`21`) | Move credits from an identity balance into the [shielded pool](../explanations/shielded-pool.md) | +| [Identity Top Up From Shielded Pool](../protocol-ref/shielded-pool.md#identity-top-up-from-shielded-pool) (`22`) | Add credits to an existing identity from the shielded pool | ### Batch transitions Batch transitions (payload type `1`) carry either document or token actions: -- **Document actions** — create, replace, delete, transfer, purchase, and update price. See [Document](../explanations/platform-protocol-document.md) for details. +- **Document actions** — create, replace, delete, transfer, purchase, update price, and, from protocol version 14, index-only delete for index-only document types. See [Document](../explanations/platform-protocol-document.md) for details. - **Token actions** — mint, burn, transfer, freeze/unfreeze, claim, direct purchase, and set price, along with administrative actions. See [Tokens](../explanations/tokens.md) for details. ### Application Usage diff --git a/docs/explanations/proofs.md b/docs/explanations/proofs.md index dd67ba13f..520a771dd 100644 --- a/docs/explanations/proofs.md +++ b/docs/explanations/proofs.md @@ -158,7 +158,7 @@ Proof verification also detects proof-of-absence, confirming when requested data ## Asset Lock Proofs -Asset lock proofs are a special category used when creating or funding [identities](../explanations/identity.md). They prove that Dash has been locked on the core blockchain (layer 1) to establish credits on Dash Platform (layer 2). +Asset lock proofs are a special category used when bringing Dash onto Platform. They prove that Dash has been locked on the core blockchain (layer 1) to establish credits on Dash Platform (layer 2). The credits can fund an [identity](../explanations/identity.md), a [Platform address](../protocol-ref/address-system.md), or the [shielded pool](../explanations/shielded-pool.md). ### Instant Asset Lock Proof @@ -181,7 +181,7 @@ Uses ChainLocks to prove funds are locked at a specific core blockchain height: This method is used when InstantSend confirmation is not available. :::{attention} -Asset lock proofs are verified by the network during identity creation and topup state transitions. The locked funds cannot be spent on the core chain once used to create platform credits. +Asset lock proofs are verified by the network during identity creation and topup, Platform address funding, and shielding directly from an asset lock. The locked funds cannot be spent on the core chain once used to create platform credits. ::: ## Related Topics diff --git a/docs/explanations/shielded-pool.md b/docs/explanations/shielded-pool.md index a7c37b4d0..c26998632 100644 --- a/docs/explanations/shielded-pool.md +++ b/docs/explanations/shielded-pool.md @@ -46,9 +46,9 @@ A shielded transition is composed of one or more **actions**. Each action struct ## Transition types -Six state transition types interact with the shielded pool. The wire-level structure of each — including field-by-field tables and source links — is documented in the [Shielded Pool protocol reference](../protocol-ref/shielded-pool.md). +Several state transition types interact with the shielded pool. The wire-level structure of each — including field-by-field tables and source links — is documented in the [Shielded Pool protocol reference](../protocol-ref/shielded-pool.md). -Consensus gates every transition that moves credits *out of* the pool on the pool holding a minimum number of encrypted notes. This is not a soft privacy recommendation: until the pool reaches that size, unshields, shielded withdrawals, and identity creation from the pool are rejected outright. The gate exists so that exits always draw from a meaningful anonymity set, but its practical effect is that funds shielded into a young or lightly used pool cannot leave it immediately. The threshold is given in the [Shielded Pool protocol reference](../protocol-ref/shielded-pool.md). +Consensus gates every transition that moves credits *out of* the pool on the pool holding a minimum number of encrypted notes. This is not a soft privacy recommendation: until the pool reaches that size, unshields, shielded withdrawals, identity creation from the pool, and identity top-ups from the pool are rejected outright. The gate exists so that exits always draw from a meaningful anonymity set, but its practical effect is that funds shielded into a young or lightly used pool cannot leave it immediately. The threshold is given in the [Shielded Pool protocol reference](../protocol-ref/shielded-pool.md). ### Shield @@ -78,6 +78,14 @@ The funding amount cannot be chosen freely: it must be one of a small fixed set The notes being spent do not have to add up to the chosen denomination exactly - any excess is returned to the pool as a new note, so change stays shielded. If identity creation then fails a stateful check, the denomination still leaves the pool: it lands, less a penalty, at a fallback Platform address named in the transition. +### Shield from identity + +Moves credits *into* the pool from an identity's balance, without first moving them to a Platform address. Available from protocol version 14. + +### Identity top up from shielded pool + +Moves credits *out of* the pool into the balance of an identity that already exists. Like an unshield, the amount and the destination identity are visible; only the source notes stay private. Available from protocol version 14. + ## What the pool does not provide - **Anonymity sets**: The privacy guarantee depends on how many other notes exist in the pool. A pool with a single user offers limited cover; privacy improves as more users participate. diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index e14f18296..20007ba35 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -112,16 +112,16 @@ When creating a token, you define its configuration using the following paramete |:------------------------|:------------------|:--------| | Description | **No** | None | | [Conventions](#display-conventions) | Yes | Required; must include English | -| [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** | [0](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L48) | +| [Decimal precision](#display-conventions)| Yes | [8](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs#L57) | +| [Base supply](#token-supply) | **No** | [0](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L47) | | [Maximum supply](#token-supply) | Yes | None | | [Keep history](#history) | **No** | True (all history types) | | [Start paused](#initial-state) | **No** | False | | [Allow transfer to frozen balance](#allow-transfer-to-frozen-balance) | **No** | True | | [Main control group](#main-control-group)| Yes | None | | Main control group can be modified | **No** | NoOne | -| Marketplace rules | Yes | None | -| [Distribution rules](#distribution-rules)| Yes | None | +| Marketplace rules | Yes | NotTradeable | +| [Distribution rules](#distribution-rules)| Yes (pre-programmed schedule excluded) | None | #### Display Conventions @@ -133,7 +133,7 @@ When creating a token, you define its configuration using the following paramete - Initial supply at launch (base supply) - Maximum supply - - No minting is possible if the maximum supply equals the base supply + - Minting is rejected if it would push the current supply above the maximum supply, so a token that starts at its maximum cannot be minted until some of it is burned - Token can be configured to allow authorized parties to change the maximum supply #### History @@ -227,7 +227,7 @@ distribution options are summarized below: | Method | Description | Example | Notes | | ------ | ----------- | -------- | ------ | | Manual Minting | Authorized users/groups can create new tokens until `maxSupply` is reached | On-demand minting | - Requires proper configuration to enable
- Minting actions may be logged or controlled via permissions | -| Programmed Distribution | A fixed number of tokens are allocated to designated identities at explicit timestamps, and the recipients must [claim](#claim) them to receive the tokens | *On Jan 1, 2047, allocate `X` tokens to the provided identity* | - Schedules token release at known times
- Each entry is a one-time allocation at a fixed timestamp; there is no recurrence option | +| Programmed Distribution | A fixed number of tokens are allocated to designated identities at explicit timestamps, and the recipients must [claim](#claim) them to receive the tokens | *On Jan 1, 2047, allocate `X` tokens to the provided identity* | - Schedules token release at known times
- Each entry is a one-time allocation at a fixed timestamp; there is no recurrence option
- The schedule is set when the contract is registered and cannot be changed later | | [Perpetual Distribution](../protocol-ref/data-contract-token.md#perpetual-distribution-options) | Scheduled release of tokens based on block, time, or epoch intervals | *Emit 100 tokens every 20 blocks*, or *Halve the emission every year* | - Offers ongoing, dynamic token emission patterns.
- Supports variable rates (e.g., linear, steps).
- Emissions accrue on schedule and are always collected by the recipient via a [claim](#claim). | Dash Platform also supports three options to control the destination for newly minted tokens: From 912e03362cc25dad9ed0789e1f1a0ab0ac61a1a0 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 15 Sep 2026 16:08:49 -0400 Subject: [PATCH 8/8] docs: update protocol reference for Dash Platform 4.2 Repoint source links from v4.1.0 to v4.2-dev across the protocol reference, recomputing line anchors where structs, enums and constant blocks moved. Rename the serialized format version field from $version to $formatVersion on the state transition, data contract and identity tables, and in the identity JSON response examples. Correct the identity create fee formula and example to include the asset lock cost, and state the minimum identity top-up fee. Document behavior added in protocol version 14: the contested index checks on document create transitions, the conditional refersTo requirements, and the shielded denomination set. Add the group validation rules, the contract version stamp size constant, default values for the token supply and control properties, and note that the EvonodesByParticipation pairing is unchecked at registration. Co-Authored-By: Claude Opus 5 (1M context) --- docs/protocol-ref/address-system.md | 20 +- docs/protocol-ref/data-contract-document.md | 54 ++-- docs/protocol-ref/data-contract-token.md | 46 ++-- docs/protocol-ref/data-contract.md | 49 ++-- docs/protocol-ref/data-trigger.md | 14 +- docs/protocol-ref/document.md | 30 +-- docs/protocol-ref/errors.md | 2 +- docs/protocol-ref/identity.md | 46 ++-- docs/protocol-ref/overview.md | 2 +- docs/protocol-ref/protocol-constants.md | 263 ++++++++++---------- docs/protocol-ref/shielded-pool.md | 28 +-- docs/protocol-ref/state-transition.md | 40 +-- docs/protocol-ref/token.md | 44 ++-- 13 files changed, 324 insertions(+), 314 deletions(-) diff --git a/docs/protocol-ref/address-system.md b/docs/protocol-ref/address-system.md index 137ecac6b..1b4a3ea68 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.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. +Address-based state transitions were [enabled in Protocol Version 11](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.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.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs). ### Address Witness @@ -65,7 +65,7 @@ The `$type` discriminator and camelCase `redeemScript` field name apply to the J 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.1.0/packages/rs-dpp/src/address_funds/witness.rs). +See the [witness implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/witness.rs). ### Fee Strategy @@ -80,7 +80,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.1.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.2-dev/packages/rs-dpp/src/address_funds/fee_strategy/mod.rs). ### Common Type Aliases @@ -109,7 +109,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.1.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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_to_addresses_transition/). ### Identity Create from Addresses @@ -130,7 +130,7 @@ Create a new identity funded from Platform address balances. **Cost:** Base cost 2,000,000 + 6,500,000 per key + 500,000 per input + 6,000,000 for the change output (if present). Example: 2 keys, 1 input, no change output = 15,500,000 credits. ::: -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/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_from_addresses_transition/). ### Identity Top-Up from Addresses @@ -151,7 +151,7 @@ Add credits to an existing identity from Platform address balances. **Fee:** Base top-up cost 500,000 credits + 500,000 per input + 6,000,000 for the change output (if present). ::: -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/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_from_addresses_transition/). ### Address Funds Transfer @@ -175,7 +175,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.1.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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funds_transfer_transition/). ### Address Funding from Asset Lock @@ -203,7 +203,7 @@ Exactly one output must have a `None` value. This remainder output receives what **Fee:** 50,000,000 credits (asset lock base) + 500,000 per input + 6,000,000 per output (at least one output is counted). Example: 1 output, no inputs = 56,000,000 credits. ::: -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/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_funding_from_asset_lock_transition/). ### Address Credit Withdrawal @@ -226,7 +226,7 @@ Withdraw credits from Platform addresses back to the Core chain. **Fee:** 400,000,000 credits + 500,000 per input + 6,000,000 for the change output (if present). Withdrawal fees are significantly higher due to the complexity and finality of moving funds back to the Core chain. ::: -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/). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/address_funds/address_credit_withdrawal_transition/). ### Address State Transition Signing diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 0fe95fba0..bb0d26481 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.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 `$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.2-dev/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`). @@ -144,9 +144,9 @@ An identifier property (`type: array`, `byteArray: true`, `contentMediaType: app |-------|------|----------|-------------| | `type` | string | Yes | `identity`, `contract`, `token`, `permanentDocument`, or `identityPublicKey` | | `contractId` | string or array (32 bytes) | No | `permanentDocument` only. Contract holding the referenced document type. Defaults to the declaring contract. | -| `documentType` | string (1-64 chars) | `permanentDocument` only | Name of the referenced document type. The referenced type must set `canBeDeleted: false`. | +| `documentType` | string (1-64 chars) | Yes, for `permanentDocument` | Name of the referenced document type. The referenced type must set `canBeDeleted: false`. | | `propertyAgreement` | object (1-10 entries) | No | `permanentDocument` only. Maps a property of this document to a property of the referenced document. Both values must be equal when the document is written, and both properties must have the same type. | -| `keyIdProperty` | string (1-256 chars) | `identityPublicKey` only | Property of this document that holds the referenced key id. The `refersTo` property itself holds the identity id. | +| `keyIdProperty` | string (1-256 chars) | Yes, for `identityPublicKey` | Property of this document that holds the referenced key id. The `refersTo` property itself holds the identity id. | `contractId`, `documentType`, and `propertyAgreement` are rejected unless `type` is `permanentDocument`; `keyIdProperty` is rejected unless `type` is `identityPublicKey`. @@ -156,10 +156,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.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) | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L23) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L24) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L21) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/v4.2-dev/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 @@ -298,8 +298,8 @@ The table below describes the properties used to configure a contested index: | Property Name | Type | Description | |-|-|-| | fieldMatches | array | Array containing conditions to check | -| fieldMatches.field | string | Name of the field to check for matches | -| fieldMatches.regexPattern | string | Regex used to check for matches | +| fieldMatches.field | string | Name of the field to check for matches (1-256 characters) | +| fieldMatches.regexPattern | string | Regex used to check for matches (1-256 characters) | | resolution | integer | Method to resolve the contest:
`0` - masternode voting | | description | string | Optional free-text note (1-256 characters) | @@ -326,17 +326,17 @@ 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.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 `timeRange` overlap factor (`range / step`) (added in 4.2.0) | 24 | -| Maximum `timeRange` `ttl` (added in 4.2.0) | 604,800 seconds (1 week) | -| 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) | +| Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L358) / [32](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L359) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json#L378) | +| Maximum `timeRange` overlap factor (`range / step`) (added in 4.2.0) | [24](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L65) | +| Maximum `timeRange` `ttl` (added in 4.2.0) | [604,800](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L66) seconds (1 week) | +| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L28) | | 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.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) | +| **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.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L29) | +| **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.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L30) | :::{seealso} For all protocol constants, see [Protocol Constants](protocol-constants.md). @@ -371,14 +371,14 @@ A document type with `documentsKeepHistory: true` must also set `canBeDeleted: f ### 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.1.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.2-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L294-L337) object with the following properties: | Property | Type | Required | Description | |----------|------|----------|-------------| -| `contractId` | array (32 bytes) | No | Identifier of the contract containing the payment token. Defaults to the current contract if omitted. | +| `contractId` | array (32 bytes) | No | Identifier of the contract containing the payment token. Omit it for a token in the current contract; setting it to the contract's own id is rejected. | | `tokenPosition` | integer (0–65535) | Yes | Position of the token within the contract | | `amount` | integer (1–281474976710655) | Yes | Number of tokens required for the operation | -| `effect` | integer | No | Token disposition after payment:
`0` - Transfer to contract owner (default)
`1` - Burn (tokens destroyed) | +| `effect` | integer | No | Token disposition after payment:
`0` - Transfer to contract owner (default)
`1` - Burn (tokens destroyed). Burning is allowed only for a token in the current contract, so `1` is rejected when `contractId` is set. | | `gasFeesPaidBy` | integer | No | Who pays gas fees for the operation:
`0` - Document owner (default)
`1` - Contract owner
`2` - Prefer contract owner (falls back to document owner if insufficient) | The following operation types can each have an independent cost configuration: @@ -394,7 +394,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.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). + This list of properties is defined in the [Rust DPP implementation](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L48) and the [document meta-schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). | Property Name | Type | Description | |---------------|------|-------------| @@ -493,7 +493,7 @@ Properties named by `documentsSummable`, `documentsAverageable`, `summable`, or 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 were introduced in the v1 document meta-schema and carry forward unchanged into v2 and v3. 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). +These flags were introduced in the v1 document meta-schema and carry forward unchanged into v2 and v3. They are rejected when applied to pre-v12 contracts. The current v3 meta-schema, including these flags and the ranked keywords, is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json). See the [`getDocuments` reference](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) for the request/response shapes that consume these flags. @@ -512,14 +512,14 @@ Document types can opt into recording ownership and pricing events in the [docum 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 or later 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). +The flags are read only when the contract validates against the v2 or later document meta-schema (protocol version 13 or later). Under earlier meta-schema versions they are treated as false. The current v3 meta-schema is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/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.1.0/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json)). +schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json)). | Keyword | Constraint | | ------- | ---------- | @@ -591,4 +591,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. Protocol version 13 (Dash Platform 4.1) validates against the [v2 meta-schema](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). Protocol version 14 (Dash Platform 4.2.0) validates against the [v3 meta-schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json), which adds the ranked index keywords, `refersTo`, `requiredSince`, `timeRange`, and the `indexOnly` keywords. +See full document schema details in the rs-dpp document meta schema. Protocol version 13 (Dash Platform 4.1) validates against the [v2 meta-schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v2/document-meta.json). Protocol version 14 (Dash Platform 4.2.0) validates against the [v3 meta-schema](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/schema/meta_schemas/document/v3/document-meta.json), which adds the ranked index keywords, `refersTo`, `requiredSince`, `timeRange`, and the `indexOnly` keywords. diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md index 4693f2418..b873650fb 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.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 | +| Token registration | [0.1](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L14) | Per keyword fee for including search keywords | ## Assigning Position @@ -127,17 +127,17 @@ Token configuration controls behavioral aspects of token operations, including s ### Supply Management -| Property | Type | Description | -|----------|------|-------------| -| `baseSupply` | unsigned integer | Initial supply of tokens created at contract deployment | -| `maxSupply` | unsigned integer | Maximum number of tokens that can ever exist (null for unlimited) | +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `baseSupply` | unsigned integer | 0 | Initial supply of tokens created at contract deployment | +| `maxSupply` | unsigned integer | null | Maximum number of tokens that can ever exist (null for unlimited) | ### Operational Controls -| Property | Type | Description | -|----------|------|-------------| -| `startAsPaused` | boolean | Whether the token begins in a paused state where tokens cannot be transferred | -| `allowTransferToFrozenBalance` | boolean | Whether transfers to frozen balances are permitted | +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `startAsPaused` | boolean | false | Whether the token begins in a paused state where tokens cannot be transferred | +| `allowTransferToFrozenBalance` | boolean | true | Whether minting and transfers to frozen balances are permitted | ### Control Group Management @@ -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.1.0/packages/rs-dpp/src/data_contract/change_control_rules/authorized_action_takers.rs#L26-L33) 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.2-dev/packages/rs-dpp/src/data_contract/change_control_rules/authorized_action_takers.rs#L28-L35) is: | Authorized Party | JSON value | Description | | - | - | - | @@ -185,7 +185,7 @@ At action time, a group action authorized by `MainGroup` succeeds only when the ### Change Rule Structure -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: +Each rule consists of the following parameters [defined in DPP](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/change_control_rules/v0/mod.rs) that control its behavior: | Field | Description | | - | - | @@ -652,27 +652,27 @@ The keyword and description limits below apply to the data contract that holds t | Parameter | Value | |-----------|-------| -| 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 bytes](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 keywords | [50](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/methods/validate_update/common/mod.rs#L329-L335) | +| Keyword length | [3 to 50 bytes](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/methods/validate_update/common/mod.rs#L340-L345) | +| Description length | [3 to 100 characters](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/methods/validate_update/common/mod.rs#L379-L386) | +| Maximum note length | [2048 bytes](https://github.com/dashpay/platform/blob/v4.2-dev/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.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) | +| Language code length | [2 to 12 characters](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.1.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.2-dev/packages/rs-dpp/src/errors/consensus/basic/data_contract/invalid_token_base_supply_error.rs#L24-L28) | ## Example Syntax diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index 91316cce5..21c6823c0 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -14,7 +14,7 @@ The following sections provide details that developers need to construct valid c Dash Platform charges fees for registering data contracts based on complexity. These fees compensate evonodes for their role in storing and processing contract-related data. -The table below outlines the current fee structure for various data contract components. Fees are denominated in DASH and are charged at registration time based on the structure of the contract. +The table below outlines the current fee structure for various data contract components. Fees are denominated in DASH and are charged at registration time based on the structure of the contract. The amounts are [defined in rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs#L4-L15). | Fee Component | Amount (DASH) | Description | |--------------------------------------------------------|-------------------|---------| @@ -28,7 +28,7 @@ The table below outlines the current fee structure for various data contract com | `token_uses_pre_programmed`
`_distribution_fee` | 0.1 | Charged when tokens use scheduled distributions (e.g., airdrops). Adds periodic complexity. | | `search_keyword_fee` | 0.1 per keyword | Charged per search keyword defined. Keywords enable reverse lookups and indexing, increasing on-chain storage and filtering load. | -These fees are additive. For example, a contract that defines two document types, each with one unique index, and one token using a perpetual distribution will incur the following total fee: +These fees are additive, but each index pays only one of the three index fees: the contested fee if the index is contested, otherwise the unique fee if it is unique, otherwise the non-unique fee. A contested index is always unique and pays only the contested fee. For example, a contract that defines two document types, each with one unique index, and one token using a perpetual distribution will incur the following total fee: ```text 0.1 (base contract) + 0.02×2 (document types) + 0.01×2 (1 unique index per document type × 2) = 0.16 DASH @@ -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.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) | +| Estimated maximum serialized data contract size | [16384 bytes (16 KB)](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L39) | +| Maximum field value size | [5120 bytes (5 KB)](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L40) | +| Maximum state transition size | [20480 bytes (20 KB)](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L44) | 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.1.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.2-dev/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L77-L121)): | Property | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | @@ -1091,7 +1091,7 @@ This page reflects the v3 meta-schema, which adds the `refersTo` and `requiredSi ### 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.1.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.2-dev/packages/rs-dpp/src/data_contract/generate_data_contract.rs). ```rust // From the Rust reference implementation (rs-dpp) @@ -1119,7 +1119,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.1.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.2-dev/packages/rs-dpp/src/data_contract/config/fields.rs). | Contract option | Default | Description | |-----------------------------------------|---------|-------------| @@ -1149,7 +1149,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.1.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.2-dev/packages/dashpay-contract/schema/v1/dashpay.schema.json#L142-L146)) demonstrates the use of both key-related options at the document level: ``` json "contactRequest": { @@ -1158,7 +1158,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.1.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.2-dev/packages/rs-dpp/src/data_contract/config/v1/mod.rs#L23-L50) for more details, and the [config update rules](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/config/methods/validate_update/v1/mod.rs) for what may change after registration. ### Data Contract groups @@ -1175,11 +1175,20 @@ 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.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.1.0/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L129-L134) value. | +| Minimum group size | [2](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L111-L114) | Minimum members per group | +| `max_contract_group_size` | [256](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L55) | 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.2-dev/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L133-L138) value. | | Maximum required power | 65,535 (u32; cap enforced at u16::MAX) | Maximum threshold power | +Groups are also checked against these rules at contract registration: + +- No member may have a power of `0`. +- `requiredPower` must be greater than `0`. +- The powers of all members must add up to at least `requiredPower`. +- If any members have power below `requiredPower` and therefore cannot act alone, + their combined power must reach `requiredPower`. This prevents a group where one + member can act alone but all remaining members together cannot reach the threshold. + #### Group Action Info When submitting a group-authorized action, the transition includes: @@ -1215,7 +1224,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.1.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.2-dev/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L40-L43) for more details. ### Data Contract tokens @@ -1231,7 +1240,7 @@ See the [groups implementation in rs-dpp](https://github.com/dashpay/platform/bl :::{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). +The document history contract is a [system data contract](https://github.com/dashpay/platform/blob/v4.2-dev/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 | | - | - | @@ -1246,7 +1255,7 @@ Its documents are written by the protocol while applying the corresponding docum | `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). +See the [contract schema in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/document-history-contract/schema/v1/document-history-contract-documents.json). ## Data Contract State Transition Details @@ -1258,7 +1267,7 @@ Data contracts are created on the platform by submitting the [data contract obje | Field | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | -| $version | unsigned integer | 16 bits | The state transition format version (currently `0`) | +| $formatVersion | unsigned integer | 16 bits | The state transition format version (currently `0`) | | type | unsigned integer | 8 bits | State transition type (`0` for data contract create) | | dataContract | [data contract object](#data-contract-object) | Varies | Object containing the data contract details | | identityNonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks | @@ -1266,7 +1275,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L36-L44) for more details. +See the [data contract create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs#L36-L44) for more details. ### Data Contract Update @@ -1290,7 +1299,7 @@ object](#data-contract-object) in a data contract update state transition consis | Field | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | -| $version | unsigned integer | 16 bits | The state transition format version (currently `0`) | +| $formatVersion | unsigned integer | 16 bits | The state transition format version (currently `0`) | | type | unsigned integer | 8 bits | State transition type (`4` for data contract update) | | dataContract | [data contract object](#data-contract-object) | Varies | Object containing the updated data contract details
**Note:** the data contract's [`version` property](#data-contract-version) must be incremented with each update | | identityContractNonce | unsigned integer | 64 bits | Identity contract nonce for replay protection | @@ -1298,7 +1307,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_update_transition/v0/mod.rs#L31-L43) for more details. +See the [data contract update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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/data-trigger.md b/docs/protocol-ref/data-trigger.md index b77ac2639..c2c50a7a8 100644 --- a/docs/protocol-ref/data-trigger.md +++ b/docs/protocol-ref/data-trigger.md @@ -18,17 +18,17 @@ 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.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: +As an example, DPP contains several data triggers for DPNS as defined in the [data trigger bindings](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v2/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.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` | [`CREATE`](https://github.com/dashpay/platform/blob/v4.2-dev/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.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) | +| DPNS | `domain` | [`REPLACE`](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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. diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 52b447051..eab72147b 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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_base_transition/v1/mod.rs#L40-L58). +Each document transition must comply with the [document base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.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.2-dev/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.1.0/packages/rs-dpp/src/tokens/token_payment_info/v0/mod.rs#L34-L54). +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.2-dev/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.1.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.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transition_action_type.rs#L6-L14). The Action column is the enum index. In the JSON form, `$action` carries the camelCase name instead: `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`, or `indexOnlyDelete`. +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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transition_action_type.rs#L6-L15). The Action column is the enum index. In the JSON form, `$action` carries the camelCase name instead: `create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`, or `indexOnlyDelete`. | Action | Name | Description | | :-: | - | - | @@ -103,10 +103,10 @@ The document create transition extends the [base transition](#document-base-tran | Field | Type | Size | Description | | - | - | - | - | | $entropy | array | 32 bytes | Entropy used in creating the [document ID](#document-id). Generated as [shown here](#entropy-generation). | -| 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)).| +| data | object | Varies | Document data being submitted. | +| $prefundedVotingBalance | array | 2 elements | (Optional) Contested index name and prefunded amount of credits reserved for unique index conflict resolution voting (e.g., [premium DPNS name](../explanations/dpns.md#conflict-resolution)). Starting in protocol version 14, the named index must be the contested index resolved for the submitted document values. Field rejected if another index is named or the document resolves to no contested index. | -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). +Each document create transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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. @@ -142,9 +142,9 @@ The document replace transition extends the [base transition](#document-base-tra | Field | Type | Size | Description | | - | - | - | - | | $revision | unsigned integer | 64 bits | Document revision (=> 1) | -| data | | Varies | Document data being updated | +| data | object | 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.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). +Each document replace transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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. @@ -175,7 +175,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.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. +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.2-dev/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 @@ -186,7 +186,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.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). +Each document transfer transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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 @@ -197,7 +197,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.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). +Each document purchase transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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 @@ -208,7 +208,7 @@ 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.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). +Each document update price transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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 Index-Only Delete Transition @@ -237,7 +237,7 @@ Each document index-only delete transition must comply with the structure define ## 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.1.0/packages/rs-dpp/src/document/v0/mod.rs#L37-L101)): +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.2-dev/packages/rs-dpp/src/document/v0/mod.rs#L37-L115)): | Property | Type | Required | Description | | - | - | - | - | diff --git a/docs/protocol-ref/errors.md b/docs/protocol-ref/errors.md index f00fb1383..14f9c8fea 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.1.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.2-dev/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/identity.md b/docs/protocol-ref/identity.md index 595d2cd7e..0d4840535 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.1.0/packages/rs-dpp/src/identity/v0/mod.rs#L38-L44) for more details. +See the [identity implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/identity/v0/mod.rs#L41-L47) 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.1.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.2-dev/packages/rs-platform-value/src/types/identifier.rs). ::: -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. +See rs-dpp for examples of using [InstantSend](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.1.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.2-dev/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 state transition adding the key (identity create, identity update, or identity create from addresses) by the private key for this public key. Must be empty for key types `2`, `3`, and `4`. | -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. +See the [public key implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/identity/identity_public_key/v0/mod.rs#L43-L61) 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.1.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.2-dev/packages/rs-dpp/src/identity/identity_public_key/key_type.rs#L47-L54) 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.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: +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.2-dev/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) | | :--: | -------------- | ------------------------- | @@ -151,19 +151,19 @@ The following constants and limits apply to identities: | `min_identity_funding_amount` | 200,000 credits | Minimum funding for address-based identity create and top-up transitions | | `identity_create_base_cost` | 2,000,000 credits | Base fee for identity creation | | `identity_key_in_creation_cost` | 6,500,000 credits | Fee per key during creation | -| `identity_topup_base_cost` | 500,000 credits | Base fee for identity top-up | +| `identity_topup_base_cost` | 500,000 credits | Base fee for identity top-up. The minimum top-up fee is this plus the asset lock requirement (50,000,000 credits), so 50,500,000 credits. | ### Identity Creation Cost Calculation The total cost to create an identity is: ```text -Total = identity_create_base_cost + (number_of_keys × identity_key_in_creation_cost) +Total = identity_create_base_cost + asset_lock_base_cost + (number_of_keys × identity_key_in_creation_cost) ``` **Examples:** -- 1 key: 2,000,000 + 6,500,000 = **8,500,000 credits** (0.000085 Dash) +- 1 key: 2,000,000 + 200,000,000 + 6,500,000 = **208,500,000 credits** (0.002085 Dash) - 2 keys: 2,000,000 + 13,000,000 = **15,000,000 credits** (0.00015 Dash) - 6 keys: 2,000,000 + 39,000,000 = **41,000,000 credits** (0.00041 Dash) @@ -203,7 +203,7 @@ Identities are created on the platform by submitting the identity information in | Field | Type | Description | | --------------- | -------------- | ----------- | -| $version | integer | The state transition format version (currently `0`) | +| $formatVersion | integer | The state transition format version (currently `0`) | | type | integer | State transition type (`2` for identity create) | | publicKeys | array of [keys](#identity-publickeys) | Public key(s) associated with the identity | | assetLockProof | [proof object](#asset-lock) | Asset lock proof object proving the [asset lock transaction](inv:user:std#ref-txs-assetlocktx) exists on the Core chain and is locked | @@ -211,7 +211,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L43-L54) for more details. +See the [identity create implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_create_transition/v0/mod.rs#L43-L54) for more details. ### Identity TopUp @@ -219,14 +219,14 @@ Identity credit balances are increased by submitting the topup information in an | Field | Type | Description | | --------------- | -------------- | ----------- | -| $version | integer | The state transition format version (currently `0`) | +| $formatVersion | integer | The state transition format version (currently `0`) | | type | integer | State transition type (`3` for identity topup) | | assetLockProof | [proof object](#asset-lock) | Asset lock proof object proving the layer 1 locking transaction exists and is locked | | identityId | array of bytes | An [identity id](#identity-id) for the identity receiving the topup (can be any identity) (32 bytes) | | 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.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L39-L46) for more details. +See the [identity topup implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_topup_transition/v0/mod.rs#L39-L46) for more details. ### Identity Update @@ -234,7 +234,7 @@ Identities are updated on the platform by submitting the identity information in | Field | Type | Description | | -------------------- | -------------------- | ----------- | -| $version | integer | The state transition format version (currently `0`) | +| $formatVersion | integer | The state transition format version (currently `0`) | | type | integer | State transition type (`5` for identity update) | | identityId | array of bytes | The [identity id](#identity-id) (32 bytes) | | revision | integer | Identity update revision | @@ -245,7 +245,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L39-L68) for more details. +See the [identity update implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_update_transition/v0/mod.rs#L39-L68) for more details. ### Identity Credit Transfer @@ -253,7 +253,7 @@ Identities can transfer credits on the platform by submitting an identity credit | Field | Type | Description | | -------------------- | -------------- | ----------- | -| $version | integer | The state transition format version (currently `0`) | +| $formatVersion | integer | The state transition format version (currently `0`) | | type | integer | State transition type (`7` for identity credit transfer) | | identityId | array of bytes | The [identity id](#identity-id) of the sender (32 bytes) | | recipientId | array of bytes | The [identity id](#identity-id) of the recipient (32 bytes) | @@ -267,7 +267,7 @@ Identities can transfer credits on the platform by submitting an identity credit The `recipientId` must differ from `identityId`; transfers to the sending identity are rejected. ::: -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. +See the [identity credit transfer implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L42-L53) for more details. ### Identity Credit Withdrawal @@ -275,7 +275,7 @@ Credits can be withdrawn from an identity to an external Core wallet using an id | Field | Type | Description | | -------------------- | -------------- | ----------- | -| $version | integer | The state transition format version (currently `1`) | +| $formatVersion | integer | The state transition format version (currently `1`) | | type | integer | State transition type (`6` for identity credit withdrawal) | | identityId | array of bytes | An [identity id](#identity-id) (32 bytes) | | amount | integer | The amount of credits to withdraw (64 bits) | @@ -291,17 +291,17 @@ Credits can be withdrawn from an identity to an external Core wallet using an id **Constraints:** `pooling` must be `0` (Never); `1` (IfAvailable) and `2` (Standard) are not yet implemented. `coreFeePerByte` must be a non-zero [Fibonacci number](https://en.wikipedia.org/wiki/Fibonacci_sequence). `outputScript`, when set, must be P2PKH or P2SH. `amount` must be within the [min and max withdrawal amount](protocol-constants.md) limits. ::: -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. +See the [identity credit withdrawal implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.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. +Currently there are two types of asset lock proofs [defined by rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.1.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.2-dev/packages/rs-dpp/src/identity/state_transition/asset_lock_proof/instant/instant_asset_lock_proof.rs#L38-L45). | Field | Type | Description | | ----------- | -------------- | ----------- | @@ -312,7 +312,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.1.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.2-dev/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/overview.md b/docs/protocol-ref/overview.md index 6d392772f..d2eadbaf5 100644 --- a/docs/protocol-ref/overview.md +++ b/docs/protocol-ref/overview.md @@ -14,7 +14,7 @@ In addition to ensuring data complies with predefined JSON Schemas, DPP also def ## Reference Implementation -The current reference implementation is the (Rust) [rs-dpp](https://github.com/dashpay/platform/tree/master/packages/rs-dpp) library. The schemas and meta-schemas referred to in this specification can be found here in the reference implementation: . +The current reference implementation is the (Rust) [rs-dpp](https://github.com/dashpay/platform/tree/master/packages/rs-dpp) library. The reference implementation contains both [DPP schemas](https://github.com/dashpay/platform/tree/master/packages/rs-dpp/src/schema) and [document meta-schemas](https://github.com/dashpay/platform/tree/master/packages/rs-dpp/schema/meta_schemas). ## Release Notes diff --git a/docs/protocol-ref/protocol-constants.md b/docs/protocol-ref/protocol-constants.md index 3e4893f58..408e8b5cb 100644 --- a/docs/protocol-ref/protocol-constants.md +++ b/docs/protocol-ref/protocol-constants.md @@ -12,25 +12,25 @@ 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.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 size | 16,384 bytes (16 KiB) | Maximum serialized data contract | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L18) | +| Withdrawals per block | 4 | Maximum withdrawal transactions per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L19) | +| Retry signing expired withdrawals per block | 1 | Max expired withdrawal retries per block | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L20) | +| Max withdrawal amount | 50,000,000,000,000 credits | 500 Dash maximum per withdrawal | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L21) | | Daily withdrawal limit | Protocol versions 8-13: 200,000,000,000,000 credits (2000 Dash)
Protocol version 14+: 15% of the credits Platform held one day earlier, with a 500-Dash floor and 4000-Dash cap | The relative limit added in 4.2.0 is `min(max(day-old total × 15%, max withdrawal amount), 4000 Dash)`. Until a full day of credit history is available after activation, the previous 2000-Dash limit remains in effect. | [v8-v13](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/v1/mod.rs), [v14+](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/v2/mod.rs) | -| 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 | 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 contract group size | 256 | Maximum members per group | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L26) | +| Max token redemption cycles | 128 | Maximum redemption cycles | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L27) | +| 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.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L35) | | Max time-range overlap factor | 24 | **Added in 4.2.0.** Maximum `range / step` for a [timeRange](data-contract-document.md#document-indices) index, so at most 24 windows overlap at any timestamp | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L65) | | Max time-range TTL | 604,800 seconds (1 week) | **Added in 4.2.0.** Maximum `ttl` a [timeRange](data-contract-document.md#document-indices) index may declare | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L66) | | Min time-range TTL drop operations per write | 32 | **Added in 4.2.0.** Minimum expired-entry cleanup operations Drive performs on each write into a `ttl` index | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L67) | | Core dust relay fee | 3,000 duffs/kB | **Added in 4.2.0.** Used to compute the Core dust threshold of a withdrawal's output script (546 duffs for P2PKH). An expired withdrawal whose whole amount is below it is marked `FAILED` instead of being re-signed | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L54) | | Min GroveDB proof envelope version | 1 | **Added in 4.2.0.** Clients verifying with protocol version 14 tables reject the legacy V0 proof envelope | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/system_limits/v4.rs#L68) | -| 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) | +| 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.2-dev/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.2-dev/packages/rs-dpp/src/data_contract/serialized_version/mod.rs#L40) | ## Credit System @@ -38,8 +38,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.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) | +| `CREDITS_PER_DUFF` | 1,000 | Credits created per duff (satoshi) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/balances/credits.rs#L43) | +| `MAX_CREDITS` | 9,223,372,036,854,775,807 | Maximum credit value (i64::MAX) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/balances/credits.rs#L41) | **Conversion:** 1 Dash = 100,000,000 duffs = 100,000,000,000 credits @@ -51,13 +51,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.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) | +| `BASE_ST_PROCESSING_FEE` | 10,000 | Base state transition processing fee | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/fee/default_costs/constants.rs#L9) | ### State Transition Pricing @@ -65,20 +65,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.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) | +| Credit Transfer | 100,000 | 0.000001 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/state_transition_min_fees/v1.rs#L18) | ### Execution and Resource Pricing @@ -90,16 +90,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.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) | +| Fetch identity balance | 10,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/processing/v1.rs#L13) | #### Storage @@ -107,11 +107,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.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) | +| Storage disk usage (per byte) | 27,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/storage/v1.rs) | +| Storage seek | 2,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/storage/v1.rs) | | TTL ephemeral disk usage (per byte) | 270 | **Added in 4.2.0.** Charged as processing for bytes written under a [timeRange `ttl`](data-contract-document.md#document-indices) index instead of the storage rate; not refunded on removal. [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/storage/v1.rs#L23) | #### Cryptographic Operations @@ -122,11 +122,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.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) | +| ECDSA Secp256k1 | 15,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/signature/v1.rs) | +| ECDSA Hash160 | 15,500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/signature/v1.rs) | ##### Hashing @@ -134,13 +134,13 @@ Fees for cryptographic hash operations. | Operation | Fee (Credits) | Source | |-----------|---------------|--------| -| 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) | +| Single SHA256 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Blake3 (base) | 100 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Blake3 (per block) | 300 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | +| Sinsemilla (base) | 40,000 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/hashing/v1.rs) | #### Data Contract Validation @@ -148,13 +148,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.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) | +| Document type base fee | 500 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/data_contract_validation/v1.rs#L11) | ### Voting @@ -162,9 +162,9 @@ Fees related to contested document voting. | Fee Type | Amount (Credits) | Amount (Dash) | Source | |----------|------------------|---------------|--------| -| Contested document vote resolution fund | **Updated in 4.2.0.**
Through protocol version 13: 20,000,000,000
Protocol version 14+: 10,000,000,000 | 0.2
0.1 | [through v13](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs), [v14+](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v2.rs#L6) | -| 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) | +| Contested document vote resolution fund | **Updated in 4.2.0.**
Through protocol version 13: 20,000,000,000
Protocol version 14+: 10,000,000,000 | 0.2
0.1 | [through v13](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs), [v14+](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v2.rs#L6) | +| Contested document unlock fund | 400,000,000,000 | 4.0 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/vote_resolution_fund_fees/v1.rs) | ## Identity Model @@ -172,20 +172,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.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/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) | +| Max public keys per identity | 15,000 | Maximum keys an identity can have | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/identity/identity_nonce.rs#L15) | +| Max missing identity revisions | 24 | Maximum revision gaps | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/identity/identity_nonce.rs#L17) | ### 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.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) | +| Min asset lock balance | 200,000 duffs | 0.002 Dash minimum | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L25) | ## Document & Data Contract Model @@ -193,20 +193,21 @@ 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.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) | +| Max indexed string length | 63 characters | Maximum indexable string | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L28) | +| Max indexed byte array length | 255 bytes | Maximum indexable byte array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L29) | +| Max indexed array items | 1,024 | Maximum items in indexed array | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L30) | +| Max index size | 255 bytes | Maximum total index size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L42) | +| Default hash size | 32 bytes | Standard hash size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L39) | +| Default float size | 8 bytes | Standard float size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L40) | +| Empty tree storage size | 33 bytes | Storage for empty tree | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L41) | +| Storage flags size | 2 bytes | Size of storage flags | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L43) | +| Contract version stamp size | 5 bytes | **Added in 4.2.0.** Extra bytes document serialization format 3 adds to the estimated document size | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/document_type/mod.rs#L46) | ### Data Contract Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| 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) | +| Initial contract version | 1 | Starting version number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/mod.rs#L80) | ### Data Contract Registration Fees @@ -214,15 +215,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.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) | +| Base contract registration | 10,000,000,000 | 0.1 | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-platform-version/src/version/fee/data_contract_registration/v2.rs) | ### Tokens @@ -232,7 +233,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.1.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.2-dev/packages/rs-dpp/src/tokens/mod.rs#L19) | #### Token Distribution Function Limits @@ -240,17 +241,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.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) | +| `MAX_DISTRIBUTION_PARAM` | 1 | 281,474,976,710,655 (2^48 - 1) | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/data_contract/associated_token/token_perpetual_distribution/distribution_function/mod.rs#L22) | ## Address System @@ -261,42 +262,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.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) | +| Address hash size | 20 bytes | Size of address hash | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L24) | +| Platform HRP (mainnet) | "dash" | Human-readable prefix | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L259) | +| Platform HRP (non-mainnet) | "tdash" | Human-readable prefix used for testnet, devnet, and regtest | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L261) | +| P2PKH address type (bech32m) | 0xb0 (176) | Pay-to-public-key-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L280) | +| P2SH address type (bech32m) | 0x80 (128) | Pay-to-script-hash bech32m encoding type byte | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/address_funds/platform_address.rs#L282) | ### 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.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) | +| Min output amount | 500,000 credits | Minimum output per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.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) | +| Genesis epoch index | 0 | First epoch number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/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.1.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.2-dev/packages/rs-dpp/src/fee/fee_result/refunds.rs#L23) | ## Withdrawal Constants | Constant | Value | Description | Source | |----------|-------|-------------|--------| -| 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) | +| 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.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L24) | +| Min core fee per byte | 1 | Must be Fibonacci number | [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L39) | diff --git a/docs/protocol-ref/shielded-pool.md b/docs/protocol-ref/shielded-pool.md index 1b397fd1d..31bd03f81 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.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. +Shielded state transitions were [enabled in Protocol Version 12](https://github.com/dashpay/platform/blob/v4.2-dev/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). ::: @@ -40,7 +40,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.1.0/packages/rs-dpp/src/shielded/mod.rs). +See the [Orchard bundle primitives in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/shielded/mod.rs). ### Actions @@ -57,15 +57,15 @@ 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) | -Each action permanently stores [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). The minimum shielded fee charges a per-action storage allowance of `shielded_storage_bytes_per_action` bytes at the storage rate: 344 bytes through protocol version 13, and 550 bytes from protocol version 14 to cover tree framing overhead. +Each action permanently stores [344 bytes](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v9.rs#L357) (312 bytes in the note commitment tree + 32 bytes in the nullifier tree). The minimum shielded fee charges a per-action storage allowance of `shielded_storage_bytes_per_action` bytes at the storage rate: 344 bytes through protocol version 13, and 550 bytes from protocol version 14 to cover tree framing overhead. -See the [serialized action implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/shielded/mod.rs). +See the [serialized action implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/shielded/mod.rs). ### Anchors 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. +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.2-dev/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v1.rs#L297-L298), 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 @@ -75,7 +75,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.1.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.2-dev/packages/rs-dpp/src/shielded/sighash.rs#L21-L41). ## Shielded State Transition Details @@ -101,7 +101,7 @@ Maximum actions per transition: [`max_shielded_transition_actions`](protocol-con **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). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_transition/v0/mod.rs#L37-L63). ### Shielded Transfer @@ -119,7 +119,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_transfer_transition/v0/mod.rs#L31-L42). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_transfer_transition/v0/mod.rs#L31-L42). ### Unshield @@ -138,7 +138,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/unshield_transition/v0/mod.rs#L32-L45). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/unshield_transition/v0/mod.rs#L32-L45). ### Shield from Asset Lock @@ -159,7 +159,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_asset_lock_transition/v0/mod.rs#L35-L60). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_asset_lock_transition/v0/mod.rs#L35-L60). ### Shielded Withdrawal @@ -182,7 +182,7 @@ Transparent fields (`coreFeePerByte`, `pooling`, `outputScript`) are bound to th **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). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shielded_withdrawal_transition/v0/mod.rs#L33-L54). ### Identity Create From Shielded Pool @@ -213,12 +213,12 @@ The `denomination` field must exactly match one of the values accepted by the ac | 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) | +| 14 | 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). +Protocol version 13 added 0.03 and 0.25 DASH and retired 0.3 DASH. Protocol version 14 keeps the version 13 set unchanged. 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.2-dev/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v10.rs#L386-L394). -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). +See the [implementation in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/identity_create_from_shielded_pool_transition/v0/mod.rs#L31-L64). ### Shield from Identity diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index 8b977c608..2da9d36da 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.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). +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.2-dev/packages/rs-dpp/src/balances/credits.rs#L43). 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.2-dev/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.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L15). +State transitions are limited to a maximum size of [20 KiB / 20,480 bytes](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/common_fields.rs). State transitions draw from the following common fields: +The list of common fields used by multiple state transitions is defined in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/common_fields.rs). State transitions draw from the following common 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.1.0/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21)). See [State Transition Types](#state-transition-types) for the full list. | +| $formatVersion | 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.2-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L22)). 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 or 96 bytes | Signature of state transition data. Present on identity-signed and asset-lock-signed transitions (types 0-9, 13, 18, and 21): 65 bytes for ECDSA signatures or 96 bytes for BLS signatures. | | inputWitnesses | array | Varies | Address-ownership witnesses. Present on address-authorized transitions (types 10-15); may be empty when the transition has no address inputs. | @@ -44,7 +44,7 @@ Additionally, the identity-signed state transitions (types 0, 1, 4-9, and 21) in ## State Transition Types -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. +Dash Platform Protocol defines the following [state transition types](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L22-L47). 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 | | --- | --- | --- | @@ -77,9 +77,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.1.0/packages/rs-platform-version/src/version/system_limits/v3.rs#L16)) | +| 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.2-dev/packages/rs-platform-version/src/version/system_limits/v3.rs#L18)) | -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). +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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L30-L38). ### Masternode Vote @@ -87,10 +87,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.1.0/packages/rs-dpp/src/voting/votes/mod.rs#L28-L30) | Varies | Vote information | +| vote | [Vote](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/voting/votes/mod.rs#L41-L43) | 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.1.0/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L39-L49). +See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L43-L53). ## State Transition Signing @@ -139,7 +139,7 @@ requires at least a CRITICAL key (level `1`). | State transition | Accepted security level(s) | | ---------------- | -------------------------- | | Identity update | MASTER (`0`) | -| Identity credit transfer, Identity credit withdrawal, Data contract update, Shield from identity | CRITICAL (`1`) | +| Identity credit transfer, Identity credit transfer to addresses, Identity credit withdrawal, Data contract update, Shield from identity | CRITICAL (`1`) | | Data contract create | CRITICAL or HIGH (`1`-`2`) | | Batch (document/token), Masternode vote | CRITICAL, HIGH, or MEDIUM (`1`-`3`) | @@ -199,15 +199,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.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 | +| [Batch](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L56-L57) | +| [Identity topup](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/public_key_in_creation/v0/mod.rs#L56-L57) | +| [Identity credit transfer](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.2-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L49-L52) | Exclude | Exclude | N/A | N/A | | [Shield from identity](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/shielded/shield_from_identity_transition/v0/mod.rs#L66-L69) | Exclude | Exclude | N/A | N/A | :::{note} diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index e8e0222f5..62feb8ffc 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 | -| $groupContractPosition
$groupActionId
$groupActionIsProposer | unsigned integer
array
boolean | 16 bits
32 bytes
- | Optional group multi-party authentication info, flattened from [GroupStateTransitionInfo](https://github.com/dashpay/platform/blob/v4.1.0/packages/rs-dpp/src/group/mod.rs#L45-L54) so the three fields appear at the top level of the transition. All three are present together or absent together. Since protocol version 13, a transition confirming an existing group action must carry the same `$dataContractId` and `$tokenContractPosition` as the original proposal. | +| $groupContractPosition
$groupActionId
$groupActionIsProposer | unsigned integer
array
boolean | 16 bits
32 bytes
- | Optional group multi-party authentication info, flattened from [GroupStateTransitionInfo](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/group/mod.rs#L45-L54) so the three fields appear at the top level of the transition. All three are present together or absent together. Since protocol version 13, a transition confirming an existing group action must carry the same `$dataContractId` and `$tokenContractPosition` as the original proposal. | -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). +Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.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.2-dev/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.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. +The token transition actions [defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.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.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L23-L33). +Each token burn transition must comply with the [token burn transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L25-L39). +Each token mint transition must comply with the [token mint transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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. 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 | -| 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 | +| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v4.2-dev/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.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L39-L55). +Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L22-L32). +Each token freeze transition must comply with the [token freeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L22-L32). +Each token unfreeze transition must comply with the [token unfreeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.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). +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.2-dev/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.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 (binary `0` = PreProgrammed, `1` = Perpetual; JSON `"PreProgrammed"` or `"Perpetual"`) | +| distributionType | [TokenDistributionType enum](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/associated_token/token_distribution_key.rs#L29-L36) | Varies | Type of [token distribution](../explanations/tokens.md#distribution-rules) targeted (binary `0` = PreProgrammed, `1` = Perpetual; JSON `"PreProgrammed"` or `"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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L21-L29). +Each token claim transition must comply with the [token claim transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/tokens/emergency_action.rs#L14-L18) | Varies | The emergency action to be executed (binary `0` = Pause, `1` = Resume; JSON `"pause"` or `"resume"`) | +| emergencyAction | [TokenEmergencyAction enum](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/tokens/emergency_action.rs#L16-L20) | Varies | The emergency action to be executed (binary `0` = Pause, `1` = Resume; JSON `"pause"` or `"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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L19-L27). +Each token emergency action transition must comply with the [token emergency action transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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.1.0/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L36-L70) | Varies | Updated token configuration item | +| updateTokenConfigurationItem | [TokenConfigurationChangeItem object](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L40-L74) | 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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L22-L30). +Each token configuration update transition must comply with the [token config update transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/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,7 +197,7 @@ 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.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. | +| price | Optional [TokenPricingSchedule](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/tokens/token_pricing_schedule.rs#L37-L53) | 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 | The pricing schedule is tagged by a `$type` field naming the form. A single fixed price uses `singlePrice`: @@ -225,7 +225,7 @@ Tiered pricing uses `setPrices`, keyed by minimum token amount: 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). +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.2-dev/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 @@ -240,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.1.0/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_direct_purchase_transition/v0/mod.rs#L23-L34). +Each token purchase transition must comply with the [token direct purchase transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v4.2-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_direct_purchase_transition/v0/mod.rs#L23-L34).