How to Write and Submit a Polygon Improvement Proposal (PIP)

A Polygon Improvement Proposal, or PIP, is a formal design document submitted through the Polygon-Improvement-Proposals GitHub repository that proposes a specific change to the Polygon protocol. Writing one means drafting your idea using the official PIP template, discussing it on the Polygon Community Forum first, then opening a pull request so a PIP editor can review it before it moves through Draft, Review, Last Call, and Final status.

That’s the short version. If you’ve spent any time trying to understand Polygon governance from the outside, you already know the short version doesn’t tell you much. Where do you actually start? What happens after you submit? And why do people keep mixing up PIPs with something called a PRC? Let’s go through it properly.

➤ What Exactly Is a Polygon Improvement Proposal?

PIPs describe community standards for the Polygon ecosystem, covering everything from core protocol specifications for Heimdall (the consensus layer client) and Bor (the execution layer client) to client APIs and contract standards. That definition comes straight from PIP-1, the “PIP Purpose and Guidelines” document authored by Harry Rook and Mateusz Rzeszowski back in February 2023, and it’s still the governing document today.

The framework isn’t original to Polygon, and nobody pretends it is. It’s explicitly modeled on Ethereum’s EIP process, which itself borrowed from Bitcoin’s BIP-0001, which in turn borrowed from Python’s PEP-0001. That lineage matters because if you’ve ever read an Ethereum Improvement Proposal, a lot of the PIP structure will feel immediately familiar: the same status labels, the same emphasis on a written specification before code gets touched, the same insistence that ideas get discussed publicly before they get formalized.

Polygon is a decentralized network of validator nodes, and no single entity controls it. That’s not just marketing language. Per Polygon’s own governance documentation, changes to the network require broad ecosystem consensus, and if the ecosystem can’t agree, the result can be a chain split, generally called a fork. PIPs exist specifically to reduce the odds of that happening by giving the community a shared, versioned place to hash out disagreements before anything touches mainnet.

➤ How Does Polygon Governance Actually Work?

Polygon governance runs on three coordinated layers, and understanding all three is the difference between writing a PIP that goes nowhere and one that actually gets adopted.

The first layer is off-chain ecosystem consensus, built around three components according to Polygon’s governance fundamentals documentation. PIPs themselves are the formal proposal mechanism. The Polygon Protocol Governance Call (often shortened to PPGC) is a recurring, transcribed technical call where Polygon Labs developers, from governance, validator support, PoS, and research teams, meet with the broader community to reach what’s called “rough consensus,” a term borrowed from IETF standards culture. These calls decide which PIPs get bundled into a given upgrade and set the rollout schedule. The third piece is the Polygon Community Forum, which handles the long-form discussion, from big-picture philosophical debates down to line-by-line technical nitpicking.

The second layer is implementation. Once a hard fork is agreed on through community consensus, core developers open pull requests in the relevant GitHub repositories, test the release on local devnets, tag it as a pre-release once it’s stable, then deploy it to the Amoy testnet (the network that replaced Mumbai) for at least a week while the Amoy Testing Committee reports on stability during the PPGC. Only once that’s confirmed does the upgrade get scheduled for mainnet and tagged final.

The third layer is onchain consensus. Validators upgrade their nodes, and the change becomes canonical once at least two thirds of the total validating stake, inherited from the CometBFT consensus mechanism, is running the new version. Separately, Heimdall has a built-in governance module that can push certain consensus parameter changes without requiring a full client upgrade at all. Proposals go through that module with a deposit, validators vote, and per the current parameters published in Polygon’s documentation, a proposal needs 33.4 percent quorum, a simple 50 percent threshold to pass, and can be blocked by a 33.4 percent veto vote, all denominated in staked POL.

That third layer is worth sitting with for a second, because it’s the part most explainer content skips. A PIP being “approved” in discussion doesn’t automatically mean it’s live. Someone still has to run the code, and validators representing real economic stake still have to choose to run it.

