Document

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 reference implementation, the base fields shown below are defined in the document base fields.

Field Name	Description
$id	The document ID (32 bytes)
$type	Document type defined in the referenced contract
$revision	Document revision (=>1)
$dataContractId	Data contract the document is associated with (32 bytes)
$ownerId	Identity 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
$transferredAt	Time (in milliseconds) the document was last transferred
$createdAtBlockHeight	Platform block height when the document was created
$updatedAtBlockHeight	Platform block height when the document was last updated
$transferredAtBlockHeight	Platform block height when the document was last transferred
$createdAtCoreBlockHeight	Core block height when the document was created
$updatedAtCoreBlockHeight	Core block height when the document was last updated
$transferredAtCoreBlockHeight	Core block height when the document was last transferred
$creatorId	Identity that originally created the document (32 bytes). Present on document types that are transferable or have a trade mode set, and preserved when ownership changes

Attention

The timestamp and block height fields will only be present in documents that add them to the list of required properties.

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 Type	Field Name	Data Type
preorder	saltedDomainHash	array (32 bytes)
—	—	—
domain	label	string
domain	normalizedLabel	string
domain	parentDomainName	string
domain	normalizedParentDomainName	string
domain	preorderSalt	array (bytes)
domain	records	object
domain	records.identity	array (32 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.

{
  "$id": "3AhZ5h63ZrFJXfE3YP3iEFVxyndYWPMxR9fSEaMo67QJ",
  "$type": "domain",
  "$dataContractId": "GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec",
  "$ownerId": "6TGHW8WBcNzFrWwAueGtqtAah7w98EELFZ7xdTHegnvH",
  "$revision": 1,
  "$createdAt": 1712872800000,
  "$updatedAt": 1712872800000,
  "$transferredAt": 1712872800000,
  "label": "DQ-Jasen-82083",
  "normalizedLabel": "dq-jasen-82083",
  "normalizedParentDomainName": "dash",
  "parentDomainName": "dash",
  "preorderSalt": "bcCSdtGqqZdXBQB4DDBIU2RPAwFDFt9tMr0LX6m5qCQ=",
  "records": {
    "identity": "UQTRY+wqPyL27V7YjJadJdyXVBETj6CfzvqUg5aY5E4="
  },
  "subdomainRules": {
    "allowSubdomains": false
  }
}

Document Submission

Once a document has been created, it must be encapsulated in a Batch state transition to be sent to the platform. Batch state transitions (type 1) bundle one or more document and/or token transitions submitted together by the same identity. For additional details, see the State Transition explanation.

Field Name	Description
type	State transition type (1 for a Batch)
ownerId	Identity submitting the batch
transitions	Document and token transitions bundled in the batch (e.g. document create, replace, delete, transfer, purchase, updatePrice)
userFeeIncrease	Optional amount the submitter adds to the fee to raise the priority of the batch and improve its chance of timely inclusion
signaturePublicKeyId	The id of the identity public key that signed the state transition
signature	Signature of state transition data

State transitions are versioned through their serialized enum representation rather than a top-level protocolVersion field.

Document Transition Base

Every document transition in a batch shares a common base, regardless of the action it performs. The base identifies which document the transition targets - the document ID, its type, and the data contract that defines it - and adds two further elements:

• A per-identity, per-contract nonce that orders an identity’s transitions against a given contract and prevents a transition from being replayed.

• Optional token payment information, used when the contract charges one of its tokens for the action rather than charging the submitter in credits. See the Tokens explanation for how token-based document fees are configured.

The sections below describe the fields each action adds on top of this shared base.

Document Create

The document create transition is used to create a new document on Dash Platform. The document create transition extends the transition base to include the following additional fields:

Field	Type	Description
$entropy	array (32 bytes)	Entropy used in creating the document ID
$prefundedVotingBalance	object	(Optional) Credits set aside to fund masternode voting when the document contests a unique index

The transition does not carry timestamp or block height fields. Platform assigns those from the block in which the transition is processed, and they appear on the resulting document only when the data contract sets them as required for the document type.

Creating a document on a contested unique index requires setting aside a prefunded voting balance. Those credits fund the masternode vote that decides which of the competing identities receives the resource. This is the mechanism behind contested DPNS names - see the Name Service explanation for how it applies to username registration.

Document Replace

The document replace transition is used to update the data in an existing Dash Platform document. The document replace transition extends the transition base to include the following additional fields:

Field	Type	Description
$revision	integer	Document revision (=> 1)

If the data contract sets the updated at timestamp as required for the document type, Platform assigns the updated timestamp and block height from block info rather than accepting them from the caller.

Document Delete

The document delete transition is used to delete an existing Dash Platform document. It only requires the fields found in the transition base.

Document Transfer

The document transfer transition is used to transfer ownership of an existing document to another identity. It extends the transition base with the recipient identifier:

Field	Type	Description
$revision	integer	Document revision (=> 1)
recipientOwnerId	array (32 bytes)	The identity receiving ownership of the document

Document transfers are only allowed for document types that are marked transferable in the data contract.

Document Purchase

The document purchase transition is used to buy a document that the current owner has listed for sale. It extends the transition base with the agreed price:

Field	Type	Description
$revision	integer	Document revision (=> 1)
price	integer	Price (in credits) the buyer is paying, which must match the document’s current listed price

Document purchases are only allowed for document types whose trade mode permits sale.

Document Update Price

The document update price transition is used by the current owner to list a document for sale (or change its listed price). It extends the transition base with the new price:

Field	Type	Description
$revision	integer	Document revision (=> 1)
$price	integer	New price (in credits) at which the document is offered for sale

Note

For more detailed information, see the Platform Protocol Reference - Document page.