Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: enhance README with comprehensive contribution guidelines #51

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: enhance README with comprehensive contribution guidelines #51

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 60 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,25 +5,52 @@ At [Trail of Bits](https://www.trailofbits.com/), we audit many implementations

We hope that ZKDocs can fill in this gap and benefit the larger cryptography community.

### Comprehensive
We aim to be both self-contained and comprehensive in the topics related to zero-knowledge proof systems, from descriptions of simple systems like Schnorr’s identification protocol, to complex proof systems like Paillier-Blum modulus. We also cover cryptographic primitives such as: random sampling, Fiat-Shamir transformation, and Shamir's Secret Sharing.
## Key Features

### Comprehensive
We aim to be both self-contained and comprehensive in the topics related to zero-knowledge proof systems, from descriptions of simple systems like Schnorr's identification protocol, to complex proof systems like Paillier-Blum modulus. We also cover cryptographic primitives such as: random sampling, Fiat-Shamir transformation, and Shamir's Secret Sharing.

### Detailed
We describe each protocol in great detail, including all necessary setup, sanity-checks, auxiliary algorithms, further references, and potential security pitfalls with their associated severity.


### Interactive

The protocol descriptions are interactive, letting you modify variable names. This allows you to match the variable names in ZKdocs' specification to the variable names in your code, making it easier to find bugs and missing assertions.

![Basic interactivity usage](/static/figs/demo.gif)

Interactivity features:
- Click on a variable to highlight it across the document.
- Type or paste with a variable highlighted to edit its name. Press `Enter` or `Escape` to stop editing.
#### Interactivity features:
- Click on a variable to highlight it across the document
- Type or paste with a variable highlighted to edit its name. Press `Enter` or `Escape` to stop editing
- Press the `Reset variable names` button to reset the names of all variables on the current page (variable names are independent across different pages)

## Getting Started

### Prerequisites
- [Hugo](https://gohugo.io/documentation/) (v0.80.0 or later)
- macOS: `brew install hugo`
- Windows: `choco install hugo-extended`
- Linux: `sudo apt install hugo`

### Local Development
1. Clone the repository:
```bash
git clone https://github.com/trailofbits/zkdocs.git
cd zkdocs
```

2. Start the development server:
```bash
hugo server --minify --theme book
```

3. Open your browser and navigate to `http://localhost:1313`

### Testing
Before submitting your changes, make sure to:
1. Run the development server and verify your changes locally
2. Check that all mathematical formulas render correctly
3. Test the interactive features with your modifications

----

## Roadmap
Expand Down Expand Up @@ -62,7 +89,6 @@ Interactivity features:

----


## Dependencies
- [hugo](https://gohugo.io/documentation/) - install with

Expand Down Expand Up @@ -97,3 +123,29 @@ Interactivity features:
{{< /rawhtml >}}
```
- [header.html](themes/book/layouts/partials/docs/header.html) has all latex macros if more need to be added. In particular it includes all interactive variable macros that the javascript handles afterwards. So, if you write `$\varz$` it will default to a `z` but the user can change its name anywhere on the page.

## Contributing Guidelines

### How to Contribute
1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Submit a pull request

### Commit Message Format
Please follow these guidelines for commit messages:
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line

### Documentation Style
- The file [schnorr.md](/content/docs/zkdocs/zero-knowledge-protocols/schnorr.md) serves as a template for protocol documentation
- Use LaTeX macros for consistent protocol representation
- Follow the existing structure for new protocol additions

## License
This project is licensed under the MIT License - see the LICENSE file for details

## Contact
For questions and support, please open an issue in the GitHub repository.