➤ How Do You Write a PIP? A Practical Walkthrough

Writing a PIP well starts before you open a text editor. Per PIP-1, the process runs through five stages, and skipping the first one is the single most common way a proposal stalls out.

Idea. Post it on the Polygon Community Forum first. This isn’t optional politeness, it’s baked into the process document itself. Your job at this stage is to make the idea clear enough that editors, developers, and interested community members can actually give useful feedback, and to check that nobody has already proposed something similar. PIP-1 calls this the uniqueness principle: if a similar proposal already exists, you’re expected to reach out to that author rather than duplicate the effort.

Draft. Once the idea has some shape, you assemble it using the official PIP template. This is where a lot of first-time authors underestimate the amount of technical rigor expected. A complete PIP needs an Abstract (roughly 200 words describing the technical issue), a Motivation section explaining clearly why the existing protocol can’t already do what you’re proposing (and disclosing any potential self-interest you have in the change, PIP-1 is explicit that proposals without sufficient motivation can be rejected outright), a Specification detailed enough that a competing team could build an interoperable implementation from it alone, a Rationale explaining the design decisions and alternatives you considered, a Backwards Compatibility section if relevant, Test Cases (mandatory for anything touching consensus), an optional Reference Implementation, a Security Considerations section (also mandatory, and a PIP cannot reach Final status without one reviewers consider sufficient), and a Copyright waiver under CC0 1.0 Universal.

Review. Once you think the draft has taken real shape, you mark it as requesting Peer Review. It gets discussed in a Polygon Builders Session and announced through Discord so the wider community knows it exists.

Last Call. After peer review wraps, a PIP editor assigns Last Call status and sets a review end date. This only happens once the editor believes there’s genuine consensus that the proposal is close to finalized. If Last Call surfaces a necessary normative change, the PIP goes right back to Review. That loop exists for a reason, it stops half-baked proposals from sliding through on momentum alone.

Final. This is the finished standard. No further amendments beyond correcting errata or adding non-normative clarifications. Notably, per PIP-1, a PIP only actually receives Final status once its implementation has gone live on mainnet, not simply once the writing is done.

There’s also a sixth status worth knowing: Withdrawn. If an author pulls their proposal, that PIP number is retired permanently. If the underlying idea becomes relevant again later, it has to come back under a brand new number. And one status is reserved for continuously evolving documents like PIP-1 itself: Continuous.

➤ Tips That Actually Move the Needle on a PIP

Beyond following the template, a few habits separate proposals that get taken seriously from ones that get quietly ignored.

• Precision over breadth. PIP-1 explicitly calls out precision as a core principle: a PIP should precisely reflect a narrowly defined subject, and complex ideas should be split into multiple complementary proposals rather than crammed into one sprawling document.
• Write for one interpretation. The understandability principle in PIP-1 states a PIP author should aim to ensure there’s only one possible reading of the proposed change. Ambiguity in a technical specification isn’t a style problem, it’s a risk to implementation.
• Don’t skip the motivation. Reviewers are told they can reject submissions outright if the motivation section doesn’t clearly explain why the current protocol falls short.
• Engage with the forum thread, not just the pull request. The PIP editors read the PIP itself for technical soundness, title accuracy, and language quality, per the editor responsibilities listed in PIP-1, but the forum is where real consensus actually gets tested.

➤ What Is the Polygon PIP Submission Process?

Once your draft is ready, submission runs through GitHub. You fork the Polygon-Improvement-Proposals repository, create a new file for your PIP following the template structure, and open a pull request. A PIP editor reads it to check that it’s ready, sound, and complete, checks the title accurately describes the content, checks language and grammar, and either sends it back for revision with specific instructions or uploads it into the repository.

It’s worth being precise about what PIP editors actually decide, because this trips people up constantly. Editors judge whether a proposal meets the Polygon standard for completeness and technical soundness. They do not decide whether a PIP gets implemented or adopted by the network. That distinction runs all the way through the process: technical gatekeeping happens at the editor and peer review level, while actual adoption depends on rough consensus at the Polygon Protocol Governance Call and, ultimately, on validators choosing to run the code.

