Add gRPC protobufs to SDK

zcash-client-sdk-js/package.json

@@ -12,6 +12,9 @@
   "author": "Jack Grigg <jack@z.cash>",
   "license": "MIT",
   "devDependencies": {
+    "google-protobuf": "3.8.0",
+    "grpc": "1.21.1",
+    "grpc-web": "1.0.4",
     "webpack": "4.33.0"
   },
   "dependencies": {

zcash-client-sdk-js/src/compact_formats.proto

@@ -0,0 +1,48 @@
+syntax = "proto3";
+package cash.z.wallet.sdk.rpc;
+option go_package = "walletrpc";
+
+// Remember that proto3 fields are all optional. A field that is not present will be set to its zero value.
+// bytes fields of hashes are in canonical little-endian format.
+
+// CompactBlock is a packaging of ONLY the data from a block that's needed to:
+//   1. Detect a payment to your shielded Sapling address
+//   2. Detect a spend of your shielded Sapling notes
+//   3. Update your witnesses to generate new Sapling spend proofs.
+message CompactBlock {
+    uint32 protoVersion = 1; // the version of this wire format, for storage
+    uint64 height = 2; // the height of this block
+    bytes hash = 3;
+    bytes prevHash = 4;
+    uint32 time = 5;
+    bytes header = 6; // (hash, prevHash, and time) OR (full header)
+    repeated CompactTx vtx = 7; // compact transactions from this block
+}
+
+message CompactTx {
+    // Index and hash will allow the receiver to call out to chain
+    // explorers or other data structures to retrieve more information
+    // about this transaction.
+    uint64 index = 1;
+    bytes hash = 2;
+
+    // The transaction fee: present if server can provide. In the case of a
+    // stateless server and a transaction with transparent inputs, this will be
+    // unset because the calculation requires reference to prior transactions.
+    // in a pure-Sapling context, the fee will be calculable as:
+    //    valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut))
+    uint32 fee = 3;
+
+    repeated CompactSpend spends = 4;
+    repeated CompactOutput outputs = 5;
+}
+
+message CompactSpend {
+    bytes nf = 1;
+}
+
+message CompactOutput {
+    bytes cmu = 1;
+    bytes epk = 2;
+    bytes ciphertext = 3;
+}

zcash-client-sdk-js/src/service.proto

@@ -0,0 +1,49 @@
+syntax = "proto3";
+package cash.z.wallet.sdk.rpc;
+option go_package = "walletrpc";
+
+import "compact_formats.proto";
+
+// A BlockID message contains identifiers to select a block: a height or a
+// hash. If the hash is present it takes precedence.
+message BlockID {
+     uint64 height = 1;
+     bytes hash = 2;
+}
+
+// BlockRange technically allows ranging from hash to hash etc but this is not
+// currently intended for support, though there is no reason you couldn't do
+// it. Further permutations are left as an exercise.
+message BlockRange {
+    BlockID start = 1;
+    BlockID end = 2;
+}
+
+// A TxFilter contains the information needed to identify a particular
+// transaction: either a block and an index, or a direct transaction hash.
+message TxFilter {
+     BlockID block = 1;
+     uint64 index = 2;
+     bytes hash = 3;
+}
+
+// RawTransaction contains the complete transaction data.
+message RawTransaction {
+    bytes data = 1;
+}
+
+message SendResponse {
+    int32 errorCode = 1;
+    string errorMessage = 2;
+}
+
+// Empty placeholder. Someday we may want to specify e.g. a particular chain fork.
+message ChainSpec {}
+
+service CompactTxStreamer {
+    rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
+    rpc GetBlock(BlockID) returns (CompactBlock) {}
+    rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
+    rpc GetTransaction(TxFilter) returns (RawTransaction) {}
+    rpc SendTransaction(RawTransaction) returns (SendResponse) {}
+}

zcash-client-sdk-js/src/service_grpc_web_pb.js

@@ -0,0 +1,366 @@
+/**
+ * @fileoverview gRPC-Web generated client stub for cash.z.wallet.sdk.rpc
+ * @enhanceable
+ * @public
+ */
+
+// GENERATED CODE -- DO NOT EDIT!
+
+
+
+const grpc = {};
+grpc.web = require('grpc-web');
+
+
+var compact_formats_pb = require('./compact_formats_pb.js')
+const proto = {};
+proto.cash = {};
+proto.cash.z = {};
+proto.cash.z.wallet = {};
+proto.cash.z.wallet.sdk = {};
+proto.cash.z.wallet.sdk.rpc = require('./service_pb.js');
+
+/**
+ * @param {string} hostname
+ * @param {?Object} credentials
+ * @param {?Object} options
+ * @constructor
+ * @struct
+ * @final
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient =
+    function(hostname, credentials, options) {
+  if (!options) options = {};
+  options['format'] = 'text';
+
+  /**
+   * @private @const {!grpc.web.GrpcWebClientBase} The client
+   */
+  this.client_ = new grpc.web.GrpcWebClientBase(options);
+
+  /**
+   * @private @const {string} The hostname
+   */
+  this.hostname_ = hostname;
+
+  /**
+   * @private @const {?Object} The credentials to be used to connect
+   *    to the server
+   */
+  this.credentials_ = credentials;
+
+  /**
+   * @private @const {?Object} Options for the client
+   */
+  this.options_ = options;
+};
+
+
+/**
+ * @param {string} hostname
+ * @param {?Object} credentials
+ * @param {?Object} options
+ * @constructor
+ * @struct
+ * @final
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient =
+    function(hostname, credentials, options) {
+  if (!options) options = {};
+  options['format'] = 'text';
+
+  /**
+   * @private @const {!grpc.web.GrpcWebClientBase} The client
+   */
+  this.client_ = new grpc.web.GrpcWebClientBase(options);
+
+  /**
+   * @private @const {string} The hostname
+   */
+  this.hostname_ = hostname;
+
+  /**
+   * @private @const {?Object} The credentials to be used to connect
+   *    to the server
+   */
+  this.credentials_ = credentials;
+
+  /**
+   * @private @const {?Object} Options for the client
+   */
+  this.options_ = options;
+};
+
+
+/**
+ * @const
+ * @type {!grpc.web.AbstractClientBase.MethodInfo<
+ *   !proto.cash.z.wallet.sdk.rpc.ChainSpec,
+ *   !proto.cash.z.wallet.sdk.rpc.BlockID>}
+ */
+const methodInfo_CompactTxStreamer_GetLatestBlock = new grpc.web.AbstractClientBase.MethodInfo(
+  proto.cash.z.wallet.sdk.rpc.BlockID,
+  /** @param {!proto.cash.z.wallet.sdk.rpc.ChainSpec} request */
+  function(request) {
+    return request.serializeBinary();
+  },
+  proto.cash.z.wallet.sdk.rpc.BlockID.deserializeBinary
+);
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.ChainSpec} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @param {function(?grpc.web.Error, ?proto.cash.z.wallet.sdk.rpc.BlockID)}
+ *     callback The callback function(error, response)
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.BlockID>|undefined}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient.prototype.getLatestBlock =
+    function(request, metadata, callback) {
+  return this.client_.rpcCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetLatestBlock',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetLatestBlock,
+      callback);
+};
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.ChainSpec} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!Promise<!proto.cash.z.wallet.sdk.rpc.BlockID>}
+ *     A native promise that resolves to the response
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient.prototype.getLatestBlock =
+    function(request, metadata) {
+  return this.client_.unaryCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetLatestBlock',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetLatestBlock);
+};
+
+
+/**
+ * @const
+ * @type {!grpc.web.AbstractClientBase.MethodInfo<
+ *   !proto.cash.z.wallet.sdk.rpc.BlockID,
+ *   !proto.cash.z.wallet.sdk.rpc.CompactBlock>}
+ */
+const methodInfo_CompactTxStreamer_GetBlock = new grpc.web.AbstractClientBase.MethodInfo(
+  compact_formats_pb.CompactBlock,
+  /** @param {!proto.cash.z.wallet.sdk.rpc.BlockID} request */
+  function(request) {
+    return request.serializeBinary();
+  },
+  compact_formats_pb.CompactBlock.deserializeBinary
+);
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.BlockID} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @param {function(?grpc.web.Error, ?proto.cash.z.wallet.sdk.rpc.CompactBlock)}
+ *     callback The callback function(error, response)
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.CompactBlock>|undefined}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient.prototype.getBlock =
+    function(request, metadata, callback) {
+  return this.client_.rpcCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetBlock',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetBlock,
+      callback);
+};
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.BlockID} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!Promise<!proto.cash.z.wallet.sdk.rpc.CompactBlock>}
+ *     A native promise that resolves to the response
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient.prototype.getBlock =
+    function(request, metadata) {
+  return this.client_.unaryCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetBlock',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetBlock);
+};
+
+
+/**
+ * @const
+ * @type {!grpc.web.AbstractClientBase.MethodInfo<
+ *   !proto.cash.z.wallet.sdk.rpc.BlockRange,
+ *   !proto.cash.z.wallet.sdk.rpc.CompactBlock>}
+ */
+const methodInfo_CompactTxStreamer_GetBlockRange = new grpc.web.AbstractClientBase.MethodInfo(
+  compact_formats_pb.CompactBlock,
+  /** @param {!proto.cash.z.wallet.sdk.rpc.BlockRange} request */
+  function(request) {
+    return request.serializeBinary();
+  },
+  compact_formats_pb.CompactBlock.deserializeBinary
+);
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.BlockRange} request The request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.CompactBlock>}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient.prototype.getBlockRange =
+    function(request, metadata) {
+  return this.client_.serverStreaming(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetBlockRange',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetBlockRange);
+};
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.BlockRange} request The request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.CompactBlock>}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient.prototype.getBlockRange =
+    function(request, metadata) {
+  return this.client_.serverStreaming(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetBlockRange',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetBlockRange);
+};
+
+
+/**
+ * @const
+ * @type {!grpc.web.AbstractClientBase.MethodInfo<
+ *   !proto.cash.z.wallet.sdk.rpc.TxFilter,
+ *   !proto.cash.z.wallet.sdk.rpc.RawTransaction>}
+ */
+const methodInfo_CompactTxStreamer_GetTransaction = new grpc.web.AbstractClientBase.MethodInfo(
+  proto.cash.z.wallet.sdk.rpc.RawTransaction,
+  /** @param {!proto.cash.z.wallet.sdk.rpc.TxFilter} request */
+  function(request) {
+    return request.serializeBinary();
+  },
+  proto.cash.z.wallet.sdk.rpc.RawTransaction.deserializeBinary
+);
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.TxFilter} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @param {function(?grpc.web.Error, ?proto.cash.z.wallet.sdk.rpc.RawTransaction)}
+ *     callback The callback function(error, response)
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.RawTransaction>|undefined}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient.prototype.getTransaction =
+    function(request, metadata, callback) {
+  return this.client_.rpcCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetTransaction',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetTransaction,
+      callback);
+};
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.TxFilter} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!Promise<!proto.cash.z.wallet.sdk.rpc.RawTransaction>}
+ *     A native promise that resolves to the response
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient.prototype.getTransaction =
+    function(request, metadata) {
+  return this.client_.unaryCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/GetTransaction',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_GetTransaction);
+};
+
+
+/**
+ * @const
+ * @type {!grpc.web.AbstractClientBase.MethodInfo<
+ *   !proto.cash.z.wallet.sdk.rpc.RawTransaction,
+ *   !proto.cash.z.wallet.sdk.rpc.SendResponse>}
+ */
+const methodInfo_CompactTxStreamer_SendTransaction = new grpc.web.AbstractClientBase.MethodInfo(
+  proto.cash.z.wallet.sdk.rpc.SendResponse,
+  /** @param {!proto.cash.z.wallet.sdk.rpc.RawTransaction} request */
+  function(request) {
+    return request.serializeBinary();
+  },
+  proto.cash.z.wallet.sdk.rpc.SendResponse.deserializeBinary
+);
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.RawTransaction} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @param {function(?grpc.web.Error, ?proto.cash.z.wallet.sdk.rpc.SendResponse)}
+ *     callback The callback function(error, response)
+ * @return {!grpc.web.ClientReadableStream<!proto.cash.z.wallet.sdk.rpc.SendResponse>|undefined}
+ *     The XHR Node Readable Stream
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerClient.prototype.sendTransaction =
+    function(request, metadata, callback) {
+  return this.client_.rpcCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/SendTransaction',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_SendTransaction,
+      callback);
+};
+
+
+/**
+ * @param {!proto.cash.z.wallet.sdk.rpc.RawTransaction} request The
+ *     request proto
+ * @param {?Object<string, string>} metadata User defined
+ *     call metadata
+ * @return {!Promise<!proto.cash.z.wallet.sdk.rpc.SendResponse>}
+ *     A native promise that resolves to the response
+ */
+proto.cash.z.wallet.sdk.rpc.CompactTxStreamerPromiseClient.prototype.sendTransaction =
+    function(request, metadata) {
+  return this.client_.unaryCall(this.hostname_ +
+      '/cash.z.wallet.sdk.rpc.CompactTxStreamer/SendTransaction',
+      request,
+      metadata || {},
+      methodInfo_CompactTxStreamer_SendTransaction);
+};
+
+
+module.exports = proto.cash.z.wallet.sdk.rpc;
+