58597139fa
## Description Closes: #9404 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
<!--
|
||
order: 6
|
||
-->
|
||
|
||
# Rosetta
|
||
|
||
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).
|
||
|
||
## 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:
|
||
|
||
```sh
|
||
appd rosetta --help
|
||
```
|
||
|
||
To test and run Rosetta API endpoints for applications that are running and exposed, use the following command:
|
||
|
||
```sh
|
||
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 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
|
||
|
||
In case more customization is required, it's possible to embed the Client type and override the methods which require customizations.
|
||
|
||
Example:
|
||
|
||
```go
|
||
package custom_client
|
||
import (
|
||
|
||
"context"
|
||
"github.com/coinbase/rosetta-sdk-go/types"
|
||
"github.com/cosmos/cosmos-sdk/server/rosetta/lib"
|
||
)
|
||
|
||
// CustomClient embeds the standard cosmos client
|
||
// which means that it implements the cosmos-rosetta-gateway Client
|
||
// interface while at the same time allowing to customize certain methods
|
||
type CustomClient struct {
|
||
*rosetta.Client
|
||
}
|
||
|
||
func (c *CustomClient) ConstructionPayload(_ context.Context, request *types.ConstructionPayloadsRequest) (resp *types.ConstructionPayloadsResponse, err error) {
|
||
// provide custom signature bytes
|
||
panic("implement me")
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
Example:
|
||
|
||
```go
|
||
package custom_errors
|
||
import crgerrs "github.com/cosmos/cosmos-sdk/server/rosetta/lib/errors"
|
||
|
||
var customErrRetriable = true
|
||
var CustomError = crgerrs.RegisterError(100, "custom message", customErrRetriable, "description")
|
||
```
|
||
|
||
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.
|