diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md index c53f05a59..b5cc9eeac 100644 --- a/docs/explanations/dapi.md +++ b/docs/explanations/dapi.md @@ -31,4 +31,4 @@ retrieval. ## Endpoint Overview -DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). The JSON-RPC endpoints expose some layer 1 information while the gRPC endpoints support layer 2 as well as streaming of events related to blocks and transactions/transitions. For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md). +DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). The JSON-RPC endpoints expose some layer 1 information while the gRPC endpoints support layer 2 as well as streaming of events related to blocks, transactions/transitions, and masternode-list updates. For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md). diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md index 36e77dc71..b81b00d1d 100644 --- a/docs/explanations/drive-platform-chain.md +++ b/docs/explanations/drive-platform-chain.md @@ -22,7 +22,7 @@ In order to support Dash Platform's performance requirements, the platform chain - Hosted exclusively on masternodes - Uses a [practical Byzantine Fault Tolerance (pBFT)](../reference/glossary.md#practical-byzantine-fault-tolerance-pbft) consensus algorithm - Has a deterministic fee structure -- Provides fast (< 10 seconds) and absolute block finality (no reorgs) +- Provides fast (~5 second target block spacing) and absolute block finality (no reorgs) ### Blocks and Transitions diff --git a/docs/explanations/drive-platform-state.md b/docs/explanations/drive-platform-state.md index d9fd9738f..10706e5dd 100644 --- a/docs/explanations/drive-platform-state.md +++ b/docs/explanations/drive-platform-state.md @@ -6,7 +6,7 @@ Platform state represents the current state of all the data stored on the platform. You can think about this as one large database, where each application has its own database (Application State) defined by the Data Contract associated with the application. Therefore, the platform state can be thought of as a global view of all Dash Platform data, whereas the application state is a local view of one application's data. -The Platform Chain is processed by a state machine to reach consensus on how to build the state and what it should look like. The last block of the Platform Chain contains the root of the tree structure built from all documents in the platform state. By checking the root of the state tree stored in the block, the node can confirm that it has the correct state. +The Platform Chain is processed by a state machine to reach consensus on how to build the state and what it should look like. Each committed block's header contains an AppHash that commits to the root of the state tree after the block's execution. By checking the AppHash stored in the block, a node can confirm that it has the correct state. ```{eval-rst} .. figure:: ../../img/platform-state.svg @@ -17,3 +17,13 @@ The Platform Chain is processed by a state machine to reach consensus on how to Platform State Propagation ``` + +## GroveDB and AppHash + +Platform state is stored in [GroveDB](https://github.com/dashpay/grovedb), a hierarchical authenticated data structure maintained by Drive. Because GroveDB is authenticated, each operation that mutates state also updates an aggregate root hash that commits to the entire state tree. + +Under the [Tenderdash](../explanations/platform-consensus.md) same-block execution model, state transitions in a proposed block are validated and applied during block processing. The resulting state-tree root is then embedded in the committed block's header as the `AppHash`, meaning the committed block itself commits to the post-execution state. + +## Proofs + +Because state is stored in GroveDB, [DAPI](../explanations/dapi.md) queries can return GroveDB proofs alongside the requested data. Clients verify these proofs against the block header's `AppHash` (which itself is signed by the validator quorum), allowing light clients to trustlessly confirm the returned data without re-executing the chain. diff --git a/docs/explanations/drive.md b/docs/explanations/drive.md index bee7c69a3..f4dadeebe 100644 --- a/docs/explanations/drive.md +++ b/docs/explanations/drive.md @@ -18,13 +18,14 @@ There are a number of components working together to facilitate Drive's overall - Platform state machine (validates data against the [Dash platform protocol](../explanations/platform-protocol.md); applies data to state and storage) - [Platform state](../explanations/drive-platform-state.md) (represents current data) - Storage (record of state transitions) +- GroveDB (authenticated hierarchical storage backend enabling cryptographic proofs returned via [DAPI](../explanations/dapi.md)) ### Data Update Process The process of adding or updating data in Drive consists of several steps to ensure data is validated, propagated, and stored properly. This description provides a simplified overview of the process: 1. [State transitions](../explanations/platform-protocol-state-transition.md) are submitted to the platform via [DAPI](../explanations/dapi.md) -2. DAPI sends the state transitions to the platform chain where they are validated, ordered, and committed to a block +2. DAPI broadcasts state transitions to Tenderdash, which validates them and includes them in block proposals 3. Valid state transitions are applied to the platform state 4. The platform chain propagates a block containing the state transitions 5. Receiving nodes update Drive data based on the valid state transitions in the block diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index 6f7e70c9e..7987584cb 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -34,6 +34,8 @@ The current cost schedule is outlined in the table below: | Load from memory | 10 / byte | | Blake3 hash function | 100 base + 300 / 64-byte block | +Processing fees vary by operation. The value shown is a representative base cost; the total processing fee for a state transition is the sum of the individual per-operation costs incurred while validating and applying it. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the full cost schedule. + :::{note} Refer to the [Identity explanation](../explanations/identity.md) section for information regarding how credits are created. ::: diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index 05ac5535e..b5e2b96b2 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -16,7 +16,7 @@ The [Identities Dash Improvement Proposal (DIP)](https://github.com/dashpay/dips ## Identity Management -In order to [create an identity](#identity-create-process), a user pays the network to store their public key(s) on the platform chain. Since new users may not have existing Dash funds, an invitation process will allow users to create an identity despite lacking their own funds. The invitation process will effectively separate the funding and registration steps that are required for any new identity to be created. +In order to [create an identity](#identity-create-process), a user pays the network to store their public key(s) on the platform chain. This is done by locking Dash on the Core chain in an asset lock transaction and then submitting an identity create state transition that references a proof of that lock. 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. @@ -26,11 +26,11 @@ Once an identity is created, its credit balance is used to pay for activity (e.g On Testnet, a [test Dash faucet](https://faucet.testnet.networks.dash.org/) 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. +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. -After the transaction is broadcast and confirmed, the sponsor sends information about the invitation to the new user. This may be done as a hyperlink that the core wallet understands, or as a QR code that a mobile wallet can scan. Once the user has the transaction data from the sponsor, they can use it to fund an [identity create state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-create-transition) within Dash platform. +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. -Users who already have Dash funds can act as their own sponsor if they wish, using the same steps listed here. +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. ### Identity Balance Topup Process @@ -64,6 +64,6 @@ Note: the payout key is associated with the masternode owner identity, so both t ## Credits -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. +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. 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. diff --git a/docs/explanations/nft.md b/docs/explanations/nft.md index f163f8e7a..4829cb824 100644 --- a/docs/explanations/nft.md +++ b/docs/explanations/nft.md @@ -39,7 +39,7 @@ NFTs can be directly transferred or traded without the need for a marketplace: To preserve the authenticity of NFTs, Dash Platform includes creation restriction options. This ensures that only authorized entities can create certain types of NFTs. For example, in the case of land ownership NFTs, a designated authority may be the only one that can issue tokens. Restriction options are: -* **Owner Only**: Only the contract owner can create NFTs (**_Note: this is the only option implemented for the initial release_**) +* **Owner Only**: Only the contract owner can create NFTs * **No Creation Allowed**: NFT creation is disabled for this contract * **No Restrictions**: Anyone can create NFTs for the contract @@ -77,7 +77,7 @@ Once the data contract design is completed, the contract can be registered on th ### Minting NFTs -Tokens are minted by creating new documents under the data contract. Each token is an instance of one of the document types defined in the contract. +NFTs are minted by creating new documents under the data contract. Each NFT is an instance of one of the document types defined in the contract. ```{eval-rst} .. _explanations-nft-trade: diff --git a/docs/explanations/platform-consensus.md b/docs/explanations/platform-consensus.md index 0421aa20d..73afaccf1 100644 --- a/docs/explanations/platform-consensus.md +++ b/docs/explanations/platform-consensus.md @@ -31,7 +31,7 @@ Tendermint has been mainly designed to enable efficient verification and authent :::{note} -- Block execution only occurs after a block is committed. So, cryptographic proofs for the latest state are only available in the subsequent block. +- In classic Tendermint, block execution occurs after commit, so state proofs appear in the subsequent block. Tenderdash (used by Dash Platform) performs same-block execution, so the committed block's AppHash already commits to the post-execution state. - 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. @@ -41,7 +41,7 @@ Additional information about Tendermint is available in the 1) | +| recipientOwnerId | array (32 bytes) | The identity receiving ownership of the document | + +Document transfers are only allowed for document types that are marked transferable in the data contract. + +### Document Purchase + +The document purchase transition is used to buy a document that the current owner has listed for sale. It extends the [base schema](#base-fields) with the agreed price: + +| Field | Type | Description | +| - | - | - | +| $revision | integer | Document revision (=> 1) | +| price | integer | Price (in credits) the buyer is paying, which must match the document's current listed price | + +Document purchases are only allowed for document types whose trade mode permits sale. + +### Document Update Price + +The document update price transition is used by the current owner to list a document for sale (or change its listed price). It extends the [base schema](#base-fields) with the new price: + +| Field | Type | Description | +| - | - | - | +| $revision | integer | Document revision (=> 1) | +| price | integer | New price (in credits) at which the document is offered for sale | + :::{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 705a02f03..46b2f4e2c 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-overview) (`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) (`create`, `replace`, `delete`, `transfer`, `purchase`, `updatePrice`) or [token](../explanations/tokens.md) (e.g. mint, burn, transfer, freeze/unfreeze, claim, direct purchase, set price) 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/explanations/platform-protocol.md b/docs/explanations/platform-protocol.md index d2ce2c80c..6191b6330 100644 --- a/docs/explanations/platform-protocol.md +++ b/docs/explanations/platform-protocol.md @@ -6,7 +6,7 @@ ## Overview -To ensure the consistency and integrity of data stored on Layer 2, all data is governed by the Dash Platform Protocol (DPP). Dash Platform Protocol describes serialization and validation rules for the platform's 3 core data structures: data contracts, documents, and state transitions. Each of these structures are briefly described below. +To ensure the consistency and integrity of data stored on Layer 2, all data is governed by the Dash Platform Protocol (DPP). Dash Platform Protocol describes serialization and validation rules for the platform's core data structures: data contracts (including tokens, groups, and keywords), documents, and state transitions. Each of these structures are briefly described below. ## Structure Descriptions @@ -40,6 +40,16 @@ The user signature is made for the binary representation of the state transition For additional detail, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. +### Contract-level features + +In addition to documents, a data contract may declare: + +* **Tokens** - fungible token definitions with their own configuration, distribution, and authorization rules. See the [Tokens](../explanations/tokens.md) explanation. +* **Groups** - sets of identities with assigned power that can jointly authorize token and other privileged actions on the contract. +* **Keywords** - contract-level discovery terms that allow contracts to be searched and surfaced by clients. + +For additional detail, see the [Data Contract](../explanations/platform-protocol-data-contract.md) explanation. + ## Versions Platform Protocol evolves together with the public Dash Platform codebase. For the latest diff --git a/docs/explanations/query.md b/docs/explanations/query.md index a8a5624aa..26b6011bd 100644 --- a/docs/explanations/query.md +++ b/docs/explanations/query.md @@ -52,6 +52,8 @@ Proofs are especially valuable for: Dash Platform requires queries to use indexes defined in the data contract for the relevant document 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. + Benefits of indexed querying include: - Predictable performance @@ -59,5 +61,5 @@ Benefits of indexed querying include: :::{important} Indexes should be planned during contract design since there are [limited index update -options](./platform-protocol-data-contract.md#contract-updates) for already registered contracts. +options](./platform-protocol-data-contract.md#updates) for already registered contracts. ::: diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index 3fd8baca3..73f21af07 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -70,7 +70,9 @@ The initial token implementation includes all actions required to create, use, a #### Claim -- Claim tokens that have been created by a distribution method (e.g., preprogrammed). Tokens created this way are not directly assigned to the authorized identity, but must be claimed to take ownership. +- 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. #### Emergency Action @@ -114,6 +116,7 @@ When creating a token, you define its configuration using the following paramete | [Main control group](#main-control-group)| Yes | None | | Main control group can be modified | Yes | NoOne | | Marketplace rules | Yes | None | +| [Distribution rules](#distribution-rules)| Yes | None | #### Display Conventions @@ -233,7 +236,7 @@ Groups can be used to distribute token configuration and update authorization ac - Each group member is assigned an integer power. - The group itself has a required power threshold to authorize an action. -- Groups can have up to 256 members, each with a maximum power of 2^16 - 1 (65535). +- 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). **Example** @@ -267,6 +270,8 @@ This allows for: Creating a token on Dash Platform consists of creating a data contract, registering it on the network, and then creating tokens based on the schema defined in the data contract. +When a contract that declares a token is registered, Platform automatically mints the token's configured base supply to the contract owner (or to the destination configured for new tokens). A single contract may declare more than one token; each token is identified by its position within the contract and configured independently. Ongoing changes to token balances - including further minting, burning, transfers, freezes, and claims - are performed through the [token state transitions](#actions). + ### Contract Setup Structurally, there is no difference between contracts incorporating tokens and non-token contracts. While token contracts have a large set of token-specific options, there is no other difference. @@ -285,4 +290,9 @@ When enabled, the authorized party can set the token price using a state transit ### Marketplace -A planned token marketplace will support the trading of tokens. +Token contracts already expose marketplace rules in their configuration, which declares a trade mode that governs how tokens may be traded on Platform. The currently supported trade modes are: + +- **`NotTradeable`** - the token cannot be traded on Platform (default). +- **`TradeableOnMarketplace`** - the token is eligible for trading via Platform's marketplace mechanism. + +The protocol-level marketplace rules are in place, but broader client tooling and user-facing marketplace experiences are expected to continue evolving in future releases.