Basic Token tutorial: API mismatches with evo-sdk@3.1.0-dev.1

[thepastaclaw]

Tutorial

Creating a Basic Token
(source)

API Mismatch Issues

1. contracts.publish() — wrong signature

Tutorial uses:

sdk.contracts.publish({ identityId, documentSchemas, tokens: [tokenConfig], privateKeyWif, signingKeyIndex, nonce })

Actual ContractPublishOptions: { dataContract: DataContract, identityKey: IdentityPublicKey, signer: IdentitySigner }. There is no documentSchemas, tokens, privateKeyWif, or nonce field. Token configuration must be part of the DataContract construction.

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

Property getter, not a method.

3. tokens.mint() — wrong signature

Tutorial uses:

sdk.tokens.mint({ tokenId, amount, recipientId, identityId, privateKeyWif, signingKeyIndex, nonce })

Actual TokenMintOptions:

{ dataContractId: Identifier, tokenPosition: number, amount: bigint, identityId: Identifier, recipientId?: Identifier, identityKey: IdentityPublicKey, signer: IdentitySigner }

Key differences:

• Uses dataContractId + tokenPosition instead of tokenId
• Requires identityKey + signer instead of privateKeyWif/signingKeyIndex
• amount must be bigint, not number
• No nonce field

4. tokens.identityBalances() / balances.get(tokenId) — Map key mismatch

Tutorial does balances.get(tokenId) where tokenId is a string. The Map keys are Identifier objects, so direct .get() with a string won't match. Need to iterate entries and compare via .toString().

5. tokens.transfer() — wrong signature

Tutorial uses:

sdk.tokens.transfer({ tokenId, amount, recipientId, identityId, privateKeyWif, signingKeyIndex, nonce })

Actual TokenTransferOptions:

{ dataContractId: Identifier, tokenPosition: number, amount: bigint, senderId: Identifier, recipientId: Identifier, identityKey: IdentityPublicKey, signer: IdentitySigner }

Note: identityId → senderId, tokenId → dataContractId + tokenPosition.

6. tokens.burn() — wrong signature

Same pattern: uses tokenId/privateKeyWif/nonce instead of dataContractId/tokenPosition/identityKey/signer.

7. Token config is a plain object in the tutorial

Tutorial shows:

{ conventions: {...}, manualMinting: { rules: { type: "ownerOnly" } }, maxSupply: 1_000_000_00 }

Real API requires constructing full SDK classes: TokenConfiguration, TokenConfigurationConvention, TokenConfigurationLocalization, ChangeControlRules, AuthorizedActionTakers, TokenDistributionRules, TokenKeepsHistoryRules, TokenMarketplaceRules, TokenTradeMode. ~30 lines of boilerplate for what the tutorial shows as 10.

Runtime Issues (discovered during live testnet execution)

8. Token operations require CRITICAL security level key

The tutorial uses signingKeyIndex: 0 (Master key) for token ops, but minting/burning/transferring tokens requires a CRITICAL-level authentication key. Using HIGH or MASTER fails with:

Invalid public key security level HIGH. The state transition requires one of CRITICAL

9. Schema properties require position fields

Same as Car Sales #8 — DPP requires position: N on every property.

10. identityNonce needs to be incremented

Same as Car Sales #11 — nonce() returns last used, constructor needs nonce + 1n.

11. supply.totalSupply access pattern

Tutorial uses supply.totalSupply. The actual return type from sdk.tokens.totalSupply() may differ — needs verification of the TokenTotalSupply class shape.

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: basic-token tutorial — match actual evo-sdk API #7 comment)