Overview

Since Dash Platform v0.22, it is possible to update existing data contracts in certain backwards-compatible ways. This includes:

Adding new documents
Adding new optional properties to existing documents
Adding non-unique indices for properties added in the update.

In this tutorial we will update an existing data contract.

Prerequisites

General prerequisites (Node.js / Dash SDK installed)
A wallet mnemonic with some funds in it: Tutorial: Create and Fund a Wallet
A Dash Platform Identity: Tutorial: Register an Identity
A Dash Platform Contract ID: Tutorial: Register a Data Contract

Code

The following example demonstrates updating an existing contract to add a new property to an existing document:

const Dash = require('dash');

const clientOpts = {
  wallet: {
    mnemonic: 'a Dash wallet mnemonic with funds goes here',
    unsafeOptions: {
      skipSynchronizationBeforeHeight: 650000, // only sync from early-2022
    },    
  },
};
const client = new Dash.Client(clientOpts);

const updateContract = async () => {
  const { platform } = client;
  const identity = await platform.identities.get('an identity ID goes here');

  const existingDataContract = await platform.contracts.get('a contract ID goes here');
  const documents = existingDataContract.getDocuments();

  documents.note.properties.author = {
    type: 'string',
  };

  existingDataContract.setDocuments(documents);

  // Make sure contract passes validation checks
  await platform.dpp.initialize();
  const validationResult = await platform.dpp.dataContract.validate(
    existingDataContract,
  );

  if (validationResult.isValid()) {
    console.log('Validation passed, broadcasting contract..');
    // Sign and submit the data contract
    return platform.contracts.update(existingDataContract, identity);
  }
  console.error(validationResult); // An array of detailed validation errors
  throw validationResult.errors[0];
};

updateContract()
  .then((d) => console.log('Contract updated:\n', d.toJSON()))
  .catch((e) => console.error('Something went wrong:\n', e))
  .finally(() => client.disconnect());

📘
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 retrieve an existing contract owned by our identity. We then get the contract's documents and modify a document (adding an author property to the note document in the example).The setDocuments method takes one argument: the object containing the updated document types.

Once the data contract has been updated, we still need to submit it to DAPI. The platform.contracts.update method takes a data contract and an identity parameter. Internally, it creates a State Transition containing the updated contract, signs the state transition, and submits the signed state transition to DAPI. A response will only be returned if an error is encountered.

📘Wallet Operations

The JavaScript SDK does not cache wallet information. It re-syncs the entire Core chain for some wallet operations (e.g. client.getWalletAccount()) which can result in wait times of 5+ minutes.

A future release will add caching so that access is much faster after the initial sync. For now, the skipSynchronizationBeforeHeight option can be used to sync the wallet starting at a certain block height.