improve(README): Add details about upgradeability (#909)

Generally clean up docs and add section on how upgradeability works

Author: nicholaspai

README.md

@@ -5,20 +5,25 @@ liquidity held in a central `HubPool` on Ethereum, which also serves as the cros
 system. `SpokePool` contracts are deployed to any network that wants to originate token deposits or be the final
 destination for token transfers, and they are all governed by the `HubPool` on Ethereum.
 
-This contract set is the second iteration of the [Across smart contracts](https://github.com/across-protocol/across-smart-contracts)
-which facilitate token transfers from any L2 to L1.
+These contracts have been continuously audited by OpenZeppelin and the audit reports can be found [here](https://docs.across.to/resources/audits).
 
-These contracts were [audited by OpenZeppelin](https://blog.openzeppelin.com/uma-across-v2-audit/) which is a great resource for understanding the contracts.
+## Understanding Upgradeability
 
-[This video](https://www.youtube.com/watch?v=iuxf6Crv8MI) is also useful for understanding the technical architecture.
+The SpokePool contracts are [UUPSUpgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/cbb66aca87521f818d9c1769c69d5dcc1004977a/contracts/proxy/utils/UUPSUpgradeable.sol) Proxy contracts which means that their addresses will always be the same but their implementation code can change.
+
+All SpokePools can be upgraded if the "admin" of the contract calls `upgradeTo`. The SpokePool's admin is set by implementing the [`_requireAdminSender()` virtual function](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/SpokePool.sol#L1745) in the child contract. For example here are the [Arbitrum](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/Arbitrum_SpokePool.sol#L114) and [Optimism](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/Ovm_SpokePool.sol#L208) implementations of the admin check.
+
+All SpokePools are implemented such that the admin is the HubPool, and therefore we describe the SpokePools as having "cross-chain ownership". The owner of the HubPool can call [this function](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/HubPool.sol#L249) to send a cross-chain execution of `upgradeTo` on any SpokePool in order to upgrade it.
+
+This [script](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/tasks/upgradeSpokePool.ts) is useful for creating the calldata to execute a cross-chain upgrade via the HubPool.
 
 ## Deployed Contract Versions
 
-The latest contract deployments on Production will always be under the `deployed` tag.
+The latest contract deployments can be found in `/deployments/deployments.json`.
 
 ## Requirements
 
-This repository assumes you have [Node](https://nodejs.org/en/download/package-manager) installed, with a minimum version of 16.18.0. Depending on what you want to do with the repo you might also need [foundry](https://book.getfoundry.sh/getting-started/installation) and [anchor](https://www.anchor-lang.com/docs/installation) to also be installed. If you have build issues please insure these are both installed first.
+This repository assumes you have [Node](https://nodejs.org/en/download/package-manager) installed, with a minimum version of 16.18.0. Depending on what you want to do with the repo you might also need [foundry](https://book.getfoundry.sh/getting-started/installation) and [anchor](https://www.anchor-lang.com/docs/installation) to also be installed. If you have build issues please ensure these are both installed first.
 
 Note if you get build issues on the initial `yarn` command try downgrading to node 20.17 (`nvm use 20.17`). If you've never used anchor before you might need to run `avm use latest` as well.
 
@@ -56,15 +61,15 @@ NODE_URL_1=https://mainnet.infura.com/xxx yarn hardhat deploy --tags HubPool --n
 ETHERSCAN_API_KEY=XXX yarn hardhat etherscan-verify --network mainnet --license AGPL-3.0 --force-license --solc-input
 ```
 
-## Tasks
+## Miscellaneous topics
 
-##### Finalize Scroll Claims from L2 -> L1 (Mainnet | Sepolia)
+### Manually Finalizing Scroll Claims from L2 -> L1 (Mainnet | Sepolia)
 
 ```shell
 yarn hardhat finalize-scroll-claims --l2-address {operatorAddress}
 ```
 
-## Slither
+### Slither
 
 [Slither](https://github.com/crytic/slither) is a Solidity static analysis framework written in Python 3. It runs a
 suite of vulnerability detectors, prints visual information about contract details, and provides an API to easily write
@@ -83,11 +88,13 @@ slither contracts/SpokePool.sol
 
 You can replace `SpokePool.sol` with the specific contract you want to analyze.
 
-## ZK Sync Adapter
+### ZK Sync Adapter
+
+ZK EVM's typically require a special compiler to convert Solidity into code that can be run on the ZK VM.
 
-These are special instructions for compiling and deploying contracts on `zksync`. The compile command will create `artifacts-zk` and `cache-zk` directories.
+There are special instructions for compiling and deploying contracts on `zksync`. The compile command will create `artifacts-zk` and `cache-zk` directories.
 
-### Compile
+#### Compile
 
 This step requires [Docker Desktop](https://www.docker.com/products/docker-desktop/) to be running, as the `solc` docker image is fetched as a prerequisite.