PoS structure (WIP)

Author: nadimkobeissi

docs/pos/index.md

@@ -0,0 +1 @@
+# Architecture

docs/technology/pos/api.md

@@ -0,0 +1,108 @@
+# POL
+:::
+
+## General Overview
+
+### What is POL?
+
+POL is the native token upgrade for the Polygon ecosystem, designed for use in a wide range of activities and purposes, including as a tool for network participation and security. By staking POL, participants can actively contribute to the ecosystem as validators. Importantly, POL has many of the same features as MATIC, is built on OpenZeppelin's ERC20 implementations, and supports [<ins>EIP-2612</ins>](https://eips.ethereum.org/EIPS/eip-2612) for signature-based permit approvals.
+
+### Do I Need to Do Anything Today as an Active Participant?
+
+**No**, if you’re currently using MATIC in the Polygon PoS network, there is nothing to do in the near term. 
+
+Separately, you are encouraged to engage in the governance and decision-making processes put forward by the recent PIPs. 
+Your involvement and input can play a significant role in shaping the future of the Polygon ecosystem.
+
+You can participate in governance proposals to vote on various aspects of the Polygon ecosystem through the PIP program.
+Check out how to do so [<ins>here</ins>](/docs/category/proposals/).
+
+### **Do** I Need to Do Anything Today **as a Node Operator or Delegator?**
+
+**No**. You can provide feedback on the proposed changes in the PIPs and monitor Github and the forum for new node software versions to remain compatible with your given chain when PIPs are approved by the community.
+
+### **Do** I Need to Do Anything **Today as an Application or Tooling Developer?**
+
+**No**. You can review the [<ins>PIPs</ins>](https://forum.polygon.technology/t/pip-17-polygon-ecosystem-token-pol/12912) and provide feedback on the proposed changes and analyze if any changes break your smart contracts. Developers for applications on the Polygon PoS should not see any breaking changes.
+
+### When Will POL Be Officially Upgraded?
+
+If the POL proposal is supported by the community, the POL upgrade is estimated to take place in Q4 2023. The systems utilizing MATIC will not begin the transition until Q1 2024, allowing time for a smooth migration/upgrade and stakeholder preparation.
+
+### What is the Initial Amount of POL Tokens?
+
+The initial amount of POL refers to the **total number** of POL when the upgrade occurs. In the case of POL, the initial amount is **10 billion tokens — 1:1** with MATIC since this is an **upgrade**.
+
+## Technical Specifications
+
+### Does the Amount of POL Increase Over Time?
+
+Yes, the amount of POL **will increase**, starting at 3% per year at genesis. Governance may change this rate through an upgrade of the `EmissionManager` contract.
+
+### How is POL Minted?
+
+The `EmissionsManager` smart contract is responsible for initiating the upgrade to POL through a minting process. This contract is upgradeable, allowing for future changes through governance. It also ensures that the `StakeManager` and `Treasury` contracts receive their respective amounts of the newly minted tokens.
+
+### What Determines the Emission Rate?
+
+The emission rate is governed by a variable named `mintPerSecondCap` in the primary POL smart contract. Additionally, the `EmissionManager` contract uses a constant called `INTEREST_PER_YEAR_LOG2` to calculate an **annual emission rate, compounded per year**.
+
+### Can the Emission Rate Be Modified?
+
+Yes, the emission rate can be modified through a governance proposal, but cannot surpass `mintPerSecondCap` in the primary POL smart contract.
+
+### What Considerations Go Into POL’s Design?
+
+The economic design of POL incorporates several key considerations to aim for stability, such as:
+
+- **Community Governance**: Active community participation in governance processes allows for adaptability and responsiveness to changing conditions.
+- **Smart Contract Security**: The integrity of the underlying smart contracts is crucial for maintaining a stable environment.
+
+## Token Migration and Reversal
+
+### What Is the Purpose of Token Migration?
+
+Token migration serves the purpose of allowing for the upgrade from MATIC to POL. This migration operates on a **1-to-1 conversion** basis.
+
+A migration smart contract will allow users to upgrade from MATIC to POL by calling a smart contract function that will accept MATIC and provide an equal amount of POL in return.  The contract is designed to permit the entire supply of MATIC tokens to be upgraded.
+
+### What Happens to the MATIC Tokens After Migration?
+
+MATIC is held in the migration contract and can be used for unmigration.
+
+### Can POL Tokens Be Reverted Back to MATIC?
+
+**Yes**, the migration contract includes a feature known as "unmigration." This allows users to convert their POL to an equivalent amount of MATIC. Governance controls this feature, providing flexibility in response to network conditions or security concerns.
+## Bridging Mechanisms
+
+### How Does the Modified Plasma Bridge Function?
+
+The Plasma Bridge will undergo modifications, with community approval, to change the native token of Polygon PoS to the new POL token. Specifically, the following changes are being proposed:
+
+- **Bridging POL to Polygon PoS**: if you bridge POL tokens to Polygon PoS, you will receive 
+an equal amount of native tokens (POL) on Polygon PoS.
+- **Bridging POL to Ethereum****: when bridging native tokens (POL), the bridge will always disburse POL tokens.
+
+### Are There Any Breaking Changes?
+
+Yes, if an existing contract relies on receiving MATIC from a bridge and receives POL instead, this might result in locked funds. **Developers must check their contracts, verify the transaction lifecycle, and engage on the forum for any doubts.**
+
+## Governance and Security Protocols
+
+### Who Holds the Authority to Govern the POL-based Contracts?
+
+The contracts are governed by the Polygon decentralized governance model. **In accordance with the PIP process, the community can propose changes and provide feedback.**
+
+### What Security Measures Are in Place?
+
+The contracts have been designed with various security measures, including rate limits on minting and the ability to lock or unlock features like unmigration.
+
+## Implications and Safeguards
+
+### How Is POL Used to Reward Ecosystem Participation?
+
+POL's design aims to foster a sustainable and predictable growth model. This model primarily rewards active contributors and participants within the ecosystem.
+
+### How Can I Avoid Scams?
+
+Always verify contract addresses and use reputable platforms for transactions. Exercise extreme caution when dealing with claims like "swaps" or “transfers” from unverified sources.

docs/technology/pos/architecture/index.md

@@ -0,0 +1,31 @@
+# What is Polygon PoS?
+
+Polygon PoS, originally launched as Matic Network, has undergone significant transformations to address the evolving needs of blockchain scalability and security. Initially designed to scale Ethereum through a hybrid Plasma sidechain, the network is currently in the process of transitioning into a ZK-based validium solution on Ethereum. This evolution aims to offer enhanced scalability and robust security features.
+
+In this transformation, Polygon PoS incorporates the execution environment of Polygon zkEVM along with a dedicated data availability layer. The architecture is inherently modular and composable, enabling it to seamlessly integrate into a broader fleet of layer-two scaling solutions. Despite its place in this diverse ecosystem, Polygon PoS will retain its role as a crucial "mainnet," serving as the foundational infrastructure for a wide array of decentralized applications and services.
+
+## How PoS Works Today
+
+### Transaction Lifecycle
+The following cyclical workflow outlines the operational mechanics of today's Polygon PoS architecture:
+
+1. **User Initiates Transaction**: On the Polygon PoS chain, typically via a smart contract function call.
+2. **Validation by Public Plasma Checkpoint Nodes**: These nodes validate the transaction against the Polygon chain's current state.
+3. **Checkpoint Creation and Submission**: A checkpoint of the validated transactions is created and submitted to the core contracts on the Ethereum mainnet.
+4. **Verification by Core Contracts**: Utilizing Fraud Proofs, the core contracts verify the checkpoint's validity.
+5. **Transaction Execution**: Upon successful verification, the transaction is executed and state changes are committed to the Matic Sidechain.
+6. **Asset Transfer (Optional)**: If needed, assets can be transferred back to the Ethereum mainnet via the Plasma Exit Queue in the core contracts.
+7. **Cycle Reiteration**: The process can be initiated again by the user, returning to step 1.
+
+### Core Contracts on Ethereum Mainnet
+Ethereum mainnet serves as the foundational layer upon which Polygon's PoS architecture is built. Within the Ethereum ecosystem, a set of core contracts play a pivotal role in connecting the Polygon PoS chain to Ethereum. These core contracts are responsible for a range of functionalities, from anchoring the Polygon chain to handling asset transfers.
+
+The core contracts on the Ethereum mainnet incorporate two key features for security and functionality: Fraud Proofs and the Plasma Exit Queue. Fraud Proofs act as a security layer, enabling the validation of transactions and state changes to ensure transparency and security across operations. On the other hand, the Plasma Exit Queue manages the safe and efficient transfer of assets back to the Ethereum mainnet, allowing users to seamlessly move assets between the Polygon PoS chain and Ethereum without compromising data integrity or security.
+
+### Public Plasma Checkpoint Nodes
+Public Plasma Checkpoint Nodes serve as the validators in the Polygon PoS architecture. They perform two primary functions: transaction validation and checkpoint submission. When a transaction is initiated on the Polygon PoS chain, these nodes validate the transaction against the current state of the Polygon chain. After validating a set number of transactions, these nodes create a Merkle root of the transaction hashes, known as a "checkpoint," and submit it to the core contracts on the Ethereum mainnet.
+
+The role of these nodes is crucial as they act as a bridge between the Ethereum mainnet and the Polygon PoS chain. They ensure data integrity and security by submitting cryptographic proofs to the core contracts on Ethereum.
+
+### Polygon Sidechain
+The Polygon Sidechain is where the actual transaction processing takes place. Unlike the Ethereum mainnet, which can get congested and has higher transaction costs, the Sidechain offers a more scalable and cost-effective solution. The blocks in the Sidechain are validated by the Public Plasma Checkpoint Nodes and are organized in a manner that allows for high throughput and low latency.