> 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

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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.