diff --git a/.eslintignore b/.eslintignore index e274726052..ed7bd68074 100644 --- a/.eslintignore +++ b/.eslintignore @@ -4,5 +4,7 @@ node_modules/ babel.config.js docusaurus.config.js sidebars.js -versioned_docs/version-5.x/third-party-tools/swanky/Figure.tsx -versioned_docs/version-5.x/testing/testnet/Faucet.tsx \ No newline at end of file +versioned_docs/version-4.x/third-party-tools/swanky/Figure.tsx +versioned_docs/version-4.x/testnet/Faucet.tsx +docs/third-party-tools/swanky/Figure.tsx +docs/testnet/Faucet.tsx diff --git a/docs/basics/cross-contract-calling.md b/docs/basics/cross-contract-calling.md index 25bd8876e3..9ed2193710 100644 --- a/docs/basics/cross-contract-calling.md +++ b/docs/basics/cross-contract-calling.md @@ -192,9 +192,9 @@ Data Ok(true) ## Builders The -[`CreateBuilder`](https://docs.rs/ink_env/latest/ink_env/call/struct.CreateBuilder.html) +[`CreateBuilder`](https://docs.rs/ink_env/5.0.0/ink_env/call/struct.CreateBuilder.html) and -[`CallBuilder`](https://docs.rs/ink_env/latest/ink_env/call/struct.CallBuilder.html) +[`CallBuilder`](https://docs.rs/ink_env/5.0.0/ink_env/call/struct.CallBuilder.html) offer low-level, flexible interfaces for performing cross-contract calls. The `CreateBuilder` allows you to instantiate already uploaded contracts, and the `CallBuilder` allows you to call messages on instantiated contracts. @@ -228,6 +228,7 @@ Below is an example of how to instantiate a contract using the `CreateBuilder`. ```rust use contract::MyContractRef; let my_contract: MyContractRef = build_create::() + .instantiate_v1() .code_hash(Hash::from([0x42; 32])) .gas_limit(0) .endowment(10) @@ -272,6 +273,7 @@ Below is an example of how to call a contract using the `CallBuilder`. We will: ```rust let my_return_value = build_call::() .call(AccountId::from([0x42; 32])) + .call_v1() .gas_limit(0) .transferred_value(10) .exec_input( @@ -333,11 +335,11 @@ These allow contract developers to handle two types of errors: 2. Error from the programming language (e.g `LangError`s) See the documentation for -[`try_instantiate`](https://docs.rs/ink_env/latest/ink_env/call/struct.CreateBuilder.html#method.try_instantiate), -[`try_invoke`](https://docs.rs/ink_env/latest/ink_env/call/struct.CallBuilder.html#method.try_invoke-2), -[`ink::env::Error`](https://docs.rs/ink_env/latest/ink_env/enum.Error.html) +[`try_instantiate`](https://docs.rs/ink_env/5.0.0/ink_env/call/struct.CreateBuilder.html#method.try_instantiate), +[`try_invoke`](https://docs.rs/ink_env/5.0.0/ink_env/call/struct.CallBuilder.html#method.try_invoke-2), +[`ink::env::Error`](https://docs.rs/ink_env/5.0.0/ink_env/enum.Error.html) and -[`ink::LangError`](https://docs.rs/ink/latest/ink/enum.LangError.html) +[`ink::LangError`](https://docs.rs/ink/5.0.0/ink/enum.LangError.html) for more details on proper error handling. :::tip diff --git a/docs/basics/env-functions.md b/docs/basics/env-functions.md index bce5e172b1..c775c6312f 100644 --- a/docs/basics/env-functions.md +++ b/docs/basics/env-functions.md @@ -3,8 +3,12 @@ title: Environment Functions slug: /basics/environment-functions --- + + +# Environment Functions + ink! exposes a number of handy environment functions. -A full overview [is found here](https://docs.rs/ink_env/4.0.0/ink_env/#functions). +A full overview [is found here](https://docs.rs/ink_env/5.0.0/ink_env/#functions). In an `#[ink(constructor)]` use `Self::env()` to access those, in an `#[ink(message)]` use `self.env()`. @@ -12,11 +16,11 @@ So e.g. `Self::env().caller()` or `self.env().caller()`. Some handy functions include: -* [`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). +* [`caller()`](https://docs.rs/ink_env/5.0.0/ink_env/fn.caller.html): Returns the address of the caller of the executed contract. +* [`account_id()`](https://docs.rs/ink_env/5.0.0/ink_env/fn.account_id.html): Returns the account ID of the executed contract. +* [`balance()`](https://docs.rs/ink_env/5.0.0/ink_env/fn.balance.html): Returns the balance of the executed contract. +* [`block_number()`](https://docs.rs/ink_env/5.0.0/ink_env/fn.block_number.html): Returns the current block number. +* [`emit_event(…)`](https://docs.rs/ink_env/5.0.0/ink_env/fn.emit_event.html): Emits an event with the given event data. +* [`transfer(…)`](https://docs.rs/ink_env/5.0.0/ink_env/fn.transfer.html): Transfers value from the contract to the destination account ID. +* [`hash_bytes(…)`](https://docs.rs/ink_env/5.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/5.0.0/ink_env/#functions). diff --git a/docs/basics/events.md b/docs/basics/events.md index aaa5710686..a111bda578 100644 --- a/docs/basics/events.md +++ b/docs/basics/events.md @@ -62,32 +62,127 @@ for an elaborate example which uses events. ## Event Definition +Since ink! version 5.0, events can be defined independently of the contract which emits them. +Events can now be defined once and shared across multiple contracts. + +This is useful for events for contracts which conform to standards such as ERC-20: +contract indexers/explorers are now able to group all e.g. `Transferred` events. + This is how an event definition looks: ```rust -#[ink(event)] +use ink::primitives::AccountId; + +#[ink::event] pub struct Transferred { #[ink(topic)] from: Option, - #[ink(topic)] to: Option, + amount: u128, +} +``` +> Note that generics are [not currently supported](https://github.com/paritytech/ink/issues/2044) +> , so the concrete types of `Environment` +> specific types such as `AccountId` must match up with the types used in the contract. - amount: Balance +This definition can exist within a contract definition module (inline events), in a different +module in the same crate or even in a different crate to be shared by multiple contracts. -} +### Legacy syntax for inline Event definitions + +Events defined within a `#[ink::contract]` module can continue to use the original syntax for an +event definition, using the `#[ink(event)]` attribute. Under the covers this is simply expanded +to the new top level `#[ink::event]` macro, so both events defined using the legacy style and +using the new `event` attribute macro directly will behave exactly the same. + +### Topics + +When an event is emitted, 0 or more topics can be associated with it. The event is then indexed +together with other events with the same topic value. + +An event's fields can be annotated with `#[ink(topic)]` (see example), which will result in a +topic derived from the value of that field being emitted together with the event. + +Topics are by default a 32 byte array (`[u8; 32]`), although this is configurable on the +Polkadot SDK runtime level. If the SCALE encoded bytes of a field value are `<= 32`, then the +encoded bytes are used directly as the topic value. + +For example, in the common case of indexing a field of type `AccountId`, where the default +`AccountId` type is 32 bytes in length, the topic value will be the encoded account id itself. This +makes it easy to filter for all events which have a topic of a specific `AccountId`. + +If however the size of the encoded bytes of the value of a field exceeds 32, then the encoded +bytes will be hashed using the `Blake2x256` hasher. + +> Topics are a native concept in the Polkadot SDK, and can be queried via [`EventTopics`](https://docs.rs/frame-system/latest/frame_system/pallet/storage_types/struct.EventTopics.html) + +How to choose which fields to make topics? A good rule of thumb is to ask yourself if somebody +might want to search for this topic. For this reason the `amount` in the example `Transferred` event +above was not made indexable ‒ there will most probably be a lot of different events with differing +amounts each. + +#### Signature Topic + +By default all events have a signature topic. This allows indexing of all events of the same +type, emitted by different contracts. The `#[ink::event]` macro generates a signature topic at +compile time by hashing the name of the event concatenated with the *names of the types* of the all +the field +names: ``` +blake2b("Event(field1_type,field2_type)")` +``` +So for our `Transferred` example it will be: +``` +blake2b("Transferred(Option,Option,u128)")` +``` + +:::caution +Important caveat: because the *name* of the field type is used, refactoring an event +definition to use a type alias or a fully qualified type will change the signature topic, even +though the underlying type is the same. Two otherwise identical definitions of an event with the +same name and same field types but different field type names will have different signature +topics. +::: + +When decoding events emitted from a contract, signature topics are now required to determine which +type of event to decode into. -Add the `#[ink(topic)]` attribute tag to each item in your event that you want to have indexed. -A good rule of thumb is to ask yourself if somebody might want to search for this topic. -For this reason the `amount` in the exemplary event above was not -made indexable ‒ there will most probably be a lot of different events with -differing amounts each. +#### Anonymous Events -The signature of the event is by default one of the topics of the event, except -if you annotate the event with `#[ink(anonymous)]`. -See [here](../macros-attributes/anonymous.md) for details on this attribute. +Events annotated with `anonymous` will not have a signature topic generated and published with the +event. +For inline events, this can be done by marking the event with the `anonymous` attribute e.g. + +```rust +#[ink(event, anonymous)] +pub struct Event { .. } +``` +or +```rust +#[ink(event)] +#[ink(anonymous)] +pub struct Event { .. } +``` + +For events defined using the `#[ink::event]` macro, the `anonymous` flag needs to be added as an +argument: + +```rust +#[ink::event(anonymous)] +pub struct Event { .. } +``` + +Without a signature topic, indexers will not be able to index over the type of the event, which +may be desirable for some contracts, and would be a small gas cost optimization if necessary. + +However, when interacting with the contract from a client, no signature topic means that another +way is required to determine the type of the event to be decoded into (i.e. how do we know it is +a `Transferred` event, not an `Approval` event. One way would be to try decoding for each type +of event defined in the metadata of the contract until one succeeds. If calling a specific +`message`, it may be known up front what type of event that message will raise, so the client +code could just decode into that event directly. ## Emitting Events in a Constructor @@ -128,3 +223,12 @@ pub fn transfer(&mut self, to: AccountId, amount: Balance) -> Result { Ok(()) } ``` + +## Cost of using Events + +When using events and topics, developers should be mindful of the costs associated. Firstly: if +optimizing for contract size, using events will increase the size of the final code size. So +minimizing or eliminating event usage where necessary will reduce contract size. The same can be +said for the execution (aka gas) costs when using events. We recommend considering the cost of +events when using them, and measuring the code size and gas costs with different usage patterns +when optimizing. diff --git a/versioned_docs/version-5.x/basics/gas.md b/docs/basics/gas.md similarity index 100% rename from versioned_docs/version-5.x/basics/gas.md rename to docs/basics/gas.md diff --git a/docs/basics/metadata.md b/docs/basics/metadata.md index 6c92b3f6d8..83bb99b93f 100644 --- a/docs/basics/metadata.md +++ b/docs/basics/metadata.md @@ -174,12 +174,12 @@ The contract `spec` consists of the following **required** keys: - `return_type`: The return type of the message. - `docs`: The message documentation. - `environment`: Configuration of the types that the host blockchain operates with. -You can check default types in [Environment](https://use.ink/basics/chain-environment-types) section. +You can check default types in [Environment](./environment.md) section. - `accountId`: The type describing an account address. - `balance`: The type describing balance values. - `blockNumber`: The type describing a block number. - `chainExtension`: The type describing the chain extension for the environment. -For more information about usage and definition check [this section](https://use.ink/macros-attributes/chain-extension). +For more information about usage and definition check [this section](../macros-attributes/chain-extension.md). - `maxEventTopics`: The maximum number of supported event topics provided by the runtime. - `timestamp`: the type describing a timestamp. - `events`: The events of the contract. @@ -203,7 +203,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/ink/enum.LangError.html) docs for more). +variant (see the [`LangError`](https://docs.rs/ink/5.0.0/ink/enum.LangError.html) docs for more). ::: diff --git a/docs/basics/selectors.md b/docs/basics/selectors.md index c06dd485c9..1f6b75e8f3 100644 --- a/docs/basics/selectors.md +++ b/docs/basics/selectors.md @@ -4,6 +4,8 @@ hide_title: true slug: /basics/selectors --- + + # Selectors Selectors in ink! are a language agnostic way of identifying constructors and messages. diff --git a/docs/basics/storing-values.md b/docs/basics/storing-values.md index 7db6574b67..d823d4d438 100644 --- a/docs/basics/storing-values.md +++ b/docs/basics/storing-values.md @@ -32,7 +32,7 @@ they were primitive types. ### String, Vector and More -The [`ink_prelude`](https://docs.rs/ink_prelude/latest/ink_prelude/index.html) crate provides an efficient approach to import commonly used Rust types such as `String` and `Vec`, ensuring safe usage within an ink! contract. +The [`ink_prelude`](https://docs.rs/ink_prelude/5.0.0/ink_prelude/index.html) crate provides an efficient approach to import commonly used Rust types such as `String` and `Vec`, ensuring safe usage within an ink! contract. This simplifies the type referencing process between the `std` and `no_std` environments. Typically, these types are defined within the `std` crate in the `std` environment, and the `alloc` crate in the `no_std` environment. Given that ink! smart contract code is compiled in both environments (`no_std` for production and `std` for unit tests), developers might find themselves writing intricate conditional compilation macros. The `ink_prelude` crate conveniently re-exports these types, eliminating this complexity. diff --git a/docs/basics/trait-definitions.md b/docs/basics/trait-definitions.md index a3edabc3bc..d08a9b8d35 100644 --- a/docs/basics/trait-definitions.md +++ b/docs/basics/trait-definitions.md @@ -95,7 +95,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/ink/attr.contract.html) macro can +structure so that the main [`#[ink::contract]`](https://docs.rs/ink/5.0.0/ink/attr.contract.html) macro can properly generate code for its implementations. # Example: Definition diff --git a/docs/basics/upgradeability.md b/docs/basics/upgradeability.md index f7f0f20529..2ecae8148c 100644 --- a/docs/basics/upgradeability.md +++ b/docs/basics/upgradeability.md @@ -255,6 +255,31 @@ As you can see, delegatee's code looks like a normal ink! Smart Contract with so - `addresses` mapping key is identical - Constructor does not have any logic, as the code is never instantiated. (It can be, but plays no effect on the execution) +### Delegate dependency locks + +In a delegator contract pattern, one contract delegates calls to another contract. +Thus it depends upon the contract code to which it delegates. Since on-chain contract code +can be deleted by anybody if there are no instances of the contract on the chain, this would +break the `delegator` contract. To prevent this, the `delegator` contract can utilize the +`lock_delegate_dependency` and `unlock_delegate_dependency` host functions. Calling +`lock_delegate_dependency` will prevent the code at the given hash from being deleted e.g. + +```rust +self.env().lock_delegate_dependency(&code_hash); +``` + +A subsequent call to `unlock_delegate_dependency` from within the `delegator` contract +instance releases the lock from that contract, allowing that code at the given hash to be +deleted if no other instances of the contract or delegate dependency locks exist. + +```rust +self.env().lock_delegate_dependency(&code_hash); +``` + +Note that these two methods can be called by anybody executing the contract, so it is the +responsibility of the contract developer to ensure correct access control. +You can take a look at our [`upgradeable-contracts/delegator`](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts#delegator) +example, which demonstrates the usage of these two functions. ## Note on the usage of wildcard selectors diff --git a/docs/basics/verification/contract-verification.md b/docs/basics/verification/contract-verification.md index f15bfe663e..83856bb625 100644 --- a/docs/basics/verification/contract-verification.md +++ b/docs/basics/verification/contract-verification.md @@ -20,14 +20,14 @@ process must recompile the contract in an identical host environment to which it was originally built. The simplest way to do this is using a Docker container. -Since ink! `4.0.0`, `cargo-contract` provides the necessary tools to produce +Since ink! 5.0, `cargo-contract` provides the necessary tools to produce a verifiable build and verify a binary against the reference contract. :::note -Contract verification tools are currently available in `cargo-contract` -version `4.0.0-alpha`. To install it, run +Contract verification tools are available from `cargo-contract` +version 4.0 on. To install it, run ``` -cargo install cargo-contract --locked --version 4.0.0-alpha +cargo install cargo-contract --locked --version ^4 ``` ::: @@ -117,5 +117,5 @@ of all contracts to be visible. Specify a relative manifest path to the root con `cargo contract build --verifiable --manifest-path ink-project-a/Cargo.toml` ::: -You can find a Dockefile and further documentation on image usage -in [the `cargo-contract` repository](https://github.com/paritytech/cargo-contract/tree/master/build-image) +You can find a Dockerfile and further documentation on image usage +in [the `cargo-contract` repository](https://github.com/paritytech/cargo-contract/tree/master/build-image) \ No newline at end of file diff --git a/docs/datastructures/custom.md b/docs/datastructures/custom.md index 1929a97f46..fca1fda520 100644 --- a/docs/datastructures/custom.md +++ b/docs/datastructures/custom.md @@ -14,22 +14,22 @@ 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/ink_storage_traits/trait.Storable.html) +[`Storable`](https://docs.rs/ink_storage_traits/5.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_traits/4.0.0/ink_storage_traits/trait.StorageLayout.html) +[`StorageLayout`](https://docs.rs/ink_storage_traits/5.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: ```rust /// A custom type that we can use in our contract storage -#[derive(scale::Decode, scale::Encode)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] #[cfg_attr( feature = "std", - derive(scale_info::TypeInfo, ink::storage::traits::StorageLayout) + derive(ink::storage::traits::StorageLayout) )] pub struct Inner { value: bool, @@ -42,7 +42,7 @@ pub struct ContractStorage { ``` Even better: there is a macro -[`#[ink::storage_item]`](https://docs.rs/ink_macro/4.0.0/ink_macro/attr.storage_item.html), +[`#[ink::storage_item]`](https://docs.rs/ink_macro/5.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: @@ -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/ink_storage_traits/trait.Packed.html) +non-[`Packed`](https://docs.rs/ink_storage_traits/5.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/ink_storage_traits/struct.ManualKey.html) +[`ManualKey`](https://docs.rs/ink_storage_traits/5.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 @@ -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/ink_storage/struct.Mapping.html). +[`Mapping`](https://docs.rs/ink_storage/5.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 diff --git a/docs/datastructures/mapping.md b/docs/datastructures/mapping.md index 8f74bed453..be7924704e 100644 --- a/docs/datastructures/mapping.md +++ b/docs/datastructures/mapping.md @@ -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/ink_storage/struct.Mapping.html). +In this section we demonstrate how to work with ink! [`Mapping`](https://docs.rs/ink_storage/5.0.0/ink_storage/struct.Mapping.html). Here is an example of a mapping from a user to a `Balance`: @@ -111,6 +111,75 @@ Furthermore, it follows that mapping values do not have a contiguous storage lay not possible to iterate over the contents of a map. +### Use fallible storage methods for dynamically sized values +Reading from or writing to a `Mapping` implies encoding or decoding +the according `Mapping` key and value. This happens transparently under the hood. +However, because the static buffer used to store the encoded data is of limited +size, it can fail and trap the contract. + +:::note + +The static buffer defaults to 16KB in size. + +::: + +This can be an issue for values with dynamically sized types. +It is recommended to use fallible storage methods (prefixed with `try_`) for +`Mapping`s containing dynamically sized values. + +Consider a `Mapping` with `String` values like so: + +```rust +#[ink(storage)] +pub struct MyContract { + on_chain_log: Mapping, + nonce: u64, +} +``` + +If the `String` overgrows the static buffer size, it will no longer fit into the mapping: + +```rust +#[ink(message)] +pub fn do_something(&mut self, data: String) { + let caller = self.env().caller(); + + let log_message = format!("{caller:?}: {data}"); + + // Panics if log_message overgrows the static buffer size! + self.on_chain_log.insert(&self.nonce, &log_message); + + self.nonce += 1; +} +``` + +Instead, consider using the fallible `try_insert` method to handle the situation: + +```rust +#[ink(message)] +pub fn do_something2(&mut self, data: String) { + let caller = self.env().caller(); + + let log_message = format!("{caller:?}: {data}"); + + // `try_insert` will not panic but return an error instead. + if self + .on_chain_log + .try_insert(&self.nonce, &log_message) + .is_err() + { + // We get the chance to handle this problem properly: + // Restrain the log message to a size guaranteed to fit. + let log_message = format!("{caller:?}: "); + self.on_chain_log.insert(&self.nonce, &log_message); + } + + self.nonce += 1; +} +``` + +We provide fallible `try_` versions for all storage operations on `Mapping`. + ### Updating values The attentive reader may have noticed that accessing mapping values via the `Mapping::get()` diff --git a/docs/datastructures/overview.md b/docs/datastructures/overview.md index b9817bf768..800e6ebf0e 100644 --- a/docs/datastructures/overview.md +++ b/docs/datastructures/overview.md @@ -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/ink_storage/struct.Mapping.html) -and [`Lazy`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Lazy.html). +[`Mapping`](https://docs.rs/ink_storage/5.0.0/ink_storage/struct.Mapping.html) +and [`Lazy`](https://docs.rs/ink_storage/5.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. @@ -29,4 +29,4 @@ it can be used to prevent the contract from eagerly loading large storage fields during each contract call. Conceivably, it may be desirable to change certain aspects on how your contract deals with its storage variables. You can find out more about this in the section about the ink! -[Storage Layout](https://use.ink/datastructures/storage-layout). +[Storage Layout](./storage-layout.md). diff --git a/docs/datastructures/storage-in-metadata.md b/docs/datastructures/storage-in-metadata.md index 3b46889e9b..b6e7c1b2ff 100644 --- a/docs/datastructures/storage-in-metadata.md +++ b/docs/datastructures/storage-in-metadata.md @@ -1,12 +1,12 @@ --- -title: Metadata Format +title: Storage Metadata Format slug: /datastructures/storage-in-metadata hide_title: true --- -# Metadata Format +# Storage Metadata Format The storage layout of a contract is reflected inside the metadata. It allows third-party tooling to work with contract storage and can also help to better understand the storage @@ -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/ink_storage_traits/trait.Packed.html) +[`Packed`](https://docs.rs/ink_storage_traits/5.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. diff --git a/docs/datastructures/storage-layout.md b/docs/datastructures/storage-layout.md index cca8d29194..9aae3e0ed7 100644 --- a/docs/datastructures/storage-layout.md +++ b/docs/datastructures/storage-layout.md @@ -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/ink_storage_traits/trait.Packed.html). +[`Packed`](https://docs.rs/ink_storage_traits/5.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. @@ -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/ink_storage_traits/struct.AutoKey.html) +[`AutoKey`](https://docs.rs/ink_storage_traits/5.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/ink_storage_traits/struct.ManualKey.html) +[`ManualKey`](https://docs.rs/ink_storage_traits/5.0.0/ink_storage_traits/struct.ManualKey.html) primitive allows manual control over the storage key of a field like so: ```rust diff --git a/versioned_docs/version-5.x/datastructures/storagevec.md b/docs/datastructures/storagevec.md similarity index 93% rename from versioned_docs/version-5.x/datastructures/storagevec.md rename to docs/datastructures/storagevec.md index 20fd449754..c21d2f68a8 100644 --- a/versioned_docs/version-5.x/datastructures/storagevec.md +++ b/docs/datastructures/storagevec.md @@ -134,9 +134,9 @@ element is calculated as follows: `StorageVec` is a `Lazy` type similar to `Mapping`. Hence, the same considerations apply to `StorageVec` too: -- [Storage loading behavior](https://use.ink/datastructures/mapping#storage-loading-behavior) -- [Use fallible storage methods for dynamically sized values](https://use.ink/datastructures/mapping#use-fallible-storage-methods-for-dynamically-sized-values) -- [Updating values](https://use.ink/datastructures/mapping#updating-values) +- [Storage loading behavior](../datastructures/mapping.md#storage-loading-behavior) +- [Use fallible storage methods for dynamically sized values](../datastructures/mapping.md#use-fallible-storage-methods-for-dynamically-sized-values) +- [Updating values](../datastructures/mapping.md#updating-values) ## Rust Docs diff --git a/docs/examples/contracts.md b/docs/examples/contracts.md index e8447a2ada..f78a982b4d 100644 --- a/docs/examples/contracts.md +++ b/docs/examples/contracts.md @@ -1,8 +1,13 @@ --- -title: Smart Contracts +title: Smart Contract Examples slug: /examples/smart-contracts +hide_title: true --- + + +# Smart Contract Examples + We have a repository `ink-examples`, in which you find a number of contracts written in ink!. Some of the most interesting ones: diff --git a/docs/examples/dapps.md b/docs/examples/dapps.md index ef9fd40746..c818f01dcf 100644 --- a/docs/examples/dapps.md +++ b/docs/examples/dapps.md @@ -1,12 +1,12 @@ --- -title: DApps +title: dApps slug: /examples/dapps hide_title: true --- - + -# DApps +# dApps We'll point to a couple full-stack dApp examples here. These can serve as inspiration for how to create a frontend for your @@ -14,8 +14,11 @@ smart contract. Three popular libraries for building frontends are: -- [`polkadot-js/api`](https://github.com/polkadot-js/api) a low-level TypeScript API. -- [useInkathon](https://github.com/scio-labs/use-inkathon) a React hooks library. +- [`@polkadot/api`](https://github.com/polkadot-js/api): a general purpose low-level TypeScript API for substrate. + +- [`@polkadot/api-contract`](https://polkadot.js.org/docs/api-contract): a `pallet-contract` specific TypeScript API. + +- [useInkathon](https://github.com/scio-labs/use-inkathon): a React hooks library for interacting with Wasm contracts and Substrate. ## INK!athon @@ -34,4 +37,4 @@ The entire source code (contract + frontend) is located here: You can view an online demo of the dApp here: [https://tiny.ink](https://tiny.ink). To create new short links you need `ROC` tokens from our testnet. -See [here](../testnet/overview.md) for how to get those. +See [here](../testing/overview.md) for how to get those. diff --git a/docs/faq/faq.md b/docs/faq/faq.md index f8ed8321d5..f18dd4c336 100644 --- a/docs/faq/faq.md +++ b/docs/faq/faq.md @@ -92,8 +92,10 @@ See the [Chain Extensions](../macros-attributes/chain-extension.md) section for ### 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/ink_macro/attr.contract.html#header-arguments) -for the contract macro. It allows you to specify your environment a la +Please see [this section](../macros-attributes/contract.md#env-impl-environment) in our documentation. + +Detailed documentation is found in [the Rust docs](https://docs.rs/ink_macro/5.0.0/ink_macro/attr.contract.html#header-arguments) +for the `#[ink(contract)]` macro. It allows you to specify your environment a la `#[ink::contract(env = MyEnvironment)]`. ### What does the `#![cfg_attr(not(feature = "std"), no_std)]` at the beginning of each contract mean? @@ -133,7 +135,7 @@ The contract storage is built on top of the runtime storage, and access is consi ### How do I print something to the console from the runtime? -Please see our page on [Contract Debugging](../basics/debugging.md). +Please see our page on [Contract Debugging](../testing/debugging.md). ### Why is Rust's standard library (stdlib) not available in ink!? @@ -169,15 +171,15 @@ Rust's standard library consists of three different layers: A number of crypto hashes are built into the [pallet-contracts](../intro/how-it-works.md) 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/ink_env/hash/trait.CryptoHash.html). +can view the complete list [here](https://docs.rs/ink_env/5.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.md) 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/ink_env/fn.hash_bytes.html) -* [`self.env().hash_encoded()`](https://docs.rs/ink_env/4.0.0/ink_env/fn.hash_encoded.html) +* [`self.env().hash_bytes()`](https://docs.rs/ink_env/5.0.0/ink_env/fn.hash_bytes.html) +* [`self.env().hash_encoded()`](https://docs.rs/ink_env/5.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? @@ -228,7 +230,7 @@ If you don't find the issue you can also ask for help in our public [Discord](https://discord.gg/j2DKRRbSJr) channel. -### What are the `scale::Encode` and `scale::Decode` traits? +### What are the `Encode`, `Decode` and `TypeInfo` arguments in `#[ink::scale_derive(Encode, Decode, TypeInfo)]` ? Substrate-based blockchains use the [SCALE codec](https://github.com/paritytech/parity-scale-codec) to encode data. @@ -237,6 +239,9 @@ be SCALE-encodable ‒ i.e. it needs to implement either `scale::Encode`, `scale::Decode`, or both. This affects e.g. data you want to return to a caller, data that you want to take as input, or data you want to store on-chain. +ink! re-exports these traits and provides a useful macro `#[ink::scale_derive(Encode, Decode, TypeInfo)]` that allows to derive them +in a concise way. + A common error you might get when a necessary SCALE trait is not implemented for a data structure could be along the lines of `the trait "WrapperTypeEncode" is not implemented for "Foo"`. @@ -259,12 +264,15 @@ to a caller or when it is persisted to the contracts storage. * `Decode` is used for the inverse, e.g. when reading from storage or taking an input from a user (or another contract). +* `TypeInfo` is used to encode the information about the type that is +often used for the generation of metadata. + It's possible to derive those traits and oftentimes the simplest way is to just derive the missing trait for the object for which its implementation -is missing: +is missing using the ink! macro: ```rust -#[derive(scale::Encode, scale::Decode)] +#[ink::scale_derive(Encode, Decode)] struct MyCustomDataStructure { … } ``` @@ -279,4 +287,39 @@ and you should only persist items which you need to derive state transitions in your contract. If you still, for some reason, need to use `String`, then you should use -the `String` [from the ink! prelude](https://docs.rs/ink_prelude/latest/ink_prelude/string/struct.String.html). +the `String` [from the ink! prelude](https://docs.rs/ink_prelude/5.0.0/ink_prelude/string/struct.String.html). + +

