diff --git a/docs/explanations/dashpay.md b/docs/explanations/dashpay.md index b6a29f6e0..f09a29542 100644 --- a/docs/explanations/dashpay.md +++ b/docs/explanations/dashpay.md @@ -12,12 +12,6 @@ contract that enables a decentralized application that creates bidirectional [di payment channels](../reference/glossary.md#direct-settlement-payment-channel-dspc) between [identities](../explanations/identity.md). -> πŸ“˜ -> -> For previews of an updated Dash mobile wallet UI based on the DashPay contract or to join the -> alpha test program, please visit the target="_blank">DashPay landing page at dash.org. - The DashPay contract enables an improved Dash wallet experience with features including: * **User Centric Interaction**: DashPay brings users front and center in a cryptocurrency wallet. @@ -86,11 +80,11 @@ 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/documents_batch/data_triggers/triggers/dashpay) enforce additional validation rules related to the `contactRequest` document. -> πŸ‘ DashPay DIP -> -> Please refer to the [DashPay Dash Improvement Proposal -> (DIP)](https://github.com/dashpay/dips/blob/master/dip-0015.md) for more extensive background -> information and complete details about the data contract. +:::{tip} +See the [DashPay Dash Improvement Proposal +(DIP)](https://github.com/dashpay/dips/blob/master/dip-0015.md) for more extensive background +information and complete details about the data contract. +::: * Contact request details @@ -99,6 +93,7 @@ enforce additional validation rules related to the `contactRequest` document. * Contact Info details +:::{dropdown} DashPay data contract ```json { "profile": { @@ -129,31 +124,45 @@ enforce additional validation rules related to the `contactRequest` document. "avatarUrl": { "type": "string", "format": "uri", - "maxLength": 2048 + "minLength": 1, + "maxLength": 2048, + "position": 0 }, "avatarHash": { "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, - "description": "SHA256 hash of the bytes of the image specified by avatarUrl" + "description": "SHA256 hash of the bytes of the image specified by avatarUrl", + "position": 1 }, "avatarFingerprint": { "type": "array", "byteArray": true, "minItems": 8, "maxItems": 8, - "description": "dHash the image specified by avatarUrl" + "description": "dHash the image specified by avatarUrl", + "position": 2 }, "publicMessage": { "type": "string", - "maxLength": 140 + "minLength": 1, + "maxLength": 140, + "position": 3 }, "displayName": { "type": "string", - "maxLength": 25 + "minLength": 1, + "maxLength": 25, + "position": 4 } }, + "minProperties": 1, + "dependentRequired": { + "avatarUrl": ["avatarHash", "avatarFingerprint"], + "avatarHash": ["avatarUrl", "avatarFingerprint"], + "avatarFingerprint": ["avatarUrl", "avatarHash"] + }, "required": [ "$createdAt", "$updatedAt" @@ -195,21 +204,25 @@ enforce additional validation rules related to the `contactRequest` document. "type": "array", "byteArray": true, "minItems": 32, - "maxItems": 32 + "maxItems": 32, + "position": 0 }, "rootEncryptionKeyIndex": { "type": "integer", - "minimum": 0 + "minimum": 0, + "position": 1 }, "derivationEncryptionKeyIndex": { "type": "integer", - "minimum": 0 + "minimum": 0, + "position": 2 }, "privateData": { "type": "array", "byteArray": true, "minItems": 48, "maxItems": 2048, + "position": 3, "description": "This is the encrypted values of aliasName + note + displayHidden encoded as an array in cbor" } }, @@ -224,6 +237,8 @@ enforce additional validation rules related to the `contactRequest` document. "additionalProperties": false }, "contactRequest": { + "documentsMutable": false, + "canBeDeleted": false, "requiresIdentityEncryptionBoundedKey": 2, "requiresIdentityDecryptionBoundedKey": 2, "type": "object", @@ -283,45 +298,49 @@ enforce additional validation rules related to the `contactRequest` document. "byteArray": true, "minItems": 32, "maxItems": 32, + "position": 0, "contentMediaType": "application/x.dash.dpp.identifier" }, "encryptedPublicKey": { "type": "array", "byteArray": true, "minItems": 96, - "maxItems": 96 + "maxItems": 96, + "position": 1 }, "senderKeyIndex": { "type": "integer", - "minimum": 0 + "minimum": 0, + "position": 2 }, "recipientKeyIndex": { "type": "integer", - "minimum": 0 + "minimum": 0, + "position": 3 }, "accountReference": { "type": "integer", - "minimum": 0 + "minimum": 0, + "position": 4 }, "encryptedAccountLabel": { "type": "array", "byteArray": true, "minItems": 48, - "maxItems": 80 + "maxItems": 80, + "position": 5 }, "autoAcceptProof": { "type": "array", "byteArray": true, "minItems": 38, - "maxItems": 102 - }, - "coreHeightCreatedAt": { - "type": "integer", - "minimum": 1 + "maxItems": 102, + "position": 6 } }, "required": [ "$createdAt", + "$createdAtCoreBlockHeight", "toUserId", "encryptedPublicKey", "senderKeyIndex", diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index 34988589f..c74b5c569 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -8,9 +8,9 @@ Dash Platform Name Service (DPNS) is a service used to register names on Dash Platform. It is a general service that is used to provide usernames and application names for [identities](../explanations/identity.md) but can also be extended in the future to resolve other cryptocurrency addresses, websites, and more. DPNS is implemented as an application on top of the platform and leverages platform capabilities. -> πŸ‘ DPNS DIP -> -> The [DPNS Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips/blob/master/dip-0012.md) provides more extensive background information and details. +:::{tip} +The [DPNS Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips/blob/master/dip-0012.md) provides more extensive background information and details. +::: ### Relationship to identities @@ -18,11 +18,9 @@ DPNS names and [Identities](../explanations/identity.md) are tightly integrated. ## Details -### Name Registration Process +Given the DNS-compatible nature of DPNS, all DPNS names are technically domain names and are registered under a top-level DPNS domain (`.dash`). Some applications may abstract the top-level domain away, but it is important to be aware that it exists. -> πŸ“˜ -> -> Given the DNS-compatible nature of DPNS, all DPNS names are technically domain names and are registered under a top-level DPNS domain (`.dash`). Some applications may abstract the top-level domain away, but it is important to be aware that it exists. +### Name Registration Process To prevent [front-running](https://en.wikipedia.org/wiki/Domain_name_front_running), name registration is split into a two phase process consisting of: @@ -39,12 +37,18 @@ In the registration phase, the domain name (e.g. `alice.dash`) is once again sub ### Conflict resolution -Since some names may be popular, the registration process includes a voting mechanism to resolve conflicts when multiple identities request the same name. This is only done for names that meet both of the following conditions: +Since some names may be popular, the registration process includes a voting mechanism to resolve conflicts when multiple identities request the same name. Identities requesting premium names must pay a fee (200 credits) to cover the masternode voting costs. + +:::{note} +This process only applies to names that meet the following conditions: + +* Less than 20 characters long (i.e. "alice", "quantumexplorer") AND +* Contain no numbers or only contain the number(s) 0 and/or 1 (i.e. "bob", "carol01") -* Less than 20 characters long (i.e. "alice", "quantumexplorer") -* Contains no numbers or only contains the number(s) 0 and/or 1 (i.e. "bob", "carol01") +All other available names can be registered immediately. +::: -Identities requesting contested names must pay a fee (200 credits) to cover the masternode voting costs. The voting window begins when a name matching the criteria above is requested and ends after two weeks. Additional identities can request the same name during the first week. Masternodes and evonodes can vote for one of the identities, abstain, or vote to lock the request. +The voting window begins when a name matching the criteria above is requested and ends after two weeks. Additional identities can request the same name during the first week. Masternodes and evonodes can vote for one of the identities, abstain, or vote to lock the request. After voting concludes, the name is either awarded to one of the identities or locked. If the vote locks the name, no identity receives it. Locked names can no longer be requested or awarded in Dash Platform v1.0, but future updates may add unlock capabilities. @@ -52,12 +56,13 @@ Assuming masternodes do not vote to lock, the identity receiving the most votes ### Implementation -DPNS names have several constraints as defined in the [DPNS data contract](https://github.com/dashpay/platform/blob/v1.0.0-beta.3/packages/dpns-contract/schema/v1/dpns-contract-documents.json). The constraints provide compatibility with DNS and protection from homograph attacks: +DPNS names have several constraints as defined in the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json). The constraints provide compatibility with DNS and protection from homograph attacks: -* Maximum length - 63 characters -* Character set - `0-9`, `-` (hyphen), and `A-Z` (case insensitive) - * Note: Use of `-` as a prefix/suffix to a name is _not_ allowed (e.g. `-name` or `name-`). This constraint is defined by this JSON-Schema [pattern](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L38) in the DPNS data contract: `^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$` -* Domain labels are converted to lowercase for case-insensitive uniqueness validation. Then, "o", "i" and "l" replaced with "0" and "1" to mitigate [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack). For example, "Alice" is normalized "a11ce". +1. Maximum length - 63 characters +1. Character set - `0-9`, `-` (hyphen), and `A-Z` (case insensitive) + * Note: Use of `-` as a prefix/suffix to a name is _not_ allowed (e.g. `-name` or `name-`). This constraint is defined by this JSON-Schema [pattern](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L44) in the DPNS data contract: `"^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$` +1. Domain labels are converted to lowercase for case-insensitive uniqueness validation. +1. To mitigate [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), `o` is replaced with `0` and `i`/`l` are replaced with `1`. For example, "Alice" is normalized to "a11ce". Additional validation rules related to the `domain` document are enforced by the DPNS [data triggers](../explanations/platform-protocol-data-trigger.md) defined in [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/documents_batch/data_triggers/triggers). diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index d88f59cc7..e120ccd72 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -15,9 +15,9 @@ Fees on Dash Platform are divided into two main categories: Storage fees cover the costs to store the various types of data throughout the network, while processing fees cover the computational costs incurred by the masternodes to process state transitions. For everyday use, processing fees are minuscule compared to storage fees. However, they are important in the prevention of attacks on the network, in which case they become prohibitively expensive. -> πŸ‘ Fee System DIP -> -> Comprehensive details regarding fees will be available in an upcoming *Dash Platform Fee System* DIP. +:::{tip} +Comprehensive details regarding fees will be available in an upcoming *Dash Platform Fee System* DIP. +::: ## Costs @@ -34,9 +34,9 @@ The current cost schedule is outlined in the table below: | Load from memory | 20 / byte | | Blake3 hash function | 400 + 64 / 64-byte block | -> πŸ“˜ Credits -> -> Refer to the [Identity explanation](../explanations/identity.md) section for information regarding how credits are created. +:::{note} +Refer to the [Identity explanation](../explanations/identity.md) section for information regarding how credits are created. +::: ## Fee Multiplier diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index bc0943598..e72053548 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -10,9 +10,9 @@ Identities are foundational to Dash Platform. They provide a familiar, easy-to-u Identities are separate from names and can be thought of as a lower-level primitive that provides the foundation for various user-facing functionality. An identity consists primarily of one or more public keys recorded on the platform chain that can be used to control a user's profile and sign their documents. Each identity also has a balance of [credits](#credits) that is established by locking funds on layer 1. These credits are used to pay fees associated with the [state transitions](../explanations/platform-protocol-state-transition.md) used to perform actions on the platform. -> πŸ‘ Identities DIP -> -> The [Identities Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips/blob/master/dip-0011.md) provides more extensive background information and details. +:::{tip} +The [Identities Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips/blob/master/dip-0011.md) provides more extensive background information and details. +::: ## Identity Management @@ -22,9 +22,9 @@ Once an identity is created, its credit balance is used to pay for activity (e.g ### Identity Create Process -> πŸ“˜ Testnet Faucet -> -> On Testnet, a [test Dash faucet](https://testnet-faucet.dash.org/) is available. It dispenses small amounts to enable all users to directly acquire the funds necessary to create an identity and username. +:::{note} +On Testnet, a [test Dash faucet](https://insight.testnet.networks.dash.org:3002/insight/) is available. It dispenses small amounts to enable all users to directly acquire the funds necessary to create an identity and username. +::: First, a sponsor (which could be a business, another person, or even the same user who is creating the identity) spends Dash in a transaction to create an invitation. The transaction contains one or more outputs which lock some Dash funds to establish credits within Dash platform. @@ -36,9 +36,9 @@ Users who already have Dash funds can act as their own sponsor if they wish, usi The identity balance topup process works in a similar way to the initial identity creation funding. As with identity creation, a lock transaction is created on the layer 1 core blockchain. This lock transaction is then referenced in the [identity topup state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-topup-transition) which increases the identity's balance by the designated amount. -> πŸ“˜ -> -> 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. +:::{note} +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. +::: ### Identity Update Process @@ -66,6 +66,6 @@ Note: the payout key is associated with the masternode owner identity, so both t DPP v0.13 introduced the initial implementation of credits. As mentioned above, 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 transaction, their credit balance increases by that amount. As they perform platform actions, these credits are deducted to pay the associated fees. -> πŸ“˜ -> -> As of Dash Platform Protocol v1.0, credits deducted to pay state transition fees cannot be converted by masternodes back into Dash. This aspect of the credit system will come in a future release. +:::{attention} +As of Dash Platform v1.0, credits deducted to pay state transition fees cannot be converted back into Dash by masternodes. This aspect of the credit system will come in a future release. +::: diff --git a/docs/explanations/platform-consensus.md b/docs/explanations/platform-consensus.md index 63784bc41..0421aa20d 100644 --- a/docs/explanations/platform-consensus.md +++ b/docs/explanations/platform-consensus.md @@ -29,17 +29,15 @@ Tendermint has been mainly designed to enable efficient verification and authent - The Validator set committing the block. - Various results returned by the application. -> πŸ“˜ Notes about Tendermint -> -> - Block execution only occurs after a block is committed. So, cryptographic proofs for the latest state are only available in the subsequent block. -> -> - Information like the transaction results and the validator set is never directly included in the block - only their Merkle roots are. -> -> - Verification of a block requires a separate data structure to store this information. We call this the β€œState.” -> -> - Block verification also requires access to the previous block. -> -> Additional information about Tendermint is available in the Tendermint Core spec. +:::{note} + +- Block execution only occurs after a block is committed. So, cryptographic proofs for the latest state are only available in the subsequent block. +- Information like the transaction results and the validator set is never directly included in the block - only their Merkle roots are. +- Verification of a block requires a separate data structure to store this information. We call this the β€œState.” +- Block verification also requires access to the previous block. + +Additional information about Tendermint is available in the Tendermint Core spec. +::: ### Tendermint Limitations diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md index ecf595e46..ec6d09e01 100644 --- a/docs/explanations/platform-protocol-data-contract.md +++ b/docs/explanations/platform-protocol-data-contract.md @@ -56,275 +56,283 @@ Dash Platform v0.25 added key access rules that enable adding an encryption or d Dash Platform v0.22 added the ability to update existing data contracts in certain backwards-compatible ways. This includes adding new documents, adding new optional properties to existing documents, and adding non-unique indices for properties added in the update. -> πŸ“˜ -> -> For more detailed information, see the [Platform Protocol Reference - Data Contract](../protocol-ref/data-contract.md) page. +:::{note} +For more detailed information, see the [Platform Protocol Reference - Data Contract](../protocol-ref/data-contract.md) page. +::: ## Example Contract The [DashPay contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/dashpay.schema.json) is included below for reference. It defines a `contact` document and a `profile` document. Each of these documents then defines the properties and indices they require: -```json -{ - "profile": { - "type": "object", - "indices": [ - { - "name": "ownerId", - "properties": [ - { - "$ownerId": "asc" - } - ], - "unique": true +:::{dropdown} DashPay contract + ```json + { + "profile": { + "type": "object", + "indices": [ + { + "name": "ownerId", + "properties": [ + { + "$ownerId": "asc" + } + ], + "unique": true + }, + { + "name": "ownerIdAndUpdatedAt", + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "avatarUrl": { + "type": "string", + "format": "uri", + "minLength": 1, + "maxLength": 2048, + "position": 0 + }, + "avatarHash": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "description": "SHA256 hash of the bytes of the image specified by avatarUrl", + "position": 1 + }, + "avatarFingerprint": { + "type": "array", + "byteArray": true, + "minItems": 8, + "maxItems": 8, + "description": "dHash the image specified by avatarUrl", + "position": 2 + }, + "publicMessage": { + "type": "string", + "minLength": 1, + "maxLength": 140, + "position": 3 + }, + "displayName": { + "type": "string", + "minLength": 1, + "maxLength": 25, + "position": 4 + } }, - { - "name": "ownerIdAndUpdatedAt", - "properties": [ - { - "$ownerId": "asc" - }, - { - "$updatedAt": "asc" - } - ] - } - ], - "properties": { - "avatarUrl": { - "type": "string", - "format": "uri", - "maxLength": 2048, - "position": 0 + "minProperties": 1, + "dependentRequired": { + "avatarUrl": ["avatarHash", "avatarFingerprint"], + "avatarHash": ["avatarUrl", "avatarFingerprint"], + "avatarFingerprint": ["avatarUrl", "avatarHash"] }, - "avatarHash": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "description": "SHA256 hash of the bytes of the image specified by avatarUrl", - "position": 1 - }, - "avatarFingerprint": { - "type": "array", - "byteArray": true, - "minItems": 8, - "maxItems": 8, - "description": "dHash the image specified by avatarUrl", - "position": 2 - }, - "publicMessage": { - "type": "string", - "maxLength": 140, - "position": 3 - }, - "displayName": { - "type": "string", - "maxLength": 25, - "position": 4 - } + "required": [ + "$createdAt", + "$updatedAt" + ], + "additionalProperties": false }, - "required": [ - "$createdAt", - "$updatedAt" - ], - "additionalProperties": false - }, - "contactInfo": { - "type": "object", - "indices": [ - { - "name": "ownerIdAndKeys", - "properties": [ - { - "$ownerId": "asc" - }, - { - "rootEncryptionKeyIndex": "asc" - }, - { - "derivationEncryptionKeyIndex": "asc" - } - ], - "unique": true - }, - { - "name": "ownerIdAndUpdatedAt", - "properties": [ - { - "$ownerId": "asc" - }, - { - "$updatedAt": "asc" - } - ] - } - ], - "properties": { - "encToUserId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "position": 0 - }, - "rootEncryptionKeyIndex": { - "type": "integer", - "minimum": 0, - "position": 1 - }, - "derivationEncryptionKeyIndex": { - "type": "integer", - "minimum": 0, - "position": 2 + "contactInfo": { + "type": "object", + "indices": [ + { + "name": "ownerIdAndKeys", + "properties": [ + { + "$ownerId": "asc" + }, + { + "rootEncryptionKeyIndex": "asc" + }, + { + "derivationEncryptionKeyIndex": "asc" + } + ], + "unique": true + }, + { + "name": "ownerIdAndUpdatedAt", + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "encToUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "position": 0 + }, + "rootEncryptionKeyIndex": { + "type": "integer", + "minimum": 0, + "position": 1 + }, + "derivationEncryptionKeyIndex": { + "type": "integer", + "minimum": 0, + "position": 2 + }, + "privateData": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 2048, + "position": 3, + "description": "This is the encrypted values of aliasName + note + displayHidden encoded as an array in cbor" + } }, - "privateData": { - "type": "array", - "byteArray": true, - "minItems": 48, - "maxItems": 2048, - "position": 3, - "description": "This is the encrypted values of aliasName + note + displayHidden encoded as an array in cbor" - } + "required": [ + "$createdAt", + "$updatedAt", + "encToUserId", + "privateData", + "rootEncryptionKeyIndex", + "derivationEncryptionKeyIndex" + ], + "additionalProperties": false }, - "required": [ - "$createdAt", - "$updatedAt", - "encToUserId", - "privateData", - "rootEncryptionKeyIndex", - "derivationEncryptionKeyIndex" - ], - "additionalProperties": false - }, - "contactRequest": { - "requiresIdentityEncryptionBoundedKey": 2, - "requiresIdentityDecryptionBoundedKey": 2, - "type": "object", - "indices": [ - { - "name": "ownerIdUserIdAndAccountRef", - "properties": [ - { - "$ownerId": "asc" - }, - { - "toUserId": "asc" - }, - { - "accountReference": "asc" - } - ], - "unique": true - }, - { - "name": "ownerIdUserId", - "properties": [ - { - "$ownerId": "asc" - }, - { - "toUserId": "asc" - } - ] - }, - { - "name": "userIdCreatedAt", - "properties": [ - { - "toUserId": "asc" - }, - { - "$createdAt": "asc" - } - ] - }, - { - "name": "ownerIdCreatedAt", - "properties": [ - { - "$ownerId": "asc" - }, - { - "$createdAt": "asc" - } - ] - } - ], - "properties": { - "toUserId": { - "type": "array", - "byteArray": true, - "minItems": 32, - "maxItems": 32, - "position": 0, - "contentMediaType": "application/x.dash.dpp.identifier" - }, - "encryptedPublicKey": { - "type": "array", - "byteArray": true, - "minItems": 96, - "maxItems": 96, - "position": 1 - }, - "senderKeyIndex": { - "type": "integer", - "minimum": 0, - "position": 2 + "contactRequest": { + "documentsMutable": false, + "canBeDeleted": false, + "requiresIdentityEncryptionBoundedKey": 2, + "requiresIdentityDecryptionBoundedKey": 2, + "type": "object", + "indices": [ + { + "name": "ownerIdUserIdAndAccountRef", + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + }, + { + "accountReference": "asc" + } + ], + "unique": true + }, + { + "name": "ownerIdUserId", + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + } + ] + }, + { + "name": "userIdCreatedAt", + "properties": [ + { + "toUserId": "asc" + }, + { + "$createdAt": "asc" + } + ] + }, + { + "name": "ownerIdCreatedAt", + "properties": [ + { + "$ownerId": "asc" + }, + { + "$createdAt": "asc" + } + ] + } + ], + "properties": { + "toUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "position": 0, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "encryptedPublicKey": { + "type": "array", + "byteArray": true, + "minItems": 96, + "maxItems": 96, + "position": 1 + }, + "senderKeyIndex": { + "type": "integer", + "minimum": 0, + "position": 2 + }, + "recipientKeyIndex": { + "type": "integer", + "minimum": 0, + "position": 3 + }, + "accountReference": { + "type": "integer", + "minimum": 0, + "position": 4 + }, + "encryptedAccountLabel": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 80, + "position": 5 + }, + "autoAcceptProof": { + "type": "array", + "byteArray": true, + "minItems": 38, + "maxItems": 102, + "position": 6 + } }, - "recipientKeyIndex": { - "type": "integer", - "minimum": 0, - "position": 3 - }, - "accountReference": { - "type": "integer", - "minimum": 0, - "position": 4 - }, - "encryptedAccountLabel": { - "type": "array", - "byteArray": true, - "minItems": 48, - "maxItems": 80, - "position": 5 - }, - "autoAcceptProof": { - "type": "array", - "byteArray": true, - "minItems": 38, - "maxItems": 102, - "position": 6 - }, - "coreHeightCreatedAt": { - "type": "integer", - "minimum": 1, - "position": 7 - } - }, - "required": [ - "$createdAt", - "toUserId", - "encryptedPublicKey", - "senderKeyIndex", - "recipientKeyIndex", - "accountReference" - ], - "additionalProperties": false + "required": [ + "$createdAt", + "$createdAtCoreBlockHeight", + "toUserId", + "encryptedPublicKey", + "senderKeyIndex", + "recipientKeyIndex", + "accountReference" + ], + "additionalProperties": false + } } -} -``` + ``` -This is a visualization of the JSON data contract as UML class diagram for better understanding of the structure: + This is a visualization of the JSON data contract as UML class diagram for better understanding of the structure: -```{eval-rst} -.. figure:: ./img/dashpay-uml.png - :class: no-scaled-link - :align: center - :width: 90% - :alt: Dashpay Contract Diagram + ```{eval-rst} + .. figure:: ./img/dashpay-uml.png + :class: no-scaled-link + :align: center + :width: 90% + :alt: Dashpay Contract Diagram - Dashpay Contract Diagram -``` + Dashpay Contract Diagram + ``` -View [a full-size copy of this diagram](./img/dashpay-uml.png). + View [a full-size copy of this diagram](./img/dashpay-uml.png). diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index e28d19de2..d7a561035 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -4,17 +4,15 @@ # 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 the initial version of Dash Platform. The design will likely undergo changes in the future. ## 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. -> ❗️ Constraints -> -> 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. +:::{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. +::: ## Details diff --git a/docs/explanations/platform-protocol-document.md b/docs/explanations/platform-protocol-document.md index 4ef649e3b..d501f2c06 100644 --- a/docs/explanations/platform-protocol-document.md +++ b/docs/explanations/platform-protocol-document.md @@ -26,13 +26,13 @@ Dash Platform Protocol (DPP) defines a set of base fields that must be present i | $createdAt | Time (in milliseconds) the document was created | | $updatedAt | Time (in milliseconds) the document was last updated | -> 🚧 Timestamp fields -> -> Note: The `$createdAt` and `$updatedAt` fields will only be present in documents that add them to the list of [required properties](../reference/data-contracts.md#required-properties-optional). +:::{attention} +The `$createdAt` and `$updatedAt` fields will only be present in documents that add them to the list of [required properties](../reference/data-contracts.md#required-properties-optional). +::: ### Data Contract Fields -Each application defines its own fields via document definitions in its data contract. Details of the [DPNS data contract documents](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) are described below as an example. This contract defines two document types (`preorder` and `domain`) and provides the functionality described in the [Name Service explanation](../explanations/dpns.md). +Each application defines its own fields via document definitions in its data contract. Details of the [DPNS data contract documents](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json) are described below as an example. This contract defines two document types (`preorder` and `domain`) and provides the functionality described in the [Name Service explanation](../explanations/dpns.md). | Document Type | Field Name | Data Type | | - | - | - | @@ -114,6 +114,6 @@ The document replace transition is used to update the data in an existing Dash P The document delete transition is used to delete an existing Dash Platform document. It only requires the fields found in the base document transition. -> πŸ“˜ -> -> For more detailed information, see the [Platform Protocol Reference - Document](../protocol-ref/document.md) page. +:::{note} +For more detailed information, see the [Platform Protocol Reference - Document](../protocol-ref/document.md) page. +::: diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md index d5c481907..bdfcd1dc3 100644 --- a/docs/explanations/platform-protocol-state-transition.md +++ b/docs/explanations/platform-protocol-state-transition.md @@ -51,6 +51,6 @@ State transitions are constructed by client-side libraries and then submitted to Some state transitions (e.g. data contracts, identity) are validated solely by rules explicitly defined in DPP, while others (e.g. documents) are also subject to the rules defined by the relevant application’s data contract. Once the state transition has been validated, the platform stores the data and updates the platform state. -> πŸ“˜ -> -> For more detailed information, see the [Platform Protocol Reference - State Transition](../protocol-ref/state-transition.md) page. +:::{note} +For more detailed information, see the [Platform Protocol Reference - State Transition](../protocol-ref/state-transition.md) page. +::: diff --git a/docs/explanations/platform-protocol.md b/docs/explanations/platform-protocol.md index 0616d60fa..d02446bb0 100644 --- a/docs/explanations/platform-protocol.md +++ b/docs/explanations/platform-protocol.md @@ -14,9 +14,9 @@ To ensure the consistency and integrity of data stored on Layer 2, all data is g A data contract is a database schema that a developer needs to register with the platform in order to start using any decentralized storage functionality. Data contracts are described using the JSON Schema language and must follow some basic rules as described in the platform protocol repository. -> πŸ“˜ Contract updates -> -> Dash's data contracts support backwards-compatible modifications after their initial deployment unlike many smart contract based systems. This provides developers with additional flexibility when designing applications. +:::{note} +Dash's data contracts support backwards-compatible modifications after their initial deployment unlike many smart contract based systems. This provides developers with additional flexibility when designing applications. +::: For additional detail, see the [Data Contract](../explanations/platform-protocol-data-contract.md) explanation. diff --git a/docs/other/key-concepts.md b/docs/other/key-concepts.md index 85550e209..9eec26435 100644 --- a/docs/other/key-concepts.md +++ b/docs/other/key-concepts.md @@ -8,7 +8,7 @@ In order to pay for these various operations, Dash must be spent by either the a # Data Contracts -A data contract is an agreement between your application and the Dash network as to how your data should be stored and validated by the Dash network. The concept is analogous to creating a schema for a document-oriented database. Data contracts are JSON objects, and an example contract for the [Dash Platform Naming Service (DPNS)](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) is included below: +A data contract is an agreement between your application and the Dash network as to how your data should be stored and validated by the Dash network. The concept is analogous to creating a schema for a document-oriented database. Data contracts are JSON objects, and an example contract for the [Dash Platform Naming Service (DPNS)](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json) is included below: ```json { diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md index c6957cae0..b82bcb905 100644 --- a/docs/reference/query-syntax.md +++ b/docs/reference/query-syntax.md @@ -8,19 +8,9 @@ Generally queries will consist of a `where` clause plus optional [modifiers](#query-modifiers) controlling the specific subset of results returned. -> 🚧 Query limitations -> -> Dash Platform v0.22 introduced a number of limitations due to the switch to using [GroveDB](https://github.com/dashpay/grovedb). See details in pull requests [77](https://github.com/dashpay/platform/pull/77) and [230](https://github.com/dashpay/platform/pull/230) that implemented these changes. -> -> Query validation details may be found [here](https://github.com/dashpay/platform/blob/master/packages/js-drive/lib/document/query/validateQueryFactory.js) along with the associated validation [tests](https://github.com/dashpay/platform/blob/master/packages/js-drive/test/unit/document/query/validateQueryFactory.spec.js). - ## Where Clause -The Where clause must be a non-empty array containing not more than 10 conditions. For some operators, `value` will be an array. See the following general syntax example: - ->❗️ -> -> As of Dash Platform v0.22, _all fields_ referenced in a query's where clause must be defined in the _same index_. This includes `$createdAt` and `$updatedAt`. +The Where clause must be a non-empty array containing not more than 10 conditions. For some operators, `value` will be an array. All fields referenced in a query's where clause must be defined in the same index. This includes `$createdAt` and `$updatedAt`. See the following general syntax example: ```json Syntax { @@ -33,13 +23,12 @@ The Where clause must be a non-empty array containing not more than 10 condition ### Fields -Valid fields consist of the indices defined for the document being queried. For example, the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) defines three indices: +Valid fields consist of the indices defined for the document being queried. For example, the [DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json) defines two indices for domain documents: | Index Field(s) | Index Type | Unique | | - | - | :-: | -| [normalizedParentDomainName, normalizedLabel](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L5-L16) | Compound | Yes | -| [records.dashUniqueIdentityId](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L17-L25) | Single Field | Yes | -| [records.dashAliasIdentityId](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L26-L33) | Single Field | No | +| [normalizedParentDomainName, normalizedLabel](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L5-L16) | Compound | Yes | +| [records.identity](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json#L31-L39) | Single Field | No | ```{eval-rst} .. @@ -61,14 +50,6 @@ Valid fields consist of the indices defined for the document being queried. For #### Range -> 🚧 Dash Platform v0.22 notes -> -> - Only one range operator is allowed in a query (except for between behavior) -> - The `in` operator is only allowed for last two indexed properties -> - Range operators are only allowed after `==` and `in` operators -> - Range operators are only allowed for the last two fields used in the where condition -> - Queries using range operators must also include an `orderBy` statement - | Name | Description | | :-: | - | | < | Matches values that are less than a specified value | @@ -77,13 +58,13 @@ Valid fields consist of the indices defined for the document being queried. For | > | Matches values that are greater than a specified value | | in | Matches all document(s) where the value of the field equals any value in the specified array
Array may include up to 100 (unique) elements | -### Array Operators - -| Name | Description | -| :-: | - | -| length | **Not available in Dash Platform v0.22**
Selects documents if the array field is a specified size (integer) | -| contains | **Not available in Dash Platform v0.22**
- Matches arrays that contain all elements specified in the query condition array
- 100 element maximum -| elementMatch | **Not available in Dash Platform v0.22**
- Matches documents that contain an array field with at least one element that matches all the criteria in the query condition array
- Two or more conditions must be provided +:::{tip} +- Only one range operator is allowed in a query (except for between behavior) +- The `in` operator is only allowed for last two indexed properties +- Range operators are only allowed after `==` and `in` operators +- Range operators are only allowed for the last two fields used in the where condition +- Queries using range operators must also include an `orderBy` statement +::: ### Evaluation Operators @@ -93,94 +74,59 @@ Valid fields consist of the indices defined for the document being queried. For ### Operator Examples -```json < +::::{tab-set} +:::{tab-item} Range +```json { where: [ - ['nameHash', '<', '56116861626961756e6176657a382e64617368'], + ["nameHash", "<", "56116861626961756e6176657a382e64617368"], ], } ``` +::: +:::{tab-item} in ```json in { where: [ - ['normalizedParentDomainName', '==', 'dash'], + ["normalizedParentDomainName", "==", "dash"], // Return all matching names from the provided array - ['normalizedLabel', 'in', ['alice', 'bob']], + ["normalizedLabel", "in", ["alice", "bob"]], ] } ``` +::: +:::{tab-item} startsWith ```json startsWith { where: [ - ['normalizedParentDomainName', '==', 'dash'], + ["normalizedParentDomainName", "==", "dash"], // Return any names beginning with "al" (e.g. alice, alfred) - ['normalizedLabel', 'startsWith', 'al'], - ] -} -``` - -```json length -// Not available in Dash Platform v0.22 -// See https://github.com/dashpay/platform/pull/77 -{ - where: [ - // Return documents that have 5 values in their `items` array - ['items', 'length', 5], - ] -} -``` - -```json contains -// Not available in Dash Platform v0.22 -// See https://github.com/dashpay/platform/pull/77 -{ - where: [ - // Return documents that have both "red" and "blue" - // in the `colors` array - ['colors', 'contains', ['red', 'blue']], - ] -} -``` - -```json elementMatch -// Not available in Dash Platform v0.22 -// See https://github.com/dashpay/platform/pull/77 -{ - where: [ - // Return `scores` documents where the results contain - // elements in the range 80-90 - ['scores', 'elementMatch', - [ - ['results', '>=', '80'], - ['results', '<=', '90'] - ], + ["normalizedLabel", "startsWith", "al"], ], + orderBy: [ + ["normalizedLabel", "asc"], ] } ``` +::: +:::: ## Query Modifiers The query modifiers described here determine how query results will be sorted and what subset of data matching the query will be returned. ->❗️ Breaking changes -> -> Starting with Dash Platform v0.22, `startAt` and `startAfter` must be provided with a document ID rather than an integer. - | Modifier | Effect | Example | | - | - | - | | `limit` | Restricts the number of results returned (maximum: 100) | `limit: 10` | -| `orderBy` | Returns records sorted by the field(s) provided (maximum: 2). Sorting must be by the last indexed property. Can only be used with `>`, `<`, `>=`, `<=`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` +| `orderBy` | Returns records sorted by the field(s) provided (maximum: 2). Sorting must be by the last indexed property. Can only be used with `>`, `<`, `>=`, `<=`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` | | `startAt` | Returns records beginning with the document ID provided | `startAt: Buffer.from(Identifier.from())` | | `startAfter` | Returns records beginning after the document ID provided | `startAfter: Buffer.from(Identifier.from())` | -> 🚧 Compound Index Constraints -> -> For indices composed of multiple fields ([example from the DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json)), the sort order in an `orderBy` must either match the order defined in the data contract OR be the inverse order. -> -> Please refer to [pull request 230](https://github.com/dashpay/platform/pull/230) for additional information related to compound index constraints in Platform v0.22. +:::{attention} +For indices composed of multiple fields ([example from the DPNS data contract](https://github.com/dashpay/platform/blob/master/packages/dpns-contract/schema/v1/dpns-contract-documents.json)), the sort order in an `orderBy` must either match the order defined in the data contract OR be the inverse order. +::: ## Example query diff --git a/docs/sdk-rs/overview.md b/docs/sdk-rs/overview.md index 65b85bb22..f08ad9776 100644 --- a/docs/sdk-rs/overview.md +++ b/docs/sdk-rs/overview.md @@ -27,11 +27,11 @@ detailed examples or see a simple example in the See the [Platform Terminal User Interface (TUI)](https://github.com/dashpay/platform-tui/) for an application that uses the SDK to execute various state transitions. -> 🚧 Work in progress -> -> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, -> the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available -> for reference. Please keep in mind that it is incomplete and may be outdated. +:::{attention} +SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, +the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available +for reference. Please keep in mind that it is incomplete and may be outdated. +::: ### Mocking diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md index 100e3b823..e9bf3dbec 100644 --- a/docs/sdk-rs/quick-start.md +++ b/docs/sdk-rs/quick-start.md @@ -65,15 +65,16 @@ rpcpassword= Restart Dash Core to apply the changes. -> 🚧 **Using Dash Platform without Dash Core** -> -> The Rust SDK requests proofs for all data retrieved from Platform. This makes it the recommended -> (most secure) option, but also is why a Dash Core full node is currently required. -> -> The [JavaScript SDK](../tutorials/introduction.md) provides access to Dash Platform without -> requiring a full node; however, it **_does not support Dash Platform's proofs_**. The Rust DAPI -> client can also perform read operations without a full node if proofs are not requested. See the -> [DAPI client example](#dapi-client-example) below for details. +:::{admonition} **Using Dash Platform without Dash Core** +:class: attention +The Rust SDK requests proofs for all data retrieved from Platform. This makes it the recommended +(most secure) option, but also is why a Dash Core full node is currently required. + +The [JavaScript SDK](../tutorials/introduction.md) provides access to Dash Platform without +requiring a full node; however, it **_does not support Dash Platform's proofs_**. The Rust DAPI +client can also perform read operations without a full node if proofs are not requested. See the +[DAPI client example](#dapi-client-example) below for details. +::: ## Create a new project @@ -169,11 +170,11 @@ Identity balance: 932523994 ## SDK documentation -> 🚧 Work in progress -> -> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, -> the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available -> for reference. Please keep in mind that it is incomplete and may be outdated. +:::{attention} +SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, +the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available +for reference. Please keep in mind that it is incomplete and may be outdated. +::: ## DAPI client example