5 releases (breaking)

new 0.40.0 Apr 9, 2024
0.39.0 Mar 8, 2024
0.35.0 Nov 16, 2023
0.33.0 Oct 18, 2023
0.31.0 Sep 5, 2023

#869 in Magic Beans

Download history 11/week @ 2023-12-29 12/week @ 2024-01-05 13/week @ 2024-01-12 5/week @ 2024-01-19 6/week @ 2024-01-26 1/week @ 2024-02-02 17/week @ 2024-02-16 26/week @ 2024-02-23 14/week @ 2024-03-01 182/week @ 2024-03-08 123/week @ 2024-03-15 15/week @ 2024-03-22 16/week @ 2024-03-29 114/week @ 2024-04-05

289 downloads per month

Unlicense and GPL-3.0-or-later…

2.5K SLoC


Open in GitHub Codespaces

This repository contains Substrate's node-template configured to include Substrate's pallet-contracts ‒ a smart contract module.

This repository contains a couple of modifications that make it unsuitable for a production deployment, but a great fit for development and testing:

  • The unstable features of the pallet-contracts are enabled by default (see the runtime/Cargo.toml).
  • The consensus algorithm has been switched to manual-seal in #42. Hereby blocks are authored immediately at every transaction, so there is none of the typical six seconds block time associated with grandpa or aura.
    • By default, either manual or instant seal does not result in block finalization unless the engine_finalizeBlock RPC is executed. However, it is possible to configure the finalization of sealed blocks to occur after a certain amount of time by setting the --finalize-delay-sec option to a specific value, which specifies the number of seconds to delay before finalizing the blocks. The default value is 1 second.
      ./target/release/substrate-contracts-node --finalize-delay-sec 5
  • If no CLI arguments are passed the node is started in development mode by default.
  • A custom logging filter is applied by default that hides block production noise and prints the contracts debug buffer to the console.
  • With each start of the node process the chain starts from genesis ‒ so no chain state is retained, all contracts will be lost! If you want to retain chain state you have to supply a --base-path.
  • For pallet_contracts::Config we increased the allowed contract sizes. This avoids running into CodeTooLarge when uploading contracts during development. See the comment in runtime/src/lib.rs for more details.

If you are looking for a node suitable for production see these configurations:


Download Binary

The easiest way is to download a binary release from our releases page and just execute ./substrate-contracts-node.

Build Locally

Follow the official installation steps to set up all Substrate prerequisites.

Afterwards you can install this node via

cargo install contracts-node


To run a local dev node execute


A new chain in temporary directory will be created each time the command is executed. This is the default for this node. If you want to persist chain state across runs you need to specify a directory with --base-path.

See our FAQ for more details: How do I print something to the console from the runtime?.

Connect with frontend

Once the node template is running locally, you can connect to it with frontends like Contracts UI or Polkadot-JS Apps and interact with your chain.

How to upgrade to new Polkadot release

We can have two types of releases:

  • Internal release: This type of release does not involve releasing the crates on crates.io. It involves using Git references in the Cargo.toml dependencies. We utilize this type of release for faster iteration when we don't want to wait for the substrate crates to be released.

  • Crate release: This is the preferable type of release, which involves specifying crate versions in the Cargo.toml dependencies and releasing the crates on crates.io..

  • Check Substrate's node-template, which was renamed after the Polkadot release 1.8.0 to solochain-template, for new commits between the new polkadot release branch and the one this repository is currently synced with. The current branch is mentioned in the last release.
  • Apply each commit that happened in this node-template folder since the last sync.
  • Check parachain-template and apply each commit that has occurred in its folder since the last sync.
  • Check commits for pallet-contracts since the last time someone synchronized this repository with Substrate in order to not miss any important changes.
  • (Crate release only) Execute psvm -p ./Cargo.toml -v X.X.X, to update the dependencies to the required versions. Replace X.X.X with the requested Polkadot release version.
  • (Internal release only) Manually update the dependencies in Cargo.toml to the required Git SHA versions.
  • Increment the minor version number in Cargo.toml and node/Cargo.toml.
  • Execute cargo run --release. If successful, it should produce blocks and a new, up to date, Cargo.lock will be created.
  • Create a PR with the changes, have it reviewed.
  • (Crate release only) Upload crates to crates.io using the commands below, replacing XX with your incremented version number: cargo release 0.XX.0 -v --no-tag --no-push -p contracts-node-runtime -p contracts-parachain-runtime --execute cargo release 0.XX.0 -v --no-tag --no-push -p contracts-node --execute Note: Before uploading, perform a dry run to ensure that it will be successful.
  • Merge the release PR branch.
  • Replace XX in this command with your incremented version number and execute it: git checkout main && git pull && git tag v0.XX.0 && git push origin v0.XX.0. This will push a new tag with the version number to this repository.
  • We have set this repository up in a way that tags à la vX.X.X trigger a CI run that creates a GitHub draft release. You can observe CI runs on GitLab. This draft release will contain a binary for Linux and Mac and appear under Releases. Add a description in the style of "Synchronized with polkadot-v1.8.0 branch." and publish it.


~3M SLoC