ADR 35: Rosetta API Support

docs/architecture/adr-035-rosetta-api-support.md

@@ -0,0 +1,238 @@
+# ADR 035: Rosetta API Support
+
+## Context
+
+[Rosetta API](https://www.rosetta-api.org/) is an open-source specification and set of tools developed by Coinbase to 
+standardise blockchain interactions.
+
+Through the use of a standard API for integrating blockchain applications it will
+
+* Be easier for a user to interact with a given blockchain
+* Allow exchanges to integrate new blockchains quickly and easily
+* Enable application developers to build cross-blockchain applications such as block explorers, wallets and dApps at 
+  considerably lower cost and effort.
+
+## Decision
+
+It is clear that adding Rosetta API support to the Cosmos SDK will bring value to all the developers and 
+Cosmos SDK based chains in the ecosystem. How it is implemented is key.
+
+The driving principles of the proposed design are:
+
+1. **Extensibility:** it must be as riskless and painless as possible for application developers to set-up network 
+   configurations to expose Rosetta API-compliant services.
+2. **Long term support:** This proposal aims to provide support for all the supported Cosmos SDK release series.
+3. **Cost-efficiency:** Backporting changes to Rosetta API specifications from `master` to the various stable 
+   branches of Cosmos SDK is a cost that needs to be reduced.
+
+We will achieve these delivering on these principles by the following:
+
+1. There will be an external repo called [cosmos-rosetta-gateway](https://github.com/tendermint/cosmos-rosetta-gateway) 
+   for the implementation of the core Rosetta API features, particularly:
+   a. The types and interfaces. This separates design from implementation detail.
+   b. Some core implementations: specifically, the `Service` functionality as this is independent of the Cosmos SDK version.
+2. Due to differences between the Cosmos release series, each series will have its own specific API implementations of `Network` struct and `Adapter` interface.
+3. There will be two options for starting an API service in applications:
+   a. API shares the application process
+   b. API-specific process.
+
+
+## Architecture
+
+### The External Repo
+
+As section will describe the proposed external library, including the service implementation, plus the defined types and interfaces.
+
+#### Service
+
+`Service` is a simple `struct` that is started and listens to the port specified in the options. This is meant to be used across all the Cosmos SDK versions that are actively supported.
+
+The constructor follows:
+
+`func New(options Options, network Network) (*Service, error)`
+
+#### Types
+
+`Service` accepts an `Options` `struct` that holds service configuration values, such as the port the service would be listening to:
+
+```golang
+type Options struct {
+    ListenAddress string
+}
+```
+
+The `Network` type holds network-specific properties (i.e. configuration values) and adapters. Pre-configured concrete types will be available for each Cosmos SDK release. Applications can also create their own custom types.
+
+```golang
+type Network struct {
+	Properties rosetta.NetworkProperties
+	Adapter    rosetta.Adapter
+}
+```
+
+A `NetworkProperties` `struct` comprises basic values that are required by a Rosetta API `Service`:
+
+```golang
+type NetworkProperties struct {
+	// Mandatory properties
+	Blockchain          string
+	Network             string
+	SupportedOperations []string
+}
+```
+
+Rosetta API services use `Blockchain` and `Network` as identifiers, e.g. the developers of _gaia_, the application that powers the Cosmos Hub, may want to set those to `Cosmos Hub` and `cosmos-hub-3` respectively.
+
+`SupportedOperations` contains the transaction types that are supported by the library. At the present time, 
+only `cosmos-sdk/MsgSend` is supported in Launchpad. Additional operations will be added in due time.
+
+For Launchpad we will map the amino type name to the operation supported, in Stargate we will use the protoc one.
+
+#### Interfaces
+
+Every SDK version uses a different format to connect (rpc, gRpc, etc), we have abstracted this in what is called the 
+Adapter. This is an interface that defines the methods an adapter implementation must provide in order to be used 
+in the `Network` interface.
+
+Each Cosmos SDK release series will have their own Adapter implementations.
+Developers can implement their own custom adapters as required.
+
+```golang
+type Adapter interface {
+	DataAPI
+	ConstructionAPI
+}
+
+type DataAPI interface {
+	server.NetworkAPIServicer
+	server.AccountAPIServicer
+	server.MempoolAPIServicer
+	server.BlockAPIServicer
+	server.ConstructionAPIServicer
+}
+
+type ConstructionAPI interface {
+	server.ConstructionAPIServicer
+}
+```
+
+### 2. Cosmos SDK Implementation
+
+As described, each Cosmos SDK release series will have version specific implementations of `Network` and `Adapter`, as 
+well as a `NewNetwork` constructor.
+
+Due to separation of interface and implementation, application developers have the option to override as needed, 
+using this code as reference.
+
+```golang
+// NewNetwork returns the default application configuration.
+
+func NewNetwork(options Options) service.Network {
+	cosmosClient := cosmos.NewClient(fmt.Sprintf("http://%s", options.CosmosEndpoint))
+	tendermintClient := tendermint.NewClient(fmt.Sprintf("http://%s", options.TendermintEndpoint))
+
+	return service.Network{
+		Properties: rosetta.NetworkProperties{
+			Blockchain:          options.Blockchain,
+			Network:             options.Network,
+			SupportedOperations: []string{OperationTransfer},
+		},
+		Adapter: newAdapter(
+			cosmosClient,
+			tendermintClient,
+			properties{
+				Blockchain:   options.Blockchain,
+				Network:      options.Network,
+				OfflineMode:  options.OfflineMode,
+			},
+		),
+	}
+}
+```
+
+### 3. API service invocation
+
+As stated at the start, application developers will have two methods for invocation of the Rosetta API service:
+
+1. Shared process for both application and API
+2. Standalone API service
+
+#### Shared Process (Only Stargate)
+
+Rosetta API service could run within the same execution process as the application. New configuration option and 
+command line flags would be provided to support this:
+
+```golang
+	if config.Rosetta.Enable {
+     ....
+            get contecxt, flags, etc
+        	...
+
+            h, err := service.New(
+                service.Options{ListenAddress: config.Rosetta.ListenAddress},
+                rosetta.NewNetwork(cdc, options),
+            )
+            if err != nil {
+            }
+
+            ...
+
+            go func() {
+			if err := h.Start(config); err != nil {
+				errCh <- err
+			}
+		    }()
+    }
+
+```
+
+#### Separate API service
+
+Client application developers can write a new command to launch a Rosetta API server as a separate process too:
+
+```golang
+func RosettaCommand(cdc *codec.Codec) *cobra.Command {
+
+    ...
+    cmd := &cobra.Command{
+    	Use:   "rosetta",
+        ....
+
+		RunE: func(cmd *cobra.Command, args []string) error {
+            ....
+            get contecxt, flags, etc
+        	...
+
+            h, err := service.New(
+                  service.Options{Endpoint: endpoint},
+                  rosetta.NewNetwork(cdc, options),
+            )
+            if err != nil {
+            	return err
+            }
+
+            ...
+
+            h.Start()
+        }
+    }
+    ...
+
+}
+```
+
+## Status
+
+Proposed
+
+## Consequences
+
+### Positive
+
+- Out-of-the-box Rosetta API support within Cosmos SDK.
+- Blockchain interface standardisation
+
+## References
+
+- https://www.rosetta-api.org/
+- https://github.com/tendermint/cosmos-rosetta-gateway