Rel: use-ink/ink#792, paritytech/substrate#8773

• Mention new seal_debug_message seal contracts function.
• Mention new macros.

Need to create a new page with examples for ContractReference

It would also be nice to link to cross-contract calling and upgradability techniques

Answer questions under https://paritytech.github.io/ink-docs/faq.

The file is found here.

These were re-written in #186, so the Spanish version will also need to be re-written.

See the release notes of ink! rc7 for more details: https://github.com/paritytech/ink/blob/cmichi-release-ink-rc7/RELEASES.md.

We should highlight how the behavior is for sub-contracts.

Maybe @Robbepop wants to tackle this?

We should add a section "Upgradeable Contracts" under "Basics".

ink! currently has those three approaches for upgradeable contracts: https://github.com/paritytech/ink/tree/master/examples/upgradeable-contracts.

We should have a page in our documentation on each, explaining the use cases and how to use them. The result of use-ink/ink#1247 should be incorporated here as well.

If you have ideas for illustrations to accompany these pages: feel free to approach our illustrator to create some in the ink! style.

We need to document the storage layout format. This should be a dedicated section.

I tried to use Canvas UI like docs but I found that they have a problem here and advised to use polkadot.

In paritytech/substrate#9669 we decided to remove this concept.

In the future there will be a different mechanism to cope with state boat, but until that one is here we should remove mentions of this no longer used concept.

More context: substrate-developer-hub/substrate-docs#460

I assume this will be the "canonical" place for contract standards to emerge, as PSP22 is directly related here?

I would think that highlighting in the FAQ something about "what is the ERC#### equivalent for ink & contracts pallet?" or "what contract standards exist?" that directs to PSPs would be a good staring point 😁

We should add a section "Common Misconceptions" or "Common (Beginner?) Mistakes" with the things we see in real-world contracts. Such as:

• A misconception that we often see is that developers think the smart contract is the actual interface for the user.
  That's why we often see mnemonic String types returned (in the worst case verbatim error messages instead of error codes).

