From a127534938876d74ea44f0cd14a7f9223a1d6ea1 Mon Sep 17 00:00:00 2001
From: Chih Cheng Liang <chihchengliang@gmail.com>
Date: Sat, 9 Mar 2019 01:30:00 +0800
Subject: [PATCH] add document of BLS api

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index b4e313b..f646686 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,55 @@ Elliptic curve crypto in python including secp256k1 and alt_bn128
 pip install py_ecc
 ```
 
+## BLS Signatures
+
+```python
+from py_ecc import bls
+
+domain = 43
+
+private_key = 5566
+public_key = bls.privtopub(private_key)
+
+# Hash your message to 32 bytes
+message_hash = b'\xab' * 32
+
+# Signing
+signature = bls.sign(message_hash, private_key, domain)
+
+# Verifying
+assert bls.verify(message_hash, public_key, signature, domain)
+```
+
+Think of a `domain` as a version. Signing and verifying would not work on different domains. Setting a new domain in an upgraded system prevents it from being affected by the old messages and signatures.
+
+### Aggregating Signatures and Public Keys
+
+```python
+private_keys = [3, 14, 159]
+public_keys = [bls.privtopub(key) for key in private_keys]
+signatures = [bls.sign(message_hash, key, domain) for key in private_keys]
+
+# Aggregating
+agg_sig = bls.aggregate_signatures(signatures)
+agg_pub = bls.aggregate_pubkeys(public_keys)
+
+# Verifying
+assert bls.verify(message_hash, agg_pub, agg_sig, domain)
+```
+
+### Multiple Aggregation
+
+```python
+message_hash_1, message_hash_2 = b'\xaa' * 32, b'\xbb' * 32
+
+msg_hashes = [message_hash_1, message_hash_2]
+agg_pubs = [agg_pub_1, agg_pub_2]
+agg_agg_sig = bls.aggregate_signatures([agg_sig_1, agg_sig_2])
+
+assert bls.verify_multiple(agg_pubs, msg_hashes, agg_agg_sig, domain)
+```
+
 ## Developer Setup
 
 If you would like to hack on py_ecc, please check out the [Ethereum Development Tactical Manual](https://github.com/ethereum/ethereum-dev-tactical-manual) for information on how we do: