getDocumentProof

Retrieve a blockchain proof for a single document

Definition

getDocumentProof returns a structured Chainpoint format receipt, which cryptographically proves that a document for a specific version is included within that versions hash. This can be used to prove an individual document is included within a version without having to access other documents in a version.

The getDocumentProof command has the following form:

JavaScript

{
    "getDocumentProof":  {
         "collection": <string>,
         "filter": <document>,
         "version": <number>,
         "format": <string>
    }
}

The command accepts the following fields:

Field	Type	Mandatory	Description
collection	string	yes	The collection name which the document belongs to.
filter	document	yes	The condition to filter the documents.
version	number	yes	The versions for the proof. The first version proof after the document will be created will be selected as the document proof.
format	string	no	Either binary or json. Default is json.

📘

Note

A document can have more than one version, and a version of a document can have more than one proof. Once you create a version of a document, any version proof submitted while the document version remains in effect is sufficient to prove the document. However, the proof created most recently after the document is created is the "best" proof, since its blockchain timestamp will be closest to the document creation date. We use that most recent version proof to create the document proof.

Output

The returned document contains a subset of the following fields:

Field	Type	Description
ok	number	The status of the command.
proofs	array	The proofs array returned can be empty or contain one or more Document Proof.

Document Proof

A single document proof contains a subset of the following fields:

Field	Type	Description
collection	string	The collection of the document.
scope	string	The scope of the proof.
provenDbId	any	The provenDbId of the document. It refers to _provendb_metadata._id.
documentId	any	The document's _id
version	number	The version that the document is first proved.
status	string	The proof status.
errmsg	string	The proof error message, if any.
btcTransaction	string	The BTC transaction ID of the proof.
btcBlockNumber	string	The BTC block number the proof is anchored to.
versionProofId	string	The proof ID of the proof returned.
documentHash	string	The hash of the document submitted in the proof's version hash.
versionHash	string	The hash of the version submitted in the proof.
proof	binary or object	The proof for the document. It can be either binary or JSON object depending on the format requested. Default is JSON object.

Example

Return proofs for any document in the collection files_5c6b4735769348aee6f8fd00 with the string "Last Will and Testement" in the name attribute as of version 8 of the database:

JavaScript

mongo>db.runCommand({getDocumentProof:{
...    collection:'files_5c6b4735769348aee6f8fd00' ,
...    filter:{name:{$regex:"Last Will and Testement"}},
...    version:8,
...    format:'binary'
... }})
{
	"ok" : 1,
	"proofs" : [
		{
			"collection" : "files_5c6b4735769348aee6f8fd00",
            "scope" : "database",
			"version" : NumberLong(6),
			"documentId" : ObjectId("5c7f46eebe1e3eaea78b1abe"),
			"versionProofId" : "cb7a1180-3fc6-11e9-a4bd-019793331702",
			"status" : "Valid",
			"btcTransaction" : "9b890c83fcdda9d415bb9c14dfac248e541f2c3387de1c5a290c1774c96e116d",
			"btcBlockNumber" : "565864",
			"documentHash" : "1bc4d9d07a4142ee9070253a86d49fff767d95bbe5cc40efbac96e60233ff592",
			"versionHash" : "ec81ad126f5e922984e34bc3bd27d875e52a0cb4406900ae3092e8900bf81dc4",
			"proof" : BinData(0,"eJysV81uZke1vfddMozT+7d...")
		}
	]
}