https://github.com/teddyjfpender/hairy
A Haskell STARK Prover.
https://github.com/teddyjfpender/hairy
circle-stark haskell stark stwo
Last synced: 6 months ago
JSON representation
A Haskell STARK Prover.
- Host: GitHub
- URL: https://github.com/teddyjfpender/hairy
- Owner: teddyjfpender
- Created: 2025-05-11T13:57:36.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-05-11T22:44:59.000Z (9 months ago)
- Last Synced: 2025-05-11T23:18:41.368Z (9 months ago)
- Topics: circle-stark, haskell, stark, stwo
- Language: Haskell
- Homepage:
- Size: 6.5 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# HAIRY - STARK Prover
[](https://opensource.org/licenses/MIT)
[](https://github.com/teddyjfpender/hairy/actions/workflows/ci.yml)
[](https://hackage.haskell.org/package/)
[](http://stackage.org/lts/package/)
[](http://stackage.org/nightly/package/)
[](#prerequisites)
**H**askell **A**lgebraic **IR** (AIR) prover… **Y**? Because every project name needs a questionable backronym and we're not shaving it off. **Hairy** is a re-write of Stwo in Haskell.
This project is built & maintained by AI Agents (shocking!). Idea being that LLMs are pretty bad at writing good Haskell code and maybe there is a process here that allows us to write better Haskell code. Such a process can look like mathematical specification (inspired by another repository) generated by an LLM --> code generated by an LLM --> test generated by an LLM.
## Table of Contents
- [Features](#features)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Setup Guide](#setup-guide)
- [Using Cabal](#using-cabal)
- [Using Stack](#using-stack)
- [Usage](#usage)
- [Library](#library)
- [Executables](#executables)
- [Running Tests](#running-tests)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## Features
HAIRY is experimental at best. But it tries to replicated the Stwo repo as best it can. For now, expect some primitive packages only.
## Project Structure
This project uses Cabal and is structured as a multi-package monorepo. The main packages are defined in the root `cabal.project` file:
- `core`: The primary library containing the core STARK proving logic, located in `core/core.cabal`.
- `examples`: Sample executables demonstrating the library, located in `core/examples/examples.cabal`.
- *(Add more packages here as your project evolves)*
The `cabal.project` file orchestrates the build for the entire workspace.
## Prerequisites
Before you begin, ensure you have the following installed:
- [GHC (Glasgow Haskell Compiler)](https://www.haskell.org/ghc/) (e.g., version 9.x.x or as specified in your `.cabal` files)
- [Cabal (Haskell build tool)](https://www.haskell.org/cabal/) (e.g., version 3.x)
- OR [Stack (Haskell build tool)](https://docs.haskellstack.org/en/stable/install_and_upgrade/) (optional, if you add a `stack.yaml`)
## Installation
Clone the repository:
```bash
git clone https://github.com/teddyjfpender/hairy.git
cd hairy
```
### Setup Guide
To set up the development environment, follow these steps in order:
1. **Initial Setup**: Run the devcontainer setup script first to check prerequisites and prepare the environment:
```bash
chmod +x devcontainer-setup.sh
./devcontainer-setup.sh
```
This script will check if you have Docker and VS Code installed, pull the necessary Docker image, and offer to open VS Code with the devcontainer.
2. **Container Initialization**: When the devcontainer starts, the `container-setup.sh` script will run automatically to install all dependencies. This may take several minutes. If you need to run this script manually:
```bash
chmod +x container-setup.sh
./container-setup.sh
```
3. **Verify Installation**: Once the setup is complete, verify that everything is working correctly:
```bash
cabal build all
cabal test all
```
After completing these steps, your development environment will be fully set up with all dependencies installed for offline development.
### Using Cabal
To build the project using Cabal:
```bash
cabal update # Fetches the latest package list from Hackage
cabal build all # Builds all packages in the project
cabal test all # Tests all packages in the project
```
This will compile all local packages defined in your `cabal.project` file.
To install executables (if any) from the project:
```bash
# Replace with the actual executable name from your .cabal file
cabal install exe: --install-method=copy --overwrite-policy=always
```
Or, to run an executable directly:
```bash
# Replace with the actual executable name
cabal run exe: -- arguments
```
### Using Stack
(Optional: If you set up a `stack.yaml` for the project)
```bash
stack setup # Downloads the correct GHC version if needed
stack build # Builds all packages
stack test # Tests all packages
```
To run an executable:
```bash
# Replace with the actual executable name
stack exec -- arguments
```
## Usage
### Library
The primary library provided by this project is `core`. To use it in another Haskell project, add `core` (or the specific package name you intend to use if it differs) to the `build-depends` section of your `.cabal` file.
```haskell
-- Example of using a function from the 'core' library
import Core.SomeModule (someFunction) -- TODO: Update with actual module and function
main :: IO ()
main = do
putStrLn "Using the HAIRY library:"
print (someFunction 42) -- TODO: Update with actual function call
```
### Executables
If the HAIRY project provides any command-line executables, describe how to run them here.
```bash
# For Cabal (replace with actual name)
cabal run exe: -- --option1 value1 --option2
# For Stack (replace with actual name, if using Stack)
stack exec -- --option1 value1 --option2
```
## Running Tests
To run all test suites in the project:
### Using Cabal
```bash
cabal test all
```
This command will execute all test suites defined in the `.cabal` files of your local packages (e.g., `m31-tests` from the `core` package).
If you're looking to create some coverage reports then you can run:
```bash
cabal test all --enable-coverage
```
## Development
Information for developers:
- **Setting up a development environment**: Standard `cabal build all` or `stack build` should suffice.
- **Interactive Development (REPL)**:
```bash
# For a specific component (e.g., the 'core' library)
cabal repl lib:core
# Or for a test suite
cabal repl test:m31-tests
```
- **Live Reloading (GHCID)**: Install `ghcid` (`cabal install ghcid` or `stack install ghcid`) then run:
```bash
ghcid --command="cabal repl lib:core" # Or your target component
```
- **Code Formatting**: Consider using [Ormolu](https://github.com/tweag/ormolu) or [Fourmolu](https://github.com/fourmolu/fourmolu).
```bash
# Example with Ormolu
ormolu -i . # Formats files in place
```
- **Linting**: [HLint](https://github.com/ndmitchell/hlint) is a popular choice.
```bash
hlint .
```
## Development Environment
### Using DevContainer
This project includes a devcontainer configuration for easy development setup. The devcontainer provides a consistent development environment with all necessary tools pre-installed.
To use the devcontainer:
1. Make sure you have Docker and VS Code with the Remote - Containers extension installed.
2. Run the setup script at the root of the repository:
```bash
./devcontainer-setup.sh
```
This script will check prerequisites, pull the required Docker image, and provide options to open the project in VS Code with the devcontainer.
3. Alternatively, you can open the project in VS Code and use the command palette (F1) to select "Remote-Containers: Open Folder in Container..."
The devcontainer includes:
- GHC 9.6.3
- Cabal
- Python 3 with required dependencies
- All the tools needed for development
### Offline Development
This project is designed to support offline development once the container is set up. The `container-setup.sh` script installs all necessary dependencies and development tools during container initialization, including:
- Haskell development tools (hlint, ormolu, ghcid, cabal-fmt, hoogle)
- Python testing and linting tools (pytest, black, flake8, mypy)
- Common Haskell libraries pre-downloaded for offline use
- Full documentation via Hoogle
When working in the devcontainer, you should have everything needed without requiring further internet access.
To manually run the setup script (if needed):
```bash
./container-setup.sh
```
## Continuous Integration
This project uses GitHub Actions for continuous integration. The CI workflow:
- Runs on every push to main/master branches and on pull requests
- Sets up the Haskell environment with GHC 9.6.3
- Installs Python dependencies
- Builds and tests all packages
- Uses caching to speed up builds
You can see the build status in the badge at the top of this README.
## Contributing
Contributions are welcome! Please follow these general steps:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature-name`).
3. Make your changes.
4. Ensure tests pass (`cabal test all` or `stack test`).
5. Add tests for new features or bug fixes.
6. Format and lint your code.
7. Commit your changes (`git commit -am 'Add some feature'`).
8. Push to the branch (`git push origin feature/your-feature-name`).
9. Create a new Pull Request.
Please make sure to update tests and documentation as appropriate.
## License
This project is licensed under the MIT License. You should create a `LICENSE` file in the root of your project with the full text of the MIT license, or your chosen license.