diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 000000000..8b7b24239 --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,28 @@ +# Development Container + +The development container config ([.devcontainer.json](./devcontainer.json)) enables starting a +pre-configured [GitHub Codespaces](https://github.com/features/codespaces) environment ready to +build and preview the docs in this repository. + +## Building a preview + +The current version of the docs will be automatically built the when a new codespace is created. To +re-build the docs after making changes, simply run this command from the terminal: + +```shell +rm -rf _build/ && make html +``` + +Note: you may need go to the main menu, click `View`, then `Terminal` if the terminal isn't visible. + +## Viewing the preview + +To preview the docs, run the following command in the terminal: + +```shell +python -m http.server 8080 -d _build/html +``` + +This will start a simple Python web server on port 8080 in the codespace and open a preview of the +site in VSCode's built-in simple browser. To preview in your actual browser, click the `PORTS` tab, +right-click on `Doc Preview (8080)`, and select `Open in Browser`. diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..b6d1da49d --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,51 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu +{ + "name": "Ubuntu", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/base:jammy", + // Features to add to the dev container. More info: https://containers.dev/features. + "features": { + "ghcr.io/devcontainers/features/github-cli:1": {}, + "ghcr.io/devcontainers/features/python:1": {} + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "./.devcontainer/postCreateCommands.sh", + + // Configure tool-specific properties. + "customizations": { + "codespaces": { + "openFiles": [ + ".devcontainer/README.md", + "README.md" + ] + }, + "vscode": { + "extensions": [ + "lextudio.restructuredtext", + "trond-snekvik.simple-rst", + "DavidAnson.vscode-markdownlint", + "ZainChen.json", + "stkb.rewrap" + ] + } + }, + "portsAttributes": { + "8080": { + "label": "Doc Preview", + "onAutoForward": "openPreview" + } + } + + // // Configure command(s) to run after starting + // "postStartCommand": { + // "serve-doc-preview": "python -m http.server 8080 -d _build/html/" + // } + + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/.devcontainer/postCreateCommands.sh b/.devcontainer/postCreateCommands.sh new file mode 100755 index 000000000..bc62f4925 --- /dev/null +++ b/.devcontainer/postCreateCommands.sh @@ -0,0 +1,10 @@ +#/!bin/sh + +# Command to run during postCreateCommand +# Done in script because when done via object the commands are run in parallel +# (which isn't always desirable) +# https://containers.dev/implementors/spec/#parallel-exec +# https://containers.dev/implementors/json_reference/#formatting-string-vs-array-properties + +pip install -r requirements.txt +make html diff --git a/.github/workflows/preview-url.yml b/.github/workflows/preview-url.yml new file mode 100644 index 000000000..75a37ec66 --- /dev/null +++ b/.github/workflows/preview-url.yml @@ -0,0 +1,23 @@ +name: Add preview URL to PR description +on: + pull_request_target: + types: [opened] + paths: + - '**.md' + - '**.png' + - '**.rst' + - '**.svg' + +jobs: + build: + runs-on: ubuntu-22.04 + steps: + - name: edit-pull-request-description + uses: Jerome1337/comment-pull-request@v1.0.4 + + env: + GITHUB_TOKEN: ${{ github.token }} + with: + description-message: | + + Preview build: https://dash-docs-platform--${{github.event.pull_request.number}}.org.readthedocs.build/en/${{github.event.pull_request.number}}/ diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..2f2a1c2b7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +*.db +*.exe +_build +**/.DS_Store +.vscode diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..f04743b5a --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,10 @@ +{ + "default": true, + "MD004": { "style": "asterisk"}, + "MD013": false, + "MD033": false, + "MD036": false, + "MD040": true, + "MD041": false, + "MD049": true +} diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/_static/css/footer.css b/_static/css/footer.css new file mode 100644 index 000000000..70a4a920d --- /dev/null +++ b/_static/css/footer.css @@ -0,0 +1,11 @@ +/* Make each footer item in-line so they stack horizontally instead of vertically */ +.footer-item { + display: inline-block; +} + +/* Add a separating border line for all but the last item */ +.footer-item:not(:last-child) { + border-right: 1px solid var(--pst-color-text-base); + margin-right: .5em; + padding-right: .5em; +} diff --git a/_static/css/pydata-overrides.css b/_static/css/pydata-overrides.css new file mode 100644 index 000000000..f2d590d9a --- /dev/null +++ b/_static/css/pydata-overrides.css @@ -0,0 +1,151 @@ +/* Update theme variables based on https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/styling.html#css-theme-variables */ +@import url('https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,300;0,400;0,600;0,900;1,900&family=Open+Sans:ital,wght@0,400;0,500;1,400&display=swap'); + +:root { + --dash-blue: #008de4; + --dash-deep-blue: #012060; + --dash-midnight-blue: #0b0f3b; +} + +html[data-theme="light"] { + --pst-color-primary:var(--dash-blue); + --pst-color-link:var(--pst-color-primary); + --pst-color-link-hover:var(--dash-deep-blue); +} + +html[data-theme="dark"] { + --pst-color-primary:var(--dash-blue); + --pst-color-link:var(--pst-color-primary); +} + +html { + /* Headers */ + --pst-font-size-h1: 28px; + --pst-font-size-h2: 24px; + --pst-font-size-h3: 20px; + + /* Sidebar styles */ + --pst-sidebar-font-size: 0.95em; + --pst-sidebar-header-font-size: 1.2em; +} + +html[data-theme=dark] .bd-content img:not(.only-dark):not(.dark-light) { + background: none; + border-radius: none; +} + +h1,h2,h3,h4,h5,h6{ + font-family: 'Montserrat', sans-serif; + font-weight: 600; +} + +p, a, li, ol { + font-family: 'Open Sans', sans-serif; +} + +p { + font-size: 0.95em; + line-height: 1.5; +} + +.sidebar-end-items__item { + position: relative; +} + +select { + width: 100%; + padding: 10px; + appearance: none; + background: transparent; + border-radius: 0.25rem; +} + +html[data-theme=dark] select { + color: #fff; +} + +html[data-theme="light"] select{ + color: #000; +} + +html[data-theme="light"] { + --table-bg-color-odd: #eeeeee; + --table-bg-color-even: #ffffff; +} + +tbody tr:nth-child(odd) { background-color: var(--table-bg-color-odd); } +tbody tr:nth-child(even) { background-color: var(--table-bg-color-even); } + +.table thead th.head { + vertical-align: middle; +} + +/* These are hacks to hide the pydata-theme search popup behind the readthedocs +sphinx search extension interface. +*/ +.search-button__wrapper.show .search-button__search-container, +.search-button__wrapper.show .search-button__overlay { + z-index: 1; +} + +.search-button__wrapper.show .search-button__overlay { + display: none; +} + +/* Make sure it doesn't stick out on the sides of the RtD search screen */ +.search-button__wrapper.show .search-button__search-container { + width: 15%; +} + +/* Handle actual styling of the RtD search extension's screen */ +.search__outer { + background-color: var(--pst-color-on-background); + border: var(--pst-color-border); + border-radius: 0.25em; +} + +.search__outer__input { + background-color: var(--pst-color-on-background); + color: var(--pst-color-text-base); + font-size: var(--pst-font-size-icon); +} + +.rtd__search__credits { + background-color: var(--pst-color-background); + color: var(--pst-color-text-muted); +} + +.rtd__search__credits a { + color: var(--pst-color-link); +} + +.search__result__content, .search__result__subheading, .search__error__box { + color: var(--pst-color-text-base); +} + +.search__result__subheading span { + border-bottom-color: var(--pst-color-text-base); +} + +[data-theme="dark"] .search__outer .search__result__content span, +[data-theme="dark"] .search__outer .search__result__title span { + background-color: var(--pst-color-muted-highlight); /* Dark mode background color */ +} + +.search__outer .search__result__content span, +.search__outer .search__result__title span { + border-bottom-color: var(--pst-color-text-base); +} + +/* Make sure "X" remains visible */ +.search__cross__img { + fill: var(--pst-color-text-base); +} + +/* Prevent hover from actually changing the color by setting it to what it + already is */ +.outer_div_page_results:hover, .search__result__box .active { + background-color: var(--pst-color-on-background); +} + +/* End of styling of the RtD search extension's screen */ diff --git a/_static/img/favicon-144x144.png b/_static/img/favicon-144x144.png new file mode 100644 index 000000000..5a92e49f8 Binary files /dev/null and b/_static/img/favicon-144x144.png differ diff --git a/_static/img/favicon-16x16.png b/_static/img/favicon-16x16.png new file mode 100644 index 000000000..28332377a Binary files /dev/null and b/_static/img/favicon-16x16.png differ diff --git a/_static/img/favicon-32x32.png b/_static/img/favicon-32x32.png new file mode 100644 index 000000000..3f4d052c3 Binary files /dev/null and b/_static/img/favicon-32x32.png differ diff --git a/_static/img/favicon-96x96.png b/_static/img/favicon-96x96.png new file mode 100644 index 000000000..4681cfb34 Binary files /dev/null and b/_static/img/favicon-96x96.png differ diff --git a/_static/js/pydata-search-close.js b/_static/js/pydata-search-close.js new file mode 100644 index 000000000..b7147eaff --- /dev/null +++ b/_static/js/pydata-search-close.js @@ -0,0 +1,82 @@ +// Script to allow use of readthedocs-sphinx-search extension with the pydata +// theme +// +// Based in part on: +// https://github.com/pydata/pydata-sphinx-theme/blob/v0.13.3/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js#L167-L272 + +/******************************************************************************* + * Search + */ +/** Find any search forms on the page and return their input element */ +var findSearchInput = () => { + let forms = document.querySelectorAll("form.bd-search"); + if (!forms.length) { + // no search form found + return; + } else { + var form; + if (forms.length == 1) { + // there is exactly one search form (persistent or hidden) + form = forms[0]; + } else { + // must be at least one persistent form, use the first persistent one + form = document.querySelector( + "div:not(.search-button__search-container) > form.bd-search" + ); + } + return form.querySelector("input"); + } +}; + +/** Function to hide the search field */ +var hideSearchField = () => { + + let input = findSearchInput(); + let searchPopupWrapper = document.querySelector(".search-button__wrapper"); + let hiddenInput = searchPopupWrapper.querySelector("input"); + + if (input === hiddenInput) { + searchPopupWrapper.classList.remove("show"); + } + + if (document.activeElement === input) { + input.blur(); + } +}; + +/** Add an event listener for hideSearchField() for Escape*/ +var addEventListenerForSearchKeyboard = () => { + window.addEventListener( + "keydown", + (event) => { + // Allow Escape key to hide the search field + if (event.code == "Escape") { + hideSearchField(); + } + }, + true + ); +}; + +/** Activate callbacks for search button popup */ +var setupSearchButtons = () => { + addEventListenerForSearchKeyboard(); +}; + +// Custom code to manage closing the RtD search dialog properly +$(document).ready(function(){ + $(".search__cross").click(function(){ + hideSearchField(); + }); + $(".search__outer__wrapper.search__backdrop").click(function(){ + hideSearchField(); + }); + $(".search-button__overlay").click(function(){ + // Shouldn't be necessary since it's currently hidden by CSS, but just in + // case + console.log("Close by search-button__overlay"); + hideSearchField(); + }); +}); + +$(setupSearchButtons); diff --git a/_templates/sidebar-main.html b/_templates/sidebar-main.html new file mode 100644 index 000000000..5bda0fbc6 --- /dev/null +++ b/_templates/sidebar-main.html @@ -0,0 +1,563 @@ +
+
+ +
+
\ No newline at end of file diff --git a/conf.py b/conf.py new file mode 100644 index 000000000..88368e05f --- /dev/null +++ b/conf.py @@ -0,0 +1,137 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Dash Platform' +copyright = '2023, Dash Core Group, Inc' +author = 'thephez' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'latest' +# The full version, including alpha/beta/rc tags. +release = u'latest' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'hoverxref.extension', + 'myst_parser', + 'sphinx.ext.autodoc', + 'sphinx_copybutton', + 'sphinx_design', + 'sphinx_search.extension', + 'sphinx.ext.intersphinx', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', '.devcontainer', 'scripts', 'img/dev/gifs/README.md', 'docs/other'] + +# The master toctree document. +master_doc = 'index' + +hoverxref_role_types = { + 'hoverxref': 'tooltip', +} + +# -- Myst parser configuration ----------------------------------------------- +# Auto-generate header anchors for md headings +myst_heading_anchors = 5 + +# Enable colon_fence for better markdown compatibility +# https://myst.tools/docs/mystjs/syntax-overview#directives +myst_enable_extensions = ["colon_fence"] + +# -- intersphinx configuration ----------------------------------------------- +intersphinx_mapping = { + "user": ("https://docs.dash.org/en/stable/", None), + "core": ("https://docs.dash.org/projects/core/en/stable/", None), +} + +# We recommend adding the following config value. +# Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings. +# This behavior has unintended side-effects, namely that documentations local references can +# suddenly resolve to an external location. +# See also: +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes +intersphinx_disabled_reftypes = ["*"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ['_static'] +html_logo = 'img/dash_logo.png' +html_css_files = [ + 'css/footer.css', + 'css/pydata-overrides.css', +] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +html_sidebars = { + "index": ["sidebar-main.html"], + "**": ["sidebar-nav-bs"] +} + +html_theme_options = { +# "announcement": "Test build of Dash Core documentation migrated from Readme.io!", + "external_links": [ + {"name": "Core docs", "url": "https://docs.dash.org/projects/core/en/stable/docs/index.html"}, + {"name": "User docs", "url": "https://docs.dash.org/"}, + {"name": "Dash.org", "url": "https://www.dash.org"}, + {"name": "Forum", "url": "https://www.dash.org/forum"}, + ], + "use_edit_page_button": True, + "github_url": "https://github.com/dashpay/docs-platform", + "show_toc_level": 2, + "show_nav_level": 1, + "favicons": [ + { + "rel": "icon", + "sizes": "16x16", + "href": "img/favicon-16x16.png", + }, + { + "rel": "icon", + "sizes": "32x32", + "href": "img/favicon-32x32.png", + }, + { + "rel": "icon", + "sizes": "96x96", + "href": "img/favicon-96x96.png", + }, + { + "rel": "icon", + "sizes": "144x144", + "href": "img/favicon-144x144.png", + }, + ], +# "navbar_start": ["navbar-logo", "languages"], +# "navbar_center": ["languages", "navbar-nav", "languages"], +# "navbar_end": ["navbar-icon-links", "version"], +# "secondary_sidebar_items": ["languages", "page-toc", "edit-this-page", "sourcelink"], +# "footer_items": ["languages", "copyright", "sphinx-version", "theme-version"], +# "primary_sidebar_end": ["languages"], +} + +html_context = { + # "github_url": "https://github.com", # or your GitHub Enterprise site + "github_user": "dashpay", + "github_repo": "docs-platform", + "github_version": "0.24.0", + "doc_path": "", +} + +def setup(app): + app.add_js_file('js/pydata-search-close.js') diff --git a/docs/dapi-client-js/overview.md b/docs/dapi-client-js/overview.md new file mode 100644 index 000000000..e30895b85 --- /dev/null +++ b/docs/dapi-client-js/overview.md @@ -0,0 +1,43 @@ +```{eval-rst} +.. _dapi-client-js-index: +``` + +# Overview + +## DAPI-Client + +[![NPM Version](https://img.shields.io/npm/v/@dashevo/dapi-client)](https://www.npmjs.com/package/@dashevo/dapi-client) +[![Build Status](https://github.com/dashevo/js-dapi-client/actions/workflows/test_and_release.yml/badge.svg)](https://github.com/dashevo/js-dapi-client/actions/workflows/test_and_release.yml) +[![Release Date](https://img.shields.io/github/release-date/dashpay/platform)](https://github.com/dashpay/platform/releases/latest) +[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen)](https://github.com/RichardLitt/standard-readme) + +Client library used to access Dash DAPI endpoints + +This library enables HTTP-based interaction with the Dash blockchain and Dash Platform via the decentralized API ([DAPI](https://github.com/dashpay/platform/tree/master/packages/dapi)) hosted on Dash masternodes. + +- `DAPI-Client` provides automatic server (masternode) discovery using either a default seed node or a user-supplied one +- `DAPI-Client` maps to DAPI's [RPC](https://github.com/dashpay/platform/tree/master/packages/dapi/lib/rpcServer/commands) and [gRPC](https://github.com/dashpay/platform/tree/master/packages/dapi/lib/grpcServer/handlers) endpoints + +### Install + +### ES5/ES6 via NPM + +In order to use this library in Node, you will need to add it to your project as a dependency. + +Having [NodeJS](https://nodejs.org/) installed, just type in your terminal : + +```sh +npm install @dashevo/dapi-client +``` + +### CDN Standalone + +For browser usage, you can also directly rely on unpkg : + +``` + +``` + +## Licence + +[MIT](https://github.com/dashevo/dapi-client/blob/master/LICENCE.md) © Dash Core Group, Inc. \ No newline at end of file diff --git a/docs/dapi-client-js/quick-start.md b/docs/dapi-client-js/quick-start.md new file mode 100644 index 000000000..411e04d37 --- /dev/null +++ b/docs/dapi-client-js/quick-start.md @@ -0,0 +1,37 @@ +# Quick start + +## ES5/ES6 via NPM + +In order to use this library in Node, you will need to add it to your project as a dependency. + +Having [NodeJS](https://nodejs.org/) installed, just type in your terminal : + +```sh +npm install @dashevo/dapi-client +``` + +## CDN Standalone + +For browser usage, you can also directly rely on unpkg : + +``` + +``` + +You can see an [example usage here](https://github.com/dashpay/platform/blob/master/packages/js-dapi-client/examples/web/web.usage.html) . + +## Initialization + +```js +const DAPIClient = require('@dashevo/dapi-client'); +const client = new DAPIClient(); + +(async () => { + const bestBlockHash = await client.core.getBestBlockHash(); + console.log(bestBlockHash); +})(); +``` + +## Quicknotes + +This package allows you to fetch & send information from both the payment chain (layer 1) and the application chain (layer 2, a.k.a Platform chain). \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/broadcasttransaction.md b/docs/dapi-client-js/usage/core/broadcasttransaction.md new file mode 100644 index 000000000..2dd20c4c0 --- /dev/null +++ b/docs/dapi-client-js/usage/core/broadcasttransaction.md @@ -0,0 +1,17 @@ +# broadcasttransaction + +**Usage**: `await client.core.broadcastTransaction(transaction)` +**Description**: Allow to broadcast a valid **signed** transaction to the network. + +Parameters: + +| parameters | type | required | Description | +| ------------------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------- | +| **transaction** | Buffer | yes | A valid Buffer representation of a transaction | +| **options** | Object | | | +| **options.allowHighFees** | Boolean | no[=false] | As safety measure, "absurd" fees are rejected when considered to high. This allow to overwrite that comportement | +| **options.bypassLimits** | Boolean | no[=false] | Allow to bypass default transaction policy rules limitation | + +Returns : transactionId (string). + +N.B : The TransactionID provided is subject to [transaction malleability](https://docs.dash.org/projects/core/en/stable/docs/guide/transactions-transaction-malleability.html), and is not a source of truth (the transaction might be included in a block with a different txid). \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/core.md b/docs/dapi-client-js/usage/core/core.md new file mode 100644 index 000000000..bb7ffee96 --- /dev/null +++ b/docs/dapi-client-js/usage/core/core.md @@ -0,0 +1,18 @@ +# Core + +```{toctree} +:maxdepth: 2 +:titlesonly: + + +broadcasttransaction +generatetoaddress +getbestblockhash +getblockbyhash +getblockbyheight +getblockhash +getmnlistdiff +getstatus +gettransaction +subscribetotransactionswithproofs +``` diff --git a/docs/dapi-client-js/usage/core/generatetoaddress.md b/docs/dapi-client-js/usage/core/generatetoaddress.md new file mode 100644 index 000000000..5e94781d5 --- /dev/null +++ b/docs/dapi-client-js/usage/core/generatetoaddress.md @@ -0,0 +1,15 @@ +# generatetoaddress + +**Usage**: `await client.core.generateToAddress(blockMumber, address, options)` +**Description**: Allow to broadcast a valid **signed** transaction to the network. +**Notes**: Will only works on regtest. + +Parameters: + +| parameters | type | required | Description | +| ---------------- | ----------------- | -------- | --------------------------------------------------------- | +| **blocksNumber** | Number | yes | A number of block to see generated on the regtest network | +| **address** | String | yes | The address that will receive the newly generated Dash | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise\} - a set of generated blockhashes. \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getbestblockhash.md b/docs/dapi-client-js/usage/core/getbestblockhash.md new file mode 100644 index 000000000..7964a4203 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getbestblockhash.md @@ -0,0 +1,12 @@ +# getbestblockhash + +**Usage**: `await client.core.getBestBlockHash(options)` +**Description**: Allow to fetch the best (highest/latest block hash) from the network + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | ----------- | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise} - The best block hash \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockbyhash.md b/docs/dapi-client-js/usage/core/getblockbyhash.md new file mode 100644 index 000000000..949f1f329 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockbyhash.md @@ -0,0 +1,13 @@ +# getblockbyhash + +**Usage**: `await client.core.getBlockByHash(hash, options)` +**Description**: Allow to fetch a specific block by its hash + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | ------------------ | +| **hash** | String | yes | A valid block hash | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise\} - The specified bufferized block \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockbyheight.md b/docs/dapi-client-js/usage/core/getblockbyheight.md new file mode 100644 index 000000000..f73d9ce8a --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockbyheight.md @@ -0,0 +1,13 @@ +# getblockbyheight + +**Usage**: `await client.core.getBlockByHeight(height, options)` +**Description**: Allow to fetch a specific block by its height + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | -------------------- | +| **height** | Number | yes | A valid block height | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise\} - The specified bufferized block \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getblockhash.md b/docs/dapi-client-js/usage/core/getblockhash.md new file mode 100644 index 000000000..e9aa91d47 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getblockhash.md @@ -0,0 +1,13 @@ +# getblockhash + +**Usage**: `await client.core.getBlockHash(height, options)` +**Description**: Allow to fetch a specific block hash from its height + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | -------------------- | +| **height** | Number | yes | A valid block height | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise\} - the corresponding block hash \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getmnlistdiff.md b/docs/dapi-client-js/usage/core/getmnlistdiff.md new file mode 100644 index 000000000..f6282e1e6 --- /dev/null +++ b/docs/dapi-client-js/usage/core/getmnlistdiff.md @@ -0,0 +1,14 @@ +# getmnlistdiff + +**Usage**: `await client.core.getMnListDiff(baseBlockHash, blockHash, options)` +**Description**: Allow to fetch a specific block hash from its height + +Parameters: + +| parameters | type | required | Description | +| ----------------- | ----------------- | -------- | ----------------------------- | +| **baseBlockHash** | String | yes | hash or height of start block | +| **blockHash** | String | yes | hash or height of end block | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise} - The Masternode List Diff of the specified period \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/getstatus.md b/docs/dapi-client-js/usage/core/getstatus.md new file mode 100644 index 000000000..f7bd66bee --- /dev/null +++ b/docs/dapi-client-js/usage/core/getstatus.md @@ -0,0 +1,31 @@ +# getstatus + +**Usage**: `await client.core.getStatus(options)` +**Description**: Allow to fetch a specific block hash from its height + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | ----------- | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise} - Status object + +```js +const status = await client.core.getStatus() +/** +{ + coreVersion: 150000, + protocolVersion: 70216, + blocks: 10630, + timeOffset: 0, + connections: 58, + proxy: '', + difficulty: 0.001745769130443678, + testnet: false, + relayFee: 0.00001, + errors: '', + network: 'testnet' +} +**/ +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/gettransaction.md b/docs/dapi-client-js/usage/core/gettransaction.md new file mode 100644 index 000000000..fea1ae92f --- /dev/null +++ b/docs/dapi-client-js/usage/core/gettransaction.md @@ -0,0 +1,13 @@ +# gettransaction + +**Usage**: `await client.core.getTransaction(id, options)` +**Description**: Allow to fetch a transaction by ID + +Parameters: + +| parameters | type | required | Description | +| ----------- | ----------------- | -------- | ------------------------------- | +| **id** | string | yes | A valid transaction id to fetch | +| **options** | DAPIClientOptions | no | | + +Returns : {Promise\} - The bufferized transaction \ No newline at end of file diff --git a/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md b/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md new file mode 100644 index 000000000..09b300fb5 --- /dev/null +++ b/docs/dapi-client-js/usage/core/subscribetotransactionswithproofs.md @@ -0,0 +1,46 @@ +# subscribetotransactionswithproofs + +**Usage**: `await client.core.subscribeToTransactionsWithProofs(bloomFilter, options = { count: 0 })` +**Description**: For any provided bloomfilter, it will return a ClientReadableStream streaming the transaction matching the filter. + +Parameters: + +| parameters | type | required | Description | +| --------------------------- | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------- | +| **bloomFilter.vData** | Uint8Array/Array | yes | The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes. | +| **bloomFilter.nHashFuncs** | Number | yes | The number of hash functions to use in this filter. The maximum value allowed in this field is 50. | +| **bloomFilter.nTweak** | Number | yes | A random value to add to the seed value in the hash function used by the bloom filter. | +| **bloomFilter.nFlags** | Number | yes | A set of flags that control how matched items are added to the filter. | +| **options.fromBlockHash** | String | yes | Specifies block hash to start syncing from | +| **options.fromBlockHeight** | Number | yes | Specifies block height to start syncing from | +| **options.count** | Number | no (default: 0) | Number of blocks to sync, if set to 0 syncing is continuously sends new data as well | + +Returns : Promise|!grpc.web.ClientReadableStream\ + +Example : + +```js +const filter; // A BloomFilter object +const stream = await client.subscribeToTransactionsWithProofs(filter, { fromBlockHeight: 0 }); + +stream + .on('data', (response) => { + const merkleBlock = response.getRawMerkleBlock(); + const transactions = response.getRawTransactions(); + + if (merkleBlock) { + const merkleBlockHex = Buffer.from(merkleBlock).toString('hex'); + } + + if (transactions) { + transactions.getTransactionsList() + .forEach((tx) => { + // tx are probabilistic, so you will have to verify it's yours + const tx = new Transaction(Buffer.from(tx)); + }); + } + }) + .on('error', (err) => { + // do something with err + }); +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/dapiclient.md b/docs/dapi-client-js/usage/dapiclient.md new file mode 100644 index 000000000..ee576394d --- /dev/null +++ b/docs/dapi-client-js/usage/dapiclient.md @@ -0,0 +1,27 @@ +# DAPIClient + +**Usage**: `new DAPIClient(options)` +**Description**: This method creates a new DAPIClient instance. + +Parameters: + +| parameters | type | required[def value] | Description | +| :------------------------------ | :------------------ | :-------------------------- | :--------------------------------------------------------------------------------------------- | +| **options** | Object | | | +| **options.dapiAddressProvider** | DAPIAddressProvider | no[ListDAPIAddressProvider] | Allow to override the default dapiAddressProvider (do not allow seeds or dapiAddresses params) | +| **options.seeds** | string\[] | no[seeds] | Allow to override default seeds (to connect to specific node) | +| **options.network** | string | no[=evonet] | Allow to setup the network to be used (livenet, testnet, evonet,..) | +| **options.timeout** | number | no[=2000] | Used to specify the timeout time in milliseconds. | +| **options.retries** | number | no[=3] | Used to specify the number of retries before aborting and erroring a request. | +| **options.baseBanTime** | number | no[=6000] | | + +Returns : DAPIClient instance. + +```js +const DAPIClient = require('@dashevo/dapi-client'); +const client = new DAPIClient({ + timeout: 5000, + retries: 3, + network: 'livenet' +}); +``` \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/broadcaststatetransition.md b/docs/dapi-client-js/usage/platform/broadcaststatetransition.md new file mode 100644 index 000000000..15667f37a --- /dev/null +++ b/docs/dapi-client-js/usage/platform/broadcaststatetransition.md @@ -0,0 +1,13 @@ +# broadcaststatetransition + +**Usage**: `async client.platform.broadcastStateTransition(stateTransition, options)` +**Description**: Send State Transition to machine + +Parameters: + +| parameters | type | required | Description | +| ------------------- | ----------------- | -------- | ----------------------------------- | +| **stateTransition** | Buffer | yes | A valid bufferized state transition | +| **options** | DAPIClientOptions | no | A valid state transition | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getdatacontract.md b/docs/dapi-client-js/usage/platform/getdatacontract.md new file mode 100644 index 000000000..c6c4ebd96 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getdatacontract.md @@ -0,0 +1,12 @@ +# getdatacontract + +**Usage**: `async client.platform.getDataContract(contractId)` +**Description**: Fetch Data Contract by id + +Parameters: + +| parameters | type | required | Description | +| -------------- | ------ | -------- | ----------------------------- | +| **contractId** | String | yes | A valid registered contractId | + +Returns : Promise \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getdocuments.md b/docs/dapi-client-js/usage/platform/getdocuments.md new file mode 100644 index 000000000..ff290de62 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getdocuments.md @@ -0,0 +1,18 @@ +# getdocuments + +**Usage**: `async client.platform.getDocuments(contractId, type, options)` +**Description**: Fetch Documents from Drive + +Parameters: + +| parameters | type | required | Description | +| ---------------------- | ------ | -------- | -------------------------------------------------- | +| **contractId** | String | yes | A valid registered contractId | +| **type** | String | yes | DAP object type to fetch (e.g: 'preorder' in DPNS) | +| **options.where** | Object | yes | Mongo-like query | +| **options.orderBy** | Object | yes | Mongo-like sort field | +| **options.limit** | Number | yes | Limit the number of object to fetch | +| **options.startAt** | Number | yes | number of objects to skip | +| **options.startAfter** | Number | yes | exclusive skip | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentity.md b/docs/dapi-client-js/usage/platform/getidentity.md new file mode 100644 index 000000000..fa6de9f78 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentity.md @@ -0,0 +1,12 @@ +# getidentity + +**Usage**: `async client.platform.getIdentity(id)` +**Description**: Fetch the identity by id + +Parameters: + +| parameters | type | required | Description | +| ---------- | ------ | -------- | --------------------------- | +| **id** | String | yes | A valid registered identity | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md b/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md new file mode 100644 index 000000000..646b3bc27 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentitybyfirstpublickey.md @@ -0,0 +1,12 @@ +# getidentitybyfirstpublickey + +**Usage**: `async client.platform.getIdentityByFirstPublicKey(publicKeyHash)` +**Description**: Fetch the identity using the public key hash of the identity's first key + +Parameters: + +| parameters | type | required | Description | +| ----------------- | ------ | -------- | ----------------------- | +| **publicKeyHash** | String | yes | A valid public key hash | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md b/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md new file mode 100644 index 000000000..814d11d37 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/getidentityidbyfirstpublickey.md @@ -0,0 +1,12 @@ +# getidentityidbyfirstpublickey + +**Usage**: `async client.platform.getIdentityIdByFirstPublicKey(publicKeyHash)` +**Description**: Fetch the identity ID using the public key hash of the identity's first key + +Parameters: + +| parameters | type | required | Description | +| ----------------- | ------ | -------- | ----------------------- | +| **publicKeyHash** | String | yes | A valid public key hash | + +Returns : Promise\ \ No newline at end of file diff --git a/docs/dapi-client-js/usage/platform/platform.md b/docs/dapi-client-js/usage/platform/platform.md new file mode 100644 index 000000000..f24015909 --- /dev/null +++ b/docs/dapi-client-js/usage/platform/platform.md @@ -0,0 +1,14 @@ +# Platform + +```{toctree} +:maxdepth: 2 +:titlesonly: + + +broadcaststatetransition +getdatacontract +getdocuments +getidentity +getidentitybyfirstpublickey +getidentityidbyfirstpublickey +``` diff --git a/docs/dapi-client-js/usage/usage.md b/docs/dapi-client-js/usage/usage.md new file mode 100644 index 000000000..361a9a1e1 --- /dev/null +++ b/docs/dapi-client-js/usage/usage.md @@ -0,0 +1,10 @@ +# Usage + +```{toctree} +:maxdepth: 2 +:titlesonly: + +dapiclient +core/core +platform/platform +``` diff --git a/docs/explanations/dapi.md b/docs/explanations/dapi.md new file mode 100644 index 000000000..a95149d34 --- /dev/null +++ b/docs/explanations/dapi.md @@ -0,0 +1,29 @@ +```{eval-rst} +.. _explanations-dapi: +``` + +# Decentralized API (DAPI) + +## Overview + +Historically, nodes in most cryptocurrency networks communicated with each other, and the outside world, according to a peer-to-peer (P2P) protocol. The use of P2P protocols presented some downsides for developers, namely, network resources were difficult to access without specialized knowledge or trusted third-party services. + +To overcome these obstacles, the Dash decentralized API (DAPI) uses Dash's robust masternode infrastructure to provide an API for accessing the network. DAPI supports both layer 1 (Core blockchain) and layer 2 (Dash Platform) functionality so all developers can interact with Dash via a single interface. + +```{eval-rst} +.. figure:: ../../img/dapi.svg + :class: no-scaled-link + :align: center + :width: 90% + :alt: DAPI Overview + + DAPI Overview +``` + +## Security + +DAPI protects connections by using TLS to encrypt communication between clients and the masternodes. This encryption safeguards transmitted data from unauthorized access, interception, or tampering. [Platform gRPC endpoints](../reference/dapi-endpoints-platform-endpoints.md) provide an additional level of security by optionally returning cryptographic proofs. Successful proof verification guarantees that the server responded without modifying the requested data. + +## 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). \ No newline at end of file diff --git a/docs/explanations/dashpay.md b/docs/explanations/dashpay.md new file mode 100644 index 000000000..0797f5ac0 --- /dev/null +++ b/docs/explanations/dashpay.md @@ -0,0 +1,278 @@ +# DashPay + +## Overview + +DashPay is one of the first applications of Dash Platform's [data contracts](../explanations/platform-protocol-data-contract.md) . At its core DashPay is a data contract that enables a decentralized application that creates bidirectional [direct settlement 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 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. Instead of sending to an address, a user sends directly to another user. Users will have a username, a display name, an avatar and a quick bio/information message. + +- **Easy Payments**: Once two users have exchanged contact requests, each can make payments to the other without manually sharing addresses via emails, texts or BIP21 QR codes. This is because every contact request contains the information (an encrypted extended public key) required to send payments to the originator of the request. When decrypted, this extended public key can be used by the recipient of the contact request to generate payment addresses for the originator of the contact request. + +- **Payment History**: When a contact is established, a user can easily track the payments they have sent to another user and the payments that they have received from that other user. A user will have an extended private key to track payments that are received from the other user and an extended public key to track payments that are sent to that other user. + +- **Payment Participant Protection**: The extended public keys in contact requests are encrypted in such a way that only the two users involved in a contact's two way relationship can decrypt those keys. This ensures that when any two users make payments in DashPay, only they know the sender and receiver while 3rd parties do not. + +## Details + +The contract defines three document types: `contactRequest`, `profile` and `contactInfo`. ContactRequest documents are the most important. They are used to establish relationships and payment channels between Dash identities. Profile documents are used to store public facing information about Dash identities including avatars and display names. ContactInfo documents can be used to store private information about other Dash identities. + +### Establishing a Contact + +1. Bob installs wallet software that supports DashPay. +2. Bob [registers an identity](../tutorials/identities-and-names/register-an-identity.md) and then [creates a username](../tutorials/identities-and-names/register-a-name-for-an-identity.md) through [DPNS](../explanations/dpns.md). +3. Bob searches for Carol by her username. Behind the scenes this search returns the unique identifier for Carol's identity. An example of doing this can be seen in the [Retrieve a Name tutorial](../tutorials/identities-and-names/retrieve-a-name.md). +4. Bob sends a contact request containing an encrypted extended public key to Carol. This establishes a one way relationship from Bob to Carol. +5. Carol accepts the request by sending a contact request containing an encrypted extended public key back to Bob. This establishes a one way relationship from Carol to Bob. +6. Bob and Carol are now contacts of one another and can make payments to each other by decrypting the extended public key received from the other party and deriving payment addresses from it. Since both have established one way relationships with each other, they now have a two way relationship. If Bob gets a new device, he can use his recovery phrase from step one and restore his wallet, contacts (including Carol) and payments to and from his contacts. + +```{eval-rst} +.. figure:: ./img/dashpay.png + :class: no-scaled-link + :align: center + :height: 350 + :alt: Contact-based Wallet + + Contact-based Wallet +``` + +### Implementation + +DashPay has many constraints as defined in the [DashPay data contract](https://github.com/dashevo/platform/blob/master/packages/dashpay-contract/schema/dashpay.schema.json). Additionally, the DashPay data triggers defined in [js-dpp](https://github.com/dashevo/platform/tree/master/packages/js-dpp/lib/dataTrigger/dashpayDataTriggers) 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. + +- Contact request details +- Profile details +- Contact Info details + +```json +{ + "profile": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "avatarUrl": { + "type": "string", + "format": "url", + "maxLength": 2048 + }, + "avatarHash": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "description": "SHA256 hash of the bytes of the image specified by avatarUrl" + }, + "avatarFingerprint": { + "type": "array", + "byteArray": true, + "minItems": 8, + "maxItems": 8, + "description": "dHash the image specified by avatarUrl" + }, + "publicMessage": { + "type": "string", + "maxLength": 140 + }, + "displayName": { + "type": "string", + "maxLength": 25 + } + }, + "required": [ + "$createdAt", + "$updatedAt" + ], + "additionalProperties": false + }, + "contactInfo": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "rootEncryptionKeyIndex": "asc" + }, + { + "derivationEncryptionKeyIndex": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "encToUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32 + }, + "rootEncryptionKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "derivationEncryptionKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "privateData": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 2048, + "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 + }, + "contactRequest": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + }, + { + "accountReference": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + } + ] + }, + { + "properties": [ + { + "toUserId": "asc" + }, + { + "$createdAt": "asc" + } + ] + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$createdAt": "asc" + } + ] + } + ], + "properties": { + "toUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "encryptedPublicKey": { + "type": "array", + "byteArray": true, + "minItems": 96, + "maxItems": 96 + }, + "senderKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "recipientKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "accountReference": { + "type": "integer", + "minimum": 0 + }, + "encryptedAccountLabel": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 80 + }, + "autoAcceptProof": { + "type": "array", + "byteArray": true, + "minItems": 38, + "maxItems": 102 + }, + "coreHeightCreatedAt": { + "type": "integer", + "minimum": 1 + } + }, + "required": [ + "$createdAt", + "toUserId", + "encryptedPublicKey", + "senderKeyIndex", + "recipientKeyIndex", + "accountReference" + ], + "additionalProperties": false + } +} +``` \ No newline at end of file diff --git a/docs/explanations/dpns.md b/docs/explanations/dpns.md new file mode 100644 index 000000000..42828589a --- /dev/null +++ b/docs/explanations/dpns.md @@ -0,0 +1,61 @@ +# Name Service (DPNS) + +## Overview + +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. + +### Relationship to identities +DPNS names and [Identities](../explanations/identity.md) are tightly integrated. Identities provide a foundation that DPNS builds on to enable name-based interactions -- a user experience similar to what is found in non-cryptocurrency applications. With DPNS, users or application developers register a name and associate it with an identity. Once linked, the identity's private keys allow them to prove ownership of the name to establish trust when they interact with other users and applications. + +## 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. + +To prevent [front-running](https://en.wikipedia.org/wiki/Domain_name_front_running), name registration is split into a two phase process consisting of: +1. Pre-ordering the domain name +2. Registering the domain name + +In the pre-order phase, the domain name is salted to obscure the actual domain name being registered (e.g. `hash('alice.dash' + salt)`) and submitted to platform. This is done to prevent masternodes from seeing the names being registered and "stealing" them for later resale. Once the pre-order receives a sufficient number of confirmations, the registration can proceed. + +In the registration phase, the domain name (e.g. `alice.dash`) is once again submitted along with the salt used in the pre-order. The salt serves as proof that the registration is from the user that submitted the pre-order. This registration also references the identity being associated with the domain name to complete the identity-domain link. + +### Implementation + +DPNS names currently have several constraints as defined in the [DPNS data contract](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json). The constraints exist to maintain compatibility with DNS: +* 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/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L35) in the DPNS data contract: +> ``` +> "^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$" +> ``` + +Additionally, the DPNS [data triggers](../explanations/platform-protocol-data-trigger.md) defined in [js-dpp](https://github.com/dashevo/platform/tree/master/packages/js-dpp/lib/dataTrigger) enforce additional validation rules related to the `domain` document. + +For more implementation details, please reference the open-source JavaScript DPNS client reference implementation found in the [js-dpns-client](https://github.com/dashevo/js-dpns-client) repository. Additionally, the DPNS data contract is available in the [dpns-contract](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) repository. + +### Contract Diagram + +This is a visualization of the JSON data contract as UML class diagram for better understanding of the structure. The left side shows the `domain` document and the right side shows the `preorder` document: + +```{eval-rst} +.. figure:: ./img/dpns-uml.png + :class: no-scaled-link + :align: center + :width: 90% + :alt: DPNS Contract Diagram + + DPNS Contract Diagram +``` + +View [a full-size copy of this diagram](./img/dpns-uml.png). diff --git a/docs/explanations/drive-platform-chain.md b/docs/explanations/drive-platform-chain.md new file mode 100644 index 000000000..d6ed3de58 --- /dev/null +++ b/docs/explanations/drive-platform-chain.md @@ -0,0 +1,24 @@ +# Platform Chain + +## Overview + +The platform chain is the [Drive](../explanations/drive.md) component responsible for replicating the platform state across all masternodes participating in the network. Masternodes 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. + +## Details + +### Evolution of design + +Early designs of Drive were based on using on the layer 1 core blockchain and [IPFS](https://docs.ipfs.io/introduction/overview/) to replicate layer 2 data. As the design matured, a number of challenges led to a re-evaluation of how to efficiently secure, propagate, and finalize this data. Ultimately, meeting the requirements for a trustless, decentralized system led to choosing a blockchain-based solution over some seemingly obvious choices that work fine in a centralized setting. + +### Characteristics + +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) +- 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) + +### Blocks and Transitions + +Similar to transactions on the Dash core chain, state transitions are aggregated and put into blocks periodically on the platform chain. Each block has a header that points back to the previous block, thus forming a chain of blocks that is shared among all masternodes. The platform's pBFT consensus algorithm is responsible for ordering the state transitions into a block and then committing the block. As soon as a block is accepted by a ⅔ + 1 majority of validators, it becomes final and cannot be changed. Thus, the platform chain is not susceptible to blockchain reorganizations. \ No newline at end of file diff --git a/docs/explanations/drive-platform-state.md b/docs/explanations/drive-platform-state.md new file mode 100644 index 000000000..9bd349fc4 --- /dev/null +++ b/docs/explanations/drive-platform-state.md @@ -0,0 +1,15 @@ +# Platform State + +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. + +```{eval-rst} +.. figure:: ../../img/platform-state.svg + :class: no-scaled-link + :align: center + :width: 80% + :alt: Platform State Propagation + + Platform State Propagation +``` diff --git a/docs/explanations/drive.md b/docs/explanations/drive.md new file mode 100644 index 000000000..a451721ad --- /dev/null +++ b/docs/explanations/drive.md @@ -0,0 +1,45 @@ +# Drive + +## Overview + +Using the traditional, layer 1 blockchain for data storage is widely known to be expensive and inefficient. Consequently, data for Dash Platform applications is stored in Drive, a layer 2 component that provides decentralized storage hosted by masternodes. As data changes over time, Drive maintains a record of the current state of each item to support easy retrieval using [DAPI](../explanations/dapi.md). + +## Details + +### Drive Components + +There are a number of components working together to facilitate Drive's overall functionality. These components are listed below along with a brief description of service they provide: + + - [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) + +### 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 +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 + +```{eval-rst} +.. figure:: ../../img/drive.svg + :class: no-scaled-link + :align: center + :width: 80% + :alt: Storing data in Drive + + Storing data in Drive +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:hidden: + +drive-platform-chain +drive-platform-state +``` diff --git a/docs/explanations/fees.md b/docs/explanations/fees.md new file mode 100644 index 000000000..438e0a8a1 --- /dev/null +++ b/docs/explanations/fees.md @@ -0,0 +1,68 @@ +# Fees + +## Overview + +Since Dash Platform is a decentralized system with inherent costs to its functionality, an adequate fee system is necessary in order to incentive the hosts (masternodes) to maintain it. + +Fees on Dash Platform are divided into two main categories: + * Storage fees + * Processing fees + +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. + +## Costs + +The current cost schedule is outlined in the table below: + +| Operation | Cost (credits) | +| - | - | +| Permanent storage | 40000 / byte | +| Base processing fee | 100000 | +| Write to storage | 750 / byte | +| Load from storage | 3500 / byte | +| Seek storage | 2000 | +| Query | 75 / byte | +| 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. + +## Fee Multiplier + +Given fluctuations of the Dash price, a variable *Fee Multiplier* provides a way to balance the cost of fees with network hosting requirements. All fees are multiplied by the Fee Multiplier: + +```text + feePaid = initialFee * feeMultiplier +``` + +The Fee Multiplier is subject to change at any time at the discretion of the masternodes via a voting mechanism. Dash Core Group research indicates maintaining fees at approximately 2x the cost of hosting the network is optimal. + + + +## Storage Refund + +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. + +## User Tip + +Wallets will be enabled to give users the option to provide a tip to the block proposer in hopes of incentivizing them to include their state transition in the next block. This feature will be especially useful in times of high traffic. + +## Formula + +The high level formula for a state transition's fee is: + +```text + fee = storageFee + processingFee - storageRefund + userTip +``` + + \ No newline at end of file diff --git a/docs/explanations/identity.md b/docs/explanations/identity.md new file mode 100644 index 000000000..6ed8df1c0 --- /dev/null +++ b/docs/explanations/identity.md @@ -0,0 +1,65 @@ +# Identity + +## Overview + +Identities are foundational to Dash Platform. They provide a familiar, easy-to-use way for users to interact and identify one another using names rather than complicated cryptocurrency identifiers such as public key hashes. + +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. + +## 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. + +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. + +### 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. + +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. + +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. + +Users who already have Dash funds can act as their own sponsor if they wish, using the same steps listed here. + +### Identity Balance Topup Process + +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. + +### Identity Update Process + +> 👍 +> +> Added in Dash Platform Protocol v0.23 + +Identity owners may find it necessary to update their identity keys periodically for security purposes. The [identity update state transition](https://github.com/dashpay/dips/blob/master/dip-0011.md#identity-update-transition) enables users to add new keys and disable existing ones. + +Identity updates only require the creation of a state transition that includes a list of keys being added and/or disabled. Platform retains disabled keys so that any existing data they signed can still be verified while preventing them from signing new data. + +### Masternode Identities + +Dash Platform v0.22 introduced identities for masternode owners and operators, and a future release will introduce identities for masternode voters. The system automatically creates and updates these identities based on information in the layer 1 masternode registration transactions. For example, owner/operator withdraw keys on Platform are aligned with the keys assigned on the Core blockchain. + +In a future release, the credits paid as fees for state transitions will be distributed to masternode-related identities similar to how rewards are currently distributed to masternodes on the core blockchain. Credits will be split between owner and operator in the same ratio as on layer 1, and masternode owners will also have the flexibility to further split their portion between multiple identities to support reward-sharing use cases. + +## Credits + +> 👍 Added in Dash Platform Protocol v0.13 +> +> DPP v0.13 introduced the initial implementation of credits. Future releases will expand the functionality available. + +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 v0.13, 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. \ No newline at end of file diff --git a/docs/explanations/img/dashpay-uml.png b/docs/explanations/img/dashpay-uml.png new file mode 100644 index 000000000..d7f7ff2ab Binary files /dev/null and b/docs/explanations/img/dashpay-uml.png differ diff --git a/docs/explanations/img/dashpay.png b/docs/explanations/img/dashpay.png new file mode 100644 index 000000000..b859fc4ae Binary files /dev/null and b/docs/explanations/img/dashpay.png differ diff --git a/docs/explanations/img/dpns-uml.png b/docs/explanations/img/dpns-uml.png new file mode 100644 index 000000000..e197054c5 Binary files /dev/null and b/docs/explanations/img/dpns-uml.png differ diff --git a/docs/explanations/platform-consensus.md b/docs/explanations/platform-consensus.md new file mode 100644 index 000000000..da402faed --- /dev/null +++ b/docs/explanations/platform-consensus.md @@ -0,0 +1,82 @@ +# Platform Consensus + +Dash Platform is a decentralized network that requires its own consensus algorithm for decision-making and verifying state transitions. This consensus algorithm must fulfill the following three requirements: + +** \* Fast write operations:** The Drive block time needs to be small since state transitions must be confirmed and applied to the state as quickly as possible. +** \* Fast reads:** Each block should update the state so that the data and cryptographic proofs can be read directly from the database. However, this needs to be done fast, so a consensus algorithm with faster reads is needed. +** \* Data consistency:** Nodes should always respond with the same data for a given block height to negate instances of blockchain reorgs. + +Tendermint was selected as the consensus solution that most closely aligned with the requirements and goals of Dash Platform. + +## Tendermint + +Tendermint is a mostly asynchronous, pBFT-based consensus protocol. Here is a quick overview of how it works: + +- Validators participate by taking turns to propose. They validate state transitions by voting on them. +- If a validator successfully validates a block, it gets added to the chain. Do note that voting on state transitions is indirect. Plus, validators don't work on individual transitions, but vote on a block of transitions. This method is a lot more resource-friendly. +- If a validator fails to add a block, the protocol automatically moves to the next round, and a new validator is chosen to propose the block. +- Following the proposal, Tendermint goes through two stages to voting – Pre-vote and Pre-Commit. +- A block gets committed when it gets >2/3rd of the total validators pre-committing for it in one round. The sequence of Propose -> Pre-vote -> Pre-commit is one round. +- In the event of a network dispute, Tendermint prefers consistency over availability.No additional blocks are confirmed or finalized until the dispute is resolved. This takes network reorg out of the equation. + +Tendermint has been mainly designed to enable efficient verification and authentication of the latest state of the blockchain. It does so by embedding cryptographic commitments for certain information in the block "header." This information includes: + +- Contents of the block. +- 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. + +### Tendermint Limitations + +While Tendermint provided a great starting point, implementing the classic version of the algorithm would have required us to start from scratch. For example, Tendermint validators use [EdDSA](https://en.wikipedia.org/wiki/EdDSA) cryptographic keys to sign votes during the consensus process. + +However, Dash already has a well-established network of Masternodes that use BLS keys and a [BLS threshold signing mechanism](https://blog.dash.org/secret-sharing-and-threshold-signatures-with-bls-954d1587b5f) to produce a single signature that mobile wallets and other light clients can easily verify. In addition, subsets of masternodes, called [Long-living Masternode Quorums (LLMQ)](https://github.com/dashpay/dips/blob/master/dip-0006.md), can perform BLS threshold signing on arbitrary messages. + +Rather than reinventing the wheel, Dash chose to fork the Tendermint code and integrate masternode quorums into the process to create a new consensus algorithm called "Tenderdash." + +## Tenderdash + +As with Tendermint, Tenderdash provides Byzantine Fault Tolerant (BFT) State Machine Replication via blocks containing transactions. Additionally, it has been updated to integrate some improvements that leverage Dash's LLMQs. Key mechanisms of the Tenderdash algorithm include: + +- If enough members have signed the same message, a valid recovered threshold signature can be created and propagated to the rest of the network. +- Quorums are formed and rotated from time to time through distributed key generation (DKG) sessions. +- DKG chooses pseudorandom nodes from the deterministic masternode list. +- The resulting quorum is then committed to the core blockchain as a transaction. +- 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). + +This allows Dash Platform to leverage the best of both worlds – the speed and finality of Tendermint and the security of PoW. + +### Dynamic Validator Set Rotation + +Rather than having a static validator set, Tenderdash periodically changes to a new set of validator nodes. These validator sets are a subset of masternodes that belong to the LLMQs. + +The validator set is assigned to a new masternode quorum every 15 blocks (~2 mins). To determine the next quorum, the BLS threshold signature of the previous block is used as a [verifiable random function](https://en.wikipedia.org/wiki/Verifiable_random_function) to choose one of the available quorums. + +There are many advantages to adopting this dynamic rotation approach: + +- The validator set is less predictable, which reduces the window for attacks like DoS. +- The process balances the performance and security of platform chains like InstantSend and ChainLock quorum changes on the core chain. + +## How Does Tenderdash Differ From Tendermint? + +Here are the differences between Tenderdash and Tendermint: + +- **Threshold Signatures**: Tenderdash employs threshold signatures for signing, adding an extra layer of security. +- **Quorum-Based Voting**: Tenderdash implements quorums, meaning not all validators participate in every voting round; only active quorum members are involved, enhancing efficiency. +- **Execution Timing**: Tenderdash facilitates same-block execution, optimizing transaction processing, whereas Tendermint traditionally relies on next-block execution. +- **Consensus Module Refactoring**: Tenderdash has undergone a complete overhaul of its vote-extensions and consensus module, working diligently to eliminate deadlocks and increase stability. +- **Dynamic Validator Management**: Tenderdash incorporates logic to actively connect with new validators in a set and disconnect those that are no longer in the validator set, thereby ensuring an adaptable and efficient network. +- **Project Activity**: Whereas Tenderdash continues to evolve and improve, Tendermint appears somewhat inactive lately, though this observation might be subjective. \ No newline at end of file diff --git a/docs/explanations/platform-protocol-data-contract.md b/docs/explanations/platform-protocol-data-contract.md new file mode 100644 index 000000000..a3fe88a27 --- /dev/null +++ b/docs/explanations/platform-protocol-data-contract.md @@ -0,0 +1,288 @@ +# Data Contract + +## Overview + +As described briefly in the [Dash Platform Protocol explanation](../explanations/platform-protocol.md#data-contract), Dash Platform uses data contracts to define the schema (structure) of data it stores. Therefore, an application must first register a data contract before using the platform to store its data. Then, when the application attempts to store or change data, the request will only succeed if the new data matches the data contract's schema. + +The first two data contracts are the [DashPay wallet](https://www.dash.org/dashpay/) and [Dash Platform Name Service (DPNS)](../explanations/dpns.md). The concept of the social, username-based DashPay wallet served as the catalyst for development of the platform, with DPNS providing the mechanism to support usernames. + +## Details + +### Ownership + +Data contracts are owned by the [identity](../explanations/identity.md) that registers them. Each identity may be used to create multiple data contracts and data contract updates can only be made using the identity that owns it. + +### Structure + +Each data contract must define several fields. When using the [JavaScript implementation](https://github.com/dashevo/platform/tree/master/packages/js-dpp) of the Dash Platform Protocol, some of these fields are automatically set to a default value and do not have to be explicitly provided. These include: + - The platform protocol schema it uses (default: defined by [js-dpp](https://github.com/dashevo/platform/blob/master/packages/js-dpp/lib/dataContract/DataContract.js#L352)) + - A contract ID (generated from a hash of the data contract's owner identity plus some entropy) + - One or more documents + +In the [example contract](#example-contract) shown below, a `contact` document and a `profile` document are defined. Each of these documents then defines the properties and indices it requires. + +### Registration + +Once a [Dash Platform Protocol](../explanations/platform-protocol.md) compliant data contract has been defined, it may be registered on the platform. Registration is completed by submitting a state transition containing the data contract to [DAPI](../explanations/dapi.md). + +The drawing below illustrates the steps an application developer follows to complete registration. + +```{eval-rst} +.. figure:: ../../img/data-contract.svg + :class: no-scaled-link + :align: center + :width: 80% + :alt: Data Contract Registration + + Data Contract Registration +``` + +### Updates + +Since Dash Platform v0.22, it is possible 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. + +## Example Contract + +An example contract for [DashPay](https://github.com/dashevo/platform/blob/master/packages/dashpay-contract/schema/dashpay.schema.json) is included below: + +```json +{ + "profile": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "avatarUrl": { + "type": "string", + "format": "url", + "maxLength": 2048 + }, + "avatarHash": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "description": "SHA256 hash of the bytes of the image specified by avatarUrl" + }, + "avatarFingerprint": { + "type": "array", + "byteArray": true, + "minItems": 8, + "maxItems": 8, + "description": "dHash the image specified by avatarUrl" + }, + "publicMessage": { + "type": "string", + "maxLength": 140 + }, + "displayName": { + "type": "string", + "maxLength": 25 + } + }, + "required": [ + "$createdAt", + "$updatedAt" + ], + "additionalProperties": false + }, + "contactInfo": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "rootEncryptionKeyIndex": "asc" + }, + { + "derivationEncryptionKeyIndex": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$updatedAt": "asc" + } + ] + } + ], + "properties": { + "encToUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32 + }, + "rootEncryptionKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "derivationEncryptionKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "privateData": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 2048, + "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 + }, + "contactRequest": { + "type": "object", + "indices": [ + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + }, + { + "accountReference": "asc" + } + ], + "unique": true + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "toUserId": "asc" + } + ] + }, + { + "properties": [ + { + "toUserId": "asc" + }, + { + "$createdAt": "asc" + } + ] + }, + { + "properties": [ + { + "$ownerId": "asc" + }, + { + "$createdAt": "asc" + } + ] + } + ], + "properties": { + "toUserId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "encryptedPublicKey": { + "type": "array", + "byteArray": true, + "minItems": 96, + "maxItems": 96 + }, + "senderKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "recipientKeyIndex": { + "type": "integer", + "minimum": 0 + }, + "accountReference": { + "type": "integer", + "minimum": 0 + }, + "encryptedAccountLabel": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 80 + }, + "autoAcceptProof": { + "type": "array", + "byteArray": true, + "minItems": 38, + "maxItems": 102 + }, + "coreHeightCreatedAt": { + "type": "integer", + "minimum": 1 + } + }, + "required": [ + "$createdAt", + "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: + +```{eval-rst} +.. figure:: ./img/dashpay-uml.png + :class: no-scaled-link + :align: center + :width: 90% + :alt: Dashpay Contract Diagram + + Dashpay Contract Diagram +``` + +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 new file mode 100644 index 000000000..6fc631680 --- /dev/null +++ b/docs/explanations/platform-protocol-data-trigger.md @@ -0,0 +1,28 @@ +# 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. + +## 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. + +## 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. + +As an example, DPP contains several [data triggers for DPNS](https://github.com/dashevo/platform/tree/master/packages/js-dpp/lib/dataTrigger/). The `domain` document has added constraints for creation. All DPNS document types have constraints on replacing or deleting: + +| Data Contract | Document | Action(s) | Trigger Description | +| - | - | - | - | +| DPNS | `domain` | [`CREATE`](https://github.com/dashevo/platform/blob/master/packages/js-dpp/lib/dataTrigger/dpnsTriggers/createDomainDataTrigger.js) | Enforces DNS compatibility, validate provided hashes, and restrict top-level domain (TLD) registration | +| ---- | ----| ---- | ---- | +| DPNS | All Document Types | [`REPLACE`](https://github.com/dashevo/platform/blob/master/packages/js-dpp/lib/dataTrigger/rejectDataTrigger.js) | Prevents updates to any DPNS document type | +| DPNS | All Document Types | [`DELETE`](https://github.com/dashevo/platform/blob/master/packages/js-dpp/lib/dataTrigger/rejectDataTrigger.js) | Prevents deletion of any DPNS document type | + +When document state transitions are received, DPP checks if there is a trigger associated with the document type and action. If a trigger is found, DPP executes the trigger logic. Successful execution of the trigger logic is necessary for the document to be accepted and applied to the [platform state](../explanations/drive-platform-state.md). \ No newline at end of file diff --git a/docs/explanations/platform-protocol-document.md b/docs/explanations/platform-protocol-document.md new file mode 100644 index 000000000..e02c4f9e6 --- /dev/null +++ b/docs/explanations/platform-protocol-document.md @@ -0,0 +1,111 @@ +# Document + +## Overview + +Dash Platform is based on [document-oriented database](https://en.wikipedia.org/wiki/Document-oriented_database) concepts and uses related terminology. In short, JSON documents are stored into document collections which can then be fetched back using a [query language](../reference/query-syntax.md) similar to common document-oriented databases like [MongoDB](https://www.mongodb.com/), [CouchDB](https://couchdb.apache.org/), or [Firebase](https://firebase.google.com/). + +Documents are defined in an application's [Data Contract](../explanations/platform-protocol-data-contract.md) and represent the structure of application-specific data. Each document consists of one or more fields and the indices necessary to support querying. + +## Details + +### Base Fields + +Dash Platform Protocol (DPP) defines a set of base fields that must be present in all documents. For the [`js-dpp` reference implementation](https://github.com/dashevo/platform/tree/master/packages/js-dpp), the base fields shown below are defined in the [document base schema](https://github.com/dashevo/platform/blob/master/packages/js-dpp/schema/document/documentBase.json). + +| Field Name | Description | +| - | - | +| protocolVersion | The platform protocol version (currently `1`) | +| $id | The document ID (32 bytes) | +| $type | Document type defined in the referenced contract | +| $revision | Document revision (=>1) | +| $dataContractId | Data contract ID generated from the data contract's `ownerId` and `entropy` (32 bytes) | +| $ownerId | [Identity](../explanations/identity.md) of the user submitting the document (32 bytes) | +| $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). + +### 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/dashevo/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). + +| Document Type | Field Name | Data Type | +| - | - | - | +| preorder | saltedDomainHash | string | +| --- | --- | --- | +| domain | label | string | +| domain | normalizedLabel | string | +| domain | normalizedParentvDomainName | string | +| domain | preorderSalt | array (bytes) | +| domain | records | object | +| domain | records.dashUniqueIdentityId | array (bytes) | +| domain | records.dashAliasIdentityId | array (bytes) | +| domain | subdomainRules | object | +| domain | subdomainRules.allowSubdomains | boolean | + +### Example Document + +The following example shows the structure of a DPNS `domain` document as output from `JSON.stringify()`. Note the `$` prefix indicating the base fields. + +```json +{ + "$protocolVersion": 1, + "$id": "5D8U1k6t6ax8TnyL6QGFFbtMhn39zsixrSMQaxZrYKf1", + "$type": "domain", + "$dataContractId": "GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec", + "$ownerId": "9gU2ZnDhkakHgB4eLbqvEAwQPDBwhW12KD5xPZxybNjE", + "$revision": 1, + "label": "RT-Sylvan-71605", + "normalizedLabel": "rt-sylvan-71605", + "normalizedParentDomainName": "dash", + "preorderSalt": "zKaLWLe+kKHiRoBXdfSd7TSU9HdIseeoOly1eTYZ670=", + "records": { + "dashUniqueIdentityId": "9gU2ZnDhkakHgB4eLbqvEAwQPDBwhW12KD5xPZxybNjE" + }, + "subdomainRules": { + "allowSubdomains": false + } +} +``` + +## Document Submission + +Once a document has been created, it must be encapsulated in a State Transition to be sent to the platform. The structure of a document state transition is shown below. For additional details, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. + +| Field Name | Description | +| - | - | +| protocolVersion | Dash Platform Protocol version (currently `0`) | +| type | State transition type (`1` for documents) | +| ownerId | Identity submitting the document(s) | +| transitions | Document `create`, `replace`, or `delete` transitions (up to 10 objects) | +| signaturePublicKeyId | The `id` of the identity public key that signed the state transition | +| signature | Signature of state transition data | + +### 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: + +| Field | Type | Description| +| - | - | - | +| $entropy | array (32 bytes) | Entropy used in creating the document ID | +| $createdAt | integer | (Optional) Time (in milliseconds) the document was created | +| $updatedAt | integer | (Optional) Time (in milliseconds) the document was last updated | + +### 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: + +| Field | Type | Description| +| - | - | - | +| $revision | integer | Document revision (=> 1) | +| $updatedAt | integer | (Optional) Time (in milliseconds) the document was last updated | + +### 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. + +> 📘 +> +> For more detailed information, see the [Platform Protocol Reference - Document](../protocol-ref/document.md) page. \ No newline at end of file diff --git a/docs/explanations/platform-protocol-state-transition.md b/docs/explanations/platform-protocol-state-transition.md new file mode 100644 index 000000000..2d082f9a6 --- /dev/null +++ b/docs/explanations/platform-protocol-state-transition.md @@ -0,0 +1,49 @@ +# State Transition + +## Overview + +At any given point in time, the data stored by each application (and more broadly, the entire platform) is in a specific state. State transitions are the means for submitting data that creates, updates, or deletes platform data and results in a change to a new state. + +For example, Alice may have already added Bob and Carol as friends in [DashPay](../explanations/dashpay.md) while also having a pending friend request to Dan. If Dan declines the friend request, the state will transition to a new one where Alice and Bob remain in Alice’s friend list while Dan moves to the declined list. + +```{eval-rst} +.. figure:: ../../img/state-transition.svg + :class: no-scaled-link + :align: center + :width: 90% + :alt: State transition example + + State Transition Example +``` + +## Implementation Overview + +To ensure the consistency and integrity of data stored on Layer 2, all data is governed by the [Dash Platform Protocol](../explanations/platform-protocol.md) (DPP) which describes serialization and validation rules. Since state transitions are the vehicle for delivering data to the platform, the implementation of state transitions resides in DPP alongside the validation logic. + +### Structure + +To support the various data types used on the platform and enable future updates, state transitions were designed to be flexible. Each state transition consists of a: + +1. Header - version and payload type +2. Payload - contents vary depending on payload type +3. Signature - signature of the header/payload by the identity submitting to state transition + +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-creation) (`0`) | [Database schema](../explanations/platform-protocol-data-contract.md) for a single application | +| [Documents Batch](../protocol-ref/document.md#document-submission) (`1`) | An array of 1 or more [document](../explanations/platform-protocol-document.md) transition objects containing application data | +| [Identity Create](../protocol-ref/identity.md#identity-creation) (`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 | + +### Application Usage + +State transitions are constructed by client-side libraries and then submitted to the platform via [DAPI](../explanations/dapi.md). Based on the validation rules described in [DPP](../explanations/platform-protocol.md) (and an application [data contract](../explanations/platform-protocol-data-contract.md) where relevant), Dash Platform first validates the state transition. + +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 \ No newline at end of file diff --git a/docs/explanations/platform-protocol.md b/docs/explanations/platform-protocol.md new file mode 100644 index 000000000..e71c92718 --- /dev/null +++ b/docs/explanations/platform-protocol.md @@ -0,0 +1,58 @@ +# Platform Protocol (DPP) + +## 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. + +## Structure Descriptions + +### Data Contract + +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. Contracts are serialized to binary form using [CBOR](https://cbor.io/). + +> 📘 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. + +For additional detail, see the [Data Contract](../explanations/platform-protocol-data-contract.md) explanation. + +### Document + +A document is an atomic entity used by the platform to store user-submitted data. It resembles the documents stored in a [document-oriented DB](https://en.wikipedia.org/wiki/Document-oriented_database) (e.g. [MongoDB](https://www.mongodb.com/document-databases)). All documents must follow some specific rules that are defined by a generic document schema. Additionally, documents are always related to a particular application, so they must comply with the rules defined by the application’s data contract. Documents are submitted to the platform API ([DAPI](../explanations/dapi.md)) by clients during their use of the application. + +For additional detail, see the [Document](../explanations/platform-protocol-document.md) explanation. + +### State Transition + +A state transition represents a change made by a user to the application and platform states. It consists of: + +- Either: + - An array of documents, or + - One data contract +- The contract ID of the application to which the change is made +- The user's signature. + +The user signature is made for the binary representation of the state transition using a private key associated with an [identity](../explanations/identity.md). A state transition is constructed by a client-side library when the user creates documents and submits them to the platform API. + +For additional detail, see the [State Transition](../explanations/platform-protocol-state-transition.md) explanation. + +## Versions + +| Version | Information | +| :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.24 | See details in the [GitHub release](https://github.com/dashpay/platform/releases/tag/v0.24.0). | +| 0.23 | See details in the [GitHub release](https://github.com/dashevo/platform/releases/tag/v0.23.0). | +| 0.22 | See details in the [GitHub release](https://github.com/dashevo/platform/releases/tag/v0.22.0). | +| 0.21 | See details in the [GitHub release](https://github.com/dashevo/js-dpp/releases/tag/v0.21.0). | +| 0.20 | This release updated to a newer version of JSON Schema (2020-12 spec) and also switched to a new regex module ([Re2](https://github.com/google/re2)) for improved security. See more details in the [GitHub release](https://github.com/dashevo/js-dpp/releases/tag/v0.20.0). | + +```{toctree} +:maxdepth: 2 +:titlesonly: +:hidden: + +platform-protocol-data-contract +platform-protocol-state-transition +platform-protocol-document +platform-protocol-data-trigger +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..df2f31bcc --- /dev/null +++ b/docs/index.md @@ -0,0 +1,202 @@ +```{eval-rst} +.. _platform-index: +``` + +# Platform docs + +Welcome to the Dash Platform developer documentation. You'll find guides and documentation to help +you start working with Dash Platform and building decentralized applications based on the Dash +cryptocurrency. Let's jump right in! + +```{eval-rst} +.. grid:: 1 2 3 3 + + .. grid-item-card:: 💡 Introduction + :margin: 2 2 auto auto + :link-type: ref + :link: intro-index + + Background information about Dash + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 💻 Tutorials + :margin: 2 2 auto auto + :link-type: ref + :link: tutorials-intro + + Basics of building with Dash Platform + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 📑 Explanations + :margin: 2 2 auto auto + :link-type: ref + :link: explanations-dapi + + Descriptions of Dash Platform features + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 📚 Reference + :margin: 2 2 auto auto + :link-type: ref + :link: reference-dapi-endpoints + + API endpoint details and technical information + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 🔍 Platform Protocol Reference + :margin: 2 2 auto auto + :link-type: ref + :link: protocol-ref-overview + + Dash Platform protocol reference + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 📖 Resources + :margin: 2 2 auto auto + :link-type: ref + :link: resources-repository-overview + + Links to helpful sites and tools + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 🛠️ Dash SDK + :margin: 2 2 auto auto + :link-type: ref + :link: sdk-js-index + + JavaScript SDK documentation + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 🛠️ DAPI Client + :margin: 2 2 auto auto + :link-type: ref + :link: dapi-client-js-index + + JavaScript DAPI-Client documentation + + +++ + :ref:`Click to begin ` +``` + +```{toctree} +:maxdepth: 2 +:caption: Introduction +:hidden: + +intro/what-is-dash +intro/what-is-dash-platform +intro/to-testnet +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Tutorials +:hidden: + +tutorials/introduction +tutorials/connecting-to-testnet +tutorials/create-and-fund-a-wallet +tutorials/identities-and-names +tutorials/contracts-and-documents +tutorials/send-funds +tutorials/use-dapi-client-methods +tutorials/setup-a-node +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Explanations +:hidden: + +explanations/dapi +explanations/platform-protocol +explanations/identity +explanations/dpns +explanations/drive +explanations/platform-consensus +explanations/dashpay +explanations/fees +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Reference +:hidden: + +reference/dapi-endpoints +reference/query-syntax +reference/data-contracts +reference/glossary +reference/frequently-asked-questions +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Platform Protocol Reference +:hidden: + +protocol-ref/overview +protocol-ref/identity +protocol-ref/data-contract +protocol-ref/state-transition +protocol-ref/document +protocol-ref/data-trigger +protocol-ref/errors +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Resources +:hidden: + +resources/repository-overview +Testnet Block Explorer +Testnet Faucet +JavaScript SDK +resources/source-code +Previous Version of Docs +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Dash SDK +:hidden: + +sdk-js/overview +sdk-js/examples/examples +sdk-js/getting-started/getting-started +sdk-js/platform/platform +sdk-js/usage/usage +sdk-js/wallet/wallet +``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: DAPI Client +:hidden: + +dapi-client-js/overview +dapi-client-js/quick-start +dapi-client-js/usage/usage +``` diff --git a/docs/intro/to-testnet.md b/docs/intro/to-testnet.md new file mode 100644 index 000000000..b7b2241a8 --- /dev/null +++ b/docs/intro/to-testnet.md @@ -0,0 +1,26 @@ +# Intro to Testnet + +Testnet is the Dash testing network used for experimentation and evaluation of Dash Core and Dash Platform features. As a testing network, Testnet may be subject to occasional updates and changes that break backwards compatibility. + +## Network Details + +### Infrastructure + +Dash Core Group provides the core Testnet infrastructure consisting of 150 masternodes running Dash Core along with the platform services that provide the [decentralized API (DAPI)](../explanations/dapi.md) and [storage (Drive)](../explanations/drive.md) functionality. + +Testnet also includes a [block explorer](https://testnet-insight.dashevo.org/insight/) for the core blockchain and a [test Dash faucet](https://testnet-faucet.dash.org/) that dispenses funds to users/developers experimenting on the network. + +### Features + +The Dash Platform features available on testnet include: + +- [Dash Platform Name Service](../explanations/dpns.md) (DPNS): a data contract and supporting logic for name registration +- [Identities](../explanations/identity.md): creation of identities +- [Names](../explanations/dpns.md): creation of DPNS names that link to an identity +- [Data Contracts](../explanations/platform-protocol-data-contract.md): creation of data contracts +- [Documents](../explanations/platform-protocol-document.md): used to store/update/delete data associated with data contracts +- [DashPay](../explanations/dashpay.md): a data contract enableing a decentralized application that creates bidirectional direct settlement payment channels between identities and supports contact (name) based payments + +## Getting involved + +This network is open for all who are interested in testing and interacting with Dash Platform. To learn how to connect, please jump to the [Connecting to a Network tutorial](../tutorials/connecting-to-testnet.md). \ No newline at end of file diff --git a/docs/intro/what-is-dash-platform.md b/docs/intro/what-is-dash-platform.md new file mode 100644 index 000000000..14d28975f --- /dev/null +++ b/docs/intro/what-is-dash-platform.md @@ -0,0 +1,54 @@ +# What is Dash Platform + +Dash Platform is a [Web3](https://en.wikipedia.org/wiki/Web3) technology stack for building decentralized applications on the Dash network. The two main architectural components, [Drive](../explanations/drive.md) and [DAPI](../explanations/dapi.md), turn the Dash P2P network into a cloud that developers can integrate with their applications. + +## Key Advantages + +### Decentralized Cloud Storage + +Store your application data in the safest place on the Internet. All data stored on the Dash network is protected by Dash's consensus algorithm, ensuring data integrity and availability. + +### Reduced Data Silos + +Because your application data is stored across many nodes on the Dash network, it is safe and always available for customers, business partners, and investors. + +### Client Libraries + +Write code and integrate with Dash Platform using the languages that matter to your business. Don't worry about understanding blockchain infrastructure: a growing number of client libraries abstract away the complexity typically associated with working on blockchain-based networks. + +### Instant Data Confirmation + +Unlike many blockchain-based networks, data stored on the platform is instantly confirmed by the Dash consensus algorithm to ensure the best user experience for users. With Dash Platform, you can gain the advantages of a blockchain-based storage network without the usual UX compromises. + +```{eval-rst} +.. figure:: ../../img/join-community.svg + :class: no-scaled-link + :align: center + :width: 60% + :alt: Developer community image +``` + +## Key Components + +### DAPI - A decentralized API + +DAPI is a _decentralized_ HTTP API exposing [JSON-RPC](https://www.jsonrpc.org/) and [gRPC](https://grpc.io/) endpoints. Through these endpoints, developers can send and retrieve application data and query the Dash blockchain. + +DAPI provides developers the same access and security as running their own Dash node without the cost and maintenance overhead. Unlike traditional APIs which have a single point of failure, DAPI allows clients to connect to different instances depending on resource availability in the Dash network. + +Developers can connect to DAPI directly or use a client library. This initial client library, dapi-client, is a relatively simple API wrapper developed by Dash Core Group to provide function calls to the DAPI endpoints. + +The source for both DAPI and dapi-client are available on GitHub: + +- DAPI: +- DAPI-Client: + +### Drive - Decentralized Storage + +Drive is Dash Platform's storage component, allowing for consensus-based verification and validation of user-created data. In order for this to occur, developers create a [data contract](../explanations/platform-protocol-data-contract.md). This data contract describes the data structures that comprise an application, similar to creating a schema for a document-oriented database like MongoDB. + +Data created by users of the application is validated and verified against this contract. Upon successful validation/verification, application data is submitted to Drive (via DAPI), where it is stored on the masternode network. Drive uses Dash's purpose-built database, [GroveDB](https://github.com/dashevo/grovedb/), to provide efficient proofs with query responses, so you don't have to trust the API provider to be certain your data is authentic. + +The source is available on GitHub: + +- Drive: \ No newline at end of file diff --git a/docs/intro/what-is-dash.md b/docs/intro/what-is-dash.md new file mode 100644 index 000000000..2f28f2189 --- /dev/null +++ b/docs/intro/what-is-dash.md @@ -0,0 +1,52 @@ +```{eval-rst} +.. _intro-index: +``` + +# What is Dash + +Dash is the world's first and longest-running [DAO](https://www.investopedia.com/tech/what-dao/), a cryptocurrency that has stood the test of time, a truly decentralized and open source project built without a premine, [ICO](https://www.investopedia.com/terms/i/initial-coin-offering-ico.asp), or venture capital investment. Dash is the only solution on the market today developing a decentralized API as an integral part of its [Web3](https://en.wikipedia.org/wiki/Web3) stack, making it the first choice for developers creating unstoppable apps. + +Dash is built on battle-tested technology including Bitcoin and Cosmos Tendermint, and implements cutting-edge threshold signing features on masternodes to guarantee transaction finality in little more than a second. Dash is fast, private, secure, decentralized, and open-source, your first choice for truly decentralized Web3 services and for earning yield in return for providing infrastructure services. + +## Key Advantages + +### Industry Leading Security + +The Dash network is the most secure blockchain-based payments network, thanks to technological innovations such as [ChainLocks](#chainlocks). This mitigates the risk of 51% attacks, forcing any would-be malicious actor to successfully attack both the mining layer and the [masternode](#masternodes) layer. To attack both layers, a malicious actor would have to spend a large amount of Dash in order to dictate false entries to the blockchain, thereby raising the price of Dash in the process. Therefore, a successful attack would be cost prohibitive due to the large percentage of Dash's total market required to attempt it. + +### Stable and Long Lasting Governance + +The Dash [decentralized autonomous organization (DAO)](../reference/glossary.md#decentralized-autonomous-organization-dao) is the oldest and most successful example of decentralized governance. In that regard, one of Dash's most notable innovations is the creation of a treasury, which funds project proposals that advance the Dash network and ecosystem. This treasury is funded by 10% of the block reward, which is a combination of transaction fees collected on the network and newly minted Dash awarded to miners for securing the blockchain. Nodes that maintain a minimum of 1000 Dash ([masternodes](#masternodes)) receive voting rights on how to distribute treasury funds. Voting on project proposals encourages engagement with the overall network and ecosystem, resulting in numerous projects being funded that advance Dash in terms of technology development, marketing, and business development. + +### Established History of Technological Innovation + +Most of Dash's technical innovations are described in greater detail elsewhere in this developer hub. However, its record speaks for itself with innovations in governance ([masternodes](https://docs.dash.org/en/stable/introduction/features.html#masternodes), [treasury system](https://docs.dash.org/en/stable/introduction/features.html#decentralized-governance)), security ([ChainLocks](https://docs.dash.org/en/stable/introduction/features.html#chainlocks)), usability (automatic [InstantSend](https://docs.dash.org/en/stable/introduction/features.html#instantsend)), and scalability ([long-living masternode quorums](../reference/glossary.md#long-living-masternode-quorum-llmq)). + +### Instantly Confirmed Transactions + +All transactions are automatically sent and received instantly at no extra cost. Transaction security and decentralization are not compromised, due to the ChainLocks innovation. As a result, using Dash to transact means getting the speed and fungibility of fiat currency, while simultaneously having the lower costs, privacy, and security of funds of a blockchain-based network. + +## Key Features +### Masternodes + +The most important differentiating feature of the Dash payments network is the concept of a **masternode**. On a traditional p2p network, nodes participate equally in the sharing of data and network resources. These nodes are all compensated equally for their contributions toward preserving the network. + +However, the Dash network has a second layer of network participants that provide enhanced functionality in exchange for greater compensation. This second layer of masternodes is the reason why Dash is the most secure payments network, and can provide industry-leading features such as instant transaction settlement and usernames. + +### Long-Living Masternode Quorums + +Dash's [long-living masternode quorums](https://docs.dash.org/projects/core/en/stable/docs/guide/dash-features-masternode-quorums.html) (LLMQs) are used to facilitate the operation of masternode-provided features in a decentralized, deterministic way. These LLMQs are deterministic subsets of the overall masternode list that are formed via a [distributed key generation](../reference/glossary.md#distributed-key-generation-dkg) protocol and remain active for long periods of time (e.g. hours to days). The main task of LLMQs is to perform threshold signing of consensus-related messages for features like InstantSend and ChainLocks. + +### InstantSend + +InstantSend provides a way to lock transaction inputs and enable secure, instantaneous transactions. Long-living masternode quorums check whether or not a submitted transaction is valid. If it is valid, the masternodes “lock” the inputs to that specific transaction and broadcast this information to the network, effectively promising that the transaction will be included in subsequently mined blocks and not allowing any other transaction to spend any of the locked inputs. + +### ChainLocks + +ChainLocks are a feature provided by the Dash Network which provides certainty when accepting payments. This technology, particularly when used in parallel with InstantSend, creates an environment in which payments can be accepted immediately and without the risk of “Blockchain Reorganization Events”. + +The risk of blockchain reorganization is typically addressed by requiring multiple “confirmations” before a transaction can be safely accepted as payment. This type of indirect security is effective, but at a cost of time and user experience. ChainLocks are a solution for this problem. + +### Proof-of-Service + +The Proof of Service (PoSe) scoring system helps incentivize masternodes to provide network services. Masternodes that fail to participate in quorums that provide core services are penalized, which eventually results in them being excluded from masternode payment eligibility. \ No newline at end of file diff --git a/docs/other/incentives.md b/docs/other/incentives.md new file mode 100644 index 000000000..9dde7d887 --- /dev/null +++ b/docs/other/incentives.md @@ -0,0 +1,29 @@ +# Overview + +In a decentralized network, there is no authority directing each part of the system to do its work. Because of this, it's important to plan the system so that each participant benefits only by contributing in a way that helps the network. The major participants in Dash Platform are two of the three participants in Dash Core: + +**Users:** new services that are part of Dash Platform give users capabilities they didn't have before. + +**DAPI (Masternodes):** Masternodes operate a public API which receives platform data requests and alterations. They must have the resources to respond quickly and consistently. + +**Miners:** Masternode data is hashed to a separate blockchain (the [platform chain](../explanations/drive-platform-chain.md)) operated just by the masternodes, so miners' only contribution to Dash Platform is to store transactions from users converting Dash to credits, or from masternodes converting credits back to Dash. + +In general, masternodes and miners are incentivized to perform this work by fees that the users pay as they use Dash Platform. In some cases, such as new user creation, someone else may pay the fee for the user. This may be expanded in the future to allow organizations to pay for their own users' platform activity. + +# Details + +## Fees + +Dash Platform collects fees for three activities: + +* [Registering a new identity](../tutorials/identities-and-names/register-an-identity.md) +* [Registering a Data Contract](../tutorials/contracts-and-documents/submit-documents.md) +* [Updating Application Data](tutorial-submit-a-state-transition) + +New users may not have any Dash of their own, so when registering an identity, some Dash is converted into _credits_, which is Dash that can only be spent on Platform activity. Users can also convert Dash into credits after registration as needed. + +Dash Platform fees go to the masternodes, but how they are distributed is not yet finalized. The fees for registering a new identity, registering a data contract, and submitting a state transition, mainly exist today to reduce frivolous use of the platform. In the future when block rewards have decreased, fees may become the main source of compensation for the work Masternodes do storing and processing these activities. + +## Attacks + +Another kind of incentive which must be considered is the incentive to cheat. If there is a way that a participant can harm the network to improve their own situation, someone will do it. For example, if the fees from state transitions always went to the next masternode in line for a block payout, that masternode would be able to spam large, expensive state transitions, knowing that they would be getting their money back almost immediately. These kind of incentives guide and constrain all aspects of decentralized systems like Dash. \ No newline at end of file diff --git a/docs/other/key-concepts.md b/docs/other/key-concepts.md new file mode 100644 index 000000000..9f05ee411 --- /dev/null +++ b/docs/other/key-concepts.md @@ -0,0 +1,107 @@ +In order to successfully develop a Dash Platform Application, developers will need to know how to communicate their data infrastructure to the Dash network, structure their application data, interact with usernames, and pay for various data operations. + +# Operation Costs + +In any decentralized network, nodes are compensated for the activities they undertake to maintain the network. Consequently, any action taken by an application to store, retrieve, or manipulate data involves a cost that will be paid to the masternodes. Sometimes this cost will be the same as a traditional currency exchange on the Dash network ( < $0.01 USD), and sometimes this cost will be slightly higher as a result of the quantity of data being stored or retrieved. + +In order to pay for these various operations, Dash must be spent by either the application administrator or user. Obviously, this represents a paradigm shift for how most consumers interact with an application. Therefore, managing the payment of various data operations is a matter of choice for the developer, by choosing to sponsor costs on behalf of a user or by passing the cost of the data operation onto the user. + +# 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/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) is included below: + +```json +{ + "domain": { + "indices": [ + { + "properties": [ + { "$userId": "asc" }, + { "nameHash": "asc" } + ], + "unique": true + } + ], + "properties": { + "nameHash": { + "type": "string", + "minLength": 1 + }, + "label": { + "type": "string", + "pattern": "^((?!-)[a-zA-Z0-9-]{0,62}[a-zA-Z0-9])$" + }, + "normalizedLabel": { + "type": "string", + "pattern": "^((?!-)[a-z0-9-]{0,62}[a-z0-9])$" + }, + "normalizedParentDomainName": { + "type": "string", + "minLength": 1 + }, + "preorderSalt": { + "type": "string", + "minLength": 1 + }, + "records": { + "type": "object", + "properties": { + "dashIdentity": { + "type": "string", + "minLength": 64, + "maxLength": 64 + } + }, + "minProperties": 1, + "additionalProperties": false + } + }, + "required": [ + "nameHash", + "label", + "normalizedLabel", + "normalizedParentDomainName", + "preorderSalt", + "records" + ], + "additionalProperties": false + }, + "preorder": { + "indices": [ + { + "properties": [ + { "$userId": "asc" }, + { "saltedDomainHash": "asc" } + ], + "unique": true + } + ], + "properties": { + "saltedDomainHash": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "saltedDomainHash" + ], + "additionalProperties": false + } +} +``` +As your application evolves, changes to your data contract might be required. Consequently, data contracts can be versioned in order to prevent breaking changes in your application. + +# State Transitions + +At any given point in time, your application has a specific state regarding the type and content of its data. Whenever you create, update, or delete data, your application undergoes a state transition. Data is stored on Dash Platform when an application submits a state transition to the Dash network. This state transition is a JSON-formatted object that corresponds to the structure defined in the application’s data contract. + +Based on the validation rules described in the data contract, Dash Platform will validate and either accept or reject a state transition based on the previously defined criteria. + + +# Identities and Names + +A major feature of Dash Platform is the ability to associate users with human-readable usernames, which has been notoriously difficult to implement in decentralized systems. In order to work with usernames in a Dash Platform application, it is important to understand the difference between identities and usernames. + +Identities are unique identifiers that are stored on the Dash blockchain. It is important to understand that identities represent the core identifier for an individual, business, or application. In that regard, identities in the Dash network are analogous to DNA. Two individuals might share the same name, but their core identities will still be different. + +Usernames are human-readable names that are stored in Dash Platform Name Service, a Dash Platform application. The application takes an identity stored on the Dash blockchain and resolves that identifier to a username, similar to how DNS works for a website URL and its corresponding IP address. Usernames are an attribute of an identity, which is why they are architecturally separate from identity and stored in a Dash Platform application. This separation allows for a decentralized identity ecosystem to develop around the Dash network. \ No newline at end of file diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md new file mode 100644 index 000000000..ed430eccc --- /dev/null +++ b/docs/protocol-ref/data-contract.md @@ -0,0 +1,676 @@ +# Data Contract + +## Data Contract Overview + +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: [documents](#data-contract-documents) and [definitions](#data-contract-definitions). All data contracts must define one or more documents, whereas definitions are optional and may not be used for simple contracts. + +### General Constraints + +There are a variety of constraints currently defined for performance and security reasons. The following constraints are applicable to all aspects of data contracts. Unless otherwise noted, these constraints are defined in the platform's JSON Schema rules (e.g. [rs-dpp data contract meta schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json)). + +#### Keyword + +> 🚧 +> +> The `$ref` keyword has been [disabled](https://github.com/dashevo/platform/pull/300) since Platform v0.22. + +| Keyword | Constraint | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `default` | Restricted - cannot be used (defined in DPP logic) | +| `propertyNames` | Restricted - cannot be used (defined in DPP logic) | +| `uniqueItems: true` | `maxItems` must be defined (maximum: 100000) | +| `pattern: ` | `maxLength` must be defined (maximum: 50000) | +| `format: ` | `maxLength` must be defined (maximum: 50000) | +| `$ref: ` | **Temporarily disabled**
`$ref` can only reference `$defs` -
remote references not supported | +| `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` | Disabled for data contracts | +| `dependencies` | Not supported. Use `dependentRequired` and `dependentSchema` instead | +| `additionalItems` | Not supported. Use `items: false` and `prefixItems` instead | +| `patternProperties` | Restricted - cannot be used for data contracts | +| `pattern` | Accept only [RE2](https://github.com/google/re2/wiki/Syntax) compatible regular expressions (defined in DPP logic) | + +#### Data Size + +**Note:** These constraints are defined in the Dash Platform Protocol logic (not in JSON Schema). + +All serialized data (including state transitions) is limited to a maximum size of [16 KB](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/util/serializer.rs#L8). + +#### Additional Properties + +Although JSON Schema allows additional, undefined properties [by default](https://json-schema.org/understanding-json-schema/reference/object.html?#properties), they are not allowed in Dash Platform data contracts. Data contract validation will fail if they are not explicitly forbidden using the `additionalProperties` keyword anywhere `properties` are defined (including within document properties of type `object`). + +Include the following at the same level as the `properties` keyword to ensure proper validation: + +```json +"additionalProperties": false +``` + +## Data Contract Object + +The data contract object consists of the following fields as defined in the JavaScript reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json)): + +| Property | Type | Required | Description | +| --------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | Yes | The platform protocol version ([currently `1`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/version/mod.rs#L9)) | +| $schema | string | Yes | A valid URL (default: ) | +| $id | array of bytes | Yes | Contract ID generated from `ownerId` and entropy ([32 bytes; content media type: `application/x.dash.dpp.identifier`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L378-L384)) | +| version | integer | Yes | The data contract version | +| ownerId | array of bytes | Yes | [Identity](../protocol-ref/identity.md) that registered the data contract defining the document ([32 bytes; content media type: `application/x.dash.dpp.identifier`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L389-L395) | +| documents | object | Yes | Document definitions (see [Documents](#data-contract-documents) for details) | +| $defs | object | No | Definitions for `$ref` references used in the `documents` object (if present, must be a non-empty object with \<= 100 valid properties) | + +### Data Contract Schema + +Details regarding the data contract object may be found in the [rs-dpp data contract meta schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json). A truncated version is shown below for reference: + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "type": "object", + "$defs": { + // Truncated ... + }, + "properties": { + "protocolVersion": { + "type": "integer", + "minimum": 0, + "$comment": "Maximum is the latest protocol version" + }, + "$schema": { + "type": "string", + "const": "https://schema.dash.org/dpp-0-4-0/meta/data-contract" + }, + "$id": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "version": { + "type": "integer", + "minimum": 1 + }, + "ownerId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "documents": { + "type": "object", + "propertyNames": { + "pattern": "^[a-zA-Z0-9-_]{1,64}$" + }, + "additionalProperties": { + "type": "object", + "allOf": [ + { + "properties": { + "indices": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 32 + }, + "properties": { + "type": "array", + "items": { + "type": "object", + "propertyNames": { + "maxLength": 256 + }, + "additionalProperties": { + "type": "string", + "enum": [ + "asc" + ] + }, + "minProperties": 1, + "maxProperties": 1 + }, + "minItems": 1, + "maxItems": 10 + }, + "unique": { + "type": "boolean" + } + }, + "required": [ + "properties", + "name" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 10 + }, + "type": { + "const": "object" + }, + "signatureSecurityLevelRequirement": { + "type": "integer", + "enum": [ + 0, + 1, + 2, + 3 + ], + "description": "Public key security level. 0 - Master, 1 - Critical, 2 - High, 3 - Medium. If none specified, High level is used" + } + } + }, + { + "$ref": "#/$defs/documentSchema" + } + ], + "unevaluatedProperties": false + }, + "minProperties": 1, + "maxProperties": 100 + }, + "$defs": { + "$ref": "#/$defs/documentProperties" + } + }, + "required": [ + "protocolVersion", + "$schema", + "$id", + "version", + "ownerId", + "documents" + ], + "additionalProperties": false +} +``` + +**Example** + +```json +{ + "id": "AoDzJxWSb1gUi2dSmvFeUFpSsjZQRJaqCpn7vCLkwwJj", + "ownerId": "7NUbPf231ixt1kVBQsBvSMMBxd7AgPad8KtdtfFGhXDP", + "schema": "https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "documents": { + "note": { + "properties": { + "message": { + "type": "string" + } + }, + "additionalProperties": false + } + } +} +``` + +### Data Contract id + +The data contract `$id` is a hash of the `ownerId` and entropy as shown [here](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/generate_data_contract.rs). + +```rust +// From the Rust reference implementation (rs-dpp) +// generate_data_contract.rs +/// Generate data contract id based on owner id and entropy +pub fn generate_data_contract_id(owner_id: impl AsRef<[u8]>, entropy: impl AsRef<[u8]>) -> Vec { + let mut b: Vec = vec![]; + let _ = b.write(owner_id.as_ref()); + let _ = b.write(entropy.as_ref()); + hash(b) +} +``` + +### Data Contract version + +The data contract `version` is an integer representing the current version of the contract. This +property must be incremented if the contract is updated. + +### Data Contract Documents + +The `documents` object defines each type of document required by the data contract. At a minimum, a document must consist of 1 or more properties. Documents may also define [indices](#document-indices) and a list of [required properties](#required-properties-optional). The `additionalProperties` properties keyword must be included as described in the [constraints](#additional-properties) section. + +The following example shows a minimal `documents` object defining a single document (`note`) that has one property (`message`). + +```json +{ + "note": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "additionalProperties": false + } +} +``` + +#### Document Properties + +The `properties` object defines each field that will be used by a document. Each field consists of an object that, at a minimum, must define its data `type` (`string`, `number`, `integer`, `boolean`, `array`, `object`). Fields may also apply a variety of optional JSON Schema constraints related to the format, range, length, etc. of the data. + +**Note:** The `object` type is required to have properties defined either directly or via the data contract's [$defs](#data-contract-definitions). For example, the body property shown below is an object containing a single string property (objectProperty): + +```javascript +const contractDocuments = { + message: { + "type": "object", + properties: { + body: { + type: "object", + properties: { + objectProperty: { + type: "string" + }, + }, + additionalProperties: false, + }, + header: { + type: "string" + } + }, + additionalProperties: false + } +}; +``` + +**Note:** A full explanation of the capabilities of JSON Schema is beyond the scope of this document. For more information regarding its data types and the constraints that can be applied, please refer to the [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference/index.html) documentation. + +##### Property Constraints + +There are a variety of constraints currently defined for performance and security reasons. + +| Description | Value | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L22) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L23) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L20) (Note: minimum length was 3 prior to v0.23) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L20) | +| Property name characters | Alphanumeric (`A-Z`, `a-z`, `0-9`)
Hyphen (`-`)
Underscore (`_`) | + +Prior to Dash Platform v0.23 there were stricter limitations on minimum property name length and the characters that could be used in property names. + +##### Required Properties (Optional) + +Each document may have some fields that are required for the document to be valid and other fields that are optional. Required fields are defined via the `required` array which consists of a list of the field names from the document that must be present. The `required` object should be excluded for documents without any required properties. + +```json +"required": [ + "", + "" +] +``` + +**Example** +The following example (excerpt from the DPNS contract's `domain` document) demonstrates a document that has 6 required fields: + +```json +"required": [ + "label", + "normalizedLabel", + "normalizedParentDomainName", + "preorderSalt", + "records", + "subdomainRules" +] +``` + +#### Document Indices + +Document indices may be defined if indexing on document fields is required. + +**Note:** Dash Platform v0.23 only allows [ascending default ordering](https://github.com/dashpay/platform/pull/435) for indices. + +The `indices` array consists of: + +- One or more objects that each contain: + - A unique `name` for the index + - A `properties` array composed of a `` object for each document field that is part of the index (sort order: `asc` only for Dash Platform v0.23) + - An (optional) `unique` element that determines if duplicate values are allowed for the document type + +**Note:** + +- The `indices` object should be excluded for documents that do not require indices. +- When defining an index with multiple properties (i.e a compound index), the order in which the properties are listed is important. Refer to the [mongoDB documentation](https://docs.mongodb.com/manual/core/index-compound/#prefixes) for details regarding the significance of the order as it relates to querying capabilities. Dash uses [GroveDB](https://github.com/dashevo/grovedb) which works similarly but does requiring listing _all_ the index's fields in query order by statements. + +```json +"indices": [ + { + "name": "Index1", + "properties": [ + { "": "asc" }, + { "": "asc" } + ], + "unique": true|false + }, + { + "name": "Index2", + "properties": [ + { "": "asc" }, + ], + } +] +``` + +##### Index Constraints + +For performance and security reasons, indices have the following constraints. These constraints are subject to change over time. + +| Description | Value | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L413) / [32](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L414) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L446) | +| Maximum number of unique indices | [3](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L40) | +| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L433) | +| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L39) | +| **Note: Dash Platform v0.22+. [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225)**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L43) | +| **Note: Dash Platform v0.22+. [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225)**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L44) | +| Usage of `$id` in an index [disallowed](https://github.com/dashpay/platform/pull/178) | N/A | + +**Example** +The following example (excerpt from the DPNS contract's `preorder` document) creates an index named `saltedHash` on the `saltedDomainHash` property that also enforces uniqueness across all documents of that type: + +```json +"indices": [ + { + "name": "saltedHash", + "properties": [ + { + "saltedDomainHash": "asc" + } + ], + "unique": true + } +] +``` + +#### Full Document Syntax + +This example syntax shows the structure of a documents object that defines two documents, an index, and a required field. + +```json +{ + "": { + "type": "object", + "properties": { + "": { + "type": "" + }, + "": { + "type": "" + }, + }, + "indices": [ + { + "name": "", + "properties": [ + { + "": "asc" + } + ], + "unique": true|false + }, + ], + "required": [ + "" + ] + "additionalProperties": false + }, + "": { + "type": "object", + "properties": { + "": { + "type": "" + }, + "": { + "type": "" + }, + }, + "additionalProperties": false + }, +} +``` + +#### Document Schema + +Full document schema details may be found in this section of the [rs-dpp data contract meta schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L368-L471). + +### Data Contract Definitions + +> ❗️ Definitions are currently unavailable + +The optional `$defs` object enables definition of aspects of a schema that are used in multiple places. This is done using the JSON Schema support for [reuse](https://json-schema.org/understanding-json-schema/structuring.html#defs). Items defined in `$defs` may then be referenced when defining `documents` through use of the `$ref` keyword. + +**Note:** + +- Properties defined in the `$defs` object must meet the same criteria as those defined in the `documents` object (e.g. the `additionalProperties` properties keyword must be included as described in the [constraints](#additional-properties) section). +- Data contracts can only use the `$ref` keyword to reference their own `$defs`. Referencing external definitions is not supported by the platform protocol. + +**Example** +The following example shows a definition for a `message` object consisting of two properties: + +```json +{ + // Preceding content truncated ... + "$defs": { + "message": { + "type": "object", + "properties": { + "timestamp": { + "type": "number" + }, + "description": { + "type": "string" + } + }, + "additionalProperties": false + } + } +} +``` + +## Data Contract State Transition Details + +There are two data contract-related state transitions: [data contract create](#data-contract-creation) and [data contract update](#data-contract-update). Details are provided in this section. + +### Data Contract Creation + +Data contracts are created on the platform by submitting the [data contract object](#data-contract-object) in a data contract create state transition consisting of: + +| Field | Type | Description | +| -------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | The platform protocol version ([currently `1`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/version/mod.rs#L9)) | +| type | integer | State transition type (`0` for data contract create) | +| dataContract | [data contract object](#data-contract-object) | Object containing the data contract details | +| entropy | array of bytes | Entropy used to generate the data contract ID. Generated as [shown here](../protocol-ref/state-transition.md#entropy-generation). (32 bytes) | +| signaturePublicKeyId | number | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition | +| signature | array of bytes | Signature of state transition data (65 or 96 bytes) | + +Each data contract state transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/stateTransition/dataContractCreate.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 0 + }, + "dataContract": { + "type": "object" + }, + "entropy": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32 + }, + "signaturePublicKeyId": { + "type": "integer", + "minimum": 0 + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 96 + } + }, + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "dataContract", + "entropy", + "signaturePublicKeyId", + "signature" + ] +} +``` + +**Example State Transition** + +```json +{ + "protocolVersion":1, + "type":0, + "signature":"IFmEb/OwyYG0yn33U4/kieH4JL63Ft25GAun+XqWOalkbDrpL9z+OH+Sb03xsyMNzoILC2T1Q8yV1q7kCmr0HuQ=", + "signaturePublicKeyId":0, + "dataContract":{ + "protocolVersion":1, + "$id":"44dvUnSdVtvPPeVy6mS4vRzJ4zfABCt33VvqTWMM8VG6", + "$schema":"https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "version":1, + "ownerId":"6YfP6tT9AK8HPVXMK7CQrhpc8VMg7frjEnXinSPvUmZC", + "documents":{ + "note":{ + "type":"object", + "properties":{ + "message":{ + "type":"string" + } + }, + "additionalProperties":false + } + } + }, + "entropy":"J2Sl/Ka9T1paYUv6f2ec5MzaaACs9lcUvOskBU0SMlo=" +} +``` + +### Data Contract Update + +Existing data contracts can be updated in certain backwards-compatible ways. The following aspects +of a data contract can be updated: + +- Adding a new document +- Adding a new optional property to an existing document +- Adding non-unique indices for properties added in the update + +Data contracts are updated on the platform by submitting the modified [data contract +object](#data-contract-object) in a data contract update state transition consisting of: + +| Field | Type | Description | +| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | The platform protocol version ([currently `1`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/version/mod.rs#L9)) | +| type | integer | State transition type (`4` for data contract update) | +| dataContract | [data contract object](#data-contract-object) | Object containing the updated data contract details
**Note:** the data contract's [`version` property](#data-contract-version) must be incremented with each update | +| signaturePublicKeyId | number | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition | +| signature | array of bytes | Signature of state transition data (65 or 96 bytes) | + +Each data contract state transition must comply with this JSON-Schema definition established in +[rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/stateTransition/dataContractUpdate.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 4 + }, + "dataContract": { + "type": "object" + }, + "signaturePublicKeyId": { + "type": "integer", + "minimum": 0 + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 96 + } + }, + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "dataContract", + "signaturePublicKeyId", + "signature" + ] +} +``` + +**Example State Transition** + +```json +{ + "protocolVersion":1, + "type":4, + "signature":"IBboAbqbGBiWzyJDyhwzs1GujR6Gb4m5Gt/QCugLV2EYcsBaQKTM/Stq7iyIm2YyqkV8VlWqOfGebW2w5Pjnfak=", + "signaturePublicKeyId":0, + "dataContract":{ + "protocolVersion":1, + "$id":"44dvUnSdVtvPPeVy6mS4vRzJ4zfABCt33VvqTWMM8VG6", + "$schema":"https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "version":2, + "ownerId":"6YfP6tT9AK8HPVXMK7CQrhpc8VMg7frjEnXinSPvUmZC", + "documents":{ + "note":{ + "type":"object", + "properties":{ + "message":{ + "type":"string" + }, + "author":{ + "type":"string" + } + }, + "additionalProperties":false + } + } + } +} +``` + +### Data Contract State Transition Signing + +Data contract state transitions must be signed by a private key associated with the contract owner's identity. + +The process to sign a data contract state transition consists of the following steps: + +1. Canonical CBOR encode the state transition data - this include all ST fields except the `signature` and `signaturePublicKeyId` +2. Sign the encoded data with a private key associated with the `ownerId` +3. Set the state transition `signature` to the value of the signature created in the previous step +4. Set the state transition`signaturePublicKeyId` to the [public key `id`](../protocol-ref/identity.md#public-key-id) corresponding to the key used to sign \ No newline at end of file diff --git a/docs/protocol-ref/data-trigger.md b/docs/protocol-ref/data-trigger.md new file mode 100644 index 000000000..e5d75e222 --- /dev/null +++ b/docs/protocol-ref/data-trigger.md @@ -0,0 +1,43 @@ +# Data Trigger + +## Data Trigger Overview + +Although [data contracts](../protocol-ref/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 (DPP) supports this application-specific custom logic using Data Triggers. + +## 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 transition action](../protocol-ref/document.md#document-transition-action) so separate triggers can be created for the CREATE, REPLACE, or DELETE actions. + +When document state transitions are received, DPP checks if there is a trigger associated with the document transition type and action. If there is, it then executes the trigger logic. + +**Note:** Successful execution of the trigger logic is necessary for the document to be accepted and applied to the platform state. + +### Example + +As an example, DPP contains several data triggers for DPNS as defined in the [data triggers factory](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_trigger/get_data_triggers_factory.rs). The `domain` document has added constraints for creation. All DPNS document types have constraints on replacing or deleting: + +| Data Contract | Document | Action(s) | Trigger Description | +| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | +| DPNS | `domain` | [`CREATE`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/lib/dataTrigger/dpnsTriggers/createDomainDataTrigger.js) | Enforces DNS compatibility, validates provided hashes, and restricts top-level domain (TLD) registration | +| ---- | ---- | ---- | ---- | +| DPNS | All Document Types | [`REPLACE`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_trigger/reject_data_trigger.rs) | Prevents updates to existing documents | +| DPNS | All Document Types | [`DELETE`](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_trigger/reject_data_trigger.rs) | Prevents deletion of existing documents | + +**DPNS Trigger Constraints** + +The following table details the DPNS constraints applied via data triggers. These constraints are in addition to the ones applied directly by the DPNS data contract. + +| Document | Action | Constraint | +| ---------- | --------- | ----------------------------------------------------------------------------------------------------------- | +| `domain` | `CREATE` | Full domain length \<= 253 characters | +| `domain` | `CREATE` | `normalizedLabel` matches lowercase `label` | +| `domain` | `CREATE` | `ownerId` matches `records.dashUniqueIdentityId` or `dashAliasIdentityId` (whichever one is present) | +| `domain` | `CREATE` | Only creating a top-level domain with an authorized identity | +| `domain` | `CREATE` | Referenced `normalizedParentDomainName` must be an existing parent domain | +| `domain` | `CREATE` | Subdomain registration for non top level domains prevented if `subdomainRules.allowSubdomains` is true | +| `domain` | `CREATE` | Subdomain registration only allowed by the parent domain owner if `subdomainRules.allowSubdomains` is false | +| `domain` | `CREATE` | Referenced `preorder` document must exist | +| `domain` | `REPLACE` | Action not allowed | +| `domain` | `DELETE` | Action not allowed | +| `preorder` | `REPLACE` | Action not allowed | +| `preorder` | `DELETE` | Action not allowed | \ No newline at end of file diff --git a/docs/protocol-ref/document.md b/docs/protocol-ref/document.md new file mode 100644 index 000000000..8f256237e --- /dev/null +++ b/docs/protocol-ref/document.md @@ -0,0 +1,386 @@ +# Document + +## Document Submission + +Documents are sent to the platform by submitting the them in a document batch state transition consisting of: + +| Field | Type | Description| +| - | - | - | +| protocolVersion | integer | The platform protocol version (currently `1`) | +| type | integer | State transition type (`1` for document batch) | +| ownerId | array | [Identity](../protocol-ref/identity.md) submitting the document(s) (32 bytes) | +| transitions | array of transition objects | Document `create`, `replace`, or `delete` transitions (up to 10 objects) | +| signaturePublicKeyId | number | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition | +| signature | array | Signature of state transition data (65 or 96 bytes) | + +Each document batch state transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentsBatch.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 1 + }, + "ownerId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "transitions": { + "type": "array", + "items": { + "type": "object" + }, + "minItems": 1, + "maxItems": 10 + }, + "signaturePublicKeyId": { + "type": "integer", + "minimum": 0 + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 96 + } + }, + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "ownerId", + "transitions", + "signaturePublicKeyId", + "signature" + ] +} +``` + +### Document Base Transition + +All document transitions in a document batch state transition are built on the base schema and include the following fields: + +| Field | Type | Description| +| - | - | - | +| $id | array | The [document ID](#document-id) (32 bytes)| +| $type | string | Name of a document type found in the data contract associated with the `dataContractId` (1-64 characters) | +| $action | array of integers | [Action](#document-transition-action) the platform should take for the associated document | +| $dataContractId | array | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` (32 bytes) | + +Each document transition must comply with the document transition [base schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/base.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "$id": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "$type": { + "type": "string" + }, + "$action": { + "type": "integer", + "enum": [0, 1, 3] + }, + "$dataContractId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + } + }, + "required": [ + "$id", + "$type", + "$action", + "$dataContractId" + ], + "additionalProperties": false +} +``` + +#### Document id + +The document `$id` is created by hashing the document's `dataContractId`, `ownerId`, `type`, and `entropy` as shown in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/document/generate_document_id.rs). + +```rust +// From the Rust reference implementation (rs-dpp) +// generate_document_id.rs +pub fn generate_document_id( + contract_id: &Identifier, + owner_id: &Identifier, + document_type: &str, + entropy: &[u8], +) -> Identifier { + let mut buf: Vec = vec![]; + + buf.extend_from_slice(&contract_id.to_buffer()); + buf.extend_from_slice(&owner_id.to_buffer()); + buf.extend_from_slice(document_type.as_bytes()); + buf.extend_from_slice(entropy); + + Identifier::from_bytes(&hash(&buf)).unwrap() +} +``` + +#### Document Transition Action + +| Action | Name | Description | +| :-: | - | - | +| 0 | Create | Create a new document with the provided data | +| 1 | Replace | Replace an existing document with the provided data | +| 2 | `RESERVED` | Unused action | +| 3 | Delete | Delete the referenced document | + +### Document Create Transition + +The document create transition extends the base schema to include the following additional fields: + +| Field | Type | Description| +| - | - | - | +| $entropy | array | Entropy used in creating the [document ID](#document-id). Generated as [shown here](../protocol-ref/state-transition.md#entropy-generation). (32 bytes) | +| $createdAt | integer | (Optional) | Time (in milliseconds) the document was created | +| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | + +Each document create transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/create.json) (in addition to the document transition [base schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/base.json)) that is required for all document transitions): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "$entropy": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32 + }, + "$createdAt": { + "type": "integer", + "minimum": 0 + }, + "$updatedAt": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "$entropy" + ], + "additionalProperties": false +} +``` + +**Note:** The document create transition must also include all required properties of the document as defined in the data contract. + +The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-submission): + +```json +{ + "$action": 0, + "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8", + "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP", + "$type": "note", + "$entropy": "yfo6LnZfJ5koT2YUwtd8PdJa8SXzfQMVDz", + "message": "Tutorial Test @ Mon, 27 Apr 2020 20:23:35 GMT" +} +``` + +| Field | Required By | +| - | - | +| $action | Document [base transition](#document-base-transition) | +| $dataContractId | Document [base transition](#document-base-transition) | +| $id | Document [base transition](#document-base-transition) | +| $type | Document [base transition](#document-base-transition) | +| $entropy | Document [create transition](#document-create-transition) | +| message | Data Contract (the `message` document defined in the referenced data contract -`5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8`) | + +### Document Replace Transition + +The document replace transition extends the base schema to include the following additional fields: + +| Field | Type | Description| +| - | - | - | +| $revision | integer | Document revision (=> 1) | +| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | + +Each document replace transition must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/replace.json) (in addition to the document transition [base schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/document/stateTransition/documentTransition/base.json)) that is required for all document transitions): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "$revision": { + "type": "integer", + "minimum": 1 + }, + "$updatedAt": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "$revision" + ], + "additionalProperties": false +} +``` + +**Note:** The document create transition must also include all required properties of the document as defined in the data contract. + +The following example document create transition and subsequent table demonstrate how the document transition base, document create transition, and data contract document definitions are assembled into a complete transition for inclusion in a [state transition](#document-submission): + +```json +{ + "$action": 1, + "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8", + "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP", + "$type": "note", + "$revision": 1, + "message": "Tutorial Test @ Mon, 27 Apr 2020 20:23:35 GMT" +} +``` + +| Field | Required By | +| - | - | +| $action | Document [base transition](#document-base-transition) | +| $dataContractId | Document [base transition](#document-base-transition) | +| $id | Document [base transition](#document-base-transition) | +| $type | Document [base transition](#document-base-transition) | +| $revision | Document revision | +| message | Data Contract (the `message` document defined in the referenced data contract -`5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8`) | + +### Document Delete Transition + +The document delete transition only requires the fields found in the [base document transition](#document-base-transition). + +### Example Document Batch State Transition + +```json +{ + "protocolVersion": 1, + "type": 1, + "signature": "ICu/H7MoqxNUzznP9P2aTVEo91VVy0T8M3QWCH/7dg2UVokG98TbD4DQB4E8SD4GzHoRrBMycJ75SbT2AaF9hFc=", + "signaturePublicKeyId": 0, + "ownerId": "4ZJsE1Yg8AosmC4hAeo3GJgso4N9pCoa6eCTDeXsvdhn", + "transitions": [ + { + "$id": "8jm8iHsYE6ENENvFVeFVFMCwfgEqo5P1iR2q4KAYgpbS", + "$type": "note", + "$action": 1, + "$dataContractId": "AnmBaYH13RyiuvBkBD6qkdc36H5DKt6ToMrkqgUnnywz", + "message": "Updated document @ Mon, 26 Oct 2020 14:58:31 GMT", + "$revision": 2 + } + ] +} +``` + +## Document Object + +The document object represents the data provided by the platform in response to a query. Responses consist of an array of these objects containing the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/schema/document/documentExtended.json)): + +| Property | Type | Required | Description | +| - | - | - | - | +| protocolVersion | integer | Yes | The platform protocol version (currently `1`) | +| $id | array | Yes | The [document ID](#document-id) (32 bytes)| +| $type | string | Yes | Document type defined in the referenced contract (1-64 characters) | +| $revision | integer | No | Document revision (=>1) | +| $dataContractId | array | Yes | Data contract ID [generated](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` (32 bytes) | +| $ownerId | array | Yes | [Identity](../protocol-ref/identity.md) of the user submitting the document (32 bytes) | +| $createdAt | integer | (Optional) | Time (in milliseconds) the document was created | +| $updatedAt | integer | (Optional) | Time (in milliseconds) the document was last updated | + +Each document object must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/schema/document/documentExtended.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "$protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "$id": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "$type": { + "type": "string" + }, + "$revision": { + "type": "integer", + "minimum": 1 + }, + "$dataContractId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "$ownerId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "$createdAt": { + "type": "integer", + "minimum": 0 + }, + "$updatedAt": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "$protocolVersion", + "$id", + "$type", + "$revision", + "$dataContractId", + "$ownerId" + ], + "additionalProperties": false +} +``` + +### Example Document Object + +```json +{ + "$protocolVersion": 1, + "$id": "4mWnFcDDzCpeLExJqE8v7pfN4EERC8NE2xn4hw3VKriU", + "$type": "note", + "$dataContractId": "63au7XVDt8aHtPrsYKoHx2bnRTSenwH62pDN1BQ5n5m9", + "$ownerId": "7TkaE5uhG3T9AhyEkAvYCqZvRH4pyBibhjuSYPReNfME", + "$revision": 1, + "message": "Tutorial Test @ Mon, 26 Oct 2020 15:54:35 GMT", + "$createdAt": 1603727675072, + "$updatedAt": 1603727675072 +} +``` \ No newline at end of file diff --git a/docs/protocol-ref/errors.md b/docs/protocol-ref/errors.md new file mode 100644 index 000000000..a376a8849 --- /dev/null +++ b/docs/protocol-ref/errors.md @@ -0,0 +1,176 @@ +# Consensus Errors + +## Platform Error Codes + +A comprehensive set of consensus error codes were introduced in Dash Platform v0.21. The tables below follow the codes found in [code.js](https://github.com/dashpay/platform/blob/master/packages/rs-dpp/src/errors/consensus/codes.rs) of the consensus source code. + +The error codes are organized into four categories that each span 1000 error codes. Each category may be further divided into sub-categories. The four categories and their error code ranges are: + +| Category | Code range | Description | +| ------------------------------ | :---------: | ------------------------------------------------------------------------------------- | +| [Basic](#basic) | 1000 - 1999 | Errors encountered while validating structure and data | +| [Signature](#signature-errors) | 2000 - 2999 | Errors encountered while validating identity existence and state transition signature | +| [Fee](#fee-errors) | 3000 - 3999 | Errors encountered while validating an identity's balance is sufficient to pay fees | +| [State](#state) | 4000 - 4999 | Errors encounter while validating state transitions against the platform state | + +## Basic + +Basic errors occupy the codes ranging from 1000 to 1999. This range is divided into several categories for clarity. + +### Decoding Errors + +| Code | Error Description | Comment | +| :--: | -------------------------------- | ------- | +| 1000 | ProtocolVersionParsingError | | +| 1001 | SerializedObjectParsingError | | +| 1002 | UnsupportedProtocolVersionError | | +| 1003 | IncompatibleProtocolVersionError | | + +### Structure Errors + +| Code | Error Description | Comment | +| :--: | -------------------------- | ------------------ | +| 1004 | JsonSchemaCompilationError | | +| 1005 | JsonSchemaError | | +| 1006 | InvalidIdentifierError | | +| 1060 | ValueError | **Added in v0.24** | + +### Data Contract Errors + +| Code | Error Description | Comment | +| :--: | --------------------------------------------- | -------------------- | +| 1007 | DataContractMaxDepthExceedError | | +| 1008 | DuplicateIndexError | | +| 1009 | IncompatibleRe2PatternError | | +| 1010 | InvalidCompoundIndexError | | +| 1011 | InvalidDataContractIDError | | +| 1012 | InvalidIndexedPropertyConstraintError | | +| 1013 | InvalidIndexPropertyTypeError | | +| 1014 | InvalidJsonSchemaRefError | | +| 1015 | SystemPropertyIndexAlreadyPresentError | | +| 1016 | UndefinedIndexPropertyError | | +| 1017 | UniqueIndicesLimitReachedError | | +| 1048 | DuplicateIndexNameError | Added in v0.22 | +| 1050 | InvalidDataContractVersionError | 4013 prior to v0.23 | +| 1051 | IncompatibleDataContractSchemaError | 4014 prior to v0.23 | +| 1052 | DataContractImmutablePropertiesUpdateError | 4015 prior to v0.23 | +| 1053 | DataContractUniqueIndicesChangedError | 4016 prior to v0.23 | +| 1054 | DataContractInvalidIndexDefinitionUpdateError | Added in v0.23 | +| 1055 | DataContractHaveNewUniqueIndexError | Added in v0.23 | + +### Document Errors + +| Code | Error Description | Comment | +| :--: | -------------------------------------------- | ------- | +| 1018 | DataContractNotPresentError | | +| 1019 | DuplicateDocumentTransitionsWithIDsError | | +| 1020 | DuplicateDocumentTransitionsWithIndicesError | | +| 1021 | InconsistentCompoundIndexDataError | | +| 1022 | InvalidDocumentTransitionActionError | | +| 1023 | InvalidDocumentTransitionIDError | | +| 1024 | InvalidDocumentTypeError | | +| 1025 | MissingDataContractIDBasicError | | +| 1026 | MissingDocumentTransitionActionError | | +| 1027 | MissingDocumentTransitionTypeError | | +| 1028 | MissingDocumentTypeError | | + +### Identity Errors + +| Code | Error Description | Comment | +| :--: | ------------------------------------------------------------ | ------------------ | +| 1029 | DuplicatedIdentityPublicKeyBasicError | | +| 1030 | DuplicatedIdentityPublicKeyIDBasicError | | +| 1031 | IdentityAssetLockProofLockedTransactionMismatchError | | +| 1032 | IdentityAssetLockTransactionIsNotFoundError | | +| 1033 | IdentityAssetLockTransactionOutputAlreadyExistsError | | +| 1034 | IdentityAssetLockTransactionOutputNotFoundError | | +| 1035 | InvalidAssetLockProofCoreChainHeightError | | +| 1036 | InvalidAssetLockProofTransactionHeightError | | +| 1037 | InvalidAssetLockTransactionOutputReturnSizeError | | +| 1038 | InvalidIdentityAssetLockTransactionError | | +| 1039 | InvalidIdentityAssetLockTransactionOutputError | | +| 1040 | InvalidIdentityPublicKeyDataError | | +| 1041 | InvalidInstantAssetLockProofError | | +| 1042 | InvalidInstantAssetLockProofSignatureError | | +| 1046 | MissingMasterPublicKeyError | Added in v0.22 | +| 1047 | InvalidIdentityPublicKeySecurityLevelError | Added in v0.22 | +| 1056 | InvalidIdentityKeySignatureError | Added in v0.23 | +| 1057 | InvalidIdentityCreditWithdrawalTransitionOutputScriptError | **Added in v0.24** | +| 1058 | InvalidIdentityCreditWithdrawalTransitionCoreFeeError | **Added in v0.24** | +| 1059 | NotImplementedIdentityCreditWithdrawalTransitionPoolingError | **Added in v0.24** | + +### State Transition Errors + +| Code | Error Description | Comment | +| :--: | ----------------------------------- | ------- | +| 1043 | InvalidStateTransitionTypeError | | +| 1044 | MissingStateTransitionTypeError | | +| 1045 | StateTransitionMaxSizeExceededError | | + +## Signature Errors + +Signature errors occupy the codes ranging from 2000 to 2999. + +| Code | Error Description | Comment | +| :--: | ------------------------------------------- | -------------- | +| 2000 | IdentityNotFoundError | | +| 2001 | InvalidIdentityPublicKeyTypeError | | +| 2002 | InvalidStateTransitionSignatureError | | +| 2003 | MissingPublicKeyError | | +| 2004 | InvalidSignaturePublicKeySecurityLevelError | Added in v0.23 | +| 2005 | WrongPublicKeyPurposeError | Added in v0.23 | +| 2006 | PublicKeyIsDisabledError | Added in v0.23 | +| 2007 | PublicKeySecurityLevelNotMetError | Added in v0.23 | + +## Fee Errors + +Fee errors occupy the codes ranging from 3000 to 3999. + +| Code | Error Description | Comment | +| :--: | ----------------------- | -------------------------------------------------- | +| 3000 | BalanceIsNotEnoughError | Current credits balance is insufficient to pay fee | + +## State + +State errors occupy the codes ranging from 4000 to 4999. This range is divided into several categories for clarity. + +### Data Contract Errors + +| Code | Error Description | Comment | +| :--: | ------------------------------- | ------- | +| 4000 | DataContractAlreadyPresentError | | + +### Document Errors + +| Code | Error Description | Comment | +| :--: | :------------------------------------ | :------ | +| 4004 | DocumentAlreadyPresentError | | +| 4005 | DocumentNotFoundError | | +| 4006 | DocumentOwnerIdMismatchError | | +| 4007 | DocumentTimestampsMismatchError | | +| 4008 | DocumentTimestampWindowViolationError | | +| 4009 | DuplicateUniqueIndexError | | +| 4010 | InvalidDocumentRevisionError | | + +### Identity Errors + +| Code | Error Description | Comment | +| :--: | ----------------------------------------------- | ------------------ | +| 4011 | IdentityAlreadyExistsError | | +| 4012 | IdentityPublicKeyDisabledAtWindowViolationError | Added in v0.23 | +| 4017 | IdentityPublicKeyIsReadOnlyError | Added in v0.23 | +| 4018 | InvalidIdentityPublicKeyIdError | Added in v0.23 | +| 4019 | InvalidIdentityRevisionError | Added in v0.23 | +| 4020 | StateMaxIdentityPublicKeyLimitReachedError | Added in v0.23 | +| 4021 | DuplicatedIdentityPublicKeyStateError | Added in v0.23 | +| 4022 | DuplicatedIdentityPublicKeyIdStateError | Added in v0.23 | +| 4023 | IdentityPublicKeyIsDisabledError | Added in v0.23 | +| 4024 | IdentityInsufficientBalanceError | **Added in v0.24** | + +### Data Trigger Errors + +| Code | Error Description | Comment | +| :--: | ----------------------------- | ------- | +| 4001 | DataTriggerConditionError | | +| 4002 | DataTriggerExecutionError | | +| 4003 | DataTriggerInvalidResultError | | \ No newline at end of file diff --git a/docs/protocol-ref/identity.md b/docs/protocol-ref/identity.md new file mode 100644 index 000000000..79c35f2f3 --- /dev/null +++ b/docs/protocol-ref/identity.md @@ -0,0 +1,753 @@ +# Identity + +## Identity Overview + +Identities are a low-level construct that provide the foundation for user-facing functionality on the platform. An identity is a public key (or set of public keys) recorded on the platform chain that can be used to prove ownership of data. Please see the [Identity DIP](https://github.com/dashpay/dips/blob/master/dip-0011.md) for additional information. + +Identities consist of three components that are described in further detail in the following sections: + +| Field | Type | Description | +| --------------- | -------------- | ------------------------------------------- | +| protocolVersion | integer | The protocol version | +| id | array of bytes | The identity id (32 bytes) | +| publicKeys | array of keys | Public key(s) associated with the identity | +| balance | integer | Credit balance associated with the identity | +| revision | integer | Identity update revision | + +Each identity must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/identity.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "id": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "publicKeys": { + "type": "array", + "minItems": 1, + "maxItems": 32, + "uniqueItems": true + }, + "balance": { + "type": "integer", + "minimum": 0 + }, + "revision": { + "type": "integer", + "minimum": 0, + "description": "Identity update revision" + } +}, + "required": [ + "protocolVersion", + "id", + "publicKeys", + "balance", + "revision" + ] +} +``` + +**Example Identity** + +```json +{ + "protocolVersion":1, + "id":"6YfP6tT9AK8HPVXMK7CQrhpc8VMg7frjEnXinSPvUmZC", + "publicKeys":[ + { + "id":0, + "type":0, + "purpose":0, + "securityLevel":0, + "data":"AkWRfl3DJiyyy6YPUDQnNx5KERRnR8CoTiFUvfdaYSDS", + "readOnly":false + } + ], + "balance":0, + "revision":0 +} +``` + +### Identity id + +The identity `id` is calculated by Base58 encoding the double sha256 hash of the [outpoint](https://docs.dash.org/projects/core/en/stable/docs/resources/glossary.html#outpoint) used to fund the identity creation. + +`id = base58(sha256(sha256()))` + +**Note:** The identity `id` uses the Dash Platform specific `application/x.dash.dpp.identifier` content media type. For additional information, please refer to the [js-dpp PR 252](https://github.com/dashevo/js-dpp/pull/252) that introduced it and [identifier.rs](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-platform-value/src/types/identifier.rs). + +### Identity publicKeys + +The identity `publicKeys` array stores information regarding each public key associated with the identity. Multiple identities may use the same public key. + +**Note:** Since v0.23, each identity must have at least two public keys: a primary key (security level `0`) that is only used when updating the identity and an additional one (security level `2`) used to sign state transitions. + +Each item in the `publicKeys` array consists of an object containing: + +| Field | Type | Description | +| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | integer | The key id (all public keys must be unique) | +| type | integer | Type of key (default: 0 - ECDSA) | +| data | array of bytes | Public key (0 - ECDSA: 33 bytes, 1 - BLS: 48 bytes, 2 - ECDSA Hash160: 20 bytes, 3 - [BIP13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) Hash160: 20 bytes) | +| purpose | integer | Public key purpose (0 - Authentication, 1 - Encryption, 2 - Decryption, 3 - Withdraw) | +| securityLevel | integer | Public key security level (0 - Master, 1 - Critical, 2 - High, 3 - Medium) | +| readonly | boolean | Identity public key can't be modified with `readOnly` set to `true`. This can’t be changed after adding a key. | +| disabledAt | integer | Timestamp indicating that the key was disabled at a specified time | + +Keys for some purposes must meet certain [security level criteria](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/identity/identity_public_key/security_level.rs#L62-L77) as detailed below: + +| Key Purpose | Allowed Security Level(s) | +| -------------- | ------------------------- | +| Authentication | Any security level | +| Encryption | Medium | +| Decryption | Medium | +| Withdraw | Critical | + +Each identity public key must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/publicKey.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "id": { + "type": "integer", + "minimum": 0, + "description": "Public key ID", + "$comment": "Must be unique for the identity. It can’t be changed after adding a key. Included when signing state transitions to indicate which identity key was used to sign." + }, + "type": { + "type": "integer", + "enum": [ + 0, + 1, + 2, + 3 + ], + "description": "Public key type. 0 - ECDSA Secp256k1, 1 - BLS 12-381, 2 - ECDSA Secp256k1 Hash160, 3 - BIP 13 Hash160", + "$comment": "It can't be changed after adding a key" + }, + "purpose": { + "type": "integer", + "enum": [ + 0, + 1, + 2, + 3 + ], + "description": "Public key purpose. 0 - Authentication, 1 - Encryption, 2 - Decryption, 3 - Withdraw", + "$comment": "It can't be changed after adding a key" + }, + "securityLevel": { + "type": "integer", + "enum": [ + 0, + 1, + 2, + 3 + ], + "description": "Public key security level. 0 - Master, 1 - Critical, 2 - High, 3 - Medium", + "$comment": "It can't be changed after adding a key" + }, + "data": true, + "readOnly": { + "type": "boolean", + "description": "Read only", + "$comment": "Identity public key can't be modified with readOnly set to true. It can’t be changed after adding a key" + }, + "disabledAt": { + "type": "integer", + "description": "Timestamp indicating that the key was disabled at a specified time", + "minimum": 0 + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": 0 + } + } + }, + "then": { + "properties": { + "data": { + "type": "array", + "byteArray": true, + "minItems": 33, + "maxItems": 33, + "description": "Raw ECDSA public key", + "$comment": "It must be a valid key of the specified type and unique for the identity. It can’t be changed after adding a key" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": 1 + } + } + }, + "then": { + "properties": { + "data": { + "type": "array", + "byteArray": true, + "minItems": 48, + "maxItems": 48, + "description": "Raw BLS public key", + "$comment": "It must be a valid key of the specified type and unique for the identity. It can’t be changed after adding a key" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": 2 + } + } + }, + "then": { + "properties": { + "data": { + "type": "array", + "byteArray": true, + "minItems": 20, + "maxItems": 20, + "description": "ECDSA Secp256k1 public key Hash160", + "$comment": "It must be a valid key hash of the specified type and unique for the identity. It can’t be changed after adding a key" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": 3 + } + } + }, + "then": { + "properties": { + "data": { + "type": "array", + "byteArray": true, + "minItems": 20, + "maxItems": 20, + "description": "BIP13 script public key", + "$comment": "It must be a valid script hash of the specified type and unique for the identity" + } + } + } + } + ], + "required": [ + "id", + "type", + "data", + "purpose", + "securityLevel" + ], + "additionalProperties": false +} +``` + +#### Public Key `id` + +Each public key in an identity's `publicKeys` array must be assigned a unique index number (`id`). + +#### Public Key `type` + +The `type` field indicates the algorithm used to derive the key. + +| Type | Description | +| :--: | ----------------------------------------------------------------------------------------------------- | +| 0 | ECDSA Secp256k1 (default) | +| 1 | BLS 12-381 | +| 2 | ECDSA Secp256k1 Hash160 | +| 3 | [BIP13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) pay-to-script-hash public key | + +#### Public Key `data` + +The `data` field contains the compressed public key. + +#### Public Key `purpose` + +The `purpose` field describes which operations are supported by the key. Please refer to [DIP11 - Identities](https://github.com/dashpay/dips/blob/master/dip-0011.md#keys) for additional information regarding this. + +| Type | Description | +| :--: | -------------- | +| 0 | Authentication | +| 1 | Encryption | +| 2 | Decryption | +| 3 | Withdraw | + +#### Public Key `securityLevel` + +The `securityLevel` field indicates how securely the key should be stored by clients. Please refer to [DIP11 - Identities](https://github.com/dashpay/dips/blob/master/dip-0011.md#keys) for additional information regarding this. + +| Level | Description | Security Practice | +| :---: | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0 | Master | Should always require a user to authenticate when signing a transition. Can only be used to update an identity. | +| 1 | Critical | Should always require a user to authenticate when signing a transition | +| 2 | High | Should be available as long as the user has authenticated at least once during a session. Typically used to sign state transitions, but cannot be used for identity update transitions. | +| 3 | Medium | Should not require user authentication but must require access to the client device | + +#### Public Key `readOnly` + +The `readOnly` field indicates that the public key can't be modified if it is set to `true`. The +value of this field cannot be changed after adding the key. + +#### Public Key `disabledAt` + +The `disabledAt` field indicates that the key has been disabled. Its value equals the timestamp when the key was disabled. + +### Identity balance + +Each identity has a balance of credits established by value locked via a layer 1 lock transaction. This credit balance is used to pay the fees associated with state transitions. + +## Identity State Transition Details + +There are three identity-related state transitions: [identity create](#identity-creation), [identity topup](#identity-topup), and [identity update](#identity-update). Details are provided in this section including information about [asset locking](#asset-lock) and [signing](#identity-state-transition-signing) required for these state transitions. + +### Identity Creation + +Identities are created on the platform by submitting the identity information in an identity create state transition. + +| Field | Type | Description | +| --------------- | -------------- | --------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | The protocol version (currently `1`) | +| type | integer | State transition type (`2` for identity create) | +| assetLockProof | object | [Asset lock proof object](#asset-lock) proving the layer 1 locking transaction exists and is locked | +| publicKeys | array of keys | [Public key(s)](#identity-publickeys) associated with the identity | +| signature | array of bytes | Signature of state transition data by the single-use key from the asset lock (65 bytes) | + +Each identity must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/stateTransition/identityCreate.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 2 + }, + "assetLockProof": { + "type": "object" + }, + "publicKeys": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "uniqueItems": true + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 65, + "description": "Signature made by AssetLock one time ECDSA key" + } + }, + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "assetLockProof", + "publicKeys", + "signature" + ] +} +``` + +**Example State Transition** + +```json +{ + "protocolVersion":1, + "type":2, + "signature":"IBTTgge+/VDa/9+n2q3pb4tAqZYI48AX8X3H/uedRLH5dN8Ekh/sxRRQQS9LaOPwZSCVED6XIYD+vravF2dhYOE=", + "assetLockProof":{ + "type":0, + "instantLock":"AQHDHQdekbFZJOQFEe1FnRjoDemL/oPF/v9IME/qphjt5gEAAAB/OlZB9p8vPzPE55MlegR7nwhXRpZC4d5sYnOIypNgzfdDRsW01v8UtlRoORokjoDJ9hA/XFMK65iYTrQ8AAAAGI4q8GxtK9LHOT1JipnIfwiiv8zW+C/sbokbMhi/BsEl51dpoeBQEUAYWT7KRiJ4Atx49zIrqsKvmU1mJQza0Y1YbBSS/b/IPO8StX04bItPpDuTp6zlh/G7YOGzlEoe", + "transaction":"0300000001c31d075e91b15924e40511ed459d18e80de98bfe83c5feff48304feaa618ede6010000006b483045022100dd0e4a6c25b1c7ed9aec2c93133f6de27b4c695a062f21f0aed1a2999fccf01c0220384aaf84cd5fd1c741fd1739f5c026a492abbfc18cfde296c6d90e98304f2f76012102fb9e87840f7e0a9b01f955d8eb4d1d2a52b32c9c43c751d7a348482c514ad222ffffffff021027000000000000166a14ea15af58c614b050a3b2e6bcc131fe0e7de37b9801710815000000001976a9140ccc680f945e964f7665f57c0108cba5ca77ed1388ac00000000", + "outputIndex":0 + }, + "publicKeys":[ + { + "id":0, + "type":0, + "purpose":0, + "securityLevel":0, + "data":"AkWRfl3DJiyyy6YPUDQnNx5KERRnR8CoTiFUvfdaYSDS", + "readOnly":false + } + ] +} +``` + +### Identity TopUp + +Identity credit balances are increased by submitting the topup information in an identity topup state transition. + +| Field | Type | Description | +| --------------- | -------------- | ---------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | The protocol version (currently `1`) | +| type | integer | State transition type (`3` for identity topup) | +| assetLockProof | object | [Asset lock proof object](#asset-lock) proving the layer 1 locking transaction exists and is locked | +| identityId | array of bytes | An [Identity ID](#identity-id) for the identity receiving the topup (can be any identity) (32 bytes) | +| signature | array of bytes | Signature of state transition data by the single-use key from the asset lock (65 bytes) | + +Each identity must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/stateTransition/identityTopUp.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 3 + }, + "assetLockProof": { + "type": "object" + }, + "identityId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 65, + "description": "Signature made by AssetLock one time ECDSA key" + } + }, + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "assetLockProof", + "identityId", + "signature" + ] +} +``` + +**Example State Transition** + +```json +{ + "protocolVersion":1, + "type":3, + "signature":"IEqOV4DsbVa+nPipva0UrT0z0ZwubwgP9UdlpwBwXbFSWb7Mxkwqzv1HoEDICJ8GtmUSVjp4Hr2x0cVWe7+yUGc=", + "identityId":"6YfP6tT9AK8HPVXMK7CQrhpc8VMg7frjEnXinSPvUmZC", + "assetLockProof":{ + "type":0, + "instantLock":"AQF/OlZB9p8vPzPE55MlegR7nwhXRpZC4d5sYnOIypNgzQEAAAAm8edm9p8URNEE9PBo0lEzZ2s9nf4u1SV0MaZyB0JTRasiXu8QtTmfqZWjI3qVtOpUhGPu6r/2fV+0Ffi3AAAAhA77E0aScf+5PTYzgV5WR6VJ/EnjvXyAMmAcu222JyvA7M+5OoCzVF/IQs2IWaPOFsRl1n5C+dMxdvrxhpVLT8QfZJSl19wzybWrHbGRaHDw4iWHvfYdwyXN+vP8UwDz", + "transaction":"03000000017f3a5641f69f2f3f33c4e793257a047b9f0857469642e1de6c627388ca9360cd010000006b483045022100d8c383b15a3738d13b029605d242f041bea874cb4d0def1303ca7cdf76092bf102201b1d401ae9e8cdc5efc061249d2a967960dadce53c66e34d249c42049b48b26701210335b684aa510a9b54a3a4f79283e64482a323190045c239fae5ecb0450c78f965ffffffff02e803000000000000166a14f5383f51784bc4a27e2040bdd6cd9aae7fe6814d31690815000000001976a9144a0511ec3362b35983d0a101f0572dd26abce2ee88ac00000000", + "outputIndex":0 + } +} +``` + +### Identity Update + +Identities are updated on the platform by submitting the identity information in an identity update state transition. This state transition requires either a set of one or more new public keys to add to the identity or a list of existing keys to disable. + +| Field | Type | Description | +| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| protocolVersion | integer | The protocol version (currently `1`) | +| type | integer | State transition type (`5` for identity update) | +| identityId | array of bytes | The identity id (32 bytes) | +| signature | array of bytes | Signature of state transition data (65 bytes) | +| revision | integer | Identity update revision | +| publicKeysDisabledAt | integer | (Optional) Timestamp when keys were disabled. Required if `disablePublicKeys` is present. | +| addPublicKeys | array of public keys | (Optional) Array of up to 10 new public keys to add to the identity. Required if adding keys. | +| disablePublicKeys | array of integers | (Optional) Array of up to 10 existing identity public key ID(s) to disable for the identity. Required if disabling keys. | +| signaturePublicKeyId | integer | The ID of public key used to sign the state transition | + +Each identity must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/stateTransition/identityUpdate.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "protocolVersion": { + "type": "integer", + "$comment": "Maximum is the latest protocol version" + }, + "type": { + "type": "integer", + "const": 5 + }, + "identityId": { + "type": "array", + "byteArray": true, + "minItems": 32, + "maxItems": 32, + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "signature": { + "type": "array", + "byteArray": true, + "minItems": 65, + "maxItems": 96 + }, + "revision": { + "type": "integer", + "minimum": 0, + "description": "Identity update revision" + }, + "publicKeysDisabledAt": { + "type": "integer", + "minimum": 0 + }, + "addPublicKeys": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "uniqueItems": true + }, + "disablePublicKeys": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "uniqueItems": true, + "items": { + "type": "integer", + "minimum": 0 + } + }, + "signaturePublicKeyId": { + "type": "integer", + "minimum": 0 + } + }, + "dependentRequired" : { + "disablePublicKeys": ["publicKeysDisabledAt"], + "publicKeysDisabledAt": ["disablePublicKeys"] + }, + "anyOf": [ + { + "type": "object", + "required": ["addPublicKeys"], + "properties": { + "addPublicKeys": true + } + }, + { + "type": "object", + "required": ["disablePublicKeys"], + "properties": { + "disablePublicKeys": true + } + } + ], + "additionalProperties": false, + "required": [ + "protocolVersion", + "type", + "identityId", + "signature", + "revision", + "signaturePublicKeyId" + ] +} +``` + +### Asset Lock + +The [identity create](#identity-creation) and [identity topup](#identity-topup) state transitions both include an asset lock proof object. This object references the layer 1 lock transaction and includes proof that the transaction is locked. + +Currently there are two types of asset lock proofs: InstantSend and ChainLock. Transactions almost always receive InstantSend locks, so the InstantSend asset lock proof is the predominate type. + +#### InstantSend Asset Lock Proof + +The InstantSend asset lock proof is used for transactions that have received an InstantSend lock. + +| Field | Type | Description | +| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| type | integer | The asset lock proof type (`0` for InstantSend locks) | +| instantLock | array of bytes | The InstantSend lock ([`islock`](https://docs.dash.org/projects/core/en/stable/docs/reference/p2p-network-instantsend-messages.html#islock)) | +| transaction | array of bytes | The asset lock transaction | +| outputIndex | integer | Index of the transaction output to be used | + +Asset locks using an InstantSend lock as proof must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/stateTransition/assetLockProof/instantAssetLockProof.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "type": { + "type": "integer", + "const": 0 + }, + "instantLock": { + "type": "array", + "byteArray": true, + "minItems": 165, + "maxItems": 100000 + }, + "transaction": { + "type": "array", + "byteArray": true, + "minItems": 1, + "maxItems": 100000 + }, + "outputIndex": { + "type": "integer", + "minimum": 0 + } + }, + "additionalProperties": false, + "required": [ + "type", + "instantLock", + "transaction", + "outputIndex" + ] +} +``` + +#### ChainLock Asset Lock Proof + +The ChainLock asset lock proof is used for transactions that have note received an InstantSend lock, but have been included in a block that has received a ChainLock. + +| Field | Type | Description | +| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| type | array of bytes | The type of asset lock proof (`1` for ChainLocks) | +| coreChainLockedHeight | integer | Height of the ChainLocked Core block containing the transaction | +| outPoint | object | The [outpoint](https://docs.dash.org/projects/core/en/stable/docs/resources/glossary.html#outpoint) being used as the asset lock | + +Asset locks using a ChainLock as proof must comply with this JSON-Schema definition established in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/identity/stateTransition/assetLockProof/chainAssetLockProof.json): + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "type": { + "type": "integer", + "const": 1 + }, + "coreChainLockedHeight": { + "type": "integer", + "minimum": 1, + "maximum": 4294967295 + }, + "outPoint": { + "type": "array", + "byteArray": true, + "minItems": 36, + "maxItems": 36 + } + }, + "additionalProperties": false, + "required": [ + "type", + "coreChainLockedHeight", + "outPoint" + ] +} +``` + +### Identity State Transition Signing + +**Note:** The identity create and topup state transition signatures are unique in that they must be signed by the private key used in the layer 1 locking transaction. All other state transitions will be signed by a private key of the identity submitting them. + +The process to sign an identity create state transition consists of the following steps: + +1. Canonical CBOR encode the state transition data - this include all ST fields except the `signature` +2. Sign the encoded data with private key associated with a lock transaction public key +3. Set the state transition `signature` to the value of the signature created in the previous step + +#### Code snipits related to signing + +```rust +/// From rs-dpp +/// abstract_state_transition.rs +/// Signs data with the private key +fn sign_by_private_key( + &mut self, + private_key: &[u8], + key_type: KeyType, + bls: &impl BlsModule, +) -> Result<(), ProtocolError> { + let data = self.to_buffer(true)?; + match key_type { + KeyType::BLS12_381 => self.set_signature(bls.sign(&data, private_key)?.into()), + + // https://github.com/dashevo/platform/blob/9c8e6a3b6afbc330a6ab551a689de8ccd63f9120/packages/js-dpp/lib/stateTransition/AbstractStateTransition.js#L169 + KeyType::ECDSA_SECP256K1 | KeyType::ECDSA_HASH160 => { + let signature = signer::sign(&data, private_key)?; + self.set_signature(signature.to_vec().into()); + } + + // the default behavior from + // https://github.com/dashevo/platform/blob/6b02b26e5cd3a7c877c5fdfe40c4a4385a8dda15/packages/js-dpp/lib/stateTransition/AbstractStateTransition.js#L187 + // is to return the error for the BIP13_SCRIPT_HASH + KeyType::BIP13_SCRIPT_HASH => { + return Err(ProtocolError::InvalidIdentityPublicKeyTypeError( + InvalidIdentityPublicKeyTypeError::new(key_type), + )) + } + }; + Ok(()) +} + + +/// From rust-dashcore +/// signer.rs +/// sign and get the ECDSA signature +pub fn sign(data: &[u8], private_key: &[u8]) -> Result<[u8; 65], anyhow::Error> { + let data_hash = double_sha(data); + sign_hash(&data_hash, private_key) +} + +/// signs the hash of data and get the ECDSA signature +pub fn sign_hash(data_hash: &[u8], private_key: &[u8]) -> Result<[u8; 65], anyhow::Error> { + let pk = SecretKey::from_slice(private_key) + .map_err(|e| anyhow!("Invalid ECDSA private key: {}", e))?; + + let secp = Secp256k1::new(); + let msg = Message::from_slice(data_hash).map_err(anyhow::Error::msg)?; + + let signature = secp + .sign_ecdsa_recoverable(&msg, &pk) + .to_compact_signature(true); + Ok(signature) +} +``` \ No newline at end of file diff --git a/docs/protocol-ref/overview.md b/docs/protocol-ref/overview.md new file mode 100644 index 000000000..2ce477bd8 --- /dev/null +++ b/docs/protocol-ref/overview.md @@ -0,0 +1,53 @@ +```{eval-rst} +.. _protocol-ref-overview: +``` + +# Overview + +## Introduction + +The Dash Platform Protocol (DPP) defines a protocol for the data objects (e.g. [identities](../protocol-ref/identity.md), data contracts, documents, state transitions) that can be stored on [Dash's layer 2 platform](../intro/what-is-dash-platform.md). All data stored on Dash Platform is governed by DPP to ensure data consistency and integrity is maintained. + +Dash Platform data objects consist of JSON and are validated using the JSON Schema specification via pre-defined JSON Schemas and meta-schemas described in these sections. The meta-schemas allow for creation of DPP-compliant schemas which define fields for third-party Dash Platform applications. + +In addition to ensuring data complies with predefined JSON Schemas, DPP also defines rules for hashing and serialization of these objects. + +## Reference Implementation + +The current reference implementation is the (Rust) [rs-dpp](https://github.com/dashevo/platform/tree/master/packages/rs-dpp) library. The schemas and meta-schemas referred to in this specification can be found here in the reference implementation: . + +## Release Notes + +Release notes for past versions are located on the [dashpay/platform GitHub release page](https://github.com/dashpay/platform/releases). They provide information about breaking changes, features, and fixes. + +## Topics + +[Identities](../protocol-ref/identity.md) + +- [Create](../protocol-ref/identity.md#identity-creation) +- [TopUp](../protocol-ref/identity.md#identity-topup) + +[Data Contracts](../protocol-ref/data-contract.md) + +- [Documents](../protocol-ref/data-contract.md#data-contract-documents) + - [Properties](../protocol-ref/data-contract.md#document-properties) + - [Indices](../protocol-ref/data-contract.md#document-indices) +- [Definitions](../protocol-ref/data-contract.md#data-contract-definitions) + +[Document](../protocol-ref/document.md) + +[State Transitions](../protocol-ref/state-transition.md) + +- [Overview / general structure](../protocol-ref/state-transition.md) +- Types + - [Identity Create ST](../protocol-ref/identity.md#identity-creation) + - [Data Contract ST](../protocol-ref/data-contract.md#data-contract-creation) + - [Document Batch ST](../protocol-ref/document.md) + - Document Transitions + - [Document Transition Base](../protocol-ref/document.md#document-base-transition) + - [Document Create Transition](../protocol-ref/document.md#document-create-transition) + - [Document Replace Transition](../protocol-ref/document.md#document-replace-transition) + - [Document Delete Transition](../protocol-ref/document.md#document-delete-transition) +- [Signing](../protocol-ref/state-transition.md#state-transition-signing) + +[Data Triggers](../protocol-ref/data-trigger.md) \ No newline at end of file diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md new file mode 100644 index 000000000..892698a24 --- /dev/null +++ b/docs/protocol-ref/state-transition.md @@ -0,0 +1,139 @@ +# State Transition + +## State Transition Overview + + State transitions are the means for submitting data that creates, updates, or deletes platform data and results in a change to a new state. Each one must contain: + +- [Common fields](#common-fields) present in all state transitions +- Additional fields specific to the type of action the state transition provides (e.g. [creating an identity](../protocol-ref/identity.md#identity-creation)) + +### Fees + +State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of [1000 credits/satoshi](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/identity/credits_converter.rs#L3). Fees for actions vary based on parameters related to storage and computational effort that are defined in [rs-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/state_transition/fee/constants.rs). + +### Size + +All serialized data (including state transitions) is limited to a maximum size of [16 KB](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/util/serializer.rs#L8). + +### Common Fields + +All state transitions include the following fields: + +| Field | Type | Description | +| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| protocolVersion | integer | The platform protocol version (currently `1`) | +| type | integer | State transition type:
`0` - [data contract create](../protocol-ref/data-contract.md#data-contract-creation)
`1` - [documents batch](../protocol-ref/document.md#document-submission)
`2` - [identity create](../protocol-ref/identity.md#identity-creation)
`3` - [identity topup](identity.md#identity-topup)
`4` - [data contract update](data-contract.md#data-contract-update)
`5` - [identity update](identity.md#identity-update) | +| signature | array of bytes | Signature of state transition data (65 bytes) | + +Additionally, all state transitions except the identity create and topup state transitions include: + +| Field | Type | Description | +| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| signaturePublicKeyId | integer | The `id` of the [identity public key](../protocol-ref/identity.md#identity-publickeys) that signed the state transition (`=> 0`) | + +## State Transition Types + +### Data Contract Create + +| Field | Type | Description | +| ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| dataContract | [data contract object](../protocol-ref/data-contract.md#data-contract-object) | Object containing valid [data contract](../protocol-ref/data-contract.md) details | +| entropy | array of bytes | Entropy used to generate the data contract ID (32 bytes) | + +More detailed information about the `dataContract` object can be found in the [data contract section](../protocol-ref/data-contract.md). + +#### Entropy Generation + +Entropy is included in [Data Contracts](../protocol-ref/data-contract.md#data-contract-creation) and [Documents](../protocol-ref/document.md#document-create-transition). + +```rust +// From the Rust reference implementation (rs-dpp) +// entropyGenerator.js +fn generate(&self) -> anyhow::Result<[u8; 32]> { + let mut buffer = [0u8; 32]; + getrandom(&mut buffer).context("generating entropy failed")?; + Ok(buffer) +} +``` + +### Data Contract Update + +| Field | Type | Description | +| ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| dataContract | [data contract object](../protocol-ref/data-contract.md#data-contract-object) | Object containing valid [data contract](../protocol-ref/data-contract.md) details | + +More detailed information about the `dataContract` object can be found in the [data contract section](../protocol-ref/data-contract.md). + +### Documents Batch + +| Field | Type | Description | +| ----------- | --------------------------- | -------------------------------------------------------------------------------------- | +| ownerId | array of bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) (32 bytes) | +| transitions | array of transition objects | Document `create`, `replace`, or `delete` transitions (up to 10 objects) | + +More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). + +### Identity Create + +| Field | Type | Description | +| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| assetLockProof | array of bytes | Lock [outpoint](https://docs.dash.org/projects/core/en/stable/docs/resources/glossary.html#outpoint) from the layer 1 locking transaction (36 bytes) | +| publicKeys | array of keys | [Public key(s)](../protocol-ref/identity.md#identity-publickeys) associated with the identity (maximum number of keys: `10`) | + +More detailed information about the `publicKeys` object can be found in the [identity section](../protocol-ref/identity.md). + +### Identity TopUp + +| Field | Type | Description | +| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| assetLockProof | array of bytes | Lock [outpoint](https://docs.dash.org/projects/core/en/stable/docs/resources/glossary.html#outpoint) from the layer 1 locking transaction (36 bytes) | +| identityId | array of bytes | An [Identity ID](../protocol-ref/identity.md#identity-id) for the identity receiving the topup (can be any identity) (32 bytes) | + +### Identity Update + +| Field | Type | Description | +| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| identityId | array of bytes | The [Identity ID](../protocol-ref/identity.md#identity-id) for the identity being updated (32 bytes) | +| revision | integer | Identity update revision. Used for optimistic concurrency control. Incremented by one with each new update so that the update will fail if the underlying data is modified between reading and writing. | +| addPublicKeys | array of public keys | (Optional) Array of up to 10 new public keys to add to the identity. Required if adding keys. | +| disablePublicKeys | array of integers | (Optional) Array of up to 10 existing identity public key ID(s) to disable for the identity. Required if disabling keys. | +| publicKeysDisabledAt | integer | (Optional) Timestamp when keys were disabled. Required if `disablePublicKeys` is present. | + +## State Transition Signing + +State transitions must be signed by a private key associated with the identity creating the state transition. Since v0.23, each identity must have at least two keys: a primary key (security level `0`) that is only used when signing identity update state transitions and an additional key (security level `2`) that is used to sign all other state transitions. + +The process to sign a state transition consists of the following steps: + +1. Canonical CBOR encode the state transition data - this include all ST fields except the `signature` and `signaturePublicKeyId` +2. Sign the encoded data with a private key associated with the identity creating the state transition +3. Set the state transition `signature` to the value of the signature created in the previous step +4. For all state transitions _other than identity create or topup_, set the state transition`signaturePublicKeyId` to the [public key `id`](../protocol-ref/identity.md#public-key-id) corresponding to the key used to sign + +### Signature Validation + +The `signature` validation (see [js-dpp](https://github.com/dashpay/platform/blob/v0.24.5/packages/js-dpp/test/unit/stateTransition/validation/validateStateTransitionIdentitySignatureFactory.spec.js)) verifies that: + +1. The identity exists +2. The identity has a public key +3. The identity's public key is of type `ECDSA` +4. The state transition signature is valid + +The example test output below shows the necessary criteria: + +```text +validateStateTransitionIdentitySignatureFactory + ✔ should pass properly signed state transition + ✔ should return invalid result if owner id doesn't exist + ✔ should return MissingPublicKeyError if the identity doesn't have a matching public key + ✔ should return InvalidIdentityPublicKeyTypeError if type is not exist + ✔ should return InvalidStateTransitionSignatureError if signature is invalid + Consensus errors + ✔ should return InvalidSignaturePublicKeySecurityLevelConsensusError if InvalidSignaturePublicKeySecurityLevelError was thrown + ✔ should return PublicKeySecurityLevelNotMetConsensusError if PublicKeySecurityLevelNotMetError was thrown + ✔ should return WrongPublicKeyPurposeConsensusError if WrongPublicKeyPurposeError was thrown + ✔ should return PublicKeyIsDisabledConsensusError if PublicKeyIsDisabledError was thrown + ✔ should return InvalidStateTransitionSignatureError if DPPError was thrown + ✔ should throw unknown error + ✔ should not verify signature on dry run +``` \ No newline at end of file diff --git a/docs/reference/dapi-endpoints-core-grpc-endpoints.md b/docs/reference/dapi-endpoints-core-grpc-endpoints.md new file mode 100644 index 000000000..572bdf1d5 --- /dev/null +++ b/docs/reference/dapi-endpoints-core-grpc-endpoints.md @@ -0,0 +1,534 @@ +# Core gRPC Endpoints + +Please refer to the [gRPC Overview](../reference/dapi-endpoints-grpc-overview.md) for details regarding running the examples shown below, encoding/decoding the request/response data, and clients available for several languages. + +## Endpoint Details + +### broadcastTransaction + +**Returns**: The transaction id (TXID) if successful +**Parameters**: + +| Name | Type | Required | Description | +| ----------------- | ------- | -------- | ------------------------------------ | +| `transaction` | Bytes | Yes | A raw transaction | +| `allow_high_fees` | Boolean | No | Enables bypassing the high fee check | +| `bypass_limits` | Boolean | No | | + +#### Example Request and Response + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); +const { Transaction } = require('@dashevo/dashcore-lib'); + +const client = new DAPIClient({ + seeds: [{ + host: 'seed-1.testnet.networks.dash.org', + port: 1443, + }], +}); + +// Replace the transaction hex below with your own transaction prior to running +const tx = Transaction('02000000022fd1c4583099109524b8216d712373bd837d24a502414fcadd8ae94753c3d87e010000006a47304402202cbdc560898ad389005fbe231fb345da503d838cfadab738a7d2f57bdd7ff77c02206e02b9f05c3dfb380d158949407372f26fa8ecc66956297792509c2f700723d1012103422fa857d5049000c22c3188e84557da5b783c2ef54b83a76a2933a0564c22dafeffffff07e987f3bb114c4370b937915e980657e2706135e21fbd8972a5534c804d5495000000006a473044022041a69c058035a2a8c88715c018efcb77a9ee3a08b72fd24afe8591364cee8dc002203026f115ac9c7206a985f71422ac38d451bde092d708bfb81ef35b2968f4ee34012102f0ce58f50515d04d4ff01a550a4d3246fbdc9d27031ef7d883e845b6b41f0e4efeffffff0269440f00000000001976a91465f6a3d634ba58247825c6fd55174ca72fdcdbd988ac00e1f505000000001976a9144139b147b5cef5fef5bcdb02fcdf55e426f74dbb88ac4d5b0600'); + +client.core.broadcastTransaction(tx.toBuffer()) + .then((response) => console.log(response)); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { + CorePromiseClient, + }, +} = require('@dashevo/dapi-grpc'); +const { Transaction } = require('@dashevo/dashcore-lib'); + +const corePromiseClient = new CorePromiseClient('https://seed-1.testnet.networks.dash.org:1443'); + +// Replace the transaction hex below with your own transaction prior to running +const tx = Transaction('02000000022fd1c4583099109524b8216d712373bd837d24a502414fcadd8ae94753c3d87e010000006a47304402202cbdc560898ad389005fbe231fb345da503d838cfadab738a7d2f57bdd7ff77c02206e02b9f05c3dfb380d158949407372f26fa8ecc66956297792509c2f700723d1012103422fa857d5049000c22c3188e84557da5b783c2ef54b83a76a2933a0564c22dafeffffff07e987f3bb114c4370b937915e980657e2706135e21fbd8972a5534c804d5495000000006a473044022041a69c058035a2a8c88715c018efcb77a9ee3a08b72fd24afe8591364cee8dc002203026f115ac9c7206a985f71422ac38d451bde092d708bfb81ef35b2968f4ee34012102f0ce58f50515d04d4ff01a550a4d3246fbdc9d27031ef7d883e845b6b41f0e4efeffffff0269440f00000000001976a91465f6a3d634ba58247825c6fd55174ca72fdcdbd988ac00e1f505000000001976a9144139b147b5cef5fef5bcdb02fcdf55e426f74dbb88ac4d5b0600'); + +corePromiseClient.client.broadcastTransaction({ transaction: tx.toBuffer() }) + .then((response) => console.log(response)); +``` + +:::: + +::::{tab-set-code} + +```json +{ + "transactionId": "552eaf24a60014edcbbb253dbc4dd68766532cab3854b44face051cedcfd578f" +} +``` + +:::: + +### getStatus + +**Returns**: Status information from the Core chain +**Parameters**: None + +#### Example Request and Response + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); + +const client = new DAPIClient({ + seeds: [{ + host: 'seed-1.testnet.networks.dash.org', + port: 1443, + }], +}); + +client.core.getStatus() + .then((response) => console.log(response)); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { + GetStatusRequest, + CorePromiseClient, + }, +} = require('@dashevo/dapi-grpc'); + +const corePromiseClient = new CorePromiseClient('https://seed-1.testnet.networks.dash.org:1443'); + +corePromiseClient.client.getStatus(new GetStatusRequest()) + .then((response) => console.log(response)); +``` +```shell Request (gRPCurl) +# gRPCurl +# Run in the platform repository's `packages/dapi-grpc/` directory +grpcurl -proto protos/core/v0/core.proto \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Core/getStatus +``` + +:::: + +> 📘 +> +> **Note:** The gRPCurl response `bestBlockHash`, `chainWork`, and `proTxHash` data is Base64 encoded. + +::::{tab-set-code} + +```json JSON +// Response (JavaScript) +{ + "version":{ + "protocol":70227, + "software":190100, + "agent":"/Dash Core:19.1.0(dcg-masternode-27)/" + }, + "time":{ + "now":1684860969, + "offset":0, + "median":1684860246 + }, + "status":"READY", + "syncProgress":0.9999992137956843, + "chain":{ + "name":"test", + "headersCount":892412, + "blocksCount":892412, + "bestBlockHash":"", + "difficulty":0.003254173843543036, + "chainWork":"", + "isSynced":true, + "syncProgress":0.9999992137956843 + }, + "masternode":{ + "status":"READY", + "proTxHash":"", + "posePenalty":0, + "isSynced":true, + "syncProgress":1 + }, + "network":{ + "peersCount":145, + "fee":{ + "relay":0.00001, + "incremental":0.00001 + } + } +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "version": { + "protocol": 70227, + "software": 190000, + "agent": "/Dash Core:19.0.0/" + }, + "time": { + "now": 1684357132, + "median": 1684356285 + }, + "status": "READY", + "syncProgress": 0.9999996650927735, + "chain": { + "name": "test", + "headersCount": 888853, + "blocksCount": 888853, + "bestBlockHash": "AAAAtZ1kS2uIxOX4u1CaHqEPQhOVs23wPK9TjBZnZAI=", + "difficulty": 0.003153826459898978, + "chainWork": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAtaNAXYoQDE=", + "isSynced": true, + "syncProgress": 0.9999996650927735 + }, + "masternode": { + "status": "READY", + "proTxHash": "vcAa/9GeHoyawgatmvVCbavRGA3uUtnDigwp7EqRyn0=", + "isSynced": true, + "syncProgress": 1 + }, + "network": { + "peersCount": 147, + "fee": { + "relay": 1e-05, + "incremental": 1e-05 + } + } +} +``` + +:::: + +### getBlock + +**Returns**: A raw block +**Parameters**: + +| Name | Type | Required | Description | +| ------------------------- | ------- | -------- | --------------------------------------------------- | +| **One of the following:** | | | | +| `hash` | Bytes | No | Return the block matching the block hash provided | +| `height` | Integer | No | Return the block matching the block height provided | + +#### Example Request and Response + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); + +const client = new DAPIClient({ + seeds: [{ + host: 'seed-1.testnet.networks.dash.org', + port: 1443, + }], +}); + +client.core.getBlockByHeight(1) + .then((response) => console.log(response.toString('hex'))); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { + CorePromiseClient, + }, +} = require('@dashevo/dapi-grpc'); + +const corePromiseClient = new CorePromiseClient('https://seed-1.testnet.networks.dash.org:1443'); + +corePromiseClient.client.getBlock({ height: 1 }) + .then((response) => console.log(response.block.toString('hex'))); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { + CorePromiseClient, + }, +} = require('@dashevo/dapi-grpc'); + +const corePromiseClient = new CorePromiseClient('https://seed-1.testnet.networks.dash.org:1443'); + +corePromiseClient.client.getBlock({ + hash: '0000047d24635e347be3aaaeb66c26be94901a2f962feccd4f95090191f208c1', +}).then((response) => { + console.log(response.block.toString('hex')); +}); +``` +```shell Request (gRPCurl) +# gRPCurl +grpcurl -proto protos/core/v0/core.proto \ + -d '{ + "height":1 + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Core/getBlock +``` + +:::: + +> 📘 Block Encoding +> +> **Note:** The gRPCurl response block data is Base64 encoded + +::::{tab-set-code} + +```shell Response (JavaScript) +# Response (JavaScript) +020000002cbcf83b62913d56f605c0e581a48872839428c92e5eb76cd7ad94bcaf0b00007f11dcce14075520e8f74cc4ddf092b4e26ebd23b8d8665a1ae5bfc41b58fdb4c3a95e53ffff0f1ef37a00000101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff0a510101062f503253482fffffffff0100743ba40b0000002321020131f38ae3eb0714531dbfc3f45491b4131d1211e3777177636388bb5a74c3e4ac00000000 +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "block": "AgAAACy8+DtikT1W9gXA5YGkiHKDlCjJLl63bNetlLyvCwAAfxHczhQHVSDo90zE3fCStOJuvSO42GZaGuW/xBtY/bTDqV5T//8PHvN6AAABAQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP////8KUQEBBi9QMlNIL/////8BAHQ7pAsAAAAjIQIBMfOK4+sHFFMdv8P0VJG0Ex0SEeN3cXdjY4i7WnTD5KwAAAAA" +} +``` + +:::: + +### getTransaction + +**Returns**: A raw transaction +**Parameters**: + +| Name | Type | Required | Description | +| ---- | ------ | -------- | ----------------------- | +| `id` | String | Yes | A transaction id (TXID) | + +#### Example Request and Response + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); + +const client = new DAPIClient({ + seeds: [{ + host: 'seed-1.testnet.networks.dash.org', + port: 1443, + }], +}); + +const txid = '4004d3f9f1b688f2babb1f98ea48e1472be51e29712f942fc379c6e996cdd308'; +client.core.getTransaction(txid) + .then((response) => console.dir(response, { length: 0 })); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { + CorePromiseClient, + }, +} = require('@dashevo/dapi-grpc'); + +const corePromiseClient = new CorePromiseClient('https://seed-1.testnet.networks.dash.org:1443'); + +const txid = '4004d3f9f1b688f2babb1f98ea48e1472be51e29712f942fc379c6e996cdd308'; + +corePromiseClient.client.getTransaction({ id: txid }) + .then((response) => console.dir(response, { length: 0 })); +``` +```shell Request (gRPCurl) +# gRPCurl +grpcurl -proto protos/core/v0/core.proto \ + -d '{ + "id":"4004d3f9f1b688f2babb1f98ea48e1472be51e29712f942fc379c6e996cdd308" + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Core/getTransaction +``` + +:::: + +> 📘 Transaction Encoding +> +> **Note:** The gRPCurl response `transaction` and `blockHash` data are Base64 encoded + +::::{tab-set-code} + +```text Response (JavaScript) +# Response (JavaScript) +GetTransactionResponse { + transaction: Buffer(196) [Uint8Array] [ + 3, 0, 5, 0, 1, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 255, 255, 255, 255, 6, 3, 194, 90, 6, 1, 9, + 255, 255, 255, 255, 2, 238, 252, 207, 49, 0, 0, 0, + 0, 25, 118, 169, 20, 126, 178, 93, 197, 175, 71, 45, + 107, 241, 154, 135, 122, 150, 240, 167, 7, 194, 198, 27, + 118, 136, 172, 101, 251, 183, 74, 0, 0, 0, 0, 25, + 118, 169, 20, 30, + ... 96 more items + ], + blockHash: Buffer(32) [Uint8Array] [ + 0, 0, 2, 9, 133, 199, 245, 83, + 191, 120, 191, 203, 109, 166, 9, 115, + 193, 152, 249, 11, 7, 245, 126, 31, + 55, 65, 10, 150, 205, 150, 131, 213 + ], + height: 416450, + confirmations: 386421, + instantLocked: false, + chainLocked: true +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "transaction": "AwAFAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP////8GA8JaBgEJ/////wLu/M8xAAAAABl2qRR+sl3Fr0cta/Gah3qW8KcHwsYbdoisZfu3SgAAAAAZdqkUHsXGbpeJxlWuBo01CItAczRf4LCIrAAAAABGAgDCWgYA3zSmucmdu7+CaY+6n4aGHySJHhbAxeiB3gNMGSIgYA1c6q3De0wxbi7HpAf4g4BgSUqhmkAxVflcQyddo+2zGA==", + "blockHash": "AAACCYXH9VO/eL/LbaYJc8GY+QsH9X4fN0EKls2Wg9U=", + "height": 416450, + "confirmations": 472404, + "isChainLocked": true +} +``` + +:::: + +### subscribeToBlockHeadersWithChainLocks + +This endpoint helps support simplified payment verification ([SPV](https://docs.dash.org/projects/core/en/stable/docs/guide/operating-modes-simplified-payment-verification-spv.html)) via DAPI by providing access to block headers which can then be used to verify transactions and simplified masternode lists. + +**Returns**: streams the requested block header information +**Parameters**: + +| Name | Type | Required | Description | +| ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- | +| ---------- | | | | +| **One of the following:** | | | | +| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided | +| `from_block_height` | Integer | No | Return records beginning with the block height provided | +| ---------- | | | | +| `count` | Integer | No | Number of blocks to sync. If set to 0 syncing is continuously sends new data as well (default: 0) | + +** Example Request and Response ** + +::::{tab-set-code} + +```shell +# gRPCurl +grpcurl -proto protos/core/v0/core.proto \ + -d '{ + "from_block_height": 1, + "count": 1 +}' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Core/subscribeToBlockHeadersWithChainLocks +``` + +:::: + +> 📘 +> +> **Note:** The gRPCurl response `chainlock` and `headers` data is Base64 encoded + +::::{tab-set-code} + +```json +// Response (gRPCurl) +{ + "chainLock": "FZANAAJkZxaMU6888G2zlRNCD6EemlC7+OXEiGtLZJ21AAAAo7qvfeETyNxWVog47Yiyx9j9FSUCVkUWBrn0ZAfIbeU75kiccv4ilNmj1Peavv1oD+Ti9dqJYy9K8/MuDt7rYnVfmPWIUj03QYWKzQKr/PaMkavTaa+PCOrqQYxcLX/s" +} +{ + "blockHeaders": { + "headers": [ + "AgAAACy8+DtikT1W9gXA5YGkiHKDlCjJLl63bNetlLyvCwAAfxHczhQHVSDo90zE3fCStOJuvSO42GZaGuW/xBtY/bTDqV5T//8PHvN6AAA=" + ] + } +} +``` + +:::: + +### subscribeToTransactionsWithProofs + +**Returns**: streams the requested transaction information +**Parameters**: + +| Name | Type | Required | Description | +| ---------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `bloom_filter.v_data` | Bytes | Yes | The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes | +| `bloom_filter.n_hash_funcs` | Integer | Yes | The number of hash functions to use in this filter. The maximum value allowed in this field is 50 | +| `bloom_filter.n_tweak` | Integer | Yes | A random value to add to the seed value in the hash function used by the bloom filter | +| `bloom_filter.n_flags` | Integer | Yes | A set of flags that control how matched items are added to the filter | +| ---------- | | | | +| **One of the following:** | | | | +| `from_block_hash` | Bytes | No | Return records beginning with the block hash provided | +| `from_block_height` | Integer | No | Return records beginning with the block height provided | +| ---------- | | | | +| `count` | Integer | No | Number of blocks to sync. If set to 0 syncing is continuously sends new data as well (default: 0) | +| `send_transaction_hashes` \* | Boolean | No | | + +** Example Request and Response ** + +::::{tab-set-code} + +```shell Request (gRPCurl) +# gRPCurl +grpcurl -proto protos/core/v0/core.proto \ + -d '{ + "from_block_height": 1, + "count": 1, + "bloom_filter": { + "n_hash_funcs": 11, + "v_data": "", + "n_tweak": 0, + "n_flags": 0 + } +}' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Core/subscribeToTransactionsWithProofs +``` + +:::: + +> 📘 +> +> **Note:** The gRPCurl response `transactions` and `rawMerkleBlock` data is Base64 encoded + +::::{tab-set-code} + +```json Response +// Response (gRPCurl) +{ + "rawTransactions": { + "transactions": [ + "AQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP////8KUQEBBi9QMlNIL/////8BAHQ7pAsAAAAjIQIBMfOK4+sHFFMdv8P0VJG0Ex0SEeN3cXdjY4i7WnTD5KwAAAAA" + ] + } +} +{ + "rawMerkleBlock": "AgAAACy8+DtikT1W9gXA5YGkiHKDlCjJLl63bNetlLyvCwAAfxHczhQHVSDo90zE3fCStOJuvSO42GZaGuW/xBtY/bTDqV5T//8PHvN6AAABAAAAAX8R3M4UB1Ug6PdMxN3wkrTibr0juNhmWhrlv8QbWP20AQE=" +} +``` + +:::: + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "
\n\n\n" + } + [/block] +``` + +## Deprecated Endpoints + +There are no recently deprecated endpoints, but the previous version of documentation can be [viewed here](https://dashplatform.readme.io/v0.23.0/docs/reference-dapi-endpoints-core-grpc-endpoints). + +## Code Reference + +Implementation details related to the information on this page can be found in: + +- The [Platform repository](https://github.com/dashevo/platform/tree/master/packages/dapi) `packages/dapi/lib/grpcServer/handlers/core` folder +- The [Platform repository](https://github.com/dashevo/platform/tree/master/packages/dapi-grpc) `packages/dapi-grpc/protos` folder \ No newline at end of file diff --git a/docs/reference/dapi-endpoints-grpc-overview.md b/docs/reference/dapi-endpoints-grpc-overview.md new file mode 100644 index 000000000..fd1ec2c42 --- /dev/null +++ b/docs/reference/dapi-endpoints-grpc-overview.md @@ -0,0 +1,88 @@ +# gRPC Overview + +The gRPC endpoints provide access to information from Dash Platform (layer 2) as well as streaming of events related to blocks and transactions/transitions. + +## Connecting to gRPC + +### Auto-generated Clients + +Clients for a number of languages are built automatically from the protocol definitions and are available in the `packages/dapi-grpc/clients` folder of the [platform](https://github.com/dashpay/platform/tree/master/packages/dapi-grpc/clients) repository. The protocol definitions are available in the [`protos` folder](https://github.com/dashpay/platform/tree/master/packages/dapi-grpc/protos). Pull requests are welcome to add support for additional languages that are not currently being built. + +### Command Line Examples + +Some examples shown in the endpoint details pages use a command-line tool named [gRPCurl](https://github.com/fullstorydev/grpcurl) that allows interacting with gRPC servers in a similar way as `curl` does for the [JSON-RPCs](../reference/dapi-endpoints-json-rpc-endpoints.md). Additional information may be found in the [gRPC documentation](https://grpc.io/docs/guides/). + +To use gRPCurl as shown in the detailed examples, clone the [platform](https://github.com/dashevo/platform/) repository and execute the example requests from the `packages/dapi-grpc` directory of that repository as shown in this example: + +```shell +## Clone the dapi-grpc repository +git clone https://github.com/dashpay/platform.git +cd platform/packages/dapi-grpc + +## Execute gRPCurl command +grpcurl -plaintext -proto protos/... +``` + +## Data Encoding + +The data submitted/received from the gRPC endpoints is encoded using both [CBOR](https://tools.ietf.org/html/rfc7049) and Base64. Data is first encoded with CBOR and the resulting output is then encoded in Base64 before being sent. + +Canonical encoding is used for state transitions, identities, data contracts, and documents. This puts the object's data fields in a sorted order to ensure the same hash is produced every time regardless of the actual order received by the encoder. Reproducible hashes are necessary to support validation of request/response data. + +Libraries such as [`cbor` (JavaScript)](https://www.npmjs.com/package/cbor) and [`cbor2` (Python)](https://pypi.org/project/cbor2/) can be used to encode/decode data for DAPI gRPC endpoints. + +The examples below use the response from a [`getIdentity` gPRC request](../reference/dapi-endpoints-platform-endpoints.md#getidentity) to demonstrate how to both encode data for sending and decode received data: + +::::{tab-set-code} + +```javascript NodeJS - Decode Identity +// NodeJS - Decode Identity +const cbor = require('cbor'); + +const grpc_identity_response = 'o2JpZHgsQ2JZVnlvS25HeGtIYUJydWNDQWhQRUJjcHV6OGoxNWNuWVlpdjFDRUhCTnhkdHlwZQFqcHVibGljS2V5c4GkYmlkAWRkYXRheCxBbXpSMkZNNGZZd0NtWnhHWjFOMnRhMkZmdUo5NU93K0xMQXJaREx1WUJqdGR0eXBlAWlpc0VuYWJsZWT1' + +const identity_cbor = Buffer.from(grpc_identity_response, 'base64').toJSON(); +const identity = cbor.decode(Buffer.from(identity_cbor)); + +console.log('Identity details'); +console.dir(identity); +``` +```python Python - Decode Identity +# Python - Decode Identity +from base64 import b64decode, b64encode +import json +import cbor2 + +grpc_identity_response = 'o2JpZHgsQ2JZVnlvS25HeGtIYUJydWNDQWhQRUJjcHV6OGoxNWNuWVlpdjFDRUhCTnhkdHlwZQFqcHVibGljS2V5c4GkYmlkAWRkYXRheCxBbXpSMkZNNGZZd0NtWnhHWjFOMnRhMkZmdUo5NU93K0xMQXJaREx1WUJqdGR0eXBlAWlpc0VuYWJsZWT1' + +identity_cbor = b64decode(grpc_identity_response) +identity = cbor2.loads(identity_cbor) + +print('Identity details:\n{}\n'.format(json.dumps(identity, indent=2))) +``` +```python Python - Encode Identity +# Python - Encode Identity +from base64 import b64decode, b64encode +import json +import cbor2 + +## Encode an identity +identity = { + "id": "CbYVyoKnGxkHaBrucCAhPEBcpuz8j15cnYYiv1CEHBNx", + "type": 1, + "publicKeys": [ + { + "id": 1, + "data": "AmzR2FM4fYwCmZxGZ1N2ta2FfuJ95Ow+LLArZDLuYBjt", + "type": 1, + "isEnabled": True + } + ] +} + +identity_cbor = cbor2.dumps(identity) +identity_grpc = b64encode(identity_cbor) +print('Identity gRPC data: {}'.format(identity_grpc)) +``` + +:::: diff --git a/docs/reference/dapi-endpoints-json-rpc-endpoints.md b/docs/reference/dapi-endpoints-json-rpc-endpoints.md new file mode 100644 index 000000000..2a67f0548 --- /dev/null +++ b/docs/reference/dapi-endpoints-json-rpc-endpoints.md @@ -0,0 +1,337 @@ +# JSON-RPC Endpoints + +## Overview + +The endpoints described on this page provide access to information from the Core chain (layer 1). + +### Required Parameters + +All valid JSON-RPC requests require the inclusion the parameters listed in the following table. + +| Name | Type | Description | +| --------- | ------- | ------------------------------------------------------------------------------------- | +| `method` | String | Name of the endpoint | +| `id` | Integer | Request id (returned in the response to differentiate results from the same endpoint) | +| `jsonrpc` | String | JSON-RPC version ("2.0") | + +Additional information may be found in the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object). + +## Endpoint Details + +### getBestBlockHash + +**Returns**: the block hash of the chaintip +**Parameters**: none + +#### Example Request and Response + +::::{tab-set-code} + +```shell Curl +curl -k --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{ + "method":"getBestBlockHash", + "id":1, + "jsonrpc":"2.0", + "params":{} + }' +``` +```javascript JavaScript +var request = require("request"); + +var options = { + method: 'POST', + url: 'https://seed-1.testnet.networks.dash.org:1443', + headers: {'content-type': 'application/json'}, + body: '{"method":"getBestBlockHash","id":1,"jsonrpc":"2.0"}' +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` +```javascript Node +// Node.js +var XMLHttpRequest = require('xhr2'); +var data = '{"method":"getBestBlockHash","id":1,"jsonrpc":"2.0"}'; + +var xhr = new XMLHttpRequest(); + +xhr.addEventListener("readystatechange", function () { + if (this.readyState === this.DONE) { + console.log(this.responseText); + } +}); + +xhr.open("POST", "https://seed-1.testnet.networks.dash.org:1443"); +xhr.setRequestHeader("content-type", "application/json"); + +xhr.send(data); +``` +```python Python +import requests +import json + +url = "https://seed-1.testnet.networks.dash.org:1443/" +headers = {'content-type': 'application/json'} + +payload_json = { + "method": "getBestBlockHash", + "id": 1, + "jsonrpc": "2.0", + "params": {} +} + +response = requests.request("POST", url, data=json.dumps(payload_json), headers=headers) + +print(response.text) +``` +```ruby Ruby +require 'uri' +require 'net/http' + +url = URI("https://seed-1.testnet.networks.dash.org:1443/") +http = Net::HTTP.new(url.host, url.port) + +request = Net::HTTP::Post.new(url) +request["content-type"] = 'application/json' + +request.body = '{ + "method":"getBestBlockHash", + "id":1, + "jsonrpc":"2.0", + "params":{ } +}' + +response = http.request(request) +puts response.read_body +``` + +:::: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0000009fd106a7aa7142925fcd311442790145a3351fa2508d9da2b3462086fd" +} +``` + +### getBlockHash + +**Returns**: the block hash for the given height +**Parameters**: + +| Name | Type | Required | Description | +| -------- | ------- | -------- | ------------ | +| `height` | Integer | Yes | Block height | + +#### Example Request and Response + +::::{tab-set-code} + +```shell Curl +curl -k --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{ + "method":"getBlockHash", + "id":1, + "jsonrpc":"2.0", + "params": { + "height": 1 + } + }' +``` +```python Python +import requests +import json + +url = "https://seed-1.testnet.networks.dash.org:1443/" +headers = {'content-type': 'application/json'} + +payload_json = { + "method": "getBlockHash", + "id": 1, + "jsonrpc": "2.0", + "params": { + "height": 100 + } +} + +response = requests.request("POST", url, data=json.dumps(payload_json), headers=headers) + +print(response.text) +``` +```ruby Ruby +require 'uri' +require 'net/http' + +url = URI("https://seed-1.testnet.networks.dash.org:1443/") +http = Net::HTTP.new(url.host, url.port) + +request = Net::HTTP::Post.new(url) +request["content-type"] = 'application/json' + +request.body = '{ + "method":"getBlockHash", + "id":1, + "jsonrpc":"2.0", + "params":{ + "height":100 + } +}' + +response = http.request(request) +puts response.read_body +``` + +:::: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0000047d24635e347be3aaaeb66c26be94901a2f962feccd4f95090191f208c1" +} +``` + +### getMnListDiff + +**Returns**: a masternode list diff for the provided block hashes +**Parameters**: + +| Name | Type | Required | Description | +| --------------- | ------ | -------- | --------------------------------- | +| `baseBlockHash` | String | Yes | Block hash for the starting block | +| `blockHash` | String | Yes | Block hash for the ending block | + +#### Example Request and Response + +::::{tab-set-code} + +```shell Curl +curl -k --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{ + "method":"getMnListDiff", + "id":1, + "jsonrpc":"2.0", + "params": { + "baseBlockHash": "00000016b4d13db8395b31d87c76ca88824b26e03e54480d8c9ddf6f11857a7c", + "blockHash": "0000002266d8e7836eb116fe467597d13d9862c6612e31bbd6161c35b6485493" + } + }' +``` +```python Python +import requests +import json + +url = "https://seed-1.testnet.networks.dash.org:1443/" +headers = {'content-type': 'application/json'} + +payload_json = { + "method":"getMnListDiff", + "id":1, + "jsonrpc":"2.0", + "params": { + "baseBlockHash": "00000016b4d13db8395b31d87c76ca88824b26e03e54480d8c9ddf6f11857a7c", + "blockHash": "0000002266d8e7836eb116fe467597d13d9862c6612e31bbd6161c35b6485493" + } +} + +response = requests.request("POST", url, data=json.dumps(payload_json), headers=headers) + +print(response.text) +``` +```ruby Ruby +require 'uri' +require 'net/http' + +url = URI("https://seed-1.testnet.networks.dash.org:1443/") +http = Net::HTTP.new(url.host, url.port) + +request = Net::HTTP::Post.new(url) +request["content-type"] = 'application/json' + +request.body = '{ + "method":"getMnListDiff", + "id":1, + "jsonrpc":"2.0", + "params": { + "baseBlockHash": "00000016b4d13db8395b31d87c76ca88824b26e03e54480d8c9ddf6f11857a7c", + "blockHash": "0000002266d8e7836eb116fe467597d13d9862c6612e31bbd6161c35b6485493" + } +}' + +response = http.request(request) +puts response.read_body +``` + +:::: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "baseBlockHash": "00000016b4d13db8395b31d87c76ca88824b26e03e54480d8c9ddf6f11857a7c", + "blockHash": "0000002266d8e7836eb116fe467597d13d9862c6612e31bbd6161c35b6485493", + "cbTxMerkleTree": "0300000003795f4c55c12757f3783a81a804585545d1844660f0b59e25a93d332bdf98a1032552fe1c2eada657f6714b14e1746a8f09b3a526e88243831133a7e25c9afcde8800af04201e85dc0cffb817c5fe7b4972ccf2647503d3d45f41304b664e8cba0107", + "cbTx": "03000500010000000000000000000000000000000000000000000000000000000000000000ffffffff1202e21b0e2f5032506f6f6c2d74444153482fffffffff04cb525b96010000001976a9144f79c383bc5d3e9d4d81b98f87337cedfa78953688ac26c4609a010000001976a914243f5bceb1ae0a580f5a9415f9a015ad38477e7188ac6e710504000000001976a914badadfdebaa6d015a0299f23fbc1fcbdd72ba96f88ac00000000000000002a6a289c7178341d0097998baa6098724d78fd01b46455890203d99413e86a55ebb610000000000700000000000000260100e21b0000f02004439b25d27e07bb9afbd07db7dfc71aa91338391cef46e08488fe66bfe9", + "deletedMNs": [], + "mnList": [ + { + "proRegTxHash": "682b3e58e283081c51f2e8e7a7de5c7312a2e8074affaf389fafcc39c4805404", + "confirmedHash": "00000018c824355520c6a850076c041b533d05cbe481f8187e541d7e2f856def", + "service": "64.193.62.206:19999", + "pubKeyOperator": "85f2269374676476f00068b7cb168d124b7b780a92e8564e18edf45d77497abd9debf186ee98001a0c9a6dfccbab7a0a", + "votingAddress": "yid7uAsVJzvSLrEekHuGNuY3KWCqJopyJ8", + "isValid": true, + "nVersion": 2, + "nType": 0 + }, + { + "proRegTxHash": "c48a44a9493eae641bea36992bc8c27eaaa33adb1884960f55cd259608d26d2f", + "confirmedHash": "000000237725f8fe7d78153ae9c11193ee0cda18f8b48141acff8e1ac713da5b", + "service": "173.61.30.231:19013", + "pubKeyOperator": "8700add55a28ef22ec042a2f28e25fb4ef04b3024a7c56ad7eed4aebc736f312d18f355370dfb6a5fec9258f464b227e", + "votingAddress": "yTMDce5yEpiPqmgPrPmTj7yAmQPJERUSVy", + "isValid": true, + "nVersion": 2, + "nType": 0 + }, + { + "proRegTxHash": "9f4f9f83ecbcd5739d7f1479ee14b508f2414d044a717acba0960566c4e6091d", + "confirmedHash": "0000000000000000000000000000000000000000000000000000000000000000", + "service": "45.32.211.155:19999", + "pubKeyOperator": "88e37b3fcba972fe0c2c0ea15f8285c8bfb262ad4d8a6741a530154f1abc4edd367a22abd0cb1934647f033913cca58a", + "votingAddress": "ybAZoZ6iybhEwoCfb6utGfU753R1wcQSZT", + "isValid": true, + "nVersion": 2, + "nType": 0 + } + ], + "nVersion": 2, + "deletedQuorums": [], + "newQuorums": [], + "merkleRootMNList": "e9bf66fe8884e046ef1c393813a91ac7dfb77dd0fb9abb077ed2259b430420f0" + } +} + +``` + +## Deprecated Endpoints + +There are no recently deprecated endpoint, but the previous version of documentation can be [viewed here](https://dashplatform.readme.io/v0.23.0/docs/reference-dapi-endpoints-json-rpc-endpoints). + +## Code Reference + +Implementation details related to the information on this page can be found in: + +- The [DAPI repository](https://github.com/dashevo/platform/tree/master/packages/dapi) `lib/rpcServer/commands` folder \ No newline at end of file diff --git a/docs/reference/dapi-endpoints-platform-endpoints.md b/docs/reference/dapi-endpoints-platform-endpoints.md new file mode 100644 index 000000000..04008dfbc --- /dev/null +++ b/docs/reference/dapi-endpoints-platform-endpoints.md @@ -0,0 +1,789 @@ +# Platform gRPC Endpoints + +Please refer to the [gRPC Overview](../reference/dapi-endpoints-grpc-overview.md) for details regarding running the examples shown below, encoding/decoding the request/response data, and clients available for several languages. + +## Data Proofs and Metadata + +Since Dash Platform 0.20.0, Platform gRPC endpoints can provide [proofs](https://github.com/dashpay/platform/blob/master/packages/dapi-grpc/protos/platform/v0/platform.proto#L17-L22) so the data returned for a request can be verified as being valid. Full support is not yet available in the JavaScript client, but can be used via the low level [dapi-grpc library](https://github.com/dashevo/platform/tree/master/packages/dapi-grpc). + +Some [additional metadata](https://github.com/dashevo/platform/blob/master/packages/dapi-grpc/protos/platform/v0/platform.proto#L30-L33) is also provided with responses: + +| Metadata field | Description | +| :---------------------- | :---------------------------------------------------- | +| `height` | Last committed platform chain height | +| `coreChainLockedHeight` | Height of the most recent ChainLock on the core chain | +| `timeMs` | Unix timestamp in milliseconds for the response | +| `protocolVersion` | Platform protocol version | + +## Endpoint Details + +### broadcastStateTransition + +> 📘 +> +> **Note:** The [`waitForStateTransitionResult` endpoint](#waitforstatetransitionresult) should be used in conjunction with this one for instances where proof of block confirmation is required. + +Broadcasts a [state transition](../explanations/platform-protocol-state-transition.md) to the platform via DAPI to make a change to layer 2 data. The `broadcastStateTransition` call returns once the state transition has been accepted into the mempool. + +**Returns**: Nothing or error + +**Parameters**: + +| Name | Type | Required | Description | +| ------------------ | -------------- | -------- | -------------------------------------------------------------------- | +| `state_transition` | Bytes (Base64) | Yes | A [state transition](../explanations/platform-protocol-state-transition.md) | + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "\n\n\n\n" + } + [/block] +``` + +**Response**: No response except on error + +### getIdentity + +> 🚧 Breaking changes +> +> As of Dash Platform 0.24 the `protocolVersion` is no longer included in the CBOR-encoded data. It is instead prepended as a varint to the data following CBOR encoding. + +**Returns**: [Identity](../explanations/identity.md) information for the requested identity +**Parameters**: + +| Name | Type | Required | Description | +| ------- | ------- | -------- | --------------------------------------------------------------------- | +| `id` | Bytes | Yes | An identity `id` | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity | + +> 📘 +> +> **Note**: When requesting proofs, the data requested will be encoded as part of the proof in the response. + +** Example Request and Response ** + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const cbor = require('cbor'); +const varint = require('varint'); + +const client = new DAPIClient(); + +const identityId = Identifier.from('4EfA9Jrvv3nnCFdSf7fad59851iiTRZ6Wcu6YVJ4iSeF'); +client.platform.getIdentity(identityId).then((response) => { + // Strip off protocol version (leading varint) and decode + const identityBuffer = Buffer.from(response.getIdentity()); + const protocolVersion = varint.decode(identityBuffer); + const identity = cbor.decode( + identityBuffer.slice(varint.encodingLength(protocolVersion), identityBuffer.length), + ); + console.log(identity); +}); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { PlatformPromiseClient, GetIdentityRequest }, +} = require('@dashevo/dapi-grpc'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const cbor = require('cbor'); +const varint = require('varint'); + +const platformPromiseClient = new PlatformPromiseClient( + 'https://seed-1.testnet.networks.dash.org:1443', +); + +const id = Identifier.from('4EfA9Jrvv3nnCFdSf7fad59851iiTRZ6Wcu6YVJ4iSeF'); +const idBuffer = Buffer.from(id); +const getIdentityRequest = new GetIdentityRequest(); +getIdentityRequest.setId(idBuffer); +getIdentityRequest.setProve(false); + +platformPromiseClient.getIdentity(getIdentityRequest) + .then((response) => { + // Strip off protocol version (leading varint) and decode + const identityBuffer = Buffer.from(response.getIdentity()); + const protocolVersion = varint.decode(identityBuffer); + const decodedIdentity = cbor.decode( + identityBuffer.slice(varint.encodingLength(protocolVersion), identityBuffer.length), + ); + console.log(decodedIdentity); + }) + .catch((e) => console.error(e)); +``` +```shell gRPCurl +# gRPCurl +# `id` must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "id":"MBLBm5jsADOt2zbNZLf1EGcPKjUaQwS19plBRChu/aw=" + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getIdentity +``` + +:::: + +::::{tab-set-code} + +```json Response (JavaScript) +// Response (JavaScript) +{ + "id": "", + "balance": 5255234422, + "revision": 0, + "publicKeys": [ + { + "id": 0, + "data": "", + "type": 0, + "purpose": 0, + "readOnly": false, + "securityLevel": 0 + }, + { + "id": 1, + "data": "", + "type": 0, + "purpose": 0, + "readOnly": false, + "securityLevel": 2 + } + ] +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "identity": "AaRiaWRYIDASwZuY7AAzrds2zWS39RBnDyo1GkMEtfaZQUQobv2sZ2JhbGFuY2UbAAAAATk8g3ZocmV2aXNpb24AanB1YmxpY0tleXOCpmJpZABkZGF0YVghAsi0dHtSjKxf3femzGNwLuBO19EzKQTghRA0PqANzlRqZHR5cGUAZ3B1cnBvc2UAaHJlYWRPbmx59G1zZWN1cml0eUxldmVsAKZiaWQBZGRhdGFYIQIB7ij4T1SFOQVn6TnCtYYBC2Omnsksq1NdyWqMcZE2AmR0eXBlAGdwdXJwb3NlAGhyZWFkT25sefRtc2VjdXJpdHlMZXZlbAI=", + "metadata": { + "height": "4217", + "coreChainLockedHeight": 858833, + "timeMs": "1688058824358", + "protocolVersion": 1 + } +} +``` + +:::: + +### getIdentitiesByPublicKeyHashes + +**Returns**: [Identity](../explanations/identity.md) an array of identities associated with the provided public key hashes +**Parameters**: + +| Name | Type | Required | Description | +| ------------------- | ------- | -------- | ----------------------------------------------------------------------- | +| `public_key_hashes` | Bytes | Yes | Public key hashes (sha256-ripemd160) of identity public keys | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identities | + +> 📘 +> +> **Note**: When requesting proofs, the data requested will be encoded as part of the proof in the response. + +> 📘 Public key hash +> +> Note: the hash must be done using all fields of the identity public key object - e.g. +> +> ```json +> { +> "id": 0, +> "type": 0, +> "purpose": 0, +> "securityLevel": 0, +> "data": "A2GTAJk9eAWkMXVCb+rRKXH99POtR5OaW6zqZl7/yozp", +> "readOnly": false +> } +> ``` +> +> When using the js-dpp library, the hash can be accessed via the [IdentityPublicKey object's](https://github.com/dashevo/platform/blob/master/packages/js-dpp/lib/identity/IdentityPublicKey.js) `hash` method (e.g. `identity.getPublicKeyById(0).hash()`). + +** Example Request and Response ** + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); +const DashPlatformProtocol = require('@dashevo/dpp'); + +const client = new DAPIClient(); +const dpp = new DashPlatformProtocol(); + +const publicKeyHash = 'b8d1591aa74d440e0af9c0be16c55bbc141847f7'; +const publicKeysBuffer = [Buffer.from(publicKeyHash, 'hex')]; + +dpp.initialize().then(() => { + client.platform.getIdentitiesByPublicKeyHashes(publicKeysBuffer) + .then((response) => { + const retrievedIdentity = dpp.identity.createFromBuffer(response.identities[0]); + console.log(retrievedIdentity.toJSON()); + }); +}); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { PlatformPromiseClient, GetIdentitiesByPublicKeyHashesRequest }, +} = require('@dashevo/dapi-grpc'); +const DashPlatformProtocol = require('@dashevo/dpp'); + +const dpp = new DashPlatformProtocol(); + +dpp.initialize() + .then(() => { + const platformPromiseClient = new PlatformPromiseClient( + 'https://seed-1.testnet.networks.dash.org:1443', + ); + + const publicKeyHash = 'b8d1591aa74d440e0af9c0be16c55bbc141847f7'; + const publicKeysBuffer = [Buffer.from(publicKeyHash, 'hex')]; + + const getIdentitiesByPublicKeyHashesRequest = new GetIdentitiesByPublicKeyHashesRequest(); + getIdentitiesByPublicKeyHashesRequest.setPublicKeyHashesList(publicKeysBuffer); + + platformPromiseClient.getIdentitiesByPublicKeyHashes(getIdentitiesByPublicKeyHashesRequest) + .then((response) => { + const identitiesResponse = response.getIdentitiesList(); + console.log(dpp.identity.createFromBuffer(Buffer.from(identitiesResponse[0])).toJSON()); + }) + .catch((e) => console.error(e)); + }); +``` +```shell gRPCurl +# gRPCurl +# `public_key_hashes` must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "public_key_hashes":"uNFZGqdNRA4K+cC+FsVbvBQYR/c=" + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getIdentitiesByPublicKeyHashes +``` + +:::: + +::::{tab-set-code} + +```json Response (JavaScript) +// Response (JavaScript) +{ + "protocolVersion": 1, + "id": "4EfA9Jrvv3nnCFdSf7fad59851iiTRZ6Wcu6YVJ4iSeF", + "publicKeys": [ + { + "id": 0, + "type": 0, + "purpose": 0, + "securityLevel": 0, + "data": "Asi0dHtSjKxf3femzGNwLuBO19EzKQTghRA0PqANzlRq", + "readOnly": false + }, + { + "id": 1, + "type": 0, + "purpose": 0, + "securityLevel": 2, + "data": "AgHuKPhPVIU5BWfpOcK1hgELY6aeySyrU13JaoxxkTYC", + "readOnly": false + } + ], + "balance": 5255234422, + "revision": 0 +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "identities": [ + "AaRiaWRYIDASwZuY7AAzrds2zWS39RBnDyo1GkMEtfaZQUQobv2sZ2JhbGFuY2UbAAAAATk8g3ZocmV2aXNpb24AanB1YmxpY0tleXOCpmJpZABkZGF0YVghAsi0dHtSjKxf3femzGNwLuBO19EzKQTghRA0PqANzlRqZHR5cGUAZ3B1cnBvc2UAaHJlYWRPbmx59G1zZWN1cml0eUxldmVsAKZiaWQBZGRhdGFYIQIB7ij4T1SFOQVn6TnCtYYBC2Omnsksq1NdyWqMcZE2AmR0eXBlAGdwdXJwb3NlAGhyZWFkT25sefRtc2VjdXJpdHlMZXZlbAI=" + ], + "metadata": { + "height": "4216", + "coreChainLockedHeight": 858832, + "timeMs": "1688058626337", + "protocolVersion": 1 + } +} +``` + +:::: + +### getDataContract + +**Returns**: [Data Contract](../explanations/platform-protocol-data-contract.md) information for the requested data contract +**Parameters**: + +| Name | Type | Required | Description | +| ------- | ------- | -------- | -------------------------------------------------------------------------- | +| `id` | Bytes | Yes | A data contract `id` | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested data contract | + +> 📘 +> +> **Note**: When requesting proofs, the data requested will be encoded as part of the proof in the response. + +** Example Request and Response ** + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const cbor = require('cbor'); +const varint = require('varint'); + +const client = new DAPIClient(); + +const contractId = Identifier.from('GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'); +client.platform.getDataContract(contractId).then((response) => { + // Strip off protocol version (leading varint) and decode + const contractBuffer = Buffer.from(response.getDataContract()); + const protocolVersion = varint.decode(contractBuffer); + const contract = cbor.decode( + contractBuffer.slice(varint.encodingLength(protocolVersion), contractBuffer.length), + ); + console.dir(contract, { depth: 10 }); +}); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { PlatformPromiseClient, GetDataContractRequest }, +} = require('@dashevo/dapi-grpc'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const cbor = require('cbor'); +const varint = require('varint'); + +const platformPromiseClient = new PlatformPromiseClient( + 'https://seed-1.testnet.networks.dash.org:1443', +); + +const contractId = Identifier.from('GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'); +const contractIdBuffer = Buffer.from(contractId); +const getDataContractRequest = new GetDataContractRequest(); +getDataContractRequest.setId(contractIdBuffer); + +platformPromiseClient.getDataContract(getDataContractRequest) + .then((response) => { + // Strip off protocol version (leading varint) and decode + const contractBuffer = Buffer.from(response.getDataContract()); + const protocolVersion = varint.decode(contractBuffer); + const decodedDataContract = cbor.decode( + contractBuffer.slice(varint.encodingLength(protocolVersion), contractBuffer.length), + ); + console.dir(decodedDataContract, { depth: 5 }); + }) + .catch((e) => console.error(e)); +``` +```shell gRPCurl +# gRPCurl +# `id` must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "id":"5mjGWa9mruHnLBht3ntbfgodcSoJxA1XIfYiv1PFMVU=" + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getDataContract +``` + +:::: + +::::{tab-set-code} + +```json Response (JavaScript) +// Response (JavaScript) +{ + "$id": "Buffer(32) [Uint8Array] [ + 230, 104, 198, 89, 175, 102, 174, 225, + 231, 44, 24, 109, 222, 123, 91, 126, + 10, 29, 113, 42, 9, 196, 13, 87, + 33, 246, 34, 191, 83, 197, 49, 85 + ]", + "$schema": "https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "ownerId": "Buffer(32) [Uint8Array] [ + 48, 18, 193, 155, 152, 236, 0, 51, + 173, 219, 54, 205, 100, 183, 245, 16, + 103, 15, 42, 53, 26, 67, 4, 181, + 246, 153, 65, 68, 40, 110, 253, 172 + ]", + "version": 1, + "documents": { + "domain": { + "type": "object", + "indices": [ + { + "name": "parentNameAndLabel", + "unique": true, + "properties": [ + { "normalizedParentDomainName": "asc" }, + { "normalizedLabel": "asc" } + ] + }, + { + "name": "dashIdentityId", + "unique": true, + "properties": [ { "records.dashUniqueIdentityId": "asc" } ] + }, + { + "name": "dashAlias", + "properties": [ { "records.dashAliasIdentityId": "asc" } ] + } + ], + "$comment": "In order to register a domain you need to create a preorder. The preorder step is needed to prevent man-in-the-middle attacks. normalizedLabel + '.' + normalizedParentDomain must not be longer than 253 chars length as defined by RFC 1035. Domain documents are immutable: modification and deletion are restricted", + "required": [ + "label", + "normalizedLabel", + "normalizedParentDomainName", + "preorderSalt", + "records", + "subdomainRules" + ], + "properties": { + "label": { + "type": "string", + "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$", + "maxLength": 63, + "minLength": 3, + "description": "Domain label. e.g. 'Bob'." + }, + "records": { + "type": "object", + "$comment": "Constraint with max and min properties ensure that only one identity record is used - either a `dashUniqueIdentityId` or a `dashAliasIdentityId`", + "properties": { + "dashAliasIdentityId": { + "type": "array", + "$comment": "Must be equal to the document owner", + "maxItems": 32, + "minItems": 32, + "byteArray": true, + "description": "Identity ID to be used to create alias names for the Identity", + "contentMediaType": "application/x.dash.dpp.identifier" + }, + "dashUniqueIdentityId": { + "type": "array", + "$comment": "Must be equal to the document owner", + "maxItems": 32, + "minItems": 32, + "byteArray": true, + "description": "Identity ID to be used to create the primary name the Identity", + "contentMediaType": "application/x.dash.dpp.identifier" + } + }, + "maxProperties": 1, + "minProperties": 1, + "additionalProperties": false + }, + "preorderSalt": { + "type": "array", + "maxItems": 32, + "minItems": 32, + "byteArray": true, + "description": "Salt used in the preorder document" + }, + "subdomainRules": { + "type": "object", + "required": [ "allowSubdomains" ], + "properties": { + "allowSubdomains": { + "type": "boolean", + "$comment": "Only the domain owner is allowed to create subdomains for non top-level domains", + "description": "This option defines who can create subdomains: true - anyone; false - only the domain owner" + } + }, + "description": "Subdomain rules allow domain owners to define rules for subdomains", + "additionalProperties": false + }, + "normalizedLabel": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$", + "$comment": "Must be equal to the label in lowercase. This property will be deprecated due to case insensitive indices", + "maxLength": 63, + "description": "Domain label in lowercase for case-insensitive uniqueness validation. e.g. 'bob'" + }, + "normalizedParentDomainName": { + "type": "string", + "pattern": "^$|^[a-z0-9][a-z0-9-\\.]{0,61}[a-z0-9]$", + "$comment": "Must either be equal to an existing domain or empty to create a top level domain. Only the data contract owner can create top level domains.", + "maxLength": 63, + "minLength": 0, + "description": "A full parent domain name in lowercase for case-insensitive uniqueness validation. e.g. 'dash'" + } + }, + "additionalProperties": false + }, + "preorder": { + "type": "object", + "indices": [ + { + "name": "saltedHash", + "unique": true, + "properties": [ { "saltedDomainHash": "asc" } ] + } + ], + "$comment": "Preorder documents are immutable: modification and deletion are restricted", + "required": [ "saltedDomainHash" ], + "properties": { + "saltedDomainHash": { + "type": "array", + "maxItems": 32, + "minItems": 32, + "byteArray": true, + "description": "Double sha-256 of the concatenation of a 32 byte random salt and a normalized domain name" + } + }, + "additionalProperties": false + } + } +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "dataContract": "AaVjJGlkWCDmaMZZr2au4ecsGG3ee1t+Ch1xKgnEDVch9iK/U8UxVWckc2NoZW1heDRodHRwczovL3NjaGVtYS5kYXNoLm9yZy9kcHAtMC00LTAvbWV0YS9kYXRhLWNvbnRyYWN0Z293bmVySWRYIDASwZuY7AAzrds2zWS39RBnDyo1GkMEtfaZQUQobv2sZ3ZlcnNpb24BaWRvY3VtZW50c6JmZG9tYWlupmR0eXBlZm9iamVjdGdpbmRpY2Vzg6NkbmFtZXJwYXJlbnROYW1lQW5kTGFiZWxmdW5pcXVl9Wpwcm9wZXJ0aWVzgqF4Gm5vcm1hbGl6ZWRQYXJlbnREb21haW5OYW1lY2FzY6Fvbm9ybWFsaXplZExhYmVsY2FzY6NkbmFtZW5kYXNoSWRlbnRpdHlJZGZ1bmlxdWX1anByb3BlcnRpZXOBoXgccmVjb3Jkcy5kYXNoVW5pcXVlSWRlbnRpdHlJZGNhc2OiZG5hbWVpZGFzaEFsaWFzanByb3BlcnRpZXOBoXgbcmVjb3Jkcy5kYXNoQWxpYXNJZGVudGl0eUlkY2FzY2gkY29tbWVudHkBN0luIG9yZGVyIHRvIHJlZ2lzdGVyIGEgZG9tYWluIHlvdSBuZWVkIHRvIGNyZWF0ZSBhIHByZW9yZGVyLiBUaGUgcHJlb3JkZXIgc3RlcCBpcyBuZWVkZWQgdG8gcHJldmVudCBtYW4taW4tdGhlLW1pZGRsZSBhdHRhY2tzLiBub3JtYWxpemVkTGFiZWwgKyAnLicgKyBub3JtYWxpemVkUGFyZW50RG9tYWluIG11c3Qgbm90IGJlIGxvbmdlciB0aGFuIDI1MyBjaGFycyBsZW5ndGggYXMgZGVmaW5lZCBieSBSRkMgMTAzNS4gRG9tYWluIGRvY3VtZW50cyBhcmUgaW1tdXRhYmxlOiBtb2RpZmljYXRpb24gYW5kIGRlbGV0aW9uIGFyZSByZXN0cmljdGVkaHJlcXVpcmVkhmVsYWJlbG9ub3JtYWxpemVkTGFiZWx4Gm5vcm1hbGl6ZWRQYXJlbnREb21haW5OYW1lbHByZW9yZGVyU2FsdGdyZWNvcmRzbnN1YmRvbWFpblJ1bGVzanByb3BlcnRpZXOmZWxhYmVspWR0eXBlZnN0cmluZ2dwYXR0ZXJueCpeW2EtekEtWjAtOV1bYS16QS1aMC05LV17MCw2MX1bYS16QS1aMC05XSRpbWF4TGVuZ3RoGD9pbWluTGVuZ3RoA2tkZXNjcmlwdGlvbngZRG9tYWluIGxhYmVsLiBlLmcuICdCb2InLmdyZWNvcmRzpmR0eXBlZm9iamVjdGgkY29tbWVudHiQQ29uc3RyYWludCB3aXRoIG1heCBhbmQgbWluIHByb3BlcnRpZXMgZW5zdXJlIHRoYXQgb25seSBvbmUgaWRlbnRpdHkgcmVjb3JkIGlzIHVzZWQgLSBlaXRoZXIgYSBgZGFzaFVuaXF1ZUlkZW50aXR5SWRgIG9yIGEgYGRhc2hBbGlhc0lkZW50aXR5SWRganByb3BlcnRpZXOic2Rhc2hBbGlhc0lkZW50aXR5SWSnZHR5cGVlYXJyYXloJGNvbW1lbnR4I011c3QgYmUgZXF1YWwgdG8gdGhlIGRvY3VtZW50IG93bmVyaG1heEl0ZW1zGCBobWluSXRlbXMYIGlieXRlQXJyYXn1a2Rlc2NyaXB0aW9ueD1JZGVudGl0eSBJRCB0byBiZSB1c2VkIHRvIGNyZWF0ZSBhbGlhcyBuYW1lcyBmb3IgdGhlIElkZW50aXR5cGNvbnRlbnRNZWRpYVR5cGV4IWFwcGxpY2F0aW9uL3guZGFzaC5kcHAuaWRlbnRpZmllcnRkYXNoVW5pcXVlSWRlbnRpdHlJZKdkdHlwZWVhcnJheWgkY29tbWVudHgjTXVzdCBiZSBlcXVhbCB0byB0aGUgZG9jdW1lbnQgb3duZXJobWF4SXRlbXMYIGhtaW5JdGVtcxggaWJ5dGVBcnJhefVrZGVzY3JpcHRpb254PklkZW50aXR5IElEIHRvIGJlIHVzZWQgdG8gY3JlYXRlIHRoZSBwcmltYXJ5IG5hbWUgdGhlIElkZW50aXR5cGNvbnRlbnRNZWRpYVR5cGV4IWFwcGxpY2F0aW9uL3guZGFzaC5kcHAuaWRlbnRpZmllcm1tYXhQcm9wZXJ0aWVzAW1taW5Qcm9wZXJ0aWVzAXRhZGRpdGlvbmFsUHJvcGVydGllc/RscHJlb3JkZXJTYWx0pWR0eXBlZWFycmF5aG1heEl0ZW1zGCBobWluSXRlbXMYIGlieXRlQXJyYXn1a2Rlc2NyaXB0aW9ueCJTYWx0IHVzZWQgaW4gdGhlIHByZW9yZGVyIGRvY3VtZW50bnN1YmRvbWFpblJ1bGVzpWR0eXBlZm9iamVjdGhyZXF1aXJlZIFvYWxsb3dTdWJkb21haW5zanByb3BlcnRpZXOhb2FsbG93U3ViZG9tYWluc6NkdHlwZWdib29sZWFuaCRjb21tZW50eE9Pbmx5IHRoZSBkb21haW4gb3duZXIgaXMgYWxsb3dlZCB0byBjcmVhdGUgc3ViZG9tYWlucyBmb3Igbm9uIHRvcC1sZXZlbCBkb21haW5za2Rlc2NyaXB0aW9ueFtUaGlzIG9wdGlvbiBkZWZpbmVzIHdobyBjYW4gY3JlYXRlIHN1YmRvbWFpbnM6IHRydWUgLSBhbnlvbmU7IGZhbHNlIC0gb25seSB0aGUgZG9tYWluIG93bmVya2Rlc2NyaXB0aW9ueEJTdWJkb21haW4gcnVsZXMgYWxsb3cgZG9tYWluIG93bmVycyB0byBkZWZpbmUgcnVsZXMgZm9yIHN1YmRvbWFpbnN0YWRkaXRpb25hbFByb3BlcnRpZXP0b25vcm1hbGl6ZWRMYWJlbKVkdHlwZWZzdHJpbmdncGF0dGVybnghXlthLXowLTldW2EtejAtOS1dezAsNjF9W2EtejAtOV0kaCRjb21tZW50eGlNdXN0IGJlIGVxdWFsIHRvIHRoZSBsYWJlbCBpbiBsb3dlcmNhc2UuIFRoaXMgcHJvcGVydHkgd2lsbCBiZSBkZXByZWNhdGVkIGR1ZSB0byBjYXNlIGluc2Vuc2l0aXZlIGluZGljZXNpbWF4TGVuZ3RoGD9rZGVzY3JpcHRpb254UERvbWFpbiBsYWJlbCBpbiBsb3dlcmNhc2UgZm9yIGNhc2UtaW5zZW5zaXRpdmUgdW5pcXVlbmVzcyB2YWxpZGF0aW9uLiBlLmcuICdib2IneBpub3JtYWxpemVkUGFyZW50RG9tYWluTmFtZaZkdHlwZWZzdHJpbmdncGF0dGVybngmXiR8XlthLXowLTldW2EtejAtOS1cLl17MCw2MX1bYS16MC05XSRoJGNvbW1lbnR4jE11c3QgZWl0aGVyIGJlIGVxdWFsIHRvIGFuIGV4aXN0aW5nIGRvbWFpbiBvciBlbXB0eSB0byBjcmVhdGUgYSB0b3AgbGV2ZWwgZG9tYWluLiBPbmx5IHRoZSBkYXRhIGNvbnRyYWN0IG93bmVyIGNhbiBjcmVhdGUgdG9wIGxldmVsIGRvbWFpbnMuaW1heExlbmd0aBg/aW1pbkxlbmd0aABrZGVzY3JpcHRpb254XkEgZnVsbCBwYXJlbnQgZG9tYWluIG5hbWUgaW4gbG93ZXJjYXNlIGZvciBjYXNlLWluc2Vuc2l0aXZlIHVuaXF1ZW5lc3MgdmFsaWRhdGlvbi4gZS5nLiAnZGFzaCd0YWRkaXRpb25hbFByb3BlcnRpZXP0aHByZW9yZGVypmR0eXBlZm9iamVjdGdpbmRpY2VzgaNkbmFtZWpzYWx0ZWRIYXNoZnVuaXF1ZfVqcHJvcGVydGllc4GhcHNhbHRlZERvbWFpbkhhc2hjYXNjaCRjb21tZW50eEpQcmVvcmRlciBkb2N1bWVudHMgYXJlIGltbXV0YWJsZTogbW9kaWZpY2F0aW9uIGFuZCBkZWxldGlvbiBhcmUgcmVzdHJpY3RlZGhyZXF1aXJlZIFwc2FsdGVkRG9tYWluSGFzaGpwcm9wZXJ0aWVzoXBzYWx0ZWREb21haW5IYXNopWR0eXBlZWFycmF5aG1heEl0ZW1zGCBobWluSXRlbXMYIGlieXRlQXJyYXn1a2Rlc2NyaXB0aW9ueFlEb3VibGUgc2hhLTI1NiBvZiB0aGUgY29uY2F0ZW5hdGlvbiBvZiBhIDMyIGJ5dGUgcmFuZG9tIHNhbHQgYW5kIGEgbm9ybWFsaXplZCBkb21haW4gbmFtZXRhZGRpdGlvbmFsUHJvcGVydGllc/Q=", + "metadata": { + "height": "4253", + "coreChainLockedHeight": 889435, + "timeMs": "1684440772828", + "protocolVersion": 1 + } +} +``` + +:::: + +### getDocuments + +**Returns**: [Document](../explanations/platform-protocol-document.md) information for the requested document(s) +**Parameters**: + +> 🚧 - Parameter constraints +> +> The `where`, `order_by`, `limit`, `start_at`, and `start_after` parameters must comply with the limits defined on the [Query Syntax](../reference/query-syntax.md) page. +> +> Additionally, note that `where` and `order_by` must be [CBOR](https://tools.ietf.org/html/rfc7049) encoded. + +| Name | Type | Required | Description | +| ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | +| `data_contract_id` | Bytes | Yes | A data contract `id` | +| `document_type` | String | Yes | A document type defined by the data contract (e.g. `preorder` or `domain` for the DPNS contract) | +| `where` \* | Bytes | No | Where clause to filter the results (**must be CBOR encoded**) | +| `order_by` \* | Bytes | No | Sort records by the field(s) provided (**must be CBOR encoded**) | +| `limit` | Integer | No | Maximum number of results to return | +| ---------- | | | | +| _One_ of the following: | | | | +| `start_at` | Integer | No | Return records beginning with the index provided | +| `start_after` | Integer | No | Return records beginning after the index provided | +| ---------- | | | | +| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested document(s) | + +> 📘 +> +> **Note**: When requesting proofs, the data requested will be encoded as part of the proof in the response. + +** Example Request and Response ** + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const cbor = require('cbor'); +const varint = require('varint'); + +const client = new DAPIClient(); + +const contractId = Identifier.from('GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'); +client.platform.getDocuments(contractId, 'domain', { limit: 10 }).then((response) => { + for (const rawData of response.documents) { + // Strip off protocol version (leading varint) and decode + const documentBuffer = Buffer.from(rawData); + const protocolVersion = varint.decode(documentBuffer); + const document = cbor.decode( + documentBuffer.slice(varint.encodingLength(protocolVersion), documentBuffer.length), + ); + console.log(document); + } +}); +``` +```javascript JavaScript (dapi-grpc) +// JavaScript (dapi-grpc) +const { + v0: { PlatformPromiseClient, GetDocumentsRequest }, +} = require('@dashevo/dapi-grpc'); +const cbor = require('cbor'); +const Identifier = require('@dashevo/dpp/lib/Identifier'); +const varint = require('varint'); + +const platformPromiseClient = new PlatformPromiseClient( + 'https://seed-1.testnet.networks.dash.org:1443', +); + +const contractId = Identifier.from('GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec'); +const contractIdBuffer = Buffer.from(contractId); +const getDocumentsRequest = new GetDocumentsRequest(); +const type = 'domain'; +const limit = 10; + +getDocumentsRequest.setDataContractId(contractIdBuffer); +getDocumentsRequest.setDocumentType(type); +// getDocumentsRequest.setWhere(whereSerialized); +// getDocumentsRequest.setOrderBy(orderBySerialized); +getDocumentsRequest.setLimit(limit); +// getDocumentsRequest.setStartAfter(startAfter); +// getDocumentsRequest.setStartAt(startAt); + +platformPromiseClient.getDocuments(getDocumentsRequest) + .then((response) => { + for (const document of response.getDocumentsList()) { + // Strip off protocol version (leading varint) and decode + const documentBuffer = Buffer.from(document); + const protocolVersion = varint.decode(documentBuffer); + const decodedDocument = cbor.decode( + documentBuffer.slice(varint.encodingLength(protocolVersion), documentBuffer.length), + ); + console.log(decodedDocument); + } + }) + .catch((e) => console.error(e)); +``` +```shell Request (gRPCurl) +# gRPCurl +# Request documents +# `id` must be represented in base64 +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "data_contract_id":"5mjGWa9mruHnLBht3ntbfgodcSoJxA1XIfYiv1PFMVU=", + "document_type":"domain", + "limit":1 + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/getDocuments +``` + +:::: + +::::{tab-set-code} + +```json Response (JavaScript) +// Response (JavaScript) +{ + "$id": "", + "$type": "domain", + "label": "Dash01", + "records": { + "dashUniqueIdentityId": "" + }, + "$ownerId": "", + "$revision": 1, + "preorderSalt": "", + "subdomainRules": { "allowSubdomains": false }, + "$dataContractId": "", + "normalizedLabel": "dash01", + "normalizedParentDomainName": "dash" +} +``` +```json Response (gRPCurl) +// Response (gRPCurl) +{ + "documents": [ + "AatjJGlkWCACod79ik2tILNnybx5VepoaX2cceXDSogwSgxdWi9zYmUkdHlwZWZkb21haW5lbGFiZWx0Yzg4OWMyM2FiY2ZkYzU3NGNmZWJncmVjb3Jkc6FzZGFzaEFsaWFzSWRlbnRpdHlJZFggMBLBm5jsADOt2zbNZLf1EGcPKjUaQwS19plBRChu/axoJG93bmVySWRYIDASwZuY7AAzrds2zWS39RBnDyo1GkMEtfaZQUQobv2saSRyZXZpc2lvbgFscHJlb3JkZXJTYWx0WCAkJyav6iQVX7hFrUFagKC+xddHsyA5Wo/NdvejXt6aSG5zdWJkb21haW5SdWxlc6FvYWxsb3dTdWJkb21haW5z9W8kZGF0YUNvbnRyYWN0SWRYIOZoxlmvZq7h5ywYbd57W34KHXEqCcQNVyH2Ir9TxTFVb25vcm1hbGl6ZWRMYWJlbHRjODg5YzIzYWJjZmRjNTc0Y2ZlYngabm9ybWFsaXplZFBhcmVudERvbWFpbk5hbWVg" + ], + "metadata": { + "height": "4254", + "coreChainLockedHeight": 889435, + "timeMs": "1684440970270", + "protocolVersion": 1 + } +} +``` + +:::: + +### waitForStateTransitionResult + +**Returns**: The state transition hash and either a proof that the state transition was confirmed in a block or an error. +**Parameters**: + +| Name | Type | Required | Description | +| ----------------------- | ------- | -------- | -------------------------------- | +| `state_transition_hash` | Bytes | Yes | Hash of the state transition | +| `prove` | Boolean | Yes | Set to `true` to request a proof | + +> 📘 +> +> **Note**: When requesting proofs, the data requested will be encoded as part of the proof in the response. + +** Example Request** + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "\n\n\n\n" + } + [/block] +``` + +::::{tab-set-code} + +```javascript JavaScript (dapi-client) +// JavaScript (dapi-client) +const DAPIClient = require('@dashevo/dapi-client'); + +const client = new DAPIClient(); + +// Replace with your actual hash +const hash = ; +client.platform.waitForStateTransitionResult(hash, { prove: true }) + .then((response) => { + console.log(response); + }); + +``` +```shell Request (gRPCurl) +# gRPCurl +# Replace `your_state_transition_hash` with your own before running +# `your_state_transition_hash` must be represented in base64 +# Example: wEiwFu9WvAtylrwTph5v0uXQm743N+75C+C9DhmZBkw= +grpcurl -proto protos/platform/v0/platform.proto \ + -d '{ + "state_transition_hash":your_state_transition_hash, + "prove": "true" + }' \ + seed-1.testnet.networks.dash.org:1443 \ + org.dash.platform.dapi.v0.Platform/waitForStateTransitionResult +``` + +:::: + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "\n\n" + } + [/block] +``` + +## Deprecated Endpoints + +No endpoints were deprecated in Dash Platform v0.24, but the previous version of documentation can be [viewed here](https://dashplatform.readme.io/v0.23.0/docs/reference-dapi-endpoints-platform-endpoints). + +## Code Reference + +Implementation details related to the information on this page can be found in: + +- The [Platform repository](https://github.com/dashevo/platform/tree/master/packages/dapi) `packages/dapi/lib/grpcServer/handlers/core` folder +- The [Platform repository](https://github.com/dashevo/platform/tree/master/packages/dapi-grpc) `packages/dapi-grpc/protos` folder \ No newline at end of file diff --git a/docs/reference/dapi-endpoints.md b/docs/reference/dapi-endpoints.md new file mode 100644 index 000000000..f1ad79a9f --- /dev/null +++ b/docs/reference/dapi-endpoints.md @@ -0,0 +1,67 @@ +```{eval-rst} +.. _reference-dapi-endpoints: +``` + +# DAPI Endpoints + +[DAPI](../explanations/dapi.md) 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. + +## JSON-RPC Endpoints + +| Layer | Endpoint | Description | +| :---: | ---------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| 1 | [`getBestBlockHash`](../reference/dapi-endpoints-json-rpc-endpoints.md#getbestblockhash) | Returns block hash of the chaintip | +| 1 | [`getBlockHash`](../reference/dapi-endpoints-json-rpc-endpoints.md#getblockhash) | Returns block hash of the requested block | +| 1 | [`getMnListDiff`](../reference/dapi-endpoints-json-rpc-endpoints.md#getmnlistdiff) | Returns masternode list diff for the provided block hashes | + +## gRPC Endpoints + +### Core gRPC Service + +| Layer | Endpoint | | +| :---: | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | [`broadcastTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#broadcasttransaction) | Broadcasts the provided transaction | +| 1 | [`getBlock`](../reference/dapi-endpoints-core-grpc-endpoints.md#getblock) | Returns information for the requested block | +| 1 | [`getStatus`](../reference/dapi-endpoints-core-grpc-endpoints.md#getstatus) | Returns blockchain status information | +| 1 | [`getTransaction`](../reference/dapi-endpoints-core-grpc-endpoints.md#gettransaction) | Returns details for the requested transaction | +| 1 | [`subscribeTo` `BlockHeadersWithChainLocks`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetoblockheaderswithchainlocks) | Returns the requested block headers along with the associated ChainLocks.
_Added in Dash Platform v0.22_ | +| 1 | [`subscribeTo` `TransactionsWithProofs`](../reference/dapi-endpoints-core-grpc-endpoints.md#subscribetotransactionswithproofs) | Returns transactions matching the provided bloom filter along with the associated [`islock` message](https://docs.dash.org/projects/core/en/stable/docs/reference/p2p-network-instantsend-messages.html#islock) and [merkle block](https://docs.dash.org/projects/core/en/stable/docs/reference/p2p-network-data-messages.html#merkleblock) | + +### Platform gRPC Service + +In addition to providing the request data, the following endpoints can also provide proofs that the data returned is valid and complete. + +| Layer | Endpoint | | +| :---: | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| 2 | [`broadcastStateTransition`](../reference/dapi-endpoints-platform-endpoints.md#broadcaststatetransition) | Broadcasts the provided State Transition | +| 2 | [`getIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getidentity) | Returns the requested identity | +| 2 | [`getIdentitiesByPublicKeyHashes`](../reference/dapi-endpoints-platform-endpoints.md#getidentitiesbypublickeyhashes) | Returns the identities associated with the provided public key hashes
_Added in Dash Platform v0.16_ | +| 2 | [`getDataContract`](../reference/dapi-endpoints-platform-endpoints.md#getdatacontract) | Returns the requested data contract | +| 2 | [`getDocuments`](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) | Returns the requested document(s) | +| 2 | [`waitForStateTransitionResult`](../reference/dapi-endpoints-platform-endpoints.md#waitforstatetransitionresult) | Responds with the state transition hash and either a proof that the state transition was confirmed in a block or an error | + + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "
\n\n" + } + [/block] +``` + +> 📘 +> +> The previous version of documentation can be [viewed here](https://dashplatform.readme.io/v0.23.0/docs/reference-dapi-endpoints). + +```{toctree} +:maxdepth: 2 +:titlesonly: +:hidden: + +dapi-endpoints-json-rpc-endpoints +dapi-endpoints-grpc-overview +dapi-endpoints-core-grpc-endpoints +dapi-endpoints-platform-endpoints +``` diff --git a/docs/reference/data-contracts.md b/docs/reference/data-contracts.md new file mode 100644 index 000000000..2308335af --- /dev/null +++ b/docs/reference/data-contracts.md @@ -0,0 +1,277 @@ +# Data Contracts + +## Overview + +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: [documents](#documents) and [definitions](#definitions). All data contracts must define one or more documents, whereas definitions are optional and may not be used for simple contracts. + +## Documents + +The `documents` object defines each type of document required by the data contract. At a minimum, a document must consist of 1 or more properties. Documents may also define [indices](#document-indices) and a list of [required properties](#required-properties-optional). The `additionalProperties` properties keyword must be included as described in the [constraints](#additional-properties) section. + +The following example shows a minimal `documents` object defining a single document (`note`) that has one property (`message`). + +```json +{ + "note": { + "properties": { + "message": { + "type": "string" + } + }, + "additionalProperties": false + } +} +``` + +### Document Properties + +The `properties` object defines each field that will be used by a document. Each field consists of an object that, at a minimum, must define its data `type` (`string`, `number`, `integer`, `boolean`, `array`, `object`). + +Fields may also apply a variety of optional JSON Schema constraints related to the format, range, length, etc. of the data. A full explanation of the capabilities of JSON Schema is beyond the scope of this document. For more information regarding its data types and the constraints that can be applied, please refer to the [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference/index.html) documentation. + +#### Special requirements for `object` properties + +The `object` type is required to have properties defined either directly or via the data contract's [$defs](#definitions). For example, the `body` property shown below is an object containing a single string property (`objectProperty`): + +```javascript +const contractDocuments = { + message: { + type: "object", + properties: { + body: { + type: "object", + properties: { + objectProperty: { + type: "string" + }, + }, + additionalProperties: false, + }, + header: { + type: "string" + } + }, + additionalProperties: false + } +}; +``` + +#### Property Constraints + +There are a variety of constraints currently defined for performance and security reasons. + +| Description | Value | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Minimum number of properties | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L22) | +| Maximum number of properties | [100](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L23) | +| Minimum property name length | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L20) (Note: minimum length was 3 prior to v0.23) | +| Maximum property name length | [64](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L20) | +| Property name characters | Alphanumeric (`A-Z`, `a-z`, `0-9`)
Hyphen (`-`)
Underscore (`_`) | + +Prior to Dash Platform v0.23 there were stricter limitations on minimum property name length and the characters that could be used in property names. + +#### Required Properties (Optional) + +Each document may have some fields that are required for the document to be valid and other fields that are optional. Required fields are defined via the `required` array which consists of a list of the field names from the document that must be present. The `required` object should be excluded for documents without any required properties. + +```json +"required": [ + "", + "" +] +``` + +**Example** +The following example (excerpt from the DPNS contract's `domain` document) demonstrates a document that has 6 required fields: + +```json +"required": [ + "nameHash", + "label", + "normalizedLabel", + "normalizedParentDomainName", + "preorderSalt", + "records" +], +``` + +### Document Indices + +Document indices may be defined if indexing on document fields is required. The `indices` object should be excluded for documents that do not require indices. + +The `indices` array consists of: + +- One or more objects that each contain: + - A unique `name` for the index + - A `properties` array composed of a `` object for each document field that is part of the index (sort order: [`asc` only](https://github.com/dashevo/platform/pull/435) for Dash Platform v0.23) + - An (optional) `unique` element that determines if duplicate values are allowed for the document + +> 🚧 Compound Indices +> +> When defining an index with multiple properties (i.e a compound index), the order in which the properties are listed is important. Refer to the [mongoDB documentation](https://docs.mongodb.com/manual/core/index-compound/#prefixes) for details regarding the significance of the order as it relates to querying capabilities. Dash uses [GroveDB](https://github.com/dashevo/grovedb) which works similarly but does requiring listing all the index's fields in query order by statements. + +```json +"indices": [ + { + "properties": [ + { "": "" }, + { "": "" } + ], + "unique": true|false + }, + { + "properties": [ + { "": "" }, + ], + } +] +``` + +#### Index Constraints + +For performance and security reasons, indices have the following constraints. These constraints are subject to change over time. + +| Description | Value | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L413) / [32](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L414) | +| Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L446) | +| Maximum number of unique indices | [3](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L40) | +| Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json#L433) | +| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L39) | +| **Note: Dash Platform v0.22+. [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225)**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L43) | +| **Note: Dash Platform v0.22+. [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225)**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/data_contract/validation/data_contract_validator.rs#L44) | +| Usage of `$id` in an index [disallowed](https://github.com/dashpay/platform/pull/178) | N/A | + +**Example** +The following example (excerpt from the DPNS contract's `preorder` document) creates an index on `saltedDomainHash` that also enforces uniqueness across all documents of that type: + +```json +"indices": [ + { + "properties": [ + { "saltedDomainHash": "asc" } + ], + "unique": true + } +], +``` + +### Full Document Syntax + +This example syntax shows the structure of a documents object that defines two documents, an index, and a required field. + +```json +{ + "": { + "type": "object", + "properties": { + "": { + "type": "" + }, + "": { + "type": "" + }, + }, + "indices": [ + { + "name": "", + "properties": [ + { + "": "asc" + } + ], + "unique": true|false + }, + ], + "required": [ + "" + ] + "additionalProperties": false + }, + "": { + "type": "object", + "properties": { + "": { + "type": "" + }, + "": { + "type": "" + }, + }, + "additionalProperties": false + }, +} +``` + +## Definitions + +> ❗️ Definitions are currently unavailable + +The optional `$defs` object enables definition of aspects of a schema that are used in multiple places. This is done using the JSON Schema support for [reuse](https://json-schema.org/understanding-json-schema/structuring.html#reuse). + +Items defined in `$defs` may then be referenced when defining `documents` through use of the `$ref` keyword. Properties defined in the `$defs` object must meet the same criteria as those defined in the `documents` object. Data contracts can only use the `$ref` keyword to reference their own `$defs`. Referencing external definitions is not supported by the platform protocol. + +**Example** +The following example shows a definition for a `message` object consisting of two properties: + +```json +{ + // Preceeding content truncated ... + "$defs": { + "message": { + "type": "object", + "properties": { + "timestamp": { + "type": "number" + }, + "description": { + "type": "string" + } + }, + "additionalProperties": false + } + } +} +``` + +### General Constraints + +There are a variety of constraints currently defined for performance and security reasons. The following constraints are applicable to all aspects of data contracts. Unless otherwise noted, these constraints are defined in the platform's JSON Schema rules (e.g. [rs-dpp data contract meta schema](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/schema/data_contract/dataContractMeta.json)). + +#### Keyword + +> 🚧 +> +> The `$ref` keyword has been [disabled](https://github.com/dashevo/platform/pull/300) since Platform v0.22. + +| Keyword | Constraint | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `default` | Restricted - cannot be used (defined in DPP logic) | +| `propertyNames` | Restricted - cannot be used (defined in DPP logic) | +| `uniqueItems: true` | `maxItems` must be defined (maximum: 100000) | +| `pattern: ` | `maxLength` must be defined (maximum: 50000) | +| `format: ` | `maxLength` must be defined (maximum: 50000) | +| `$ref: ` | **Temporarily disabled**
`$ref` can only reference `$defs` -
remote references not supported | +| `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` | Disabled for data contracts | +| `dependencies` | Not supported. Use `dependentRequired` and `dependentSchema` instead | +| `additionalItems` | Not supported. Use `items: false` and `prefixItems` instead | +| `patternProperties` | Restricted - cannot be used for data contracts | +| `pattern` | Accept only [RE2](https://github.com/google/re2/wiki/Syntax) compatible regular expressions (defined in DPP logic) | + +#### Data Size + +**Note:** These constraints are defined in the Dash Platform Protocol logic (not in JSON Schema). + +All serialized data (including state transitions) is limited to a maximum size of [16 KB](https://github.com/dashpay/platform/blob/v0.24.5/packages/rs-dpp/src/util/serializer.rs#L8). + +#### Additional Properties + +Although JSON Schema allows additional, undefined properties [by default](https://json-schema.org/understanding-json-schema/reference/object.html?#properties), they are not allowed in Dash Platform data contracts. Data contract validation will fail if they are not explicitly forbidden using the `additionalProperties` keyword anywhere `properties` are defined (including within document properties of type `object`). + +Include the following at the same level as the `properties` keyword to ensure proper validation: + +```json +"additionalProperties": false +``` \ No newline at end of file diff --git a/docs/reference/frequently-asked-questions.md b/docs/reference/frequently-asked-questions.md new file mode 100644 index 000000000..fd29effb3 --- /dev/null +++ b/docs/reference/frequently-asked-questions.md @@ -0,0 +1,33 @@ +# Frequently Asked Questions + +## What is Evolution? +"Evolution" is a codename used to reference various products. It includes "Dash Platform," a FireBase-like platform for developing backends for websites and applications, hosted on the masternode network. + +Also, the term " Evolution" refers to several other products that we are going to develop on top of the platform. An example of such an app is DashPay - an easy to use payment solution with usernames and contact lists. + +## How does a DAPI client discover the IP address of masternodes hosting DAPI endpoints? +The DNS seed will provide a deterministic masternode list (DML) to the client. More on the deterministic MN list can be found here: + + - DML spec: https://github.com/dashpay/dips/blob/master/dip-0003.md + - DML verification: https://github.com/dashpay/dips/blob/master/dip-0004.md + +## Why can't I connect to DAPI from a page served over HTTPS? + +Modern browsers block connections to insecure content when the main page is loaded securely. At the moment, there are technical obstacles to serving DAPI content over HTTPS. Until then, the only way to test DAPI from a web page is to serve the web page insecurely. Dash Core team is evaluating different ways to work around this browser restriction and have a trustworthy connection to DAPI. + +## Will it be possible to use apps with only an identity, or will a DPNS name have to be registered first? + +Apps can interact with an identity whether or not it has a DPNS name registered. Someone may create an app that requires one, but it's not a platform restriction. + +## Should it be possible to create multiple identities using a single private key? + +It may not be a very good practice, but this is not restricted. + +## Will DAPI RPCs always be free? How will DoS attacks be mitigated? + +Right now there's only IP based rate limits. Generally Core team wants platform data to be available for everyone, so there are no plans today to have paid queries. + +## When I try to load the Dash javascript library, why is there is a syntax error "Invalid regular expression"? + +This can be caused by loading the script with the wrong character encoding. The `dash` npm package uses UTF-8 encoding. Try this: +`` \ No newline at end of file diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md new file mode 100644 index 000000000..27baa8fae --- /dev/null +++ b/docs/reference/glossary.md @@ -0,0 +1,150 @@ +# Glossary + +## Application +The combination of Application Identity, Data Contract, and Application State that together represent a Dash Platform Application + +## Application State +The collection of documents created by users during their use of an application + +## Block +One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the [core blockchain](#core-chain) + +## Block Reward +The amount that miners may claim as a reward for creating a block. Equal to the sum of the block subsidy (newly available duffs) plus the transactions fees paid by transactions included in the block + +## ChainLock + +Defined in [DIP8](https://github.com/dashpay/dips/blob/master/dip-0008.md), ChainLocks are a method of using an LLMQ to threshold sign a block immediately after it is propagated by the miner in order to enforce the first-seen rule. This powerful method of mitigating 51% mining attacks results in near-instant consensus on the valid chain. + +## Classical Transactions +Standard Dash transactions moving Dash on the core blockchain ledger + +## Coinbase Transaction +The first transaction in a block. Always created by a miner, it includes a single coinbase. + +## Core Chain +Layer 1 blockchain used for payments, governance, and providing the foundation for tier 2 masternode infrastructure (LLMQs, DML, PoSe, etc.) + +## Credits +Means of paying fees on the layer 2 platform + +## DAPI +Dash's decentralized API for interacting with the core blockchain (layer 1) and the platform (layer 2) + +## DAPI Client +An HTTP Client that connects to DAPI to enable users to read and write data to the Dash platform + +## DashPay +Dash Platform based wallet supporting payments via usernames + +## DashPay Contact Request +A platform document that defines a one way relationship between a sender and a recipient. It includes an encrypted extended public key which will allow the sender to pay the recipient using addresses that other users have no knowledge of. The sender creates and publishes this document. When two users have both sent contact requests to each other, then each is considered a fully established contact with the other. + +## DashPay Contact Info +A platform document containing an identity's set of private information related to other identities that are contacts. + +## DashPay Profile +A platform document containing a set of public information for an identity that includes a display name, a public message (bio/status) and an avatar URL. The display name and avatar help complement the identity's username from DPNS to better visually identify an identity in a user interface. An identity can only have a single DashPay profile. + +## Dash Core +Layer 1 core blockchain reference client + +## Data Contract +The database schema a developer submits in order to start using Dash Platform as a back end for their application + +## Dash Platform Application +A client application that leverages Dash Platform services + +## Dash Platform Naming Service (DPNS) +A service used to register names on the Dash Platform. Can be extended to work in a DNS-like mode. Implemented as an application on top of the platform that leverages platform capabilities + +## Dash Platform Protocol (DPP) +Describes data structures and validation rules for the data structures used by the platform (e.g. Data Contract, Document, and State Transition). Data structures are defined using JSON-Schema based format + +## Decentralized Autonomous Organization (DAO) +An organization where decision making is governed according to a set of rules that is transparent, controlled by organization members, and lacking any central authority. Financial records are tracked using a blockchain, which provides the transparency and trust required by organization members. + +## Devnet + +A development environment in which developers can obtain and spend Dash that has no real-world value on a network that is very similar to the Dash [mainnet](#mainnet). Multiple independent devnets can coexist without interference. Devnets can be either public or private networks. See the Testing Applications page for a more detailed description of network types. + +## Direct Settlement Payment Channel (DSPC) + +In DashPay, established contacts have address spaces to send and receive from each other. When these are present either in one way or bi-directional we will call this a direct settlement payment channel. + +## Distributed Key Generation (DKG) +Distributed key generation (DKG) is a cryptographic process in which multiple parties contribute to the calculation of a shared public and private key set. In Dash, DKG is used to generate a BLS key pair for use in a [long-living masternode quorum](#long-living-masternode-quorum-llmq) (LLMQ) to perform threshold signing on network messages. Further detail can be found in [DIP-6 Long-Living Masternode Quorums](https://github.com/dashpay/dips/blob/master/dip-0006.md#llmq-dkg-network-protocol). + +## Document +A data entry, similar to a document in a document-oriented database. Represented as a JSON. An atomic entity used by the platform to store the user-submitted data + +## Drive +Layer 2 platform storage + +## Layer (1, 2, 3) +- Layer 1: Core blockchain and [Dash Core](#dash-core) +- Layer2: Drive and DAPI +- Layer 3: DAPI clients + +## Local network + +A configuration unique to [dashmate](https://www.npmjs.com/package/dashmate) that uses Dash Core's [regtest](#regtest) network type to create a multi-node network on a single computer. This configuration allows developers to work independently on their own network for testing and development. + +## Long Living Masternode Quorum (LLMQ) +Deterministic subset of the global deterministic masternode list used to perform threshold signing of consensus-related messages + +## Mainnet + +The original and main network for Dash transactions, where transaction have real economic value. + +## Masternode +2nd-tier collateralized Node in the Dash P2P network, performing additional functions and forming a provision layer + +## Platform Chain +Layer 2 blockchain that propagates platform data among masternodes, propagates platform blocks among masternodes, applies Layer 2 consensus, authoritatively orders state transitions, and controls platform state consistency + +## Platform State +All layer 2 data including contracts, documents (user data), credit balance, identity (username) + +## practical Byzantine Fault Tolerance (pBFT) +A consensus algorithm designed to work efficiently in asynchronous environments while assuming the presence of adversarial actors. Advantages of pBFT include energy efficiency, transaction finality, and low reward variance. + +## Proof of Service (PoSe) +Ability to trustlessly prove that a [masternode](#masternode) provided the required service to the network in order to earn a reward + +## Proof of Work (PoW) +Ability to trustlessly prove that a node completed a certain amount of work during the process of confirming a new block to the blockchain. + +## Quorum +Group of masternodes signing some action, formation of the group determined by via some determination algorithm + +## Quorum Signature +BLS signature resulting from some agreement within a masternode quorum + +## Regtest + +A local regression testing environment in which developers can almost instantly generate blocks on demand for testing events, and can create private Dash with no real-world value. See the Testing Applications page for a more detailed description of network types. + +## Simple Payment Verification +A method for verifying if transactions are part of a block without downloading the whole block. This is useful for lightweight clients which don't run continuously and which don't have the storage space or bandwidth for a full copy of the blockchain. + +## Special Transactions +Transactions containing an extra payload using the format defined by [DIP-2](https://github.com/dashpay/dips/blob/master/dip-0002.md) + +## State Machine +The application that validates state transitions and updates state in Drive + +## State Transition +The change a user does to the application and platforms states. Consists of an array of documents _or_ one data contract, the id of the application to which the change is made, and a user signature + +## Tenderdash +Dash fork of [Tendermint](https://tendermint.com/core) modified for use in Dash Platform. See [Platform Consensus](../explanations/platform-consensus.md) for more information. + +## Testnet + +A global testing environment in which developers can obtain and spend Dash that has no real-world value on a network that is very similar to the Dash [mainnet](#mainnet). See the Testing Applications page for a more detailed description of network types. + +See: [Intro to Testnet](../intro/to-testnet.md) for more information + +## Validator Set +The group of masternodes responsible for the layer 2 blockchain (platform chain) consensus at a given time. They vote on the content of each platform chain block and are analogous to miners on the layer 1's core blockchain \ No newline at end of file diff --git a/docs/reference/platform-proofs.md b/docs/reference/platform-proofs.md new file mode 100644 index 000000000..86fa39338 --- /dev/null +++ b/docs/reference/platform-proofs.md @@ -0,0 +1,141 @@ +# Platform Proofs + +>❗️ Platform v0.22.0 +> +> Note: As part of the transition from MongoDB to Dash's [GroveDB](https://github.com/dashevo/grovedb), proofs will be not be available for at least the initial version of Platform v0.22. + +Since data verification is a critical aspect of Dash Platform, all [Platform endpoints](../reference/dapi-endpoints-platform-endpoints.md) can provide an optional proof that the response is correct. Set the optional `prove` parameter (`"prove": true`) in the request to receive a proof that contains the requested data. + +## Proof Structure + +Each proof consists of four parts: + +| Field | Type | Description | +|-|-|-| +| rootTreeProof | Bytes (base64) | Merkle path to the `storeTreeProof` | +| [storeTreeProof](#store-tree-proof) | Object | Object containing data and proofs from one or more store trees. Currently there are 5 types of trees: identities, public key hash to identity IDs, data contracts, documents, and state transitions. The merk tree proofs contain the store root hash, the merkle path, and the requested data | +| signatureLlmqHash | Bytes (base64) | Hash of the LLMQ that created the `signature` | +| signature | Bytes (base64) | Signature of the merkle root of the `rootTreeProof` | + +```json +{ + "proof": { + "rootTreeProof": "v+99FytmaUPDP65HthQllBL1JDXt2Zu/kzFEQRw66rT6QF8LYwKmAP6fEaXLaSVPe/OHfTDEG2+KoLxjyirQIDmDy4lNl4yhJE5stQZGO2G/74H4MxN/a/luSWkqE1vF", + "storeTreeProofs": { + "identitiesProof": "AeFWk/kp1HXlJMzA4Wwov+NifjrocHebDU8863BDtp4aAlHeCG7lcVi52OSo+U5LlykSjARXJ5Rv6hE+mui+RnUFEAGJ24nuRAkAZMjcRp1sbzLPwYxxagTD12YTLksNN+y1cAKxpoxQdHpC/RQN7cq7fE/z6+0ccpoVQbobRPGtfCSj4hABjDZM5byc2NbfTNb7NGWDKm0bAoZjaAHx+C7Gn2cKmfsCIyWhRVW4QDdnoxTDvJuHCKJeK8dWzsrfVuUYTejcw6MQAX4HE7Y1WuXPPAG6uU9vewbilQnhjLzSTYNVLsdkxmLfAmwhTWaLg5A+tuxnzvdPhNU+bmbyMHr4PIL8Z+ScbyikEAFtCRA34Yl9tuEzqAF1EdiY0U9/jNoyEpU2vkPLO7xUYAJEmc3z/snpNWPXQdMrrAAHqWNhwddPRSMrF0epC75qThADIHwTzudaE/98V8XvldeYDIpe0yZOW3s6iK0jdqsoOJz3AIABAAAApGJpZFggfBPO51oT/3xXxe+V15gMil7TJk5bezqIrSN2qyg4nPdnYmFsYW5jZRoAp8O4aHJldmlzaW9uAGpwdWJsaWNLZXlzgaNiaWQAZGRhdGFYIQOF51gOnYk5T+0EdR4DSKUkDo5TmEDMoMxdxOy7FnqKjmR0eXBlABEREQL0H2yuZyiMzKzHmrXCwp/W7DuDkZYlEx7JE5xlYGhJxhABJt9KcGPXHnE7hzz3aQ9PpYDhvILZCDUOu5BBwV66RPYRERECyX/3Cih/TZdB9cVOX8Xmo2UEPNvt9iOufQ4oCmoytwsQAU14wPdQ7t7FfsfXx9fGnwbZk8h1uxoWd0MroZRO0YVXEQ==", + "publicKeyHashesToIdentityIdsProof": "Afe33zbtlgXiPzJ1+zSjjVttIBmiKHy1iEc7uOKqxVUGAjs/C8gAlTwbVhnRBqbhGFkz0Kg/0Cr8mAV41WXxocBpEAGVsw8werVp7Cka+OSMj3GgkX2Da0FMMGGIJx4aZxPwPhE=" + }, + "signatureLlmqHash": "AAACBMSv9TakRGNdP+yvxw/+VCgIbALhn314jLOpgcY=", + "signature": "Fhl8Md9MDlB0Tlekgjoj+Qe5PdKeUDyL6svVmcP9ttRu1UB7oeAGaSMAyqJI+k/HA/jAfPFb9+q9gepdZDhj8zHrl5BRSaAiBPEtM6CTQ+eCWUvqOlDENVQfubrXLLdk" + }, + "metadata": { + "height": "7986", + "coreChainLockedHeight": 57585 + } +} +``` + +### Root tree proof + +> 📘 +> +> Details regarding the root tree proofs and their verification will be provided in a future update to this page. + +### Store tree proof + +Store tree proofs are based on a modified version of [Merk](https://github.com/nomic-io/merk/). Some details from the Merk documentation are included below. Additional details are available in the [Algorithms document](https://github.com/nomic-io/merk/blob/develop/docs/algorithms.md) on the Merk repository. + +Dash Platform 0.21.0 introduced updates to support returning multiple store tree proofs. Each response that requests proofs will receive one or more of the following: + - `identitiesProof` + - `publicKeyHashesToIdentityIdsProof` + - `dataContractsProof` + - `documentsProof` + - `stateTransitionProof` + +> 🚧 +> +> Dash Platform 0.21.0 introduced a 4 byte [protocol version](https://github.com/dashevo/js-dpp/pull/325) that is prepended to the binary format and is not part of the CBOR-encoded data. When parsing proofs it is necessary to exclude these bytes before decoding the returned data with CBOR. + +#### Structure + +Merk proofs are a list of stack-based operators and node data, with 3 possible operators: `Push(node)`, `Parent`, and `Child`. A stream of these operators can be processed by a verifier in order to reconstruct a sparse representation of part of the tree, in a way where the data can be verified against a known root hash. + +The value of `node` in a `Push` operation can be one of three types: + +* `Hash(hash)` - The hash of a node +* `KVHash(hash)` - The key/value hash of a node +* `KV(key, value)` - The key and value of a node + +#### Binary Format + +We can efficiently encode these proofs by encoding each operator as follows: + +| Operator | Op. Value | Size | Description | +|-|:-:|-|-| +| Push(Hash(hash)) | `0x01` | 32 bytes | Node hash | +| Push(KVHash(hash)) | `0x02` | 32 bytes | Node key/value hash | +| Push(KV(key, value)) | `0x03` | < 1-byte key length >
< n-byte key >
< 2-byte value length >
< n-byte value > | Node key/value | + +This results in a compact binary representation, with a very small space overhead (roughly 2 bytes per node in the proof (1 byte for the Push operator type flag, and 1 byte for a Parent or Child operator), plus 3 bytes per key/value pair (1 byte for the key length, and 2 bytes for the value length)). + +## Retrieving response data from proofs + +The function below shows a simple example of parsing a response's `storeTreeProof` to retrieve the data asked for by the request: + +```javascript +// Get data from base64 encoded store tree proof +function getStoreProofData(storeProof) { + const values = []; + const buf = Buffer.from(storeProof, 'base64'); + + let x = 0; + let valueFound = false; + while (x < buf.length) { + const type = buf.readUInt8(x); + x += 1; + + switch (type) { + case 0x01: { // Hash + x += hashLength; + break; + } + + case 0x02: { // Key/value hash + x += hashLength; + break; + } + + case 0x03: { // Key / Value + const keySize = buf.readUInt8(x); + x += (1 + keySize); + + const valueSize = buf.readUInt16BE(x); + x += 2; + + // Value + // Start at x+4 because the first 4 bytes are the protocol version + // and are not part of the CBOR value + const value = buf.toString('hex', x + 4, x + valueSize); + x += valueSize; + const map = cbor.decode(value); + + valueFound = true; + values.push(map); + break; + } + + case 0x10: // Parent + break; + + case 0x11: // Child + break; + + default: + console.log(`Unknown type: ${type.toString(16)}`); + break; + } + } + console.log(`Value found: ${valueFound}`); + return values; +} +``` \ No newline at end of file diff --git a/docs/reference/query-syntax.md b/docs/reference/query-syntax.md new file mode 100644 index 000000000..fd04601ce --- /dev/null +++ b/docs/reference/query-syntax.md @@ -0,0 +1,194 @@ +# Query Syntax + +## Overview + +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/dashevo/grovedb). See details in pull requests [77](https://github.com/dashevo/platform/pull/77) and [230](https://github.com/dashevo/platform/pull/230) that implemented these changes. +> +> Query validation details may be found [here](https://github.com/dashevo/platform/blob/master/packages/js-drive/lib/document/query/validateQueryFactory.js) along with the associated validation [tests](https://github.com/dashevo/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`. + +```json Syntax +{ + where: [ + [, , ], + [, , [, ]] + ] +} +``` + +### Fields + +Valid fields consist of the indices defined for the document being queried. For example, the [DPNS data contract](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json) defines three indices: + +| Index Field(s) | Index Type | Unique | +| - | - | :-: | +| [normalizedParentDomainName, normalizedLabel](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L5-L16) | Compound | Yes | +| [records.dashUniqueIdentityId](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L17-L25) | Single Field | Yes | +| [records.dashAliasIdentityId](https://github.com/dashevo/platform/blob/master/packages/dpns-contract/schema/dpns-contract-documents.json#L26-L33) | Single Field | No | + +```{eval-rst} +.. + Commented out info + [block:html] + { + "html": "
\n\n" + } + [/block] +``` + +### Comparison Operators + +#### Equal + +| Name | Description | +| :-: | - | +| == | Matches values that are equal to a specified value | + +#### 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 | +| <= | Matches values that are less than or equal to a specified value | +| >= | Matches values that are greater than or equal to a specified value | +| > | 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 + +### Evaluation Operators + +| Name | Description | +| :-: | - | +| startsWith | Selects documents where the value of a field begins with the specified characters (string, <= 255 characters). Must include an `orderBy` statement. | + +### Operator Examples + +```json < +{ + where: [ + ['nameHash', '<', '56116861626961756e6176657a382e64617368'], + ], +} +``` +```json in +{ + where: [ + ['normalizedParentDomainName', '==', 'dash'], + // Return all matching names from the provided array + ['normalizedLabel', 'in', ['alice', 'bob']], + ] +} +``` +```json startsWith +{ + where: [ + ['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/dashevo/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/dashevo/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/dashevo/platform/pull/77 +{ + where: [ + // Return `scores` documents where the results contain + // elements in the range 80-90 + ['scores', 'elementMatch', + [ + ['results', '>=', '80'], + ['results', '<=', '90'] + ], + ], + ] +} +``` + +## 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']]` +| `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/dashevo/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/dashevo/platform/pull/230) for additional information related to compound index constraints in Platform v0.22. + +## Example query +The following query combines both a where clause and query modifiers. + +```javascript +import Dash from "dash" + +const { Essentials: { Buffer }, PlatformProtocol: { Identifier } } = Dash; + +const query = { + limit: 5, + startAt: Buffer.from(Identifier.from('4Qp3menV9QjE92hc3BzkUCusAmHLxh1AU6gsVsPF4L2q')), + where: [ + ['normalizedParentDomainName', '==', 'dash'], + ['normalizedLabel', 'startsWith', 'test'], + ], + orderBy: [ + ['normalizedLabel', 'asc'], + ], +} +``` \ No newline at end of file diff --git a/docs/resources/repository-overview.md b/docs/resources/repository-overview.md new file mode 100644 index 000000000..f2e390aa4 --- /dev/null +++ b/docs/resources/repository-overview.md @@ -0,0 +1,109 @@ +```{eval-rst} +.. _resources-repository-overview: +``` + +# Repository Overview + +> 📘 Change to monorepo +> +> Dash Platform v0.21 migrated to a [monorepo](https://en.wikipedia.org/wiki/Monorepo) structure to streamline continuous integration builds and testing. A number of the libraries below were previously independent repositories but now are aggregated into the [`packages` directory](https://github.com/dashevo/platform/tree/master/packages) of the monorepo (). + +## js-dash-sdk + +Dash client-side JavaScript library for application development and wallet payment/signing. Uses wallet-lib, dapi-client, and dashcore-lib to expose layer-1 and layer-2 functionality. Main user is app developers. + +npm: `dash` +[Repository](https://github.com/dashevo/platform/tree/master/packages/js-dash-sdk) + +## js-dapi-client + +Client library for accessing [DAPI Endpoints](../reference/dapi-endpoints.md) . Enables interaction with Dash platform through the [DAPI](../explanations/dapi.md) hosted on masternodes. Provides automatic masternode discovery starting from any initial masternode. + +npm: `@dashevo/dapi-client` +[Repository](https://github.com/dashevo/platform/tree/master/packages/js-dapi-client) + +## dapi + +A decentralized API for the Dash network. Exposes endpoints for interacting with the layer 1 blockchain and layer 2 platform services. + +[Repository](https://github.com/dashevo/platform/tree/master/packages/dapi) + +## js-dpp + +JavaScript implementation of [Dash Platform Protocol](../explanations/platform-protocol.md). Performs validation of all data submitted to the platform. + +npm: `@dashevo/dpp` +[Repository](https://github.com/dashevo/platform/tree/master/packages/js-dpp) + +## Supporting Repositories + +### drive + +Manages the platform state and provides decentralized application storage on the Dash network. + +[Repository](https://github.com/dashevo/platform/tree/master/packages/js-drive) + +### dashcore-lib + +A JavaScript Dash library + +npm: `@dashevo/dashcore-lib` +Repository: + +### grove-db + +A hierarchical authenticated data structure. The construction is based on [Database Outsourcing with Hierarchical Authenticated Data Structures](https://eprint.iacr.org/2015/351.pdf). + +[Repository](https://github.com/dashevo/grovedb) + +### wallet-lib + +An extensible JavaScript Wallet Library for Dash. Provides layer 1 SPV wallet functionality. + +npm: `@dashevo/wallet-lib` +[Repository](https://github.com/dashevo/platform/tree/master/packages/wallet-lib) + +### dapi-grpc + +Decentralized API gRPC definition files and generated clients. Used by clients (e.g. dapi-client) to interact with DAPI endpoints. + +npm: `@dashevo/dapi-grpc` +[Repository](https://github.com/dashevo/platform/tree/master/packages/dapi-grpc) + +### dash-network-deploy + +Tool for assisting Dash devnet network deployment and testing. + + + +### platform-test-suite + +Test suite for end-to-end testing of Dash Platform by running some real-life scenarios against a Dash Network. + +[Repository](https://github.com/dashevo/platform/tree/master/packages/platform-test-suite) + +### rs-drive + +Implements secondary indices for Platform in conjunction with GroveDB. + +[Repository](https://github.com/dashevo/rs-drive) + +### dashmate + +A distribution package for Dash masternode installation. + +[Repository](https://github.com/dashevo/platform/tree/master/packages/dashmate) + +## Contract Repositories + +### dashpay-contract + +DashPay contract documents JSON Schema + +[Repository](https://github.com/dashevo/platform/tree/master/packages/dashpay-contract) + +### dpns-contract + +DPNS contract documents JSON Schema + +[Repository](https://github.com/dashevo/platform/tree/master/packages/dpns-contract) \ No newline at end of file diff --git a/docs/resources/source-code.md b/docs/resources/source-code.md new file mode 100644 index 000000000..ef59ad7a1 --- /dev/null +++ b/docs/resources/source-code.md @@ -0,0 +1,5 @@ +# Source Code + +Source code produced by Dash Core Group is located in two GitHub organizations: +- [Dashpay](https://github.com/dashpay) - Dash Core Blockchain software and documention +- [Dashevo](https://github.com/dashevo) - Dash Platform software \ No newline at end of file diff --git a/docs/sdk-js/examples/examples.md b/docs/sdk-js/examples/examples.md new file mode 100644 index 000000000..e3aac57c3 --- /dev/null +++ b/docs/sdk-js/examples/examples.md @@ -0,0 +1,13 @@ +# Examples + +```{toctree} +:maxdepth: 2 +:titlesonly: + +fetch-an-identity-from-its-name +generate-a-new-mnemonic +paying-to-another-address +receive-money-and-check-balance +sign-and-verify-messages +use-different-account +``` diff --git a/docs/sdk-js/examples/fetch-an-identity-from-its-name.md b/docs/sdk-js/examples/fetch-an-identity-from-its-name.md new file mode 100644 index 000000000..c32c8ff34 --- /dev/null +++ b/docs/sdk-js/examples/fetch-an-identity-from-its-name.md @@ -0,0 +1,17 @@ +# Fetching an identity from its name + +Assuming you have created an identity and attached a name to it (see how to [register an identity](../../tutorials/identities-and-names/register-an-identity.md) and how to [attach it to a name](../../tutorials/identities-and-names/register-a-name-for-an-identity.md)), you will then be able to directly recover an identity from its names. See below: + +```js +const client = new Dash.Client({ + wallet: { + mnemonic: '', // Your app mnemonic, which holds the identity + }, +}); + +// This is the name previously registered in DPNS. +const identityName = 'alice'; + +const nameDocument = await client.platform.names.resolve(`${identityName}.dash`); +const identity = await client.platform.identities.get(nameDocument.ownerId); +``` \ No newline at end of file diff --git a/docs/sdk-js/examples/generate-a-new-mnemonic.md b/docs/sdk-js/examples/generate-a-new-mnemonic.md new file mode 100644 index 000000000..9fb6bfcd6 --- /dev/null +++ b/docs/sdk-js/examples/generate-a-new-mnemonic.md @@ -0,0 +1,48 @@ +# Generate a new mnemonic + +In order to be able to keep your private keys private, we encourage to create your own mnemonic instead of using those from the examples (that might be empty). +Below, you will be proposed two options allowing you to create a new mnemonic, depending on the level of customisation you need. + +## Dash.Client + +By passing `null` to the mnemonic value of the wallet options, you can get Wallet-lib to generate a new mnemonic for you. + +```js +const Dash = require("dash"); +const client = new Dash.Client({ + network: "testnet", + wallet: { + mnemonic: null, + }, +}); +const mnemonic = client.wallet.exportWallet(); +console.log({mnemonic}); +``` + +## Dash.Mnemonic + +```js +const Dash = require("dash"); +const {Mnemonic} = Dash.Core; + +const mnemnonic = new Mnemonic().toString() +``` + +### Language selection + +```js +const {Mnemonic} = Dash.Core; +const {CHINESE, ENGLISH, FRENCH, ITALIAN, JAPANESE, SPANISH} = Mnemonic.Words; +console.log(new Mnemonic(Mnemonic.Words.FRENCH).toString()) +``` + +### Entropy size + +By default, the value for mnemonic is `128` (12 words), but you can generate a 24 words (or other) : + +```js +const {Mnemonic} = Dash.Core; +console.log(new Mnemonic(256).toString()) +``` + +You can even replace the word list by your own, providing a list of 2048 unique words. \ No newline at end of file diff --git a/docs/sdk-js/examples/paying-to-another-address.md b/docs/sdk-js/examples/paying-to-another-address.md new file mode 100644 index 000000000..1eba64a9b --- /dev/null +++ b/docs/sdk-js/examples/paying-to-another-address.md @@ -0,0 +1,28 @@ +# Paying to another address + +In order to pay, you need to have an [existing balance](../examples/receive-money-and-check-balance.md). +The below code will allow you to pay to a single address a specific amount of satoshis. + +```js +const Dash = require('dash'); + +const mnemonic = ''; // your mnemonic here. +const client = new Dash.Client({ + wallet: { + mnemonic, + }, +}); + +async function payToRecipient(account) { + const transaction = account.createTransaction({ + recipient: 'yNPbcFfabtNmmxKdGwhHomdYfVs6gikbPf', + satoshis: 10000, + }); + const transactionId = await account.broadcastTransaction(transaction); +} + +client.wallet.getAccount().then(payToRecipient); + +``` + +See more on create [transaction options here](https://dashpay.github.io/platform/Wallet-library/account/createTransaction/). \ No newline at end of file diff --git a/docs/sdk-js/examples/receive-money-and-check-balance.md b/docs/sdk-js/examples/receive-money-and-check-balance.md new file mode 100644 index 000000000..b0bd85aa2 --- /dev/null +++ b/docs/sdk-js/examples/receive-money-and-check-balance.md @@ -0,0 +1,92 @@ +# Receive money and display balance + +## Initialize client + +Initialize the SDK Client with your [generated mnemonic](../examples/generate-a-new-mnemonic.md) passed as an option. + +```js +const Dash = require("dash"); +const mnemonic = ''// your mnemonic here. +const client = new Dash.Client({ + wallet: { + mnemonic, + } +}); + +async function showBalance() { + const account = await client.wallet.getAccount(); + const totalBalance = account.getTotalBalance(); + console.log(`Account's total balance: ${totalBalance} duffs`); +} +``` + +Having your `client` instance set up, you will be able to access the `account` and `wallet` instance generated from your mnemonic. + +By default `getAccount()` returns the first BIP44 account. +You can read more on [how to use a different account](../examples/use-different-account.md). + +## Generate a receiving address + +Dash wallet supports two different types of addresses: + +- `external` addresses used for receiving funds from other addresses +- `internal` addresses used for change outputs of outgoing transactions +- For your privacy, you might want to generate a new address for each payment: + +```js +async function generateUnusedAddress() { + const account = await client.wallet.getAccount(); + const { address } = account.getUnusedAddress(); + console.log(`Unused external address: ${address}`); +} +``` + +This above code will generate a new unique (never used) address. + +## Displaying your balance + +_Dash Wallet returns the balance in duffs (1 Dash is equal to 100.000.000 duffs)_ + +`getTotalBalance()` function takes into account `confirmed` and `unconfirmed` transactions (not included in a block). +It is recommended to check the confirmed balance before making a payment: + +```js +async function showBalance() { + const account = await client.wallet.getAccount(); + const totalBalance = account.getTotalBalance(); + const confirmedBalance = account.getConfirmedBalance(); + const unconfirmedBalance = account.getUnconfirmedBalance(); + console.log(`Account balance: + Confirmed: ${confirmedBalance} + Unconfirmed: ${unconfirmedBalance} + Total: ${totalBalance} + `); +} +``` + +## Listen for event on received transaction + +When a new unconfirmed transaction is received, you can receive an event, and then validate the address or perform an action if needed. + +```js +// FETCHED/UNCONFIRMED_TRANSACTION event is currently disabled + +async function listenUnconfirmedTransaction() { + const account = await client.wallet.getAccount(); + account.on('FETCHED/UNCONFIRMED_TRANSACTION', (data) => { + console.dir(data); + }); +} +``` + +## Get address at specific index + +In case you want to retrieve an address at specific index: + +```js +async function getAddressAtIndex() { + const account = await client.wallet.getAccount(); + const { address: externalAddress } = account.getAddress(2); + const { address: internalAddress } = account.getAddress(2, 'internal'); +} +``` \ No newline at end of file diff --git a/docs/sdk-js/examples/sign-and-verify-messages.md b/docs/sdk-js/examples/sign-and-verify-messages.md new file mode 100644 index 000000000..5faa38d48 --- /dev/null +++ b/docs/sdk-js/examples/sign-and-verify-messages.md @@ -0,0 +1,24 @@ +# Sign and verify messages + +Dash SDK exports the Message constructor inside the Core namespace `new Dash.Core.Message` + +```js +const Dash = require('dash'); + +const mnemonic = ''; + +const client = new Dash.Client({ + wallet: { + mnemonic, + }, +}); + +async function signAndVerify() { + const account = await client.wallet.getAccount(); + + const pk = new Dash.Core.PrivateKey(); + const message = new Dash.Core.Message('hello, world'); + const signed = account.sign(message, pk); + const verified = message.verify(pk.toAddress().toString(), signed.toString()); +} +``` \ No newline at end of file diff --git a/docs/sdk-js/examples/use-different-account.md b/docs/sdk-js/examples/use-different-account.md new file mode 100644 index 000000000..e316a0e98 --- /dev/null +++ b/docs/sdk-js/examples/use-different-account.md @@ -0,0 +1,11 @@ +# Using a different account + +Clients initialized with a mnemonic support multiple accounts as defined in [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). + +By default `client.wallet.getAccount()` returns the account at index `0`. + +To access other accounts, pass the `index` option: + +``` +const secondAccount = await client.wallet.getAccount({ index: 1 }) +``` \ No newline at end of file diff --git a/docs/sdk-js/getting-started/about-schemas.md b/docs/sdk-js/getting-started/about-schemas.md new file mode 100644 index 000000000..edc7dbf46 --- /dev/null +++ b/docs/sdk-js/getting-started/about-schemas.md @@ -0,0 +1,5 @@ +# About Schemas + +Schemas represents the application data structure, a JSON Schema language based set of rules that allows the creation of a Data Contract. + +You can read more in the [Dash Platform Documentation - Data contract section](../../explanations/platform-protocol-data-contract.md). \ No newline at end of file diff --git a/docs/sdk-js/getting-started/core-concepts.md b/docs/sdk-js/getting-started/core-concepts.md new file mode 100644 index 000000000..dc2ca8f96 --- /dev/null +++ b/docs/sdk-js/getting-started/core-concepts.md @@ -0,0 +1,30 @@ +# Core concepts + +The [Dash Core Developer Guide](https://docs.dash.org/projects/core/en/stable/docs/guide/introduction.html) will answer most of questions about the fundamentals of Dash. However, some elements provided by the SDK need to be grasped, so we will quickly cover some of those. + +## Wallet + +At the core of Dash is the Payment Chain. In order to be able to transact on it, one needs to have a set of [UTXOs](https://docs.dash.org/projects/core/en/stable/docs/guide/block-chain-transaction-data.html) that are controlled by a Wallet instance. + +In order to access your UTXO, you will have to provide a valid mnemonic that will unlock the Wallet and automatically fetch the associated UTXOs. + +When an SDK instance is created, you can access your wallet via the `client.wallet` variable. (Check [wallet-lib documentation](https://dashpay.github.io/platform/Wallet-library/) for more details) + +## Account + +Since the introduction of deterministic wallets ([BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)), a wallet is represented by multiple accounts. + +It is the instance you will use most of the time for receiving or broadcasting payments. + +You can access your account with `client.getWalletAccount()`. See [how to use a different account](../examples/use-different-account.md) if you need to get an account at a specific index. + +## App Schema and Contracts + +The Dash Platform Chain provides developers with the ability to create applications. +Each application requires a set of rules and conditions described as a portable document in the form of a JSON Schema. + +When registered, those applications schemas are called contracts and contains a contractId (namespace : `client.platform.contracts`). + +By default, this library supports Dash Platform Name Service (DPNS) (to attach a name to an identity), under the namespace `client.platform.names` for testnet. + +See: [how to use multiple apps](../getting-started/working-with-multiple-apps.md) \ No newline at end of file diff --git a/docs/sdk-js/getting-started/dash-platform-applications.md b/docs/sdk-js/getting-started/dash-platform-applications.md new file mode 100644 index 000000000..f07a91ed8 --- /dev/null +++ b/docs/sdk-js/getting-started/dash-platform-applications.md @@ -0,0 +1,9 @@ +# Dash Platform applications + +## DPNS + +DPNS is handled in the Dash SDK Client under the namespace `client.platform.names.*'`. [Read more here](../platform/names/names.md) + +## DashPay + +The DashPay contract is registered on testnet under contract id `Bwr4WHCPz5rFVAD87RqTs3izo4zpzwsEdKPWUT1NS1C7`. Its functionality is not incorporated with the Dash SDK at this time. \ No newline at end of file diff --git a/docs/sdk-js/getting-started/getting-started.md b/docs/sdk-js/getting-started/getting-started.md new file mode 100644 index 000000000..d77eb3fcf --- /dev/null +++ b/docs/sdk-js/getting-started/getting-started.md @@ -0,0 +1,12 @@ +# Getting started + +```{toctree} +:maxdepth: 2 + +about-schemas +core-concepts +dash-platform-applications +working-with-multiple-apps +quick-start +with-typescript +``` diff --git a/docs/sdk-js/getting-started/quick-start.md b/docs/sdk-js/getting-started/quick-start.md new file mode 100644 index 000000000..ae84f7bdc --- /dev/null +++ b/docs/sdk-js/getting-started/quick-start.md @@ -0,0 +1,46 @@ +# Quick start + +In order to use this library, you will need to add our [NPM package](https://www.npmjs.com/dash) to your project. + +Having [NodeJS](https://nodejs.org/) installed, just type : + +```bash +npm install dash +``` + +## Initialization + +Let's create a Dash SDK client instance specifying both our mnemonic and the schema we wish to work with. + +```js +const Dash = require('dash'); +const opts = { + wallet: { + mnemonic: "arena light cheap control apple buffalo indicate rare motor valid accident isolate", + }, +}; +const client = new Dash.Client(opts); +client.wallet.getAccount().then(async (account) => { + // Do something +}) +``` + +Quick note: +If no `mnemonic` is provided or `mnemonic: null` is passed inside the `wallet` option, a new mnemonic will be generated. + + +## Make a payment + +```js +client.wallet.getAccount().then(async (account) => { + const transaction = account.createTransaction({ + recipient: 'yixnmigzC236WmTXp9SBZ42csyp9By6Hw8', + amount: 0.12, + }); + await account.broadcastTransaction(transaction); +}); +``` + +## Interact with Dash Platform + +See the [Tutorial section](../../tutorials/introduction.md) of the Dash Platform documentation for examples. \ No newline at end of file diff --git a/docs/sdk-js/getting-started/with-typescript.md b/docs/sdk-js/getting-started/with-typescript.md new file mode 100644 index 000000000..635e19157 --- /dev/null +++ b/docs/sdk-js/getting-started/with-typescript.md @@ -0,0 +1,36 @@ +# TypeScript + +In order to use Dash SDK with TypeScript. + +Create an index.ts file + +```js +import Dash from 'dash'; +const clientOpts = { + wallet: { + mnemonic: null, // Will generate a new address, you should keep it. + }, +}; +const client = new Dash.Client(clientOpts); + +const initializeAccount = async () => { + const account = await client.wallet.getAccount(); + const balance = account.getTotalBalance(); + console.log(`Account balance: ${balance}`) +} +``` + +Have a following `tsconfig.json` file + +```json +{ + "compilerOptions": { + "module": "commonjs", + "moduleResolution": "node", + "esModuleInterop": true + } +} +``` + +**Compile:** `tsc -p tsconfig.json` +**Run:** `node index.js` \ No newline at end of file diff --git a/docs/sdk-js/getting-started/working-with-multiple-apps.md b/docs/sdk-js/getting-started/working-with-multiple-apps.md new file mode 100644 index 000000000..60466b892 --- /dev/null +++ b/docs/sdk-js/getting-started/working-with-multiple-apps.md @@ -0,0 +1,23 @@ +# Working with multiple apps + +When working with other registered contracts, you will need to know their `contractId` and reference it in the SDK constructor. + +Assuming a contract DashPay has the following `contractId: "77w8Xqn25HwJhjodrHW133aXhjuTsTv9ozQaYpSHACE3"`. +You can then pass it as an option. + +```js +const client = new Dash.Client({ + apps: { + dashpay: { + contractId: '77w8Xqn25HwJhjodrHW133aXhjuTsTv9ozQaYpSHACE3' + } + } +}); +``` + +This allow the method `client.platform.documents.get` to provide you field selection. +Therefore, if the contract has a `profile` field that you wish to access, the SDK will allow you to use dot-syntax for access : + +```js +const bobProfile = await client.platform.documents.get('dashpay.profile', { name: 'bob' }); +``` \ No newline at end of file diff --git a/docs/sdk-js/overview.md b/docs/sdk-js/overview.md new file mode 100644 index 000000000..672614a26 --- /dev/null +++ b/docs/sdk-js/overview.md @@ -0,0 +1,47 @@ +```{eval-rst} +.. _sdk-js-index: +``` + +# Overview + +[![NPM Version](https://img.shields.io/npm/v/dash)](https://www.npmjs.org/package/dash) +[![Release Packages](https://github.com/dashpay/platform/actions/workflows/release.yml/badge.svg)](https://github.com/dashpay/platform/actions/workflows/release.yml) +[![Release Date](https://img.shields.io/github/release-date/dashpay/platform)](https://github.com/dashpay/platform/releases/latest) +[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen)](https://github.com/RichardLitt/standard-readme) + +Dash library for JavaScript/TypeScript ecosystem (Wallet, DAPI, Primitives, BLS, ...) + +Dash library provides access via [DAPI](../explanations/dapi.md) to use both the Dash Core network and Dash Platform on [supported networks](https://github.com/dashpay/platform/#supported-networks). The Dash Core network can be used to broadcast and receive payments. Dash Platform can be used to manage identities, register data contracts for applications, and submit or retrieve application data via documents. + +## Install + +### From NPM + +In order to use this library, you will need to add our [NPM package](https://www.npmjs.com/dash) to your project. + +Having [NodeJS](https://nodejs.org/) installed, just type: + +```bash +npm install dash +``` + +### From unpkg + +```html + +``` + +### Usage examples + +- [Generate a mnemonic](./examples/generate-a-new-mnemonic.md) +- [Receive money and display balance](./examples/receive-money-and-check-balance.md) +- [Pay to another address](./examples/paying-to-another-address.md) +- [Use another BIP44 account](./examples/use-different-account.md) + +### Dash Platform Tutorials + +See the [Tutorial section](../tutorials/introduction.md) of the Dash Platform documentation for examples. + +## Licence + +[MIT](https://github.com/dashevo/dashjs/blob/master/LICENCE.md) © Dash Core Group, Inc. \ No newline at end of file diff --git a/docs/sdk-js/platform/contracts/contracts.md b/docs/sdk-js/platform/contracts/contracts.md new file mode 100644 index 000000000..a1b4f52e9 --- /dev/null +++ b/docs/sdk-js/platform/contracts/contracts.md @@ -0,0 +1,16 @@ +# Contracts + +## What is a contract + +Contracts are registered sets of rules defined in a [JSON Application Schema](../../getting-started/core-concepts.md). + +See the Dash Platform documentation for more information about [Data Contracts](../../../explanations/platform-protocol-data-contract.md). + +```{toctree} +:maxdepth: 2 + +create +get +publish +update +``` diff --git a/docs/sdk-js/platform/contracts/create.md b/docs/sdk-js/platform/contracts/create.md new file mode 100644 index 000000000..b6e1bed22 --- /dev/null +++ b/docs/sdk-js/platform/contracts/create.md @@ -0,0 +1,38 @@ +# Create + +**Usage**: `client.platform.contracts.create(contractDefinitions, identity)` +**Description**: This method will return a Contract object initialized with the parameters defined and apply to the used identity. + +Parameters: + +| parameters | type | required | Description | +| ----------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| **contractDefinitions** | JSONDataContract | yes | The defined [JSON Application Schema](../../../explanations/platform-protocol-data-contract.md) | +| **identity** | Identity | yes | A valid [registered `application` identity](../identities/register.md) | + +**Example**: + +```js + const identityId = '';// Your identity identifier. + + // Your valid json contract definitions + const contractDefinitions = { + note: { + properties: { + message: { + type: "string" + } + }, + additionalProperties: false + } + }; + const identity = await client.platform.identities.get(identityId); + const contract = client.platform.contracts.create(contractDefinitions, identity); + + // You can use the validate method from DPP to validate the created contract + const validationResult = client.platform.dpp.dataContract.validate(contract); +``` + +**Note**: When your contract is created, it will only exist locally. Use the [publish](../contracts/publish.md) method to register it. + +Returns: Contract. \ No newline at end of file diff --git a/docs/sdk-js/platform/contracts/get.md b/docs/sdk-js/platform/contracts/get.md new file mode 100644 index 000000000..7cf5587b0 --- /dev/null +++ b/docs/sdk-js/platform/contracts/get.md @@ -0,0 +1,14 @@ +# Get + +**Usage**: `client.platform.contracts.get(contractId)` +**Description**: This method will allow you to fetch back a contract from its id. + +Parameters: + +| parameters | type | required | Description | +| -------------- | ------ | -------- | ---------------------------------------------------- | +| **identifier** | string | yes | Will fetch back the contract matching the identifier | + +**Example**: `await client.platform.contracts.get('77w8Xqn25HwJhjodrHW133aXhjuTsTv9ozQaYpSHACE3')` + +Returns: Contract (or `null` if it's not a registered contract). \ No newline at end of file diff --git a/docs/sdk-js/platform/contracts/publish.md b/docs/sdk-js/platform/contracts/publish.md new file mode 100644 index 000000000..9eb493f14 --- /dev/null +++ b/docs/sdk-js/platform/contracts/publish.md @@ -0,0 +1,23 @@ +# Publish + +**Usage**: `client.platform.contracts.publish(contract, identity)` +**Description**: This method will sign and broadcast any valid contract. + +Parameters: + +| parameters | type | required | Description | +| ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------- | +| **contract** | Contract | yes | A valid [created contract](../contracts/create.md) | +| **identity** | Identity | yes | A valid [registered `application` identity](../identities/register.md) | + +**Example**: + +```js +const identityId = '';// Your identity identifier. +const identity = await client.platform.identities.get(identityId); +// See the contract.create documentation for more on how to create a dataContract +const contract = await client.platform.contracts.create(contractDefinitions, identity); +await client.platform.contracts.publish(contract, identity); +``` + +Returns : DataContractCreateTransition. \ No newline at end of file diff --git a/docs/sdk-js/platform/contracts/update.md b/docs/sdk-js/platform/contracts/update.md new file mode 100644 index 000000000..e6ac2b0bf --- /dev/null +++ b/docs/sdk-js/platform/contracts/update.md @@ -0,0 +1,13 @@ +# Update + +**Usage**: `client.platform.contracts.update(contract, identity)` +**Description**: This method will sign and broadcast an updated valid contract. + +Parameters: + +| parameters | type | required | Description | +| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------- | +| **contract** | Contract | yes | A valid [created contract](../contracts/create.md) | +| **identity** | Identity | yes | A valid [registered `application` identity](../identities/register.md) | + +Returns: DataContractUpdateTransition. \ No newline at end of file diff --git a/docs/sdk-js/platform/documents/broadcast.md b/docs/sdk-js/platform/documents/broadcast.md new file mode 100644 index 000000000..da9d88c42 --- /dev/null +++ b/docs/sdk-js/platform/documents/broadcast.md @@ -0,0 +1,32 @@ +# Broadcast + +**Usage**: `client.platform.document.broadcast(documents, identity)` +**Description**: This method will broadcast the document on the Application Chain + +Parameters: + +| parameters | type | required | Description | +| --------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | +| **documents** | Object | yes | | +| **documents.create** | ExtendedDocument\[] | no | array of valid [created document](../documents/create.md) to create | +| **documents.replace** | ExtendedDocument\[] | no | array of valid [created document](../documents/create.md) to replace | +| **documents.delete** | ExtendedDocument\[] | no | array of valid [created document](../documents/create.md) to delete | +| **identity** | Identity | yes | A valid [registered identity](../identities/register.md) | + +**Example**: + +```js +const identityId = '';// Your identity identifier +const identity = await client.platform.identities.get(identityId); + +const helloWorldDocument = await client.platform.documents.create( + // Assuming a contract tutorialContract is registered with a field note + 'tutorialContract.note', + identity, + { message: 'Hello World'}, +); + +await client.platform.documents.broadcast({ create: [helloWorldDocument] }, identity); +``` + +Returns: documents. \ No newline at end of file diff --git a/docs/sdk-js/platform/documents/create.md b/docs/sdk-js/platform/documents/create.md new file mode 100644 index 000000000..f261034d7 --- /dev/null +++ b/docs/sdk-js/platform/documents/create.md @@ -0,0 +1,30 @@ +# Create + +**Usage**: `client.platform.documents.create(typeLocator, identity, documentOpts)` +**Description**: This method will return a ExtendedDocument object initialized with the parameters defined and apply to the used identity. + +Parameters: + +| parameters | type | required | Description | +| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- | +| **dotLocator** | string | yes | Field of a specific application, under the form `appName.fieldName` | +| **identity** | Identity | yes | A valid [registered identity](../identities/register.md) | +| **docOpts** | Object | yes | A valid data that match the data contract structure | + +**Example**: + +```js +const identityId = '';// Your identity identifier +const identity = await client.platform.identities.get(identityId); + +const helloWorldDocument = await client.platform.documents.create( + // Assume a contract helloWorldContract is registered with a field note + 'helloWorldContract.note', + identity, + { message: 'Hello World'}, + ); +``` + +**Note**: When your document is created, it will only exist locally, use the [broadcast](../documents/broadcast.md) method to register it. + +Returns: ExtendedDocument \ No newline at end of file diff --git a/docs/sdk-js/platform/documents/documents.md b/docs/sdk-js/platform/documents/documents.md new file mode 100644 index 000000000..f44b9180f --- /dev/null +++ b/docs/sdk-js/platform/documents/documents.md @@ -0,0 +1,16 @@ +# Documents + +## What is a document + +Documents in Dash Platform are similar to those in standard document-oriented databases (MongoDB,...). +They represent a record consisting of one, or multiples field-value pairs and should respect the structure of the dataContract on which they are submitted in. + +See more on the Dash Platform documentation about [Data Contract](../../../explanations/platform-protocol-data-contract.md). + +```{toctree} +:maxdepth: 2 + +broadcast +create +get +``` diff --git a/docs/sdk-js/platform/documents/get.md b/docs/sdk-js/platform/documents/get.md new file mode 100644 index 000000000..4772a6e12 --- /dev/null +++ b/docs/sdk-js/platform/documents/get.md @@ -0,0 +1,35 @@ +# Get + +**Usage**: `client.platform.documents.get(typeLocator, opts)` +**Description**: This method will allow you to fetch back documents matching the provided parameters. + +Parameters: + +| parameters | type | required | Description | +| --------------- | ------ | ---------------- | ------------------------------------------------------------------- | +| **typeLocator** | string | yes | Field of a specific application, under the form `appName.fieldName` | +| **opts** | object | no (default: {}) | Query options of the request | + +**Queries options**: + +| parameters | type | required | Description | +| -------------- | ------- | -------- | ------------------------- | +| **where** | array | no | Mongo-like where query | +| **orderBy** | array | no | Mongo-like orderBy query | +| **limit** | integer | no | how many objects to fetch | +| **startAt** | integer | no | number of objects to skip | +| **startAfter** | integer | no | exclusive skip | + +[Learn more about query syntax](../../../reference/query-syntax.md). + +**Example**: + +```js + const queryOpts = { + where: [ + ['normalizedLabel', '==', 'alice'], + ['normalizedParentDomainName', '==', 'dash'], + ], + }; + await client.platform.documents.get('dpns.domain', queryOpts); +``` \ No newline at end of file diff --git a/docs/sdk-js/platform/identities/get.md b/docs/sdk-js/platform/identities/get.md new file mode 100644 index 000000000..b9ba54088 --- /dev/null +++ b/docs/sdk-js/platform/identities/get.md @@ -0,0 +1,14 @@ +# Get + +**Usage**: `client.platform.identities.get(identityId)` +**Description**: This method will allow you to fetch back an identity from its id. + +Parameters: + +| parameters | type | required | Description | +| -------------- | ------ | -------- | ---------------------------------------------------- | +| **identifier** | string | yes | Will fetch back the identity matching the identifier | + +**Example**: `await client.platform.identities.get('3GegupTgRfdN9JMS8R6QXF3B2VbZtiw63eyudh1oMJAk')` + +Returns: Identity (or `null` if it does not exist). \ No newline at end of file diff --git a/docs/sdk-js/platform/identities/identities.md b/docs/sdk-js/platform/identities/identities.md new file mode 100644 index 000000000..467ceeafc --- /dev/null +++ b/docs/sdk-js/platform/identities/identities.md @@ -0,0 +1,21 @@ +# Identities + +## What is an identity + +An Identity is a blockchain-based identifier for individuals (users) and applications. +Identities are the atomic element that, when linked with additional applications, can be extended to provide new functionality. + +Read more on the Dash Platform documentation about [Identity](../../../explanations/identity.md). +You might also want to consult the usage for the [DPNS Name Service](../names/names.md) in order to attach a name to your created identity. + +## Credits + +Each identity contains a credit balance. The ratio is 1 duff = 1000 credits. + +```{toctree} +:maxdepth: 2 + +get +register +topup +``` diff --git a/docs/sdk-js/platform/identities/register.md b/docs/sdk-js/platform/identities/register.md new file mode 100644 index 000000000..cfd037c78 --- /dev/null +++ b/docs/sdk-js/platform/identities/register.md @@ -0,0 +1,16 @@ +# Register + +**Usage**: `client.platform.identities.register()` +**Description**: This method will register a new identity for you. + +Parameters: + +| parameters | type | required | Description | +| ------------- | ------ | -------- | ------------------------------------------------------------------- | +| fundingAmount | number | no | Defaults: 10000. Allow to set a funding amount in duffs (satoshis). | + +**Example**: `await client.platform.identities.register()` + +**Note**: The created identity will be associated to the active account. You might want to know more about how to [change your active account](../../examples/use-different-account.md). + +Returns: Identity. \ No newline at end of file diff --git a/docs/sdk-js/platform/identities/topup.md b/docs/sdk-js/platform/identities/topup.md new file mode 100644 index 000000000..bca04e36f --- /dev/null +++ b/docs/sdk-js/platform/identities/topup.md @@ -0,0 +1,25 @@ +# Topup + +**Usage**: `client.platform.identities.topUp(identity, amount)` +**Description**: This method will topup the provided identity's balance. + +_The identity balance might slightly vary from the topped up amount because of the transaction fee estimation._ + +Parameters: + +| parameters | type | required | Description | +| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------- | +| **identity** | Identity | yes | A valid [registered identity](../identities/register.md) | +| **amount** | number | yes | A duffs (satoshis) value corresponding to the amount you want to top up to the identity. | + +**Example**: + +```js +const identityId = '';// Your identity identifier +const identity = await client.platform.identities.get(identityId); +await client.platform.identities.topUp(identity.getId(), 10000); + +console.log(`New identity balance: ${identity.balance}`) +``` + +Returns: Boolean. \ No newline at end of file diff --git a/docs/sdk-js/platform/names/names.md b/docs/sdk-js/platform/names/names.md new file mode 100644 index 000000000..59400072b --- /dev/null +++ b/docs/sdk-js/platform/names/names.md @@ -0,0 +1,20 @@ +# Names + +## What is DPNS + +DPNS is a special Dash Platform Application that is intended to provide a naming service for the Application Chain. + +Decoupling name from the blockchain identity enables a unique user experience coupled with the highest security while remaining compatible with [Decentralized Identifiers](https://www.w3.org/TR/did-core/). + +Limitation: max length of 63 characters on charset `0-9`,`A-Z`(case insensitive), `-`. + +Domain names are linked to an Identity. + +```{toctree} +:maxdepth: 2 + +register +resolve +resolvebyrecord +search +``` diff --git a/docs/sdk-js/platform/names/register.md b/docs/sdk-js/platform/names/register.md new file mode 100644 index 000000000..59482fc80 --- /dev/null +++ b/docs/sdk-js/platform/names/register.md @@ -0,0 +1,18 @@ +# Register + +**Usage**: `client.platform.names.register(name, records, identity)` +**Description**: This method will create a DPNS record matching your identity to the user or appname defined. + +Parameters: + +| parameters | type | required | Description | +| -------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **name** | String | yes | An alphanumeric (1-63 character) value used for human-identification (can contain `-` but not as the first or last character). If a name with no parent domain is entered, '.dash' is used. | +| **records** | Object | yes | records object having only one of the following items | +| **records.dashUniqueIdentityId** | String | no | Unique Identity ID for this name record | +| **records.dashAliasIdentityId** | String | no | Used to signify that this name is the alias for another id | +| **identity** | Identity | yes | A valid [registered identity](../identities/register.md) | + +**Example**: `await client.platform.names.register('alice', { dashUniqueIdentityId: identity.getId() }, identity)` + +Returns: the created domain document \ No newline at end of file diff --git a/docs/sdk-js/platform/names/resolve.md b/docs/sdk-js/platform/names/resolve.md new file mode 100644 index 000000000..ecd4a082c --- /dev/null +++ b/docs/sdk-js/platform/names/resolve.md @@ -0,0 +1,14 @@ +# Resovle + +**Usage**: `client.platform.names.resolve('.dash')` +**Description**: This method will allow you to resolve a DPNS record from its humanized name. + +Parameters: + +| parameters | type | required | Description | +| ---------- | ------ | -------- | ----------------------------------------------------------------------------- | +| **name** | String | yes | An alphanumeric (2-63) value used for human-identification (can contains `-`) | + +**Example**: `await client.platform.names.resolve('alice.dash')` + +Returns : ExtendedDocument (or `null` if do not exist). \ No newline at end of file diff --git a/docs/sdk-js/platform/names/resolvebyrecord.md b/docs/sdk-js/platform/names/resolvebyrecord.md new file mode 100644 index 000000000..63b272456 --- /dev/null +++ b/docs/sdk-js/platform/names/resolvebyrecord.md @@ -0,0 +1,22 @@ +# ResolveByRecord + +**Usage**: `client.platform.names.resolveByRecord(record, value)` +**Description**: This method will allow you to resolve a DPNS record by identity ID. + +Parameters: + +| parameters | type | required | Description | +| ---------- | ------ | -------- | -------------------------------------------------------------------- | +| **record** | String | yes | Type of the record (`dashUniqueIdentityId` or `dashAliasIdentityId`) | +| **value** | String | yes | Identifier value for the record | + +**Example**: + +This example will describe how to resolve names by the dash unique identity id. + +```js +const identityId = '3ge4yjGinQDhxh2aVpyLTQaoka45BkijkoybfAkDepoN'; +const document = await client.platform.names.resolveByRecord('dashUniqueIdentityId', identityId); +``` + +Returns: array of ExtendedDocument. \ No newline at end of file diff --git a/docs/sdk-js/platform/names/search.md b/docs/sdk-js/platform/names/search.md new file mode 100644 index 000000000..0a3bc0141 --- /dev/null +++ b/docs/sdk-js/platform/names/search.md @@ -0,0 +1,24 @@ +# Search + +**Usage**: `client.platform.names.search(labelPrefix, parentDomain)` +**Description**: This method will allow you to search all records matching the label prefix on the specified parent domain. + +Parameters: + +| parameters | type | required | Description | +| ---------------- | ------ | -------- | ------------------------------------------------- | +| **labelPrefix** | String | yes | label prefix to search for | +| **parentDomain** | String | yes | parent domain name on which to perform the search | + +**Example**: + +This example will describe how to search all names on the parent domain `dash` that starts with the label prefix `al`. +It will resolves names documents such as `alice`, `alex` etc... + +```js +const labelPrefix = 'al'; +const parentDomain = 'dash'; +const document = await client.platform.names.search(labelPrefix, parentDomain); +``` + +Returns: Documents matching the label prefix on the parent domain. \ No newline at end of file diff --git a/docs/sdk-js/platform/platform.md b/docs/sdk-js/platform/platform.md new file mode 100644 index 000000000..11f4f1d4b --- /dev/null +++ b/docs/sdk-js/platform/platform.md @@ -0,0 +1,20 @@ +# Platform + +The Dash Platform provides a technology stack on the top of Dash Network that allows creation of feature-rich decentralized applications. + +You can learn more from the [Dash Platform Documentation - What is Dash Platform?](../../intro/what-is-dash-platform.md) + +## Platform components + +- DAPI: A decentralized API that runs on all Masternodes and offers gRPC endpoints for retrieving payment chain metadata (blocks, transactions), as well as application data (documents, contracts, identities). +- Drive: Application chain storage layer where the data defined by Data Contracts is stored and managed. +- DPNS: Naming service provided by a Dash Platform App + +```{toctree} +:maxdepth: 3 + +contracts/contracts +documents/documents +identities/identities +names/names +``` diff --git a/docs/sdk-js/usage/dapi.md b/docs/sdk-js/usage/dapi.md new file mode 100644 index 000000000..83ade98b8 --- /dev/null +++ b/docs/sdk-js/usage/dapi.md @@ -0,0 +1,13 @@ +# DAPI + +## About DAPI + +DAPI (Decentralized API) is a distributed and decentralized endpoints provided by the Masternode Network. + +## Get the DAPI-Client instance + +```js + const dapiClient = client.getDAPIClient(); +``` + +The usage is then [described here](../../explanations/dapi.md). \ No newline at end of file diff --git a/docs/sdk-js/usage/dashcore-lib-primitives.md b/docs/sdk-js/usage/dashcore-lib-primitives.md new file mode 100644 index 000000000..269da2340 --- /dev/null +++ b/docs/sdk-js/usage/dashcore-lib-primitives.md @@ -0,0 +1,122 @@ +# Dashcore Lib primitives + +All Dashcore lib primitives are exposed via the `Core` namespace. + +```js +const Dash = require('dash'); +const { + Core: { + Block, + Transaction, + Address, + // ... + } +} = Dash; +``` + +## Transaction + +The Transaction primitive allows creating and manipulating transactions. It also allows signing transactions with a private key. +Supports fee control and input/output access (which allows passing a specific script). + +```js +const { Transaction } = Dash.Core; +const tx = new Transaction(txProps) +``` + +Access the [Transaction documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/transaction.md) + +## Address + +Standardized representation of a Dash Address. Address can be instantiated from a String, PrivateKey, PublicKey, HDPrivateKey or HdPublicKey. +Pay-to-script-hash (P2SH) multi-signature addresses from an array of PublicKeys are also supported. + +```js +const { Address } = Dash.Core; +``` + +Access the [Address documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/address.md) + +## Block + +Given a binary representation of the block as input, the Block class allows you to have a deserialized representation of a Block or its header. It also allows validating the transactions in the block against the header merkle root. + +The block's transactions can also be explored by iterating over elements in array (`block.transactions`). + +`const { Block } = Dash.Core;` + +Access the [Block documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/block.md) + +## UnspentOutput + +Representation of an UnspentOutput (also called UTXO as in Unspent Transaction Output). +Mostly useful in association with a Transaction and for Scripts. + +`const { UnspentOutput } = Dash.Core.Transaction;` + +Access the [UnspentOutput documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/unspentoutput.md) + +## HDPublicKey + +Hierarchical Deterministic (HD) version of the PublicKey. +Used internally by Wallet-lib and for exchange between peers (DashPay) + +const { HDPublicKey } = Dash.Core;\` + +Access the [HDKeys documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/hierarchical.md#hdpublickey) + +## HDPrivateKey + +Hierarchical Deterministic (HD) version of the PrivateKey. +Used internally by Wallet-lib. + +`const { HDPrivateKey } = Dash.Core;` + +Access the [HDKeys documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/hierarchical.md#hdprivatekey) + +## PublicKey + +`const { PublicKey } = Dash.Core;` + +Access the [PublicKey documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/publickey.md) + +## PrivateKey + +`const { PrivateKey } = Dash.Core;` + +Access the [PrivateKey documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/privatekey.md) + +## Mnemonic + +Implementation of [BIP39 Mnemonic code for generative deterministic keys](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). +Generates a random mnemonic with the chosen language, validates a mnemonic or returns the associated HDPrivateKey. + +`const { Mnemonic } = Dash.Core;` + +Access the [Mnemonic documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/mnemonic.md) + +## Network + +A representation of the internal parameters relative to the selected network. By default, all primitives works with 'livenet'. + +`const { Network } = Dash.Core;` + +Access the [Network documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/networks.md) + +## Script + +`const { Script } = Dash.Core.Transaction;` + +Access the [Script documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/script.md) + +## Input + +`const { Input } = Dash.Core.Transaction;` + +Access the [Transaction documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/transaction.md#adding-inputs) + +## Output + +`const { Output } = Dash.Core.Transaction;` + +Access the [Transaction documentation on dashpay/dashcore-lib](https://github.com/dashpay/dashcore-lib/blob/master/docs/core-concepts/transaction.md#handling-outputs) \ No newline at end of file diff --git a/docs/sdk-js/usage/usage.md b/docs/sdk-js/usage/usage.md new file mode 100644 index 000000000..dd2c4456a --- /dev/null +++ b/docs/sdk-js/usage/usage.md @@ -0,0 +1,9 @@ +# Usage + +```{toctree} +:maxdepth: 2 +:titlesonly: + +dapi +dashcore-lib-primitives +``` diff --git a/docs/sdk-js/wallet/accounts.md b/docs/sdk-js/wallet/accounts.md new file mode 100644 index 000000000..fdacb8ff4 --- /dev/null +++ b/docs/sdk-js/wallet/accounts.md @@ -0,0 +1,27 @@ +# Accounts + +## Getting an account + +When Wallet is initialized with `mnemonic`, it holds multiple Accounts according to BIP44. +Each Account holds the keys needed to make a payments from it. + +Wallet's `getAccount` method used to access an account: + +```js +const client = new Dash.Client({ + wallet: { + mnemonic: "maximum blast eight orchard waste wood gospel siren parent deer athlete impact", + }, +}); + +const account = await client.wallet.getAccount() +// Do something with account +``` + +As optional parameter, an integer representing the account `index` can be passed as parameter. By default, index account on call is 0. + +``` +client.wallet.getAccount({ index: 1 }) +``` + +Awaiting for the `getAccount()` promise is necessary to ensure the wallet is synced-up with the network and make sure that the UTXO set is ready to be used for payment/signing. \ No newline at end of file diff --git a/docs/sdk-js/wallet/signing-encrypt.md b/docs/sdk-js/wallet/signing-encrypt.md new file mode 100644 index 000000000..b6d78ec8b --- /dev/null +++ b/docs/sdk-js/wallet/signing-encrypt.md @@ -0,0 +1,30 @@ +# Signing and encryption + +## Obtain account + +```js +const account = await client.wallet.getAccount(); +``` + +## Sign a Transaction + +```js +const tx = new Dash.Core.Transaction({ + // ...txOpts +}); +const signedTx = account.sign(tx); +``` + +## Encrypt a message + +```js + const message = 'Something'; + const signedMessage = account.encrypt('AES', message, 'secret'); +``` + +## Decrypt a message + +```js +const encrypted = 'U2FsdGVkX19JLa+1UpbMcut1/QFWLMlKUS+iqz+7Wl4='; +const message = account.decrypt('AES', encrypted, 'secret'); +``` \ No newline at end of file diff --git a/docs/sdk-js/wallet/wallet.md b/docs/sdk-js/wallet/wallet.md new file mode 100644 index 000000000..f0f9513b6 --- /dev/null +++ b/docs/sdk-js/wallet/wallet.md @@ -0,0 +1,17 @@ +# Wallet + +## About Wallet-lib + +When Dash.Client is initiated with a `mnemonic` property, a wallet instance becomes accessible via `client.wallet` property. + +To initialize the wallet account and synchronize with the network, use `client.wallet.getAccount()`. + +Find out more about the Wallet in its [complete documentation](https://dashpay.github.io/platform/Wallet-library/) + +```{toctree} +:maxdepth: 2 +:titlesonly: + +accounts +signing-encrypt +``` diff --git a/docs/tutorials/connecting-to-testnet.md b/docs/tutorials/connecting-to-testnet.md new file mode 100644 index 000000000..9720e8f62 --- /dev/null +++ b/docs/tutorials/connecting-to-testnet.md @@ -0,0 +1,139 @@ +# Connect to a network + +The purpose of this tutorial is to walk through the steps necessary to access the network. + +## Overview + +Platform services are provided via a combination of HTTP and gRPC connections to DAPI, and some connections to an Insight API. Although one could interact with DAPI by connecting to these directly, or by using [DAPI-client](https://github.com/dashevo/platform/tree/master/packages/js-dapi-client), the easiest approach is to use the [JavaScript Dash SDK](https://github.com/dashevo/platform/tree/master/packages/js-dash-sdk). The Dash SDK connects to the testnet by default. + +## Prerequisites + +- An installation of [NodeJS v12 or higher](https://nodejs.org/en/download/) + +## Connect via Dash SDK + +### 1. Install the Dash SDK + +The JavaScript SDK package is available from npmjs.com and can be installed by running `npm install dash` from the command line: + +```shell +npm install dash +``` + +### 2. Connect to Dash Platform + +Create a file named `dashConnect.js` with the following contents. Then run it by typing `node dashConnect.js` from the command line: + +```javascript dashConnect.js +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +async function connect() { + return await client.getDAPIClient().core.getBestBlockHash(); +} + +connect() + .then((d) => console.log('Connected. Best block hash:\n', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +Once this returns successfully, you're ready to begin developing! See the [Quickstart](../tutorials/introduction.md#quickstart) for recommended next steps. For details on all SDK options and methods, please refer to the [SDK documentation](../sdk-js/overview.md). + +## Connect to a Devnet + +The SDK also supports connecting to development networks (devnets). Since devnets can be created by anyone, the client library will be unaware of them unless connection information is provided using one of the options described below. + +### Connect via Seed + +Using a seed node is the preferred method in most cases. The client uses the provided seed node to a retrieve a list of available masternodes on the network so requests can be spread across the entire network. + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ + seeds: [{ + host: 'seed-1.testnet.networks.dash.org:1443', + }], +}); + +async function connect() { + return await client.getDAPIClient().core.getBestBlockHash(); +} + +connect() + .then((d) => console.log('Connected. Best block hash:\n', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +### Connect via Address + +Custom addresses may be directly specified via `dapiAddresses` in cases where it is beneficial to know exactly what node(s) are being accessed (e.g. debugging, local development, etc.). + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ + dapiAddresses: [ + '127.0.0.1:3000:3010', + '127.0.0.2:3000:3010', + ], +}); + +async function connect() { + return await client.getDAPIClient().core.getBestBlockHash(); +} + +connect() + .then((d) => console.log('Connected. Best block hash:\n', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +## Connect Directly to DAPI (Optional) + +> 🚧 Advanced Topic +> +> Normally, the Dash SDK, dapi-client, or another library should be used to interact with DAPI. This may be helpful for debugging in some cases, but generally is not required. + +The example below demonstrates retrieving the hash of the best block hash directly from a DAPI node via command line and several languages: + +::::{tab-set-code} + +```shell +curl --request POST \ + --url https://seed-1.testnet.networks.dash.org:1443/ \ + --header 'content-type: application/json' \ + --data '{"method":"getBlockHash","id":1,"jsonrpc":"2.0","params":{"height": 100 }}' +``` +```python +import requests + +url = "https://seed-1.testnet.networks.dash.org:1443/" + +payload = "{\"method\":\"getBlockHash\",\"id\":1,\"jsonrpc\":\"2.0\",\"params\":{\"height\":100}}" +headers = {'content-type': 'application/json'} + +response = requests.request("POST", url, data=payload, headers=headers) + +print(response.text) +``` +```ruby +require 'uri' +require 'net/http' + +url = URI("https://seed-1.testnet.networks.dash.org:1443/") + +http = Net::HTTP.new(url.host, url.port) + +request = Net::HTTP::Post.new(url) +request["content-type"] = 'application/json' +request.body = "{\"method\":\"getBlockHash\",\"id\":1,\"jsonrpc\":\"2.0\",\"params\":{\"height\":100}}" + +response = http.request(request) +puts response.read_body +``` + +:::: diff --git a/docs/tutorials/contracts-and-documents.md b/docs/tutorials/contracts-and-documents.md new file mode 100644 index 000000000..6617d60fa --- /dev/null +++ b/docs/tutorials/contracts-and-documents.md @@ -0,0 +1,29 @@ +# Contracts and documents + +The following tutorials cover working with data contracts as well as storing and updating related data using the documents they define. + +- [Register a Data Contract](../tutorials/contracts-and-documents/register-a-data-contract.md) +- [Retrieve a Data Contract](../tutorials/contracts-and-documents/retrieve-a-data-contract.md) +- [Update a Data Contract](../tutorials/contracts-and-documents/update-a-data-contract.md) +- [Submit Documents](../tutorials/contracts-and-documents/submit-documents.md) +- [Retrieve Documents](../tutorials/contracts-and-documents/retrieve-documents.md) +- [Update Documents](../tutorials/contracts-and-documents/update-documents.md) +- [Delete Documents](../tutorials/contracts-and-documents/delete-documents.md) + +> 📘 Tutorial code +> +> You can clone a repository containing the code for all tutorials from GitHub or download it as a [zip file](https://github.com/dashevo/platform-readme-tutorials/archive/refs/heads/main.zip). + +```{toctree} +:maxdepth: 2 +:titlesonly: +:hidden: + +contracts-and-documents/register-a-data-contract +contracts-and-documents/retrieve-a-data-contract +contracts-and-documents/update-a-data-contract +contracts-and-documents/submit-documents +contracts-and-documents/retrieve-documents +contracts-and-documents/update-documents +contracts-and-documents/delete-documents +``` diff --git a/docs/tutorials/contracts-and-documents/delete-documents.md b/docs/tutorials/contracts-and-documents/delete-documents.md new file mode 100644 index 000000000..febe4906c --- /dev/null +++ b/docs/tutorials/contracts-and-documents/delete-documents.md @@ -0,0 +1,71 @@ +# Delete documents + +In this tutorial we will update delete data from Dash Platform. Data is stored in the form of [documents](../../explanations/platform-protocol-document.md) which are encapsulated in a [state transition](../../explanations/platform-protocol-state-transition.md) before being submitted to DAPI. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- Access to a previously created document (e.g., one created using the [Submit Documents tutorial](../../tutorials/contracts-and-documents/submit-documents.md)) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, + apps: { + tutorialContract: { + contractId: '3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE', + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const deleteNoteDocument = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + const documentId = 'an existing document ID goes here'; + + // Retrieve the existing document + const [document] = await client.platform.documents.get( + 'tutorialContract.note', + { where: [['$id', '==', documentId]] }, + ); + + // Sign and submit the document delete transition + return platform.documents.broadcast({ delete: [document] }, identity); +}; + +deleteNoteDocument() + .then((d) => console.log('Document deleted:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + + + +> 👍 Initializing the Client with a contract identity +> +> The example above shows how access to contract documents via `.` syntax (e.g. `tutorialContract.note`) can be enabled by passing a contract identity to the constructor. Please refer to the [Dash SDK documentation](https://github.com/dashevo/platform/blob/master/packages/js-dash-sdk/docs/getting-started/multiple-apps.md) for details. + +# What's happening + +After we initialize the Client, we retrieve the document to be deleted via `platform.documents.get` using its `id`. + +Once the document has been retrieved, we must submit it to [DAPI](../../explanations/dapi.md). Documents are submitted in batches that may contain multiple documents to be created, replaced, or deleted. In this example, a single document is being deleted. + +The `platform.documents.broadcast` method takes the document batch (e.g. `{delete: [documents[0]]}`) and an identity parameter. Internally, it creates a [State Transition](../../explanations/platform-protocol-state-transition.md) containing the previously created document, signs the state transition, and submits the signed state transition to DAPI. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/register-a-data-contract.md b/docs/tutorials/contracts-and-documents/register-a-data-contract.md new file mode 100644 index 000000000..f4db23b45 --- /dev/null +++ b/docs/tutorials/contracts-and-documents/register-a-data-contract.md @@ -0,0 +1,462 @@ +# Register a data contract + +In this tutorial we will register a data contract. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) + +# Code + +## Defining contract documents + +As described in the [data contract explanation](../../explanations/platform-protocol-data-contract.md#structure), data contracts must include one or more developer-defined [documents](../../explanations/platform-protocol-document.md). + +The most basic example below (tab 1) demonstrates a data contract containing a single document type (`note`) which has a single string property (`message`). + +The second tab shows the same data contract with an index defined on the `$ownerId` field. This would allow querying for documents owned by a specific identity using a [where clause](../../reference/query-syntax.md#where-clause). + +The third tab shows a data contract using the [JSON-Schema $ref feature](https://json-schema.org/understanding-json-schema/structuring.html#reuse) that enables reuse of defined objects. Note that the $ref keyword has been [temporarily disabled](https://github.com/dashevo/platform/pull/300) since Platform v0.22. + +The fourth tab shows a data contract requiring the optional `$createdAt` and `$updatedAt` [base fields](../../explanations/platform-protocol-document.md#base-fields). Using these fields enables retrieving timestamps that indicate when a document was created or modified. + +> 🚧 +> +> Since Platform v0.23, an index can [only use the ascending order](https://github.com/dashevo/platform/pull/435) (`asc`). Future updates will remove this restriction. + +::::{tab-set-code} + +```json 1. Minimal contract +// 1. Minimal contract +{ + "note": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "additionalProperties": false + } +} +``` +```json 2. Indexed +// 2. Indexed +{ + "note": { + "type": "object", + "indices": [ + { + "name": "ownerId", + "properties": [{ "$ownerId": "asc" }], "unique": false } + ], + "properties": { + "message": { + "type": "string" + } + }, + "additionalProperties": false + } +} + +/* +An identity's documents are accessible via a query including a where clause like: +{ + where: [['$ownerId', '==', 'an identity id']], +} +*/ +``` +```json +// 3. References ($ref) +// NOTE: The `$ref` keyword is temporarily disabled for Platform v0.22. +{ + "customer": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "billing_address": { "$ref": "#/$defs/address" }, + "shipping_address": { "$ref": "#/$defs/address" } + }, + "additionalProperties": false + } +} + +/* +The contract document defined above is dependent on the following object +being added to the contract via the contracts `.setDefinitions` method: + +{ + address: { + type: "object", + properties: { + street_address: { type: "string" }, + city: { type: "string" }, + state: { type: "string" } + }, + required: ["street_address", "city", "state"], + additionalProperties: false + } +} +*/ +``` +```json +// 4. Timestamps +{ + "note": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "required": ["$createdAt", "$updatedAt"], + "additionalProperties": false + } +} + +/* +If $createdAt and/or $updatedAt are added to the list of required properties +for a document, all documents of that type will store a timestamp indicating +when the document was created or modified. + +This information will be returned when the document is retrieved. +*/ +``` +```json +// 5. Binary data +{ + "block": { + "type": "object", + "properties": { + "hash": { + "type": "array", + "byteArray": true, + "maxItems": 64, + "description": "Store block hashes" + } + }, + "additionalProperties": false + } +} + +/* +Setting `"byteArray": true` indicates that the provided data will be an +array of bytes (e.g. a NodeJS Buffer). +*/ +``` + +:::: + +> 📘 +> +> Please refer to the [data contract reference page](../../reference/data-contracts.md) for more comprehensive details related to contracts and documents. + +## Registering the data contract + +The following examples demonstrate the details of creating contracts using the features [described above](#defining-contract-documents): + +::::{tab-set-code} + +```javascript 1. Minimal contract +// 1. Minimal contract +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const contractDocuments = { + note: { + type: 'object', + properties: { + message: { + type: 'string', + }, + }, + additionalProperties: false, + }, + }; + + const contract = await platform.contracts.create(contractDocuments, identity); + console.dir({ contract: contract.toJSON() }); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate(contract); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.publish(contract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +registerContract() + .then((d) => console.log('Contract registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript 2. Indexed +// 2. Indexed +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const contractDocuments = { + note: { + type: 'object', + indices: [{ + name: 'ownerId', + properties: [{ $ownerId: 'asc' }], + unique: false, + }], + properties: { + message: { + type: 'string', + }, + }, + additionalProperties: false, + }, + }; + + const contract = await platform.contracts.create(contractDocuments, identity); + console.dir({ contract: contract.toJSON() }); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate(contract); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.publish(contract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +registerContract() + .then((d) => console.log('Contract registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript 3. References ($ref) +// 3. References ($ref) +// NOTE: The `$ref` keyword is temporarily disabled for Platform v0.22. +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + // Define a reusable object + const definitions = { + address: { + type: 'object', + properties: { + street_address: { type: 'string' }, + city: { type: 'string' }, + state: { type: 'string' }, + }, + required: ['street_address', 'city', 'state'], + additionalProperties: false, + }, + }; + + // Create a document with properties using a definition via $ref + const contractDocuments = { + customer: { + type: 'object', + properties: { + name: { type: 'string' }, + billing_address: { $ref: '#/$defs/address' }, + shipping_address: { $ref: '#/$defs/address' }, + }, + additionalProperties: false, + }, + }; + + const contract = await platform.contracts.create(contractDocuments, identity); + + // Add reusable definitions referred to by "$ref" to contract + contract.setDefinitions(definitions); + console.dir({ contract: contract.toJSON() }); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate(contract); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.publish(contract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +registerContract() + .then((d) => console.log('Contract registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript 4. Timestamps +// 4. Timestamps +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const contractDocuments = { + note: { + type: 'object', + properties: { + message: { + type: 'string', + }, + }, + required: ['$createdAt', '$updatedAt'], + additionalProperties: false, + }, + }; + + const contract = await platform.contracts.create(contractDocuments, identity); + console.dir({ contract: contract.toJSON() }); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate(contract); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.publish(contract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +registerContract() + .then((d) => console.log('Contract registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript 5. Binary data +// 5. Binary data +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const contractDocuments = { + block: { + type: 'object', + properties: { + hash: { + type: 'array', + byteArray: true, + maxItems: 64, + description: 'Store block hashes', + }, + }, + additionalProperties: false, + }, + }; + + const contract = await platform.contracts.create(contractDocuments, identity); + console.dir({ contract: contract.toJSON() }, { depth: 5 }); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate(contract); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.publish(contract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +registerContract() + .then((d) => console.log('Contract registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +:::: + +> 👍 +> +> **Make a note of the returned data contract `$id` as it will be used used in subsequent tutorials throughout the documentation.** + +# What's Happening + +After we initialize the Client, we create an object defining the documents this data contract requires (e.g. a `note` document in the example). The `platform.contracts.create` method takes two arguments: a contract definitions JSON-schema object and an identity. The contract definitions object consists of the document types being created (e.g. `note`). It defines the properties and any indices. + +Once the data contract has been created, we still need to submit it to DAPI. The `platform.contracts.publish` method takes a data contract and an identity parameter. Internally, it creates a State Transition containing the previously created contract, signs the state transition, and submits the signed state transition to DAPI. A response will only be returned if an error is encountered. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md b/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md new file mode 100644 index 000000000..474998a9b --- /dev/null +++ b/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md @@ -0,0 +1,87 @@ +# Retrieve a data contract + +In this tutorial we will retrieve the data contract created in the [Register a Data Contract tutorial](../../tutorials/contracts-and-documents/register-a-data-contract.md). + +## Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A Dash Platform Contract ID: [Tutorial: Register a Data Contract](../../tutorials/contracts-and-documents/register-a-data-contract.md) + +# Code + +## Retrieving a data contract + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +const retrieveContract = async () => { + const contractId = '3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE'; + return client.platform.contracts.get(contractId); +}; + +retrieveContract() + .then((d) => console.dir(d.toJSON(), { depth: 5 })) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +## Updating the client app list + +> 📘 +> +> In many cases it may be desirable to work with a newly retrieved data contract using the `.` syntax (e.g. `dpns.domain`). Data contracts that were created after the client was initialized or not included in the initial client options can be added via `client.getApps().set(...)`. + +```javascript +const Dash = require('dash'); +const { PlatformProtocol: { Identifier } } = Dash; + +const myContractId = 'a contract ID'; +const client = new Dash.Client(); + +client.platform.contracts.get(myContractId) + .then((myContract) => { + client.getApps().set('myNewContract', { + contractId: Identifier.from(myContractId), + contract: myContract, + }); + }); +``` + +# Example Data Contract + +The following example response shows a retrieved contract: + +```json +{ + "protocolVersion":1, + "$id":"G1FVmxxrnbT6CiQU7w2xgY9oMMqkkZb7vS6fkeRrSTXG", + "$schema":"https://schema.dash.org/dpp-0-4-0/meta/data-contract", + "version":2, + "ownerId":"8uFQj2ptknrcwykhQbTzQatoQUyxn4VJQn1J25fxeDvk", + "documents":{ + "note":{ + "type":"object", + "properties":{ + "author":{ + "type":"string" + }, + "message":{ + "type":"string" + } + }, + "additionalProperties":false + } + } +} +``` + +> 📘 +> +> Please refer to the [data contract reference page](../../reference/data-contracts.md) for more comprehensive details related to contracts and documents. + +# What's Happening + +After we initialize the Client, we request a contract. The `platform.contracts.get` method takes a single argument: a contract ID. After the contract is retrieved, it is displayed on the console. + +The second code example shows how the contract could be assigned a name to make it easily accessible without initializing an additional client. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/retrieve-documents.md b/docs/tutorials/contracts-and-documents/retrieve-documents.md new file mode 100644 index 000000000..3d8904340 --- /dev/null +++ b/docs/tutorials/contracts-and-documents/retrieve-documents.md @@ -0,0 +1,144 @@ +# Retrieve documents + +In this tutorial we will retrieve some of the current data from a data contract. Data is stored in the form of documents as described in the Dash Platform Protocol [Document explanation](../../explanations/platform-protocol-document.md). + +## Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A Dash Platform Contract ID: [Tutorial: Register a Data Contract](../../tutorials/contracts-and-documents/register-a-data-contract.md) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + apps: { + tutorialContract: { + contractId: '3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE', + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const getDocuments = async () => { + return client.platform.documents.get('tutorialContract.note', { + limit: 2, // Only retrieve 2 document + }); +}; + +getDocuments() + .then((d) => { + for (const n of d) { + console.log('Document:\n', n.toJSON()); + } + }) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +> 👍 Initializing the Client with a contract identity +> +> The example above shows how access to contract documents via `.` syntax (e.g. `tutorialContract.note`) can be enabled by passing a contract identity to the constructor. Please refer to the [Dash SDK documentation](https://github.com/dashevo/platform/blob/master/packages/js-dash-sdk/docs/getting-started/multiple-apps.md) for details. + +## Queries + +The example code uses a very basic query to return only one result. More extensive querying capabilities are covered in the [query syntax reference](../../reference/query-syntax.md). + +# Example Document + +The following examples show the structure of a `note` document (from the data contract registered in the tutorial) returned from the SDK when retrieved with various methods. + +The values returned by `.toJSON()` include the base document properties (prefixed with `$`) present in all documents along with the data contract defined properties. + +> 📘 +> +> Note: When using `.toJSON()`, binary data is displayed as a base64 string (since JSON is a text-based format). + +The values returned by `.getData()` (and also shown in the console.dir() `data` property) represent _only_ the properties defined in the `note` document described by the [tutorial data contract](../../tutorials/contracts-and-documents/register-a-data-contract.md#code). + +::::{tab-set-code} + +```json .toJSON() +// .toJSON() +{ + "$protocolVersion": 0, + "$id": "6LpCQhkXYV2vqkv1UWByew4xQ6BaxxnGkhfMZsN3SV9u", + "$type": "note", + "$dataContractId": "3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE", + "$ownerId": "CEPMcuBgAWeaCXiP2gJJaStANRHW6b158UPvL1C8zw2W", + "$revision": 1, + "message": "Tutorial CI Test @ Fri, 23 Jul 2021 13:12:13 GMT" +} +``` +```json .getData() +// .getData() +{ + "Tutorial CI Test @ Fri, 23 Jul 2021 13:12:13 GMT" +} +``` +```text .data.message +# .data.message +Tutorial CI Test @ Fri, 23 Jul 2021 13:12:13 GMT +``` +```json console.dir(document) +// console.dir(document) +Document { + dataContract: DataContract { + protocolVersion: 0, + id: Identifier(32) [Uint8Array] [ + 40, 93, 196, 112, 38, 188, 51, 122, + 149, 59, 21, 39, 147, 119, 87, 53, + 236, 60, 97, 42, 31, 82, 135, 120, + 68, 188, 55, 153, 226, 198, 181, 139 + ], + ownerId: Identifier(32) [Uint8Array] [ + 166, 222, 98, 87, 193, 19, 82, 37, + 50, 118, 210, 64, 103, 122, 28, 155, + 168, 21, 198, 134, 142, 151, 153, 136, + 46, 64, 223, 74, 215, 153, 158, 167 + ], + schema: 'https://schema.dash.org/dpp-0-4-0/meta/data-contract', + documents: { note: [Object] }, + '$defs': undefined, + binaryProperties: { note: {} }, + metadata: Metadata { blockHeight: 526, coreChainLockedHeight: 542795 } + }, + entropy: undefined, + protocolVersion: 0, + id: Identifier(32) [Uint8Array] [ + 79, 93, 213, 226, 76, 79, 205, 191, + 165, 190, 68, 28, 8, 83, 61, 226, + 222, 248, 48, 235, 147, 110, 181, 229, + 7, 66, 65, 230, 100, 194, 192, 156 + ], + type: 'note', + dataContractId: Identifier(32) [Uint8Array] [ + 40, 93, 196, 112, 38, 188, 51, 122, + 149, 59, 21, 39, 147, 119, 87, 53, + 236, 60, 97, 42, 31, 82, 135, 120, + 68, 188, 55, 153, 226, 198, 181, 139 + ], + ownerId: Identifier(32) [Uint8Array] [ + 166, 222, 98, 87, 193, 19, 82, 37, + 50, 118, 210, 64, 103, 122, 28, 155, + 168, 21, 198, 134, 142, 151, 153, 136, + 46, 64, 223, 74, 215, 153, 158, 167 + ], + revision: 1, + data: { message: 'Tutorial CI Test @ Fri, 23 Jul 2021 13:12:13 GMT' }, + metadata: Metadata { blockHeight: 526, coreChainLockedHeight: 542795 } +} +``` + +:::: + +# What's happening + +After we initialize the Client, we request some documents. The `client.platform.documents.get` method takes two arguments: a record locator and a query object. The records locator consists of an app name (e.g. `tutorialContract`) and the top-level document type requested, (e.g. `note`). + +> 📘 DPNS Contract +> +> Note: Access to the DPNS contract is built into the Dash SDK. DPNS documents may be accessed via the `dpns` app name (e.g. `dpns.domain`). + +If you need more than the first 100 documents, you'll have to make additional requests with `startAt` incremented by 100 each time. In the future, the Dash SDK may return documents with paging information to make this easier and reveal how many documents are returned in total. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/submit-documents.md b/docs/tutorials/contracts-and-documents/submit-documents.md new file mode 100644 index 000000000..7db849737 --- /dev/null +++ b/docs/tutorials/contracts-and-documents/submit-documents.md @@ -0,0 +1,81 @@ +# Submit documents + +In this tutorial we will submit some data to an application on Dash Platform. Data is stored in the form of [documents](../../explanations/platform-protocol-document.md) which are encapsulated in a [state transition](../../explanations/platform-protocol-state-transition.md) before being submitted to DAPI. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) +- A Dash Platform Contract ID: [Tutorial: Register a Data Contract](../../tutorials/contracts-and-documents/register-a-data-contract.md) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, + apps: { + tutorialContract: { + contractId: '3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE', + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const submitNoteDocument = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const docProperties = { + message: `Tutorial Test @ ${new Date().toUTCString()}`, + }; + + // Create the note document + const noteDocument = await platform.documents.create( + 'tutorialContract.note', + identity, + docProperties, + ); + + const documentBatch = { + create: [noteDocument], // Document(s) to create + replace: [], // Document(s) to update + delete: [], // Document(s) to delete + }; + // Sign and submit the document(s) + return platform.documents.broadcast(documentBatch, identity); +}; + +submitNoteDocument() + .then((d) => console.log(d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + + + +> 👍 Initializing the Client with a contract identity +> +> The example above shows how access to contract documents via `.` syntax (e.g. `tutorialContract.note`) can be enabled by passing a contract identity to the constructor. Please refer to the [Dash SDK documentation](https://github.com/dashevo/platform/blob/master/packages/js-dash-sdk/docs/getting-started/multiple-apps.md) for details. + +# What's happening + +After we initialize the Client, we create a document that matches the structure defined by the data contract of the application being referenced (e.g. a `note` document for the contract registered in the [data contract tutorial](../../tutorials/contracts-and-documents/register-a-data-contract.md#code)). The `platform.documents.create` method takes three arguments: a document locator, an identity, and the document data. The document locator consists of an application name (e.g. `tutorialContract`) and the document type being created (e.g. `note`). The document data should contain values for each of the properties defined for it in the data contract (e.g. `message` for the tutorial contract's note). + +Once the document has been created, we still need to submit it to [DAPI](../../explanations/dapi.md). Documents are submitted in batches that may contain multiple documents to be created, replaced, or deleted. In this example, a single document is being created. The `documentBatch` object defines the action to be completed for the document (the empty action arrays - `replace` and `delete` in this example - may be excluded and are shown for reference only here). + +The `platform.documents.broadcast` method then takes the document batch and an identity parameter. Internally, it creates a [State Transition](../../explanations/platform-protocol-state-transition.md) containing the previously created document, signs the state transition, and submits the signed state transition to DAPI. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/update-a-data-contract.md b/docs/tutorials/contracts-and-documents/update-a-data-contract.md new file mode 100644 index 000000000..852c5fd66 --- /dev/null +++ b/docs/tutorials/contracts-and-documents/update-a-data-contract.md @@ -0,0 +1,85 @@ +# Update a data contract + +Since Dash Platform v0.22, it is possible to update existing data contracts in certain backwards-compatible ways. This includes: + +- Adding new documents +- Adding new optional properties to existing documents +- Adding _non-unique_ indices for properties added in the update. + +In this tutorial we will update an existing data contract. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) +- A Dash Platform Contract ID: [Tutorial: Register a Data Contract](../../tutorials/contracts-and-documents/register-a-data-contract.md) + +# Code + +The following example demonstrates updating an existing contract to add a new property to an existing document: + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const updateContract = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + + const existingDataContract = await platform.contracts.get('a contract ID goes here'); + const documents = existingDataContract.getDocuments(); + + documents.note.properties.author = { + type: 'string', + }; + + existingDataContract.setDocuments(documents); + + // Make sure contract passes validation checks + const validationResult = await platform.dpp.dataContract.validate( + existingDataContract, + ); + + if (validationResult.isValid()) { + console.log('Validation passed, broadcasting contract..'); + // Sign and submit the data contract + return platform.contracts.update(existingDataContract, identity); + } + console.error(validationResult); // An array of detailed validation errors + throw validationResult.errors[0]; +}; + +updateContract() + .then((d) => console.log('Contract updated:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + + + +> 📘 +> +> Please refer to the [data contract reference page](../../reference/data-contracts.md) for more comprehensive details related to contracts and documents. + +# What's Happening + +After we initialize the Client, we retrieve an existing contract owned by our identity. We then get the contract's documents and modify a document (adding an `author` property to the `note` document in the example).The `setDocuments` method takes one argument: the object containing the updated document types. + +Once the data contract has been updated, we still need to submit it to DAPI. The `platform.contracts.update` method takes a data contract and an identity parameter. Internally, it creates a State Transition containing the updated contract, signs the state transition, and submits the signed state transition to DAPI. A response will only be returned if an error is encountered. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/contracts-and-documents/update-documents.md b/docs/tutorials/contracts-and-documents/update-documents.md new file mode 100644 index 000000000..4b15a90a4 --- /dev/null +++ b/docs/tutorials/contracts-and-documents/update-documents.md @@ -0,0 +1,72 @@ +# Update documents + +In this tutorial we will update existing data on Dash Platform. Data is stored in the form of [documents](../../explanations/platform-protocol-document.md) which are encapsulated in a [state transition](../../explanations/platform-protocol-state-transition.md) before being submitted to DAPI. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- Access to a previously created document (e.g., one created using the [Submit Documents tutorial](../../tutorials/contracts-and-documents/submit-documents.md)) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, + apps: { + tutorialContract: { + contractId: '3iaEhdyAVbmSjd59CT6SCrqPjfAfMdPTc8ksydgqSaWE', + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const updateNoteDocument = async () => { + const { platform } = client; + const identity = await platform.identities.get('an identity ID goes here'); + const documentId = 'an existing document ID goes here'; + + // Retrieve the existing document + const [document] = await client.platform.documents.get( + 'tutorialContract.note', + { where: [['$id', '==', documentId]] }, + ); + + // Update document + document.set('message', `Updated document @ ${new Date().toUTCString()}`); + + // Sign and submit the document replace transition + return platform.documents.broadcast({ replace: [document] }, identity); +}; + +updateNoteDocument() + .then((d) => console.log('Document updated:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + + + +> 👍 Initializing the Client with a contract identity +> +> The example above shows how access to contract documents via `.` syntax (e.g. `tutorialContract.note`) can be enabled by passing a contract identity to the constructor. Please refer to the [Dash SDK documentation](https://github.com/dashevo/platform/blob/master/packages/js-dash-sdk/docs/getting-started/multiple-apps.md) for details. + +# What's happening + +After we initialize the Client, we retrieve the document to be updated via `platform.documents.get` using its `id`. Once the document has been retrieved, we must submit it to [DAPI](../../explanations/dapi.md) with the desired data updates. Documents are submitted in batches that may contain multiple documents to be created, replaced, or deleted. In this example, a single document is being updated. + +The `platform.documents.broadcast` method then takes the document batch (e.g. `{replace: [noteDocument]}`) and an identity parameter. Internally, it creates a [State Transition](../../explanations/platform-protocol-state-transition.md) containing the previously created document, signs the state transition, and submits the signed state transition to DAPI. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/create-and-fund-a-wallet.md b/docs/tutorials/create-and-fund-a-wallet.md new file mode 100644 index 000000000..a456a8847 --- /dev/null +++ b/docs/tutorials/create-and-fund-a-wallet.md @@ -0,0 +1,62 @@ +# Create and fund a wallet + +In order to make changes on Dash Platform, you need a wallet with a balance. This tutorial explains how to generate a new wallet, retrieve an address from it, and transfer test funds to the address from a faucet. + +## Prerequisites + +- [General prerequisites](../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: null, // this indicates that we want a new wallet to be generated + // if you want to get a new address for an existing wallet + // replace 'null' with an existing wallet mnemonic + offlineMode: true, // this indicates we don't want to sync the chain + // it can only be used when the mnemonic is set to 'null' + }, +}; + +const client = new Dash.Client(clientOpts); + +const createWallet = async () => { + const account = await client.getWalletAccount(); + + const mnemonic = client.wallet.exportWallet(); + const address = account.getUnusedAddress(); + console.log('Mnemonic:', mnemonic); + console.log('Unused address:', address.address); +}; + +createWallet() + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); + +// Handle wallet async errors +client.on('error', (error, context) => { + console.error(`Client error: ${error.name}`); + console.error(context); +}); +``` + +```text +Mnemonic: thrive wolf habit timber birth service crystal patient tiny depart tower focus +Unused address: yXF7LsyajRvJGX96vPHBmo9Dwy9zEvzkbh +``` + +> 🚧 +> +> **Please save your mnemonic for the next step and for re-use in subsequent tutorials throughout the documentation.** + +# What's Happening + +Once we connect, we output the newly generated mnemonic from `client.wallet.exportWallet()` and an unused address from the wallet from `account.getUnusedAddress()`. + +# Next Step + +Using the faucet at https://testnet-faucet.dash.org/, send test funds to the "unused address" from the console output. You will need to wait until the funds are confirmed to use them. There is a block explorer running at https://testnet-insight.dashevo.org/insight/ which can be used to check confirmations. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names.md b/docs/tutorials/identities-and-names.md new file mode 100644 index 000000000..85ec39e85 --- /dev/null +++ b/docs/tutorials/identities-and-names.md @@ -0,0 +1,28 @@ +# Identities and names + +The following tutorials cover creating and managing identities as well as creating and retrieving names. + +- [Register an Identity](../tutorials/identities-and-names/register-an-identity.md) +- [Retrieve an Account's Identities](../tutorials/identities-and-names/retrieve-an-accounts-identities.md) +- [Topup an Identity's Balance](../tutorials/identities-and-names/topup-an-identity-balance.md) +- [Register a Name for an Identity](../tutorials/identities-and-names/register-a-name-for-an-identity.md) +- [Retrieve a Name](../tutorials/identities-and-names/retrieve-a-name.md) + +> 📘 Tutorial code +> +> You can clone a repository containing the code for all tutorials from GitHub or download it as a [zip file](https://github.com/dashevo/platform-readme-tutorials/archive/refs/heads/main.zip). + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Identities +:hidden: + +identities-and-names/register-an-identity +identities-and-names/retrieve-an-identity +identities-and-names/topup-an-identity-balance +identities-and-names/update-an-identity +identities-and-names/retrieve-an-accounts-identities +identities-and-names/register-a-name-for-an-identity +identities-and-names/retrieve-a-name +``` diff --git a/docs/tutorials/identities-and-names/register-a-name-for-an-identity.md b/docs/tutorials/identities-and-names/register-a-name-for-an-identity.md new file mode 100644 index 000000000..2475b7678 --- /dev/null +++ b/docs/tutorials/identities-and-names/register-a-name-for-an-identity.md @@ -0,0 +1,100 @@ +# Register a name for an identity + +The purpose of this tutorial is to walk through the steps necessary to register a [Dash Platform Name Service (DPNS)](../../reference/glossary.md#dash-platform-naming-service-dpns) name. + +## Overview +Dash Platform names make cryptographic identities easy to remember and communicate. An identity may have multiple alias names (`dashAliasIdentityId`) in addition to its default name (`dashUniqueIdentityId`). Additional details regarding identities can be found in the [Identity description](../../explanations/identity.md). + +**Note**: An identity must have a default name before any aliases can be created for the identity. + +### Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) +- A name you want to register: [Name restrictions](../../explanations/dpns.md#implementation) + +## Code + + The examples below demonstrate creating both the default name and alias names. + +**Note**: the name must be the full domain name including the parent domain (i.e. `myname.dash` instead of just `myname`). Currently `dash` is the only top-level domain that may be used. + +::::{tab-set-code} + +```javascript Register Name for Identity +// Register Name for Identity +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with testnet funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerName = async () => { + const { platform } = client; + + const identity = await platform.identities.get('an identity ID goes here'); + const nameRegistration = await platform.names.register( + '.dash', + { dashUniqueIdentityId: identity.getId() }, + identity, + ); + + return nameRegistration; +}; + +registerName() + .then((d) => console.log('Name registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript Register Alias for Identity +// Register Alias for Identity +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with testnet funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const registerAlias = async () => { + const platform = client.platform; + const identity = await platform.identities.get('an identity ID goes here'); + const aliasRegistration = await platform.names.register( + '.dash', + { dashAliasIdentityId: identity.getId() }, + identity, + ); + + return aliasRegistration; +}; + +registerAlias() + .then((d) => console.log('Alias registered:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +:::: + +## What's Happening + +After initializing the Client, we fetch the Identity we'll be associating with a name. This is an asynchronous method so we use _await_ to pause until the request is complete. Next, we call `platform.names.register` and pass in the name we want to register, the type of identity record to create, and the identity we just fetched. We wait for the result, and output it to the console. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/register-an-identity.md b/docs/tutorials/identities-and-names/register-an-identity.md new file mode 100644 index 000000000..c5c2e5f2a --- /dev/null +++ b/docs/tutorials/identities-and-names/register-an-identity.md @@ -0,0 +1,52 @@ +# Register an Identity + +The purpose of this tutorial is to walk through the steps necessary to register an identity. + +## Overview +Identities serve as the basis for interactions with Dash Platform. They consist primarily of a public key used to register a unique entity on the network. Additional details regarding identities can be found in the [Identity description](../../explanations/identity.md). + +### Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [How to Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) + +## Code + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with testnet funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const createIdentity = async () => { + return client.platform.identities.register(); +}; + +createIdentity() + .then((d) => console.log('Identity:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +The Identity will be output to the console. The Identity will need to have one confirmation before it is accessible via `client.platform.identity.get`. + +> 👍 +> +> **Make a note of the returned identity `id` as it will be used used in subsequent tutorials throughout the documentation.** + +## What's Happening + +After connecting to the Client, we call `platform.identities.register`. This will generate a keypair and submit an _Identity Create State Transaction_. After the Identity is registered, we output it to the console. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/retrieve-a-name.md b/docs/tutorials/identities-and-names/retrieve-a-name.md new file mode 100644 index 000000000..b2a77b522 --- /dev/null +++ b/docs/tutorials/identities-and-names/retrieve-a-name.md @@ -0,0 +1,101 @@ +# Retrieve a name + +In this tutorial we will retrieve the name created in the [Register a Name for an Identity tutorial](../../tutorials/identities-and-names/register-a-name-for-an-identity.md). Additional details regarding identities can be found in the [Identity description](../../explanations/identity.md). + +## Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) + +## Code + +::::{tab-set-code} + +```javascript JavaScript - Resolve by Name +// Resolve by Name +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +const retrieveName = async () => { + // Retrieve by full name (e.g., myname.dash) + return client.platform.names.resolve('.dash'); +}; + +retrieveName() + .then((d) => console.log('Name retrieved:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript JavaScript - Revolve by Record +// Revolve by Record +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +const retrieveNameByRecord = async () => { + // Retrieve by a name's identity ID + return client.platform.names.resolveByRecord( + 'dashUniqueIdentityId', + '', + ); +}; + +retrieveNameByRecord() + .then((d) => console.log('Name retrieved:\n', d[0].toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript JavaScript - Search for Name +// Search for Name +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +const retrieveNameBySearch = async () => { + // Search for names (e.g. `user*`) + return client.platform.names.search('user', 'dash'); +}; + +retrieveNameBySearch() + .then((d) => { + for (const name of d) { + console.log('Name retrieved:\n', name.toJSON()); + } + }) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +:::: + +## Example Name + +The following example response shows a retrieved name (`user-9999.dash`): + +```json +{ + "$protocolVersion": 0, + "$id": "4veLBZPHDkaCPF9LfZ8fX3JZiS5q5iUVGhdBbaa9ga5E", + "$type": "domain", + "$dataContractId": "566vcJkmebVCAb2Dkj2yVMSgGFcsshupnQqtsz1RFbcy", + "$ownerId": "HBNMY5QWuBVKNFLhgBTC1VmpEnscrmqKPMXpnYSHwhfn", + "$revision": 1, + "label": "user-9999", + "records": { + "dashUniqueIdentityId": "HBNMY5QWuBVKNFLhgBTC1VmpEnscrmqKPMXpnYSHwhfn" + }, + "preorderSalt": "BzQi567XVqc8wYiVHS887sJtL6MDbxLHNnp+UpTFSB0", + "subdomainRules": { "allowSubdomains": false }, + "normalizedLabel": "user-9999", + "normalizedParentDomainName": "dash" +} +``` + +## What's Happening + +After we initialize the Client, we request a name. The [code examples](#code) demonstrate the three ways to request a name: + +1. Resolve by name. The `platform.names.resolve` method takes a single argument: a fully-qualified name (e.g., `user-9999.dash`). +2. Resolve by record. The `platform.names.resolveByRecord` method takes two arguments: the record type (e.g., `dashUniqueIdentityId`) and the record value to resolve. +3. Search. The `platform.names.search` method takes two arguments: the leading characters of the name to search for and the domain to search (e.g., `dash` for names in the `*.dash` domain). The search will return names that begin the with string provided in the first parameter. + +After the name is retrieved, it is displayed on the console. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/retrieve-an-accounts-identities.md b/docs/tutorials/identities-and-names/retrieve-an-accounts-identities.md new file mode 100644 index 000000000..5a780c4b5 --- /dev/null +++ b/docs/tutorials/identities-and-names/retrieve-an-accounts-identities.md @@ -0,0 +1,55 @@ +# Retrieve an account's identities + +In this tutorial we will retrieve the list of identities associated with a specified mnemonic-based account. Since multiple identities may be created using the same mnemonic, it is helpful to have a way to quickly retrieve all these identities (e.g. if importing the mnemonic into a new device). + +## Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) + +# Code + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with testnet funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}); + +const retrieveIdentityIds = async () => { + const account = await client.getWalletAccount(); + return account.identities.getIdentityIds(); +}; + +retrieveIdentityIds() + .then((d) => console.log('Mnemonic identities:\n', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +Example Response + +```json +[ + "6Jz8pFZFhssKSTacgQmZP14zGZNnFYZFKSbx4WVAJFy3", + "8XoJHG96Vfm3eGh1A7HiDpMb1Jw2B9opRJe8Z38urapt", + "CEPMcuBgAWeaCXiP2gJJaStANRHW6b158UPvL1C8zw2W", + "GTGZrkPC72tWeBaqopSCKgiBkVVQR3s3yBsVeMyUrmiY" +] +``` + +# What's Happening + +After we initialize the Client and getting the account, we call `account.identities.getIdentityIds()` to retrieve a list of all identities created with the wallet mnemonic. The list of identities is output to the console. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/retrieve-an-identity.md b/docs/tutorials/identities-and-names/retrieve-an-identity.md new file mode 100644 index 000000000..07fe17f19 --- /dev/null +++ b/docs/tutorials/identities-and-names/retrieve-an-identity.md @@ -0,0 +1,48 @@ +# Retrieve an identity + +In this tutorial we will retrieve the identity created in the [Register an Identity tutorial](../../tutorials/identities-and-names/register-an-identity.md). + +## Prerequisites +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) + +# Code + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +const retrieveIdentity = async () => { + return client.platform.identities.get('an identity ID goes here'); +}; + +retrieveIdentity() + .then((d) => console.log('Identity retrieved:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +# Example Identity + +The following example response shows a retrieved identity: + +```json +{ + "protocolVersion":0, + "id":"6Jz8pFZFhssKSTacgQmZP14zGZNnFYZFKSbx4WVAJFy3", + "publicKeys":[ + { + "id":0, + "type":0, + "data":"A4zZl0EaRBB6IlDbyR80YUM2l02qqNUCoIizkQxubtxi" + } + ], + "balance":10997588, + "revision":0 +} +``` + +# What's Happening + +After we initialize the Client, we request an identity. The `platform.identities.get` method takes a single argument: an identity ID. After the identity is retrieved, it is displayed on the console. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/topup-an-identity-balance.md b/docs/tutorials/identities-and-names/topup-an-identity-balance.md new file mode 100644 index 000000000..ffd83567e --- /dev/null +++ b/docs/tutorials/identities-and-names/topup-an-identity-balance.md @@ -0,0 +1,53 @@ +# Topup an identity's balance + +The purpose of this tutorial is to walk through the steps necessary to add credits to an identity's balance. + +# Overview + +As users interact with Dash Platform applications, the credit balance associated with their identity will decrease. Eventually it will be necessary to topup the balance by converting some Dash to credits. Additional details regarding credits can be found in the [Credits description](../../explanations/identity.md#credits). + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) + +# Code + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with testnet funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const topupIdentity = async () => { + const identityId = 'an identity ID goes here'; + const topUpAmount = 1000; // Number of duffs + + await client.platform.identities.topUp(identityId, topUpAmount); + return client.platform.identities.get(identityId); +}; + +topupIdentity() + .then((d) => console.log('Identity credit balance: ', d.balance)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +# What's Happening + +After connecting to the Client, we call `platform.identities.topUp` with an identity ID and a topup amount in duffs (1 duff = 1000 credits). This creates a lock transaction and increases the identity's credit balance by the relevant amount (minus fee). The updated balance is output to the console. + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. \ No newline at end of file diff --git a/docs/tutorials/identities-and-names/update-an-identity.md b/docs/tutorials/identities-and-names/update-an-identity.md new file mode 100644 index 000000000..0c3284776 --- /dev/null +++ b/docs/tutorials/identities-and-names/update-an-identity.md @@ -0,0 +1,141 @@ +# Update an identity + +Since Dash Platform v0.23, it is possible to update identities to add new keys or disable existing ones. Platform retains disabled keys so that any existing data they signed can still be verified while preventing them from signing new data. + +# Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A Dash Platform Identity: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) + +# Code + +The two examples below demonstrate updating an existing identity to add a new key and disabling an existing key: + +> 🚧 +> +> The current SDK version signs all state transitions with public key id `1`. If it is disabled, the SDK will be unable to use the identity. Future SDK versions will provide a way to also sign using keys added in an identity update. + +::::{tab-set-code} + +```javascript Disable identity key +// Disable identity key +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const updateIdentityDisableKey = async () => { + const identityId = 'an identity ID goes here'; + const keyId = 'a public key ID goes here'; // One of the identity's public key IDs + + // Retrieve the identity to be updated and the public key to disable + const existingIdentity = await client.platform.identities.get(identityId); + const publicKeyToDisable = existingIdentity.getPublicKeyById(keyId); + + const updateDisable = { + disable: [publicKeyToDisable], + }; + + await client.platform.identities.update(existingIdentity, updateDisable); + return client.platform.identities.get(identityId); +} + +updateIdentityDisableKey() + .then((d) => console.log('Identity updated:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` +```javascript Add identity key +// Add identity key +const Dash = require('dash'); +const { IdentityPublicKey, IdentityPublicKeyWithWitness } = require('@dashevo/wasm-dpp'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'a Dash wallet mnemonic with funds goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const updateIdentityAddKey = async () => { + const identityId = 'an identity ID goes here'; + const existingIdentity = await client.platform.identities.get(identityId); + const newKeyId = existingIdentity.toJSON().publicKeys.length; + + // Get an unused identity index + const account = await client.platform.client.getWalletAccount(); + const identityIndex = await account.getUnusedIdentityIndex(); + + // Get unused private key and construct new identity public key + const { privateKey: identityPrivateKey } = + account.identities.getIdentityHDKeyByIndex(identityIndex, 0); + + const identityPublicKey = identityPrivateKey.toPublicKey().toBuffer(); + + const newPublicKey = new IdentityPublicKeyWithWitness({ + id: newKeyId, + type: IdentityPublicKey.TYPES.ECDSA_SECP256K1, + data: identityPublicKey, + purpose: IdentityPublicKey.PURPOSES.AUTHENTICATION, + securityLevel: IdentityPublicKey.SECURITY_LEVELS.CRITICAL, + readOnly: false, + signature: Buffer.alloc(0), + }); + + const updateAdd = { + add: [newPublicKey], + }; + + // Submit the update signed with the new key + await client.platform.identities.update(existingIdentity, updateAdd, { + [newPublicKey.getId()]: identityPrivateKey, + }); + + return client.platform.identities.get(identityId);}; +}; + +updateIdentityAddKey() + .then((d) => console.log('Identity updated:\n', d.toJSON())) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +:::: + +# What's Happening + +## Disabling keys + +After we initialize the Client, we retrieve our existing identity and provide the `id` of one (or more) of the identity keys to disable. The update is submitted to DAPI using the `platform.identities.update` method with two arguments: + +1. An identity +2. An object containing the key(s) to be disabled + +Internally, the method creates a State Transition containing the updated identity, signs the state transition, and submits the signed state transition to DAPI. After the identity is updated, we output it to the console. + +## Adding keys + +After we initialize the Client, we retrieve our existing identity and set an `id` for the key to be added. Next, we get an unused private key from our wallet and use it to derive a public key to add to our identity. The update is submitted to DAPI using the `platform.identities.update` method with three arguments: + +1. An identity +2. An object containing the key(s) to be added +3. An object containing the id and private key for each public key being added + +> 📘 +> +> When adding new public keys, they must be signed using the associated private key to prove ownership of the keys. + +Internally, the method creates a State Transition containing the updated identity, signs the state transition, and submits the signed state transition to DAPI. After the identity is updated, we output it to the console. \ No newline at end of file diff --git a/docs/tutorials/introduction.md b/docs/tutorials/introduction.md new file mode 100644 index 000000000..ce63f0934 --- /dev/null +++ b/docs/tutorials/introduction.md @@ -0,0 +1,29 @@ +```{eval-rst} +.. _tutorials-intro: +``` + +# Introduction + +The tutorials in this section walk through the steps necessary to begin building on Dash Platform using the Dash JavaScript SDK. As all communication happens via the masternode hosted decentralized API (DAPI), you can begin using Dash Platform immediately without running a local blockchain node. + +Building on Dash Platform requires first registering an Identity and then registering a Data Contract describing the schema of data to be stored. Once that is done, data can be stored and updated by submitting Documents that comply with the Data Contract. + +> 📘 Tutorial code +> +> You can clone a repository containing the code for all tutorials from GitHub or download it as a [zip file](https://github.com/dashevo/platform-readme-tutorials/archive/refs/heads/main.zip). + +## Prerequisites + +The tutorials in this section are written in JavaScript and use [Node.js](https://nodejs.org/en/about/). The following prerequisites are necessary to complete the tutorials: + +- [Node.js](https://nodejs.org/en/) (v12+) +- Familiarity with JavaScript asynchronous functions using [async/await](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) +- The Dash JavaScript SDK (see [Connecting to a Network](../tutorials/connecting-to-testnet.md#1-install-the-dash-sdk)) + +## Quickstart + +While going through each tutorial is advantageous, the subset of tutorials listed below get you from a start to storing data on Dash Platform most quickly: +- [Obtaining test funds](../tutorials/create-and-fund-a-wallet.md) +- [Registering an Identity](../tutorials/identities-and-names/register-an-identity.md) +- [Registering a Data Contract](../tutorials/contracts-and-documents/submit-documents.md) +- [Submitting data](../tutorials/contracts-and-documents/submit-documents.md) diff --git a/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md b/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md new file mode 100644 index 000000000..9261c9244 --- /dev/null +++ b/docs/tutorials/node-setup/connect-to-a-network-dash-core-full-node.md @@ -0,0 +1,23 @@ +# Dash Core full node + +Since Dash Platform is fully accessible via DAPI, running a full node is unnecessary and generally provides no particular benefit. Regardless, the steps below provide the necessary information for advanced users to connect. + +## Config File + + The config file shown below may be used to connect a Dash Core node to Testnet. Testnet currently operates using [Dash Core v19.3.0](https://github.com/dashpay/dash/releases/tag/v19.3.0). + +```ini dash-testnet.conf +# dash-testnet.conf +testnet=1 + +# Hard-coded first node +addnode=seed-1.testnet.networks.dash.org:19999 +``` + +## Starting Dash Core + +To start Dash Core and connect to Testnet, simply run dashd or dash-qt with the `conf` parameter set to the configuration file created above: ` -conf=` + +```shell Start dashd on Testnet +dashd -conf=/home/dash/.dashcore/dash-testnet.conf +``` \ No newline at end of file diff --git a/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md b/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md new file mode 100644 index 000000000..376e8afe2 --- /dev/null +++ b/docs/tutorials/node-setup/connect-to-a-network-dash-masternode.md @@ -0,0 +1,176 @@ +# Dash masternode + +The purpose of this tutorial is to walk through the steps necessary to set up a masternode with Dash Platform services. + +## Prerequisites +- [Docker](https://docs.docker.com/engine/install/) (v20.10.0+) and [docker-compose](https://docs.docker.com/compose/install/) (v1.25.0+) installed +- An installation of [NodeJS](https://nodejs.org/en/download/) (v16, NPM v8.0+) + +The following is not necessary for setting up a local network for development, but is helpful if setting up a testnet masternode: +- Access to a Linux system configured with a non-root user ([guide](https://docs.dash.org/en/stable/masternodes/setup.html#set-up-your-vps)) + + +> 📘 +> +> More comprehensive details of using the dashmate tool can be found in the [dashmate README](https://github.com/dashevo/platform/tree/master/packages/dashmate). + +Use NPM to install dashmate globally in your system: + +```shell +npm install -g dashmate +``` + +## Local Network + +Dashmate can be used to create a local network on a single computer. This network contains multiple nodes to mimic conditions and features found in testnet/mainnet settings. + +> 📘 +> +> Dashmate local networks use the [regtest network type](../../reference/glossary.md#regtest) so layer 1 blocks can be easily mined as needed. + +### Setup + +Run the following command to start the setup wizard, then accept the default values at each step to create a local network: + +```shell +dashmate setup local +``` + +Example (partial) output of the setup wizard showing important information: +``` + ✔ Initialize SDK + › HD private key: tprv8ZgxMBicQKsPfLTCjh8vdHkDHYM369tUeQ4aqpV9GzUfQyBKutfstB1sDfQyLERACTEYy5Qjph42gBiqqnqYmXJZZqRc4PQssGzbvwJXHnN + ✔ Register DPNS identity + › DPNS identity: 6whgUd1LzwzU4ob7K8FGCLV765K7dp2JbEmVgdTQEFxD + ✔ Register DPNS contract + › DPNS contract ID: EpCvWuoh3JcFetFY83HdwuzRUvwxF2hc3mU19MtBg2kK + ✔ Obtain DPNS contract commit block height + › DPNS contract block height: 5 + ✔ Register top level domain "dash" + ✔ Register identity for Dashpay + › Dashpay's owner identity: 2T7kLcbJzQrLhBV6BferW42Jimb3BJ5zAAore42mfNyE + ✔ Register Dashpay Contract + › Dashpay contract ID: EAv8ePXREdJ719ntcRiKuEYxv9XooMwL1mJmPHMGuW9r + ✔ Obtain Dashpay contract commit block height + › Dashpay contract block height: 15 + ✔ Register Feature Flags identity + › Feature Flags identity: 8BsvV4RCbW7srWj81kgjJCykRBF2rzyigys8XkBchY96 + ✔ Register Feature Flags contract + › Feature Flags contract ID: JDrDAGVqTWsM9k7KGBsSjcyC11Vd2UdPxPoPf4NzyyrP + ✔ Obtain Feature Flags contract commit block height + › Feature Flags contract block height: 20 + +``` + +> 📘 +> +> Make a note of the key and identity information displayed during setup as they may be required in the future. + +### Operation + +Once the setup completes, start/stop/restart the network via the following commands: + +```shell +dashmate group start +dashmate group stop +dashmate group restart +``` + +The status of the network's nodes can be check via the group status command: + +```shell +dashmate group status +``` + +### Mining Dash + +During development it may be necessary to obtain Dash to create and topup [identities](../../explanations/identity.md). This can be done using the dashmate `wallet:mint` command. First obtain an address to fund via the [Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) tutorial and then mine Dash to it as shown below: + +::::{tab-set-code} + +```shell Mine to provided address +# Mine to provided address + +# Stop the devnet first +dashmate group stop + +# Mine 10 Dash to a provided address +dashmate wallet mint 10 --address= --config=local_seed + +# Restart the devnet +dashmate group start +``` +```shell Mine to new address +# Mine to new address + +# Stop the devnet first +dashmate group:stop + +# Mine 10 Dash to a random address/key +# The address and private key will be displayed +dashmate wallet:mint 10 --config=local_seed + +# Restart the devnet +dashmate group:start +``` + +:::: + +Example output of `dashmate wallet mint 10 --address=yYqfdpePzn2kWtMxr9nz22HBFM7WBRmAqG --config=local_seed`: + +```text +✔ Generate 10 dash to address + ✔ Start Core + ↓ Use specified address yYqfdpePzn2kWtMxr9nz22HBFM7WBRmAqG [SKIPPED] + ✔ Generate ≈10 dash to address yYqfdpePzn2kWtMxr9nz22HBFM7WBRmAqG + › Generated 172.59038279 dash + ✔ Wait for balance to confirm + ✔ Stop Core +``` + +### Using the network + +Once the address is funded, you can begin creating identities, data contracts, etc. and experimenting with Dash Platform. The [other tutorials](../../tutorials/introduction.md) in this section will help you get started. + +To make the Dash SDK connect to your local network, set the `network` option to `'local'`: + +```javascript +const clientOpts = { + network: 'local', + ... +}; + +const client = new Dash.Client(clientOpts); +``` + +## Testnet Masternode Setup + +> ❗️ Advanced Topic +> +> Running a masternode requires familiarity with Dash Platform services. Improper configuration may impact testing so please exercise caution if running a masternode. + +To setup a testnet masternode, please refer to the comprehensive documentation of the process as described [here](https://docs.dash.org/en/stable/masternodes/setup-testnet.html#dashmate-installation). The following video also details how to complete the process. + +```{eval-rst} +.. raw:: html + +
+ +
+``` + +> 📘 Full Platform Node +> +> A full node that with all Platform services can be started by simply running the setup command with the [node type setup parameter](https://github.com/dashevo/platform/tree/master/packages/dashmate#setup-node) set to `fullnode` and then starting the node. +> ``` +> dashmate setup testnet fullnode +> dashmate start +> ``` + +## Remote Development Network + +> 📘 Connecting to a remote development network +> +> In order to connect to a remote [devnet](../../reference/glossary.md#devnet) (e.g. one run by Dash Core Group), please use one of the methods described in the [Connect to a Devnet](../../tutorials/connecting-to-testnet.md#connect-to-a-devnet) section. + +For development we recommend using either a local network created via dashmate as [described above](#local-network) or using Testnet. While configuring a remote development network is possible using the Dash network deployment tool, it is beyond the scope of this documentation. For details regarding this tool, please refer to the [GitHub repository](https://github.com/dashevo/dash-network-deploy). \ No newline at end of file diff --git a/docs/tutorials/send-funds.md b/docs/tutorials/send-funds.md new file mode 100644 index 000000000..52c2b9b86 --- /dev/null +++ b/docs/tutorials/send-funds.md @@ -0,0 +1,51 @@ +# Send funds + +Once you have a wallet and some funds ([tutorial](../tutorials/create-and-fund-a-wallet.md)), another common task is sending Dash to an address. (Sending Dash to a contact or a DPNS identity requires the Dashpay app, which has not been registered yet.) + +# Code + +> 📘 Wallet Operations +> +> The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. `client.getWalletAccount()`) which can result in wait times of 5+ minutes. +> +> A future release will add caching so that access is much faster after the initial sync. For now, the `skipSynchronizationBeforeHeight` option can be used to sync the wallet starting at a certain block height. + +```javascript +const Dash = require('dash'); + +const clientOpts = { + network: 'testnet', + wallet: { + mnemonic: 'your wallet mnemonic goes here', + unsafeOptions: { + skipSynchronizationBeforeHeight: 650000, // only sync from early-2022 + }, + }, +}; +const client = new Dash.Client(clientOpts); + +const sendFunds = async () => { + const account = await client.getWalletAccount(); + + const transaction = account.createTransaction({ + recipient: 'yP8A3cbdxRtLRduy5mXDsBnJtMzHWs6ZXr', // Testnet2 faucet + satoshis: 100000000, // 1 Dash + }); + return account.broadcastTransaction(transaction); +}; + +sendFunds() + .then((d) => console.log('Transaction broadcast!\nTransaction ID:', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); + +// Handle wallet async errors +client.on('error', (error, context) => { + console.error(`Client error: ${error.name}`); + console.error(context); +}); +``` + +# What's Happening + +After initializing the Client, we build a new transaction with `account.createTransaction`. It requires a recipient and an amount in satoshis (often called "duffs" in Dash). 100 million satoshis equals one Dash. We pass the transaction to `account.broadcastTransaction` and wait for it to return. Then we output the result, which is a transaction ID. After that we disconnect from the Client so node can exit. \ No newline at end of file diff --git a/docs/tutorials/setup-a-node.md b/docs/tutorials/setup-a-node.md new file mode 100644 index 000000000..8c9518acd --- /dev/null +++ b/docs/tutorials/setup-a-node.md @@ -0,0 +1,12 @@ +# Set up a node + +Since Dash Platform is accessible through DAPI, running a node is typically unnecessary. The information provided in this section is for advanced users interested in running their own network for development or participating in testing the project by running a testnet node. + +```{toctree} +:maxdepth: 2 +:titlesonly: +:hidden: + +node-setup/connect-to-a-network-dash-masternode +node-setup/connect-to-a-network-dash-core-full-node +``` diff --git a/docs/tutorials/use-dapi-client-methods.md b/docs/tutorials/use-dapi-client-methods.md new file mode 100644 index 000000000..4111d00dd --- /dev/null +++ b/docs/tutorials/use-dapi-client-methods.md @@ -0,0 +1,34 @@ +# Use DAPI client methods + +In addition to the SDK methods for interacting with identities, names, contracts, and documents, the SDK also provides direct access to DAPI client methods. + +## Prerequisites + +- [General prerequisites](../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) + +# Code + +The following example demonstrates several of the Core DAPI client methods. DAPI client also has several Platform methods accessible via `getDAPIClient().platform.*`. The methods can be found here in the [js-dapi-client repository](https://github.com/dashevo/platform/tree/master/packages/js-dapi-client/lib/methods). + +```javascript +const Dash = require('dash'); + +const client = new Dash.Client({ network: 'testnet' }); + +async function dapiClientMethods() { + console.log(await client.getDAPIClient().core.getBlockHash(1)); + console.log(await client.getDAPIClient().core.getBestBlockHash()); + console.log(await client.getDAPIClient().core.getBlockByHeight(1)); + + return client.getDAPIClient().core.getStatus(); +} + +dapiClientMethods() + .then((d) => console.log('Core status:\n', d)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +> 📘 +> +> Examples using DAPI client to access many of the DAPI endpoints can be found in the [DAPI Endpoint Reference section](../reference/dapi-endpoints.md). \ No newline at end of file diff --git a/img/dapi.svg b/img/dapi.svg new file mode 100644 index 000000000..d9f30e7f1 --- /dev/null +++ b/img/dapi.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/dash-d.png b/img/dash-d.png new file mode 100644 index 000000000..c02c266cc Binary files /dev/null and b/img/dash-d.png differ diff --git a/img/dash_logo.png b/img/dash_logo.png new file mode 100644 index 000000000..a00358aae Binary files /dev/null and b/img/dash_logo.png differ diff --git a/img/dash_logo_white.png b/img/dash_logo_white.png new file mode 100644 index 000000000..20466d376 Binary files /dev/null and b/img/dash_logo_white.png differ diff --git a/img/data-contract.svg b/img/data-contract.svg new file mode 100644 index 000000000..f8f863bb1 --- /dev/null +++ b/img/data-contract.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/drive.svg b/img/drive.svg new file mode 100644 index 000000000..ef4044bb0 --- /dev/null +++ b/img/drive.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/join-community.svg b/img/join-community.svg new file mode 100644 index 000000000..e9ed63074 --- /dev/null +++ b/img/join-community.svg @@ -0,0 +1,4860 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/platform-state.svg b/img/platform-state.svg new file mode 100644 index 000000000..619c49d03 --- /dev/null +++ b/img/platform-state.svg @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/state-transition.svg b/img/state-transition.svg new file mode 100644 index 000000000..1214ab6b5 --- /dev/null +++ b/img/state-transition.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/index.md b/index.md new file mode 100644 index 000000000..34ed41492 --- /dev/null +++ b/index.md @@ -0,0 +1,68 @@ +```{eval-rst} +.. meta:: + :description: The Dash Documentation offers information and guides on Dash, the open source peer-to-peer cryptocurrency with a strong focus on the payments industry. + +================== +Dash Documentation +================== + +Dash aims to be the most user-friendly and scalable payments-focused +cryptocurrency in the world. The Dash network features instant transaction +confirmation, double spend protection, optional privacy equal to that of +physical cash, a self-governing, and a self-funding model driven by incentivized +full nodes. While Dash is based on Bitcoin and compatible with many key +components of the Bitcoin ecosystem, its two-tier network structure offers +significant improvements in transaction speed, privacy and governance. This +section of the documentation describes these and many more key features that set +Dash apart in the blockchain economy. + +Check out the `official Dash website `__ to learn how +`individuals `__ and `businesses +`__ can use Dash. + +.. grid:: 1 3 3 3 + + .. grid-item-card:: 👤 User Docs + :margin: 2 2 auto auto + :link-type: ref + :link: user:user-index + + Learn what Dash is and how it works. Topics include how to obtain and store Dash, the governance system, and masternode setup. + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: ⚙ Core Docs + :margin: 2 2 auto auto + :link-type: ref + :link: core:core-index + + Find technical details about the Dash Core blockchain, along with protocol and API reference material. + + +++ + :ref:`Click to begin ` + + .. grid-item-card:: 🚀 Platform Docs + :margin: 2 2 auto auto + :link-type: ref + :link: platform-index + + Start working with Dash Platform and discover how you can use its powerful capabilities to power your Web3 project. + + +++ + `Click to begin `__ + +.. toctree:: + :maxdepth: 3 + :titlesonly: + :hidden: + + docs/index +``` + +```{eval-rst} +.. image:: https://raw.githubusercontent.com/dashpay/docs/master/img/businessplan.svg + :class: no-scaled-link + :align: center + :width: 90% +``` diff --git a/make.bat b/make.bat new file mode 100644 index 000000000..954237b9b --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/requirements.txt b/requirements.txt index d48fdda0c..f83fd3132 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,10 @@ Babel==2.12.1 myst-parser==1.0.0 pydata-sphinx-theme==0.12.0 +readthedocs-sphinx-search==0.3.1 +pytz==2022.7 sphinx==5.3.0 sphinx-copybutton==0.5.2 sphinx-hoverxref==1.3.0 -sphinx-multiproject==1.0.0rc1 sphinx_design==0.4.1 jinja2==3.1.2 \ No newline at end of file diff --git a/scripts/1-readme-rename.sh b/scripts/1-readme-rename.sh new file mode 100755 index 000000000..15900b4b9 --- /dev/null +++ b/scripts/1-readme-rename.sh @@ -0,0 +1,23 @@ +#!/bin/bash + +RENAME_ARGS="-d" + +find docs/dapi-client-js -iname "*.md" -type f -name 'dapi-client-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dapi-client-//' +find docs/dapi-client-js/usage -iname "*.md" -type f -name 'usage-*' -print0 | xargs -0 rename $RENAME_ARGS 's/usage-//' +find docs/explanations -iname "*.md" -type f -name 'explanation-*' -print0 | xargs -0 rename $RENAME_ARGS 's/explanation-//' +find docs/intro -iname "*.md" -type f -name 'introduction-*' -print0 | xargs -0 rename $RENAME_ARGS 's/introduction-//' +find docs/intro -iname "*.md" -type f -name 'intro-*' -print0 | xargs -0 rename $RENAME_ARGS 's/intro-//' +find docs/protocol-ref -iname "*.md" -type f -name 'platform-protocol-reference-*' -print0 | xargs -0 rename $RENAME_ARGS 's/platform-protocol-reference-//' +find docs/reference -iname "*.md" -type f -name 'reference-*' -print0 | xargs -0 rename $RENAME_ARGS 's/reference-//' +find docs/resources -iname "*.md" -type f -name 'resources-*' -print0 | xargs -0 rename $RENAME_ARGS 's/resources-//' +find docs/sdk-js -iname "*.md" -type f -name 'dash-sdk-overview*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-//' +find docs/sdk-js/examples -iname "*.md" -type f -name 'dash-sdk-examples-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-examples-//' +find docs/sdk-js/getting-started -iname "*.md" -type f -name 'dash-sdk-getting-started-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-getting-started-//' +find docs/sdk-js/platform -iname "*.md" -type f -name 'dash-sdk-contracts-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-contracts-//' +find docs/sdk-js/platform -iname "*.md" -type f -name 'dash-sdk-documents-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-documents-//' +find docs/sdk-js/platform -iname "*.md" -type f -name 'dash-sdk-identities-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-identities-//' +find docs/sdk-js/platform -iname "*.md" -type f -name 'dash-sdk-names-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-names-//' +find docs/sdk-js/usage -iname "*.md" -type f -name 'dash-sdk-usage-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-usage-//' +find docs/sdk-js/wallet -iname "*.md" -type f -name 'dash-sdk-wallet-*' -print0 | xargs -0 rename $RENAME_ARGS 's/dash-sdk-wallet-//' +find docs/tutorials -iname "*.md" -type f -name 'tutorials-*' -print0 | xargs -0 rename $RENAME_ARGS 's/tutorials-//' +find docs/tutorials -iname "*.md" -type f -name 'tutorial-*' -print0 | xargs -0 rename $RENAME_ARGS 's/tutorial-//' diff --git a/scripts/2-readme-link-conversion-from-backup.sh b/scripts/2-readme-link-conversion-from-backup.sh new file mode 100755 index 000000000..26b405bf0 --- /dev/null +++ b/scripts/2-readme-link-conversion-from-backup.sh @@ -0,0 +1,119 @@ +#!/bin/bash + +# This script converts the readme.io link to one that will work with ReadTheDocs +# +# The format here is: +# 's~](~](\.\.//~g' +# +# So in this example: 's~](reference-dapi-endpoints-core-grpc-endpoints~](\.\./reference/dapi-endpoints-core-grpc-endpoints.md~g' +# The repo directory is "reference" +# And the file in that repository is "dapi-endpoints-core-grpc-endpoints.md" + +# Directory-specific changes +# +# These need to be done first because they work on specific directories. This is necessary because +# tutorials have a sub-directory so links in them need to go up 2 levels (../../) to get to the +# right location. + +# Reference +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](reference-glossary~](\.\./\.\./reference/glossary.md~g' {} + +find ./docs/tutorials/node-setup -iname "*.md" -exec sed -i 's~](reference-glossary~](\.\./\.\./reference/glossary.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](reference-data-contracts~](\.\./\.\./reference/data-contracts.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](reference-query-syntax~](\.\./\.\./reference/query-syntax.md~g' {} + + +# Explanation +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](explanation-dpns~](\.\./\.\./explanations/dpns.md~g' {} + +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](explanation-identity~](\.\./\.\./explanations/identity.md~g' {} + +find ./docs/tutorials/node-setup -iname "*.md" -exec sed -i 's~](docs/explanation-identity~](\.\./\.\./explanations/identity.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](explanation-dapi~](\.\./\.\./explanations/dapi.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-data-contract~](\.\./\.\./explanations/platform-protocol-data-contract.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-state-transition~](\.\./\.\./explanations/platform-protocol-state-transition.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-document~](\.\./\.\./explanations/platform-protocol-document.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-data-trigger~](\.\./\.\./explanations/platform-protocol-data-trigger.md~g' {} + + +# Tutorials +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](tutorials-introduction#~](\.\./\.\./tutorials/introduction.md#~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorials-introduction#~](\.\./\.\./tutorials/introduction.md#~g' {} + +find ./docs/tutorials/node-setup -iname "*.md" -exec sed -i 's~](tutorials-introduction~](\.\./\.\./tutorials/introduction.md~g' {} + + +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](tutorial-create-and-fund-a-wallet~](\.\./\.\./tutorials/create-and-fund-a-wallet.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorial-create-and-fund-a-wallet~](\.\./\.\./tutorials/create-and-fund-a-wallet.md~g' {} + +find ./docs/tutorials/node-setup -iname "*.md" -exec sed -i 's~](doc:tutorial-create-and-fund-a-wallet~](\.\./\.\./tutorials/create-and-fund-a-wallet.md~g' {} + + +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](tutorial-register-an-identity~](\.\./\.\./tutorials/identities-and-names/register-an-identity.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorial-register-an-identity~](\.\./\.\./tutorials/identities-and-names/register-an-identity.md~g' {} + +find ./docs/tutorials/identities-and-names -iname "*.md" -exec sed -i 's~](tutorial-register-a-name-for-an-identity~](\.\./\.\./tutorials/identities-and-names/register-a-name-for-an-identity.md~g' {} + + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorial-submit-documents~](\.\./\.\./tutorials/contracts-and-documents/submit-documents.md~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorial-register-a-data-contract#section-code~](\.\./\.\./tutorials/contracts-and-documents/register-a-data-contract.md#code~g' {} + +find ./docs/tutorials/contracts-and-documents -iname "*.md" -exec sed -i 's~](tutorial-register-a-data-contract~](\.\./\.\./tutorials/contracts-and-documents/register-a-data-contract.md~g' {} + +find ./docs/tutorials/node-setup -iname "*.md" -exec sed -i 's~](tutorial-connecting-to-testnet~](\.\./\.\./tutorials/connecting-to-testnet.md~g' {} + + + +# General changes (apply to all files in the project) + +# Introduction +find . -iname "*.md" -exec sed -i 's~](doc:intro-to-testnet~](\.\./intro/to-testnet.md~g' {} + + +# Tutorials +find . -iname "*.md" -exec sed -i 's~](tutorials-introduction~](\.\./tutorials/introduction.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-create-and-fund-a-wallet~](\.\./tutorials/create-and-fund-a-wallet.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-submit-documents~](\.\./tutorials/contracts-and-documents/submit-documents.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-register-a-data-contract~](\.\./tutorials/contracts-and-documents/submit-documents.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-register-an-identity~](\.\./tutorials/identities-and-names/register-an-identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-register-a-name-for-an-identity~](\.\./tutorials/identities-and-names/register-a-name-for-an-identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-register-an-identity~](\.\./tutorials/identities-and-names/register-an-identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-retrieve-an-accounts-identities~](\.\./tutorials/identities-and-names/retrieve-an-accounts-identities.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-topup-an-identity-balance~](\.\./tutorials/identities-and-names/topup-an-identity-balance.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-register-a-name-for-an-identity~](\.\./tutorials/identities-and-names/register-a-name-for-an-identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-retrieve-a-name~](\.\./tutorials/identities-and-names/retrieve-a-name.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](tutorial-connecting-to-testnet~](\.\./tutorials/connecting-to-testnet.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-register-a-data-contract~](\.\./tutorials/contracts-and-documents/register-a-data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-retrieve-a-data-contract~](\.\./tutorials/contracts-and-documents/retrieve-a-data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-update-a-data-contract~](\.\./tutorials/contracts-and-documents/update-a-data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-submit-documents~](\.\./tutorials/contracts-and-documents/submit-documents.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-retrieve-documents~](\.\./tutorials/contracts-and-documents/retrieve-documents.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-update-documents~](\.\./tutorials/contracts-and-documents/update-documents.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:tutorial-delete-documents~](\.\./tutorials/contracts-and-documents/delete-documents.md~g' {} + + +# Explanations +find . -iname "*.md" -exec sed -i 's~](explanation-dapi~](\.\./explanations/dapi.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-dpns~](\.\./explanations/dpns.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:explanation-dpns~](\.\./explanations/dpns.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-identity~](\.\./explanations/identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-drive-platform-chain~](\.\./explanations/drive-platform-chain.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-drive-platform-state~](\.\./explanations/drive-platform-state.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-drive~](\.\./explanations/drive.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-data-contract~](\.\./explanations/platform-protocol-data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:explanation-platform-protocol-data-contract~](\.\./explanations/platform-protocol-data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-data-trigger~](\.\./explanations/platform-protocol-data-trigger.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-state-transition~](\.\./explanations/platform-protocol-state-transition.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-platform-protocol-document~](\.\./explanations/platform-protocol-document.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:explanation-platform-protocol-document~](\.\./explanations/platform-protocol-document.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-platform-protocol~](\.\./explanations/platform-protocol.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](doc:explanation-platform-consensus~](\.\./explanations/platform-consensus.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](explanation-dashpay~](\.\./explanations/dashpay.md~g' {} + + +# Reference +find . -iname "*.md" -exec sed -i 's~](reference-dapi-endpoints-core-grpc-endpoints~](\.\./reference/dapi-endpoints-core-grpc-endpoints.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-dapi-endpoints-grpc-overview~](\.\./reference/dapi-endpoints-grpc-overview.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-dapi-endpoints-json-rpc-endpoints~](\.\./reference/dapi-endpoints-json-rpc-endpoints.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-dapi-endpoints-platform-endpoints~](\.\./reference/dapi-endpoints-platform-endpoints.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-dapi-endpoints~](\.\./reference/dapi-endpoints.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-glossary~](\.\./reference/glossary.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-query-syntax~](\.\./reference/query-syntax.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](reference-data-contracts~](\.\./reference/data-contracts.md~g' {} + + +# Platform Protocol Reference +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-data-contract#~](\.\./protocol-ref/data-contract.md#~g' {} + +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-data-contract~](\.\./protocol-ref/data-contract.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-data-trigger~](\.\./protocol-ref/data-trigger.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-document~](\.\./protocol-ref/document.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-identity~](\.\./protocol-ref/identity.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](platform-protocol-reference-state-transition~](\.\./protocol-ref/state-transition.md~g' {} + +find . -iname "*.md" -exec sed -i 's~](data-contract-version~](#data-contract-version~g' {} + +find ./docs/protocol-ref/errors.md -iname "*.md" -exec sed -i 's~](#signature)~](#signature-errors)~g' {} + +find ./docs/protocol-ref/errors.md -iname "*.md" -exec sed -i 's~](#fee)~](#fee-errors)~g' {} + + +# Resources +