| Name | certora-quorum JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Quorum: Open-Source Governance Security Tool for Web3 Protocols |
| upload_time | 2025-02-20 08:19:01 |
| maintainer | None |
| docs_url | None |
| author | Cerotra |
| requires_python | <4.0,>=3.11 |
| license | MIT |
| keywords |
quorum
proposals
reports
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Quorum
Quorum is an open-source Python utility that ensures the integrity of smart contracts deployed on blockchains. By comparing on-chain code against known official repositories, Quorum helps detect unauthorized changes, bolstering the security and trustworthiness of decentralized systems.
## Key Features
1. **Fetch & Compare Smart Contract Source Codes:**
- Retrieves source code directly from various block explorers via contract addresses.
- Generates unified diffs highlighting differences between local and fetched source codes.
2. **Repository & Code Verification:**
- Compare code against audited or reviewed repositories to confirm authenticity.
- Automates repository management (clone & update) based on your configuration.
3. **Global Variable Check:**
- Ensures all unmatched contracts’ global variables are constant or immutable.
4. **Feed Price Check:**
- Validates that the contract feed price is listed on recognized providers like Chainlink or Chronicle.
5. **New Listing Check:**
- Checks if a given proposal introduces a new asset listing on the protocol.
6. **Quick Setup Command:**
- Generates essential configuration files (`.env.example`, `ground_truth.json`, `execution.json`, etc.)
- Guides you through environment variable and repository configuration steps.
---
## Prerequisites
- **Python 3.11 or higher**
Quorum requires Python 3.11+, as it utilizes features from the most recent Python release.
---
## Installation
### Via `pip`
#### Using pypi:
```bash
pip install certora-quorum
```
#### Using git+https:
```bash
pip install git+ssh://git@github.com/Certora/Quorum.git
```
### Via `uv`
#### Isolated Installation
*This will install certora-quorum into an isolated virtual environment. This is the preferred method to install pythonic command line tools.*
```bash
uv tool install certora-quorum
```
#### Project Installation
```
uv add certora-quorum
```
### Or clone the repository:
```bash
git clone git@github.com:Certora/Quorum.git
```
---
## Quick Setup
Quorum offers a convenient setup command to streamline initial configuration by creating required files and providing guidance.
### 1. Run Setup Command
```bash
quorum setup --working_dir "/home/user/quorum_project"
```
- **`working_directory`** *(Optional)*: Path where Quorum’s configuration files will be placed. If omitted, the current directory is used.
**Example**:
```bash
quorum setup --working_dir ./my_quorum_project
```
This action will:
- Create the specified (or default) directory if it doesn’t exist.
- Copy **four** template files:
1. `ground_truth.json`
2. `execution.json`
3. `.env.example`
4. `README.md`
- Provide inline comments within these files for guidance.
### 2. Post-Setup Configuration
1. **Environment Variables**
Edit the `.env` file (or your shell profile) with your actual API keys and custom paths:
```bash
export ETHSCAN_API_KEY="your_etherscan_api_key"
export ANTHROPIC_API_KEY="your_anthropic_api_key"
export QUORUM_PATH="/path/to/your/quorum_directory"
export COINMARKETCAP_API_KEY="your_coinmarketcap_api_key" (Optional only if you want to use CoinMarketCap as a price feed provider)
```
2. **Configuration Files**
- **`ground_truth.json`**: Define repositories and providers (e.g., price feed providers, token validation).
- **`execution.json`**: Specify proposal addresses to be checked for different chains.
- **`README.md`**: An auto-generated resource explaining your next steps.
3. **Optional: Command Autocompletion**
Enable Quorum command autocompletion by adding this line to your shell profile (`.bashrc` or `.zshrc`):
```bash
eval "$(register-python-argcomplete quorum)"
```
---
## Clarifications
Quorum leverages `solcx` (latest version) to parse contract code into an AST. Contracts incompatible with the latest `solc` version may break checks involving AST parsing (e.g., global variable checks, new listing checks).
---
## Environment Variables
To fully enable Quorum’s checks, set the following:
### Required Variables
- **`ETHSCAN_API_KEY`**: Your Etherscan API key (for block explorer queries).
- **`ANTHROPIC_API_KEY`**: Required if you intend to use advanced LLM-based checks (e.g., new listing first deposit checks).
- **`QUORUM_PATH`**: Directory path where Quorum stores cloned repos, diffs, logs, etc.
- **`COINMARKETCAP_API_KEY`**: Optional if you want to use CoinMarketCap as a price feed provider.
### Setting Variables
1. **Shell Environment:**
```bash
export ETHSCAN_API_KEY="your_etherscan_api_key"
export ANTHROPIC_API_KEY="your_anthropic_api_key"
export QUORUM_PATH="/path/to/quorum_artifacts"
export COINMARKETCAP_API_KEY="your_coinmarketcap_api_key"
```
2. **`.env` File:**
```
ETHSCAN_API_KEY=your_etherscan_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
QUORUM_PATH="/path/to/quorum_artifacts"
COINMARKETCAP_API_KEY="your_coinmarketcap_api_key"
```
*(This file is automatically created by `Quorum setup` if not already present.)*
---
## Usage
Quorum now provides a **single CLI** with multiple **subcommands** for different tasks. Below is an overview of each subcommand, with examples.
### 1. **validate-address**
**Purpose:** Analyzes a single proposal address for a specific customer on a given chain.
```bash
quorum validate-address --customer "Aave" --chain "Ethereum" --payload_address "0xAD6..."
```
### 2. **validate-batch**
**Purpose:** Processes multiple proposals in bulk using a JSON config file.
```bash
quorum validate-batch --config "/path/to/config.json"
```
*(See “**Example Usage with Config File**” for a sample config.)*
### 3. **validate-by-id**
**Purpose:** Looks up all payload addresses for a single proposal ID (useful for proposals containing multiple payloads).
```bash
quorum validate-by-id --customer "Aave" --proposal_id 137
```
### 4. **validate-ipfs**
**Purpose:** Validates whether the IPFS description content aligns with the actual on-chain payload. Uses LLM-based analysis.
```bash
quorum validate-ipfs --proposal_id 132 --chain "Ethereum" --payload_address "0xAD6..."
```
### 5. **generate-report**
**Purpose:** Generates a human-readable report of the proposal details, leveraging Jinja2 templates.
```bash
quorum generate-report --proposal_id 137 \
--template "src/quorum/auto_report/AaveReportTemplate.md.j2" \
--generate_report_path "reports/v3-137.md"
```
### 6. **setup**
**Purpose:** Bootstraps your Quorum environment, creating `.env`, `ground_truth.json`, `execution.json`, and an initial `README.md`.
```bash
quorum setup --working_dir "/home/user/quorum_project"
```
*(Refer to “**Quick Setup**” for details.)*
---
## Example Usage with Config File
For bulk execution, create a config file (e.g., `config.json`) with the following format:
```json
{
"Aave": {
"Ethereum": { "Proposals": [ "0xAD6..." ] },
"Arbitrum": { "Proposals": [ "0x22ca2..." ] },
...
}
}
```
Then run:
```bash
quorum validate-batch --config "/path/to/config.json"
```
*(Chains without proposals are automatically skipped.)*
---
## Configuration Details
### ground_truth.json
Defines each protocol’s repositories and providers:
```json
{
"ProtocolName": {
"dev_repos": [
"https://github.com/org/repo1",
"https://github.com/org/repo2"
],
"review_repo": "https://github.com/org/review",
"price_feed_providers": ["Chainlink", "Chronicle"],
"token_validation_providers": ["Coingecko", "CoinMarketCap"]
}
}
```
### Currently Supported Providers
- **Price Feeds**: Chainlink, Chronicle
- **Token Validation**: Coingecko, CoinMarketCap
---
## Artifacts Structure
All artifacts (cloned repos, diffs, logs) are stored under `QUORUM_PATH`. Below is a typical folder hierarchy:
```
QUORUM_PATH/
├── ground_truth.json
├── CustomerName/
│ ├── modules/
│ │ ├── repository1/
│ │ ├── repository2/
│ ├── checks/
│ │ ├── ChainName/
│ │ │ ├── ProposalAddress/
│ │ │ │ ├── DiffCheck_<timestamp>/
│ │ │ │ ├── FeedPriceCheck_<timestamp>/
│ │ │ │ ├── GlobalVariableCheck_<timestamp>/
│ │ │ │ ├── NewListingCheck_<timestamp>/
│ │ │ ├── ...
│ ├── execution.json
│ └── ground_truth.json
```
1. **`CustomerName/`**: Each customer has a dedicated folder.
2. **`modules/`**: Contains cloned Git repositories.
3. **`checks/`**: Contains patch files (diffs) and JSON logs from the checks performed.
4. **`execution.json`**: Tracks the proposals processed in the last run.
5. **`ground_truth.json`**: Core configuration defining the official repositories and providers.
---
## Development
For dev guide please refer to [DEVREADME.md](DEVREADME.md)
## License
Quorum is licensed under the [MIT License](LICENSE).
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/Certora/Quorum).
## Acknowledgments
- Special thanks to all contributors and the open-source community for their support.
---
**Happy Auditing!** If you have any questions or run into issues, please don’t hesitate to create a GitHub issue or open a discussion.
Raw data
{
"_id": null,
"home_page": null,
"name": "certora-quorum",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "Quorum, Proposals, Reports",
"author": "Cerotra",
"author_email": "support@certora.com",
"download_url": "https://files.pythonhosted.org/packages/df/f3/102f36c16a295b8872c5562181194f3cf7374621123bfb1ce3242dcf0e4e/certora_quorum-1.1.0.tar.gz",
"platform": null,
"description": "# Quorum\n\nQuorum is an open-source Python utility that ensures the integrity of smart contracts deployed on blockchains. By comparing on-chain code against known official repositories, Quorum helps detect unauthorized changes, bolstering the security and trustworthiness of decentralized systems.\n\n## Key Features\n1. **Fetch & Compare Smart Contract Source Codes:** \n - Retrieves source code directly from various block explorers via contract addresses. \n - Generates unified diffs highlighting differences between local and fetched source codes. \n\n2. **Repository & Code Verification:** \n - Compare code against audited or reviewed repositories to confirm authenticity. \n - Automates repository management (clone & update) based on your configuration. \n\n3. **Global Variable Check:** \n - Ensures all unmatched contracts\u2019 global variables are constant or immutable. \n\n4. **Feed Price Check:** \n - Validates that the contract feed price is listed on recognized providers like Chainlink or Chronicle. \n\n5. **New Listing Check:** \n - Checks if a given proposal introduces a new asset listing on the protocol. \n\n6. **Quick Setup Command:** \n - Generates essential configuration files (`.env.example`, `ground_truth.json`, `execution.json`, etc.) \n - Guides you through environment variable and repository configuration steps. \n\n---\n\n## Prerequisites\n\n- **Python 3.11 or higher** \n Quorum requires Python 3.11+, as it utilizes features from the most recent Python release.\n\n---\n\n## Installation\n\n### Via `pip`\n\n#### Using pypi:\n```bash\npip install certora-quorum\n```\n\n#### Using git+https:\n```bash\npip install git+ssh://git@github.com/Certora/Quorum.git\n```\n\n### Via `uv`\n\n#### Isolated Installation\n\n*This will install certora-quorum into an isolated virtual environment. This is the preferred method to install pythonic command line tools.*\n\n```bash\nuv tool install certora-quorum\n```\n\n#### Project Installation\n\n```\nuv add certora-quorum\n```\n\n### Or clone the repository:\n\n```bash\ngit clone git@github.com:Certora/Quorum.git\n```\n\n---\n\n## Quick Setup\n\nQuorum offers a convenient setup command to streamline initial configuration by creating required files and providing guidance.\n\n### 1. Run Setup Command\n\n```bash\nquorum setup --working_dir \"/home/user/quorum_project\"\n```\n\n- **`working_directory`** *(Optional)*: Path where Quorum\u2019s configuration files will be placed. If omitted, the current directory is used.\n\n**Example**:\n```bash\nquorum setup --working_dir ./my_quorum_project\n```\n\nThis action will:\n- Create the specified (or default) directory if it doesn\u2019t exist.\n- Copy **four** template files:\n 1. `ground_truth.json`\n 2. `execution.json`\n 3. `.env.example`\n 4. `README.md`\n- Provide inline comments within these files for guidance.\n\n### 2. Post-Setup Configuration\n\n1. **Environment Variables** \n Edit the `.env` file (or your shell profile) with your actual API keys and custom paths:\n ```bash\n export ETHSCAN_API_KEY=\"your_etherscan_api_key\"\n export ANTHROPIC_API_KEY=\"your_anthropic_api_key\"\n export QUORUM_PATH=\"/path/to/your/quorum_directory\"\n\n export COINMARKETCAP_API_KEY=\"your_coinmarketcap_api_key\" (Optional only if you want to use CoinMarketCap as a price feed provider)\n ```\n\n2. **Configuration Files** \n - **`ground_truth.json`**: Define repositories and providers (e.g., price feed providers, token validation). \n - **`execution.json`**: Specify proposal addresses to be checked for different chains. \n - **`README.md`**: An auto-generated resource explaining your next steps.\n\n3. **Optional: Command Autocompletion**\n Enable Quorum command autocompletion by adding this line to your shell profile (`.bashrc` or `.zshrc`):\n ```bash\n eval \"$(register-python-argcomplete quorum)\"\n ```\n---\n\n## Clarifications\n\nQuorum leverages `solcx` (latest version) to parse contract code into an AST. Contracts incompatible with the latest `solc` version may break checks involving AST parsing (e.g., global variable checks, new listing checks).\n\n---\n\n## Environment Variables\n\nTo fully enable Quorum\u2019s checks, set the following:\n\n### Required Variables\n- **`ETHSCAN_API_KEY`**: Your Etherscan API key (for block explorer queries). \n- **`ANTHROPIC_API_KEY`**: Required if you intend to use advanced LLM-based checks (e.g., new listing first deposit checks). \n- **`QUORUM_PATH`**: Directory path where Quorum stores cloned repos, diffs, logs, etc.\n- **`COINMARKETCAP_API_KEY`**: Optional if you want to use CoinMarketCap as a price feed provider.\n\n### Setting Variables\n\n1. **Shell Environment:**\n\n ```bash\n export ETHSCAN_API_KEY=\"your_etherscan_api_key\"\n export ANTHROPIC_API_KEY=\"your_anthropic_api_key\"\n export QUORUM_PATH=\"/path/to/quorum_artifacts\"\n export COINMARKETCAP_API_KEY=\"your_coinmarketcap_api_key\"\n ```\n\n2. **`.env` File:**\n\n ```\n ETHSCAN_API_KEY=your_etherscan_api_key\n ANTHROPIC_API_KEY=your_anthropic_api_key\n QUORUM_PATH=\"/path/to/quorum_artifacts\"\n COINMARKETCAP_API_KEY=\"your_coinmarketcap_api_key\"\n ```\n\n*(This file is automatically created by `Quorum setup` if not already present.)*\n\n---\n\n## Usage\n\nQuorum now provides a **single CLI** with multiple **subcommands** for different tasks. Below is an overview of each subcommand, with examples.\n\n### 1. **validate-address**\n\n**Purpose:** Analyzes a single proposal address for a specific customer on a given chain.\n\n```bash\nquorum validate-address --customer \"Aave\" --chain \"Ethereum\" --payload_address \"0xAD6...\"\n```\n\n### 2. **validate-batch**\n\n**Purpose:** Processes multiple proposals in bulk using a JSON config file.\n\n```bash\nquorum validate-batch --config \"/path/to/config.json\"\n```\n*(See \u201c**Example Usage with Config File**\u201d for a sample config.)*\n\n### 3. **validate-by-id**\n\n**Purpose:** Looks up all payload addresses for a single proposal ID (useful for proposals containing multiple payloads).\n\n```bash\nquorum validate-by-id --customer \"Aave\" --proposal_id 137\n```\n\n### 4. **validate-ipfs**\n\n**Purpose:** Validates whether the IPFS description content aligns with the actual on-chain payload. Uses LLM-based analysis.\n\n```bash\nquorum validate-ipfs --proposal_id 132 --chain \"Ethereum\" --payload_address \"0xAD6...\"\n```\n\n### 5. **generate-report**\n\n**Purpose:** Generates a human-readable report of the proposal details, leveraging Jinja2 templates.\n\n```bash\nquorum generate-report --proposal_id 137 \\\n --template \"src/quorum/auto_report/AaveReportTemplate.md.j2\" \\\n --generate_report_path \"reports/v3-137.md\"\n```\n\n### 6. **setup**\n\n**Purpose:** Bootstraps your Quorum environment, creating `.env`, `ground_truth.json`, `execution.json`, and an initial `README.md`.\n\n```bash\nquorum setup --working_dir \"/home/user/quorum_project\"\n```\n\n*(Refer to \u201c**Quick Setup**\u201d for details.)*\n\n---\n\n## Example Usage with Config File\n\nFor bulk execution, create a config file (e.g., `config.json`) with the following format:\n\n```json\n{\n \"Aave\": {\n \"Ethereum\": { \"Proposals\": [ \"0xAD6...\" ] },\n \"Arbitrum\": { \"Proposals\": [ \"0x22ca2...\" ] },\n ...\n }\n}\n```\n\nThen run:\n\n```bash\nquorum validate-batch --config \"/path/to/config.json\"\n```\n\n*(Chains without proposals are automatically skipped.)*\n\n---\n\n## Configuration Details\n\n### ground_truth.json\n\nDefines each protocol\u2019s repositories and providers:\n\n```json\n{\n \"ProtocolName\": {\n \"dev_repos\": [\n \"https://github.com/org/repo1\",\n \"https://github.com/org/repo2\"\n ],\n \"review_repo\": \"https://github.com/org/review\",\n \"price_feed_providers\": [\"Chainlink\", \"Chronicle\"],\n \"token_validation_providers\": [\"Coingecko\", \"CoinMarketCap\"]\n }\n}\n```\n\n### Currently Supported Providers\n- **Price Feeds**: Chainlink, Chronicle \n- **Token Validation**: Coingecko, CoinMarketCap\n\n---\n\n## Artifacts Structure\n\nAll artifacts (cloned repos, diffs, logs) are stored under `QUORUM_PATH`. Below is a typical folder hierarchy:\n\n```\nQUORUM_PATH/\n\u251c\u2500\u2500 ground_truth.json\n\u251c\u2500\u2500 CustomerName/\n\u2502 \u251c\u2500\u2500 modules/\n\u2502 \u2502 \u251c\u2500\u2500 repository1/\n\u2502 \u2502 \u251c\u2500\u2500 repository2/\n\u2502 \u251c\u2500\u2500 checks/\n\u2502 \u2502 \u251c\u2500\u2500 ChainName/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ProposalAddress/\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 DiffCheck_<timestamp>/\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 FeedPriceCheck_<timestamp>/\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 GlobalVariableCheck_<timestamp>/\n\u2502 \u2502 \u2502 \u2502 \u251c\u2500\u2500 NewListingCheck_<timestamp>/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 execution.json\n\u2502 \u2514\u2500\u2500 ground_truth.json\n```\n\n1. **`CustomerName/`**: Each customer has a dedicated folder. \n2. **`modules/`**: Contains cloned Git repositories. \n3. **`checks/`**: Contains patch files (diffs) and JSON logs from the checks performed. \n4. **`execution.json`**: Tracks the proposals processed in the last run. \n5. **`ground_truth.json`**: Core configuration defining the official repositories and providers.\n\n---\n\n## Development\n\nFor dev guide please refer to [DEVREADME.md](DEVREADME.md)\n\n## License\n\nQuorum is licensed under the [MIT License](LICENSE).\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/Certora/Quorum).\n\n## Acknowledgments\n\n- Special thanks to all contributors and the open-source community for their support.\n\n---\n\n**Happy Auditing!** If you have any questions or run into issues, please don\u2019t hesitate to create a GitHub issue or open a discussion.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Quorum: Open-Source Governance Security Tool for Web3 Protocols",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"quorum",
" proposals",
" reports"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ebea8d1b6714eda062ec4eeac5f5b1bfeadafd4f44b9f57c92697612ccb94aa0",
"md5": "a8e239b036f9c277e52c85e694258547",
"sha256": "f3471d3bd199dd472ac75f706b587502c5f7f36054b53b5819b653c56ed58cd5"
},
"downloads": -1,
"filename": "certora_quorum-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8e239b036f9c277e52c85e694258547",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 1841828,
"upload_time": "2025-02-20T08:18:59",
"upload_time_iso_8601": "2025-02-20T08:18:59.856775Z",
"url": "https://files.pythonhosted.org/packages/eb/ea/8d1b6714eda062ec4eeac5f5b1bfeadafd4f44b9f57c92697612ccb94aa0/certora_quorum-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dff3102f36c16a295b8872c5562181194f3cf7374621123bfb1ce3242dcf0e4e",
"md5": "615da9afbe7551f1aa4d04cd987feba9",
"sha256": "d68e03985829d2c034540de3cc028241ec025f415d7ac7613a4ce06d56402dfc"
},
"downloads": -1,
"filename": "certora_quorum-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "615da9afbe7551f1aa4d04cd987feba9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 1311762,
"upload_time": "2025-02-20T08:19:01",
"upload_time_iso_8601": "2025-02-20T08:19:01.567344Z",
"url": "https://files.pythonhosted.org/packages/df/f3/102f36c16a295b8872c5562181194f3cf7374621123bfb1ce3242dcf0e4e/certora_quorum-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-20 08:19:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "certora-quorum"
}
