diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md index 9c50e1cfe..5e51ad78e 100644 --- a/docs/explanations/dapi.md +++ b/docs/explanations/dapi.md @@ -31,4 +31,11 @@ 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. The layer 1 Core gRPC service additionally provides streaming of events related to blocks, transactions, and masternode-list updates; the layer 2 Platform endpoints are request/response only. For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md). +DAPI currently provides 2 types of endpoints: [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/docs/guides/). + +- JSON-RPC endpoints are a small surface that mostly exposes layer 1 information, with the exception of a Platform status method +- gRPC endpoints cover both Core and Platform: + - Core endpoints are mostly request/response, plus streaming subscriptions for block headers, transactions, and masternode-list updates + - Platform endpoints are request/response only. + +For a list of all endpoints and usage details, please see the [DAPI endpoint reference section](../reference/dapi-endpoints.md). diff --git a/docs/explanations/dashpay.md b/docs/explanations/dashpay.md index 3a37d86d8..424b450c5 100644 --- a/docs/explanations/dashpay.md +++ b/docs/explanations/dashpay.md @@ -78,7 +78,8 @@ DashPay has many constraints as defined in the [DashPay data contract](https://github.com/dashpay/platform/blob/master/packages/dashpay-contract/schema/v1/dashpay.schema.json). Additionally, the DashPay data triggers defined in [rs-drive-abci](https://github.com/dashpay/platform/tree/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/triggers/dashpay) -enforce additional validation rules related to the `contactRequest` document. +enforce additional validation rules related to the `contactRequest` document. Note: as a system data +contract, the version active on a network is determined by that network's active protocol version. :::{tip} See the [DashPay Dash Improvement Proposal diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md index ea247c9cc..16e782bf4 100644 --- a/docs/explanations/dpns.md +++ b/docs/explanations/dpns.md @@ -87,7 +87,8 @@ DPNS names have several constraints as defined in the [DPNS data contract](https 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/batch/data_triggers/triggers/dpns). +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/batch/data_triggers/triggers/dpns). Note: as a system data +contract, the version active on a network is determined by that network's active protocol version. ```{eval-rst} .. diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md index 50b698db1..b34be1941 100644 --- a/docs/explanations/drive-platform-chain.md +++ b/docs/explanations/drive-platform-chain.md @@ -6,7 +6,7 @@ ## Overview -The platform chain is the [Drive](../explanations/drive.md) component responsible for replicating the platform state across all evonodes participating in the network. Evonodes (the high-performance masternode tier) operate this Proof of Service (PoSe) chain to provide layer 2 consensus and support Dash Platform-specific requirements without impacting layer 1 functionality. Although the platform chain can read from the Dash layer 1 core blockchain, the core blockchain is not dependent on it or aware of it. +The platform chain is the [Drive](../explanations/drive.md) component responsible for replicating the platform state across all evonodes participating in the network. Evonodes (the high-performance masternode tier) operate this chain to provide layer 2 consensus and support Dash Platform-specific requirements without impacting layer 1 functionality. Although the platform chain can read from the Dash layer 1 core blockchain, the core blockchain is not dependent on it or aware of it. ## Details @@ -18,7 +18,7 @@ Early designs of Drive were based on using on the layer 1 core blockchain and [I In order to support Dash Platform's performance requirements, the platform chain has the following design characteristics: -- Relies on masternode Proof of Service, not miner Proof of Work (PoW) +- Secured by evonode quorums anchored to the core chain rather than by mining (Proof of Work) - Hosted exclusively on evonodes (the high-performance masternode tier) - Uses a [practical Byzantine Fault Tolerance (pBFT)](../reference/glossary.md#practical-byzantine-fault-tolerance-pbft) consensus algorithm - Has a deterministic fee structure diff --git a/docs/explanations/drive-platform-state.md b/docs/explanations/drive-platform-state.md index 10706e5dd..f43c9d62e 100644 --- a/docs/explanations/drive-platform-state.md +++ b/docs/explanations/drive-platform-state.md @@ -27,3 +27,5 @@ Under the [Tenderdash](../explanations/platform-consensus.md) same-block executi ## 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. + +For additional detail on the two-layer verification model, see the [Proofs](../explanations/proofs.md) explanation. diff --git a/docs/explanations/drive.md b/docs/explanations/drive.md index 27a0168ee..5edc1acd3 100644 --- a/docs/explanations/drive.md +++ b/docs/explanations/drive.md @@ -17,7 +17,7 @@ There are a number of components working together to facilitate Drive's overall - [Platform chain](../explanations/drive-platform-chain.md) (orders state transitions; creates and propagates blocks of state transitions) - 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) +- Storage (persists the current state - identities, data contracts, documents, etc.) - GroveDB (authenticated hierarchical storage backend enabling cryptographic proofs returned via [DAPI](../explanations/dapi.md)) ### Data Update Process @@ -25,10 +25,9 @@ There are a number of components working together to facilitate Drive's overall 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 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 +2. DAPI relays state transitions to the platform chain's consensus engine (Tenderdash), which asks the platform state machine to validate them and speculatively execute them when building or verifying a block proposal +3. The block is propagated and voted on by validators +4. Once the block is committed, each node finalizes it — persisting the speculative state changes to Drive, or executing the block if it was received via sync ```{eval-rst} .. figure:: ../../img/drive.svg diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md index 19373223a..19b066325 100644 --- a/docs/explanations/fees.md +++ b/docs/explanations/fees.md @@ -42,7 +42,7 @@ Refer to the [Identity explanation](../explanations/identity.md) section for inf ## Fee Multiplier -The *Fee Multiplier* provides a mechanism to balance the cost of fees against network hosting requirements as the Dash price fluctuates. It is recorded per epoch and used when distributing collected fees from the credit pools, along with epoch accounting. +The *Fee Multiplier* provides a mechanism to balance the cost of fees against network hosting requirements as the Dash price fluctuates. It is recorded per epoch and reported alongside epoch accounting information. At the active fee version it is a reserved parameter: it is not applied when distributing collected fees from the credit pools. The multiplier does not scale the fee a user is charged. The active fee version fixes it at 1.0x, and the final fee charged for a state transition is calculated using the complete formula below, @@ -58,6 +58,8 @@ An in-depth look at the Fee Multiplier can be found at **link** In an attempt to minimize Dash Platform's storage requirements, users are incentivized to remove data that they no longer want to be stored in the Dash Platform state for a refund. Data storage fees are distributed to masternodes over the data's lifetime which is 50 years for permanent storage. Therefore, at any time before the data's fees are entirely distributed, there will be fees remaining which can be refunded to the user if they decide to delete the data. +Distribution is front-loaded rather than spread evenly across those 50 years, so the refundable remainder falls fastest in the early years. Removals below a small minimum byte threshold are not refunded at all. See the [protocol constants reference](../protocol-ref/protocol-constants.md) for the distribution schedule and the refund threshold. + ## User Fee Increase Platform supports a user fee increase that can be used to incentivize inclusion of a state @@ -72,6 +74,8 @@ The high level formula for a state transition's fee is: fee = storageFee + processingFee + (processingFee * userFeeIncrease / 100) - storageRefund ``` +The storage refund is netted against the total rather than clamped at zero. A state transition that frees more storage than it consumes produces a net credit to the identity instead of a charge. + diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md index 8f0d173fd..697e3a991 100644 --- a/docs/explanations/identity.md +++ b/docs/explanations/identity.md @@ -73,4 +73,4 @@ Note: the payout key is associated with the masternode owner identity, so both t Credits provide the mechanism for paying fees that cover the cost of platform usage. Once a user locks Dash on the core blockchain and proves ownership of the locked value in an identity create or topup state transition, their credit balance increases by that amount. Credits can also reach an identity from a [Platform address](../protocol-ref/address-system.md) or the [shielded pool](./shielded-pool.md) without a layer 1 lock. As they perform platform actions, these credits are deducted to pay the associated fees. -Credits can be converted back to Dash using the identity credit withdrawal state transition, subject to a daily network-wide limit. That limit is a proportion of the total credits held on Platform rather than a fixed amount, so it grows and shrinks with the size of the network. +Credits can be converted back to Dash using the identity credit withdrawal state transition, subject to a daily network-wide limit. That limit is a fixed amount defined by the protocol - currently 2000 Dash per day across the whole network. Because it is a versioned protocol parameter, the value can be changed by a protocol upgrade. diff --git a/docs/explanations/nft.md b/docs/explanations/nft.md index be8e1166b..b2748b545 100644 --- a/docs/explanations/nft.md +++ b/docs/explanations/nft.md @@ -31,6 +31,8 @@ NFTs can be directly transferred or traded without the need for a marketplace, p * Transferring allows the owner to assign a new owner without making the NFT available for purchase. * Trading involves a two-step process where the seller sets the NFT's price, and the first buyer that matches this price receives the NFT automatically. Once the transaction is complete, the price is reset to prevent further immediate purchases, ensuring a non-interactive and seamless trading experience. +A document type can also be configured so that each transfer, purchase, and price update is recorded on chain in Platform's document history system contract, giving an NFT a queryable provenance and sale history. Recording is off by default and, like the other document type options, is fixed when the document type is defined in the data contract. See [Document History Flags](../protocol-ref/data-contract-document.md#document-history-flags) in the protocol reference. + ```{eval-rst} .. _explanations-nft-create-restrict: ``` @@ -77,7 +79,7 @@ Once the data contract design is completed, the contract can be registered on th ### Minting NFTs -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. +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. See the [submit documents tutorial](../tutorials/contracts-and-documents/submit-documents.md) for example code. ```{eval-rst} .. _explanations-nft-trade: @@ -90,3 +92,5 @@ The trading process for Dash Platform NFTs is designed to be user-friendly and e Once an NFT is created, the owner can set a sale price to indicate the NFT is available for purchase. Interested buyers can then initiate a purchase by matching this set price. Upon completion of the transaction, the ownership of the NFT is automatically transferred to the buyer, and the sale price is reset to indicate the NFT is no longer available for purchase. Since the functionality needed to set a price, buy, and transfer ownership of NFTs is part of the protocol, the system handles all necessary trading operations directly. This provides an efficient trading experience that is integrated with the indexing and proof capabilities of Dash Platform. + +For example code, see the [set a document price](../tutorials/contracts-and-documents/set-a-document-price.md), [purchase documents](../tutorials/contracts-and-documents/purchase-documents.md), and [transfer documents](../tutorials/contracts-and-documents/transfer-documents.md) tutorials. diff --git a/docs/explanations/platform-consensus.md b/docs/explanations/platform-consensus.md index 8fe363a8e..d37b951fb 100644 --- a/docs/explanations/platform-consensus.md +++ b/docs/explanations/platform-consensus.md @@ -58,6 +58,7 @@ As with Tendermint, Tenderdash provides Byzantine Fault Tolerant (BFT) State Mac - The members of a quorum operate somewhat like validators but do so more efficiently due to the pre-existing BLS threshold signature. - BLS threshold signing results in more compact block headers since only a single BLS threshold signature is required instead of individual signatures from each validator. Notably, this means that any client can easily verify the block signatures using the deterministic masternode list. - The validators' signature is produced by an LLMQ, which is secured by the core blockchain’s Proof-of-Work (PoW). +- Validators can attach signatures over additional data to their votes in the same consensus round. Dash Platform uses this to have the quorum collectively sign withdrawal transactions, so funds leaving Platform carry a signature the core chain can verify. This allows Dash Platform to leverage the best of both worlds - the speed and finality of Tendermint and the security of PoW. diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md index eaa2662f8..f8c4fa80e 100644 --- a/docs/explanations/platform-protocol-data-contract.md +++ b/docs/explanations/platform-protocol-data-contract.md @@ -61,14 +61,14 @@ Permitted changes include: * Adding new document types * Adding new optional properties to existing document types -* Adding non-unique indices for newly added properties +* Adding non-unique indices on newly added document types * Adding new tokens to the contract * Adding new groups to the contract * Updating contract keywords and description -Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, or altering existing unique indices. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update. +Restricted changes include modifications that would break existing stored documents - for example, removing or renaming existing properties, changing their types, or altering the index definitions of an existing document type. Whether a document type records the history of its transfers, sales, and price changes is also fixed when the document type is created and cannot be turned on or off by a later contract update. -A contract update cannot remove or modify an existing token or group. Changing an existing token's configuration is done with a [token configuration update transition](../explanations/tokens.md#configuration-updates), governed by that token's own change control rules, and existing groups are permanently fixed once the contract is registered. +A contract update cannot remove or modify an existing token or group. Changing an existing token's configuration is done with a [token configuration update transition](../explanations/tokens.md#configuration-updates), governed by that token's own change control rules, and existing groups are immutable once the contract is registered. Optional contract revision history storage allows contracts to retain a record of their revisions that can be retrieved and verified. Identity key access rules also allow an encryption or decryption key to be bound to a specific contract or document type for more granular key management. diff --git a/docs/explanations/platform-protocol-data-trigger.md b/docs/explanations/platform-protocol-data-trigger.md index fc298bb8f..f40ef231d 100644 --- a/docs/explanations/platform-protocol-data-trigger.md +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -16,7 +16,7 @@ Given a number of technical considerations (security, masternode processing capa ## Details -Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action` so separate triggers can be created for the `CREATE`, `REPLACE`, or `DELETE` actions. +Since all application data is submitted in the form of documents, data triggers are defined in the context of documents. To provide even more granularity, they also incorporate the document `action`, so a separate trigger can be created for any [document transition action](../explanations/platform-protocol-document.md#document-submission): `create`, `replace`, `delete`, `transfer`, `purchase`, and `updatePrice`. Which trigger runs for a given contract, document type, and action is defined in the data trigger [binding list](https://github.com/dashpay/platform/blob/master/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/data_triggers/bindings/list/v1/mod.rs). The trigger implementations linked in the tables below (for example the shared `reject` trigger) are generic and do not name the contracts that use them - the binding list is what associates each action with its trigger. @@ -31,6 +31,8 @@ As an example, DPP contains several [data triggers for DPNS](https://github.com/ :::{note} The `REPLACE` and `DELETE` rows for DPNS both link to the same shared `reject` trigger, which DPNS reuses to disallow those actions on `domain` documents. The DPNS `preorder` document type has no data triggers at all - its immutability comes from the contract schema rather than from trigger logic. + +The absence of a trigger matters too: DPNS `domain` documents deliberately have no trigger bound to the `transfer`, `purchase`, or `updatePrice` actions, so those actions fall through to generic document validation. That is what makes [username transfers and sales](../explanations/dpns.md#name-transfers-and-sales) possible, while `REPLACE` and `DELETE` remain rejected so name records stay immutable and permanent. ::: In addition to DPNS, DPP ships data triggers for a small set of other system contracts: diff --git a/docs/explanations/platform-protocol-document.md b/docs/explanations/platform-protocol-document.md index 1b4d0b4bf..373b9b8af 100644 --- a/docs/explanations/platform-protocol-document.md +++ b/docs/explanations/platform-protocol-document.md @@ -32,6 +32,7 @@ Dash Platform Protocol (DPP) defines a set of base fields that must be present i | $createdAtCoreBlockHeight | Core block height when the document was created | | $updatedAtCoreBlockHeight | Core block height when the document was last updated | | $transferredAtCoreBlockHeight | Core block height when the document was last transferred | +| $creatorId | [Identity](../explanations/identity.md) that originally created the document (32 bytes). Present on document types that are transferable or have a trade mode set, and preserved when ownership changes | :::{attention} The timestamp and block height fields will only be present in documents that add them to the list of [required properties](../reference/data-contracts.md#required-properties). @@ -98,14 +99,23 @@ Once a document has been created, it must be encapsulated in a Batch state trans State transitions are versioned through their serialized enum representation rather than a top-level `protocolVersion` field. +### Document Transition Base + +Every document transition in a batch shares a common base, regardless of the action it performs. The base identifies which document the transition targets - the document ID, its type, and the data contract that defines it - and adds two further elements: + +- A per-identity, per-contract nonce that orders an identity's transitions against a given contract and prevents a transition from being replayed. +- Optional token payment information, used when the contract charges one of its tokens for the action rather than charging the submitter in credits. See the [Tokens](../explanations/tokens.md#token-based-fees) explanation for how token-based document fees are configured. + +The sections below describe the fields each action adds on top of this shared base. + ### Document Create -The document create transition is used to create a new document on Dash Platform. The document create transition extends the [base schema](#base-fields) to include the following additional fields: +The document create transition is used to create a new document on Dash Platform. The document create transition extends the [transition base](#document-transition-base) to include the following additional fields: | Field | Type | Description| | - | - | - | | $entropy | array (32 bytes) | Entropy used in creating the document ID | -| prefundedVotingBalance | object | (Optional) Credits set aside to fund masternode voting when the document contests a unique index | +| $prefundedVotingBalance | object | (Optional) Credits set aside to fund masternode voting when the document contests a unique index | The transition does not carry timestamp or block height fields. Platform assigns those from the block in which the transition is processed, and they appear on the resulting document only when the data contract sets them as required for the document type. @@ -113,7 +123,7 @@ Creating a document on a contested unique index requires setting aside a prefund ### Document Replace -The document replace transition is used to update the data in an existing Dash Platform document. The document replace transition extends the [base schema](#base-fields) to include the following additional fields: +The document replace transition is used to update the data in an existing Dash Platform document. The document replace transition extends the [transition base](#document-transition-base) to include the following additional fields: | Field | Type | Description| | - | - | - | @@ -123,11 +133,11 @@ If the data contract sets the updated at timestamp as required for the document ### Document Delete -The document delete transition is used to delete an existing Dash Platform document. It only requires the fields found in the base document transition. +The document delete transition is used to delete an existing Dash Platform document. It only requires the fields found in the [transition base](#document-transition-base). ### Document Transfer -The document transfer transition is used to transfer ownership of an existing document to another identity. It extends the [base schema](#base-fields) with the recipient identifier: +The document transfer transition is used to transfer ownership of an existing document to another identity. It extends the [transition base](#document-transition-base) with the recipient identifier: | Field | Type | Description | | - | - | - | @@ -138,7 +148,7 @@ Document transfers are only allowed for document types that are marked transfera ### 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: +The document purchase transition is used to buy a document that the current owner has listed for sale. It extends the [transition base](#document-transition-base) with the agreed price: | Field | Type | Description | | - | - | - | @@ -149,7 +159,7 @@ Document purchases are only allowed for document types whose trade mode permits ### 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: +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 [transition base](#document-transition-base) with the new price: | Field | Type | Description | | - | - | - | diff --git a/docs/explanations/platform-protocol.md b/docs/explanations/platform-protocol.md index 0e36b9fc6..72b89d15f 100644 --- a/docs/explanations/platform-protocol.md +++ b/docs/explanations/platform-protocol.md @@ -53,6 +53,7 @@ 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. +* **Description** - an optional human-readable summary of the contract, used alongside keywords when contracts are surfaced to users. For additional detail, see the [Data Contract](../explanations/platform-protocol-data-contract.md) explanation. diff --git a/docs/explanations/shielded-pool.md b/docs/explanations/shielded-pool.md index 68b917287..ac02a0381 100644 --- a/docs/explanations/shielded-pool.md +++ b/docs/explanations/shielded-pool.md @@ -6,7 +6,7 @@ ## Overview -The shielded pool is an optional privacy layer on Dash Platform that lets users hold and move credits without revealing balances, sender, or recipient on-chain. Funds move *into* the pool through a shield transition, move *within* the pool privately, and exit through an unshield, a shielded withdrawal, or by funding a newly created identity. While funds remain inside the pool, only their owner can see them. +The shielded pool is an optional privacy layer on Dash Platform that lets users hold and move credits without revealing balances, sender, or recipient on-chain. Funds move *into* the pool through a shield transition, move *within* the pool privately, and exit through an unshield, a shielded withdrawal, or by funding a newly created identity. While funds remain inside the pool, only their owner can see them. The shielded pool became available at protocol version 12. The pool uses the [Orchard](https://zips.z.cash/protocol/protocol.pdf) shielded protocol — the same zero-knowledge design (Halo 2 proofs, with no trusted setup) used by Zcash for its current shielded pool. Transactions inside the pool prove their own validity without disclosing the amounts or parties involved. @@ -76,6 +76,8 @@ Creates a new identity funded directly from the pool by spending one or more not The funding amount cannot be chosen freely: it must be one of a small fixed set of allowed denominations, and any other amount is rejected. Restricting the exit to standard sizes means every identity created at a given denomination looks identical on-chain, so the new identity cannot be linked back to a particular shielded balance by its amount. The permitted denominations are listed in the [Shielded Pool protocol reference](../protocol-ref/shielded-pool.md). +The notes being spent do not have to add up to the chosen denomination exactly - any excess is returned to the pool as a new note, so change stays shielded. If identity creation then fails a stateful check, the denomination still leaves the pool: it lands, less a penalty, at a fallback Platform address named in the transition. + ## What the pool does not provide - **Anonymity sets**: The privacy guarantee depends on how many other notes exist in the pool. A pool with a single user offers limited cover; privacy improves as more users participate. diff --git a/docs/explanations/tokens.md b/docs/explanations/tokens.md index 4fe9eeca0..f48f61284 100644 --- a/docs/explanations/tokens.md +++ b/docs/explanations/tokens.md @@ -89,7 +89,7 @@ Update token configuration parameters, including: - Marketplace trade mode - Which group acts as the main control group -A configuration update can point the token at a different [group](#groups), but it cannot change any group's members or their powers. Groups are fixed when the data contract is registered. +A configuration update can point the token at a different [group](#groups), but it cannot change any group's members or their powers. Existing groups are immutable once the data contract is registered, although a data contract update can add groups at new positions. #### Set Purchase Price @@ -226,7 +226,7 @@ distribution options are summarized below: | ------ | ----------- | -------- | ------ | | Manual Minting | Authorized users/groups can create new tokens until `maxSupply` is reached | On-demand minting | - Requires proper configuration to enable
- Minting actions may be logged or controlled via permissions | | Programmed Distribution | A fixed number of tokens are allocated to designated identities at explicit timestamps, and the recipients must [claim](#claim) them to receive the tokens | *On Jan 1, 2047, allocate `X` tokens to the provided identity* | - Schedules token release at known times
- Each entry is a one-time allocation at a fixed timestamp; there is no recurrence option | -| [Perpetual Distribution](../protocol-ref/data-contract-token.md#perpetual-distribution-options) | Scheduled release of tokens based on blocks or time intervals | *Emit 100 tokens every 20 blocks*, or *Halve the emission every year* | - Offers ongoing, dynamic token emission patterns.
- Supports variable rates (e.g., linear, steps).
- Emissions accrue on schedule and are always collected by the recipient via a [claim](#claim). | +| [Perpetual Distribution](../protocol-ref/data-contract-token.md#perpetual-distribution-options) | Scheduled release of tokens based on block, time, or epoch intervals | *Emit 100 tokens every 20 blocks*, or *Halve the emission every year* | - Offers ongoing, dynamic token emission patterns.
- Supports variable rates (e.g., linear, steps).
- Emissions accrue on schedule and are always collected by the recipient via a [claim](#claim). | Dash Platform also supports three options to control the destination for newly minted tokens: @@ -278,7 +278,7 @@ This allows for: - Shared-currency ecosystems, by pricing document actions in a token that belongs to another contract. Such external-token payments transfer to the contract owner; burning is only permitted for a contract's own token. - A gasless user experience, by having the contract owner rather than the document owner pay the Platform credit cost of the action -Alongside the amount and its effect, each cost specifies who pays the Platform gas fees and may set minimum and maximum bounds. Clients should generally set a maximum: without one, a contract whose rules allow the price to change could charge more than the user expected between signing and execution. +Alongside the amount and its effect, each cost in the contract specifies who pays the Platform gas fees and may set minimum and maximum bounds. Separately, the client submitting the action can attach its own minimum and maximum bounds on what it is willing to pay. Clients should generally set a maximum: without one, a contract whose rules allow the price to change could charge more than the user expected between signing and execution. ## Token Creation @@ -286,11 +286,13 @@ Creating a token on Dash Platform consists of creating a data contract, register 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). +A token can also be added to a contract that is already registered, by updating the contract to declare a token at a previously unused position. Token positions that already exist cannot be altered, and their configuration cannot be modified by a contract update. All post-registration changes to an existing token must use the [token config update](#configuration-updates) action. + ### 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. -Once the data contract design is completed, the contract can be registered on the network in preparation for token minting and use. See the [contract registration tutorial](../tutorials/contracts-and-documents/register-a-data-contract.md) for examples of how to register a contract. +Once the data contract design is completed, the contract can be registered on the network in preparation for token minting and use. See the [contract registration tutorial](../tutorials/contracts-and-documents/register-a-data-contract.md) for examples of how to register a contract. For step-by-step examples covering token contract registration, minting, burning, transferring, and querying token information, see the [token tutorials](../tutorials/tokens.md). ## Token Trading