Skip to content

Commit

Permalink
Update SDK README and CONTRIBUTING files (#375)
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
@racbc
racbc authored Mar 2, 2022
1 parent c26e095 commit 9eb6dd2
Show file tree
Hide file tree
Showing 2 changed files with 132 additions and 49 deletions.
98 changes: 65 additions & 33 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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

<!-- Before adding link 15, populate link 4. One you do that, please erase this note. --->
[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-
<!--- [4]: link removed --->
[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
83 changes: 67 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,38 +16,89 @@ Go SDK to create and interact with Rosetta API implementations
<a href="https://github.com/coinbase/rosetta-sdk-go/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/coinbase/rosetta-sdk-go.svg" /></a>
<a href="https://pkg.go.dev/github.com/coinbase/rosetta-sdk-go?tab=overview"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=shield" /></a>
</p>
<p align="center">
Build once.
Integrate your blockchain everywhere.
</p>

## 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
Expand All @@ -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

0 comments on commit 9eb6dd2

Please sign in to comment.