docs(sdk): fix platform book evo-sdk tutorial code to match 3.1.0-dev API

[thepastaclaw]

Fixes #3424

Summary

Fixes all 4 Evo SDK tutorial code blocks to compile and run against @dashevo/evo-sdk@3.1.0-dev.1. Every code change has been verified on live testnet.

What changed

The tutorials (merged in #3422) were written against a planned convenience API that does not exist in the current SDK. This PR updates all code blocks to use the actual API while preserving the tutorial structure and prose.

Files changed

• book/src/evo-sdk/tutorials/car-sales.md
• book/src/evo-sdk/tutorials/basic-token.md
• book/src/evo-sdk/tutorials/card-game.md
• book/src/evo-sdk/tutorials/react-integration.md

Categories of fixes

API signature corrections:

• contracts.publish() — construct DataContract + IdentitySigner, not simplified fields
• documents.create/replace/transfer() — construct Document objects with identityKey + signer
• documents.query() — dataContractId/documentTypeName instead of contractId/documentType
• tokens.mint/transfer/burn() — dataContractId + tokenPosition instead of tokenId; identityKey + signer instead of privateKeyWif
• Token config — full TokenConfiguration class hierarchy instead of plain objects

Property accessor corrections:

• contract.getId() → contract.id
• identity.getBalance() → identity.balance
• identity.getPublicKeys() → identity.publicKeys
• doc.getData() → doc.properties

Schema/runtime corrections (discovered during live testing):

• Added position fields to all schema properties (required by DPP)
• Fixed maxLength: 64 → 63 for indexed string properties
• Token amounts as bigint (e.g., 10_000_00n)
• Added notes about CRITICAL security level requirement for token ops

Testing

All tutorials verified on testnet with identity HHjmkbcwqFzToaoyvQcP45JZro7PoczAv7Nii57uYPX1:

• ✅ Car Sales: contract publish → create listing → query → update → review
• ✅ Basic Token: contract+token publish → mint → check balance → burn
• ✅ Card Game: contract+token publish → mint gems → create cards → query → record match → reward

Test scripts: https://github.com/thepastaclaw/dash-react-tutorial/tree/develop/test-runner

[coderabbitai]

📝 Walkthrough

Walkthrough

Tutorials updated to use SDK class-based Token/Contract/Document/Signer primitives: DataContract, TokenConfiguration, Document, Identifier, and IdentitySigner are used for publishing, token ops, and document CRUD; IDs and data access moved to property-based patterns (e.g., contract.id, doc.properties); balances and token references use dataContractId/tokenPosition.

Changes

Cohort / File(s)	Summary
Schema Definitions book/src/evo-sdk/tutorials/car-sales.md, book/src/evo-sdk/tutorials/card-game.md	Added position metadata to schema properties; adjusted string maxLength values (e.g., 64→63).
Contract Publishing Flow book/src/evo-sdk/tutorials/basic-token.md, book/src/evo-sdk/tutorials/car-sales.md, book/src/evo-sdk/tutorials/card-game.md, book/src/evo-sdk/tutorials/react-integration.md	Construct DataContract with ownerId, identityNonce, schemas, and tokens map (keyed by position); publish via sdk.contracts.publish({ dataContract, identityKey, signer }); access contract id via contract.id.
Token Configuration & Ops book/src/evo-sdk/tutorials/basic-token.md, book/src/evo-sdk/tutorials/card-game.md	Replaced inline token JSON with SDK classes (e.g., TokenConfiguration, AuthorizedActionTakers, ContractOwner); mint/transfer/burn now use dataContractId + tokenPosition, Identifier-typed ids, IdentitySigner, and bigint amounts (...n).
Document CRUD & Queries book/src/evo-sdk/tutorials/car-sales.md, book/src/evo-sdk/tutorials/card-game.md, book/src/evo-sdk/tutorials/react-integration.md	Create/replace/get now build Document instances with documentTypeName, dataContractId, ownerId, properties; SDK calls use { document, identityKey, signer }; queries use dataContractId/documentTypeName; access data via doc.properties.
Identity and Access Patterns book/src/evo-sdk/tutorials/react-integration.md, book/src/evo-sdk/tutorials/car-sales.md	Replace privateKeyWif/signing-index/nonce flows with fetching Identity, selecting a public key, constructing IdentitySigner from WIF, and passing identityKey + signer to SDK calls; identity fields accessed via properties (id, balance, publicKeys).
Balance Lookup Logic book/src/evo-sdk/tutorials/basic-token.md, book/src/evo-sdk/tutorials/react-integration.md	Replace map lookup by tokenId (balances.get(tokenId)) with iterating returned balance entries and matching by contractId/id.toString() to find the target balance; supply query still demonstrates calculateId(contractId, 0) where shown.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant SDK
  participant IdRepo as IdentityStore
  participant Chain as Network

  Client->>IdRepo: fetch(IDENTITY_ID)
  IdRepo-->>Client: Identity (id, publicKeys, privateWif)
  Client->>Client: select publicKey index, create IdentitySigner(privateWif)
  Client->>SDK: new DataContract(ownerId, identityNonce, schemas, tokens)
  Client->>SDK: sdk.contracts.publish({ dataContract, identityKey, signer })
  SDK->>Chain: submit contract publish tx (signed)
  Chain-->>SDK: publish result (contract)
  SDK-->>Client: contract (contract.id)

Loading

sequenceDiagram
  participant Client
  participant SDK
  participant IdRepo as IdentityStore
  participant Chain as Network

  Client->>IdRepo: fetch(IDENTITY_ID)
  IdRepo-->>Client: Identity + privateWif
  Client->>Client: create IdentitySigner
  Client->>SDK: sdk.tokens.mint({ dataContractId, tokenPosition, recipientId, amount, identityKey, signer })
  SDK->>Chain: submit mint tx (signed)
  Chain-->>SDK: tx result
  SDK-->>Client: updated balances / receipt

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A hop, a sign, a contract bright,
With Signer in paw and tokens in sight,
Documents neat, positions in row,
Bigints marching—off we go! 🌿

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately describes the main change: updating tutorial code examples to match the evo-sdk@3.1.0-dev API.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}

