Hey! These docs are for version 0.17.0, which is no longer officially supported. Click here for the latest version, 0.21.0!

Document

Dash Platform application data records

Overview

Dash Platform is based on 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 similar to common document-oriented databases like MongoDB, CouchDB, or Firebase.

Documents are defined in an application's Data Contract 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, the base fields shown below are defined in the document base schema.

Field NameDescription
protocolVersionThe platform protocol version (currently 0)
$idThe document ID (32 bytes)
$typeDocument type defined in the referenced contract
$revisionDocument revision (=>1)
$dataContractIdData contract ID generated from the data contract's ownerId and entropy (32 bytes)
$ownerIdIdentity of the user submitting the document (32 bytes)
$createdAtTime (in milliseconds) the document was created
$updatedAtTime (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.

Data Contract Fields

Each application defines its own fields via document definitions in its data contract. Details of the DPNS data contract documents 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.

Document NameField NameData Type
preordersaltedDomainHashstring
---------
domainlabelstring
domainnormalizedLabelstring
domainnormalizedParentvDomainNamestring
domainpreorderSaltarray (bytes)
domainrecordsobject
domainrecords.dashUniqueIdentityIdarray (bytes)
domainrecords.dashAliasIdentityIdarray (bytes)
domainsubdomainRulesobject
domainsubdomainRules.allowSubdomainsboolean

Example Document

The following example shows the structure of a DPNS domain document as output from the document .toJSON() method. Note the $ prefix indicating the base fields.

{
  '$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'
}

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 explanation.

Field NameDescription
protocolVersionDash Platform Protocol version (currently 0)
typeState transition type (1 for documents)
ownerIdIdentity submitting the document(s)
transitionsDocument create, replace, or delete transitions (up to 10 objects)
signaturePublicKeyIdThe id of the identity public key that signed the state transition
signatureSignature 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 to include the following additional fields:

FieldTypeDescription
$entropyarray (32 bytes)Entropy used in creating the document ID
$createdAtinteger(Optional)
$updatedAtinteger(Optional)

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 to include the following additional fields:

FieldTypeDescription
$revisionintegerDocument revision (=> 1)
$updatedAtinteger(Optional)

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.


Did this page help you?