Getting a warning in cargo-contract about type compatibility?

+ +ink! and Substrate both support the possibility of deciding to deviate +from the default types for `Balance`, `BlockNumber`, etc. +These types are called environment types. + +If a chain decides on custom environment types, contract authors need +to specify these types that deviate from the ink! default environment in their +contracts. Otherwise, undefined behavior can occur when uploading a contract +with deviating types to a chain. + +Custom environment types can be specified in ink! via the `#[contract(env = MyCustomEnvironment)]` +attribute. You can read more are about this [here](../macros-attributes/contract.md#env-impl-environment). + +When using `cargo-contract` to interact with a chain you might get a warning along those lines: + +``` +Warning: This chain does not yet support checking for compatibility of your contract types. +``` + +This warning appears when the chain that you are targeting (via the `--url` cli flag) +does not contain a version of `pallet-contracts` that does support type comparison. +Type comparison is a feature that we introduced, it means we check that the environmental +types of your contract are equivalent to the environmental types of the chain that you are +targeting. +It's a safety feature to make sure that you are not accidentally deploying a contract with +e.g. `type Balance = u128` to a chain with a different `Balance` type. + +The `cargo-contract` warning means this check for compatible types cannot be performed. +This check is only available on chains from `polkadot-1.2.0` on, specifically from +[this commit](https://github.com/paritytech/polkadot-sdk/commit/d8a74901462ffb49345af6db7c5a7a6e2b3c92ed). + +If a chain indeed requires that contract developers have to use custom environment types, +this should be communicated prominently by them. \ No newline at end of file diff --git a/docs/faq/migrating-from-ink-3-to-4.md b/docs/faq/migrating-from-ink-3-to-4.md index 4f896df7c5..7644a066a3 100644 --- a/docs/faq/migrating-from-ink-3-to-4.md +++ b/docs/faq/migrating-from-ink-3-to-4.md @@ -284,8 +284,8 @@ After: The storage layout under the `storage` key changed for v4. If you have an application that is using it consider reading the updated documentation: -- [General storage documentation](../datastructures/overview.md) -- [Storage metadata format](../datastructures/storage-in-metadata.md) +- [General storage documentation](../../versioned_docs/version-4.x/datastructures/overview.md) +- [Storage metadata format](../../versioned_docs/version-4.x/datastructures/storage-in-metadata.md) ## Removal of `AccountId` `Default` implementation In [#1255](https://github.com/paritytech/ink/pull/1255) we removed the `Default` trait diff --git a/versioned_docs/version-5.x/faq/migrating-from-ink-4-to-5.md b/docs/faq/migrating-from-ink-4-to-5.md similarity index 96% rename from versioned_docs/version-5.x/faq/migrating-from-ink-4-to-5.md rename to docs/faq/migrating-from-ink-4-to-5.md index 74b9a76ecd..0e9c9c5039 100644 --- a/versioned_docs/version-5.x/faq/migrating-from-ink-4-to-5.md +++ b/docs/faq/migrating-from-ink-4-to-5.md @@ -179,7 +179,7 @@ pub enum Error {} pub enum Error {} ``` -The documentation of the macro can be found [here](https://docs.rs/ink/5.0.0-rc/ink/attr.scale_derive.html). +The documentation of the macro can be found [here](https://docs.rs/ink/5.0.0/ink/attr.scale_derive.html). ### Wildcard selectors: only one other message is allowed in the contract besides the wildcard selector @@ -328,8 +328,8 @@ limit (i.e. 5%, 10%). The method `.extra_gas_portion(margin: u64)` method is part of the builder API: -* [`ink_e2e::InstantiateBuilder::extra_gas_portion`](https://docs.rs/ink_e2e/5.0.0-rc/ink_e2e/struct.InstantiateBuilder.html#method.extra_gas_portion) -* [`ink_e2e::CallBuilder::extra_gas_portion`](https://docs.rs/ink_e2e/5.0.0-rc/ink_e2e/struct.CallBuilder.html#method.extra_gas_portion) +* [`ink_e2e::InstantiateBuilder::extra_gas_portion`](https://docs.rs/ink_e2e/5.0.0/ink_e2e/struct.InstantiateBuilder.html#method.extra_gas_portion) +* [`ink_e2e::CallBuilder::extra_gas_portion`](https://docs.rs/ink_e2e/5.0.0/ink_e2e/struct.CallBuilder.html#method.extra_gas_portion) #### Improved `call()` API @@ -356,7 +356,7 @@ The test will detect the contract and build it as part of the test. #### In [#2076](https://github.com/paritytech/ink/pull/2076), we've added a new -[`remove_code`](https://docs.rs/ink_e2e/5.0.0-rc/ink_e2e/trait.ContractsBackend.html#method.remove_code) +[`remove_code`](https://docs.rs/ink_e2e/5.0.0/ink_e2e/trait.ContractsBackend.html#method.remove_code) function to the E2E API: ```rust @@ -386,7 +386,7 @@ access it or write to it. You can find verbatim documentation on `StorageVec` [here](../datastructures/storagevec.md). 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). +The Rust docs can be found [here](https://docs.rs/ink/5.0.0/ink/storage/struct.StorageVec.html). ### Fallible methods for `Lazy`, `Mapping`, `StorageVec` @@ -398,9 +398,9 @@ For `StorageVec::{peek, get, set, pop, push}` we added `try_*` methods in 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. +* [`StorageVec`](https://docs.rs/ink/5.0.0/ink/storage/struct.StorageVec.html) +* [`Lazy`](https://docs.rs/ink/5.0.0/ink/storage/struct.Lazy.html) +* [`Mapping`](https://docs.rs/ink/5.0.0/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) @@ -408,7 +408,7 @@ 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). +[`non_fallible_api`](../linter/rules/non_fallible_api.md). ### Chain Extension API changed + Support for multiple chain extensions @@ -437,7 +437,7 @@ The argument type changed from `u32` to `u16`: The top level macro `#[ink::chain_extension]` now _requires_ an `(extension = N: u16)` argument to support multiple chain extensions. If you are using only one extension, the ID can be any `u16` number, -otherwise please consult the [`#[ink::chain_extension]` macro documentation](https://use.ink/5.x/macros-attributes/chain-extension) +otherwise please consult the [`#[ink::chain_extension]` macro documentation](../macros-attributes/chain-extension.md) ```diff -#[ink::chain_extension] +#[ink::chain_extension(extension = 1)] @@ -466,7 +466,7 @@ The previous v1 `call` and `instantiate` functions only provided a single `gas_l which was used as the value for `ref_time_limit`. You can still use these `v1` versions. For `call` on a call builder obtained through -[`build_call`](https://docs.rs/ink_env/5.0.0-rc.2/ink_env/call/fn.build_call.html): +[`build_call`](https://docs.rs/ink_env/5.0.0/ink_env/call/fn.build_call.html): ``` call_builder @@ -475,7 +475,7 @@ call_builder .invoke(); ``` -For `instantiate` on [`build_create`](https://docs.rs/ink_env/5.0.0-rc.2/ink_env/call/fn.build_create.html): +For `instantiate` on [`build_create`](https://docs.rs/ink_env/5.0.0/ink_env/call/fn.build_create.html): The new `v2` parameters can be set like so: @@ -680,7 +680,7 @@ the guarantee that it cannot be deleted. We've updated the [`upgradeable-contracts/delegator`](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts#delegator) example to demonstrate these new calls. -For that purpose we've also added a [`remove_code`](https://docs.rs/ink_e2e/5.0.0-rc/ink_e2e/trait.ContractsBackend.html#method.remove_code) +For that purpose we've also added a [`remove_code`](https://docs.rs/ink_e2e/5.0.0/ink_e2e/trait.ContractsBackend.html#method.remove_code) function to the E2E API. These two functions are only available from `polkadot-1.8.0` on. diff --git a/versioned_docs/version-5.x/funding-programs/overview.md b/docs/funding-programs/overview.md similarity index 100% rename from versioned_docs/version-5.x/funding-programs/overview.md rename to docs/funding-programs/overview.md diff --git a/docs/getting-started/compiling.md b/docs/getting-started/compiling.md index aaf52c3d5e..48e396169a 100644 --- a/docs/getting-started/compiling.md +++ b/docs/getting-started/compiling.md @@ -14,10 +14,11 @@ Run the following command in your `flipper` directory to compile your smart cont cargo contract build ``` -This command will build the following for your contract: a Wasm binary, a metadata file (which contains the -contract's ABI) and a `.contract` file which bundles both. This `.contract` file can be used to -deploy your contract to a chain. If all goes well, you should see a `target` folder which -contains these files: +This command will build the following for your contract: +a Wasm binary, a metadata file (which contains the +contract's ABI) and a `.contract` file which bundles both. + +If all goes well, you should see a `target` folder which contains these files: ``` target @@ -26,6 +27,25 @@ target └─ flipper.wasm └─ flipper.json ``` +You can think of it this way: the raw Wasm binary contains just +the bytecode of your contract. Without further information it's +not possible to know what this bytecode refers to. For example, +which functions can be called in there and what their arguments +are. This additional information that describes what the raw Wasm +is about is called metadata ‒ data that describes other data. + +

+ +

+ +The purpose of each file is: + +* `flipper.wasm`: This is the raw contract bytecode that will be deployed on-chain. +* `flipper.json`: The isolated metadata, which is not stored on-chain. +It's big and would take up too much space and costs. +This file is used by e.g. a dApp user interface to know how to communicate with the on-chain contract. +* `flipper.contract`: Combines both the contract's bytecode and the metadata. This file +is used when you are using a Developer UI like [Contracts UI](https://contracts-ui.substrate.io/). Let's take a look at the structure of the `flipper.json`: @@ -57,6 +77,20 @@ If you look closely at the constructors and messages, you will also notice a `se contains a 4-byte hash of the function name and is used to route your contract calls to the correct functions. +You can also open up the `flipper.contract` file in any text editor. You'll notice that it's +nearly the same as the `flipper.json`. The only different is that the `.contract` file contains +an additional field with the hex-encoded Wasm bytecode of your contract: + +``` +{ + "source": { + … + "wasm": "0x006173…", + }, + … +} +``` + In the next section we will start a [Substrate Smart Contracts node](https://github.com/paritytech/substrate-contracts-node) and configure the [Contracts UI](https://github.com/paritytech/contracts-ui) to interact with it. diff --git a/docs/getting-started/running.md b/docs/getting-started/running.md index db967e2a41..202f9d7b0d 100644 --- a/docs/getting-started/running.md +++ b/docs/getting-started/running.md @@ -12,7 +12,7 @@ The [`substrate-contracts-node`](https://github.com/paritytech/substrate-contrac is a simple Substrate blockchain which is configured to include the `contracts` module. It's a comfortable option if you want to get a quickstart. -[After successfully installing `substrate-contracts-node`](../getting-started/setup.md#installing-substrate-contracts-node), +[After successfully installing `substrate-contracts-node`](./setup.md#installing-substrate-contracts-node), you can start a local development chain by running: ```bash diff --git a/docs/intro/how-it-works.md b/docs/intro/how-it-works.md index 444fbae69f..ed41e4ec77 100644 --- a/docs/intro/how-it-works.md +++ b/docs/intro/how-it-works.md @@ -55,7 +55,7 @@ Those chains typically take the off-the-shelf `pallet-contracts` and create some ### Use Case 2: Smart Contracts as "second-class citizens" There is another not so obvious use case for `pallet-contracts`: smart contracts as “second-class citizens” on an existing chain. By this we mean that the central value proposition of the chain has nothing to do with smart contracts, but it still includes them as an add-on. -We provide an API (called [chain extensions](https://use.ink/macros-attributes/chain-extension)) with which a parachain can expose certain parts of its business logic to smart contract developers. Through this, smart contract developers can utilize the business logic primitives of the chain to build a new application on top of it. Think for example of a decentralized exchange blockchain. This chain would in its simplest form have an order book to place bids and asks ‒ there is no need for taking untrusted, Turing-complete, programs from the outside. The parachain could decide to expose the order book into smart contracts though, giving external developers the option of building new applications that utilize the order book. For example, to upload trading algorithms as smart contracts to the chain. +We provide an API (called [chain extensions](../macros-attributes/chain-extension.md)) with which a parachain can expose certain parts of its business logic to smart contract developers. Through this, smart contract developers can utilize the business logic primitives of the chain to build a new application on top of it. Think for example of a decentralized exchange blockchain. This chain would in its simplest form have an order book to place bids and asks ‒ there is no need for taking untrusted, Turing-complete, programs from the outside. The parachain could decide to expose the order book into smart contracts though, giving external developers the option of building new applications that utilize the order book. For example, to upload trading algorithms as smart contracts to the chain. Smart contracts here are an opportunity to up the user engagement and drive usage of the chain's native token. And the billing for utilizing the chain comes already built-in with the pallet ‒ users have to pay gas fees for the execution of their smart contract. diff --git a/docs/intro/ink-vs-cosmwasm.md b/docs/intro/ink-vs-cosmwasm.md index aa0892b9f2..95a4b76e72 100644 --- a/docs/intro/ink-vs-cosmwasm.md +++ b/docs/intro/ink-vs-cosmwasm.md @@ -59,7 +59,7 @@ While CosmWasm unit tests have different modules for each of the three main entr functions, ink! allows for a more generalised approach, where the `#[ink(test)]` macro is used for each unit test. -You can read more about ink! unit tests [here](https://use.ink/basics/contract-testing#unit-tests). +You can read more about ink! unit tests [here](../testing/off-chain.md). ## Compiler diff --git a/docs/intro/ink-vs-solidity.md b/docs/intro/ink-vs-solidity.md index 473c41455b..c3ccf44f56 100644 --- a/docs/intro/ink-vs-solidity.md +++ b/docs/intro/ink-vs-solidity.md @@ -29,47 +29,10 @@ The following table gives a brief comparison of features between ink! and Solidi -## Solidity to ink! Guide - -### Table of Contents - -- [Solidity to ink! Guide](#solidity-to-ink-guide) -- [Table of Contents](#table-of-contents) -- [Converting a Solidity contract to ink!](#converting-a-solidity-contract-to-ink) - - [1. Generate a new ink! contract](#1-generate-a-new-ink-contract) - - [2. Build the contract](#2-build-the-contract) - - [3. Convert Solidity class fields to Rust struct](#3-convert-solidity-class-fields-to-rust-struct) - - [4. Convert each function](#4-convert-each-function) -- [Best Practices + Tips](#best-practices--tips) -- [Syntax Equivalencies](#syntax-equivalencies) - - [`public function`](#public-function) - - [`mapping declaration`](#mapping-declaration) - - [`mapping usage`](#mapping-usage) - - [`struct`](#struct) - - [`assertions / requires`](#assertions--requires) - - [`timestamp`](#timestamp) - - [`contract caller`](#contract-caller) - - [`contract's address`](#contracts-address) - - [`bytes`](#bytes) - - [`uint256`](#uint256) - - [`payable`](#payable) - - [`received deposit / payment`](#received-deposit--payment) - - [`contract balance`](#contract-balance) - - [`transfer tokens from contract`](#transfer-tokens-from-contract) - - [`events & indexed`](#events--indexed) - - [`errors and returning`](#errors-and-returning) - - [`throw`](#throw) - - [`assert`](#assert) - - [`require and revert`](#require-and-revert) - - [`nested mappings + custom / advanced structures`](#nested-mappings--custom--advanced-structures) - - [`cross-contract calling`](#cross-contract-calling) - - [`submit generic transaction / dynamic cross-contract calling`](#submit-generic-transaction--dynamic-cross-contract-calling) -- [Limitations of ink! v3](#limitations-of-ink-v3) -- [Troubleshooting Errors](#troubleshooting-errors) -- [unit testing (off-chain)](#unit-testing-off-chain) - ## Converting a Solidity Contract to ink! +In the following, we'll explain how to convert a Solidity contract to ink!. + ### 1. Generate a new ink! contract Run the following command to generate the skeleton for an ink! contract. @@ -223,8 +186,8 @@ mod example { data: u128, } - #[derive(Debug, scale::Encode, scale::Decode, PartialEq, Eq)] - #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))] + #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive(Debug, PartialEq, Eq)] pub enum Error { DataShouldNotBeZero, } @@ -323,7 +286,7 @@ pub struct ContractName { } ``` -When using a map in ink!, `ink_lang::utils::initialize_contract` must be used in the constructor. See [here](https://use.ink/datastructures/mapping) for more details. +When using a map in ink!, `ink_lang::utils::initialize_contract` must be used in the constructor. See [here](../datastructures/mapping.md) for more details. ### `mapping usage` @@ -548,8 +511,8 @@ function myFunction(bool returnError) public pure { ```rust // ink! -#[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)] -#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))] +#[derive(Debug, PartialEq, Eq)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum Error { /// Provide a detailed comment on the error MyError, @@ -639,15 +602,8 @@ mod dao { storage::Mapping, }; - #[derive( - scale::Encode, - scale::Decode, - Debug, - )] - #[cfg_attr( - feature = "std", - derive(scale_info::TypeInfo) - )] + #[derive(Debug)] + #[ink::scale_derive(Encode, Decode, TypeInfo)] pub struct Proposal { voted_yes: BTreeMap, } @@ -699,7 +655,7 @@ mod dao { ### `cross-contract calling` -In ink!, to do [cross-contract calling](https://use.ink/basics/cross-contract-calling), the contract will need to be added to the project. Ensure the contract is properly exporting its Structs. See the `erc20` contract example: +In ink!, to do [cross-contract calling](../basics/cross-contract-calling.md), the contract will need to be added to the project. Ensure the contract is properly exporting its Structs. See the `erc20` contract example: ```rust #![cfg_attr(not(feature = "std"), no_std, no_main)] @@ -732,7 +688,7 @@ crate-type = [ ink-as-dependency = [] ``` -`ink-as-dependency` "tells the ink! code generator to always or never compile the smart contract as if it was used as a dependency of another ink! smart contract" ([source](https://use.ink/basics/cross-contract-calling)). +`ink-as-dependency` "tells the ink! code generator to always or never compile the smart contract as if it was used as a dependency of another ink! smart contract" ([source](../basics/cross-contract-calling.md)). Then, In the main contract's Cargo.toml, import the contract that will be cross-called. @@ -762,7 +718,7 @@ use erc20::Erc20Ref; There are two methods to setup the other contract. 1. Instantiate the cross-called-contract in the main contract's constructor. - See [here](https://use.ink/basics/cross-contract-calling/) for a tutorial, and [here](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts/delegator) for an example. + See [here](../basics/cross-contract-calling.md) for a tutorial, and [here](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts/delegator) for an example. 2. Or, add the `AccountId` of an already deployed contract. Here is an example constructor to set this up: @@ -834,6 +790,7 @@ fn invoke_transaction( .call_type( Call::new() .callee(callee) // contract to call + .call_v1() .gas_limit(*gas_limit) .transferred_value(transfer_amount), // value to transfer with call ) diff --git a/docs/intro/intro.mdx b/docs/intro/intro.mdx index deea0d7994..b936acefee 100644 --- a/docs/intro/intro.mdx +++ b/docs/intro/intro.mdx @@ -8,7 +8,7 @@ hide_table_of_contents: true
- +
@@ -24,6 +24,9 @@ hide_table_of_contents: true
+
+ +
@@ -37,7 +40,7 @@ hide_table_of_contents: true
ink! is a programming language for smart contracts.
- You can use it with blockchains built with the Polkadot SDK. + You can use it with blockchains built on Substrate.
@@ -64,55 +67,57 @@ hide_table_of_contents: true

## Our Pitch -
-
- -

Inherent safety-guarantees with the Rust programming language.

-
-
- -

Ability to use all the normal Rust tooling ‒ clippy, crates.io, IDE’s, etc.

-
-
- -

Interoperability with Solidity contracts.

-
-
+
+
+
+ +

Inherent safety-guarantees with the Rust programming language.

+
+
+ +

Ability to use all the normal Rust tooling ‒ clippy, crates.io, IDE’s, etc.

+
+
+ +

Interoperability with Solidity contracts.

+
+
-
-  -
+
+   +
-
-
- -

Clear migration path for graduating to a parachain.

-
-
- -

Established industry standard for the compiler target.

-
-
- -

Native to Polkadot. Complements your Substrate parachain perfectly.

-
+
+
+ +

Clear migration path for graduating to a parachain.

+
+
+ +

Established industry standard for the compiler target.

+
+
+ +

Native to Polkadot. Complements your Substrate parachain perfectly.

+
+
## Where can I deploy ink! contracts? -
+

@@ -154,6 +159,19 @@ hide_table_of_contents: true
+
+
+ + + +
+
+ + + +
+
+

@@ -196,14 +214,6 @@ hide_table_of_contents: true
-
-
- - - -
-
-

@@ -308,3 +318,4 @@ hide_table_of_contents: true +You can read more on standards [here](../standards/overview.md). diff --git a/docs/intro/migrate-to-parachain.md b/docs/intro/migrate-to-parachain.md index 0059aafe7c..2dca974fc2 100644 --- a/docs/intro/migrate-to-parachain.md +++ b/docs/intro/migrate-to-parachain.md @@ -23,7 +23,7 @@ Much of the difficulty in launching a parachain comes in configuring a node impl ## Utilizing existing FRAME pallets -There is a rich library of FRAME pallets, which may provide a drop in replacement for some (or all) of your smart contract functionality. For example, for a [PSP22](https://use.ink/getting-started/use-openbrush/) (similar to ERC20) fungible token contract, this could be replaced either by the native Parachain token itself via `pallet_balances` or by an asset on `pallet_assets`. Governance functions could be replaced by e.g. `pallet_democracy`, and so on. See [`polkadot-sdk`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) for a range of pre-built pallets which can be used to handle some common functions. +There is a rich library of FRAME pallets, which may provide a drop in replacement for some (or all) of your smart contract functionality. For example, for a [PSP22](../standards/overview.md) (similar to ERC20) fungible token contract, this could be replaced either by the native Parachain token itself via `pallet_balances` or by an asset on `pallet_assets`. Governance functions could be replaced by e.g. `pallet_democracy`, and so on. See [`polkadot-sdk`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) for a range of pre-built pallets which can be used to handle some common functions. ## Similarities and differences between `ink!` and `FRAME` @@ -67,7 +67,7 @@ pub struct Register { } ``` -Each of these structs annotated with `#[ink(event)]` can be translated to a variant in the pallet `Error` enum annotated with `#[pallet::error]`. Any of the `ink!` environment type aliases (both `Hash` and `AccountId` in the above example) must be translated to their equivalent associated type on the `Config` trait e.g. `AccountId` → `T::AccountId`. Also the `#[ink(topic)]` annotations must be removed: topics must be calculated manually when the event is emitted, and will be covered later. Remove the `#[pallet::generate_deposit(pub(super) fn deposit_event)]` and the final `Event` type will look like: +Each of these structs annotated with `#[ink(event)]` can be translated to a variant in the pallet `Error` enum annotated with `#[pallet::error]`. Any of the `ink!` environment type aliases (both `Hash` and `AccountId` in the above example) must be translated to their equivalent associated type on the `Config` trait e.g. `AccountId` -> `T::AccountId`. Also the `#[ink(topic)]` annotations must be removed: topics must be calculated manually when the event is emitted, and will be covered later. Remove the `#[pallet::generate_deposit(pub(super) fn deposit_event)]` and the final `Event` type will look like: ```rust= diff --git a/docs/intro/polkadot.md b/docs/intro/polkadot.md index 7f39ee5afa..280720133f 100644 --- a/docs/intro/polkadot.md +++ b/docs/intro/polkadot.md @@ -23,4 +23,5 @@ _To restate this important distinction: developing a parachain runtime is differ The trade-off is that with a parachain one has the freedom to decide on (nearly) all the rules that make up the parachain. With a smart contract one is constrained by what the chain allows and the safety pillars that necessarily have to be in place. A smart contract can never be as fast as a native pallet built in the parachain runtime ‒ there is too much logic in between. A smart contract on the other hand has less friction for developing and deploying it. Developers don't have to take care of governance, crypto-economics, etc. One just needs a few tokens and can go on its merry way deploying a smart contract. It's as simple as that. -![](/img/smart-contract-vs-parachain.png) \ No newline at end of file +![](/img/smart-contract-vs-parachain.png) + diff --git a/versioned_docs/version-5.x/intro/where-to-deploy.md b/docs/intro/where-to-deploy.md similarity index 100% rename from versioned_docs/version-5.x/intro/where-to-deploy.md rename to docs/intro/where-to-deploy.md diff --git a/versioned_docs/version-5.x/linter/overview.md b/docs/linter/overview.md similarity index 100% rename from versioned_docs/version-5.x/linter/overview.md rename to docs/linter/overview.md diff --git a/versioned_docs/version-5.x/linter/rules/no_main.md b/docs/linter/rules/no_main.md similarity index 100% rename from versioned_docs/version-5.x/linter/rules/no_main.md rename to docs/linter/rules/no_main.md diff --git a/versioned_docs/version-5.x/linter/rules/non_fallible_api.md b/docs/linter/rules/non_fallible_api.md similarity index 100% rename from versioned_docs/version-5.x/linter/rules/non_fallible_api.md rename to docs/linter/rules/non_fallible_api.md diff --git a/versioned_docs/version-5.x/linter/rules/primitive_topic.md b/docs/linter/rules/primitive_topic.md similarity index 93% rename from versioned_docs/version-5.x/linter/rules/primitive_topic.md rename to docs/linter/rules/primitive_topic.md index 3e0ca0b09a..03acd15b3a 100644 --- a/versioned_docs/version-5.x/linter/rules/primitive_topic.md +++ b/docs/linter/rules/primitive_topic.md @@ -6,7 +6,7 @@ description: primitive_topic lint documentation # primitive_topic ## What it does Checks for ink! contracts that use the -[`#[ink(topic)]`](https://use.ink/macros-attributes/topic) annotation with primitive number +[`#[ink(topic)]`](../../macros-attributes/topic.md) annotation with primitive number types. Topics are discrete events for which it makes sense to filter. Typical examples of fields that should be filtered are `AccountId`, `bool` or `enum` variants. diff --git a/versioned_docs/version-5.x/linter/rules/storage_never_freed.md b/docs/linter/rules/storage_never_freed.md similarity index 100% rename from versioned_docs/version-5.x/linter/rules/storage_never_freed.md rename to docs/linter/rules/storage_never_freed.md diff --git a/versioned_docs/version-5.x/linter/rules/strict_balance_equality.md b/docs/linter/rules/strict_balance_equality.md similarity index 100% rename from versioned_docs/version-5.x/linter/rules/strict_balance_equality.md rename to docs/linter/rules/strict_balance_equality.md diff --git a/docs/macros-attributes/anonymous.md b/docs/macros-attributes/anonymous.md index 6074a20708..99467f177a 100644 --- a/docs/macros-attributes/anonymous.md +++ b/docs/macros-attributes/anonymous.md @@ -8,16 +8,16 @@ hide_title: true Applicable to ink! events. -Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. +Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as +topic upon emitting. Similar to anonymous events in Solidity. -Anonymous events have similar semantics as in Solidity in that their -event signature won't be included in their event topics serialization -to reduce event emitting overhead. This is especially useful for user -defined events. +Anonymous events have similar semantics as in Solidity in that their event signature won't be +included in their event topics serialization to reduce event emitting overhead. This is +especially useful for user defined events. -The signature of the event is by default one of the topics of the event, except -if you annotate the event with `#[ink(anonymous)]`. -The attribute implies that it is not possible to filter for specific anonymous events by name. +The signature of the event is by default one of the topics of the event, except if you annotate the +event with `#[ink(anonymous)]`. The attribute implies that it is not possible to filter for +specific anonymous events by the signature topic. ## Example @@ -29,4 +29,19 @@ pub struct MyEvent { field_1: i32, field_2: bool, } -``` \ No newline at end of file +``` + +The equivalent syntax for standalone `#[ink::event]` definitions (not defined inline in a +contract) is: + +```rust +#[ink::event(anonymous)] +pub struct MyEvent { + #[ink(topic)] + field_1: i32, + field_2: bool, +} +``` + + + diff --git a/docs/macros-attributes/chain-extension.md b/docs/macros-attributes/chain-extension.md index c4dcdd93d5..6c6f8a6cfa 100644 --- a/docs/macros-attributes/chain-extension.md +++ b/docs/macros-attributes/chain-extension.md @@ -7,7 +7,7 @@ hide_title: true In the default configuration of the `contracts-pallet` a smart contract can only interact with the runtime -via its well defined set of basic smart contract interface. This API already allows a whole variety of +via its well defined set of basic smart contract interface functions. This API already allows a whole variety of interaction between the `contracts-pallet` and the executed smart contract. For example it is possible to call and instantiate other smart contracts on the same chain, emit events, query context information or run built-in cryptographic hashing procedures. @@ -23,7 +23,7 @@ With chain extensions you can expose parts of your runtime logic to smart contract developers. :::note -The ink! repository contains [the `rand-extension` example](https://github.com/paritytech/ink-examples/tree/main/rand-extension). +The ink! examples repository contains [the `rand-extension` example](https://github.com/paritytech/ink-examples/tree/main/rand-extension). This is a complete example of a chain extension implemented in both ink! and Substrate. ::: @@ -49,14 +49,31 @@ ink! smart contracts using this chain extension simply depend on this crate and use its associated environment definition in order to make use of the methods provided by the chain extension. -## Attributes +## Macro Attributes + +The macro supports only one required argument: `extension = N: u16`. +The runtime may have several chain extensions at the same time. The `extension` +identifier points to the corresponding chain extension in the runtime. +The value should be the same as during the definition of the chain extension. +You can consult the +[chain extension module documentation](https://paritytech.github.io/polkadot-sdk/master/pallet_contracts/chain_extension/index.html) +if you are unsure how to find the chain extension code. +Otherwise, you should consult the target chain's documentation +for specifications of any chain extensions it exposes. + +:::note +If the chain extension is not used in a tuple in the runtime configuration, +`extension = N: u16` can take any `u16` number. +::: + +## Method Attributes There are two different attributes with which the chain extension methods can be flagged: | Attribute | Required | Default Value | Description | |:----------|:--------:|:--------------|:-----------:| -| `ink(extension = N: u32)` | Yes | - | Determines the unique function ID of the chain extension method. | +| `ink(function = N: u16)` | Yes | - | Determines the unique function ID within the chain extension. | | `ink(handle_status = flag: bool)` | Optional | `true` | Assumes that the returned status code of the chain extension method always indicates success and therefore always loads and decodes the output buffer of the call. | As with all ink! attributes multiple of them can either appear in a contiguous list: @@ -64,11 +81,11 @@ As with all ink! attributes multiple of them can either appear in a contiguous l ```rust type Access = i32; -#[ink::chain_extension] +#[ink::chain_extension(extension = 12)] pub trait MyChainExtension { type ErrorCode = i32; - #[ink(extension = 5, handle_status = false)] + #[ink(function = 5, handle_status = false)] fn key_access_for_account(key: &[u8], account: &[u8]) -> Access; } ``` @@ -78,11 +95,11 @@ pub trait MyChainExtension { ```rust type Access = i32; -#[ink::chain_extension] +#[ink::chain_extension(extension = 12)] pub trait MyChainExtension { type ErrorCode = i32; - #[ink(extension = 5)] + #[ink(function = 5)] #[ink(handle_status = false)] fn key_access_for_account(key: &[u8], account: &[u8]) -> Access; } @@ -154,7 +171,7 @@ from and to the runtime storage using access privileges: ```rust /// Custom chain extension to read to and write from the runtime. -#[ink::chain_extension] +#[ink::chain_extension(extension = 12)] pub trait RuntimeReadWrite { type ErrorCode = ReadWriteErrorCode; @@ -163,8 +180,9 @@ pub trait RuntimeReadWrite { /// # Note /// /// Actually returns a value of type `Result, Self::ErrorCode>`. - /// #[ink(extension = 1, returns_result = false)] - /// fn read(key: &[u8]) -> Vec; + #[ink(function = 1, returns_result = false)] + fn read(key: &[u8]) -> Vec; + /// /// Reads from runtime storage. /// @@ -180,7 +198,7 @@ pub trait RuntimeReadWrite { /// /// This requires `ReadWriteError` to implement `From` /// and may potentially return any `Self::ErrorCode` through its return value. - #[ink(extension = 2)] + #[ink(function = 2)] fn read_small(key: &[u8]) -> Result<(u32, [u8; 32]), ReadWriteError>; /// Writes into runtime storage. @@ -188,7 +206,7 @@ pub trait RuntimeReadWrite { /// # Note /// /// Actually returns a value of type `Result<(), Self::ErrorCode>`. - #[ink(extension = 3)] + #[ink(function = 3)] fn write(key: &[u8], value: &[u8]); /// Returns the access allowed for the key for the caller. @@ -196,7 +214,7 @@ pub trait RuntimeReadWrite { /// # Note /// /// Assumes to never fail the call and therefore always returns `Option`. - #[ink(extension = 4, handle_status = false)] + #[ink(function = 4, handle_status = false)] fn access(key: &[u8]) -> Option; /// Unlocks previously acquired permission to access key. @@ -209,18 +227,18 @@ pub trait RuntimeReadWrite { /// /// Assumes the call to never fail and therefore does _NOT_ require `UnlockAccessError` /// to implement `From` as in the `read_small` method above. - #[ink(extension = 5, handle_status = false)] + #[ink(function = 5, handle_status = false)] fn unlock_access(key: &[u8], access: Access) -> Result<(), UnlockAccessError>; } -#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum ReadWriteErrorCode { InvalidKey, CannotWriteToKey, CannotReadFromKey, } -#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum ReadWriteError { ErrorCode(ReadWriteErrorCode), BufferTooSmall { required_bytes: u32 }, @@ -238,7 +256,7 @@ impl From for ReadWriteError { } } -#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] pub struct UnlockAccessError { reason: String, } @@ -249,7 +267,7 @@ impl From for UnlockAccessError { } } -#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] +#[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum Access { ReadWrite, ReadOnly, @@ -367,29 +385,29 @@ mod read_writer { } /// Custom chain extension to read to and write from the runtime. - #[ink::chain_extension] + #[ink::chain_extension(extension = 12)] pub trait RuntimeReadWrite { type ErrorCode = ReadWriteErrorCode; - #[ink(extension = 1)] + #[ink(function = 1)] fn read(key: &[u8]) -> Vec; - #[ink(extension = 2)] + #[ink(function = 2)] fn read_small(key: &[u8]) -> Result<(u32, [u8; 32]), ReadWriteError>; - #[ink(extension = 3)] + #[ink(function = 3)] fn write(key: &[u8], value: &[u8]); - #[ink(extension = 4, handle_status = false)] + #[ink(function = 4, handle_status = false)] fn access(key: &[u8]) -> Option; - #[ink(extension = 5, handle_status = false)] + #[ink(function = 5, handle_status = false)] fn unlock_access(key: &[u8], access: Access) -> Result<(), UnlockAccessError>; } - #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] + #[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum ReadWriteErrorCode { InvalidKey, CannotWriteToKey, CannotReadFromKey, } - #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] + #[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum ReadWriteError { ErrorCode(ReadWriteErrorCode), BufferTooSmall { required_bytes: u32 }, @@ -405,7 +423,7 @@ mod read_writer { } } - #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] + #[ink::scale_derive(Encode, Decode, TypeInfo)] pub struct UnlockAccessError { reason: String, } @@ -414,7 +432,7 @@ mod read_writer { panic!("encountered unexpected invalid SCALE encoding") } } - #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] + #[ink::scale_derive(Encode, Decode, TypeInfo)] pub enum Access { ReadWrite, ReadOnly, @@ -447,6 +465,90 @@ mod read_writer { } ``` +## Using Multiple Chain Extensions + +It is possible to use multiple exposed chain extensions in the single environment of a smart contract. +The declaration procedure of the chain extension stays the same. + +Suppose we want to combine two chain extension called `Psp22Extension` and `FetchRandom`, ink! provides +a useful macro [`ink::combine_extensions!`](https://docs.rs/ink/5.0.0/ink/macro.combine_extensions.html) that allows to construct the structure combining +the aforementioned chain extensions like so: +```rust +ink::combine_extensions! { + /// This extension combines the `FetchRandom` and `Psp22Extension` extensions. + /// It is possible to combine any number of extensions in this way. + /// + /// This structure is an instance that is returned by the `self.env().extension()` call. + pub struct CombinedChainExtension { + /// The instance of the `Psp22Extension` chain extension. + /// + /// It provides you access to `PSP22` functionality. + pub psp22: Psp22Extension, + /// The instance of the `FetchRandom` chain extension. + /// + /// It provides you access to randomness functionality. + pub rand: FetchRandom, + } +} +``` + +The combined structure is called `CombinedChainExtension`, and we can refer to it +when specifying the chain extension type in `Environment`: +```rust +type ChainExtension = CombinedChainExtension; +``` + +Each extension's method can be called by accessing it via the name of the field of `CombineChainExtension`: +```rust +self.env().extension().rand.() +// or +self.env().extension().psp22.() +// e.g. +self.env().extension().psp22.total_supply() +``` + +:::note +The ink! repository contains the [full example](https://github.com/paritytech/ink-examples/tree/main/combined-extension) illustrating how to combine existing chain extensions +and mock them for testing. +::: + + +## Mocking Chain Extension + +You can mock chain extensions for unit testing purposes. +This can be achieved by implementing the [`ink::env::test::ChainExtension`](https://docs.rs/ink_env/5.0.0/ink_env/test/trait.ChainExtension.html) trait. + +```rust +/// Opaque structure +struct MockedPSP22Extension; + +// Implementing +impl ink::env::test::ChainExtension for MockedPSP22Extension { + fn ext_id(&self) -> u16 { + // It is identifier used by `psp22_extension::Psp22Extension` extension. + // Must be the same as the once specified in `#[ink::chain_extension(extension = _)]` + 13 + } + + // Call dispatcher. + // Call specific code based on the function id which is dispatched from the contract/ + fn call(&mut self, func_id: u16, _input: &[u8], output: &mut Vec) -> u32 { + match func_id { + // `func_id` of the `total_supply` function. + // must match `#[ink(function = _)]` of the corresponding method + 0x162d => { + ink::scale::Encode::encode_to(&TOTAL_SUPPLY, output); + 0 + }, + // Other functions + _ => { + 1 + } + } + } +} +``` + ## Technical Limitations - Due to technical limitations it is not possible to refer to the `ErrorCode` associated type @@ -454,4 +556,4 @@ mod read_writer { Instead chain extension authors should directly use the error code type when required. This limitation might be lifted in future versions of ink!. - It is not possible to declare other chain extension traits as super traits or super - chain extensions of another. + chain extensions of another. \ No newline at end of file diff --git a/docs/macros-attributes/event.md b/docs/macros-attributes/event.md index 8fd1f56a81..78b5e2838b 100644 --- a/docs/macros-attributes/event.md +++ b/docs/macros-attributes/event.md @@ -1,13 +1,16 @@ --- -title: "#[ink(event)]" +title: "#[ink::event]" slug: /macros-attributes/event hide_title: true --- - + Applicable on `struct` definitions. Defines an ink! event. A contract can define multiple such ink! events. +Events can now be defined independently of contracts. The legacy syntax of events defined +within a contract module using `#[ink(event)]` continues to be valid. + [See our section on Events](../basics/events.md) for a detailed description and examples. diff --git a/docs/monthly-update/archive.md b/docs/monthly-update/archive.md deleted file mode 100644 index 0709ecedbf..0000000000 --- a/docs/monthly-update/archive.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Archive -slug: /monthly-update/archive ---- - -## 2022 - -* [August](../monthly-update/2022/08.md) -* [July](../monthly-update/2022/07.md) -* [June](../monthly-update/2022/06.md) -* [May](../monthly-update/2022/05.md) -* [April](../monthly-update/2022/04.md) -* [March](../monthly-update/2022/03.md) diff --git a/versioned_docs/version-5.x/standards/overview.md b/docs/standards/overview.md similarity index 100% rename from versioned_docs/version-5.x/standards/overview.md rename to docs/standards/overview.md diff --git a/versioned_docs/version-5.x/testing/debugging.md b/docs/testing/debugging.md similarity index 95% rename from versioned_docs/version-5.x/testing/debugging.md rename to docs/testing/debugging.md index 57153ee321..1f31e5f8a2 100644 --- a/versioned_docs/version-5.x/testing/debugging.md +++ b/docs/testing/debugging.md @@ -11,7 +11,7 @@ hide_title: true There are three ways to debug your ink! contract currently: * You can write tests using one of the mechanisms described on the - [Contract Testing](../testing/overview.md) page. + [Contract Testing](./overview.md) page. * You can interact with your contract via a UI or command-line. This is described on the [Call Your Contract](../getting-started/calling.md) page. * You can print debug statements in your contract. Those will appear @@ -21,8 +21,8 @@ There are three ways to debug your ink! contract currently: You can use those two macros: -* [`ink::env::debug_println!`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/macro.debug_println.html) -* [`ink::env::debug_print!`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/macro.debug_print.html) +* [`ink::env::debug_println!`](https://docs.rs/ink_env/5.0.0/ink_env/macro.debug_println.html) +* [`ink::env::debug_print!`](https://docs.rs/ink_env/5.0.0/ink_env/macro.debug_print.html) There are things you could do to enable debug messages on the client console: diff --git a/versioned_docs/version-5.x/testing/drink.md b/docs/testing/drink.md similarity index 98% rename from versioned_docs/version-5.x/testing/drink.md rename to docs/testing/drink.md index b0fc87bd8b..6ba8619f8b 100644 --- a/versioned_docs/version-5.x/testing/drink.md +++ b/docs/testing/drink.md @@ -105,11 +105,11 @@ You can check some helpful and verbose examples [here](https://github.com/inkdev DRink! is already integrated with the ink! framework and can be used as a drop-in replacement for the standard E2E testing environment. Just use corresponding argument in the test macro: ```rust -#[ink_e2e::test(backend(runtime_only()))] +#[ink_e2e::test(backend(runtime_only))] ``` to your test function and you have just switched from E2E testcase to DRink!-based one, that doesn't use any running node in the background! -For a full example check out [ink! repository](https://github.com/paritytech/ink-examples/blob/main/e2e-runtime-only-backend/lib.rs). +For a full example check out [ink! repository](https://github.com/paritytech/ink/tree/master/integration-tests/e2e-runtime-only-backend). ### With a command line tool diff --git a/versioned_docs/version-5.x/testing/e2e.md b/docs/testing/e2e.md similarity index 100% rename from versioned_docs/version-5.x/testing/e2e.md rename to docs/testing/e2e.md diff --git a/versioned_docs/version-5.x/testing/off-chain.md b/docs/testing/off-chain.md similarity index 96% rename from versioned_docs/version-5.x/testing/off-chain.md rename to docs/testing/off-chain.md index 23e35f43ed..71f65d856b 100644 --- a/versioned_docs/version-5.x/testing/off-chain.md +++ b/docs/testing/off-chain.md @@ -48,7 +48,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-examples/blob/main/erc20/lib.rs) contract on how to utilize those or [the documentation](https://docs.rs/ink/5.0.0-rc.1/ink/attr.test.html) for details. +See the [`examples/erc20`](https://github.com/paritytech/ink-examples/blob/main/erc20/lib.rs) contract on how to utilize those or [the documentation](https://docs.rs/ink/5.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 diff --git a/versioned_docs/version-5.x/testing/overview.md b/docs/testing/overview.md similarity index 100% rename from versioned_docs/version-5.x/testing/overview.md rename to docs/testing/overview.md diff --git a/versioned_docs/version-5.x/testing/testing-with-live-state.md b/docs/testing/testing-with-live-state.md similarity index 100% rename from versioned_docs/version-5.x/testing/testing-with-live-state.md rename to docs/testing/testing-with-live-state.md diff --git a/docs/testnet/Faucet.tsx b/docs/testing/testnet/Faucet.tsx similarity index 100% rename from docs/testnet/Faucet.tsx rename to docs/testing/testnet/Faucet.tsx diff --git a/versioned_docs/version-5.x/testing/testnet/faucet.md b/docs/testing/testnet/faucet.md similarity index 100% rename from versioned_docs/version-5.x/testing/testnet/faucet.md rename to docs/testing/testnet/faucet.md diff --git a/docs/testnet/overview.md b/docs/testing/testnet/overview.md similarity index 100% rename from docs/testnet/overview.md rename to docs/testing/testnet/overview.md diff --git a/docs/third-party-tools/ink-analyzer.md b/docs/third-party-tools/ink-analyzer.md index ef00d9619b..4bb152a13a 100644 --- a/docs/third-party-tools/ink-analyzer.md +++ b/docs/third-party-tools/ink-analyzer.md @@ -13,7 +13,7 @@ ink! analyzer aims to improve ink! language support in [integrated development e ## Problem -While ink! developers can leverage Rust tooling and excellent IDE/code editor support via [rust-analyzer](https://rust-analyzer.github.io/) and [IntelliJ Rust](https://www.jetbrains.com/rust/) because ["ink! is just standard Rust in a well-defined "contract format" with specialized `#[ink(…)]` attribute macros"](https://use.ink/getting-started/creating-an-ink-project), +While ink! developers can leverage Rust tooling and excellent IDE/code editor support via [rust-analyzer](https://rust-analyzer.github.io/) and [IntelliJ Rust](https://www.jetbrains.com/rust/) because ["ink! is just standard Rust in a well-defined "contract format" with specialized `#[ink(…)]` attribute macros"](../getting-started/creating.md), relying on only generic Rust language support in IDEs, code editors and other development tools has some significant limitations for the developer experience including: - No language support (e.g. diagnostic errors/warnings and quick fixes) for ink!'s domain specific semantic rules for smart contracts (e.g. exactly one `#[ink(storage)]` struct, at least one `#[ink(message)]` method and the same for `#[ink(constructor)]`, ink! attributes should be applied to items of the correct type e.t.c). diff --git a/docs/third-party-tools/inkathon.mdx b/docs/third-party-tools/inkathon.mdx index 765ca06772..da7f5a35e1 100644 --- a/docs/third-party-tools/inkathon.mdx +++ b/docs/third-party-tools/inkathon.mdx @@ -1,9 +1,9 @@ --- -title: ink!athon DApp Boilerplate +title: ink!athon dApp Boilerplate slug: /getting-started/inkathon --- -# ink!athon DApp Boilerplate +# ink!athon dApp Boilerplate ink!athon is a starter kit for full-stack dApp development with ink! smart contracts and a React-based frontend in one place. With convenient helper scripts and a pre-configured project setup, it lets you scaffold any dApp quickly. It's developed by the same team that is behind [AZERO.ID](https://azero.id), where this boilerplate is used in production. @@ -38,7 +38,7 @@ The starter kit is set up as a monorepo with two packages. ## Community & Support -import { BigCTA } from '../../src/components/BigCTA' +import { BigCTA } from '/src/components/BigCTA' () - .instantiate_v1() .code_hash(Hash::from([0x42; 32])) .gas_limit(0) .endowment(10) @@ -273,7 +272,6 @@ Below is an example of how to call a contract using the `CallBuilder`. We will: ```rust let my_return_value = build_call::() .call(AccountId::from([0x42; 32])) - .call_v1() .gas_limit(0) .transferred_value(10) .exec_input( @@ -335,11 +333,11 @@ These allow contract developers to handle two types of errors: 2. Error from the programming language (e.g `LangError`s) See the documentation for -[`try_instantiate`](https://docs.rs/ink_env/latest/ink_env/call/struct.CreateBuilder.html#method.try_instantiate), -[`try_invoke`](https://docs.rs/ink_env/latest/ink_env/call/struct.CallBuilder.html#method.try_invoke-2), -[`ink::env::Error`](https://docs.rs/ink_env/latest/ink_env/enum.Error.html) +[`try_instantiate`](https://docs.rs/ink_env/4.3.0/ink_env/call/struct.CreateBuilder.html#method.try_instantiate), +[`try_invoke`](https://docs.rs/ink_env/4.3.0/ink_env/call/struct.CallBuilder.html#method.try_invoke-2), +[`ink::env::Error`](https://docs.rs/ink_env/4.3.0/ink_env/enum.Error.html) and -[`ink::LangError`](https://docs.rs/ink/latest/ink/enum.LangError.html) +[`ink::LangError`](https://docs.rs/ink/4.3.0/ink/enum.LangError.html) for more details on proper error handling. :::tip diff --git a/docs/basics/debugging.md b/versioned_docs/version-4.x/basics/debugging.md similarity index 100% rename from docs/basics/debugging.md rename to versioned_docs/version-4.x/basics/debugging.md diff --git a/versioned_docs/version-4.x/basics/env-functions.md b/versioned_docs/version-4.x/basics/env-functions.md new file mode 100644 index 0000000000..bce5e172b1 --- /dev/null +++ b/versioned_docs/version-4.x/basics/env-functions.md @@ -0,0 +1,22 @@ +--- +title: Environment Functions +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/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/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). diff --git a/versioned_docs/version-5.x/basics/environment.md b/versioned_docs/version-4.x/basics/environment.md similarity index 100% rename from versioned_docs/version-5.x/basics/environment.md rename to versioned_docs/version-4.x/basics/environment.md diff --git a/versioned_docs/version-4.x/basics/events.md b/versioned_docs/version-4.x/basics/events.md new file mode 100644 index 0000000000..aaa5710686 --- /dev/null +++ b/versioned_docs/version-4.x/basics/events.md @@ -0,0 +1,130 @@ +--- +title: Events +slug: /basics/events +hide_title: true +--- + + + +# Events + +An ink! smart contract may define events that it can emit during contract execution. +Emitting events can be used by third party tools to query information about a contract's +execution and state. + +![Contract execution via transaction](/img/events.svg) + +## Example + +The following example ink! contract shows how an event `Transferred` is defined and +emitted in the `#[ink(constructor)]`. + +```rust +#[ink::contract] +mod erc20 { + /// Defines an event that is emitted + /// every time value is transferred. + #[ink(event)] + pub struct Transferred { + from: Option, + to: Option, + value: Balance, + } + + #[ink(storage)] + pub struct Erc20 { + total_supply: Balance, + // more fields ... + } + + impl Erc20 { + #[ink(constructor)] + pub fn new(initial_supply: Balance) -> Self { + let caller = Self::env().caller(); + Self::env().emit_event(Transferred { + from: None, + to: Some(caller), + value: initial_supply, + }); + Self { total_supply: initial_supply } + } + + #[ink(message)] + pub fn total_supply(&self) -> Balance { + self.total_supply + } + } +} +``` + +See our [`ERC20 example contract`](https://github.com/paritytech/ink-examples/blob/main/erc20/lib.rs) +for an elaborate example which uses events. + +## Event Definition + +This is how an event definition looks: + +```rust +#[ink(event)] +pub struct Transferred { + #[ink(topic)] + from: Option, + + #[ink(topic)] + to: Option, + + amount: Balance + +} +``` + +Add the `#[ink(topic)]` attribute tag to each item in your event that you want to have indexed. +A good rule of thumb is to ask yourself if somebody might want to search for this topic. +For this reason the `amount` in the exemplary event above was not +made indexable ‒ there will most probably be a lot of different events with +differing amounts each. + +The signature of the event is by default one of the topics of the event, except +if you annotate the event with `#[ink(anonymous)]`. +See [here](../macros-attributes/anonymous.md) for details on this attribute. + + +## Emitting Events in a Constructor + +In a constructor events are emitted via `Self::env().emit_event()`. +See this example: + +```rust +#[ink(constructor)] +pub fn new(initial_value: Balance) -> Self { + let caller = Self::env().caller(); + let mut balances = HashMap::new(); + balances.insert(caller, initial_supply); + + Self::env().emit_event(Transferred { + from: None, + to: Some(caller), + amount: initial_supply + }); + + Self { total_supply: initial_supply, balances } +} +``` + +## Emitting Events from Messages + +In a message events are emitted via `self.env().emit_event()`: + +```rust +#[ink(message)] +pub fn transfer(&mut self, to: AccountId, amount: Balance) -> Result { + let from = self.env().caller(); + // implementation hidden + self.env().emit_event(Transferred { + from: Some(from), + to: Some(to), + amount + }); + Ok(()) +} +``` diff --git a/versioned_docs/version-5.x/basics/metadata.md b/versioned_docs/version-4.x/basics/metadata.md similarity index 97% rename from versioned_docs/version-5.x/basics/metadata.md rename to versioned_docs/version-4.x/basics/metadata.md index b13988610f..013150c1aa 100644 --- a/versioned_docs/version-5.x/basics/metadata.md +++ b/versioned_docs/version-4.x/basics/metadata.md @@ -174,12 +174,12 @@ The contract `spec` consists of the following **required** keys: - `return_type`: The return type of the message. - `docs`: The message documentation. - `environment`: Configuration of the types that the host blockchain operates with. -You can check default types in [Environment](https://use.ink/basics/chain-environment-types) section. +You can check default types in [Environment](../basics/environment.md) section. - `accountId`: The type describing an account address. - `balance`: The type describing balance values. - `blockNumber`: The type describing a block number. - `chainExtension`: The type describing the chain extension for the environment. -For more information about usage and definition check [this section](https://use.ink/macros-attributes/chain-extension). +For more information about usage and definition check [this section](../macros-attributes/chain-extension.md). - `maxEventTopics`: The maximum number of supported event topics provided by the runtime. - `timestamp`: the type describing a timestamp. - `events`: The events of the contract. @@ -203,7 +203,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/5.0.0-rc.1/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). ::: diff --git a/versioned_docs/version-5.x/basics/mutating-values.md b/versioned_docs/version-4.x/basics/mutating-values.md similarity index 100% rename from versioned_docs/version-5.x/basics/mutating-values.md rename to versioned_docs/version-4.x/basics/mutating-values.md diff --git a/versioned_docs/version-5.x/basics/reading-values.md b/versioned_docs/version-4.x/basics/reading-values.md similarity index 100% rename from versioned_docs/version-5.x/basics/reading-values.md rename to versioned_docs/version-4.x/basics/reading-values.md diff --git a/versioned_docs/version-5.x/basics/selectors.md b/versioned_docs/version-4.x/basics/selectors.md similarity index 97% rename from versioned_docs/version-5.x/basics/selectors.md rename to versioned_docs/version-4.x/basics/selectors.md index 1f6b75e8f3..c06dd485c9 100644 --- a/versioned_docs/version-5.x/basics/selectors.md +++ b/versioned_docs/version-4.x/basics/selectors.md @@ -4,8 +4,6 @@ hide_title: true slug: /basics/selectors --- - - # Selectors Selectors in ink! are a language agnostic way of identifying constructors and messages. diff --git a/versioned_docs/version-5.x/basics/storing-values.md b/versioned_docs/version-4.x/basics/storing-values.md similarity index 95% rename from versioned_docs/version-5.x/basics/storing-values.md rename to versioned_docs/version-4.x/basics/storing-values.md index 7db6574b67..42ac948ad1 100644 --- a/versioned_docs/version-5.x/basics/storing-values.md +++ b/versioned_docs/version-4.x/basics/storing-values.md @@ -32,7 +32,7 @@ they were primitive types. ### String, Vector and More -The [`ink_prelude`](https://docs.rs/ink_prelude/latest/ink_prelude/index.html) crate provides an efficient approach to import commonly used Rust types such as `String` and `Vec`, ensuring safe usage within an ink! contract. +The [`ink_prelude`](https://docs.rs/ink_prelude/4.3.0/ink_prelude/index.html) crate provides an efficient approach to import commonly used Rust types such as `String` and `Vec`, ensuring safe usage within an ink! contract. This simplifies the type referencing process between the `std` and `no_std` environments. Typically, these types are defined within the `std` crate in the `std` environment, and the `alloc` crate in the `no_std` environment. Given that ink! smart contract code is compiled in both environments (`no_std` for production and `std` for unit tests), developers might find themselves writing intricate conditional compilation macros. The `ink_prelude` crate conveniently re-exports these types, eliminating this complexity. diff --git a/docs/basics/testing.md b/versioned_docs/version-4.x/basics/testing.md similarity index 100% rename from docs/basics/testing.md rename to versioned_docs/version-4.x/basics/testing.md diff --git a/versioned_docs/version-5.x/basics/trait-definitions.md b/versioned_docs/version-4.x/basics/trait-definitions.md similarity index 98% rename from versioned_docs/version-5.x/basics/trait-definitions.md rename to versioned_docs/version-4.x/basics/trait-definitions.md index a1700a4595..a3edabc3bc 100644 --- a/versioned_docs/version-5.x/basics/trait-definitions.md +++ b/versioned_docs/version-4.x/basics/trait-definitions.md @@ -95,7 +95,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/5.0.0-rc.1/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 diff --git a/versioned_docs/version-5.x/basics/upgradeability.md b/versioned_docs/version-4.x/basics/upgradeability.md similarity index 91% rename from versioned_docs/version-5.x/basics/upgradeability.md rename to versioned_docs/version-4.x/basics/upgradeability.md index 2ecae8148c..f7f0f20529 100644 --- a/versioned_docs/version-5.x/basics/upgradeability.md +++ b/versioned_docs/version-4.x/basics/upgradeability.md @@ -255,31 +255,6 @@ As you can see, delegatee's code looks like a normal ink! Smart Contract with so - `addresses` mapping key is identical - Constructor does not have any logic, as the code is never instantiated. (It can be, but plays no effect on the execution) -### Delegate dependency locks - -In a delegator contract pattern, one contract delegates calls to another contract. -Thus it depends upon the contract code to which it delegates. Since on-chain contract code -can be deleted by anybody if there are no instances of the contract on the chain, this would -break the `delegator` contract. To prevent this, the `delegator` contract can utilize the -`lock_delegate_dependency` and `unlock_delegate_dependency` host functions. Calling -`lock_delegate_dependency` will prevent the code at the given hash from being deleted e.g. - -```rust -self.env().lock_delegate_dependency(&code_hash); -``` - -A subsequent call to `unlock_delegate_dependency` from within the `delegator` contract -instance releases the lock from that contract, allowing that code at the given hash to be -deleted if no other instances of the contract or delegate dependency locks exist. - -```rust -self.env().lock_delegate_dependency(&code_hash); -``` - -Note that these two methods can be called by anybody executing the contract, so it is the -responsibility of the contract developer to ensure correct access control. -You can take a look at our [`upgradeable-contracts/delegator`](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts#delegator) -example, which demonstrates the usage of these two functions. ## Note on the usage of wildcard selectors diff --git a/versioned_docs/version-5.x/basics/verification/contract-verification.md b/versioned_docs/version-4.x/basics/verification/contract-verification.md similarity index 93% rename from versioned_docs/version-5.x/basics/verification/contract-verification.md rename to versioned_docs/version-4.x/basics/verification/contract-verification.md index 98fdcfd959..f15bfe663e 100644 --- a/versioned_docs/version-5.x/basics/verification/contract-verification.md +++ b/versioned_docs/version-4.x/basics/verification/contract-verification.md @@ -20,14 +20,14 @@ process must recompile the contract in an identical host environment to which it was originally built. The simplest way to do this is using a Docker container. -Since ink! 5.0, `cargo-contract` provides the necessary tools to produce +Since ink! `4.0.0`, `cargo-contract` provides the necessary tools to produce a verifiable build and verify a binary against the reference contract. :::note -Contract verification tools are available from `cargo-contract` -version 4.0 on. To install it, run +Contract verification tools are currently available in `cargo-contract` +version `4.0.0-alpha`. To install it, run ``` -cargo install cargo-contract --locked --version ^4 +cargo install cargo-contract --locked --version 4.0.0-alpha ``` ::: @@ -118,4 +118,4 @@ of all contracts to be visible. Specify a relative manifest path to the root con ::: You can find a Dockefile and further documentation on image usage -in [the `cargo-contract` repository](https://github.com/paritytech/cargo-contract/tree/master/build-image) \ No newline at end of file +in [the `cargo-contract` repository](https://github.com/paritytech/cargo-contract/tree/master/build-image) diff --git a/versioned_docs/version-5.x/basics/verification/sirato.md b/versioned_docs/version-4.x/basics/verification/sirato.md similarity index 100% rename from versioned_docs/version-5.x/basics/verification/sirato.md rename to versioned_docs/version-4.x/basics/verification/sirato.md diff --git a/versioned_docs/version-5.x/brand-assets/cargo-contract.md b/versioned_docs/version-4.x/brand-assets/cargo-contract.md similarity index 100% rename from versioned_docs/version-5.x/brand-assets/cargo-contract.md rename to versioned_docs/version-4.x/brand-assets/cargo-contract.md diff --git a/versioned_docs/version-5.x/brand-assets/community-badges.md b/versioned_docs/version-4.x/brand-assets/community-badges.md similarity index 100% rename from versioned_docs/version-5.x/brand-assets/community-badges.md rename to versioned_docs/version-4.x/brand-assets/community-badges.md diff --git a/versioned_docs/version-5.x/brand-assets/ink.md b/versioned_docs/version-4.x/brand-assets/ink.md similarity index 100% rename from versioned_docs/version-5.x/brand-assets/ink.md rename to versioned_docs/version-4.x/brand-assets/ink.md diff --git a/versioned_docs/version-5.x/brand-assets/stickers.md b/versioned_docs/version-4.x/brand-assets/stickers.md similarity index 100% rename from versioned_docs/version-5.x/brand-assets/stickers.md rename to versioned_docs/version-4.x/brand-assets/stickers.md diff --git a/versioned_docs/version-5.x/datastructures/custom.md b/versioned_docs/version-4.x/datastructures/custom.md similarity index 85% rename from versioned_docs/version-5.x/datastructures/custom.md rename to versioned_docs/version-4.x/datastructures/custom.md index bd0b6a46f2..1929a97f46 100644 --- a/versioned_docs/version-5.x/datastructures/custom.md +++ b/versioned_docs/version-4.x/datastructures/custom.md @@ -14,22 +14,22 @@ 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/5.0.0-rc.1/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_traits/5.0.0-rc.1/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: ```rust /// A custom type that we can use in our contract storage -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(scale::Decode, scale::Encode)] #[cfg_attr( feature = "std", - derive(ink::storage::traits::StorageLayout) + derive(scale_info::TypeInfo, ink::storage::traits::StorageLayout) )] pub struct Inner { value: bool, @@ -42,7 +42,7 @@ pub struct ContractStorage { ``` Even better: there is a macro -[`#[ink::storage_item]`](https://docs.rs/ink_macro/5.0.0-rc.1/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: @@ -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/5.0.0-rc.1/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/5.0.0-rc.1/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 @@ -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/5.0.0-rc.1/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 diff --git a/versioned_docs/version-5.x/datastructures/mapping.md b/versioned_docs/version-4.x/datastructures/mapping.md similarity index 69% rename from versioned_docs/version-5.x/datastructures/mapping.md rename to versioned_docs/version-4.x/datastructures/mapping.md index b54814d9de..8f74bed453 100644 --- a/versioned_docs/version-5.x/datastructures/mapping.md +++ b/versioned_docs/version-4.x/datastructures/mapping.md @@ -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/5.0.0-rc.1/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`: @@ -111,75 +111,6 @@ Furthermore, it follows that mapping values do not have a contiguous storage lay not possible to iterate over the contents of a map. -### Use fallible storage methods for dynamically sized values -Reading from or writing to a `Mapping` implies encoding or decoding -the according `Mapping` key and value. This happens transparently under the hood. -However, because the static buffer used to store the encoded data is of limited -size, it can fail and trap the contract. - -:::note - -The static buffer defaults to 16KB in size. - -::: - -This can be an issue for values with dynamically sized types. -It is recommended to use fallible storage methods (prefixed with `try_`) for -`Mapping`s containing dynamically sized values. - -Consider a `Mapping` with `String` values like so: - -```rust -#[ink(storage)] -pub struct MyContract { - on_chain_log: Mapping, - nonce: u64, -} -``` - -If the `String` overgrows the static buffer size, it will no longer fit into the mapping: - -```rust -#[ink(message)] -pub fn do_something(&mut self, data: String) { - let caller = self.env().caller(); - - let log_message = format!("{caller:?}: {data}"); - - // Panics if log_message overgrows the static buffer size! - self.on_chain_log.insert(&self.nonce, &log_message); - - self.nonce += 1; -} -``` - -Instead, consider using the fallible `try_insert` method to handle the situation: - -```rust -#[ink(message)] -pub fn do_something2(&mut self, data: String) { - let caller = self.env().caller(); - - let log_message = format!("{caller:?}: {data}"); - - // `try_insert` will not panic but return an error instead. - if self - .on_chain_log - .try_insert(&self.nonce, &log_message) - .is_err() - { - // We get the chance to handle this problem properly: - // Restrain the log message to a size guaranteed to fit. - let log_message = format!("{caller:?}: "); - self.on_chain_log.insert(&self.nonce, &log_message); - } - - self.nonce += 1; -} -``` - -We provide fallible `try_` versions for all storage operations on `Mapping`. - ### Updating values The attentive reader may have noticed that accessing mapping values via the `Mapping::get()` diff --git a/versioned_docs/version-5.x/datastructures/overview.md b/versioned_docs/version-4.x/datastructures/overview.md similarity index 86% rename from versioned_docs/version-5.x/datastructures/overview.md rename to versioned_docs/version-4.x/datastructures/overview.md index 47ad4ad5bb..2f2d35c6e5 100644 --- a/versioned_docs/version-5.x/datastructures/overview.md +++ b/versioned_docs/version-4.x/datastructures/overview.md @@ -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/5.0.0-rc.1/ink_storage/struct.Mapping.html) -and [`Lazy`](https://docs.rs/ink_storage/5.0.0-rc.1/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. @@ -29,4 +29,4 @@ it can be used to prevent the contract from eagerly loading large storage fields during each contract call. Conceivably, it may be desirable to change certain aspects on how your contract deals with its storage variables. You can find out more about this in the section about the ink! -[Storage Layout](https://use.ink/datastructures/storage-layout). +[Storage Layout](./storage-layout.md). diff --git a/versioned_docs/version-5.x/datastructures/storage-in-metadata.md b/versioned_docs/version-4.x/datastructures/storage-in-metadata.md similarity index 98% rename from versioned_docs/version-5.x/datastructures/storage-in-metadata.md rename to versioned_docs/version-4.x/datastructures/storage-in-metadata.md index 7e3a524a38..3b46889e9b 100644 --- a/versioned_docs/version-5.x/datastructures/storage-in-metadata.md +++ b/versioned_docs/version-4.x/datastructures/storage-in-metadata.md @@ -1,12 +1,12 @@ --- -title: Storage Metadata Format +title: Metadata Format slug: /datastructures/storage-in-metadata hide_title: true --- -# Storage Metadata Format +# Metadata Format The storage layout of a contract is reflected inside the metadata. It allows third-party tooling to work with contract storage and can also help to better understand the storage @@ -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/5.0.0-rc.1/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. diff --git a/versioned_docs/version-5.x/datastructures/storage-layout.md b/versioned_docs/version-4.x/datastructures/storage-layout.md similarity index 95% rename from versioned_docs/version-5.x/datastructures/storage-layout.md rename to versioned_docs/version-4.x/datastructures/storage-layout.md index fe5d1dd8bb..cca8d29194 100644 --- a/versioned_docs/version-5.x/datastructures/storage-layout.md +++ b/versioned_docs/version-4.x/datastructures/storage-layout.md @@ -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/5.0.0-rc.1/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. @@ -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/5.0.0-rc.1/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/5.0.0-rc.1/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 diff --git a/versioned_docs/version-5.x/examples/contracts.md b/versioned_docs/version-4.x/examples/contracts.md similarity index 96% rename from versioned_docs/version-5.x/examples/contracts.md rename to versioned_docs/version-4.x/examples/contracts.md index f78a982b4d..e8447a2ada 100644 --- a/versioned_docs/version-5.x/examples/contracts.md +++ b/versioned_docs/version-4.x/examples/contracts.md @@ -1,13 +1,8 @@ --- -title: Smart Contract Examples +title: Smart Contracts slug: /examples/smart-contracts -hide_title: true --- - - -# Smart Contract Examples - We have a repository `ink-examples`, in which you find a number of contracts written in ink!. Some of the most interesting ones: diff --git a/versioned_docs/version-5.x/examples/dapps.md b/versioned_docs/version-4.x/examples/dapps.md similarity index 64% rename from versioned_docs/version-5.x/examples/dapps.md rename to versioned_docs/version-4.x/examples/dapps.md index c818f01dcf..ef9fd40746 100644 --- a/versioned_docs/version-5.x/examples/dapps.md +++ b/versioned_docs/version-4.x/examples/dapps.md @@ -1,12 +1,12 @@ --- -title: dApps +title: DApps slug: /examples/dapps hide_title: true --- - + -# dApps +# DApps We'll point to a couple full-stack dApp examples here. These can serve as inspiration for how to create a frontend for your @@ -14,11 +14,8 @@ smart contract. Three popular libraries for building frontends are: -- [`@polkadot/api`](https://github.com/polkadot-js/api): a general purpose low-level TypeScript API for substrate. - -- [`@polkadot/api-contract`](https://polkadot.js.org/docs/api-contract): a `pallet-contract` specific TypeScript API. - -- [useInkathon](https://github.com/scio-labs/use-inkathon): a React hooks library for interacting with Wasm contracts and Substrate. +- [`polkadot-js/api`](https://github.com/polkadot-js/api) a low-level TypeScript API. +- [useInkathon](https://github.com/scio-labs/use-inkathon) a React hooks library. ## INK!athon @@ -37,4 +34,4 @@ The entire source code (contract + frontend) is located here: You can view an online demo of the dApp here: [https://tiny.ink](https://tiny.ink). To create new short links you need `ROC` tokens from our testnet. -See [here](../testing/overview.md) for how to get those. +See [here](../testnet/overview.md) for how to get those. diff --git a/versioned_docs/version-5.x/faq/faq.md b/versioned_docs/version-4.x/faq/faq.md similarity index 81% rename from versioned_docs/version-5.x/faq/faq.md rename to versioned_docs/version-4.x/faq/faq.md index 4a76ce355f..39ad910221 100644 --- a/versioned_docs/version-5.x/faq/faq.md +++ b/versioned_docs/version-4.x/faq/faq.md @@ -92,10 +92,8 @@ See the [Chain Extensions](../macros-attributes/chain-extension.md) section for ### How can I use ink! with a Substrate chain with a custom chain config? -Please see [this section](../macros-attributes/contract.md#env-impl-environment) in our documentation. - -Detailed documentation is found in [the Rust docs](https://docs.rs/ink_macro/5.0.0-rc.1/ink_macro/attr.contract.html#header-arguments) -for the `#[ink(contract)]` macro. It allows you to specify your environment a la +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)]`. ### What does the `#![cfg_attr(not(feature = "std"), no_std)]` at the beginning of each contract mean? @@ -135,7 +133,7 @@ The contract storage is built on top of the runtime storage, and access is consi ### How do I print something to the console from the runtime? -Please see our page on [Contract Debugging](../testing/debugging.md). +Please see our page on [Contract Debugging](../basics/debugging.md). ### Why is Rust's standard library (stdlib) not available in ink!? @@ -171,15 +169,15 @@ Rust's standard library consists of three different layers: A number of crypto hashes are built into the [pallet-contracts](../intro/how-it-works.md) 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/5.0.0-rc.1/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.md) 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/5.0.0-rc.1/ink_env/fn.hash_bytes.html) -* [`self.env().hash_encoded()`](https://docs.rs/ink_env/5.0.0-rc.1/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? @@ -230,7 +228,7 @@ If you don't find the issue you can also ask for help in our public [Discord](https://discord.gg/j2DKRRbSJr) channel. -### What are the `Encode`, `Decode` and `TypeInfo` arguments in `#[ink::scale_derive(Encode, Decode, TypeInfo)]` ? +### What are the `scale::Encode` and `scale::Decode` traits? Substrate-based blockchains use the [SCALE codec](https://github.com/paritytech/parity-scale-codec) to encode data. @@ -239,9 +237,6 @@ be SCALE-encodable ‒ i.e. it needs to implement either `scale::Encode`, `scale::Decode`, or both. This affects e.g. data you want to return to a caller, data that you want to take as input, or data you want to store on-chain. -ink! re-exports these traits and provides a useful macro `#[ink::scale_derive(Encode, Decode, TypeInfo)]` that allows to derive them -in a concise way. - A common error you might get when a necessary SCALE trait is not implemented for a data structure could be along the lines of `the trait "WrapperTypeEncode" is not implemented for "Foo"`. @@ -264,15 +259,12 @@ to a caller or when it is persisted to the contracts storage. * `Decode` is used for the inverse, e.g. when reading from storage or taking an input from a user (or another contract). -* `TypeInfo` is used to encode the information about the type that is -often used for the generation of metadata. - It's possible to derive those traits and oftentimes the simplest way is to just derive the missing trait for the object for which its implementation -is missing using the ink! macro: +is missing: ```rust -#[ink::scale_derive(Encode, Decode)] +#[derive(scale::Encode, scale::Decode)] struct MyCustomDataStructure { … } ``` @@ -287,39 +279,4 @@ and you should only persist items which you need to derive state transitions in your contract. If you still, for some reason, need to use `String`, then you should use -the `String` [from the ink! prelude](https://docs.rs/ink_prelude/latest/ink_prelude/string/struct.String.html). - -

Getting a warning in cargo-contract about type compatibility?

- -ink! and Substrate both support the possibility of deciding to deviate -from the default types for `Balance`, `BlockNumber`, etc. -These types are called environment types. - -If a chain decides on custom environment types, contract authors need -to specify these types that deviate from the ink! default environment in their -contracts. Otherwise, undefined behavior can occur when uploading a contract -with deviating types to a chain. - -Custom environment types can be specified in ink! via the `#[contract(env = MyCustomEnvironment)]` -attribute. You can read more are about this [here](../macros-attributes/contract.md#env-impl-environment). - -When using `cargo-contract` to interact with a chain you might get a warning along those lines: - -``` -Warning: This chain does not yet support checking for compatibility of your contract types. -``` - -This warning appears when the chain that you are targeting (via the `--url` cli flag) -does not contain a version of `pallet-contracts` that does support type comparison. -Type comparison is a feature that we introduced, it means we check that the environmental -types of your contract are equivalent to the environmental types of the chain that you are -targeting. -It's a safety feature to make sure that you are not accidentally deploying a contract with -e.g. `type Balance = u128` to a chain with a different `Balance` type. - -The `cargo-contract` warning means this check for compatible types cannot be performed. -This check is only available on chains from `polkadot-1.2.0` on, specifically from -[this commit](https://github.com/paritytech/polkadot-sdk/commit/d8a74901462ffb49345af6db7c5a7a6e2b3c92ed). - -If a chain indeed requires that contract developers have to use custom environment types, -this should be communicated prominently by them. \ No newline at end of file +the `String` [from the ink! prelude](https://docs.rs/ink_prelude/4.3.0/ink_prelude/string/struct.String.html). diff --git a/versioned_docs/version-5.x/faq/migrating-from-ink-3-to-4.md b/versioned_docs/version-4.x/faq/migrating-from-ink-3-to-4.md similarity index 88% rename from versioned_docs/version-5.x/faq/migrating-from-ink-3-to-4.md rename to versioned_docs/version-4.x/faq/migrating-from-ink-3-to-4.md index 58bedfc4f4..4f896df7c5 100644 --- a/versioned_docs/version-5.x/faq/migrating-from-ink-3-to-4.md +++ b/versioned_docs/version-4.x/faq/migrating-from-ink-3-to-4.md @@ -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/5.0.0-rc.1/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); @@ -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/5.0.0-rc.1/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/5.0.0-rc.1/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 @@ -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/5.0.0-rc.1/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` instead of `()`. -A new function [`ink_env::take_contract_storage`](https://docs.rs/ink_env/5.0.0-rc.1/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 @@ -177,7 +177,7 @@ for constructors `Result`). 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/5.0.0-rc.1/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). @@ -321,14 +321,14 @@ better. ## Updates to the `CallBuilder` and `CreateBuilder` APIs There's been several changes to the -[`CallBuilder`](https://docs.rs/ink_env/5.0.0-rc.1/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/5.0.0-rc.1/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/5.0.0-rc.1/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. @@ -337,9 +337,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/5.0.0-rc.1/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/5.0.0-rc.1/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 @@ -349,13 +349,13 @@ 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/5.0.0-rc.1/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/5.0.0-rc.1/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/5.0.0-rc.1/ink_env/call/struct.CallBuilder.html#method.call) (this replaces `CallBuilder::callee()`) -- For `DelegateCall` you can use [`CallBuilder::delegate()`](https://docs.rs/ink_env/5.0.0-rc.1/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) ## Removal of `[lib.crate-type]` and `[lib.name]` from contract manifest Earlier versions of `cargo-contract` required that these two fields were specified in the @@ -373,7 +373,7 @@ crate-type = [ ] ``` -However, with with [cargo-contract#929](https://github.com/paritytech/cargo-contract/pull/929) we changed this behavior to: +However, with [cargo-contract#929](https://github.com/paritytech/cargo-contract/pull/929) we changed this behavior to: - Use the contract name by default, removing the need for the `name` field - Compile contracts as `rlib`s by default, and automatically changing to `cdylib` as needed diff --git a/versioned_docs/version-5.x/frontend/overview.md b/versioned_docs/version-4.x/frontend/overview.md similarity index 100% rename from versioned_docs/version-5.x/frontend/overview.md rename to versioned_docs/version-4.x/frontend/overview.md diff --git a/versioned_docs/version-5.x/getting-started/assets/canvas-connect-to-local.png b/versioned_docs/version-4.x/getting-started/assets/canvas-connect-to-local.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/canvas-connect-to-local.png rename to versioned_docs/version-4.x/getting-started/assets/canvas-connect-to-local.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-false.png b/versioned_docs/version-4.x/getting-started/assets/flipper-false.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-false.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-false.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-01.png b/versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-01.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-01.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-01.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-02.png b/versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-02.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-02.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-02.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-03.png b/versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-03.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-03.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-03.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-04.png b/versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-04.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-instantiate-04.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-instantiate-04.png diff --git a/versioned_docs/version-5.x/getting-started/assets/flipper-true.png b/versioned_docs/version-4.x/getting-started/assets/flipper-true.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/flipper-true.png rename to versioned_docs/version-4.x/getting-started/assets/flipper-true.png diff --git a/versioned_docs/version-5.x/getting-started/assets/send-as-transaction.png b/versioned_docs/version-4.x/getting-started/assets/send-as-transaction.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/send-as-transaction.png rename to versioned_docs/version-4.x/getting-started/assets/send-as-transaction.png diff --git a/versioned_docs/version-5.x/getting-started/assets/start-substrate-node.png b/versioned_docs/version-4.x/getting-started/assets/start-substrate-node.png similarity index 100% rename from versioned_docs/version-5.x/getting-started/assets/start-substrate-node.png rename to versioned_docs/version-4.x/getting-started/assets/start-substrate-node.png diff --git a/versioned_docs/version-5.x/getting-started/calling.md b/versioned_docs/version-4.x/getting-started/calling.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/calling.md rename to versioned_docs/version-4.x/getting-started/calling.md diff --git a/versioned_docs/version-5.x/getting-started/cargo-contract.md b/versioned_docs/version-4.x/getting-started/cargo-contract.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/cargo-contract.md rename to versioned_docs/version-4.x/getting-started/cargo-contract.md diff --git a/versioned_docs/version-5.x/getting-started/compiling.md b/versioned_docs/version-4.x/getting-started/compiling.md similarity index 62% rename from versioned_docs/version-5.x/getting-started/compiling.md rename to versioned_docs/version-4.x/getting-started/compiling.md index 48e396169a..aaf52c3d5e 100644 --- a/versioned_docs/version-5.x/getting-started/compiling.md +++ b/versioned_docs/version-4.x/getting-started/compiling.md @@ -14,11 +14,10 @@ Run the following command in your `flipper` directory to compile your smart cont cargo contract build ``` -This command will build the following for your contract: -a Wasm binary, a metadata file (which contains the -contract's ABI) and a `.contract` file which bundles both. - -If all goes well, you should see a `target` folder which contains these files: +This command will build the following for your contract: a Wasm binary, a metadata file (which contains the +contract's ABI) and a `.contract` file which bundles both. This `.contract` file can be used to +deploy your contract to a chain. If all goes well, you should see a `target` folder which +contains these files: ``` target @@ -27,25 +26,6 @@ target └─ flipper.wasm └─ flipper.json ``` -You can think of it this way: the raw Wasm binary contains just -the bytecode of your contract. Without further information it's -not possible to know what this bytecode refers to. For example, -which functions can be called in there and what their arguments -are. This additional information that describes what the raw Wasm -is about is called metadata ‒ data that describes other data. - -

- -

- -The purpose of each file is: - -* `flipper.wasm`: This is the raw contract bytecode that will be deployed on-chain. -* `flipper.json`: The isolated metadata, which is not stored on-chain. -It's big and would take up too much space and costs. -This file is used by e.g. a dApp user interface to know how to communicate with the on-chain contract. -* `flipper.contract`: Combines both the contract's bytecode and the metadata. This file -is used when you are using a Developer UI like [Contracts UI](https://contracts-ui.substrate.io/). Let's take a look at the structure of the `flipper.json`: @@ -77,20 +57,6 @@ If you look closely at the constructors and messages, you will also notice a `se contains a 4-byte hash of the function name and is used to route your contract calls to the correct functions. -You can also open up the `flipper.contract` file in any text editor. You'll notice that it's -nearly the same as the `flipper.json`. The only different is that the `.contract` file contains -an additional field with the hex-encoded Wasm bytecode of your contract: - -``` -{ - "source": { - … - "wasm": "0x006173…", - }, - … -} -``` - In the next section we will start a [Substrate Smart Contracts node](https://github.com/paritytech/substrate-contracts-node) and configure the [Contracts UI](https://github.com/paritytech/contracts-ui) to interact with it. diff --git a/versioned_docs/version-5.x/getting-started/creating.md b/versioned_docs/version-4.x/getting-started/creating.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/creating.md rename to versioned_docs/version-4.x/getting-started/creating.md diff --git a/versioned_docs/version-5.x/getting-started/deploying.md b/versioned_docs/version-4.x/getting-started/deploying.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/deploying.md rename to versioned_docs/version-4.x/getting-started/deploying.md diff --git a/versioned_docs/version-5.x/getting-started/running.md b/versioned_docs/version-4.x/getting-started/running.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/running.md rename to versioned_docs/version-4.x/getting-started/running.md diff --git a/versioned_docs/version-5.x/getting-started/setup.md b/versioned_docs/version-4.x/getting-started/setup.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/setup.md rename to versioned_docs/version-4.x/getting-started/setup.md diff --git a/versioned_docs/version-5.x/getting-started/troubleshooting.md b/versioned_docs/version-4.x/getting-started/troubleshooting.md similarity index 100% rename from versioned_docs/version-5.x/getting-started/troubleshooting.md rename to versioned_docs/version-4.x/getting-started/troubleshooting.md diff --git a/docs/inkubator/overview.md b/versioned_docs/version-4.x/inkubator/overview.md similarity index 89% rename from docs/inkubator/overview.md rename to versioned_docs/version-4.x/inkubator/overview.md index f8e9591086..75a18028d5 100644 --- a/docs/inkubator/overview.md +++ b/versioned_docs/version-4.x/inkubator/overview.md @@ -10,6 +10,6 @@ slug: /inkubator-overview ink!ubator is an initiative funded by the Polkadot Treasury's Bounty Program. It is designed to kickstart the ink! ecosystem on Polkadot, Kusama, and other Substrate chains. -import { BigCTA } from "../../src/components/BigCTA"; +import { BigCTA } from "/src/components/BigCTA"; diff --git a/versioned_docs/version-5.x/intro/how-it-works.md b/versioned_docs/version-4.x/intro/how-it-works.md similarity index 92% rename from versioned_docs/version-5.x/intro/how-it-works.md rename to versioned_docs/version-4.x/intro/how-it-works.md index 444fbae69f..ed41e4ec77 100644 --- a/versioned_docs/version-5.x/intro/how-it-works.md +++ b/versioned_docs/version-4.x/intro/how-it-works.md @@ -55,7 +55,7 @@ Those chains typically take the off-the-shelf `pallet-contracts` and create some ### Use Case 2: Smart Contracts as "second-class citizens" There is another not so obvious use case for `pallet-contracts`: smart contracts as “second-class citizens” on an existing chain. By this we mean that the central value proposition of the chain has nothing to do with smart contracts, but it still includes them as an add-on. -We provide an API (called [chain extensions](https://use.ink/macros-attributes/chain-extension)) with which a parachain can expose certain parts of its business logic to smart contract developers. Through this, smart contract developers can utilize the business logic primitives of the chain to build a new application on top of it. Think for example of a decentralized exchange blockchain. This chain would in its simplest form have an order book to place bids and asks ‒ there is no need for taking untrusted, Turing-complete, programs from the outside. The parachain could decide to expose the order book into smart contracts though, giving external developers the option of building new applications that utilize the order book. For example, to upload trading algorithms as smart contracts to the chain. +We provide an API (called [chain extensions](../macros-attributes/chain-extension.md)) with which a parachain can expose certain parts of its business logic to smart contract developers. Through this, smart contract developers can utilize the business logic primitives of the chain to build a new application on top of it. Think for example of a decentralized exchange blockchain. This chain would in its simplest form have an order book to place bids and asks ‒ there is no need for taking untrusted, Turing-complete, programs from the outside. The parachain could decide to expose the order book into smart contracts though, giving external developers the option of building new applications that utilize the order book. For example, to upload trading algorithms as smart contracts to the chain. Smart contracts here are an opportunity to up the user engagement and drive usage of the chain's native token. And the billing for utilizing the chain comes already built-in with the pallet ‒ users have to pay gas fees for the execution of their smart contract. diff --git a/versioned_docs/version-5.x/intro/ink-vs-cosmwasm.md b/versioned_docs/version-4.x/intro/ink-vs-cosmwasm.md similarity index 98% rename from versioned_docs/version-5.x/intro/ink-vs-cosmwasm.md rename to versioned_docs/version-4.x/intro/ink-vs-cosmwasm.md index aa0892b9f2..40faf6cbf4 100644 --- a/versioned_docs/version-5.x/intro/ink-vs-cosmwasm.md +++ b/versioned_docs/version-4.x/intro/ink-vs-cosmwasm.md @@ -59,7 +59,7 @@ While CosmWasm unit tests have different modules for each of the three main entr functions, ink! allows for a more generalised approach, where the `#[ink(test)]` macro is used for each unit test. -You can read more about ink! unit tests [here](https://use.ink/basics/contract-testing#unit-tests). +You can read more about ink! unit tests [here](../basics/testing.md#unit-tests). ## Compiler diff --git a/versioned_docs/version-5.x/intro/ink-vs-solidity.md b/versioned_docs/version-4.x/intro/ink-vs-solidity.md similarity index 90% rename from versioned_docs/version-5.x/intro/ink-vs-solidity.md rename to versioned_docs/version-4.x/intro/ink-vs-solidity.md index 9975dd1eff..8d19e0c10a 100644 --- a/versioned_docs/version-5.x/intro/ink-vs-solidity.md +++ b/versioned_docs/version-4.x/intro/ink-vs-solidity.md @@ -29,9 +29,46 @@ The following table gives a brief comparison of features between ink! and Solidi
-## Converting a Solidity Contract to ink! +## Solidity to ink! Guide + +### Table of Contents + +- [Solidity to ink! Guide](#solidity-to-ink-guide) +- [Table of Contents](#table-of-contents) +- [Converting a Solidity contract to ink!](#converting-a-solidity-contract-to-ink) + - [1. Generate a new ink! contract](#1-generate-a-new-ink-contract) + - [2. Build the contract](#2-build-the-contract) + - [3. Convert Solidity class fields to Rust struct](#3-convert-solidity-class-fields-to-rust-struct) + - [4. Convert each function](#4-convert-each-function) +- [Best Practices + Tips](#best-practices--tips) +- [Syntax Equivalencies](#syntax-equivalencies) + - [`public function`](#public-function) + - [`mapping declaration`](#mapping-declaration) + - [`mapping usage`](#mapping-usage) + - [`struct`](#struct) + - [`assertions / requires`](#assertions--requires) + - [`timestamp`](#timestamp) + - [`contract caller`](#contract-caller) + - [`contract's address`](#contracts-address) + - [`bytes`](#bytes) + - [`uint256`](#uint256) + - [`payable`](#payable) + - [`received deposit / payment`](#received-deposit--payment) + - [`contract balance`](#contract-balance) + - [`transfer tokens from contract`](#transfer-tokens-from-contract) + - [`events & indexed`](#events--indexed) + - [`errors and returning`](#errors-and-returning) + - [`throw`](#throw) + - [`assert`](#assert) + - [`require and revert`](#require-and-revert) + - [`nested mappings + custom / advanced structures`](#nested-mappings--custom--advanced-structures) + - [`cross-contract calling`](#cross-contract-calling) + - [`submit generic transaction / dynamic cross-contract calling`](#submit-generic-transaction--dynamic-cross-contract-calling) +- [Limitations of ink! v3](#limitations-of-ink-v3) +- [Troubleshooting Errors](#troubleshooting-errors) +- [unit testing (off-chain)](#unit-testing-off-chain) -In the following, we'll explain how to convert a Solidity contract to ink!. +## Converting a Solidity Contract to ink! ### 1. Generate a new ink! contract @@ -186,8 +223,8 @@ mod example { data: u128, } - #[ink::scale_derive(Encode, Decode, TypeInfo)] - #[derive(Debug, PartialEq, Eq)] + #[derive(Debug, scale::Encode, scale::Decode, PartialEq, Eq)] + #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))] pub enum Error { DataShouldNotBeZero, } @@ -286,7 +323,7 @@ pub struct ContractName { } ``` -When using a map in ink!, `ink_lang::utils::initialize_contract` must be used in the constructor. See [here](https://use.ink/datastructures/mapping) for more details. +When using a map in ink!, `ink_lang::utils::initialize_contract` must be used in the constructor. See [here](../datastructures/mapping.md) for more details. ### `mapping usage` @@ -511,8 +548,8 @@ function myFunction(bool returnError) public pure { ```rust // ink! -#[derive(Debug, PartialEq, Eq)] -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)] +#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))] pub enum Error { /// Provide a detailed comment on the error MyError, @@ -602,8 +639,15 @@ mod dao { storage::Mapping, }; - #[derive(Debug)] - #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive( + scale::Encode, + scale::Decode, + Debug, + )] + #[cfg_attr( + feature = "std", + derive(scale_info::TypeInfo) + )] pub struct Proposal { voted_yes: BTreeMap, } @@ -655,7 +699,7 @@ mod dao { ### `cross-contract calling` -In ink!, to do [cross-contract calling](https://use.ink/basics/cross-contract-calling), the contract will need to be added to the project. Ensure the contract is properly exporting its Structs. See the `erc20` contract example: +In ink!, to do [cross-contract calling](../basics/cross-contract-calling.md), the contract will need to be added to the project. Ensure the contract is properly exporting its Structs. See the `erc20` contract example: ```rust #![cfg_attr(not(feature = "std"), no_std, no_main)] @@ -688,7 +732,7 @@ crate-type = [ ink-as-dependency = [] ``` -`ink-as-dependency` "tells the ink! code generator to always or never compile the smart contract as if it was used as a dependency of another ink! smart contract" ([source](https://use.ink/basics/cross-contract-calling)). +`ink-as-dependency` "tells the ink! code generator to always or never compile the smart contract as if it was used as a dependency of another ink! smart contract" ([source](../basics/cross-contract-calling)). Then, In the main contract's Cargo.toml, import the contract that will be cross-called. @@ -718,7 +762,7 @@ use erc20::Erc20Ref; There are two methods to setup the other contract. 1. Instantiate the cross-called-contract in the main contract's constructor. - See [here](https://use.ink/basics/cross-contract-calling/) for a tutorial, and [here](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts/delegator) for an example. + See [here](../basics/cross-contract-calling.md) for a tutorial, and [here](https://github.com/paritytech/ink-examples/tree/main/upgradeable-contracts/delegator) for an example. 2. Or, add the `AccountId` of an already deployed contract. Here is an example constructor to set this up: @@ -790,7 +834,6 @@ fn invoke_transaction( .call_type( Call::new() .callee(callee) // contract to call - .call_v1() .gas_limit(*gas_limit) .transferred_value(transfer_amount), // value to transfer with call ) diff --git a/versioned_docs/version-5.x/intro/intro.mdx b/versioned_docs/version-4.x/intro/intro.mdx similarity index 82% rename from versioned_docs/version-5.x/intro/intro.mdx rename to versioned_docs/version-4.x/intro/intro.mdx index 6a05e3d7ec..d8b2518790 100644 --- a/versioned_docs/version-5.x/intro/intro.mdx +++ b/versioned_docs/version-4.x/intro/intro.mdx @@ -8,7 +8,7 @@ hide_table_of_contents: true
- +
@@ -24,9 +24,6 @@ hide_table_of_contents: true
-
- -
@@ -40,7 +37,7 @@ hide_table_of_contents: true
ink! is a programming language for smart contracts.
- You can use it with blockchains built on Substrate. + You can use it with blockchains built with the Polkadot SDK.
@@ -67,57 +64,55 @@ hide_table_of_contents: true

## Our Pitch -
-
-
- -

Inherent safety-guarantees with the Rust programming language.

-
-
- -

Ability to use all the normal Rust tooling ‒ clippy, crates.io, IDE’s, etc.

-
-
- -

Interoperability with Solidity contracts.

-
-
+
+
+ +

Inherent safety-guarantees with the Rust programming language.

+
+
+ +

Ability to use all the normal Rust tooling ‒ clippy, crates.io, IDE’s, etc.

+
+
+ +

Interoperability with Solidity contracts.

+
+
-
-   -
+
+  +
-
-
- -

Clear migration path for graduating to a parachain.

-
-
- -

Established industry standard for the compiler target.

-
-
- -

Native to Polkadot. Complements your Substrate parachain perfectly.

-
-
+
+
+ +

Clear migration path for graduating to a parachain.

+
+
+ +

Established industry standard for the compiler target.

+
+
+ +

Native to Polkadot. Complements your Substrate parachain perfectly.

+
## Where can I deploy ink! contracts? -
+

@@ -159,19 +154,6 @@ hide_table_of_contents: true
-
-
- - - -
-
- - - -
-
-

@@ -214,6 +196,14 @@ hide_table_of_contents: true
+
+
+ + + +
+
+

@@ -318,4 +308,3 @@ hide_table_of_contents: true -You can read more on standards [here](../standards/overview.md). diff --git a/versioned_docs/version-5.x/intro/migrate-to-parachain.md b/versioned_docs/version-4.x/intro/migrate-to-parachain.md similarity index 94% rename from versioned_docs/version-5.x/intro/migrate-to-parachain.md rename to versioned_docs/version-4.x/intro/migrate-to-parachain.md index c0e1d0d049..ec83705821 100644 --- a/versioned_docs/version-5.x/intro/migrate-to-parachain.md +++ b/versioned_docs/version-4.x/intro/migrate-to-parachain.md @@ -23,7 +23,7 @@ Much of the difficulty in launching a parachain comes in configuring a node impl ## Utilizing existing FRAME pallets -There is a rich library of FRAME pallets, which may provide a drop in replacement for some (or all) of your smart contract functionality. For example, for a [PSP22](https://use.ink/getting-started/use-openbrush/) (similar to ERC20) fungible token contract, this could be replaced either by the native Parachain token itself via `pallet_balances` or by an asset on `pallet_assets`. Governance functions could be replaced by e.g. `pallet_democracy`, and so on. See [`polkadot-sdk`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) for a range of pre-built pallets which can be used to handle some common functions. +There is a rich library of FRAME pallets, which may provide a drop in replacement for some (or all) of your smart contract functionality. For example, for a [PSP22](../third-party-tools/openbrush.md) (similar to ERC20) fungible token contract, this could be replaced either by the native Parachain token itself via `pallet_balances` or by an asset on `pallet_assets`. Governance functions could be replaced by e.g. `pallet_democracy`, and so on. See [`polkadot-sdk`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame) for a range of pre-built pallets which can be used to handle some common functions. ## Similarities and differences between `ink!` and `FRAME` @@ -67,7 +67,7 @@ pub struct Register { } ``` -Each of these structs annotated with `#[ink(event)]` can be translated to a variant in the pallet `Error` enum annotated with `#[pallet::error]`. Any of the `ink!` environment type aliases (both `Hash` and `AccountId` in the above example) must be translated to their equivalent associated type on the `Config` trait e.g. `AccountId` -> `T::AccountId`. Also the `#[ink(topic)]` annotations must be removed: topics must be calculated manually when the event is emitted, and will be covered later. Remove the `#[pallet::generate_deposit(pub(super) fn deposit_event)]` and the final `Event` type will look like: +Each of these structs annotated with `#[ink(event)]` can be translated to a variant in the pallet `Error` enum annotated with `#[pallet::error]`. Any of the `ink!` environment type aliases (both `Hash` and `AccountId` in the above example) must be translated to their equivalent associated type on the `Config` trait e.g. `AccountId` → `T::AccountId`. Also the `#[ink(topic)]` annotations must be removed: topics must be calculated manually when the event is emitted, and will be covered later. Remove the `#[pallet::generate_deposit(pub(super) fn deposit_event)]` and the final `Event` type will look like: ```rust= diff --git a/versioned_docs/version-5.x/intro/polkadot.md b/versioned_docs/version-4.x/intro/polkadot.md similarity index 98% rename from versioned_docs/version-5.x/intro/polkadot.md rename to versioned_docs/version-4.x/intro/polkadot.md index 280720133f..7f39ee5afa 100644 --- a/versioned_docs/version-5.x/intro/polkadot.md +++ b/versioned_docs/version-4.x/intro/polkadot.md @@ -23,5 +23,4 @@ _To restate this important distinction: developing a parachain runtime is differ The trade-off is that with a parachain one has the freedom to decide on (nearly) all the rules that make up the parachain. With a smart contract one is constrained by what the chain allows and the safety pillars that necessarily have to be in place. A smart contract can never be as fast as a native pallet built in the parachain runtime ‒ there is too much logic in between. A smart contract on the other hand has less friction for developing and deploying it. Developers don't have to take care of governance, crypto-economics, etc. One just needs a few tokens and can go on its merry way deploying a smart contract. It's as simple as that. -![](/img/smart-contract-vs-parachain.png) - +![](/img/smart-contract-vs-parachain.png) \ No newline at end of file diff --git a/versioned_docs/version-5.x/intro/upcoming-events.md b/versioned_docs/version-4.x/intro/upcoming-events.md similarity index 100% rename from versioned_docs/version-5.x/intro/upcoming-events.md rename to versioned_docs/version-4.x/intro/upcoming-events.md diff --git a/versioned_docs/version-5.x/intro/why-rust.md b/versioned_docs/version-4.x/intro/why-rust.md similarity index 100% rename from versioned_docs/version-5.x/intro/why-rust.md rename to versioned_docs/version-4.x/intro/why-rust.md diff --git a/versioned_docs/version-5.x/intro/why-webassembly.md b/versioned_docs/version-4.x/intro/why-webassembly.md similarity index 100% rename from versioned_docs/version-5.x/intro/why-webassembly.md rename to versioned_docs/version-4.x/intro/why-webassembly.md diff --git a/versioned_docs/version-4.x/macros-attributes/anonymous.md b/versioned_docs/version-4.x/macros-attributes/anonymous.md new file mode 100644 index 0000000000..6074a20708 --- /dev/null +++ b/versioned_docs/version-4.x/macros-attributes/anonymous.md @@ -0,0 +1,32 @@ +--- +title: "#[ink(anonymous)]" +slug: /macros-attributes/anonymous +hide_title: true +--- + + + +Applicable to ink! events. + +Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. + +Anonymous events have similar semantics as in Solidity in that their +event signature won't be included in their event topics serialization +to reduce event emitting overhead. This is especially useful for user +defined events. + +The signature of the event is by default one of the topics of the event, except +if you annotate the event with `#[ink(anonymous)]`. +The attribute implies that it is not possible to filter for specific anonymous events by name. + +## Example + +```rust +#[ink(event)] +#[ink(anonymous)] +pub struct MyEvent { + #[ink(topic)] + field_1: i32, + field_2: bool, +} +``` \ No newline at end of file diff --git a/versioned_docs/version-5.x/macros-attributes/chain-extension.md b/versioned_docs/version-4.x/macros-attributes/chain-extension.md similarity index 74% rename from versioned_docs/version-5.x/macros-attributes/chain-extension.md rename to versioned_docs/version-4.x/macros-attributes/chain-extension.md index 8f92be7ed1..c4dcdd93d5 100644 --- a/versioned_docs/version-5.x/macros-attributes/chain-extension.md +++ b/versioned_docs/version-4.x/macros-attributes/chain-extension.md @@ -7,7 +7,7 @@ hide_title: true In the default configuration of the `contracts-pallet` a smart contract can only interact with the runtime -via its well defined set of basic smart contract interface functions. This API already allows a whole variety of +via its well defined set of basic smart contract interface. This API already allows a whole variety of interaction between the `contracts-pallet` and the executed smart contract. For example it is possible to call and instantiate other smart contracts on the same chain, emit events, query context information or run built-in cryptographic hashing procedures. @@ -23,7 +23,7 @@ With chain extensions you can expose parts of your runtime logic to smart contract developers. :::note -The ink! examples repository contains [the `rand-extension` example](https://github.com/paritytech/ink-examples/tree/main/rand-extension). +The ink! repository contains [the `rand-extension` example](https://github.com/paritytech/ink-examples/tree/main/rand-extension). This is a complete example of a chain extension implemented in both ink! and Substrate. ::: @@ -49,31 +49,14 @@ ink! smart contracts using this chain extension simply depend on this crate and use its associated environment definition in order to make use of the methods provided by the chain extension. -## Macro Attributes - -The macro supports only one required argument: `extension = N: u16`. -The runtime may have several chain extensions at the same time. The `extension` -identifier points to the corresponding chain extension in the runtime. -The value should be the same as during the definition of the chain extension. -You can consult the -[chain extension module documentation](https://paritytech.github.io/polkadot-sdk/master/pallet_contracts/chain_extension/index.html) -if you are unsure how to find the chain extension code. -Otherwise, you should consult the target chain's documentation -for specifications of any chain extensions it exposes. - -:::note -If the chain extension is not used in a tuple in the runtime configuration, -`extension = N: u16` can take any `u16` number. -::: - -## Method Attributes +## Attributes There are two different attributes with which the chain extension methods can be flagged: | Attribute | Required | Default Value | Description | |:----------|:--------:|:--------------|:-----------:| -| `ink(function = N: u16)` | Yes | - | Determines the unique function ID within the chain extension. | +| `ink(extension = N: u32)` | Yes | - | Determines the unique function ID of the chain extension method. | | `ink(handle_status = flag: bool)` | Optional | `true` | Assumes that the returned status code of the chain extension method always indicates success and therefore always loads and decodes the output buffer of the call. | As with all ink! attributes multiple of them can either appear in a contiguous list: @@ -81,11 +64,11 @@ As with all ink! attributes multiple of them can either appear in a contiguous l ```rust type Access = i32; -#[ink::chain_extension(extension = 12)] +#[ink::chain_extension] pub trait MyChainExtension { type ErrorCode = i32; - #[ink(function = 5, handle_status = false)] + #[ink(extension = 5, handle_status = false)] fn key_access_for_account(key: &[u8], account: &[u8]) -> Access; } ``` @@ -95,11 +78,11 @@ pub trait MyChainExtension { ```rust type Access = i32; -#[ink::chain_extension(extension = 12)] +#[ink::chain_extension] pub trait MyChainExtension { type ErrorCode = i32; - #[ink(function = 5)] + #[ink(extension = 5)] #[ink(handle_status = false)] fn key_access_for_account(key: &[u8], account: &[u8]) -> Access; } @@ -171,7 +154,7 @@ from and to the runtime storage using access privileges: ```rust /// Custom chain extension to read to and write from the runtime. -#[ink::chain_extension(extension = 12)] +#[ink::chain_extension] pub trait RuntimeReadWrite { type ErrorCode = ReadWriteErrorCode; @@ -180,9 +163,8 @@ pub trait RuntimeReadWrite { /// # Note /// /// Actually returns a value of type `Result, Self::ErrorCode>`. - #[ink(function = 1, returns_result = false)] - fn read(key: &[u8]) -> Vec; - + /// #[ink(extension = 1, returns_result = false)] + /// fn read(key: &[u8]) -> Vec; /// /// Reads from runtime storage. /// @@ -198,7 +180,7 @@ pub trait RuntimeReadWrite { /// /// This requires `ReadWriteError` to implement `From` /// and may potentially return any `Self::ErrorCode` through its return value. - #[ink(function = 2)] + #[ink(extension = 2)] fn read_small(key: &[u8]) -> Result<(u32, [u8; 32]), ReadWriteError>; /// Writes into runtime storage. @@ -206,7 +188,7 @@ pub trait RuntimeReadWrite { /// # Note /// /// Actually returns a value of type `Result<(), Self::ErrorCode>`. - #[ink(function = 3)] + #[ink(extension = 3)] fn write(key: &[u8], value: &[u8]); /// Returns the access allowed for the key for the caller. @@ -214,7 +196,7 @@ pub trait RuntimeReadWrite { /// # Note /// /// Assumes to never fail the call and therefore always returns `Option`. - #[ink(function = 4, handle_status = false)] + #[ink(extension = 4, handle_status = false)] fn access(key: &[u8]) -> Option; /// Unlocks previously acquired permission to access key. @@ -227,18 +209,18 @@ pub trait RuntimeReadWrite { /// /// Assumes the call to never fail and therefore does _NOT_ require `UnlockAccessError` /// to implement `From` as in the `read_small` method above. - #[ink(function = 5, handle_status = false)] + #[ink(extension = 5, handle_status = false)] fn unlock_access(key: &[u8], access: Access) -> Result<(), UnlockAccessError>; } -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum ReadWriteErrorCode { InvalidKey, CannotWriteToKey, CannotReadFromKey, } -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum ReadWriteError { ErrorCode(ReadWriteErrorCode), BufferTooSmall { required_bytes: u32 }, @@ -256,7 +238,7 @@ impl From for ReadWriteError { } } -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub struct UnlockAccessError { reason: String, } @@ -267,7 +249,7 @@ impl From for UnlockAccessError { } } -#[ink::scale_derive(Encode, Decode, TypeInfo)] +#[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum Access { ReadWrite, ReadOnly, @@ -385,29 +367,29 @@ mod read_writer { } /// Custom chain extension to read to and write from the runtime. - #[ink::chain_extension(extension = 12)] + #[ink::chain_extension] pub trait RuntimeReadWrite { type ErrorCode = ReadWriteErrorCode; - #[ink(function = 1)] + #[ink(extension = 1)] fn read(key: &[u8]) -> Vec; - #[ink(function = 2)] + #[ink(extension = 2)] fn read_small(key: &[u8]) -> Result<(u32, [u8; 32]), ReadWriteError>; - #[ink(function = 3)] + #[ink(extension = 3)] fn write(key: &[u8], value: &[u8]); - #[ink(function = 4, handle_status = false)] + #[ink(extension = 4, handle_status = false)] fn access(key: &[u8]) -> Option; - #[ink(function = 5, handle_status = false)] + #[ink(extension = 5, handle_status = false)] fn unlock_access(key: &[u8], access: Access) -> Result<(), UnlockAccessError>; } - #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum ReadWriteErrorCode { InvalidKey, CannotWriteToKey, CannotReadFromKey, } - #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum ReadWriteError { ErrorCode(ReadWriteErrorCode), BufferTooSmall { required_bytes: u32 }, @@ -423,7 +405,7 @@ mod read_writer { } } - #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub struct UnlockAccessError { reason: String, } @@ -432,7 +414,7 @@ mod read_writer { panic!("encountered unexpected invalid SCALE encoding") } } - #[ink::scale_derive(Encode, Decode, TypeInfo)] + #[derive(scale::Encode, scale::Decode, scale_info::TypeInfo)] pub enum Access { ReadWrite, ReadOnly, @@ -465,90 +447,6 @@ mod read_writer { } ``` -## Using Multiple Chain Extensions - -It is possible to use multiple exposed chain extensions in the single environment of a smart contract. -The declaration procedure of the chain extension stays the same. - -Suppose we want to combine two chain extension called `Psp22Extension` and `FetchRandom`, ink! provides -a useful macro [`ink::combine_extensions!`](https://docs.rs/ink/5.0.0-rc/ink/macro.combine_extensions.html) that allows to construct the structure combining -the aforementioned chain extensions like so: -```rust -ink::combine_extensions! { - /// This extension combines the `FetchRandom` and `Psp22Extension` extensions. - /// It is possible to combine any number of extensions in this way. - /// - /// This structure is an instance that is returned by the `self.env().extension()` call. - pub struct CombinedChainExtension { - /// The instance of the `Psp22Extension` chain extension. - /// - /// It provides you access to `PSP22` functionality. - pub psp22: Psp22Extension, - /// The instance of the `FetchRandom` chain extension. - /// - /// It provides you access to randomness functionality. - pub rand: FetchRandom, - } -} -``` - -The combined structure is called `CombinedChainExtension`, and we can refer to it -when specifying the chain extension type in `Environment`: -```rust -type ChainExtension = CombinedChainExtension; -``` - -Each extension's method can be called by accessing it via the name of the field of `CombineChainExtension`: -```rust -self.env().extension().rand.() -// or -self.env().extension().psp22.() -// e.g. -self.env().extension().psp22.total_supply() -``` - -:::note -The ink! repository contains the [full example](https://github.com/paritytech/ink-examples/tree/main/combined-extension) illustrating how to combine existing chain extensions -and mock them for testing. -::: - - -## Mocking Chain Extension - -You can mock chain extensions for unit testing purposes. -This can be achieved by implementing the [`ink::env::test::ChainExtension`](https://docs.rs/ink_env/latest/ink_env/test/trait.ChainExtension.html) trait. - -```rust -/// Opaque structure -struct MockedPSP22Extension; - -// Implementing -impl ink::env::test::ChainExtension for MockedPSP22Extension { - fn ext_id(&self) -> u16 { - // It is identifier used by `psp22_extension::Psp22Extension` extension. - // Must be the same as the once specified in `#[ink::chain_extension(extension = _)]` - 13 - } - - // Call dispatcher. - // Call specific code based on the function id which is dispatched from the contract/ - fn call(&mut self, func_id: u16, _input: &[u8], output: &mut Vec) -> u32 { - match func_id { - // `func_id` of the `total_supply` function. - // must match `#[ink(function = _)]` of the corresponding method - 0x162d => { - ink::scale::Encode::encode_to(&TOTAL_SUPPLY, output); - 0 - }, - // Other functions - _ => { - 1 - } - } - } -} -``` - ## Technical Limitations - Due to technical limitations it is not possible to refer to the `ErrorCode` associated type @@ -556,4 +454,4 @@ impl ink::env::test::ChainExtension for MockedPSP22Extension { Instead chain extension authors should directly use the error code type when required. This limitation might be lifted in future versions of ink!. - It is not possible to declare other chain extension traits as super traits or super - chain extensions of another. \ No newline at end of file + chain extensions of another. diff --git a/versioned_docs/version-5.x/macros-attributes/constructor.md b/versioned_docs/version-4.x/macros-attributes/constructor.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/constructor.md rename to versioned_docs/version-4.x/macros-attributes/constructor.md diff --git a/versioned_docs/version-5.x/macros-attributes/contract.md b/versioned_docs/version-4.x/macros-attributes/contract.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/contract.md rename to versioned_docs/version-4.x/macros-attributes/contract.md diff --git a/versioned_docs/version-5.x/macros-attributes/default.md b/versioned_docs/version-4.x/macros-attributes/default.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/default.md rename to versioned_docs/version-4.x/macros-attributes/default.md diff --git a/versioned_docs/version-5.x/macros-attributes/event.md b/versioned_docs/version-4.x/macros-attributes/event.md similarity index 51% rename from versioned_docs/version-5.x/macros-attributes/event.md rename to versioned_docs/version-4.x/macros-attributes/event.md index 78b5e2838b..8fd1f56a81 100644 --- a/versioned_docs/version-5.x/macros-attributes/event.md +++ b/versioned_docs/version-4.x/macros-attributes/event.md @@ -1,16 +1,13 @@ --- -title: "#[ink::event]" +title: "#[ink(event)]" slug: /macros-attributes/event hide_title: true --- - + Applicable on `struct` definitions. Defines an ink! event. A contract can define multiple such ink! events. -Events can now be defined independently of contracts. The legacy syntax of events defined -within a contract module using `#[ink(event)]` continues to be valid. - [See our section on Events](../basics/events.md) for a detailed description and examples. diff --git a/versioned_docs/version-5.x/macros-attributes/implementation.md b/versioned_docs/version-4.x/macros-attributes/implementation.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/implementation.md rename to versioned_docs/version-4.x/macros-attributes/implementation.md diff --git a/versioned_docs/version-5.x/macros-attributes/message.md b/versioned_docs/version-4.x/macros-attributes/message.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/message.md rename to versioned_docs/version-4.x/macros-attributes/message.md diff --git a/versioned_docs/version-5.x/macros-attributes/namespace.md b/versioned_docs/version-4.x/macros-attributes/namespace.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/namespace.md rename to versioned_docs/version-4.x/macros-attributes/namespace.md diff --git a/versioned_docs/version-5.x/macros-attributes/overview.md b/versioned_docs/version-4.x/macros-attributes/overview.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/overview.md rename to versioned_docs/version-4.x/macros-attributes/overview.md diff --git a/versioned_docs/version-5.x/macros-attributes/payable.md b/versioned_docs/version-4.x/macros-attributes/payable.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/payable.md rename to versioned_docs/version-4.x/macros-attributes/payable.md diff --git a/versioned_docs/version-5.x/macros-attributes/selector.md b/versioned_docs/version-4.x/macros-attributes/selector.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/selector.md rename to versioned_docs/version-4.x/macros-attributes/selector.md diff --git a/versioned_docs/version-5.x/macros-attributes/storage.md b/versioned_docs/version-4.x/macros-attributes/storage.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/storage.md rename to versioned_docs/version-4.x/macros-attributes/storage.md diff --git a/versioned_docs/version-5.x/macros-attributes/topic.md b/versioned_docs/version-4.x/macros-attributes/topic.md similarity index 100% rename from versioned_docs/version-5.x/macros-attributes/topic.md rename to versioned_docs/version-4.x/macros-attributes/topic.md diff --git a/docs/monthly-update/2022/03.md b/versioned_docs/version-4.x/monthly-update/2022/03.md similarity index 100% rename from docs/monthly-update/2022/03.md rename to versioned_docs/version-4.x/monthly-update/2022/03.md diff --git a/docs/monthly-update/2022/04.md b/versioned_docs/version-4.x/monthly-update/2022/04.md similarity index 100% rename from docs/monthly-update/2022/04.md rename to versioned_docs/version-4.x/monthly-update/2022/04.md diff --git a/docs/monthly-update/2022/05.md b/versioned_docs/version-4.x/monthly-update/2022/05.md similarity index 100% rename from docs/monthly-update/2022/05.md rename to versioned_docs/version-4.x/monthly-update/2022/05.md diff --git a/docs/monthly-update/2022/06.md b/versioned_docs/version-4.x/monthly-update/2022/06.md similarity index 100% rename from docs/monthly-update/2022/06.md rename to versioned_docs/version-4.x/monthly-update/2022/06.md diff --git a/docs/monthly-update/2022/07.md b/versioned_docs/version-4.x/monthly-update/2022/07.md similarity index 100% rename from docs/monthly-update/2022/07.md rename to versioned_docs/version-4.x/monthly-update/2022/07.md diff --git a/docs/monthly-update/2022/08.md b/versioned_docs/version-4.x/monthly-update/2022/08.md similarity index 100% rename from docs/monthly-update/2022/08.md rename to versioned_docs/version-4.x/monthly-update/2022/08.md diff --git a/docs/monthly-update/2022/09.md b/versioned_docs/version-4.x/monthly-update/2022/09.md similarity index 100% rename from docs/monthly-update/2022/09.md rename to versioned_docs/version-4.x/monthly-update/2022/09.md diff --git a/docs/monthly-update/2022/10.md b/versioned_docs/version-4.x/monthly-update/2022/10.md similarity index 100% rename from docs/monthly-update/2022/10.md rename to versioned_docs/version-4.x/monthly-update/2022/10.md diff --git a/docs/monthly-update/2022/11.md b/versioned_docs/version-4.x/monthly-update/2022/11.md similarity index 100% rename from docs/monthly-update/2022/11.md rename to versioned_docs/version-4.x/monthly-update/2022/11.md diff --git a/docs/monthly-update/2022/12.md b/versioned_docs/version-4.x/monthly-update/2022/12.md similarity index 100% rename from docs/monthly-update/2022/12.md rename to versioned_docs/version-4.x/monthly-update/2022/12.md diff --git a/docs/monthly-update/2023/01.md b/versioned_docs/version-4.x/monthly-update/2023/01.md similarity index 100% rename from docs/monthly-update/2023/01.md rename to versioned_docs/version-4.x/monthly-update/2023/01.md diff --git a/docs/monthly-update/2023/02.md b/versioned_docs/version-4.x/monthly-update/2023/02.md similarity index 100% rename from docs/monthly-update/2023/02.md rename to versioned_docs/version-4.x/monthly-update/2023/02.md diff --git a/docs/monthly-update/2023/03.md b/versioned_docs/version-4.x/monthly-update/2023/03.md similarity index 100% rename from docs/monthly-update/2023/03.md rename to versioned_docs/version-4.x/monthly-update/2023/03.md diff --git a/versioned_docs/version-4.x/monthly-update/archive.md b/versioned_docs/version-4.x/monthly-update/archive.md new file mode 100644 index 0000000000..7930ba0a60 --- /dev/null +++ b/versioned_docs/version-4.x/monthly-update/archive.md @@ -0,0 +1,13 @@ +--- +title: Archive +slug: /monthly-update/archive +--- + +## 2022 + +* [August](./2022/08.md) +* [July](./2022/07.md) +* [June](./2022/06.md) +* [May](./2022/05.md) +* [April](./2022/04.md) +* [March](./2022/03.md) diff --git a/docs/monthly-update/overview.md b/versioned_docs/version-4.x/monthly-update/overview.md similarity index 100% rename from docs/monthly-update/overview.md rename to versioned_docs/version-4.x/monthly-update/overview.md diff --git a/versioned_docs/version-5.x/testing/testnet/Faucet.tsx b/versioned_docs/version-4.x/testnet/Faucet.tsx similarity index 100% rename from versioned_docs/version-5.x/testing/testnet/Faucet.tsx rename to versioned_docs/version-4.x/testnet/Faucet.tsx diff --git a/docs/testnet/faucet.md b/versioned_docs/version-4.x/testnet/faucet.md similarity index 100% rename from docs/testnet/faucet.md rename to versioned_docs/version-4.x/testnet/faucet.md diff --git a/versioned_docs/version-5.x/testing/testnet/overview.md b/versioned_docs/version-4.x/testnet/overview.md similarity index 100% rename from versioned_docs/version-5.x/testing/testnet/overview.md rename to versioned_docs/version-4.x/testnet/overview.md diff --git a/docs/third-party-tools/contract-wizard/index.md b/versioned_docs/version-4.x/third-party-tools/contract-wizard/index.md similarity index 97% rename from docs/third-party-tools/contract-wizard/index.md rename to versioned_docs/version-4.x/third-party-tools/contract-wizard/index.md index 2da312d42d..9402f9253d 100644 --- a/docs/third-party-tools/contract-wizard/index.md +++ b/versioned_docs/version-4.x/third-party-tools/contract-wizard/index.md @@ -14,7 +14,7 @@ To open the app follow [this link](https://contractwizard.xyz) ::: -![Contract Wizard Img](./assets/landing.png) +![Contract Wizard Img](/img/third-party-tools/contract-wizard/landing.png) ## Purpose of the Polkadot Contract Wizard diff --git a/versioned_docs/version-5.x/third-party-tools/ink-analyzer.md b/versioned_docs/version-4.x/third-party-tools/ink-analyzer.md similarity index 98% rename from versioned_docs/version-5.x/third-party-tools/ink-analyzer.md rename to versioned_docs/version-4.x/third-party-tools/ink-analyzer.md index ef00d9619b..4bb152a13a 100644 --- a/versioned_docs/version-5.x/third-party-tools/ink-analyzer.md +++ b/versioned_docs/version-4.x/third-party-tools/ink-analyzer.md @@ -13,7 +13,7 @@ ink! analyzer aims to improve ink! language support in [integrated development e ## Problem -While ink! developers can leverage Rust tooling and excellent IDE/code editor support via [rust-analyzer](https://rust-analyzer.github.io/) and [IntelliJ Rust](https://www.jetbrains.com/rust/) because ["ink! is just standard Rust in a well-defined "contract format" with specialized `#[ink(…)]` attribute macros"](https://use.ink/getting-started/creating-an-ink-project), +While ink! developers can leverage Rust tooling and excellent IDE/code editor support via [rust-analyzer](https://rust-analyzer.github.io/) and [IntelliJ Rust](https://www.jetbrains.com/rust/) because ["ink! is just standard Rust in a well-defined "contract format" with specialized `#[ink(…)]` attribute macros"](../getting-started/creating.md), relying on only generic Rust language support in IDEs, code editors and other development tools has some significant limitations for the developer experience including: - No language support (e.g. diagnostic errors/warnings and quick fixes) for ink!'s domain specific semantic rules for smart contracts (e.g. exactly one `#[ink(storage)]` struct, at least one `#[ink(message)]` method and the same for `#[ink(constructor)]`, ink! attributes should be applied to items of the correct type e.t.c). diff --git a/versioned_docs/version-5.x/third-party-tools/inkathon.mdx b/versioned_docs/version-4.x/third-party-tools/inkathon.mdx similarity index 96% rename from versioned_docs/version-5.x/third-party-tools/inkathon.mdx rename to versioned_docs/version-4.x/third-party-tools/inkathon.mdx index da7f5a35e1..790d55bf00 100644 --- a/versioned_docs/version-5.x/third-party-tools/inkathon.mdx +++ b/versioned_docs/version-4.x/third-party-tools/inkathon.mdx @@ -1,9 +1,9 @@ --- -title: ink!athon dApp Boilerplate +title: ink!athon DApp Boilerplate slug: /getting-started/inkathon --- -# ink!athon dApp Boilerplate +# ink!athon DApp Boilerplate ink!athon is a starter kit for full-stack dApp development with ink! smart contracts and a React-based frontend in one place. With convenient helper scripts and a pre-configured project setup, it lets you scaffold any dApp quickly. It's developed by the same team that is behind [AZERO.ID](https://azero.id), where this boilerplate is used in production. diff --git a/docs/third-party-tools/openbrush.md b/versioned_docs/version-4.x/third-party-tools/openbrush.md similarity index 100% rename from docs/third-party-tools/openbrush.md rename to versioned_docs/version-4.x/third-party-tools/openbrush.md diff --git a/versioned_docs/version-5.x/third-party-tools/subwallet.md b/versioned_docs/version-4.x/third-party-tools/subwallet.md similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/subwallet.md rename to versioned_docs/version-4.x/third-party-tools/subwallet.md diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/Figure.tsx b/versioned_docs/version-4.x/third-party-tools/swanky/Figure.tsx similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/Figure.tsx rename to versioned_docs/version-4.x/third-party-tools/swanky/Figure.tsx diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/SwankySuiteAstar.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/SwankySuiteAstar.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/SwankySuiteAstar.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/SwankySuiteAstar.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/acc-create.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/acc-create.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/acc-create.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/acc-create.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/check.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/check.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/check.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/check.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/compile.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/compile.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/compile.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/compile.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-commands.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-commands.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-commands.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-commands.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-explain.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-explain.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-explain.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-explain.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-new.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-new.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-new.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-new.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-query.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-query.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-query.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-query.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-tx.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-tx.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/contract-tx.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/contract-tx.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/deploy.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/deploy.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/deploy.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/deploy.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/folder-structure.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/folder-structure.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/folder-structure.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/folder-structure.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/help.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/help.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/help.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/help.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/init.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/init.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/init.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/init.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/node-start.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/node-start.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/node-start.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/node-start.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/test-report.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/test-report.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/test-report.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/test-report.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/assets/test.png b/versioned_docs/version-4.x/third-party-tools/swanky/assets/test.png similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/assets/test.png rename to versioned_docs/version-4.x/third-party-tools/swanky/assets/test.png diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/cli.md b/versioned_docs/version-4.x/third-party-tools/swanky/cli.md similarity index 99% rename from versioned_docs/version-5.x/third-party-tools/swanky/cli.md rename to versioned_docs/version-4.x/third-party-tools/swanky/cli.md index ce5a9cf8a1..ef23e454d1 100644 --- a/versioned_docs/version-5.x/third-party-tools/swanky/cli.md +++ b/versioned_docs/version-4.x/third-party-tools/swanky/cli.md @@ -204,7 +204,7 @@ You can test your contracts using [Mocha](https://mochajs.org/) framework and [C :::note Please note these tests are not ink! E2E tests, but are written in TypeScript, and require a local node to be running. -You can get more information on ink! E2E test framework in the [ink! documentation](https://use.ink/basics/contract-testing/#end-to-end-e2e-tests). +You can get more information on ink! E2E test framework in the [ink! documentation](../../basics/testing.md#end-to-end-e2e-tests). ::: A contract template will provide you with a simple test as well, which you can use as a starting point. The tests utilize [@polkadot/api](https://polkadot.js.org/docs/api/) library, and contract types generated by [typechain-polkadot](https://github.com/727-Ventures/typechain-polkadot). diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/index.md b/versioned_docs/version-4.x/third-party-tools/swanky/index.md similarity index 100% rename from versioned_docs/version-5.x/third-party-tools/swanky/index.md rename to versioned_docs/version-4.x/third-party-tools/swanky/index.md diff --git a/versioned_docs/version-5.x/third-party-tools/swanky/node.md b/versioned_docs/version-4.x/third-party-tools/swanky/node.md similarity index 97% rename from versioned_docs/version-5.x/third-party-tools/swanky/node.md rename to versioned_docs/version-4.x/third-party-tools/swanky/node.md index 71fcc0dcf2..e337afe03d 100644 --- a/versioned_docs/version-5.x/third-party-tools/swanky/node.md +++ b/versioned_docs/version-4.x/third-party-tools/swanky/node.md @@ -99,7 +99,7 @@ To print errors and contract debug output to the console log, supply `-lerror,ru Important: Debug output is only printed for RPC calls or off-chain tests ‒ not for transactions. -See the ink! [FAQ](https://use.ink/faq/#how-do-i-print-something-to-the-console-from-the-runtime) for more details: How do I print something to the console from the runtime?. +See the ink! [FAQ](../../faq/faq.md#how-do-i-print-something-to-the-console-from-the-runtime) for more details: How do I print something to the console from the runtime?. ### Connect with Polkadot.js Apps Portal diff --git a/versioned_docs/version-5.x/basics/env-functions.md b/versioned_docs/version-5.x/basics/env-functions.md deleted file mode 100644 index 76cb516339..0000000000 --- a/versioned_docs/version-5.x/basics/env-functions.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Environment Functions -slug: /basics/environment-functions ---- - - - -# Environment Functions - -ink! exposes a number of handy environment functions. -A full overview [is found here](https://docs.rs/ink_env/5.0.0-rc.1/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/5.0.0-rc.1/ink_env/fn.caller.html): Returns the address of the caller of the executed contract. -* [`account_id()`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/fn.account_id.html): Returns the account ID of the executed contract. -* [`balance()`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/fn.balance.html): Returns the balance of the executed contract. -* [`block_number()`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/fn.block_number.html): Returns the current block number. -* [`emit_event(…)`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/fn.emit_event.html): Emits an event with the given event data. -* [`transfer(…)`](https://docs.rs/ink_env/5.0.0-rc.1/ink_env/fn.transfer.html): Transfers value from the contract to the destination account ID. -* [`hash_bytes(…)`](https://docs.rs/ink_env/5.0.0-rc.1/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/5.0.0-rc.1/ink_env/#functions). diff --git a/versioned_docs/version-5.x/basics/events.md b/versioned_docs/version-5.x/basics/events.md deleted file mode 100644 index a111bda578..0000000000 --- a/versioned_docs/version-5.x/basics/events.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: Events -slug: /basics/events -hide_title: true ---- - - - -# Events - -An ink! smart contract may define events that it can emit during contract execution. -Emitting events can be used by third party tools to query information about a contract's -execution and state. - -![Contract execution via transaction](/img/events.svg) - -## Example - -The following example ink! contract shows how an event `Transferred` is defined and -emitted in the `#[ink(constructor)]`. - -```rust -#[ink::contract] -mod erc20 { - /// Defines an event that is emitted - /// every time value is transferred. - #[ink(event)] - pub struct Transferred { - from: Option, - to: Option, - value: Balance, - } - - #[ink(storage)] - pub struct Erc20 { - total_supply: Balance, - // more fields ... - } - - impl Erc20 { - #[ink(constructor)] - pub fn new(initial_supply: Balance) -> Self { - let caller = Self::env().caller(); - Self::env().emit_event(Transferred { - from: None, - to: Some(caller), - value: initial_supply, - }); - Self { total_supply: initial_supply } - } - - #[ink(message)] - pub fn total_supply(&self) -> Balance { - self.total_supply - } - } -} -``` - -See our [`ERC20 example contract`](https://github.com/paritytech/ink-examples/blob/main/erc20/lib.rs) -for an elaborate example which uses events. - -## Event Definition - -Since ink! version 5.0, events can be defined independently of the contract which emits them. -Events can now be defined once and shared across multiple contracts. - -This is useful for events for contracts which conform to standards such as ERC-20: -contract indexers/explorers are now able to group all e.g. `Transferred` events. - -This is how an event definition looks: - -```rust -use ink::primitives::AccountId; - -#[ink::event] -pub struct Transferred { - #[ink(topic)] - from: Option, - #[ink(topic)] - to: Option, - amount: u128, -} -``` -> Note that generics are [not currently supported](https://github.com/paritytech/ink/issues/2044) -> , so the concrete types of `Environment` -> specific types such as `AccountId` must match up with the types used in the contract. - -This definition can exist within a contract definition module (inline events), in a different -module in the same crate or even in a different crate to be shared by multiple contracts. - -### Legacy syntax for inline Event definitions - -Events defined within a `#[ink::contract]` module can continue to use the original syntax for an -event definition, using the `#[ink(event)]` attribute. Under the covers this is simply expanded -to the new top level `#[ink::event]` macro, so both events defined using the legacy style and -using the new `event` attribute macro directly will behave exactly the same. - -### Topics - -When an event is emitted, 0 or more topics can be associated with it. The event is then indexed -together with other events with the same topic value. - -An event's fields can be annotated with `#[ink(topic)]` (see example), which will result in a -topic derived from the value of that field being emitted together with the event. - -Topics are by default a 32 byte array (`[u8; 32]`), although this is configurable on the -Polkadot SDK runtime level. If the SCALE encoded bytes of a field value are `<= 32`, then the -encoded bytes are used directly as the topic value. - -For example, in the common case of indexing a field of type `AccountId`, where the default -`AccountId` type is 32 bytes in length, the topic value will be the encoded account id itself. This -makes it easy to filter for all events which have a topic of a specific `AccountId`. - -If however the size of the encoded bytes of the value of a field exceeds 32, then the encoded -bytes will be hashed using the `Blake2x256` hasher. - -> Topics are a native concept in the Polkadot SDK, and can be queried via [`EventTopics`](https://docs.rs/frame-system/latest/frame_system/pallet/storage_types/struct.EventTopics.html) - -How to choose which fields to make topics? A good rule of thumb is to ask yourself if somebody -might want to search for this topic. For this reason the `amount` in the example `Transferred` event -above was not made indexable ‒ there will most probably be a lot of different events with differing -amounts each. - -#### Signature Topic - -By default all events have a signature topic. This allows indexing of all events of the same -type, emitted by different contracts. The `#[ink::event]` macro generates a signature topic at -compile time by hashing the name of the event concatenated with the *names of the types* of the all -the field -names: -``` -blake2b("Event(field1_type,field2_type)")` -``` -So for our `Transferred` example it will be: -``` -blake2b("Transferred(Option,Option,u128)")` -``` - -:::caution -Important caveat: because the *name* of the field type is used, refactoring an event -definition to use a type alias or a fully qualified type will change the signature topic, even -though the underlying type is the same. Two otherwise identical definitions of an event with the -same name and same field types but different field type names will have different signature -topics. -::: - -When decoding events emitted from a contract, signature topics are now required to determine which -type of event to decode into. - -#### Anonymous Events - -Events annotated with `anonymous` will not have a signature topic generated and published with the -event. - -For inline events, this can be done by marking the event with the `anonymous` attribute e.g. - -```rust -#[ink(event, anonymous)] -pub struct Event { .. } -``` -or -```rust -#[ink(event)] -#[ink(anonymous)] -pub struct Event { .. } -``` - -For events defined using the `#[ink::event]` macro, the `anonymous` flag needs to be added as an -argument: - -```rust -#[ink::event(anonymous)] -pub struct Event { .. } -``` - -Without a signature topic, indexers will not be able to index over the type of the event, which -may be desirable for some contracts, and would be a small gas cost optimization if necessary. - -However, when interacting with the contract from a client, no signature topic means that another -way is required to determine the type of the event to be decoded into (i.e. how do we know it is -a `Transferred` event, not an `Approval` event. One way would be to try decoding for each type -of event defined in the metadata of the contract until one succeeds. If calling a specific -`message`, it may be known up front what type of event that message will raise, so the client -code could just decode into that event directly. - -## Emitting Events in a Constructor - -In a constructor events are emitted via `Self::env().emit_event()`. -See this example: - -```rust -#[ink(constructor)] -pub fn new(initial_value: Balance) -> Self { - let caller = Self::env().caller(); - let mut balances = HashMap::new(); - balances.insert(caller, initial_supply); - - Self::env().emit_event(Transferred { - from: None, - to: Some(caller), - amount: initial_supply - }); - - Self { total_supply: initial_supply, balances } -} -``` - -## Emitting Events from Messages - -In a message events are emitted via `self.env().emit_event()`: - -```rust -#[ink(message)] -pub fn transfer(&mut self, to: AccountId, amount: Balance) -> Result { - let from = self.env().caller(); - // implementation hidden - self.env().emit_event(Transferred { - from: Some(from), - to: Some(to), - amount - }); - Ok(()) -} -``` - -## Cost of using Events - -When using events and topics, developers should be mindful of the costs associated. Firstly: if -optimizing for contract size, using events will increase the size of the final code size. So -minimizing or eliminating event usage where necessary will reduce contract size. The same can be -said for the execution (aka gas) costs when using events. We recommend considering the cost of -events when using them, and measuring the code size and gas costs with different usage patterns -when optimizing. diff --git a/versioned_docs/version-5.x/macros-attributes/anonymous.md b/versioned_docs/version-5.x/macros-attributes/anonymous.md deleted file mode 100644 index 99467f177a..0000000000 --- a/versioned_docs/version-5.x/macros-attributes/anonymous.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "#[ink(anonymous)]" -slug: /macros-attributes/anonymous -hide_title: true ---- - - - -Applicable to ink! events. - -Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as -topic upon emitting. Similar to anonymous events in Solidity. - -Anonymous events have similar semantics as in Solidity in that their event signature won't be -included in their event topics serialization to reduce event emitting overhead. This is -especially useful for user defined events. - -The signature of the event is by default one of the topics of the event, except if you annotate the -event with `#[ink(anonymous)]`. The attribute implies that it is not possible to filter for -specific anonymous events by the signature topic. - -## Example - -```rust -#[ink(event)] -#[ink(anonymous)] -pub struct MyEvent { - #[ink(topic)] - field_1: i32, - field_2: bool, -} -``` - -The equivalent syntax for standalone `#[ink::event]` definitions (not defined inline in a -contract) is: - -```rust -#[ink::event(anonymous)] -pub struct MyEvent { - #[ink(topic)] - field_1: i32, - field_2: bool, -} -``` - - - diff --git a/versioned_sidebars/version-5.x-sidebars.json b/versioned_sidebars/version-4.x-sidebars.json similarity index 70% rename from versioned_sidebars/version-5.x-sidebars.json rename to versioned_sidebars/version-4.x-sidebars.json index 24b016a3d7..0ab481c43d 100644 --- a/versioned_sidebars/version-5.x-sidebars.json +++ b/versioned_sidebars/version-4.x-sidebars.json @@ -4,7 +4,6 @@ "intro/intro", "intro/why-rust", "intro/why-webassembly", - "intro/where-to-deploy", "intro/polkadot", "intro/how-it-works", "intro/ink-vs-solidity", @@ -28,12 +27,13 @@ "basics/events", "basics/selectors", "basics/trait-definitions", - "basics/gas", "basics/cross-contract-calling", "basics/upgradeability", "basics/env-functions", "basics/environment", "basics/metadata", + "basics/testing", + "basics/debugging", { "type": "category", "label": "Verification", @@ -43,25 +43,6 @@ ] } ], - "Testing & Debugging": [ - "testing/overview", - "testing/off-chain", - "testing/drink", - "testing/e2e", - "testing/testing-with-live-state", - { - "type": "category", - "label": "Testnet", - "items": [ - "testing/testnet/overview", - "testing/testnet/faucet" - ], - "link": { - "type": "doc", - "id": "testing/testnet/overview" - } - } - ], "Macros & Attributes": [ "macros-attributes/overview", "macros-attributes/contract", @@ -80,26 +61,11 @@ ], "Storage & Data Structures": [ "datastructures/overview", - "datastructures/storagevec", "datastructures/mapping", "datastructures/storage-layout", "datastructures/custom", "datastructures/storage-in-metadata" ], - "Linter": [ - "linter/overview", - { - "type": "category", - "label": "Linting rules", - "items": [ - "linter/rules/no_main", - "linter/rules/primitive_topic", - "linter/rules/storage_never_freed", - "linter/rules/strict_balance_equality", - "linter/rules/non_fallible_api" - ] - } - ], "Frontend Development": [ "frontend/overview" ], @@ -107,17 +73,18 @@ "examples/contracts", "examples/dapps" ], - "Standards": [ - "standards/overview" + "ink!ubator": [ + "inkubator/overview" ], - "Funding Programs": [ - "funding-programs/overview" + "Testnet": [ + "testnet/overview", + "testnet/faucet" ], "Third Party Tools & Libraries": [ - "third-party-tools/inkathon", + "third-party-tools/openbrush", { "type": "category", - "label": "Swanky Suite", + "label": "Swanky suite", "items": [ "third-party-tools/swanky/cli", "third-party-tools/swanky/node" @@ -128,11 +95,12 @@ } }, "third-party-tools/ink-analyzer", - "third-party-tools/subwallet" + "third-party-tools/inkathon", + "third-party-tools/subwallet", + "third-party-tools/contract-wizard/index" ], "FAQ": [ "faq/faq", - "faq/migrating-from-ink-4-to-5", "faq/migrating-from-ink-3-to-4" ], "Brand Assets": [ @@ -142,4 +110,4 @@ "brand-assets/stickers" ] } -} +} \ No newline at end of file diff --git a/versions.json b/versions.json index c83af3ab28..7bdae8aa87 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,4 @@ [ "3.x", - "5.x" + "4.x" ]