feat: migrate tutorials from js-dash-sdk to evo-sdk

.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.mjs

@@ -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-retrieve.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-topup.mjs

@@ -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-transfer-credits.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);
+}

1-Identities-and-Names/identity-update-add-key.mjs

@@ -0,0 +1,60 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/update-an-identity.html
+import {
+  IdentityPublicKeyInCreation,
+  KeyType,
+  Purpose,
+  SecurityLevel,
+  wallet,
+} from '@dashevo/evo-sdk';
+import {
+  setupDashClient,
+  clientConfig,
+  dip13KeyPath,
+} from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+
+// Fetch identity to determine the next available key ID
+const { identity, signer } = await keyManager.getMaster();
+const existingKeys = identity.toJSON().publicKeys;
+const newKeyId = Math.max(...existingKeys.map((k) => k.id)) + 1;
+
+console.log(`Adding key ${newKeyId} to identity ${keyManager.identityId}...`);
+
+// Derive the new key using the standard DIP-13 path
+const newKeyPath = await dip13KeyPath(
+  clientConfig.network,
+  keyManager.identityIndex,
+  newKeyId,
+);
+const newKeyInfo = await wallet.deriveKeyFromSeedWithPath({
+  mnemonic: clientConfig.mnemonic,
+  path: newKeyPath,
+  network: clientConfig.network,
+});
+const newKeyObj = newKeyInfo.toObject();
+
+// Build the new public key
+const newPublicKey = new IdentityPublicKeyInCreation({
+  keyId: newKeyId,
+  purpose: Purpose.AUTHENTICATION,
+  securityLevel: SecurityLevel.HIGH,
+  keyType: KeyType.ECDSA_SECP256K1,
+  data: Uint8Array.from(Buffer.from(newKeyObj.publicKey, 'hex')),
+});
+
+// Add the new key's WIF to the signer so it can co-sign
+signer.addKeyFromWif(newKeyObj.privateKeyWif);
+
+try {
+  await sdk.identities.update({
+    identity,
+    addPublicKeys: [newPublicKey],
+    signer,
+  });
+
+  const updatedIdentity = await sdk.identities.fetch(keyManager.identityId);
+  console.log('Identity updated:\n', updatedIdentity.toJSON());
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}

1-Identities-and-Names/identity-update-disable-key.mjs

@@ -0,0 +1,22 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/update-an-identity.html
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+const { identity, signer } = await keyManager.getMaster();
+
+const KEY_ID = 99; // Replace with one of the identity's existing public key IDs
+
+console.log(`Disabling key ${KEY_ID} on identity ${keyManager.identityId}...`);
+
+try {
+  await sdk.identities.update({
+    identity,
+    disablePublicKeys: [KEY_ID], // Disable public key id KEY_ID
+    signer,
+  });
+
+  const updatedIdentity = await sdk.identities.fetch(keyManager.identityId);
+  console.log('Identity updated:\n', updatedIdentity.toJSON());
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}

1-Identities-and-Names/identity-withdraw-credits.mjs

@@ -0,0 +1,28 @@
+// See https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/withdraw-an-identity-balance.html
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+const { identity, signer } = await keyManager.getTransfer();
+
+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';
+const amount = 190000n; // Credits to withdraw
+const amountDash = Number(amount) / (1000 * 100000000);
+
+console.log(`Withdrawing ${amount} credits (${amountDash} DASH)`);
+
+try {
+  const remainingBalance = await sdk.identities.creditWithdrawal({
+    identity,
+    amount,
+    toAddress,
+    signer,
+  });
+
+  console.log(`Identity balance after withdrawal: ${remainingBalance} credits`);
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}