Update documents#

In this tutorial we will update existing data on Dash Platform. Data is stored in the form of documents which are encapsulated in a state transition before being submitted to DAPI.

Prerequisites#

Code#

document-update.mjs#
import { Document } from '@dashevo/evo-sdk';
import { setupDashClient } from '../setupDashClient.mjs';

const { sdk, keyManager } = await setupDashClient();
const { identity, identityKey, signer } = await keyManager.getAuth();

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

// Replace with your existing document ID from the Submit Documents tutorial
const DOCUMENT_ID = process.env.DOCUMENT_ID || 'YOUR_DOCUMENT_ID';

try {
  // Fetch the existing document to get current revision
  const docs = await sdk.documents.query({
    dataContractId: DATA_CONTRACT_ID,
    documentTypeName: 'note',
    where: [['$id', '==', DOCUMENT_ID]],
  });
  const existingDoc = [...docs.values()][0];
  if (!existingDoc) {
    throw new Error(`Document ${DOCUMENT_ID} not found`);
  }

  // Create the replacement document with incremented revision
  const document = new Document({
    properties: {
      message: `Updated Tutorial Test @ ${new Date().toUTCString()}`,
    },
    documentTypeName: 'note',
    dataContractId: DATA_CONTRACT_ID,
    ownerId: identity.id,
    revision: existingDoc.revision + 1n,
    id: DOCUMENT_ID,
  });

  // Submit the replacement to the platform
  await sdk.documents.replace({
    document,
    identityKey,
    signer,
  });

  console.log('Document updated:\n', document.toJSON());
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

What’s happening#

After we initialize the client, we get the auth key signer from the key manager. We first query for the existing document by its $id to retrieve the current revision number. We then create a new Document object with the updated properties, the same id, and the revision incremented by one (as a BigInt).

The sdk.documents.replace() method takes the document and signing credentials. Internally, it creates a State Transition containing the replacement document, signs the state transition, and submits it to DAPI.

Note

The SDK requires constructing a complete replacement Document with all fields — including the document id and incremented revision. The example above queries the existing document first to determine the current revision.

Tip

See this in an example app: Dashnote — Update a note is the canonical fetch → bump revision → replace example.