certora-quorum


Namecertora-quorum JSON
Version 1.1.0 PyPI version JSON
download
home_pageNone
SummaryQuorum: Open-Source Governance Security Tool for Web3 Protocols
upload_time2025-02-20 08:19:01
maintainerNone
docs_urlNone
authorCerotra
requires_python<4.0,>=3.11
licenseMIT
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"
}
        
Elapsed time: 0.41927s