Merge pull request 0xPolygon#52 from 0xPolygon/empieichO-docs-review

update - intro sections

Author: EmpieichO

docs/cdk/concepts/index.md

@@ -1 +1 @@
-Welcome to Concepts
+Welcome to the Concepts section.

docs/learn/deep-dive-arch.md

@@ -0,0 +1,3 @@
+### Deep-dive into the architecture
+
+For a deep dive into the proposed architecture of Polygon 2.0, please read the blog post [here](https://polygon.technology/blog/polygon-2-0-protocol-vision-and-architecture). More details will be forthcoming and added to this section in the coming months.

docs/learn/index.md

@@ -4,4 +4,26 @@ hide:
 	- toc
 ---
 
-TODO: learn section
+The Polygon Knowledge Layer consists of two parts. Firstly, documents that developers need in order to build with Polygon protocols. Secondly, resources necessary for learning about Polygon technologies.
+
+The Learn section outlines scaling technologies, both live and in-development Polygon protocols, with the intention to display how they will all fit together. 
+As these scaling technologies go live, details of the concepts will in tandem be documented and published.
+
+This section gives you a peek into the future, the Polygon 2.0 vision which is community-driven.
+
+## Polygon 2.0: The basics
+
+Polygon technologies will help developers build in an elastically scalable and unified ecosystem of ZK-powered Layer 2s on Ethereum, where users can create, program and exchange value.
+
+The Polygon 2.0 vision is a unified multichain ecosystem. A web of interoperable ZK-powered Ethereum L2s, with near-instant and atomic L2 <> L2 transactions, and designed to empower developers to build without limitations. Developers will choose to build dApps, design and launch dedicated application-specific L2 chains, or migrate existing EVM Layer 1 chains to become an L2.
+
+The endgame of Polygon 2.0 is for developers to build in an environment that feels and functions more like the internet. This means a blockchain ecosystem that can scale without limit, seamlessly unified, and backed by the decentralization and security of Ethereum.
+
+### Zero-knowledge is the key
+
+Fundamentally, building this web of ZK-powered L2s comes down to one challenge: trustless, off-chain computation. In order to scale Ethereum, one needs to preserve Ethereum’s execution logic while making it more efficient. 
+
+The best way to accomplish this goal is through zero-knowledge cryptography as it is capable of providing verifiable proofs that attest to the integrity of off-chain computations. Otherwise, scaling technologies often have to add additional social-economic mechanisms to mediate off-chain computations. The consequence of which is delayed settlement of transactions.
+
+Polygon 2.0 applies the open source, zero-knowledge scaling technology developed at Polygon Labs, and this will allow Ethereum to scale to the limits of the internet.
+

docs/learn/liquidity-and-scalability.md

@@ -0,0 +1,20 @@
+Polygon 2.0 envisions a network of ZK-powered L2s on Ethereum that unify liquidity across the ecosystem and can scale on demand. Here is how that vision comes into focus.
+
+### Unified liquidity
+
+In an interoperable Polygon ecosystem, access to cross-chain liquidity will be a solved problem. This is due to the in-development interop layer, which is what distinguishes the Polygon ecosystem from other multi-chain scaling architectures. 
+
+The interop layer will be a service that aggregates proofs and coordinates cross-chain transactions between L2 chains built using Polygon technology, enabling unified liquidity. The interop layer expands on the design of the LxLy protocol, currently used by Polygon zkEVM. The core characteristics of the interop layer are:
+
+- Proof aggregation: The aggregator accepts ZK proofs and Message Queues' representations (like Merkle roots) from chains, aggregates these ZK proofs into a single ZK proof, and submits the proof to Ethereum.
+- Atomic cross-chain execution: Bundles of transactions are submitted to many chains in the Polygon network, with the guarantee that all transactions will be successfully executed, or none will be included.
+
+With readily-available liquidity, developers can focus on use-case, rather than bootstrapping users. By abstracting the complexity of cross-chain communication, from the perspective of the end-user, the entire Polygon network will feel like using a single chain.
+
+### Unlimited scale
+
+Polygon CDK is an open source toolkit that allows developers to design and launch ZK-powered chains on demand–or migrate existing EVM-based L1 chains into L2s–backed by the security of Ethereum. In practice, it means unlimited scale in an environment unified through the interop layer.
+
+Existing approaches to an ecosystem of L2s often provide new blockspace at the expense of a chain’s sovereignty. In contrast, Polygon CDK helps developers preserve a chain’s self-determination. The tools available in Polygon CDK are modular: Chains may use any parts of the stack they need, and none that they don’t. Configs will include, but are not limited to, customizable gas tokens, rollup and validium modes, support for different data availability solutions, and more.  
+
+Even as the Polygon ecosystem feels like a single chain, each specific chain will be distinctive, with Polygon PoS, Polygon zkEVM, each Polygon CDK chain, and, eventually, Polygon Miden, providing differentiated feature-sets that will suit some projects more than others.

docs/learn/polygon-protocols.md

@@ -0,0 +1,61 @@
+## Polygon PoS 
+
+Polygon PoS is a widely-adopted EVM-compatible sidechain designed for low transaction costs and fast transaction times.
+
+### Where Polygon PoS is heading
+
+Here is how the proposed development, with consensus of the Polygon community, will be achieved:
+
+- Changes to network architecture. Becoming a zero-knowledge validium instead of a zk-rollup.
+- Changes to network token.
+- Introduction of a Staking Layer, which will eventually serve all L2 chains in the Polygon network.
+
+Polygon 2.0: A pre-PIP discussion for upgrading Polygon PoS to a zkEVM validium is underway. This community discussion is guiding the technical specification of the potential upgrade. If this PIP is accepted, Polygon PoS will eventually plug into the interop layer that will connect the entire Polygon network. 
+
+Phase 0: PIP-18 has suggested a phased approach to implementation of Polygon 2.0. As it relates to Polygon PoS, Phase 0 includes:
+
+- The initiation of the POL upgrade
+- The upgrade from MATIC to POL as the native (gas) token for PoS
+- The adoption of POL as the staking token for Polygon PoS
+- The launch of the Staking Layer and migration of Polygon public chains to consequently leverage it.
+
+## Polygon zkEVM
+
+Polygon zkEVM is a Type-3, EVM-equivalent ZK rollup, which maximizes network security by posting both ZK proofs and transaction data to Ethereum.
+
+### Where Polygon zkEVM is heading
+
+Type 2: The primary goal for Polygon zkEVM is to become a full Type-2 ZK-EVM, supporting all nine precompiled smart contracts and all the opcodes. 
+
+Security: The two near-term priorities for Polygon zkEVM are:
+- Adding support for a forced-transaction mechanism that will make the network censorship-resistant.
+- Lengthening the 10-day timelock for network upgrades.
+
+EVM-equivalence: As EIPs change and shape Ethereum’s execution logic, Polygon zkEVM will evolve to maintain EVM-equivalence. The two most important forthcoming changes are:
+- EIP-4844: Expected in the Cancun hard fork, proto-Danksharding creates a low-cost alternative to CALLDATA, expected to greatly reduce transaction fees on rollups.
+- EIP-7212: A new precompiled contract will support signature verifications in the secp256r1 elliptic curve.
+
+Polygon 2.0: Polygon zkEVM will continue to offer the strongest open source software security guarantees by making transaction data available (DA) on Ethereum. Eventually, Polygon zkEVM will plug into the unified interop layer that will help connect the entire Polygon ecosystem.
+
+## Polygon CDK
+
+Polygon CDK is a collection of open source software components for launching ZK-powered L2 chains on Ethereum. Currently, it supports two primary configurations, rollup mode and validium mode, with an additional customizable data availability committee (DAC) for validium chains. 
+
+### Where Polygon CDK is heading
+
+Upcoming release: The next release of Polygon CDK, expected in Q1 2024, will support a wider set of features and configurations. These include:
+
+- The unified LxLy bridge: As the first phase of the interop layer, projects building with CDK will have the option to plug into the unified LxLy bridge that will, eventually, help connect the entire Polygon ecosystem.
+- Custom native (gas) tokens.
+- Custom allow-lists for smart contracts and transactions.
+- Support for modular, third-party data availability solutions.
+
+## Polygon Miden
+
+Polygon Miden is an in-development, novel ZK rollup designed as a zkVM. Powered by the Miden VM, Polygon Miden extends Ethereum’s feature set, providing throughput and privacy features that are beyond the capabilities of the EVM. 
+
+### Where Polygon Miden is heading
+
+A testnet for Polygon Miden is expected to launch in Q1 2024, with mainnet following later in the year. 
+
+Polygon 2.0: Once Polygon Miden is on mainnet, it will plug into the interop layer that will help connect the entire Polygon ecosystem.

docs/zkEVM/concepts/circom-intro-brief.md

@@ -6,11 +6,11 @@
 
 As seen in the [zkProver Overview](../architecture/zkprover/index.md) document, the output of the STARK Recursion component is a STARK proof.
 
-The next step in the zkProver's process of providing validity proof is to **produce the witness similar to the output of the STARK Recursion**.
+The next step in the zkProver's process of providing validity proof is to produce the witness similar to the output of the STARK Recursion.
 
 Although the zkProver is designed as a state machine emulating the EVM, in order to generate this witness, it makes use of a tool based on the Arithmetic circuits model, called CIRCOM.
 
-**CIRCOM takes the output of the STARK Recursion as input, so as to create its corresponding witness**.
+CIRCOM takes the output of the STARK Recursion as input, so as to create its corresponding witness.
 
 The witness is in turn taken as input to the Rapid SNARK, which is used to generate a SNARK proof published as the validity proof.
 
@@ -50,7 +50,7 @@ CIRCOM is a Domain-Specific Language (DSL) used to define Arithmetic circuits, a
 
 ### CIRCOM as a DSL
 
-As described in the title of its [specifications paper](https://www.techrxiv.org/articles/preprint/CIRCOM_A_Robust_and_Scalable_Language_for_Building_Complex_Zero-Knowledge_Circuits/19374986/1), CIRCOM is a **language for building complex zero-knowledge circuits**.
+As described in the title of its [specifications paper](https://www.techrxiv.org/articles/preprint/CIRCOM_A_Robust_and_Scalable_Language_for_Building_Complex_Zero-Knowledge_Circuits/19374986/1), CIRCOM is a language for building complex zero-knowledge circuits.
 
 It is designed as a low-level circuit language, mimicking the design of electronic circuits, for naturally defining Arithmetic circuits.
 
@@ -66,7 +66,7 @@ However, CIRCOM users can also use templates from [CIRCOMLIB](https://github.com
 
 In addition to being a DSL used to define and create Arithmetic circuits, CIRCOM has a special compiler of Arithmetic circuits into their equivalent R1CS.
 
-The term "CIRCOM" is in fact short for **Circuit Compiler**, implying that the CIRCOM compiler takes an Arithmetic circuit as input and outputs the following:
+The term "CIRCOM" is in fact short for Circuit Compiler, implying that the CIRCOM compiler takes an Arithmetic circuit as input and outputs the following:
 
 - A file with the R1CS description, containing the set of associated R1CS constraints, and
 - A program written either in C++ or WebAssembly, for efficiently computing a valid assignment to all wires of the circuit (the witness).
@@ -124,9 +124,9 @@ c <== a * b;
 
 ### Creation of templates
 
-One of the main peculiarities of CIRCOM is the allowance to define parameterizable small circuits called **templates**.
+One of the main peculiarities of CIRCOM is the allowance to define parameterizable small circuits called templates.
 
-Templates are **parametrizable** in the sense that their outputs depend on free input values (i.e., values that are freely chosen by users).
+Templates are parametrizable in the sense that their outputs depend on free input values (i.e., values that are freely chosen by users).
 
 They are general descriptions of circuits, that have some input and output signals, as well as a relation between the inputs and the outputs.
 
@@ -149,7 +149,7 @@ template Multiplier () {
 
 Although the above code succeeds in creating the `Multiplier template`, the template is yet to be instantiated.
 
-In CIRCOM, the instantiation of a template is called a **component**, and it is created as follows:
+In CIRCOM, the instantiation of a template is called a component, and it is created as follows:
 
 ```
 component main = Multiplier();
@@ -191,7 +191,7 @@ At this stage, either one of the C++ or WebAssembly programs generated by the co
 
 Whichever program is used, needs as input, a file containing a set of valid input values.
 
-Recall that **a valid set of circuit input, intermediate and output values is called the witness**.
+Recall that a valid set of circuit input, intermediate and output values is called the witness.
 
 ### Private and public signals
 
@@ -227,7 +227,7 @@ Note that global inputs are considered `private` signals while global outputs ar
 
 However, the `main` component has a special attribute to set a list of global inputs as public signals.
 
-The rule of thumb is: **Any other input signal not included in this list `{public [s1,..,sn]}`, is considered private**.
+The rule of thumb is: Any other input signal not included in this list `{public [s1,..,sn]}`, is considered private.
 
 ### Concluding CIRCOM's features
 

docs/zkEVM/concepts/index.md

@@ -1 +1,7 @@
-Welcome to the Concepts section.
+This section covers some of the basic concepts crucial to understanding the design approach of Polygon zkEVM. Since Polygon zkEVM emulates the EVM, a few EVM basics are herein detailed.
+
+One of the differences between Polygon zkEVM and Ethereum is in the way their states are recorded. Ethereum uses Patricia Merkle tries while Polygon zkEVM uses Sparse Merkle trees (SMTs). The Concepts section therefore discusses how SMTs are constructed and the Create, Read, Update and Delete operations executed on the SMTs.
+
+The design approach is delineated in terms of an example: the multiplicative Fibonacci state machine. Further details of the Polygon zkEVM design are given in the form of a 'Generic state machine', which involves a program written in zkASM called the ROM.
+
+This section also includes a brief discussion on what CIRCOM is, and how it is used in the zkProver.

docs/zkEVM/get-started/quick-start/connect-wallet.md

@@ -2,16 +2,16 @@
 !!!caution
     Check the list of potential risks associated with the use of Polygon zkEVM in the [Disclosures]() section.
 
-Add the **Polygon zkEVM** network to your wallet in order to interact with either the mainnet or the testnet.
+Connect to either the Polygon zkEVM's mainnet or the testnet. 
 
-Navigate to `Add network` in your wallet, and enter the respective network details as given in the below table:
+Add the Polygon zkEVM network of your choice to your wallet by navigating to `Add network`, and enter the respective network details as given in the below table:
 
 | Network | RPC URL | ChainID | Block Explorer URL | Currency |
 | ------- | ------------------------------- | ---------------- | ---------------- | ----- |
 | Polygon zkEVM | `https://zkevm-rpc.com` | `1101` | `https://zkevm.polygonscan.com/` | **ETH** |
 | zkEVM Testnet | `https://rpc.public.zkevm-test.net` | `1442` | `https://testnet-zkevm.polygonscan.com` | **ETH** |
 
-Here is a video tutorial on **how to add Polygon zkEVM Testnet to MetaMask and deploy smart contracts**:
+Here is a video tutorial on how to add Polygon zkEVM Testnet to MetaMask and deploy smart contracts:
 
 <video loop width="100%" height="100%" controls="true" >
   <source type="video/mp4" src="../../../../img/zkEVM/tutorial.mp4"></source>

docs/zkEVM/get-started/setup-nodes/local-node.md

@@ -1,6 +1,7 @@
-
 Developers who wish to test their own smart contracts, experiment with new code, or simply test a zk-rollup network on their local machines can do so by setting up Polygon zkEVM's local development environment.
 
+Developers can setup a node with either the Polygon zkEVM's mainnet or the testnet.
+
 This tutorial is a guide to setting up a local but single zkEVM node. It is _single_ because it has no connections to external peers. It is a sandbox environment existing only on the user's local machine.
 
 !!!caution

docs/zkEVM/get-started/setup-nodes/production-node.md

@@ -1,6 +1,7 @@
-
 Polygon zkEVM's Mainnet Beta is available for developers to launch smart contracts, execute transactions, and experiment with the network. This tutorial extends the exploration by allowing developers to launch their own production zkNode.
 
+Developers can setup a production node with either the Polygon zkEVM's mainnet or the testnet.
+
 After spinning up an instance of the production zkNode, you will be able to run the Synchronizer and utilize the JSON-RPC interface.
 
 !!!info