Add migration guide from ink! 4.x to 5.0 #301
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…n-guide-4.x-to-5.0
smiasojed
approved these changes
Jan 29, 2024
SkymanOne
reviewed
Jan 29, 2024
xermicus
reviewed
Jan 30, 2024
xermicus
reviewed
Jan 30, 2024
Comment on lines
+273
to
+313
| ### New Data Structure: `StorageVec` | ||
|
|
||
| We've added a `Vec`-like data structure, built on top of Mapping. | ||
|
|
||
| This allows to retrieve elements from a vector and grow it without | ||
| having to load and push all elements. | ||
| For `Vec`, the cost of reading or writing a single element grows linearly corresponding | ||
| to the number of elements in the vector (its length). Additionally, the maximum capacity | ||
| of the whole vector is limited by the size of [ink!'s static buffer](https://github.com/paritytech/ink/blob/master/ARCHITECTURE.md#communication-with-the-pallet) | ||
| used during ABI encoding and decoding (default 16 KiB). | ||
| `StorageVec` on the other hand allows to access each element individually. | ||
|
|
||
| With a `Vec` it's possible to e.g. introduce a security issue in your contract | ||
| where an attacker can fill the `Vec`, making it very costly for other users to | ||
| access it or write to it. | ||
|
|
||
| You can find verbatim documentation on `StorageVec` [here](/5.x/datastructures/storagevec). | ||
| The page explains when to use `StorageVec` and when not. | ||
| The Rust docs can be found [here](https://docs.rs/ink/5.0.0-rc/ink/storage/struct.StorageVec.html). | ||
|
|
||
| ### Fallible methods for `Lazy`, `Mapping`, `StorageVec` | ||
|
|
||
| In [#1910](https://github.com/paritytech/ink/pull/1910) we added `try_*` methods for | ||
| reading and writing `Lazy` and `Mapping` values to and from storage. | ||
| The try methods correspond to `Mapping::{insert, get, take}`, `Lazy::{set, get}`. | ||
| For `StorageVec::{peek, get, set, pop, push}` we added `try_*` methods in | ||
| [#1995](https://github.com/paritytech/ink/pull/1995). | ||
|
|
||
| Please see the individual Rust docs for these new methods: | ||
|
|
||
| * [`StorageVec`](https://docs.rs/ink/5.0.0-rc/ink/storage/struct.StorageVec.html) | ||
| * [`Lazy`](https://docs.rs/ink/5.0.0-rc/ink/storage/struct.Lazy.html) | ||
| * [`Mapping`](https://docs.rs/ink/5.0.0-rc/ink/storage/struct.Mapping.html). For `Mapping`, the encoded size of the key is also accounted for. | ||
|
|
||
| You should use the `try_*` methods for dynamically sized values, unless you made sure | ||
| otherwise they will fit into the static buffer. The [static buffer in ink!](https://github.com/paritytech/ink/blob/master/ARCHITECTURE.md#communication-with-the-pallet) | ||
| is 16 kB by default. | ||
|
|
||
| We added a lint to `cargo-contract` 4.0 that will detect | ||
| potentially unsafe uses of methods for which there are safer alternatives: | ||
| [`non_fallible_api`](https://use.ink/5.x/linter/rules/non_fallible_api). |
Co-authored-by: Gherman <german@parity.io>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Most static image files are already in
master.