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

## Types of Upgrades

<Columns cols={3}>
  <Card title="Security patches" href="#security-patches">
    Critical fixes for payment infrastructure protection
  </Card>

  <Card title="Feature updates" href="#feature-updates">
    New capabilities for payment applications
  </Card>

  <Card title="Performance optimisations" href="#performance-optimisations">
    Improvements for high-volume transaction processing
  </Card>
</Columns>

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

<Steps>
  <Step title="Notify applications">
    Inform connected services about planned maintenance.
  </Step>

  <Step title="Verify compatibility">
    Ensure new non-validator client versions work with current consensus endpoints.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test RPC endpoints">
    Verify payment application compatibility after upgrade.
  </Step>

  <Step title="Monitor transaction processing">
    Ensure normal operation for USD₮ transfers and custom gas operations.
  </Step>
</Steps>

<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.
</Tip>

## Post-Upgrade Verification

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

<Check>**Consensus synchronisation**: Block height aligns with network</Check>
<Check>**RPC functionality**: Test key endpoints used by payment applications</Check>
<Check>**Performance baseline**: Compare post-upgrade metrics with previous baselines</Check>
<Check>**Monitoring**: Validate that monitoring and alerting systems remain operational</Check>

<Tip>
  Document configuration changes and observed behavior. This improves reliability for future upgrades and troubleshooting. For common issues, see the [troubleshooting guide](./troubleshooting).
</Tip>

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

<Steps>
  <Step title="Stop services">
    Stop non-validator node services.
  </Step>

  <Step title="Revert image and config">
    Revert to previous Docker image and configuration.
  </Step>

  <Step title="Restart and re-sync">
    Restart services and re-sync with the network.
  </Step>

  <Step title="Verify functionality">
    Re-test RPC endpoints and transaction functionality.
  </Step>

  <Step title="Notify teams">
    Notify application teams of restoration.
  </Step>
</Steps>

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