github.com/Finschia/finschia-sdk@v0.48.1/docs/run-node/rosetta.md (about)

     1  # Rosetta
     2  
     3  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).
     4  
     5  ## Add Rosetta Command
     6  
     7  The Rosetta API server is a stand-alone server that connects to a node of a chain developed with Cosmos SDK.
     8  
     9  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`).
    10  
    11  Import the `server` package:
    12  
    13  ```go
    14      "github.com/Finschia/finschia-sdk/server"
    15  ```
    16  
    17  Find the following line:
    18  
    19  ```go
    20  initRootCmd(rootCmd, encodingConfig)
    21  ```
    22  
    23  After that line, add the following:
    24  
    25  ```go
    26  rootCmd.AddCommand(
    27    server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler)
    28  )
    29  ```
    30  
    31  The `RosettaCommand` function builds the `rosetta` root command and is defined in the `server` package within Cosmos SDK.
    32  
    33  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.
    34  
    35  An implementation example can be found in `simapp` package.
    36  
    37  ## Use Rosetta Command
    38  
    39  To run Rosetta in your application CLI, use the following command:
    40  
    41  ```
    42  appd rosetta --help
    43  ```
    44  
    45  To test and run Rosetta API endpoints for applications that are running and exposed, use the following command:
    46  
    47  ```
    48  appd rosetta
    49       --blockchain "your application name (ex: gaia)"
    50       --network "your chain identifier (ex: testnet-1)"
    51       --tendermint "tendermint endpoint (ex: localhost:26657)"
    52       --grpc "gRPC endpoint (ex: localhost:9090)"
    53       --addr "rosetta binding address (ex: :8080)"
    54  ```
    55  
    56  ## Extension
    57  
    58  There are two ways in which you can customize and extend the implementation with your custom settings.
    59  
    60  ### Message extension
    61  
    62  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.
    63  Examples on how to do so can be found in the staking types such as `MsgDelegate`, or in bank types such as `MsgSend`.
    64  
    65  ### Client interface override
    66  
    67  In case more customization is required, it's possible to embed the Client type and override the methods which require customizations.
    68  
    69  Example:
    70  
    71  ```go
    72  package custom_client
    73  import (
    74  
    75  "context"
    76  "github.com/coinbase/rosetta-sdk-go/types"
    77  "github.com/Finschia/finschia-sdk/server/rosetta/lib"
    78  )
    79  
    80  // CustomClient embeds the standard cosmos client
    81  // which means that it implements the cosmos-rosetta-gateway Client
    82  // interface while at the same time allowing to customize certain methods
    83  type CustomClient struct {
    84      *rosetta.Client
    85  }
    86  
    87  func (c *CustomClient) ConstructionPayload(_ context.Context, request *types.ConstructionPayloadsRequest) (resp *types.ConstructionPayloadsResponse, err error) {
    88      // provide custom signature bytes
    89      panic("implement me")
    90  }
    91  ```
    92  
    93  ### Error extension
    94  
    95  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.
    96  
    97  Example:
    98  
    99  ```go
   100  package custom_errors
   101  import crgerrs "github.com/Finschia/finschia-sdk/server/rosetta/lib/errors"
   102  
   103  var customErrRetriable = true
   104  var CustomError = crgerrs.RegisterError(100, "custom message", customErrRetriable, "description")
   105  ```
   106  
   107  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.
   108  
   109  ## Integration in app.go
   110  
   111  To integrate rosetta as a command in your application, in app.go, in your root command simply use the `server.RosettaCommand` method.
   112  
   113  Example:
   114  
   115  ```go
   116  package app
   117  import (
   118  
   119  "github.com/Finschia/finschia-sdk/server"
   120  "github.com/spf13/cobra"
   121  )
   122  
   123  func buildAppCommand(rootCmd *cobra.Command) {
   124      // more app.go init stuff
   125  	// ...
   126      // add rosetta command
   127  	rootCmd.AddCommand(server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler))
   128  }
   129  ```
   130  
   131  A full implementation example can be found in `simapp` package.
   132  
   133  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.