DID SDK v1 to v2 Migration

This guide summarizes key migration points from the legacy SDK model to DID SDK 2.0.

Package Scope Changes

Previous Current

@hashgraph-did-sdk/ or @hashgraph-did-js-sdk/

@swiss-digital-assets-institute/*

Message Model Changes

DID SDK 2.0 replaces the previous event-style message set with a versioned envelope model:

Legacy model DID SDK 2.0

DIDOwnerMessage

CreateDidMessage

DIDAddVerificationMethodMessage, DIDRemoveVerificationMethodMessage

Represented as full-document updates through UpdateDidMessage

DIDAddServiceMessage, DIDRemoveServiceMessage

Represented as full-document updates through UpdateDidMessage

DIDDeactivateMessage

DeactivateDidMessage

Registrar API Changes

updateDID input shape

In DID SDK 2.0, updateDID takes updatedDidDocument (full document), not an updates operation array.

await updateDID(
  {
    did,
    updatedDidDocument,
  },
  providers,
);

DIDUpdateBuilder remains available as a helper for building operation sets while preparing the next document state.

CSM flow payloads

Client-managed-secret flows now use proof primitives:

  • generate*DIDRequest returns { state, signingRequest }

  • submit*DIDRequest requires { state, proof, verifierOptions }

Resolver Enhancements

resolveDID and dereferenceDID now support historical state resolution:

  • versionId (topic sequence number)

  • versionTime (ISO 8601 timestamp)

If both are provided, versionId takes precedence.

Core Model Updates

Core message handling is proof-based in DID SDK 2.0:

  • DIDMessage.proof replaces signature-centric wording

  • setProof(…​) replaces setSignature(…​) behavior

  • Error code uses invalidProof

Core also exports validateDidDocument(…​) for document-structure validation.

  1. Migrate package imports to @swiss-digital-assets-institute/*.

  2. Replace legacy messages with CreateDidMessage / UpdateDidMessage / DeactivateDidMessage.

  3. Update registrar integrations to updatedDidDocument and proof-based CSM submit APIs.

  4. Add resolver versioning support where historical reads are needed.

  5. Validate updated DID documents with validateDidDocument(…​) in integration boundaries.

References