ADR 35: Rosetta API Support

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

@@ -0,0 +1,225 @@
+# ADR 033: Rosetta API support
+
+## Context
+
+Rosetta API, an open-source specification and set of tools developed by Coinbase, makes integration with blockchains simpler, faster, and more reliable by establishing a standard API for integrating blockchain applications.
+
+By using a common interface that standardizes the process of how a user interacts with a blockchain, both the work of exchanges to integrate with new blockchains and also of the developers to build cross-blockchain applications such as block explorers, wallets and dApps is considerably reduced.
+
+We think that providing Rosetta support to the Cosmos SDK will add value to all the developers and Cosmos SDK based chains in the ecosystem.
+
+## Decision
+
+
+The service is structured in a way that:
+
+1. It becomes easy to inject different implementations for different types of SDK. For this abstraction we have used the term Adapter.
+2. Due to the nature of versioning that has been done with Cosmos SDK so far it becomes very difficult to have different SDK versions included in the same repo, for that we created a generic shared code that includes the Service and the Adapter interface.
+3. It is easy to inject and instantiate wherever is needed in the different applications.
+
+
+## Architecture
+
+
+### Service
+
+The Service is just an struct that is started and listens to the port specified in the options. This is commonly used for all the SDK versions supported.
+
+To construct one we can call the constructor:
+
+`func New(options Options, network Network) (*Service, error)`
+
+It accepts an options struct that only holds the port to listen to:
+
+```
+type Options struct {
+	Port uint32
+}
+```
+
+And a Network struct. This struct is the one that is specific to every SDK version, or even a network specific that the generic SDK does not cover all their needs.
+
+```
+type Network struct {
+	Properties rosetta.NetworkProperties
+	Adapter    rosetta.Adapter
+}
+````
+
+The properties struct is needed in order to run the Service, these are options that are mandatory and are related to Rosetta specific properties.
+
+```
+type NetworkProperties struct {
+	// Mandatory properties
+	Blockchain          string
+	Network             string
+	AddrPrefix          string
+	SupportedOperations []string
+}
+```
+
+The `Blockchain` and `Network` are the ones that Rosetta uses to label the networks that the API supports, for example, if we were implementing a Bitcoin API Rosetta blockchain would be "Bitcoin" and network could be "mainnet", etc.
+
+The `AddrPrefix` is specific to the nature of cosmos type addresses. Because a network can have a different type of address we need to provide it, for example for IOV it would be "star" and for cosmos hub would be "cosmos".
+
+And the `SupportedOperations` is related to Rosetta, these are the operations the API supports. An operation can be a `Transfer`, `Delegation`, etc. For now we only support one type of operation, `Transfer`.
+
+The other important thing that the Network holds is the Adapter interface. This interface is the specific implementation for every cosmos version.
+
+And adapter must satisfy the interface:
+
+```
+type Adapter interface {
+	DataAPI
+	ConstructionAPI
+}
+
+type DataAPI interface {
+	server.NetworkAPIServicer
+	server.AccountAPIServicer
+	server.MempoolAPIServicer
+	server.BlockAPIServicer
+	server.ConstructionAPIServicer
+}
+
+type ConstructionAPI interface {
+	server.ConstructionAPIServicer
+}
+
+````
+
+### How to use it in the Cosmos SDK.
+
+The best way to do it would be that every Cosmos SDK version holds the implementation of the Network struct, this can be an example located in the Cosmos SDK Launchpad version.
+
+```
+// NewLaunchpadNetwork returns a configured network to work in a Launchpad version.
+func NewLaunchpadNetwork(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,
+				AddrPrefix:  options.AddrPrefix,
+				OfflineMode: options.OfflineMode,
+			},
+		),
+	}
+}
+```
+
+As we see we hold not only the instantiation of a Launchpad specific network but the adapter implementation too. As the way to talk to different rpc endpoint change between different versions (Launchpad, Stargate, etc), makes sense to keep it in their respective branches.
+
+In this way we could have two options (yet to decide) that we can expose rosetta in the cosmos SDK.
+
+#### Embedding it in the Start command.
+
+This will look more like the approach the API in cosmos works: [link](https://github.com/cosmos/cosmos-sdk/blob/ca7b31dd5d23b10a919de1a60bbac90e89c5bf78/server/start.go#L248).
+
+So we can add something like:
+
+```
+	if config.Rosetta.Enable {
+     ....
+            get contecxt, flags, etc
+        	...
+
+            h, err := service.New(
+                service.Options{Port: uint32(*flagPort)},
+                launchpad.NewLaunchpadNetwork(launchpad.Options{
+                    CosmosEndpoint:     *flagAppRPC,
+                    TendermintEndpoint: *flagTendermintRPC,
+                    Blockchain:         *flagBlockchain,
+                    Network:            *flagNetworkID,
+                    AddrPrefix:         *flagAddrPrefix,
+                    OfflineMode:        *flagOfflineMode,
+                }),
+            )
+            if err != nil {
+            }
+
+            ...
+
+            go func() {
+			if err := h.Start(config); err != nil {
+				errCh <- err
+			}
+		    }()
+    }
+
+```
+
+#### The cobra command approach
+
+This means providing a new command in order to run the service, an example can look something like:
+
+```
+func NewRosettaServiceCmd() *cobra.Command {
+
+    ...
+    cmd := &cobra.Command{
+    	Use:   "vote [proposal-id] [option]",
+        ....
+
+		RunE: func(cmd *cobra.Command, args []string) error {
+            ....
+            get contecxt, flags, etc
+        	...
+
+            h, err := service.New(
+                service.Options{Port: uint32(*flagPort)},
+                launchpad.NewLaunchpadNetwork(launchpad.Options{
+                    CosmosEndpoint:     *flagAppRPC,
+                    TendermintEndpoint: *flagTendermintRPC,
+                    Blockchain:         *flagBlockchain,
+                    Network:            *flagNetworkID,
+                    AddrPrefix:         *flagAddrPrefix,
+                    OfflineMode:        *flagOfflineMode,
+                }),
+            )
+            if err != nil {
+            }
+
+            ...
+
+            h.Start()
+        }
+    }
+    ...
+
+}
+```
+
+This is closer to the Standalone approach. Right now in the current implementation we have a main.go that can be run as a Standalone, this probably will be removed once we migrate the code from Tendermint repo an embed it in Cosmos SDK.
+
+
+### The external Library
+
+Because apart from the Network struct and Adapter implemention there is a lot of code that would be shared across versions, we can provide a repo for the Rosetta Service that will hold only the Service, the Interfaces and the types. This includes all that is not specific to a single version. (Still to decide if we keep an external shared dependency or not.)
+
+
+## Status
+
+Accepted
+
+## Consequences
+
+### Positive
+
+- Provide out-of-the-box Rosetta interface just by using the Cosmos SDK.
+- Contribute to the standarization of blockchain interfaces.
+
+## References
+
+- https://www.rosetta-api.org/
+- https://github.com/tendermint/cosmos-rosetta-gateway