The Polygon Wiki serves as the central source of truth for Polygon. Spearheaded by Polygon Labs, it is a community-centric initiative that aims to provide the most current and comprehensive resources for those interested in learning about, developing on, or maintaining projects within the Polygon ecosystem.
| ❗ Please note that the first half of this README provides an overview of Polygon, while the second half focuses on the repository and source. |
|---|
- Polygon Overview
- Repository Overview
This section provides a comprehensive introduction to Polygon, its evolution, and its stack of solutions. It aims to give readers a clear understanding of what Polygon is, its strategic focus areas like Polygon 2.0, and the various components that make up its ecosystem.
Polygon is a pioneering blockchain protocol engineered to act as a universal layer for digital value exchange.
Originally launched as Matic Network with the goal of scaling Ethereum through a hybrid Plasma sidechain, Polygon has undergone a transformative evolution. It has matured into a comprehensive suite of protocols designed to enhance Ethereum's scalability and versatility. This strategic transformation was not an arbitrary decision; it was a calculated move backed by extensive research and testing, all aimed at addressing the diverse needs of various applications. In addition, the advent of zero-knowledge technology (zk-tech) marked a significant milestone, indicating that blockchains are now well-equipped to serve enterprise-level applications and drive mass adoption.
These various solutions are meant to function as not separate protocols; they are components of one unified Polygon protocol. The next iteration of the protocol aims to refine and integrate these components to drive mass adoption.
Building on these advancements, Polygon Labs has introduced "Polygon 2.0," a specialized protocol designed to establish a universal value layer for the internet. It achieves this by interconnecting a network of Layer 2 solutions, all of which are unified by seamless liquidity. In doing so, Polygon 2.0 seeks to push the boundaries of what blockchain technology can achieve, featuring:
- Universal Blockchain Access: Democratizes access to blockchain technology, paving the way for mass adoption.
- Ethereum Synergy: Aligns closely with Ethereum's roadmap to augment both scalability and functionality.
- Fluid Liquidity: Establishes a cohesive liquidity ecosystem that seamlessly integrates various Layer 2 solutions.
- Interoperable Messaging & Composability: Facilitates smooth communication and interaction across a diverse range of product suites and blockchain-based solutions.
- Adaptive Modularity: Provides a flexible architecture that allows for easy customization and future upgrades.
- Near-Instant Transaction Finality: Guarantees quick and reliable transaction confirmations, enhancing the overall user experience.
As of today, Polygon offers a diverse range of solutions and products designed to meet various blockchain needs. Below are the key components of the current Polygon stack:
The Proof-of-Stake (PoS) Mainnet serves as the backbone of Polygon's Layer 2 scaling solutions. It provides a secure and efficient platform for decentralized applications and transactions.
zkEVM is Polygon's zero-knowledge-based Ethereum Virtual Machine. It aims to bring scalability and privacy to Ethereum-compatible blockchains.
Supernets are application-specific chains that operate on the Polygon Edge consensus client with PolyBFT consensus. They offer scalability and interoperability for decentralized applications.
Miden is a fully EVM-compatible zk-rollup. It aims to provide a scalable and secure Layer 2 solution with the benefits of zero-knowledge proofs.
Polygon ID is a decentralized identity solution that aims to provide secure and verifiable identity management on the blockchain.
These components collectively form the current stack of Polygon, each serving specific needs while contributing to the ecosystem's overall scalability, security, and interoperability.
Polygon 2.0 is designed with a multi-layered architecture to provide a comprehensive solution for scalability, security, and interoperability. The architecture is composed of four core layers:
The Staking Layer serves as the backbone of the network, providing security and consensus. It is responsible for validator management and staking operations, ensuring the overall integrity of the network.
The Interop Layer focuses on enabling seamless communication between different blockchain networks. It employs the LXLY bridge to facilitate the transfer of assets and data across multiple Layer 2 solutions and even other Layer 1 blockchains.
This layer is where all the computation takes place. It supports various execution environments like zkEVM, zk-Rollups, and more, allowing developers to choose the best fit for their applications.
The Proving Layer is responsible for generating cryptographic proofs for the executed transactions. These proofs are then verified by the Staking Layer to finalize transactions.
Together, these layers work in harmony to offer a scalable, secure, and interoperable ecosystem, pushing the boundaries of what blockchain technology can achieve.
The modular nature of Polygon 2.0 allows developers to mix and match different components from each layer, creating a tailored solution for their specific application. This modularity extends to consensus mechanisms, execution environments, and data availability options.
Polygon 2.0 is designed to be future-proof, with the ability to integrate new technologies as they emerge. This ensures that the framework remains at the forefront of the rapidly evolving blockchain landscape.
The following diagram illustrates the various layers of Polygon 2.0.
Polygon 2.0 introduces a forward-looking framework for decentralized governance, aiming to give the community full control over the Polygon network. This governance model is inspired by proven blockchain governance systems, particularly Ethereum's. The framework is built on three main pillars: Protocol Governance, System Smart Contracts Governance, and Community Treasury Governance.
-
Protocol Governance: The Polygon Improvement Proposal (PIP) framework serves as an open platform for the development of Polygon protocols. In Polygon 2.0, the PIP framework will cover the entire permissionless stack, allowing the community to propose and research upgrades.
-
System Smart Contracts Governance: This pillar focuses on the upgradeability of protocol components implemented as smart contracts. An Ecosystem Council, governed by the community, will be responsible for these upgrades. The council will operate under a tailor-made governance framework designed for secure and scalable decision-making.
-
Community Treasury Governance: A self-sustainable Community Treasury will be established to fund public goods and support promising ecosystem projects. The governance of this treasury will evolve from an initial board to more explicit community-driven governance mechanisms.
Community feedback and participation are integral to the governance process. Various channels, including forum posts and community calls, are used to gather feedback from validators, users, infrastructure providers, and dApp developers.
Polygon's native token, MATIC, has been pivotal in the network's growth since its inception in 2020. With the introduction of Polygon 2.0, a new token, POL, is proposed as a technical upgrade to MATIC. POL is designed to be a third-generation hyperproductive token, offering a range of utilities and incentives to its holders.
-
Third-Generation Token: POL introduces the concept of hyperproductive tokens. Unlike first and second-generation tokens, POL enables its holders to validate multiple chains and assume multiple roles within those chains, thereby offering practically unlimited opportunities.
-
Major Benefits: POL aims to provide ecosystem security, infinite scalability, and community ownership without introducing friction for users and developers.
-
Multifold Utility and Incentives: Validators are required to stake POL to join the validator set. Once staked, they can validate any Polygon chain and establish multiple streams of incentives, including protocol rewards, transaction fees, and additional rewards.
-
Future-Proof Ecosystem: POL will have a continuous emission to fund a Community Treasury, which will be governed by the Polygon community. This treasury will support protocol development, research, ecosystem grants, and adoption incentives.
-
Seamless Upgrade: The transition from MATIC to POL will be facilitated through a simple technical action. Token holders will send MATIC to an upgrade smart contract, which will automatically return the equivalent amount of POL.
Polygon's blockchain development framework to build soverign blockchains have evolved significantly over time, each iteration bringing new features and capabilities. Below is a comparative table that outlines the key differences and features of Polygon Edge, Supernets, and the latest Chain Development Kit (CDK).
| Feature | Edge | Supernets | CDK |
|---|---|---|---|
| Layer | Layer 3 | Layer 3 | Layer 2 |
| Consensus | IBFT | PolyBFT | zk-based / PolyBFT |
| Focus | App-Chains | App-Chains, Infrastructure, & Customizations | App-Chains, Infrastructure, Customizations, Modular Development, Cost-Reduction |
| Security | Inherits from PoS | Theoretically Inherits from Rootchain + Ethereum | Inherits from Ethereum |
| Scalability | Limited | Extended Block Space | Boundless |
| Interoperability | Limited | Custom Native Bridge | Universal Layered Bridge |
| Governance | N/A | Customizable | Customizable |
| Data Availability | On-chain | On-chain | Customizable |
| Modularity | Limited | Limited | Yes |
| Components | Edge client + core contracts on Ethereum | Edge client + EVM-based rootchain + sovereign core contracts | zkValidium, zk-Rollup, & Polygon 2.0 |
-
Polygon Edge: Initially served as an SDK for launching app-chains to build Ethereum compatible blockchain networks, functioning as Layer 3 solutions.
-
Polygon Supernets: Evolved from Edge to tackle the complexities of infrastructure development and bootstrapping for app-chains. Supernets also provide enhanced interoperability and customization options, also operating as Layer 3 solutions.
-
Polygon CDK: The most recent and sophisticated iteration, the CDK concentrates on Layer 2 solutions. It embodies modularity and customization, leveraging cutting-edge protocol primitives from Polygon 2.0. This enables developers to architect chains tailored to their unique requirements.
Explore the core codebases that power the Polygon ecosystem. This section provides quick links and descriptions for our most essential repositories, serving as a starting point for developers, enterprises, and community members alike.
| Category | Repository Name | Description |
|---|---|---|
| Edge | Polygon Edge | A repository for Polygon's edge services. |
| CDK | CDK Validium Node | A CDK for Validium node deployment. |
| CDK Data Availability | A CDK for data availability solutions. | |
| CDK Validium Contracts | Smart contract implementation which will be used by Supernets2. | |
| Core | Core Contracts | Smart contracts that form the core of the Polygon network. |
| DApps and Explorers | DApp Explorer Polygon | A DApp explorer for the Polygon network. |
| Bridges and Interoperability | PoS ZkEVM Bridge | A bridge for ZkEVM in a PoS environment. |
| Tools | Gas Swapper | A tool for gas swapping. |
| Indicia | A repository for Indicia, a Polygon service. | |
| ZkEVM | ZkEVM Wrapper | Wrapper contracts for transferring ETH and ERC20 tokens to ZkEVM. |
| Economic Models | Polygon 2.0 Economic Model | A simulation model to study validator incentives and ecosystem security in Polygon 2.0. |
| Category | Repository Name | Description |
|---|---|---|
| Prover | zkEVM Prover | Prover for ZkEVM. |
| Node | zkEVM Node | Node implementation for ZkEVM. |
| Contracts | zkEVM Contracts | Smart contracts for ZkEVM. |
| Bridge Service | zkEVM Bridge Service | Bridge service for ZkEVM. |
| PIL Libraries | PIL2 Stark JS | JavaScript library for PIL2 STARKs. |
| PILCOM | PILCOM library for ZkEVM. | |
| Test Vectors | zkEVM Test Vectors | Test vectors for ZkEVM. |
| Common Libraries | zkEVM CommonJS | CommonJS library for ZkEVM. |
| Communication Protocols | zkEVM Comms Protocol | Communication protocol for ZkEVM. |
| JavaScript Provers | zkEVM ProverJS | JavaScript prover for ZkEVM. |
| Goldilocks | Goldilocks | Goldilocks library for ZkEVM. |
| PIL STARK | PIL STARK | PIL STARK library for ZkEVM. |
| ROM | zkEVM ROM | Read-Only Memory for ZkEVM. |
| ASM Compiler | zkASMCOM | ZkASM compiler for ZkEVM. |
| Category | Repository Name | Description |
|---|---|---|
| Core Components | Heimdall | Heimdall layer for PoS Network. |
| Bor | Bor node for PoS Network. | |
| Tendermint | Tendermint fork for PoS consensus engine. | |
| Cosmos SDK | Cosmos SDK fork for PoS Network. | |
| Token Management | Polygon Token List | A list of tokens on the PoS network. |
| Polygon Token Assets | Token assets for the PoS network. | |
| Subgraphs | Subgraphs | Subgraphs for PoS Network. |
| CLI Tools | Matic CLI | Command-line interface for PoS Network. |
| Polygon CLI | Command-line interface for Polygon. | |
| Gas Management | Matic Gas Station | Gas station for PoS Network. |
| Portals and Bridges | PoS Portal | Proof of Stake portal for PoS Network. |
| Proposals | Polygon Improvement Proposals | Repository for Polygon Improvement Proposals. |
| SDKs and Libraries | Matic.js | JavaScript library for PoS Network. |
| DevOps | Node Ansible | Ansible scripts for node management. |
| Terraform Polygon Supernets | Terraform scripts for Polygon Supernets. | |
| Contracts | Contracts | Smart contracts for PoS Network. |
| Genesis Contracts | Genesis contracts for PoS Network. | |
| Proofs and APIs | Proof Generation API | API for proof generation. |
| Erigon | Erigon | Erigon Ethereum client. |
| Policies | Policy at Polygon | Policies at Polygon. |
This section delves into the specifics of this repository, explaining its structure, the types of files and folders it contains, and how to navigate it. It serves as a guide for developers and contributors who are interested in the source code, documentation, or contributing to the project.
In sync with the ongoing advancements of Polygon 2.0, the Polygon documentation platform is also slated for significant enhancements. Originally conceived as a "Developer Hub," the platform evolved into a "Wiki" in an attempt to effectively meet the distinct needs of various projects.
While termed a "Wiki," the platform transcends the traditional scope of a wiki, serving as more than just a repository of information. This is because it aims serve as a versatile platform that accommodates different types of technical content and the diverse needs and stages of project development.
- Unified Experience: Seamlessly integrated with the main Polygon website, the documentation will feature a new, dynamic learning experience. The source will maintain its independent existence for continued integrity and versatility.
- Dynamic Documentation: Transition from a static information repository to an interactive, dynamic knowledge platform.
- Enhanced Learning Experience: Intuitive and enriching content tailored to facilitate learning, whether you're a beginner or an expert.
- User-Centric Design: Improved information architecture and navigation, designed with different user personas in mind, all guided by principles of developer advocacy and product development.
The Polygon community is committed to offering a comprehensive and current resource that helps users stay at the cutting edge of blockchain technology. Watch this space for more updates.
The Polygon Wiki is built using Docusaurus, making it easy to serve and host its static files.
The deployment process for the Polygon Wiki involves two environments: staging and prod. Both environments are configured to run against the main branch of the repository.
Any deployment—whether to Staging or Production—requires explicit authorization from an admin of the repository.
- Staging: This environment is used for testing and quality assurance. Changes are deployed here first to ensure they meet the required standards before moving to Production.
- Production: This is the live environment accessible to the end-users. Deployments to Production are made after successful validation in the Staging environment.
The documentation utilizes Algolia's DocSearch to provide a powerful and user-friendly search experience. DocSearch is specifically designed to improve navigation in documentation websites, making it easier for users to find the information they need.
Google Analytics is integrated into the platform to monitor user interactions and collect valuable data. This helps in understanding user engagement and behavior, thereby aiding in the continuous improvement of the documentation. For those curious about how data is handled, please refer to our Terms of Use.
| ❗ The Wiki is undergoing a reorganization and update. Translation efforts will resume upon completion of this revamp. |
|---|
This section provides an overview of the various files and folders in the Polygon Wiki repository, explaining the purpose of each.
| Name | Purpose |
|---|---|
.git, .github |
Manage git configurations and GitHub-specific settings. |
README.md |
The main introduction file for the Polygon Wiki repository. |
sidebars.js |
Used to modify the sidebar navigation. |
docusaurus.config.js |
Configuration file for website layout and other Docusaurus settings. |
src/pages/index.js |
Used to modify the blocks structure and footer links. |
yarn.lock |
Yarn lock file to keep track of all package versions. |
package.json |
Specifies dependencies and scripts for the project. |
node_modules/ |
Contains all the npm packages and dependencies. |
build/ |
Contains static content generated for deployment. |
docs/ |
Contains the Markdown files that make up the content of the Wiki. |
static/ |
Contains static assets like images, CSS, and fonts. |
translations/ |
Contains files for managing different languages. |
Note: This is a general overview and the actual repository may contain additional files and folders for specific functionalities.
GitHub labels are used to categorize the urgency and importance of issues. These priority levels are set by the documentation team based on the following criteria:
| Label | Impact Level | Resolution Time | Example Use Case |
|---|---|---|---|
| P0 | Critical ("Urgent"): Requires immediate attention | Same day: Drop all other tasks and resolve immediately | The website is down, causing a severe impact on the business. |
| P1 | High ("Important"): Significant business impact | Within 3 days: Must be addressed promptly | An API endpoint is changing, requiring immediate documentation updates. |
| P2 | Medium ("Sometime Soon"): Scheduled or planned | Within 2-3 weeks: Can be scheduled for near-term completion | Upcoming addition of a new method to a project API. |
| P3 | Low ("Nice to Have"): Suggestions or conceptual updates | No set deadline: Address when possible | A suggested blog post on the advantages of decentralization for developers. |
The Documentation team at Polygon Labs are the primary maintainers of the Polygon Wiki and will review all issues and pull requests created in this repository. If you spot typos or grammar mistakes, please go ahead and submit a pull request with the fixes. For bigger changes, it's a good idea to start with a GitHub issue to discuss it with the maintainers. We generally prefer pull requests over issues for suggesting changes to the Wiki.
| ❗ We've set up guidelines to make sure all new contributions keep improving the Wiki without compromising its quality. They are available here. |
|---|
Before making a contribution, please consult any existing issues or initiate a new discussion to ensure alignment with the Wiki's objectives. Once you've done that, you'll find that your contributions can significantly enrich the Wiki in the following ways:
-
General Overviews: Introductory pieces that offer a holistic understanding of Polygon's ecosystem, including its core infrastructure and Layer 2 solutions.
-
Technical Deep Dives: In-depth articles that explore specific components of Polygon's architecture, such as its protocol layers, primitives, and consensus algorithms.
-
Use-Case Scenarios: Articles that showcase real-world applications of Polygon in various sectors like DeFi, NFTs, supply chain, and more.
-
Interoperability Explainers: Contributions that clarify how Polygon interfaces with other blockchain ecosystems, Layer 1 solutions, or cross-chain platforms.
-
Tooling: Documentation or guides on tools that facilitate development, testing, or deployment on Polygon. This could include IDE plugins, testing frameworks, or monitoring tools.
-
Third-Party Services: Information on external services that integrate with Polygon, such as oracles, data analytics platforms, or liquidity providers.
-
Community Contributions: Lists of active Polygon communities, educational resources, or upcoming events that enrich the ecosystem.
-
Governance & Economics: Insights into the governance model and tokenomics that underpin Polygon's network.
-
Security Practices: Guidelines and resources for ensuring the security and integrity of dApps, smart contracts, and general infrastructure on Polygon.
-
Troubleshooting Guides: Solutions to common challenges, FAQs, and other resources that assist both newcomers and experienced users.
-
Emerging Technologies: Articles on upcoming features, Layer 2 advancements, or experimental technologies that are in the Polygon pipeline.
| ❗ Note: The Polygon Wiki includes third-party content. Please review the Third-Party Content Disclaimer for details. |
|---|
Contributing to the Polygon Wiki is straightforward. You'll need a GitHub account and a basic understanding of Markdown syntax to get started.
- Locate the Page: Visit the Polygon Wiki page you wish to edit.
- Navigate to the Bottom: Scroll to the bottom of the page.
- Edit Link: Click on the Edit this page link. This will redirect you to the corresponding Markdown file on GitHub.
- Edit Mode: Once on GitHub, click the pencil icon located in the upper-right corner to enter edit mode.
- Make Edits: Modify the Markdown file as needed.
- Initiate Pull Request: Scroll to the bottom and click on Create pull request.
- Title Your PR: Give your pull request a descriptive title. For instance, if you're editing the "Getting Started" page, you could title it Update /docs/develop/getting-started.md.
- Describe Changes: In the pull request description, specify the issue your changes resolve.
See GitHub Docs on Linking a Pull Request to an Issue for guidance.
- Additional Information: Provide a concise summary of the changes you've made. Include screenshots or references if applicable.
- Submit: Click Propose changes to finalize your pull request. This will create a new branch in your fork.
A Polygon Wiki maintainer will review your pull request. If approved, it will be merged into the main branch.
Prerequisites:
-
Fork the Repository
See GitHub Docs: Fork a repo for guidance.
-
Clone Your Fork
git clone git@github.com:[your_github_handle]/wiki.git
-
Navigate to the Repository
cd wiki -
Add Upstream Remote
git remote add upstream https://github.com/0xPolygon/wiki
-
Sync Your Fork
git checkout master git fetch upstream git merge upstream/master
-
Install Dependencies
yarn install
The site is built using Docusaurus. You may need to install Docusaurus before running the Wiki locally.
yarn add docusaurus
Alternatively, you can upgrade Docusaurus.
yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
-
Run the Wiki Locally
yarn start
Below is a list of the primary maintainers of the Polygon Wiki.
If you're ever contacted by one of these individuals, take the following steps to ensure the communication is legitimate:
- Verify Contact Information: Match the contact details with the origin of the message.
- Double-Check: Reach out to another person on this list to confirm the legitimacy of the initial contact.
| ❗ Beware of Impersonation Scams: Always cross-verify the identity of the person contacting you. Confirm that their contact details align with the message source and seek additional verification when in doubt. |
|---|
- @DannyS03: Lead contact, primarily focuses on CDK, PoS & ZK, along with project organization.
- @EmpieichO: Primarily focusses on zkEVM & Miden, and specifications.
- @cerberushades: Primarily focuses on Polygon ID.
The Polygon Wiki is licensed under the MIT License free software license.