@dashevo/wasm-dpp2 4.2.0-beta.5 → 4.2.0-beta.7

package/README.md

@@ -46,3 +46,45 @@ carried before it is passed to `DocumentCreateTransition` is replaced: the
 transition can only carry the id consensus recomputes. For the same reason
 `new Document({...})` refuses an explicit `id` that disagrees with the one its
 `identityContractNonce` derives. No app needs to reimplement the hash.
+
+## Checking a contract update
+
+A data contract update is refused when it breaks an update rule: the version
+must rise by exactly one, the indexes of an existing document type are fixed,
+a property may be added but not removed, a new required property needs
+`requiredSince`, and so on for every keyword (see the book, *Contract
+Keywords*, the *On update* row of each keyword). `DataContract.validateUpdate`
+runs those rules with the code consensus runs on the update transition
+(`DataContract::validate_update`), so an app, a CI job or a review tool can
+check a proposed contract before paying for a transition the platform would
+refuse:
+
+```ts
+const version = new PlatformVersion(14);
+const current = DataContract.fromJSON(currentJson, true, version);
+const proposed = DataContract.fromJSON(proposedJson, true, version);
+
+const errors = current.validateUpdate(proposed, undefined, version);
+// [] when the update is valid; otherwise ConsensusError objects, e.g.
+// errors[0].code === 10217 when an index of an existing type changed
+```
+
+Each error is a `ConsensusError` with the `code` a refused transition reaches
+JS with. The second argument is the `BlockInfo` of the block the update would
+be executed in, of which only the time is read (an added token's
+pre-programmed distributions may not start before it); `undefined` uses the
+device clock. The two contracts are compared whatever their ids, as the
+platform compares the stored contract with the proposed one. Build the
+proposed contract with full validation, as above, since the transition's
+structural checks run there. No state is read, so what the platform checks
+against state on top is not covered: that the contract exists, that group
+members, identities named by token configurations and appointed moderators
+exist, that references into other contracts resolve, and the signature, nonce
+and fees.
+
+This package is built with the crate's `validation` feature, which the method
+needs. It also makes full validation (`fromJSON(…, true, …)`, `fromObject`,
+`fromBytes`, `new DataContract({ fullValidation: true })`) run the document
+meta-schema, and contract parse errors come back as consensus errors with
+codes. `@dashevo/wasm-sdk` and `@dashevo/evo-sdk` build these bindings without
+it, to keep their size, so they have no `validateUpdate`.