dot-ring 0.1.0__tar.gz

dot_ring-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chainscore Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dot_ring-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include pyproject.toml
+include README.md
+include LICENSE
+recursive-include dot_ring *.pyx *.pxd *.c *.h
+recursive-include dot_ring/blst *.so *.dylib *.dll

dot_ring-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: dot-ring
+Version: 0.1.0
+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-Expression: 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.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.12
+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>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.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"
+Dynamic: license-file
+
+![alt text](./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)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+`@dot-ring` is a Python library for generating Verifiable Random Functions with Additional Data (VRF-AD) on 10+ Elliptic Curves, including IETF, Pedersen VRF and Ring Proof.
+
+
+Specifications in compliance: 
+- [Bandersnatch VRF](https://github.com/davxy/bandersnatch-vrf-spec/blob/main/specification.md) 
+- [Ring Proof](https://github.com/davxy/ring-proof-spec)
+- [RFC9381](https://datatracker.ietf.org/doc/rfc9381)
+- [RFC9380](https://datatracker.ietf.org/doc/rfc9380)
+- [BCGSV23](https://eprint.iacr.org/2023/002)
+- [MSZ21](https://eprint.iacr.org/2021/1152)
+---
+
+## Installation & Setup
+
+### Prerequisites
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) (Recommended for dependency management)
+
+### Installation using uv (Recommended)
+
+1.  **Install uv** (if not already installed):
+    ```bash
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
+
+2.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/chainscore/dot-ring.git
+    cd dot-ring
+    ```
+
+3.  **Run the setup script**:
+    This script installs all dependencies, builds `blst` bindings, and compiles Cython extensions.
+    ```bash
+    ./setup.sh
+    ```
+
+### Manual Installation
+
+If you prefer not to use `uv` or the setup script, you can install using pip:
+
+```bash
+pip install .
+# For development dependencies
+pip install .[dev]
+```
+
+To install `blst` manually:
+```bash
+git clone https://github.com/supranational/blst.git .blst
+cd .blst/bindings/python
+./run.me
+# Then ensure the generated blst.py and shared library are in your PYTHONPATH or site-packages
+export PYTHONPATH=YOUR_PATH_HERE/blst/bindings/python:$PYTHONPATH
+```
+
+## Example Usage
+```python
+# Sample test vector
+secret_key="3d6406500d4009fdf2604546093665911e753f2213570a29521fd88bc30ede18"
+alpha=""
+salt=""
+add=""
+ring_pks="7b32d917d5aa771d493c47b0e096886827cd056c82dbdba19e60baa8b2c60313d3b1bdb321123449c6e89d310bc6b7f654315eb471c84778353ce08b951ad471561fdb0dcfb8bd443718b942f82fe717238cbcf8d12b8d22861c8a09a984a3c5a1b1da71cc4682e159b7da23050d8b6261eb11a3247c89b07ef56ccd002fd38b4fd11f89c2a1aaefe856bb1c5d4a1fad73f4de5e41804ca2c17ba26d6e10050c86d06ee2c70da6cf2da2a828d8a9d8ef755ad6e580e838359a10accb086ae437ad6fdeda0dde0a57c51d3226b87e3795e6474393772da46101fd597fbd456c1b3f9dc0c4f67f207974123830c2d66988fb3fb44becbbba5a64143f376edc51d9"
+```
+### For IETF VRF
+```python
+from dot_ring import Bandersnatch, IETF_VRF
+
+# Generate Proof
+proof: IETF_VRF = IETF_VRF[Bandersnatch].proof(alpha, secret_key, add)
+# Or from bytes
+proof_bytes = proof.to_bytes()
+proof: IETF_VRF = IETF_VRF[Bandersnatch].from_bytes(proof_bytes)
+
+# Verify Proof
+public_key = IETF_VRF[Bandersnatch].get_public_key(secret_key)
+is_valid: bool = proof.verify(public_key, alpha, add)
+```
+
+### For Pedersen VRF
+```python
+from dot_ring import Bandersnatch, PedersenVRF
+
+# Generate Proof
+proof: PedersenVRF = PedersenVRF[Bandersnatch].proof(alpha, secret_key, add)
+# Or import from bytes
+proof_bytes = proof.to_bytes()
+proof: PedersenVRF = PedersenVRF[Bandersnatch].from_bytes(proof_bytes)
+
+# Verify Proof
+# Public key is blinded in Pedersen VRF and included in the proof
+is_valid: bool = proof.verify(alpha, add)
+```
+
+### For Ring VRF
+```python
+from dot_ring import Bandersnatch, RingVRF
+
+# Parse keys if they are in a single byte string
+keys_list = RingVRF[Bandersnatch].parse_keys(ring_pks)
+
+# Generate ring root commitment
+ring_root = RingVRF[Bandersnatch].construct_ring_root(keys_list)
+
+# Generate Ring VRF proof
+# producer_key is the public key corresponding to secret_key
+producer_key = RingVRF[Bandersnatch].get_public_key(secret_key)
+proof: RingVRF = RingVRF[Bandersnatch].proof(alpha, add, secret_key, producer_key, keys_list)
+# Or from bytes
+proof_bytes = proof.to_bytes() # 768 bytes ring proof
+proof: RingVRF = RingVRF[Bandersnatch].from_bytes(proof_bytes)
+# Verify Ring VRF Proof
+is_valid: bool = proof.verify(alpha, add, ring_root)
+```
+
+
+## Testing
+
+You can run the test suite with **pytest** using `uv`:
+
+```bash
+uv run pytest tests/
+```
+See [TESTING.md](./TESTING.md) for an overview of the test suite and instructions on running tests.
+
+
+## Docker Setup
+
+### Build the Docker Image
+```bash
+docker build -t dot_ring .
+```
+
+### Run tests inside a container
+```bash
+docker run -it dot_ring uv run pytest tests/
+```
+
+### Generate a Coverage report
+- Terminal summary
+```bash
+docker run -it dot_ring uv run pytest tests/ --cov=dot_ring --cov-report=term-missing
+```
+
+- HTML report
+```bash
+docker run -it dot_ring uv run pytest tests/ --cov=dot_ring --cov-report=html
+open htmlcov/index.html #open it in your browser
+``` 
+Access an interactive shell inside the container
+```bash
+docker run -it dot_ring bash
+```
+
+## Contact
+
+Prasad // Chainscore Labs
+
+![alt text](<docs/chainscore.png>)
+
+[Email](mailto:prasad@chainscore.finance)
+
+[Website](https://chainscore.finance)

dot_ring-0.1.0/README.md

@@ -0,0 +1,172 @@
+![alt text](./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)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+`@dot-ring` is a Python library for generating Verifiable Random Functions with Additional Data (VRF-AD) on 10+ Elliptic Curves, including IETF, Pedersen VRF and Ring Proof.
+
+
+Specifications in compliance: 
+- [Bandersnatch VRF](https://github.com/davxy/bandersnatch-vrf-spec/blob/main/specification.md) 
+- [Ring Proof](https://github.com/davxy/ring-proof-spec)
+- [RFC9381](https://datatracker.ietf.org/doc/rfc9381)
+- [RFC9380](https://datatracker.ietf.org/doc/rfc9380)
+- [BCGSV23](https://eprint.iacr.org/2023/002)
+- [MSZ21](https://eprint.iacr.org/2021/1152)
+---
+
+## Installation & Setup
+
+### Prerequisites
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) (Recommended for dependency management)
+
+### Installation using uv (Recommended)
+
+1.  **Install uv** (if not already installed):
+    ```bash
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
+
+2.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/chainscore/dot-ring.git
+    cd dot-ring
+    ```
+
+3.  **Run the setup script**:
+    This script installs all dependencies, builds `blst` bindings, and compiles Cython extensions.
+    ```bash
+    ./setup.sh
+    ```
+
+### Manual Installation
+
+If you prefer not to use `uv` or the setup script, you can install using pip:
+
+```bash
+pip install .
+# For development dependencies
+pip install .[dev]
+```
+
+To install `blst` manually:
+```bash
+git clone https://github.com/supranational/blst.git .blst
+cd .blst/bindings/python
+./run.me
+# Then ensure the generated blst.py and shared library are in your PYTHONPATH or site-packages
+export PYTHONPATH=YOUR_PATH_HERE/blst/bindings/python:$PYTHONPATH
+```
+
+## Example Usage
+```python
+# Sample test vector
+secret_key="3d6406500d4009fdf2604546093665911e753f2213570a29521fd88bc30ede18"
+alpha=""
+salt=""
+add=""
+ring_pks="7b32d917d5aa771d493c47b0e096886827cd056c82dbdba19e60baa8b2c60313d3b1bdb321123449c6e89d310bc6b7f654315eb471c84778353ce08b951ad471561fdb0dcfb8bd443718b942f82fe717238cbcf8d12b8d22861c8a09a984a3c5a1b1da71cc4682e159b7da23050d8b6261eb11a3247c89b07ef56ccd002fd38b4fd11f89c2a1aaefe856bb1c5d4a1fad73f4de5e41804ca2c17ba26d6e10050c86d06ee2c70da6cf2da2a828d8a9d8ef755ad6e580e838359a10accb086ae437ad6fdeda0dde0a57c51d3226b87e3795e6474393772da46101fd597fbd456c1b3f9dc0c4f67f207974123830c2d66988fb3fb44becbbba5a64143f376edc51d9"
+```
+### For IETF VRF
+```python
+from dot_ring import Bandersnatch, IETF_VRF
+
+# Generate Proof
+proof: IETF_VRF = IETF_VRF[Bandersnatch].proof(alpha, secret_key, add)
+# Or from bytes
+proof_bytes = proof.to_bytes()
+proof: IETF_VRF = IETF_VRF[Bandersnatch].from_bytes(proof_bytes)
+
+# Verify Proof
+public_key = IETF_VRF[Bandersnatch].get_public_key(secret_key)
+is_valid: bool = proof.verify(public_key, alpha, add)
+```
+
+### For Pedersen VRF
+```python
+from dot_ring import Bandersnatch, PedersenVRF
+
+# Generate Proof
+proof: PedersenVRF = PedersenVRF[Bandersnatch].proof(alpha, secret_key, add)
+# Or import from bytes
+proof_bytes = proof.to_bytes()
+proof: PedersenVRF = PedersenVRF[Bandersnatch].from_bytes(proof_bytes)
+
+# Verify Proof
+# Public key is blinded in Pedersen VRF and included in the proof
+is_valid: bool = proof.verify(alpha, add)
+```
+
+### For Ring VRF
+```python
+from dot_ring import Bandersnatch, RingVRF
+
+# Parse keys if they are in a single byte string
+keys_list = RingVRF[Bandersnatch].parse_keys(ring_pks)
+
+# Generate ring root commitment
+ring_root = RingVRF[Bandersnatch].construct_ring_root(keys_list)
+
+# Generate Ring VRF proof
+# producer_key is the public key corresponding to secret_key
+producer_key = RingVRF[Bandersnatch].get_public_key(secret_key)
+proof: RingVRF = RingVRF[Bandersnatch].proof(alpha, add, secret_key, producer_key, keys_list)
+# Or from bytes
+proof_bytes = proof.to_bytes() # 768 bytes ring proof
+proof: RingVRF = RingVRF[Bandersnatch].from_bytes(proof_bytes)
+# Verify Ring VRF Proof
+is_valid: bool = proof.verify(alpha, add, ring_root)
+```
+
+
+## Testing
+
+You can run the test suite with **pytest** using `uv`:
+
+```bash
+uv run pytest tests/
+```
+See [TESTING.md](./TESTING.md) for an overview of the test suite and instructions on running tests.
+
+
+## Docker Setup
+
+### Build the Docker Image
+```bash
+docker build -t dot_ring .
+```
+
+### Run tests inside a container
+```bash
+docker run -it dot_ring uv run pytest tests/
+```
+
+### Generate a Coverage report
+- Terminal summary
+```bash
+docker run -it dot_ring uv run pytest tests/ --cov=dot_ring --cov-report=term-missing
+```
+
+- HTML report
+```bash
+docker run -it dot_ring uv run pytest tests/ --cov=dot_ring --cov-report=html
+open htmlcov/index.html #open it in your browser
+``` 
+Access an interactive shell inside the container
+```bash
+docker run -it dot_ring bash
+```
+
+## Contact
+
+Prasad // Chainscore Labs
+
+![alt text](<docs/chainscore.png>)
+
+[Email](mailto:prasad@chainscore.finance)
+
+[Website](https://chainscore.finance)

dot_ring-0.1.0/dot_ring/__init__.py

@@ -0,0 +1,118 @@
+"""
+dot-ring: A Python library for Verifiable Random Functions with Additional Data (VRF-AD).
+
+Supports 10+ elliptic curves including IETF, Pedersen VRF and Ring Proof.
+
+Example usage:
+    >>> from dot_ring import Bandersnatch, IETF_VRF, PedersenVRF, RingVRF
+    >>> 
+    >>> # IETF VRF
+    >>> proof = IETF_VRF[Bandersnatch].proof(alpha, secret_key, additional_data)
+    >>> is_valid = proof.verify(public_key, alpha, additional_data)
+    >>>
+    >>> # Pedersen VRF
+    >>> proof = PedersenVRF[Bandersnatch].proof(alpha, secret_key, additional_data)
+    >>> is_valid = proof.verify(alpha, additional_data)
+    >>>
+    >>> # Ring VRF
+    >>> ring_root = RingVRF[Bandersnatch].construct_ring_root(keys_list)
+    >>> proof = RingVRF[Bandersnatch].proof(alpha, ad, secret_key, producer_key, keys)
+    >>> is_valid = proof.verify(alpha, ad, ring_root)
+"""
+
+__version__ = "0.1.0"
+
+# =============================================================================
+# VRF Implementations
+# =============================================================================
+from dot_ring.vrf.ietf.ietf import IETF_VRF
+from dot_ring.vrf.pedersen.pedersen import PedersenVRF
+from dot_ring.vrf.ring.ring_vrf import RingVRF
+
+# =============================================================================
+# Curve Variants - Primary curves
+# =============================================================================
+from dot_ring.curve.specs.bandersnatch import Bandersnatch
+from dot_ring.curve.specs.bandersnatch_sw import Bandersnatch_SW
+from dot_ring.curve.specs.ed25519 import Ed25519_RO, Ed25519_NU
+from dot_ring.curve.specs.ed448 import Ed448_RO, Ed448_NU
+from dot_ring.curve.specs.curve25519 import Curve25519_RO, Curve25519_NU
+from dot_ring.curve.specs.curve448 import Curve448_RO, Curve448_NU
+
+# NIST curves
+from dot_ring.curve.specs.p256 import P256_RO, P256_NU
+from dot_ring.curve.specs.p384 import P384_RO, P384_NU
+from dot_ring.curve.specs.p521 import P521_RO, P521_NU
+from dot_ring.curve.specs.secp256k1 import Secp256k1_RO, Secp256k1_NU
+
+# ZK-friendly curves
+from dot_ring.curve.specs.baby_jubjub import BabyJubJub
+from dot_ring.curve.specs.jubjub import JubJub
+
+# BLS12-381 curves
+from dot_ring.curve.specs.bls12_381_G1 import BLS12_381_G1_RO, BLS12_381_G1_NU
+from dot_ring.curve.specs.bls12_381_G2 import BLS12_381_G2_RO, BLS12_381_G2_NU
+
+# =============================================================================
+# Convenience aliases
+# =============================================================================
+Ed25519 = Ed25519_RO
+Ed448 = Ed448_RO
+Curve25519 = Curve25519_RO
+Curve448 = Curve448_RO
+P256 = P256_RO
+P384 = P384_RO
+P521 = P521_RO
+Secp256k1 = Secp256k1_RO
+BLS12_381_G1 = BLS12_381_G1_RO
+BLS12_381_G2 = BLS12_381_G2_RO
+
+# =============================================================================
+# Public API
+# =============================================================================
+__all__ = [
+    # Version
+    "__version__",
+    # VRF implementations
+    "IETF_VRF",
+    "PedersenVRF", 
+    "RingVRF",
+    # Primary curves
+    "Bandersnatch",
+    "Bandersnatch_SW",
+    "Ed25519",
+    "Ed25519_RO",
+    "Ed25519_NU",
+    "Ed448",
+    "Ed448_RO",
+    "Ed448_NU",
+    "Curve25519",
+    "Curve25519_RO",
+    "Curve25519_NU",
+    "Curve448",
+    "Curve448_RO",
+    "Curve448_NU",
+    # NIST curves
+    "P256",
+    "P256_RO",
+    "P256_NU",
+    "P384",
+    "P384_RO",
+    "P384_NU",
+    "P521",
+    "P521_RO",
+    "P521_NU",
+    "Secp256k1",
+    "Secp256k1_RO",
+    "Secp256k1_NU",
+    # ZK-friendly curves
+    "BabyJubJub",
+    "JubJub",
+    # BLS12-381
+    "BLS12_381_G1",
+    "BLS12_381_G1_RO",
+    "BLS12_381_G1_NU",
+    "BLS12_381_G2",
+    "BLS12_381_G2_RO",
+    "BLS12_381_G2_NU",
+]