For proposals that touch system smart contracts specifically (rather than the core protocol clients), there’s an additional layer. Polygon’s Governance Hub announcement describes a 13 member Protocol Council that publishes a transparency report for every relevant PIP explaining its decision and opening a voting period, after which token holders with staked POL can vote on the council’s decision or delegate that vote to a community delegate. Regular proposals through this path need 7 out of 13 council members in agreement and are subject to a 10 day timelock before execution. The inaugural council, established through PIP-29 in October 2023, included figures like Polygon’s Jordi Baylina, Coinbase protocol specialist Viktor Bunin, and Ethereum Foundation researcher Justin Drake, according to reporting from Decrypt and CoinDesk at the time.

Governance on Polygon isn’t frozen in place either. Proposals continue moving through the pipeline in 2026, including ones addressing entirely new use cases. PIP-82, for example, deals with fee distribution tied to agentic commerce and the x402 payment standard, which activates the long dormant HTTP 402 status code to let AI agents transact on-chain for data and API access without per-transaction friction. It’s a useful reminder that the PIP process isn’t just a historical artifact of the 2023 Polygon 2.0 rollout, it’s an active pipeline still absorbing genuinely new categories of proposal.

➤ What’s the Difference Between a PIP and a PRC?

This is one of the most common points of confusion, and it’s worth being direct about it. A PIP is the umbrella framework for proposing changes to the Polygon protocol itself. A PRC, or Polygon Request for Comment, is a specific category that lives inside the same repository, in its own PRC folder, and is dedicated specifically to proposals about token standards, the same relationship the “Ethereum Request for Comment” (ERC) has to the broader EIP process.

Practically speaking, if you’re proposing a change to how Heimdall or Bor validate blocks, that’s a PIP under the Core type. If you’re proposing a new smart contract interface, like a token standard other developers should implement consistently across the ecosystem, that goes in the PRC folder specifically. The repository’s own guidance is blunt about this: if your proposal discusses a new contract standard, you’re expected to submit it under the PRC folder rather than as a general PIP.

➤ A Readiness Checklist Before You Submit

Reading through dozens of stalled forum threads, a pattern shows up again and again: it’s rarely the technical idea that kills a PIP, it’s an incomplete document that forces reviewers to keep bouncing it back. Before opening a pull request, it’s worth running your draft against a short checklist like this one.

1. Forum discussion exists and has real replies, not just your own post. If nobody outside your immediate circle has engaged with the idea yet, it’s too early to draft.
2. The Motivation section names the specific limitation in the current protocol, not a vague appeal to “improving the ecosystem.”
3. The Specification is detailed enough that a second team could build it independently without asking you clarifying questions.
4. Backwards Compatibility is addressed even if the answer is “none,” rather than left out entirely.
5. Security Considerations covers realistic attack surfaces, not a placeholder sentence.
6. You’ve checked whether this belongs in the PRC folder instead of the general PIP track.

This isn’t an official Polygon document, it’s simply a distillation of where PIP-1’s stated principles tend to trip people up in practice.

➤ What to Expect After You Submit

Once your PIP is live in the repository, it enters a review and feedback cycle. Community members and the Polygon core development team will scrutinize it, and this iterative back and forth is what actually determines whether a proposal is technically sound enough to move forward. A few factors consistently influence whether a PIP gets picked up: how well it aligns with Polygon’s existing roadmap, its technical feasibility and implementation complexity, the level of community support it’s generated on the forum, and its potential impact on network security, scalability, or decentralization.

Patience matters here. There’s no fixed timeline written into PIP-1 for how long Review or Last Call should take, and that’s intentional, since the process is meant to move at the pace of genuine rough consensus rather than a calendar deadline.

➤ Limitations and Open Challenges in the PIP Process

