Retrieve data contract history#

In this tutorial we will retrieve the history of a data contract created in the Register a Data Contract tutorial. Only contracts that have enabled the keepsHistory option during contract creation will store revision information.

Note

This retrieves revisions of the contract definition. It does not return the revision history of individual documents (see getDocumentHistory) or records of document transfers and sales (see document ownership and pricing history).

Prerequisites#

Code#

contract-retrieve-history.mjs#
import { setupDashClient } from '../setupDashClient.mjs';

const { sdk } = await setupDashClient();

// Default tutorial contract with history (testnet). Replace or override via DATA_CONTRACT_ID.
const DATA_CONTRACT_ID =
  process.env.DATA_CONTRACT_ID ||
  '5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r';

try {
  const history = await sdk.contracts.getHistory({
    dataContractId: DATA_CONTRACT_ID,
  });

  for (const [timestamp, contract] of history) {
    console.log(`Version at ${timestamp}:`, contract.toJSON());
  }
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

Example data contract history#

The following example response shows a retrieved contract history:

Version at 1772722751435: {
  '$format_version': '1',
  id: '5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r',
  config: {
    '$format_version': '1',
    canBeDeleted: false,
    readonly: false,
    keepsHistory: true,
    documentsKeepHistoryContractDefault: false,
    documentsMutableContractDefault: true,
    documentsCanBeDeletedContractDefault: true,
    requiresIdentityEncryptionBoundedKey: null,
    requiresIdentityDecryptionBoundedKey: null,
    sizedIntegerTypes: true
  },
  version: 1,
  ownerId: 'FKZZFDTfGdSWUmL2g7H9e46pMJMPQp9DHQcvjrsS6884',
  schemaDefs: null,
  documentSchemas: {
    note: {
      type: 'object',
      properties: [Object],
      additionalProperties: false
    }
  },
  createdAt: 1772722751435,
  updatedAt: null,
  createdAtBlockHeight: 273561,
  updatedAtBlockHeight: null,
  createdAtEpoch: 14269,
  updatedAtEpoch: null,
  groups: {},
  tokens: {},
  keywords: [],
  description: null
}

Note

Please refer to the data contract reference page for more comprehensive details related to contracts and documents.

What’s Happening#

After we initialize the client, we request a contract’s history. The contract ID defaults to a testnet tutorial contract but can be overridden via the DATA_CONTRACT_ID environment variable. The sdk.contracts.getHistory method takes an object with a dataContractId property. It returns a Map where each key is a timestamp (BigInt) and each value is the contract at that revision. After the contract history is retrieved, we iterate over the entries and display each revision on the console.