• We should explain why contract size is important.
  We sometimes get questions like "My 100K contract can't be deployed". This is usually due to some third party crate dependency with default features enabled. Oftentimes the size can be reduced by tuning the features of that dep or using the built-in ink! API instead (oftentimes it's crypto/hashing dependencies).

• We should explain better why String should be avoided and especially what the alternatives are.
  We already have a section How do I use String in my contract? in our FAQ, but it goes in a bit of a different direction. Using String pulls in logic needed for e.g. UTF-8 handling, which one might not need, but it blows up the contract file size. Also, for String dynamic allocation is needed, increasing the file size of the contract as well and being expensive in terms of performance. A use-case I have now seen a couple times is to use String to generate some uuid, we should look into an alternative for doing that.

Before this one: https://paritytech.github.io/ink-docs/why-rust-for-smart-contracts.

Follow-up from use-ink/ink#1132.

This is the PR which was in the parity-scale-codec upgrade: paritytech/parity-scale-codec#299, our assumption was that it would decrease gas costs in all example contracts.

Still strange that gas doesn't change for all contracts where the size changed. Is the size change maybe in a path that isn't hit by the waterfall?

Running the Setup process in the Linux (Ubuntu)
Current documentation for setup , directly bring request to install "cargo-contract"

encountered following error

The following warnings were emitted during compilation:

warning: Git command failed with status: exit status: 128
warning: Could not find .git/HEAD searching from /home/acceleration/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-contract-1.2.0 upwards!

error: failed to run custom build command for cargo-contract v1.2.0

Caused by:
process didn't exit successfully: /tmp/cargo-installXRjowk/release/build/cargo-contract-dce69dd49011874b/build-script-build (exit status: 1)
--- stdout
cargo:warning=Git command failed with status: exit status: 128
cargo:rustc-env=CARGO_CONTRACT_CLI_IMPL_VERSION=1.2.0-unknown-x86_64-linux-gnu
cargo:warning=Could not find .git/HEAD searching from /home/acceleration/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-contract-1.2.0 upwards!
Creating template zip: template_dir '/home/acceleration/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-contract-1.2.0/templates/new', destination archive '/tmp/cargo-installXRjowk/release/build/cargo-contract-31cbde62fc603f30/out/template.zip'
Done: /home/acceleration/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-contract-1.2.0/templates/new written to /tmp/cargo-installXRjowk/release/build/cargo-contract-31cbde62fc603f30/out/template.zip

--- stderr
Encountered error: dylint-link was not found!
Make sure it is installed and the binary is in your PATH environment.

You can install it by executing cargo install dylint-link.
warning: build failed, waiting for other jobs to finish...

End of Error

The solution is also found at the end of the error msg , is to install the dylink-link.

Require this to be added into the documentation

Would like to request for others to check if they encounter the same issue.

Not sure this happens only for me or not.
But, even If I push the search box, it doesn't work. So, I cannot search information in the doc which is painful.

I'd appreciated if you would check. Thank you

On the top right button.

Right now the search displays both Spanish + English results. It should just display the results of the language page that the user is on.

If this is just not possible with our current plugin (https://github.com/easyops-cn/docusaurus-search-local), we have to evaluate others.

Currently this is the only information in the docs wrt our metadata format: https://paritytech.github.io/ink-docs/getting-started/building-your-contract/.

We should have a dedicated section which explains the format and its intention in more depth. Ideally we would have a typical foo.contract and just explain every key-value pair.

Answer in the FAQ.

See e.g. https://paritytech.github.io/ink-docs/faq/.

This is most likely because we use relative paths for those images and those stop working if there is a / the end of the URL.

Using an absolute path to / is not possible, since the URL is https://paritytech.github.io/ink-docs/.

Using /ink-docs/ as an absolute path prefix is also not possible, since running the docs locally under http://localhost/ should continue to be possible.

The current examples of upgradeability and call forwarding are confusing, incomplete, and
and some cases misleading.

We should update these examples to show correct behaviour, and to guide contract
developers into using correct patterns.

List of examples that we should aim to provide:

• A basic proxy with delegate_call
• A EIP-1967 based proxy

Concepts we want to illustrate:

• Storage collisions and corruption
• Safe delegate calls
• Effects and implications of different ink::env::CallFlags

### Tasks
- [x] `delegate_call` example
- [x] ~~A EIP-1967 based proxy~~ Achieved by `set_code_hash()`

Before use-ink/ink#1065 constructors in ink! were payable (that is, they accepted a value) by default. For reasons described in that PR this is no longer the default behaviour.

Now, constructors will need to opt into accepting a value through the use of the already existing #[ink(payable)] attribute.

Right now we're in-between releases so links to the latest documentation are changing even during the course of a single PR (see #137). Instead of fixing them all in the PRs we should do one big check once ink! 4.0 is finally released.

We should add a section for frequently asked Rust questions, that don't specifically address an ink! issue, but still come up often.

Examples are:

• I get an error that the Encode trait is missing, what should I do now?
• …

This issue can be tackled after paritytech/substrate#7533 has been implemented.

ToDo

• Add a chapter describing the behavior of the contract pallets storage and code rent.
• Describe how relevant information regarding how much storage the can be accessed from ink!
  • For example: How big is the size the contract's code/storage occupies on the chain? What is the cost? What are relevant constants and thresholds?

Requested by https://github.com/grizzly375.

Add a chapter under "Overview" comparing all of those.

As ink! ecosystem is growing, we have witnessed increased interest and activity in hackathon and education spaces.
I think it would helpful for community to have a calendar with all upcoming educational courses and upcoming hackathons to be present in the calendar format on the website.

Mention the new cargo-contract commands for CLI contract interaction:

• cargo contract upload
• cargo contract instantiate
• cargo contract call

See https://github.com/paritytech/cargo-contract#usage or cargo contract --help for more info.

Hey there, at the moment (at least for me), the search bar in the upper right returns results for both documented ink! versions (3 & 4). And it doesn't even highlight the version. I find it quite counter-intuitive (esp. for newbies) accidentally switching to an earlier version of the documentation without even noticing.

IMO, it should either highlight the version next to the results or (preferred) search should be only within the currently active version of the documentation.

Substrate is unusual from other blockchains because an account nonce can be reset if, for
example, an account's balance drops below the existential deposit for the Substrate chain
it's on.

In other blockchain ecosystems this is not the case, so an account nonce is typically
used to provide replay protection. In Substrate this is done through the use of
transaction mortality.

Since smart contract developers will be coming from different ecosystems we should
document this behaviour for them, and have some possible mitigation.

Here are some resources to help get these docs started:

• Original Substrate issue
• Discussion about UX improvements
• Polkadot transaction mortality docs

ink! 4 is one the upcoming stable releases with backward compatibility and LTS.

With growing community of developers and organised hackathons, tutorial series can provide a better onboarding experience in addition to the documentation.

The idea

• Pre-recorded video tutorials
• 30m length max per video
• The format is "from zero to hero"
• Building a dApp using ink! and relevant frontend tooling
• Transcript and code snippets available on the tutorial page in addition to the video
• A repo of the project with branches for corresponding tutorials

Maybe @sacha-l can help with the recording and @al3mart help with the Spanish translation of the transcript

Follow-up to #145.

Now

Should be

Illustrator + SVG files here.

The font in there should be Montserrat, I think this file still contains the bare text annotated with a font, the svg (or png) on the website should have Montserrat (if svg then as path, and not as text).

In getting-started/setup:

https://github.com/paritytech/ink-docs/blob/9441b53e8bd0baae19b39ecf90f7f9dddeb25594/docs/getting-started/setup.md?plain=1#L65

Gives compilation errors when using nightly 2022-07-20:

$  cargo install contracts-node --git https://github.com/paritytech/substrate-contracts-node.git --tag v0.12.0 --force --locked
    Updating git repository `https://github.com/paritytech/substrate-contracts-node.git`
  Installing contracts-node v0.12.0 (https://github.com/paritytech/substrate-contracts-node.git?tag=v0.12.0#7cd3c5e2)
    Updating crates.io index
   Compiling libc v0.2.121
   
... (some compiling later)

   Compiling pallet-transaction-payment-rpc v4.0.0-dev (https://github.com/paritytech/substrate#3cad018b)
The following warnings were emitted during compilation:

warning: Could not find `Cargo.lock` for `/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime/Cargo.toml`, while searching from `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/build/contracts-node-runtime-238b369d8fd463ef/out`. To fix this, point the `WASM_BUILD_WORKSPACE_HINT` env variable to the directory of the workspace being compiled.
warning: Could not find `Cargo.lock` for `/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime/Cargo.toml`, while searching from `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/build/contracts-node-runtime-238b369d8fd463ef/out`. To fix this, point the `WASM_BUILD_WORKSPACE_HINT` env variable to the directory of the workspace being compiled.

error: failed to run custom build command for `contracts-node-runtime v0.12.0 (/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime)`

Caused by:
  process didn't exit successfully: `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/build/contracts-node-runtime-da5507166d315b2d/build-script-build` (exit status: 1)
  --- stdout
  cargo:warning=Could not find `Cargo.lock` for `/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime/Cargo.toml`, while searching from `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/build/contracts-node-runtime-238b369d8fd463ef/out`. To fix this, point the `WASM_BUILD_WORKSPACE_HINT` env variable to the directory of the workspace being compiled.
  cargo:warning=Could not find `Cargo.lock` for `/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime/Cargo.toml`, while searching from `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/build/contracts-node-runtime-238b369d8fd463ef/out`. To fix this, point the `WASM_BUILD_WORKSPACE_HINT` env variable to the directory of the workspace being compiled.
  Information that should be included in a bug report.
  Executing build command: "rustup" "run" "nightly" "cargo" "rustc" "--target=wasm32-unknown-unknown" "--manifest-path=/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W/release/wbuild/contracts-node-runtime/Cargo.toml" "--color=always" "--profile" "release"
  Using rustc version: rustc 1.64.0-nightly (d68e7ebc3 2022-07-20)


  --- stderr
      Updating crates.io index
      Updating git repository `https://github.com/paritytech/substrate`
     Compiling proc-macro2 v1.0.40

... (some compiling later)

     Compiling contracts-node-runtime v0.12.0 (/Users/lucasvanmol/.cargo/git/checkouts/substrate-contracts-node-cf7c16677784d274/7cd3c5e/runtime)
  error[E0437]: type `TransactionByteFee` is not a member of trait `pallet_transaction_payment::Config`

... (and some more compilation errors)

     error: could not compile `contracts-node-runtime` due to 7 previous errors
warning: build failed, waiting for other jobs to finish...
error: failed to compile `contracts-node v0.12.0 (https://github.com/paritytech/substrate-contracts-node.git?tag=v0.12.0#7cd3c5e2)`, intermediate artifacts can be found at `/var/folders/8t/pz12r_6j2l3bvlmwvx5nl8k80000gn/T/cargo-installj40w4W`

Reccomend upgrade to --tag v0.17.0, which works as normal

We get asked quite often how to pass arguments to chain extensions. We should put this into the chapter on chain extensions.

Solution can be found here: use-ink/ink#1029.

There are a few breaking changes between ink! 3.0 and 4.0. We should write a small guide
about what some of these changes are to make the transition easier for developers.

Non-exhaustive list of things to cover:

• Removal of storage traits (SpreadLayout et.al)
• New storage macros
• CallBuilder/CreateBuilder changes
• ABI changes (version, lang_error, etc.)
• Results from Constructors

The SVG links at this page are broken:

• https://paritytech.github.io/ink-docs/datastructures/img/spread.svg
• https://paritytech.github.io/ink-docs/datastructures/img/packed.svg

We want to have a full-text search in our docusaurus instance. The easiest way to set this up would be to use a third-party service, which regularly indexes registered pages. Since we ideally don't want to have any third-party components a local setup is preferable.

These are two local-search plugins which look promising:

• https://github.com/daldridge/docusaurus-plugin-lunr
• https://github.com/lelouch77/docusaurus-lunr-search

There are probably more though.

We should decide on a plugin and include it into our setup.

We should document the results of use-ink/cargo-contract#696.

The documentation should contain the user perspective of (1) ink! contract developer (2) block explorer.

The info should be along the lines of what @HCastano posted in Element:

To verify the on-chain artifact you need two verification steps. First see if the given code matches the given contract bundle, and then check if the on-chain source matches the given contract bundle. That was you know that the given code matches what's on-chain

The contract you want to verify must have been previously built in a well-known environment, otherwise you may not be able to verify it's validity after the fact

So contain broader context around just executing the verify command.

In use-ink/ink#1111 the collection and lazy module were hidden.

One effect is that the CI of ink-docs is currently broken due to a number of dead links detected:

https://github.com/paritytech/ink-docs/runs/5104398596?check_suite_focus=true (search for Status: 404).

The effect is that no changes committed to this repo will be published to GitHub pages currently (so the version tag in the substrate-contracts-version installation instructions is still the old one, even though I've pushed a commit which updates it).

The ink-docs still contain a lot of mentions of e.g. Lazy:

$ rg Lazy
docs/datastructures/spread-packed.md
32:    b: ink_storage::Lazy<i32>,
52:    b: ink_storage::Lazy<i32>,
69:    b: ink_storage::Lazy<i32>,
96:    b: ink_storage::Lazy<i32>,

docs/datastructures/opting-out.md
14:    b: ink_storage::Lazy<i32>,

docs/datastructures/overview.md
31:The `ink_storage::Lazy` type caches their entities and acts lazily on the storage.
60:In order to prevent this eager loading of storage contents we can make use of `ink_storage::Lazy` or other lazy data structures defined in that crate:
65:    a: ink_storage::Lazy<i32>,
66:    b: ink_storage::Lazy<i32>,
73:            true  => Lazy::set(&self.a, self.offset + new_value),
74:            false => Lazy::set(&self.b, self.offset + new_value),
80:Note that `offset` remained `i32` since it is always needed and could spare the minor overhead of the `ink_storage::Lazy` wrapper.

docs/faq/faq.md
208:### When to use `Lazy<T>` over just `T` for a contract field?
210:The `ink_storage::Lazy` type caches their entities and acts lazily on the storage.

docs/basics/cross-contract-calling.md
23:use ink_storage::Lazy;
30:    other_contract: Lazy<OtherContract>,

docs/basics/mutating-values.md
30:## Lazy Storage Values
32:There is [a `Lazy` type](https://paritytech.github.io/ink/ink_storage/struct.Lazy.html) that can be
34:examples do not require the use of `Lazy` values. Since there is
35:some overhead associated with `Lazy` values, they should only be used where required.
37:This is an example of using the `Lazy` type:
43:    my_number: ink_storage::Lazy<u32>,
50:            my_number: ink_storage::Lazy::<u32>::new(init_value),
56:        ink_storage::Lazy::<u32>::set(&mut self.my_number, new_value);
62:        let cur = ink_storage::Lazy::<u32>::get(my_number);
63:        ink_storage::Lazy::<u32>::set(my_number, cur + add_value);

For collections it will probably be similar.

After use-ink/ink#831 is merged there will be two choices for dynamic memory allocators in ink!. The default is the new bump allocator while the other choice is wee_alloc (which used to be the old default).

The fundamental tradeoff here is .wasm size vs. efficient use of memory.

For someone concerned with running smart contracts on a parachain, size would be the most important consideration. However, if someone is running a standalone chain then memory efficiency might be more important.

The guide should explain:

• The role of a dynamic memory allocator
• The different allocators available
• The trade-offs between the allocators
• How to switch between allocators

Follow-up to a chat in dm's:

…discussion on why we do not write the compiler name down in the WASM blob, why providing mappings between the metadata and the binary is not a problem we want to solve directly in the lang etc.. 😁 maybe this is something for the FAQ

IIRC you also wanted to add a point about "Why is the metadata not on-chain?".

Add a new section "Migration Guides" with a chapter CosmWasm.

The chapter should contain a short comparison of ink! and CosmWasm, as well as a guide on how to migrate a CosmWasm smart contract over to ink!.

This page (among others) shows deprecated instructions for specifying a Selector.

When trying to create a Selector with the following syntax selector = "0xDEADBEEF" on cargo contracts 0.15, the error received is: #[ink(selector = ..)] attributes with string inputs are deprecated. use an integer instead, e.g. #[ink(selector = 1)] or #[ink(selector = 0xC0DECAFE). The docs should probably make mention of the deprecation and offer an up-to-date suggestion.

In the Metadata page the header graphic is using metadata.json. This was changed in use-ink/cargo-contract#952 to be $contract_name.json. We should update the graphic to say hello-world.json instead.

Walk through a typical ink! Cargo.toml and explain the individual entries and dependencies.

There is already a placeholder site under basics/cargo-toml.

There are already some placeholder sites. Add these to sidebar.js to make them visible:

'cargo-contract/deploy',
'cargo-contract/instantiate',
'cargo-contract/call',

The pallet-contracts contains functionality that enables sudo/governance to force-overwrite the contract code of a particular AccountId.

There will eventually be some mishap with a contract on some chain and we introduced a way to force-replace a contract with paritytech/substrate#11451.

We should add an FAQ point "How to ask sudo/governance to force-replace my contract?" that explains how to do this. Ideally with screenshots.