From be12bb5bb7a82f5e0cb7cf885f6bb6385fb5504f Mon Sep 17 00:00:00 2001
From: Marko <marbar3778@yahoo.com>
Date: Mon, 6 Jul 2020 13:27:17 +0200
Subject: [PATCH] ADR-057: RPC (#4857)

## Description

This adr is meant to weight the pros and cons of gRPC and JSON-RPC. It is fairly incomplete on the JSON-RPC side.

EDIT: Thank you to erik on filling out the pros and cons!!

Work Towards: #3367
---
 docs/architecture/README.md      |  2 +
 docs/architecture/adr-057-RPC.md | 90 ++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 docs/architecture/adr-057-RPC.md

diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 7519951d9..6557bd23d 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -73,3 +73,5 @@ Note the context/background should be written in the present tense.
 - [ADR-053-State-Sync-Prototype](./adr-053-state-sync-prototype.md)
 - [ADR-054-crypto-encoding-2](./adr-054-crypto-encoding-2.md)
 - [ADR-055-protobuf-design](./adr-055-protobuf-design.md)
+- [ADR-056-proving-amnesia-attacks](./adr-056-proving-amnesia-attacks.md)
+- [ADR-057-RPC](./adr-057-RPC.md)
diff --git a/docs/architecture/adr-057-RPC.md b/docs/architecture/adr-057-RPC.md
new file mode 100644
index 000000000..5e7c9f1dc
--- /dev/null
+++ b/docs/architecture/adr-057-RPC.md
@@ -0,0 +1,90 @@
+# ADR 057: RPC
+
+## Changelog
+
+- 19-05-2020: created
+
+## Context
+
+Currently the RPC layer of Tendermint is using a variant of the JSON-RPC protocol. This ADR is meant to serve as a pro/con list for possible alternatives and JSON-RPC.
+
+There are currently two options being discussed: gRPC & JSON-RPC.
+
+### JSON-RPC
+
+JSON-RPC is a JSON-based RPC protocol. Tendermint has implemented its own variant of JSON-RPC which is not compatible with the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification).
+
+**Pros:**
+
+- Easy to use & implement (by default)
+- Well-known and well-understood by users and integrators
+- Integrates reasonably well with web infrastructure (proxies, API gateways, service meshes, caches, etc)
+- human readable encoding (by default)
+
+**Cons:**
+
+- No schema support
+- RPC clients must be hand-written
+- Streaming not built into protocol
+- Underspecified types (e.g. numbers and timestamps)
+- Tendermint has its own implementation (not standards compliant, maintenance overhead)
+  - High maintenance cost associated to this
+- Stdlib `jsonrpc` package only supports JSON-RPC 1.0, no dominant package for JSON-RPC 2.0
+- Tooling around documentation/specification (e.g. Swagger) could be better
+- JSON data is larger (offset by HTTP compression)
+- Serializing is slow ([~100% marshal, ~400% unmarshal](https://github.com/alecthomas/go_serialization_benchmarks)); insignificant in absolute terms
+- Specification was last updated in 2013 and is way behind Swagger/OpenAPI
+
+### gRPC + gRPC-gateway (REST + Swagger)
+
+gRPC is a high performant RPC framework. It has been battle tested by a large number of users and is heavily relied on and maintained by countless large corporations.
+
+**Pros:**
+
+- Efficient data retrieval for users, lite clients and other protocols
+- Easily implemented in supported languages (Go, Dart, JS, TS, rust, Elixir, Haskell, ...)
+- Defined schema with richer type system (Protocol Buffers)
+- Can use common schemas and types across all protocols and data stores (RPC, ABCI, blocks, etc)
+- Established conventions for forwards- and backwards-compatibility
+- Bi-directional streaming
+- Servers and clients are be autogenerated in many languages (e.g. Tendermint-rs)
+- Auto-generated swagger documentation for REST API
+- Backwards and forwards compatibility guarantees enforced at the protocol level.
+- Can be used with different codecs (JSON, CBOR, ...)
+
+**Cons:**
+
+- Complex system involving cross-language schemas, code generation, and custom protocols
+- Type system does not always map cleanly to native language type system; integration woes
+- Many common types require Protobuf plugins (e.g. timestamps and duration)
+- Generated code may be non-idiomatic and hard to use
+- Migration will be disruptive and laborious
+
+## Decision
+
+> This section explains all of the details of the proposed solution, including implementation details.
+> It should also describe affects / corollary items that may need to be changed as a part of this.
+> If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
+> (e.g. the optimal split of things to do between separate PR's)
+
+## Status
+
+> A decision may be "proposed" if it hasn't been agreed upon yet, or "accepted" once it is agreed upon. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.
+
+{Deprecated|Proposed|Accepted}
+
+## Consequences
+
+> This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones.
+
+### Positive
+
+### Negative
+
+### Neutral
+
+## References
+
+> Are there any relevant PR comments, issues that led up to this, or articles referenced for why we made the given design choice? If so link them here!
+
+- {reference link}