Skip to content

docs: more v2 #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
May 5, 2025
Merged

docs: more v2 #121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
552f509
docs: correct data contract error range
thephez Apr 22, 2025
5abae8e
docs(api): update token event info
thephez Apr 22, 2025
496e5f3
docs(ref): fix contract links
thephez Apr 22, 2025
35e92ce
docs: add token fee info to explanation
thephez Apr 23, 2025
f1327c6
docs: update token config info and action rules
thephez Apr 23, 2025
fd73155
docs: add token direct purchase info
thephez Apr 23, 2025
a00c8b0
docs(ref): data contract updates
thephez Apr 23, 2025
5945994
docs: link updates
thephez Apr 23, 2025
673c776
docs: add contract fees info
thephez May 5, 2025
b3608c7
docs: add js-sdk connection example for local build
thephez May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 72 additions & 14 deletions docs/explanations/tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Dash Platform’s token functionality provides a straightforward, account-based
- **Access Control [Groups](#groups)**: Multi-party groups with user-defined thresholds support complex authorization schemes for token management
- **Built-in [Distribution](#distribution-rules)**: Manual minting or scheduled release over time
- **Seamless Integration**: Tokens live alongside documents in a single data contract, enabling additional use cases (e.g., ticketing, digital assets, stablecoins)
- **Token-Based Document [Fees](#token-based-fees)**: Charge tokens for an application's document actions (e.g., create, transfer), with options to burn tokens or reward the contract owner

The following sections describe the features and configuration options available for token creators
using Dash Platform.
Expand Down Expand Up @@ -103,11 +104,12 @@ When creating a token, you define its configuration using the following paramete
| Configuration Parameter | Mutable | Default |
|:------------------------|:------------------|:--------|
| [Conventions](#display-conventions) | Yes | N/A. Depends on implementation |
| [Decimal precision](#display-conventions)| Yes | [8](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs#L38) |
| [Base supply](#token-supply) | **No** | [100000](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L159) |
| [Decimal precision](#display-conventions)| Yes | [8](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L376) |
| [Base supply](#token-supply) | **No** | [100000](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs#L378) |
| [Maximum supply](#token-supply) | Yes | None |
| [Keep history](#history) | Yes | True |
| [Start paused](#initial-state) | Yes | False |
| [Allow transfer to frozen balance](#allow-transfer-to-frozen-balance) | Yes | True |
| [Main control group](#main-control-group)| Yes | None |
| Main control group can be modified | Yes | NoOne |

Expand Down Expand Up @@ -137,6 +139,10 @@ When creating a token, you define its configuration using the following paramete
- Whether the authority to change these parameters can be transferred or locked to "no one"
- Example: "Only group #1 can update the max supply.” See the [Rules section](#rules) for details.

#### Allow Transfer to Frozen Balance

- Allow transferring and minting of tokens to frozen identity token balances

#### Main Control Group

- A group that can be referenced in other fields to control multiple aspects of the token with the same group.
Expand Down Expand Up @@ -179,19 +185,46 @@ Rules can authorize no one, specific identities, or multiparty groups. The compl

##### Action Rules

Token action rules can be configured to allow updating who has access to many [token actions](#actions). The following table summarizes the available action rules:
Token action rules can be configured to control access to many [token actions](#actions). The
following table summarizes the configurable rules and their default authorized parties:

###### General Controls

| Configuration Rule | Can be Changed? | Default Authorized Party |
|:--------------------------------------|:----------------|:-------------------------|
| Conventions change rules | Yes | NoOne |
| Max supply change rules | Yes | NoOne |
| Main control group can be modified | Yes | NoOne |

###### Minting and Burning

| Configuration Rule | Can be Changed? | Default Authorized Party |
|:--------------------------------------|:----------------|:-------------------------|
| Manual minting rules | Yes | Contract Owner |
| Manual burning rules | Yes | Contract Owner |
| Minting: choosing destination rules | Yes | NoOne |

###### Freezing Controls

| Configuration Rule | Can be Changed? | Default Authorized Party |
|:--------------------------------------|:----------------|:-------------------------|
| Freeze rules | Yes | NoOne |
| Unfreeze rules | Yes | NoOne |
| Destroy frozen funds rules | Yes | NoOne |

###### Distribution

| Configuration Rule | Can be Changed? | Default Authorized Party |
|:--------------------------------------|:----------------|:-------------------------|
| Perpetual distribution rules | Yes | NoOne |
| New tokens destination identity rules | Yes | NoOne |
| Direct purchase pricing change rules | Yes | NoOne |

###### Emergency

| Configuration Rule | Can be Changed? | Default Authorized Party|
|:-------------------|:------------------|:--------|
| Conventions change rules | Yes | NoOne |
| Max supply change rules | Yes | NoOne |
| Manual minting rules | Yes | Contract Owner |
| Manual burning rules | Yes | Contract Owner |
| Freeze rules | Yes | NoOne |
| Unfreeze rules | Yes | NoOne |
| Destroy frozen funds rules | Yes | NoOne |
| Emergency_action rules | Yes | NoOne |
| Main control group can be modified | Yes | NoOne |
| Configuration Rule | Can be Changed? | Default Authorized Party |
|:--------------------------------------|:----------------|:-------------------------|
| Emergency action rules | Yes | NoOne |

##### Distribution Rules

Expand Down Expand Up @@ -430,6 +463,21 @@ For example, a group is defined with a required threshold of 10. The group membe

In this group, Member A and Member C have a combined power of 11 and can perform actions without approval from Member B. If Member B proposes an action, Member A and C must both approve to authorize the action.

### Token-Based Fees

Dash Platform allows developers to charge token fees for document-related actions (e.g., creating or transferring a document). This provides a way to monetize app usage or implement economic incentives using tokens. These fees are configured in the data contract and apply to all document types in the contract.

Examples:

- Require 1000 tokens to create a document
- Burn 200 tokens when a document is transferred

This allows for:

- Spam protection (pay-to-post)
- Revenue generation for app creators
- Deflationary models via token burning

## Token Creation

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.
Expand Down Expand Up @@ -510,4 +558,14 @@ Once the data contract design is completed, the contract can be registered on th

## Token Trading

### Direct Purchase

Tokens can be configured to enable direct purchase by users. This allows the contract owner (or other authorized party) to sell the token directly to users at a fixed price or according to a tiered pricing schedule.

The token’s [change control rules](#change-control-rules) include a `changeDirectPurchasePricingRules` setting to determine who is authorized to set or update the price. By default this is set to no one (`NoOne`) to disable direct sales. To allow direct sales, this rule should be set to authorize someone (e.g., the contract owner) to change pricing.

When enabled, the authorized party can set the token price using a state transition. Users can purchase the token through Platform’s built-in mechanism (see [Token Set Purchase Price Transition](../protocol-ref/token.md#token-set-purchase-price-transition) and [Token Purchase Transition](../protocol-ref/token.md#token-purchase-transition)). The direct purchase system supports defining a minimum purchase amount and volume discounts via pricing tiers. The token’s price can also be removed to stop sales.

### Marketplace

A planned token marketplace will support the trading of tokens.
120 changes: 116 additions & 4 deletions docs/protocol-ref/data-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,34 @@

Data contracts define the schema (structure) of data an application will store on Dash Platform. Contracts are described using [JSON Schema](https://json-schema.org/understanding-json-schema/) which allows the platform to validate the contract-related data submitted to it.

The following sections provide details that developers need to construct valid contracts. All data contracts must define one or more [documents](#data-contract-documents) or [tokens](#data-contract-tokens), whereas definitions are optional and may not be used for simple contracts.
The following sections provide details that developers need to construct valid contracts. All data contracts must define at least one [document](#data-contract-documents) or [token](#data-contract-tokens). A contract may define multiple documents and/or tokens.

### Fees

Dash Platform charges fees for registering data contracts based on complexity. These fees compensate evonodes for their role in storing and processing contract-related data.

The table below outlines the current fee structure for various data contract components. Fees are denominated in DASH and are charged at registration time based on the structure of the contract.

| Fee Component | Amount (DASH) | Description |
|--------------------------------------------------------|-------------------|---------|
| `base_contract_registration_fee` | 0.1 | Fixed fee for every data contract. Covers the baseline cost of anchoring a contract into platform state. |
| `document_type_registration_fee` | 0.02 | Charged per [document type](./data-contract-document.md#contract-documents). Reflects indexing and storage schema overhead. |
| `document_type_base_non_unique`<br>`_index_registration_fee` | 0.01 | Per non-unique [index](./data-contract-document.md#document-indices) in a document type. Supports query operations. |
| `document_type_base_unique_index`<br>`_registration_fee` | 0.01 | Per unique [index](./data-contract-document.md#document-indices). Enforces uniqueness and adds validation complexity. |
| `document_type_base_contested`<br>`_index_registration_fee` | 1.0 | Per [contested index](./data-contract-document.md#contested-indices). Used for identity/username resolution; requires voting and [conflict resolution](../explanations/dpns.md#conflict-resolution) by masternodes and evonodes. |
| `token_registration_fee` | 0.1 | Per token defined in the contract. Reflects additional overhead from managing balances, transfers, and supply. |
| `token_uses_perpetual`<br>`_distribution_fee` | 0.1 | Additional fee for tokens that use perpetual (e.g., block-based) distribution mechanisms. These create ongoing state changes triggered by network events. |
| `token_uses_pre_programmed`<br>`_distribution_fee` | 0.1 | Charged when tokens use scheduled distributions (e.g., airdrops). Adds periodic complexity. |
| `search_keyword_fee` | 0.1 per keyword | Charged per search keyword defined. Keywords enable reverse lookups and indexing, increasing on-chain storage and filtering load. |

These fees are additive. For example, a contract that defines two document types, each with one unique index, and one token using a perpetual distribution will incur the following total fee:

```text
0.1 (base) + 0.02×2 (documents) + 0.01×2 (unique indices) = 0.16 DASH
0.1 (token) + 0.1 (perpetual) = 0.2 DASH

Total fee: 0.16 + 0.2 = 0.36 DASH
```

### General Constraints

Expand Down Expand Up @@ -40,7 +67,7 @@ Include the following at the same level as the `properties` keyword to ensure pr

## Data Contract Object

The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L67-L105)):
The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L77-L121)):

| Property | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
Expand All @@ -54,6 +81,8 @@ The data contract object consists of the following fields as defined in the Rust
| $defs | object | Varies | (Optional) Definitions for `$ref` references used in the `documents` object (if present, must be a non-empty object with \<= 100 valid properties) |
| [groups](#data-contract-groups) | Group | Varies | (Optional) Groups that allow for specific multiparty actions on the contract. |
| [tokens](./data-contract-token.md) | object | Varies | (Optional \*) Token definitions (see [Contract Tokens](./data-contract-token.md) for details) |
| keywords | array of strings | Varies | (Optional) Keywords associated with the contract to improve searchability. Maximum of 20 words. |
| description | string | 3-100 characters | (Optional) Brief description of the contract. |

\* The data contract object must define documents or tokens. It may include both documents and tokens.

Expand Down Expand Up @@ -293,7 +322,9 @@ The full schema is [defined is rs-dpp](https://github.com/dashpay/platform/blob/
"properties": {
"position": true
},
"required": ["position"]
"required": [
"position"
]
}
}
}
Expand Down Expand Up @@ -353,6 +384,50 @@ The full schema is [defined is rs-dpp](https://github.com/dashpay/platform/blob/
}
}
]
},
"documentActionTokenCost": {
"type": "object",
"properties": {
"contractId": {
"type": "array",
"contentMediaType": "application/x.dash.dpp.identifier",
"byteArray": true,
"minItems": 32,
"maxItems": 32
},
"tokenPosition": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 281474976710655
},
"effect": {
"type": "integer",
"enum": [
0,
1
],
"description": "0 - TransferTokenToContractOwner (default), 1 - Burn"
},
"gasFeesPaidBy": {
"type": "integer",
"enum": [
0,
1,
2
],
"description": "0 - DocumentOwner (default), 1 - ContractOwner, 2 - PreferContractOwner"
}
},
"required": [
"tokenPosition",
"amount"
],
"additionalProperties": false
}
},
"properties": {
Expand Down Expand Up @@ -442,7 +517,9 @@ The full schema is [defined is rs-dpp](https://github.com/dashpay/platform/blob/
"maxLength": 256
}
},
"required": ["resolution"],
"required": [
"resolution"
],
"additionalProperties": false
}
},
Expand Down Expand Up @@ -519,6 +596,30 @@ The full schema is [defined is rs-dpp](https://github.com/dashpay/platform/blob/
],
"description": "Key requirements. 0 - Unique Non Replaceable, 1 - Multiple, 2 - Multiple with reference to latest key."
},
"tokenCost": {
"type": "object",
"properties": {
"create": {
"$ref": "#/$defs/documentActionTokenCost"
},
"replace": {
"$ref": "#/$defs/documentActionTokenCost"
},
"delete": {
"$ref": "#/$defs/documentActionTokenCost"
},
"transfer": {
"$ref": "#/$defs/documentActionTokenCost"
},
"update_price": {
"$ref": "#/$defs/documentActionTokenCost"
},
"purchase": {
"$ref": "#/$defs/documentActionTokenCost"
}
},
"additionalProperties": false
},
"properties": {
"type": "object",
"additionalProperties": {
Expand Down Expand Up @@ -578,6 +679,17 @@ The full schema is [defined is rs-dpp](https://github.com/dashpay/platform/blob/
"type": "string"
}
},
"keywords": {
"type": "array",
"description": "List of up to 20 descriptive keywords for the contract, used in the Keyword Search contract",
"items": {
"type": "string",
"minLength": 3,
"maxLength": 50
},
"maxItems": 20,
"uniqueItems": true
},
"additionalProperties": {
"type": "boolean",
"const": false
Expand Down
2 changes: 1 addition & 1 deletion docs/protocol-ref/errors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Code range: 10100-10199

### Data Contract

Code range: 10200-10399
Code range: 10200-10349

| Code | Error Description | Comment |
| :---: | ----------------------------------------------- | ------- |
Expand Down
4 changes: 2 additions & 2 deletions docs/protocol-ref/token.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Each token transition must comply with the [token base transition defined in rs-

#### Token id

The `$tokenId` is created by double sha256 hashing the token `$dataContractId` and `$tokenContractPosition` with a byte vector of the string "dash_token" as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L22-L27).
The `$tokenId` is created by double sha256 hashing the token `$dataContractId` and `$tokenContractPosition` with a byte vector of the string "dash_token" as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L26-L31).

```rust
// From the Rust reference implementation (rs-dpp)
Expand Down Expand Up @@ -57,7 +57,7 @@ The token transition actions [defined in rs-dpp](https://github.com/dashpay/plat

### Token Notes

Some token transitions include optional notes fields. The maximum note length for these fields is [2048 characters](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L14).
Some token transitions include optional notes fields. The maximum note length for these fields is [2048 characters](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L18).

### Token Burn Transition

Expand Down
Loading