fix: update transition examples for evo-sdk v4

[thepastaclaw]

Summary

• replace pre-v4 write examples with the shipped v4 typed payload, identity key, and signer flows
• align identity, contract, document, token, DPNS/voting, and Platform Address metadata with @dashevo/evo-sdk@4.0.0
• add declaration-backed regression checks for transition option names, required members, wrapper types, and generated query formatting
• keep generated documentation checks stable when only the report timestamp changes

Closes #63.

Validation

• python3 scripts/generate_docs.py
• python3 scripts/check_documentation.py
• npx vitest run — 151 tests passed
• node --test tests/type-extraction.test.mjs — 6 tests passed
• focused testnet transition E2E — 7/7 contract, document, and token workflows passed
• full testnet transition E2E — 21 passed, 11 repository-defined skips, 3 fixture-only failures
• git diff --check upstream/master..HEAD
• mandatory exact-head pre-PR review — ship

Notes

public/docs.html is generated and gitignored; it was regenerated locally and covered by the documentation checker and transition-example tests. public/AI_REFERENCE.md is tracked and regenerated in this branch.

Network-writing tests used fresh standard-key identities and an identity-owned disposable token contract. Credit transfer/withdrawal, contract create/update, document CRUD, token mint/burn/transfer/freeze/unfreeze/destroy, and emergency actions passed. The three full-suite failures were fixture prerequisites: two later contract creates ran below the approximately 12 billion-credit testnet creation cost, and token claim used a fixture without perpetual distribution. Focused runs passed the affected contract/document paths when funded; no product defect was found.

The examples and regression tests were also validated against the exact installed @dashevo/evo-sdk@4.0.0 and @dashevo/wasm-sdk@4.0.0 declarations and runtime behavior.

Related: #64 contains the initial API-shape migration. This draft also resolves the remaining declaration and generated-example mismatches found during exact-version review, including address metadata, signer key purposes, identity-create key relationships, token fixtures, withdrawal destinations, and multiline query rendering.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6ad8c7b9-ee08-4024-a885-e4064ef85d0d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

⛔ Blockers found — Sonnet deferred (commit baf93a6)
Canonical validated blockers: 1

[thepastaclaw]

Preliminary review — Codex only

The current head still generates invalid signing-key selection logic for the DPNS and masternode voting examples. Both issues were introduced by this PR's v4 transition documentation work and can cause users following the generated examples to submit transitions with keys that fail Platform authorization.

Validated blockers were found in the Codex precheck. Sonnet is deferred until a fresh Codex revalidation clears the blocker gate.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 2 blocking

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `scripts/generate_docs.py`:
- [BLOCKING] scripts/generate_docs.py:1151-1154: Validate the DPNS signing key before accepting key ID 1
  The fixed-ID lookup bypasses the semantic checks in the fallback: if key ID 1 exists but has another purpose or security level, it is passed directly to `registerName`. DPNS registration creates document transitions whose default HIGH requirement permits CRITICAL or HIGH AUTHENTICATION keys; an arbitrary key ID is not guaranteed to satisfy those rules and will fail authorization. Select exclusively by purpose and an accepted security level, and report a clear error when no suitable key exists.
- [BLOCKING] scripts/generate_docs.py:1176-1178: Do not fall back to an arbitrary key for masternode voting
  When no VOTING-purpose key is found, the generated example falls back to key ID 0 without verifying its purpose. Masternode vote transitions explicitly require a VOTING key, so a typical key ID 0 with another purpose will fail authorization instead of producing a useful local error. The same fallback is duplicated in the `masternodeVote` example at lines 1204-1206; both examples must require a VOTING-purpose key and throw clearly if none is available.

Note: GitHub does not allow PastaClaw to submit an approval or request changes on their own PR, so the canonical verifier result is transported as a COMMENT review.

[thepastaclaw]

🔴 Blocking: Validate the DPNS signing key before accepting key ID 1

The fixed-ID lookup bypasses the semantic checks in the fallback: if key ID 1 exists but has another purpose or security level, it is passed directly to registerName. DPNS registration creates document transitions whose default HIGH requirement permits CRITICAL or HIGH AUTHENTICATION keys; an arbitrary key ID is not guaranteed to satisfy those rules and will fail authorization. Select exclusively by purpose and an accepted security level, and report a clear error when no suitable key exists.

Suggested change

	const identityKey = identity.getPublicKeyById(1)
	|| identity.publicKeys.find(
	k => k.purpose === 'AUTHENTICATION' && k.securityLevel === 'HIGH',
	);
	const identityKey = identity.publicKeys.find(
	k => k.purpose === 'AUTHENTICATION'
	&& ['CRITICAL', 'HIGH'].includes(k.securityLevel),
	);
	if (!identityKey) {
	throw new Error('No CRITICAL/HIGH authentication key available for DPNS registration');
	}

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: Do not fall back to an arbitrary key for masternode voting

When no VOTING-purpose key is found, the generated example falls back to key ID 0 without verifying its purpose. Masternode vote transitions explicitly require a VOTING key, so a typical key ID 0 with another purpose will fail authorization instead of producing a useful local error. The same fallback is duplicated in the masternodeVote example at lines 1204-1206; both examples must require a VOTING-purpose key and throw clearly if none is available.

_{source: ['codex']}