Car Sales tutorial: API mismatches with evo-sdk@3.1.0-dev.1

[thepastaclaw]

Tutorial

Car Sales Management
(source)

API Mismatch Issues

1. contracts.publish() — wrong signature

Tutorial uses:

sdk.contracts.publish({ identityId, documentSchemas, privateKeyWif, signingKeyIndex, nonce })

Actual ContractPublishOptions:

{ dataContract: DataContract, identityKey: IdentityPublicKey, signer: IdentitySigner, settings?: PutSettings }

The tutorial's simplified "pass schemas + WIF key" interface does not exist. The real API requires constructing a DataContract object first, then passing identityKey + IdentitySigner.

2. contract.getId() — wrong accessor

Tutorial uses contract.getId().toString(). The DataContract class uses a property getter contract.id (returns Identifier), not a method.

3. documents.create() — wrong signature

Tutorial uses:

sdk.documents.create({ contractId, documentType, document: {...}, identityId, privateKeyWif, signingKeyIndex, nonce })

Actual DocumentCreateOptions: { document: Document, identityKey: IdentityPublicKey, signer: IdentitySigner }

4. documents.query() — wrong field names

Tutorial uses contractId/documentType. SDK expects dataContractId/documentTypeName.

5. doc.getData() — does not exist

Should be doc.properties.

6. documents.replace() — wrong signature

Tutorial uses:

sdk.documents.replace({ contractId, documentType, documentId, document: {...}, identityId, privateKeyWif, signingKeyIndex, nonce })

Actual DocumentReplaceOptions: { document: Document, identityKey: IdentityPublicKey, signer: IdentitySigner }
The real API requires fetching the existing document, modifying it, incrementing revision, and passing it back.

7. identities.nonce() / identities.contractNonce() — return type

Tutorial treats these as providing a nonce field directly. The actual API returns Promise<bigint | undefined>, and the real options interfaces don't have a nonce field — nonce management is handled internally.

Runtime Issues (discovered during live testnet execution)

8. Schema properties require position fields

DPP requires each property in a document schema to have a position: N field. The tutorial omits this entirely. Without it, DataContract construction fails with "position not found in map".

9. Indexed string properties need maxLength <= 63

The tutorial uses maxLength: 64 for fields like make and status, but the platform rejects indexed string properties with maxLength > 63.

10. Index sort direction only supports asc

The tutorial uses orderBy: [["rating", "desc"]] in review queries, but DPP index definitions only accept asc. Using desc fails at contract publish.

11. identityNonce needs to be incremented

sdk.identities.nonce() returns the last used nonce. The DataContract constructor needs the next unused one (nonce + 1n).

12. Integer properties return as bigint from queries

When documents are queried, integer fields come back as bigint. When passing them back in documents.replace(), they must be converted to number or the platform rejects them with "not of type integer".

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: car-sales tutorial — match actual evo-sdk API #6 comment)