From 7dc6404d621ab8f7f52c9cc0e52fb12d5751d657 Mon Sep 17 00:00:00 2001
From: Craig Raw <craigraw@gmail.com>
Date: Wed, 14 Oct 2020 13:37:23 +0200
Subject: [PATCH] add readme

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..779ccc4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# Hummingbird
+
+### Java implementation of Uniform Resources (UR)
+
+Hummingbird is a Java implementation of the [Uniform Resources (UR)](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md) specification.
+It is a direct port of the [URKit](https://github.com/BlockchainCommons/URKit) implementation by Wolf McNally. 
+It contains both the classes to represent a UR, and a UR encoder and decoder to encode and decode to/from the QR representations.
+
+## Configuration
+
+Hummingbird is hosted in Maven Central and can be added as a dependency with the following:
+
+```
+implementation('com.sparrowwallet:hummingbird:1.1')
+```
+
+## Usage
+
+Decoding a UR can be done as follows (here decoding a ``crypto-psbt`` UR type):
+
+```java
+URDecoder decoder = new URDecoder();
+while(decoder.getResult() == null) {
+    //Loop adding QR fragments to the decoder until it has a result
+    String qrText = getFromNextQR();
+    decoder.receivePart(qrText);
+}
+
+URDecoder.Result urResult = decoder.getResult();
+if(urResult.type == ResultType.SUCCESS) {
+    if(urResult.ur.getType().equals(UR.CRYPTO_PSBT_TYPE)) {
+        byte[] psbt = urResult.ur.toBytes();       
+    }
+}
+```
+
+Encoding a UR:
+
+```java
+final int MIN_FRAGMENT_LENGTH = 10;
+final int MAX_FRAGMENT_LENGTH = 100;
+
+UR ur = UR.fromBytes(data);
+UREncoder encoder = new UREncoder(ur, MAX_FRAGMENT_LENGTH, MIN_FRAGMENT_LENGTH, 0);
+while(true) {
+    String fragment = encoder.nextPart();
+    //Show UR fragment as QR code...
+}
+```
+
+## Testing
+
+Hummingbird has a thorough testsuite ported from URKit. The tests can be run with:
+
+```
+./gradlew test
+```
+
+## License
+
+Hummingbird is licensed under the Apache 2 software license.