Workflow test

.env.example

@@ -0,0 +1,5 @@
+PRIVATE_KEY=
+INFURA_KEY=
+ETHERSCAN_API_KEY=
+POLYGONSCAN_API_KEY=
+POLYGONSCAN_ZKEVM_API_KEY=

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# This group is setup to ensure a security review is always required for PRs
+/src/             @0xPolygon/internal-security
+/script/**/*.sol  @0xPolygon/internal-security
+/deployments/     @0xPolygon/internal-security

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+# Pull Request
+
+## Description
+
+Please include a summary of the change and which feature was implemented or which issue was fixed. Also, include relevant motivation and context. List any dependencies that are required for this change.
+
+Fixes # (issue)
+
+### How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.
+
+# Checklist:
+
+Before deployment
+
+- [ ] 100% test and branch coverage
+- [ ] check slither for severe issues
+- [ ] fuzz and invariant tests (when applicable)
+- [ ] formal verification (when applicable)
+- [ ] deployment or upgrade scripts ready
+- [ ] version management agreed upon and implemented
+- [ ] internal team review
+- [ ] **Security Team review**
+
+After deployment
+
+- [ ] transfer ownership after deployments (when applicable)
+- [ ] complete upgrade (when applicable)
+- [ ] generate deployment/upgrade log files
+- [ ] update [static](https://github.com/maticnetwork/static/tree/master/network) with new contract address and/or version
+
+---
+
+### Considerations
+
+- I have followed the [contributing guidelines](../CONTRIBUTING.md).
+- My code follows the style guidelines of this project and I have run `forge fmt` and prettier to ensure the code style is valid
+- I have performed a self-review of my own code
+- I have commented my code, particularly in hard-to-understand areas
+- I have made corresponding changes to the documentation
+- My changes generate no new warnings
+- I have added tests that prove my fix is effective or that my feature works
+- New and existing unit tests pass locally with my changes
+
+### Additional context
+
+Add any other context about the pull request here.

.github/workflows/pr-check.yaml

@@ -0,0 +1,20 @@
+name: Source branch check
+on:
+  pull_request:
+    branches: [main]
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - edited
+jobs:
+  check-main:
+    if: github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branches
+        run: |
+          if [ ${{ github.head_ref }} != "staging" ]; then
+            echo "Merge requests to main branch are only allowed from staging branch."
+            exit 1
+          fi

.github/workflows/pre-commit.yaml

@@ -0,0 +1,21 @@
+# checks that pre-commit hooks pass before allowing to merge a PR
+
+name: pre-commit
+on:
+  pull_request:
+    branches: [main, master, staging, dev, feat/**, fix/**]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v2
+        with:
+          submodules: recursive
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Install pre-commit
+        run: pip install pre-commit
+      - name: Run pre-commit
+        run: pre-commit run --all-files

.github/workflows/test.yaml

@@ -0,0 +1,36 @@
+name: test
+
+on:
+  pull_request:
+    branches: [main, master, staging, dev, feat/**, fix/**]
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  check:
+    strategy:
+      fail-fast: true
+
+    name: Foundry project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Run Forge build
+        run: |
+          forge --version
+          forge build --sizes
+        id: build
+
+      - name: Run Forge tests
+        run: |
+          forge test -vvv
+        id: test

.gitignore

@@ -0,0 +1,14 @@
+/target
+/out
+/cache
+/coverage
+lcov.info
+.DS_Store
+.env
+.vscode
+
+broadcast/*/31337
+deployments/**/31337.*
+
+script/util/storage_check_cache
+script/util/storage_check_report

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "lib/forge-std"]
+	path = lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/openzeppelin-contracts"]
+	path = lib/openzeppelin-contracts
+	url = https://github.com/openzeppelin/openzeppelin-contracts
+[submodule "lib/openzeppelin-contracts-upgradeable"]
+	path = lib/openzeppelin-contracts-upgradeable
+	url = https://github.com/openzeppelin/openzeppelin-contracts-upgradeable

.nvmrc

@@ -0,0 +1 @@
+18.16.0

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+        description: Forces to replace line ending by the UNIX 'lf' character.
+        exclude: "^docs/autogen"
+  - repo: local
+    hooks:
+      - id: format
+        name: Format solidity code
+        description: Format solidity code with `forge fmt`
+        language: system
+        entry: forge fmt
+        exclude: "^lib/"
+        pass_filenames: true
+      - id: doc
+        name: Generate documentation
+        description: Generate docs with `forge doc`
+        language: system
+        # generates docs and unstages files if only the commit hash changed within the file, this way only when the documentation is updated, the documentation needs to be regenerated and only the changed files are pushed
+        entry: "script/util/doc_gen.sh"
+        pass_filenames: false
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.0.3"
+    hooks:
+      - id: prettier
+        name: Format non solidity files with prettier
+        exclude: "^docs/autogen"

.prettierignore

@@ -0,0 +1,6 @@
+foundry.toml
+out
+lib/
+cache/
+docs/autogenerated
+*.sol

.prettierrc

@@ -0,0 +1,25 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": false,
+  "bracketSpacing": true,
+  "overrides": [
+    {
+      "files": "*.sol",
+      "options": {
+        "printWidth": 120,
+        "tabWidth": 4,
+        "useTabs": false,
+        "singleQuote": false,
+        "bracketSpacing": false
+      }
+    },
+    {
+      "files": "*.json",
+      "options": {
+        "tabWidth": 4
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -0,0 +1,158 @@
+# Contributing
+
+- [Install](#install)
+- [Pre-commit Hooks](#pre-commit-hooks)
+- [Branching](#branching)
+  - [Main](#main)
+  - [Staging](#staging)
+  - [Dev](#dev)
+  - [Feature](#feature)
+  - [Fix](#fix)
+- [Code Practices](#code-practices)
+  - [Interfaces](#interfaces)
+  - [NatSpec \& Comments](#natspec--comments)
+- [Versioning](#versioning)
+- [Testing](#testing)
+  - [Deployer Template](#deployer-template)
+- [Deployment](#deployment)
+  - [Deployer Template](#deployer-template-1)
+  - [Deployment](#deployment-1)
+  - [Deployment Info Generation](#deployment-info-generation)
+- [Deployer Template Script](#deployer-template-script)
+- [Releases](#releases)
+
+## Install
+
+Follow these steps to set up your local environment for development:
+
+- [Install foundry](https://book.getfoundry.sh/getting-started/installation)
+- Install dependencies: `forge install`
+- [Install pre-commit](https://pre-commit.com/#post-commit)
+- Install pre commit hooks: `pre-commit install`
+
+## Pre-commit Hooks
+
+Follow the [installation steps](#install) to enable pre-commit hooks. To ensure consistency in our formatting we use `pre-commit` to check whether code was formatted properly and the documentation is up to date. Whenever a commit does not meet the checks implemented by pre-commit, the commit will fail and the pre-commit checks will modify the files to make the commits pass. Include these changes in your commit for the next commit attempt to succeed. On pull requests the CI checks whether all pre-commit hooks were run correctly.
+This repo includes the following pre-commit hooks that are defined in the `.pre-commit-config.yaml`:
+
+- `mixed-line-ending`: This hook ensures that all files have the same line endings (LF).
+- `format`: This hook uses `forge fmt` to format all Solidity files.
+- `doc`: This hook uses `forge doc` to automatically generate documentation for all Solidity files whenever the NatSpec documentation changes. The `script/util/doc_gen.sh` script is used to generate documentation. Forge updates the commit hash in the documentation automatically. To only generate new documentation when the documentation has actually changed, the script checks whether more than just the hash has changed in the documentation and discard all changes if only the hash has changed.
+- `prettier`: All remaining files are formatted using prettier.
+
+## Branching
+
+This section outlines the branching strategy of this repo.
+
+### Main
+
+The main branch is supposed to reflect the deployed state on all networks. Any pull requests into this branch MUST come from the staging branch. The main branch is protected and requires a separate code review by the security team. Whenever the main branch is updated, a new release is created with the latest version. For more information on versioning, check [here](#versioning).
+
+### Staging
+
+The staging branch reflects new code complete deployments or upgrades containing fixes and/or features. Any pull requests into this branch MUST come from the dev branch. The staging branch is used for security audits and deployments. Once the deployment is complete and deployment log files are generated, the branch can be merged into main. For more information on the deployment and log file generation check [here](#deployment--versioning).
+
+### Dev
+
+This is the active development branch. All pull requests into this branch MUST come from fix or feature branches. Upon code completion this branch is merged into staging for auditing and deployment.
+
+### Feature
+
+Any new feature should be developed on a separate branch. The naming convention for these branches is `feat/*`. Once the feature is complete, a pull request into the dev branch can be created.
+
+### Fix
+
+Any bug fixes should be developed on a separate branch. The naming convention for these branches is `fix/*`. Once the fix is complete, a pull request into the dev branch can be created.
+
+## Code Practices
+
+### Interfaces
+
+Every contract MUST implement their corresponding interface that includes all externally callable functions, errors and events.
+
+### NatSpec & Comments
+
+Interfaces should be the entrypoint for all contracts. When exploring the a contract within the repository, the interface MUST contain all relevant information to understand the functionality of the contract in the form of NatSpec comments. This includes all externally callable functions, errors and events. The NatSpec documentation MUST be added to the functions, errors and events within the interface. This allows a reader to understand the functionality of a function before moving on to the implementation. The implementing functions MUST point to the NatSpec documentation in the interface using `@inheritdoc`. Internal and private functions shouldn't have NatSpec documentation except for `@dev` comments, whenever more context is needed. Additional comments within a function should only be used to give more context to more complex operations, otherwise the code should be kept readable and self-explanatory.
+
+## Versioning
+
+This repo utilizes [semantic versioning](https://semver.org/) for smart contracts. An `IVersioned` interface is included in the [interfaces directory](src/interface/IVersioned.sol) exposing a unified versioning interface for all contracts. This version MUST be included in all contracts, whether they are upgradeable or not, to be able to easily match deployed versions. For example, in the case of a non-upgradeable contract one version could be deployed to a network and later a new version might be deployed to another network. The exposed `version()` function is also used by the [Deployment Info Generator](#deployment-info-generation) to extract information about the version.
+
+Whenever contracts are modified, only the version of the changed contracts should be updated. Unmodified contracts should remain on the version of their last change.
+
+## Testing
+
+### Deployer Template
+
+This repo provides a deployer template for consistency between scripts and unit tests. For more information on how to use the template, check [here](#deployer-template-script).
+
+## Deployment
+
+This repo utilizes versioned deployments. Any changes to a contract should update the version of this specific contract. To deploy a new version of a contract, create a new deployment script in a directory named after the new version of the modified contracts (e.g., `1.0.0`). A script is provided that extracts deployment information from the `run-latest.json` file within the `broadcast` directory generated while the forge script runs. From this information a JSON and markdown file is generated containing various information about the deployment itself as well as past deployments.
+
+### Deployer Template
+
+This repo provides a deployer template for consistency between scripts and unit tests. For more information on how to use the template, check [here](#deployer-template-script).
+
+### Deployment
+
+This repo set up the following RPCs in the `foundry.toml` file:
+
+- mainnet: Ethereum Mainnet
+- goerli: Ethereum Goerli
+- sepolia: Ethereum Sepolia
+- polygon_pos: Polygon PoS
+- mumbai: Polygon Mumbai
+- polygon_zkevm: Polygon zkEVM
+- polygon_zkevm_testnet: Polygon zkEVM Testnet
+
+To deploy the contracts, provide the `--broadcast` flag to the forge script command. Should the etherscan verification time out, it can be picked up again by replacing the `--broadcast` flag with `--resume`.
+Deploy the contracts to one of the predefined networks by providing the according key with the `--rpc-url` flag. Most of the predefined networks require the `INFURA_KEY` environment variable to be set in the `.env` file.
+Including the `--verify` flag will verify deployed contracts on Etherscan. Define the appropriate environment variable for the Etherscan api key in the `.env` file.
+
+```shell
+forge script script/1.0.0/Deploy.s.sol --broadcast --rpc-url <rpc_url> --verify
+```
+
+### Deployment Info Generation
+
+A JSON and Markdown file can be generated in the `deployments` directory containing various information about the deployment itself as well as past deployments using the following command. To find out more about versioning of contracts within this repo, check [here](CONTRIBUTING.md#versioning).
+
+```shell
+node script/util/extract.js <chainId> <version> <scriptName>
+```
+
+As the `chainId`, provide the chainId of the network the contracts were deployed to as a number. The supplied `version` should be the version of the modified contracts and the sub directory the deployment script is located in (e.g., `1.0.0`). The `scriptName` should be the file name of the script used in the deployment (e.g., `Deploy.s.sol`).
+
+When upgrading a contract, most of the times just the new implementation is deployed and the actual upgrade is triggered by a governance process or a multisig. The script will check whether the implementation of the upgraded contract was updated to the deployed version and if not, it will fail and not generate any files.
+
+## Deployer Template Script
+
+This repo provides a deployer template for consistency between scripts and unit tests.
+
+A deployer is an `abstract` contract, meant to be inherited in scripts and tests. The deployer consists of two functions: `deploy<Contract>` and `deploy<Contract>_NoInit`. It handels the creation, proxification, and initialization of the contract.
+
+To generate a new deployer:
+
+```
+node script/util/generateDeployer.js <contractFile> [params] <outputDir>
+```
+
+## Releases
+
+Releases should be created whenever the code on the main branch is updated to reflect a deployment or an upgrade on a network. The release should be named after the version of the contracts deployed or upgraded.
+The release should include the following:
+
+- In case of a MAJOR version
+  - changelog
+  - summary of new features
+  - summary of breaking changes
+- In case of a MINOR version
+  - changelog
+  - summary of new features
+  - summary of fixes
+- In case of a PATCH version
+  - changelog
+  - summary of fixes
+- Deployment information
+- TODO