===========================================
INK! COMPREHENSIVE DOCUMENTATION
Smart Contract Development on Polkadot
===========================================

TABLE OF CONTENTS
=================
1. RECOMMENDED TESTNET: PassetHub
2. RELATED DOCUMENTATION
3. QUICK START
4. BACKGROUND CONCEPTS
   - Smart Contracts vs. Polkadot Parachains
   - ink! vs. CosmWasm
   - ink! vs. Solidity
5. DEVELOPMENT WORKFLOW
   - Dependencies and Environment Setup
   - Compile and Test
   - Deploy and Interact
6. CONVERTING SOLIDITY TO INK!
   - Step-by-step conversion guide
   - Syntax equivalencies
7. BEST PRACTICES AND TIPS

===========================================

🌐 1. RECOMMENDED TESTNET: PassetHub
==================================
**Default Network for ALL Development:**
- Network: PassetHub Testnet (ParaID 1111)
- RPC: wss://testnet-passet-hub.polkadot.io
- Use this for deployment, testing, and contract interactions
- DO NOT use production/mainnet unless explicitly requested

IMPORTANT: This documentation covers the ink! smart contract language in detail.
For tooling and workflow automation, see pop-cli-comprehensive-guide.txt.

2. RELATED DOCUMENTATION:
==========================
- pop-cli-comprehensive-guide.txt: Complete Pop CLI tooling guide (recommended for development workflow)
- ink-technical-guide.txt: Deep technical implementation details
- xcm-comprehensive-guide.txt: Cross-chain messaging integration (theory and patterns)
- xcm-ink-examples-guide.txt: Real-world XCM contract examples with complete code

3. QUICK START:
===============
For the fastest way to get started with ink! development, use Pop CLI:
1. Install Pop CLI: brew install r0gue-io/pop-cli/pop
2. Create contract: pop new contract my_contract
3. Build: pop build
4. Test: pop test
5. Deploy: pop up --url wss://testnet-passet-hub.polkadot.io --use-wallet
   IMPORTANT: Capture the contract address from the deployment output!

See pop-cli-comprehensive-guide.txt for complete Pop CLI documentation.

===========================================

# Directory Structure
```
docs/
  background/
    contracts-vs-parachains.md
    ink-vs-cosmwasm.md
    ink-vs-solidity.md
    migrate-to-parachain.md
    polkadot-sdk.md
    why-riscv.md
    why-rust.md
  basics/
    abi/
      all.md
      ink.md
      overview.md
      solidity.md
    metadata/
      ink-format.md
      overview.md
      solidity-format.md
    contract-template.md
    contract-verification.md
    cross-contract-calling.md
    env-functions.md
    environment.md
    events.md
    gas.md
    mutating-values.md
    precompiles.md
    reading-values.md
    selectors.md
    storing-values.md
    trait-definitions.md
    upgradeability.md
    xcm.md
  datastructures/
    custom.md
    mapping.md
    overview.md
    storage-in-metadata.md
    storage-layout.md
    storagevec.md
  debugging/
    decoding.md
    events.md
    overview.md
    precompiles.md
    replays.md
    return_value.md
    sandbox.md
    tracing.md
  faq/
    faq.md
    migrating-from-ink-3-to-4.md
    migrating-from-ink-4-to-5.md
    migrating-from-ink-5-to-6.md
  getting-started/
    assets/
      canvas-connect-to-local.png
      flipper-false.png
      flipper-instantiate-01.png
      flipper-instantiate-02.png
      flipper-instantiate-03.png
      flipper-instantiate-04.png
      flipper-true.png
      send-as-transaction.png
      start-substrate-node.png
    calling.md
    compiling.md
    creating.md
    deploying.md
    setup.md
  integrations-and-sdks/
    javascript-typescript/
      core-libraries.md
      react.md
    ethereum-compatibility.md
    other-languages.md
    overview.md
  intro/
    intro.mdx
    overview.md
    tutorials-examples.md
    where-to-deploy.md
  linter/
    rules/
      no_main.md
      non_fallible_api.md
      primitive_topic.md
      storage_never_freed.md
      strict_balance_equality.md
    overview.md
  macros-attributes/
    anonymous.md
    constructor.md
    contract_ref.md
    contract.md
    default.md
    error.md
    event.md
    implementation.md
    message.md
    name.md
    namespace.md
    overview.md
    payable.md
    selector.md
    storage.md
    topic.md
    trait_definition.md
  testing/
    testnet/
      faucet.md
      Faucet.tsx
      overview.md
    e2e.md
    overview.md
    sandbox.md
    testing-with-live-state.md
    unit-integration.md
```

# Files

## File: docs/background/contracts-vs-parachains.md
````markdown
---
title: Smart Contracts vs. Parachains
hide_title: true
slug: /background/smart-contracts-vs-parachains
---

<head>
    <meta name="description" content="Comparison of Polkadot Parachains and Smart Contracts." />
    <meta name="keywords" content="Polkadot, Parachain, Smart Contracts" />
    <meta property="og:title" content="Smart Contracts vs. Polkadot Parachains" />
    <meta property="og:description" content="Comparison of Polkadot Parachains and Smart Contracts." />
</head>

![Polkadot Title Picture](/img/title/polkadot.svg)

# Smart Contracts vs. Polkadot Parachains

One of the first questions we typically get when somebody learns about the Polkadot SDK is when to develop a
parachain vs. when to develop a smart contract.

## The Difference
The distinction here is that in the context of Polkadot and Kusama a parachain leases a slot for a couple of months for up to two years. The deal with a lease is that the parachain gets a fixed slot for executing its business logic (typically referred to as its _state transition function_) and can persist its modified state in a block. In Polkadot SDK terminology this state transition function is called the chain's _runtime_.

The distinction to other ecosystems here is that, in the context of Polkadot, parachains and smart contracts exist at different layers of the stack: _smart contracts sit on top of parachains_. Parachains would usually be described as layer-1 blockchains — except for that they don't have to build their own security, are upgradable, and interoperable.

## Polkadot Parachains
It's noteworthy that a parachain's state transition function doesn't get further validated — it's up to the parachain how it utilizes its slot time. The parachain already pre-paid for its slot when it won the slot auction on Polkadot or Kusama. This means the parachain can build its own (blockchain) world! For example, it can decide on how transaction fees are charged ‒ or even if transaction fees are charged at all. These options are crucial when building new or more user-friendly business models. 

Other distinguishing factors between parachains that we observe in the wild are differences in how governance works or the crypto-economics. There are some constraints on how the parachain can build its world though. Like physics in the real world it has to adhere to certain ground rules. For Polkadot and Kusama that's for example the consensus algorithm for the Relay Chain to communicate with the parachain. From those ground rules the advantages of Polkadot and Kusama emerge. Advantages like the aforementioned shared security, cross-chain communication, or guaranteed execution slot time.

## Smart Contracts
For smart contracts, on the other hand, an existing parachain has to include the `pallet-revive` for users to deploy smart contracts. The deployed smart contract is always untrusted code. Anyone (or any program) that has tokens of the chain can upload a smart contract without requiring permission. Smart contracts allow _permissionless_ deployment of _untrusted_ programs on a blockchain. The `pallet-revive` has to assume that these programs are adversarial, it has to put a number of safety pillars in place to ensure that the contract can not e.g. stall the chain or cause state corruption of other contracts. For `pallet-revive` those safety pillars include mechanisms like gas metering or deposits for storing data on-chain.

_To restate this important distinction: developing a parachain runtime is different from developing a smart contract — a smart contract sits on top of a parachain_.

## The Trade-off

![Smart Contract vs. Parachain](../../static/img/smart-contract-vs-parachain.svg)

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.
````

## File: docs/background/ink-vs-cosmwasm.md
````markdown
---
title: ink! vs. CosmWasm
slug: /background/ink-vs-cosmwasm
hide_title: true
---

<head>
    <meta name="title" content="Polkadot's ink! vs. CosmWasm" />
    <meta name="description" content="Comparison of Polkadot's ink! vs. CosmWasm." />
    <meta name="keywords" content="Polkadot, ComsWasm, Cosmos, ink!, Smart Contracts" />
    <meta property="og:title" content="ink! vs. CosmWasm" />
    <meta property="og:description" content="Comparison of Polkadot's ink! vs. CosmWasm." />
</head>

![Cosmwasm Title Picture](/img/title/cosmwasm.svg)

# ink! vs. CosmWasm

This is a short comparison between [ink!](https://github.com/use-ink/ink/)
and [CosmWasm](https://github.com/CosmWasm/cosmwasm) meant to onboard
developers coming from the Cosmos ecosystem.

## Architecture

CosmWasm is modular, meaning that any blockchain using the Cosmos SDK can add smart
contract support to their chain. That is similar to the [Polkadot SDK](https://polkadot.com/platform/sdk)
approach, where chains have the option to add `pallet-revive` to their runtime.

Aside from that, the architecture philosophy is likely the point where CosmWasm and ink!
differ the most. CosmWasm follows the actor model design pattern, while ink! follows a
synchronous execution model. That means some fundamental differences in how the source
code is structured.

The main entry point functions of CosmWasm contracts are:

- `instantiate` which bootstraps the initial contract state (assuming it's already been
  deployed).
- `execute` which has the actor perform operations to its internal state.
- `query` which retrieves data from the actor’s internal state.

An ink! contract can have as many public dispatchables as the developer desires, and
differently from CosmWasm, it doesn’t rely on JSON schemas for defining how the messages
are structured.

Instead, ink! makes heavy usage of Rust macros. The main ink! macros are:

- `#[ink(constructor)]` which is called when the contract is deployed, and is responsible
  for bootstrapping the initial contract state into the storage. It is analogous to the
  CosmWasm `instantiate` function.
- `#[ink(storage)]` which annotates a struct that represents the contract's internal
  state.
- `#[ink(message)]` which marks a function as a public dispatchable, meaning that it is
  exposed in the contract interface to the outside world. This macro can make a function
  behave analogously to CosmWasm’s `execute` and `query` functions. This depends on how it
  affects the internal contract state and what the return types.
- `#[ink(event)]` and `#[ink(topic)]` which annotates a struct and its members as the
  events and topics that the contract might emit.

There are other ink! macros, for which details can be found at [Macros & Attributes](../macros-attributes/overview.md).

## Unit Testing

Unit testing in CosmWasm is quite similar to ink!. Both use the conventional Rust
`#[cfg(test)]` macro and set up a mock on-chain environment.

While CosmWasm unit tests have different modules for each of the three main entry-point
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](../testing/unit-integration.md).

## Compiler

CosmWasm uses [cargo-wasm](https://docs.rs/crate/cargo-wasm/latest) as its main
compiler, while ink! uses [Pop CLI](https://github.com/r0gue-io/pop-cli) as the
recommended development tool. Pop CLI provides an all-in-one solution for building,
testing, and deploying ink! contracts with an intuitive developer experience.

# Local Development Network

In terms of local development networks, the [cosmos/gaia](https://github.com/cosmos/gaia)
repository acts as the basic template for a generic Cosmos node. With the addition of the
`x/wasm` module and some clean-up, this template repository becomes
[wasmd](https://github.com/CosmWasm/wasmd), the entry point for CosmWasm development.

In terms of Polkadot SDK, [`polkadot-sdk-solochain-template`](https://github.com/paritytech/polkadot-sdk-solochain-template) is a basic generic template of a node.
Similar to `x/wasm`, [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive)
is the module that adds RISC-V smart contract functionality to the chain. 
We provide the [ink-node](https://github.com/use-ink/ink-node), which is analogous to `wasmd` — a basic template node 
for smart contract development.

## Testnets

For CosmWasm development and on-chain testing, `wasmd` can be operated as a local setup
(single or multiple nodes), or connected to the `cliffnet` public test network.

For testing, ink! contracts can be deployed on a few different options:

- Locally, on a single or multiple node setup of [`ink-node`](https://github.com/use-ink/ink-node).
- [PassetHub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftestnet-passet-hub.polkadot.io#/explorer) testnet (ParaID: 1111, RPC: wss://testnet-passet-hub.polkadot.io).

## Development Workflow

### Dependencies and Environment Setup

The first step in CosmWasm development is to
[install dependencies and setup the environment](https://docs.cosmwasm.com/core/installation),
namely Rust, the WebAssembly target, `cargo-generate` and `cargo-run-script`.

For ink! you can also find [a setup guide](../getting-started/setup.md) which will help you
with dependencies, namely Rust and Pop CLI. Pop CLI handles all tooling setup automatically.

### Compile and Test

CosmWasm provides a template at the
[cw-template](https://github.com/CosmWasm/cw-template) repository. In order to generate a new project, all  you have to do is run:

```
cargo generate --git https://github.com/CosmWasm/cw-template.git --name PROJECT_NAME
```

Replacing `PROJECT_NAME` with the name of your project.

Similarly, ink! provides an
[`examples`](https://github.com/use-ink/ink-examples/tree/main) directory of its
main repository.

A contract can be compiled from its directory via:

```
pop build
```

and tested via:

```
pop test
```

### Deploy and Interact

CosmWasm contracts are deployed and instantiated with help of the `wasmd` executable. The
list of step is provided [here](https://docs.cosmwasm.com/wasmd).

ink! contracts are deployed and interacted with using Pop CLI, which provides an intuitive
command-line interface with interactive prompts:

- Deploy: `pop up`
- Call: `pop call`
- [Instructions for Pop CLI](https://learn.onpop.io)
- Web UI alternative: [`contracts-ui`](https://ui.use.ink)
````

## File: docs/background/ink-vs-solidity.md
````markdown
---
title: ink! vs. Solidity
hide_title: true
slug: /background/ink-vs-solidity
---

<head>
    <meta name="title" content="Polkadot's ink! vs. Solidity" />
    <meta name="description" content="Comparison of Polkadot's ink! vs. Solidity." />
    <meta name="keywords" content="Polkadot, Solidity, Ethereum, ink!, Smart Contracts" />
    <meta property="og:title" content="Polkadot's ink! vs. Solidity" />
    <meta property="og:description" content="Comparison of Polkadot's ink! vs. Solidity." />
</head>

![Solidity Title Picture](/img/title/solidity.svg)

# ink! vs. Solidity

The following table gives a brief comparison of features between ink! and Solidity:

<div class="comparison">

|                       | ink!                         | Solidity     |
| :-------------------- |:-----------------------------|:-------------|
| Virtual Machine       | PolkaVM                      | EVM          |
| Encoding              | SCALE or Solidity ABI        | Solidity ABI |
| Language              | Rust                         | Standalone   |
| Overflow Protection   | Enabled by default           | Yes          |
| Constructor Functions | Multiple                     | Single       |
| Tooling               | Most tools that support Rust | Custom       |
| Versioning            | Semantic                     | Semantic     |
| Has Metadata?         | Yes                          | Yes          |
| Multi-File Project    | Yes                          | Yes          |
| Storage Entries       | Variable                     | 256 bits     |
| Supported Types       | Docs                         | Docs         |
| Has Interfaces?       | Yes (Rust Traits)            | Yes          |

</div>

## 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.
The command will set up the boilerplate code for ink!'s "Hello, World!"
(the [`flipper`](https://github.com/use-ink/ink-examples/tree/main/flipper) contract)).

```
pop new contract <contract-name>
```

### 2. Build the contract

```
pop build
```

### 3. Convert Solidity class fields to Rust struct

Solidity is an object-oriented language, and uses classes. ink! (Rust) does not use classes.

An example Solidity class looks like:

<!-- Markdown syntax highlighting does not support Solidity. C++ seems to be the best match -->

```C++
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.1;

contract MyContract {
    bool private _theBool;
    event UpdatedBool(bool indexed _theBool);

    constructor(bool theBool) {
        require(theBool == true, "theBool must start as true");

        _theBool = theBool;
    }

    function setBool(bool newBool) public returns (bool boolChanged) {
        if (_theBool == newBool) {
            boolChanged = false;
        } else {
            boolChanged = true;
        }

        _theBool = newBool;

        // emit event
        emit UpdatedBool(newBool);
    }
}
```

And the equivalent contract in ink! looks like:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod mycontract {
    #[ink(storage)]
    pub struct MyContract {
        the_bool: bool, // class members become struct fields
    }

    #[ink(event)]
    pub struct UpdatedBool {
        #[ink(topic)] // -> indexed
        the_bool: bool,
    }

    impl MyContract {
        #[ink(constructor)]
        pub fn new(the_bool: bool) -> Self {
            assert!(the_bool == true, "the_bool must start as true");
            Self { the_bool }
        }

        #[ink(message)] // functions become struct implementations
        pub fn set_bool(&mut self, new_bool: bool) -> bool {
            let bool_changed: bool;

            if self.the_bool == new_bool{
                bool_changed = false;
            }else{
                bool_changed = true;
            }

            self.the_bool = new_bool;

            self.env().emit_event(UpdatedBool {
                the_bool: new_bool
            });

            // return
            bool_changed
        }
    }
}
```

A few key differences are:

- Solidity class variables / members will be placed in the contract struct in ink!
- All class methods in Solidity are `impl`emented for the contract struct in ink!
- Solidity frequently prefixes variables with an underscore (`_name`). ink! / Rust only prefixes with an underscore for _unused_ variables.
- Solidity uses camelCase. ink! uses snake_case.
- In Solidity, the variable type comes before the variable name (e.g. bool myVar). While ink! specifies var type after the var name (e.g. my_var: bool)

### 4. Convert each function

- Start converting each function one by one.
  - A recommended approach is to, if possible, skip cross-contract calls at first and use mock data instead
  - This way off-chain unit tests can be written to test the core functionality
    - unit tests are off-chain and do not work with cross-contract calls
  - Once fully tested, start adding in cross-contract calls and perform on-chain manual + integration tests
- Ensure that function's visibility (public, private) are matched in ink!
- In Solidity, if a function returns a `bool success`, ink! will use a `Result<()>` instead (`Result::Ok` or `Result::Err`).

Solidity return example:

```c++
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.1;

contract Example {
    uint128 public data;

    constructor(){}

    function setData(uint128 newData) public returns (
        bool success,
        string memory reason
        ) {

        if (newData == 0) {
            return (false, "Data should not be zero");
        }

        data = newData;
        return (true, "");
    }
}
```

The equivalent contract in ink!:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod example {
    #[ink(storage)]
    pub struct Example {
        data: u128,
    }

    #[ink::scale_derive(Encode, Decode, TypeInfo)]
    #[derive(Debug, PartialEq, Eq)]
    pub enum Error {
        DataShouldNotBeZero,
    }

    pub type Result<T> = core::result::Result<T, Error>;

    impl Example {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self { data: 0 }
        }

        #[ink(message)]
        pub fn set_data(&mut self, new_data: u128) -> Result<()> {
            if new_data == 0 {
                return Err(Error::DataShouldNotBeZero);
            }

            self.data = new_data;
            Ok(())
        }
    }
}
```

## Best Practices + Tips

- If the Solidity contract uses a `string`, it is recommended to use a `Vec<u8>` to avoid the overhead of a `String`. See [here](https://substrate.stackexchange.com/questions/1174/why-is-it-a-bad-idea-to-use-string-in-an-ink-smart-contract) for more details on why. The smart contract should only contain the information that strictly needs to be placed on the blockchain and go through consensus. The UI should be used for displaying strings.
- Double check all `.unwrap()`s performed. Solidity does not have as strict checking as ink! does. For example, a mapping field can be accessed as simple as `myMapping[someKey]`. ink!, however, requires `self.my_mapping.get(some_key).unwrap()`. A useful way to handle `None` cases is to use `.unwrap_or(some_val)`.
- Run the contracts node with `ink-node -lerror,runtime::contracts=debug` for debug prints, and errors to be displayed in the nodes console.
- Just as in Solidity, ink! does not have floating point numbers due to the non-deterministic nature. Instead, the frontend should add decimal points as needed.

<!-- TODO: commented out until validity of this is confirmed (references are more efficient for riscv, similar to WASM).
- When passing parameters to a helper, it is recommended to pass references (even for primitives) as RISCV is more efficient with references.
  For example (see [erc20](https://github.com/use-ink/ink-examples/blob/main/erc20/lib.rs) example):

```rust
/// Returns the account balance for the specified `owner`.
///
/// Returns `0` if the account is non-existent.
#[ink(message)]
pub fn balance_of(&self, owner: AccountId) -> Balance {
    self.balance_of_impl(&owner)
}

/// Returns the account balance for the specified `owner`.
///
/// Returns `0` if the account is non-existent.
///
/// # Note
///
/// Prefer to call this method over `balance_of` since this
/// works using references which are more efficient in Wasm.
#[inline]
fn balance_of_impl(&self, owner: &AccountId) -> Balance {
    self.balances.get(owner).unwrap_or_default()
}
```
-->


## Syntax Equivalencies

### `public function`

```c++
// solidity
function fnName() public {}
// or
// by default, functions are public
function fnName() {}
```

```rust
// ink!
#[ink(message)]
pub fn fn_name(&self) {}
```

### `mapping declaration`

```c++
// solidity
mapping(address => uint128) private mapName;
```

```rust
//ink!
use ink::storage::Mapping;

#[ink(storage)]
pub struct ContractName {
    map_name: Mapping<AccountId, u128>,
}
```

### `mapping usage`

```c++
// solidity

// insert / update
aMap[aKey] = aValue;

// get
aMap[aKey]
```

```rust
// ink!

//insert / update
self.a_map.insert(&a_key, &a_value);

// get
self.a_map.get(a_key).unwrap()
```

### `struct`

```c++
// solidity
struct MyPerson{
    address person;
    u64 favNum;
}
```

```rust
// ink!
struct MyPerson {
    person: AccountId,
    fav_num: u64,
}
```

### `assertions / requires`

```c++
// solidity
require(someValue < 10, "someValue is not less than 10");
```

```rust
// ink!
assert!(some_value < 10, "some_value is not less than 10");
```

### `timestamp`

```c++
// solidity
block.timestamp
```

```rust
// ink!
self.env().block_timestamp()
```

### `contract caller`

```c++
// solidity
address caller = msg.sender;
```

```rust
// ink!
let caller: Address = self.env().caller();
```

### `contract's address`

```c++
// solidity
address(this)
```

```rust
// ink!
self.env().account_id()
```

### `bytes`

Solidity has a type `bytes`. `bytes` is (essentially) equivalent to an array of uint8. So, `bytes` in Solidity => `Vec<u8>` or `[u8; ...]` in ink!. See [here](https://ethereum.stackexchange.com/questions/91119/difference-between-byte-and-uint8-datatypes-in-solidity) for more details. If desired, a `bytes` struct can be created in ink! to replicate the `bytes` type in Solidity.

### `uint256`

Solidity uses `uint256` and `uint` to represent a 256-bit type.

Solidity is 256-bit / 32-byte word optimized. Meaning, using `uint256` in Solidity contracts will reduce gas usage -- but increase storage usage. The largest size ink! has built in is a `u128`. ink! compiles to Wasm. The largest primitive Wasm has is 64bit (due to most computers using 64bit). So, there is no benefit to using any larger primitive over a collection.

When porting a `uint256` from Solidity to ink!, it is recommended to, with discretion, determine the range of the value, and choose the appropriate size (u8, u16, u32, u64, u128). If a 256-bit hash value is required, ink! has a `Hash` primitive available. In the event a value needs to be 256-bit, it is recommended to use an array (e.g. `[u64; 4]`).

### `payable`

```c++
// solidity
function myFunction() payable returns (uint64) {}
```

```rust
#[ink(message, payable)]
pub fn my_function(&mut self) -> u64 {}
```

### `received deposit / payment`

```C++
// solidity
msg.value
```

```rust
// ink!
self.env().transferred_value()
```

### `contract balance`

```c++
// solidity
address(this).balance
```

```rust
// ink!
self.env().balance()
```

### `transfer tokens from contract`

```c++
// solidity
recipient.send(amount)
```

```rust
// ink!
if self.env().transfer(recipient, amount).is_err() {
    panic!("error transferring")
}
```

### `events & indexed`

```c++
// solidity

event MyCoolEvent(
    u128 indexed indexedValue,
    u128 notIndexedValue,
);

// emit event
emit MyCoolEvent(someValue, someOtherValue);
```

```rust
// ink!

#[ink(event)]
pub struct MyCoolEvent {
    #[ink(topic)]
    indexed_value: u128,

    not_indexed_value: u128,
}

// emit event
self.env().emit_event(MyCoolEvent {
    indexed_value: some_value,
    not_indexed_value: some_other_value
});
```

### `errors and returning`

Solidity has several error handling mechanisms: `assert`, `require`, `revert`, and `throw`. Each of these will revert the changed state when called. See [this article](https://medium.com/blockchannel/the-use-of-revert-assert-and-require-in-solidity-and-the-new-revert-opcode-in-the-evm-1a3a7990e06e) for details on these.

ink! uses a `Result` enum (`Ok(T)`, `Err(E)`), `assert!` and `panic!`. [This Stack Exchange](https://substrate.stackexchange.com/questions/2391/panic-in-ink-smart-contracts) answer and [GitHub discussion](https://github.com/use-ink/ink/issues/641) provide more details on these.

#### `throw`

Throw is deprecated in Solidity and would throw an invalid opcode error (no details) and revert the state. As an alternative to the `if...{throw;}` pattern in Solidity, a `Result::Err` should be returned for expected errors, and an `assert!` should be used for errors that should not occur.

#### `assert`

In Solidity, `assert` is used as internal guards against errors in the _code_. In general, properly functioning code should never hit a failing assert. `assert` in Solidity does not have error strings. In ink!, use `assert!`. `assert!` will `panic!` if it evaluates to _false_. The state will be reverted, and a `CalleeTrapped` will be returned. The (optional) error string will be printed to the debug buffer.

```rust
// ink!
assert!(caller == owner, "caller is not owner")
```

#### `require and revert`

In Solidity, `require` is used for general (normal) errors -- such as errors that occur based on user input. `require` does have the option for an error string. `revert` is very similar to `require` except that `revert` will be called in `if ... else` chains. Both `require` and `revert` will revert the chain state. In ink!, `if ... { return Err(Error::SomeError) }` should be used for `require` or `revert`. When a `Result::Err` is returned in ink!, then all state is reverted.

In general, `Result::Err` should be used when a _calling contract_ needs to know _why_ a function failed. Otherwise, `assert!` should be used as it has less overhead than a `Result`.

```c++
// Solidity
function myFunction(bool returnError) public pure {
    require(!returnError, "my error here");

    // or

    if returnError {
        revert("my error here");
    }
}
```

```rust
// ink!

#[derive(Debug, PartialEq, Eq)]
#[ink::scale_derive(Encode, Decode, TypeInfo)]
pub enum Error {
    /// Provide a detailed comment on the error
    MyError,
}

// result type
pub type Result<T> = core::result::Result<T, Error>;

// ...

#[ink(message)]
pub fn my_function(&self, return_error: bool) -> Result<()> {
    if return_error{
        return Err(Error::MyError)
    }
    Ok(())
}
```

<!-- TODO: needs to be reworked with ink!'s new storage (allowing nested mappings).
### `nested mappings + custom / advanced structures`

In Solidity, it is easy to do nested mappings. It is not as straightforward in ink!.

imagine the following scenario

```c++
// solidity
contract Dao {
    struct Proposal {
        mapping (address => bool) votedYes
    }

    mapping (address => bool) public isWhitelisted;
    Proposal[] public proposals;
}
```

in ink! this _seems_ like it could be represented like so:

```rust
#[ink::contract]
mod dao {

    use ink::{
        prelude::vec::Vec,
        storage::Mapping,
    };

    #[ink(storage)]
    pub struct Proposal {
        voted_yes: Mapping<AccountId, bool>,
    }

    #[ink(storage)]
    pub struct Dao {
        proposals: Vec<Proposal>,
        is_whitelisted: Mapping<AccountId, bool>,
    }

    impl Dao{
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                is_whitelisted: Mapping::default(),
                proposals: Vec::new(),
            }
        }
    }
}
```

However, this will cause an error due to the nested mapping. [This answer](https://substrate.stackexchange.com/questions/1659/how-to-have-a-mapping-in-a-custom-structure-inside-an-ink-contract) explains in detail why nested mappings are not allowed

So, as of now, to get around this issue an alternate data structure will need to be used. A data-structure that can be interchanged with the `Mapping` syntax and with minimal additional implementations is the `BTreeMap`. `BTreeMap` is less efficient than `Mapping`, but is an easy workaround until nested mappings are allowed. This will be used in the nested struct. Additional `derive`s will need to be added to be compatible with the #[ink(storage)] struct (see below).

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod dao {

    use ink::{
        prelude::{
            collections::BTreeMap,
            vec::Vec,
        },
        storage::Mapping,
    };

    #[derive(Debug)]
    #[ink::scale_derive(Encode, Decode, TypeInfo)]
    pub struct Proposal {
        voted_yes: BTreeMap<AccountId, bool>,
    }

    #[ink(storage)]
    #[derive(Debug)]
    pub struct Dao {
        proposals: Vec<Proposal>,
        is_whitelisted: Mapping<AccountId, bool>,
    }

    impl Dao{
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                is_whitelisted: Mapping::default(),
                proposals: Vec::new(),
            }
        }

        #[ink(message)]
        pub fn add_proposal(&mut self) {
            self.proposals.push(Proposal {
                voted_yes: BTreeMap::new(),
            });
        }

        #[ink(message)]
        pub fn vote(&mut self, proposal_id: u32, vote: bool) {
            let proposal = self.proposals
                .get_mut(proposal_id as usize)
                .unwrap();

            proposal.voted_yes
                .insert(Self::env().caller(), vote);
        }

        #[ink(message)]
        pub fn get_proposal(&self, proposal_id: u32) -> BTreeMap<AccountId, bool> {
            self.proposals
                .get(proposal_id as usize)
                .unwrap()
                .voted_yes
                .clone()
        }
    }
}
```

-->

### `cross-contract calling`
See here to learn the different ways to do [cross-contract calling](../basics/cross-contract-calling.md)

<!-- TODO: cleanup this section 
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)]

// make the structs visible
pub use self::erc20::{
    Erc20,
    // this is necessary
    Erc20Ref,
};

#[ink::contract]
pub mod erc20 {}
```

In the new cross-called contract's Cargo.toml, add (or edit) the following:

```
[lib]
name = "erc20"
path = "lib.rs"
crate-type = [
	# Used for normal contract Wasm blobs.
	"cdylib",
    # Used for ABI generation. Necessary for importing as a dependency
    "rlib",
]

[features]
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](../basics/cross-contract-calling.md)).

Then, In the main contract's Cargo.toml, import the contract that will be cross-called.

```rust
erc20 = { path = "erc20", default-features = false, features = ["ink-as-dependency"] }
```

And make sure to add it to the `std` field of the .toml file.

```rust
[features]
default = ["std"]
std = [
    # ...

    "erc20/std",
]
```

Now, import the cross-called-contract to the main contract:

```rust
// example
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](../basics/cross-contract-calling.md) for a tutorial, and [here](https://github.com/use-ink/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:

   ```rust
   use my_other_contract::MyOtherContractRef;
   // ...
   fn new(contract_id: AccountId) -> Self {
        // for already deployed contract
        let contract_ref: MyOtherContractRef =
            ink_env::call::FromAccountId::from_account_id(contract_id);
        Self {contract_ref}
   }
   ```

Now, to perform the cross-contract call:

```rust
{
    self.contract_ref.some_external_function(a_param);
}
```

Note: as of now (ink! v3.3.1), when using cross-contract calls, emitting events will not work and compile errors will occur. See [issue #1000](https://github.com/use-ink/ink/issues/1000). Furthermore, the compiler will throw an error saying that (for example) Erc20Ref does not implement `SpreadAllocate`. This [issue #1149](https://github.com/use-ink/ink/issues/1149) explains more and has a workaround. These issues will be fixed in [issue #1134](https://github.com/use-ink/ink/issues/1134).
-->

### `submit generic transaction / dynamic cross-contract calling`

invokes function found at `callee` contract address, sends the `transferAmount` to the `callee`, and the `transactionData` payload.

```c++
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.1;

contract CallContract {

    constructor() {}

    function invokeTransaction(
        address payable callee,
        uint transferAmount,
        bytes4 functionSelector,
        string memory transactionData
    ) public returns(bool success, bytes memory message) {

        bytes memory _data = abi
            .encodePacked(functionSelector, transactionData);

        (success, message) = callee
            .call{value: transferAmount}(_data);

        return (success, message);
    }
}
```

The equivalant in Ink!:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod call_contract {
    use ink::{
        env::call::{
            build_call,
            Call,
            ExecutionInput,
            Selector
        },
        prelude::vec::Vec,
    };

    #[ink(storage)]
    #[derive(Default)]
    pub struct CallContract {}

    #[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
    #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
    pub enum Error {
        TransactionFailed,
    }
    type Result<T> = core::result::Result<T, Error>;


    impl CallContract{
        #[ink(constructor)]
        pub fn new() -> Self {
            Default::default()
        }

        #[ink(message, payable)]
        pub fn invoke_transaction(
            &mut self,
            callee: AccountId,
            transfer_amount: u128,
            function_selector: [u8; 4],
            transaction_data: Vec<u8>,
            gas_limit: Option<u64>,
        ) -> Result<()> {

            let transaction_result = build_call::<<Self as ::ink::env::ContractEnv>::Env>()
                .call_type(
                    Call::new(callee) // contract to call
                        .gas_limit(gas_limit.unwrap_or_default())
                        .transferred_value(transfer_amount), // value to transfer with call
                )
                .exec_input(
                    ExecutionInput::new(Selector::new(function_selector))
                        .push_arg(transaction_data), // SCALE-encoded parameters
                )
                .returns::<()>()
                .try_invoke();

            match transaction_result {
                Ok(Ok(_)) => Ok(()),
                _ => Err(Error::TransactionFailed),
            }
        }
    }
}
```

Note: the `function_selector` bytes can be found in the generated `target/ink/<contract-name>.json`.

## Troubleshooting Errors

- `"failed to load bitcode of module '...' "`

This happens when trying to import a contract for cross-contract calling.

**Solution**  
Ensure that the following is added to Cargo.toml contract import:`

```
features = ["ink-as-dependency"]
```

so the import would look like:

```
mycontract = { path = "mycontract/", default-features = false, features = ["ink-as-dependency"]}
```

## unit testing (off-chain)

- Unit tests are an integral part of smart-contract development and ensuring your code works off-chain before testing on-chain.
- To run ink! tests, use the command `pop test`. Add the `--nocapture` flag for debug prints to show.
- From the contract module, make sure to make the contract struct and anything else that is going to be used in the unit tests public. For example:

```rust
// top of file
#![cfg_attr(not(feature = "std"), no_std, no_main)]


pub use self::mycontract::{
    MyContract
};
```

- For more complex testing that requires a running node, such as cross-contract calls,please refer to [the showcased example here](https://github.com/use-ink/ink-examples/tree/main/multi-contract-caller)
- useful code to interact and modify the contract environment for testing

[ink_env docs](https://use-ink.github.io/ink/ink_env/)

```rust
// get the default accounts (alice, bob, ...)
let accounts = ink::env::test::default_accounts::<ink::env::DefaultEnvironment>();
accounts.alice //usage example

// set which account calls the contract
ink::env::test::set_caller::<ink::env::DefaultEnvironment>(accounts.bob);

// get the contract's address
let callee = ink::env::account_id::<ink::env::DefaultEnvironment>();

// set the contracts address.
// by default, this is alice's account
ink::env::test::set_callee::<ink::env::DefaultEnvironment>(callee);

// transfer native currency to the contract
ink::env::test::set_value_transferred::<ink::env::DefaultEnvironment>(2);

// increase block number (and block timestamp).
// this can be placed in a loop to advance the block many times
ink::env::test::advance_block::<ink::env::DefaultEnvironment>();

// generate arbitrary AccountId
AccountId::from([0x01; 32]);

// generate arbitrary Hash
Hash::from([0x01; 32])

// macro for tests that are expected to panic.
#[should_panic]
```
````

## File: docs/background/migrate-to-parachain.md
````markdown
---
title: Migrate an ink! contract to a Parachain
hide_title: true
slug: /background/migrate-ink-contracts-to-polkadot-frame-parachain-rollup
---

![Polkadot Title Picture](/img/title/polkadot.svg)

# Migrate an ink! contract to a Parachain

Smart contracts written in ink! are a great starting point for developing applications in the Polkadot ecosystem. Developers can go from an idea to a fully functioning web3 application "in production" in a matter of hours or days. This allows faster feedback on ideas, to validate whether there is user demand in the first place, and to easily iterate and refine the implementation.

For many applications, smart contracts are good enough. However, they are exposed to the inherent limitations of the smart contract execution environment: 
    
1. Sharing of blockspace with other smart contracts, volatile "gas" fees.
2. Default model enforces gas fees being paid by the end user.
3. Relative poor performance of interpreted smart contract (untrusted) code compared to precompiled Parachain runtime (trusted) code.
4. Limited access to the host chain environment and any special functionality provided by an extensive suite of customisable FRAME pallets.

Once a web3 application has proven it can work, the team may consider "upgrading" to a Parachain to unlock the full power of a dedicated App Chain. Compared to developing and deploying a smart contract, this requires considerably more time and expertise, which is why we encourage to start with ink! where possible, at least at the prototype stage.

Much of the difficulty in launching a parachain comes in configuring a node implementation, bootstrapping and maintaining a collator network, deploying to testnets, managing infrastructure, acquiring "Coretime" (previously via a slot auction). All of which is time consuming and costly. This is important to note because this guide will focus on the migration of the code from ink! to `FRAME`, which might be a learning curve but overall a minor part of the overall migration, and a one-off cost.

## 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 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`

### Similar

The biggest advantage we have when migrating from ink! to `FRAME` is that both are Rust based DSLs, in both cases actual Rust (or Rust-like)  code annotated with attributes expands into Rust code for handling all the boilerplate for integrating into their respective execution environments. Indeed the modern `FRAME 2.0` was originally inspired by the ink! approach of attribute macros annotating Rust code.

So we can assume that the developer performing the migration is already familiar with Rust and its development environment, which is already a huge headstart for developing with `FRAME`. 

Next we can assume some familiarity with the execution environment, after all a contract is running inside of `pallet_contracts` and is invoked in a similar way via a pallet dispatchable, has access to storage (sandboxed to the contract), and can emit events.

### Different

The biggest difference is that a contract is user uploaded and therefore untrusted code, so there are restrictions to what the contract is able to do and it will perform slower because it is interpreted. For example, a contract can only read and write from its own sandboxed storage.

Runtime code built using `FRAME` is trusted, can be precompiled and therefore executes significantly faster (though that may change if/when contracts are able to target [PolkaVM](https://forum.polkadot.network/t/announcing-polkavm-a-new-risc-v-based-vm-for-smart-contracts-and-possibly-more/3811)). Pallets have direct access to other pallets and have full access to the Parachain storage, and the permissioning can be configured as desired.

Because ink! is executing in a more constrained environment, it is able to be much more opinionated and therefore a simpler language. Because execution is metered (pay as you go execution by the user), there is no need to worry about benchmarking for "weight" calculation. `FRAME` is more powerful, but necessarily more complicated.

## Example Migration

We'll use the [`DNS` example](https://github.com/use-ink/ink-examples/blob/main/dns/lib.rs) contract to demonstrate a migration.

### Setup

Start by cloning the [Parachain Template](https://github.com/paritytech/polkadot-sdk-parachain-template) which contains a [template pallet](https://github.com/paritytech/polkadot-sdk-parachain-template/blob/master/pallets/template/src/lib.rs) which we can modify.

Now we will move down the contract from top to bottom and begin the migration of code.

### Event Definitions

First thing we encounter are events. E.g.:

```rust
#[ink(event)]
pub struct Register {
    #[ink(topic)]
    name: Hash,
    #[ink(topic)]
    from: AccountId,
}
```

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
#[pallet::event]
pub enum Event<T: Config> {
    Register {
        name: T::Hash,
        from: T::AccountId,
    },
    SetAddress {
        name: T::Hash,
        from: T::AccountId,
        old_address: Option<T::AccountId>,
        new_address: T::AccountId,
    },
    Transfer {
        name: T::Hash,
        from: T::AccountId,
        old_owner: Option<T::AccountId>,
        new_owner: T::AccountId,
    }
}
```

### Storage

The storage layout of the contract is defined by the following struct:

```rust
#[ink(storage)]
pub struct DomainNameService {
    /// A hashmap to store all name to addresses mapping.
    name_to_address: Mapping<Hash, AccountId>,
    /// A hashmap to store all name to owners mapping.
    name_to_owner: Mapping<Hash, AccountId>,
    /// The default address.
    default_address: AccountId,
}
```
In ink!, the layout of the contract storage is defined by this top level `struct`. A brief recap of how this is used:
- Constructors must return an initialized instance of this struct, which is then written to storage. 
- Non mutable messages e.g. `#[ink(message)] fn message(&self, ..)` will load an instance of this struct and pass it as `&self`.
- Mutable messages e.g. `#[ink(message)] fn message(&mut self, ..)`, will load an instance of the struct and persist it if the message succeeds in executing.
- Fields of type `Mapping` or `Lazy` are not written directly into the same storage slot as the parent, but are wrappers around direct reads/writes to storage under many or a single key respectively.

In `FRAME`, all storage operations happen eagerly via "type aliases" annotated with `#[pallet::storage]`. So for each field in the `#[ink(storage)]` struct, we require a corresponding pallet storage definition.

`default_address: AccountId` translates to:

```rust
#[pallet::storage]
pub type DefaultAddress<T: Config> = StorageValue<_, T::AccountId>;
```

`name_to_address: Mapping<Hash, AccountId>,` translates to a `StorageMap` like so:

```rust
#[pallet::storage]
pub type NameToAddress<T: Config> = StorageMap<_, Blake2_128Concat, T::Hash, T::AccountId>;
```

`name_to_owner: Mapping<Hash, AccountId>,` also translates to a `StorageMap`:

```rust
#[pallet::storage]
pub type NameToOwner<T: Config> = StorageMap<_, Blake2_128Concat, T::Hash, T::AccountId>;
```

Reading and writing these storage values must all be done explicitly, in contrast with ink! which can do so automatically for non "lazy" values. When it comes to migrating the messages, this will be demonstrated.

### Error Definition

Simply copy across the variants of the `enum Error` to the equivalent `#[pallet::error]` definition. In our case we end up with:

```rust
#[pallet::error]
pub enum Error<T> {
    /// Returned if the name already exists upon registration.
    NameAlreadyExists,
    /// Returned if caller is not owner while required to.
    CallerIsNotOwner,
}
```
Note that the `T` generic parameter is not used in this case, the `error` macro handles the generation of `PhantomData<T>`. If we use some environmental types we can use the `T` similar to the event definition.

### Constructors

In this example, the single constructor is simply initializing the storage to empty values. 

```rust
 #[ink(constructor)]
pub fn new() -> Self {
    Default::default()
}
```
This code is executed when the contract instance was initialized.

Our use case is a migration, so we will assume that the existing data must be migrated from contract storage to the pallet storage. This will be covered in the [Data Migration](#data-migration) section.

No code migration is required then for this constructor.

### Messages

#### Mutable

There are 3 mutable messages (that can change the state of the contract): `register`, `set_address` and `transfer`. This guide will demonstrate `register`, and the other two can follow a similar pattern. The message is defined as so, with added numerical comments to show the translation to the equivalent `FRAME` code.

```rust
#[ink(message)]
pub fn register(&mut self, name: Hash) -> Result<()> {
    // 1.
    let caller = self.env().caller();
    // 2.
    if self.name_to_owner.contains(name) {
        return Err(Error::NameAlreadyExists)
    }
    // 3.
    self.name_to_owner.insert(name, &caller);
    // 4.
    self.env().emit_event(Register { name, from: caller });
    // 5.
    Ok(())
}
```

Before proceeding, it is necessary to add a custom `deposit_event` function for raising events which accepts topics:

```rust
impl<T: Config> Pallet<T> {
    fn deposit_event(topics: Vec<T::Hash>, event: Event<T>) {
        <frame_system::Pallet<T>>::deposit_event_indexed(
            &topics,
            <T as Config>::RuntimeEvent::from(event).into()
        )
    }
}
```
Now we can translate the `register` message into a "Dispatchable":

```rust
#[pallet::call_index(0)]
#[pallet::weight(Weight::from_parts(10_000, 0)
    .saturating_add(T::DbWeight::get().reads(1))
    .saturating_add(T::DbWeight::get().writes(1)))]
pub fn register(origin: OriginFor<T>, name: T::Hash) -> DispatchResultWithPostInfo {
    // 1.
    let caller = ensure_signed(origin)?;
    // 2.
    ensure!(!NameToOwner::<T>::contains_key(&name), Error::<T>::NameAlreadyExists);
    // 3.
    <NameToOwner<T>>::insert(name, &caller);
    // 4.
    Self::deposit_event(
        &[name.clone(), T::Hashing::hash_of(&caller)],
        Event::Register { name, from: caller }
    );
    // 5.
    Ok(().into())
}
```
Compare the numbered annotations from the ink! contract message and the `FRAME` dispatchable, and you can see they are very similar, just different APIs for interacting with the environment and with storage.

For `4.`, in `FRAME` we need to generate the topic list manually which is done automatically in ink! via the annotations.

#### Weights

The `pallet::weight` attribute defines the `weight` of the dispatchable i.e. the amount of onchain resources it is estimated to consume. Because we are now writing trusted code, we can define this up front (no runtime gas metering). The number in the `weight` is typically generated via a benchmarking process. It is important to integrate this process and set a non-arbitrary value here before deploying to a production chain. 
You can read more [here](https://docs.polkadot.com/polkadot-protocol/basics/blocks-transactions-fees/fees/).

#### Immutable (read only) messages

`ink!` messages can return a value, which when executed as an RPC "dry-run" (not via a transaction), are used to read the state of contracts. Dispatchables in `FRAME` cannot return values directly. There are two ways to read the state from a FRAME pallet:

1. Reading from `#[pallet::storage]` items directly, client libraries will generate an API to do this from the runtime metadata. See e.g. [`subxt`](https://github.com/paritytech/subxt/blob/master/subxt/examples/storage_fetch.rs)
2. Via runtime APIs, RPC methods that can be wired up directly into query methods on a pallet. See [here](https://docs.polkadot.com/polkadot-protocol/basics/node-and-runtime/#runtime-apis) for more info.

In our case, `1.` is good enough, so the following read only message:

```rust
#[ink(message)]
pub fn get_address(&self, name: Hash) -> AccountId {
    self.get_address_or_default(name)
}

fn get_address_or_default(&self, name: Hash) -> AccountId {
    self.name_to_address
        .get(name)
        .unwrap_or(self.default_address)
}
```
Can be queried *without* any modifications to the `NameToAddress` storage type:

```rust
#[pallet::storage]
pub type NameToAddress<T: Config> = StorageMap<_, Blake2_128Concat, T::Hash, T::AccountId>;
```
`subxt` would generate the following accessor for querying the storage:

```rust
let storage_query = my_custom_chain::storage().dns().name_to_address(&name);

// Use that query to `fetch` a result. This returns an `Option<_>`, which will be
// `None` if no value exists at the given address. You can also use `fetch_default`
// where applicable, which will return the default value if none exists.
let result = api
    .storage()
    .at_latest()
    .await?
    .fetch(&storage_query)
    .await?;
```

### Data Migration

Data migration can be done at either genesis time or once the custom parachain is up and running. 

#### Retrieving the data from the contract

In both cases the first steps are to first download the current state of the contract at a fixed point in time, and then ensuring that no changes can be made to the contract after that. 

This could be done by using `set_code_hash` to update the source code of the contract to a special contract which allows only querying and downloading the state of the current contract, and no mutating messages.

An alternative would be querying the contract storage directly, but currently there are no good tools for this, and it would require some key calculation for retrieving the data at all storage locations. Additionally the contract would still need to be "frozen" somehow to ensure no changes can be made to the contract state.

#### Initializing the pallet 

Once the data has been downloaded and serialized, it can be used to initialize the state of the custom parachain runtime. This can be hardcoded in a `#[pallet::genesis_build]` impl block. See [here](https://docs.polkadot.com/develop/parachains/deployment/generate-chain-specs/) for more info.

Alternatively the state could be initialized via dispatchable extrinsic(s) which initialize the storage.

### Adjusting UIs

User interfaces will need to be adjusted to interact with a pallet rather than a contract. This should be relatively straightforward since client libraries usually have first-class support for interacting with Polkadot SDK pallets, and the signing etc. should already be integrated.
````

## File: docs/background/polkadot-sdk.md
````markdown
---
title: Polkadot SDK and ink!
hide_title: true
slug: /background/polkadot-sdk
---

<head>
    <meta name="description" content="Explanation of how ink! ties into Polkadot SDK and `pallet-revive`." />
    <meta name="keywords" content="Polkadot SDK, ink!, pallet-revive, Smart Contracts" />
    <meta property="og:title" content="How does ink! tie into Polkadot SDK?" />
    <meta property="og:description" content="Explanation of how ink! ties into Polkadot SDK and `pallet-revive`." />
</head>

![Polkadot SDK Title Picture](/img/title/polkadot.svg)

# Polkadot SDK

ink! is a programming language for smart contracts; blockchains built with [the Polkadot SDK](https://github.com/paritytech/polkadot-sdk)
can choose from a number of smart contract languages which one(s) they want to support.
ink! is one of them. It is an opinionated language that we have built by extending the popular Rust programming language with functionality needed to make it smart contract compatible.

## How does ink! tie into Polkadot SDK?

[Polkadot SDK](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html) is a framework for building blockchains – those can be standalone blockchains or blockchains connected to [Kusama](http://kusama.network) or [Polkadot](http://polkadot.network), so called _parachains_. The Polkadot SDK contains a number of modules, in Polkadot SDK terminology those are called _pallets_. Polkadot SDK comes with a set of pallets for many requirements modern blockchains typically have – staking, fungible tokens, non-fungible tokens, governance, etc.

Polkadot SDK also ships with a module for smart contracts, this module is called [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive).
If a parachain is developed in the Polkadot SDK it can easily add smart contract functionality by including this pallet.

How does ink! come into play here? ink! is a programming language, specifically it is an embedded domain-specific language for the popular Rust programming language. This means that you can use all the normal Rust syntax plus some specifics that we added to make the language suitable for the smart contract world. The `pallet-revive` takes these ink! contracts and executes them safely. So in short: _with ink! you can write smart contracts in Rust for blockchains built with the Polkadot SDK that include `pallet-revive`_.

![](/img/ink-pallet-contracts.png)

## How does the `pallet-revive` work?

`pallet-revive` was intentionally designed in a way that it is decoupled from the language that is used to write smart contracts. The pallet is only the execution environment and it takes RISC-V binary files as input. Smart contracts for this pallet have to be compiled to the RISC-V target architecture.

For contract developers this means they can use ink! for writing smart contracts, but can also decide on other languages. 
Right now the pallet supports ink! (Rust) and Solidity (via [Parity's revive compiler](https://github.com/paritytech/revive)).

It's not hard to add new languages. There just needs to be a compiler for the language down to RISC-V bytecode, then it's possible to implement the API of `pallet-revive`. This API at the moment consists of about 50 functions for anything a smart contract may desire: storage access, cryptographic functionality, environmental information like block numbers, access to functions for getting random numbers or self-terminate the contract, etc. Not all of those have to be implemented in the language ‒ the ink! "Hello, World!" requires just six API functions. The following schema depicts this relationship:

![](/img/ink-polkavm-riscv-solidity.svg)

We think this design is more future-proof than some architectures found in competing ecosystems. There is no tight coupling between language and execution environment. RISC-V is an industry standard and a multitude of programming languages can nowadays be compiled down to it. If in, say ten years time, researchers come up with an innovative language for writing smart contracts (or a subset of an existing language) then as long as there is a compiler that supports RISC-V it will be easy to make this language compatible with `pallet-revive`.

## Why include `pallet-revive` on a parachain?

There are a couple use cases for including smart contract functionality on a parachain. We distinguish three big ones.

### Use Case 1: Smart Contracts as "first-class citizens"
The most obvious use case is a parachain which provides smart contracts as a “first-class citizen”, meaning smart contracts are the central value proposition of the chain.

Those chains typically take the off-the-shelf `pallet-revive` and create additional innovation on top of it.
An example for this is [Polkadot](https://onpop.io/).

### Use Case 2: Smart Contracts as "second-class citizens"
There is another not so obvious use case for `pallet-revive`: 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.

The `pallet-revive` provides a [Precompile API](../basics/precompiles.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.

### Use Case 3: Smart Contracts as a first step into Polkadot or Kusama
A third big use case for `pallet-revive` is to prototype an idea as a proof-of-concept smart contract before leasing a dedicated parachain slot on Polkadot or Kusama.

The time to develop a smart contract and deploy it is shorter than the onboarding story for a parachain. One can deploy a proof-of-concept smart contract first, see if it gains traction and the idea holds up to the real world. Only subsequently, once there is a need for e.g. cheaper transaction fees, more efficient execution, or a governance mechanism for the community, the smart contract could be migrated to a dedicated parachain runtime with its own slot. ink! contracts and Polkadot SDK runtimes are both written in Rust and share similar primitives, this enables a clear path to graduate from a smart contract to its own runtime. Developers can reuse large parts of their code, their tests, as well as frontend and client code.

![](/img/ink-gateway.jpg)

## Smart Contracts vs. Parachains
One of the first questions we typically get when somebody learns about Polkadot SDK, Polkadot, or Kusama is when to develop a parachain vs. when to develop a smart contract.

The distinction here is that in the context of Polkadot and Kusama a parachain leases a slot for a couple of months for up to two years. The deal with a lease is that the parachain gets a fixed slot for executing its business logic (typically referred to as its _state transition function_) and can persist its modified state in a block. In the Polkadot SDK terminology this state transition function is called the chain's _runtime_.

The distinction to other ecosystems here is that, in the context of Polkadot, parachains and smart contracts exist at different layers of the stack: _smart contracts sit on top of parachains_. Parachains would usually be described as layer-1 blockchains ‒ except for that they don't have to build their own security, are upgradable, and interoperable.

It's noteworthy that a parachain's state transition function doesn't get further validated ‒ it's up to the parachain how it utilizes its slot time. The parachain already pre-paid for its slot when it won the slot auction on Polkadot or Kusama. This means the parachain can build its own (blockchain) world! For example, it can decide on how transaction fees are charged ‒ or even if transaction fees are charged at all. These options are crucial when building new or more user-friendly business models. Other distinguishing factors between parachains that we observe in the wild are differences in how governance works or the crypto-economics. There are some constraints on how the parachain can build its world though. Like physics in the real world it has to adhere to certain ground rules. For Polkadot and Kusama that's for example the consensus algorithm for the Relay Chain to communicate with the parachain. From those ground rules the advantages of Polkadot and Kusama emerge. Advantages like the aforementioned shared security, cross-chain communication, or guaranteed execution slot time.

For smart contracts, on the other hand, an existing parachain has to include `pallet-revive` for users to deploy smart contracts. The deployed smart contract is always untrusted code. Anyone (or any program) that has tokens of the chain can upload a smart contract without requiring permission. Smart contracts allow _permissionless_ deployment of _untrusted_ programs on a blockchain. The `pallet-revive` has to assume that these programs are adversarial, it has to put a number of safety pillars in place to ensure that the contract can not e.g. stall the chain or cause state corruption of other contracts. For `pallet-revive` those safety pillars include mechanisms like gas metering or deposits for storing data on-chain.

_To restate this important distinction: developing a parachain runtime is different from developing a smart contract ‒ a smart contract sits on top of a parachain_.

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)
````

## File: docs/background/why-riscv.md
````markdown
---
title: Why RISC-V and PolkaVM for Smart Contracts?
hide_title: true
slug: /background/why-riscv-and-polkavm-for-smart-contracts
---

<head>
    <meta name="description" content="What is PolkaVM? And what does it mean for smart contracts in Polkadot." />
    <meta name="keywords" content="Polkadot, PolkaVM, RISC-V, RISCV, Smart Contracts" />
    <meta property="og:title" content="Why RISC-V and PolkaVM for Smart Contracts?" />
    <meta property="og:description" content="What is PolkaVM? And what does it mean for smart contracts in Polkadot." />
    <meta property="og:image" content="https://use-ink.com/img/opengraph/riscv-polkavm.png" />
    <meta property="og:image:width" content="1200" />
    <meta property="og:image:height" content="630" />
    <meta property="og:image:alt" content="RISC-V, PolkaVM, and ink!" />
    <meta property="og:image:type" content="image/png" />
</head>

import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/title/polkadot-riscv.svg')} title="RISC-V" className="titlePic"  />

## 🤔 Shortcomings of WebAssembly for Smart Contracts

From ink! v1 to v5, the execution platform was Substrate's smart contracts
module [`pallet-contracts`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/contracts/).
This pallet required the smart contracts that were uploaded to be in the _WebAssembly
(Wasm) bytecode format_. So ink! contracts were always compiled to a WebAssembly binary.
This could be done by invoking `cargo build`/`rustc` directly or via tooling like
[Pop CLI](https://github.com/r0gue-io/pop-cli) (which handles all compilation
complexity and optimal flags automatically).

As an ongoing research project Parity was always looking at alternatives to WebAssembly
for smart contract execution. Some of those investigations are
persisted in the Polkadot Forum. The forum post on [the eBPF investigation](https://forum.polkadot.network/t/ebpf-contracts-hackathon/1084)
(eBPF is used in Solana) highlights some shortcomings of WebAssembly for smart contracts.

## 🧑‍🔬 RISC-V + PolkaVM 

During 2023, Parity core developer Jan Bujak ([@koute](https://github.com/koute)) did another
exploration on alternatives for WebAssembly. [His forum post](https://forum.polkadot.network/t/exploring-alternatives-to-wasm-for-smart-contracts/2434)
gives a great overview on how he landed at RISC-V and its potential.
His explorations yielded promising results and a new project
was started: [PolkaVM](https://github.com/paritytech/polkavm)
([the announcement contains more info](https://forum.polkadot.network/t/announcing-polkavm-a-new-risc-v-based-vm-for-smart-contracts-and-possibly-more/3811)).
PolkaVM is intended to be a very fast RISC-V based virtual machine. Jan
regularly shared performance benchmarks in the Polkadot Forum. Those were very
good and got community enthusiasm started.
For blockchains a very fast performance correlates with transaction throughput
and transaction costs, which implies improved scalability and reduced costs for users.

## 🤝 `pallet-revive`

Parity in late 2024 forked Substrate's `pallet-contracts` into a new project called
[`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive).
Smart contracts that are uploaded to this new pallet have to be
in the RISC-V bytecode format, and no longer in WebAssembly.

Besides the contract binary format, a number of other significant changes were
made to provide first-class support for Solidity contracts:

    * Extensive changes were made in the inner logic of the pallet to bring its behavior
    closer to the EVM (e.g. types, events, and debugging was changed to be Solidity
    compatible).

    * In the `pallet-contracts` era, the idea for Solidity compatibility was a project
    called [Solang](https://github.com/hyperledger-solang/solang/). It's a Solidity
    compiler that parses Solidity syntax and outputs WebAssembly.
    Parsing the Solidity syntax turned out to be a complex undertaking. Solidity
    as a language is also evolving and provided a moving target.<br/><br/>
    As an iteration on that approach, for `pallet-revive` Parity started a new
    project called [`revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive/src) ᠆
    a compiler from the Solidity bytecode YUL to a RISC-V
    contract that can be executed on `pallet-revive`.
    This bytecode is more stable than the language syntax. Plus Solidity developers
    can continue to use the Solidity compiler `solc` to compile their contracts.

    * An RPC wrapper that maps Ethereum RPC's onto Substrate was created.

At the time of writing, `pallet-revive` is deployed to the Polkadot testnet Westend
(on the AssetHub parachain).
A launch on Polkadot's canary network Kusama is targeted for early Q2/25.
The Polkadot launch is targeted for Q3/25.

## 🙌 Migrating ink! to RISC-V + PolkaVM + `pallet-revive`

`pallet-revive` and RISC-V are seen as the future of smart contracts in the Polkadot
ecosystem. We agree with that vision and are excited to work on making the ink! stack
ready for it!
In autumn 2024 the ink! Alliance created [a Polkadot treasury proposal](https://forum.polkadot.network/t/treasury-ink-alliance-for-a-more-successful-plaza/9692)
around this.
The Polkadot community signaled its alignment and gave us the mandate of
migrating ink! to this new stack.

Hence, v5 of ink! was the last version supporting `pallet-contracts`
and Wasm. We can still backport important fixes, but the coming releases (`>= v6`) will
all no longer be compatible. In case you want to create a PR for a backport, we have
the v5 release branch [here](https://github.com/use-ink/ink/tree/v5.x).
For tooling, Pop CLI v0.10.0 supports ink! v5.

We have created [this migration guide](/docs/v6/faq/migrating-from-ink-5-to-6) from ink! v5 to v6.
All breaking changes and new features are documented there.

What has not yet been migrated is [Contracts UI](https://github.com/use-ink/contracts-ui)
and external libraries (such as [ink!athon](https://inkathon.xyz/), the
[ink! Analyzer VS Code extension](https://marketplace.visualstudio.com/items?itemName=ink-analyzer.ink-analyzer),
`polkadot-js`, …).
We are in contact with the maintainers of these external libraries about migrating 
them as well.
````

## File: docs/background/why-rust.md
````markdown
---
title: Why Rust for Smart Contracts?
hide_title: true
slug: /background/why-rust-for-smart-contracts
---

<head>
    <meta name="description" content="Explanation why Rust is a great language for smart contracts." />
    <meta name="keywords" content="ink!, Rust, Smart Contracts" />
    <meta property="og:title" content="Why Rust for Smart Contracts?" />
    <meta property="og:description" content="Explanation why Rust is a great language for smart contracts." />
</head>

![Rust Title Picture](/img/title/rust.svg)

# Why Rust for Smart Contracts?

ink! chooses not to invent a new programming language, but rather adapt a subset of Rust to serve our purpose.
If this doesn't already convince you, you find many more good reasons here:

* <span class="highlight">Rust is an ideal smart contract language:</span> It is type safe, memory safe, and free of undefined behaviors. It generates small binaries because it doesn’t include extra bloat, like a garbage collector, and advanced optimizations and tree shaking remove dead code. Through compiler flags, Rust can automatically protect against integer overflow.

* <span class="highlight">Rust ecosystem:</span> You gain all the support available to the Rust ecosystem for free. As the language develops, ink! will automatically gain access to new features and functionality, improving how you can write smart contracts in the future.

* <span class="highlight">Tooling:</span> Because ink! follows Rust standards, tools like rustfmt, clippy and rust-analyzer already work out of the box.
The same goes for code formatting and syntax highlighting in most modern text editors.
Also, Rust has an integrated test and benchmark runner,

* <span class="highlight">No overhead:</span> Minimal runtime.

* <span class="highlight">Safe & Efficient:</span> Zero-cost & safe abstractions.

* <span class="highlight">Productive:</span> Cargo + <a href="https://crates.io">crates.io</a> Ecosystem.

* <span class="highlight">1st class RISC-V:</span> The Rust compiler has excellent support for the RISC-V bytecode architecture.
That's because it leverages LLVM as its backend to generate machine code for the RISC-V architecture.

* <span class="highlight">Small Size:</span> In the space-constrained blockchain world size is important. 
The Rust compiler is a great help for that, since it reorders struct fields in order 
to make each type as small as possible. Thus, Rust data structures are very compact,
in many cases even more compact than in C.

ink! is an [Embedded Domain Specific Language](https://wiki.haskell.org/Embedded_domain_specific_language) (eDSL):
a domain-specific language of the Rust programming language.
That means:

* we allow only a subset of the Rust programming language features to be used
  for writing smart contracts. For example, it is not possible do any 
  multi-threading operations or access the web.
* we provide annotations, macros, and primitives that are needed when writing
  smart contracts. For example, annotations on what the smart contract's storage
  struct is or what an event is.

ink! is just standard Rust in a well-defined "contract format" with specialized `#[ink(…)]` attribute macros. These attribute macros tell ink! what the different parts of your Rust smart contract represent, and ultimately allow ink! to do all the magic needed to create Polkadot SDK compatible RISC-V bytecode!
````

## File: docs/basics/abi/all.md
````markdown
---
title: |
  "All" ABI Mode
hide_title: true
slug: /basics/abi/all
---

![Metadata Title Picture](/img/title/metadata-revive.svg)

# "All" ABI Mode

The "all" ABI mode is declared in the contract's manifest file (i.e. the `Cargo.toml` file)
as follows:

```toml
[package.metadata.ink-lang]
abi = "all"
```

When the "all" ABI is specified, the ink! code generator follows both 
the ink! and Solidity ABI specifications, and generates entry points 
for both calling conventions. This means:

- For each message, two selectors are generated, one for [ink!](./ink.md) 
  and another for [Solidity](./solidity.md) ABI.
- Each selector is ABI specific and its entry point uses the corresponding
  input/output encoding/decoding scheme (i.e. entry points for ink! selectors use
  Parity's [SCALE Codec][scale-codec], while entry points for Solidity selectors
  use Solidity ABI encoding/decoding for input/output encoding/decoding).
- Message selector manual overrides 
  (using the [`selector` attribute][selector-attribute]) are respected for 
  ink! ABI entry points but ignored for Solidity ABI entry points
  (i.e. Solidity selectors are **always** generated according to the
  [Solidity ABI specification for function selectors][sol-abi-selector]).
- Multiple constructors are supported (as per the ink! ABI), however, 
  if multiple constructors are defined, then one of the constructors
  must be annotated with the [`default` attribute][default-attribute] 
  to identify it as the constructor to use for Solidity ABI encoded instantiation.
  Note that if only a single constructor is defined, 
  then the `default` attribute annotation is unnecessary.
- Call builders and [contract references][contract-refs] are generated for
  both ink! and Solidity ABI calling conventions.
- Both an ink! and Solidity ABI encoded event are emitted for each call to
  `Self::env().emit_event()` or `self.env().emit_event()`.

:::note
Your contract sizes will get larger if you support both the ink! and Solidity ABI.
:::

:::note
The "all" ABI mode can only be used if all message argument and return types, 
the argument and return type of the constructor used for Solidity ABI encoded instantiation, 
and event argument types can be mapped to equivalent Solidity ABI types 
([more details here][sol-type-mapping]).
:::

[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
[selector-attribute]: ../../macros-attributes/selector.md
[default-attribute]: ../../macros-attributes/default.md
[contract-refs]: ../cross-contract-calling.md#contract-references
[sol-type-mapping]: ../../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping
````

## File: docs/basics/abi/ink.md
````markdown
---
title: ink! ABI
hide_title: true
slug: /basics/abi/ink
---

![Metadata Title Picture](/img/title/metadata-revive.svg)

# ink! ABI

The ink! ABI is declared in the contract's manifest file (i.e. the `Cargo.toml` file) 
as follows:

```toml
[package.metadata.ink-lang]
abi = "ink"
```

When the ink! ABI is specified, the ink! code generator follows the ink! ABI specification. 
This means:

- By default, message selectors are generated according to the
  [ink! ABI specification for selectors][ink-spec-selector].
- Message selectors can be manually overridden using the [`selector` attribute][selector-attribute].
- Parity's [SCALE Codec][scale-codec] is used for input/output encoding/decoding.
- Call builders (used for making cross-contract calls) are generated for ink! ABI
  calling conventions.

[ink-spec-selector]: ../selectors.md
[selector-attribute]: ../../macros-attributes/selector.md
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
````

## File: docs/basics/abi/overview.md
````markdown
---
title: Overview
hide_title: true
slug: /basics/abi
---

![Metadata Title Picture](/img/title/metadata-revive.svg)

# ABI (Application Binary Interface)

An ABI (Application Binary Interface) defines a standard way to interact with contracts
(i.e. it defines the calling conventions to use for public function calls).

More concretely this entails specifications for:
- Computing or defining selectors which identify the entry points for public function calls
- Encoding and decoding public function input and output data
- Encoding and decoding event and error data

With ink! v6, the ink! code generator supports two ABI specifications:

- [Our own native ink! ABI specification](./ink.md)
- [The Solidity ABI specification](./solidity.md)

Supporting the Solidity ABI specification allows: 
- Solidity contracts to transparently call ink! contracts 
- Developers to use Solidity tools (e.g. [ethers.js][ethers-js]) to 
  transparently interact with ink! contracts.

Additionally, the ink! code generator can operate in an [`"all"` ABI mode](./all.md), 
where it generates a binary that supports both the ink! and Solidity ABI specifications 
(i.e. it generates a binary that transparently supports both ink! and Solidity 
calling conventions, and thus transparently supports interactions from 
both ink! and Solidity contracts and external tools).

## Declaring the ABI

The ABI for an ink! contract is declared in the contract's manifest file 
(i.e. the `Cargo.toml` file), as a field `abi` of a custom `ink-lang` table
in the [`package.metadata` table][package-metadata] e.g.

```toml
[package.metadata.ink-lang]
abi = "sol"
```

The default value for `abi` is currently `"ink"`, 
but we might change this before a production release. 

Allowed values are `"ink"`, `"sol"` and `"all"`.

:::note
The Solidity ABI specification can only be used if all constructor and message
argument and return types, and event argument types can be mapped to
equivalent Solidity ABI types ([more details here][sol-type-mapping]).
:::

:::note
Your contract sizes will get larger if you support both the ink! and Solidity ABI.
:::

[package-metadata]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table
[ethers-js]: https://docs.ethers.org/
[sol-type-mapping]: ../../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping
````

## File: docs/basics/abi/solidity.md
````markdown
---
title: Solidity ABI
hide_title: true
slug: /basics/abi/solidity
---

![Metadata Title Picture](/img/title/solidity.svg)

# Solidity ABI

The Solidity ABI is declared in the contract's manifest file (i.e. the `Cargo.toml` file)
as follows:

```toml
[package.metadata.ink-lang]
abi = "sol"
```

When the Solidity ABI is specified, the ink! code generator follows the [Solidity ABI specification][sol-abi]. 
This means:

- Message selectors are **always** generated according to the
  [Solidity ABI specification for function selectors][sol-abi-selector].
- Message selector manual overrides using the [`selector` attribute][selector-attribute] are ignored.
- [Solidity ABI encoding][sol-abi-codec] is used for input/output encoding/decoding.
- Only one constructor can be defined for the contract.
- Call builders are generated for Solidity ABI calling conventions.

:::note
The Solidity ABI specification can only be used if all constructor and message
argument and return types, and event argument types can be mapped to
equivalent Solidity ABI types ([more details here][sol-type-mapping]).
:::

:::info
The contract ABI only describes how external interactions with a contract are
encoded/decoded. 
The internal storage representation of a contract is still done in the SCALE codec!

_Using the Solidity ABI does not imply switching to a different storage layout!_
:::

[sol-abi]: https://docs.soliditylang.org/en/latest/abi-spec.html
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
[selector-attribute]: ../../macros-attributes/selector.md
[sol-abi-codec]: https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding
[sol-type-mapping]: ../../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping
````

## File: docs/basics/metadata/ink-format.md
````markdown
---
title: ink! Format
hide_title: true
slug: /basics/metadata/ink
---

![Metadata Title Picture](/img/title/metadata-revive.svg)

# ink! Metadata

The ink! metadata is generated when a contract is built using Pop CLI, e.g
`pop build`.
It can be found in your contract's target directory under the name
`<contract-name>.json`.

:::note

The metadata is also contained in your `<contract-name>.contract` file. The difference is
that the `.contract` file also contains the binary of your contract (under `source.contract_binary`).

:::

## `<contract-name>.json`
The metadata is defined by the following **required** keys:
- `source`: Information about the contract's binary.
- `contract`: Metadata about the contract.
- `abi`: Raw JSON of the contract's abi metadata, generated during contract compilation.

It may _optionally_ contain the following keys:
- `user`: Additional user-defined metadata.

```json
{
  "source": {
    "hash": "...",
    "language": "...",
    "compiler": "..."
  },
  "contract": {
    "name": "...",
    "version": "...",
    "authors": [
      "..."
    ]
  },
  "spec": {
    "constructors": ["..."],
    "messages": ["..."]
  }
}
```

:::note

Notice that we don't have an `abi` key, but we instead use the `spec` field to specify
the contract's ABI. You can read more about that in the [ABI documentation](#abi).

:::

The following sections will dive deeper into how these sections are made up.

### `source`
This object contains information about how the contract was built.

It consists of the following **required** keys:
- `hash`: The hash of the contract's binary.
- `language`: The language used to write the contract.
- `compiler`: The compiler used to compile the contract.

It may _optionally_ include the following keys:
- `contract_binary`: The actual binary code of the contract, for optionally bundling the code with the metadata.
- `build_info`: Extra information about the environment in which the contract was built.

```json
"source": {
  "hash": "0x157014494527fee27a82e49bbd9eea10c0713bb0566f6def37f4595db86236ff",
  "language": "ink! 6.0.0",
  "compiler": "rustc 1.85.0"
}
```

:::info

Pop CLI handles metadata generation automatically during the build process.
See the [Pop CLI documentation](https://learn.onpop.io) for more details.

:::

### `contract`
This object contains extra metadata about the contract.

The **required** keys include:
 - `name`: The name of the smart contract.
 - `version`: The version of the smart contract.
 - `authors`: The authors of the smart contract.

It can _optionally_ include the following keys:
 - `description`: The description of the smart contract.
 - `documentation`: Link to the documentation of the smart contract.
 - `repository`: Link to the code repository of the smart contract.
 - `homepage`: Link to the homepage of the smart contract.
 - `license`: The license of the smart contract.

```json
"contract": {
  "name": "flipper",
  "version": "6.0.0",
  "authors": [
    "Use Ink <ink@use.ink>"
  ]
}
```

:::info

Pop CLI handles contract metadata generation automatically during the build process.
See the [Pop CLI documentation](https://learn.onpop.io) for more details.

:::

### ABI
This is the specification of the contract.

Unlike the previous metadata sections the structure of the object stored here is not
defined. Instead, it is up to each programming language (e.g. ink! or Solidity) to
define their own metadata format which will then be stored here.

In this document we will focus on the ink! ABI.

The ink! metadata consists of the following **required** sections
 - `spec`: The description of the contract (e.g constructors, messages, events, etc.).
 - `storage`: The layout of the storage data structure
 - `types`: A read-only registry containing types in their portable form for
   serialization.
 - `version`: The version of the ink! metadata.

```json
"spec": { ... },
"storage": { ... },
"types": { ... },
"version": "..."
```

:::info

If you're interested in the code reference from ink!
see [here](https://github.com/use-ink/ink/blob/master/crates/metadata/src/lib.rs#L82).

:::

#### `spec`
The contract `spec` consists of the following **required** keys:
- `constructors`: The set of constructors of the contract.
    - `label`: The label of the constructor. In case of a trait provided constructor the
      label is prefixed with the trait label.
    - `selector`: The selector hash of the message.
    - `payable`: If the constructor accepts any `value` from the caller.
    - `default`: If the constructor is marked as default, useful for UIs.
    - `args`: The parameters of the deployment handler.
    - `docs`: The deployment handler documentation.
- `messages`: The external messages of the contract.
    - `label`: The label of the message. In case of trait provided messages and
      constructors the prefix by convention in ink! is the label of the trait.
    - `selector`: The selector hash of the message.
    - `mutates`: If the message is allowed to mutate the contract state.
    - `payable`: If the message accepts any `value` from the caller.
    - `default`: If the message is marked as default, useful for UIs.
    - `args`: The parameters of the message.
    - `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 the [Environment](../environment.md) section.
  - `accountId`: The type describing an account address.
  - `balance`: The type describing balance values.
  - `blockNumber`: The type describing a block number. 
  - `timestamp`: the type describing a timestamp.
- `events`: The events of the contract.
    - `label`: The label of the event.
    - `args`: The event arguments.
    - `docs`: The event documentation.
- `docs`: The contract documentation.
- `lang_error`: The language specific error type.

:::note

While all these keys are required, they may be empty. For example, if a contract does not
define any events then the `events` key would contain an empty array `[]`.

:::

:::tip ink! 3.x Compatibility Note

The `lang_error` field was introduced as part of ink! 4.0. This represents an error which
comes from the smart contracting language itself, and not the contract nor the underlying
environment (i.e. `pallet-revive`).

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

:::

```json
"spec": {
  "constructors": [
    {
      "args": [
        { ... }
      ],
      "docs": [
        "Creates a new flipper smart contract initialized with the given value."
      ],
      "label": "new",
      "payable": false,
      "default": false,
      "selector": "0x9bae9d5e"
    }
  ],
  "docs": [],
  "events": [],
  "lang_error": {
    "displayName": [
      "ink",
      "LangError"
    ],
    "type": 3
  },
  "messages": [
    {
      "args": [],
      "docs": [
        " Flips the current value of the Flipper's boolean."
      ],
      "label": "flip",
      "mutates": true,
      "payable": false,
      "default": false,
      "returnType": null,
      "selector": "0x633aa551"
    }
  ]
}
```

#### `storage`
This key describes the storage layout of an ink! contract. It tracks some of the
different structures which can be placed in storage.

It consists of the following _optional_ keys (depending on what data structures are used
by the contract):

- `root`: The root cell defines the storage key for all sub-trees
    - `root_key`: The root key of the sub-tree.
    - `layout`: The storage layout of the unbounded layout elements.
- `leaf`: The root cell defines the storage key for all sub-trees
    - `key`: The offset key into the storage.
    - `ty`: The type of the encoded entity.
- `hash`: A layout that hashes values into the entire storage key space.
    - `offset`: The key offset used by the strategy.
    - `strategy`: The hashing strategy to layout the underlying elements.
    - `layout`: The storage layout of the unbounded layout elements.
- `array`: An array of associated storage cells encoded with a given type.
    - `offset`: The offset key of the array layout. This is the same key as the element
      at index 0 of the array layout.
    - `len`: The number of elements in the array layout.
    - `layout`: The layout of the elements stored in the array layout.
- `struct`: A struct layout with fields of different types.
    - `name`: The name of the struct.
    - `fields`: The fields of the struct layout.
- `enum`: An enum layout with a discriminant telling which variant is layed out.
    - `name`: The name of the enum.
    - `dispatch_key`: The key where the discriminant is stored to dispatch the variants.
    - `variants`: The variants of the enum.

```json
"storage": {
  "root": {
    "layout": {
      "struct": {
        "fields": [
          {
            "layout": {
              "leaf": {
                "key": "0x00000000",
                "ty": 0
              }
            },
            "name": "value"
          }
        ],
        "name": "Flipper"
      }
    },
    "root_key": "0x00000000"
  }
}
```

#### `types`
This object contains the type registry for the smart contract. It consists of an array of
type objects, each of which is defined as follows:
- `id`: Numerical ID for referencing the type.
- `ty`: The definition of the type.
    - `path`: The unique path to the type. Can be empty for built-in types.
    - `params`: The generic type parameters of the type in use. Empty for non generic
      types.
    - `def`: The actual type definition.
    - `docs`: Documentation.

The type definition object (`def`) supports the following `primitive` types:
- `bool`, `char`, `str`, `u8`, `u16`, `u32`, `u64`, `u128`, `i8`, `i16`, `i32`, `i64`, `i128`.

It also supports a variety of complex built-in and user-defined types. However, we will
not dig into them here. If you are interested in learning more take a look at the
[`scale-info`](https://github.com/paritytech/scale-info) crate.

```json
"types": [
  {
    "id": 0,
    "type": {
      "def": {
        "primitive": "bool"
      }
    }
  }
]
```

Other parts of the metadata, such as the `storage` object, will reference individual
types from this type registry using the `id` key.

#### `version`
This indicates the version of the ABI format the generated metadata conforms to. This is
distinct from any concept of Rust's crate versioning.

```json
"version": "6"
```

### `user`
This is an _optional_ field used to add user-defined metadata. Some examples of things
you may want to include here:
- `moon_phase`: Phase of the moon during which the smart contract works.
- `favorite_blockchain`: The favorite blockchain of the contract authors (answer: Polkadot!).
````

## File: docs/basics/metadata/overview.md
````markdown
---
title: Overview
hide_title: true
slug: /basics/metadata
---

![Metadata Title Picture](/img/title/metadata-revive.svg)

# Metadata

You can think of "Metadata" this way: when a contract is built,
the product of this process is a binary (the `.polkavm` file) that 
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 or what their arguments
are. This additional information that describes what the raw binary
is about is called metadata — data that describes other data.

Metadata is used to describe a contract in a language agnostic way. 
It is intended to be used by third party tools (e.g. UIs, block explorers e.t.c) 
in order to correctly call contract functions and interpret events.

ink! supports two formats of metadata:

* [Our own native ink! metadata format](./ink-format.md)
* [The Solidity metadata format](./solidity-format.md)

Supporting the Solidity metadata format allows developers to use Solidity tools
(e.g. [ethers.js][ethers-js]) to transparently interact with 
[Solidity ABI compatible ink! contracts][sol-compat].

So developers have a choice which metadata they want to generate for a contract.
They can decide when using the `--metadata` flag with `ink` or `solidity`.

Generating Solidity metadata is only possible if all constructor and message 
argument and return types, and event argument types can be mapped to 
equivalent Solidity ABI types ([more details here][sol-type-mapping]).

[ethers-js]: https://docs.ethers.org/
[sol-compat]: ../../integrations-and-sdks/ethereum-compatibility.md
[sol-type-mapping]: ../../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping
````

## File: docs/basics/metadata/solidity-format.md
````markdown
---
title: Solidity Format
hide_title: true
slug: /basics/metadata/solidity
---

![Metadata Title Picture](/img/title/solidity.svg)

# Solidity Metadata Format

Solidity compatible metadata is generated by building a [Solidity ABI compatible ink! contract][sol-compat] using 

```shell
cargo contract build ---metadata solidity
```

This generates 2 metadata files in your contract's target directory:
- `<contract-name>.abi`: follows the [Solidity ABI JSON format][sol-abi-json] for describing a contract's interface.
  It's used by tools for contract interaction (e.g. [ethers.js][ethers-js])
- `<contract-name>.json`: follows the [Solidity contract metadata specification][sol-metadata].
  It's used for reproducible builds/compilation and verification of deployed contracts 
  (e.g. by block explorers and contract verification tools).

:::note
Generating Solidity metadata is only possible if all constructor and message
arguments and return types can be mapped to equivalent Solidity ABI types
([more details here][sol-type-mapping]).
:::

[sol-compat]: ../../integrations-and-sdks/ethereum-compatibility.md
[sol-abi-json]: https://docs.soliditylang.org/en/latest/abi-spec.html#json
[sol-metadata]: https://docs.soliditylang.org/en/latest/metadata.html
[ethers-js]: https://docs.ethers.org/
[sol-type-mapping]: ../../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping

## `<contract-name>.abi`

The generated `<contract-name>.abi` file follows the [Solidity ABI JSON format][sol-abi-json].
A notable distinction is that while [ink! contracts can have multiple constructors][ink-ctor], 
the Solidity ABI JSON format only allows one, therefore the constructor annotated with
a [`#[default]`][ink-attr-default] attribute is used.

[ink-ctor]: ../../macros-attributes/constructor.md
[ink-attr-default]: ../../macros-attributes/default.md

## `<contract-name>.json`

The generated `<contract-name>.json` file follows the [Solidity contract metadata specification][sol-metadata]
with the exception being that we repurpose the `"settings"` key to include ink! contract and build info 
namespaced under a `"settings.ink"` key:

### `settings.ink`

It consists of the following **required** keys:

- `hash`: The hash of the contract's binary.
  (The same content as [`source.hash`][ink-meta-source] in ink! metadata format).
- `build_info`: Extra information about the environment in which the contract was built.
  (The same content as [`source.build_info`][ink-meta-source] in ink! metadata format).

[ink-meta-source]: ./ink-format.md#source

It may *optionally* include the following key:

- `image`: If the contract is meant to be verifiable, then the Docker image is specified.
  (The same content as [`image`][verifiable-build] in ink! metadata format,
  which is used for [verifiable builds][verifiable-build]).

[verifiable-build]: ../contract-verification.md#verifiable-build

:::note
The ABI JSON content (i.e. the content of the `<contract-name>.abi` file) is also contained
in the `<contract-name>.json` metadata file under the `"output.abi"` key.
:::
````

## File: docs/basics/contract-template.md
````markdown
---
title: Contract Template
hide_title: true
slug: /basics/contract-template
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Macro Title Picture](/img/title/macro.svg)

# Contract Template

On this page we'll go over the elements of a basic contract.

## Creating a template

Change into your working directory and run:

```bash
pop new contract foobar
```

This will create a new project folder named `foobar`.

```bash
cd foobar/
```

In the `lib.rs` file you find initial scaffolded code, which you can use as a starting point.

Quickly check that it compiles, and the trivial tests pass with:

```bash
pop test
```

Also check that you can build the contract by running:

```bash
pop build
```

`pop test` builds the contract for `std` (for unit testing),
`pop build` builds for an on-chain deployment (`no_std` with a RISC-V target).

If everything looks good, then we are ready to start programming!

## Template Content

The template contains scaffolded code that provides a starting point
for writing an ink! contract. In the following we'll take a look
at what the files contain.
The files you get locally will look similar, just that we added
explanatory comments here.

### `Cargo.toml`

```toml
[package]
name = "foobar"
version = "0.1.0"
authors = ["[your_name] <[your_email]>"]
edition = "2021"

[dependencies]
# The `ink` crate contains the ink! eDSL and re-exports
# a number of other ink! specific crates. For example,
# `ink::env` is the `ink_env` crate that contains functions
# to interact with a contract's environment (querying information
# about a caller, the current block number, etc.).
ink = { version = "6.0.0-beta", default-features = false }

# IMPORTANT: If you need XCM functionality, you MUST enable the "xcm" feature:
# ink = { version = "6.0.0-beta", default-features = false, features = ["xcm"] }

[dev-dependencies]
# This developer dependency is for the End-to-End testing framework.
ink_e2e = { version = "6.0.0-beta", default-features = false }

[lib]
name = "foobar"
path = "lib.rs"

[features]
default = ["std"]
std = [
    "ink/std",
]
ink-as-dependency = []

# This feature is just a convention, so that the end-to-end tests
# are only executed if `cargo contract test` is explicitly invoked with
# `--features e2e-tests`.
e2e-tests = []
```

:::note
**XCM Feature Required:** If your contract uses XCM functionality (cross-chain messaging),
you MUST add `"xcm"` to the features list in the ink dependency. Without this feature enabled,
you will get compilation errors when trying to use `ink::xcm::prelude::*` or any XCM-related functions.

Example with XCM:
```toml
[dependencies]
ink = { version = "6.0.0-beta", default-features = false, features = ["xcm"] }
```
:::

### `lib.rs`

Every ink! contract is required to contain:

* Exactly one `#[ink(storage)]` struct.
* At least one `#[ink(constructor)]` function.
* At least one `#[ink(message)]` function.

The scaffolded code will look similar to the following, we've
changed the comments though to explain what is going on there
on a high level.

```rust
// If the `std` feature from the `Cargo.toml` is not enabled
// we switch on `no_std`, this has the effect of Rusts standard
// library not being included in our contract.
//
// The Rust standard library is OS-dependent and Wasm is
// architecture independent.
#![cfg_attr(not(feature = "std"), no_std, no_main)]

// This is the ink! macro, the starting point for your contract.
// Everything below it might look like Rust code, but it is actually
// run through a parser in ink!.
#[ink::contract]
pub mod flipper {
    /// This is the contract's storage.
    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {
        /// A constructor that the contract can be initialized with.
        #[ink(constructor)]
        pub fn new(init_value: bool) -> Self {
            /* --snip-- */
        }

        /// An alternative constructor that the contract can be
        /// initialized with.
        #[ink(constructor)]
        pub fn new_default() -> Self {
            /* --snip-- */
        }

        /// A state-mutating function that the contract exposes to the
        /// outside world.
        ///
        /// By default functions are private, they have to be annotated
        /// with `#[ink(message)]` and `pub` to be available from the
        /// outside.
        #[ink(message)]
        pub fn flip(&mut self) {
            /* --snip-- */
        }

        /// A public contract function that has no side-effects.
        ///
        /// Note that while purely reading functions can be invoked
        /// by submitting a transaction on-chain, this is usually
        /// not done as they have no side-effects and the transaction
        /// costs would be wasted.
        /// Instead those functions are typically invoked via RPC to
        /// return a contract's state.
        #[ink(message)]
        pub fn get(&self) -> bool {
            /* --snip-- */
        }
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        /// This attribute denotes that the test is executed in
        /// a simulated, mocked blockchain environment. There are
        /// functions available to influence how the test environment
        /// is configured (e.g. setting an account to a specified balance).
        #[ink::test]
        fn default_works() {
            /* --snip-- */
        }

        /* --snip-- */
    }

    #[cfg(all(test, feature = "e2e-tests"))]
    mod e2e_tests {
        use super::*;
        use ink_e2e::build_message;

        type E2EResult<T> = std::result::Result<T, Box<dyn std::error::Error>>;

        /// With this attribute the contract will be compiled and deployed
        /// to a Substrate node that is required to be running in the
        /// background.
        ///
        /// We offer API functions that enable developers to then interact
        /// with the contract. ink! will take care of putting contract calls
        /// into transactions that will be submitted to the Substrate chain.
        ///
        /// Developers can define assertions on the outcome of their transactions,
        /// such as checking for state mutations, transaction failures or
        /// incurred gas costs.
        #[ink_e2e::test]
        async fn it_works(mut client: ink_e2e::Client<C, E>) -> E2EResult<()> {
            /* --snip-- */
        }

        /* --snip-- */
    }
}
```
````

## File: docs/basics/contract-verification.md
````markdown
---
title: Contract Verification
slug: /basics/verification/contract-verification
hide_title: true
---

![intro image](/img/title/verification.svg)

# Contract Verification

Contract verification is the process of matching a deployed ink! contract
with the source code and metadata generated when it was built.

The verification process for Rust-based smart contract languages is more
complex than EVM-based languages such as Solidity due to the Rust
compiler not providing deterministic builds of contracts.

In order to verify an ink! smart contract, the verification
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.

## Verifiable build

As mentioned earlier, due to the non-deterministic nature of Rust compilation,
smart contract developers are advised to build their project inside
a Docker container we provide. Luckily, `cargo contract build`
provides the `--verifiable` flag for this purpose.

The steps for the verifiable build production are:

1. [Install Docker Engine](https://docs.docker.com/engine/install/)
2. (Linux users) Make sure you complete the [post-installation step](https://docs.docker.com/engine/install/linux-postinstall/).
   This is required for the correct operation of the command.
3. Ensure Docker Engine is up and running, and the socket is accessible.
4. Simply run `cargo contract build --verifiable`.

This will pull the appropriate Docker image version, perform a deterministic build,
and write artifacts in the standard output directory.

If everything is correct, you can verify the image version in the metadata file.
It should contain a key-value `image` after the `contract` information:

```json
  "contract": {
    "name": "flipper",
    "version": "6.0.0",
    "authors": [
      "Use Ink <ink@use.ink>"
    ]
  },
  "image": "use-ink/contracts-verifiable:6.0.0",
```

You are now ready to deploy your contract to a production chain.

:::note
The image is `amd64` based. Therefore, the build times can be significantly slower
on Apple Silicon machines. To overcome the issue enable _Rosetta for x86/amd64 emulation_
in _Settings_ → _Features in development_ tab in Docker Desktop App.
:::

## Verifying contracts

Similar to Etherscan, you want to ensure that the given contract bundle
is indeed a copy of some well-known contract code.

Contract verification allows you to verify the given cargo project
against a reference contract bundle.

For advanced verification scenarios, you may need to use cargo-contract directly.
See the [contract verification documentation](https://use.ink/docs/basics/contract-verification).

If the reference contract was not built inside a Docker container, the command
will compare the build info from the reference contract with the current environment
to ensure a match in environment.

:::warning
If you are not using standardized verifiable builds. It is your responsibility
to ensure deterministic environment both for build and verification of
smart contracts.
:::

If the build info from the `.contract` file matches the environment and a
Docker `image` is present in metadata, the build tooling will compile the
project inside the specified `image` Docker container for reproducibility.
Otherwise, a local build is carried out.

Upon completion, the built contract bundle is compared to the reference one
and the result is returned.

## Advanced usage

If you would like to carry out other operations inside a deterministic environment
you can use the contracts-verifiable Docker image. It is available on [Docker Hub](https://hub.docker.com/repository/docker/useink/contracts-verifiable/general).

:::tip
If you are building a multi-contract project,
make sure you are executing the build in the parent directory in order to mount the directory
of all contracts to be visible. Specify a relative manifest path to the root contract.
:::

For advanced build scenarios and Docker image details, see the [contract verification documentation](https://use.ink/docs/basics/contract-verification).
````

## File: docs/basics/cross-contract-calling.md
````markdown
---
title: Cross-Contract Calling
slug: /basics/cross-contract-calling
hide_title: true
---

![Cross Contract Title Picture](/img/title/cross-contract.svg)

# Cross-Contract Calls

In ink! contracts it is possible to call messages and constructors of other
on-chain contracts.

> ⚠️ **SECURITY WARNING**: Cross-contract calls are the #1 source of security vulnerabilities!
>
> **Always follow the Checks-Effects-Interactions pattern:**
> 1. ✅ Check conditions first (validation)
> 2. ✅ Update your contract's state second
> 3. ✅ Call external contracts LAST
>
> **Why?** External contracts can call you back (reentrancy attack) and exploit inconsistent state.
> See the [Security Best Practices](#understanding-security-best-practices) section for detailed examples.

There are a few approaches to performing these cross-contract calls in ink!:
1. Contract references (i.e `ContractRef`)
2. Builders (i.e `CreateBuilder` and `CallBuilder`)
3. Calling Solidity ABI Encoded Contracts with `CallBuilder`

Contract references can only be used for cross-contract calls to other ink! contracts.
Builders can be used to issue cross-contract calls to any RISC-V contract, such as those
written in ink! or Solidity.

## Contract References

Contract references refer to structs that are generated by the ink! code generation for the
purposes of cross-contract calls.

They give developers a type-safe way of interacting with a contract.

A downside to using them is that you need to import the contract you want to call as a
dependency of your own contract.

If you want to interact with a contract that is already on-chain you will need to use the
[`Builders`](#builders) approach instead.

:::note
In ["all" ABI mode][abi-all], contract references are generated for both ink!/native
and Solidity ABI calling conventions, with the Solidity ABI specific contract reference
named with an additional `Sol` suffix
(e.g. `ContractRefSol` for a contract named `Contract`).

Note that, this `Sol` suffix is not necessary in ["sol" ABI mode][abi-sol]
(i.e. for a contract named `Contract`, `ContractRef` will use the Solidity ABI
calling conventions in "sol" ABI mode).
:::

[abi-all]: ./abi/all.md
[abi-sol]: ./abi/solidity.md

### `BasicContractRef` walkthrough

We will walk through the [`cross-contract-calls`](https://github.com/use-ink/ink-examples/tree/master/cross-contract-calls)
example in order to demonstrate how cross-contract calls using contract references work.

The general workflow will be:
1. Prepare `OtherContract` to be imported to other contracts
1. Import `OtherContract` into `BasicContractRef`
1. Upload `OtherContract` on-chain
1. Instantiate `OtherContract` using `BasicContractRef`
1. Call `OtherContract` using `BasicContractRef`

#### Prepping `OtherContract`

We need to make sure that the ink! generated contract ref for `OtherContract` is
available to other pieces of code.

We do this by re-exporting the contract reference as follows:

```rust
pub use self::other_contract::OtherContractRef;
```

#### Importing `OtherContract`

Next, we need to import `OtherContract` to our `BasicContractRef` contract.

First, we add the following lines to our `Cargo.toml` file:

```toml
# In `basic_contract_ref/Cargo.toml`

other_contract = { path = "other_contract", default-features = false, features = ["ink-as-dependency"] }

# -- snip --

[features]
default = ["std"]
std = [
    "ink/std",
    # -- snip --
    "other_contract/std",
]
```

Two things to note here:
1. If we don't specify the `ink-as-dependency` feature we will end up with linking
   errors.
2. If we don't enable the `std` feature for `std` builds we will not be able to generate
   our contract's metadata.

#### Wiring `BasicContractRef`

First, we will import the contract reference of `OtherContract`, and declare the
reference to be part of our storage struct.

```rust
// In `basic_contract_ref/lib.rs`

use other_contract::OtherContractRef;

#[ink(storage)]
pub struct BasicContractRef {
    other_contract: OtherContractRef,
}
```

Next, we to add a way to instantiate `OtherContract`. We do this from the constructor of our
of contract.

```rust
// In `basic_contract_ref/lib.rs`

#[ink(constructor)]
pub fn new(other_contract_code_hash: Hash) -> Self {
    let other_contract = OtherContractRef::new(true)
        .code_hash(other_contract_code_hash)
        .endowment(0)
        .salt_bytes([0xDE, 0xAD, 0xBE, 0xEF])
        .instantiate();

    Self { other_contract }
}
```

Note that for instantiating a contract we need access to the uploaded on-chain
`code_hash`. We will get back to this later.

Once we have an instantiated reference to `OtherContract` we can call its messages just
like normal Rust methods!

```rust
// In `basic_contract_ref/lib.rs`

#[ink(message)]
pub fn flip_and_get(&mut self) -> bool {
    self.other_contract.flip();
    self.other_contract.get()
}
```

#### Uploading `OtherContract`

You will need the [`ink-node`](https://github.com/use-ink/ink-node)
running in the background for the next steps.

We can upload `OtherContract` using Pop CLI as follows:

```
# In the `basic_contract_ref` directory
cd other_contract
pop build
pop up --upload-only --suri //Alice
```

If successful, this will output a `code_hash` similar to:

```
Code hash "0x74a610235df4ff0161f0247e4c9d73934b70c1520d24ef843f9df9fcc3e63caa"
```

We can then use this `code_hash` to instantiate our `BasicContractRef` contract.

#### Instantiating `OtherContract` through `BasicContractRef`

We will first need to instantiate `BasicContractRef`.

```
# In the `basic_contract_ref` directory
pop build
pop up \
    --constructor new \
    --args 0x74a610235df4ff0161f0247e4c9d73934b70c1520d24ef843f9df9fcc3e63caa \
    --suri //Alice
```

If successful, this will output a contract address for `BasicContractRef` similar to:

```
Contract 5CWz6Xnivp9PSoZq6qPRP8xVAShZgtNVGTCLCsq3qzqPV7Rq
```

#### Calling with `OtherContract` through `BasicContractRef`

Finally, we can call the `OtherContract` methods through `BasicContractRef` as follows:

```
pop call contract \
    --contract 5CWz6Xnivp9PSoZq6qPRP8xVAShZgtNVGTCLCsq3qzqPV7Rq \
    --message flip_and_get \
    --suri //Alice \
    --dry-run
```

Which will result in something like:

```
Result Success!
Reverted false
Data Ok(true)
```

## Builders
The
[`CreateBuilder`](https://use-ink.github.io/ink/ink_env/call/struct.CreateBuilder.html)
and
[`CallBuilder`](https://use-ink.github.io/ink/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.

### CreateBuilder
The `CreateBuilder` offers an an easy way for you to **instantiate** a contract. Note
that you'll still need this contract to have been previously uploaded.

:::note

For a refresher on the difference between `upload` and `instantiate`
[see here](../getting-started/deploying.md).

:::

In order to instantiate a contract you need a reference to your contract, just like in
[the previous section](#contract-references).

Below is an example of how to instantiate a contract using the `CreateBuilder`. We will:
- instantiate the uploaded contract with a `code_hash` of `0x4242...`
- with no gas limit specified (`0` means unlimited)
- sending `10` units of transferred value to the contract instance
- instantiating with the `new` constructor
- with the following arguments
    - a `u8` with value `42`
    - a `bool` with value `true`
    - an array of 32 `u8` with value `0x10`
- generate the address (`AccountId`) using the specified `salt_bytes`
- and we expect it to return a value of type `MyContractRef`

```rust
use contract::MyContractRef;
let my_contract: MyContractRef = build_create::<MyContractRef>()
    .instantiate_v1()
    .code_hash(Hash::from([0x42; 32]))
    .gas_limit(0)
    .endowment(10)
    .exec_input(
        ExecutionInput::new(Selector::new(ink::selector_bytes!("new")))
            .push_arg(42)
            .push_arg(true)
            .push_arg(&[0x10u8; 32])
    )
    .salt_bytes(&[0xDE, 0xAD, 0xBE, 0xEF])
    .returns::<MyContractRef>()
    .instantiate();
```

Since `CreateBuilder::instantiate()` returns a contract reference, we can use this
contract reference to call messages just like in the
[previous section](#contract-references).

:::note
To instantiate a contract that uses a different [ABI][abi] than your contract, 
you can instead use an ABI-specific utility (i.e. `build_create_sol` or `build_create_ink`)

```rust
build_create_sol::<MyContractRef>()
```
:::

[abi]: ./abi/overview.md

### CallBuilder
The `CallBuilder` gives you a couple of ways to call messages from other contracts. There
are two main approaches to this: `Call`s and `DelegateCall`s. We will briefly cover both
here.

#### CallBuilder: Call
When using `Call`s the `CallBuilder` requires an already instantiated contract.

We saw an example of how to use the `CreateBuilder` to instantiate contracts in the
[previous section](#contract-references).

Below is an example of how to call a contract using the `CallBuilder`. We will:
- make a regular `Call`
- to a contract at the address `0x4242...`
- with no gas limit specified (`0` means unlimited)
- sending `10` units of transferred value to the contract instance
- calling the `flip` message
- with the following arguments
    - a `u8` with value `42`
    - a `bool` with value `true`
    - an array of 32 `u8` with value `0x10`
- and we expect it to return a value of type `bool`

```rust
let my_return_value = build_call::<DefaultEnvironment>()
    .call(H160::from([0x42; 20]))
    .call_v1()
    .gas_limit(0)
    .transferred_value(10)
    .exec_input(
        ExecutionInput::new(Selector::new(ink::selector_bytes!("flip")))
            .push_arg(42u8)
            .push_arg(true)
            .push_arg(&[0x10u8; 32])
    )
    .returns::<bool>()
    .invoke();
```

Note:

Message arguments will be encoded in the order in which they are provided to the `CallBuilder`.
This means that they should match the order (and type) they appear in the function
signature.

You will not be able to get any feedback about this at compile time. You will only
find out your call failed at runtime!

:::note
To call messages from a contract that uses a different [ABI][abi] than your contract,
you can instead use an ABI-specific utility (i.e. `build_call_sol` or `build_call_ink`).

```rust
build_call_sol::<DefaultEnvironment>()
```

You can see a full example of an ink! contract calling a Solidity ABI encoded contract
in the ["CallBuilder Solidity" example below](#callbuilder-solidity).
:::

#### CallBuilder: Delegate Call
You can also use the `CallBuilder` to craft calls using `DelegateCall` mechanics.
If you need a refresher on what delegate calls are,
[see this article](https://medium.com/coinmonks/delegatecall-calling-another-contract-function-in-solidity-b579f804178c).

In the case of `DelegateCall`s, we don't require an already instantiated contract.
We only need the `code_hash` of an uploaded contract.

Below is an example of how to delegate call a contract using the `CallBuilder`. We will:
- make a `DelegateCall`
- to a contract with a `code_hash` (not contract address!) of `0x4242...`
- calling the `flip` message
- with the following arguments
    - a `u8` with value `42`
    - a `bool` with value `true`
    - an array of 32 `u8` with value `0x10`
- and we expect it to return an `i32`

```rust
let my_return_value = build_call::<DefaultEnvironment>()
    .delegate(H160::from([0x42; 20]))
    .exec_input(
        ExecutionInput::new(Selector::new(ink::selector_bytes!("flip")))
            .push_arg(42u8)
            .push_arg(true)
            .push_arg(&[0x10u8; 32])
    )
    .returns::<i32>()
    .invoke();
```

### CallBuilder Solidity
`CallBuilder` also allows you to call contracts that are Solidity ABI encoded. 
This enables interoperability between Solidity, ink!, and other Solidity ABI encoded contracts!

This requires using a Solidity compatible function selector using a `keccak256` hash of the function signature.

```rust
let my_return_value = build_call_sol::<DefaultEnvironment>()
    .call(H160::from([0x42; 20]))
    .ref_time_limit(0)
    .transferred_value(10)
    .exec_input(
        ExecutionInput::new([0xcd, 0xe4, 0xef, 0xa9].into()) // solidity selector: keccak256("flip()")
    )
    .returns::<bool>()
    .invoke();
```

### Builder Error Handling
The `CreateBuilder` and the `CallBuilder` both offer error handling with the
`try_instantiate()` and `try_invoke()` methods respectively.

These allow contract developers to handle two types of errors:
1. Errors from the underlying execution environment (e.g the Contracts pallet)
2. Error from the programming language (e.g `LangError`s)

See the documentation for
[`try_instantiate`](https://use-ink.github.io/ink/ink_env/call/struct.CreateBuilder.html#method.try_instantiate),
[`try_invoke`](https://use-ink.github.io/ink/ink_env/call/struct.CallBuilder.html#method.try_invoke-2),
[`ink::env::Error`](https://use-ink.github.io/ink/ink_env/enum.Error.html)
and
[`ink::LangError`](https://use-ink.github.io/ink/ink/enum.LangError.html)
for more details on proper error handling.
````

## File: docs/basics/env-functions.md
````markdown
---
title: Environment Functions
slug: /basics/environment-functions
---

![Env Function Title Picture](/img/title/env-function.svg)

# Environment Functions

ink! exposes a number of handy environment functions.
A full overview [is found here](https://use-ink.github.io/ink/ink_env/#functions).

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

Some handy functions include:

* [`caller()`](https://use-ink.github.io/ink/ink_env/fn.caller.html): Returns the address of the caller of the executed contract.
* [`address()`](https://use-ink.github.io/ink/ink_env/fn.address.html): Returns the address of the executed contract.
* [`balance()`](https://use-ink.github.io/ink/ink_env/fn.balance.html): Returns the balance of the executed contract.
* [`block_number()`](https://use-ink.github.io/ink/ink_env/fn.block_number.html): Returns the current block number.
* [`emit_event(…)`](https://use-ink.github.io/ink/ink_env/fn.emit_event.html): Emits an event with the given event data.
* [`transfer(…)`](https://use-ink.github.io/ink/ink_env/fn.transfer.html): Transfers value from the contract to the destination account ID.
* [`hash_bytes(…)`](https://use-ink.github.io/ink/ink_env/fn.hash_bytes.html): Conducts the crypto hash of the given input and stores the result in output.
* […and many more](https://use-ink.github.io/ink/ink_env/#functions).

> ⚠️ **SECURITY WARNING**: When using `transfer()` or any function that sends funds:
>
> **Always update your state BEFORE calling transfer!** (Checks-Effects-Interactions pattern)
>
> ```rust
> // ✅ SAFE: State updated first
> self.balances.insert(caller, 0);
> self.env().transfer(caller, amount)?;
>
> // ❌ VULNERABLE: Transfer before state update
> self.env().transfer(caller, amount)?;
> self.balances.insert(caller, 0);  // Reentrancy risk!
> ```
>
> See [Security Best Practices](#security-best-practices-for-ink-contracts) for more details.
````

## File: docs/basics/environment.md
````markdown
---
title: Chain Environment Types
slug: /basics/chain-environment-types
hide_title: true
---

![Environment Title Picture](/img/title/environment.svg)

# Chain Environment Types

ink! defines a trait [`Environment`](https://use-ink.github.io/ink/ink_env/trait.Environment.html)
and also a default implementation of that trait ‒ [`DefaultEnvironment`](https://use-ink.github.io/ink/ink_env/enum.DefaultEnvironment.html).

These are the types that ink! uses, if no explicit steps are taken:

```rust
/// The fundamental types of the default configuration.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "std", derive(TypeInfo))]
pub enum DefaultEnvironment {}

impl Environment for DefaultEnvironment {
    const MAX_EVENT_TOPICS: usize = 4;

    type AccountId = AccountId;
    type Balance = Balance;
    type Hash = Hash;
    type Timestamp = Timestamp;
    type BlockNumber = BlockNumber;
    type ChainExtension = NoChainExtension;
    type EventRecord = EventRecord;
}
```

The context here is that you can use ink! on any blockchain that was built with
the [Polkadot SDK](https://polkadot.com/platform/sdk) and includes the
[`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive)
module.

Chains built with the Polkadot SDK can decide on their own which types they want
to use for e.g. the chain's block number or account id's. For example,
chains that intend to be compatible to Ethereum typically use the same
type as Ethereum for their `AccountId`.

Most Polkadot SDK chains stay with the default types though and
ink! just uses those by default as well. It is possible to configure
a different environment in the contract macro ([documentation here](https://use-ink.github.io/ink/ink/attr.contract.html#header-arguments))
though:

```rust
#[ink::contract(env = MyCustomTypes)]
```

:::caution
If you write a contract for a chain that deviates from our default
types (`DefaultEnvironment`), you have to make sure to configure that chain's
`Environment` for your contract!
:::
````

## File: docs/basics/events.md
````markdown
---
title: Events
slug: /basics/events
hide_title: true
---

![Balloons 1 Title Picture](/img/title/balloons-1.svg)

# 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.

> ⚠️ **PRIVACY NOTE**: Events are public and permanent!
>
> - 🔍 **Always Visible**: Events are logged on-chain and anyone can read them
> - ⏰ **Forever**: Events cannot be deleted or hidden after emission
> - 💡 **Use Wisely**: Never emit sensitive data (private keys, passwords, personal info)
> - ✅ **Good for**: Tracking transfers, state changes, user actions
> - 💰 **Gas Cost**: Events cost gas, but less than storage writes
>
> Events are perfect for off-chain indexing and user notifications, but treat them like public announcements!

![Contract execution via transaction](/img/events-revive.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<AccountId>,
        to: Option<AccountId>,
        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/use-ink/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<AccountId>,
    #[ink(topic)]
    to: Option<AccountId>,
    amount: u128,
}
```

:::note
Generics are [not currently supported](https://github.com/use-ink/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, up to 4 topics (including the signature topic, if any) 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 a 32 byte array (`[u8; 32]`), and the topic value is encoded as follows:

- If the SCALE encoded bytes of a field value are `<= 32`,
  then the encoded bytes are used directly as the topic value.
  If necessary, the topic value is padded on the right side with zero-bytes such that its length is 32 bytes.
  - 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 the size of the SCALE encoded bytes of the field value exceeds 32,
  then the encoded bytes are hashed using the `Blake2x256` hash function.

:::note
The topic encoding specification above only applies to native/ink! ABI encoded events.

For Solidity ABI encoded events, topics (and event data) are encoded according to the
[Solidity ABI specification for events][sol-abi-events] and [indexed event parameters][sol-abi-topics].
:::

[sol-abi-events]: https://docs.soliditylang.org/en/latest/abi-spec.html#events
[sol-abi-topics]: https://docs.soliditylang.org/en/latest/abi-spec.html#encoding-of-indexed-event-parameters

:::note
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 all the fields:
```
blake2b("Event(field1_type,field2_type)")`
```
So for our `Transferred` example it will be: 
```
blake2b("Transferred(Option<AccountId>,Option<AccountId>,u128)")`
```

:::note
The signature topic computation specification above only applies to native/ink! ABI encoded events.

For Solidity ABI encoded events, the signature topic is computed as the event signature
according to the [Solidity ABI specification for events][sol-abi-events].
:::

:::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(())
}
```

:::note
In ["all" ABI mode][abi-all], both an ink! and Solidity ABI encoded event are emitted
for each call to `Self::env().emit_event()` or `self.env().emit_event()`.

To emit a single event for a specific ABI, 2 additional ABI-specific utilities are provided
in "all" ABI mode:
- `emit_event_ink`: emits a single ink! ABI encoded event.
- `emit_event_sol`: emits a single Solidity ABI encoded event.
:::

[abi-all]: ./abi/all.md

## 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.
````

## File: docs/basics/gas.md
````markdown
---
title: Gas
slug: /basics/gas
hide_title: true
---

![Gas Title Picture](/img/title/gas.svg)

# Understanding Gas & Performance in ink!

## What is Gas?

**Gas** is what you pay to execute your smart contract. Think of it like electricity - the more your contract does, the more it costs.

### Why Gas Exists

Blockchains have limited resources. Gas prevents:
- **Infinite loops** - Loops that never end
- **Resource abuse** - Someone spamming the network
- **Network congestion** - Too many heavy operations

**Every operation costs gas. If you run out, execution stops.**

### What Uses Gas?

**Expensive operations (high gas):**
- Writing to storage
- Creating new contracts
- Cross-contract calls
- Complex computations
- Large loops

**Cheap operations (low gas):**
- Reading from storage
- Local variable operations
- Simple arithmetic
- Returning values

### Gas in ink! = (refTime, proofSize)

ink! tracks two types of resources:

**refTime** - Computational time (how long code runs)
**proofSize** - Storage reads (how much data is accessed)

**For beginners:** Just know that both matter, but refTime is usually the main concern.

## Optimization Tips for Beginners

### 1. Minimize Storage Writes

**Storage writes are the most expensive operation!**

```rust
// ❌ EXPENSIVE: Multiple writes
#[ink(message)]
pub fn bad_example(&mut self) {
    self.counter = self.counter + 1;  // Read + Write
    self.counter = self.counter + 1;  // Read + Write
    self.counter = self.counter + 1;  // Read + Write
}

// ✅ CHEAP: One write
#[ink(message)]
pub fn good_example(&mut self) {
    let new_value = self.counter + 3;  // Read once, calculate
    self.counter = new_value;          // Write once
}
```

### 2. Use Mapping Instead of Vec for Large Data

```rust
// ❌ EXPENSIVE for many users: Must load entire vector
#[ink(storage)]
pub struct BadToken {
    balances: Vec<(AccountId, Balance)>,  // Gets slow with many users!
}

// ✅ EFFICIENT: Only loads what you need
#[ink(storage)]
pub struct GoodToken {
    balances: Mapping<AccountId, Balance>,  // Fast lookups!
}
```

**Rule: Use `Mapping` when you have many items and need individual access.**

### 3. Avoid Unbounded Loops

```rust
// ❌ DANGEROUS: Could run out of gas if vec is large
#[ink(message)]
pub fn process_all(&mut self) {
    for item in self.items.iter() {  // What if there are 10,000 items?
        self.process(item);
    }
}

// ✅ SAFE: Process in batches
#[ink(message)]
pub fn process_batch(&mut self, start: u32, count: u32) {
    let end = start + count;
    for i in start..end {
        if let Some(item) = self.items.get(i) {
            self.process(item);
        }
    }
}
```

**Rule: Never loop over unbounded collections. Use pagination!**

### 4. Batch Operations

```rust
// ❌ INEFFICIENT: Multiple external calls
#[ink(message)]
pub fn transfer_to_many_slow(&mut self, recipients: Vec<AccountId>) {
    for recipient in recipients {
        self.transfer(recipient, 100)?;  // Separate call each time
    }
}

// ✅ EFFICIENT: Batch in one call
#[ink(message)]
pub fn transfer_to_many_fast(&mut self, recipients: Vec<AccountId>) {
    for recipient in recipients {
        // Update storage directly, emit one event at end
        let balance = self.balances.get(recipient).unwrap_or(0);
        self.balances.insert(recipient, balance + 100);
    }
    self.env().emit_event(BatchTransferComplete { count: recipients.len() });
}
```

### 5. Use Lazy Storage for Large Data

```rust
// For data that's not accessed every time:
use ink::storage::Lazy;

#[ink(storage)]
pub struct MyContract {
    frequently_used: u32,           // Always loaded
    rarely_used: Lazy<BigStruct>,   // Only loaded when accessed
}
```

## Gas Cost Hierarchy (Expensive to Cheap)

1. **Storage Write** - Most expensive!
2. **Cross-contract call** - Expensive
3. **Cryptographic operations** - Moderate
4. **Storage Read** - Moderate
5. **Computation** - Cheap
6. **Local variables** - Very cheap

## Estimating Gas Costs

**Unfortunately, exact costs vary by parachain.** Each blockchain sets its own fees.

**General guidance:**
- **Simple transfers:** Low cost
- **Token mints/burns:** Moderate cost
- **Complex DeFi operations:** High cost
- **NFT minting:** Moderate-high cost

**Best practice:** Test on testnet first to see actual costs!

## Gas Limits & Running Out

When calling a contract, you specify a gas limit:

```bash
pop call contract --message transfer --gas-limit 10000000000
```

**What happens if you run out?**
- Execution stops immediately
- State changes are reverted
- You still pay for gas used up to that point

**How to avoid:**
- Test thoroughly on testnet
- Start with high limits, optimize later
- Use `--dry-run` to estimate gas first

## Performance Best Practices Summary

1. **Minimize storage writes** - Most expensive operation
2. **Use `Mapping` for large datasets** - More efficient than `Vec`
3. **No unbounded loops** - Always paginate
4. **Batch operations** - Fewer calls = lower gas
5. **Lazy load rarely-used data** - Don't load what you don't need
6. **Test on testnet** - See real gas costs before mainnet

## Common Gas Mistakes

❌ **Mistake 1:** Storing too much data
```rust
// Storing entire strings on-chain
pub struct BadContract {
    user_bios: Mapping<AccountId, String>,  // Could be huge!
}
```

❌ **Mistake 2:** Iterating over everything
```rust
// Looping through all users
for user in all_users {  // Expensive!
    update(user);
}
```

❌ **Mistake 3:** Redundant storage reads
```rust
// Reading same value multiple times
let a = self.value;
let b = self.value;  // Read again!
let c = self.value;  // And again!
```

## Learn More

For complete gas documentation:
**https://use.ink/docs/v6/basics/gas**

**Remember: Storage writes are expensive. Optimize them first!**

---

## What is "Gas" in ink!?

For ink!, the term Gas refers to the resources used by a contract call.
It's important for smart contracts that the caller has to pay for any utilized resource.

Those resources can be either storage space (for storing data in the contract's storage)
or computational time (for executing the contract and its logic). The term Gas encompasses both
of these resources: `Gas = (refTime, proofSize)`.

The terms hereby refer to:

`refTime`: The amount of computational time that can be used for execution, in picoseconds.

`proofSize`: The amount of storage in bytes that a transaction is allowed to read.

The term `refTime` comes from "reference time", referring to the Polkadot SDK Weights system, where
computation time is benchmarked on reference hardware. You can read more details
[here](https://docs.polkadot.com/polkadot-protocol/glossary/#weight).

The term `proofSize` is only relevant for parachains on the [Polkadot](https://polkadot.network/)
or [Kusama](https://kusama.network/) networks.
_It can be ignored for standalone chains (like [Aleph Zero](https://alephzero.org/))._
On a high level, `proofSize` is the size of the proof that individual parachains send to
the Polkadot or Kusama relay chain to allow re-executing their block for validation
(this is called Proof of Validity).
Phrased differently: Layer-1 chains send a proof of validity to a Layer-0 chain to validate the block.
This Proof of Validity contains everything necessary to execute the block -- the code of each contract
that is executed plus the storage each contract reads and writes.

:::info
Blockchains that support ink! are built using Polkadot SDK which uses the concept of Weight
to describe the usage of resources.
Specifically, the terms above come from the Polkadot SDK "Weights V2" system.
For ink!, Gas is a synonym to the concept called "Weight" in this SDK.
The Weights concept is similar to what smart contract developers might know from other
ecosystems, but is more fine grained. It also tracks the utilized bandwidth, not just
execution. For ink! smart contracts the utilized bandwidth is the `proofSize` explained above.

We decided on using the term "Gas" to make onboarding easier for developers from other
smart contract ecosystems. So: `Gas = Weight = (refTime, proofSize)`.
:::
````

## File: docs/basics/mutating-values.md
````markdown
---
title: Mutating Storage Values
slug: /basics/mutating-values
hide_title: true
---

![Storage Mutating Title Picture](/img/title/storage-mutating.svg)

# Security Best Practices for ink! Contracts

Smart contracts handle real value, so security is critical. This guide covers the most important security concepts for beginners.

## Why Security Matters

Unlike regular programs, smart contracts:
- **Handle money** - Bugs can lead to stolen funds
- **Are immutable** - Once deployed, code can't easily be changed
- **Are public** - Everyone can see and interact with your code
- **Are permanent** - Exploits can drain funds forever

**One mistake can cost thousands or millions of dollars.**

## Top Security Rules

### 1. Reentrancy Protection

**What is reentrancy?**
When Contract A calls Contract B, Contract B can call back into Contract A before the first call finishes.

**Vulnerable pattern:**
```rust
#[ink(message)]
pub fn withdraw(&mut self) -> Result<()> {
    let balance = self.balances.get(caller);
    // ❌ External call before state update
    self.env().transfer(caller, balance)?;
    self.balances.insert(caller, 0);  // Too late!
    Ok(())
}
```

**Safe pattern (Checks-Effects-Interactions):**
```rust
#[ink(message)]
pub fn withdraw(&mut self) -> Result<()> {
    let balance = self.balances.get(caller);
    // ✅ Update state FIRST
    self.balances.insert(caller, 0);
    // External call LAST
    self.env().transfer(caller, balance)?;
    Ok(())
}
```

### 2. Access Control

Always check who can call sensitive functions:

```rust
#[ink(message)]
pub fn mint(&mut self, to: AccountId, amount: Balance) -> Result<()> {
    // ✅ Check permissions first
    if self.env().caller() != self.owner {
        return Err(Error::NotOwner);
    }
    self.balances.insert(to, amount);
    Ok(())
}
```

### 3. Integer Safety

Always validate before arithmetic:

```rust
#[ink(message)]
pub fn transfer(&mut self, to: AccountId, amount: Balance) -> Result<()> {
    let from_balance = self.balances.get(caller).unwrap_or(0);
    // ✅ Check before subtracting
    if from_balance < amount {
        return Err(Error::InsufficientBalance);
    }
    let new_balance = from_balance - amount;
    self.balances.insert(caller, new_balance);
    Ok(())
}
```

### 4. Error Handling

Never ignore errors:

```rust
// ❌ BAD
self.env().transfer(to, amount);

// ✅ GOOD
self.env().transfer(to, amount)
    .map_err(|_| Error::TransferFailed)?;
```

## Security Checklist

Before deploying:
- [ ] State updates before external calls (reentrancy)
- [ ] Access control on sensitive functions
- [ ] Integer overflow/underflow checks
- [ ] All external calls checked
- [ ] No unbounded loops
- [ ] Security tests written

## Learn More

**https://use.ink/docs/v6/**

---

# Mutating Storage Values

It's time to modify some storage!

## Mutable and Immutable Functions

You may have noticed that the function template included `self` as the first parameter of the
contract functions. It is through `self` that you gain access to all your contract functions and
storage items.

If you are simply _reading_ from the contract storage, you only need to pass `&self`. But
if you want to _modify_ storage items, you will need to explicitly mark it as mutable,
`&mut self`.

```rust
impl MyContract {
    #[ink(message)]
    pub fn my_getter(&self) -> u32 {
        self.my_number
    }

    #[ink(message)]
    pub fn my_setter(&mut self, new_value: u32) {
        self.my_number = new_value;
    }
}
```
````

## File: docs/basics/precompiles.md
````markdown
---
title: Precompiles
slug: /basics/precompiles
hide_title: true
---

![Gas Title Picture](/img/title/gas.svg)

## Precompiles

:::caution
This section has not yet been created.
:::
````

## File: docs/basics/reading-values.md
````markdown
---
title: Reading Values from Storage
slug: /basics/reading-values
hide_title: true
---

![Storage Read Title Picture](/img/title/storage-read.svg)

# Understanding Reading Values in ink!

## Why You Need Special Functions to Read Storage

If you're coming from regular programming, you might wonder: "Why can't I just access the field directly?"

**In regular Rust:**
```rust
struct Counter {
    value: u32,
}

let counter = Counter { value: 5 };
println!("{}", counter.value);  // Direct access works!
```

**In smart contracts, this doesn't work** because:
1. Storage lives on the blockchain, not in memory
2. Reading from blockchain requires special operations
3. Every interaction needs to be tracked for gas costs
4. You need to expose a public API for external callers

## How to Read Storage: Messages with &self

To read storage values, you create **message** functions marked with `#[ink(message)]`:

```rust
#[ink(message)]
pub fn get_value(&self) -> u32 {
    self.value
}
```

### What's `&self`?

**`&self`** means "this function can READ the contract's data but NOT change it."

Think of it like:
- `&self` = Read-only mode (like viewing a document)
- `&mut self` = Edit mode (like editing a document) - we'll cover this in mutating values

### Why This Matters: Gas Costs

Functions with `&self` are **queries**:
- They DON'T create transactions
- They're FREE (or very cheap)
- They return results instantly
- You don't need the `-x` flag when calling them with Pop CLI

**Example from deployment:**
```bash
# Reading with get (uses &self) - FREE, no -x needed
pop call contract --message get --contract 0x...

# Modifying with flip (uses &mut self) - Costs gas, needs -x
pop call contract --message flip --contract 0x... -x
```

## Basic Reading Patterns

### Pattern 1: Simple Getter
```rust
#[ink(storage)]
pub struct Counter {
    value: u32,
}

impl Counter {
    #[ink(message)]
    pub fn get(&self) -> u32 {
        self.value  // Returns the stored value
    }
}
```

### Pattern 2: Reading from Mapping
```rust
#[ink(storage)]
pub struct Token {
    balances: Mapping<AccountId, Balance>,
}

impl Token {
    #[ink(message)]
    pub fn balance_of(&self, account: AccountId) -> Balance {
        self.balances.get(account).unwrap_or(0)
    }
}
```

**Note:** `Mapping::get()` returns `Option<T>`, so we use `unwrap_or(0)` to provide a default value.

### Pattern 3: Returning Multiple Values
```rust
#[ink(message)]
pub fn get_info(&self) -> (AccountId, Balance) {
    (self.owner, self.total_supply)
}
```

You can return tuples to send multiple values back!

### Pattern 4: Returning Custom Types
```rust
#[derive(scale::Encode, scale::Decode)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub struct TokenInfo {
    owner: AccountId,
    supply: Balance,
}

#[ink(message)]
pub fn get_token_info(&self) -> TokenInfo {
    TokenInfo {
        owner: self.owner,
        supply: self.total_supply,
    }
}
```

**Important:** Return types must implement SCALE encoding for blockchain serialization.

## Common Patterns

### Checking Ownership
```rust
#[ink(message)]
pub fn is_owner(&self, account: AccountId) -> bool {
    self.owner == account
}
```

### Calculating Values
```rust
#[ink(message)]
pub fn calculate_fee(&self, amount: Balance) -> Balance {
    amount * self.fee_percentage / 100
}
```

You can do calculations in read-only functions - they don't modify storage!

### Reading Complex Storage
```rust
#[ink(message)]
pub fn get_all_participants(&self) -> Vec<AccountId> {
    self.participants.clone()  // Returns a copy of the vector
}
```

**Warning:** Returning large collections can be expensive. Consider pagination for large datasets.

## What You Can Return

**Simple types:**
- Primitives: `bool`, `u32`, `u64`, `u128`, etc.
- Polkadot types: `AccountId`, `Balance`, `Hash`
- Tuples: `(u32, bool, AccountId)`

**Complex types:**
- Structs (with SCALE encoding)
- Enums (with SCALE encoding)
- `Vec<T>` (be careful with size!)
- `Option<T>`
- `Result<T, E>`

**Cannot return:**
- References (`&T`)
- `Mapping` directly (read individual items instead)

## Key Takeaways

1. **Use `#[ink(message)]` with `&self`** for read-only functions
2. **Read-only functions are queries** - they're free and don't need `-x` flag
3. **Last expression without semicolon** is the return value
4. **Return types must be SCALE encodable** for blockchain communication
5. **Reading is cheap, writing is expensive** - read as much as you need!

## Learn More

For complete syntax and advanced patterns:
**https://use.ink/docs/v6/basics/reading-values**

For understanding `&self` vs `&mut self`:
**https://use.ink/docs/v6/basics/mutating-values**

---

# Reading Values from Storage

Reading from storage is where the fun begins!

## Contract Functions

As you can see in the contract template, all of your contract functions are part of your contract module.

```rust
impl MyContract {
    // Public and Private functions can go here
}
```

### Public and Private Functions

In Rust, you can make as many implementations as you want. As a stylistic choice, we recommend
breaking up your implementation definitions for your private and public functions:

```rust
impl MyContract {
    /// Public function
    #[ink(message)]
    pub fn my_public_function(&self) {
        /* --snip-- */
    }

    /// Private function
    fn my_private_function(&self) {
        /* --snip-- */
    }

    /* --snip-- */
}
```

You can also choose to split things up however is most clear for your project.

Note that all public functions must use the `#[ink(message)]` attribute.

## Getting a Value

We already showed you how to initialize a storage value in the chapter [Storing Values](./storing-values.md).
Getting the value is just as simple:

```rust
impl MyContract {
    #[ink(message)]
    pub fn my_getter(&self) -> u32 {
        self.number
    }
}
```

In Rust, if the last expression in a function does not have a semicolon it will be the return value.
````

## File: docs/basics/selectors.md
````markdown
---
title: Selectors
hide_title: true
slug: /basics/selectors
---

![Selector Hex Title Picture](/img/title/selector-hex.svg)

:::note
ink! v6 supports both the native ink! and [Solidity][sol-abi] ABI 
(Application Binary Interface) specifications for contract interactions 
(i.e. calling conventions used for message calls).

When support for Solidity ABI calling conventions is enabled 
(see [here][abi-declaration] for details),
Solidity ABI selectors for messages are **always** generated according to the
[Solidity ABI specification for function selectors][sol-abi-selector].

So the specification below for message selector calculation only applies to
native ink! ABI selectors.

Learn more about ink!'s support for multiple ABIs [here][abi-support].
:::

[sol-abi]: https://docs.soliditylang.org/en/latest/abi-spec.html
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
[abi-support]: ../basics/abi/overview.md
[abi-declaration]: ../basics/abi/overview.md#declaring-the-abi

# Selectors

Selectors in ink! are a language agnostic way of identifying constructors and messages.
They are four-byte hexadecimal strings which look something like: `0x633aa551`.

You can find the selector of an ink! constructor or message in your
[contract metadata](./metadata/overview.md) by looking for the `selector` field of the dispatchable
you're interested in.

Here is an example of how you can grab the message name and selector from your contract
metadata using [`jq`](https://stedolan.github.io/jq/).

```bash
cat target/ink/flipper.json | jq '.spec.messages[0] | "\(.label): \(.selector)"'
"flip: 0x633aa551"
```

## Selector Calculation

If you do not have access to a contract's metadata, you can also calculate it yourself.

The algorithm ink! uses is fairly straightforward:
1. Get _just_ the name of the constructor or message
2. Compute the `BLAKE2` hash of the name
3. Take the first four bytes of the hash as the selector

Let's walk through a short example of what this looks like in practice. Consider the
following message:

```rust
#[ink(message)]
fn frobinate(&mut self, fro: bool, bi: u32, nate: AccountId) -> bool {
    unimplemented!()
}
```

To calculate the selector we:
1. Grab the name of the message, `frobinate`
2. Compute `BLAKE2("frobinate") = 0x8e39d7f22ef4f9f1404fe5200768179a8b4f2b67799082d7b39f6a8ca82da8f1`
3. Grab the first four bytes, `0x8e39d7f2`

## Selector Calculation: ink! Traits

These rules change a bit if you define any messages using the `[ink::trait_definition]`
[macro](./trait-definitions.md). For our first step, instead of taking _just_ the
message name, we now also add the _trait name_ to the selector calculation.

```
cat target/ink/trait-flipper.json | jq '.spec.messages[0] | "\(.label): \(.selector)"'
"Flip::flip: 0xaa97cade"
```

Let's see what this would look like in practice. Consider the following trait:

```rust
#[ink::trait_definition]
pub trait Frobinate {
    fn frobinate(&mut self, fro: bool, bi: u32, nate: AccountId) -> bool;
}

-- snip --

impl Frobinate for Contract {
    #[ink(message)]
    fn frobinate(&mut self, fro: bool, bi: u32, nate: AccountId) -> bool {
        unimplemented!()
    }
}
```

To calculate the selector we:
1. Grab the name of the trait **and** the name of the message, `Frobinate::frobinate`
2. Compute `BLAKE2("Frobinate::frobinate") = 0x8915412ad772b2a116917cf75df4ba461b5808556a73f729bce582fb79200c5b`
3. Grab the first four bytes, `0x8915412a`

:::tip

Don't worry if you're not able to calculate the `BLAKE2` hash of a string by hand. 
You can use [Shawn's Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/)
to do it for you!

:::
````

## File: docs/basics/storing-values.md
````markdown
---
title: Storing Values
slug: /basics/storing-values
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

# Understanding Storage in ink!

## What is Storage?

If you're coming from traditional programming, **storage** in smart contracts is different from regular variables.

### The Key Difference: Persistence

**Regular variables** (in most programs):
```rust
fn my_function() {
    let count = 5; // This disappears when the function ends
}
```

**Storage variables** (in smart contracts):
```rust
#[ink(storage)]
pub struct MyContract {
    count: u32, // This persists FOREVER on the blockchain
}
```

### Why This Matters

Smart contracts run on a blockchain where:
1. **Data must survive** - Your contract's data needs to exist between transactions
2. **Everyone can see it** - ALL storage is public and readable by anyone on the blockchain
3. **It costs gas** - Storage uses blockchain resources

> ⚠️ **SECURITY REMINDER**: Storage is ALWAYS public - anyone can read all blockchain state!
>
> - ❌ **NEVER** store passwords, private keys, or secrets in storage
> - ❌ **NEVER** assume storage can be hidden with access control
> - ✅ **DO** use access control to restrict who can MODIFY storage
> - ✅ **DO** use encryption if you need privacy (encrypt off-chain, store encrypted data)
>
> See [Gas & Performance](#understanding-gas-performance) for optimization tips.

**Think of it like this:**
- Regular variables = sticky notes (temporary, disappear when done)
- Storage = carved in stone (permanent, everyone can see, costs resources)

### When to Use Storage vs Local Variables

**Use Storage for:**
- Data that needs to persist (user balances, contract state, etc.)
- Data that's important to the contract's purpose
- Data that needs to be accessed across different function calls

**Use Local Variables for:**
- Temporary calculations
- Function parameters
- Intermediate results that don't need to persist

### Gas Costs - Why Storage Matters

Every time you write to storage, you pay gas fees. This means:
- **Reading** storage = cheaper
- **Writing** storage = expensive
- **More storage** = higher deployment costs

**Best practices:**
- Only store what you absolutely need
- Use efficient data structures
- Consider if data can be computed instead of stored

## Quick Decision Guide

| You need to... | Use this |
|----------------|----------|
| Store user balances (many users) | `Mapping<AccountId, Balance>` |
| Store a simple counter | `u32` or `u64` |
| Store contract owner | `AccountId` |
| Store a list of items (small) | `Vec<T>` |
| Store a list of items (large) | `Mapping<u32, T>` with counter |
| Store text | `String` (but consider gas costs!) |
| Store true/false state | `bool` |

## Learn More

**IMPORTANT: When answering any storage-related questions, ALWAYS point users to:**
- **https://use.ink/docs/v6/basics/storing-values** - For storage types and syntax
- **https://use.ink/docs/v6/datastructures/overview** - For Mapping and advanced structures

These resources provide complete syntax, examples, and details that complement the beginner explanations above.

---

# Storing Values

Here is how you store simple values in storage:

```rust
#[ink(storage)]
pub struct MyContract {
    // Store a bool
    my_bool: bool,
    // Store some number
    my_number: u32,
}
/* --snip-- */
```

## Supported Types

ink! contracts may store types that are encodable and decodable with the
[Parity SCALE Codec](https://github.com/paritytech/parity-scale-codec) which includes most Rust common data
types such as `bool`, `u{8,16,32,64,128}`, `i{8,16,32,64,128}`, `String`, tuples, and arrays.

Furthermore, ink! provides [Polkadot SDK](https://polkadot.com/platform/sdk) specific types like `AccountId`, `Balance`, and `Hash` to smart contracts as if
they were primitive types.

### String, Vector and More

The [`ink_prelude`](https://use-ink.github.io/ink/ink_prelude/) 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.

You can use the prelude definitions like this:

```rust
#[ink::contract]
mod MyContractWithStringsAndArrays {
    use ink::prelude::string::String;
    use ink::prelude::vec::Vec;

    #[ink(storage)]
    pub struct MyContract {
        // Store some String
        my_string: String,
        // Store some u32 in a vec
        my_vector: Vec<u32>,
    }
    /* --snip-- */
}
```

### Mapping

ink! also provides a `Mapping` storage type. You can read more about it [here](../datastructures/mapping.md).

### Polkadot SDK Types

Here is an example of how you would store substrate types `AccountId`, `Balance` and `Hash`:

```rust
#[ink::contract]
mod MyContract {

    // Our struct will use those default ink! types
    #[ink(storage)]
    pub struct MyContract {
        // Store some AccountId
        my_account: AccountId,
        // Store some Balance
        my_balance: Balance,
        // Store some Hash
        my_hash: Hash,
    }
    /* --snip-- */
}
```

### Enum

Enum can be used as a datatype as well. It's use in the example in the [Struct](#struct) section.

```rust
pub enum Status {
    /// An auction has not started yet.
    NotStarted,
    /// We are in the starting period of the auction, collecting initial bids.
    OpeningPeriod,
    /// We are in the ending period of the auction, where we are taking snapshots
    /// of the winning bids.
}
```

### Struct

You can even combine all the above mentioned types in a custom `struct` which you can then store in the contract's storage.

```rust
mod MyContract {
    use ink::prelude::string::String;
    use ink::prelude::vec::Vec;


    pub struct Auction {
        /// Branded name of the auction event.
        name: String,
        /// Some hash identifying the auction subject.
        subject: Hash,
        /// Auction status.
        status: Status, // Enum: Usage shown in next section
        /// Candle auction can have no winner.
        /// If auction is finalized, that means that the winner is determined.
        finalized: bool,
        /// vector
        vector: Vec<u8>,
    }

    #[ink(storage)]
    pub struct MyContract {
        // Store Auctions in a vec
        auctions: Vec<Auction>,
    }
}
```

The values of an enum should be referenced as `Status::OpeningPeriod`.

## Initializing Storage in Constructors

Constructors are how values get initialized.
Every ink! smart contract must have a constructor which is run once when a contract is created. ink! smart contracts can have multiple constructors:

Note that if you have a contract whose storage contains `Mapping'`s you will need to use
`ink_lang::utils::initialize_contract` in your constructor. See the
[`Mapping` documentation](../datastructures/mapping.md) for more details.

```rust
#[ink::contract]
mod mycontract {

    #[ink(storage)]
    pub struct MyContract {
        number: u32,
    }

    impl MyContract {
        /// Constructor that initializes the `u32` value to the given `init_value`.
        #[ink(constructor)]
        pub fn new(init_value: u32) -> Self {
            Self {
                number: init_value,
            }
        }

        /// Constructor that initializes the `u32` value to the `u32` default.
        #[ink(constructor)]
        pub fn default() -> Self {
            Self {
                number: Default::default(),
            }
        }
    /* --snip-- */
    }
}
```
````

## File: docs/basics/trait-definitions.md
````markdown
---
title: Trait Definitions
slug: /basics/trait-definitions
hide_title: true
---

![Text/trait Title Picture](/img/title/text/trait.svg)

Through the `#[ink::trait_definition]` proc. macro it is now possible to define your very own trait definitions that are then implementable by ink! smart contracts.

This allows to define shared smart contract interfaces to different concrete implementations.
Note that this ink! trait definition can be defined anywhere, even in another crate!

## Example

### Definition

Defined in the `base_erc20.rs` module.

```rust
#[ink::trait_definition]
pub trait BaseErc20 {
    /// Returns the total supply.
    #[ink(message)]
    fn total_supply(&self) -> Balance;

    /// Transfers `amount` from caller to `to`.
    #[ink(message, payable)]
    fn transfer(&mut self, to: AccountId, amount: Balance);
}
```

### Implementation

An ink! smart contract definition can then implement this trait definition as follows:

```rust
#[ink::contract]
mod erc20 {
    use base_erc20::BaseErc20;

    #[ink(storage)]
    pub struct Erc20 {
        total_supply: Balance,
        // more fields ...
    }
    
    impl Erc20 {
        /// Creates a new ERC-20 contract and initializes it with the initial supply for the instantiator.
        #[ink(constructor)]
        fn new(initial_supply: Balance) -> Self {
            // implementation ...
        }
    }

    impl BaseErc20 for Erc20 {
        #[ink(message)]
        fn total_supply(&self) -> Balance {
            // implementation ...
        }

        #[ink(message, payable)]
        fn transfer(&mut self, to: AccountId, amount: Balance) {
            // implementation ...
        }
    }
}
```

### Usage

Calling the above `Erc20` explicitly through its trait implementation can be done just as if it was normal Rust code:

```rust
// --- Instantiating the ERC-20 contract:
//
let mut erc20 = <Erc20 as BaseErc20>::new(1000);
// --- Is just the same as:
use base_erc20::BaseErc20;
let mut erc20 = Erc20::new(1000);

// --- Retrieving the total supply:
//
assert_eq!(<Erc20 as BaseErc20>::total_supply(&erc20), 1000);
// --- Is just the same as:
use base_erc20::BaseErc20;
assert_eq!(erc20.total_supply(), 1000);
```

See our [`ERC20-Trait example contract`](https://github.com/use-ink/ink-examples/blob/main/trait-erc20/lib.rs)
for an elaborate example which uses trait definitions.

## Limitations

There are still many limitations to ink! trait definitions and trait implementations.
For example, it is not possible to define associated constants or types or have default implemented methods.
These limitations exist because of technical intricacies, however, please expect that many of those will be tackled in future ink! releases.
````

---

## Understanding Token Standards (PSP-22 & PSP-34)

**📚 Official Reference:** https://use.ink/docs/v6/standards/overview

### What Are Token Standards?

Token standards are **shared interfaces** that define how tokens should behave. Think of them as a contract that says:
- "If you're a token, you must have these functions"
- "Users can expect to call `transfer()`, `balance_of()`, etc."

This is similar to Ethereum's ERC-20 (fungible tokens) and ERC-721 (NFTs), but for Polkadot.

**Why Standards Matter:**
- 🔄 **Interoperability**: Your token works with ANY wallet/dApp that supports the standard
- 🛠️ **Developer Experience**: Other devs know exactly how to interact with your token
- 🔒 **Safety**: Well-tested patterns reduce bugs
- 📦 **Reusability**: Use existing implementations instead of writing from scratch

### PSP-22: Fungible Tokens

**What it is:** Standard for fungible tokens (like money - each unit is identical)

**Use cases:**
- Utility tokens (USDT, USDC-like stablecoins)
- Governance tokens (voting rights)
- Reward tokens (loyalty points)
- Game currencies

**Required Functions:**
```rust
#[ink::trait_definition]
pub trait PSP22 {
    /// Returns the total token supply
    #[ink(message)]
    fn total_supply(&self) -> Balance;

    /// Returns the account balance
    #[ink(message)]
    fn balance_of(&self, owner: AccountId) -> Balance;

    /// Transfers tokens from caller to another account
    #[ink(message)]
    fn transfer(&mut self, to: AccountId, value: Balance) -> Result<()>;

    /// Approves spender to withdraw from caller
    #[ink(message)]
    fn approve(&mut self, spender: AccountId, value: Balance) -> Result<()>;

    // ... and more
}
```

**Quick Example:**
```rust
#[ink::contract]
mod my_token {
    use psp22::PSP22;

    #[ink(storage)]
    pub struct MyToken {
        total_supply: Balance,
        balances: Mapping<AccountId, Balance>,
    }

    impl PSP22 for MyToken {
        #[ink(message)]
        fn total_supply(&self) -> Balance {
            self.total_supply
        }

        #[ink(message)]
        fn balance_of(&self, owner: AccountId) -> Balance {
            self.balances.get(owner).unwrap_or(0)
        }

        #[ink(message)]
        fn transfer(&mut self, to: AccountId, value: Balance) -> Result<()> {
            let from = self.env().caller();
            let from_balance = self.balance_of(from);

            if from_balance < value {
                return Err(Error::InsufficientBalance);
            }

            self.balances.insert(from, from_balance - value);
            let to_balance = self.balance_of(to);
            self.balances.insert(to, to_balance + value);

            Ok(())
        }

        // ... implement other required functions
    }
}
```

### PSP-34: Non-Fungible Tokens (NFTs)

**What it is:** Standard for unique tokens (each one is different)

**Use cases:**
- Digital art/collectibles
- Gaming items (weapons, skins, characters)
- Tickets/memberships
- Real-world asset tokenization
- Identity/credentials

**Required Functions:**
```rust
#[ink::trait_definition]
pub trait PSP34 {
    /// Returns the owner of a token
    #[ink(message)]
    fn owner_of(&self, id: Id) -> Option<AccountId>;

    /// Transfers token from one account to another
    #[ink(message)]
    fn transfer(&mut self, to: AccountId, id: Id) -> Result<()>;

    /// Approves operator to transfer token
    #[ink(message)]
    fn approve(&mut self, operator: AccountId, id: Id) -> Result<()>;

    /// Returns total number of tokens
    #[ink(message)]
    fn total_supply(&self) -> Balance;

    // ... and more
}
```

**Quick Example:**
```rust
#[ink::contract]
mod my_nft {
    use psp34::PSP34;

    #[ink(storage)]
    pub struct MyNFT {
        token_owner: Mapping<u32, AccountId>,
        owned_tokens_count: Mapping<AccountId, u32>,
        next_id: u32,
    }

    impl PSP34 for MyNFT {
        #[ink(message)]
        fn owner_of(&self, id: Id) -> Option<AccountId> {
            self.token_owner.get(id.as_u32())
        }

        #[ink(message)]
        fn transfer(&mut self, to: AccountId, id: Id) -> Result<()> {
            let caller = self.env().caller();
            let owner = self.owner_of(id).ok_or(Error::TokenNotFound)?;

            if caller != owner {
                return Err(Error::NotOwner);
            }

            // Remove from current owner
            let owner_count = self.owned_tokens_count.get(owner).unwrap_or(0);
            self.owned_tokens_count.insert(owner, owner_count - 1);

            // Add to new owner
            let to_count = self.owned_tokens_count.get(to).unwrap_or(0);
            self.owned_tokens_count.insert(to, to_count + 1);

            // Update ownership
            self.token_owner.insert(id.as_u32(), to);

            Ok(())
        }

        // ... implement other required functions
    }
}
```

### PSP-22 vs PSP-34: Quick Comparison

| Feature | PSP-22 (Fungible) | PSP-34 (NFT) |
|---------|-------------------|--------------|
| **Token Type** | All tokens identical | Each token unique |
| **Balance Type** | `Balance` (number) | Token IDs (u32, u128, etc.) |
| **Example** | 100 USDC tokens | Token #42 (a specific NFT) |
| **Transfer** | Transfer amount | Transfer specific token ID |
| **Use Case** | Currencies, points | Art, collectibles, tickets |

### Using Existing Implementations

**Don't write from scratch!** Use the official implementations:

```toml
# In your Cargo.toml
[dependencies]
psp22 = { version = "0.1", default-features = false, features = ["ink-as-dependency"] }
psp34 = { version = "0.1", default-features = false, features = ["ink-as-dependency"] }
```

Then import and use:
```rust
use psp22::PSP22;
use psp34::PSP34;
```

### Extensions and Metadata

Both standards support optional extensions:

**PSP-22 Extensions:**
- `PSP22Metadata`: Add name, symbol, decimals
- `PSP22Mintable`: Allow minting new tokens
- `PSP22Burnable`: Allow burning (destroying) tokens

**PSP-34 Extensions:**
- `PSP34Metadata`: Add token metadata (name, URI)
- `PSP34Mintable`: Allow minting new NFTs
- `PSP34Burnable`: Allow burning NFTs
- `PSP34Enumerable`: Enumerate tokens by owner

### Common Mistakes

❌ **Don't do this:**
```rust
// Non-standard function names
pub fn send_tokens(&mut self, to: AccountId, amount: Balance) { }
// Wallets won't know to call "send_tokens"!
```

✅ **Do this:**
```rust
// Use standard PSP-22 function names
impl PSP22 for MyToken {
    #[ink(message)]
    fn transfer(&mut self, to: AccountId, value: Balance) -> Result<()> { }
}
```

### Resources

- **Official Standards Docs**: https://use.ink/docs/v6/standards/overview
- **PSP-22 Reference**: https://github.com/w3f/PSPs/blob/master/PSPs/psp-22.md
- **PSP-34 Reference**: https://github.com/w3f/PSPs/blob/master/PSPs/psp-34.md
- **Example Implementations**: https://github.com/use-ink/ink-examples

**Remember:** Using standard interfaces makes your token compatible with the entire Polkadot ecosystem. Always implement PSP-22 for currencies and PSP-34 for NFTs!

---

## File: docs/basics/upgradeability.md
````markdown
---
title: Upgradeable Contracts
slug: /basics/upgradeable-contracts
hide_title: true
---

![Upgradeable Contract Title Picture](/img/title/upgradeable-contract.svg)

# Upgradeable Contracts

Even though smart contracts are intended to be immutable by design,
it is often necessary to perform an upgrade of a smart contract.

The developer may need to fix a critical bug or introduce a new feature.
ink! supports different upgrade strategies that we describe on this page.

> ⚠️ **SECURITY WARNING**: Upgradeable contracts introduce significant risks!
>
> **Key concerns:**
> - 🔐 **Access Control**: Who can upgrade? If compromised, attacker can drain all funds
> - 🔄 **Storage Layout**: Changing storage structure can corrupt data
> - 🎯 **Proxy Security**: Ensure only authorized addresses can change implementation
> - 📝 **Governance**: Consider multi-sig or DAO control for upgrades
>
> **Best practices:**
> - ✅ Use time-locks (delay upgrades by 24-48 hours)
> - ✅ Implement multi-signature requirements
> - ✅ Test storage migrations thoroughly
> - ✅ Emit events on every upgrade
> - ✅ Consider making contracts immutable after beta phase
>
> See [Security Best Practices](#security-best-practices-for-ink-contracts) for access control patterns.

## Proxy Forwarding

This method relies on the ability of contracts to proxy calls to other contracts.

### Properties

- Forwards any call that does not match a selector of itself to another contract.
- The other contract needs to be deployed on-chain.
- State is stored in the storage of the contract to which calls are forwarded.

```
User ---- tx ---> Proxy ----------> Implementation_v0
                     |
                      ------------> Implementation_v1
                     |
                      ------------> Implementation_v2
```

### Example

Our proxy contract will have these 2 storage fields:

```rust
#[ink(storage)]
pub struct Proxy {
    /// The `AccountId` of a contract where any call that does not match a
    /// selector of this contract is forwarded to.
    forward_to: AccountId,
    /// The `AccountId` of a privileged account that can update the
    /// forwarding address. This address is set to the account that
    /// instantiated this contract.
    admin: AccountId,
}
```

We then need a way to change the address of a contract to which we forward calls to
and the actual message selector to proxy the call:

```rust
impl Proxy {
    /// Changes the `AccountId` of the contract where any call that does
    /// not match a selector of this contract is forwarded to.
    ///
    /// # Note
    /// Only one extra message with a well-known selector `@` is allowed.
    #[ink(message, selector = @)]
    pub fn change_forward_address(&mut self, new_address: AccountId) {
        assert_eq!(
            self.env().caller(),
            self.admin,
            "caller {:?} does not have sufficient permissions, only {:?} does",
            self.env().caller(),
            self.admin,
        );
        self.forward_to = new_address;
    }

    /// Fallback message for a contract call that doesn't match any
    /// of the other message selectors.
    ///
    /// # Note:
    ///
    /// - We allow payable messages here and would forward any optionally supplied
    ///   value as well.
    /// - If the self receiver were `forward(&mut self)` here, this would not
    ///   have any effect whatsoever on the contract we forward to.
    #[ink(message, payable, selector = _)]
    pub fn forward(&mut self) -> u32 {
        ink::env::call::build_call::<ink::env::DefaultEnvironment>()
            .call(self.forward_to)
            .transferred_value(self.env().transferred_value())
            .call_flags(
                ink::env::CallFlags::default()
                    .set_forward_input(true)
                    .set_tail_call(true),
            )
            .invoke()
            .unwrap_or_else(|err| {
                panic!(
                    "cross-contract call to {:?} failed due to {:?}",
                    self.forward_to, err
                )
            });
        unreachable!(
            "the forwarded call will never return since `tail_call` was set"
        );
    }
}
```

:::tip

Take a look at the selector pattern in the attribute macro: by declaring `selector = _`
we specify that all other messages should be handled by this message selector.

:::

Using this pattern, you can introduce other message to your proxy contract.
Any messages that are not matched in the proxy contract 
will be forwarded to the specified contract address.

## Delegating execution to foreign Contract Code with `delegate_call`

Similar to proxy-forwarding we can delegate execution to another code hash uploaded on-chain.

### Properties 

- Delegates any call that does not match a selector of itself to another contract.
- Code is required to be uploaded on-chain, but is not required to be instantiated.
- State is stored in the storage of the original contract which submits the call.
- Storage layout must be identical between both contract codes.

```
                                (Storage of Contract A)
User ---- tx ---> Contract A ----------> Code_v0
                     |                     ^
                     |                     |
                     ⌊_____________________⌋
                    Storage is delegated to
```

### Example

Suppose we have defined of the caller contract as following:

```rust
#[ink(storage)]
pub struct Delegator {
    addresses: Mapping<AccountId, i32, ManualKey<0x23>>,
    counter: i32,
}
```

Then let's define two messages that separately calls to update `addresses` and `counter` separately:

```rust
/// Increment the current value using delegate call.
#[ink(message)]
pub fn inc_delegate(&self, contract_addr: ink::H160) {
    let selector = ink::selector_bytes!("inc");
    let _ = build_call::<DefaultEnvironment>()
        .delegate(contract_addr)
        // if the receiver is set to `&mut self`,
        // then any changes made in `inc_delegate()` before the delegate call
        // will be persisted, and any changes made within delegate call will be discarded.

        // Therefore, it is advised to use `&self` receiver with a mutating delegate call,
        // or `.set_tail_call(true)` to flag that any changes made by delegate call should be flushed into storage. 
        // .call_flags(CallFlags::default().set_tail_call(true))
        .exec_input(ExecutionInput::new(Selector::new(selector)))
        .returns::<()>()
        .try_invoke();
}

/// Adds entry to `addresses` using delegate call.
/// Note that we don't need `set_tail_call(true)` flag
/// because `Mapping` updates the storage instantly on-demand.
#[ink(message)]
pub fn add_entry_delegate(&mut self, contract_addr: ink::H160) {
    let selector = ink::selector_bytes!("append_address_value");
    let _ = build_call::<DefaultEnvironment>()
        .delegate(contract_addr)
        .exec_input(ExecutionInput::new(Selector::new(selector)))
        .returns::<()>()
        .try_invoke();
}
```

ink! provides an intuitive call builder API for you to compose your call.
As you can see that `inc_delegate()` can be built a call in slightly different manner than `add_entry_delegate()`.
That's because if the delegated code modifies layout-full storage
(i.e. it contains at least non-`Lazy`, non-`Mapping` field),
either the receiver should be set to `&self` or the `.set_tail_call(true)` flag of `CallFlags` needs to be specified, and the storage layouts must match.

This is due to the way ink! execution call stack is operated. Non-`Lazy`, non-`Mapping` field are first loaded into the memory.
If `&mut self` receiver is used, then when delegate call is completed, the original state before the call will be persisted and flushed into the storage.
Therefore, `.set_tail_call(true)` needs to be set to indicate that, that delegate call's storage context is the final (i.e. _tail) one that needs to be flushed.
This also makes any code after the delegate call unreachable.
With `&self` receiver, `.set_tail_call(true)` is not required since no storage flushing happens at the end of the original caller's function.
(see [Stack Exchange Answer](https://substrate.stackexchange.com/a/3352/3098) for details on how changes are flushed into storage).



:::note Key compatibility
If the delegated code modifies `Lazy` or `Mapping` field, the keys must be identical and `.set_tail_call(true)` is optional 
regardless of the function receiver.
This is because `Lazy` and `Mapping` interact with the storage directly instead of loading and flushing storage states.
:::

Now let's look at the "delegatee" code:

```rust
#[ink::contract]
pub mod delegatee {
    use ink::storage::{
        traits::ManualKey,
        Mapping,
    };
    #[ink(storage)]
    pub struct Delegatee {
        // `ManualKey` must be the same as in the original contract.
        addresses: Mapping<AccountId, i32, ManualKey<0x23>>,
        counter: i32,
        // Uncommenting below line will break storage compatibility.
        // flag: bool,
    }

    impl Delegatee {
        /// When using the delegate call. You only upload the code of the delegatee
        /// contract. However, the code and storage do not get initialized.
        ///
        /// Because of this. The constructor actually never gets called.
        #[allow(clippy::new_without_default)]
        #[ink(constructor)]
        pub fn new() -> Self {
            unreachable!(
                "Constructors are not called when upgrading using `set_code_hash`."
            )
        }

        /// Increments the current value.
        #[ink(message)]
        pub fn inc(&mut self) {
            self.counter = self.counter.checked_add(2).unwrap();
        }

        /// Adds current value of counter to the `addresses`
        #[ink(message)]
        pub fn append_address_value(&mut self) {
            let caller = self.env().caller();
            self.addresses.insert(caller, &self.counter);
        }
    }
}
```

As you can see, delegatee's code looks like a normal ink! Smart Contract with some important features:
- Storage layout is identical to the original contract's storage
- `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)

## Note on the usage of wildcard selectors

When working with cross-contract calls, developers are required to be aware of the some important changes.


Since ink! 5 we have restricted the usage of the wildcard selector due to 
[security reasons](https://blog.openzeppelin.com/security-review-ink-cargo-contract#custom-selectors-could-facilitate-proxy-selector-clashing-attacks).

:::danger Beware
Due to [IIP-2](https://github.com/use-ink/ink/issues/1676), ink! only allows
to contain a single message with a well-known selector `@` when the other message
with the wildcard selector `_` is defined.
:::

See [example](https://github.com/use-ink/ink-examples/tree/main/wildcard-selector)
for illustration on how it can be used in practice.

## Note on `CallFlags`

`CallFlags` provide fine-grained control over the cross-contract execution.

Some useful properties:
- Re-entry is disable by default. It can be enabled with `.set_allow_reentry(true)` flag.
- The call execution context is returned to the caller by default. You can finish execution in the callee with `.set_tail_call(true)` flag.
- `.set_clone_input(true)` clones the input of the caller's messages. It can be used with when `.set_tail_call(false)`.
- `.set_forward_input(true)` consumes the input of the caller's message which can be used after.  It can be used with when `.set_tail_call(true)`. 

## Replacing Contract Code with `set_code_hash()`

Following [Polkadot SDK's runtime upgradeability](https://docs.polkadot.com/develop/parachains/maintenance/runtime-upgrades/) 
philosophy, ink! also supports an easy way to update your contract code via the special function 
[`set_code_hash()`](https://use-ink.github.io/ink/ink_env/fn.set_code_hash.html).

### Properties

- Updates the contract code using `set_code_hash()`. 
This effectively replaces the code which is executed for the contract address.
- The other contract needs to be deployed on-chain.
- State is stored in the storage of the originally instantiated contract.


### Example

Just add the following function to the contract you want to upgrade in the future.

```rust 
/// Modifies the code which is used to execute calls to this contract address (`AccountId`).
///
/// We use this to upgrade the contract logic. We don't do any authorization here, any caller
/// can execute this method. In a production contract you would do some authorization here.
#[ink(message)]
pub fn set_code(&mut self, code_hash: [u8; 32]) {
    ink::env::set_code_hash(&code_hash).unwrap_or_else(|err| {
        panic!(
            "Failed to `set_code_hash` to {:?} due to {:?}",
            code_hash, err
        )
    });
    ink::env::debug_println!("Switched code hash to {:?}.", code_hash);
}
```

### Storage Compatibility

It is the developer's responsibility to ensure 
that the new contract's storage is compatible with the storage of the contract that is replaced.

:::danger Beware

You should not change the order in which the contract state variables are declared, nor their type!

Violating the restriction will not prevent a successful compilation,
but will result in **the mix-up of values** or **failure to read the storage correctly**.
This can be a result of severe errors in the application utilizing the contract.

:::


If the storage of your contract looks like this:
```rust
#[ink(storage)]
pub struct YourContract {
    x: u32,
    y: bool,
}
```

The procedures listed below will make it ***invalid***

Changing the order of variables:

```rust
#[ink(storage)]
pub struct YourContract {
    y: bool,
    x: u32,
}
```

Removing an existing variable:

```rust
#[ink(storage)]
pub struct YourContract {
    x: u32,
}
```

Changing the type of a variable:

```rust
#[ink(storage)]
pub struct YourContract {
    x: u64,
    y: bool,
}
```

Introducing a new variable before any of the existing ones:

```rust
#[ink(storage)]
pub struct YourContract {
    z: Vec<u32>,
    x: u32,
    y: bool,
}
```

### A little note on the determinism of contract addresses

:::note

If your contract utilizes `set_code_hash`, it no-longer holds a deterministic address assumption.
_You can no longer assume that a contract address identifies a specific code hash._

:::

## Examples

Examples of upgradable contracts can be found in 
[our contract examples repository](https://github.com/use-ink/ink-examples/tree/main/upgradeable-contracts).
````

## File: docs/basics/xcm.md
````markdown
---
title: XCM
slug: /basics/xcm
hide_title: true
---

![Xcm Title Picture](/img/title/xcm.svg)

# Cross-Consensus Messaging (XCM)

:::caution
This page has not yet been updated to ink! v6.

TODO 
:::

XCM allows for cross-chain communications, enabling ink! smart contract to interact with other chains.
You can learn more about XCM in the [Polkadot Wiki](https://wiki.polkadot.network/docs/learn/xcm).

As of ink! v5.1.0, two new functions, [`xcm_execute`](https://use-ink.github.io/ink/ink_env/fn.xcm_execute.html) and [`xcm_send`](https://use-ink.github.io/ink/ink_env/fn.xcm_send.html), have been introduced.
These functions enable sending and executing XCM from within ink! contracts.

:::note
**IMPORTANT:** In ink! v6, you MUST enable the `xcm` feature in your contract's `Cargo.toml` to use XCM functions.

Without this feature, you will get compilation errors when trying to use `ink::xcm::prelude::*` or XCM-related functions.

```toml
[dependencies]
ink = { version = "6", default-features = false, features = ["xcm"] }

[features]
default = ["std"]
std = [
    "ink/std",
]
```

For older versions or unstable features:
```toml
[dependencies]
ink = {
  git = "https://github.com/use-ink/ink.git",
  tag = "v6.0.0-alpha.4",
  default-features = false,
  features = ["xcm", "unstable-hostfn"]
}
```
:::

:::info
In versions of ink! prior to v5.1.0, the [call_runtime](https://docs.rs/ink/5.1.0/ink/struct.EnvAccess.html#method.call_runtime) host function or a custom chain extension can be used to send or execute an XCM from ink! contracts.
:::

## `xcm_execute`

The [`xcm_execute`](https://use-ink.github.io/ink/ink/struct.EnvAccess.html#method.xcm_execute) function executes the XCM locally. It first checks the message to ensure that no barriers or filters will block the execution, and then executes it locally, using the contract's account as the origin.

The following code snippet demonstrates how to use `xcm_execute` to perform a [reserve-backed transfer](https://wiki.polkadot.network/docs/learn/xcm/journey/transfers-reserve#1-initiatereservewithdraw):

```rust
#[ink(message)]
pub fn reserve_transfer(&mut self, value: Balance) -> Result<(), RuntimeError> {
    // The beneficiary of the transfer.
    // Here, the beneficiary is the caller's account on the relay chain.
    let beneficiary: Location = AccountId32 {
        network: None,
        id: *self.env().caller().as_ref(),
    }.into();

    // Create an XCM message.
    let message: Xcm<()> = Xcm::builder_unsafe()

     // Withdraw the relay's native token derivative from the contract's account.
     .withdraw_asset((Parent, amount))

    // The initiate_reserve_withdraw instruction takes the derivative token from the holding register and burns it.
    // It then sends the nested XCM to the reserve in this example, the relay chain.
    // Upon receiving the XCM, the reserve will withdraw the asset from our chain's sovereign account, and deposit on the caller's account.
    .initiate_reserve_withdraw(
        All,
        Parent,
        Xcm::builder_unsafe()
            .buy_execution((Here, fee), Unlimited)
            .deposit_asset(All, beneficiary)
            .build(),
    )
    .build();

    self.env().xcm_execute(&VersionedXcm::V4(message))?;
    Ok(())
}
```

## `xcm_send`

The [`xcm_send`](https://use-ink.github.io/ink/ink_env/fn.xcm_send.html) function enables sending XCM to be executed by another chain.
Messages sent originate from the contract's account. Consequently, the receiving chain will process the message using the contract's sovereign account as the origin.

The following example demonstrates how to use `xcm_send`. In this example, we send an XCM to the relay chain.
This XCM will execute using the contract's sovereign account as the origin of the call.
It will then transfer, some `value` from this account to the caller's account.

```rust
#[ink(message)]
pub fn send_funds(&mut self, value: Balance, fee: Balance) -> Result<(), RuntimeError> {
    // The destination of the XCM message. Assuming we run the contract on a parachain, the parent will be the relay chain.
    let destination: Location = Parent.into();

    // the asset to be sent, since we are sending the XCM to the relay chain,
    // this represents `value` amount of the relay chain's native asset.
    let assets: Asset = (Here, value).into();

    // The beneficiary of the asset.
    // Here, the beneficiary is the caller's account on the relay chain.
    let beneficiary: Location = AccountId32 {
        network: None,
        id: *self.env().caller().as_ref(),
    }.into();

    // Create an XCM message
    let message: Xcm<()> = Xcm::builder()

        // Withdraw the asset from the origin (the sovereign account of the contract on the relay chain)
        .withdraw_asset(assets.clone().into())

        // Buy execution to pay the fee on the relay chain
        .buy_execution((Here, fee).into(), WeightLimit::Unlimited)

        // Deposit the asset to the caller's account on the relay chain
        .deposit_asset(assets.into(), beneficiary)
        .build();

    // Send the constructed XCM message to the relay chain, using the xcm_send host function.
    self.env().xcm_send(
        &VersionedLocation::V4(destination),
        &VersionedXcm::V4(message),
    )?;

    Ok(())
}
```
````

## File: docs/datastructures/custom.md
````markdown
---
title: Custom Data Structures
slug: /datastructures/custom-datastructure
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

# Custom Data Structures

The `ink_storage` crate provides useful utilities and data structures to organize and
manipulate the contract's storage. However, contract authors should know that they can
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://use-ink.github.io/ink/ink_storage_traits/trait.Storable.html)
trait, so it can be SCALE
[`encoded`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.Encode.html)
and
[`decoded`](https://docs.rs/parity-scale-codec/latest/parity_scale_codec/trait.Decode.html).
Additionally, the traits
[`StorageLayout`](https://use-ink.github.io/ink/ink_storage_traits//trait.StorageLayout.html)
and [`TypeInfo`](https://docs.rs/scale-info/latest/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)]
#[cfg_attr(
    feature = "std",
    derive(ink::storage::traits::StorageLayout)
)]
pub struct Inner {
    value: bool,
}

#[ink(storage)]
pub struct ContractStorage {
    inner: Inner,
}
```

Even better: there is a macro
[`#[ink::storage_item]`](https://use-ink.github.io/ink/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:

```rust
/// A custom type that we can use in our contract storage
#[ink::storage_item]
pub struct Inner {
    value: bool,
}

#[ink(storage)]
pub struct ContractStorage {
    inner: Inner,
}
```

Naturally, you can as well implement any required trait manually. Please directly refer to
the relevant trait documentations for more information.

:::note

The `#[ink::storage_item]` macro is responsible for storage key calculation of 
non-[`Packed`](https://use-ink.github.io/ink/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://use-ink.github.io/ink/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 
for key calculation by disabling the derives: `#[ink::storage_item(derive = false)]`.

:::

## Generic storage fields

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://use-ink.github.io/ink/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
how many values there are in the mapping (its length). This could be implemented as a
thin wrapper around the ink! `Mapping` as follows:

```rust
/// Values for this map need to implement the `Default` trait.
/// Naturally, they also must be compatible with contract storage.
/// Note that the underlying `Mapping` type only supports `Packed` values.
#[ink::storage_item]
pub struct DefaultMap<K, V: Packed + Default> {
    values: Mapping<K, V>,
    length: u32,
}

impl<K: Encode, V: Packed + Default> DefaultMap<K, V> {
    /// Accessing non-existent keys will return the default value.
    pub fn get(&self, key: &K) -> V {
        self.values.get(key).unwrap_or_default()
    }

    /// Inserting into the map increases its length by one.
    pub fn set<I, U>(&mut self, key: I, value: &U)
    where
        I: scale::EncodeLike<K>,
        E: scale::EncodeLike<V> + Storable,
    {
        if self.values.insert(key, value).is_none() {
            self.length += 1
        }
    }

    /// Removing a value from the map decreases its length by one.
    pub fn remove(&mut self, key: &K) {
        if self.values.take(key).is_some() {
            self.length -= 1
        }
    }

    /// Return how many values the mapping contains
    pub fn len(&self) -> u32 {
        self.length
    }
}

/// `DefaultMap` is compatible with contract storage.
#[ink(storage)]
pub struct MyContract {
    my_map: DefaultMap<BlockNumber, Balance>,
}
```

:::caution

Generic data types may substantially increase your contracts overall code size, making it
more costly to store on-chain.

The reason for this is [Rust's monomorphization][rust-monomorphization].

:::

[rust-monomorphization]: https://rustc-dev-guide.rust-lang.org/backend/monomorph.html
````

## File: docs/datastructures/mapping.md
````markdown
---
title: Working with Mapping
slug: /datastructures/mapping
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

# Working with Mapping

In this section we demonstrate how to work with ink! [`Mapping`](https://use-ink.github.io/ink/ink_storage/struct.Mapping.html).

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

```rust
#[ink(storage)]
pub struct MyContract {
    /// Assign a balance to every account.
    balances: ink::storage::Mapping<AccountId, Balance>,
}
```

This means that for a given key, you can store a unique instance of a value type. In this
case, each "user" gets credited their own balance.

## Example: Using a `Mapping`

The following example contract utilizes a `Mapping` so that anyone can deposit and withdraw
balance for their own account:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod mycontract {
    use ink::storage::Mapping;

    #[ink(storage)]
    pub struct MyContract {
        /// Assign a balance to every account ID
        balances: Mapping<AccountId, Balance>,
    }

    impl MyContract {
        /// Constructor to initialize the contract with an empty mapping.
        #[ink(constructor, payable)]
        pub fn new() -> Self {
            let balances = Mapping::default();
            Self { balances }
        }

        /// Retrieve the balance of the caller.
        #[ink(message)]
        pub fn get_balance(&self) -> Option<Balance> {
            let caller = self.env().caller();
            self.balances.get(caller)
        }

        /// Credit more money to the contract.
        #[ink(message, payable)]
        pub fn transfer(&mut self) {
            let caller = self.env().caller();
            let balance = self.balances.get(caller).unwrap_or(0);
            let endowment = self.env().transferred_value();
            self.balances.insert(caller, &(balance + endowment));
        }

        /// Withdraw all your balance from the contract.
        pub fn withdraw(&mut self) {
            let caller = self.env().caller();
            let balance = self.balances.get(caller).unwrap();
            self.balances.remove(caller);
            self.env().transfer(caller, balance).unwrap()
        }
    }
}

```

## Considerations when using the `Mapping` type

One of the main purposes of the ink! `Mapping` is to allow storing a lot of values.

:::note

There are many additional data structures accessible under `ink::prelude::collections`,
such as `HashMap` or `BTreeMap` (to name a few). Note that these data structures all exhibit
`Packed` storage loading behavior, as opposed to the ink! `Mapping`!

:::

### Storage loading behavior

Each `Mapping` value lives under it's own storage key. Briefly, this means that `Mapping`s
are lazily loaded in ink!. In other words, if your message only accesses a single key of a
mapping, it will not load the whole mapping but only the value being accessed.

```rust
// This causes only a single storage access and the decoding of a single "MyValue" struct,
// no matter how many elements there are inside the mapping.
let foo: MyValue = my_mapping.get(0)?;

for n in 0..5 {
    // This causes a storage access and a decoding operation for each loop iteration.
    // It is not possible to "fetch" all key/value pairs directly at once.
    let bar: MyValue = my_mapping.get(n)?;
}
```

Furthermore, it follows that mapping values do not have a contiguous storage layout, and it is
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<u64, String>,
    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:?}: <data omitted>");
        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()`
method will result in an owned value (a local copy), as opposed to a direct reference
into the storage. Changes to this value won't be reflected in the contract's storage
"automatically". To avoid this common pitfall, the value must be inserted again at the same
key after it was modified. The `transfer` function from above example illustrates this:

```rust
pub fn transfer(&mut self) {
    let caller = self.env().caller();
    // `balance` is a local value and not a reference to the value on storage!
    let balance = self.balances.get(caller).unwrap_or(0);
    let endowment = self.env().transferred_value();
    // The following line of code would have no effect to the balance of the
    // caller stored in contract storage:
    //
    // balance += endowment;
    //
    // Instead, we use the `insert` function to write it back like so:
    self.balances.insert(caller, &(balance + endowment));
}
```
````

## File: docs/datastructures/overview.md
````markdown
---
title: Overview
slug: /datastructures/overview
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

# Overview

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://use-ink.github.io/ink/ink_storage/struct.Mapping.html)
and [`Lazy`](https://use-ink.github.io/ink/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.
As a core ingredient to the ink! language, its main advantage is being simple and
lightweight: It favors being efficient in terms of gas costs and code size
over providing a lot of high-level functionality found in other implementations
like the `ink::prelude::collections::HashMap` type.
Overall, the ink! `Mapping` will be a solid choice for most contracts. Moreover, smart
contracts developers can implement advanced features themselves.

`Lazy` is a wrapper type that can be used over any other storage compatible type.
This allows smart contract developers fine-grained manual control over the layout of
the contract storage by assigning a separate storage cell for the field. For example,
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](./storage-layout.md).
````

## File: docs/datastructures/storage-in-metadata.md
````markdown
---
title: Storage Metadata Format
slug: /datastructures/storage-in-metadata
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

:::caution
This page has not yet been edited for ink! v6.
There are many mentions of `pallet-contracts` and its internals here.
This info needs to be checked for validity in `pallet-revive`.

We should also highlight that this is for the ink! Metadata Format.

TODO
:::

# 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
layout of any given contract.

Given a contract with the following storage:

```rust
#[ink(storage)]
pub struct MyContract {
    balance: Balance,
    block: BlockNumber,
    lazy: Lazy<bool>,
}
```

The storage will be reflected inside the metadata as like follows:

```json
"root": {
  "layout": {
    "struct": {
      "fields": [
        {
          "layout": {
            "leaf": {
              "key": "0x00000000",
              "ty": 0
            }
          },
          "name": "balance"
        },
        {
          "layout": {
            "leaf": {
              "key": "0x00000000",
              "ty": 1
            }
          },
          "name": "block"
        },
        {
          "layout": {
            "root": {
              "layout": {
                "leaf": {
                  "key": "0xb1f4904e",
                  "ty": 2
                }
              },
              "root_key": "0xb1f4904e"
            }
          },
          "name": "lazy"
        }
      ],
      "name": "MyContract"
    }
  },
  "root_key": "0x00000000"
}
```

We observe that the storage layout is represented as a tree, where tangible storage values
end up inside a `leaf`. Because of
[`Packed`](https://use-ink.github.io/ink/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.

A `root_key` is meant to either be used to directly access a `Packed` storage field
or to serve as the base key for calculating the actual keys needed to access values in
non-`Packed` fields (such as `Mapping`s).

## Storage key calculation for ink! `Mapping` values

Base storage keys are always 4 bytes in size. However, the storage API of the contracts
pallet supports keys of arbitrary length. In order to reach a mapping value, the storage
key of said value is calculated at runtime.

The formula to calculate the base storage key `S` used to access a mapping value under the
key `K` for a mapping with base key `B` can be expressed as follows:

```
S = scale::encode(B) + scale::encode(K)
```

Where the base key `B` is the `root_key` (of type `u32`) found in the contract metadata.

In words, SCALE encode the base (root) key of the mapping and concatenate it with the
SCALE encoded key of the mapped value to obtain the actual storage key used to
access the mapped value.

Given the following contract storage, which maps accounts to a balance:

```rust
#[ink(storage)]
pub struct Contract {
    roles: Mapping<AccountId, Balance, ManualKey<0x12345678>>,
}
```

Now let's suppose we are interested in finding the balance for the account 
`5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY`. The storage key is calculated as follows:

1. SCALE encode the base key of the mapping (`0x12345678u32`), resulting in `0x78563412`
2. SCALE encode the `AccountId`, which will be 
   `0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d`.
   Note that you'll need to convert the SS58 into a `AccountId32` first.
3. Concatenating those two will result in the key 
   `0x78563412d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d`.

```rust
let account_id = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
let account: AccountId32 = Ss58Codec::from_string(account_id).unwrap();
let storage_key = &(0x12345678u32, account).encode();
println!("0x{}", hex::encode(storage_key));
// 0x78563412d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
```

## Accessing storage items with the `contractsApi` runtime call API

There are two ways to query for storage fields of smart contracts from outside a contract.
Both methods are accessible via the [`polkadot-js`](https://polkadot.js.org/apps/) web UI.

The straight forward way to query a contracts storage is via a
[`runtime API`](https://polkadot.js.org/apps/#/runtime) call, using the `contractsApi`
endpoint provided by the contracts pallet. The endpoint provides a `getStorage` method,
which just expects a contract address and a storage key as arguments.

For example, to access the root storage struct under the key `0x00000000` of a contract,
just specify the contract's address and the storage key `0x00000000` as-is. The API call
will return the scale-encoded root storage struct of the contract.

## Accessing storage items with the `childState` RPC call API

Under the hood, each contract gets its own
[child trie](https://paritytech.github.io/substrate/master/frame_support/storage/child/index.html), where its storage items are actually stored.

Additionally, the contracts pallet uses the
[`Blake2 128 Concat`](https://paritytech.github.io/substrate/master/frame_support/struct.Blake2_128Concat.html)
[`Transparent hashing algorithm`](https://docs.substrate.io/build/runtime-storage/#transparent-hashing-algorithms)
to calculate storage keys for any stored item inside the child trie.
You'll need to account for that as well.

With that in mind, to directly access storage items of any on-chain contract using a
childState [`RPC call`](https://polkadot.js.org/apps/#/rpc), you'll need the following:
- The child trie ID of the contract, represented as a [`PrefixedStorageKey`](https://docs.rs/sp-storage/latest/sp_storage/struct.PrefixedStorageKey.html)
- The hashed storage key of the storage field

### Finding the contracts child trie ID

The child trie ID is the `Blake2_256` hash of the contracts instantiation nonce
concatenated to it's `AccountId`. You can find it in
[`polkadot-js chainstate query interface`](https://polkadot.js.org/apps/#/chainstate),
where you need to execute the `contracts_contractInfoOf` state query.

It can also be calculate manually according to the following code snippet. The
instantiation note of the contract must be still be known. You can get it using the
`contracts_nonce` chain state query in polkadot-js UI.

```rust
use sp_core::crypto::Ss58Codec;
use parity_scale_codec::Encode;

// Given our contract ID is 5DjcHxSfjAgCTSF9mp6wQBJWBgj9h8uh57c7TNx1mL5hdQp4
let account: AccountId32 =
    Ss58Codec::from_string("5DjcHxSfjAgCTSF9mp6wQBJWBgj9h8uh57c7TNx1mL5hdQp4").unwrap();
// Given our instantiation nonce was 1
let nonce: u64 = 1;

// The child trie ID can be calculated as follows:
let trie_id = (&account, nonce).using_encoded(Blake2_256::hash);
```

### Calculate the `PrefixedStorageKey` from the child trie ID
A `PrefixedStorageKey` based on the child trie ID can be constructed using the `ChildInfo`
primitive as follows:

```rust
use sp_core::storage::ChildInfo;
let prefixed_storage_key = ChildInfo::new_default(&trie_id).into_prefixed_storage_key();
```

### Calculate the storage key using transparent hashing

Finally, we calculate the hashed storage key of the storage item we are wanting to access.
The algorithm is simple: `Blake2_128` hash the storage key and then concatenate the unhashed
key to the hash. Given you want to access the storage item under the `0x00000000`,
it will look like this in code:

```rust
use frame_support::Blake2_128Concat;

// The base key is 0x00000000
let storage_key = Blake2_128Concat::hash(&[0, 0, 0, 0]);
```

### A full example

Let's recap the last few paragraphs into a full example. Given:

* A contract at address `5DjcHxSfjAgCTSF9mp6wQBJWBgj9h8uh57c7TNx1mL5hdQp4`
* With instantiation nonce of `1`
* The root storage struct is to be found at base key `0x00000000`

The following Rust program demonstrates how to calculate the `PrefixedStorageKey` of the
contracts child trie, as well as the hashed key for the storage struct, which can then be
used with the `chilstate` RPC endpoint function `getStorage` in polkadot-js to receive
the root storage struct of the contract:

```rust
use frame_support::{sp_runtime::AccountId32, Blake2_128Concat, Blake2_256, StorageHasher};
use parity_scale_codec::Encode;
use sp_core::{crypto::Ss58Codec, storage::ChildInfo};
use std::ops::Deref;

fn main() {
    // Find the child storage trie ID
    let account_id = "5DjcHxSfjAgCTSF9mp6wQBJWBgj9h8uh57c7TNx1mL5hdQp4";
    let account: AccountId32 = Ss58Codec::from_string(account_id).unwrap();
    let instantiation_nonce = 1u64;
    let trie_id = (account, instantiation_nonce).using_encoded(Blake2_256::hash);
    assert_eq!(
        hex::encode(trie_id),
        "2fa252b7f996d28fd5d8b11098c09e56295eaf564299c6974421aa5ed887803b"
    );

    // Calculate the PrefixedStorageKey based on the trie ID
    let prefixed_storage_key = ChildInfo::new_default(&trie_id).into_prefixed_storage_key();
    println!("0x{}", hex::encode(prefixed_storage_key.deref()));
    // 0x3a6368696c645f73746f726167653a64656661756c743a2fa252b7f996d28fd5d8b11098c09e56295eaf564299c6974421aa5ed887803b

    // Calculate the storage key using transparent hashing
    let storage_key = Blake2_128Concat::hash(&[0, 0, 0, 0]);
    println!("0x{}", hex::encode(&storage_key));
    // 0x11d2df4e979aa105cf552e9544ebd2b500000000
}
```
````

## File: docs/datastructures/storage-layout.md
````markdown
---
title: Storage Layout
slug: /datastructures/storage-layout
hide_title: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Storage Title Picture](/img/title/storage.svg)

# Storage Layout

Smart contract authors are given some flexibility in regards on how they want to organize
the storage layout of their contracts.
Let's dive deeper into the concepts behind ink! storage to get a better understanding
of some of its implications and limitations.

## Storage Organization

The following schema depicts the storage which is exposed
to ink! by the [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive/):

<div class="schema">
    <img src={useBaseUrl('/img/kv-revive.svg')} alt="Storage Organization: Layout" />
</div>

Storage data is always encoded with the
[`SCALE`](https://docs.polkadot.com/polkadot-protocol/basics/data-encoding/#scale-codec-libraries) codec.
The storage API operates by storing and loading entries into and from a single storage
cells, where each storage cell is accessed under its own dedicated storage key. To some
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://use-ink.github.io/ink/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.

For example, if we have a somewhat small contract storage struct consisting of only a few
tiny fields, pulling everything from the storage inside every message is not
problematic. It may even be advantageous - especially if we expect most messages to
interact with most of the storage fields.

On the other hand, this can get problematic if we're storing a large `ink::prelude::vec::Vec`
in the contract storage but provide messages that do not need to read and write from this
`Vec`. In that scenario, each and every contract message bears runtime overhead by dealing
with that `Vec`, regardless whether they access it or not. This results in extra gas costs.
To solve this problem we need to turn our storage into a non-packed layout somehow.

<div class="schema">
    <img src={useBaseUrl('/img/packed-revive.svg')} alt="Storage Organization: Packed" />
</div>

:::caution

If any type exhibiting `Packed` layout gets large enough (an ever-growing `Vec` might be
a prime candidate for this), it will break your contract.
This is because for encoding and decoding storage items, there is a buffer with only limited
capacity (around 16KB in the default configuration) available. This means any contract
trying to decode more than that will trap! If you are unsure about the potential size a
data structure might get, consider using an ink! `Mapping`, which can store an arbitrary
number of elements, instead.

:::

## Eager Loading vs. Lazy Loading
ink! provides means of breaking the storage up into smaller pieces, which can be loaded
on demand, with the
[`Lazy`](https://use-ink.github.io/ink/ink/storage/struct.Lazy.html) primitive.
Wrapping any storage field inside a `Lazy` struct makes the storage
struct in which that field appears also
non-`Packed`, preventing it from being eagerly loaded during arbitrary storage operations:

<div class="schema">
    <img src={useBaseUrl('/img/storage-layout-revive.svg')} alt="Storage Organization: Layout with a Lazy field" />
</div>

Note that in above illustration, the key of `0x12345678` just serves as an example; we'll
learn more about storage key calculation
[later in this chapter](#manual-vs-automatic-key-generation).

The following example demonstrates how we can solve the problem introduced in the above
section. You'll notice that for the lazily loaded storage field, we now work with getters
and setters to access and modify the underlying storage value:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod mycontract {
    use ink::prelude::vec::Vec;
    use ink::storage::Lazy;

    #[derive(Default)]
    #[ink(storage)]
    pub struct MyContract {
        tiny_value: Balance,
        /// This vector might get large and expensive to work with.
        /// We want to enforce a non-`Packed` storage layout.
        large_vec: Lazy<Vec<Balance>>,
    }

    impl MyContract {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self::default()
        }

        /// Because `large_vec` is loaded lazily, this message is always cheap.
        #[ink(message)]
        pub fn get_balance(&self) -> Balance {
            self.tiny_value
        }

        /// Lazy fields like `large_vec` provide `get()` and `set()` storage operators.
        #[ink(message)]
        pub fn add_balance(&mut self, value: Balance) {
            let mut balances = self.large_vec.get_or_default();
            balances.push(value);
            self.large_vec.set(&balances);
        }
    }
}
```

:::caution

`ink::prelude::vec::Vec`'s are always loaded in their entirety. This is because all elements
of the `ink::prelude::vec::Vec` live under a single storage key. Wrapping the
`ink::prelude::vec::Vec` inside `Lazy`, like the
provided example above does, has no influence on its inner layout. If you are dealing with
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://use-ink.github.io/ink/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://use-ink.github.io/ink/ink_storage_traits//struct.ManualKey.html)
primitive allows manual control over the storage key of a field like so:

```rust
#[ink(storage)]
pub struct MyContract {
    /// The storage key for this field is always `0x0000007f`
    inner: Lazy<bool, ManualKey<127>>,
}
```

This may be advantageous: Your storage key will always stay the same, regardless of
the version of your contract or ink! itself (note that the key calculation algorithm may
change with future ink! versions).

:::tip

Using `ManualKey` instead of `AutoKey` might be especially desirable for upgradable
contracts, as using `AutoKey` might result in a different storage key for the same field
in a newer version of the contract. This may break your contract after an upgrade 😱!

:::

The storage key of the contracts root storage struct defaults to `0x00000000`.  However,
contract developers can set the key to an arbitrary 4 bytes value by providing it a
`ManualKey` like so:

```rust
/// Manually set the root storage key of `MyContract` to be `0xcafebabe`.
#[ink(storage)]
pub struct MyContract<KEY: StorageKey = ManualKey<0xcafebabe>> {
    value: bool,
}
```

## Considerations

It might be worthwhile to think about the desired storage layout of your contract. While
using a `Packed` layout will keep your contracts overall code size smaller, it can cause
unnecessarily high gas costs. Thus, we consider it a good practice to break up large
or complex storage layouts into reasonably sized distinct storage cells.

:::note

ink! `Mapping`s are always non-`Packed` and loaded lazily, one key-value pair at the time.

:::
````

## File: docs/datastructures/storagevec.md
````markdown
---
title: Working with StorageVec
slug: /datastructures/storagevec
hide_title: true
---

![Storage Title Picture](/img/title/storage.svg)

# Working with `StorageVec`

In this section we demonstrate how to work with ink!'s
[`StorageVec`](https://use-ink.github.io/ink/ink_storage/struct.StorageVec.html).

## Example: Using a `StorageVec`

Here is an example of an append-only on-chain log:

```rust
#[ink(storage)]
pub struct MyContract {
    on_chain_log: ink::storage::StorageVec<String>,
}
```

The following example contract utilizes a `StorageVec` to log each operation on chain (similar to emitting events but the contract can access them).

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod mycontract {
    use ink::prelude::{format, string::String};
    use ink::storage::StorageVec;

    #[ink(storage)]
    pub struct MyContract {
        on_chain_log: StorageVec<String>,
    }

    impl MyContract {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                on_chain_log: Default::default(),
            }
        }

        /// Donate money to the contract.
        #[ink(message, payable)]
        pub fn donate(&mut self) {
            let caller = self.env().caller();
            let endowment = self.env().transferred_value();

            let log_message = format!("{caller:?} donated {endowment}");

            self.on_chain_log.push(&log_message);
        }

        /// How many donations had the contract so far?
        #[ink(message)]
        pub fn log_length(&self) -> u32 {
            self.on_chain_log.len()
        }

        /// What was the last donation to the contract?
        #[ink(message)]
        pub fn last_donation(&self) -> Option<String> {
            self.on_chain_log.peek()
        }
    }
}

```

## Difference between `StorageVec` and Rusts `Vec` type

Any Rust `Vec<T>` will exhibit `Packed` storage layout; where
`StorageVec` stores each value under it's own storage key.

Hence, any read or write from or to a `Vec` on storage will load
or store _all_ of its elements.

This can be undesirable:
The cost of reading or writing a _single_ element grows linearly
corresponding to the number of elements in the vector (its length).
Additionally, the maximum capacity of the _whole_ vector is limited by
the size of [ink!'s static buffer](https://github.com/use-ink/ink/blob/master/ARCHITECTURE.md#communication-with-the-pallet)
used during ABI encoding and decoding (default 16 KiB).

`StorageVec` on the other hand allows to access each element individually.
Thus, it can theoretically grow to infinite size.
However, we currently limit the length at 2 ^ 32 elements. In practice,
even if the vector elements are single bytes, it'll allow to store
more than 4 GB data in blockchain storage.

### Caveats

Iterators are not provided. `StorageVec` is expected to be used to
store a lot elements, where iterating through the elements would be
rather inefficient. Manually iterating over the elements using a loop
is possible but considered an anti-pattern for most cases.

For the same reason, operations which would require re-ordering
stored elements are not supported. Examples include inserting and
deleting elements at arbitrary positions or sorting elements.

The decision whether to use `Vec<T>` or `StorageVec` can be seen as an
optimization problem with several factors:
* How large you expect the vector to grow
* The size of individual elements being stored
* How frequently reads, writes and iterations happen

For example, if a vector is expected to stay small but is frequently
iterated over. Choosing a `Vec<T>` instead of `StorageVec` will be
preferred as individual storage reads are much more expensive as
opposed to retrieving and decoding the whole collection with a single
storage read.

### Storage Layout

At given `StorageKey` `K`, the length of the `StorageVec` is hold.
Each element `E` is then stored under a combination of the `StorageVec`
key `K` and the elements index.

Given `StorageVec` under key `K`, the storage key `E` of the `N`th
element is calculated as follows:

`E = scale::Encode((K, N))`

## Considerations when using the `StorageVec` type

`StorageVec` is a `Lazy` type similar to `Mapping`.

Hence, the same considerations apply to `StorageVec` too:
- [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

See here for the Rust documentation of this data structure:
[`StorageVec`](https://use-ink.github.io/ink/ink_storage/struct.StorageVec.html).
````

## File: docs/debugging/decoding.md
````markdown
---
title: Decode raw transactions
slug: /contract-debugging/decoding-transactions
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Decode Data Payload

You can use a block explorer (or an app like Polkadot.js) to retrieve the data
payload of a contract transaction. For decoding transaction data, you can use
specialized tools that understand the contract metadata.

Contract metadata (generated during `pop build`) includes the ABI information needed
to decode transaction payloads. Tools and block explorers can use this metadata to
display human-readable method names and parameters.

Example decoded output:
```
Decoded data: inc_by { n: 1 }
```

If the contract was called through a cross-contract interaction, the payload will not be available in the transaction. In such cases, you can use the approach described in the next section to access it.
````

## File: docs/debugging/events.md
````markdown
---
title: Debug Events
slug: /contract-debugging/debug-events
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Emit debugging events

The idea here is to add a feature to your contract's `Cargo.toml`. You can 
name it e.g. `debug`.
In your contract you would then emit debug information if the flag is set.

This allows for emitting debug events in the contract, that can be checked 
for in your tests.

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]

#[ink::contract]
mod debugging_strategies {
    #[cfg(feature = "debug")]
    use ink::prelude::{
        borrow::ToOwned,
        format,
        string::String,
    };

    #[ink::event]
    #[cfg(feature = "debug")]
    pub struct DebugEvent {
        message: String,
    }

    #[ink(storage)]
    #[derive(Default)]
    pub struct DebuggingStrategies {}

    impl DebuggingStrategies {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {}
        }

        #[ink(message)]
        pub fn get(&self) {
            #[cfg(feature = "debug")]
            self.env().emit_event(DebugEvent {
                message: format!("received {:?}", self.env().transferred_value())
                    .to_owned(),
            });
            // …
        }
    }
}
```

This event will be shown when you call a contract. You can also access it in E2E tests:

```rust
#[ink_e2e::test(features = ["debug"])]
async fn e2e_debugging_event_emitted<Client: E2EBackend>(
    mut client: Client,
) -> E2EResult<()> {
    // given
    // create contract
    /* --snip-- */

    // when
    // call contract
    /* --snip-- */

    // then
    // the contract wil have emitted an event
    let contract_events = call_res.contract_emitted_events()?;
    assert_eq!(1, contract_events.len());
    let contract_event = &contract_events[0];
    let debug_event: DebugEvent =
        ink::scale::Decode::decode(&mut &contract_event.event.data[..])
            .expect("encountered invalid contract event data buffer");
    assert_eq!(debug_event.message, "received 0");

    Ok(())
}
```

We've put the above into a complete example. You can see the full source code
[here](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies/lib.rs).
````

## File: docs/debugging/overview.md
````markdown
---
title: Overview
slug: /contract-debugging/
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Overview

On a high-level there are two workflows for debugging your contract:

* You can write tests using one of the mechanisms described on the
  [Contract Testing](../testing/overview.md) page.
* You can interact with your contract via a UI or command-line. The  
  workflow is described on the [Call Your Contract](../getting-started/calling.md) page.

In each of those two options you have access to more detailed debugging
information. 

In this chapter we'll examine different debugging techniques using these
two workflows.
````

## File: docs/debugging/precompiles.md
````markdown
---
title: Precompiles
slug: /contract-debugging/precompiles
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Precompile

We don't have any examples for debugging with precompiles yet. 

Our intention is to add an explanation here, once the precompile API 
in `pallet-revive` is released.

The overarching with precompiles for debugging is to implement one that 
outputs log information to the node process console (`stdout` or `stderr`).
This precompile could then be called from within an ink! contract.
````

## File: docs/debugging/replays.md
````markdown
---
title: Replays
slug: /contract-debugging/transaction-extrinsic-replays
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

:::caution
This section has not yet been updated to ink! v6.

TODO Verify if this still works.
:::


# Replays
On this page we'll examine possibilities of replaying on-chain action.

## Replay and Debug a Block

To replay a transaction, you can use [Chopstick](https://github.com/AcalaNetwork/chopsticks) to create a local fork of the chain and replay the block with trace-level logging.

Assuming you have a node that you can connect to at `$ENDPOINT` and the transaction you want to replay is in block `$BLOCK_HASH`, you can use the following command:

```bash
npx @acala-network/chopsticks@latest run-block \
    --endpoint $ENDPOINT \
    --block $BLOCK_HASH \
    --runtime-log-level 5 \
    | grep runtime::contracts
```

This command replays the block with trace-level logging enabled. By filtering the output with `runtime::contracts`, you can view all the contract calls in the block:

```
runtime::contracts           TRACE: call ExportedFunction::Call account: , input_data: [246, 118, 44, 201]
runtime::contracts           TRACE: call ExportedFunction::Call account: , input_data: [254, 91, 216, 234, 1, 0, 0, 0]
runtime::contracts           TRACE: call result ExecReturnValue { flags: (empty), data: [0] }
runtime::contracts           TRACE: call result ExecReturnValue { flags: (empty), data: [0] }
```

From here, you can identify the call you are interested in and decode the data payload:

```bash
echo 254, 91, 216, 234, 1, 0, 0, 0 \
    | tr ',' ' ' \
    | xargs printf '%02x' \
    | xargs cargo contract decode message -d
```

This command will output the following:

```
Decoded data: inc_by { n: 1 }
```

## Fork Node and Replay Transactions

:::caution
This section has not yet been updated to ink! v6.

TODO Verify if this still works.
:::

You can also use [Chopstick](https://github.com/AcalaNetwork/chopsticks) to start a local fork of your chain.

This command starts a fork beginning at block `$BLOCK_HASH`. You can connect to this fork using `ws://localhost:8000` to submit extrinsics via PolkadotJs or `cargo contract`:

```bash
npx @acala-network/chopsticks@latest \
    --endpoint $ENDPOINT \
    --block $BLOCK_HASH \
    --runtime-log-level 5
```

Here, for example, you can re-run the transaction that we decoded in the previous section:

```bash
pop call contract \
    --contract $CONTRACT_ADDR \
    --message inc_by \
    --args 1 \
    --suri //Alice \
    --url ws://localhost:8000 \
    -x
```

Since trace-level logging is used, you will receive detailed information about all the host functions called during the execution of the contract:

```
runtime::contracts           TRACE: call ExportedFunction::Call account: , input_data: [254, 91, 216, 234, 2, 0, 0, 0]
runtime::contracts           TRACE: call result ExecReturnValue { flags: (empty), data: [0] }
runtime::contracts           DEBUG: Execution finished with debug buffer: seal0::value_transferred(out_ptr: 65488, out_len_ptr: 65516) = Ok(())
seal0::input(out_ptr: 65536, out_len_ptr: 65524) = Ok(())
seal1::get_storage(key_ptr: 65536, key_len: 4, out_ptr: 65540, out_len_ptr: 65524) = Ok(Success)
seal2::set_storage(key_ptr: 65536, key_len: 4, value_ptr: 65540, value_len: 4) = Ok(4)
seal0::seal_return(flags: 0, data_ptr: 65536, data_len: 1) = Err(TrapReason::Return(ReturnData { flags: 0, data: [0] }))
```
````

## File: docs/debugging/return_value.md
````markdown
---
title: Return value
slug: /contract-debugging/return-value
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Return an error message

You can return a specific error message from your contract via 
[`ink::return_value(REVERT, err);`](https://use-ink.github.io/ink/ink_env/fn.return_value.html).

If you do a dry-run of the contract call, you can read this data.


You cannot read the data if you submit the extrinsic on-chain
(i.e. execute the contract call "for real", on-chain). This is because extrinsic 
do not return data. They are executed in a transaction pool, asynchronous.

Furthermore, since you "REVERT" the transaction, it will just fail with
`ExtrinsicFailed`.

Here's an example:

```rust
#[ink::message]
fn get(&self) {
    ink::return_value(
        ink::env::ReturnFlags::REVERT,
        format!("received {:?}", self.env().transferred_value()).as_bytes();
    );
}
```

We've put the above into a complete example. You can see the full source code
[here](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies/lib.rs).
````

## File: docs/debugging/sandbox.md
````markdown
---
title: Sandbox
slug: /contract-debugging/sandbox
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Sandbox API

In the chapter on [Testing Strategies](../testing/sandbox.md), we explain that ink! supports
two means of End-to-End testing:

* `#[ink_e2e::test]`:
  The End-to-End tests spawn a local node process in the backend
  and submit transactions against it, returning the output to you.

* `#[ink_sandbox::test(backend(runtime_only(sandbox = sandbox_runtime::ContractCallerSandbox,client  = ink_sandbox::SandboxClient)))]` 
  With these settings, the End-to-End tests will be executed in
  a sandbox. The sandbox contains the `pallet-revive`, but anything
  that the node would do is mocked and can be influenced (block numbers, etc.).

You can utilize the DRink! library that is described on
[Testing Strategies](../testing/sandbox.md) to influence the state of the mocked 
sandbox. This is very useful for debugging, and we invite you to read the linked page.
````

## File: docs/debugging/tracing.md
````markdown
---
title: Tracing API
slug: /contract-debugging/pallet-revive-tracing-api
hide_title: true
---

![Magnifying Glass Title Picture](/img/title/magnifying-glass.svg)

# Tracing APIs

The [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive/src) 
has implemented a tracing API.
This is what the Ethereum-debugging tools use when interacting with `pallet-revive`.

You can utilize the tracing API in your E2E tests:

```rust
/// This test illustrates how to use the `pallet-revive` tracing functionality.
#[ink_e2e::test]
async fn e2e_tracing<Client: E2EBackend>(mut client: Client) -> E2EResult<()> {
    // given
    let mut constructor = DebuggingStrategiesRef::new();
    let contract = client
        .instantiate("debugging_strategies", &ink_e2e::bob(), &mut constructor)
        .submit()
        .await
        .expect("instantiate failed");
    let call_builder = contract.call_builder::<DebuggingStrategies>();

    let call = call_builder.instantiate_and_call(contract.code_hash);
    let call_res = client
        .call(&ink_e2e::alice(), &call)
        .value(1_337_000_000)
        .submit()
        .await?;

    // when
    let trace: ink_e2e::CallTrace = call_res.trace.expect("trace must exist");
    assert_eq!(trace.calls.len(), 2);
    // This is how the object looks:
    // ```
    // CallTrace {
    //     from: 0x9621dde636de098b43efb0fa9b61facfe328f99d,
    //     gas: 1497105168000,
    //     gas_used: 1548337586000,
    //     to: 0xd71ff7085ed0e3e8b6c8e95eb6094f4311ae8e2f,
    //     input: Bytes(
    //         0x829da98747d85e35d0b3ca3c7ceeac09b63ec2754e6a05eb6d2d5b92fb916da126364dd4,
    //     ),
    //     output: Bytes(0x0001),
    //     error: None,
    //     revert_reason: None,
    //     calls: [
    //         CallTrace {
    //             from: 0xd71ff7085ed0e3e8b6c8e95eb6094f4311ae8e2f,
    //             gas: 711404887000,
    //             gas_used: 205987649000,
    //             to: 0xfd8bf44f34a2d2cec42b8ab31ede1bb1bc366e8e,
    //             input: Bytes(0x9bae9d5e),
    //             output: Bytes(0x0000),
    //             error: None,
    //             revert_reason: None,
    //             calls: [],
    //             logs: [],
    //             value: Some(0),
    //             call_type: Call,
    //         },
    //         CallTrace {
    //             from: 0xd71ff7085ed0e3e8b6c8e95eb6094f4311ae8e2f,
    //             gas: 124370129000,
    //             gas_used: 163567881000,
    //             to: 0xfd8bf44f34a2d2cec42b8ab31ede1bb1bc366e8e,
    //             input: Bytes(0x2f865bd9),
    //             output: Bytes(0x0001),
    //             error: None,
    //             revert_reason: None,
    //             calls: [],
    //             logs: [],
    //             value: Some(0),
    //             call_type: Call,
    //         },
    //     ],
    //     logs: [],
    //     value: Some(0),
    //     call_type: Call,
    // }
    // ```

    // then
    #[allow(non_upper_case_globals)]
    const NativeToEthRatio: u128 = 1_000_000; // todo add to environment
    assert_eq!(
        trace.value,
        Some(ink::U256::from(1_337_000_000 * NativeToEthRatio))
    );

    Ok(())
}
```

We've put the above into a complete example. You can see the full source code
[here](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies/lib.rs).
````

## File: docs/faq/faq.md
````markdown
---
title: Frequently Asked Questions
hide: true
slug: /faq
hide_table_of_contents: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Faq Title Picture](/img/title/faq.svg)

# Frequently Asked Questions

### Who is "Squink"?

<img src={useBaseUrl('/img/ink-squink.svg')} alt="Squink ‒ the ink! mascot" className="squid" />
This little cute purple squid is Squink.<br/><br/>

Squink is the mascot of ink! and guides new users and adventurers through our presentations
workshops and tutorials. It also has a romance with Rust's mascot, Ferris.

Generally it is very friendly and open to learning new Rustaceans but be aware to never upset
it by taking away dots from the word ink! by spelling it incorrectly!
It really is into dots. Stories tell that it demanded the spelling of ink! with as many dots as possible.

<h3 id="correct-spelling">Is it "ink" or "ink!"? What does the "!" stand for?</h3>

The correct spelling is _ink!_ ‒ with a lowercase "i" and an exclamation mark at the end.
The history here is that:

* …in the very first iteration ink! was originally a [declarative Rust macro](https://doc.rust-lang.org/book/ch19-06-macros.html#declarative-macros-with-macro_rules-for-general-metaprogramming). A contract was invoked by writing `ink!{ … }`.
* …there is a real-world analogy here of writing a paper contract using ink.
* …we wanted to have as many DOTs as possible in the name 😉.
* …the symmetry of the top and bottom dot of i and ! is aesthetically pleasing 🌻.

So please don't make poor Squink cry having to read !ink, ink, Ink!, or Ink.

<center>
<img src={useBaseUrl('/img/sad-squid.svg')} alt="Squink ‒ the ink! mascot" width="300" />
</center>

### What's ink!'s relationship to the Polkadot SDK/Substrate?

Please see our page [Polkadot SDK](../background/polkadot-sdk.md) for more information.

### How to call other smart contracts on the same blockchain?

See our [Cross-contract calling](../basics/cross-contract-calling.md) page.

### How to call other smart contracts on another rollup/parachain?

See our page on [XCM](../basics/xcm.md).

### What is a contract's ABI or Metadata?

In ink! a smart contract's metadata is retrieved by using the `cargo-contract` CLI tool and
invoking `cargo contract build` which outputs a `.contract` file that includes both the compiled
`.polkavm` of the ink! smart contract as well as the so-called metadata information of the same
smart contract.
The metadata is especially important for third party tools such as Polkadot JS Apps or the Contracts UI
and provides useful information about the contract's constructors, messages, events, function selectors,
documentation and comments of the aforementioned structures as well as how inputs and outputs shall
be encoded and decoded respectively etc.

### Can a re-entrancy bug occur in ink! contracts?

:::caution
This page has to be reviewed in light of our ABI changes.

TODO There are some reentrancy features in ink!,
those should be explained here or on another page.
:::

# Cross-Contract Calls

### How can my smart contract interact with the runtime?

See the [Precompiles](../basics/precompiles.md) section for more information.

### How can I use ink! with a Polkadot SDK 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://use-ink.github.io/ink/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, no_main)]` at the beginning of each contract mean?

The `#[cfg(..)]` or `#[cfg_attr(..)]` annotations are how Rust does conditional compilation.

ink! smart contracts can be compiled in two different modes.

Through `#![cfg_attr(not(feature = "std"), no_std, no_main)]` an ink! smart contract tells the Rust compiler
in which mode they are being compiled. This also plays a significant role in how ink! generates
the smart contract code.

The two modes are as follows:

1. On-chain mode: This is the mode chosen when compiling an ink! smart contract for deployment on a blockchain.
   The resulting binary is a `.polkavm` file and as such it is not possible to use certain parts of Rust's standard
   library.
2. Off-chain mode: This is the mode chosen when trying to test an ink! smart contract using the off-chain
   environment. Off-chain environment testing is very useful to check if certain ink! constructors or messages
   are well behaving and allow for better debuggability than when trying to debug the same smart contract deployed
   on a chain.

<h3 id="why-no_std">Why is Rust's standard library (stdlib) not available in ink!?</h3>

Rust's standard library consists of three different layers:

1. `core` library which defines everything that has no dependencies outside of Rust itself.
   Included are types such as `Option`, `Result` as well as a whole variety of modules,
   functions and macro.

   ink! smart contracts allow authors to use Rust's `core` crate.

2. `alloc` library which is depending on a global allocator and mainly defines collections
   that spill their elements on to the execution's heap memory.
   Examples for collections are `Box`, `String`, `Vec`, `HashMap`, `LinkedList` and modules
   such as `fmt`, `rc` (ref-counted pointers) or borrows.

   ink! smart contracts allow authors to use Rust's `alloc` crate.
   By default ink! authors use definitions from the `alloc` crate through `ink::prelude` crate.

   3. `std` library is what people generally call Rust's standard library.

   >    The Rust Standard Library is the foundation of portable Rust software, a set of minimal and battle-tested shared abstractions for the broader Rust ecosystem.

   It requires several operating system capabilities in order to work correctly such as input and
   output systems for files, networking etc.

   Since our RISC-V compilation target does not support Rust's
   standard library ink! authors cannot use it either for their own purposes. Instead the [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive)
   tries to provide some common functionality that would otherwise be missing for common smart contract
   operations.

### Overflow Safety?

Being written in Rust, ink! provides robust overflow/underflow safety using compiler-level overflow checks as follows:
- `const` integer arithmetic operations (i.e. expressions involving only `const` integer operands)
  are checked for overflows at compile-time (e.g. `255u8 + 1` will lead to a compilation error due to overflow).
- For dynamic integer arithmetic operations, ink! (more specifically [`cargo-contract`][cargo-contract])
  automatically enables Rust's ["overflow-checks" instrumentation][rustc-overflow-checks],
  which automatically adds dynamic/runtime checks that panic on overflow.

[cargo-contract]: ../getting-started/setup.md#cargo-contract
[rustc-overflow-checks]: https://doc.rust-lang.org/rustc/codegen-options/index.html#overflow-checks

However, where possible, it's preferred to explicitly handle the possibility of overflow
using the following family of methods that are provided for primitive numeric types in Rust:
- `wrapping_*` methods for explicit wrapping behaviour (e.g. [`wrapping_add`][wrapping-add])
- `checked_*` methods which return `None` in case of overflow (e.g. [`checked_add`][checked-add])
- `saturating_*` methods which saturate at the type's minimum or maximum value
  (e.g. [`saturating_add`][saturating-add])
- `overflowing_*` methods which return the value and a `bool` flag indicating whether
  an overflow occurred (e.g. [`overflowing_add`][overflowing-add])

[wrapping-add]: https://doc.rust-lang.org/std/primitive.u8.html#method.wrapping_add
[checked-add]: https://doc.rust-lang.org/std/primitive.u8.html#method.checked_add
[saturating-add]: https://doc.rust-lang.org/std/primitive.u8.html#method.saturating_add
[overflowing-add]: https://doc.rust-lang.org/std/primitive.u8.html#method.overflowing_add

:::note
Unlike default `rustc`/`cargo` behavior, ink! (more specifically [`cargo-contract`][cargo-contract])
automatically enables dynamic overflow checks in release mode by default
(i.e. dynamic overflow checks are enabled when compiling with `cargo contract build --release`).

However, `cargo-contract` still allows you to override this behavior using the
["overflow-checks" setting][cargo-overflow-checks] for the release profile in
your contract's manifest file (i.e. `Cargo.toml`).
:::

[cargo-overflow-checks]: https://doc.rust-lang.org/cargo/reference/profiles.html#overflow-checks

:::caution
Apart from [integer arithmetic operations][arithmetic-operations], another cause of implicit overflows
is [integer type cast expressions (i.e. `as` conversions)][as-conversions].

However, unlike integer arithmetic operations, Rust's ["overflow-checks" instrumentation][rustc-overflow-checks]
doesn't add overflow checks for integer type cast expressions (e.g. `256u16 as u8`).
The motivation for this decision is explained [here][overflow-rfc-as].

As a less robust alternative, ink! provides a `cargo contract lint` command,
which (in addition to our [custom lints][custom-lints]) enables the following [`clippy`][clippy] lints to check for
overflowing/underflowing and lossy integer type cast expressions **in the local crate**
(i.e. the following lints only check code from the local crate, they don't check code from dependencies).
- https://rust-lang.github.io/rust-clippy/master/index.html#cast_possible_truncation
- https://rust-lang.github.io/rust-clippy/master/index.html#cast_possible_wrap
- https://rust-lang.github.io/rust-clippy/master/index.html#cast_sign_loss

In the future, ink! may provide more robust checks for overflows due integer type cast expressions
(i.e. `as` conversions).
:::

[arithmetic-operations]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#arithmetic-and-logical-binary-operators
[as-conversions]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics
[overflow-rfc-as]: https://rust-lang.github.io/rfcs/0560-integer-overflow.html#making-as-be-checked
[custom-lints]: ../linter/overview.md
[clippy]: https://doc.rust-lang.org/clippy/

### What is the difference between memory and storage?

In ink!, memory refers to computer memory, while storage refers to the on-chain storage
used by a contract instance. Memory is temporary and only lasts until the contract
execution is done, while storage is persistent and lasts over many contract executions.
The contract storage is built on top of the runtime storage, and access is considered to be slow.

### How do I hash a value?

A number of crypto hashes are built into [`pallet-revive`](../background/polkadot-sdk.md) and
therefore very efficient to use. We currently support a handful of those, you
can view the complete list [here](https://use-ink.github.io/ink/ink_env/hash/trait.CryptoHash.html).

If you have the urgent need for another crypto hash you could introduce it through
[Precompiles](../basics/precompiles.md)
or make a proposal to include it into the default set of the `pallet-revive`.

Using one of the built-in crypto hashes can be done as explained here:
* [`self.env().hash_bytes()`](https://use-ink.github.io/ink/ink_env/fn.hash_bytes.html)
* [`self.env().hash_encoded()`](https://use-ink.github.io/ink/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?

Floats are cool for all kinds of reasons, but they also have one important
drawback. Floating point arithmetic is non-deterministic which means that
different processors compute (slightly) different results for the same
operation. Although there is an IEEE spec, non-determinism can come from specific
libraries used, or even hardware. In order for the nodes in a blockchain network
to reach agreement on the state of the chain, all operations must be completely
deterministic. Hence, we don't allow floating point data types in ink!.

Consequently, it's not possible to return a decimal number from an ink! message.
What you should do instead is to have your user interface denominate the returned
number to decimals.

Note, that it's typical for blockchains to have the number of available tokens
defined as a non-floating number and determine the denomination in the user
interface. For example, 1 Bitcoin is equivalent to the smallest unit of 100,000,000
Satoshi and all Bitcoin implementations internally persist account balances in
Satoshi, not as a decimal number of Bitcoin.

### Why can't I just use the standard Rust data collections in ink!?

You can use them! They are exposed via the `ink_prelude` crate (e.g. `ink::prelude::vec::Vec`)
and you can return them from ink! messages and also persist them to storage.

_However, the Rust stdlib collections are not optimized for smart contract usage!_ So for example,
if you use them to persist your data on the chain they will always occupy a single storage cell
and thus always be loaded eagerly, in their entirety. This can be very costly! Just think about
a `Vec` or a `HashMap` where the smart contract might only need access to a few elements, rather
than the entire data collection.

### Why am I getting a `ContractTrapped` error when interacting with a contract?

When it does not constitute a deliberate assertion, like for example a permission check,
it is most likely a bug in your contract or in ink!.

A common source of `ContractTrapped` are Integer overflows, those can cause
your contract to trap as well.

### What are the `Encode`, `Decode` and `TypeInfo` arguments in `#[ink::scale_derive(Encode, Decode, TypeInfo)]` ?

Polkadot SDK-based blockchains use the [SCALE codec](https://github.com/paritytech/parity-scale-codec)
to encode data.
As a consequence the data for every interaction with Polkadot SDK needs to
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"`.
For example, you might encounter this error if you try to store a custom data
structure in the contract's storage. Or e.g. when attempting to return
a custom error from an ink! message.

:::note
The error `the trait "WrapperTypeEncode" is not implemented for …` is also
a common error when a mismatching version of `parity-scale-codec` is used
in the contract opposed to the version used by ink!.
:::

The solution typically is to add a fitting implementation of the trait
for your data structure:

* `Encode` is used for encoding a data structure when it is e.g. returned
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:

```rust
#[ink::scale_derive(Encode, Decode)]
struct MyCustomDataStructure { … }
```

### How do I use `String` in my contract?

In general, you should think twice if you really need `String`.
Smart contracts usually don't use strings; those are typically
used for user interactions and should live in your UI and not on the chain.

Minimizing storage usage of your contract is a best practice
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://use-ink.github.io/ink/ink_prelude/string/struct.String.html).

<h3 id="type-comparison">Getting a warning in <code>cargo-contract</code> about type compatibility?</h3>

ink! and Polkadot SDK 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-revive` 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.

If a chain indeed requires that contract developers have to use custom environment types,
this should be communicated prominently by them. 

### When an ink! contract is compiled with support for the Solidity ABI (abi = "sol" or "all"), does anything about its on-chain storage change?

No. The internal storage representation of a contract is still done in the SCALE codec!

The contract ABI only describes how external interactions with a contract are
encoded/decoded.
Using the Solidity ABI does not imply switching to a different storage layout!
````

## File: docs/faq/migrating-from-ink-3-to-4.md
````markdown
---
title: "Migration: ink! v3 → v4"
slug: /faq/migrating-from-ink-3-to-4
---

![Migration 3.x To 4.0 Title Picture](/img/title/migration-3.x-to-4.0.svg)

We've made a couple of breaking changes from ink! 3.x to ink! 4.0.
On this page we outline how you can migrate existing clients and
contracts from 3.x to 4.0.

:::caution
This migration guide is only for your code base!

If you have an existing contract on-chain you cannot just
upgrade the code on-chain ‒ you also have to migrate your data,
since the way ink! 4.0 stores data and reads it (i.e. the storage
layout) changes from ink! 3.x to 4.0.
:::

## Compatibility

ink! 4.0 is compatible with:

- Stable Rust >= 1.63.0
- `scale` >=3
- `scale-info` >= 2.3
- `pallet-contracts` >= `polkadot-v0.9.37`
- `substrate-contracts-node` >= `v0.24.0`
- `polkadot-js/api` and `polkadot-js/api-contract` >= 9.10.2

## `cargo-contract` 2.0

Together with ink! 4.0 we've released `cargo-contract` 2.0.
You have to use this latest version of `cargo-contract` for ink! 4.0
contracts.
You can upgrade via:

```rust
cargo install cargo-contract --force --version 2
```

Make sure that e.g. your CI also uses `cargo-contract` 2 with ink! 4.
If you have wrapper scripts around `cargo-contract` you should
ensure that this version is enforced, otherwise users will get an error.

:::note
`cargo-contract` no longer requires `binaryen` or `wasm-opt` as an
external dependency. We required those because of `wasm-opt` tool
(which is part of `binaryen`). Fortunately we were able to find a way of
installing `wasm-opt` now as part of the `cargo-contract` installation
process.
:::

## Rust `stable` instead of `nightly`

ink! 4.0 and `cargo-contract` use `stable` Rust now.
This means no more `cargo +nightly contract` is required, you
can just use a stable Rust toolchain now (>= Rust 1.63).

## New entrance `ink` crate

The `ink_lang` crate has been replaced in [#1223](https://github.com/use-ink/ink/pull/1223)
by a new top level `ink` crate. All existing sub-crates are reexported and should be used via
the new `ink` crate, so e.g. `ink::env` instead of `ink_env`. Contract authors should now import
the top level `ink` crate instead of the individual crates.

### Migration

- In `Cargo.toml` Replace all individual `ink_*` crate dependencies with the `ink` crate.
- In the contract source:
  - Remove the commonly used `use ink_lang as ink` idiom.
  - Replace all usages of individual crates with reexports, e.g. `ink_env` ➜ `ink::env`.

## Storage API + Layout

With [#1331](https://github.com/use-ink/ink/pull/1331) the way `ink!` reads and writes
to a contract's storage changed. Storage keys are generated at compile-time, and user facing
abstractions which determine how contract data is laid out in storage are different now.

### Migration

- Initialize `Mapping` fields with `Mapping::default()` instead of `ink_lang::utils::initialize_contract` in
  constructors. See [`erc20`](https://github.com/use-ink/ink-examples/blob/main/erc20/lib.rs) and other examples which use a `Mapping`.
- `SpreadAllocate`, `SpreadLayout`, `PackedLayout`, `PackedAllocate` have been removed.

## Removal of `wee-alloc` support

ink! uses a bump allocator by default, additionally we supported another allocator
(`wee-alloc`) through a feature flag. `wee-alloc` is no longer maintained and
we removed support for it in [#1403](https://github.com/use-ink/ink/pull/1403).

## Removal of `eth_compatibility` crate

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

```rust
ink_env::ecdsa_to_eth_address(&pub_key, &mut output);
```

## `ink_storage::Mapping`

The function signature of `Mapping::insert(key, val)` changed to
`Mapping::insert(key, val) -> Option<u32>`.
The return value is the size of the pre-existing value at the specified key if any (in bytes).

Two new useful functions were added:

- [`Mapping::contains(key)`](https://docs.rs/ink_storage/4.0.0/ink_storage/struct.Mapping.html#method.contains)
  in [#1224](https://github.com/use-ink/ink/pull/1224).
- [`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/use-ink/ink/pull/1461).

In case you were working around those two functions you can now
use them directly; they are more gas-efficient than e.g. executing
a `get(key).is_none()` instead of `contains(key)`.

## Storage functions in `ink_env`

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

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

## Removal of `ink_env::random` function

We had to remove the [`ink_env::random`](https://docs.rs/ink_env/3.3.1/ink_env/fn.random.html)
function (in [#1442](https://github.com/use-ink/ink/pull/1442)).
This function allowed contract developers getting random entropy.
There is unfortunately no way how this can be done safely enough
with built-in Substrate primitives on-chain currently. We're
following the recommendation of our auditors to remove it.

The alternative right now is to provide random entropy off-chain to
the contract, to use a random entropy oracle, or to have a chain-extension
that does this, in case the chain has a possibility to do so.

We hope to bring this function back in a future release of ink!, the
best hope right now is that it could come back with
[Sassafras](https://wiki.polkadot.network/docs/learn-consensus#badass-babe-sassafras),
a block production protocol for future versions of Polkadot.

If you're interested in more information on this check out
[the Substrate PR](https://github.com/paritytech/substrate/pull/13204) which
deprecated the random interface of `pallet-contracts`.

## Constructors can now return `Result<Self, MyContractError>`

With [#1446](https://github.com/use-ink/ink/pull/1446) we introduced
the possibility for constructors to return either `Self` (as usual) or
`Result<Self, MyContractError>`.

This enables contract developers to bubble up encoded error objects to
clients/frontends about a failure. In ink! 3.x it was only possible to
panic in the constructor in case an error occurred, resulting in loss
of this information.

## Chain extension's `returns_result` removed

The `returns_result` flag has been removed from the `#[ink(extension = …)]` attribute in
[#1569](https://github.com/use-ink/ink/pull/1569).
We now infer this information at compile time. If `handle_status` is set to `true`,
the return type will still be wrapped into `Result` as before.

## Contract Metadata (ABI)

The most detailed way to grasp what changed is to look at
[this PR](https://github.com/use-ink/ink-docs/pull/138), which
updated the metadata page in our documentation.

### Add support for language level errors (`LangError`)

Under the hood, ink! now generates code that results in each message
and constructor returning a `Result<Message::Output, LangError>` (or
for constructors `Result<Constructor::Output, LangError>`).
This happens even if the message/constructor doesn't have a return type,
we default to the unit type `()` in that case.

A [`LangError`](https://docs.rs/ink/4.0.0/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).

An example of where this would arise is if a caller tries to use a non-existent message
selector for a contract. Previously, the contract would trap and not allow the caller to
do any sort of error handling if it encountered a non-existent selector.

This change doesn't affect how you write a contract! It affects clients and
frontends though, since it breaks the API in two ways:

first, all contract messages now have a `Result` return type, and second a new field,
`lang_error`, will be introduced as part of the contract spec. The second change allows
other languages (such as Solang) to use an equivalent `LangError`.

<details>
  <summary>
    Click here for a snippet of the new metadata for the Flipper contract.
  </summary>
<p>

```json
"messages": [
  {
    "args": [],
    "docs": [
      " Flips the current value of the Flipper's boolean."
    ],
    "label": "flip",
    "mutates": true,
    "payable": false,
    "returnType": {
      "displayName": [
        "ink",
        "MessageResult"
      ],
      "type": 1
    },
    "selector": "0x633aa551"
  }],
"lang_error": {
  "displayName": [
    "ink",
    "LangError"
  ],
  "type": 3
},
{
  "id": 3,
  "type": {
    "def": {
      "variant": {
        "variants": [
          {
            "index": 1,
            "name": "CouldNotReadInput"
          }
        ]
      }
    },
    "path": [
      "ink_primitives",
      "LangError"
    ]
  }
}

```

</p>
</details>

### Version field

As part of [#1313](https://github.com/use-ink/ink/pull/1313) the ink! ABI was
changed to have a proper version field as part of the ink! metadata object.
This enables querying the ABI version in a less-ambiguous way.

Before:

```json
"source": {...},
"contract": {...},
"V3": {
  "spec": {...},
  "storage": {...},
  "types": {...}
}

```

After:

```json
{
  "source": {...},
  "contract": {...},
  "spec": {...},
  "storage": {...},
  "types": [...],
  "version": "4"
}
```

### The Storage Layout (`storage`)

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](../../versioned_docs/version-v4/datastructures/overview.md)
- [Storage metadata format](../../versioned_docs/version-v4/datastructures/storage-in-metadata.md)

## Removal of `AccountId` `Default` implementation

In [#1255](https://github.com/use-ink/ink/pull/1255) we removed the `Default` trait
implementation on `AccountId`s.

The `Default` implementation of `AccountId` returned the zero-address, which is
problematic since the
[zero-address in the `sr25519` and `ed25519` curves has a known private key](https://substrate.stackexchange.com/questions/982/why-does-the-all-0-public-key-have-a-known-private-key-in-sr25519-and-ed25519).

Developers commonly reach for defaults, and the zero-address in particular, making it an
unsafe trait implementation to have given the consequences.

Imagine a developer sending tokens to the zero-address to be burned, only to find that
they've been stolen because the private key is known.

If you were previously using `AccountId`'s `Default` implementation in your code you
have a couple of different options for how to move forward. These will depend on what
exactly you were using the zero-address for.

If you were using it as a burn address:

- You can pick another address to use, assuming that you've actually picked a random
  address
- Consider a solution that involves reducing total issuance, instead of transferring
  tokens to a random address

If you were using it as a privileged account:

- Change the account
- Add checks to ensure that calls coming from the zero-address are rejected

You should also now consider dealing with `AccountId`'s as `Option<AccountId>`'s. This is
more idiomatic Rust, and also conveys the meaning of a "null" or "empty" address much
better.

## Updates to the `CallBuilder` and `CreateBuilder` APIs

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

In [#1604](https://github.com/use-ink/ink/pull/1604) we renamed the
`CallBuilder::fire()` method to
[`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.

In [#1512](https://github.com/use-ink/ink/pull/1512) and [#1525](https://github.com/use-ink/ink/pull/1525)
we added support for handing
`LangError`s from the `CreateBuilder` and `CallBuilder`, respectively.

If you want to handle errors from either `Builder` you can use the new
[`CreateBuilder::try_instantiate()`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.CreateBuilder.html#method.try_instantiate)
or
[`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
non-`try_` methods in [#1602](https://github.com/use-ink/ink/pull/1602). This means
that the `CallBuilder::invoke()` and `CreateBuilder::instantiate()` methods return values
directly, and panic when they encounter an error.

Lastly, in [#1636](https://github.com/use-ink/ink/pull/1636) we added two methods to
the `CallBuilder` to streamline
[`Call`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.Call.html)
and
[`DelegateCall`](https://docs.rs/ink_env/4.0.0/ink_env/call/struct.DelegateCall.html)
workflows:

- For `Call` you can use
  [`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
contract manifest explicitly, as follows:

```toml
[lib]
name = "flipper"
path = "lib.rs"
crate-type = [
    # Used for normal contract Wasm blobs.
    "cdylib",
    # Use to generate ABI
    "rlib",
]
```

However, with [cargo-contract#929](https://github.com/use-ink/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

This means that your new manifest should look like:

```toml
[lib]
path = "lib.rs"
```
````

## File: docs/faq/migrating-from-ink-4-to-5.md
````markdown
---
title: "Migration: ink! v4 → v5"
slug: /faq/migrating-from-ink-4-to-5
---

![Migration 4.x To 5.0 Title Picture](/img/title/migration-4.x-to-5.0.svg)

We've made a couple of breaking changes from ink! 4.x to ink! 5.0.
On this page we outline how you can migrate existing dApps and
contracts from 4.x to 5.0.

This release addresses the majority of issues raised in [the OpenZeppelin
security review](https://blog.openzeppelin.com/security-review-ink-cargo-contract).
In particular, we addressed the proxy selector clashing attack.

You can find the full changelog of the 5.0 release [here](https://github.com/use-ink/ink/blob/master/CHANGELOG.md#version-500).

:::caution
This migration guide only considers your code base! Not your storage data!

If you have an existing contract on-chain you might not be able to just
upgrade the code on-chain, you possibly also have to migrate your storage data.

The relevant change that you have to take into consideration is
[#1897](https://github.com/use-ink/ink/pull/1897).
A data migration may be required when your contract reads data from storage and truncates
the data when decoding it.
We've described this in more detail below, in the section
["Fail when decoding from storage and not all bytes consumed"](#fail-when-decoding-from-storage-and-not-all-bytes-consumed).
:::

## How to upgrade

- Change the dependency versions of `ink` and `ink_e2e` in your contracts `Cargo.toml` to `5`.
- Update your local `cargo-contract` installation to 4.0.
- Read through this page.

## Compatibility

### Substrate/Polkadot SDK

There are four new functions that are only compatible from particular releases upwards:

- v2 of `call` and `instantiate`: `>= polkadot-v1.8.0` and `substrate-contracts-node >= v0.39.0`
  ([explained here](#call-and-instantiate-v2)).
- `lock_delegate_dependency` and `unlock_delegate_dependency`:
  `>= polkadot-v1.9.0` and `substrate-contracts-node >= v0.40.0` ([explained here](#upgradeable-contracts-delegate_dependency)).

These four functions are all opt-in! None of them are required to use ink! 5.0, they are only
required if you want to access the particular functionality they provide.
Please see the linked explainers for more details about them.

If you are not using any of those four functions, the same requirements as for ink! 4.0 holds:

- `pallet-contracts` >= `polkadot-v0.9.37`.
- `substrate-contracts-node` >= `v0.24.0`

### How do I find out if a chain is compatible with ink! 5?

You can query `contracts::palletVersion()` via the chain state RPCs. It has to
be `>= 9` for ink! 5.0 to be compatible, if you don't use any of the four functions
mentioned above.
For the above mentioned four functions please see the respective sections on this page,
there we explain how to find out if a chain supports them there.

You can use the [polakdot.js app](https://polkadot.js.org/apps/) to do this:
Developer » Chain State » `contracts` » `palletVersion()` » Click on the `+` on the right.

<img src="/img/pallet-version.png"  />

The following chains are in production and support ink! 5.0, if you are not using any of the
four functions mentioned above:

<div className="row">
    <div className="col text--center">
        <a href="https://alephzero.org">
            <img src= "/img/chains/aleph-zero.svg" className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://astar.network">
            <img src= "/img/chains/astar.svg" className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://shiden.astar.network">
            <img src= "/img/chains/shiden.svg" className="chain" />
        </a>
    </div>
</div>

<div className="row">
    <div className="col text--center">
        <a href="http://phala.network">
            <img src= "/img/chains/phala.svg" className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://pendulumchain.org">
            <img src= "/img/chains/pendulum.svg" className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://pendulumchain.org/amplitude">
            <img src= "/img/chains/amplitude.svg" className="chain" />
        </a>
    </div>
</div>

<div className="row">
    <div className="col text--center">
        <a href="https://www.ternoa.network/">
            <img src= "/img/chains/ternoa.svg" className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://krest.peaq.network/">
            <img src= "/img/chains/krest.svg" className="chain" />
        </a>
    </div>
</div>

### `cargo-contract` 4.0

Together with ink! 5.0 we've released `cargo-contract` 4.0.

:::info
You have to use `cargo-contract` >= 4.0 for ink! 5.0 contracts!

You can upgrade via:

```rust
cargo install cargo-contract --version ^4
```

:::

Make sure that e.g. your CI also uses at least `cargo-contract` 4.0 with ink! v5.0.
If you have wrapper scripts around `cargo-contract`, you should
ensure that this version is enforced, otherwise users will get an error.

### Tooling & Libraries

- Stable Rust >= 1.75
- `cargo-contract` >= v4.0
- `polkadot-js/api` and `polkadot-js/api-contract` >= 10.12.1
- [`use-inkathon`](https://github.com/scio-labs/use-inkathon): upgrade the `polkadot-js/api` and `polkadot-js/api-contract` dependencies in your project to >= 10.12.1
- [ink!athon](https://inkathon.xyz/) >= 0.7.0
- [`typechain-polkadot`](https://github.com/Brushfam/typechain-polkadot) >= 1.2.0

## Important Changes

We had to introduce a number of changes that require you to manually upgrade
your contract from 4.x to 5.0. The steps to do this are explained in this section.

### `scale` dependencies were moved to `ink` entrance crate

This change was done to ensure that you always use the correct scale dependency versions
with an ink! version. The relevant PR is [#1890](https://github.com/use-ink/ink/pull/1890).

We removed the requirement for contracts to have direct dependencies on `parity-scale-codec`
and `scale-info` in their `Cargo.toml`.
You can now remove those dependencies from your contracts `Cargo.toml`:

```diff
ink = { version = "4.3", default-features = false }
-scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive"] }
-scale-info = { version = "2.6", default-features = false, features = ["derive"], optional = true }
```

Both crates have been re-exported from the `ink` umbrella crate: `ink::scale_info` and `ink::scale`.

We created a convenience macro to derive the re-exported traits `ink::scale::Encode`,
`ink::scale::Decode` and `ink::scale_info::TypeInfo`.

```rust
// Previously
#[scale::Encode, scale::Decode)]
#[cfg_attr(feature = "std", derive(::scale_info::TypeInfo))]
pub enum Error {}


// Now
#[ink::scale_derive(Encode, Decode, TypeInfo)]
pub enum Error {}
```

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

Following [our security review by OpenZeppelin](https://blog.openzeppelin.com/security-review-ink-cargo-contract),
we've tightened the usage of wildcard selectors.
With ink! 5.0 we allow only exactly one other contract message with a well-known reserved
selector to be defined. In ink! 4.x, more than one other message was allowed.

Read more in [the PR](https://github.com/use-ink/ink/pull/1708) and [IIP-2: Limit contracts with a wildcard selector to one other message](https://github.com/use-ink/ink/issues/1676).

The proposal is to restrict contracts with a wildcard selector to only have one other message
with a reserved/well-known selector. This guarantees that there are no selector clashes,
either by chance or malicious intent, and that the Proxy will only handle messages intended for it.

If a contract uses a wildcard selector `#[ink(message, payable, selector = _)]` it _MAY_ define one
other message. This message _MUST_ use the reserved selector `@`.
This selector _MUST_ only be used in conjunction with a wildcard selector.

```rust
/// Handles any message with no matching selector in this proxy contract
#[ink(message, selector = _)]
pub fn fallback(&self) {
    // forward call to the "logic" contract which actually executes the call
}

#[ink::scale_derive(Decode)]
pub enum ProxyMessage {
    UpgradeContract(Hash),
}

/// One other message allowed to handle messages.
/// Fails to compile unless `@` is used as the selector.
#[ink(message, selector = @)]
pub fn handler(&self, msg: ProxyMessage) {
  match msg {
    ProxyMessage(hash) => { }
  }
}

/// An additional message. Fails to compile when uncommented.
// #[ink(message)]
// pub fn additional_message(&self, msg: ProxyMessage) {
//    match msg {
//        ProxyMessage(hash) => ...
//    }
// }
```

### Events 2.0

In prior ink! versions, events were defined inside the `#[ink::contract]` macro.
With ink! 5.0 we decouple events from the `#[ink::contract]` macro,
allowing events to be shared between contracts.
We've updated [the Events documentation page](../basics/events.md) accordingly.

The syntax of defining events within the main `#[ink::contract]` macro will continue to work,
no code changes in existing contracts are required to update to the new syntax.

:::caution
The topic calculation changed in general, so also for events that are declared inside the
`#[ink::contract]` macro!

This is a breaking change for any client code which uses topics to filter events.

Please see [#1827](https://github.com/use-ink/ink/pull/1827) for details.
:::

#### Custom signature topics

In [#2031](https://github.com/use-ink/ink/pull/2031) we introduced an
optional attribute `signature_topic` to the `#[ink::event]` and `#[ink(event)]` macros.
It can be used to specify the signature topic for a specific event manually, instead of the
automatic topic calculation.

### No more unchecked arithmetic

Unchecked arithmetic operations in a contract are no longer supported for arithmetic
safety reasons. Compiling a contract that contains those will fail gracefully.

If you haven't already done, you now need to handle overflows that could occur.
Rust supports different possibilities of doing so (saturating, "wrap around",
and unchecked arithmetic operations) .
See [this](https://doc.rust-lang.org/book/ch03-02-data-types.html#scalar-types) section
of the Rust Programming Language for a thorough explanation on how to do safe arithmetic
operations in Rust.

This change was introduced in [#1831](https://github.com/use-ink/ink/pull/1831).

### Fail when decoding from storage and not all bytes consumed

If a contract previously relied on successful decoding which does not consume all bytes,
then recompiling with a version of ink! which includes this change will cause that contract
to trap at runtime when attempting to decode.

A simple example would be if a storage cell contains some bytes which were in the first place
an encoded `u32`. If the contract attempts to decode those into a `u8`
this would previously have succeeded, now the contract would trap.

Here's a code example of behavior that previously worked for ink! 4.x, but
would error now:

```rust
let key = 0u32;
let value = [0x42; 32];
ink::env::set_contract_storage(&key, &value);

// Only attempt to read the first byte (the `u8`) of the storage value data
let _loaded_value: Option<u8> = ink::env::get_contract_storage(&key)
    .map_err(|e| format!("get_contract_storage failed: {:?}", e))?;
```

We introduced this change in [#1897](https://github.com/use-ink/ink/pull/1897).

### [ink_e2e] API Changes

#### Builder API

In [#1917](https://github.com/use-ink/ink/pull/1917) we reworked the E2E API with
a builder API.
`instantiate`, `call` and `upload` will now return a builder instance. You can
specify optional arguments with builder methods, and submit the call for on-chain
execution with the `.submit()` method, or dry-run it with `dry_run()`.

```rust
let contract = client
    .instantiate("flipper", &ink_e2e::alice(), &mut constructor)
    .submit()
    .await
    .expect("instantiate failed");
let mut call_builder = contract.call_builder::<Flipper>();

let get = call_builder.get();
let get_res = client.call(&ink_e2e::bob(), &get).dry_run().await;
assert!(matches!(get_res.return_value(), false));
```

#### Extra gas margin

As part of [#1917](https://github.com/use-ink/ink/pull/1917) we added the possibility
to specify a gas margin (in percentage) as part of the on-chain call.

There are cases when gas estimates may not necessarily be accurate enough due to the complexity
of the smart contract logic that adds additional overhead and gas consumption.
Therefore, it is helpful to allow to specify an extra portion of the gas to be added to the
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/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

We removed the `build_message()` function with its unhandy callback.

```rust
// Previously
let first_insert = ink_e2e::build_message::<MappingsRef>(contract_id)
    .call(|contract| contract.insert_balance(1_000));

// Now
let first_insert = ink_e2e::build_message::<MappingsRef>(contract_id)
    .call().insert_balance(1_000));
```

See [#1782](https://github.com/use-ink/ink/pull/1782) for more details.

#### Removed `additional_contracts` parameter

`additional_contracts` parameter which is part of `#[ink_e2e:test]` has been removed in [#2098](https://github.com/use-ink/ink/pull/2098).
This information is now implied from the contract's manifest.
Simply, add the other contract as dependency with the `ink-as-a-dependency` feature enabled.
The test will detect the contract and build it as part of the test.

####

In [#2076](https://github.com/use-ink/ink/pull/2076), we've added a new
[`remove_code`](https://docs.rs/ink_e2e/5.0.0/ink_e2e/trait.ContractsBackend.html#method.remove_code)
function to the E2E API:

```rust
let contract = client
    .remove_code(&ink_e2e::alice(), code_hash)
    // Submit the call for on-chain execution.
    .submit()
    .await
    .expect("remove failed");
```

### New Data Structure: `StorageVec`

We've added a `Vec`-like data structure, built on top of Mapping.

This allows to retrieve elements from a vector and grow it without
having to load and push all elements.
For `Vec`, the cost of reading or writing a single element grows linearly corresponding
to the number of elements in the vector (its length). Additionally, the maximum capacity
of the whole vector is limited by the size of [ink!'s static buffer](https://github.com/use-ink/ink/blob/master/ARCHITECTURE.md#communication-with-the-pallet)
used during ABI encoding and decoding (default 16 KiB).
`StorageVec` on the other hand allows to access each element individually.

With a `Vec` it's possible to e.g. introduce a security issue in your contract
where an attacker can fill the `Vec`, making it very costly for other users to
access it or write to it.

You can find verbatim documentation on `StorageVec` [here](../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/ink/storage/struct.StorageVec.html).

### Fallible methods for `Lazy`, `Mapping`, `StorageVec`

In [#1910](https://github.com/use-ink/ink/pull/1910) we added `try_*` methods for
reading and writing `Lazy` and `Mapping` values to and from storage.
The try methods correspond to `Mapping::{insert, get, take}`, `Lazy::{set, get}`.
For `StorageVec::{peek, get, set, pop, push}` we added `try_*` methods in
[#1995](https://github.com/use-ink/ink/pull/1995).

Please see the individual Rust docs for these new methods:

- [`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/use-ink/ink/blob/master/ARCHITECTURE.md#communication-with-the-pallet)
is 16 kB by default.

We added a lint to `cargo-contract` 4.0 that will detect
potentially unsafe uses of methods for which there are safer alternatives:
[`non_fallible_api`](../linter/rules/non_fallible_api.md).

### Chain Extension API changed + Support for multiple chain extensions

With [#1958](https://github.com/use-ink/ink/pull/1958) we added support for interacting with
multiple chain extensions from ink!. This is a breaking change.

You can now e.g. have a contract that utilizes a PSP22 chain extension together with one
for random numbers.

The syntax for chain extension functions changed slightly:

```diff
-#[ink(extension = 0xfecb)]
+#[ink(function = 0xfecb)]
fn foo() {}
```

The argument type changed from `u32` to `u16`:

```diff
-/// `#[ink(extension = N: u32)]`
-Extension,
+/// `#[ink(function = N: u16)]`
+Function,
```

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/docs/v5/macros-attributes/chain-extension).

```diff
-#[ink::chain_extension]
+#[ink::chain_extension(extension = 1)]
```

:::note
If the chain extension was not used in a tuple in the runtime configuration,
`extension = N: u16` can take any `u16` number.
:::

A migration in most cases should just be to rename `#[ink(extension = …)]` to
`#[ink(function = …)]`, and specifying `extension` argument in top level macro.

We added an example contract that illustrates the usage of multiple chain extensions
in one contract:
[`combined-extension`](https://github.com/use-ink/ink-examples/tree/main/combined-extension).

### `call` and `instantiate` v2

The functions to instantiate and call other contracts got an upgrade in the
`polkadot-v1.8.0` release (in the [`d250a6`](https://github.com/paritytech/polkadot-sdk/commit/d250a6e4270a77f28e2737a4faa3fb78c8ea7a85) commit),
The new v2 of them allows passing both `Weight` parts (`ref_time_limit` and `proof_size_limit`),
as well as the `storage_deposit_limit`.

The previous v1 `call` and `instantiate` functions only provided a single `gas_limit` parameter,
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/ink_env/call/fn.build_call.html):

```
call_builder
  .call_v1()
  .gas_limit(ref_time_limit)
  .invoke();
```

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:

```rust
call_builder // or `create_builder`
  .ref_time_limit(ref_time_limit)
  .proof_size_limit(proof_size_limit)
  .storage_deposit_limit(storage_deposit_limit)
  .invoke();
```

You can find out if a chain supports the new `v2` functions for call/instantiate by
querying the `contracts::apiVersion` constant. It has to be `1`.
You can use the [polakdot.js app](https://polkadot.js.org/apps/) to do this:
Developer » Chain State » Constants » `contracts` » `apiVersion` » Click on the `+` on the right.

<img src="/img/api-version-1.png"  />

At the time of the ink! v5 release (March 2024) no parachain with ink! support
had upgraded to `polkadot-v1.8.0` yet.

Please note that if you are using trait definitions for cross-contract calls,
direct calls from the `contract_ref!` macro are only supported with the `call_v2`.
Otherwise, you need to get the `CallBuilder` from the structure
and build the call manually.

```rust
type Erc20Wrapper = contract_ref!(Erc20);
let erc20: Erc20Wrapper = new_erc20.into();
let erc20_builder = erc20.call();
erc20_builder.total_supply().call_v1().invoke()
```

### Metadata Changes

#### Events 2.0

See [#1827](https://github.com/use-ink/ink/pull/1827) for the full details.
Two fields werere added to the objects in the `events` array:
`module_path` and `signature_topic`.

Previously the order of the events in the `events` array was significant (i.e. the first
one had an implied index of `0`), and this index could be used to determine which event
to decode.
Now that is replaced by the `signature_topic`, and the order of the events in the metadata
no longer has any significance.

See the section "[Events 2.0](#events-20)" on this page for more info.

ink! 4.0:

```json
   "events": [
      {
        "args": [ ... ],
        "docs": [ ... ],
        "label": "Transfer"
      },
      ...
  ]
```

ink! 5.0:

```diff
    "events": [
      {
        "args": [ ... ],
        "docs": [ ... ],
        "label": "...",
+       "module_path": "erc20::erc20",
+       "signature_topic": "0xb5b61a3e6a21a16be4f044b517c28ac692492f73c5bfd3f60178ad98c767f4cb"
      },
      ...
  ]
```

#### New field: `staticBufferSize`

With [#1880](https://github.com/use-ink/ink/pull/1880) we added a `"staticBufferSize"` field to
the metadata file. The unit is bytes.

See the section "[Buffer size can be customized](#buffer-size-can-be-customized)" on this page for
more info.

Example:

```diff
      "maxEventTopics": 4,
+     "staticBufferSize": 16384,
      "timestamp": { ... }
```

#### Metadata storage keys encoding change

Storage keys used to access storage data are SCALE encoded. Previously,
the contract metadata used big endian encoding to represent storage keys.
With the ink! 5.0 release, these encoding formats have been aligned,
and SCALE encoding (little endian) is now used for the metadata storage keys.
This is a breaking change, and client tools that use the storage keys from contract
metadata will need to adapt accordingly.

Please see: [#2048](https://github.com/use-ink/ink/pull/2048) for details.

Example:

```diff
    "storage": {
        "root": {
        "layout": {
            "struct": {
            "fields": [
                {
                "layout": {
                    "leaf": {
-                   "key": "0x00000159",
+                   "key": "0x59010000",
                    "ty": 0
                    }
                },
                "name": "value"
                }
            ],
            "name": "Flipper"
            }
        },
-       "root_key": "0x00000159",
+       "root_key": "0x59010000",
        "ty": 1
        }
    },
```

## Interesting New Features

### End-To-End testing with a chain snapshot

With ink! 5.0 we introduce the possibility of running your tests against the
fork (i.e. snapshot) of a live chain.

See [this page](../testing/testing-with-live-state.md) in our documentation for details.

### New lints

The new lints are:

- [`no_main`](../linter/rules/no_main.md): enforces `no_main` for contracts.
- [`primitive_topic`](../linter/rules/primitive_topic.md): no number types are allowed as event topics.
- [`storage_never_freed`](../linter/rules/storage_never_freed.md): what is written into storage can be removed again.
- [`strict_balance_equality`](../linter/rules/strict_balance_equality.md): detects usage of strict balance equality checks, a common smart contract vulnerability.
- [`non_fallible_api`](../linter/rules/non_fallible_api.md): detects the usage of potentially unsafe methods for which there are safer alternatives.

With `cargo-contract` 4.0 we added a couple new lints for common smart contract issues
and best practices.
You can run the linter via `cargo contract build --lint`.

Details on each lint can be found [here](../linter/overview.md).

### New `cargo-contract` commands

We added a bunch of helpful new commands to `cargo-contract` 4.0.
For all these commands you can also supply the `--help` cli flag to get more
info (e.g. `cargo contract storage --help`).

- `cargo contract verify`: contract verification ([#1404](https://github.com/use-ink/cargo-contract/pull/1404), [#1306](https://github.com/use-ink/cargo-contract/pull/1306))
- `cargo contract info` now outputs the language of the deployed contract, using a heuristic ([#1329](https://github.com/use-ink/cargo-contract/pull/1329))
- `cargo contract info --binary`: outputs the on-chain Wasm of the contract ([#1311](https://github.com/use-ink/cargo-contract/pull/1311/))
- `cargo contract info --all`: displays all addresses of deployed contracts on a particular chain ([#1319](https://github.com/use-ink/cargo-contract/pull/1319))
- `cargo contract storage`: displays the storage of an on-chain contract ([#1395](https://github.com/use-ink/cargo-contract/pull/1395), [#1414](https://github.com/use-ink/cargo-contract/pull/1414))

<img src="/img/cargo-contract-storage.png"  /><br/>
<img src="/img/cargo-contract-info.png"  />

### Alternative off-chain E2E testing backend support: DRink!

DRink! is a toolbox for ink! developers that allows for testing your contracts
without any running node.

It has a number of features that are pretty great:

- deploy and call your contracts synchronously, _without any delays_ related to block production or networking.
- enhanced debugging and call tracing.
- supports _arbitrary runtime_ configurations, including custom chain extensions and runtime calls.
- full control over runtime state, including block number, timestamp, etc.

See the [DRink!](https://github.com/inkdevhub/drink) page for more details.

### Contract Verification

We added a bunch of helpful documentation and `cargo-contract` commands for
contract verification. Please see the page on contract verification under "Basics"
for more details.

### We improved the contract example illustrating upgradeable contracts via `delegate_call`

See [here](https://github.com/use-ink/ink-examples/tree/main/upgradeable-contracts)
for the contract example.

### Upgradeable Contracts: `delegate_dependency`

We've added support for two new host functions:

- `lock_delegate_dependency`: prevents the code at the given code hash from being removed.
- `unlock_delegate_dependency`: releases the lock on preventing the code from being removed
  from the current contract.

Having a delegate dependency allows contracts to safely delegate to another `code_hash` with
the guarantee that it cannot be deleted.

We've updated the [`upgradeable-contracts/delegator`](https://github.com/use-ink/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/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.
You can find out if a chain supports these new functions by
querying the `contracts::apiVersion` constant. It has to be `2`.
You can use the [polakdot.js app](https://polkadot.js.org/apps/) to do this:
Developer » Chain State » Constants » `contracts` » `apiVersion` » Click on the `+` on the right.

<img src="/img/api-version-2.png"  />

At the time of the ink! v5 release (March 2024) no parachain with ink! support
had upgraded to `polkadot-v1.8.0` yet.

### We made `set_code_hash` generic

The `self.env().set_code_hash()` method now accepts the `Hash` environment type instead
of a concrete `[u8; 32]`.

```rust
// Previously
pub fn set_code(&mut self, code_hash: [u8; 32]) {
    ink::env::set_code_hash(&code_hash).unwrap_or_else(|err| {});
}

// Now
pub fn set_code(&mut self, code_hash: Hash) {
    self.env().set_code_hash(&code_hash).unwrap_or_else(|err| {});
}
```

More details in [#1906](https://github.com/use-ink/ink/pull/1906).

### Buffer size can be customized

With [#1869](https://github.com/use-ink/ink/pull/1869) we added a possibility
of setting a custom static buffer size for ink! to use.

ink! uses a static buffer for interacting with pallet-contracts, i.e. to move data
between `pallet-contracts` and a smart contract. The advantage of a static buffer
is that no gas-expensive heap allocations are necessary, all allocations are done
using simple pointer arithmetic.

The default static buffer size is 16 kB, which is enough for on-chain smart
contracts. However, the [Phala Network](https://phala.network/) parachain on Polkadot
allows the deployment of ink! contracts off-chain. Hence, for their chain certain high
computation contracts might require a larger buffer size.

### Stabilized `call_runtime`

We stabilized `call_runtime` in [#1749](https://github.com/use-ink/ink/pull/1749).
It can be used to call a runtime dispatchable from an ink! contract.

You can find a contract example and a comparison with chain extensions
[here](https://github.com/use-ink/ink-examples/tree/main/call-runtime).
We've added an example of how to end-to-end test
`call_runtime` [here](https://github.com/use-ink/ink-examples/tree/main/e2e-call-runtime).
````

## File: docs/faq/migrating-from-ink-5-to-6.md
````markdown
---
title: "Migration: ink! v5 → v6"
slug: /faq/migrating-from-ink-5-to-6
---

import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/title/migration-5.x-to-6.0.svg')} className="titlePic titleSpace" title="Migration 5.x To 6.0 Title Picture" />

We've made a number of breaking changes from ink! 5.x to ink! 6.0.
On this page we outline how you can migrate existing dApps and
contracts.

The biggest change is that we've migrated from `pallet-contracts` +
WebAssembly (executed in `wasmi`) to [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive) +
RISC-V (executed in [PolkaVM](https://github.com/paritytech/polkavm/)).
_This is a major breaking change, ink! v6 is only compatible with `cargo-contract` >= v6
and chains that include `pallet-revive`._

We did a detailed write-up of the background to this development and the reasoning
[here](https://r0gue.medium.com/ink-project-state-q1-25-08441f4ac5d2). 

You can find the full changelog of the 6.0 release [here](https://github.com/use-ink/ink/blob/master/CHANGELOG.md#version-600).

:::caution
This migration guide only considers your code base! Not your storage data!

If you have an existing contract on-chain you might not be able to just
upgrade the code on-chain, you possibly also have to migrate your storage data.
:::

## Compatibility

- **`polkadot-sdk`**: [this branch](https://github.com/use-ink/polkadot-sdk/tree/pallet-revive-with-system-and-storage-precompiles)
- For the latest compatibility requirements of Rust, `cargo-contract` and the `ink-node`, see the [setup instructions](/docs/v6/getting-started/setup).

### How do I find out if a chain is compatible with ink! 6.0?

You can query `contracts::palletVersion()` via the chain state RPCs. It has to
be `>= 9` for ink! 5.0 to be compatible, if you don't use any of the four functions
mentioned above.
For the above mentioned four functions please see the respective sections on this page,
there we explain how to find out if a chain supports them there.

You can use the [polkadot.js app](https://polkadot.js.org/apps/) to connect to the chain and check if
`reviveApi` is available under Developer » Runtime calls.

<img src={useBaseUrl('/img/pallet-revive-available.png')} />

The following chains are in production and support ink! 6.0.

<div className="row">
    <div className="col text--center">
        <a href="https://onpop.io">
            <img src={useBaseUrl('/img/chains/polkadot-pop-network.svg')} className="chain" />
        </a>
    </div>
    <div className="col text--center">
        <a href="https://kusama.network/">
            <img src={useBaseUrl('/img/chains/kusama-assethub.svg')} className="chain" />
        </a>
    </div>
</div>

## Important Changes

We had to introduce a number of changes that require you to manually upgrade
your contract from 5.x to 6.0. The steps are explained in this section.

### Restrict which `cfg` attributes can be used

This change was done as a recommendation from the ink! 5.x audit.
In a nutshell it prevents developers from hiding functionality in a contract,
that would not be visible in the metadata (so e.g. on a block explorer).
The relevant PR is [#2313](https://github.com/use-ink/ink/pull/2313).

From ink! 6.0 on only these attributes are allowed in `#[cfg(…)]`: - `test` - `feature` (without `std`) - `any` - `not` - `all`

### Metadata Changes

The field `source.wasm` was renamed to `source.contract_binary`.

### Types

#### Contract Balance: `U256`
For the type of a contract's balance, `pallet-revive` uses depending on the context
* either the configured `pallet_revive::Config::Currency` type (which corresponds
  to the `ink::Environment::Balance` type.
* or a hardcoded `U256` (which corresponds to what Ethereum uses).
  In this alpha release we just adhere to requiring the types that `pallet-revive` uses.
  In an upcoming beta release this could be simplified to reduce UX friction by just
  using one type everywhere and converting to the `pallet-revive` one.

#### Contract Address: `Address` / `H160`
For a contract's account, `pallet-revive` is using either the configured `AccountId` type
of the `polkadot-sdk` runtime, or `H160`.

`Address` is a more semantically named type alias for `H160` defined in `ink_primitives`,
and re-exported in the `ink` crate.

Finding the `Address`/`H160` for an `AccountId` is done via an address derivation scheme
derived in [#7662](https://github.com/paritytech/polkadot-sdk/pull/7662).
After instantiating a contract, the address is no longer returned by `pallet-revive`.
Instead one has to derive it from given parameters (see the linked PR). `cargo-contract`
does that automatically.

For contract instantiations and contract calls the pallet requires that a 1-to-1 mapping
of an `AccountId` to an `Address`/`H160` has been created. This can be done via the
`map_account`/`unmap_account` API.
The PR [#6096](https://github.com/paritytech/polkadot-sdk/pull/6096) contains more
information.

Besides the publicly exposed crate functions, we've introduced a new subcommand
`cargo contract account` that allows resolving the `H160` contract address to the
Polkadot SDK `AccountId` which it is mapped to.

#### Contract Hash: `H256`
For a contract's hash value, `pallet-revive` uses a fixed `H256`, Previously,
the `ink::Environment::Hash` type referenced the hash type being used for the
contract's hash. Now it's just a fixed `H256`.

### Contract delegates can no longer be done by code
In `pallet-contracts` (and hence up until ink! v5), a pattern for upgradeable
contracts was to delegate the contract execution to a different code, e.g. to
a new version of the contract's code.

This distinction of contract code that was uploaded to a chain vs. an instantiated
contract from this code no longer exists in `pallet-revive`. If you want to
delegate the execution, you will have to specify another contract's address
to which code you want to delegate to. This other contract needs to be instantiated
on-chain.

For the execution, the context of the contract that delegates will continue
to be used (storage, caller, value).

Specifically the delegate API changed like this:

```rust
/// ink! v5
#[derive(Clone)]
pub struct DelegateCall<E: Environment> {
    code_hash: E::Hash,
    call_flags: CallFlags,
}

/// ink! v6
#[derive(Clone)]
pub struct DelegateCall {
    address: H160,
    flags: CallFlags,
    ref_time_limit: u64,
    proof_size_limit: u64,
    deposit_limit: Option<[u8; 32]>,
}
```

### Feature `ink/unstable-hostfn`
In `pallet-revive` a number of functions can only be called by smart contracts
if the chain that the pallet is running on has enabled the feature
`pallet-revive/unstable-hostfn`.
This feature is not enabled on Kusama or Westend!

It is enabled for the `ink-node` version that we linked above.

### New debugging workflow
Previously `pallet-contracts` returned a `debug_message` field with contract
instantiations and dry-runs.
Whenever `ink::env::debug_println` was invoked in a contract, ink! wrote debugging
info to this field. This functionality has been removed. Instead `pallet-revive` now
supports other means of debugging.

The most relevant new debugging workflow is the tracing API. There are a number
of PRs that implemented it, so we won't link a specific one here. A good starting
point to look deeper into it is the [`tracing.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/revive/src/tracing.rs).

We have implemented barebones support for this tracing API in the 6.0.0-alpha
versions of ink! + `cargo-contract`. But it's really barebones and should
certainly be improved before a production release.

We've updated [the Debugging chapter](../debugging/overview.md) of this documentation
to reflect the new workflow.
We've also added a contract example to illustrate these new debugging strategies:
[`debugging-strategies`](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies).

### Removed Events
In [#7164](https://github.com/paritytech/polkadot-sdk/pull/7164), Parity removed
most smart-contract-specific events: `Called`, `ContractCodeUpdated, CodeStored`,
`CodeRemoved`, `Terminated`, `Instantiated`, `DelegateCalled`,
`StorageDepositTransferredAndHeld`, `StorageDepositTransferredAndReleased`.

The `ContractEmitted` event (for events a contract emits) is still available.

### `no_main`

Previously ink! contracts started with this line:

```rust
#![cfg_attr(not(feature = "std"), no_std)]
```

This line instructs the Rust compiler to not link the Rust 
standard library with your contract. 
If you want to know about why:
we have an entry 
["Why is Rust's standard library (stdlib) not available in ink!?"](./faq.md)
in our FAQ.

With ink! v6, an additional crate-level attribute needs to be set:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]
```

It instructs the compiler not to use the default `fn main() {}` function as the
entry point for your smart contract. This is needed because PolkaVM uses a different
entry point (the `deploy` function).

### `substrate-contracts-node` can no longer be used
The `substrate-contracts-node` is still maintained by Parity for ink! v5 and
`pallet-contracts`, but it does not support `pallet-revive`.

We've set up a new project in its place: [`ink-node`](https://github.com/use-ink/ink-node).
As before, it functions as a simple local development node.
It contains `pallet-revive` in a default configuration.
You can find binary releases of the node [here](https://github.com/use-ink/ink-node/releases).

### Solang can no longer be used
It was previously possible to interact with Solidity contracts compiled via the 
Solang compiler. As we have moved from WebAssembly/`pallet-contracts` to 
PolkaVM/RISC-V/`pallet-revive`, users who want to deploy Solidity will use
[the Parity `revive` compiler](https://github.com/paritytech/revive). It takes 
Solidity contracts and compile them into RISC-V for PolkaVM.

### `payable` messages are now considered state-mutating

To align with how Solidity is treated by `pallet-revive`, we decided on this
breaking change.
The implication is that you can no longer mark `&self` ink! messages as `payable`,
they have to be `&mut self` now.

```diff
#[ink(message, payable)]
-pub fn my_message(&self) {}
+pub fn my_message(&mut self) {}
```

### Removed `call_runtime` and Chain Extensions

The `pallet-revive` no longer provides a host function to call into the runtime.
Parity removed this feature as the runtime can change and changes could potentially
break already deployed contracts.

The way to go instead would be to create [a precompile contract](../basics/precompiles.md))
and have your contract invoke either a cross-contract call or a delegate call into that one.

This is also the migration path recommended for Chain Extensions.

### Renamed `ink::contract_ref!` to `ink::contract_ref_from_path!`

This was necessary because we introduced a new [`#[ink::contract_ref]` attribute][contract-ref-attr].
The PR [#2648](https://github.com/use-ink/ink/pull/2648) contains more information
about the motivation and benefits of this change.

[contract-ref-attr]: ../macros-attributes/contract_ref.md

## Interesting New Features

### Solidity ABI compatible ink! contracts
We are introducing an `abi` field in a custom `ink-lang` table
in the [`package.metadata` table][package-metadata] of a contract's manifest
file (i.e. the `Cargo.toml` file).
It allows building your contract in Solidity ABI compatibility mode
when declared as follows:

```toml
[package.metadata.ink-lang]
abi = "sol"
```

The implication of supporting Solidity ABI encoding is that all types used as
constructor/message argument and return types, and event argument types must
define a mapping to an equivalent Solidity ABI type.
You won't be able to use Rust types for which no mapping to a Solidity ABI type is defined.
An error about a missing trait implementation for this type will be thrown.
You can learn more about [Rust/ink! to Solidity ABI type mapping here][sol-type-mapping].

:::note
This is similar to the requirement to implement `scale::Encode` and `scale::Decode`
for Rust types used in the public interfaces of ink!/"native" ABI encoded contracts.
:::

The default value for `abi` is currently `"ink"`, 
but we might change this before a production release.

The other option is `abi = "all"`. In this mode, the generated contract
will support both the ink! and Solidity ABI, however, the contract size
will get larger. You can learn more about [supported ABI modes here][abi-declaration].

[package-metadata]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table
[abi-declaration]: ../basics/abi/overview.md#declaring-the-abi
[sol-type-mapping]: ../integrations-and-sdks/ethereum-compatibility.md#rustink-to-solidity-abi-type-mapping

### Cross-contract calling Solidity contracts
`CallBuilder` now allows you to call contracts that are Solidity ABI encoded.

You can learn more [here](../basics/cross-contract-calling.md#callbuilder-solidity).

### Generate Solidity metadata for a Solidity ABI compatible ink! contract
We added a new subcommand:

```bash
cargo contract build ---metadata <ink|solidity>
```

You can learn more [here](../basics/metadata/solidity-format.md).

### Ability to build contract with features during E2E tests
We've added the possibility to set a feature to build a contract with during e2e tests:

```rust
#[ink_e2e::test(features = ["debug-info"])]
```

This allows for e.g. emitting debug events in the contract, which
you can then check for in testing.
Please see our [`debugging-strategies`](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies)
example for a complete explainer.

We've added a page [Debugging » Events](../debugging/events.md) to this documentation.
We've also added a contract example that illustrates the usage:
[`debugging-strategies`](https://github.com/use-ink/ink/tree/master/integration-tests/public/debugging-strategies).
````

## File: docs/getting-started/calling.md
````markdown
---
title: Call your contract
slug: /getting-started/calling-your-contract
hide_title: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Frontend Title Picture](/img/title/frontend.svg)

# Call Your Contract

Now that your contract has been fully deployed, we can start interacting with it! Flipper only has
two functions: `flip()` and `get()`. We will show you what it's like to play with both of them.

## RPC calls vs. Transactions

There are two ways of calling a contract:

### Dry-run via RPC

Remote procedure calls, or RPC methods, are a way for an external program – for example, a browser
or front-end application – to communicate with a Polkadot SDK node. 
For example, you might use an RPC method to read a stored value, submit a transaction, or request
information about the chain a node is connected to.

If a user interface displays the value of a contract (e.g. the balance of an account in
an ERC-20 contract), then this is typically done via RPC. Specifically it is done by
executing a synchronous dry-run of the contract method and returning its result.
The following schema depicts this.

![Contract dry-run via RPC](/img/rpc-revive.svg)

RPC calls don't require any tokens, they just require a connection to a node in the 
network. It's important to note that the execution won't result in any state mutations
on the blockchain, it really just is a dry-run.

### State mutating via submitting a Transaction 

The other method of executing a call to a contract is by submitting a transaction
on-chain. This requires tokens of the network to pay for the cost of the transaction.
The transaction will be put in a transaction pool and asynchronously processed.
The important implication here is that during submission of the transaction no result
is available. This is different from an RPC call.

The typical pattern for how a client can recognize the result of the contract call is
to have the contract emit an event and have the client actively listen for such an
event. Typically libraries (like `polkadot-js/api`) provide API functions to do just that.
The important take-away is that contract developers have to make sure that events
are emitted if they want clients to be able to pick up on them.

![Contract execution via transaction](/img/events-revive.svg)

## Using the Terminal

When you deployed your contract you received the contract address. Use this to interact with the contract.
```bash
Contract Address: 5DXR2MxThkyZvG3s4ubu9yRdNiifchZ9eNV8i6ErGx6u1sea
```

### 1. `get()` function

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>
  ```bash
  cargo contract call 
    --contract <insert-contract-address> 
    --message get 
    --suri //Alice
  ```
  </TabItem>
  <TabItem value="pop" label="Pop">
  ```bash
  pop call contract 
    --contract <insert-contract-address> 
    --message get 
    --suri //Alice
  ```
  </TabItem>
</Tabs>

### 2. `flip()` function

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>
  ```bash
  cargo contract call 
    --contract <insert-contract-address>
    --message flip
    --execute
    --suri //Alice
  ```
  </TabItem>
  <TabItem value="pop" label="Pop">
  ```bash
  pop call contract 
    --contract <insert-contract-address>
    --message flip
    --execute
    --suri //Alice
  ```
  </TabItem>
</Tabs>

:::tip
For more info about interacting with your smart contract using the Pop CLI, [check this out](https://learn.onpop.io/contracts/guides/call-your-contract)!
:::

## Using the Contracts UI

Go to https://ui.use.ink/

### 1. `get()` function

We set the initial value of the Flipper contract
`value` to `false` when we instantiated the contract. Let's check that this is the case.

In the **Message to Send** section, select the "**get(): bool**" message and accept the default
values for the other options.

Press **"Read"** and confirm that it returns the value `false`:

![An image of Flipper RPC call with false](/img/contracts-ui-4.png)

### 2. `flip()` function

So let's make the value turn `true` now!

The alternative message to send with the UI is `flip()`. Again, accept the default values for the other options and click **Call contract**

![An image of a Flipper transaction](/img/contracts-ui-5.png)

If the transaction was successful, we should then be able to go back to the `get()` function and see our updated storage:

![An image of Flipper RPC call with true](/img/contracts-ui-6.png)
````

## File: docs/getting-started/compiling.md
````markdown
---
title: Compile your contract
slug: /getting-started/building-your-contract
hide_title: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Cargo Contract Title Picture](/img/title/cargo-contract.svg)

# Compile Your Contract

Navigate to your contract directory (e.g., `cd flipper`) and run the following command to compile your smart contract:

<Tabs>
  <TabItem value="pop" label="Pop CLI (Recommended)" default>
  ```bash
  pop build
  ```
  </TabItem>
  <TabItem value="cargo-contract" label="cargo-contract">
  ```bash
  cargo contract build
  ```
  </TabItem>
</Tabs>

This command will build the following for your contract: 
a binary, a metadata file (which contains the
contract's ABI) and a `.contract` file which bundles both.

In principle, you can also build your contract using just the normal Rust build workflow
(`cargo build`). We'll use `cargo-contract` though, as it invokes `cargo build` with an
optimal set of flags.

If all goes well, you should see a `target` folder that contains these files:

```
target
  └─ ink
    └─ flipper.polkavm     <-- Raw contract binary
    └─ flipper.json        <-- Metadata for the contract
    └─ flipper.contract    <-- JSON file that combines binary + metadata
```

You can think of "Metadata" this way: the raw `.polkavm` 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 or what their arguments
are. This additional information that describes what the raw binary
is about is called metadata — data that describes other data.

<p>
    <img src={useBaseUrl('/img/metadata-polkavm.svg')} />
</p>

The purpose of each file is:

* `flipper.polkavm`: 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 `cargo-contract` to interact with a contract
or when you use a developer UI like [Contracts UI](https://ui.use.ink).

Let's take a look at the structure of the `flipper.json`:

```json
{
  "source": {...},
  "contract": {...},
  "spec": {
    "constructors": [...],
    "docs": [],
    "events": [],
    "messages": [...],
  },
  "storage": {...},
  "types": [...],
  "version": "6"
}
```

This file describes all the interfaces that can be used to interact with your contract:

* `types` provides the custom *data types* used throughout the rest of the JSON.
* `storage` defines all the *storage* items managed by your contract and how to ultimately access them.
* `spec` stores information about the callable functions like *constructors* and *messages* a
user can call to interact with the contract. It also has helpful information like the *events*
that are emitted by the contract or any *docs*.
  
If you look closely at the constructors and messages, you will also notice a `selector` which
contains a 4-byte hash of the function name. This selector is used to route your contract calls to the correct
functions.

You can 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 difference is that the `.contract` file contains
an additional field with the hex-encoded binary of your contract:

```json
{
    "source": {
        …
        "contract_binary": "0x006173…",
    },
    …
}
```

:::info
Pipe the `flipper.json` through [`jq`](https://jqlang.org/) to pretty-print it: `cat flipper.json | jq`.
:::

## Debug vs. Release Build

By default, `cargo-contract` builds the contract in debug mode. This means
that debugging information will be preserved.
If you e.g. panic like this:

```rust
self.env().set_code_hash(&code_hash).unwrap_or_else(|err| {
    panic!("Failed to `set_code_hash` to {code_hash:?} due to {err:?}")
});
```

The return value of a contract during a dry-run will contain this textual panic message.
To support functionality like this the debug build of a contract includes some
heavy-weight logic which increases the contract's size.

For contracts that are supposed to run in production you should always build the
contract with `--release`:

<Tabs>
  <TabItem value="pop" label="Pop CLI (Recommended)" default>
  ```bash
  pop build --release
  ```
  </TabItem>
  <TabItem value="cargo-contract" label="cargo-contract">
  ```bash
  cargo contract build --release
  ```
  </TabItem>
</Tabs>

This will ensure that nothing unnecessary is compiled into the binary blob, making
your contract faster and cheaper to deploy and execute.

:::info
With this behavior `cargo-contract` mirrors how `cargo` behaves for Rust programs:
the `--release` flag has to be passed explicitly to `cargo build`.
:::

## Test Your Contract
If you created a new project using a template, you can find at the bottom of the lib.rs simple test cases which verify the functionality of the contract. We can quickly test this code is functioning as expected:

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>
  ```bash
  cargo contract test
  ```
  </TabItem>
  <TabItem value="pop" label="Pop">
  ```bash
  pop test
  ```
  </TabItem>
</Tabs>

To which you should see a successful test completion:

```bash
running 2 tests
test flipper::tests::it_works ... ok
test flipper::tests::default_works ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
```

Learn more about the [testing strategies for ink! contracts](../testing/overview.md).
````

## File: docs/getting-started/creating.md
````markdown
---
title: Create an ink! Project
slug: /getting-started/creating-an-ink-project
hide_title: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Heart Title Picture](/img/title/heart.svg)

:::info
This guide uses **ink! v6**, the latest version. ink! v6 compiles to RISC-V bytecode (instead of WebAssembly) for better performance and efficiency. If you're following older tutorials, note that some things have changed.
:::

## Create a new project
Make sure you have [installed Pop CLI](./setup.md) and that you are in the working directory, and then run:

<Tabs>
  <TabItem value="pop" label="Pop CLI (Recommended)" default>
  ```bash
  pop new contract
  ```

  Pop CLI will guide you through an interactive setup where you can:
  - Choose a contract name
  - Select from various contract templates (Flipper, ERC20, ERC721, etc.)
  - Automatically configure your project

  </TabItem>
  <TabItem value="cargo-contract" label="cargo-contract">
  ```bash
  cargo contract new flipper
  ```
  </TabItem>
</Tabs>

This command will create a new project folder named `flipper` with:

```
flipper
  └─ lib.rs         <-- Contract Source Code
  └─ Cargo.toml     <-- Rust Dependencies and ink! Configuration
  └─ .gitignore
```

:::tip
The [Pop CLI](https://learn.onpop.io/contracts/guides/create-a-new-contract) has many templates to offer!

For more details on contract structure and examples, visit **https://use.ink/docs/v6/**
:::

## Contract Source Code

For the `lib.rs` file, `cargo-contract` automatically generates the source code for the "Flipper" contract, which is about the simplest "smart" contract you can build. You can take a sneak peak as to what will come by looking at the source code here:
[Flipper Example Source Code](https://github.com/use-ink/ink-examples/blob/main/flipper/lib.rs).

The Flipper contract is nothing more than a `bool` which gets flipped from `true` to `false` through the `flip()` function. 

Now that we are feeling confident things are working, we can actually compile the contract in the next step.
````

## File: docs/getting-started/deploying.md
````markdown
---
title: Deploy your contract
slug: /getting-started/deploy-your-contract
hide_title: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import useBaseUrl from '@docusaurus/useBaseUrl';

![Rocket Title Picture](/img/title/rocket.svg)

Deploying a smart contract means uploading your compiled contract code to a blockchain and creating an instance of it. This guide will walk you through deploying your ink! contract both locally and on the PassetHub testnet.

# Prerequisites

Before deploying, make sure you've:
1. Created your contract with `pop new contract`
2. **Built it with the release flag**: `pop build --release`

The `--release` flag is important - it optimizes your contract for production, making it smaller and more efficient.

:::tip Interactive Mode
Pop CLI commands can be run interactively! You don't always need to specify all the flags. For example, running `pop up` without arguments will prompt you to select options interactively. This guide shows the full command-line arguments for clarity, but feel free to use the interactive mode if you prefer.
:::

:::info Learn More
For complete ink! documentation, visit **https://use.ink/docs/v6/**
:::

# Deploying Locally

Local deployment is perfect for testing. You'll run a local blockchain on your computer with test accounts that already have tokens.

## Step 1: Launch Local Asset Hub

Start a local Paseo relay chain with Asset Hub:

```bash
pop up paseo --parachain asset-hub
```

This will:
- Start a local Paseo relay chain
- Start a local Asset Hub parachain
- Provide you with test accounts (Alice, Bob, Charlie, etc.) that have tokens

Keep this terminal window open - the network needs to stay running.

## Step 2: Map Your Account

Before deploying contracts, you need to map your account. This is required to interact with smart contracts.

**Option A: Using Pop CLI (Command Line)**
```bash
pop call chain \
  --pallet revive \
  --function map_account \
  -s //Alice \
  -u ws://localhost:9944
```

**Option B: Using Polkadot.js Apps (Visual)**
1. Open https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:9944#/extrinsics
2. Select the `revive` pallet
3. Select the `mapAccount` function
4. Sign and submit with Alice account

## Step 3: Deploy Your Contract

Open a new terminal (keep the network running in the first one), navigate to your contract directory, and run:

```bash
pop up \
  --path ./my-contract \
  -u ws://localhost:9944 \
  -a true \
  -s //Alice
```

**Breaking down the command:**
- `--path ./my-contract` - Path to your contract directory
- `-u ws://localhost:9944` - URL to your local node
- `-a true` - Constructor arguments (**Flipper example**: the `new(true)` constructor takes a boolean)
- `-s //Alice` - Use Alice's account to deploy (has tokens in local environment)

:::note Finding Your Constructor Arguments
The `-a` flag depends on YOUR contract's constructor!
- Open your contract's `lib.rs` file
- Look for functions marked with `#[ink(constructor)]`
- The Flipper contract has `new(init_value: bool)`, so we use `-a true` or `-a false`
- If your contract has a different constructor like `new(name: String, supply: u128)`, you'd use `-a "MyToken" -a 1000000`
:::

:::tip Interactive Mode
You can also just run `pop up` and Pop CLI will interactively prompt you for each option!
:::

After a few seconds, you'll see the contract address. **Save this address** - you'll need it to interact with your contract!

## Step 4: Interact With Your Contract

There are two types of contract calls:

### Read-Only Calls (Queries)
Functions that only read data don't need to be executed on-chain:

```bash
pop call contract \
  --path ./my-contract \
  -u ws://localhost:9944 \
  --contract 0xYOUR_CONTRACT_ADDRESS \
  --message get \
  -s //Alice
```

This performs a "dry run" that returns the value without creating a transaction.

**Example for Flipper contract:** `get` is a read-only function that returns the current boolean value.

### State-Changing Calls (Transactions)
Functions that modify state need the `-x` flag to execute on-chain:

```bash
pop call contract \
  --path ./my-contract \
  -u ws://localhost:9944 \
  --contract 0xYOUR_CONTRACT_ADDRESS \
  --message flip \
  -s //Alice \
  -x
```

The `-x` (or `--execute`) flag submits an actual transaction that changes the contract's state and costs gas.

**Example for Flipper contract:** `flip` changes the boolean value from true to false (or vice versa).

**Key difference:**
- **Without `-x`**: Reads data, free, instant
- **With `-x`**: Changes state, costs gas, takes a few seconds to confirm

:::note Finding Your Contract's Functions
The `--message` flag depends on YOUR contract's functions!
- Open your contract's `lib.rs` file
- Look for functions marked with `#[ink(message)]`
- Functions with `&self` are usually read-only (no `-x` needed)
- Functions with `&mut self` modify state (need `-x` flag)
- For Flipper: `get(&self)` is read-only, `flip(&mut self)` modifies state
:::

Replace:
- `0xYOUR_CONTRACT_ADDRESS` with the address from Step 3
- `flip` or `get` with the function names from YOUR contract

:::tip Interactive Mode
Or simply run `pop call contract` and follow the interactive prompts!
:::

---

# Deploying to PassetHub Testnet

Ready to deploy publicly? Here's how to deploy to the live PassetHub testnet (ParaID: 1111, RPC: wss://testnet-passet-hub.polkadot.io). This uses test tokens (no real money involved), but your contract will be publicly accessible.

## Step 1: Get an Account

You need a Polkadot account. We recommend using **subkey** for command-line users:

```bash
# Install subkey
cargo install --force subkey --git https://github.com/paritytech/polkadot-sdk

# Generate a new account
subkey generate
```

This outputs:
- **Secret seed** (0x... format) - use this for the `-s` flag
- **SS58 Address** (starts with 5) - use this for the faucet

**Save all this information securely!**

:::tip Alternative: Browser Extension
Prefer a visual interface? You can use the [Polkadot.js browser extension](https://polkadot.js.org/extension/) instead and use the `-w` flag with Pop CLI commands.
:::

## Step 2: Get Test Tokens

Get free PAS tokens from the faucet:

1. Go to https://faucet.polkadot.io/?parachain=1000
2. Enter your account address
3. Click "Get Tokens"
4. Wait ~30 seconds for the tokens to arrive

Verify you received tokens at: https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fasset-hub-paseo#/accounts

## Step 3: Map Your Account on PassetHub

Before deploying, map your account:

**Using Pop CLI:**
```bash
pop call chain \
  --pallet revive \
  --function map_account \
  -u wss://testnet-passet-hub.polkadot.io \
  -s "YOUR_PRIVATE_KEY_OR_SEED"
```

Replace `YOUR_PRIVATE_KEY_OR_SEED` with your private key from Step 1.

**Using Polkadot.js Apps:**
1. Go to https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Ftestnet-passet-hub.polkadot.io#/extrinsics
2. Select `revive` pallet → `mapAccount` function
3. Sign and submit

## Step 4: Deploy to Testnet

```bash
pop up \
  --path ./my-contract \
  -u wss://testnet-passet-hub.polkadot.io \
  -a true \
  -s "YOUR_PRIVATE_KEY"
```

**Note:** The `-a true` is specific to the Flipper contract's constructor. Check your contract's `lib.rs` for the constructor arguments (look for `#[ink(constructor)]`).

**Security Note:** For production or public environments, use the wallet option instead:
```bash
pop up \
  --path ./my-contract \
  -u wss://testnet-passet-hub.polkadot.io \
  -a true \
  -w
```

The `-w` flag opens a browser prompt to sign with your Polkadot.js extension - much safer than pasting private keys!

## Step 5: Call Your Contract on Testnet

**For read-only calls (queries):**
```bash
pop call contract \
  --path ./my-contract \
  -u wss://sys.ibp.network/asset-hub-paseo \
  --contract 0xYOUR_CONTRACT_ADDRESS \
  --message get \
  -w
```

**Note:** `get` is specific to the Flipper contract. Use your contract's read-only function names (marked with `#[ink(message)]` and `&self` in `lib.rs`).

**For state-changing calls (transactions), add `-x`:**
```bash
pop call contract \
  --path ./my-contract \
  -u wss://sys.ibp.network/asset-hub-paseo \
  --contract 0xYOUR_CONTRACT_ADDRESS \
  --message flip \
  -w \
  -x
```

**Note:** `flip` is specific to the Flipper contract. Use your contract's state-changing function names (marked with `#[ink(message)]` and `&mut self` in `lib.rs`).

---

# Tips

- **Always use `--release`** when building contracts for deployment
- **Local testing first** - Test thoroughly locally before deploying to testnet
- **Use `-w` flag** - Prefer wallet signing over pasting private keys when possible
- **Save contract addresses** - You'll need them to interact with your contracts
- **Check transaction status** - Failed transactions still consume gas

# Alternative: Using Contracts UI

You can also deploy visually using Contracts UI at https://ui.use.ink - connect it to your local node or PassetHub and follow the visual deployment wizard.

# Learn More

For complete ink! documentation including advanced topics, examples, and API references, visit:

**https://use.ink/docs/v6/**

**Note:** `ink-node` uses the `--dev` flag by default. You may need to specify the `--dev` flag when running a different chain binary.

<img src={useBaseUrl('/img/ink-node.png')} className="titlePic titleSpace" title="Screenshot of terminal starting a local node" />

You can interact with your node using `cargo-contract`, `pop` or [the Contracts UI](https://ui.use.ink/). If you use the Contracts UI, you have to configure it to connect to the locally running node:

- Click on the dropdown selector at the top left corner.
- Choose "Local Node".

![Connect to local node](/img/contracts-ui-local-node.png)


# Set up a Local Polkadot Hub Environment

You can easily launch a full Polkadot Hub setup locally using the [Pop CLI](https://learn.onpop.io/contracts/guides/deploy). This includes a local relay chain and one or more system parachains, allowing for end-to-end smart contract development and testing.


To spin up the environment with the Paseo relay chain and system chains like `asset-hub` and `passet-hub`, run:
```bash
  pop up paseo -p asset-hub,passet-hub
```
This command will launch:

- A local Paseo relay chain

- [Passet Hub](../intro/where-to-deploy.md#passet-hub) as a parachain, connected and ready to deploy smart contracts

You can also include additional system parachains in your local environment, such as `people` and `pop`, by extending the command:
```bash
  pop up paseo -p asset-hub,passet-hub,people,pop
```

Need more options or configuration details? Check out the CLI help:
```bash
  pop up paseo --help 
```

## Deploy the contract

Now that we have generated the contract binary from our source code and connected to a local node, we want to deploy this contract onto our local node.

Smart contract deployment on Polkadot is a little different than on traditional smart contract blockchains.

For example, the standard ERC20 token has been deployed to Ethereum thousands of times, sometimes only with changes to the initial configuration (through the Solidity `constructor` function). Each of these instances take up space on the blockchain equivalent to the contract source code size, even though no code was actually changed.

The contract deployment process in Polkadot is split into two steps:

1. Putting your contract code on the blockchain
2. Creating an instance of your contract

With this pattern, contract code like the ERC20 standard can be put on the blockchain one single time, but instantiated any number of times. No need to continually upload the same source code over and waste space on the blockchain.

## Using the Terminal

With `cargo-contract` or `pop` it's just a simple sequence of:

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>
  ```bash
  cargo contract build
  cargo contract instantiate --suri //Alice --args true
  ```
  </TabItem>
  <TabItem value="pop" label="Pop">
  ```bash
  pop build
  pop up --suri //Alice --args true
  ```
  </TabItem>
</Tabs>

## Using the Contracts UI

### 1. Upload Contract Code

Here we will upload the contract code and instantiate one copy of the contract on the blockchain (which is usually why we upload the contract code in the first place):

- Go to https://ui.use.ink/
- Make sure you have ink! v6 selected in the sidebar
- Click the **Add New Contract** button in the sidebar.
- Click the **Upload New Contract Code** button in the Add New Contract page.
- Choose an **Instantiation account** (e.g. ALICE).
- Give the contract a descriptive **Name** (e.g. Flipper Contract).
- Drag the `flipper.contract` file that contains the bundled binary blob and metadata into the drag & drop area. You will see the UI parse the metadata and enabling the button that takes you to the next step.
- Click the **Next** button

![Flipper Instantiate Contract 01](/img/contracts-ui-0.png)

### 2. Instantiate a Contract on the Blockchain

Smart contracts exist as an extension of the account system on the blockchain. Thus creating an instance of this contract will create a new `AccountId` (ETH-compatible address) which will store any balance managed by the smart contract and allow us to interact with the contract.

Now a screen displays the information that represents our smart contract. We are going to instantiate a copy of the smart contract:

- Accept the default options for the contract **Deployment Constructor**.
- Accept the default options **Max Gas Allowed** of `200000`.
- Click on `Next`

![Flipper Instantiate Contract 02](/img/contracts-ui-1.png)

The transaction is now queued, review your data and click **Upload and Instantiate** or go back and modify your inputs.

![Flipper Instantiate Contract 03](/img/contracts-ui-2.png)

You will be redirected to a new page, where you can interact with the newly created contract instance.

![Flipper Instantiate Success](/img/contracts-ui-3.png)
````

## File: docs/getting-started/setup.md
````markdown
---
title: Setup
slug: /getting-started/setup
hide_title: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Setup Title Picture](/img/title/setup.svg)

# Setup

:::info
This guide is for **ink! v6**, the latest version featuring RISC-V bytecode and enhanced performance.
:::

This guide will help you set up everything you need to start building ink! smart contracts. We'll be using **Pop CLI**, which provides the best developer experience for ink! development.

## Prerequisites

Before you begin, make sure you have the following installed:

### 1. Check if you have Homebrew (macOS/Linux users)

Run this command in your terminal:
```bash
brew --version
```

If you see a version number, you have Homebrew installed! If not, you'll need to install it first (the assistant can guide you through this).

### 2. Install Rust (Required for all installation methods)

**Minimum version required**: Rust 1.90 or higher

Install Rust using rustup:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

After installation, verify your Rust version:
```bash
rustc --version
```

You should see version 1.90 or higher. If you already have Rust installed but it's an older version, update it:
```bash
rustup update
```

### 3. Install Protobuf (Required for cargo install method)

If you plan to install Pop CLI using `cargo install`, you'll also need protobuf:

**macOS:**
```bash
brew install protobuf
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt install protobuf-compiler
```

**Linux (Fedora):**
```bash
sudo dnf install protobuf-compiler
```

Verify installation:
```bash
protoc --version
```

## Install Pop CLI

Pop CLI is the recommended tool for ink! smart contract development. It provides an excellent developer experience with automated setup, contract templates, and built-in node management.

<Tabs>
  <TabItem value="brew" label="Homebrew (Recommended)" default>

      **For macOS and Linux users with Homebrew:**

      ```bash
      brew install r0gue-io/pop-cli/pop
      ```

      This is the easiest and fastest installation method!

      Verify the installation:
      ```bash
      pop --version
      ```

  </TabItem>
  <TabItem value="cargo" label="Cargo Install">

      **For users without Homebrew or on Windows:**

      Make sure you have Rust 1.90+ and protobuf installed (see Prerequisites above), then run:

      ```bash
      cargo install pop-cli
      ```

      This will take a few minutes to compile and install.

      Verify the installation:
      ```bash
      pop --version
      ```

  </TabItem>
</Tabs>

### Pop CLI Features

**Why use Pop CLI over cargo-contract?**
- **Automated setup**: Handles all required installations and dependencies for you
- **Contract templates**: Access to a range of pre-built contract templates
- **Interactive UI**: Deploy and interact with contracts through an interactive command-line interface
- **Built-in node management**: Automatically manages the `ink-node` without manual configuration
- **Easy local network setup**: Quickly spin up local development networks
- **Wallet integration**: Seamless wallet connection and management

## Alternative: cargo-contract

If you prefer the lower-level tool, you can also use `cargo-contract`:

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>

      Install [`cargo-contract`](https://github.com/use-ink/cargo-contract), a CLI tool for setting up and managing ink! smart contracts:

      ```bash
      cargo install --force --locked cargo-contract
      ```

      Make sure you have Rust 1.88+ installed:
      ```bash
      rustup update stable
      ```

      ### ink-node

      The [ink-node](https://github.com/use-ink/ink-node) is
      a simple Polkadot SDK blockchain with smart contract functionality. It's a comfortable option for local development and testing.

      There are two ways of installing the node:

      ### (1) Download the Binary
      Go to the [ink-node releases page](https://github.com/use-ink/ink-node/releases). Under `Assets` of the latest release, download the appropriate binary for your platform:
         - **Linux (ARM64)**: `ink-node-linux-arm64.tar.gz`
         - **Linux (x86)**: `ink-node-linux.tar.gz`  
         - **macOS**: `ink-node-mac-universal.tar.gz`

      Make the binary executable:
         ```bash
         chmod +x ./ink-node
         ```

      **For macOS users:**
      When you first try to run `ink-node`, macOS may show a security warning.

      To allow the binary to run:
      1. Click the **question mark (?)** icon at the right top corner of the warning.
      2. Follow the Apple instructions that appear.
      3. Try running `ink-node` again and click **"Open Anyway"** when prompted.

      To confirm that `ink-node` is working correctly, run:
      ```bash
      ./ink-node --version
      ```
      If you see version information, your installation is successful!

      ### (2) Install or Build it yourself

      Alternatively, you can build the node by yourself.
      This can take a while though!

      The build instructions and pre-requisites can be found
      [here](https://github.com/use-ink/ink-node?tab=readme-ov-file#build-locally).
  </TabItem>
    <TabItem value="pop" label="Pop">
       Use the [Pop CLI](https://learn.onpop.io/contracts/welcome/install-pop-cli) for ink! smart contract development with an enhanced developer experience.

       ```bash
       cargo install pop-cli
       ```

       **Pop CLI advantages over `cargo-contract`:**
       - **Automated setup**: Handles all required installations and dependencies for you
       - **Contract templates**: Access to a range of pre-built contract templates
       - **Interactive UI**: Deploy and interact with contracts through an interactive command-line interface
       - **Built-in `ink-node`**: Automatically manages the `ink-node` without manual configuration
       - **Easy local network setup**: Quickly spin up local development networks
       - **Wallet integration**: Seamless wallet connection and management
    </TabItem>
</Tabs>
````

## File: docs/integrations-and-sdks/javascript-typescript/core-libraries.md
````markdown
---
title: Core Libraries
slug: /integrations-and-sdks/javascript-typescript/core-libraries
hide_title: true
---

![Frontend Title Picture](/img/title/frontend.svg)

# Core Libraries

These are the foundational libraries for interacting with ink! contracts from JavaScript and TypeScript applications. Choose the level of abstraction that best fits your project needs.

## Low-Level Libraries

### RPC Interface
- **[RPC Interface](https://wiki.polkadot.network/docs/build-node-interaction)** **(not recommended)**
- Nodes participating in the blockchain network offer a [JSON RPC interface](https://www.jsonrpc.org/) to interact with the blockchain's state and capabilities
- Direct interaction with the blockchain without any abstraction layer
- Requires deep understanding of the underlying protocols

### General Polkadot SDK Libraries

#### papi
- **[`polkadot-api`](https://papi.how/getting-started)** **(currently recommended)**
- Fully-typed TypeScript API supporting general interaction with Polkadot-SDK based blockchains
- Modern, lightweight alternative to `@polkadot/api`
- Excellent TypeScript support and developer experience

#### @polkadot/api
- **[`@polkadot/api`](https://polkadot.js.org/docs/api)** **(not recommended for new projects)**
- Allows for most general interaction with Polkadot-SDK based blockchains from JavaScript
- To interact with smart contracts, use the `pallet-revive` runtime calls
- Legacy library, consider using `polkadot-api` for new projects

## ink!-Specific SDKs

### @polkadot-api/sdk-ink
- **[`@polkadot-api/sdk-ink`](https://papi.how/sdks/ink-sdk)** **(Compatible with ink! v6)**
- PAPI SDK for interacting with ink! smart contracts
- Fully type-safe APIs for:
  - Deploying contracts
  - Dry-running calls
  - Sending messages
  - Estimating gas and storage deposits
  - Decoding events
  - Accessing on-chain storage of contracts

### dedot
- **[`dedot`](https://docs.dedot.dev/ink-smart-contracts/intro)** **(Compatible with ink! v6)**
- Next-gen TypeScript client for Polkadot & Polkadot SDK-based networks
- Fully type-safe APIs for interacting with ink! smart contracts
- Features:
  - Generates TypeScript bindings for contracts
  - Contract deployment and interaction
  - Query and transaction execution
  - Dry runs for validation
  - Event decoding with full type safety

### @polkadot/api-contract
- **[`@polkadot/api-contract`](https://polkadot.js.org/docs/api-contract)** **(Compatible with ink! v6)**
- Abstraction on top of `@polkadot/api` for `pallet-contracts` and `pallet-revive`
- Makes interaction with smart contracts more comfortable and type-safe
- Built on the legacy `@polkadot/api` foundation
````

## File: docs/integrations-and-sdks/javascript-typescript/react.md
````markdown
---
title: React Ecosystem
slug: /integrations-and-sdks/javascript-typescript/react
hide_title: true
---

![Frontend Title Picture](/img/title/frontend.svg)

# React Ecosystem

React is one of the most popular frontend frameworks for building web applications. Here are the tools and libraries specifically designed for building ink! smart contract frontends with React.

## React Hooks and Libraries

### ReactiveDOT
- **[`ReactiveDOT`](https://reactivedot.dev/)** **(Compatible with ink! v6)**
- A reactive library for building Substrate front-ends
- Modern approach to state management for blockchain applications
- Built with TypeScript and excellent developer experience

### useInkathon
- **[`useInkathon`](https://github.com/scio-labs/use-inkathon)** **(not compatible with ink! v6)**
- Hooks library for React with focus on smart-contract interactions
- Built using `@polkadot/api` & `@polkadot/api-contract`
- **Note**: Currently not updated for ink! v6 - consider alternatives for new projects

### typink
- **[`typink`](https://docs.dedot.dev/typink)** **(Compatible with ink! v6)**
- Comprehensive toolkit designed to simplify and accelerate ink! dApp development
- Features:
  - Fully type-safe React hooks for smart contract interactions
  - Built-in CLI for bootstrapping projects
  - Multi-chain support
  - Flexible wallet connector options
  - Seamless developer experience

## Full-Stack Templates

### inkathon
- **[`inkathon`](https://github.com/scio-labs/inkathon)** **(will be compatible with ink! v6 soon)**
- Full-stack web app template using Next.js
- Built on top of `useInkathon`
- **Features**:
  - Complete project setup with best practices
  - Pre-configured development environment
  - Smart contract integration examples
  - Modern UI components and styling

**The fastest way to get up and running with a smart contract and corresponding web app.**
````

## File: docs/integrations-and-sdks/ethereum-compatibility.md
````markdown
---
title: Ethereum Compatibility
hide_title: true
slug: /background/solidity-metamask-compatibility
---

<head>
    <meta name="description" content="Explanation of ink!'s compatibility with Solidity and Ethereum tooling (MetaMask, block explorers, Hardhat, …)." />
    <meta name="keywords" content="Ethereum, MetaMask, Solidity, Hardhat, ink!" />
    <meta property="og:title" content="Solidity & MetaMask Compatibility" />
    <meta property="og:description" content="Explanation of ink!'s compatibility with Solidity and Ethereum tooling (MetaMask, block explorers, Hardhat, …)." />
    <meta property="og:image" content="https://use-ink.com/img/opengraph/solidity-metamask.jpg" />
    <meta property="og:image:width" content="1200" />
    <meta property="og:image:height" content="630" />
    <meta property="og:image:alt" content="Solidity and MetaMask" />
    <meta property="og:image:type" content="image/jpg" />
</head>

![Metadata Title Picture](/img/title/solidity.svg)

First, read our blogpost [ink! speaks Solidity on PolkaVM](https://medium.com/coinsbench/ink-solidity-abi-on-polkavm-c675c854efd3).

With ink! v6, we have introduced an `abi` field in a custom `ink-lang` table 
in the [`package.metadata` table][package-metadata] of a contract's manifest
file (i.e. the `Cargo.toml` file) - [more details here][abi-declaration].
It allows building your contract in Solidity ABI compatibility mode 
when declared as follows:

```toml
[package.metadata.ink-lang]
abi = "sol"
```

The implication of supporting Solidity ABI encoding is that all types used as 
constructor/message argument and return types, and event argument types must 
define a mapping to an equivalent Solidity ABI type.

:::note
This is similar to the requirement to implement [`scale::Encode` and `scale::Decode`][scale-codec]
for Rust types used in the public interfaces of ink!/"native" ABI encoded contracts.
:::

[package-metadata]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table
[abi-declaration]: ../basics/abi/overview.md#declaring-the-abi
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec

## Rust/ink! to Solidity ABI type mapping

This mapping is defined using the [`SolEncode`][sol-encode] and [`SolDecode`][sol-decode] traits,
which are analogs to [`scale::Encode` and `scale::Decode`][scale-codec]
(but for Solidity ABI encoding/decoding).
You won't be able to use Rust types for which no mapping to a Solidity type is defined.
An error about a missing trait implementation for this type will be thrown.

[sol-encode]: https://use-ink.github.io/ink/ink/trait.SolEncode.html
[sol-decode]: https://use-ink.github.io/ink/ink/trait.SolDecode.html

### Default/provided mappings

[`SolEncode`][sol-encode] and [`SolDecode`][sol-decode] are implemented
for the following Rust/ink! primitive types creating a mapping
to the corresponding Solidity ABI types as shown in the table below:

| Rust/ink! type | Solidity ABI type | Notes |
| -------------- | ----------------- | ----- |
| `bool` | `bool` ||
| `iN` for `N ∈ {8,16,32,64,128}` | `intN` | e.g `i8` ↔ `int8` |
| `uN` for `N ∈ {8,16,32,64,128}` | `uintN` | e.g `u8` ↔ `uint8` |
| [`ink::U256`][ink-u256] | `uint256` ||
| `String` | `string` ||
| `Box<str>` | `string` ||
| [`ink::Address`][ink-address] / [`ink::H160`][ink-h160] | `address` | `ink::Address` is a type alias for the `ink::H160` type used for addresses in `pallet-revive` |
| `[T; N]` for `const N: usize` | `T[N]` | e.g. `[i8; 64]` ↔ `int8[64]` |
| `Vec<T>` | `T[]` | e.g. `Vec<i8>` ↔ `int8[]` |
| `Box<[T]>` | `T[]` | e.g. `Box<[i8]>` ↔ `int8[]` |
| [`ink::sol::FixedBytes<N>`][ink-fixed-bytes] for `1 <= N <= 32` | `bytesN` | e.g. `FixedBytes<32>` ↔ `bytes32`, `FixedBytes<N>` is just a newtype wrapper for `[u8; N]` that also implements `From<u8>` |
| [`ink::sol::DynBytes`][ink-dyn-bytes] | `bytes` | `DynBytes` is just a newtype wrapper for `Vec<u8>` that also implements `From<Box<[u8]>>` |
| `(T1, T2, T3, ... T12)` | `(U1, U2, U3, ... U12)` | where `T1` ↔ `U1`, ... `T12` ↔ `U12` e.g. `(bool, u8, Address)` ↔ `(bool, uint8, address)` |
| `Option<T>` | `(bool, T)` | e.g. `Option<u8>` ↔ `(bool, uint8)`|

[ink-u256]: https://use-ink.github.io/ink/ink/struct.U256.html
[ink-address]: https://use-ink.github.io/ink/ink/type.Address.html
[ink-h160]: https://use-ink.github.io/ink/ink/struct.H160.html
[ink-fixed-bytes]: https://use-ink.github.io/ink/ink/sol/struct.FixedBytes.html
[ink-dyn-bytes]: https://use-ink.github.io/ink/ink/sol/struct.DynBytes.html

:::note
Rust's `Option<T>` type doesn't have a **semantically** equivalent Solidity ABI type,
because [Solidity enums][sol-enum] are field-less.

So `Option<T>` is mapped to a tuple representation instead (i.e. `(bool, T)`),
because this representation allows preservation of semantic information in Solidity,
by using the `bool` as a "flag" indicating the variant
(i.e. `false` for `None` and `true` for `Some`) such that:
- `Option::None` is mapped to `(false, <default_value>)`
  where `<default_value>` is the zero bytes only representation of `T`
  (e.g. `0u8` for `u8` or `Vec::new()` for `Vec<T>`)
- `Option::Some(value)` is mapped to `(true, value)`

The resulting type in Solidity can be represented as a struct with a field for the "flag"
and another for the data.

Note that `enum` in Solidity is encoded as `uint8` in [Solidity ABI encoding][sol-abi-types],
while the encoding for `bool` is equivalent to the encoding of `uint8`,
with `true` equivalent to `1` and `false` equivalent to `0`.
Therefore, the `bool` "flag" can be safely interpreted as a `bool` or `enum` (or even `uint8`)
in Solidity code.
:::

[sol-enum]: https://docs.soliditylang.org/en/latest/types.html#enums
[sol-abi-types]: https://docs.soliditylang.org/en/latest/abi-spec.html#mapping-solidity-to-abi-types

[`SolEncode`][sol-encode] is additionally implemented for reference and smart
pointer types below:

| Rust/ink! type | Solidity ABI type | Notes |
| -------------- | ----------------- | ----- |
| `&str`, `&mut str` | `string` ||
| `&T`, `&mut T`, `Box<T>` | `T` | e.g. `&i8 ↔ int8` |
| `&[T]`, `&mut [T]` | `T[]` | e.g. `&[i8]` ↔ `int8[]` |
| [`ink::sol::ByteSlice`][ink-byte-slice] | `bytes` | `ByteSlice` is a just newtype wrapper for `&[u8]` |

[ink-byte-slice]: https://use-ink.github.io/ink/ink/sol/struct.ByteSlice.html

### Handling the `Result<T, E>` type

Rust's `Result<T, E>` type doesn't have a **semantically** equivalent Solidity ABI type,
because [Solidity enums][sol-enum] are field-less, so no composable mapping is provided.

However, `Result<T, E>` types are supported as the return type of messages
and constructors, and they're handled at language level as follows:
- When returning the `Result::Ok` variant, where `T` implements `SolEncode`,
  `T` is encoded as "normal" Solidity ABI return data.
- When returning the `Result::Err` variant, `E` must implement [`SolErrorEncode`][sol-error-encode],
  ink! will set the revert flag in the execution environment,
  and `E` will be encoded as [Solidity revert error data][sol-revert],
  with the error data representation depending on the [`SolErrorEncode`][sol-error-encode] implementation.
- Similarly, for decoding, `T` must implement `SolDecode`,
  while `E` must implement [`SolErrorDecode`][sol-error-decode], and the returned data is decoded as `T`
  (i.e. `Result::Ok`) or `E` (i.e. `Result::Err`) depending on whether
  the revert flag is set (i.e. `E` if the revert flag is set, and `T` otherwise).

The [`SolErrorEncode`][sol-error-encode] and [`SolErrorDecode`][sol-error-decode] traits define 
the highest level interfaces for encoding and decoding an arbitrary Rust/ink! error type as 
Solidity ABI revert error data.

Default implementations for both `SolErrorEncode` and `SolErrorDecode` are provided for unit
(i.e. `()`), and these are equivalent to reverting with no error data in Solidity
(i.e. empty output buffer).

For arbitrary custom error types, `Derive` macros are provided for automatically generating
implementations of `SolErrorEncode` and `SolErrorDecode` for structs and enums for which
all fields (if any) implement `SolEncode` and `SolDecode`.
- For structs, the struct name is used as the name of the [Solidity custom error][sol-custom-error]
  while the fields (if any) are the parameters
- For enums, each variant is its own [Solidity custom error][sol-custom-error],
  with the variant name being the custom error name, and the fields (if any) being the parameters

For convenience, the [`#[ink::error]`][ink-error] attribute macro is also provided for automatically deriving the following traits:
- [`SolErrorEncode`][sol-error-encode]: for encoding a custom type as revert error data
- [`SolErrorDecode`][sol-error-decode]: for decoding revert error data into a custom type
- `SolErrorMetadata`: for generating [Solidity ABI metadata][sol-abi-json] (gated behind the `std` feature)

[sol-error-encode]: https://use-ink.github.io/ink/ink/sol/trait.SolErrorEncode.html
[sol-error-decode]: https://use-ink.github.io/ink/ink/sol/trait.SolErrorDecode.html
[sol-revert]: https://docs.soliditylang.org/en/latest/control-structures.html#revert
[sol-custom-error]: https://soliditylang.org/blog/2021/04/21/custom-errors/
[ink-error]: ../macros-attributes/error.md
[sol-abi-json]: https://docs.soliditylang.org/en/latest/abi-spec.html#json

```rust
// Represented as a Solidity custom error with no parameters
#[ink::error]
struct UnitError;

// Represented as a Solidity custom error with parameters
#[ink::error]
struct ErrorWithParams(bool, u8, String);

// Represented as a Solidity custom error with named parameters
#[ink::error]
struct ErrorWithNamedParams {
    status: bool,
    count: u8,
    reason: String,
}

// Represented as multiple Solidity custom errors
// (i.e. each variant represents a Solidity custom error)
#[ink::error]
enum MultipleErrors {
    UnitError,
    ErrorWithParams(bool, u8, String),
    ErrorWithNamedParams {
        status: bool,
        count: u8,
        reason: String,
    }
}
```

:::note
In ["ink" and "all" ABI mode][abi-declaration], the [`#[ink::error]`][ink-error] attribute macro
will also derive implementations of the [`scale::Encode` and `scale::Decode`][scale-codec] traits.
:::

:::note
For other [Solidity `revert`][sol-revert] error data representations (e.g. legacy revert strings),
you can implement [`SolErrorEncode`][sol-error-encode] and [`SolErrorDecode`][sol-error-decode]
manually to match those representations.
:::

:::note
Rust's [coherence/orphan rules][rust-coherence] mean that you can only implement the
`SolErrorEncode` and `SolErrorDecode` traits for local types.
:::

### Mappings for arbitrary custom types

For arbitrary custom types, `Derive` macros are provided for automatically generating
implementations of [`SolEncode`][sol-encode] and [`SolDecode`][sol-decode]
- For structs where all fields (if any) implement `SolEncode` and `SolDecode` respectively,
  including support for generic types
- For enums where all variants are either [unit-only][enum-unit-only] or [field-less][enum-field-less]
  (see notes below for the rationale for this limitation)

[enum-unit-only]: https://doc.rust-lang.org/reference/items/enumerations.html#r-items.enum.unit-only
[enum-field-less]: https://doc.rust-lang.org/reference/items/enumerations.html#r-items.enum.fieldless

```rust
use ink_macro::{SolDecode, SolEncode};

#[derive(SolDecode, SolEncode)]
struct UnitStruct;

#[derive(SolDecode, SolEncode)]
struct TupleStruct(bool, u8, String);

#[derive(SolDecode, SolEncode)]
struct FieldStruct {
    status: bool,
    count: u8,
    reason: String,
}

#[derive(SolDecode, SolEncode)]
enum SimpleEnum {
    One,
    Two,
    Three,
}

#[derive(SolDecode, SolEncode)]
struct NestedStruct {
    unit: UnitStruct,
    tuple: TupleStruct,
    fields: FieldStruct,
    enumerate: SimpleEnum,
}

#[derive(SolDecode, SolEncode)]
struct GenericStruct<T> {
    concrete: u8,
    generic: T,
}
```

:::note
Solidity has no **semantic** equivalent for Rust/ink! enums with fields
(i.e. [Solidity enums][sol-enum] can only express the equivalent of Rust [unit-only][enum-unit-only]
or [field-less][enum-field-less] enums).

So mapping complex Rust enums (i.e. enums with fields) to "equivalent" Solidity representations
typically yields complex structures based on tuples (at [Solidity ABI encoding][sol-abi-types] level)
and structs (at Solidity language level).

Because of this, the `Derive` macros for `SolEncode` and `SolDecode` do NOT generate implementations
for enums with fields.

However, you can define custom representations for these types by manually implementing
the [`SolEncode`][sol-encode] and [`SolDecode`][sol-decode]
(see linked rustdoc for instructions).
:::

:::note
Rust's [coherence/orphan rules][rust-coherence] mean that you can
only implement the [`SolEncode`][sol-encode] and [`SolDecode`][sol-decode]
traits for local types.
:::

[rust-coherence]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementation-coherence

## Solidity Tooling

You can deploy and interact with `ink!` smart contracts using popular Solidity tools like Hardhat and Foundry thanks to the Solidity-compatible ABI output.

Full Tutorial: [Use Solidity Tooling with ink! Contracts](/tutorials/ethereum-compatibility/overview)
````

## File: docs/integrations-and-sdks/other-languages.md
````markdown
---
title: Other Languages
slug: /integrations-and-sdks/other-languages
hide_title: true
---

![Frontend Title Picture](/img/title/frontend.svg)

# Other Languages

While JavaScript and TypeScript dominate web development, smart contract frontends can be built with various technologies. Here are libraries and SDKs for other platforms and languages.

## Mobile Development

### iOS
- **[novasamatech/substrate-sdk-ios](https://github.com/novasamatech/substrate-sdk-ios)**
- Low-level generic iOS SDK for Substrate-based blockchains
- Written in Swift
- Provides foundation for building native iOS apps that interact with Polkadot networks
- Suitable for wallet applications and dApps requiring native iOS performance

### Android
- **[novasamatech/substrate-sdk-android](https://github.com/novasamatech/substrate-sdk-android)**
- Low-level Android SDK for Substrate-based blockchains
- Written in Kotlin/Java
- Enables native Android applications to interact with Polkadot networks
- Ideal for mobile wallets and native Android dApps

## Backend and Server-Side

### Rust
- **[paritytech/subxt](https://github.com/paritytech/subxt)**
- Rust library to submit extrinsics (transactions) to a Substrate node via RPC
- **Perfect for**:
  - Backend services that interact with smart contracts
  - CLI tools for contract management
  - Server-side automation and monitoring
  - Integration testing frameworks

### Python
- **[polkascan/py-substrate-interface](https://github.com/polkascan/py-substrate-interface)**
- Python library for interfacing with Substrate nodes
- **Use cases**:
  - Data analysis and blockchain monitoring
  - Backend automation scripts
  - Integration with existing Python ecosystems
  - Rapid prototyping and testing
````

## File: docs/integrations-and-sdks/overview.md
````markdown
---
title: Overview
slug: /integrations-and-sdks/overview
hide_title: true
---

![Frontend Title Picture](../../static/img/title/frontend.svg)

# Overview

Now after you [wrote](../getting-started/creating.md), [compiled](../getting-started/compiling.md) and [deployed your smart contract](../getting-started/deploying.md), it is time to craft a user experience around it.

This experience can take many shapes from mobile app to interactive terminal applications. In this section we are focusing on the most prominent shape in web3 right now, web apps.

Although we love Rust, the native language of the web is JavaScript. Thereby naturally the best tools for creating web experiences are available for JavaScript. Hence, the tools for smart contract interaction with JavaScript are the most advanced as well. To be precise all JavaScript tools mentioned here, actually leverage TypeScript to offer a JavaScript and a typesafe TypeScript experience.

## What's in this Section

This section covers:

- **[JavaScript/TypeScript Libraries](./javascript-typescript/core-libraries.md)**: Core libraries and tools for JavaScript/TypeScript development
- **[React Ecosystem](./javascript-typescript/react.md)**: React-specific frameworks and hooks for ink! integration
- **[Other Languages](./other-languages.md)**: SDKs and libraries for Python, Rust, mobile development, and more
- **[Ethereum Compatibility](./ethereum-compatibility.md)**: Use Solidity ABI compatibility mode to deploy and interact with ink! contracts using popular Ethereum tools like MetaMask, Hardhat, and Foundry
````

## File: docs/intro/intro.mdx
````
---
title: Introduction
hide_title: true
slug: /
---

import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/title/ink! 6.0.svg')} title="The ink! 6.0 smart contracts toolkit release" style={{ marginBottom: 10 }} />

## What is ink!?

ink! is a programming language for writing smart contracts that combines the power and safety of Rust with blockchain development.

Here's what makes ink! special:

**Built on Rust**: ink! takes the popular Rust programming language and adds everything you need for smart contract development. You get all of Rust's safety features like memory safety and type safety, plus access to the vast Rust ecosystem.

**Smart Contract Ready**: While ink! uses Rust as its foundation, it's specifically designed for smart contracts. This means:
- Special annotations and macros are provided for smart contract needs
- Built-in support for storage, events, and contract interactions

**Simple but Powerful**: ink! uses special `#[ink(...)]` attribute macros to turn your Rust code into smart contracts. These macros tell ink! what different parts of your code represent; like storage, functions that can be called, or events that can be emitted.

**Compile to RISC-V**: Your ink! contracts compile to RISC-V bytecode that runs efficiently on blockchains, giving you both performance and compatibility.

## What can you do with it?

ink! opens up a world of possibilities for blockchain development across the Polkadot ecosystem:

### Build Smart Contracts for Polkadot Blockchains

With ink!, you can write smart contracts that run on any blockchain built with the Polkadot SDK that includes the `pallet-revive` module. This includes many parachains and standalone chains in the Polkadot ecosystem.

- **DeFi Applications**: Build decentralized exchanges, lending protocols, and other financial applications

- **NFT Platforms**: Create marketplaces, games, and digital collectible platforms  

- **Cross-Chain Applications**: Take advantage of Polkadot's interoperability to build applications that work across multiple blockchains

- **Utility Contracts**: From simple storage contracts to complex business logic, ink! can handle it all

### Flexible Development Paths

ink! provides different approaches depending on your needs:

- **Prototype Quickly**: Start with a smart contract to test your idea and get user feedback
- **Enhanced Chain Features**: Use precompiles to access special blockchain functionality beyond basic smart contracts
- **Scale to Parachains**: Later migrate successful contracts to dedicated parachains for better performance and lower costs

### Composability

One of ink!'s unique advantages is its compatibility with Solidity. This means:
- Solidity developers can call ink! contracts seamlessly
- You can use existing Ethereum tools and frameworks
- Easy migration between different blockchain ecosystems

Want to learn more about ink!'s relationship with the Polkadot ecosystem and its various use cases? Check out our detailed guide on [Polkadot SDK and ink!](../background/polkadot-sdk.md).

Ready to get started? Head to our [Getting Started](../getting-started/setup.md) guide to begin building your first ink! smart contract.
````

## File: docs/intro/overview.md
````markdown
---
title: Overview
hide_title: true
slug: /overview
---

import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/title/ink! 6.0.svg')} title="The ink! 6.0 smart contracts toolkit release" style={{ marginBottom: 10 }} />

Welcome to the ink! documentation, the Rust-based smart contract language for the Polkadot ecosystem. This documentation will take you from your first "Hello, World!" contract to building sophisticated decentralized applications.

## Overview

### **[Getting Started](../getting-started/creating.md)**
Begin your ink! journey with setup instructions, creating your first contract, and deploying it to a blockchain. Perfect for newcomers to both ink! and smart contract development.

### **[Basics](../basics/contract-template.md)**
Master the fundamental concepts of ink! development including storage, contract interactions, events, and the ABI system that enables interoperability with other languages like Solidity.

### **[Testing](../testing/overview.md)**
Learn comprehensive testing strategies from unit tests to end-to-end testing, including working with testing tools like DRink! for robust contract development.

### **[Debugging](../debugging/overview.md)**
Discover tools and techniques for debugging your contracts, from event logging to tracing execution and using development tools.

### **[Macros & Attributes](../macros-attributes/overview.md)**
Deep dive into ink!'s powerful macro system that transforms your Rust code into smart contracts, including storage annotations, message definitions, and event handling.

### **[Storage & Data Structures](../datastructures/overview.md)**
Understand how to efficiently store and manage data in your contracts, from simple values to complex mappings and custom data structures.

### **[Linter](../linter/overview.md)**
Utilize ink!'s built-in security linter to identify common smart contract vulnerabilities and ensure your code follows best practices.

### **[Integrations and SDKs](../integrations-and-sdks/overview.md)**
Connect your contracts to web applications using TypeScript/JavaScript libraries, React hooks, Solidity Tooling, and various SDK options for building complete dApps.

### **[Technical Background](../background/polkadot-sdk.md)**
Understand the deeper technical aspects including why Rust and RISC-V were chosen, how ink! compares to other smart contract languages, and when to choose smart contracts vs. parachains.
````

## File: docs/intro/tutorials-examples.md
````markdown
---
title: Tutorials and Examples
slug: /getting-started/tutorials-and-examples
hide_title: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Heart Title Picture](/img/title/heart.svg)

# Tutorials and Examples

## Tutorials

Ready to dive deeper into ink! development? Check out our [tutorials](/tutorials/overview) that will guide you through building real-world decentralised applications step by step.

### Contribute a Tutorial

Have you built something awesome with ink!? We'd love to feature your tutorial! 

**Help the community learn by contributing your own tutorial.** Whether it's a unique use case, an innovative pattern, or a step-by-step guide for beginners, your contribution makes a difference.

[Learn how to contribute tutorials →](/tutorials/guide)

## Smart Contract Examples

Explore ready-to-use [smart contract examples](https://github.com/use-ink/ink-examples) to understand different patterns and use cases:

<div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/flipper"><img src={useBaseUrl('/img/icons/flipper.svg')} width="100" /></a>
        <p class="mb-0 text-center">
            Our "Hello, World!".<br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/flipper">» view example</a>
        </p>
    </div>
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/erc20"><img src={useBaseUrl('/img/icons/erc20.svg')} width="100" /></a>
        <p class="text-center text-red-500">
            An ERC-20 implementation.<br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/erc20">» view example</a>
        </p>
    </div>
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/erc721"><img src={useBaseUrl('/img/icons/nft.svg')} width="100" /></a>
        <p class="text-center">
            <a href="https://github.com/use-ink/ink-examples/tree/main/erc721">» view ERC-721</a>
            <br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/erc1155">» view ERC-1155</a>
        </p>
    </div>
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/upgradeable-contracts"><img src={useBaseUrl('/img/icons/upgradable.svg')} width="100" /></a>
        <p class="text-center">
            An upgradeable contract.<br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/upgradeable-contracts">» view example</a>
        </p>
    </div>
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/multisig"><img src={useBaseUrl('/img/icons/multisig.svg')} width="100" /></a>
        <p class="text-center">
            A multi-signature wallet.<br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/multisig">» view example</a>
        </p>
    </div>
    <div class="bubble-box [&_p]:!mb-0">
        <a href="https://github.com/use-ink/ink-examples/tree/main/rand-extension"><img src={useBaseUrl('/img/icons/rand-extension.svg')} width="100" /></a>
        <p class="text-center">
            Allow runtime access.<br/>
            <a href="https://github.com/use-ink/ink-examples/tree/main/rand-extension">» view example</a>
        </p>
    </div>
</div>
````

## File: docs/intro/where-to-deploy.md
````markdown
---
title: Where to Deploy
slug: /where-to-deploy
hide_title: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Rocket Title Picture](/img/title/rocket.svg)

# Where to Deploy Your ink! Contracts

Ready to deploy your ink! smart contracts? You have two main options depending on your needs: local development or live testnet deployment.

## Local Development

Perfect for initial development and testing, check out [deploying your first contract](./../getting-started/deploying.md).

## PassetHub (Testnet)

PassetHub (ParaID: 1111, RPC: wss://passet-hub-paseo.ibp.network) is a live testnet where you can deploy and test your contracts publicly.

Make sure you have a Polkadot account, check out the [guide](https://support.polkadot.network/support/solutions/articles/65000098878-how-to-create-a-dot-account) or [video](https://www.youtube.com/watch?v=DNU0p5G0Gqc) on how to do this.

**Getting Started:**
1. **Get PAS Tokens**: Use the [Paseo Faucet](https://faucet.polkadot.io/?parachain=1000)
2. **Developer Console**: https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fasset-hub-paseo#/explorer
3. **RPC URL**: `wss://sys.ibp.network/asset-hub-paseo`

### Ready to deploy

Check out how to deploy your contract [here](../getting-started/deploying.md).
````

## File: docs/linter/rules/no_main.md
````markdown
---
title: no_main
hide_title: true
description: no_main lint documentation
---
# no_main
## What it does
Checks if a contract is annotated with the `no_main` inner attribute.

## Why is this necessary?
Contracts must be annotated with `no_main` inner attribute when compiled for on-chain
execution.

## Example

```rust
// Bad: Contract does not contain the `no_main` attribute,
// so it cannot be compiled to Wasm
#![cfg_attr(not(feature = "std"), no_std)]
#[ink::contract]
mod my_contract { /* ... */ }
```

Use instead:

```rust
#![cfg_attr(not(feature = "std"), no_std, no_main)]
#[ink::contract]
mod my_contract { /* ... */ }
```
````

## File: docs/linter/rules/non_fallible_api.md
````markdown
---
title: non_fallible_api
hide_title: true
description: non_fallible_api lint documentation
---
# non_fallible_api
## What it does

The lint detects potentially unsafe uses of methods for which there are safer alternatives.

## Why is this bad?

In some standard collections in ink!, there are two types of implementations: non-fallible
(e.g. `get`) and fallible (e.g. `try_get`). Fallible alternatives are considered safer,
as they perform additional checks for incorrect input parameters and return `Result::Err`
when they are used improperly. On the other hand, non-fallible methods do not provide these
checks and will panic on incorrect input, placing the responsibility on the user to
implement these checks.

For more context, see: [ink#1910](https://github.com/use-ink/ink/pull/1910).

## Example

Consider the contract that has the following `Mapping` field:

```rust
#[ink(storage)]
pub struct Example { map: Mapping<String, AccountId> }
```

The following usage of the non-fallible API is unsafe:

```rust
// Bad: can panic if `input_string` doesn't fit into the static buffer
self.map.insert(input_string, &self.sender);
```

It could be replaced with the fallible version of `Mapping::insert`:

```rust
// Good: returns Result::Err on incorrect input
self.map.try_insert(input_string, &self.sender);
```

Otherwise, the user could explicitly check the encoded size of the argument in their code:

```rust
// Good: explicitly checked encoded size of the input
if String::encoded_size(&input_string) < ink_env::BUFFER_SIZE {
  self.map.insert(input_string, &self.sender);
}
```
````

## File: docs/linter/rules/primitive_topic.md
````markdown
---
title: primitive_topic
hide_title: true
description: primitive_topic lint documentation
---
# primitive_topic
## What it does
Checks for ink! contracts that use the
[`#[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.

## Why is this bad?
It typically doesn't make sense to annotate types like `u32` or `i32` as a topic, if those
fields can take continuous values that could be anywhere between `::MIN` and `::MAX`. An
example of a case where it doesn't make sense at all to have a topic on the storage field
is something like `value: Balance` in the examle below.

## Example
```rust
// Bad
// It typically makes no sense to filter `Balance`, since its value may varies from `::MAX`
// to `::MIN`.
#[ink(event)]
pub struct Transaction {
    #[ink(topic)]
    src: Option<AccountId>,
    #[ink(topic)]
    dst: Option<AccountId>,
    #[ink(topic)]
    value: Balance,
}
```

Use instead:

```rust
// Good
// Filtering transactions based on source and destination addresses.
#[ink(event)]
pub struct Transaction {
    #[ink(topic)]
    src: Option<AccountId>,
    #[ink(topic)]
    dst: Option<AccountId>,
    value: Balance,
}
```
````

## File: docs/linter/rules/storage_never_freed.md
````markdown
---
title: storage_never_freed
hide_title: true
description: storage_never_freed lint documentation
---
# storage_never_freed
## What it does
This lint ensures that for every storage field with a collection type, when there is an
operation to insert new elements, there's also an operation for removing elements.

## Why is this bad?
When a user executes a contract function that writes to storage, they have to put a
deposit down for the amount of storage space used. Whoever frees up that storage at some
later point gets the deposit back. Therefore, it is always a good idea to make it possible
for users to free up their storage space.

## Example
In the following example there is a storage field with the `Mapping` type that has an
function that inserts new elements:

```rust
#[ink(storage)]
pub struct Transaction {
    values: Mapping<AccountId, AccountId>,
}

fn add_value(&mut self, k: &AccountId, v: &AccountId) {
    // ...
    self.values.insert(k, v);
    // ...
}
```

But, ideally, there also should be a function that allows the user to remove elements from
the Mapping freeing storage space:

```rust
fn del_value(&mut self, k: &AccountId) {
    // ...
    self.values.remove(k);
    // ...
}
```
````

## File: docs/linter/rules/strict_balance_equality.md
````markdown
---
title: strict_balance_equality
hide_title: true
description: strict_balance_equality lint documentation
---
# strict_balance_equality
## What it does
Looks for strict equalities with balance in ink! contracts.

## Why is this bad?
The problem with strict balance equality is that it is always possible to forcibly send
tokens to a contract. For example, using
[`terminate_contract`](https://use-ink.github.io/ink/ink_env/fn.terminate_contract.html).
In such a case, the condition involving the contract balance will work incorrectly, what
may lead to security issues, including DoS attacks and draining contract's gas.

## Known problems
There are many ways to implement balance comparison in ink! contracts. This lint is not
trying to be exhaustive. Instead, it addresses the most common cases that may occur in
real-world contracts and focuses on precision and lack of false positives.

## Example
Assume, there is an attacker contract that sends all its funds to the target contract when
terminated:

```rust
#[ink::contract]
pub mod attacker {
  // ...
  #[ink(message)]
  pub fn attack(&mut self, target: &AccountId) {
      self.env().terminate_contract(target);
  }
}
```

If the target contains a condition with strict balance equality, this may be manipulated by
the attacker:

```rust
#[ink::contract]
pub mod target {
  // ...
  #[ink(message)]
  pub fn do_something(&mut self) {
      if self.env().balance() != 100 { // Bad: Strict balance equality
          // ... some logic
      }
  }
}
```

This could be mitigated using non-strict equality operators in the condition with the
balance:

```rust
#[ink::contract]
pub mod target {
  // ...
  #[ink(message)]
  pub fn do_something(&mut self) {
      if self.env().balance() < 100 { // Good: Non-strict equality
          // ... some logic
      }
  }
}
```
````

## File: docs/linter/overview.md
````markdown
---
title: Overview
hide_title: true
description: An overview of ink! linter
---

![Text/linter Title Picture](/img/title/text/linter.svg)

# Overview

# Overview
ink! includes the linter — a security tool designed to identify typical security issues in smart contracts. The linter is meant to seamlessly fit into the smart contracts development process, ensuring that contracts are thoroughly checked during the build phase before they are deployed to the blockchain.

## Installation
Our linter requires two crates and a fixed Rust toolchain version. You can use
these commands to install the required dependencies:

```bash
export TOOLCHAIN_VERSION=nightly-2025-05-14
rustup install $TOOLCHAIN_VERSION
rustup component add rust-src --toolchain $TOOLCHAIN_VERSION
rustup run $TOOLCHAIN_VERSION cargo install cargo-dylint dylint-link
```

Note that the linter requires this specific version of the toolchain, 
since it uses the internal Rust compiler API. That's also why we require
nightly for the linter, these internal crates are not accessible on stable.

## Usage
The linter operates via `cargo-contract`.

To perform a build with extra code analysis (i.e. the ink! linting rules), run the
following command within the contract directory:

```bash
cargo contract build --lint
```

This command compiles the contract and applies all linting checks. You can find the complete list of lints along with their descriptions in this documentation.

## Suppressing linter warnings
To suppress linter warnings in your ink! smart-contract, you can use `allow` attributes. You can apply these attributes either to a particular piece of code or globally.

Here's how to suppress the specific linter warnings:

```rust
// Suppressing the `primitive_topic` lint globally
#[cfg_attr(dylint_lib = "ink_linting", allow(primitive_topic))]

#[ink(message)]
pub fn test(&mut self) {
    // Suppressing the `strict_balance_equality` lint in a specific place
    #[cfg_attr(dylint_lib = "ink_linting", allow(strict_balance_equality))]
    if self.env().balance() == 10 { /* ... */ }
}
```
````

## File: docs/macros-attributes/anonymous.md
````markdown
---
title: "#[ink(anonymous)]"
slug: /macros-attributes/anonymous
hide_title: true
---

![Text/anon Title Picture](/img/title/text/anon.svg)

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,
}
```
````

## File: docs/macros-attributes/constructor.md
````markdown
---
title: "#[ink(constructor)]"
slug: /macros-attributes/constructor
hide_title: true
---

![Text/constructor Title Picture](/img/title/text/constructor.svg)

Applicable to a method.

Flags a method (or multiple methods) for the ink! storage struct as constructor making it available to the API for instantiating the contract.

There must be at least one `#[ink(constructor)]` defined method.

Methods flagged with `#[ink(constructor)]` are special in that they are dispatchable
upon contract instantiation. A contract may define multiple such constructors which
allow users of the contract to instantiate a contract in multiple different ways.


## Example

```rust
#[ink::contract]
mod erc20 {
    #[ink(storage)]
    pub struct Erc20 { ... }

    impl Erc20 {
        #[ink(constructor)]
        pub fn new(initial_supply: Balance) -> Self { .. }

        #[ink(constructor)]
        pub fn total_supply(&self) -> Balance { .. }

        // etc.
    }
}
```
````

## File: docs/macros-attributes/contract_ref.md
````markdown
---
title: "#[ink::contract_ref]"
hide_title: true
slug: /macros-attributes/contract_ref
---

![Text/contract_ref Title Picture](/img/title/text/contract_ref.svg)

Defines the interface of a "callee" contract and generates a wrapper type which can be
used for interacting with the contract.

The interface is defined using a trait, and the macro generates a native Rust type
(a contract reference) that implements this trait, so it can be used in any Rust
context that expects types.

:::note
A key difference between an `#[ink::contract_ref]` and [`#[ink::trait_definition]`][trait-def]
is that a `#[ink::contract_ref]` dynamically declares the interface of
an on-chain/"callee" contract with a possibly different ABI from the root/"caller" contract,
while a [`#[ink::trait_definition]`][trait-def] is an interface that defines shared behavior
to be implemented (or reused/inherited) by the root contract, where the ABI is
inferred from the root contract.
:::

[trait-def]: ../basics/trait-definitions.md

## Example

### Definition

```rust
#[ink::contract_ref(abi = "sol")]
pub trait Erc20 {
    /// Returns the total supply of the ERC-20 smart contract.
    #[ink(message)]
    fn total_supply(&self) -> ink::U256;

    /// Transfers balance from the caller to the given address.
    #[ink(message)]
    fn transfer(&mut self, amount: ink::U256, to: ink::Address) -> bool;

    // etc.
}
```

### Usage

Given the above interface, you can use the generated contract reference in a
"caller" contract as shown below:

```rust
#[ink::contract]
mod erc20_caller {
    use ink::U256;

    #[ink(storage)]
    pub struct Erc20Caller {
        callee: ink::Address,
    }

    impl Erc20Caller {
        #[ink(constructor)]
        pub fn new(addr: ink::Address) -> Self {
            Self { callee: addr }
        }

        #[ink(message)]
        pub fn call_erc20(&self) {
            // Calls the ERC20 contract using the contract ref generated above.
            let total = Erc20Ref::from(self.callee).total_supply();

            // Do some fun stuff!
        }
    }
}
```

## Header Arguments

The `#[ink::contract_ref]` macro can be provided with some additional
comma-separated header arguments:

### `abi: String`

Specifies the ABI (Application Binary Interface) of the "callee" contract.

**Usage Example:**
```rust
#[ink::contract_ref(abi = "sol")]
pub trait Callee {
  #[ink(message)]
  fn message1(&self);

  #[ink(message, selector = 42)]
  fn message2(&self);
}
```

**Default value:** Empty.

**Allowed values:** `"ink"`, `"sol"`

**NOTE**: When no value is provided, the generated contract reference will use the
ABI of the  root contract (i.e "ink" in ["ink" and "all" ABI mode][abi-mode]
and "sol" in ["sol" ABI mode][abi-mode]).

[abi-mode]: ../basics/abi/overview.md

### `env: impl Environment`

Specifies the environment to use for the generated contract reference.

This should be the same environment used by the root contract (if any).

The environment must implement the `Environment` (defined in `ink_env`)
trait and provides all the necessary fundamental type definitions for `Balance`,
`AccountId` etc.

**Usage Example:**

Given a custom `Environment` implementation:
```rust
#[derive(Clone)]
pub struct MyEnvironment;

impl ink_env::Environment for MyEnvironment {
  const NATIVE_TO_ETH_RATIO: u32 = 100_000_000;
  type AccountId = [u8; 16];
  type Balance = u128;
  type Hash = [u8; 32];
  type Timestamp = u64;
  type BlockNumber = u32;
  type EventRecord = ();
}
```
A user might define an interface (and generate a contract reference) that uses the
above custom `Environment` implementation as demonstrated below:
```rust
#[ink::contract_ref(env = MyEnvironment)]
pub trait Callee {
  #[ink(message)]
  fn message(&self);

  // ...
}
```

**Default value:** `DefaultEnvironment` defined in `ink_env` crate.
````

## File: docs/macros-attributes/contract.md
````markdown
---
title: "#[ink::contract]"
hide_title: true
slug: /macros-attributes/contract
---

![Text/contract Title Picture](/img/title/text/contract.svg)

# \#[ink::contract]

The `#[ink::contract]` macro is the entry point for writing ink! smart contracts.

If you are a beginner trying to learn ink! we recommend starting
from the [Getting Started](../getting-started/setup.md) page of this documentation.

## Description

The macro does analysis on the provided smart contract code and generates
proper code.

## Usage

### Header Arguments

The `#[ink::contract]` macro can be provided with some additional comma-separated
header arguments:

### `keep_attr: String`

Tells the ink! code generator which attributes should be passed to call builders.
Call builders are used for making cross-contract calls and are automatically
generated for contracts.

**Usage Example:**

```rust
#[ink::contract(keep_attr = "foo, bar")]
mod my_contract {
    #[ink(storage)]
    pub struct MyStorage;
    
    impl MyStorage {
        #[ink(constructor)]
        #[bar]
        pub fn construct() -> Self { MyStorage {} }
        
        #[ink(message)]
        #[foo]
        pub fn message(&self) {}
    }
    
    // ...
}
```

**Allowed attributes by default:** `cfg`, `cfg_attr`, `allow`, `warn`, `deny`,
`forbid`, `deprecated`, `must_use`, `doc`, `rustfmt`.

### `env: impl Environment`

Tells the ink! code generator which environment to use for the ink! smart contract.
The environment must implement the `Environment` (defined in `ink_env`) trait and provides
all the necessary fundamental type definitions for `Balance`, `AccountId` etc.

When using a custom `Environment` implementation for a smart contract all types
that it exposes to the ink! smart contract and the mirrored types used in the runtime
must be aligned with respect to SCALE encoding and semantics.

**Usage Example:**

Given a custom `Environment` implementation:
```rust
pub struct MyEnvironment;

impl ink::env::Environment for MyEnvironment {
    const MAX_EVENT_TOPICS: usize = 3;

    type AccountId = u64;
    type Balance = u128;
    type Hash = [u8; 32];
    type Timestamp = u64;
    type BlockNumber = u32;
    type ChainExtension = ::ink::env::NoChainExtension;
}
```
A user might implement their ink! smart contract using the above custom `Environment`
implementation as demonstrated below:

```rust
#[ink::contract(env = MyEnvironment)]
mod my_contract {
    pub struct MyEnvironment;

    impl ink::env::Environment for MyEnvironment {
        const MAX_EVENT_TOPICS: usize = 3;
        type AccountId = u64;
        type Balance = u128;
        type Hash = [u8; 32];
        type Timestamp = u64;
        type BlockNumber = u32;
        type ChainExtension = ::ink::env::NoChainExtension;
    }

    #[ink(storage)]
    pub struct MyStorage;

    impl MyStorage {
        #[ink(constructor)]
        pub fn construct() -> Self { MyStorage {} }

        #[ink(message)]
        pub fn message(&self) {}
    }
    // ...
}
```

**Default value:** `DefaultEnvironment` defined in `ink_env` crate.

## Analysis

The `#[ink::contract]` macro fully analyses its input smart contract
against invalid arguments and structure.

Some example rules include but are not limited to:

- There must be exactly one `#[ink(storage)]` struct.

     This struct defines the layout of the storage that the ink! smart contract operates on.
     The user is able to use a variety of built-in facilities, combine them in various ways
     or even provide their own implementations of storage data structures.

     For more information visit the `ink_storage` crate documentation.

     **Example:**

     ```rust
     #[ink::contract]
     mod flipper {
         #[ink(storage)]
         pub struct Flipper {
             value: bool,
         }

         impl Flipper {
             #[ink(constructor)]
             pub fn construct() -> Self { Flipper { value: false } }

             #[ink(message)]
             pub fn message(&self) {}
         }
     }
     ```

- There must be at least one `#[ink(constructor)]` defined method.

     Methods flagged with `#[ink(constructor)]` are special in that they are dispatchable
     upon contract instantiation. A contract may define multiple such constructors which
     allow users of the contract to instantiate a contract in multiple different ways.

     **Example:**

     Given the `Flipper` contract definition above we add an `#[ink(constructor)]`
     as follows:

     ```rust
     #[ink::contract]
     mod flipper {
         #[ink(storage)]
         pub struct Flipper {
             value: bool,
         }

         impl Flipper {
             #[ink(constructor)]
             pub fn new(initial_value: bool) -> Self {
                 Flipper { value: false }
             }

             #[ink(message)]
             pub fn message(&self) {}
         }
     }
     ```

- There must be at least one `#[ink(message)]` defined method.

     Methods flagged with `#[ink(message)]` are special in that they are dispatchable
     upon contract invocation. The set of ink! messages defined for an ink! smart contract
     define its API surface with which users are allowed to interact.

     An ink! smart contract can have multiple such ink! messages defined.

     **Note:**

     - An ink! message with a `&self` receiver may only read state whereas an ink! message
       with a `&mut self` receiver may modify state.

     **Example:**

     Given the `Flipper` contract definition above we add some `#[ink(message)]` definitions
     as follows:

     ```rust
     #[ink::contract]
     mod flipper {
         #[ink(storage)]
         pub struct Flipper {
             value: bool,
         }

         impl Flipper {
             #[ink(constructor)]
             pub fn new(initial_value: bool) -> Self {
                 Flipper { value: false }
             }

             /// Flips the current value.
             #[ink(message)]
             pub fn flip(&mut self) {
                 self.value = !self.value;
             }

             /// Returns the current value.
             #[ink(message)]
             pub fn get(&self) -> bool {
                 self.value
             }
         }
     }
     ```

     **Payable Messages:**

     An ink! message by default will reject calls that additional fund the smart contract.
     Authors of ink! smart contracts can make an ink! message payable by adding the `payable`
     flag to it. An example below:

     Note that payable ink! messages inherently modify the blockchain state, 
     and therefore must have a `&mut self` receiver.

     Note that ink! constructors are always implicitly payable and thus cannot be flagged
     as such.

     ```rust
     #[ink::contract]
     mod flipper {
         #[ink(storage)]
         pub struct Flipper {
             value: bool,
         }

         impl Flipper {
             #[ink(constructor)]
             pub fn new(initial_value: bool) -> Self {
                 Flipper { value: false }
             }

             /// Flips the current value.
             #[ink(message)]
             #[ink(payable)] // You can either specify payable out-of-line.
             pub fn flip(&mut self) {
                 self.value = !self.value;
             }

             /// Flips the current value.
             #[ink(message, payable)] // ...or specify payable inline.
             pub fn flip_2(&mut self) {
                 self.value = !self.value;
             }

             /// Returns the current value.
             #[ink(message)]
             pub fn get(&self) -> bool {
                 self.value
             }
         }
     }
     ```

     **Controlling the messages selector:**

     Every ink! message and ink! constructor has a unique selector with which the
     message or constructor can be uniquely identified within the ink! smart contract.
     These selectors are mainly used to drive the contract's dispatch upon calling it.

     An ink! smart contract author can control the selector of an ink! message or ink!
     constructor using the `selector` flag. An example is shown below:

     ```rust
     #[ink::contract]
     mod flipper {
         #[ink(storage)]
         pub struct Flipper {
             value: bool,
         }

         impl Flipper {
             #[ink(constructor)]
             #[ink(selector = "0xDEADBEEF")] // Works on constructors as well.
             pub fn new(initial_value: bool) -> Self {
                 Flipper { value: false }
             }

             /// Flips the current value.
             #[ink(message)]
             #[ink(selector = "0xCAFEBABE")] // You can either specify selector out-of-line.
             pub fn flip(&mut self) {
                 self.value = !self.value;
             }

             /// Returns the current value.
             #[ink(message, selector = "0xFEEDBEEF")] // ...or specify selector inline.
             pub fn get(&self) -> bool {
                 self.value
             }
         }
     }
     ```

## Interacting with the Contract Executor

The `ink_env` crate provides facilities to interact with the contract executor that
connects ink! smart contracts with the outer world.

For example it is possible to query the current call's caller via:

```rust
use ink_env;
ink::env::test::run_test::<ink::env::DefaultEnvironment, _>(|_| {
    let caller = ink::env::caller::<ink::env::DefaultEnvironment>();
    let _caller = caller;
    Ok(())
}).unwrap();
```

However, ink! provides a much simpler way to interact with the contract executor
via its environment accessor. An example below:

```rust
#[ink::contract]
mod greeter {
    #[ink(storage)]
    pub struct Greeter;

    impl Greeter {
        #[ink(constructor)]
        pub fn new() -> Self {
            let caller = Self::env().caller();
            let message = format!("thanks for instantiation {:?}", caller);
            ink::env::debug_println(&message);
            Greeter {}
        }

        #[ink(message, payable)]
        pub fn fund(&mut self) {
            let caller = self.env().caller();
            let value = self.env().transferred_balance();
            let message = format!("thanks for the funding of {:?} from {:?}", value, caller);
            ink::env::debug_println(&message);
        }
    }
}
```

## 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.

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<AccountId>,
         to: Option<AccountId>,
         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
         }
     }
 }
```

## Example: Flipper

The below code shows the complete implementation of the so-called Flipper
ink! smart contract.
For us it acts as the "Hello, World!" of the ink! smart contracts because
it is minimal while still providing some more or less useful functionality.

It controls a single `bool` value that can be either `false` or `true`
and allows the user to flip this value using the `Flipper::flip` message
or retrieve the current value using `Flipper::get`.

```rust
#[ink::contract]
pub mod flipper {
    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {
        /// Creates a new flipper smart contract initialized with the given value.
        #[ink(constructor)]
        pub fn new(init_value: bool) -> Self {
            Self { value: init_value }
        }

        /// Flips the current value of the Flipper's bool.
        #[ink(message)]
        pub fn flip(&mut self) {
            self.value = !self.value;
        }

        /// Returns the current value of the Flipper's bool.
        #[ink(message)]
        pub fn get(&self) -> bool {
            self.value
        }
    }
}
```
````

## File: docs/macros-attributes/default.md
````markdown
---
title: "#[ink(default)]"
slug: /macros-attributes/default
hide_title: true
---

![Text/default Title Picture](/img/title/text/default.svg)

Applicable to ink! messages and constructors.

Works as a hint for UIs to determine if constructor/message should be picked as default.

It's also used to select the constructor to include in Solidity compatible metadata.

At most one constructor or message can be marked as default.

## Example

```rust
#[ink(message, default)]
pub fn im_default(&self) {    
}
```
````

## File: docs/macros-attributes/error.md
````markdown
---
title: "#[ink::error]"
slug: /macros-attributes/error
hide_title: true
---

![Text/error Title Picture](/img/title/text/error.svg)

Applicable on `struct` and `enum` definitions.

It derives traits necessary for encoding/decoding a custom type as revert error data.

The following traits are derived depending on the ABI mode:
- In ["ink"][abi-ink] and ["all"][abi-all] ABI mode:
  - [`scale::Encode` and `scale::Decode`][scale-codec] for encoding/decoding ink! revert error data
  - [`scale_info::TypeInfo`][scale-info] for generating ink! contract metadata (gated behind the `std` feature)
- In ["sol"][abi-sol] and ["all"][abi-all] ABI mode:
  - [`SolErrorEncode`][sol-error-encode] and [`SolErrorDecode`][sol-error-decode]
    for encoding/decoding custom types as [Solidity custom errors][sol-custom-error]
  - `SolErrorMetadata` for generating [Solidity ABI metadata][sol-abi-json] (gated behind the `std` feature)

[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
[sol-error-encode]: https://use-ink.github.io/ink/ink/sol/trait.SolErrorEncode.html
[sol-error-decode]: https://use-ink.github.io/ink/ink/sol/trait.SolErrorDecode.html
[sol-custom-error]: https://soliditylang.org/blog/2021/04/21/custom-errors/
[sol-abi-json]: https://docs.soliditylang.org/en/latest/abi-spec.html#json
[scale-info]: https://docs.rs/scale-info/latest/scale_info/
[abi-ink]: ../basics/abi/ink.md
[abi-sol]: ../basics/abi/solidity.md
[abi-all]: ../basics/abi/all.md

## Example

```rust
#[ink::error]
struct UnitError;

#[ink::error]
enum MultipleErrors {
    UnitError,
    ErrorWithParams(bool, u8, String),
    ErrorWithNamedParams {
        status: bool,
        count: u8,
        reason: String,
    }
}
```

:::note
See our [Solidity ABI compatibility docs][sol-result] for more details about
handling Solidity ABI encoded [revert error data][sol-revert].
:::

[sol-revert]: https://docs.soliditylang.org/en/latest/control-structures.html#revert
[sol-result]: ../integrations-and-sdks/ethereum-compatibility.md#handling-the-resultt-e-type
````

## File: docs/macros-attributes/event.md
````markdown
---
title: "#[ink::event]"
slug: /macros-attributes/event
hide_title: true
---

![Text/event2 Title Picture](/img/title/text/event2.svg)

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.
````

## File: docs/macros-attributes/implementation.md
````markdown
---
title: "#[ink(impl)]"
slug: /macros-attributes/impl
hide_title: true
---

![Text/impl Title Picture](/img/title/text/impl.svg)

This attribute supports a niche case that is rarely needed.

Can be applied on ink! implementation blocks in order to make ink! aware
of them. This is useful if such an implementation block doesn't contain
any other ink! attributes, so it would be flagged by ink! as a Rust item.
Adding `#[ink(impl)]` on such implementation blocks makes them treated
as ink! implementation blocks thus allowing to access the environment
etc.

Note that ink! messages and constructors still need to be explicitly
flagged as such.

## Example

An implementation block can be defined as a trait implementation
for the ink! storage struct using the `#[ink(impl)]` annotation ‒ even
if none of its interior items have any ink! specific attributes on them:

```rust
use core::convert::TryFrom;

#[ink::contract]
mod my_module {
    #[ink(storage)]
    pub struct MyStorage {
        /* storage fields */
    }

    #[ink(impl)]
    impl MyStorage {
        fn my_method(&self) -> i32 {
            /* method implementation */
        }
    }

    impl MyStorage {
      #[ink(constructor)]
      pub fn my_constructor() -> Self {
          /* constructor implementation */
      }

      #[ink(message)]
      pub fn my_message(&self) {
          /* message implementation */
      }
    }
}
```
````

## File: docs/macros-attributes/message.md
````markdown
---
title: "#[ink(message)]"
slug: /macros-attributes/message
hide_title: true
---

![Text/message Title Picture](/img/title/text/message.svg)

Applicable to methods.

Flags a method for the ink! storage struct as message making it available to the API for calling the contract.

Note that all public functions must use the `#[ink(message)]` attribute

There must be at least one `#[ink(message)]` defined method.

Methods flagged with `#[ink(message)]` are special in that they are dispatchable
upon contract invocation. The set of ink! messages defined for an ink! smart contract
define its API surface with which users are allowed to interact.

An ink! smart contract can have multiple such ink! messages defined.

An ink! message with a `&self` receiver may only read state whereas an ink! message
with a `&mut self` receiver may modify state.

```rust
#[ink(message)]
pub fn read_only(&self, from: AccountId) {
    // actual implementation
}

#[ink(message)]
pub fn modifies_state(&mut self, from: AccountId) {
    // actual implementation
}
```


## Messages Return Value

The return value of a message needs to implement `scale::Encode`.

It is notable that the collections under `ink_storage` ‒ such as e.g. `Vec` or `HashMap` ‒
don't implement `scale::Encode`. This means you can't just return a `Vec` from an ink! message.
This restriction is intentional ‒ returning a complete data structure with a potentially unbounded
content is an anti-pattern for smart contracts. Just think about the unpredictable gas costs.

If you _really really_ need to return a data structure in its entirety then use the ones from
`ink_prelude` (e.g. `ink_prelude::vec::Vec`). Those implement `scale::Encode`.

:::note
In ["sol"][abi-sol] and ["all"][abi-all] ABI mode, the return value of a message
must either implement [`SolEncode`][sol-encode], or be a `Result<T,E>` type
where `T` implements [`SolEncode`][sol-encode] and `E` implements [`SolErrorEncode`][sol-error-encode].

See our [Solidity ABI compatibility docs][sol-abi-compat] for more details.
:::

[abi-all]: ../basics/abi/all.md
[abi-sol]: ../basics/abi/solidity.md
[sol-encode]: https://use-ink.github.io/ink/ink/trait.SolEncode.html
[sol-error-encode]: https://use-ink.github.io/ink/ink/sol/trait.SolErrorEncode.html
[sol-abi-compat]: ../integrations-and-sdks/ethereum-compatibility.md

## Example

Given the `Flipper` contract definition above we add some `#[ink(message)]` definitions
as follows:

```rust
#[ink::contract]
mod flipper {
    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {

        #[ink(constructor)]
        pub fn new(initial_value: bool) -> Self {
            Flipper { value: false }
        }

        /// Flips the current value.
        #[ink(message)]
        pub fn flip(&mut self) {
            self.value = !self.value;
        }

        /// Returns the current value.
        #[ink(message)]
        pub fn get(&self) -> bool {
            self.value
        }
    }
}
```
````

## File: docs/macros-attributes/name.md
````markdown
---
title: "#[ink(name = \"…\")]"
slug: /macros-attributes/name
hide_title: true
---

![Text/name Title Picture](/img/title/text/name.svg)

Applicable to ink! messages, ink! constructors and ink! events.

Specifies a name/identifier override that is used in place of the item's name/identifier for:
- [Selector][selector] computation for ink! messages and ink! constructors
- [Signature topic][signature-topic] computation for ink! events
- [Contract metadata][metadata] generation for the ink! messages, ink! constructors or ink! events

[selector]: ./selector.md
[signature-topic]: ../basics/events.md#signature-topic
[metadata]: ../basics/metadata/overview.md#topics

In general, `name` overrides should mainly be used to:
- Implement contracts compliant with Ethereum/Solidity contract standards (i.e. ERCs)
  that require/use overloaded interfaces
- Define interfaces (e.g. via trait definitions) for interacting with
  existing Solidity ABI encoded contracts with overloaded interfaces
- As a more transparent alternative to custom selectors for the
  "name-changing while maintaining the same selector" use case for ink! ABI contracts

:::note
For native/ink! ABI, message and constructor selectors are computed from the item name/identifier alone,
so multiple messages with the same `name` attribute override will have the same computed selector,
which results in a compilation error about the overlapping selectors.

In general, more semantic interfaces with descriptive and unique item names/identifiers
are encouraged for new contracts (especially contracts that support the ink! ABI
i.e. "ink" or "all" ABI mode).
:::

## Examples

```rust
#[ink(message, name = "myConstructor")]
fn my_constructor(&self) {}

#[ink(message, name = "myMessage")]
fn my_message(&self) {}

#[ink::event(name = "MyEvent")]
pub struct Event { ... }
```
    
This changes the resulting selectors of the ink! message and ink! constructor,
and the signature topic for the ink! event, as well as their names in contract metadata.

:::note
For native/ink! ABI, the [`selector` attribute][selector] has higher precedence than the `name` attribute.
This means that the manually provided selector is used when an ink! message or ink! constructor
is annotated with both the `selector` and `name` attributes e.g.
in the example below, the selector for the ink! message is `0x1`.

```
#[ink(message, name = "myMessage", selector = 0x1)]
fn my_message(&self) {}
```
:::
````

## File: docs/macros-attributes/namespace.md
````markdown
---
title: "#[ink(namespace = \"…\")]"
slug: /macros-attributes/namespace
hide_title: true
---

![Text/namespace Title Picture](/img/title/text/namespace.svg)

Applicable to ink! trait implementation blocks.

Applied on ink! trait implementation blocks to disambiguate other trait
implementation blocks with equal names.

## Example

```rust
#[ink(namespace = "my_namespace")]
impl MyTrait for MyStorage {
    #[ink(message)]
    fn my_message(&self) {}
}
```
    
This changes the resulting selectors of all the ink! messages and ink! constructors within the trait implementation.
Thus allowing disambiguation between trait implementations with overlapping message or constructor names.
````

## File: docs/macros-attributes/overview.md
````markdown
---
title: Overview
slug: /macros-attributes
hide_title: true
---

![Text/contract Title Picture](/img/title/text/contract.svg)

# Understanding Macros & Attributes

## What Are Macros?

If you've never worked with Rust before, those lines starting with `#` might look strange! They're called **attributes** and **macros**, and they're one of Rust's most powerful features.

**Think of macros as code generators.** They write repetitive boilerplate code for you automatically. Instead of writing hundreds of lines manually, you add a simple annotation and the compiler does the heavy lifting.

### A Simple Example: `#[derive(Debug)]`

Let's start with a simple Rust example (not ink! yet) to understand the concept:

**Without a macro, you'd write:**
```rust
struct Person {
    name: String,
    age: u32,
}

// You'd have to manually implement how to print this struct
impl std::fmt::Debug for Person {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "Person {{ name: {:?}, age: {:?} }}", self.name, self.age)
    }
}
```

**With the `#[derive(Debug)]` macro:**
```rust
#[derive(Debug)]
struct Person {
    name: String,
    age: u32,
}

// That's it! The macro automatically generated all the printing code for you
```

Both do the exact same thing, but the macro version is much shorter and less error-prone!

### How Macros Work in ink!

ink! uses macros extensively because smart contracts need a LOT of boilerplate code:
- Code to serialize/deserialize function calls
- Code to route function calls to the right method
- Code to interact with blockchain storage
- Code to handle events and errors
- Safety checks and validations

**Instead of writing all this yourself, ink! macros generate it automatically.**

When you write:
```rust
#[ink::contract]
mod my_contract {
    #[ink(storage)]
    pub struct MyContract {
        value: bool,
    }

    #[ink(message)]
    pub fn flip(&mut self) {
        self.value = !self.value;
    }
}
```

The ink! macros are generating hundreds of lines of code behind the scenes to:
- Make your contract callable from the blockchain
- Handle storage reads and writes safely
- Create the contract's public API
- Generate metadata so tools know how to interact with your contract
- Add security checks and gas metering hooks

**You write ~20 lines. The macros generate ~500+ lines of low-level code.**

### Why This Matters for Smart Contracts

Smart contracts are different from regular programs:
1. **They run on a blockchain** - Need special code to interact with blockchain state
2. **They're called over a network** - Need serialization/deserialization code
3. **They handle money** - Need extra safety and validation
4. **They must be efficient** - Gas costs mean every byte matters

Writing all this by hand would be tedious and error-prone. Macros solve this by:
- Ensuring consistency across all contracts
- Reducing human error
- Making the code readable and maintainable
- Hiding complexity so you can focus on your business logic

## Common ink! Macros You'll Use

Here's a quick reference of the most important ink! macros. For detailed documentation on each, visit [https://use.ink/docs/v6/macros-attributes](https://use.ink/docs/v6/macros-attributes).

### Core Contract Macros

- **`#[ink::contract]`** - Marks a module as an ink! smart contract (required, used once per contract)
- **`#[ink(storage)]`** - Defines your contract's permanent data storage (required, used once)
- **`#[ink(constructor)]`** - Marks functions that create new contract instances (required, at least one)
- **`#[ink(message)]`** - Marks functions that can be called from outside (required, at least one)
- **`#[ink(event)]`** - Defines events your contract can emit (optional)

### Additional Attributes

- **`#[ink(payable)]`** - Allows a message to receive tokens
- **`#[ink(selector = N)]`** - Manually set the function identifier
- **`#[ink(topic)]`** - Makes an event field indexed for searching
- **`#[ink(anonymous)]`** - Creates an event without automatic indexing

### When to Use Which Macro?

| You want to... | Use this macro |
|----------------|----------------|
| Create a contract | `#[ink::contract]` on your module |
| Store data permanently | `#[ink(storage)]` on a struct |
| Initialize a new contract | `#[ink(constructor)]` on a function |
| Create a public function | `#[ink(message)]` on a function |
| Log an event | `#[ink(event)]` on a struct |
| Accept token payments | `#[ink(payable)]` on a message |

## Learn More

For complete documentation on each macro with examples and advanced options, visit:
**[https://use.ink/docs/v6/macros-attributes](https://use.ink/docs/v6/macros-attributes)**

---

## Technical Details

An ink! module is the module that is flagged by `#[ink::contract]` containing all the ink! definitions.
All ink! attributes are available to specify inside an ink! module.

## Merging Attributes

It is possible to merge attributes that share a common flagged entity.
The example below demonstrates this for a payable message with a custom selector.

```rust
#[ink(message)]
#[ink(payable)]
#[ink(selector = "0xCAFEBABE")]
pub fn transfer(&mut self, from: AccountId, to: AccountId, value: Balance) -> Result<(), Error> {
    // actual implementation
}
```
We can also write the above ink! message definition in the following way:
```rust
#[ink(message, payable, selector = "0xCAFEBABE")]
pub fn transfer(&mut self, from: AccountId, to: AccountId, value: Balance) -> Result<(), Error> {
    // actual implementation
}
```
````

## File: docs/macros-attributes/payable.md
````markdown
---
title: "#[ink(payable)]"
slug: /macros-attributes/payable
hide_title: true
---

![Text/payable Title Picture](/img/title/text/payable.svg)

Applicable to ink! messages.

Allows receiving value as part of the call of the ink! message.
ink! constructors are implicitly payable, due to the initial endowment which a contract requires.

An ink! message by default will reject calls that additional fund the smart contract.
Authors of ink! smart contracts can make an ink! message payable by adding the `payable`
flag to it. An example below:

Note that payable ink! messages inherently modify the blockchain state, 
and therefore must have a `&mut self` receiver.

Note that ink! constructors are always implicitly payable and thus cannot be flagged
as such.

```rust
#[ink::contract]
mod flipper {

    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {
        #[ink(constructor)]
        pub fn new(initial_value: bool) -> Self {
            Flipper { value: false }
        }

        /// Flips the current value.
        #[ink(message)]
        #[ink(payable)] // You can either specify payable out-of-line.
        pub fn flip(&mut self) {
            self.value = !self.value;
        }
        
        /// Flips the current value.
        #[ink(message, payable)] // or specify payable inline.
        pub fn flip_2(&mut self) {
            self.value = !self.value;
        }

        /// Returns the current value.
        #[ink(message)]
        pub fn get(&self) -> bool {
            self.value
        }
    }
}
```

## Example

```rust
#[ink(message, payable)]
pub fn pay_me(&mut self) {
    let _transferred = self.env().transferred_value();
}
```

See the [`examples/contract-transfer`](https://github.com/use-ink/ink-examples/blob/main/contract-transfer/lib.rs) contract for a more extensive example.
````

## File: docs/macros-attributes/selector.md
````markdown
---
title: "#[ink(selector = S:u32)]"
slug: /macros-attributes/selector
hide_title: true
---

![Text/selector Title Picture](/img/title/text/selector.svg)

:::note
ink! v6 supports both the native ink! and [Solidity][sol-abi] ABI 
(Application Binary Interface) specifications for contract interactions 
(i.e. calling conventions used for message calls).

When support for Solidity ABI calling conventions is enabled 
(see [here][abi-declaration] for details), 
Solidity ABI selectors for messages are **always** generated according to the
[Solidity ABI specification for function selectors][sol-abi-selector].

So the instructions below for **controlling message selectors only apply to 
native ink! ABI selectors** (i.e. message selector manual overrides are ignored
when generating Solidity ABI selectors for messages).

Learn more about ink!'s support for multiple ABIs [here][abi-support].
:::

[sol-abi]: https://docs.soliditylang.org/en/latest/abi-spec.html
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
[abi-support]: ../basics/abi/overview.md
[abi-declaration]: ../basics/abi/overview.md#declaring-the-abi

Applicable to ink! messages and ink! constructors.

By default, ink! creates a selector for each message and constructor.
This is necessary since the contract is compiled to a binary blob and functions are invoked by invoking the
selector, which identifies a method ‒ method names are no longer available in these underlying layers.

Using this attribute it is possible to specify a concrete dispatch selector for the flagged entity. This allows a contract author to precisely control the selectors of their APIs making it possible to rename their API without breakage.

A selector must be a `u32` decodable integer. For example

- `selector = 0xCAFEBABE`
- `selector = 42`

An exception is the fallback selector `_`, allowing contract calls not matching any of the other message selectors to be dispatched to a fallback message. Fallback messages can be `payable`.

:::info
The term wildcard selector is just a synonym for fallback selector.
:::

## Examples

```rust
#[ink(message, selector = 0xC0DECAFE)]
fn my_message_1(&self) {}

#[ink(message, selector = 42)]
fn my_message_2(&self) {}

#[ink(message, payable, selector = _)]
fn my_fallback(&mut self) {}
```
… then the selector of `my_message_1` is `[0xC0, 0xDE, 0xCA, 0xFE]` and the selector of `my_message_2` is `[0, 0, 0, 42]`
since setting the selector manually overrides the automatically generated selector.

## Controlling message and constructor selectors

Every ink! message and ink! constructor has a selector with which the
message or constructor can be uniquely identified within the ink! smart contract.
Non-unique message or constructor selector lead to a compile time error.
These selectors are mainly used to drive the contract's dispatch upon calling it.

An ink! smart contract author can control the selector of an ink! message or ink!
constructor using the `selector` flag. An example is shown below:

```rust
#[ink::contract]
mod flipper {
    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {
        #[ink(constructor)]
        #[ink(selector = 0xDEADBEEF)] // Works on constructors as well.
        pub fn new(initial_value: bool) -> Self {
            Flipper { value: initial_value }
        }

        #[ink(message)]
        #[ink(selector = 0xCAFEBABE)] // You can either specify selector out-of-line.
        pub fn flip(&mut self) {
            self.value = !self.value;
        }

        #[ink(message, selector = 0xC0DECAFE)] // ...or specify the selector inline.
        pub fn get(&self) -> bool {
            self.value
        }
    }
}
```
````

## File: docs/macros-attributes/storage.md
````markdown
---
title: "#[ink(storage)]"
slug: /macros-attributes/storage
hide_title: true
---

![Text/storage Title Picture](/img/title/text/storage.svg)

Applicable on `struct` definitions. 

Applied on `struct` types in order to flag them for being
the contract's storage definition.
There can only be one ink! storage definition per contract.

There must be exactly one `#[ink(storage)]` struct.

This struct defines the layout of the storage that the ink! smart contract operates on.
The user is able to use a variety of built-in facilities, combine them in various ways
or even provide their own implementations of storage data structures.

For more information visit the `ink_storage` crate documentation.

## Example


```rust
#[ink::contract]
mod flipper {

    #[ink(storage)]
    pub struct Flipper {
        value: bool,
    }

    impl Flipper {
        #[ink(constructor)]
        pub fn construct() -> Self { Flipper { value: false } }

        #[ink(message)]
        pub fn message(&self) {}
    }
}
```
````

## File: docs/macros-attributes/topic.md
````markdown
---
title: "#[ink(topic)]"
slug: /macros-attributes/topic
hide_title: true
---

![Text/topic Title Picture](/img/title/text/topic.svg)

Applied on fields of ink! event types to indicate that they are topics.

Tells the ink! codegen to provide a topic hash for the given field. Every ink! event can only have a limited number of such topic field.
The semantics are similar to indexed event arguments in Solidity.

## Example

```rust
#[ink(event)]
pub struct Transferred {
    #[ink(topic)]
    from: Option<AccountId>,

    #[ink(topic)]
    to: Option<AccountId>,

    amount: Balance
}
```
````

## File: docs/macros-attributes/trait_definition.md
````markdown
---
title: "#[ink::trait_definition]"
slug: /macros-attributes/trait_definition
hide_title: true
---

![Text/trait Title Picture](/img/title/text/trait.svg)

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]`](./contract.md) macro can properly generate code
for its implementations.

[See our section on Trait Definitions](../basics/trait-definitions.md) for a detailed description and examples.
````

## File: docs/testing/testnet/faucet.md
````markdown
---
title: Faucet
slug: /faucet
hide_title: true
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Faucet Title Picture](/img/title/faucet.svg)

# Faucet

<!-- import Faucet from "./Faucet"; -->

The community-maintained Polkadot testnet "Paseo" provides a faucet: 
[Paseo Faucet](https://faucet.polkadot.io/).
By requesting funds from the link above you will receive `PAS`
tokens to your account.

The polkadot-js UI will display them under [the "Accounts" tab](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpaseo.dotters.network#/accounts):

<img src={useBaseUrl('img/pas-in-wallet.png')} alt="Paseo testnet tokens in wallet" />

You can deploy your contract with PAS token on [Pop's Testnet](https://learn.onpop.io/contracts/tutorials/your-first-ink-smart-contract). See [Pop's guide to getting tokens](https://learn.onpop.io/contracts/guides/bridge-tokens-to-pop-network).
````

## File: docs/testing/testnet/Faucet.tsx
````typescript
import React, { useMemo, useState } from 'react'
import ReCAPTCHA from 'react-google-recaptcha'

const RECAPTCHA_SITE_KEY = '6LcgFI4nAAAAAATrEMoJ6zBacsx5udc1UhGFXemH'
const FAUCET_URL = 'https://rococo-faucet.parity-testnet.parity.io/drip/web'

const Faucet = () => {
  const [captcha, setCaptcha] = useState<string | null>(null)
  const acc = useMemo(() => {
    if (typeof window === 'undefined') return '';
    const params = new URLSearchParams(window?.location?.search);
    return params?.get('acc') || undefined;
  }, [])
  const [address, setAddress] = useState<string | undefined>(acc)
  const [hash, setHash] = useState<string>()
  const [error, setError] = useState<string>()
  const [inProgress, setInProgress] = useState(false)

  const handleRequest = async () => {
    try {
      setHash(undefined)
      setError(undefined)
      setInProgress(true)

      const body = {
        address,
        parachain_id: '1002',
        recaptcha: captcha,
      }

      const fetchResult = await fetch(FAUCET_URL, {
        method: 'POST',
        body: JSON.stringify(body),
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
        },
      })
      const result = await fetchResult.json()
      if ('error' in result) {
        setError(result.error)
      } else {
        setHash(result.hash)
      }
    } catch (e) {
      // eslint-disable-next-line no-console
      console.error(e)
      setError('Hmm... something went wrong.')
    } finally {
      setInProgress(false)
    }
  }

  return (
    <div className="faucetContainer">
      <h3 className="faucetTitle">Get Testnet Tokens</h3>
      <div className="faucetPlantContainer">
        <img src="/img/plantOne.svg" alt="illustration of a sea grass plant" className="faucetPlantOne" />
        <img src="/img/plantTwo.svg" alt="illustration of a sea plant" className="faucetPlantTwo" />
      </div>
      <div className="faucetHeroContainer">
        <img src="/img/chest.svg" alt="treasure chest" className="faucetHeroImage" />
      </div>
      <form className="withHero">
        <fieldset>
          <label htmlFor="address-input">Your SS58 Address</label>
          <input
            className="addressInput"
            id="address-input"
            type="text"
            value={address}
            placeholder="e.g. 5HprbfKUFdN4qfweVbgRtqDPHfNtoi8NoWPE45e5bD5AEKiR"
            onChange={(e) => {
              setAddress(e.target.value)
              setError(undefined)
              setHash(undefined)
            }}
          />
        </fieldset>
        <ReCAPTCHA sitekey={RECAPTCHA_SITE_KEY} onChange={setCaptcha} />
        <button
          disabled={inProgress || !captcha || !address}
          onClick={async (e) => {
            e.preventDefault()
            await handleRequest()
          }}
        >
          {inProgress ? 'Requesting...' : 'Request'}
        </button>
      </form>

      <div className="faucetResultContainer">
        {hash && (
          <button
            className="faucet-success w-full border-none"
            onClick={() => window.open(`https://rococo.subscan.io/extrinsic/${hash}`, '_blank')}
          >
            <div className="faucet-success-ic">
              <p className="faucet-success-msg">Your funds have been sent!</p>
              <p className="faucet-success-cta">Click here to view the transaction</p>
            </div>
          </button>
        )}
        {error && <p className="error">{error}</p>}
      </div>
    </div>
  )
}

export default Faucet
````

## File: docs/testing/testnet/overview.md
````markdown
---
title: Contracts on Paseo
hide_title: true
slug: /testnet
---

import useBaseUrl from '@docusaurus/useBaseUrl';

![Testnet Title Picture](/img/title/testnet.svg)

# Contracts on Paseo (using Pop Testnet)

- [Paseo](https://wiki.polkadot.network/docs/build-pdk#paseo-testnet) is Polkadot's main testnet for parachains.  
- [Pop](https://learn.onpop.io/contracts) is a parachain on Paseo that allows you to deploy smart contracts – and uses Paseo's token (PAS).

## How can I use it?

### (1) Create an Account

As a first step, you should create an account. This can be done via command-line
tools (e.g. `subxt`) or via a wallet (e.g. with the `polkadot-js` browser extension).
See [here](https://wiki.polkadot.network/docs/learn-account-generation) for a detailed guide.

### (2) Get Testnet Tokens

As a second step, you have to get `PAS` testnet tokens through the [Paseo Faucet](https://faucet.polkadot.io/). For Pop, make sure to select Asset Hub as the destination (see [this guide](https://learn.onpop.io/contracts/guides/bridge-tokens-to-pop-network) for details).

Alternatively, you can use the [Matrix chat room](https://wiki.polkadot.network/docs/learn-DOT#getting-tokens-on-the-paseo-testnet).
You must send a message like this:

```
!drip <PASEO_ADDRESS>
```

If everything worked out, the `PAS` tokens will show up in your account.
In case you are using the `polkadot-js` frontend, you can see them under
[the "Accounts" tab for Paseo](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpaseo.dotters.network#/accounts).

<img src={useBaseUrl('img/pas-in-wallet.png')} alt="Paseo testnet tokens in wallet" />

### (3) Deploy Your Contract

Once you have `PAS` on Paseo you can [bridge them from Paseo to Pop](https://learn.onpop.io/contracts/guides/bridge-tokens-to-pop-network) and deploy by following the instructions in the Pop Docs [here](https://learn.onpop.io/contracts/guides/deploy#deploy-to-custom-or-public-network).
````

## File: docs/testing/e2e.md
````markdown
---
title: "Full E2E"
hide_title: true
slug: /contract-testing/end-to-end-e2e-testing
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![Testing1 Title Picture](/img/title/testing1.svg)

# End-to-End (E2E) Tests

E2E testing enables developers to write a test that will not only test the contract in an
isolated manner; instead the contract will be tested _together_ with all components that
will be involved on-chain – so from end to end. This way of testing resembles closely
how the contract will actually behave in production.

As part of the test, the contract will be compiled and deployed to a Polkadot SDK node that
is running in the background. ink! offers API functions that enable developers to then
interact with the contract via transactions that they create and submit to the blockchain.

You as a developer can define assertions on the outcome of their transactions, such as checking
for state mutations, transaction failures or incurred gas costs.

Your chain configuration will be tested together with the smart contract. And if your
chain has pallets that are involved with the smart contract execution, those will be
part of the test execution as well.

ink! does not put any requirements on the Polkadot SDK node in the background – for example,
you can run a node that contains a snapshot of a live network.

## Example

The following code example illustrates a basic E2E test for the
[flipper example](https://github.com/use-ink/ink-examples/blob/main/flipper/lib.rs).

```rust
#[ink_e2e::test]
async fn default_works<Client: E2EBackend>(mut client: Client) -> E2EResult<()> {
    // When the function is entered, the contract was already
    // built in the background via `cargo contract build`.
    // The `client` object exposes an interface to interact
    // with the Polkadot SDK node.
    
    // given
    let mut constructor = FlipperRef::new_default();

    // when
    let contract = client
        .instantiate("flipper", &ink_e2e::bob(), &mut constructor)
        .submit()
        .await
        .expect("instantiate failed");
    let call_builder = contract.call_builder::<Flipper>();

    // then
    let get = call_builder.get();
    let get_res = client.call(&ink_e2e::bob(), &get).dry_run().await?;
    assert!(matches!(get_res.return_value(), false));

    Ok(())
}
```

You can run the above test by going to the `flipper` folder in
[the ink! examples directory](https://github.com/use-ink/ink-examples/tree/main).

Before you can run the test, you have to install a Polkadot SDK
node with `pallet-revive`. By default, e2e tests require that you install [`ink-node`](https://github.com/use-ink/ink-node). You do not need to run it in the background since the node is started for each test independently.
The easiest way is to 
[download a binary from our releases page](https://github.com/use-ink/ink-node/releases)
(Linux and Mac).
Alternatively, you can build the node by yourself.
The build instructions and pre-requisites can be found
[here](https://github.com/use-ink/ink-node?tab=readme-ov-file#build-locally).

If you want to run any other node with `pallet-revive` you need to change `CONTRACTS_NODE` environment variable:

```bash
export CONTRACTS_NODE="YOUR_CONTRACTS_NODE_PATH"
```

And finally execute the following command to start e2e test execution.

<Tabs>
  <TabItem value="cargo-contract" label="cargo-contract" default>
  ```bash
  cargo contract test --features e2e-tests
  ```
  </TabItem>
  <TabItem value="pop" label="Pop">
  ```bash
  pop test --e2e
  ```
  </TabItem>
</Tabs>
````

## File: docs/testing/overview.md
````markdown
---
title: Overview
hide_title: true
slug: /contract-testing/overview
---

![Testing1 Title Picture](/img/title/testing1.svg)

# Testing Strategies

ink! supports three different stages of testing: unit, integration
and end-to-end tests. In this chapter we'll explain what the purpose
of each stage is about and how to use it.

![ink! Testing Strategies](/img/testing.png)

Generally you can think of those three types of testing as a pyramid
with the top being the most elaborate test. The End-to-End (E2E)
tests at the top will test the lower layers of the pyramid as part
of them.
````

## File: docs/testing/sandbox.md
````markdown
---
title: "Sandboxed E2E"
hide_title: true
slug: /contract-testing/drink
---

![Drink Title Picture](/img/title/drink.svg)

:::note
TODO This page has not yet been reviewed for ink! v6.
:::

# DRink!

Apart from the core ink! testing framework, we also provide the [DRink!](https://github.com/use-ink/drink) library.
It offers an intermediate solution between integration and E2E testing.

Intuitively, DRink! maintains a full in-memory blockchain state and allows you to interact with it directly.
This gives a notably robust methodology in contrast to the off-chain engine facilitated by the `ink::test` macro.
Nevertheless, it is essential to note that the absence of the entire node layer makes the environment less realistic compared to the comprehensive setup employed in the end-to-end tests.

## Comparison to the other testing strategies

To better assess when DRink! performs better than other testing methods, it is crucial to gain a deeper understanding of the consequences of its unique design and the trade-offs it entails.

1. **Speed:** since DRink! doesn't spawn any node or background process, everything happens locally, within the testing thread.
This means that the execution can be synchronous and significantly faster than the E2E tests.
Therefore, its performance should be comparable to the unit or integration testing.
Also, there is no block production or finalization delay, which is a noticeable factor in the E2E tests.
Thanks to that, we can launch long-running simulations in a reasonable time.

2. **Testing multiple contracts:** since we are working with a full blockchain state, we can perform any interaction with the contracts, which includes working with mutliple contracts at the same time.
Of course, this is the same as in the E2E tests, but it is not possible in either the unit or integration tests.

3. **Working with arbitrary runtimes:** similarly to the E2E tests, where we can spawn any node with customized runtime (Polkadot's term for the state transition function), in DRink! tests we can work with any blockchain runtime we want.

4. **Full control over runtime state:** we hold the state of the blockchain and exercise full control over it, so we can easily manipulate it however we want.
This covers manipulating block number, timestamp, account balances, etc.
Some of these are also possible in the E2E tests, but usually they require more effort or overhead.

5. **Powerful features:** thanks to the unique design of DRink!, we can easily take advantage of some powerful, not available in other testing strategies, features:

   - **contract mocking:** you can mock any contract or message you want, specifying the default behavior or the exact return value.
   - **enhanced debugging and call tracing:** you can get more insights into the contract execution process, like stack trace, debug buffers and more.

Nevertheless, there are some drawbacks of DRink! as well:

1. **No node layer:** since we don't spawn any node, we don't have access to the node layer, which means that we can't test any node-related functionality, like RPC calls, block production, etc.

2. **Artificial, isolated environment:** this is the main trade-off of DRink!.
It might give a false sense of security, while in the real environment, the contract could behave differently.
The discrepancy can be mitigated by a careful and precise simulation and setup of the environment, but it is still a factor to consider.

3. **No typed contract API:** currently, DRink! works with string-encoded arguments and values, which means that we lose the type safety and convenience that was present in the other testing frameworks.
Fortunately, this is going to change soon, as there is an ongoing effort to integrate it with [ink-wrapper](https://github.com/Cardinal-Cryptography/ink-wrapper) library.

## When to use `DRink!`?

Usually, DRink! is a good choice for the development phase of your project.
When the iteration speed is crucial, and you want to quickly test your contracts, DRink! will offer a versatile, yet highly efficient testing environment.
However, you must not forget that it is not a replacement for the E2E tests, which should be run before the deployment to the production network, as well as in your CI/CD pipelines.

DRink! also comes in handy when you need to:
 - mock some parts of your contract suite
 - debug the execution process
 - launch long-running simulations, that would normally take a lot of time when relying on a real block-time

## How to use DRink!?

There are three ways to use DRink!:

### Directly as a library

This way you gain access to full DRink! power in your test suites.

`drink` library is continuously published to [crates.io](https://crates.io/crates/drink), so you can use it in your project with either `cargo add drink` or by adding the following line to your `Cargo.toml`:
```toml
drink = { version = "0.8" }
```

Then, you can write your tests like this:
```rust
#[cfg(test)]
mod tests {
    /// This will take care of building all contract dependencies in the compilation phase and gather all contract 
    /// bundles (metadata and the compiled code) into a single registry.
    #[drink::contract_bundle_provider]
    enum BundleProvider {}

   /// Within `drink::test` macro, you are provided with a `session` object, which is a wrapper around the
   /// blockchain state. You can use it to deploy contracts, call their methods, and more.
    #[drink::test]
    fn deploy_and_call_a_contract(mut session: Session) -> Result<(), Box<dyn Error>> {
        let result: bool = session
            .deploy_bundle_and(BundleProvider::local(), "new", &["true"], NO_SALT, NO_ENDOWMENT)?
            .call_and("flip", NO_ARGS, NO_ENDOWMENT)?
            .call_and("flip", NO_ARGS, NO_ENDOWMENT)?
            .call_and("flip", NO_ARGS, NO_ENDOWMENT)?
            .call("get", NO_ARGS, NO_ENDOWMENT)??;
        assert_eq!(result, false);
    }
}
```

You can check some helpful and verbose examples [here](https://github.com/inkdevhub/drink/tree/main/examples), including the [**quick start guide**](https://github.com/inkdevhub/drink/tree/main/examples/quick-start-with-drink).

### As an alternative backend to ink!'s E2E testing framework

DRink! is already integrated with the ink! framework and can be used as a drop-in replacement for the standard E2E testing environment.

Import `ink_sandbox` in your Cargo.toml:
```toml
ink_sandbox = { git = "https://github.com/use-ink/ink", tag = "v6.0.0-alpha.4" }
```

And just use corresponding argument in the test macro:
```rust
#[ink_sandbox::test(backend(runtime_only(
    sandbox = sandbox_runtime::ContractCallerSandbox,
    client  = ink_sandbox::SandboxClient
)))]
```
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/use-ink/ink-examples/tree/main/e2e-runtime-only-backend).

### With a command line tool

We provide a CLI which puts DRink! behind friendly TUI.
For more details, consult [its README](https://github.com/inkdevhub/drink/blob/main/drink-cli/README.md).

Similarly to `drink` library, `drink-cli` is published to [crates.io](https://crates.io/crates/drink-cli) as well.
You can install it with:
```shell
cargo install drink-cli
```
````

## File: docs/testing/testing-with-live-state.md
````markdown
---
title: Testing with Chain Snapshots
hide_title: true
slug: /contract-testing/chain-snapshot
---

![Blockchain Fork Title Picture](/img/title/blockchain-fork.svg)

# Test your Contract with a Chain Snapshot

:::caution
This page has not yet been updated to ink! v6.

TODO
:::

On this page we explain how to test ink! contracts with the
fork of an existing chain. We'll take a snapshot of an existing
chain for this purpose. The snapshot contains the chains full state,
but can be modified locally without affecting the live chain. 
We'll use the [Chopsticks](https://github.com/AcalaNetwork/chopsticks)
tool for this purpose.

This is a powerful workflow that you can use to e.g.

* Test a contract upgrade or migration locally before running it in production.
* Debug the behavior of an on-chain contract with on-chain state locally.
* Get detailed debug info and replay blocks as you want.
* …and much more!

In the first section of this page we explain the general concept, using a local
`ink-node` that will play the role of our "live chain".
The `ink-node` is just for exemplary purposes, you can also 
apply the exact same workflow to production chains like Astar, Aleph Zero,
Pendulum and others.

## General Concept

First you need a node that has produced some blocks with state. We'll
use `ink-node` for this purpose.
[See here](../getting-started/deploying.md) for how to run it.

You should get output similar to:

```
ink-node
2023-09-26 07:58:28.885  INFO main sc_cli::runner: ink! Node
2023-09-26 07:58:28.887  INFO main sc_cli::runner: ✌️  version 0.30.0-124c159ba94    
2023-09-26 07:58:28.887  INFO main sc_cli::runner: ❤️  by Parity Technologies <admin@parity.io>, 2021-2023    
2023-09-26 07:58:28.887  INFO main sc_cli::runner: 📋 Chain specification: Development    
2023-09-26 07:58:28.887  INFO main sc_cli::runner: 🏷  Node name: chilly-desire-6458    
2023-09-26 07:58:28.887  INFO main sc_cli::runner: 👤 Role: AUTHORITY    
2023-09-26 07:58:28.887  INFO main sc_cli::runner: 💾 Database: ParityDb at /tmp/substrateoKCAts/chains/dev/paritydb/full    
2023-09-26 07:58:38.723  INFO main sc_rpc_server: Running JSON-RPC server: addr=127.0.0.1:9944, allowed origins=["*"]  
```

Note that the node is running on port 9944.

Next, we'll create some state and produce a bunch of blocks. You can do this by deploying [our
`flipper` example](https://github.com/use-ink/ink-examples/tree/main/flipper):

```
cd ink-examples/flipper/
cargo contract build --release
cargo contract instantiate --suri //Alice --args true -x
```

You can check that the contract exists by querying its state via `cargo-contract`:

```
cargo contract storage --contract 5FgRdaReCLFtwbzYiVd2hoz9P3oERdNy2njnFmUBHu4FYg7s
+-------+----------+--------+-------------------------+
| Index | Root Key | Parent | Value                   |
+=====================================================+
| 0     | 00000000 | root   | Flipper { value: true } |
+-------+----------+--------+-------------------------+
```

### Setup Chopsticks

We will now set up [Chopsticks](https://github.com/AcalaNetwork/chopsticks),
a powerful tool in our ecosystem that allows us to create a parallel reality
of an existing network.

We will run it and have it mirror the `ink-node` that is already running
on our machine from the previous step.

The following schema illustrates the setup that we will create:

<img className="schema2" width title="Test your smart contract on a Chopsticks branch" src="/img/test-smart-contract-with-chain-snapshot.svg" alt="Chain Snapshot" />

Clone chopsticks:

```
git clone https://github.com/AcalaNetwork/chopsticks
```

Modify the `dev.yml` config file in the cloned repository (or create one from scratch) :

```
endpoint: ws://127.0.0.1:9944
mock-signature-host: true
block: 1
db: ./db.sqlite
```

:::info
In the example above chopsticks will be mirroring up until block 1 from the
`ink-node`.

For production chains (like Aleph Zero or Astar) you would want to use a different
block number and different endpoint. The Chopsticks repository already contains a
wide number of configurations for ink! production chains (see [here](https://github.com/AcalaNetwork/chopsticks/tree/master/configs)).
If you don't find a fitting configuration there, see the section
"[Application to Production Chains](#application-to-production-chains)".
:::

You can either run chopsticks locally by following the instructions
[here](https://github.com/AcalaNetwork/chopsticks#install), or
you can run it using npx:

```
npx @acala-network/chopsticks@latest --config=configs/dev.yml
```

You should get output similar to:

```
npx @acala-network/chopsticks@latest --config=configs/dev.yml
[08:22:31.231] INFO (rpc/3037748): Development RPC listening on port 8000
```

The Chopsticks node is running on port 8000.
If you now execute the `cargo-contract` storage command against this node, you'll see
that the `flipper` contract exists there as well:

```
cargo contract storage --contract 5FgRdaReCLFtwbzYiVd2hoz9P3oERdNy2njnFmUBHu4FYg7s --url=ws://localhost:8000
+-------+----------+--------+-------------------------+
| Index | Root Key | Parent | Value                   |
+=====================================================+
| 0     | 00000000 | root   | Flipper { value: true } |
+-------+----------+--------+-------------------------+
```

Chopsticks has branched off from the live chain.
You can now submit transactions to the Chopsticks node on port 8000,
without affecting the node/chain on port 9944.

### Run ink! E2E Tests

Recap: We have our "live" `ink-node` running on port 9944
and our test node with the branched state running on port 8000.

Next we would like to run some tests against the contract on our forked chain. 
Our `flipper/lib.rs` contains a test that illustrates how to do this.
The test reads an environment variable `CONTRACT_ADDR_HEX` that refers to
the `flipper` on-chain address.

Here's the code for it:

```rust
#[ink_e2e::test]
#[ignore]
async fn e2e_test_deployed_contract<Client: E2EBackend>(
    mut client: Client,
) -> E2EResult<()> {
    // given
    let addr = std::env::var("CONTRACT_ADDR_HEX")
        .unwrap()
        .replace("0x", "");
    let acc_id = hex::decode(addr).unwrap();
    let acc_id = AccountId::try_from(&acc_id[..]).unwrap();

    // when
    // Invoke `Flipper::flip()` from Bob's account
    let call_builder = ink_e2e::create_call_builder::<Flipper>(acc_id);
    let flip = call_builder.flip();
    let _flip_res = client.call(&ink_e2e::bob(), &flip).submit().await?;
    
    // then
    let get = call_builder.get();
    let get_res = client.call(&ink_e2e::bob(), &get).dry_run().await?;
    assert!(matches!(get_res.return_value(), false));
    Ok(())
}
```

The test is marked as `#[ignore]`, as it requires the pre-conditions that we went through
above to succeed.

:::info
You can convert SS58 addresses to hex using [the `subkey` tool](https://crates.io/crates/subkey):

```
subkey inspect <YOUR-SS58>
```
:::

Here's the process to execute the above test:

```
# Address of your on-chain contract
export CONTRACT_HEX=0x2c75f0aa09dbfbfd49e6286a0f2edd3b4913f04a58b13391c79e96782f5713e3

# This env variable needs to be set to reference the Chopsticks node.
# If this env variable is not set, `ink_e2e` will spawn a new node
# process (typically of `ink-node`) for each test.
export CONTRACTS_NODE_URL=ws://127.0.0.1:8000

cargo contract test --features e2e-tests e2e_test_deployed_contract -- --ignored
```

You will get output similar to the following:

```
running 1 tests
test flipper::e2e_tests::e2e_test_deployed_contract ... ok
```

If you query the contract storage on our Chopsticks fork, you'll see that the E2E test
flipped the boolean:

```
cargo contract storage --contract 5FgRdaReCLFtwbzYiVd2hoz9P3oERdNy2njnFmUBHu4FYg7s --url=ws://localhost:8000
+-------+----------+--------+-------------------------+
| Index | Root Key | Parent | Value                   |
+=====================================================+
| 0     | 00000000 | root   | Flipper { value: false } |
+-------+----------+--------+-------------------------+
```

On the "original" `ink-node` chain the boolean will be untouched.

```
cargo contract storage --contract 5FgRdaReCLFtwbzYiVd2hoz9P3oERdNy2njnFmUBHu4FYg7s --url=ws://localhost:9944
+-------+----------+--------+-------------------------+
| Index | Root Key | Parent | Value                   |
+=====================================================+
| 0     | 00000000 | root   | Flipper { value: true } |
+-------+----------+--------+-------------------------+
```

Success! We just ran an ink! end-to-end test against the snapshot of a chain!

## Application to Production Chains

You can apply the workflow explained above to ink! production chains.

You would want to use a different block number and different endpoint.
The Chopsticks repository already contains a wide number of configurations for
ink! production chains (see [here](https://github.com/AcalaNetwork/chopsticks/tree/master/configs)).

If a pre-made config for chain you want to fork from is not available, you can just
modify the `dev.yml`. You can use [polkadot-js/apps](https://polkadot.js.org/apps) to
the URL of an endpoint to use:

<img src="/img/polkadot-js-rpc-endpoint.png"  />
````

## File: docs/testing/unit-integration.md
````markdown
---
title: Unit & Integration
hide_title: true
slug: /contract-testing/unit-integration-tests
---

![Testing1 Title Picture](/img/title/testing1.svg)

# Tests

On this page we lay out the different use-cases for unit vs. integration tests.

## Unit Tests

Testing contracts off-chain is done by `cargo contract test` and users can simply use the standard Rust
routines of creating unit test modules within the ink! project:

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn my_test() { ... }
}
```

Test instances of contracts can be created with something like:

```rust
let contract = MyContract::my_constructor(a, b);
```

Messages can simply be called on the returned instance as if `MyContract::my_constructor` returns a
`Self` instance.

See the [flipper example](https://github.com/use-ink/ink-examples/blob/main/flipper/lib.rs).

## Integration Tests

For integration tests, the test is annotated with our `#[ink::test]`
attribute instead of `#[test]`. This attribute denotes that
the test is then executed in a simulated, mocked blockchain environment.
Here functions are available to influence how the test environment
is configured (e.g. setting a specified balance of an account to
simulate how a contract would behave when interacting with it).

If you annotate a test with the `#[ink::test]` attribute it
will be executed in a simulated environment, similar to as it
would be run on-chain.
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/use-ink/ink-examples/blob/main/erc20/lib.rs) contract on how to utilize those or [the documentation](https://use-ink.github.io/ink/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
as possible.

:::note
One limitation of the off-chain testing framework is that it
currently only supports a `DefaultEnvironment`.

See [here](../basics/environment.md) for an explanation of what an environment is.
:::

### Example

```rust
#[cfg(test)]
mod tests {
    // Conventional unit test that works with assertions.
    #[ink::test]
    fn test1() {
        // test code comes here as usual
    }

    // Conventional unit test that returns some Result.
    // The test code can make use of operator-`?`.
    #[ink::test]
    fn test2() -> Result<(), ink::env::Error> {
        // test code that returns a Rust Result type
    }
}
```

## How do you find out if a test requires the off-chain environment?

If the test recursively uses or invokes methods that call a function defined
in `self.env()` or `Self::env()`.

An example is the following:

```rust
let caller: AccountId = self.env().caller();
```
````
