diff --git a/docs/README.md b/docs/README.md index ab78b037067e..e953281097fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,6 +66,7 @@ aside: false - **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK. - **[SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. - **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node. +- **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration. ## Cosmos Hub diff --git a/docs/run-node/rosetta.md b/docs/run-node/rosetta.md index 398d9a9f47e5..2356563e023c 100644 --- a/docs/run-node/rosetta.md +++ b/docs/run-node/rosetta.md @@ -4,16 +4,66 @@ order: 6 # Rosetta -Package rosetta implements the rosetta API for the current cosmos sdk release series. +The `rosetta` package implements Coinbase's [Rosetta API](https://www.rosetta-api.org). This document provides instructions on how to use the Rosetta API integration. For information about the motivation and design choices, refer to [ADR 035](../architecture/adr-035-rosetta-api-support.md). -## Extension +## Add Rosetta Command + +The Rosetta API server is a stand-alone server that connects to a node of a chain developed with Cosmos SDK. + +To enable Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file (e.g. `appd/cmd/root.go`). + +Import the `server` package: + +```go + "github.com/cosmos/cosmos-sdk/server" +``` + +Find the following line: + +```go +initRootCmd(rootCmd, encodingConfig) +``` + +After that line, add the following: + +```go +rootCmd.AddCommand( + server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler) +) +``` + +The `RosettaCommand` function builds the `rosetta` root command and is defined in the `server` package within Cosmos SDK. + +Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application's root command file is all you need to do. + +An implementation example can be found in `simapp` package. + +## Use Rosetta Command + +To run Rosetta in your application CLI, use the following command: + +``` +appd rosetta --help +``` + +To test and run Rosetta API endpoints for applications that are running and exposed, use the following command: + +``` +appd rosetta + --blockchain "your application name (ex: gaia)" + --network "your chain identifier (ex: testnet-1)" + --tendermint "tendermint endpoint (ex: localhost:26657)" + --grpc "gRPC endpoint (ex: localhost:9090)" + --addr "rosetta binding address (ex: :8080)" +``` + +## Extensions There are two ways in which you can customize and extend the implementation with your custom settings. ### Message extension -In order to make an `sdk.Msg` understandable by rosetta the only thing which is required is adding the methods to your message that satisfy the `rosetta.Msg` interface. -Examples on how to do so can be found in the staking types such as `MsgDelegate`, or in bank types such as `MsgSend`. +In order to make an `sdk.Msg` understandable by rosetta the only thing which is required is adding the methods to your messages that satisfy the `rosetta.Msg` interface. Examples on how to do so can be found in the staking types such as `MsgDelegate`, or in bank types such as `MsgSend`. ### Client interface override @@ -43,6 +93,8 @@ func (c *CustomClient) ConstructionPayload(_ context.Context, request *types.Con } ``` +NOTE: when using a customized client, the command cannot be used as the constructors required **may** differ, so it's required to create a new one. We intend to provide a way to init a customized client without writing extra code in the future. + ### Error extension Since rosetta requires to provide 'returned' errors to network options. In order to declare a new rosetta error, we use the `errors` package in cosmos-rosetta-gateway. @@ -58,29 +110,3 @@ var CustomError = crgerrs.RegisterError(100, "custom message", customErrRetriabl ``` Note: errors must be registered before cosmos-rosetta-gateway's `Server`.`Start` method is called. Otherwise the registration will be ignored. Errors with same code will be ignored too. - -## Integration in app.go - -To integrate rosetta as a command in your application, in app.go, in your root command simply use the `server.RosettaCommand` method. - -Example: - -```go -package app -import ( - -"github.com/cosmos/cosmos-sdk/server" -"github.com/spf13/cobra" -) - -func buildAppCommand(rootCmd *cobra.Command) { - // more app.go init stuff - // ... - // add rosetta command - rootCmd.AddCommand(server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler)) -} -``` - -A full implementation example can be found in `simapp` package. - -NOTE: when using a customized client, the command cannot be used as the constructors required **may** differ, so it's required to create a new one. We intend to provide a way to init a customized client without writing extra code in the future.