From 16a0e6c58cf1fcb90d3a7b3e1cea08147da8c3f9 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 11:40:52 -0400 Subject: [PATCH 01/12] docs(ref): doc page updates --- docs/protocol-ref/document.md | 119 ++++------------------------------ 1 file changed, 12 insertions(+), 107 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 58eef7356..bc297262b 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -4,121 +4,26 @@ # Document -## Document Submission +## Document Overview -Documents are sent to the platform by submitting the them in a batch state transition consisting of: +Once a [data contract](./data-contract.md) has been created, data can be stored by submitting documents that comply with the document structure specified in the contract. Each document consists of one or more fields and the indices necessary to support querying. Documents are [created](#document-create-transition), [updated](#document-replace-transition), or [deleted](#document-delete-transition) by sending by submitting them to the platform in a [batch state transition](./state-transition.md#batch). -| Field | Type | Description| -| - | - | - | -| protocolVersion | integer | The platform protocol version (currently `1`) | -| type | integer | State transition type (`1` for batch) | -| ownerId | array | [Identity](../protocol-ref/identity.md) submitting the document(s) (32 bytes) | -| transitions | array of transition objects | Document `create`, `replace`, or `delete` transitions (up to 10 objects) | -| signaturePublicKeyId | number | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition | -| signature | array | Signature of state transition data (65 or 96 bytes) | - -Each batch state transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/schema/document/v0/stateTransition/documentsBatch.json): +## Document State Transition Details -```json -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "properties": { - "protocolVersion": { - "type": "integer", - "$comment": "Maximum is the latest protocol version" - }, - "type": { - "type": "integer", - "const": 1 - }, - "ownerId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "transitions": { - "type": "array", - "items": { - "type": "object" - }, - "minItems": 1, - "maxItems": 10 - }, - "signaturePublicKeyId": { - "type": "integer", - "minimum": 0 - }, - "signature": { - "type": "array", - "byteArray": true, - "minItems": 65, - "maxItems": 96 - } - }, - "additionalProperties": false, - "required": [ - "protocolVersion", - "type", - "ownerId", - "transitions", - "signaturePublicKeyId", - "signature" - ] -} -``` +All document transitions include the [document base transition fields](#document-base-transition). Some document transitions (.e.g., [document create](#document-create-transition)) require additional fields to provide their functionality. ### Document Base Transition -All document transitions in a batch state transition are built on the base schema and include the following fields: +The following fields are included in all document transitions: -| Field | Type | Description| -| - | - | - | -| $id | array | The [document ID](#document-id) (32 bytes)| -| $type | string | Name of a document type found in the data contract associated with the `dataContractId` (1-64 characters) | -| $action | array of integers | [Action](#document-transition-action) the platform should take for the associated document | -| $dataContractId | array | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` (32 bytes) | +| Field | Type | Size | Description| +| ----- | ---- | ---- | ---------- | +| $id | array | 32 bytes | The [document ID](#document-id) | +| $identityContractNonce | unsigned integer | 64 bits | Identity contract nonce | +| $type | string | 1-64 characters | Name of a document type found in the data contract associated with the `dataContractId`| +| $dataContractId | array | 32 bytes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` | -Each document transition must comply with the document transition [base schema](https://github.com/dashpay/platform/blob/v1.8.0/packages/rs-dpp/src/schema/document/v0/stateTransition/documentTransition/base.json): - -```json -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "properties": { - "$id": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "$type": { - "type": "string" - }, - "$action": { - "type": "integer", - "enum": [0, 1, 3] - }, - "$dataContractId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - } - }, - "required": [ - "$id", - "$type", - "$action", - "$dataContractId" - ], - "additionalProperties": false -} -``` +Each document transition must comply with the [document base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_base_transition/v0/mod.rs#L43-L61). #### Document id From 1acd337aee005ff892c3da2009c52fc24c5dc873 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 11:46:14 -0400 Subject: [PATCH 02/12] docs(ref): update doc id link and description --- docs/protocol-ref/document.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index bc297262b..a2bd15b0a 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -27,25 +27,25 @@ Each document transition must comply with the [document base transition defined #### Document id -The document `$id` is created by hashing the document's `dataContractId`, `ownerId`, `type`, and `entropy` as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/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/v2.0-dev/packages/rs-dpp/src/document/generate_document_id.rs). ```rust // From the Rust reference implementation (rs-dpp) // generate_document_id.rs -pub fn generate_document_id( +pub fn generate_document_id_v0( contract_id: &Identifier, owner_id: &Identifier, - document_type: &str, + document_type_name: &str, entropy: &[u8], ) -> Identifier { let mut buf: Vec = vec![]; buf.extend_from_slice(&contract_id.to_buffer()); buf.extend_from_slice(&owner_id.to_buffer()); - buf.extend_from_slice(document_type.as_bytes()); + buf.extend_from_slice(document_type_name.as_bytes()); buf.extend_from_slice(entropy); - Identifier::from_bytes(&hash(&buf)).unwrap() + Identifier::from_bytes(&hash_double_to_vec(&buf)).unwrap() } ``` From 5ffa231cea7e6dbd1491472cfb49967eee013e3f Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 12:30:18 -0400 Subject: [PATCH 03/12] docs(ref): fix link --- docs/protocol-ref/document.md | 4 ++-- docs/protocol-ref/state-transition.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index a2bd15b0a..d98fefa2d 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -101,7 +101,7 @@ Each document create transition must comply with this JSON-Schema definition est **Note:** The document create transition must also include all required properties of the document as defined in the data contract. -The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-submission): +The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-overview): ```json { @@ -157,7 +157,7 @@ Each document replace transition must comply with this JSON-Schema definition es **Note:** The document create transition must also include all required properties of the document as defined in the data contract. -The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-submission): +The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-overview): ```json { diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index 5073d99f8..87f44602a 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -45,9 +45,9 @@ Dash Platform Protocol defines the [state transition types](https://github.com/d | Field | Type | Size | Description | | ----------- | -------------- | ---- | ----------- | | ownerId | array of bytes | 32 bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) | -| transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-submission) or token actions (up to 10 objects) | +| transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-overview) or token actions (up to 10 objects) | -More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). +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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L39-L50). ### Data Contract Create From 7804aeb662a3428d3c337f402a80e8941168771b Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 12:36:28 -0400 Subject: [PATCH 04/12] docs(ref): update action --- docs/protocol-ref/document.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index d98fefa2d..f4eaa692f 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -19,6 +19,7 @@ The following fields are included in all document transitions: | Field | Type | Size | Description| | ----- | ---- | ---- | ---------- | | $id | array | 32 bytes | The [document ID](#document-id) | +| $action | array of integers | Varies | [Action](#document-transition-action) the platform should take for the associated document | | $identityContractNonce | unsigned integer | 64 bits | Identity contract nonce | | $type | string | 1-64 characters | Name of a document type found in the data contract associated with the `dataContractId`| | $dataContractId | array | 32 bytes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` | @@ -51,6 +52,8 @@ pub fn generate_document_id_v0( #### 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transition_action_type.rs#L6-L14). + | Action | Name | Description | | :-: | - | - | | 0 | Create | Create a new document with the provided data | From a2816ea285e9c524f174a4d230825600eeea526d Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 12:49:04 -0400 Subject: [PATCH 05/12] docs(ref): update doc delete st --- docs/protocol-ref/document.md | 24 +----------------------- 1 file changed, 1 insertion(+), 23 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index f4eaa692f..7d2ccbcc2 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -184,29 +184,7 @@ The following example document create transition and subsequent table demonstrat ### Document Delete Transition -The document delete transition only requires the fields found in the [base document transition](#document-base-transition). - -### Example Document Batch State Transition - -```json -{ - "protocolVersion": 1, - "type": 1, - "signature": "ICu/H7MoqxNUzznP9P2aTVEo91VVy0T8M3QWCH/7dg2UVokG98TbD4DQB4E8SD4GzHoRrBMycJ75SbT2AaF9hFc=", - "signaturePublicKeyId": 0, - "ownerId": "4ZJsE1Yg8AosmC4hAeo3GJgso4N9pCoa6eCTDeXsvdhn", - "transitions": [ - { - "$id": "8jm8iHsYE6ENENvFVeFVFMCwfgEqo5P1iR2q4KAYgpbS", - "$type": "note", - "$action": 1, - "$dataContractId": "AnmBaYH13RyiuvBkBD6qkdc36H5DKt6ToMrkqgUnnywz", - "message": "Updated document @ Mon, 26 Oct 2020 14:58:31 GMT", - "$revision": 2 - } - ] -} -``` +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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/v0/mod.rs#L21-L24) for details. ## Document Object From 6c2e42b4b5e7672978ce743342d355990a902a9b Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 13:12:26 -0400 Subject: [PATCH 06/12] docs(ref): update data create st info --- docs/protocol-ref/document.md | 45 ++++++++--------------------------- 1 file changed, 10 insertions(+), 35 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 7d2ccbcc2..17705cf89 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -65,44 +65,19 @@ Document transition actions indicate what operation platform should perform with ### Document Create Transition -The document create transition extends the base schema to include the following additional fields: +The document create transition extends the [base transition](#document-base-transition) to include the following additional fields: -| Field | Type | Description| -| - | - | - | -| $entropy | array | Entropy used in creating the [document ID](#document-id). Generated as [shown here](../protocol-ref/state-transition.md#entropy-generation). (32 bytes) | -| $createdAt | integer | (Optional) | Time (in milliseconds) the document was created | -| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | +| Field | Type | Size | Description| +| - | - | - | - | +| $entropy | array | 32 bytes | Entropy used in creating the [document ID](#document-id). Generated as [shown here](../protocol-ref/state-transition.md#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)).| -Each document create transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/create.json) (in addition to the document transition [base schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/base.json)) 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_create_transition/v0/mod.rs#L56-L80) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). -```json -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "properties": { - "$entropy": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32 - }, - "$createdAt": { - "type": "integer", - "minimum": 0 - }, - "$updatedAt": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "$entropy" - ], - "additionalProperties": false -} -``` - -**Note:** The document create transition must also include all required properties of the document as defined in the data contract. +::: {note} +The document create transition data field must include all [required document properties](./data-contract-document.md#required-properties) specified in the data contract. +::: The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-overview): From 268f209e988fa2af03a6c6571825b981841d89c9 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 15:08:49 -0400 Subject: [PATCH 07/12] docs(ref): update document replace info --- docs/protocol-ref/document.md | 39 +++++++++-------------------------- 1 file changed, 10 insertions(+), 29 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 17705cf89..7b186bf01 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -67,7 +67,7 @@ Document transition actions indicate what operation platform should perform with The document create transition extends the [base transition](#document-base-transition) to include the following additional fields: -| Field | Type | Size | Description| +| Field | Type | Size | Description | | - | - | - | - | | $entropy | array | 32 bytes | Entropy used in creating the [document ID](#document-id). Generated as [shown here](../protocol-ref/state-transition.md#entropy-generation). | | data | | Varies | Document data being submitted. | @@ -103,37 +103,18 @@ The following example document create transition and subsequent table demonstrat ### Document Replace Transition -The document replace transition extends the base schema to include the following additional fields: +The document replace transition extends the transition base to include the following additional fields: -| Field | Type | Description| -| - | - | - | -| $revision | integer | Document revision (=> 1) | -| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | +| Field | Type | Size | Description | +| - | - | - | - | +| $revision | unsigned integer | 64 bits | Document revision (=> 1) | +| data | | Varies | Document data being updated | -Each document replace transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/replace.json) (in addition to the document transition [base schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/base.json)) 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_replace_transition/v0/mod.rs#L35-L45) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). -```json -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "properties": { - "$revision": { - "type": "integer", - "minimum": 1 - }, - "$updatedAt": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "$revision" - ], - "additionalProperties": false -} -``` - -**Note:** The document create transition must also include all required properties of the document as defined in the data contract. +::: {note} +The document replace transition data field must include all [required document properties](./data-contract-document.md#required-properties) specified in the data contract. +::: The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-overview): From 5e07a3eac64b1a033260d72963009016f1bac21a Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 15:57:27 -0400 Subject: [PATCH 08/12] docs(ref): update doc object info --- docs/protocol-ref/document.md | 75 +++++------------------------------ 1 file changed, 11 insertions(+), 64 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 7b186bf01..c7dcb3417 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -144,78 +144,25 @@ The document delete transition only requires the fields found in the [base docum ## 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/v0.24.5/packages/rs-dpp/schema/document/documentExtended.json)): +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/v2.0-dev/packages/rs-dpp/src/document/v0/mod.rs#L35-L105)): | Property | Type | Required | Description | | - | - | - | - | | protocolVersion | integer | Yes | The platform protocol version (currently `1`) | | $id | array | Yes | The [document ID](#document-id) (32 bytes)| | $type | string | Yes | Document type defined in the referenced contract (1-64 characters) | -| $revision | integer | No | Document revision (=>1) | +| $revision | unsigned integer (64 bits) | No | Document revision (=>1) if the document is mutable | | $dataContractId | array | Yes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` (32 bytes) | | $ownerId | array | Yes | [Identity](../protocol-ref/identity.md) of the user submitting the document (32 bytes) | -| $createdAt | integer | (Optional) | Time (in milliseconds) the document was created | -| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | - -Each document object must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/schema/document/documentExtended.json): - -```json -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "properties": { - "$protocolVersion": { - "type": "integer", - "$comment": "Maximum is the latest protocol version" - }, - "$id": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "$type": { - "type": "string" - }, - "$revision": { - "type": "integer", - "minimum": 1 - }, - "$dataContractId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "$ownerId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "$createdAt": { - "type": "integer", - "minimum": 0 - }, - "$updatedAt": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "$protocolVersion", - "$id", - "$type", - "$revision", - "$dataContractId", - "$ownerId" - ], - "additionalProperties": false -} -``` +| $createdAt | unsigned integer (64 bits) | No | Time (in milliseconds) at document creation, if required by the document type schema | +| $updatedAt | unsigned integer (64 bits) | No | Last document update time in milliseconds, if required by the document type schema | +|$transferredAt | unsigned integer (64 bits) | No | Last transferred time in milliseconds, if required by the document type schema | +| $createdAt
BlockHeight | unsigned integer (64 bits) | No | Block height at document creation, if required by the schema | +| $updatedAt
BlockHeight | unsigned integer (64 bits) | No | Block height at the document's last update, if required by the schema | +| $transferredAt
BlockHeight | unsigned integer (64 bits) | No | Block height when document was last transferred, if required by the schema | +| $createdAt
CoreBlockHeight | unsigned integer (64 bits) | No | Core block height at document creation, if required by the schema | +| $updatedAt
CoreBlockHeight | unsigned integer (64 bits) | No |Core block height at the document's last update, if required by the schema | +| $transferredAt
CoreBlockHeight | unsigned integer (64 bits) | No |Core block height when document was last transferred, if required by the schema | ### Example Document Object From 3c123ed88aa7b1bdbce0a188d0b5be2cc8ed7bd4 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 16:05:18 -0400 Subject: [PATCH 09/12] docs(ref): add table links --- docs/protocol-ref/document.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index c7dcb3417..9d9819ef0 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -18,8 +18,8 @@ The following fields are included in all document transitions: | Field | Type | Size | Description| | ----- | ---- | ---- | ---------- | -| $id | array | 32 bytes | The [document ID](#document-id) | -| $action | array of integers | Varies | [Action](#document-transition-action) the platform should take for the associated document | +| [$id](#document-id) | array | 32 bytes | The [document ID](#document-id) | +| [$action](#document-transition-action) | array of integers | Varies | [Action](#document-transition-action) the platform should take for the associated document | | $identityContractNonce | unsigned integer | 64 bits | Identity contract nonce | | $type | string | 1-64 characters | Name of a document type found in the data contract associated with the `dataContractId`| | $dataContractId | array | 32 bytes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` | @@ -56,9 +56,9 @@ Document transition actions indicate what operation platform should perform with | Action | Name | Description | | :-: | - | - | -| 0 | Create | Create a new document with the provided data | -| 1 | Replace | Replace an existing document with the provided data | -| 2 | Delete | Delete the referenced document | +| 0 | [Create](#document-create-transition) | Create a new document with the provided data | +| 1 | [Replace](#document-replace-transition) | Replace an existing document with the provided data | +| 2 | [Delete](#document-delete-transition) | Delete the referenced document | | 3 | Transfer | Transfer the referenced document to a new owner | | 4 | Purchase | Purchase the referenced document | | 5 | Update price | Update the price for the document | From 7818cb5ad34503e3eadd2c02a997665e32872f67 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 16:07:02 -0400 Subject: [PATCH 10/12] docs: misc small updates --- docs/explanations/platform-protocol-state-transition.md | 2 +- docs/protocol-ref/state-transition.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md index d237bcd59..1d94e51ce 100644 --- a/docs/explanations/platform-protocol-state-transition.md +++ b/docs/explanations/platform-protocol-state-transition.md @@ -37,7 +37,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-submission) (`1`) | An array of 1 or more [document](../explanations/platform-protocol-document.md) or token transition objects | +| [Batch](../protocol-ref/document.md#document-overview) (`1`) | An array of 1 or more [document](../explanations/platform-protocol-document.md) or token transition objects | | [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 | diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index 87f44602a..469b07f2c 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -136,7 +136,7 @@ See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0 | --------------- | -------------- | ---- | ----------- | | 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/v2.0-dev/packages/rs-dpp/src/voting/votes/mod.rs#L20-L22) | Varies | Vote information +| vote | [Vote](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/voting/votes/mod.rs#L20-L22) | 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/masternode_vote_transition/v0/mod.rs#L40-L50). From f1d7a16411c8887f71c1136ecb4efde275159488 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 16:19:24 -0400 Subject: [PATCH 11/12] docs(ref): add basic doc transfer st info --- docs/protocol-ref/document.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index 9d9819ef0..cce58158c 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -59,7 +59,7 @@ Document transition actions indicate what operation platform should perform with | 0 | [Create](#document-create-transition) | Create a new document with the provided data | | 1 | [Replace](#document-replace-transition) | Replace an existing document with the provided data | | 2 | [Delete](#document-delete-transition) | Delete the referenced document | -| 3 | Transfer | Transfer the referenced document to a new owner | +| 3 | [Transfer](#document-transfer-transition) | Transfer the referenced document to a new owner | | 4 | Purchase | Purchase the referenced document | | 5 | Update price | Update the price for the document | @@ -103,7 +103,7 @@ The following example document create transition and subsequent table demonstrat ### Document Replace Transition -The document replace transition extends the transition base to include the following additional fields: +The document replace transition extends the [base transition](#document-base-transition) to include the following additional fields: | Field | Type | Size | Description | | - | - | - | - | @@ -142,6 +142,17 @@ The following example document create transition and subsequent table demonstrat 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_delete_transition/v0/mod.rs#L21-L24) for details. +### Document Transfer Transition + +The document transfer transition extends the [base transition](#document-base-transition) to include the following additional fields: + +| Field | Type | Size | Description | +| - | - | - | - | +| $revision | unsigned integer | 64 bits | Document revision (=> 1) | +| recipientOwnerId | array of bytes | 32 bytes | Identifier of the recipient owner | + +Each document transfer transition must comply with the structure defined in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transfer_transition/v0/mod.rs#L33-L46) (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/v2.0-dev/packages/rs-dpp/src/document/v0/mod.rs#L35-L105)): From 2021a30a397312e03e86bd6240d37e58daae1139 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 13 Mar 2025 16:40:56 -0400 Subject: [PATCH 12/12] docs(ref): add document purchase and update price st info --- docs/protocol-ref/document.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md index cce58158c..1cc8b3ab2 100644 --- a/docs/protocol-ref/document.md +++ b/docs/protocol-ref/document.md @@ -60,8 +60,8 @@ Document transition actions indicate what operation platform should perform with | 1 | [Replace](#document-replace-transition) | Replace an existing document with the provided data | | 2 | [Delete](#document-delete-transition) | Delete the referenced document | | 3 | [Transfer](#document-transfer-transition) | Transfer the referenced document to a new owner | -| 4 | Purchase | Purchase the referenced document | -| 5 | Update price | Update the price for the document | +| 4 | [Purchase](#document-purchase-transition) | Purchase the referenced document | +| 5 | [Update price](#document-update-price-transition) | Update the price for the document | ### Document Create Transition @@ -144,15 +144,37 @@ The document delete transition only requires the fields found in the [base docum ### Document Transfer Transition -The document transfer transition extends the [base transition](#document-base-transition) to include the following additional fields: +The document transfer transition allows a document owner to transfer document ownership directly to another identity without making it available for purchase. This transition extends the [base transition](#document-base-transition) to include the following additional fields: | Field | Type | Size | Description | | - | - | - | - | | $revision | unsigned integer | 64 bits | Document revision (=> 1) | -| recipientOwnerId | array of bytes | 32 bytes | Identifier of the recipient owner | +| 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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_transfer_transition/v0/mod.rs#L33-L46) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). +### Document Purchase Transition + +The document purchase transition allows an identity to purchase a document previously made available for sale by the current document owner. This transition extends the [document base transition](#document-base-transition) to include the following additional fields: + +| Field | Type | Size | Description | +| - | - | - | - | +| $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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_purchase_transition/v0/mod.rs#L23-L33) (in addition to the [document base transition](#document-base-transition) that is required for all document transitions). + +### Document Update Price Transition + +The document update price transition allows a document owner to set or update the minimum price they will accept in exchange for transferring document ownership to another party. This transition extends the [document base transition](#document-base-transition) to include the following additional fields: + +| Field | Type | Size | Description | +| - | - | - | - | +| $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/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/document_update_price_transition/v0/mod.rs#L27-L40) (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/v2.0-dev/packages/rs-dpp/src/document/v0/mod.rs#L35-L105)):