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 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 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-hpp:

{ "$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.hellar.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 (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 the platform should take for the associated document
$dataContractId array Data 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": "<https://json-schema.org/draft/2020-12/schema>", "type": "object", "properties": { "$id": { "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, "contentMediaType": "application/x.hellar.hpp.identifier" }, "$type": { "type": "string" }, "$action": { "type": "integer", "enum": [0, 1, 3] }, "$dataContractId": { "type": "array", "byteArray": true, "minItems": 32, "maxItems": 32, "contentMediaType": "application/x.hellar.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-hpp.

`// From the Rust reference implementation (rs-hpp) // 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<u8> = 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. Generated as shown here. (32 bytes)
$createdAt integer (Optional)
$updatedAt integer (Optional)

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

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