Add tendermint-light-client-js crate (#812)

* Add first working iteration of tendermint-light-client-js crate

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Serialize/deserialize verification verdicts

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Ignore NodeJS bloat

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Fix incorrect comment changes

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Update README with screenshots

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Fix contributors for verifier-web example

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Update example package details

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Update README with example usage

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Add PartialEq trait to light client Verdict to allow for comparison

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Add tests for JavaScript verify interface

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Add CHANGELOG entry

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Add CI job for headless browser testing

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Specify path to light-client-js crate for wasm-pack test

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Turn off clippy warning for panic hook

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Implement Eq trait for verification verdict and related types

Signed-off-by: Thane Thomson <connect@thanethomson.com>

.github/workflows/build.yml

@@ -29,7 +29,7 @@ jobs:
         with:
           command: build-all
 
-  light-client-wasm:
+  build-light-client-wasm:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2

.github/workflows/test.yml

@@ -69,6 +69,15 @@ jobs:
         with:
           command: test-all-features
           args: -p tendermint-light-client
+  # From https://rustwasm.github.io/docs/wasm-bindgen/wasm-bindgen-test/continuous-integration.html#github-actions
+  tendermint-light-client-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install wasm-pack
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+      - run: wasm-pack test --headless --chrome ./light-client-js/
+      - run: wasm-pack test --headless --firefox ./light-client-js/
   tendermint-light-node:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -17,3 +17,9 @@ Cargo.lock
 
 # Proptest regressions dumps
 **/*.proptest-regressions
+
+# Light Client WASM
+light-client-js/pkg/
+light-client-js/examples/verifier-web/node_modules/
+light-client-js/examples/verifier-web/dist/
+light-client-js/examples/verifier-web/package-lock.json

CHANGELOG.md

@@ -1,11 +1,18 @@
-##  Unreleased
+## Unreleased
 
 ### FEATURES
 
 * `[tendermint-abci]` Release minimal framework for building ABCI applications
   in Rust ([#794])
+* `[tendermint-light-client-js]` First release of the
+  `tendermint-light-client-js` crate to provide access to Tendermint Light
+  Client functionality from WASM. This only provides access to the `verify`
+  method at present, exclusively provides access to block verification. This
+  does not include network access or the Light Client's bisection algorithm
+  ([#812])
 
 [#794]: https://github.com/informalsystems/tendermint-rs/pull/794
+[#812]: https://github.com/informalsystems/tendermint-rs/pull/812
 
 ## v0.18.1
 

Cargo.toml

@@ -3,6 +3,7 @@
 members = [
     "abci",
     "light-client",
+    "light-client-js",
     "light-node",
     "p2p",
     "proto",

light-client-js/Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "tendermint-light-client-js"
+version = "0.18.1"
+authors = [
+    "Romain Ruetschi <romain@informal.systems>",
+    "Thane Thomson <thane@informal.systems>"
+]
+edition = "2018"
+license = "Apache-2.0"
+description = """
+    tendermint-light-client-js provides a lightweight, WASM-based interface to
+    the Tendermint Light Client's verification functionality.
+    """
+repository = "https://github.com/informalsystems/tendermint-rs"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = ["console_error_panic_hook"]
+
+[dependencies]
+serde = { version = "1.0", features = [ "derive" ] }
+serde_json = "1.0"
+tendermint = { version = "0.18.1", path = "../tendermint" }
+tendermint-light-client = { version = "0.18.1", path = "../light-client", default-features = false }
+wasm-bindgen = { version = "0.2.63", features = [ "serde-serialize" ] }
+
+# The `console_error_panic_hook` crate provides better debugging of panics by
+# logging them with `console.error`. This is great for development, but requires
+# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
+# code size when deploying.
+console_error_panic_hook = { version = "0.1.6", optional = true }
+
+# `wee_alloc` is a tiny allocator for wasm that is only ~1K in code size
+# compared to the default allocator's ~10K. It is slower than the default
+# allocator, however.
+#
+# Unfortunately, `wee_alloc` requires nightly Rust when targeting wasm for now.
+wee_alloc = { version = "0.4.5", optional = true }
+
+[dev-dependencies]
+wasm-bindgen-test = "0.3.13"
+
+[profile.release]
+# Tell `rustc` to optimize for small code size.
+opt-level = "s"

light-client-js/README.md

@@ -0,0 +1,17 @@
+# Light-Client API for JavaScript
+
+At present this just exposes the [Tendermint Light Client]'s verification logic
+via WASM. This allows simple access to verification from JavaScript:
+
+```javascript
+import * as LightClient from 'tendermint-light-client-js';
+
+// Verify an untrusted block against a trusted one, given the specified options
+// and current date/time.
+let verdict = LightClient.verify(untrusted, trusted, options, now);
+```
+
+For an example of how to use this, please see the [verifier-web example].
+
+[Tendermint Light Client]: ../light-client/
+[verifier-web example]: ./examples/verifier-web/

light-client-js/examples/verifier-web/README.md

@@ -0,0 +1,69 @@
+# Web-Based Light Client Verification
+
+This folder contains a simple *example* web application demonstrating
+Tendermint Light Client verification.
+
+## Requirements
+
+* Rust stable latest
+* NodeJS (tested with v14.15.5)
+* [wasm-pack]
+
+## Try it out
+
+You first need to build a few things before you can try this example out
+locally.
+
+### Step 1: Building the WASM binary
+
+From the [`light-client-js` folder](../../):
+
+```bash
+wasm-pack build
+```
+
+This will build our WASM binary and JavaScript/TypeScript wrappers and place
+them into a `pkg` directory.
+
+### Step 2: Build/run the example
+
+From this directory (`light-client-js/examples/verifier-web`):
+
+```bash
+# Install all dependencies
+npm install
+
+# Build/start the example app
+npm run start
+```
+
+This should build the example and start a server at http://localhost:8080
+
+### Step 3: Input your data
+
+When you open up at http://localhost:8080, you should see something like the
+following:
+
+![screenshot1](screenshot1.png)
+
+Copy/paste the JSON representation of a trusted block alongside that of the
+untrusted block you wish to verify into the supplied editors. Configure your
+desired Light Client parameters, as well as the timestamp at which you want to
+check whether the untrusted block is trustworthy, and click the **Verify**
+button.
+
+This will show you the raw JSON object received back from the verifier.
+
+![screenshot2](screenshot2.png)
+
+## Limitations
+
+1. This example only demonstrates *verification*, and is pretty manual right
+   now (you must manually copy/paste the JSON representations of untrusted and
+   trusted blocks, and supply options/timestamps manually). No network I/O
+   happens here, so bring your own I/O to fetch light blocks.
+2. The WASM binary built in step 1 only works for bundled web applications
+   (e.g. using [webpack]). 
+
+[wasm-pack]: https://rustwasm.github.io/docs/wasm-pack/introduction.html
+[webpack]: https://webpack.js.org/

light-client-js/examples/verifier-web/bootstrap.js

@@ -0,0 +1,5 @@
+// A dependency graph that contains any wasm must all be imported
+// asynchronously. This `bootstrap.js` file does the single async import, so
+// that no one else needs to worry about it again.
+import("./index.js")
+  .catch(e => console.error("Error importing `index.js`:", e));

light-client-js/examples/verifier-web/index.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Tendermint Light Client WASM Example</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.1/css/bulma.min.css">
+  <style type="text/css">
+    .json-editor {
+      height: 300px;
+    }
+    #verdict-section {
+      visibility: hidden;
+    }
+  </style>
+</head>
+<body>
+<section class="section">
+  <div class="container">
+    <h1 class="title is-2">Tendermint Light Client WASM Example</h1>
+    <p>
+      This example demonstrates how to make use of the
+      <a href="https://github.com/informalsystems/tendermint-rs/tree/master/light-client">Tendermint Light Client</a>
+      WASM build in a simple web application.
+    </p>
+  </div>
+</section>
+
+<section class="section">
+  <div class="container">
+    <div class="columns">
+      <div class="column">
+        <h4 class="title is-4">Untrusted Block</h4>
+        <div class="json-editor" id="untrusted-block-editor"></div>
+      </div>
+
+      <div class="column">
+        <h4 class="title is-4">Trusted Block</h4>
+        <div class="json-editor" id="trusted-block-editor"></div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="section">
+  <div class="container">
+    <h4 class="title is-4">Options</h4>
+    <div class="columns">
+      <div class="column">
+        <div class="field">
+          <label class="label">Trust threshold:</label>
+          <div class="control">
+            <input class="input" type="text" value="1/3" id="trust-threshold-input">
+          </div>
+          <p class="help">Must be in the format: <b>numerator/denominator</b></p>
+        </div>
+      </div>
+
+      <div class="column">
+        <div class="field">
+          <label class="label">Trusting period:</label>
+            <div class="control">
+              <input class="input" type="text" value="1209600" id="trusting-period-input">
+            </div>
+            <p class="help">A.k.a. "unbonding period", in seconds</p>
+        </div>
+      </div>
+
+      <div class="column">
+        <div class="field">
+          <label class="label">Clock drift:</label>
+          <div class="control">
+            <input class="input" type="text" value="5" id="clock-drift-input">
+          </div>
+          <p class="help">In seconds</p>
+        </div>
+      </div>
+
+      <div class="column">
+        <div class="field">
+          <label class="label">Now:</label>
+          <div class="control">
+            <input class="input" type="text" value="2020-10-21T12:40:04.160328400Z" id="now-input">
+          </div>
+          <p class="help">Timestamp in RFC3339 format for which you want to verify the block</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section class="section">
+  <div class="container">
+    <button class="button is-large is-primary" id="verify-btn">Verify</button>
+  </div>
+</section>
+
+<section class="section" id="verdict-section">
+  <div class="container">
+    <h4 class="title is-4">Verdict</h4>
+    <pre id="verdict"></pre>
+  </div>
+</section>
+<script src="./bootstrap.js"></script>
+</body>
+</html>