From cd1bd8d19b20ac57772fef1f8fe1919654e4bc96 Mon Sep 17 00:00:00 2001 From: racbc Date: Fri, 8 Jul 2022 13:48:53 -0400 Subject: [PATCH 1/2] Update README file to new template --- README.md | 247 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 202 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 266afefe..c8aab81c 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,17 @@ +

Rosetta

+

Rosetta SDK

Go SDK to create and interact with Rosetta API implementations

+

@@ -16,30 +19,138 @@ 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](https://github.com/coinbase/rosetta-specifications) repository. -## Documentation - -You can find the Rosetta API documentation at [rosetta-api.org](https://www.rosetta-api.org/docs/welcome.html). - -Check out the [Getting Started](https://www.rosetta-api.org/docs/getting_started.html) section to start diving into Rosetta. - -Our documentation is divided into the following sections: - -* [Product Overview](https://www.rosetta-api.org/docs/welcome.html) -* [Getting Started](https://www.rosetta-api.org/docs/getting_started.html) -* [Rosetta API Spec](https://www.rosetta-api.org/docs/Reference.html) -* [Testing](https://www.rosetta-api.org/docs/rosetta_cli.html) -* [Best Practices](https://www.rosetta-api.org/docs/node_deployment.html) -* [Repositories](https://www.rosetta-api.org/docs/rosetta_specifications.html) - +Jump to: + +* [Getting Started](#Getting-Started) +* [Quick Examples](#Quick-Examples) +* [Testing](#Test-the-Implementation-with-rosetta-cli) +* [Documentation](#Documentation) +* [Related Projects](#Related-Projects) + +If you have a blockchain based on go-ethereum, we recommend that you use our [rosetta-geth-sdk](https://github.com/coinbase/rosetta-geth-sdk) SDK. + + +## Getting Started + + This Golang project provides a [server package](https://github.com/coinbase/rosetta-sdk-go/tree/master/server) 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](https://swagger.io/tools/swagger-codegen) or [OpenAPI Generator](https://openapi-generator.tech/)) 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](https://github.com/coinbase/rosetta-ecosystem) repository, and in the [ecosystem category](https://community.rosetta-api.org/c/ecosystem) 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. +```shell +go get github.com/coinbase/rosetta-sdk-go/server +``` + +### Components +#### Router +The router is a [Mux](https://github.com/gorilla/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](https://github.com/coinbase/rosetta-sdk-go/tree/master/examples/server) of how to write an implementation using the Server package in rosetta-sdk-go. + +```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](types): Auto-generated Rosetta types @@ -55,57 +166,103 @@ Our documentation is divided into the following sections: These packages are demoed extensively in [examples](examples) and are utilized throughout the [rosetta-cli](https://github.com/coinbase/rosetta-cli) tool. -## Contributing +### Syncer -You may contribute to the `rosetta-sdk-go` project in various ways: +The core of any integration is syncing blocks reliably. The [syncer](https://github.com/coinbase/rosetta-sdk-go/tree/master/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! -* [Asking Questions](CONTRIBUTING.md/#asking-questions) -* [Providing Feedback](CONTRIBUTING.md/#providing-feedback) -* [Reporting Issues](CONTRIBUTING.md/#reporting-issues) +### Parser -Read our [Contributing](CONTRIBUTING.MD) documentation for more information. +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](https://github.com/coinbase/rosetta-sdk-go/tree/master/parser) empowers any integrator to build abstractions on top of the [building blocks](https://www.rosetta-api.org/docs/rosetta_principles.html#universal-transactions) that the Rosetta API exposes. -When you've finished an implementation for a blockchain, share your work in the [ecosystem category of the community site](https://community.rosetta-api.org/c/ecosystem). 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](https://www.rosetta-api.org/docs/node_deployment.html) of any implementation. + + -## Related Projects + +## Development -* [rosetta-specifications](https://github.com/coinbase/rosetta-specifications) — The `rosetta-specifications` repository generates the SDK code in the `rosetta-sdk-go` repository. -* [rosetta-cli](https://github.com/coinbase/rosetta-cli) — Use the `rosetta-cli` tool to test your Rosetta API implementation. The tool also provides the ability to look up block contents and account balances. +Helpful commands for development: + +### Install Dependencies +``` +make deps +``` -## Reference Implementations +### Generate Types and Helpers +``` +make gen +``` -To help you with examples, we developed complete Rosetta API reference implementations for [Bitcoin](https://github.com/coinbase/rosetta-bitcoin) and [Ethereum](https://github.com/coinbase/rosetta-ethereum). Developers of Bitcoin-like or Ethereum-like blockchains may find it easier to fork these reference implementations than to write an implementation from scratch. +### Run Tests +``` +make test +``` -You can also find community implementations for a variety of blockchains in the [rosetta-ecosystem](https://github.com/coinbase/rosetta-ecosystem) repository, and in the [ecosystem category](https://community.rosetta-api.org/c/ecosystem) of our community site. +### Lint the Source Code +This includes the generated code. +``` +make lint +``` -### Using Golang -If you are comfortable with Golang, the easiest way to write a Rosetta Data API implementation is to use this repository. This Golang project provides a [server package](https://github.com/coinbase/rosetta-sdk-go/tree/master/server) 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). +### Code Check +``` +make release +``` -This is a simple [example](https://github.com/coinbase/rosetta-sdk-go/tree/master/examples/server) of how to write an implementation using this package in rosetta-sdk-go. + +## Test the Implementation with rosetta-cli -### Using Another Language +To validate `rosetta-sdk-go`, [install `rosetta-cli`](https://github.com/coinbase/rosetta-cli#install) and run one of the following commands: -If you plan to use a language other than Golang, you will need to either codegen a server (using [Swagger Codegen](https://swagger.io/tools/swagger-codegen) or [OpenAPI Generator](https://openapi-generator.tech/)) 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](https://github.com/coinbase/rosetta-ecosystem) repository, and in the [ecosystem category](https://community.rosetta-api.org/c/ecosystem) of our community site. Use this repository (rosetta-sdk-go) for an example of how to generate code from this specification. +* `rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.json` - This command validates that the Data API implementation is correct, using the bitcoin `testnet` node. 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 the `testnet` network. +* `rosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json` - This command validates that the Data API implementation is correct, using the bitcoin `mainnet` node. It also ensures that the implementation does not miss any balance-changing operations. -### Syncer +Read the [How to Test your Rosetta Implementation](https://www.rosetta-api.org/docs/rosetta_test.html) documentation for additional details. -The core of any integration is syncing blocks reliably. The [syncer](https://github.com/coinbase/rosetta-sdk-go/tree/master/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...it's up to you! + +## Contributing -### Parser +You may contribute to the `rosetta-sdk-go` project in various ways: -When reading the operations in a block, it can be helpful to apply higher-level groupings to related operations, or match operations in a transaction to some set of generic descriptions (e.g., ensure there are two operations of equal but opposite amounts). The [parser](https://github.com/coinbase/rosetta-sdk-go/tree/master/parser) empowers any integrator to build abstractions on top of the [low-level building blocks](https://www.rosetta-api.org/docs/low_level_ops.html) that the Rosetta API exposes. +* [Asking Questions](CONTRIBUTING.md/#asking-questions) +* [Providing Feedback](CONTRIBUTING.md/#providing-feedback) +* [Reporting Issues](CONTRIBUTING.md/#reporting-issues) -## SDK Development +Read our [Contributing](CONTRIBUTING.MD) documentation for more information. -While working on improvements to this repository, we recommend that you use these commands to check your code: +When you've finished an implementation for a blockchain, share your work in the [ecosystem category of the community site](https://community.rosetta-api.org/c/ecosystem). 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](https://www.rosetta-api.org/docs/node_deployment.html) of any implementation. -* `make deps` to install dependencies -* `make gen` to generate types and helpers -* `make test` to run tests -* `make lint` to lint the source code (including generated code) -* `make release` to check if code passes all tests run by CircleCI + +## Documentation + +You can find the Rosetta API documentation at [rosetta-api.org](https://www.rosetta-api.org/docs/welcome.html). +Check out the [Getting Started](https://www.rosetta-api.org/docs/getting_started.html) section to start diving into Rosetta. + +Our documentation is divided into the following sections: + +* [Product Overview](https://www.rosetta-api.org/docs/welcome.html) +* [Getting Started](https://www.rosetta-api.org/docs/getting_started.html) +* [Rosetta API Spec](https://www.rosetta-api.org/docs/Reference.html) +* [Samples](https://www.rosetta-api.org/docs/reference-implementations.html) +* [Testing](https://www.rosetta-api.org/docs/rosetta_cli.html) +* [Best Practices](https://www.rosetta-api.org/docs/node_deployment.html) +* [Repositories](https://www.rosetta-api.org/docs/rosetta_specifications.html) + + +## Related Projects + +* [rosetta-specifications](https://github.com/coinbase/rosetta-specifications) — The `rosetta-specifications` repository generates the SDK code in the `rosetta-sdk-go` repository. +* [rosetta-cli](https://github.com/coinbase/rosetta-cli) — Use the `rosetta-cli` tool to test your Rosetta API implementation. The tool also provides the ability to look up block contents and account balances. +* [rosetta-geth-sdk](https://github.com/coinbase/rosetta-geth-sdk) – The `rosetta-geth-sdk` repository 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](https://github.com/coinbase/rosetta-bitcoin) and [Ethereum](https://github.com/coinbase/rosetta-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](https://github.com/coinbase/rosetta-ecosystem) repository, and in the [ecosystem category](https://community.rosetta-api.org/c/ecosystem) of our community site. + ## License This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0). - + © 2022 Coinbase From 4933ccd4deaa10dd3b98281afb6536158adb33bf Mon Sep 17 00:00:00 2001 From: racbc Date: Thu, 14 Jul 2022 18:44:06 -0400 Subject: [PATCH 2/2] Updated the Testing header to match the approved README template --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c8aab81c..9940b2ee 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Jump to: * [Getting Started](#Getting-Started) * [Quick Examples](#Quick-Examples) -* [Testing](#Test-the-Implementation-with-rosetta-cli) +* [Testing](#Testing) * [Documentation](#Documentation) * [Related Projects](#Related-Projects) @@ -209,7 +209,7 @@ make release ``` -## Test the Implementation with rosetta-cli +## Testing To validate `rosetta-sdk-go`, [install `rosetta-cli`](https://github.com/coinbase/rosetta-cli#install) and run one of the following commands: @@ -265,4 +265,4 @@ You can also find community implementations for a variety of blockchains in the ## License This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0). -© 2022 Coinbase +© 2022 Coinbase \ No newline at end of file