Card Game tutorial: API mismatches with evo-sdk@3.1.0-dev.1

[thepastaclaw]

Tutorial

Card Game with Tokens
(source)

This tutorial combines documents and tokens, so it inherits issues from both the Car Sales and Basic Token tutorials.

API Mismatch Issues

1. contracts.publish() — wrong signature

Same as Car Sales #1 and Basic Token #1. Uses simplified { identityId, documentSchemas, tokens, privateKeyWif, signingKeyIndex, nonce } instead of { dataContract, identityKey, signer }.

2. contract.getId() — should be contract.id

Same as other tutorials.

3. tokens.mint() — wrong signature

Same as Basic Token #3. Uses tokenId/privateKeyWif instead of dataContractId/tokenPosition/identityKey/signer.

4. documents.create() — wrong signature (multiple occurrences)

Used for creating cards (Step 4) and recording matches (Step 8). Same issue: simplified interface doesn't exist.

5. documents.query() — wrong field names (multiple occurrences)

Uses contractId/documentType in Steps 5, 6, 7, 9. Should be dataContractId/documentTypeName.

6. doc.getData() — does not exist (multiple occurrences)

Used in Steps 5, 6, 9. Should be doc.properties.

7. documents.transfer() — wrong signature

Tutorial uses:

sdk.documents.transfer({ contractId, documentType, documentId, recipientId, identityId, privateKeyWif, signingKeyIndex, nonce })

Actual DocumentTransferOptions:

{ document: Document, recipientId: Identifier, identityKey: IdentityPublicKey, signer: IdentitySigner }

Requires passing the full Document object, not just IDs.

8. tokens.transfer() — wrong signature

Same as Basic Token #5. Uses tokenId/identityId instead of dataContractId/tokenPosition/senderId/identityKey/signer.

9. Nonce management

All steps pass nonce as a field in options. The actual SDK options don't have a nonce field — nonce handling is internal.

Runtime Issues (discovered during live testnet execution)

10. Mixed security levels required

Contract publish and document create/query work with a HIGH security level key, but token mint/burn/transfer require a CRITICAL security level key. The tutorial doesn't mention this distinction — it uses a single signingKeyIndex for everything.

11. Schema properties require position fields

Same as Car Sales #8. Every property needs position: N.

12. Indexed string properties need maxLength <= 63

Same as Car Sales #9. Applies to card name, element, rarity fields if they were indexed.

13. identityNonce needs to be incremented

Same as Car Sales #11.

14. Integer properties return as bigint

Same as Car Sales #12. Card power, defense, edition and match player1Score, player2Score, timestamp all return as bigint from queries.

15. Token config requires full class hierarchy

Same as Basic Token #7. What the tutorial shows as a simple object requires constructing TokenConfiguration → TokenConfigurationConvention → TokenConfigurationLocalization, plus ChangeControlRules, AuthorizedActionTakers, TokenDistributionRules, TokenKeepsHistoryRules, TokenMarketplaceRules.

Environment

• @dashevo/evo-sdk: 3.1.0-dev.1
• Verified against v3.1-dev branch source
• Live testnet run: ALL STEPS PASSED (see PR fix: card-game tutorial — match actual evo-sdk API #8 comment)