> ## 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.

# Upgrades

> Software updates, consensus upgrades, and maintenance

## 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.

> [!NOTE]
>
> 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

> [card] [Security patches](#security-patches)
>
> Critical fixes for payment infrastructure protection

> [card] [Feature updates](#feature-updates)
>
> New capabilities for payment applications

> [card] [Performance optimisations](#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.

> [!TIP]
>
> 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.

> [!TIP]
>
> **Consensus synchronisation**: Block height aligns with network

> [!TIP]
>
> **RPC functionality**: Test key endpoints used by payment applications

> [!TIP]
>
> **Performance baseline**: Compare post-upgrade metrics with previous baselines

> [!TIP]
>
> **Monitoring**: Validate that monitoring and alerting systems remain operational

> [!TIP]
>
> Document configuration changes and observed behavior. This improves reliability for future upgrades and troubleshooting. For common issues, see the [troubleshooting guide](https://docs.plasma.org/docs/node-operators/maintenance/troubleshooting.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.