Rename Parathreads -> On-demand Parachains (#5858)

* initial edits * rm parathread terminology where possible * minor edits and reorg * add banner * Bader's feedback * Update docs/build/build-data.md Co-authored-by: Radha <[email protected]> * Update docs/build/build-guide.md Co-authored-by: Radha <[email protected]> * Update docs/build/build-guide.md Co-authored-by: Radha <[email protected]> * Update docs/build/build-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/build/build-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/general/faq.md Co-authored-by: Radha <[email protected]> * Update docs/general/glossary.md Co-authored-by: Radha <[email protected]> * Update docs/general/glossary.md Co-authored-by: Radha <[email protected]> * Update docs/general/polkadot-direction.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-architecture.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-auction.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Update docs/learn/learn-parachains.md Co-authored-by: Radha <[email protected]> * Bader's feedback --------- Co-authored-by: Radha <[email protected]>
w3f · May 7, 2024 · 13fa395 · 13fa395
1 parent 158aa3e
commit 13fa395
Show file tree

Hide file tree

Showing 24 changed files with 194 additions and 242 deletions.
diff --git a/docs/build/build-data.md b/docs/build/build-data.md
@@ -69,7 +69,7 @@ infrastructure and tooling to help users visualize, curate, share, and analyze o
 and is currently live on the [Moonbeam](https://moonbeam.network/) network, bringing visibility to
 billions of blockchain data points to Polkadot via their unified API. The approach to deploying on
 Moonbeam simplifies the development of Polkadot-based blockchain applications as compared to
-implementing a full parachain or parathread.
+implementing a full parachain or an on-demand parachain.
 
 Covalent captures the entire history of blockchains and offers a way to zoom into data points
 recorded in smart contracts that are often not accessible.

diff --git a/docs/build/build-guide.md b/docs/build/build-guide.md
@@ -139,6 +139,16 @@ by design in smart contracts). This vulnerability is mitigated by the
 -- although it places more of a burden on the developer of the parachain to perform properly
 benchmarks.
 
+:::info What is an on-demand parachain?
+
+On-demand parachains use a "pay-as-you-go" model enabled by Agile Coretime to interact with the
+Relay Chain. On-demand parachains will only produce a block when needed, unlike full parachains,
+which have access to bulk coretime to produce a block at every block of the Relay Chain. When building an
+on-demand parachain, you will use the same tools (like PDKs) and get all the benefits of building a
+parachain without the cost drawback of purchasing bulk coretime.
+
+:::
+
 ### Polkadot SDK Overview
 
 Polkadot is built using the Polkadot SDK, which,
@@ -207,6 +217,32 @@ followed by FRAME, with Cumulus as the final step to understanding the entire pa
 process. This way, one can view how various paradigms are applied and decide on integrating or
 utilizing Substrate for their particular use case.
 
+Please see the [parachain development guide](build-parachains.md) for how to get started on building
+a parachain.
+
+#### Parachains Benefits
+
+Parachains contain their own runtime/STF logic and benefit from the shared security and the
+cross-consensus messaging provided by the {{ polkadot: Polkadot :polkadot }} relay chain. Parachains
+permit high flexibility and customization but require more effort to create and maintain over time.
+A production-grade parachain is typically more involved to create due to the complexity involved in
+blockchain networks' technical and economic aspects.
+
+Parachains grant the creators more space to build the monetary system and other chain aspects from
+the ground up. They will allow for a more concise and efficient execution of complex logic than a
+smart contract platform could offer. Parachains also provide more flexibility in the form of
+governance and can perform complete upgrades in a less controversial way than the current process of
+hard forks.
+
+Some examples of features you can have on a parachain:
+
+- Custom fee structure (for example, pay a flat transaction fee or pay per byte).
+- Shared security and finalization via the relay chain (Polkadot or Kusama).
+- Custom monetary policy for the native token and local economy.
+- Treasury to be funded through transitions in your state function.
+- A governance mechanism that could manage a DAO that is responsible for allocating your on-chain
+  treasury.
+
 ### Building a Pallet
 
 While parachains are highly customizable, they are often complex to develop. If you wish to get

diff --git a/docs/build/build-index.md b/docs/build/build-index.md
@@ -20,9 +20,9 @@ the wiki is divided into the following parts:
 
 ## Development Guide
 
-- [Starter's Guide](build-guide.md) - High-level overview on choosing a parachain, parathread, or
-  smart contract for your project and how to get started.
-- [Parachain Development](build-parachains.md) - Tools for building parachains and parathreads.
+- [Starter's Guide](build-guide.md) - High-level overview on choosing a parachain or smart contract
+  for your project and how to get started.
+- [Parachain Development](build-parachains.md) - Tools for building parachains.
 - [Smart Contracts](build-smart-contracts.md) - Tools to deploy contracts to a
   {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} parachain.
 

diff --git a/docs/build/build-parachains.md b/docs/build/build-parachains.md
@@ -130,8 +130,7 @@ good return on investment.
 parachain. They can be incentivized with a native token payout from:
 
 - Transaction fees collected
-- Parathread token sponsorship
-- Blocks are naturally produced when a parathread bid is less than the native token payout.
+- Parachain token sponsorship
 
 ### Para-objects
 
@@ -147,8 +146,7 @@ parallelizable objects.
 
 These could be in the form of:
 
-- System level chains (permanent chains): [leased slots](../learn/learn-auction.md),
-  [parathread pool](../learn/learn-parathreads.md)
+- System level chains (permanent chains): [leased slots](../learn/learn-auction.md)
 - [Bridge](../learn/learn-bridges.md) Hubs
 - Nested Relay Chains
 
@@ -273,7 +271,7 @@ Are you interested in building a PDK? See the [future PDKs](#future-pdks) sectio
 After creating your chain runtime logic with Substrate, you will be able to compile it down to a
 Wasm executable. This Wasm code blob will contain the entire state transition function of your
 chain, and is what you will need to deploy your project to
-{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} as either a parachain or parathread.
+{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} as a parachain.
 
 Validators on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will use the submitted
 Wasm code to validate the state transitions of your chain or thread, but doing this requires some
@@ -289,7 +287,7 @@ performs the critical action of producing new block candidates for your chain an
 Substrate comes with its own networking layer built-in but unfortunately only supports solo chains
 (that is, chains that do not connect to the relay chain). However, there is the Cumulus extension
 that includes a collator node and allows for your Substrate-built logic to be compatible with
-{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} as either a parachain or parathread.
+{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} as a parachain.
 
 ### Future PDKs
 
@@ -386,19 +384,10 @@ To include your parachain into the {{ polkadot: Polkadot :polkadot }}{{ kusama:
 network, you will need to acquire a parachain slot.
 
 Parachain slots will be sold in open auctions, the mechanics of which can be found on the
-{{ polkadot: [parachain auction](../learn/learn-auction.md) :polkadot }}
-{{ kusama: [parachain auction](../learn/learn-auction.md) :kusama }} page of the wiki.
+[parachain auction](../learn/learn-auction.md) page.
 
-### Parathread
-
-Parathreads will not require a parachain slot, so you will not need to engage in the candle auction
-mechanism. Instead, you will be able to register your parathread code to a Relay Chain for a fee and
-from then be able to start participating in the per-block auctions for inclusion of your state
-transition into a Relay Chain.
-
-For more information on how parathread per-block auctions work, see the more detailed
-{{ polkadot: [parathread](../learn/learn-parathreads.md) :polkadot }}
-{{ kusama: [parathread](../learn/learn-parathreads.md) :kusama }} page.
+A parachain can be producing blocks 
+[continuously or on-demand](../learn/learn-parachains.md#parachains-vs-on-demand-parachains).
 
 ## Resources
 

diff --git a/docs/general/faq.md b/docs/general/faq.md
@@ -292,16 +292,16 @@ implementers.
 ### Are parachains ephemeral? What happens when a parachain loses the next auction?
 
 Parachains are not ephemeral. As long as someone is keeping the data for a parachain, the parachain
-can move between being a parachain, a parathread, or a separate sovereign chain at different points
-of its lifetime. Especially with parathreads, parachains can be decommissioned to only produce
-blocks when their usage and throughput makes it necessary.
+can move between being a parachain, an
+[on-demand parachain](../learn/learn-parachains.md#on-demand-parachains), or a separate sovereign
+chain at different points of its lifetime. Especially with on-demand parachains, parachains can
+produce blocks when their usage and throughput makes it necessary.
 
 When a parachain loses an auction for renewal, that parachain has a few options. In most cases,
-becoming a parathread instead would be a suitable choice. Parathreads are still secured by the Relay
-Chain, but don't need to hold a parachain slot and can produce a block when its economically
-feasible for them. For more on parachains please see the
-[parachains page](../learn/learn-parachains.md) and for more on parathreads see
-[the parathreads page](../learn/learn-parathreads.md).
+becoming an on-demand parachain instead would be a suitable choice. On-demand parachains are still
+secured by the Relay Chain, but don't need to hold a parachain slot and can produce a block when its
+economically feasible for them. For more on parachains please see the
+[parachains page](../learn/learn-parachains.md#parachains-vs-on-demand-parachains).
 
 ## Networking
 

diff --git a/docs/general/glossary.md b/docs/general/glossary.md
@@ -31,7 +31,7 @@ parachain candidate block is valid or invalid.
 
 ## Auction (Parachain)
 
-Parachain auctions are how non-common-good parathreads win a slot to become a parachain.
+Parachain auctions are how non-system parachains can access Polkadot.
 
 ## Aura
 
@@ -448,7 +448,7 @@ A [Substrate](#substrate) runtime module.
 
 A blockchain that meets several characteristics that allow it to work within the confines of the
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Host. Also known as "parallelized
-chain."
+chain". All parachains start their life-cycle as a parathread.
 
 ## Parachain Development Kit (PDK)
 
@@ -458,14 +458,13 @@ developers to create {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama
 
 ## ParaID
 
-A unique numeric (non-negative integer) identifier for a parathread.
+A unique numeric (non-negative integer) identifier for a parachain.
 
 ## Parathread
 
-A blockchain that works within the confines of the
-{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Host, thus allowing it to connect to
-the Polkadot Relay Chain. This can be done either by becoming a parachain or connecting on a "pay as
-you go" basis. All parachains start their life-cycle as a parathread.
+Historically, the term "parathread" has been used in two contexts: a substrate-based chain not yet parachain (i.e. not connected to
+a {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} core), or as an on-demand parachain
+(i.e. a parachain using on-demand coretime).
 
 ## Parachain Registry
 

diff --git a/docs/general/polkadot-direction.md b/docs/general/polkadot-direction.md
@@ -33,9 +33,9 @@ the [whitepaper](https://polkadot.network/whitepaper/). Polkadot is:
 - **A multicore computer** where chains that continuously operate in parallel on different cores are
   called [parachains](../learn/learn-parachains.md). Currently, one core is reserved for one chain
   through [slot auction mechanism](../learn/learn-auction.md), although one core can be reserved
-  on-demand to multiple chains at different periods (see
-  [parathreads](../learn/learn-parathreads.md)). At the time of writing (mid 2023), there are around
-  50 cores independently operating in parallel on Polkadot.
+  on-demand to multiple chains at different periods (see the
+  [Agile Coretime page](../learn/learn-agile-coretime.md)). At the time of writing (mid 2024), there
+  are around 50 cores independently operating in parallel on Polkadot.
 
 From now on _application_ will be used as a general term to describe anything that can use a
 Polkadot core to access secure and decentralized computation.

diff --git a/docs/learn/archive/learn-treasury.md b/docs/learn/archive/learn-treasury.md
@@ -74,9 +74,6 @@ The Treasury is funded from different sources:
    inflation to go to the Treasury. In other words, if 50% of all tokens are staked, then 100% of
    the inflation goes to the validators as reward. If the staking rate is greater than or less than
    50%, then the validators will receive less, with the remainder going to the Treasury.
-4. Parathreads: [Parathreads](../learn-parathreads.md) participate in a per-block auction for block
-   inclusion. Part of this bid goes to the validator that accepts the block and the remainder goes
-   to the Treasury.
 
 ## Tipping
 

diff --git a/docs/learn/learn-agile-coretime.md b/docs/learn/learn-agile-coretime.md
@@ -3,7 +3,7 @@ id: learn-agile-coretime
 title: Introduction to Agile Coretime
 sidebar_label: Agile Coretime Intro
 description: Introduction to Agile Coretime and its terminology
-keywords: [coretime, blockspace, parathread, parachain, cores]
+keywords: [coretime, blockspace, parachain, on-demand, cores]
 slug: ../learn-agile-coretime
 ---
 
@@ -73,6 +73,13 @@ Previously known as instantaneous coretime, the on-demand coretime refers to cor
 through bidding in near real-time for the validation of a single parachain block on one of the cores
 reserved specifically for on-demand orders.
 
+:::info Parathreads are renamed to on-demand parachains
+
+On-demand parachains (previously called parathreads) are parachains that buy on-demand coretime and
+use it to access the Relay Chain through the on-demand coretime pool.
+
+:::
+
 ### On-demand Coretime Pool
 
 Set of cores that are available on-demand. Cores reserved through bulk coretime could also be made
@@ -479,7 +486,7 @@ Latency is the only drawback: at low demand, the buyer would receive the coretim
 the Relay Chain, but there’ll be a delay when executed on the Coretime Chain. At times of high
 demand, there will be a queue anyway and this delay matters less.
 
-#### What's the best way for on-demand tasks (previously known as on-demand parachains or parathreads) to regularly send extrinsics to the Relay Chain for allowing a block to be validate?
+#### What's the best way for on-demand tasks (previously known as on-demand parachains) to regularly send extrinsics to the Relay Chain for allowing a block to be validate?
 
 A ready-to-use automated and decentralized method for ordering on-demand coretime is
 currently [being implemented](https://github.com/paritytech/polkadot-sdk/issues/1487). Some teams

diff --git a/docs/learn/learn-architecture.md b/docs/learn/learn-architecture.md
@@ -26,19 +26,19 @@ smart contracts are not supported. The main responsibility is to coordinate the
 including parachains. Other specific work is delegated to the parachains, which have different
 implementations and features.
 
-## [Parachain](learn-parachains.md) and [Parathread](learn-parathreads.md) Slots
+## [Parachain](learn-parachains.md) Slots
 
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can support a number of execution
 slots. These slots are like cores on a computer's processor (a modern laptop's processor may have
 eight cores, for example). Each one of these cores can run one process at a time.
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} allows these slots using two
-subscription models: parachains and parathreads. Parachains have a dedicated slot (core) for their
-chain and are like a process that runs constantly. Parathreads share slots amongst a group, and are
-thus more like processes that need to be woken up and run less frequently.
+subscription models: parachains and on-demand parachains. Parachains have a dedicated slot (core)
+for their chain and are like a process that runs constantly. On-demand parachains share slots
+amongst a group, and are thus more like processes that need to be woken up and run less frequently.
 
 Most of the computation that happens across the
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network as a whole will be delegated
-to specific parachain or parathread implementations that handle various use cases.
+to specific parachain implementations that handle various use cases.
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} places no constraints over what
 parachains can do besides that they must be able to generate a proof that can be validated by the
 validators assigned to the parachain. This proof verifies the state transition of the parachain.
@@ -47,11 +47,11 @@ like smart contracts, privacy, or scalability &mdash; still, others might be exp
 architectures that are not necessarily blockchain in nature.
 
 {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} provides many ways to secure a slot
-for a parachain for a particular length of time. Parathreads are part of a pool that shares slots
-and must-win auctions for individual blocks. Parathreads and parachains have the same API; their
-difference is economic. Parachains will have to reserve
-{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} for the duration of their slot lease;
-parathreads will pay on a per-block basis. Parathreads can become parachains, and vice-versa.
+for a parachain for a particular length of time. On-demand parachains share slots with other
+parachains. Both regular and on-demand parachains have the same API; their difference is economic.
+Parachains will have to reserve {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} for the
+duration of their slot lease; on-demand parachains will pay on a per-block basis. Parachains can
+switch between being on-demand and permanent.
 
 ### [Shared Security](learn-parachains.md)
 

diff --git a/docs/learn/learn-auction.md b/docs/learn/learn-auction.md
@@ -19,8 +19,7 @@ parachain slots. The number of parachain slots is not unbounded on
 available. A limited number of slots are unlocked every few months through on-chain governance. If a
 parachain wants to have guaranteed block inclusion at every Relay Chain block, it must acquire a
 parachain slot. The development of
-[on-demand parachains](https://forum.polkadot.network/t/on-demand-parachains/2208) (previously
-referred to as parathreads) is in progress.
+[on-demand parachains](https://forum.polkadot.network/t/on-demand-parachains/2208) is complete, and they can be deployed after Agile Coretime is live on the network.
 
 The parachain slots will be leased according to an unpermissioned
 [candle auction](https://en.wikipedia.org/wiki/Candle_auction), with several alterations related to

diff --git a/docs/learn/learn-comparisons-cosmos.md b/docs/learn/learn-comparisons-cosmos.md
@@ -48,8 +48,8 @@ checks before committing it to the final chain.
 Parachain slots are limited, and thus parachain candidates participate in an auction to reserve a
 slot for up to two years. For chains that do not have the funding for a parachain slot or the
 necessity to execute with a six-second block time, Polkadot also has
-[parathreads](learn-parathreads.md). Parathreads execute on a pay-as-you-go basis, only paying to
-execute a block when they need to.
+[on-demand parachains](./learn-parachains.md#on-demand-parachains) that execute on a pay-as-you-go
+basis, only paying to execute a block when they need to.
 
 In order to interact with chains that want to use their own finalization process (e.g. Bitcoin),
 Polkadot has [bridge parachains](learn-bridges.md) that offer two-way compatibility.

diff --git a/docs/learn/learn-guides-coretime-marketplaces.md b/docs/learn/learn-guides-coretime-marketplaces.md
@@ -3,7 +3,7 @@ id: learn-guides-coretime-marketplaces
 title: Coretime Marketplaces
 sidebar_label: Coretime Marketplaces
 description: Usage guides for coretime marketplaces
-keywords: [coretime, blockspace, parathread, parachain, cores]
+keywords: [coretime, blockspace, on-demand, parachain, parathread, cores]
 slug: ../learn-guides-coretime-marketplaces
 ---
 

diff --git a/docs/learn/learn-parachains-faq.md b/docs/learn/learn-parachains-faq.md
@@ -44,7 +44,7 @@ significant number of optimizations, and there are
 future. The exact number of parachains that the Relay Chain can support without any degradation in
 performance is yet to be discovered. Also, with the
 [blockspace over blockchains](https://www.rob.tech/polkadot-blockspace-over-blockchains/) paradigm
-which brings parathreads into the picture, there is no hard limit number on the number of
+which brings on-demand parachains into the picture, there is no hard limit number on the number of
 blockchains that can be supported by {{ polkadot: Polkadot :polkadot }}
 {{ kusama: Kusama :kusama }}.
 
@@ -114,9 +114,8 @@ validators.
 ### How will parachain slots be distributed?
 
 Parachain slots are acquirable through auction. For more information on the auction process, please
-see the [parachain slot auctions](learn-auction.md) article. Additionally, some parachain slots will
-be set aside to run [parathreads](learn-parathreads.md) &mdash; chains that bid on a per-block basis
-to be included in the Relay Chain. (Parathreads are not implemented yet.)
+see the [parachain slot auctions](learn-auction.md) article. Additionally, parachains will be able
+to access the Relay Chain [on-demand](./learn-parachains.md#on-demand-parachains).
 
 ### Why doesn't everyone bid for the max length?