Runtime Documentation

parachains/README.md

@@ -0,0 +1,22 @@
+# Parachains
+
+This directory is the home of Parity-developed parachain runtimes. This directory is _runtime
+focused,_ and does not include builds of parachain _nodes._
+
+The general internal structure is:
+
+- `chain-specs`: Chain specs for the runtimes contained in its sibling dir `runtimes`.
+- `common`: Common configurations, `impl`s, etc. used by several parachain runtimes.
+- `pallets`: FRAME pallets that are specific to parachains.
+- `runtimes`: The entry point for parachain runtimes.
+
+## Common Good Parachains
+
+The `runtimes` directory includes many, but is not limited to,
+[common good parachains](https://wiki.polkadot.network/docs/learn-common-goods). Likewise, not all
+common good parachains are in this repo.
+
+## Releases
+
+The project maintainers generally try to release a set of parachain runtimes for each Polkadot
+Relay Chain runtime release.

parachains/runtimes/assets/README.md

@@ -0,0 +1,25 @@
+# Assets Parachain
+
+Implementation of _Statemint,_ a blockchain to support generic assets in the Polkadot and Kusama
+networks.
+
+Statemint allows users to:
+
+- Deploy promise-backed assets, both fungible and non-fungible, with a DOT/KSM deposit.
+- Set admin roles to manage assets and asset classes.
+- Register assets as "self-sufficient" if the Relay Chain agrees, i.e. gain the ability for an
+  asset to justify the existance of accounts sans DOT/KSM.
+- Pay transaction fees using sufficient assets.
+- Transfer (and approve transfer) assets.
+- Interact with the chain via its transactional API or XCM.
+
+Statemint must stay fully aligned with the Relay Chain it is connected to. As such, it will accept
+the Relay Chain's governance origins as its own.
+
+See
+[this article](https://www.parity.io/blog/statemint-generic-assets-chain-proposing-a-common-good-parachain-to-polkadot-governance/)
+for a higher level description.
+
+Wallets, custodians, etc. should see
+[the Polkadot Wiki's Integration Guide](https://wiki.polkadot.network/docs/build-integrate-assets)
+for details about support.

parachains/runtimes/assets/statemine/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2021 Parity Technologies (UK) Ltd.
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,7 +13,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Statemine runtime.
+//! # Statemine Runtime
+//!
+//! Statemine is the canary network for its Polkadot cousin, Statemint.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![recursion_limit = "256"]

parachains/runtimes/assets/statemint/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2021 Parity Technologies (UK) Ltd.
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,7 +13,38 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Statemint runtime.
+//! # Statemint Runtime
+//!
+//! Statemint is a parachain that provides an interface to create, manage, and use assets. Assets
+//! may be fungible or non-fungible.
+//!
+//! ## Assets
+//!
+//! - Fungibles: Configuration of `pallet-assets`.
+//! - Non-Fungibles (NFTs): Configuration of `pallet-uniques`.
+//!
+//! ## Other Functionality
+//!
+//! ### Native Balances
+//!
+//! Statemint uses its parent DOT token as its native asset.
+//!
+//! ### Governance
+//!
+//! As a common good parachain, Statemint defers its governance (namely, its `Root` origin), to its
+//! Relay Chain parent, Polkadot.
+//!
+//! ### Collator Selection
+//!
+//! Statemint uses `pallet-collator-selection`, a simple first-come-first-served registration
+//! system where collators can reserve a small bond to join the block producer set. There is no
+//! slashing.
+//!
+//! ### XCM
+//!
+//! Because Statemint is fully under the control of the Relay Chain, it is meant to be a
+//! `TrustedTeleporter`. It can also serve as a reserve location to other parachains for DOT as well
+//! as other local assets.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![recursion_limit = "256"]

parachains/runtimes/assets/westmint/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2021 Parity Technologies (UK) Ltd.
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,7 +13,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Westmint runtime.
+//! # Westmint Runtime
+//!
+//! Westmint is the testnet for Statemint.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![recursion_limit = "256"]

parachains/runtimes/contracts/contracts-rococo/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2018-2021 Parity Technologies (UK) Ltd.
+// Copyright (C) 2018-2022 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
 //
 // This program is free software: you can redistribute it and/or modify
@@ -14,6 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
+//! # Contracts Parachain
+//!
+//! A parachain for using FRAME's `pallet-contracts` and ink! contracts.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 #![recursion_limit = "256"]
 

parachains/runtimes/starters/seedling/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
 // This file is part of Cumulus.
 
 // Cumulus is free software: you can redistribute it and/or modify
@@ -14,6 +14,11 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
+//! # Seedling Runtime
+//!
+//! Seedling is a parachain meant to help parachain auction winners migrate a blockchain from
+//! another consensus system into the consensus system of a given Relay Chain.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 // `construct_runtime!` does a lot of recursion and requires us to increase the limit to 256.
 #![recursion_limit = "256"]

parachains/runtimes/starters/shell/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
 // This file is part of Cumulus.
 
 // Cumulus is free software: you can redistribute it and/or modify
@@ -14,6 +14,13 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
+//! # Shell Runtime
+//!
+//! The Shell runtime defines a minimal parachain. It can listen for a downward message authorizing
+//! an upgrade into another parachain.
+//!
+//! Generally (so far) only used as the first parachain on a Relay.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 // `construct_runtime!` does a lot of recursion and requires us to increase the limit to 256.
 #![recursion_limit = "256"]

parachains/runtimes/testing/rococo-parachain/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
 // This file is part of Cumulus.
 
 // Cumulus is free software: you can redistribute it and/or modify