From 6261bd1ea782b6963496550e58fb07761c0c1a36 Mon Sep 17 00:00:00 2001
From: Igor Artamonov <igor@artamonov.ru>
Date: Tue, 19 Oct 2021 21:59:03 -0400
Subject: [PATCH] solution: docs for NativeSubscribe

---
 docs/07-methods.adoc | 45 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/07-methods.adoc b/docs/07-methods.adoc
index 8ffdae78..7248ff6f 100644
--- a/docs/07-methods.adoc
+++ b/docs/07-methods.adoc
@@ -23,6 +23,7 @@ service Blockchain {
     rpc GetBalance (BalanceRequest) returns (stream AddressBalance) {}
 
     rpc NativeCall (NativeCallRequest) returns (stream NativeCallReplyItem) {}
+    rpc NativeSubscribe (NativeSubscribeRequest) returns (stream NativeSubscribeReplyItem) {}
 
     rpc Describe (DescribeRequest) returns (DescribeResponse) {}
     rpc SubscribeStatus (StatusRequest) returns (stream ChainStatus) {}
@@ -80,6 +81,50 @@ Where:
 NOTE: Reply Items comes right after their execution on an upstream, therefore streaming response.
 It allows to build non-blocking queries
 
+=== Wrapped JSON RPC subscriptions
+
+Most of Ethereum APIs provides _subscription_ to events usually accessed through WebSocket connection.
+Dshackle gives access to same events through gRPC protocol via the `NativeSubscribe` method.
+
+NOTE: Dshackle doesn't actually wrap existing subscription or dispatch request to an upstream.
+It rather generates same events based on the available data, i.e., aggregates it from multiple upstreams.
+
+Supported subscriptions:
+
+- `newHeads`
+- `logs`
+- `syncing`
+
+Method data:
+
+[source,proto]
+----
+message NativeSubscribeRequest {
+    ChainRef chain = 1;
+    string method = 2;
+    bytes payload = 3;
+}
+
+message NativeSubscribeReplyItem {
+    bytes payload = 1;
+}
+----
+
+Where:
+
+- `method` is a subscriptions method (one of `newHeads`, `logs` or `syncing`)
+- `payload` in request is optional subscription params object, which exists only for `logs` methods.
+In that case it may be `address` or `topics`.
+Both address and topics can be a string or array of strings.
+Empty payload for `logs` accepted as subscription to _all_ events.
+- `payload` in reply item is as subscription response encoded as JSON
+
+For example to subscribe to USDC ERC-20 coin Approval events on Ethereum mainnet the request would be:
+
+- `chain=100`
+- `method=logs`
+- `payload={"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "topics": ["0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925"]}`
+
 === SubscribeHead
 
 This methods provides subscription to the new blocks on the specified chain.