Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.plasma.org/llms.txt

Use this file to discover all available pages before exploring further.

​
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 compatibility

Ensure new non-validator client versions work with current consensus endpoints.
3

Update configuration

Apply any new configuration options for enhanced features. Pay particular attention to changes affecting custom gas token support, zero-fee transaction processing, or payment application RPC interfaces.
4

Test RPC endpoints

Verify payment application compatibility after upgrade.
5

Monitor transaction processing

Ensure normal operation for USD₮ transfers and custom gas operations.
Deploy upgrades in stages when operating multiple non-validator nodes. Start with non-critical instances before upgrading primary payment infrastructure, and monitor the first upgraded node carefully before proceeding.

​
Post-Upgrade Verification

After upgrading, verify full sync with the consensus layer and validate core functionality.
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
Monitoring: Validate that monitoring and alerting systems remain operational
Document configuration changes and observed behavior. This improves reliability for future upgrades and troubleshooting. For common issues, see the troubleshooting guide.

​
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

1

Stop services

Stop non-validator node services.
2

Revert image and config

Revert to previous Docker image and configuration.
3

Restart and re-sync

Restart services and re-sync with the network.
4

Verify functionality

Re-test RPC endpoints and transaction functionality.
5

Notify teams

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.