From 340d6365608bb94fe1e40af9e1a6a0afcab5aa6d Mon Sep 17 00:00:00 2001 From: Andrea Giacobino Date: Tue, 13 Jul 2021 14:58:53 +0200 Subject: [PATCH 01/11] docs(rosetta): add Rosetta documentation page related to #9575 --- docs/README.md | 1 + docs/rosetta/README.md | 50 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100755 docs/rosetta/README.md diff --git a/docs/README.md b/docs/README.md index ab78b037067e..f620c4ffea51 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](./rosetta/)**: Rosetta API integration. ## Cosmos Hub diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md new file mode 100755 index 000000000000..90474f5b307f --- /dev/null +++ b/docs/rosetta/README.md @@ -0,0 +1,50 @@ + + +# Rosetta + +This folder contains instructions about how to use the Coinbase Rosetta API integration. + +## Motivations and design + +For the motivation an design choices refer to the [ADR 035](../architecture/adr-035-rosetta-api-support.md) + +## Usage + +The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos-SDK. + +To enable the Rosetta API server support it's required to Add the `RosettaCommand` to your application root command file. +After the + +``` +initRootCmd(rootCmd, encodingConfig) +``` + +line, add the following lines: + +``` +rootCmd.AddCommand( + server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler) +) +``` + + +The application root command file is in the server package in `github.com/cosmos/cosmos-sdk/server`. + +Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application root command file is all you need to do. + +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)" +``` From 5fa8810c5dc3c75da820f1fa2471c662e8a41340 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:18:45 +0200 Subject: [PATCH 02/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index 90474f5b307f..cc05718e4408 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -6,7 +6,7 @@ parent: # Rosetta -This folder contains instructions about how to use the Coinbase Rosetta API integration. +This document provides instructions on how to use the Coinbase Rosetta API integration. ## Motivations and design From 6a8660d19978a5e2b18dac9970c905ba64b374fa Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:18:52 +0200 Subject: [PATCH 03/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index cc05718e4408..bd543148ce5e 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -10,7 +10,7 @@ This document provides instructions on how to use the Coinbase Rosetta API integ ## Motivations and design -For the motivation an design choices refer to the [ADR 035](../architecture/adr-035-rosetta-api-support.md) +For information about the motivation and design choices, refer to [ADR 035](../architecture/adr-035-rosetta-api-support.md). ## Usage From 3467fe38ad2f7798a9808d87d2908b61a586da6b Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:19:00 +0200 Subject: [PATCH 04/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index bd543148ce5e..025167be5e98 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -14,7 +14,7 @@ For information about the motivation and design choices, refer to [ADR 035](../a ## Usage -The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos-SDK. +The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos SDK. To enable the Rosetta API server support it's required to Add the `RosettaCommand` to your application root command file. After the From 33439d92034848389bf313296a0f5dc1038cbe12 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:19:20 +0200 Subject: [PATCH 05/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index 025167be5e98..1654269982f6 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -16,7 +16,7 @@ For information about the motivation and design choices, refer to [ADR 035](../a The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos SDK. -To enable the Rosetta API server support it's required to Add the `RosettaCommand` to your application root command file. +To enable Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file. After the ``` From 84cd92173b938488795abd15e5504267b3bdeea8 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:19:36 +0200 Subject: [PATCH 06/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index 1654269982f6..ec9b58b6600f 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -37,7 +37,11 @@ The application root command file is in the server package in `github.com/cosmos Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application root command file is all you need to do. To run Rosetta in your application CLI, use the following command: -`appd rosetta --help`. + +``` +appd rosetta --help +``` + To test and run Rosetta API endpoints for applications that are running and exposed, use the following command: ``` From 51bff89ef6e36fb8bdc3628d688d193d8b4ef726 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:19:50 +0200 Subject: [PATCH 07/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index ec9b58b6600f..4d4ebfcc0c2e 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -8,7 +8,7 @@ parent: This document provides instructions on how to use the Coinbase Rosetta API integration. -## Motivations and design +## Motivation and Design For information about the motivation and design choices, refer to [ADR 035](../architecture/adr-035-rosetta-api-support.md). From 80f8684156324c34564df12cd3f15fb55568f294 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:20:04 +0200 Subject: [PATCH 08/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index 4d4ebfcc0c2e..c988c1983fee 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -17,13 +17,13 @@ For information about the motivation and design choices, refer to [ADR 035](../a The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos SDK. To enable Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file. -After the +Find the following line within the root command file: ``` initRootCmd(rootCmd, encodingConfig) ``` -line, add the following lines: +After that line, add the following: ``` rootCmd.AddCommand( From 63a41ac747f6b8e73e35db90b9afe074d5c5f698 Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:20:26 +0200 Subject: [PATCH 09/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index c988c1983fee..c9f51a6e1262 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -32,7 +32,7 @@ rootCmd.AddCommand( ``` -The application root command file is in the server package in `github.com/cosmos/cosmos-sdk/server`. +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 root command file is all you need to do. From 9a903d295cb0dbf37845fe58f67a7f93000b0bbb Mon Sep 17 00:00:00 2001 From: Jonathan Gimeno Date: Wed, 21 Jul 2021 09:20:32 +0200 Subject: [PATCH 10/11] Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> --- docs/rosetta/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md index c9f51a6e1262..9fb07304aa0f 100755 --- a/docs/rosetta/README.md +++ b/docs/rosetta/README.md @@ -34,7 +34,7 @@ rootCmd.AddCommand( 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 root command file is all you need to do. +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. To run Rosetta in your application CLI, use the following command: From 3d69152ed640ca3ca50ba60f6c7e0bab25a725d9 Mon Sep 17 00:00:00 2001 From: ryanchrypto <12519942+ryanchrypto@users.noreply.github.com> Date: Wed, 28 Jul 2021 18:06:02 -0700 Subject: [PATCH 11/11] combine with existing doc --- docs/README.md | 2 +- docs/rosetta/README.md | 54 ------------------------- docs/run-node/rosetta.md | 86 ++++++++++++++++++++++++++-------------- 3 files changed, 57 insertions(+), 85 deletions(-) delete mode 100755 docs/rosetta/README.md diff --git a/docs/README.md b/docs/README.md index f620c4ffea51..e953281097fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,7 +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](./rosetta/)**: Rosetta API integration. +- **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration. ## Cosmos Hub diff --git a/docs/rosetta/README.md b/docs/rosetta/README.md deleted file mode 100755 index 9fb07304aa0f..000000000000 --- a/docs/rosetta/README.md +++ /dev/null @@ -1,54 +0,0 @@ - - -# Rosetta - -This document provides instructions on how to use the Coinbase Rosetta API integration. - -## Motivation and Design - -For information about the motivation and design choices, refer to [ADR 035](../architecture/adr-035-rosetta-api-support.md). - -## Usage - -The Rosetta API server is a stand-alone server that connects to a node of a chain developed with the Cosmos SDK. - -To enable Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file. -Find the following line within the root command file: - -``` -initRootCmd(rootCmd, encodingConfig) -``` - -After that line, add the following: - -``` -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. - -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)" -``` 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.