polkadot-sdk is an umbrella crate for the Polkadot SDK, in the sense that it is an "umbrella" that encompasses other components. More specifically, it re-exports all the crates that are needed by builders.

polkadot-sdk aims to be the entry to the Polkadot and Substrate ecosystem and make the SDK more approachable—the entire development environment made available with one dependency. More importantly, it guarantees the compatible combination of crate versions. So even if you know exactly which crates to use, you may still benefit from using polkadot-sdk for painless dependency updates.

You may have seen another umbrella crate named polkadot-sdk-frame. For clarification, while polkadot-sdk aims to ease dependency management, polkadot-sdk-frame intends to simplify FRAME pallet implementation, as demonstrated in the example below.

💻 Usage

The re-exported crates are grouped under the following feature sets.

• node: Anything that you need to build a node
• runtime: Most things that you need to build a runtime
• runtime-full: Also the extended runtime features that are sometimes needed

[dependencies]
polkadot-sdk = { version = "0.12.0", features = ["runtime", "serde"], default-features = false }

[features]
runtime-benchmarks = ["polkadot-sdk/runtime-benchmarks"]
with-tracing = ["polkadot-sdk/with-tracing"]

cargo build --features "runtime-benchmarks,with-tracing"

[dependencies]
polkadot-sdk = { version = "0.12.0", features = ["runtime"], default-features = false }

[features]
try-runtime = ["polkadot-sdk/try-runtime"]

cargo build --features "try-runtime"

[dependencies]
polkadot-sdk = { version = "0.12.0", features = ["runtime", "tuples-96"], default-features = false }

When using polkadot-sdk to build a node, it is a good start to enable the node feature.

[dependencies]
polkadot-sdk = { version = "0.12.0", features = ["node"] }

For a runtime implementation, you need the runtime feature instead. Besides, you may want to opt out of std with default-features = false to allow the runtime to be executed in environments where std isn't available.

[dependencies]
polkadot-sdk = { version = "0.12.0", features = ["runtime"], default-features = false }

When building a runtime or writing an application pallet, polkadot-sdk-frame can be a handy toolkit to start with. It gathers all the common types, traits, and functions from many different crates so that you can import them with a one-liner.

polkadot-sdk-frame is also a part of polkadot-sdk. It is enabled by the runtime feature.

// It's a convention to rename it to `frame`.
use polkadot_sdk::polkadot_sdk_frame as frame;

#[frame::pallet(dev_mode)]
pub mod pallet {
    // Import declarations aren't automatically inherited.
    // Need to "re-import" to make `frame` available here.
    use super::*;
    // One-liner to import all the dependencies used here.
    use frame::prelude::*;

    pub type Balance = u128;

    #[pallet::pallet]
    pub struct Pallet<T>(_);

    #[pallet::config]
    #[pallet::disable_frame_system_supertrait_check]
    pub trait Config: frame_system::Config {}

    #[pallet::storage]
    pub type Balances<T: Config> = StorageMap<_, _, T::AccountId, Balance>;

    impl<T: Config> Pallet<T> {
        pub fn transfer(
            from: T::RuntimeOrigin,
            to: T::AccountId,
            amount: Balance,
        ) -> DispatchResult {
            let sender = ensure_signed(from)?;
            let sender_balance = Balances::<T>::get(&sender).ok_or("NonExistentAccount")?;
            let sender_remainder = sender_balance
                .checked_sub(amount)
                .ok_or("InsufficientBalance")?;

            Balances::<T>::mutate(to, |b| *b = Some(b.unwrap_or(0) + amount));
            Balances::<T>::insert(&sender, sender_remainder);

            Ok(())
        }
    }
}

To learn more about building with the Polkadot SDK, you may start with these guides and our official docs.

🚀 Versioning

We do a stable release for the SDK every three months with a version schema reflecting the release cadence, which is tracked in the release registry. At the time of writing, the latest version is stable2412 (released in 2024 December). To avoid confusion, we will align the versioning of polkadot-sdk with the established schema. For instance, the next stable version will be 2503.0.0.