Skip to content

Commit

Permalink
Update docs and links for ink! 4.0 (#168)
Browse files Browse the repository at this point in the history
  • Loading branch information
cmichi authored Feb 15, 2023
1 parent f71fc02 commit 3593033
Show file tree
Hide file tree
Showing 25 changed files with 77 additions and 87 deletions.
4 changes: 2 additions & 2 deletions docs/basics/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ There are three ways to debug your ink! contract currently:
### How do I print to the terminal console from ink!?

You can use those two macros:
* [`ink::env::debug_println!`](https://docs.rs/ink_env/4.0.0-rc/ink_env/macro.debug_println.html)
* [`ink::env::debug_print!`](https://docs.rs/ink_env/4.0.0-rc/ink_env/macro.debug_print.html)
* [`ink::env::debug_println!`](https://docs.rs/ink_env/4.0.0/ink_env/macro.debug_println.html)
* [`ink::env::debug_print!`](https://docs.rs/ink_env/4.0.0/ink_env/macro.debug_print.html)

There are three things you have to do for the debug messages to show up on the console:

Expand Down
18 changes: 9 additions & 9 deletions docs/basics/env-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ slug: /basics/environment-functions
---

ink! exposes a number of handy environment functions.
A full overview [is found here](https://docs.rs/ink_env/4.0.0-rc/ink_env/#functions).
A full overview [is found here](https://docs.rs/ink_env/4.0.0/ink_env/#functions).

In an `#[ink(constructor)]` use `Self::env()` to access those,
in an `#[ink(message)]` use `self.env()`.
So e.g. `Self::env().caller()` or `self.env().caller()`.

Some handy functions include:

* [`caller()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.caller.html): Returns the address of the caller of the executed contract.
* [`account_id()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.account_id.html): Returns the account ID of the executed contract.
* [`balance()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.balance.html): Returns the balance of the executed contract.
* [`block_number()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.block_number.html): Returns the current block number.
* [`emit_event(…)`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.emit_event.html): Emits an event with the given event data.
* [`transfer(…)`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.transfer.html): Transfers value from the contract to the destination account ID.
* [`hash_bytes(…)`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.hash_bytes.html): Conducts the crypto hash of the given input and stores the result in output.
* […and many more](https://docs.rs/ink_env/4.0.0-rc/ink_env/#functions).
* [`caller()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.caller.html): Returns the address of the caller of the executed contract.
* [`account_id()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.account_id.html): Returns the account ID of the executed contract.
* [`balance()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.balance.html): Returns the balance of the executed contract.
* [`block_number()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.block_number.html): Returns the current block number.
* [`emit_event(…)`](https://docs.rs/ink_env/4.0.0/ink_env/fn.emit_event.html): Emits an event with the given event data.
* [`transfer(…)`](https://docs.rs/ink_env/4.0.0/ink_env/fn.transfer.html): Transfers value from the contract to the destination account ID.
* [`hash_bytes(…)`](https://docs.rs/ink_env/4.0.0/ink_env/fn.hash_bytes.html): Conducts the crypto hash of the given input and stores the result in output.
* […and many more](https://docs.rs/ink_env/4.0.0/ink_env/#functions).
2 changes: 1 addition & 1 deletion docs/basics/metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ comes from the smart contracting language itself, and not the contract nor the u
environment (e.g `pallet-contracts`).

All ink! messages and constructors now return a `Result` which uses this as the `Error`
variant (see the [`LangError`](https://docs.rs/ink/4.0.0-rc/ink/enum.LangError.html) docs for more).
variant (see the [`LangError`](https://docs.rs/ink/4.0.0/ink/enum.LangError.html) docs for more).

:::

Expand Down
2 changes: 1 addition & 1 deletion docs/basics/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ You then have fine-grained control over how a contract is called;
for example you can influence the block advancement, the value transferred to it,
by which account it is called, which storage it is run with, etc..

See the [`examples/erc20`](https://github.com/paritytech/ink/blob/master/examples/erc20/lib.rs) contract on how to utilize those or [the documentation](https://docs.rs/ink/4.0.0-rc/ink/attr.test.html) for details.
See the [`examples/erc20`](https://github.com/paritytech/ink/blob/master/examples/erc20/lib.rs) contract on how to utilize those or [the documentation](https://docs.rs/ink/4.0.0/ink/attr.test.html) for details.

At the moment there are some known limitations to our off-chain environment,
and we are working on making it behave as close to the real chain environment
Expand Down
2 changes: 1 addition & 1 deletion docs/basics/trait-definitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Marks trait definitions to ink! as special ink! trait definitions.

There are some restrictions that apply to ink! trait definitions that
this macro checks. Also ink! trait definitions are required to have specialized
structure so that the main [`#[ink::contract]`](https://docs.rs/ink/4.0.0-rc/ink/attr.contract.html) macro can
structure so that the main [`#[ink::contract]`](https://docs.rs/ink/4.0.0/ink/attr.contract.html) macro can
properly generate code for its implementations.

# Example: Definition
Expand Down
12 changes: 6 additions & 6 deletions docs/datastructures/custom.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ also create their own custom data structures.

## Using custom types on storage
Any custom type wanting to be compatible with ink! storage must implement the
[`Storable`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/trait.Storable.html)
[`Storable`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/trait.Storable.html)
trait, so it can be SCALE
[`encoded`](https://docs.rs/parity-scale-codec/3.2.2/parity_scale_codec/trait.Encode.html)
and
[`decoded`](https://docs.rs/parity-scale-codec/3.2.2/parity_scale_codec/trait.Decode.html).
Additionally, the traits
[`StorageLayout`](https://docs.rs/ink_storage/latest/ink_storage/traits/trait.StorageLayout.html)
[`StorageLayout`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/trait.StorageLayout.html)
and [`TypeInfo`](https://docs.rs/scale-info/2.3.1/scale_info/trait.TypeInfo.html)
are required as well. But don't worry, usually these traits can just be derived:

Expand All @@ -42,7 +42,7 @@ pub struct ContractStorage {
```

Even better: there is a macro
[`#[ink::storage_item]`](https://docs.rs/ink_macro/4.0.0-rc/ink_macro/attr.storage_item.html),
[`#[ink::storage_item]`](https://docs.rs/ink_macro/4.0.0/ink_macro/attr.storage_item.html),
which derives all necessary traits for you. If there is no need to implement any special
behavior, the above code example can be simplified further as follows:

Expand All @@ -65,10 +65,10 @@ the relevant trait documentations for more information.
:::note

The `#[ink::storage_item]` macro is responsible for storage key calculation of
non-[`Packed`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/trait.Packed.html)
non-[`Packed`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/trait.Packed.html)
types. Without it, the key for non-`Packed` fields will be zero. Using this macro is
necessary if you don't plan to use a
[`ManualKey`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/struct.ManualKey.html)
[`ManualKey`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/struct.ManualKey.html)
on a non-`Packed` type.

Types with custom implementations of the ink! storage traits can still use this macro only
Expand All @@ -81,7 +81,7 @@ for key calculation by disabling the derives: `#[ink::storage_item(derive = fals
It is possible to use generic data types in your storage, as long as any generic type
satisfies the required storage trait bounds. In fact, we already witnessed this in the
previous sections about the
[`Mapping`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Mapping.html).
[`Mapping`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html).

Let's say you want a mapping where accessing a non-existent key should just return
it's default value, akin to how mappings work in Solidity. Additionally, you want to know
Expand Down
2 changes: 1 addition & 1 deletion docs/datastructures/mapping.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ hide_title: true

# Working with Mapping

In this section we demonstrate how to work with ink! [`Mapping`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Mapping.html).
In this section we demonstrate how to work with ink! [`Mapping`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html).

Here is an example of a mapping from a user to a `Balance`:

Expand Down
4 changes: 2 additions & 2 deletions docs/datastructures/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ hide_title: true

The `ink_storage` crate acts as the standard storage library for ink! smart contracts.
At the moment it provides two primitives for interacting with storage,
[`Mapping`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Mapping.html)
and [`Lazy`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Lazy.html).
[`Mapping`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html)
and [`Lazy`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Lazy.html).

`Mapping` is a mapping of key-value pairs directly to the contract storage. It is very
similar to traditional hash tables and comparable to the `mapping` type Solidity offers.
Expand Down
2 changes: 1 addition & 1 deletion docs/datastructures/storage-in-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ The storage will be reflected inside the metadata as like follows:

We observe that the storage layout is represented as a tree, where tangible storage values
end up inside a `leaf`. Because of
[`Packed`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/trait.Packed.html)
[`Packed`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/trait.Packed.html)
encoding, leafs can share the same storage key, and
in order to reach them you'd need to fetch and decode the whole storage cell under this key.

Expand Down
6 changes: 3 additions & 3 deletions docs/datastructures/storage-layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ extent, the storage API works similar to a traditional key-value database.
## Packed vs Non-Packed layout

Types that can be stored entirely under a single storage cell are considered
[`Packed`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/trait.Packed.html).
[`Packed`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/trait.Packed.html).
By default, ink! tries to store all storage struct fields under a single storage cell.
Consequentially, with a `Packed` storage layout, any message interacting with the contract
storage will always need to operate on the entire contract storage struct.
Expand Down Expand Up @@ -132,10 +132,10 @@ large or sparse arrays on contract storage, consider using a `Mapping` instead.
## Manual vs. Automatic Key Generation

By default, keys are calculated automatically for you, thanks to the
[`AutoKey`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/struct.AutoKey.html)
[`AutoKey`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/struct.AutoKey.html)
primitive. They'll be generated at compile time and ruled out for conflicts.
However, for non-`Packed` types like `Lazy` or the `Mapping`, the
[`ManualKey`](https://docs.rs/ink_storage_traits/4.0.0-rc/ink_storage_traits/struct.ManualKey.html)
[`ManualKey`](https://docs.rs/ink_storage_traits/4.0.0/ink_storage_traits/struct.ManualKey.html)
primitive allows manual control over the storage key of a field like so:

```rust
Expand Down
8 changes: 4 additions & 4 deletions docs/faq/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ See the [Chain Extensions](/macros-attributes/chain-extension) section for more

### How can I use ink! with a Substrate chain with a custom chain config?

Please see [the `env_types` argument](https://docs.rs/ink_macro/4.0.0-rc/ink_macro/attr.contract.html#header-arguments)
Please see [the `env_types` argument](https://docs.rs/ink_macro/4.0.0/ink_macro/attr.contract.html#header-arguments)
for the contract macro. It allows you to specify your environment a la
`#[ink::contract(env = MyEnvironment)]`.

Expand Down Expand Up @@ -168,15 +168,15 @@ Rust's standard library consists of three different layers:

A number of crypto hashes are built into the [pallet-contracts](/how-it-works) and
therefore very efficient to use. We currently support a handful of those, you
can view the complete list [here](https://docs.rs/ink_env/4.0.0-rc/ink_env/hash/trait.CryptoHash.html).
can view the complete list [here](https://docs.rs/ink_env/4.0.0/ink_env/hash/trait.CryptoHash.html).

If you have the urgent need for another crypto hash you could introduce it through
[Chain Extensions](/macros-attributes/chain-extension)
or make a proposal to include it into the default set of the `pallet-contracts`.

Using one of the built-in crypto hashes can be done as explained here:
* [`self.env().hash_bytes()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.hash_bytes.html)
* [`self.env().hash_encoded()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.hash_encoded.html)
* [`self.env().hash_bytes()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.hash_bytes.html)
* [`self.env().hash_encoded()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.hash_encoded.html)

### Why is it not possible to use floating point data types in ink!? How do I implement returning a decimal number?

Expand Down
30 changes: 15 additions & 15 deletions docs/faq/migrating-from-ink-3-to-4.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ we removed support for it in [#1403](https://github.com/paritytech/ink/pull/1403

As part of [#1233](https://github.com/paritytech/ink/pull/1233)
the `eth_compatibility` crate was removed. The `ecdsa_to_eth_address()`
function from it can now be found [in the `ink_env` crate](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.ecdsa_to_eth_address.html).
function from it can now be found [in the `ink_env` crate](https://docs.rs/ink_env/4.0.0/ink_env/fn.ecdsa_to_eth_address.html).

```rust
ink_env::ecdsa_to_eth_address(&pub_key, &mut output);
Expand All @@ -105,9 +105,9 @@ The return value is the size of the pre-existing value at the specified key if a

Two new useful functions were added:

- [`Mapping::contains(key)`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Mapping.html#method.contains)
- [`Mapping::contains(key)`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html#method.contains)
in [#1224](https://github.com/paritytech/ink/pull/1224).
- [`Mapping::take()`](https://docs.rs/ink_storage/4.0.0-rc/ink_storage/struct.Mapping.html#method.take)
- [`Mapping::take()`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html#method.take)
to get a value while removing it from storage in [#1461](https://github.com/paritytech/ink/pull/1461).

In case you were working around those two functions you can now
Expand All @@ -117,10 +117,10 @@ a `get(key).is_none()` instead of `contains(key)`.
## Storage functions in `ink_env`

As part of [#1224](https://github.com/paritytech/ink/pull/1224) the return type
of [`ink_env::set_contract_storage()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.set_contract_storage.html)
of [`ink_env::set_contract_storage()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.set_contract_storage.html)
was changed to return an `Option<u32>` instead of `()`.

A new function [`ink_env::take_contract_storage`](https://docs.rs/ink_env/4.0.0-rc/ink_env/fn.take_contract_storage.html)
A new function [`ink_env::take_contract_storage`](https://docs.rs/ink_env/4.0.0/ink_env/fn.take_contract_storage.html)
was introduced.

## Removal of `ink_env::random` function
Expand Down Expand Up @@ -177,7 +177,7 @@ for constructors `Result<Constructor::Output, LangError>`).
This happens even if the message/constructor doesn't have a return type,
we default to the unit type `()` in that case.

A [`LangError`](https://docs.rs/ink/4.0.0-rc/ink/enum.LangError.html)
A [`LangError`](https://docs.rs/ink/4.0.0/ink/enum.LangError.html)
is a type of error which doesn't originate from the contract itself,
nor from the underlying execution environment (so the Contracts pallet
in this case).
Expand Down Expand Up @@ -319,14 +319,14 @@ better.

## Updates to the `CallBuilder` and `CreateBuilder` APIs
There's been several changes to the
[`CallBuilder`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CallBuilder.html)
[`CallBuilder`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CallBuilder.html)
and
[`CreateBuilder`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CreateBuilder.html)
[`CreateBuilder`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CreateBuilder.html)
APIs.

In [#1604](https://github.com/paritytech/ink/pull/1604) we renamed the
`CallBuilder::fire()` method to
[`CallBuilder::invoke()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CallBuilder.html#method.invoke-2).
[`CallBuilder::invoke()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CallBuilder.html#method.invoke-2).
This brings more consistency across our APIs which were already using the `invoke`
terminology.

Expand All @@ -335,9 +335,9 @@ we added support for handing
`LangError`s from the `CreateBuilder` and `CallBuilder`, respectively.

If you want to handle errors from either `Builder` you can use the new
[`CreateBuilder::try_instantiate()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CreateBuilder.html#method.try_instantiate)
[`CreateBuilder::try_instantiate()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CreateBuilder.html#method.try_instantiate)
or
[`CallBuilder::try_invoke()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CallBuilder.html#method.try_invoke-1)
[`CallBuilder::try_invoke()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CallBuilder.html#method.try_invoke-1)
methods.

Because of the addition of those methods we also removed any error handling from the
Expand All @@ -347,10 +347,10 @@ directly, and panic when they encounter an error.

Lastly, in [#1636](https://github.com/paritytech/ink/pull/1636) we added two methods to
the `CallBuilder` to streamline
[`Call`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.Call.html)
[`Call`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.Call.html)
and
[`DelegateCall`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.DelegateCall.html)
[`DelegateCall`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.DelegateCall.html)
workflows:
- For `Call` you can use
[`CallBuilder::call()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CallBuilder.html#method.call) (this replaces `CallBuilder::callee()`)
- For `DelegateCall` you can use [`CallBuilder::delegate()`](https://docs.rs/ink_env/4.0.0-rc/ink_env/call/struct.CallBuilder.html#method.delegate)
[`CallBuilder::call()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CallBuilder.html#method.call) (this replaces `CallBuilder::callee()`)
- For `DelegateCall` you can use [`CallBuilder::delegate()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CallBuilder.html#method.delegate)
5 changes: 0 additions & 5 deletions docs/intro/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,6 @@ hide_table_of_contents: false
<a href="https://twitter.com/ink_lang">
<img style={{height: 25}} src="https://img.shields.io/twitter/follow/ink_lang?label=Follow" />
</a>
<br/>
<em>
ink! 4.0 was published as a release candidate on Jan 31 '23.<br/>
We'll soon publish the full release.
</em>
</center>

<h3 style={{lineHeight: 1.4 + "em", marginTop: 0.5 + "em"}}>
Expand Down
2 changes: 1 addition & 1 deletion docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ module.exports = {
lastVersion: 'current',
versions: {
current: {
label: '4.0-rc',
label: '4.0',
path: '',
banner: 'none',
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ Actualmente existen tres maneras de debuggear tu contrato ink!:
### ¿Cómo imprimo algo en la consola desde el runtime?

Puedes elegir entre estos dos macros:
* [`ink::env::debug_println!`](https://docs.rs/ink_env/4.0.0-rc/ink_env/macro.debug_println.html)
* [`ink::env::debug_print!`](https://docs.rs/ink_env/4.0.0-rc/ink_env/macro.debug_print.html)
* [`ink::env::debug_println!`](https://docs.rs/ink_env/4.0.0/ink_env/macro.debug_println.html)
* [`ink::env::debug_print!`](https://docs.rs/ink_env/4.0.0/ink_env/macro.debug_print.html)

Tienes que hacer tres cosas para poder mostrar en la consola los mensajes de debug:

Expand Down
Loading

0 comments on commit 3593033

Please sign in to comment.