Metadata-Version: 2.2
Name: dot-ring
Version: 0.1.9
Summary: Serves as a library to generate and verify a signature using IETF, Pedersen and Ring VRF-AD Schemes
Author-email: prasad-kumkar <prasad@chainscore.finance>
License: MIT
Project-URL: Homepage, https://github.com/chainscore/dot-ring
Project-URL: Repository, https://github.com/chainscore/dot-ring
Project-URL: Issues, https://github.com/chainscore/dot-ring/issues
Project-URL: Documentation, https://github.com/chainscore/dot-ring#readme
Keywords: VRF,VRF-AD,IETF VRF,Pedersen VRF,Ring Proof,Ring VRF,Signature,Proof,Verify,Cryptography,Zero Knowledge,PCS,KZG,FFT,Polynomial,Interpolation,Ring Root,Commitment,Constraints,fflonk,powers of tau,string to point,point to string,encode to curve,public key,elliptic curve cryptography,proof to hash,bls12_381,Bandersnatch,fiat shamir,pairings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Communications
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.2.3
Requires-Dist: sympy>=1.13.1
Requires-Dist: pytest>=8.3.5
Requires-Dist: py-ecc>=8.0.0
Requires-Dist: gmpy2>=2.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: Cython>=3.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: setuptools>=65.0.0; extra == "dev"
Requires-Dist: wheel>=0.38.0; extra == "dev"

![alt text](https://raw.githubusercontent.com/Chainscore/dot-ring/refs/heads/main/docs/cover.svg)

[![Tests](https://github.com/Chainscore/dot-ring/actions/workflows/test.yml/badge.svg)](https://github.com/Chainscore/dot-ring/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/Chainscore/dot-ring/branch/main/graph/badge.svg)](https://codecov.io/gh/Chainscore/dot-ring)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

`dot-ring` is a Python library for Verifiable Random Functions with Additional Data (VRF-AD) supporting 10+ elliptic curves, including IETF VRF, Pedersen VRF, and Ring VRF.

**Specifications:**
[Bandersnatch VRF](https://github.com/davxy/bandersnatch-vrf-spec) •
[Ring Proof](https://github.com/davxy/ring-proof-spec) •
[RFC9381](https://datatracker.ietf.org/doc/rfc9381) •
[RFC9380](https://datatracker.ietf.org/doc/rfc9380)

---

## Installation

### Install from PyPI (Recommended)

Pre-built wheels are available for Linux and macOS - no build tools required:

```bash
pip install dot-ring
```

### Development Setup

For building from source, you need system dependencies:

| OS | Command |
|----|---------|
| **macOS** | `brew install swig` |
| **Ubuntu/Debian** | `sudo apt install swig build-essential` |
| **Fedora/RHEL** | `sudo dnf install swig gcc-c++` |
| **Arch** | `sudo pacman -S swig base-devel` |

Then install in development mode:

```bash
git clone https://github.com/chainscore/dot-ring.git
cd dot-ring
pip install -e .[dev]
```

---

## Usage

```python
secret_key = bytes.fromhex("3d6406500d4009fdf2604546093665911e753f2213570a29521fd88bc30ede18")
alpha = b"input data"
ad = b"additional data"
```

Deterministic key generation from a seed (matching ark-vrf):

```python
from dot_ring import Bandersnatch, secret_from_seed

seed = (0).to_bytes(32, "little")
public_key, secret_scalar = secret_from_seed(seed, Bandersnatch)
```

### IETF VRF

```python
from dot_ring import Bandersnatch, IETF_VRF

# Generate proof
proof = IETF_VRF[Bandersnatch].prove(alpha, secret_key, ad)

# Verify
public_key = IETF_VRF[Bandersnatch].get_public_key(secret_key)
is_valid = proof.verify(public_key, alpha, ad)

# Serialize
proof_bytes = proof.to_bytes()
proof = IETF_VRF[Bandersnatch].from_bytes(proof_bytes)
```

### Pedersen VRF

```python
from dot_ring import Bandersnatch, PedersenVRF

# Generate proof (public key is blinded in proof)
proof = PedersenVRF[Bandersnatch].prove(alpha, secret_key, ad)

# Verify
is_valid = proof.verify(alpha, ad)
```

### Ring VRF

```python
from dot_ring import Bandersnatch, RingVRF

# Setup ring
ring_pks = [pk1, pk2, pk3, ...]  # list of public keys
ring_root = RingVRF[Bandersnatch].construct_ring_root(ring_pks)

# Generate proof
my_pk = RingVRF[Bandersnatch].get_public_key(secret_key)
proof = RingVRF[Bandersnatch].prove(alpha, ad, secret_key, my_pk, ring_pks)

# Verify (proves membership without revealing which key)
is_valid = proof.verify(alpha, ad, ring_root)
```

---

## Testing

```bash
pytest tests/
```

See [TESTING.md](./TESTING.md) for details.

---

## Docker

```bash
docker build -t dot-ring .
docker run -it dot-ring pytest tests/
```

---

## Troubleshooting

| Error | Solution |
|-------|----------|
| `swig: command not found` | Only needed for building from source. Install: `brew install swig` / `apt install swig` |
| `gcc failed` | Only needed for building from source. Install: `xcode-select --install` / `apt install build-essential` |
| Import errors | Try: `pip install dot-ring --force-reinstall --no-cache-dir` |

---

## Contact

**Prasad // Chainscore Labs**

![alt text](https://raw.githubusercontent.com/Chainscore/dot-ring/refs/heads/main/docs/chainscore.png)

[Email](mailto:prasad@chainscore.finance) • [Website](https://chainscore.finance)

## Benchmarks

See the `docs/BENCHMARK.md` for performance results.
