From 25393cd9829adfc7cac1d752bc2355d74c362cea Mon Sep 17 00:00:00 2001 From: Jaco Greeff Date: Wed, 15 Apr 2020 10:43:15 +0200 Subject: [PATCH] Add note on field ordering (#2173) * Add note on field ordering * Field ordering additional links --- docs/start/types.extend.md | 9 +++++++++ docs/start/typescript.user.md | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/start/types.extend.md b/docs/start/types.extend.md index a1bed3afe1..287fd05aae 100644 --- a/docs/start/types.extend.md +++ b/docs/start/types.extend.md @@ -26,6 +26,15 @@ const api = await ApiPromise.create({ The above introduces the `types` registry, effectively allowing overrides and the definition of new types. The override above would mean that immediately the API will treat all occurrences of `Balance` not as the default, but rather as the defined size. +## Field ordering + +When defining any custom structures or types, it is critical that the following rules are applied - + +- Map exactly to what is defined in the Rust code, i.e. defining a `SaleType` cannot be `u16` on the one end and `u32` on the other end. If mismatches occur, the serialization will fail. +- Ensure that the field order is maintained in all definitions. The SCALE serialization is binary and contains no field names in the serialization, only the encoded values. Any decoding is therefore done based on the size of the type and the order thereof in the definitions. + +These rules apply everywhere. Always ensure that the types match exactly between the environments and that the ordering is maintained, be it for structs, tuples or enums. + ## User-defined structs Registration also applies to any type that can be found on a specific chain, i.e. we can add any types that is available on a specific node - diff --git a/docs/start/typescript.user.md b/docs/start/typescript.user.md index adb11e1957..1e2bb82c3e 100644 --- a/docs/start/typescript.user.md +++ b/docs/start/typescript.user.md @@ -4,7 +4,7 @@ In the previous section we looked at the TypeScript definitions that are availab ## Definitions -A large part of the type definitions are defined not as classes, but rather as structures from which type definitions are extracted and that can be used as-is to let the API know how to decode a type. By now you should be familiar with [type extensions](types.extend.md), but effectively the [types library does exactly the same](https://github.com/polkadot-js/api/tree/master/packages/types/src/interfaces). +A large part of the type definitions are defined not as classes, but rather as structures from which type definitions are extracted and that can be used as-is to let the API know how to decode a type. By now you should be familiar with [type extensions](types.extend.md) and the [rules around fields](types.extend.md#field-ordering), but effectively the [types library does exactly the same](https://github.com/polkadot-js/api/tree/master/packages/types/src/interfaces). To create TypeScript-aware definitions and keep your files in a single place, you can follow the same approach. Assuming you have a package named `@MeInc/stuff` where you have the definitions in an `stuff/interfaces` folder. Each sub-folder would indicate a runtime module, e.g.