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 Submission

Documents are sent to the platform by submitting the them in a document batch state transition consisting of:

FieldTypeDescription
protocolVersionintegerThe platform protocol version (currently 0)
typeintegerState transition type (1 for document batch)
ownerIdarrayIdentity submitting the document(s) (32 bytes)
transitionsarray of transition objectsDocument create, replace, or delete transitions (up to 10 objects)
signaturePublicKeyIdnumberThe id of the identity public key that signed the state transition
signaturearraySignature of state transition data (65 bytes)

Each document batch state transition must comply with this JSON-Schema definition established in js-dpp:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "properties": {
    "protocolVersion": {
      "type": "integer",
      "minimum": 0,
      "maximum": 0,
      "$comment": "Maximum is the latest Documents Batch Transition 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": 65
    }
  },
  "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:

FieldTypeDescription
$idarrayThe document ID (32 bytes)
$typestringName of a document type found in the data contract associated with the dataContractId
$actionarray of integersAction the platform should take for the associated document
$dataContractIdarrayData contract ID generated from the data contract's ownerId and entropy (32 bytes)

Each document transition must comply with the document transition base schema:

{
  "$schema": "http://json-schema.org/draft-07/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 here.

// From the JavaScript reference implementation (js-dpp)
// generateDocumentId.js
function generateDocumentId(contractId, ownerId, type, entropy) {
  return hash(Buffer.concat([
    contractId,
    ownerId,
    Buffer.from(type),
    entropy,
  ]));
}

Document Transition Action

ActionNameDescription
0CreateCreate a new document with the provided data
1ReplaceReplace an existing document with the provided data
2RESERVEDUnused action
3DeleteDelete the referenced document

Document Create Transition

The document create transition extends the base schema to include the following additional fields:

FieldTypeDescription
$entropyarrayEntropy used in creating the document ID. Generated as shown here. (32 bytes)
$createdAtinteger(Optional)
$updatedAtinteger(Optional)

Each document create transition must comply with this JSON-Schema definition established in js-dpp (in addition to the document transition base schema) that is required for all document transitions):

{
  "$schema": "http://json-schema.org/draft-07/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:

{
  "$action": 0,
  "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8",
  "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP",
  "$type": "note",
  "$entropy": "yfo6LnZfJ5koT2YUwtd8PdJa8SXzfQMVDz",
  "message": "Tutorial Test @ Mon, 27 Apr 2020 20:23:35 GMT"
}
FieldRequired By
$actionDocument base transition
$dataContractIdDocument base transition
$idDocument base transition
$typeDocument base transition
$entropyDocument create transition
messageData 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:

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

Each document replace transition must comply with this JSON-Schema definition established in js-dpp (in addition to the document transition base schema) that is required for all document transitions):

{
  "$schema": "http://json-schema.org/draft-07/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:

{
  "$action": 1,
  "$dataContractId": "5wpZAEWndYcTeuwZpkmSa8s49cHXU5q2DhdibesxFSu8",
  "$id": "6oCKUeLVgjr7VZCyn1LdGbrepqKLmoabaff5WQqyTKYP",
  "$type": "note",
  "$revision": 1,
  "message": "Tutorial Test @ Mon, 27 Apr 2020 20:23:35 GMT"
}
FieldRequired By
$actionDocument base transition
$dataContractIdDocument base transition
$idDocument base transition
$typeDocument base transition
$revisionDocument revision
messageData 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.

Example Document Batch State Transition

{
  "protocolVersion": 0,
  "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 JavaScript reference client (js-dpp):

PropertyTypeRequiredDescription
protocolVersionintegerYesThe platform protocol version (currently 0)
$idarrayYesThe document ID (32 bytes)
$typestringYesDocument type defined in the referenced contract
$revisionintegerNoDocument revision (=>1)
$dataContractIdarrayYesData contract ID generated from the data contract's ownerId and entropy (32 bytes)
$ownerIdarrayYesIdentity of the user submitting the document (32 bytes)
$createdAtinteger(Optional)Time (in milliseconds) the document was created
$updatedAtinteger(Optional)Time (in milliseconds) the document was last updated

Each document object must comply with this JSON-Schema definition established in js-dpp:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "$protocolVersion": {
      "type": "integer",
      "minimum": 0,
      "maximum": 0,
      "$comment": "Maximum is the latest Document 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

{
  "$protocolVersion": 0,
  "$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
}

Did this page help you?