Since Hellar Platform v.0.1.0, 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 / Hellar SDK installed)
• A wallet mnemonic with some funds in it: Tutorial: Create and Fund a Wallet
• A Hellar Platform Identity: Tutorial: Register an Identity
• A Hellar Platform Contract ID: Tutorial: Register a Data Contract

Code

The following examples demonstrate updating an existing contract to add a new property to an existing document. The second example shows how to update a contract that has contract history enabled:

JAVASCRIPT

`// Minimal contract const Hellar = require('hellar');

const clientOpts = { network: 'mainnet', wallet: { mnemonic: 'a Hellar wallet mnemonic with funds goes here', unsafeOptions: { skipSynchronizationBeforeHeight: 175000, // only sync from mid-2024 },
}, }; const client = new Hellar.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 documentSchema = existingDataContract.getDocumentSchema('note');

documentSchema.properties.author = { type: 'string', position: 1, };

existingDataContract.setDocumentSchema('note', documentSchema);

// Sign and submit the data contract await platform.contracts.update(existingDataContract, identity); return existingDataContract; };

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

JAVASCRIPT

`// Contract with history const Hellar = require('hellar');

const clientOpts = { network: 'mainnet', wallet: { mnemonic: 'a Hellar wallet mnemonic with funds goes here', unsafeOptions: { skipSynchronizationBeforeHeight: 175000, // only sync from mid-2024 },
}, }; const client = new hellar.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 documentSchema = existingDataContract.getDocumentSchema('note');

documentSchema.properties.author = { type: 'string', position: 1, };

existingDataContract.setDocumentSchema('note', documentSchema); existingDataContract.setConfig({ keepsHistory: true, // Enable storing of contract history });

// Sign and submit the data contract await platform.contracts.update(existingDataContract, identity); return existingDataContract; };

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 document schema and modify a document (adding an author property to the note document in the example). The setDocumentSchema method takes two arguments: the name of the document schema to be updated and the object containing the updated document types.