To be fair to the process rather than just promote it, a few genuine friction points are worth naming. The line between “editor approval” and “community adoption” isn’t always obvious to newcomers, and it’s a common source of frustration when a technically sound PIP still stalls because it hasn’t built rough consensus at the Governance Call level. The Protocol Council’s role for system smart contract changes adds a second track that a first-time author might not realize applies to their proposal until well into the process. And because implementation ultimately depends on core developers or other teams choosing to prioritize the work, a PIP can sit at Final status in writing for a long stretch before it’s actually live on mainnet, since Final status itself only applies once mainnet implementation is complete.

➤ Frequently asked questions

1. Do I need to know Solidity or Go to write a PIP?
   Not necessarily. Informational and Interface PIPs are often written by people focused on process, standards, or developer experience rather than core client code. Core and Contracts PIPs, however, typically require someone who understands Heimdall, Bor, or the relevant Ethereum-deployed contracts well enough to write a specification a developer team could actually implement from.
2. How long does the PIP review process typically take?
   There’s no fixed timeline in PIP-1. It depends on how quickly rough consensus forms at the Polygon Protocol Governance Call and how much iteration the Review and Last Call stages require. A narrowly scoped Informational PIP can move faster than a Core PIP that requires validator coordination and testnet validation on Amoy.
3. Can I withdraw a PIP after submitting it?
   Yes. Withdrawn is one of the six official statuses. Once withdrawn, that specific PIP number can’t be reused, and the idea would need to be resubmitted under a new number if it becomes relevant again later.
4. Who has final say over whether a PIP is implemented?
   Nobody has unilateral final say. PIP editors judge readiness and completeness, the Governance Call establishes rough consensus among core developers and the community, the Protocol Council votes on system smart contract changes with council members able to be overruled by staked POL votes, and validators ultimately determine onchain finality by choosing which software version to run.
5. Is a PRC the same thing as an ERC?
   Not the same thing, but a close structural cousin. A PRC follows the same purpose as Ethereum’s ERC process, standardizing token and contract interfaces, just scoped specifically to the Polygon ecosystem and housed within the PIP repository’s dedicated PRC folder.

➤ Conclusion

Writing a Polygon Improvement Proposal isn’t about filling in a template and hoping for the best. It’s a process built to test an idea publicly before it ever touches production code: forum discussion first, a rigorously specified draft second, peer review and Last Call before anything is called Final, and, for anything touching consensus or system contracts, a second layer of validator or Protocol Council approval before it’s actually live. Understanding where a PRC differs from a general PIP, and understanding that editor approval is a completeness check rather than an adoption guarantee, saves a lot of wasted effort. The framework Polygon uses today traces directly back to Ethereum’s EIP process and, before that, to Bitcoin and Python’s own standards traditions, and it continues to absorb genuinely new categories of proposal, from validator client upgrades to fee mechanisms for AI agent transactions. If you’re serious about shaping where Polygon goes next, the repository and the forum are the actual starting line, not a blog post summarizing them.

If you’re building on Polygon and want a technical partner who already understands this governance stack, from smart contract architecture through to protocol level integrations, Mxicoders’ blockchain development team works directly with Polygon infrastructure and can help you scope, specify, or implement a proposal correctly from the start. Explore our Polygon blockchain development services or book a free consultation to talk through your project.

➤ Sources Used

• Polygon Knowledge Layer, Governance Fundamentals
• Harry Rook & Mateusz Rzeszowski, PIP-1: PIP Purpose and Guidelines (February 22, 2023)
• 0xPolygon, Polygon Improvement Proposals (PIPs) README (GitHub)
• Polygon Labs, “Kicking Off the Polygon Governance Hub” (June 14, 2024)
• 0xPolygon, PIP-82: Fee Distribution System, x402 and Agentic Commerce (2026)
• Decrypt, “Polygon Paves Way for Governance 2.0 with Introduction of Protocol Council” (October 2023)
• CoinDesk, “Polygon Proposes Council for ‘Decentralized Governance,’ Names 13 Members” (October 19, 2023)