Rosetta SDK
Go SDK to create and interact with Rosetta API implementations
Build once. Integrate your blockchain everywhere.
Overview
The rosetta-sdk-go provides a collection of packages used for interaction with the Rosetta API specification. Much of the code in this repository is generated from the rosetta-specifications repository.
Jump to:
If you have a blockchain based on go-ethereum, we recommend that you use our rosetta-geth-sdk SDK.
Getting Started
This Golang project provides a server package that empowers a developer to write a full Rosetta Data API server by only implementing an interface. This package automatically validates client requests and calls the functions you implement with pre-parsed requests (instead of in raw JSON).
If you plan to use a language other than Golang, you will need to either codegen a server (using Swagger Codegen or OpenAPI Generator) or write one from scratch. If you choose to write an implementation in another language, we ask that you create a separate repository in an SDK-like format for all the code you generate so that other developers can use it. You can add your repository to the list in the rosetta-ecosystem repository, and in the ecosystem category of our community site. Use this repository (rosetta-sdk-go) for an example of how to generate code from this specification.
Installation Guide
This command installs the Server package.
go get github.com/coinbase/rosetta-sdk-go/serverComponents
Router
The router is a Mux router that routes traffic to the correct controller.
Controller
Controllers are automatically generated code that specify an interface that a service must implement.
Services
Services are implemented by you to populate responses. These services are invoked by controllers.
Recommended Folder Structure
main.go
/services
block_service.go
network_service.go
...
Quick Examples
Complete SDK Example
This is an example of how to write an implementation using the Server package in rosetta-sdk-go.
package main
import (
"fmt"
"log"
"net/http"
"github.com/coinbase/rosetta-sdk-go/asserter"
"github.com/coinbase/rosetta-sdk-go/examples/server/services"
"github.com/coinbase/rosetta-sdk-go/server"
"github.com/coinbase/rosetta-sdk-go/types"
)
const (
serverPort = 8080
)
// NewBlockchainRouter creates a Mux http.Handler from a collection
// of server controllers.
func NewBlockchainRouter(
network *types.NetworkIdentifier,
asserter *asserter.Asserter,
) http.Handler {
networkAPIService := services.NewNetworkAPIService(network)
networkAPIController := server.NewNetworkAPIController(
networkAPIService,
asserter,
)
blockAPIService := services.NewBlockAPIService(network)
blockAPIController := server.NewBlockAPIController(
blockAPIService,
asserter,
)
return server.NewRouter(networkAPIController, blockAPIController)
}
func main() {
network := &types.NetworkIdentifier{
Blockchain: "Rosetta",
Network: "Testnet",
}
// The asserter automatically rejects incorrectly formatted
// requests.
asserter, err := asserter.NewServer(
[]string{"Transfer", "Reward"},
false,
[]*types.NetworkIdentifier{network},
nil,
false,
"",
)
if err != nil {
log.Fatal(err)
}
// Create the main router handler then apply the logger and Cors
// middlewares in sequence.
router := NewBlockchainRouter(network, asserter)
loggedRouter := server.LoggerMiddleware(router)
corsRouter := server.CorsMiddleware(loggedRouter)
log.Printf("Listening on port %d\n", serverPort)
log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", serverPort), corsRouter))
}SDK Packages
- Types: Auto-generated Rosetta types
- Client: Low-level communication with any Rosetta server
- Server: Simplified Rosetta API server development
- Asserter: Validation of Rosetta types
- Fetcher: Simplified and validated communication with any Rosetta server
- Parser: Tool for parsing Rosetta blocks
- Syncer: Sync Rosetta blocks with customizable handling
- Reconciler: Compare derived balances with node balances
- Keys: Cryptographic operations for Rosetta-supported curves
- Constructor: Coordinate the construction and broadcast of transactions
These packages are demoed extensively in examples and are utilized throughout the rosetta-cli tool.
Syncer
The core of any integration is syncing blocks reliably. The syncer serially processes blocks from a Data API implementation (automatically handling re-orgs) with user-defined handling logic and pluggable storage. After a block is processed, store it to a DB or send a push notificationβthe decision is up to you!
Parser
When reading the operations in a block, it's helpful to apply higher-level groupings to related operations, or match operations in a transaction to some set of generic descriptions (i.e., ensure there are two operations of equal but opposite amounts). The parser empowers any integrator to build abstractions on top of the building blocks that the Rosetta API exposes.
Development
Helpful commands for development:
Install Dependencies
make deps
Generate Types, Client and Server
make gen
If you want to modify client and server, please modify files under templates/client and templates/server then run make gen
Run Tests
make test
Lint the Source Code
This includes the generated code.
make lint
Code Check
make release
Testing
To validate rosetta-sdk-go, install rosetta-cli and run one of the following commands:
rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.json- This command validates that the Data API implementation is correct, using the bitcointestnetnode. It also ensures that the implementation does not miss any balance-changing operations.rosetta-cli check:construction --configuration-file rosetta-cli-conf/testnet/config.json- This command validates the Construction API implementation. It also verifies transaction construction, signing, and submissions to thetestnetnetwork.rosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json- This command validates that the Data API implementation is correct, using the bitcoinmainnetnode. It also ensures that the implementation does not miss any balance-changing operations.
Read the How to Test your Rosetta Implementation documentation for additional details.
Contributing
You may contribute to the rosetta-sdk-go project in various ways:
Read our Contributing documentation for more information.
When you've finished an implementation for a blockchain, share your work in the ecosystem category of the community site. Platforms looking for implementations for certain blockchains will be monitoring this section of the website for high-quality implementations they can use for integration. Make sure that your implementation meets the expectations of any implementation.
Documentation
You can find the Rosetta API documentation at rosetta-api.org.
Check out the Getting Started section to start diving into Rosetta.
Our documentation is divided into the following sections:
Related Projects
- rosetta-specifications β The
rosetta-specificationsrepository generates the SDK code in therosetta-sdk-gorepository. - rosetta-cli β Use the
rosetta-clitool to test your Rosetta API implementation. The tool also provides the ability to look up block contents and account balances. - rosetta-geth-sdk β The
rosetta-geth-sdkrepository provides a collection of packages used for interaction with the Rosetta API specification. The goal of this SDK is to help accelerate Rosetta API implementation on go-ethereum based chains.
Sample Implementations
To help you with examples, we developed complete Rosetta API sample implementations for Bitcoin and Ethereum. Developers of Bitcoin-like or Ethereum-like blockchains may find it easier to fork these implementation samples than to write an implementation from scratch.
You can also find community implementations for a variety of blockchains in the rosetta-ecosystem repository, and in the ecosystem category of our community site.
License
This project is available open source under the terms of the Apache 2.0 License.
Β© 2022 Coinbase