​
Why Upgrades Matter

Plasma’s architecture evolves rapidly to support high-throughput, stablecoin-native use cases. Timely upgrades:

  • Protect against security vulnerabilities
  • Improve performance for payment workloads
  • Maintain compatibility with Plasma’s consensus layer and RPC interface

Outdated nodes may experience sync failures, degraded performance, or security issues. As non-validator nodes often serve critical RPC traffic for payment apps, staying up to date is essential.

Most non-validator node upgrades require 15–30 minutes of downtime. Major releases introducing new features or consensus changes may require longer sync windows.

​
Types of Upgrades

Security patches

Critical fixes for payment infrastructure protection

Feature updates

New capabilities for payment applications

Performance optimisations

Improvements for high-volume transaction processing

​
Security Patches

Security patches address vulnerabilities in non-validator clients, Reth, or dependencies.

Examples:

  • State inconsistency or consensus desync vulnerabilities
  • RPC access control and authentication fixes
  • Cryptographic library updates

These should be applied immediately when released.

​
Feature Updates

Feature releases enable new protocol capabilities or support new application patterns.

Examples:

  • Zero-fee USD₮ transfer enhancements
  • Custom gas token support
  • New or extended RPC methods
  • State query optimizations
  • Wallet and exchange integration improvements

​
Performance Optimisations

Performance-focused releases improve execution speed, sync efficiency, and resource usage.

Examples:

  • Faster database reads and writes
  • Reduced RPC latency under load
  • Improved memory and CPU efficiency
  • Consensus sync improvements

​
Upgrade Procedure

Non-validator node upgrades typically involve pulling a new Docker image, updating configs, and restarting the service.

  1. Notify applications: Inform connected services about planned maintenance.
  2. Verify consensus endpoint compatibility: Ensure new non-validator client versions work with current consensus endpoints.
  3. Update non-validator client configuration: Apply any new configuration options for enhanced features.
  4. Test RPC endpoint functionality: Verify payment application compatibility after upgrade.
  5. Monitor transaction processing: Ensure normal operation for USD₮ transfers and custom gas operations.

Review any configuration changes required for new features or enhanced payment processing capabilities before restarting services. Pay particular attention to changes affecting custom gas token support, zero-fee transaction processing, or payment application RPC interfaces.

Deploy upgrades in stages when operating multiple non-validator nodes, starting with non-critical instances before upgrading primary payment infrastructure. Monitor the first upgraded node carefully during initial operation, particularly for transaction processing and payment application connectivity, before proceeding with additional nodes.

​
Post-Upgrade Verification

After upgrading, verify full sync with the consensus layer and validate core functionality.

Checklist:

  • Consensus synchronisation: Block height aligns with network
  • RPC functionality: Test key endpoints used by payment applications
  • Performance baseline: Compare post-upgrade metrics with previous baselines

Compare current metrics against pre-upgrade baselines and validate that monitoring and alerting systems remain operational.

Document configuration changes and observed behavior. This improves reliability for future upgrades and troubleshooting.

​
Rollback Procedures

​
When to Rollback

Rollback if you observe:

  • Consensus sync failure
  • Severe RPC performance degradation
  • Application incompatibility
  • Security regression
  • Data inconsistency affecting balances or transfers

​
How to Roll Back

  • Stop non-validator node services
  • Revert to previous Docker image and configuration
  • Restart services and re-sync
  • Re-test RPC endpoints and transaction functionality
  • Notify application teams of restoration

​
Best Practices

​
Automation and Monitoring

  • Automate image pulls and config updates where possible
  • Track changes with version-controlled configuration
  • Enhance observability during upgrades
  • Monitor RPC error rates, sync status, and transaction throughput closely after restarts

​
Common Troubleshooting

If issues occur post-upgrade:

  • Consensus sync: Check endpoint connectivity, credentials, and allowlist status
  • RPC errors: Validate configuration, version compatibility, and updated interfaces
  • Performance regression: Monitor resource usage and review release notes

Upgrading Plasma non-validator nodes is essential to maintain reliable, secure RPC infrastructure for stablecoin-based applications. Following structured upgrade and validation procedures minimizes risk and ensures seamless performance.