From 9eb6dd29d7a046d65801239c8f1822449750ace7 Mon Sep 17 00:00:00 2001 From: racbc Date: Wed, 2 Mar 2022 11:53:21 -0600 Subject: [PATCH] Update SDK README and CONTRIBUTING files (#375) * Update SDK README and CONTRIBUTING files Updated the README and CONTRIBUTING files to encourage developer contribution. * Update link to Related Projects in README * Update CONTRIBUTING title formatting * Update CONTRIBUTING file info after feedback * Post-peer update to README and CONTRIBUTING - Made post-review updates to the README and CONTRIBUTING files. - Moved information from the rosetta-specifications README to the SDK README. --- CONTRIBUTING.md | 98 ++++++++++++++++++++++++++++++++----------------- README.md | 83 +++++++++++++++++++++++++++++++++-------- 2 files changed, 132 insertions(+), 49 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cae76e67..131f24ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,56 +1,88 @@ -# Contributing to Rosetta-SDK-Go +# Contributing to rosetta-sdk-go ## Code of Conduct -All interactions with this project follow our [Code of Conduct][code-of-conduct]. -By participating, you are expected to honor this code. Violators can be banned -from further participation in this project, or potentially all Coinbase projects. +All interactions with this project follow our [Code of Conduct](https://github.com/coinbase/code-of-conduct). By participating, you are expected to honor this code. Violators can be banned from further participation in this project, or potentially all Coinbase projects. -[code-of-conduct]: https://github.com/coinbase/code-of-conduct +## How to Contribute -## Bug Reports +You can contribute to this repository by asking questions, providing feedback, and reporting issues. -* Ensure your issue [has not already been reported][1]. It may already be fixed! -* Include the steps you carried out to produce the problem. -* Include the behavior you observed along with the behavior you expected, and - why you expected it. -* Include any relevant stack traces or debugging output. +### Asking Questions -## Feature Requests +Submit your questions via the [Rosetta Community boards][13]. -We welcome feedback with or without pull requests. If you have an idea for how -to improve the project, great! All we ask is that you take the time to write a -clear and concise explanation of what need you are trying to solve. If you have -thoughts on _how_ it can be solved, include those too! +### Providing Feedback + +You can also use the [Rosetta Community boards][13] to provide feedback. + +### Reporting Issues + +You can report issues by submitting bug reports, feature requests, or pull requests via GitHub. You **must** submit [security issues](#security-issues) and [support requests](#support-requests) through the links provided. + +#### Bug Reports + +Before filing a bug report, ensure that your issue [has not already been reported][1]. It may already be fixed! + +If your bug hasn’t been fixed, follow these steps to file a bug report: + +1. [Open an issue in GitHub][10]. +2. Add a title for your bug report. It should briefly describe the problem. +3. Follow the template that appears in the Write text box. This is the best way to describe the bug. +4. Click _Submit new issue_ to finish filing the bug report. + +#### Feature Requests + +We welcome feedback with or without pull requests. If you have an idea for how to improve the project, great! All we ask is that you take the time to write a clear and concise explanation of the need you are trying to solve. If you have thoughts on _how_ it can be solved, include those too! + +To submit a feature request, follow these steps: + +1. [Open an issue in GitHub][10]. +2. Add a title for your feature request. It should briefly describe your requested feature. +3. Follow the template that appears in the Write text box. This is the best way to explain your request. Be clear and concise in your responses. +4. Click _Submit new issue_ to submit the feature request. The best way to see a feature added, however, is to submit a pull request. -## Pull Requests +#### Pull Requests + +Before creating your pull request, it's usually worth asking whether the code you're planning on writing will be considered for merging. You can do this by [opening an issue][1] and asking. It may also help give the maintainers context for when the time comes to review your code. -* Before creating your pull request, it's usually worth asking if the code - you're planning on writing will actually be considered for merging. You can - do this by [opening an issue][1] and asking. It may also help give the - maintainers context for when the time comes to review your code. +Ensure that your [commit messages are well-written][2]. This can double as your pull request message, so it pays to take the time to write a clear message. -* Ensure your [commit messages are well-written][2]. This can double as your - pull request message, so it pays to take the time to write a clear message. +Additionally, make sure that you have written unit tests for your changes. If you're unsure as to what to test, don't hesitate to [open an issue][1] and ask! -* Add tests for your feature. You should be able to look at other tests for - examples. If you're unsure, don't hesitate to [open an issue][1] and ask! -* Run `make gen` before submitting the PR, it will make sure to update the - code so that `make check-gen` passes in the CI. You should run `make check-gen` - before sending out the PR. +To submit your pull request, follow these steps: -* Submit your pull request! +1. Follow these instructions on how to [open a pull request in GitHub][11]. +2. Click _Create pull request_ to submit your pull request. -## Support Requests +Once you submit your pull request, a reviewer will revise it, and either approve it or offer suggestions. -For security reasons, any communication referencing support tickets for Coinbase -products will be ignored. The request will have its content redacted and will -be locked to prevent further discussion. +#### Security Issues + +You can send a report through Coinbase's [H1 program][12]. Check out the [Security][14] tab for more information. + +#### Support Requests All support requests must be made via [our support team][3]. +**For security reasons, any communication referencing support tickets for Coinbase products will be ignored.** The request will have its content redacted and will be locked to prevent further discussion. + +© 2022 Coinbase + + [1]: https://github.com/coinbase/rosetta-sdk-go/issues [2]: https://chris.beams.io/posts/git-commit/#seven-rules [3]: https://support.coinbase.com/customer/en/portal/articles/2288496-how-can-i-contact-coinbase-support- + +[5]: https://github.com/coinbase/rosetta-sdk-go/issues/new/choose +[6]: https://github.com/coinbase/rosetta-sdk-go/issues/new?assignees=&labels=bug&template=bug_report.md&title= +[7]: https://github.com/coinbase/rosetta-sdk-go/issues/new?assignees=&labels=enhancement&template=feature_request.md&title= +[8]: https://github.com/coinbase/rosetta-sdk-go/pulls +[9]: https://github.com/coinbase/rosetta-sdk-go/compare +[10]: https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request#creating-an-issue +[11]: https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request#creating-a-pull-request +[12]: https://hackerone.com/coinbase +[13]: https://community.rosetta-api.org +[14]: https://github.com/coinbase/rosetta-sdk-go/security \ No newline at end of file diff --git a/README.md b/README.md index 2cb50286..626d403e 100644 --- a/README.md +++ b/README.md @@ -16,38 +16,89 @@ 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). + +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 -Before diving into the SDK, we recommend taking a look at the Rosetta API Docs: -* [Overview](https://www.rosetta-api.org/docs/welcome.html) -* [Data API](https://www.rosetta-api.org/docs/data_api_introduction.html) -* [Construction API](https://www.rosetta-api.org/docs/construction_api_introduction.html) +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) + +## SDK Packages -## Packages * [Types](types): Auto-generated Rosetta types * [Client](client): Low-level communication with any Rosetta server * [Server](server): Simplified Rosetta API server development * [Asserter](asserter): Validation of Rosetta types -* [Fetcher](fetcher): Simplified and validated communication with -any Rosetta server +* [Fetcher](fetcher): Simplified and validated communication with any Rosetta server * [Parser](parser): Tool for parsing Rosetta blocks * [Syncer](syncer): Sync Rosetta blocks with customizable handling * [Reconciler](reconciler): Compare derived balances with node balances * [Keys](keys): Cryptographic operations for Rosetta-supported curves * [Constructor](constructor): Coordinate the construction and broadcast of transactions -## Examples -The packages listed above are demoed extensively in -[examples](examples) and are utilized throughout the -[rosetta-cli](https://github.com/coinbase/rosetta-cli). +These packages are demoed extensively in [examples](examples) and are utilized throughout the [rosetta-cli](https://github.com/coinbase/rosetta-cli) tool. + +## Contributing + +You may contribute to the `rosetta-sdk-go` project in various ways: + +* [Asking Questions](CONTRIBUTING.md/#asking-questions) +* [Providing Feedback](CONTRIBUTING.md/#providing-feedback) +* [Reporting Issues](CONTRIBUTING.md/#reporting-issues) + +Read our [Contributing](CONTRIBUTING.MD) documentation for more information. + +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 + +* [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-ecosystem) — 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. + +## Reference Implementations + +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. + +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. + +### 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). + +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. + +### Using Another Language + +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. + +### Syncer + +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! + +### Parser + +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. + +## SDK Development + +While working on improvements to this repository, we recommend that you use these commands to check your code: -## Development * `make deps` to install dependencies * `make gen` to generate types and helpers * `make test` to run tests @@ -57,4 +108,4 @@ The packages listed above are demoed extensively in ## License This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0). -© 2021 Coinbase +© 2022 Coinbase \ No newline at end of file