From ec0ed1c1e5d53da7683ad4ceb6fd228ed05a8794 Mon Sep 17 00:00:00 2001 From: Adrian Gallagher Date: Mon, 21 Oct 2019 13:09:56 +1100 Subject: [PATCH] Basic documentation update for engine branch (#369) * Add basic docs for gRPC/gctcli/unified API and a few markdown fixes * Update patherinos and spacing fixes * Consistent namerinos * Fix spelling mistakes * Add fancy headers * Uperaterinos * Fix feedback nitterinos --- CONTRIBUTORS | 2 +- README.md | 87 ++++++++++--------- .../root_templates/root_readme.tmpl | 13 ++- .../sub_templates/contributors.tmpl | 6 +- cmd/gctcli/README.md | 38 ++++++++ docs/EXCHANGE_API.md | 72 +++++++++++++++ docs/FILES.md | 48 ++++++++++ docs/README.md | 31 +++++++ gctrpc/README.md | 63 ++++++++++++++ 9 files changed, 313 insertions(+), 47 deletions(-) create mode 100644 cmd/gctcli/README.md create mode 100644 docs/EXCHANGE_API.md create mode 100644 docs/FILES.md create mode 100644 docs/README.md create mode 100644 gctrpc/README.md diff --git a/CONTRIBUTORS b/CONTRIBUTORS index ae80db0c..c8958923 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -9,9 +9,9 @@ vadimzhukck | https://github.com/vadimzhukck 140am | https://github.com/140am marcofranssen | https://github.com/marcofranssen cranktakular | https://github.com/cranktakular +MadCozBadd | https://github.com/MadCozBadd leilaes | https://github.com/leilaes crackcomm | https://github.com/crackcomm -MadCozBadd | https://github.com/MadCozBadd andreygrehov | https://github.com/andreygrehov bretep | https://github.com/bretep woshidama323 | https://github.com/woshidama323 diff --git a/README.md b/README.md index 8f04d8dc..d255409b 100644 --- a/README.md +++ b/README.md @@ -53,19 +53,26 @@ We are aiming to support the top 20 highest volume exchanges based off the [Coin ## Current Features -+ Support for all Exchange fiat and digital currencies, with the ability to individually toggle them on/off. ++ Support for all exchange fiat and digital currencies, with the ability to individually toggle them on/off. + AES256 encrypted config file. + REST API support for all exchanges. + Websocket support for applicable exchanges. + Ability to turn off/on certain exchanges. -+ Ability to adjust manual polling timer for exchanges. + Communication packages (Slack, SMS via SMSGlobal, Telegram and SMTP) + HTTP rate limiter package. ++ Unified API for exchange usage. ++ Customisation of HTTP client features including setting a proxy, user agent and adjusting transport settings. ++ NTP client package. ++ Database support (Postgres and SQLite3). See [database](/database/README.md). ++ OTP generation tool. See [gen otp](/cmd/gen_otp). ++ Connection monitor package. ++ gRPC service and JSON RPC proxy. See [gRPC service](/gctrpc/README.md). ++ gRPC client. See [gctcli](/cmd/gctcli/README.md). + Forex currency converter packages (CurrencyConverterAPI, CurrencyLayer, Fixer.io, OpenExchangeRates) + Packages for handling currency pairs, tickers and orderbooks. + Portfolio management tool; fetches balances from supported exchanges and allows for custom address tracking. + Basic event trigger system. -+ WebGUI. ++ WebGUI (discontinued). ## Planned Features @@ -128,40 +135,40 @@ Binaries will be published once the codebase reaches a stable condition. ### A very special thank you to all who have contributed to this program: -|User|Github|Contribution Amount| -|--|--|--| -| thrasher- | https://github.com/thrasher- | 543 | -| shazbert | https://github.com/shazbert | 174 | -| gloriousCode | https://github.com/gloriousCode | 154 | -| xtda | https://github.com/xtda | 18 | -| ermalguni | https://github.com/ermalguni | 14 | -| vadimzhukck | https://github.com/vadimzhukck | 10 | -| 140am | https://github.com/140am | 8 | -| marcofranssen | https://github.com/marcofranssen | 8 | -| cranktakular | https://github.com/cranktakular | 5 | -| leilaes | https://github.com/leilaes | 3 | -| crackcomm | https://github.com/crackcomm | 3 | -| MadCozBadd | https://github.com/MadCozBadd | 2 | -| andreygrehov | https://github.com/andreygrehov | 2 | -| bretep | https://github.com/bretep | 2 | -| woshidama323 | https://github.com/woshidama323 | 2 | -| gam-phon | https://github.com/gam-phon | 2 | -| cornelk | https://github.com/cornelk | 2 | -| if1live | https://github.com/if1live | 2 | -| soxipy | https://github.com/soxipy | 2 | -| herenow | https://github.com/herenow | 2 | -| blombard | https://github.com/blombard | 1 | -| CodeLingoBot | https://github.com/CodeLingoBot | 1 | -| CodeLingoTeam | https://github.com/CodeLingoTeam | 1 | -| Daanikus | https://github.com/Daanikus | 1 | -| daniel-cohen | https://github.com/daniel-cohen | 1 | -| DirectX | https://github.com/DirectX | 1 | -| frankzougc | https://github.com/frankzougc | 1 | -| starit | https://github.com/starit | 1 | -| Jimexist | https://github.com/Jimexist | 1 | -| lookfirst | https://github.com/lookfirst | 1 | -| mattkanwisher | https://github.com/mattkanwisher | 1 | -| mKurrels | https://github.com/mKurrels | 1 | -| m1kola | https://github.com/m1kola | 1 | -| cavapoo2 | https://github.com/cavapoo2 | 1 | -| zeldrinn | https://github.com/zeldrinn | 1 | +|User|Contribution Amount| +|--|--| +| [thrasher-](https://github.com/thrasher-) | 548 | +| [shazbert](https://github.com/shazbert) | 176 | +| [gloriousCode](https://github.com/gloriousCode) | 155 | +| [xtda](https://github.com/xtda) | 18 | +| [ermalguni](https://github.com/ermalguni) | 14 | +| [vadimzhukck](https://github.com/vadimzhukck) | 10 | +| [140am](https://github.com/140am) | 8 | +| [marcofranssen](https://github.com/marcofranssen) | 8 | +| [cranktakular](https://github.com/cranktakular) | 5 | +| [MadCozBadd](https://github.com/MadCozBadd) | 3 | +| [leilaes](https://github.com/leilaes) | 3 | +| [crackcomm](https://github.com/crackcomm) | 3 | +| [andreygrehov](https://github.com/andreygrehov) | 2 | +| [bretep](https://github.com/bretep) | 2 | +| [woshidama323](https://github.com/woshidama323) | 2 | +| [gam-phon](https://github.com/gam-phon) | 2 | +| [cornelk](https://github.com/cornelk) | 2 | +| [if1live](https://github.com/if1live) | 2 | +| [soxipy](https://github.com/soxipy) | 2 | +| [herenow](https://github.com/herenow) | 2 | +| [blombard](https://github.com/blombard) | 1 | +| [CodeLingoBot](https://github.com/CodeLingoBot) | 1 | +| [CodeLingoTeam](https://github.com/CodeLingoTeam) | 1 | +| [Daanikus](https://github.com/Daanikus) | 1 | +| [daniel-cohen](https://github.com/daniel-cohen) | 1 | +| [DirectX](https://github.com/DirectX) | 1 | +| [frankzougc](https://github.com/frankzougc) | 1 | +| [starit](https://github.com/starit) | 1 | +| [Jimexist](https://github.com/Jimexist) | 1 | +| [lookfirst](https://github.com/lookfirst) | 1 | +| [mattkanwisher](https://github.com/mattkanwisher) | 1 | +| [mKurrels](https://github.com/mKurrels) | 1 | +| [m1kola](https://github.com/m1kola) | 1 | +| [cavapoo2](https://github.com/cavapoo2) | 1 | +| [zeldrinn](https://github.com/zeldrinn )| 1 | diff --git a/cmd/documentation/root_templates/root_readme.tmpl b/cmd/documentation/root_templates/root_readme.tmpl index 92c1c039..9666a073 100644 --- a/cmd/documentation/root_templates/root_readme.tmpl +++ b/cmd/documentation/root_templates/root_readme.tmpl @@ -54,19 +54,26 @@ We are aiming to support the top 20 highest volume exchanges based off the [Coin ## Current Features -+ Support for all Exchange fiat and digital currencies, with the ability to individually toggle them on/off. ++ Support for all exchange fiat and digital currencies, with the ability to individually toggle them on/off. + AES256 encrypted config file. + REST API support for all exchanges. + Websocket support for applicable exchanges. + Ability to turn off/on certain exchanges. -+ Ability to adjust manual polling timer for exchanges. + Communication packages (Slack, SMS via SMSGlobal, Telegram and SMTP) + HTTP rate limiter package. ++ Unified API for exchange usage. ++ Customisation of HTTP client features including setting a proxy, user agent and adjusting transport settings. ++ NTP client package. ++ Database support (Postgres and SQLite3). See [database](/database/README.md). ++ OTP generation tool. See [gen otp](/cmd/gen_otp). ++ Connection monitor package. ++ gRPC service and JSON RPC proxy. See [gRPC service](/gctrpc/README.md). ++ gRPC client. See [gctcli](/cmd/gctcli/README.md). + Forex currency converter packages (CurrencyConverterAPI, CurrencyLayer, Fixer.io, OpenExchangeRates) + Packages for handling currency pairs, tickers and orderbooks. + Portfolio management tool; fetches balances from supported exchanges and allows for custom address tracking. + Basic event trigger system. -+ WebGUI. ++ WebGUI (discontinued). ## Planned Features diff --git a/cmd/documentation/sub_templates/contributors.tmpl b/cmd/documentation/sub_templates/contributors.tmpl index e08f5609..1051ea3b 100644 --- a/cmd/documentation/sub_templates/contributors.tmpl +++ b/cmd/documentation/sub_templates/contributors.tmpl @@ -3,9 +3,9 @@ ### A very special thank you to all who have contributed to this program: -|User|Github|Contribution Amount| -|--|--|--| +|User|Contribution Amount| +|--|--| {{- range $contributor := .Contributors -}} -| {{$contributor.Login}} | {{$contributor.URL}} | {{$contributor.Contributions}} | +| [{{$contributor.Login}}]({{$contributor.URL}}) | {{$contributor.Contributions}} | {{end}} {{end}} diff --git a/cmd/gctcli/README.md b/cmd/gctcli/README.md new file mode 100644 index 00000000..6a22e7ae --- /dev/null +++ b/cmd/gctcli/README.md @@ -0,0 +1,38 @@ +# GoCryptoTrader gRPC client + + + +[![Build Status](https://travis-ci.com/thrasher-corp/gocryptotrader.svg?branch=master)](https://travis-ci.com/thrasher-corp/gocryptotrader) +[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/thrasher-corp/gocryptotrader/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/thrasher-corp/gocryptotrader?status.svg)](https://godoc.org/github.com/thrasher-corp/gocryptotrader) +[![Coverage Status](http://codecov.io/github/thrasher-corp/gocryptotrader/coverage.svg?branch=master)](http://codecov.io/github/thrasher-corp/gocryptotrader?branch=master) +[![Go Report Card](https://goreportcard.com/badge/github.com/thrasher-corp/gocryptotrader)](https://goreportcard.com/report/github.com/thrasher-corp/gocryptotrader) + +A cryptocurrency trading bot supporting multiple exchanges written in Golang. + +**Please note that this bot is under development and is not ready for production!** + +## Community + +Join our slack to discuss all things related to GoCryptoTrader! [GoCryptoTrader Slack](https://join.slack.com/t/gocryptotrader/shared_invite/enQtNTQ5NDAxMjA2Mjc5LTc5ZDE1ZTNiOGM3ZGMyMmY1NTAxYWZhODE0MWM5N2JlZDk1NDU0YTViYzk4NTk3OTRiMDQzNGQ1YTc4YmRlMTk) + +## Background + +GoCryptoTrader utilises gRPC for client/server interaction. Authentication is done +by a self signed TLS cert, which only supports connections from localhost and also +through basic authorisation specified by the users config file. + +## Usage + +GoCryptoTrader must be running with gRPC enabled in order to use the client features. + +```bash +go build or go run . +``` + +For a full list of commands, you can run `gctcli --help`. Alternatively, you can also +visit our [GoCryptoTrader API reference.](https://api.gocryptotrader.app/) + +## Autocomplete + +Bash/ZSH autocomplete entries can be found [here](/contrib). diff --git a/docs/EXCHANGE_API.md b/docs/EXCHANGE_API.md new file mode 100644 index 00000000..1448fc5c --- /dev/null +++ b/docs/EXCHANGE_API.md @@ -0,0 +1,72 @@ +# GoCryptoTrader Unified API + + + +[![Build Status](https://travis-ci.com/thrasher-corp/gocryptotrader.svg?branch=master)](https://travis-ci.com/thrasher-corp/gocryptotrader) +[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/thrasher-corp/gocryptotrader/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/thrasher-corp/gocryptotrader?status.svg)](https://godoc.org/github.com/thrasher-corp/gocryptotrader) +[![Coverage Status](http://codecov.io/github/thrasher-corp/gocryptotrader/coverage.svg?branch=master)](http://codecov.io/github/thrasher-corp/gocryptotrader?branch=master) +[![Go Report Card](https://goreportcard.com/badge/github.com/thrasher-corp/gocryptotrader)](https://goreportcard.com/report/github.com/thrasher-corp/gocryptotrader) + +A cryptocurrency trading bot supporting multiple exchanges written in Golang. + +**Please note that this bot is under development and is not ready for production!** + +## Community + +Join our slack to discuss all things related to GoCryptoTrader! [GoCryptoTrader Slack](https://join.slack.com/t/gocryptotrader/shared_invite/enQtNTQ5NDAxMjA2Mjc5LTc5ZDE1ZTNiOGM3ZGMyMmY1NTAxYWZhODE0MWM5N2JlZDk1NDU0YTViYzk4NTk3OTRiMDQzNGQ1YTc4YmRlMTk) + +## Unified API + +GoCryptoTrader supports a unified API for dealing with exchanges. Each exchange +has its own wrapper file which maps the exchanges own RESTful endpoints into a +standardised way for bot and standalone application usage. + +A full breakdown of all the supported wrapper funcs can be found [here.](https://github.com/thrasher-corp/gocryptotrader/blob/engine/exchanges/interfaces.go#L16) +Please note that these change on a regular basis as GoCryptoTrader is undergoing +rapid development. + +Each exchange supports public API endpoints which don't require any authentication +(fetching ticker, orderbook, trade data) and also private API endpoints (which +require authentication). Some examples include submitting, cancelling and fetching +open orders). To use the authenticated API endpoints, you'll need to set your API +credentials in either the `config.json` file or when you initialise an exchange in +your application, and also have the appropriate key permissions set for the exchange. +Each exchange has a credentials validator which ensures that the API credentials +supplied meet the requirements to make an authenticated request. + +## Public API Ticker Example + +```go + var b bitstamp.Bitstamp + b.SetDefaults() + ticker, err := b.FetchTicker(currency.NewPair(currency.BTC, currency.USD), asset.Spot) + if err != nil { + // Handle error + } + fmt.Println(ticker.Last) +``` + +## Private API Submit Order Example + +```go + var b bitstamp.Bitstamp + b.SetDefaults() + + b.API.Credentials.Key = "your_key" + b.API.Credentials.Secret = "your_secret" + b.API.Credentials.ClientID = "your_clientid" + + order := &exchange.OrderSubmission{ + Pair: currency.NewPair(currency.BTC, currency.USD), + OrderSide: exchange.SellOrderSide, + OrderType: exchange.LimitOrderType, + Price: 1000000, + Amount: 0.1, + } + resp, err := b.SubmitOrder(order) + if err != nil { + // Handle error + } + fmt.Println(resp.OrderID) +``` diff --git a/docs/FILES.md b/docs/FILES.md new file mode 100644 index 00000000..f456f7f7 --- /dev/null +++ b/docs/FILES.md @@ -0,0 +1,48 @@ +# GoCryptoTrader File Hierarchy + + + +[![Build Status](https://travis-ci.com/thrasher-corp/gocryptotrader.svg?branch=master)](https://travis-ci.com/thrasher-corp/gocryptotrader) +[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/thrasher-corp/gocryptotrader/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/thrasher-corp/gocryptotrader?status.svg)](https://godoc.org/github.com/thrasher-corp/gocryptotrader) +[![Coverage Status](http://codecov.io/github/thrasher-corp/gocryptotrader/coverage.svg?branch=master)](http://codecov.io/github/thrasher-corp/gocryptotrader?branch=master) +[![Go Report Card](https://goreportcard.com/badge/github.com/thrasher-corp/gocryptotrader)](https://goreportcard.com/report/github.com/thrasher-corp/gocryptotrader) + +A cryptocurrency trading bot supporting multiple exchanges written in Golang. + +**Please note that this bot is under development and is not ready for production!** + +## Community + +Join our slack to discuss all things related to GoCryptoTrader! [GoCryptoTrader Slack](https://join.slack.com/t/gocryptotrader/shared_invite/enQtNTQ5NDAxMjA2Mjc5LTc5ZDE1ZTNiOGM3ZGMyMmY1NTAxYWZhODE0MWM5N2JlZDk1NDU0YTViYzk4NTk3OTRiMDQzNGQ1YTc4YmRlMTk) + +## Default data directory + +By default, GoCryptoTrader uses the following data directores: + +Operating System | Path | Translated +--- | --- | ---- +| Windows | %APPDATA%\GoCryptoTrader | C:\Users\User\AppData\Roaming\GoCryptoTrader +| Linux | ~/.gocryptotrader | /home/user/.gocryptotrader +| macOS | ~/.gocryptotrader | /Users/User/.gocryptotrader + +This can be overridden by running GoCryptoTrader with the `-datadir` command line +parameter. + +## Subdirectories + +Depending on the features enabled, you'll see the following directories created +inside the data directory: + +Directory | Reason +--- | --- +| database | Used to store the database file (if using SQLite3) and sqlboiler config files +| logs | Used to store the debug log file (`log.txt` by default), if file output and logging is enabled +| tls | Used to store the generated self-signed certificate and key for gRPC authentication + +## Files + +File | Reason +--- | --- +config.json or config.dat (encrypted config) | Config file which GoCryptoTrader loads from (can be overridden by the `-config` command line parameter). +currency.json | Cached list of fiat and digital currencies diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..c45f6c7e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# GoCryptoTrader Documentation + + + +[![Build Status](https://travis-ci.com/thrasher-corp/gocryptotrader.svg?branch=master)](https://travis-ci.com/thrasher-corp/gocryptotrader) +[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/thrasher-corp/gocryptotrader/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/thrasher-corp/gocryptotrader?status.svg)](https://godoc.org/github.com/thrasher-corp/gocryptotrader) +[![Coverage Status](http://codecov.io/github/thrasher-corp/gocryptotrader/coverage.svg?branch=master)](http://codecov.io/github/thrasher-corp/gocryptotrader?branch=master) +[![Go Report Card](https://goreportcard.com/badge/github.com/thrasher-corp/gocryptotrader)](https://goreportcard.com/report/github.com/thrasher-corp/gocryptotrader) + +A cryptocurrency trading bot supporting multiple exchanges written in Golang. + +**Please note that this bot is under development and is not ready for production!** + +## Community + +Join our slack to discuss all things related to GoCryptoTrader! [GoCryptoTrader Slack](https://join.slack.com/t/gocryptotrader/shared_invite/enQtNTQ5NDAxMjA2Mjc5LTc5ZDE1ZTNiOGM3ZGMyMmY1NTAxYWZhODE0MWM5N2JlZDk1NDU0YTViYzk4NTk3OTRiMDQzNGQ1YTc4YmRlMTk) + +## Documentation + +See below for feature documentation: + ++ [Exchange unified API documentation](EXCHANGE_API.md) ++ [File hierarchy documentation](FILES.md) ++ [Config documentation](/config/README.md) ++ [gRPC service documentation](/gctrpc/README.md) ++ [gctcli documentation](/cmd/gctcli/README.md) ++ [Database documentation](/database/README.md) ++ [Currency documentation](/currency/README.md) ++ [Exchange documentation](/exchanges/README.md) ++ [Portfolio documentation](/portfolio/README.md) diff --git a/gctrpc/README.md b/gctrpc/README.md new file mode 100644 index 00000000..b7f0ee9d --- /dev/null +++ b/gctrpc/README.md @@ -0,0 +1,63 @@ +# GoCryptoTrader gRPC Service + + + +[![Build Status](https://travis-ci.com/thrasher-corp/gocryptotrader.svg?branch=master)](https://travis-ci.com/thrasher-corp/gocryptotrader) +[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/thrasher-corp/gocryptotrader/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/thrasher-corp/gocryptotrader?status.svg)](https://godoc.org/github.com/thrasher-corp/gocryptotrader) +[![Coverage Status](http://codecov.io/github/thrasher-corp/gocryptotrader/coverage.svg?branch=master)](http://codecov.io/github/thrasher-corp/gocryptotrader?branch=master) +[![Go Report Card](https://goreportcard.com/badge/github.com/thrasher-corp/gocryptotrader)](https://goreportcard.com/report/github.com/thrasher-corp/gocryptotrader) + +A cryptocurrency trading bot supporting multiple exchanges written in Golang. + +**Please note that this bot is under development and is not ready for production!** + +## Community + +Join our slack to discuss all things related to GoCryptoTrader! [GoCryptoTrader Slack](https://join.slack.com/t/gocryptotrader/shared_invite/enQtNTQ5NDAxMjA2Mjc5LTc5ZDE1ZTNiOGM3ZGMyMmY1NTAxYWZhODE0MWM5N2JlZDk1NDU0YTViYzk4NTk3OTRiMDQzNGQ1YTc4YmRlMTk) + +## Background + +GoCryptoTrader utilises gRPC for client/server interaction. Authentication is done +by a self signed TLS cert, which only supports connections from localhost and also +through basic authorisation specified by the users config file. + +GoCryptoTrader also supports a gRPC JSON proxy service for applications which can +be toggled on or off depending on the users preference. + +## Installation + +GoCryptoTrader requires a local installation of the Google protocol buffers +compiler `protoc` v3.0.0 or above. Please install this via your local package +manager or by downloading one of the releases from the official repository: + +[protoc releases](https://github.com/protocolbuffers/protobuf/releases) + +Then use `go get -u` to download the following packages: + +```bash +go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway +go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger +go get -u github.com/golang/protobuf/protoc-gen-go +``` + +This will place three binaries in your `$GOBIN`; + +* `protoc-gen-grpc-gateway` +* `protoc-gen-swagger` +* `protoc-gen-go` + +Make sure that your `$GOBIN` is in your `$PATH`. + +## Usage + +After the above dependencies are required, make necessary changes to the `rpc.proto` +spec file and run the generation scripts: + +### Windows + +Run `gen_pb_win.bat` + +### Linux and macOS + +Run `./gen_pb_linux.sh`