> For the complete documentation index, see [llms.txt](https://docs.optimumsec.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optimumsec.xyz/ongoing-upgrades/handling-comms-upgrade.md).

# Handling Communications Before a Smart Contract Upgrade

Effective communication before a smart contract upgrade is critical for maintaining user trust and ensuring smooth operations. The approach differs depending on whether the upgrade is a routine enhancement or an emergency security fix. Below are actionable guidelines for both scenarios.

***

## Routine Upgrade: Adding New Features

When upgrading to introduce new features, the focus is on transparency, user readiness, and minimizing disruption.

### Key Steps:

1. **Announce Early**
   * Share the planned upgrade details well in advance through official channels (website, social media, email, etc.).
   * Clearly state the purpose of the upgrade and the benefits it brings to users.
2. **Reassure Users**
   * Emphasize that all funds are safe during the upgrade.
   * Provide clear instructions if any user action is required, such as pausing interactions or withdrawing funds temporarily.
3. **Communicate Downtime**
   * Clearly outline the expected downtime, specifying the exact time and duration.
   * Explain the impact on user interactions, such as halted transactions or disabled features.
4. **Encourage Community Feedback**
   * Allow users to ask questions or raise concerns in advance to ensure they feel engaged and informed.
5. **Post-Upgrade Updates**
   * Notify users once the upgrade is complete, summarizing the changes and reaffirming the safety of their assets.

***

## Emergency Upgrade: Fixing a Security Issue

In the case of an urgent upgrade to resolve a security vulnerability, communication must be swift and focused, with a balance between transparency and discretion.

### Key Steps:

1. **Act Quickly**
   * Announce the need for immediate maintenance without disclosing sensitive details that could enable exploitation before the fix is implemented.
2. **Reassure Users**
   * Clearly state that funds are safe and the team is acting to enhance security.
   * Avoid technical jargon; focus on user trust and the steps being taken to safeguard their assets.
3. **Explain Temporary Downtime**
   * Provide an estimated timeline for the fix and any service interruptions.
   * If the downtime is extended, provide periodic updates to reassure users of progress.
4. **Coordinate with Key Stakeholders**
   * Inform trusted community leaders, partners, and validators (if applicable) about the issue to ensure alignment in messaging.
5. **Post-Upgrade Transparency**
   * After resolving the issue, share a detailed post-mortem, explaining the vulnerability, the steps taken to address it, and any additional measures to prevent recurrence.
6. **Encourage Security Reporting**
   * Remind users and developers of the project’s bug bounty program or other mechanisms to report vulnerabilities responsibly.