From 68d0fff249ef6b0123c83b65c10f5e20304126d0 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Fri, 22 Dec 2023 19:56:03 +0100 Subject: [PATCH 1/6] finish up polkadot doc --- docs/sdk/src/polkadot_sdk/polkadot.rs | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index d157a660e564..3a54c4a94e1f 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -50,7 +50,8 @@ //! correct execution of all parachain, without having all of its validators re-execute all //! parachain blocks. When seen from this perspective, the fact that Polkadot executes different //! parachains means it is a platform that has fully delivered (the holy grail of) "Full Execution -//! Sharding". TODO: link to approval checking article. https://github.com/paritytech/polkadot-sdk-docs/issues/66 +//! Sharding". +//! Learn about [Approval Checking](https://docs.google.com/presentation/d/1fjiTeT33GpxeM9TyBvxFnSVYR9NiU9SrkA2RBxSL5k8) //! * A framework to build blockchains: In order to materialize the ecosystem of parachains, an easy //! blockchain framework must exist. This is [Substrate](crate::polkadot_sdk::substrate), //! [FRAME](crate::polkadot_sdk::frame_runtime) and [Cumulus](crate::polkadot_sdk::cumulus). @@ -60,7 +61,12 @@ //! //! > Note that the interoperability promised by Polkadot is unparalleled in that any two parachains //! > connected to Polkadot have the same security and can have much better guarantees about the -//! > security of the recipient of any message. TODO: weakest link in bridges systems. https://github.com/paritytech/polkadot-sdk-docs/issues/66 +//! > security of the recipient of any message. +//! > Bridges enable transactions and information flow between different blockchain networks, +//! > crucial for Polkadot's multi-chain architecture. However, they can become the network's most +//! > vulnerable points. If a bridge's security measures are weaker than those of the connected +//! > blockchains, it poses a significant risk. Attackers might exploit these weaknesses to launch +//! > attacks such as theft or disruption of services. //! //! Polkadot delivers the above vision, alongside a flexible means for parachains to schedule //! themselves with the Relay Chain. To achieve this, Polkadot has been developed with an @@ -83,5 +89,14 @@ //! Agile periodic-sale-based model for assigning Coretime on the Polkadot Ubiquitous Computer. //! - RFC#5: [Coretime-interface](https://github.com/polkadot-fellows/RFCs/blob/main/text/0005-coretime-interface.md): //! Interface for manipulating the usage of cores on the Polkadot Ubiquitous Computer. -// TODO: add more context and explanations about Polkadot as the Ubiquitous Computer and related -// tech. https://github.com/paritytech/polkadot-sdk-docs/issues/66 +//! +//! ### Polkadot as the Ubiquitous Computer +//! +//! - **Application Space**: for different parachains with their applications +//! - **Accord Space**: for opt-in treaties across chains. Treaty's members cannot change/undermine +//! the treaty's logic. This allows trustless cross-chain applications +//! - **Core space-time**: for "consuming" coretime and using Polkadot computation. Collators send +//! blocks through cores to validators for validity and availability checks +//! - **Coretime**: sold through a broker system parachain +//! +//! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) From bd8b9666ea3479cc039cd343eeebce2d366107a5 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Tue, 26 Dec 2023 14:53:09 +0100 Subject: [PATCH 2/6] add periods --- docs/sdk/src/polkadot_sdk/polkadot.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 3a54c4a94e1f..60887344a836 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -92,11 +92,11 @@ //! //! ### Polkadot as the Ubiquitous Computer //! -//! - **Application Space**: for different parachains with their applications +//! - **Application Space**: for different parachains with their applications. //! - **Accord Space**: for opt-in treaties across chains. Treaty's members cannot change/undermine -//! the treaty's logic. This allows trustless cross-chain applications +//! the treaty's logic. This allows trustless cross-chain applications. //! - **Core space-time**: for "consuming" coretime and using Polkadot computation. Collators send -//! blocks through cores to validators for validity and availability checks -//! - **Coretime**: sold through a broker system parachain +//! blocks through cores to validators for validity and availability checks. +//! - **Coretime**: sold through a broker system parachain. //! //! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) From bb6578df03548a98530dc6479be4a2074f219aa1 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Thu, 28 Dec 2023 16:50:57 +0100 Subject: [PATCH 3/6] small improvements --- docs/sdk/src/polkadot_sdk/polkadot.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 60887344a836..efd323f826e5 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -48,10 +48,10 @@ //! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic //! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the //! correct execution of all parachain, without having all of its validators re-execute all -//! parachain blocks. When seen from this perspective, the fact that Polkadot executes different -//! parachains means it is a platform that has fully delivered (the holy grail of) "Full Execution -//! Sharding". -//! Learn about [Approval Checking](https://docs.google.com/presentation/d/1fjiTeT33GpxeM9TyBvxFnSVYR9NiU9SrkA2RBxSL5k8) +//! parachain blocks. When seen from this perspective, the fact that different Polkadot validators +//! execute different parachains means it is a platform that has fully delivered (the holy grail +//! of) "Full Execution Sharding". +//! Learn about this process called [Approval Checking](https://docs.google.com/presentation/d/1fjiTeT33GpxeM9TyBvxFnSVYR9NiU9SrkA2RBxSL5k8). //! * A framework to build blockchains: In order to materialize the ecosystem of parachains, an easy //! blockchain framework must exist. This is [Substrate](crate::polkadot_sdk::substrate), //! [FRAME](crate::polkadot_sdk::frame_runtime) and [Cumulus](crate::polkadot_sdk::cumulus). From 6f9c5cd6fb4bbecfe41e80c4f915295d697ca73b Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Fri, 29 Dec 2023 16:33:23 +0100 Subject: [PATCH 4/6] add more ubiquitous computer context --- docs/sdk/src/polkadot_sdk/polkadot.rs | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index efd323f826e5..109e3c832791 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -23,7 +23,7 @@ //! //! ## Platform //! -//! In this section, we examine what what platform Polkadot exactly provides to developers. +//! In this section, we examine what platform Polkadot exactly provides to developers. //! //! ### Polkadot White Paper //! @@ -47,7 +47,7 @@ //! Chain*"). //! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic //! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the -//! correct execution of all parachain, without having all of its validators re-execute all +//! correct execution of all parachains, without having all of its validators re-execute all //! parachain blocks. When seen from this perspective, the fact that different Polkadot validators //! execute different parachains means it is a platform that has fully delivered (the holy grail //! of) "Full Execution Sharding". @@ -90,13 +90,21 @@ //! - RFC#5: [Coretime-interface](https://github.com/polkadot-fellows/RFCs/blob/main/text/0005-coretime-interface.md): //! Interface for manipulating the usage of cores on the Polkadot Ubiquitous Computer. //! -//! ### Polkadot as the Ubiquitous Computer +//! ### Polkadot, a Ubiquitous Computer //! +//! Polkadot can be described as a "ubiquitous computer" based on its architecture. It is evolving +//! beyond its initial concept into a platform focusing on blockspace (the fundamental resource +//! chains need) rather than the chains themselves. Polkadot serves as a general-purpose provider +//! for resilient computation, offering a multicore computer-like environment where various +//! parachains operate in parallel on different cores. This approach allows applications to access +//! secure and decentralized computation flexibly and efficiently, marking a shift from a +//! chain-centric to an application-centric ecosystem. +//! +//! We can visualize it as follows: +//! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) //! - **Application Space**: for different parachains with their applications. //! - **Accord Space**: for opt-in treaties across chains. Treaty's members cannot change/undermine //! the treaty's logic. This allows trustless cross-chain applications. //! - **Core space-time**: for "consuming" coretime and using Polkadot computation. Collators send //! blocks through cores to validators for validity and availability checks. //! - **Coretime**: sold through a broker system parachain. -//! -//! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) From 61c90ac351e0d8a0d8f549416961fd359272f87a Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Fri, 29 Dec 2023 17:11:56 +0100 Subject: [PATCH 5/6] improve "space" layers description --- docs/sdk/src/polkadot_sdk/polkadot.rs | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 109e3c832791..44533a21a408 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -100,11 +100,17 @@ //! secure and decentralized computation flexibly and efficiently, marking a shift from a //! chain-centric to an application-centric ecosystem. //! -//! We can visualize it as follows: +//! #### We can visualize it as follows //! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) -//! - **Application Space**: for different parachains with their applications. -//! - **Accord Space**: for opt-in treaties across chains. Treaty's members cannot change/undermine -//! the treaty's logic. This allows trustless cross-chain applications. -//! - **Core space-time**: for "consuming" coretime and using Polkadot computation. Collators send -//! blocks through cores to validators for validity and availability checks. -//! - **Coretime**: sold through a broker system parachain. +//! Let's break down the "space" layers from the above diagram: +//! - **Application Space**: This is the space where each parachain's application logic lives as an +//! independent, but interconnected, blockchain. +//! - **Accord Space**: Is the space for opt-in treaties across chains. Treaty's members cannot +//! change/undermine the treaty's logic. This allows trustless cross-chain applications. +//! - **Core Space-time**: This can be seen as the CPU of the Polkadot Ubiquitous Computer, where +//! the processes are queued and executed. In oder words, we can say that the *Core Space-time* +//! "consumes" *Coretime* using Polkadot computation. Here is where collators send blocks through +//! cores to validators for validity and availability checks. +//! +//! Additionally, this introduces the concept of **Coretime**. Coretime is the right to use +//! Polkadot's computing power. Sold through a broker system parachain. From caf4d152d11c9214390ac968709754a9fc50a2a6 Mon Sep 17 00:00:00 2001 From: Juan Girini Date: Tue, 2 Jan 2024 07:47:59 -0300 Subject: [PATCH 6/6] simplify docs --- docs/sdk/src/polkadot_sdk/polkadot.rs | 38 ++++++--------------------- 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 44533a21a408..61a6877696cb 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -48,10 +48,11 @@ //! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic //! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the //! correct execution of all parachains, without having all of its validators re-execute all -//! parachain blocks. When seen from this perspective, the fact that different Polkadot validators -//! execute different parachains means it is a platform that has fully delivered (the holy grail -//! of) "Full Execution Sharding". -//! Learn about this process called [Approval Checking](https://docs.google.com/presentation/d/1fjiTeT33GpxeM9TyBvxFnSVYR9NiU9SrkA2RBxSL5k8). +//! parachain blocks. When seen from this perspective, Polkadot achieves the ability to verify +//! the validity of the block execution of multiple parachains using the same set of validators as +//! the Relay Chain. In practice, this means that the shards (parachains) share the same economic +//! security as the Relay Chain. +//! Learn about this process called [Approval Checking](https://polkadot.network/blog/polkadot-v1-0-sharding-and-economic-security#approval-checking-and-finality). //! * A framework to build blockchains: In order to materialize the ecosystem of parachains, an easy //! blockchain framework must exist. This is [Substrate](crate::polkadot_sdk::substrate), //! [FRAME](crate::polkadot_sdk::frame_runtime) and [Cumulus](crate::polkadot_sdk::cumulus). @@ -62,8 +63,8 @@ //! > Note that the interoperability promised by Polkadot is unparalleled in that any two parachains //! > connected to Polkadot have the same security and can have much better guarantees about the //! > security of the recipient of any message. -//! > Bridges enable transactions and information flow between different blockchain networks, -//! > crucial for Polkadot's multi-chain architecture. However, they can become the network's most +//! > Bridges enable transaction and information flow between different consensus systems, crucial +//! > for Polkadot's multi-chain architecture. However, they can become the network's most //! > vulnerable points. If a bridge's security measures are weaker than those of the connected //! > blockchains, it poses a significant risk. Attackers might exploit these weaknesses to launch //! > attacks such as theft or disruption of services. @@ -90,27 +91,4 @@ //! - RFC#5: [Coretime-interface](https://github.com/polkadot-fellows/RFCs/blob/main/text/0005-coretime-interface.md): //! Interface for manipulating the usage of cores on the Polkadot Ubiquitous Computer. //! -//! ### Polkadot, a Ubiquitous Computer -//! -//! Polkadot can be described as a "ubiquitous computer" based on its architecture. It is evolving -//! beyond its initial concept into a platform focusing on blockspace (the fundamental resource -//! chains need) rather than the chains themselves. Polkadot serves as a general-purpose provider -//! for resilient computation, offering a multicore computer-like environment where various -//! parachains operate in parallel on different cores. This approach allows applications to access -//! secure and decentralized computation flexibly and efficiently, marking a shift from a -//! chain-centric to an application-centric ecosystem. -//! -//! #### We can visualize it as follows -//! [![Polkadot as the Ubiquitous Computer](https://pbs.twimg.com/media/F3qCltlWkAECsWJ?format=jpg&name=medium)](https://twitter.com/filippoweb3/status/1692025249070563413) -//! Let's break down the "space" layers from the above diagram: -//! - **Application Space**: This is the space where each parachain's application logic lives as an -//! independent, but interconnected, blockchain. -//! - **Accord Space**: Is the space for opt-in treaties across chains. Treaty's members cannot -//! change/undermine the treaty's logic. This allows trustless cross-chain applications. -//! - **Core Space-time**: This can be seen as the CPU of the Polkadot Ubiquitous Computer, where -//! the processes are queued and executed. In oder words, we can say that the *Core Space-time* -//! "consumes" *Coretime* using Polkadot computation. Here is where collators send blocks through -//! cores to validators for validity and availability checks. -//! -//! Additionally, this introduces the concept of **Coretime**. Coretime is the right to use -//! Polkadot's computing power. Sold through a broker system parachain. +//! Learn more about [Polkadot as a Computational Resource](https://wiki.polkadot.network/docs/polkadot-direction#polkadot-as-a-computational-resource).