fix: update transition examples for evo-sdk v4

public/AI_REFERENCE.md

@@ -2248,7 +2248,34 @@ Returns:
 
 Example:
 ```javascript
-const result = await sdk.dpns.registerName({ label, identity, identityKey, signer, preorderCallback });
+import { IdentitySigner } from '@dashevo/evo-sdk';
+
+const identityId = '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk';
+const identity = await sdk.identities.fetch(identityId);
+
+const signer = new IdentitySigner();
+signer.addKeyFromWif('L1ExamplePrivateKeyWifGoesHere');
+
+// DPNS registration requires a strong authentication key.
+const identityKey = identity.publicKeys.find(
+  k => k.purpose === 'AUTHENTICATION'
+    && ['CRITICAL', 'HIGH'].includes(k.securityLevel),
+);
+if (!identityKey) {
+  throw new Error(
+    'DPNS registration requires an AUTHENTICATION key with CRITICAL or HIGH security level',
+  );
+}
+
+const result = await sdk.dpns.registerName({
+  label: 'alice',
+  identity,
+  identityKey,
+  signer,
+  preorderCallback: (preorderDocument) => {
+    console.log('preorder submitted', preorderDocument.id?.toString?.());
+  },
+});
 ```
 
 #### Token Transitions
@@ -2926,7 +2953,34 @@ Returns:
 
 Example:
 ```javascript
-const result = await sdk.voting.masternodeVote({ masternodeProTxHash, votePoll, voteChoice, votingKey, signer });
+import { IdentitySigner, ResourceVoteChoice, VotePoll } from '@dashevo/evo-sdk';
+
+const masternodeProTxHash = '143dcd6a6b7684fde01e88a10e5d65de9a29244c5ecd586d14a342657025f113';
+
+const signer = new IdentitySigner();
+signer.addKeyFromWif('L1ExampleVotingKeyWifGoesHere');
+
+// Voting key must match the masternode voting public key on the identity.
+const votingIdentity = await sdk.identities.fetch(masternodeProTxHash);
+const votingKey = votingIdentity.publicKeys.find(k => k.purpose === 'VOTING');
+if (!votingKey) {
+  throw new Error('Masternode voting requires a VOTING-purpose identity key');
+}
+
+const votePoll = new VotePoll({
+  contractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+  documentTypeName: 'domain',
+  indexName: 'parentNameAndLabel',
+  indexValues: ['dash', 'alice'],
+});
+
+await sdk.voting.masternodeVote({
+  masternodeProTxHash,
+  votePoll,
+  voteChoice: ResourceVoteChoice.TowardsIdentity('5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk'),
+  votingKey,
+  signer,
+});
 ```
 
 **Contested Resource** - `voting.masternodeVote`
@@ -2969,7 +3023,33 @@ Returns:
 
 Example:
 ```javascript
-const result = await sdk.voting.masternodeVote({ masternodeProTxHash, votePoll, voteChoice, votingKey, signer });
+import { IdentitySigner, ResourceVoteChoice, VotePoll } from '@dashevo/evo-sdk';
+
+const masternodeProTxHash = '143dcd6a6b7684fde01e88a10e5d65de9a29244c5ecd586d14a342657025f113';
+
+const signer = new IdentitySigner();
+signer.addKeyFromWif('L1ExampleVotingKeyWifGoesHere');
+
+const votingIdentity = await sdk.identities.fetch(masternodeProTxHash);
+const votingKey = votingIdentity.publicKeys.find(k => k.purpose === 'VOTING');
+if (!votingKey) {
+  throw new Error('Masternode voting requires a VOTING-purpose identity key');
+}
+
+const votePoll = new VotePoll({
+  contractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
+  documentTypeName: 'domain',
+  indexName: 'parentNameAndLabel',
+  indexValues: ['dash', 'alice'],
+});
+
+await sdk.voting.masternodeVote({
+  masternodeProTxHash,
+  votePoll,
+  voteChoice: ResourceVoteChoice.TowardsIdentity('5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk'),
+  votingKey,
+  signer,
+});
 ```
 
 #### Platform Address Transitions

public/api-definitions.json

@@ -575,7 +575,7 @@
               "type": "text",
               "label": "Label",
               "required": true,
-              "placeholder": "ąlice"
+              "placeholder": "\u0105lice"
             }
           ],
           "sdk_method": "dpns.convertToHomographSafe"

scripts/check_documentation.py

@@ -120,7 +120,42 @@ def main():
                 if missing_anchors:
                     errors.append(f"ERROR: Missing HTML return type anchors: {', '.join(missing_anchors)}")
 
+    # Guard against pre-v4 privateKeyWif-in-call examples (issue #63).
+    if not errors:
+        classic_patterns = [
+            (
+                r'documents\.create\(\{\s*contractId,\s*type:\s*documentType,\s*ownerId,\s*data,\s*entropyHex,\s*privateKeyWif\s*\}',
+                'pre-v4 documents.create(... privateKeyWif) example',
+            ),
+            (
+                r'identities\.topUp\(\{\s*identityId,\s*assetLockProof,\s*assetLockPrivateKeyWif\s*\}',
+                'pre-v4 identities.topUp(... assetLockPrivateKeyWif) example',
+            ),
+            (
+                r'identities\.create\(\{\s*assetLockProof,\s*assetLockPrivateKeyWif,\s*publicKeys\s*\}',
+                'pre-v4 identities.create(... assetLockPrivateKeyWif, publicKeys) example',
+            ),
+            (
+                r'sdk\.<namespace>\.<transition>\(\{\s*\.\.\.params,\s*privateKeyWif\s*\}',
+                'pre-v4 state-transition pattern with privateKeyWif in call',
+            ),
+            (
+                r'\bprivateKeyWif\s*:',
+                'privateKeyWif object property; use IdentitySigner.addKeyFromWif / PrivateKey.fromWIF',
+            ),
+        ]
+        for label, file_path in (('docs.html', docs_file), ('AI_REFERENCE.md', ai_file)):
+            if not file_path.exists():
+                continue
+            content = file_path.read_text(encoding='utf-8')
+            for pattern, description in classic_patterns:
+                if re.search(pattern, content):
+                    errors.append(f'ERROR: {label} still contains {description}')
+            if 'IdentitySigner' not in content:
+                errors.append(f'ERROR: {label} is missing IdentitySigner usage expected for v4 write examples')
+
     # Compose report
+
     lines = [
         '=' * 80,
         'Evo SDK Documentation Check',
@@ -145,7 +180,17 @@ def main():
 
     report = '\n'.join(lines)
     print(report)
-    (PUBLIC_DIR / 'documentation-check-report.txt').write_text(report, encoding='utf-8')
+
+    # Avoid timestamp-only churn in git: keep the previous report when the
+    # status body is unchanged, rewriting only when warnings/errors change.
+    report_path = PUBLIC_DIR / 'documentation-check-report.txt'
+    previous = report_path.read_text(encoding='utf-8') if report_path.exists() else ''
+
+    def body_without_timestamp(text: str) -> str:
+        return re.sub(r'^Timestamp:.*$', 'Timestamp:', text, count=1, flags=re.M)
+
+    if body_without_timestamp(previous) != body_without_timestamp(report):
+        report_path.write_text(report, encoding='utf-8')
 
     sys.exit(1 if errors else 0)