From df60e2867ad75d6e8e273d7dca874dc7e79486fd Mon Sep 17 00:00:00 2001
From: Jan Liphardt <jan.liphardt@stanford.edu>
Date: Sat, 3 Apr 2021 11:13:54 -0700
Subject: [PATCH 1/2] Create .gitignore

---
 .gitignore | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a81c8ee
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,138 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

From 98e527c7c5f3ad74987fb8f6cfe0f9f03be6fe04 Mon Sep 17 00:00:00 2001
From: Jan Liphardt <jan@enya.ai>
Date: Sat, 3 Apr 2021 11:42:02 -0700
Subject: [PATCH 2/2] begin to explain code

---
 README.md                                 | 16 ++++++++++++++++
 py_ecc/optimized_bn128/optimized_curve.py |  8 ++++++++
 2 files changed, 24 insertions(+)

diff --git a/README.md b/README.md
index fc7a59b..aff481d 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,17 @@
 Implements optimal ate pairings over the bn\_128 curve.
+
+### Pairings
+
+See (Subgroup security in pairing-based cryptography)[https://eprint.iacr.org/2015/247.pdf]
+
+TL;DR Some elliptic curves are "pairing friendly", such as BN, KSS and, BLS. Pairing is relevant to multitude of useful cryptographic operations, such as identity-based encryption, bulletproofs, and zkSNARKs. However, when ordinary curves are paired, vulnerabilities can be introduced, specifically, so-called subgroup attacks become feasible in certain circumstances. This code base instantiates one specific subgroup-secure pairing-friendly curve family, BN (k = 12). 
+
+Parameters are drawn from (Subgroup security in pairing-based cryptography)[https://eprint.iacr.org/2015/247.pdf], Example 1. In general, there are few ramifications for 'downstream' ECC applications, expect for a minor (2 to 13%) slowdown of pairing related computations (per Table 2 of Barreto et al.).
+
+### Usage
+
+```python
+python3 setup.py install
+
+cd tests && python3 test_bn128.py    
+```
\ No newline at end of file
diff --git a/py_ecc/optimized_bn128/optimized_curve.py b/py_ecc/optimized_bn128/optimized_curve.py
index f8a872d..b2ae877 100644
--- a/py_ecc/optimized_bn128/optimized_curve.py
+++ b/py_ecc/optimized_bn128/optimized_curve.py
@@ -1,5 +1,13 @@
 from .optimized_field_elements import FQ2, FQ12, field_modulus, FQ
 
+# Cofactor
+    # from libff comments
+    # [Sage excerpt]
+    # See: https://eprint.iacr.org/2015/247.pdf
+    # u = 4965661367192848881
+    # h2 = (36 * u^4) + (36 * u^3) + (30 * u^2) + 6*u + 1; h2
+    # # 21888242871839275222246405745257275088844257914179612981679871602714643921549
+
 curve_order = 21888242871839275222246405745257275088548364400416034343698204186575808495617
 
 # Curve order should be prime