docs(rosetta): add Rosetta documentation page (#9688)
* docs(rosetta): add Rosetta documentation page related to #9575 * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update docs/rosetta/README.md Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * combine with existing doc Co-authored-by: Robert Zaremba <robert@zaremba.ch> Co-authored-by: Jonathan Gimeno <jgimeno@gmail.com> Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> Co-authored-by: ryanchrypto <12519942+ryanchrypto@users.noreply.github.com>
This commit is contained in:
Andrea Giacobino
GitHub
parent
d587599122
commit
4eaf18ac62
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue