Added READMEs

README.md

@@ -1,12 +1,40 @@
 # BLS12-381 Curve Signature
 
-This repo contains Dusk Network's [implementation](https://github.com/bls12_381-sign/rust/bls12_381-sign) of the BLS Signatures using the BLS12-381 curve
+This repo contains Dusk Network's [implementation](https://github.com/bls12_381-sign/rust/bls12_381-sign) of the BLS Signatures using the BLS12-381 curve. This implementation currently only supports rogue-key attack resistant batching, and does not support distinct message verification.
 
-## Go
+## Rust
 
-Two options are provided to work with the library from Go:
+The [library](https://github.com/bls12_381-sign/rust/bls12_381-sign) is written in rust.
 
-1. Using unix sockets for IPC communication through GRPC with a rust service that calls the library.
-2. Using cgo bindings to interface directly with the library binaries.
+We also provide a sample IPC [micro-service](https://github.com/bls12_381-sign/rust/grpc-server) that provides a synchronous gRPC interface to the library for third-party clients.
 
-## TBC...
+## Go
+
+We provide a couple options to work with the library using Go:
+
+1. [Using CGo](https://github.com/bls12_381-sign/go/bls/cgo) to build and link directly to the lib binaries.
+1. [Using gRPC](https://github.com/bls12_381-sign/go/bls/grpc) to communicate with our simple lib IPC server.
+
+## Benchmarks
+
+We've found the CGo version to perform faster with `Go 1.17+`
+
+Recent benchmarks are attached for reference:
+
+### CGo
+```
+cpu: Intel(R) Xeon(R) CPU E5-2673 v4 @ 2.30GHz
+BenchmarkSign              	    1264	   4416508 ns/op	      48 B/op	       1 allocs/op
+BenchmarkVerify            	     706	   8568588 ns/op	       0 B/op	       0 allocs/op
+BenchmarkAggregatePk       	     864	   6687951 ns/op	     216 B/op	       3 allocs/op
+BenchmarkAggregateSig      	    4274	   1443901 ns/op	     120 B/op	       3 allocs/op
+```
+
+### gRPC
+
+```
+BenchmarkSign           	    1317	   4507956 ns/op	    5317 B/op	      95 allocs/op
+BenchmarkVerify         	     693	   8767921 ns/op	    5207 B/op	      94 allocs/op
+BenchmarkAggregatePk    	     656	   9209897 ns/op	    5385 B/op	      96 allocs/op
+BenchmarkAggregateSig   	    3651	   1645111 ns/op	    5194 B/op	      96 allocs/op
+```

go/bls/cgo/README.md

@@ -0,0 +1,11 @@
+# CGo Wrapper for BLS12-381 Sign
+
+`bls.go` exposes a CGo wrapper to the native rust [bls12-381 signing library](https://github.com/dusk-network/bls12_381-sign/rust/bls12_381-sign).
+
+## Building
+
+`Makefile` at the repo root takes care of everything, but essentially you'll want to have the built lib binaries in this directory for GCC to link against them as specified in the CGo headers at the top of `bls.go`. We provide pre-built binaries for Ubuntu and Darwin for convenience.
+
+## Usage
+
+This module exports all required methods to satisfy the [Bls12381Sign Interface](https://github.com/dusk-network/bls12_381-sign/go/bls.go). Please check `bls_test.go` for a few examples.

go/bls/grpc/README.md

@@ -0,0 +1,13 @@
+# gRPC Client for BLS12-381 Sign
+
+`bls.go` implements the [Bls12381Sign Interface](https://github.com/dusk-network/bls12_381-sign/go/bls.go) within a simple IPC-based gRPC client that interfaces with a running instance of our provided [gRPC server](https://github.com/dusk-network/bls12_381-sign/rust/grpc-server).
+
+## Building
+
+`Makefile` at the repo root takes care of everything, but essentially you'll need the following to build the code:
+ - The compiled protobuf definitions (with the auto-generated client implementation)
+ - The [service](https://github.com/dusk-network/bls12_381-sign/rust/grpc-server) binaries for your platform, so `go:embed` directives can find them.
+
+## Usage
+
+This module exports all required methods to satisfy the [Bls12381Sign Interface](https://github.com/dusk-network/bls12_381-sign/go/bls.go), as well as a `Connect()` and `Disconnect()` method which should be used to encapsulate actual calls to the library. Please check `bls_test.go` for a few examples.

rust/grpc-server/README.md

@@ -0,0 +1,14 @@
+# gRPC Client for BLS12-381 Sign
+
+Implementation of a simple IPC-based server to provide a synchronous gRPC interface to the [BLS12-381 library](https://github.com/bls12_381-sign/rust/bls12_381-sign) to external parties.
+
+## API definition
+We use protobuf to strictly define the API. The schema is available [here](https://github.com/bls12_381-sign/schema/bls12381sig.proto).
+
+## Building
+
+`Makefile` at the repo root takes care of everything. Regardless, a simple `cargo build --release` should do the job if built independently. Built service binaries can be found at `./target/release`
+
+## Usage
+
+We provide a bloat-free [example](https://github.com/dusk-network/bls12_381-sign/go/grpc) of a client written in Go which fully describes all API methods that can be used for reference.