docs(tutorials): sync with tutorial repo

thephez · thephez · commit 6c6911e80186 · 2026-03-18T13:07:50.000-04:00
diff --git a/docs/tutorials/contracts-and-documents/delete-documents.md b/docs/tutorials/contracts-and-documents/delete-documents.md
@@ -27,11 +27,11 @@ 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 ??
+  process.env.DATA_CONTRACT_ID ||
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 // Replace with your existing document ID
-const DOCUMENT_ID = process.env.DOCUMENT_ID ?? 'YOUR_DOCUMENT_ID';
+const DOCUMENT_ID = process.env.DOCUMENT_ID || 'YOUR_DOCUMENT_ID';
 
 try {
   // Delete the document from the platform
diff --git a/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md b/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md
@@ -23,7 +23,7 @@ const { sdk } = await setupDashClient();
 
 // Default tutorial contract (testnet). Replace or override via DATA_CONTRACT_ID.
 const DATA_CONTRACT_ID =
-  process.env.DATA_CONTRACT_ID ??
+  process.env.DATA_CONTRACT_ID ||
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 try {
diff --git a/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md b/docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md
@@ -26,7 +26,7 @@ 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 ??
+  process.env.DATA_CONTRACT_ID ||
   '5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r';
 
 try {
diff --git a/docs/tutorials/contracts-and-documents/retrieve-documents.md b/docs/tutorials/contracts-and-documents/retrieve-documents.md
@@ -23,7 +23,7 @@ const { sdk } = await setupDashClient();
 
 // Default tutorial contract (testnet). Replace or override via DATA_CONTRACT_ID.
 const DATA_CONTRACT_ID =
-  process.env.DATA_CONTRACT_ID ??
+  process.env.DATA_CONTRACT_ID ||
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 try {
diff --git a/docs/tutorials/contracts-and-documents/submit-documents.md b/docs/tutorials/contracts-and-documents/submit-documents.md
@@ -27,7 +27,7 @@ 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 ??
+  process.env.DATA_CONTRACT_ID ||
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 try {
diff --git a/docs/tutorials/contracts-and-documents/update-a-data-contract.md b/docs/tutorials/contracts-and-documents/update-a-data-contract.md
@@ -35,7 +35,7 @@ const { identityKey, signer } = await keyManager.getAuth();
 // Edit these values for your environment
 // Your contract ID from the Register a Data Contract tutorial
 const DATA_CONTRACT_ID =
-  process.env.DATA_CONTRACT_ID ?? 'YOUR_DATA_CONTRACT_ID';
+  process.env.DATA_CONTRACT_ID || 'YOUR_DATA_CONTRACT_ID';
 const DOCUMENT_TYPE = 'note';
 
 if (!DATA_CONTRACT_ID || DATA_CONTRACT_ID === 'YOUR_DATA_CONTRACT_ID') {
@@ -87,7 +87,7 @@ const { identityKey, signer } = await keyManager.getAuth();
 // Edit these values for your environment
 // Your contract ID from the Register a Data Contract tutorial
 const DATA_CONTRACT_ID =
-  process.env.DATA_CONTRACT_ID ?? 'YOUR_DATA_CONTRACT_ID';
+  process.env.DATA_CONTRACT_ID || 'YOUR_DATA_CONTRACT_ID';
 const DOCUMENT_TYPE = 'note';
 
 if (!DATA_CONTRACT_ID || DATA_CONTRACT_ID === 'YOUR_DATA_CONTRACT_ID') {
diff --git a/docs/tutorials/contracts-and-documents/update-documents.md b/docs/tutorials/contracts-and-documents/update-documents.md
@@ -28,11 +28,11 @@ 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 ??
+  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';
+const DOCUMENT_ID = process.env.DOCUMENT_ID || 'YOUR_DOCUMENT_ID';
 
 try {
   // Fetch the existing document to get current revision
diff --git a/docs/tutorials/identities-and-names/register-a-name-for-an-identity.md b/docs/tutorials/identities-and-names/register-a-name-for-an-identity.md
@@ -33,7 +33,7 @@ const { sdk, keyManager } = await setupDashClient();
 const { identity, identityKey, signer } = await keyManager.getAuth();
 
 // ⚠️ Change this to a unique name to register
-const NAME_LABEL = process.env.NAME_LABEL ?? 'alice';
+const NAME_LABEL = process.env.NAME_LABEL || 'alice';
 
 try {
   // Register a DPNS name for the identity
diff --git a/docs/tutorials/identities-and-names/transfer-credits-to-an-identity.md b/docs/tutorials/identities-and-names/transfer-credits-to-an-identity.md
@@ -27,7 +27,7 @@ const { identity, signer } = await keyManager.getTransfer();
 
 // Default recipient (testnet). Replace or override via RECIPIENT_ID.
 const recipientId =
-  process.env.RECIPIENT_ID ?? '7XcruVSsGQVSgTcmPewaE4tXLutnW1F6PXxwMbo8GYQC';
+  process.env.RECIPIENT_ID || '7XcruVSsGQVSgTcmPewaE4tXLutnW1F6PXxwMbo8GYQC';
 const transferAmount = 100000n; // Credits to transfer
 
 try {
diff --git a/docs/tutorials/identities-and-names/update-an-identity.md b/docs/tutorials/identities-and-names/update-an-identity.md
@@ -33,7 +33,7 @@ const { sdk, keyManager } = await setupDashClient();
 const { identity, signer } = await keyManager.getMaster();
 
 // Replace with one of the identity's existing public key IDs
-const DISABLE_KEY_ID = Number(process.env.DISABLE_KEY_ID ?? 99);
+const DISABLE_KEY_ID = Number(process.env.DISABLE_KEY_ID || 99);
 
 console.log(
   `Disabling key ${DISABLE_KEY_ID} on identity ${keyManager.identityId}...`,
diff --git a/docs/tutorials/identities-and-names/withdraw-an-identity-balance.md b/docs/tutorials/identities-and-names/withdraw-an-identity-balance.md
@@ -31,7 +31,7 @@ console.log('Identity balance before withdrawal:', identity.balance);
 
 // Default: testnet faucet address. Replace or override via WITHDRAWAL_ADDRESS.
 const toAddress =
-  process.env.WITHDRAWAL_ADDRESS ?? 'yXWJGWuD4VBRMp9n2MtXQbGpgSeWyTRHme';
+  process.env.WITHDRAWAL_ADDRESS || 'yXWJGWuD4VBRMp9n2MtXQbGpgSeWyTRHme';
 const amount = 190000n; // Credits to withdraw
 const amountDash = Number(amount) / (1000 * 100000000);
 
diff --git a/docs/tutorials/setup-sdk-client.md b/docs/tutorials/setup-sdk-client.md
@@ -51,6 +51,27 @@ try {
   /* dotenv not installed */
 }
 
+/** @typedef {import('@dashevo/evo-sdk').Identity} Identity */
+/** @typedef {import('@dashevo/evo-sdk').IdentityPublicKey} IdentityPublicKey */
+/** @typedef {import('@dashevo/evo-sdk').PlatformAddress} PlatformAddress */
+/** @typedef {import('@dashevo/evo-sdk').PlatformAddressInfo} PlatformAddressInfo */
+/** @typedef {import('@dashevo/evo-sdk').NetworkLike} NetworkLike */
+
+/**
+ * @typedef {Object} DerivedKeyEntry
+ * @property {number} keyId
+ * @property {string} privateKeyWif
+ * @property {string} [publicKey] - Only present via createForNewIdentity()
+ */
+
+/**
+ * @typedef {Object} AddressEntry
+ * @property {PlatformAddress} address
+ * @property {string} bech32m
+ * @property {string} privateKeyWif
+ * @property {string} path
+ */
+
 // ⚠️ Tutorial helper — holds WIFs in memory for convenience.
 // Do not use this pattern as-is for production key management.
 
@@ -74,6 +95,10 @@ const clientConfig = {
  * Build a DIP-13 identity key derivation path.
  * Returns the full 7-level hardened path:
  *   m/9'/{coin}'/5'/0'/0'/{identityIndex}'/{keyIndex}'
+ * @param {string} network
+ * @param {number} identityIndex
+ * @param {number} keyIndex
+ * @returns {Promise<string>}
  */
 export async function dip13KeyPath(network, identityIndex, keyIndex) {
   const base =
@@ -87,12 +112,18 @@ export async function dip13KeyPath(network, identityIndex, keyIndex) {
 // SDK client helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Create and connect an EvoSDK client for the selected network.
+ *
+ * @param {string} [network='testnet']
+ * @returns {Promise<EvoSDK>}
+ */
 export async function createClient(network = 'testnet') {
-  const factories = {
+  const factories = /** @type {Record<string, () => EvoSDK>} */ ({
     testnet: () => EvoSDK.testnetTrusted(),
     mainnet: () => EvoSDK.mainnetTrusted(),
     local: () => EvoSDK.localTrusted(),
-  };
+  });
 
   const factory = factories[network];
   if (!factory) {
@@ -101,7 +132,7 @@ export async function createClient(network = 'testnet') {
     );
   }
 
-  const sdk = factory();
+  const sdk = /** @type {EvoSDK} */ (factory());
   await sdk.connect();
   return sdk;
 }
@@ -155,6 +186,12 @@ const KEY_SPECS = [
  *   Key 4 = ENCRYPTION MEDIUM (encrypted messaging/data)
  */
 class IdentityKeyManager {
+  /**
+   * @param {EvoSDK} sdk
+   * @param {string|null|undefined} identityId
+   * @param {Record<string, DerivedKeyEntry>} keys
+   * @param {number} identityIndex
+   */
   constructor(sdk, identityId, keys, identityIndex) {
     this.sdk = sdk;
     this.id = identityId;
@@ -171,12 +208,13 @@ class IdentityKeyManager {
    * Derives all standard identity keys using DIP-9 paths.
    *
    * @param {object} opts
-   * @param {object} opts.sdk - Connected EvoSDK instance
+   * @param {EvoSDK} opts.sdk - Connected EvoSDK instance
    * @param {string} [opts.identityId] - Identity ID. If omitted, auto-resolved
    *   from the mnemonic by looking up the master key's public key hash on-chain.
    * @param {string} opts.mnemonic - BIP39 mnemonic
    * @param {string} [opts.network='testnet'] - 'testnet' or 'mainnet'
    * @param {number} [opts.identityIndex=0] - Which identity derived from this mnemonic
+   * @returns {Promise<IdentityKeyManager>}
    */
   static async create({
     sdk,
@@ -185,7 +223,7 @@ class IdentityKeyManager {
     network = 'testnet',
     identityIndex = 0,
   }) {
-    const derive = async (keyIndex) =>
+    const derive = async (/** @type {number} */ keyIndex) =>
       wallet.deriveKeyFromSeedWithPath({
         mnemonic,
         path: await dip13KeyPath(network, identityIndex, keyIndex),
@@ -241,7 +279,7 @@ class IdentityKeyManager {
    * Find the first unused DIP-9 identity index for a mnemonic.
    * Scans indices starting at 0 until no on-chain identity is found.
    *
-   * @param {object} sdk - Connected EvoSDK instance
+   * @param {EvoSDK} sdk - Connected EvoSDK instance
    * @param {string} mnemonic - BIP39 mnemonic
    * @param {string} [network='testnet'] - 'testnet' or 'mainnet'
    * @returns {Promise<number>} The first unused identity index
@@ -270,7 +308,7 @@ class IdentityKeyManager {
    * If identityIndex is omitted, auto-selects the next unused index.
    *
    * @param {object} opts
-   * @param {object} opts.sdk - Connected EvoSDK instance
+   * @param {EvoSDK} opts.sdk - Connected EvoSDK instance
    * @param {string} opts.mnemonic - BIP39 mnemonic
    * @param {string} [opts.network='testnet'] - 'testnet' or 'mainnet'
    * @param {number} [opts.identityIndex] - Identity index (auto-scanned if omitted)
@@ -285,7 +323,7 @@ class IdentityKeyManager {
     const idx =
       identityIndex ??
       (await IdentityKeyManager.findNextIndex(sdk, mnemonic, network));
-    const derive = async (keyIndex) =>
+    const derive = async (/** @type {number} */ keyIndex) =>
       wallet.deriveKeyFromSeedWithPath({
         mnemonic,
         path: await dip13KeyPath(network, idx, keyIndex),
@@ -369,7 +407,7 @@ class IdentityKeyManager {
   /**
    * Fetch identity and build { identity, identityKey, signer } for a given key.
    * @param {string} keyName - One of: master, auth, authHigh, transfer, encryption
-   * @returns {{ identity, identityKey, signer }}
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
    */
   async getSigner(keyName) {
     if (!this.id) {
@@ -378,42 +416,60 @@ class IdentityKeyManager {
           'or create/register the identity first and then set the ID.',
       );
     }
-    const key = this.keys[keyName];
+    const key = /** @type {Record<string, DerivedKeyEntry>} */ (this.keys)[
+      keyName
+    ];
     if (!key) {
       throw new Error(
         `Unknown key "${keyName}". Use: ${Object.keys(this.keys).join(', ')}`,
       );
     }
     const identity = await this.sdk.identities.fetch(this.id);
+    if (!identity) {
+      throw new Error(`Identity "${this.id}" not found on-chain.`);
+    }
     const identityKey = identity.getPublicKeyById(key.keyId);
     const signer = new IdentitySigner();
     signer.addKeyFromWif(key.privateKeyWif);
     return { identity, identityKey, signer };
   }
 
-  /** CRITICAL auth (key 2) — contracts, documents, names. */
+  /**
+   * CRITICAL auth (key 2) — contracts, documents, names.
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
+   */
   async getAuth() {
     return this.getSigner('auth');
   }
 
-  /** HIGH auth (key 1) — documents, names. */
+  /**
+   * HIGH auth (key 1) — documents, names.
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
+   */
   async getAuthHigh() {
     return this.getSigner('authHigh');
   }
 
-  /** TRANSFER — credit transfers, withdrawals. */
+  /**
+   * TRANSFER — credit transfers, withdrawals.
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
+   */
   async getTransfer() {
     return this.getSigner('transfer');
   }
 
-  /** ENCRYPTION MEDIUM — encrypted messaging/data. */
+  /**
+   * ENCRYPTION MEDIUM — encrypted messaging/data.
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
+   */
   async getEncryption() {
     return this.getSigner('encryption');
   }
 
   /**
    * MASTER — identity updates (add/disable keys).
    * @param {string[]} [additionalKeyWifs] - WIFs for new keys being added
+   * @returns {Promise<{ identity: Identity, identityKey: IdentityPublicKey | undefined, signer: IdentitySigner }>}
    */
   async getMaster(additionalKeyWifs) {
     const result = await this.getSigner('master');
@@ -439,6 +495,11 @@ class IdentityKeyManager {
  * that hold credits directly, independent of identities.
  */
 class AddressKeyManager {
+  /**
+   * @param {EvoSDK} sdk
+   * @param {AddressEntry[]} addresses
+   * @param {string} network
+   */
   constructor(sdk, addresses, network) {
     this.sdk = sdk;
     this.addresses = addresses; // [{ address, bech32m, privateKeyWif, path }]
@@ -455,10 +516,11 @@ class AddressKeyManager {
    * Derives platform address keys using BIP44 paths.
    *
    * @param {object} opts
-   * @param {object} opts.sdk - Connected EvoSDK instance
+   * @param {EvoSDK} opts.sdk - Connected EvoSDK instance
    * @param {string} opts.mnemonic - BIP39 mnemonic
    * @param {string} [opts.network='testnet'] - 'testnet' or 'mainnet'
    * @param {number} [opts.count=1] - Number of addresses to derive
+   * @returns {Promise<AddressKeyManager>}
    */
   static async create({ sdk, mnemonic, network = 'testnet', count = 1 }) {
     const addresses = [];
@@ -482,7 +544,9 @@ class AddressKeyManager {
 
       addresses.push({
         address: platformAddress,
-        bech32m: platformAddress.toBech32m(network),
+        bech32m: platformAddress.toBech32m(
+          /** @type {NetworkLike} */ (network),
+        ),
         privateKeyWif: obj.privateKeyWif,
         path,
       });
@@ -518,7 +582,7 @@ class AddressKeyManager {
 
   /**
    * Fetch current balance and nonce for the primary address.
-   * @returns {Promise<PlatformAddressInfo|undefined>}
+   * @returns {Promise<PlatformAddressInfo | undefined>}
    */
   async getInfo() {
     return this.sdk.addresses.get(this.primaryAddress.bech32m);
@@ -527,7 +591,7 @@ class AddressKeyManager {
   /**
    * Fetch current balance and nonce for an address by index.
    * @param {number} index - Address index
-   * @returns {Promise<PlatformAddressInfo|undefined>}
+   * @returns {Promise<PlatformAddressInfo | undefined>}
    */
   async getInfoAt(index) {
     const entry = this.addresses[index];
@@ -544,9 +608,13 @@ class AddressKeyManager {
 // setupDashClient — convenience wrapper
 // ---------------------------------------------------------------------------
 
+/**
+ * @param {{requireIdentity?: boolean, identityIndex?: number}} opts
+ * @returns {Promise<{ sdk: EvoSDK, keyManager: IdentityKeyManager | undefined, addressKeyManager: AddressKeyManager | undefined }>}
+ */
 export async function setupDashClient({
   requireIdentity = true,
-  identityIndex,
+  identityIndex = undefined,
 } = {}) {
   const { network, mnemonic } = clientConfig;
 
