# TZIP-18 Spec

Authors: Derek Sorensen and Jérémy Martin

## Background and Motivation

[TZIP-18](https://tzip.tezosagora.org/proposal/tzip-18/)

During the past several years, bugs and vulnerabilities in smart contracts caused millions of dollars to get stolen or lost forever. Such cases may even require manual intervention in blockchain operation to recover the funds. As a result, the community starts to acknowledge the need for upgradeable smart-contracts.

Implementing an upgradeable contract is not a trivial task, there are many considerations to be had, such as address immutability and trust between users and administrators. This TZIP addresses those issues.

## Invariants/Requirements

From TZIP:
- adding/removing entrypoints;
- changing an entrypoint's code and parameter type;
- changing the storage's content and type;
- address immutability (i.e. the contract's address does not change upon being upgraded).

From me:

1. Only governance can trigger an upgrade
* Governance is master of proxy, which is master of the contract
* Master/slave: Governance/proxy/smart contract
1. ~~Only the contract can update its own storage~~
* *This is meant to say that the smart contract is actually a smart contract*
1. At any given time, there is only one version of the contract in operation
* It's impossible to use an outdated version
* If you want to be able to use
* Keeps track of version number
1. Upgrades are atomic (done in a single txn)
* Imitate Tezos with a cooldown period
1. The proxy contract address is permanent (address permanence)
1. Storage is updated faithfully
* A proof that the lazy import mechanism works
1. Emergency hatch
* From TZIP 18:
* Governance can respond to bugs
1. Entrypoint code and parameter type can be changed (and name...)
1. Storage type can be changed

## Definitions

## Implications

## Implementation

Comes in three modules:

### Governance
**Only** has rights to propose/execute upgrades (change version number)
- Can implement any governance strategy

### Proxy
Has rights to:
- Change entrypoint pointers (guard: Governance)
- De/Activate contracts, or change the master of the smart contract (guard: Governance)
- Store/edit contract metadata (guard: Governance)
- Change governance module (guard: Governance)
- Hold funds/assets (guard: smart contract)

### Smart Contract
Handles the storage, logic, etc. of the smart contract.
- Has a contract view and update mechanism that the proxy can access, as well as a new version

Can fetch storage from older contracts for lazy migration

## Details

## Notes 2022-07-28

- two prototypes:
- entry point taking bytes
- cannot send in tickets
- UNPACK might be removed?
- directory of contracts
- both are not compatible with wallets
- some people argue contracts shouldn't be upgradeable
- experience working with customers
- all want to upgrade at some point
- usually end up creating another token (which is not great)
- important to not trick users
- need a governance model to orchestrate upgrade
- DAO similar to Tezos protocol upgrade process
- could also have admin in some cases
- upgrades are already possible
- e.g. tzBTC can put new code into lambdas
- similar to upgrade of APIs in industry
- need versioning concept
- upgrade may completely replace contract or keep part of it used
- new version always needs access to data from old version
- need tooling for data migration
- payment for storage
- initially filling big map needs to be paid (high watermark)
- migrating big map to new contract needs new payment (cannot get refund)
- may need to pay hundereds of XTZ for migration
- operation in Michelson SELF-UPGRRADE
- to replace code of contract
- provide new value for new storage type
- instruction returns operation
- if contract never calls it (also via lambda) then it is not upgradeable
- can be exploited if operation from lambda is blindly used
- prohibit upgrade in lambdas?
- the only way to pass code is via lambda
- would be able to check "what is this operation" in the contract
- SELF-DESTRUCT
- Benjamin wanted to add it long time ago?
- AB against putting in operation type
- first-class support for upgradeable contracts in protocol would be best
- contract needs to be explicit when upgrade can happen
- should existing contracts be able to upgrade?
- may be desirable - better to replace hacks for upgrade with proper machanism?
- disable by default but white-list some contracts?
- other blockchains support upgrades?
- Algorand
- users are warned to not destruct contract accidentally
- need to be explicit in UX (block explorer) to show who can upgrade
- logic is in the code - hard to explain it
- built-in support for governance in protocol?
- sounds complicated
- changing return type of contract code is complicated
- tooling needs to be upgraded
- how change type of keys of big map?
- easiest - copy old bigmap to new contract, and add new one
- lambda describing transformation?
- cannot have tickets in lambda?
- old storage may contain tickets
- when upgrade operation should be executed?
- after all other operations?
- backward compatibility
- ignore operations sent to removed/changed entrypoints?
- not using string literal for entry points?
- users would pay for use of upgraded version
- user of NFT
- governance
- can plug any contract for that

- main challenges in upgrade
- change type of entry points
- migrate storage data
- keep old contract address
- compatibility with wallets and other tools
- support different governance models for upgrade
- keep ability to upgrade under control

- next steps?
- Tom will sketch idea with Michelson operation
- Derek will write draft of spec for solution with existing Michelson