> For the complete documentation index, see [llms.txt](https://docs.aavegotchi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aavegotchi.com/developers/aavegotchi-contracts/extending-aavegotchi-contracts/upgrades.md).

# Upgrading

Upgrading the Aavegotchi Diamond

As per [EIP-2535 Diamond Standard](https://eips.ethereum.org/EIPS/eip-2535) upgrades are done by calling the `diamondCut` function to add/replace/remove any number of functions and facets in a single transaction.

Upgrading can be done safely and easily as long as some important rules are followed.

### Rules

1. Make sure that an upgrade is atomic, meaning that all changes are done in a single transaction to ensure the diamond does not get into an inconsistent state. This is done by calling `diamondCut` once with all functions to add/replace/remove.
2. The diamond and all the facets share the same contract storage address space. Do not corrupt state variables by sticking new state variables in the middle of structs. Do not change the bit size of an existing state variable if that overlaps with an existing state variable. 
3. New state variables can be added to the end of structs.
4. Existing state variables can have their name changed.

More info on upgrade rules found here: <https://eip2535diamonds.substack.com/p/diamond-upgrades?s=w>

### Upgrade Procedure

1. Modify the existing source code of the diamond and its facets.
2. Write an upgrade script that calls the `diamondCut` function to add/replace/remove functions.
3. Write any new tests and run tests to make sure they pass.
4. Commit and push changes to git.
5. Get any needed code review or code audit.
6. Execute the upgrade script.
7. Immediately[ tag the source code](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with the transaction hash that made the upgrade. Commit and push the tag to git. This records and associates the diamond and facet source code with the upgrade.
8. Use the hardhat etherscan plugin to verify the source code of any new facets that were used to add/replace functions.

Example upgrade command: `npx hardhat run scripts/upgrade.js --network kovan`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.aavegotchi.com/developers/aavegotchi-contracts/extending-aavegotchi-contracts/upgrades.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.