BCHD gRPC client for browsers
npm install grpc-bchrpc-browserA bchd rpc client for browsers using grpc/grpc-web
This package provides a simple gRPC client for connecting web applications to
a bchd full node.
A mobile friendly version of this project is formatted from markdown by github pages.
For a quick example usage subscribing transactions see the console here, or an experimental example using this module in a web worker.
Detailed RPC Documentation for the rpc protocol is a work in progress.
Client Documentation detailing methods and utility functions.
Mocha browser tests should provide some working examples.
This is slightly more than a stock client generated from protocol buffers. The following utilities have been added:
- Simple utilities to transform hex/base64/Uint8Arrays without nodejs Buffer
- A function to transform a number to a little-endian array
- Functions to validate a merkle proof from bchd
- A class to read and match compact filters for outpoints and public keys
For Bitcoin Cash and bchd specifically, functions are currently here to validate a transaction and block, as well as other utilities to handle different data types used or sent by bchd.
This project uses Google's grpc/grpc-web library
to generate a client, rather than the older and
more widely used @improbable-eng/grpc-web.
The client is built from the pb files in advance rather
than on-the-fly, a functionality which may be employed with the @improbable library.
The motivation is toward lower maintenance, long-term stability and support by using
the google library, not that this thinking played out well with the framework formerly known as angular.
One notable limitation of the official grpc/grpc-web library is a lack of FETCH support.
- The official documentation for bchrpc.
- The reference implementation from the bchd team.
- Notes on the limitations of multiplexing from a browser
Alternative implementations of this project are built using the improbable-eng library here:
- For the web: grpc-bchrpc-web
- Using a local bchd node from nodejs: grpc-bchrpc-node
Note: this project was created in node v12.2.0 (LTS) and used protoc version 3.11.4; and is open to using features from es2017 although initially targeted at es6.
To build:
npm run build # transpile typescript, browserify and minify use
npm run build:docs # build documentation for the client class
Tests can be run either from console or in a browser. The typescript is loaded via ts-node, in that context.
npm run test # run tests in node
npm run test:browser # run tests in a browser
If for some reason you need to update the gcash proto files yourself to add some future functionality use:
npm run pb-clean # remove old definitions
npm run pb-update # download bchrpc.proto from gcash/bchd/master
npm run pb-build # create client library
npm run pb-doc # generate documentation
Important: an installed version of protoc
is required to run pb-build.
IN ADDITION you must have protoc-gen-grpc-web, see grpc-web
To facilitate debugging and development of the client, it may be useful make calls using a webui. The following npm scripts are
provided, assuming you have golang installed.
npm run pb-grpcui-install # install grpcui
npm run pb-grpcui # run a local webui against a bchd node
Mainnet:
* https://bchd.greyh.at:8335
* https://bchd.imaginary.cash:8335
* https://bchd.fountainhead.cash:443
* https://bchd.sploit.cash:443
Testnet:
* https://bchd.greyh.at:18335
* https://bchd-testnet.greyh.at:18335