readme: a bit more flesh

Readme.md

@@ -1,3 +1,30 @@
+<div align="center">
+  <h1 align="center">go-did</h1>
+
+  <p>
+    <a href="https://github.com/INFURA/go-did/tags">
+        <img alt="GitHub Tag" src="https://img.shields.io/github/v/tag/INFURA/go-did">
+    </a>
+    <a href="https://github.com/INFURA/go-did/actions?query=">
+      <img src="https://github.com/INFURA/go-did/actions/workflows/gotest.yml/badge.svg" alt="Build Status">
+    </a>
+    <a href="https://INFURA.github.io/go-did/dev/bench/">
+        <img alt="Go benchmarks" src="https://img.shields.io/badge/Benchmarks-go-blue">
+    </a>
+    <a href="https://github.com/INFURA/go-did/blob/v1/LICENSE.md">
+        <img alt="Apache 2.0 + MIT License" src="https://img.shields.io/badge/License-Apache--2.0+MIT-green">
+    </a>
+    <a href="https://pkg.go.dev/github.com/INFURA/go-did">
+      <img src="https://img.shields.io/badge/Docs-godoc-blue" alt="Docs">
+    </a>
+  </p>
+</div>
+
+This is an implementation of Decentralized Identifiers (DIDs) in go. It differs from the alternatives in the following ways: 
+- **simple**: made of shared reusable components and clear interfaces
+- **fast**: while it supports DID Documents as JSON files, it's not unnecessary in the way (see below) 
+- **support producing and using DIDs**: unlike some others, this all-in-one implementation is meant to create, manipulate and handle DIDs
+- **extensible**: you can easily register your custom DID method
 
 DID spec concepts:
 

verifications/ed25519/VerificationKey2020.go

@@ -100,12 +100,14 @@ func (v VerificationKey2020) Verify(data []byte, sig []byte) bool {
 	return ed25519.Verify(v.pubkey, data, sig)
 }
 
+// encodePubkey encodes the public key in a suitable way for publicKeyMultibase
 func encodePubkey(pubkey ed25519.PublicKey) string {
 	// can only fail with an invalid encoding, but it's hardcoded
 	bytes, _ := mbase.Encode(mbase.Base58BTC, append(varint.ToUvarint(MultibaseCode), pubkey...))
 	return bytes
 }
 
+// decodePubkey decodes the public key from its publicKeyMultibase form
 func decodePubkey(encoded string) (ed25519.PublicKey, error) {
 	baseCodec, bytes, err := mbase.Decode(encoded)
 	if err != nil {