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:

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

The command accepts the following fields:

FieldTypeMandatoryDescription
collectionstringyesThe collection name which the document belongs to.
filterdocumentyesThe condition to filter the documents.
versionnumberyesThe versions for the proof. The first version proof after the document will be created will be selected as the document proof.
formatstringnoEither 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:

FieldTypeDescription
oknumberThe status of the command.
proofsarrayThe 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:

FieldTypeDescription
collectionstringThe collection of the document.
scopestringThe scope of the proof.
provenDbIdanyThe provenDbId of the document. It refers to _provendb_metadata._id.
documentIdanyThe document's _id
versionnumberThe version that the document is first proved.
statusstringThe proof status.
errmsgstringThe proof error message, if any.
btcTransactionstringThe BTC transaction ID of the proof.
btcBlockNumberstringThe BTC block number the proof is anchored to.
versionProofIdstringThe proof ID of the proof returned.
documentHashstringThe hash of the document submitted in the proof's version hash.
versionHashstringThe hash of the version submitted in the proof.
proofbinary or objectThe 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:

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...")
        }
    ]
}

What’s Next