[thepastaclaw]

⏳ Review in progress (commit 53c208c)

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

book/src/evo-sdk/tutorials/basic-token.md (1)

189-189: ⚠️ Potential issue | 🟠 Major

Reference to undefined tokenId variable.

Line 189 uses tokenId which is never defined in the tutorial:

const supply = await sdk.tokens.totalSupply(tokenId);

Based on the context and the pattern used elsewhere in this tutorial (lines 168-178), this should be contractId instead:

const supply = await sdk.tokens.totalSupply(contractId);

🔧 Proposed fix

-const supply = await sdk.tokens.totalSupply(tokenId);
+const supply = await sdk.tokens.totalSupply(contractId);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@book/src/evo-sdk/tutorials/basic-token.md` at line 189, The tutorial calls
sdk.tokens.totalSupply with an undefined tokenId; replace tokenId with the
previously defined contractId so the call becomes
sdk.tokens.totalSupply(contractId). Update the call to use contractId (the
identifier used earlier in this tutorial) to fix the undefined variable error
and keep the sdk.tokens.totalSupply usage consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@book/src/evo-sdk/tutorials/basic-token.md`:
- Around line 113-118: The DataContract constructor call should not pass a
tokens field — remove tokens from the DataContract({...}) call and instead build
the contract JSON including tokens (e.g., include tokenConfig under tokens) and
load it with DataContract.fromJSON(contractJson) so tokens are present in
contract data; also replace the undefined tokenId usage by computing it first
with sdk.tokens.calculateId(contractId, 0) and then call
sdk.tokens.totalSupply(tokenId) (refer to DataContract, DataContract.fromJSON,
tokenConfig, contractId, sdk.tokens.calculateId, and sdk.tokens.totalSupply).

In `@book/src/evo-sdk/tutorials/car-sales.md`:
- Line 163: The call to sdk.documents.get(contractId, 'listing', listingId) can
return undefined but the tutorial code assumes a Document; update the snippet to
check the returned value (e.g., the variable existing) and handle the missing
case—throw a clear error like "Listing not found" or return/handle
gracefully—before using existing in subsequent code paths so sdk.documents.get,
contractId, listingId and existing are referenced and protected against
undefined.

In `@book/src/evo-sdk/tutorials/card-game.md`:
- Around line 335-336: The tutorial calls sdk.documents.get(contractId, 'card',
fromCardId) and sdk.documents.get(contractId, 'card', toCardId') which can
return undefined; update the code around the calls (references:
sdk.documents.get, fromCard, toCard) to check for falsy values and throw or
handle an error (e.g., throw new Error('Card not found') or return a
user-friendly error) when either document is undefined before proceeding.

---

Outside diff comments:
In `@book/src/evo-sdk/tutorials/basic-token.md`:
- Line 189: The tutorial calls sdk.tokens.totalSupply with an undefined tokenId;
replace tokenId with the previously defined contractId so the call becomes
sdk.tokens.totalSupply(contractId). Update the call to use contractId (the
identifier used earlier in this tutorial) to fix the undefined variable error
and keep the sdk.tokens.totalSupply usage consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 47ddefd8-dea4-459d-bab0-7c0fa1414395

📥 Commits

Reviewing files that changed from the base of the PR and between 5381e78 and a2e3859.

📒 Files selected for processing (4)

• book/src/evo-sdk/tutorials/basic-token.md
• book/src/evo-sdk/tutorials/car-sales.md
• book/src/evo-sdk/tutorials/card-game.md
• book/src/evo-sdk/tutorials/react-integration.md

[thephez]

I haven't run the code myself, but claw created this based on the work done in a separate repo to test these tutorials and fix them. As written originally the tutorials just didn't work from what we could tell on the current published stable or dev versions of the SDK (or the current 3.1-dev branch). If not perfect, they should at least be closer to usable.