Added : Polygon Plugin

[Samarthsinghal28]

Relates to

Issue:

• #450 Initialize Eliza Plugin Structure and Configuration (Polygon)
• #453 Implement Staking Read Operations (Polygon Plugin)
• #454 Implement Core Staking Write Operations (Polygon Plugin)

This PR implements the core foundation and staking operations for the Polygon Plugin as part of the "Implement Polygon Plugin MVP" epic.

Risks

• Medium: L1 Gas Estimation Inaccuracy: The current GasService primarily uses L2 (PolygonScan) gas oracles. When used for L1 Ethereum transactions (staking, bridging), this can lead to inaccurate gas estimations, potentially causing transactions to be underpriced (fail) or overpriced.
• Medium: Missing Heimdall Governance: The P1 functionality for Polygon-specific governance (interacting with Heimdall) is not implemented. Current governance actions target EVM-based smart contracts. Users expecting native Polygon governance via Heimdall will not find this functionality.
• Low: User-Facing withdrawRewards Action Stub: The LLM-enabled withdrawRewards action is a non-functional stub. The core logic exists via the programmatic WITHDRAW_REWARDS_L1 action and the PolygonRpcService.

Background

What does this PR do?

1. Plugin Foundation (feat: replace unruggable-core with unruggable-sdk #450):

   • Establishes the plugin package structure with proper configuration and boilerplate
   • Implements configuration handling for RPC URLs, private keys, and API keys
   • Creates the provider structure and plugin lifecycle methods

2. Staking Read Operations (Package maintainers #453):

   • Integrates StakeManager and ValidatorShare ABIs for interacting with L1 staking contracts
   • Implements getValidatorInfo(validatorId) to fetch validator status, total stake, and commission rate
   • Implements getDelegatorInfo(validatorId, delegatorAddress) to get delegator stake and pending rewards
   • Creates robust error handling for contract interactions

3. Staking Write Operations (fix: don't reply to tweets older than 5 days #454):

   • Implements delegate(validatorId, amountWei) for staking MATIC/POL to validators
   • Implements undelegate(validatorId, sharesAmountWei) for initiating the unbonding process
   • Implements withdrawRewards(validatorId) for claiming accumulated staking rewards
   • Implements restakeRewards(validatorId) as a convenience function
   • Handles transaction creation, gas estimation, signing, and broadcasting

Key functionalities included:

• Plugin Core: package.json, TypeScript configuration, main plugin definition (src/index.ts) with lifecycle methods, and registration with ElizaOS.
• Configuration: Handles essential configurations like L1/L2 RPC URLs, private key, and PolygonScan API key, with validation using zod. Includes .env.example.
• L1 Staking (Ethereum):
  • PolygonRpcService implements interactions with L1 staking contracts (StakeManager, ValidatorShare) for delegation, undelegation (partial via sellVoucher_new in service), reward withdrawal, and fetching validator/delegator information.
  • User-facing LLM-enabled actions and direct programmatic actions for these operations.
• L1 Native Bridge Deposit (Polygon PoS Bridge):
  • PolygonRpcService implements deposits to the L1 RootChainManager contract.
  • Actions for initiating bridge deposits.
• L2 Interactions (Polygon PoS):
  • Basic L2 interactions like fetching balances, block numbers via PolygonRpcService.
  • Actions for these operations.
• Checkpoint Status:
  • PolygonRpcService implements checks against the L1 RootChainManager to verify L2 block checkpoint status.
  • Actions for this functionality.
• EVM-Based Governance Stubs:
  • Actions (PROPOSE_GOVERNANCE_POLYGON, VOTE_GOVERNANCE_POLYGON) are implemented to interact with EVM-compatible governor smart contracts (e.g., OpenZeppelin Governor) using viem.
• Providers: Includes a PolygonWalletProvider (using viem) for EVM wallet interactions and exposing wallet details.
• Services: PolygonRpcService (using ethers.js) for core L1/L2 EVM logic and GasService for L2 gas price fetching (PolygonScan).
• Documentation: A comprehensive README.md for the plugin.

What kind of change is this?

Features (non-breaking change which adds functionality)

Why are we doing this? Any context or related work?

This work establishes the dedicated @elizaos/plugin-polygon as outlined in the "Implement Polygon Plugin MVP" epic. The goal is to create a focused plugin capable of handling Polygon-specific interactions (L1 staking, native bridge, Heimdall governance) that go beyond the scope of a generic EVM plugin. This PR lays the groundwork for these features, with many EVM-based L1/L2 interactions already functional.

Documentation changes needed?

My changes do not require a change to the project documentation. (The plugin includes its own README.md which serves as initial documentation for its features and setup).

Testing

Where should a reviewer start?

1. packages/plugin-polygon/README.md: For an overview of the plugin's intended features and setup.
2. packages/plugin-polygon/src/index.ts: For the main plugin definition, configuration handling, and registration of components.
3. packages/plugin-polygon/src/services/PolygonRpcService.ts: To understand the core logic for L1 staking, L1 bridging, and L2 interactions.
4. packages/plugin-polygon/src/services/GasService.ts: To review the L2 gas oracle integration.
5. Key staking files:
   • packages/plugin-polygon/src/abi/: To verify the StakeManager and ValidatorShare ABIs are properly included
   • packages/plugin-polygon/src/actions/delegate.ts: For L1 staking operations
   • packages/plugin-polygon/src/actions/getValidatorInfo.ts and getDelegatorInfo.ts: For staking read operations

Detailed testing steps

Manual testing is recommended for this initial integration, focusing on the implemented P1 functionalities. Automated tests for configuration loading were considered in the ticket but not explicitly verified as present in this review.

Setup:

1. Navigate to the packages/plugin-polygon directory.
2. Create a .env file based on .env.example.
3. Populate the .env file with valid:
   • POLYGON_RPC_URL (Polygon PoS RPC endpoint)
   • ETHEREUM_RPC_URL (Ethereum Mainnet RPC endpoint for L1)
   • PRIVATE_KEY (for a wallet with funds on both L1 and L2 for testing)
   • POLYGONSCAN_KEY (API key for PolygonScan)
   • HEIMDALL_RPC_URL (placeholder, as Heimdall features are not yet implemented)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing Touches

🧪 Generate Unit Tests

• Create PR with Unit Tests
• Commit Unit Tests in branch addpolygon
• Post Copyable Unit Tests in Comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.