feat: migrate tutorials from js-dash-sdk to evo-sdk (#53)

* feat: add evo-sdk tutorials for read-only operations

Add evo-sdk tutorial examples for identities, names, contracts, and documents. Includes setupEvoClient helper for configuration and 5 working examples.

* refactor: make output consistent and init client right away

* style: npm fmt

* feat: add more tutorials

* feat: add working credit transfer tutorial

Also updates .env.example to include TRANSFER_KEY_WIF

* feat: add working identity credit withdrawal

* chore: update evo sdk to latest release

* feat: add name registration and document tutorials

* docs: update .env.example with recently added vars

* feat: add minimal contract registration tutorial

* feat: add contract update tutorial

* feat: create nft contract tutorial

* feat: add some nft-related tutorials

* feat: remaining nft tutorials and env.example updates

* chore: update evo-sdk dependency

* chore: update to evo sdk 3.1-dev.1

* feat: add evo sdk client setup and identity register tutorial

* feat: migrate identity-retrieve and document-submit to evo-sdk ESM

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add links to tutorial docs pages

* feat: migrate document-retrieve and document-delete to evo-sdk ESM

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: migrate document update to evo sdk

* fix: add bug workaround to identity create

* feat: migrate contracts tutorials to evo-sdk ESM

Migrate all contract register/retrieve/update tutorials from legacy
js-dash-sdk (CJS) to evo-sdk (ESM). Adds new variants (binary,
indexed, timestamps, history-retrieve) and works around
sdk.contracts.fetch() returning undefined for keepsHistory contracts
(dashpay/platform#3165).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: delete old sdk tutorials

* feat: migrate connect and create-wallet to evo-sdk ESM

Replace legacy js-dash-sdk CJS scripts (connect.js, create-wallet.js,
setupDashClient.js) with evo-sdk ESM equivalents. Add .local/ to
.gitignore.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: migrate DPNS name tutorials to evo-sdk

Migrate name-register, name-resolve, name-search, and name-get-identity-names from legacy js-dash-sdk (CJS) to evo-sdk (ESM).
Add friendly error for duplicate name registration attempts.

* chore: trivial updates

* chore: remove outdated files

* chore: whitespace cleanup

* feat: migrate identity topup, transfer, and withdrawal to evo-sdk

Replace legacy js-dash-sdk CJS scripts with evo-sdk ESM equivalents.
Add env var overrides for recipient ID and withdrawal address with
sensible testnet defaults.

* feat: add identity update tutorials (add-key, disable-key) for evo-sdk

Add evo-sdk ESM tutorials for adding and disabling identity keys.
Add-key auto-detects next available key ID and uses exported
dip13KeyPath helper instead of manual path construction.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: remove unneeded files

* chore: remove outdated files

* style: npm fmt updates

* docs: update README

* chore: typo fix

* docs: update readme

* docs: readme update

* chore: remove old dash sdk from package.json

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: thephez

.env.example

@@ -17,3 +17,41 @@ CONTRACT_ID='4BRJbxsDTFY4GJGrCqM6KUjv1wSQDBuUYiGkuzgcrD5d'
 NETWORK='testnet'
 # RECIPIENT_ID sets an identity ID to receive a credit transfer
 RECIPIENT_ID='6cSbshXPYDA2CmBtD31X4uo7YLwtef4mVDt15zRok8Xg'
+
+# Private keys for IDENTITY_ID in WIF format
+# You can create an identity using the Dash Evo Tool and copy these keys from there
+# https://github.com/dashpay/dash-evo-tool
+MASTER_KEY_WIF=''
+CRITICAL_KEY_WIF=''
+TRANSFER_KEY_WIF=''
+
+# DOCUMENT_ID is the ID of a document (obtained from document-submit output)
+# Used for document-update and document-delete tutorials
+DOCUMENT_ID=''
+
+# NAME_LABEL is an optional username label for name registration (without .dash)
+# If not provided, tutorials will generate a unique 20+ character label automatically
+NAME_LABEL=''
+
+# NFT Variables
+# NFT_CONTRACT_ID comes from contract-register-nft output
+NFT_CONTRACT_ID=''
+# NFT_OWNER_ID is the identity ID that owns the NFT documents
+# This should typically be the same as IDENTITY_ID above
+NFT_OWNER_ID=''
+# NFT_DOCUMENT_ID comes from nft-create output
+# Used for nft-set-price, nft-transfer, etc.
+NFT_DOCUMENT_ID=''
+
+# NFT Marketplace Variables
+# NFT_PRICE is the listing price in credits for marketplace operations
+# Note: 1000 credits = 1 satoshi equivalent
+NFT_PRICE=1000
+# NFT_DOCUMENT_ID is the document ID to purchase from the marketplace
+# This should be a different document than NFT_DOCUMENT_ID (you can't buy your own NFT)
+NFT_DOCUMENT_ID=''
+# NFT_BUYER_ID is the identity ID of the buyer (different from NFT_OWNER_ID)
+NFT_BUYER_ID=''
+# NFT_BUYER_KEY_WIF is the CRITICAL_KEY_WIF for the buyer's identity
+# Required for purchase operations (AUTHENTICATION purpose key, not TRANSFER key)
+NFT_BUYER_KEY_WIF=''

.gitignore

@@ -1,3 +1,4 @@
+.local/
 node_modules/
 .env
 .DS_Store

1-Identities-and-Names/identity-register.js

@@ -0,0 +1,44 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/register-an-identity.html
+import { randomBytes } from 'node:crypto';
+import { Identity, Identifier } from '@dashevo/evo-sdk';
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager, addressKeyManager } = await setupDashClient({
+  requireIdentity: false,
+});
+
+try {
+  // Build the identity shell with 5 standard public keys
+  const identity = new Identity(new Identifier(randomBytes(32)));
+  keyManager.getKeysInCreation().forEach((key) => {
+    identity.addPublicKey(key.toIdentityPublicKey());
+  });
+
+  // Create the identity on-chain, funded from the platform address
+  const result = await sdk.addresses.createIdentity({
+    identity,
+    inputs: [
+      {
+        address: addressKeyManager.primaryAddress.bech32m,
+        amount: 5000000n, // Credits to fund the new identity
+      },
+    ],
+    identitySigner: keyManager.getFullSigner(),
+    addressSigner: addressKeyManager.getSigner(),
+  });
+
+  console.log(
+    'Identity registered!\nIdentity ID:',
+    result.identity.id.toString(),
+  );
+} catch (e) {
+  // Known SDK bug: proof verification fails but the identity was created
+  // Issue: https://github.com/dashpay/platform/issues/3095
+  // Extract the real identity ID from the error message
+  const match = e.message?.match(/proof returned identity (\w+) but/);
+  if (match) {
+    console.log('Identity registered!\nIdentity ID:', match[1]);
+  } else {
+    console.error('Something went wrong:\n', e.message);
+  }
+}

1-Identities-and-Names/identity-register.mjs

@@ -0,0 +1,20 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/retrieve-an-identity.html
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+
+// Identity ID from the identity create tutorial
+const IDENTITY_ID = keyManager.identityId;
+
+if (!IDENTITY_ID) {
+  throw new Error(
+    'No identity found. Run the "Register an Identity" tutorial first or provide an identity ID.',
+  );
+}
+
+try {
+  const identity = await sdk.identities.fetch(IDENTITY_ID);
+  console.log('Identity retrieved:\n', identity.toJSON());
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}

1-Identities-and-Names/identity-retrieve.js

@@ -0,0 +1,28 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/topup-an-identity-balance.html
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, addressKeyManager, keyManager } = await setupDashClient();
+const signer = addressKeyManager.getSigner();
+
+try {
+  // Identity ID from the identity create tutorial
+  const IDENTITY_ID = keyManager.identityId;
+  const identity = await sdk.identities.fetch(IDENTITY_ID);
+
+  const result = await sdk.addresses.topUpIdentity({
+    identity,
+    inputs: [
+      {
+        address: addressKeyManager.primaryAddress.bech32m,
+        amount: 200000n, // Credits to transfer
+      },
+    ],
+    signer,
+  });
+
+  console.log(`Top-up result:
+  Start balance: ${identity.toJSON().balance}
+  Final balance: ${result.newBalance}`);
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}

1-Identities-and-Names/identity-retrieve.mjs

@@ -0,0 +1,24 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/transfer-credits-to-an-identity.html
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+const { identity, signer } = await keyManager.getTransfer();
+
+// Default recipient (testnet). Replace or override via RECIPIENT_ID.
+const recipientId =
+  process.env.RECIPIENT_ID ?? '7XcruVSsGQVSgTcmPewaE4tXLutnW1F6PXxwMbo8GYQC';
+const transferAmount = 100000n; // Credits to transfer
+
+try {
+  await sdk.identities.creditTransfer({
+    identity,
+    recipientId,
+    amount: transferAmount,
+    signer,
+  });
+
+  const recipient = await sdk.identities.fetch(recipientId);
+  console.log('Recipient identity balance after transfer:', recipient.balance);
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}