From 9a1c8afebe23c60af639b7953889819d7abf6ac5 Mon Sep 17 00:00:00 2001 From: Kristoffer Josefsson Date: Fri, 7 Feb 2020 10:37:10 -0800 Subject: [PATCH] WIP: Betterdocs (#206) * Added all hackage links * Added installation instructions, symlinked to docs * Polish docs * Fixed licence and author and github locations * Renamed project on main README * Clean up docs * Updated readme links in haddocks * Fix broken link * Changed font --- INSTALL.md | 67 ++++++++++++++++++ Makefile | 8 +-- README.md | 68 ++----------------- hs-abci-docs/.tintin.yml | 6 +- hs-abci-docs/doc/0010-Overview.md | 5 ++ hs-abci-docs/doc/0020-Installation.md | 1 + .../{0100-Tutorial.md => 0400-Tutorial.md} | 0 hs-abci-docs/doc/98-Logging.md | 18 +++-- hs-abci-docs/doc/99-Metrics.md | 2 +- hs-abci-docs/doc/index.md | 20 +++++- hs-abci-docs/nameservice/package.yaml | 20 ++---- .../tutorial/Foundations/02-BaseApp.md | 2 - .../tutorial/Foundations/03-Modules.md | 2 - hs-abci-docs/nameservice/tutorial/README.md | 38 +---------- .../tutorial/Tutorial/Nameservice/02-Types.md | 4 +- .../Tutorial/Nameservice/03-Message.md | 2 - .../Tutorial/Nameservice/04-Keeper.md | 2 - .../tutorial/Tutorial/Nameservice/05-Query.md | 2 - .../Tutorial/Nameservice/06-Module.md | 2 - hs-abci-docs/package.yaml | 2 +- hs-abci-docs/simple-storage/README.md | 4 +- hs-abci-docs/simple-storage/package.yaml | 6 +- hs-abci-extra/README.md | 2 +- hs-abci-extra/package.yaml | 19 ++---- hs-abci-sdk/README.md | 10 +-- hs-abci-sdk/package.yaml | 6 +- hs-abci-server/README.md | 4 +- hs-abci-server/package.yaml | 6 +- hs-abci-test-utils/package.yaml | 19 ++---- hs-abci-types/README.md | 3 +- hs-abci-types/package.yaml | 6 +- hs-iavl-client/package.yaml | 6 +- hs-tendermint-client/package.yaml | 19 ++---- 33 files changed, 164 insertions(+), 217 deletions(-) create mode 100644 INSTALL.md create mode 100644 hs-abci-docs/doc/0010-Overview.md create mode 120000 hs-abci-docs/doc/0020-Installation.md rename hs-abci-docs/doc/{0100-Tutorial.md => 0400-Tutorial.md} (100%) diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..b818511f --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,67 @@ +--- +title: Installation +--- + +## Build + +### Prerequisites + +#### stack +At the moment the project's build is managed by `stack`. You can find everything you need regarding how to install stack on your machine [here](https://docs.haskellstack.org/en/stable/README/). + +#### protoc +We use a custom setup to generate Haskell bindings to the protobuf files, using the proto-lens library from Google. In order for this to work you need to have the protobuf compiler `protoc` on your machine. You can get installation instructions [here](https://google.github.io/proto-lens/installing-protoc.html) + +#### libsecp256k1 +In order to build with stack you will need this. On MacOS you can use brew: + +``` +> brew tap cuber/homebrew-libsecp256k1 +> brew install libsecp256k1 +``` + +On linux: + +``` +> sudo add-apt-repository ppa:tah83/secp256k1 +> sudo apt-get update +> sudo apt-get install libsecp256k1 +``` + +#### style +You will also need to install `hlint` and `stylish-haskell` for code hygiene during development. In the project root simply run + +```bash +> stack install hlint stylish-haskell +``` + +### Commands +There is a `Makefile` for this project where you can find all of the options for building, testing etc. The `Makefile` +is documented and there is a help menu which you can access via the commands `make` or `make help`. + +## Protobuf Files and Generated Modules +The protobuf files are all in the `/protos` directory, and we use a custom setup in order +to generate the corresponding `Proto.*` Haskell modules. If you want to view all of these +generated modules, you can run + +```bash +> find hs-abci-types/.stack-work -path '*autogen/Proto' +``` + +to find the root directory. + +## Style Guide +There is a `.stylish-haskell.yaml` file that controls some of the style guide, particularly +around import statements and some indentation rules. There is also a small guide for things that +fall outside of this in the [style wiki](https://github.com/f-o-a-m/kepler/wiki/code-style-guide). +If it's not covered by either of these but you think it's really important, mention it in an issue. + +## Building documentation +You can build the haddocks for the library code only using + +```bash +make build-docs-local +``` + +This does not build and link documentation for dependencies, useful mostly for testing +documentation formatting. diff --git a/Makefile b/Makefile index e4b74fe7..876ac36e 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ stylish: ## Run stylish-haskell over all haskell projects find ./hs-abci-types \ ./hs-abci-extra \ ./hs-tendermint-client \ - ./hs-abci-examples \ + ./hs-abci-docs \ ./hs-abci-sdk \ ./hs-abci-test-utils \ ./hs-abci-server \ @@ -80,13 +80,13 @@ test-iavl-client: ## test the iavl client library basic operation (requires grpc ##################### deploy-simple-storage-docker: install ## run the simple storage docker network - docker-compose -f hs-abci-examples/simple-storage/docker-compose.yaml up --build + docker-compose -f hs-abci-docs/simple-storage/docker-compose.yaml up --build deploy-nameservice: install ## run the nameservice docker network with elk stack for logging - docker-compose -f hs-abci-examples/nameservice/docker-compose.yaml up --build + docker-compose -f hs-abci-docs/nameservice/docker-compose.yaml up --build deploy-nameservice-test: install ## run the nameservice docker network for testing - docker-compose -f hs-abci-examples/nameservice/docker-compose-test.yaml up --build + docker-compose -f hs-abci-docs/nameservice/docker-compose-test.yaml up --build ##################### diff --git a/README.md b/README.md index 1c6b53e7..aab1665b 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,14 @@ -# hs-abci +# kepler -[![Build Status](https://travis-ci.com/f-o-a-m/hs-abci.svg?branch=master)](https://travis-ci.com/f-o-a-m/hs-abci) +[![Build Status](https://travis-ci.com/f-o-a-m/kepler.svg?branch=master)](https://travis-ci.com/f-o-a-m/kepler) ## Introduction This is the official repository for the Haskell implementation of the ABCI server and SDK for developing applications backed by the Tendermint replication engine. You can read more about Tendermint and the ABCI specs in their [documentation](https://tendermint.com/docs/spec/abci/). -To understand how to build a simple application using this library, see the literate haskell [walkthrough](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-examples/nameservice/README.md). +To understand how to build a simple application using this library, see the literate haskell [walkthrough](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-docs/nameservice/README.md). ## Build -### Prerequisites - -#### stack -At the moment the project's build is managed by `stack`. You can find everything you need regarding how to install stack on your machine [here](https://docs.haskellstack.org/en/stable/README/). - -#### protoc -We use a custom setup to generate Haskell bindings to the protobuf files, using the proto-lens library from Google. In order for this to work you need to have the protobuf compiler `protoc` on your machine. You can get installation instructions [here](https://google.github.io/proto-lens/installing-protoc.html) - -#### libsecp256k1 -In order to build with stack you will need this. On MacOS you can use brew: - -``` -> brew tap cuber/homebrew-libsecp256k1 -> brew install libsecp256k1 -``` - -On linux: - -``` -> sudo add-apt-repository ppa:tah83/secp256k1 -> sudo apt-get update -> sudo apt-get install libsecp256k1 -``` - -#### style -You will also need to install `hlint` and `stylish-haskell` for code hygiene during development. In the project root simply run - -```bash -> stack install hlint stylish-haskell -``` - -### Commands -There is a `Makefile` for this project where you can find all of the options for building, testing etc. The `Makefile` -is documented and there is a help menu which you can access via the commands `make` or `make help`. - -## Protobuf Files and Generated Modules -The protobuf files are all in the `/protos` directory, and we use a custom setup in order -to generate the corresponding `Proto.*` Haskell modules. If you want to view all of these -generated modules, you can run - -```bash -> find hs-abci-types/.stack-work -path '*autogen/Proto' -``` - -to find the root directory. - -## Style Guide -There is a `.stylish-haskell.yaml` file that controls some of the style guide, particularly -around import statements and some indentation rules. There is also a small guide for things that -fall outside of this in the [style wiki](https://github.com/f-o-a-m/hs-abci/wiki/code-style-guide). -If it's not covered by either of these but you think it's really important, mention it in an issue. - -## Building documentation -You can build the haddocks for the library code only using - -```bash -make build-docs-local -``` - -This does not build and link documentation for dependencies, useful mostly for testing -documentation formatting. +See [installation instructions](https://github.com/f-o-a-m/kepler/blob/master/INSTALL.md) diff --git a/hs-abci-docs/.tintin.yml b/hs-abci-docs/.tintin.yml index 362ef2aa..1b0cd520 100644 --- a/hs-abci-docs/.tintin.yml +++ b/hs-abci-docs/.tintin.yml @@ -1,10 +1,10 @@ name: kepler synopsis: Haskell Cosmos SDK github: f-o-a-m/kepler -author: Martin Allen +author: f-o-a-m authorWebsite: https://foam.space color: #5E5184 #logo: https://pbs.twimg.com/profile_images/791467713956839424/pBRQn1wt_400x400.jpg -titleFont: Poiret One +titleFont: Lora titleFontWeight: 400 -bodyFont: PT Sans +bodyFont: Open Sans diff --git a/hs-abci-docs/doc/0010-Overview.md b/hs-abci-docs/doc/0010-Overview.md new file mode 100644 index 00000000..03d97d9f --- /dev/null +++ b/hs-abci-docs/doc/0010-Overview.md @@ -0,0 +1,5 @@ +--- +title: Overview +--- + +The documentation consists of an overview, foundations, a tutorial called ` nameservice` as well as documentation of logging and metrics. You can navigate to the relevant sections on the left side. diff --git a/hs-abci-docs/doc/0020-Installation.md b/hs-abci-docs/doc/0020-Installation.md new file mode 120000 index 00000000..5f52b2be --- /dev/null +++ b/hs-abci-docs/doc/0020-Installation.md @@ -0,0 +1 @@ +../../INSTALL.md \ No newline at end of file diff --git a/hs-abci-docs/doc/0100-Tutorial.md b/hs-abci-docs/doc/0400-Tutorial.md similarity index 100% rename from hs-abci-docs/doc/0100-Tutorial.md rename to hs-abci-docs/doc/0400-Tutorial.md diff --git a/hs-abci-docs/doc/98-Logging.md b/hs-abci-docs/doc/98-Logging.md index eaf50c78..9ef0ac80 100644 --- a/hs-abci-docs/doc/98-Logging.md +++ b/hs-abci-docs/doc/98-Logging.md @@ -4,7 +4,7 @@ title: Logging # Logging -The SDK has built in support for structured logging via the [katip](https://hackage.haskell.org/package/katip) logging library. Even still, the SDK is agnostic to where you want your logs to go. Katip logs are managed by *scribes* whos job is precisely this, so the output depends on which scribes you use. The two most common scribes are the [console scribe](https://hackage.haskell.org/package/katip-0.8.3.0/docs/Katip-Scribes-Handle.html#v:mkHandleScribe) and the [Elasticsearch scribe](https://hackage.haskell.org/package/katip-elasticsearch). +The SDK has built in support for structured logging via the [katip](https://hackage.haskell.org/package/katip) logging library. Even still, the SDK is agnostic to where you want your logs to go. Katip logs are managed by *scribes* whose job is precisely this, so the output depends on which scribes you use. The two most common scribes are the [console scribe](https://hackage.haskell.org/package/katip-0.8.3.0/docs/Katip-Scribes-Handle.html#v:mkHandleScribe) and the [Elasticsearch scribe](https://hackage.haskell.org/package/katip-elasticsearch). The `Nameservice` application has support for either scribe -- it will use Elasticsearch if you provide the `ES_HOST` and `ES_PORT` environment variables or otherwise will default to console logging. The docker deployment is configured to use Elasticsearch. @@ -14,19 +14,19 @@ The docker network includes an `elk` image (Elasticsearch, Logstash, Kibana) for When logging to Elasticsearch, you can use the Kibana dashboard for creating queries and visualizations. We will cover the basics here. If you have already launched the docker network, you can view the Kibana dashboard by going to http://localhost:5601/app/kibana. You should see something like - + To create an index (a searchable pattern), click on the *Management* tab, click *Create Index*, and enter `nameservice` as the pattern. You should see something like this: - + You can ignore the advanced options, e.g. time filter, for now: - + To view and search the logs, you can click the `Discover` tab. You should see all of the logs in the resulting search, from both server and application: - + ## Searching a Log Index @@ -38,19 +38,19 @@ The log structure is effectively a JSON object (with nesting). There are a few f - `message_hash`: the SHA256 of the protobuf encoded bytes for the abci message that caused the logs. - `ns` (namespace): a list of increasingly specific scopes for where the log originated. In this case, `nameservice` is the root namespace, `server` or `application` is the next scope. -Remember that the basic lifescycle of an `ABCI` message is that it first comes to the ABCI-server from tendermint, is then handed off to your application for processing, and finally the response is sent from the ABCI-server back to tendermint. In order to better track this lifecycle, we highly recommend you use the [logging middleware](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Logger.hs). This middleware will attach the `message_type` and `message_hash` to the context for every single log that is produced, meaning that you can get a trace for a given message by simply searching its hash. +Remember that the basic lifescycle of an `ABCI` message is that it first comes to the ABCI-server from tendermint, is then handed off to your application for processing, and finally the response is sent from the ABCI-server back to tendermint. In order to better track this lifecycle, we highly recommend you use the [logging middleware](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Logger.hs). This middleware will attach the `message_type` and `message_hash` to the context for every single log that is produced, meaning that you can get a trace for a given message by simply searching its hash. ### Querying the Logs You can create custom search filters in the *Discover* tab, just click the *Add a filter* button near the search bar. For example, we can filter all of the logs for those that correspond to a *deliverTx* message: - + (**NOTE**: If you run the e2e tests against the docker network, you should see search results corresponding to the transactions created by the test suite. ) Similarly, you can compose multiple filters to obtain only those logs emitted by the application itself during a *deliverTx* context, i.e. by filtering for `application` on the `ns` namespace field: - + ### Indexing Transaction Events @@ -85,5 +85,3 @@ This log corresponds to an event emitted by the `Nameservice` module during tran ``` In this way the log index serves as a rudimentary event indexer for transaction events as well. - -## [Next: Metrics](./Metrics.md) diff --git a/hs-abci-docs/doc/99-Metrics.md b/hs-abci-docs/doc/99-Metrics.md index 06efc9da..b0e600e5 100644 --- a/hs-abci-docs/doc/99-Metrics.md +++ b/hs-abci-docs/doc/99-Metrics.md @@ -6,7 +6,7 @@ title: Metrics The SDK has some built in support for metrics via [prometheus](https://prometheus.io/), but ultimately you may choose a different runtime interpretation for the metrics, or even choose to ignore it entirely. -The `Nameservice` application uses application specific metrics, for instance increasing the message counters for module level messages, or for timing module responses. It also uses the server metrics via the [metrics middleware](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Metrics.hs) to count ABCI messages and to time server responses. This middleware is highly recommended for any production system. +The `Nameservice` application uses application specific metrics, for instance increasing the message counters for module level messages, or for timing module responses. It also uses the server metrics via the [metrics middleware](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Metrics.hs) to count ABCI messages and to time server responses. This middleware is highly recommended for any production system. ## Setting up metrics diff --git a/hs-abci-docs/doc/index.md b/hs-abci-docs/doc/index.md index 1d6def92..7da17c6f 100644 --- a/hs-abci-docs/doc/index.md +++ b/hs-abci-docs/doc/index.md @@ -2,6 +2,20 @@ title: Home --- -The home of Kepler. -Link to [hackage](https://hackage.haskell.org/package/kepler) -Link to [hs-abci-sdk](haddocks/hs-abci-sdk/) +## Introduction + +This is the official repository for the Haskell implementation of the ABCI server and SDK for developing applications backed by the Tendermint replication engine. + +This site contains a [tutorial](0010-Overview.html) as well as haddocks documentation below. + +You can read more about Tendermint and the ABCI specs in the [documentation](https://tendermint.com/docs/spec/abci/) hosted on their website. + +## Documentation + +- [hs-abci-sdk](haddocks/hs-abci-sdk/) +- [hs-abci-extra](haddocks/hs-abci-extra/) +- [hs-abci-server](haddocks/hs-abci-server/) +- [hs-abci-test-utils](haddocks/hs-abci-test-utils/) +- [hs-abci-types](haddocks/hs-abci-types/) +- [hs-iavl-client](haddocks/hs-iavl-client/) +- [hs-tendermint-client](haddocks/hs-tendermint-client/) diff --git a/hs-abci-docs/nameservice/package.yaml b/hs-abci-docs/nameservice/package.yaml index e57a0f25..f0e8750d 100644 --- a/hs-abci-docs/nameservice/package.yaml +++ b/hs-abci-docs/nameservice/package.yaml @@ -1,20 +1,12 @@ name: nameservice version: 0.1.0.0 -github: "githubuser/nameservice" -license: BSD3 -author: "Author name here" -maintainer: "example@example.com" -copyright: "2019 Author name here" +github: "f-o-a-m/kepler/hs-abci-docs/nameservice" +license: Apache +author: "Martin Allen" +maintainer: "martin@foam.space" +copyright: "2020 Martin Allen" - -# Metadata used when publishing your package -# synopsis: Short description of your package -# category: Web - -# To avoid duplicated efforts in documentation and dealing with the -# complications of embedding Haddock markup inside cabal files, it is -# common to point users to the README.md file. -description: Please see the README on GitHub at +description: Please see the README on GitHub at extra-source-files: - README.md diff --git a/hs-abci-docs/nameservice/tutorial/Foundations/02-BaseApp.md b/hs-abci-docs/nameservice/tutorial/Foundations/02-BaseApp.md index 163ac17f..31a5bc28 100644 --- a/hs-abci-docs/nameservice/tutorial/Foundations/02-BaseApp.md +++ b/hs-abci-docs/nameservice/tutorial/Foundations/02-BaseApp.md @@ -30,5 +30,3 @@ These effects are: `BaseApp` acts as an intermediate effect system for specifying applications, it does not make any assumptions about how these effects will be interpreted at runtime. For example, `RawStore` could eventualy be interpeted by any persistent or in-memory storage capable of handling the commands `Put`, `Get` etc. Most of the work in writing modules involves plugging into `BaseApp` at various points. For example, your module can create custom errors to throw or catch, but you must tell the SDK how to translate this custom error into an `AppError`. Likewise your module can define custom events to log during transaction execution, but you must describe to the SDK how to translate these custom events types into the type `Event`. - -[Next: Modules](Modules.md) diff --git a/hs-abci-docs/nameservice/tutorial/Foundations/03-Modules.md b/hs-abci-docs/nameservice/tutorial/Foundations/03-Modules.md index 9f18874f..b6b2eea2 100644 --- a/hs-abci-docs/nameservice/tutorial/Foundations/03-Modules.md +++ b/hs-abci-docs/nameservice/tutorial/Foundations/03-Modules.md @@ -45,5 +45,3 @@ data Modules (ms :: [*]) r where ~~~ When you are ready to create your application, you simply specify a value of type `Modules` and some other configuration data, and the SDK will create an `App` for you. - -[Next: Types](../Tutorial/Nameservice/Types.md) diff --git a/hs-abci-docs/nameservice/tutorial/README.md b/hs-abci-docs/nameservice/tutorial/README.md index 4ce23e72..dcf218b7 100644 --- a/hs-abci-docs/nameservice/tutorial/README.md +++ b/hs-abci-docs/nameservice/tutorial/README.md @@ -1,43 +1,11 @@ --- -title: Overview +title: Tutorial --- ## Introduction We're going to build an example application that mirrors the `golang` [cosmos-sdk](https://github.com/cosmos/cosmos-sdk) example application called [Nameservice](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice). There is also a tutorial for that application which you can find [here](https://tutorials.cosmos.network/nameservice/tutorial/00-intro.html) for comparison. -## Contents -1. [Introduction](README.md) - - [Application Specification](README.md#application-specification) - - [How to Read this Tutorial](README.md#how-to-read-this-tutorial) - - [Tutorial Goals](README.md#tutorial-goals) -2. Foundations - - [Overview](Foundations/Overview.md) - - [BaseApp](Foundations/BaseApp.md) - - [Modules](Foundations/Modules.md) - 1. [Definition](Foundations/Modules.md#definition) - 2. [Composition](Foundations/Modules.md#composition) -3. Nameservice - - [Overview](Tutorial/Nameservice/Overview.md) - - [Types](Tutorial/Nameservice/Types.md) - 1. [Using A Typed Key Value Store](Tutorial/Nameservice/Types.md#using-a-typed-key-value-store) - 2. [Tutorial.Nameservice.Types](Tutorial/Nameservice/Types.md#tutorialnameservicetypes) - - [Message](Tutorial/Nameservice/Message.md) - 1. [Message Types](Tutorial/Nameservice/Message.md#message-types) - 2. [Tutorial.Nameservice.Message](Tutorial/Nameservice/Message.md#tutorialnameservicemessage) - - [Keeper](Tutorial/Nameservice/Keeper.md) - 1. [Definition](Tutorial/Nameservice/Keeper.md#definition) - 2. [Tutorial.Nameservice.Keeper](Tutorial/Nameservice/Keeper.md#tutorialnameservicekeeper) - - [Query](Tutorial/Nameservice/Query.md) - 1. [Definition](Tutorial/Nameservice/Query.md#definition) - 2. [Tutorial.Nameservice.Query](Tutorial/Nameservice/Query.md#tutorialnameservicequery) - - [Module](Tutorial/Nameservice/Module.md) - 1. [Tutorial.Nameservice.Module](Tutorial/Nameservice/Module.md#tutorialnameservicemodule) - - [Application](Tutorial/Nameservice/Application.md) - 1. [From Modules To App](Tutorial/Nameservice/Application.md#from-modules-to-app) - 2. [Tutorial.Nameservice.Application](Tutorial/Nameservice/Application.md#tutorialnameserviceapplication) - - ## Application Specification The Nameservice application is a simple marketplace for a name resolution service. Let us say that a `Name` resolves to type called `Whois` where @@ -67,7 +35,7 @@ The benefit of this is that we don't have to develop the entire application in t ## Tutorial Goals The goal of this tutorial is to explain how the Nameservice app is constructed using the `hs-abci-sdk` package. Nameservice is a relatively simple but still non-trivial application. -If you would like to start with something simpler, you can view the tutorial for the [simple-storage](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-examples/simple-storage) example application. +If you would like to start with something simpler, you can view the tutorial for the [simple-storage](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-docs/simple-storage) example application. This tutorial should teach you: 1. How to construct application specific modules. @@ -85,5 +53,3 @@ It is also allows the application developer to construct modules without much re main :: IO () main = pure () ~~~ - -[Next: BaseApp](Foundations/Overview.md) diff --git a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/02-Types.md b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/02-Types.md index f6c5aa82..48da5dc3 100644 --- a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/02-Types.md +++ b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/02-Types.md @@ -167,7 +167,7 @@ class IsAppError e where makeAppError :: e -> AppError ~~~ -The fields for `AppError` correspond to tendermint message fields for messages that support error return types, such as `checkTx`, `deliverTx`, and `query`. Typically we use the module name as the codespace, like in the definition of `NamespaceError`: +The fields for `AppError` correspond to tendermint message fields for messages that support error return types, such as `checkTx`, `deliverTx`, and `query`. Typically we use the module name as the codespace, like in the definition of `NameserviceError`: ~~~ haskell data NameserviceError = @@ -254,5 +254,3 @@ instance A.FromJSON NameClaimed where instance BA.ToEvent NameClaimed where makeEventType _ = "NameClaimed" ~~~ - -[Next: Message](Message.md) diff --git a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/03-Message.md b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/03-Message.md index 5984b55e..d48a7029 100644 --- a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/03-Message.md +++ b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/03-Message.md @@ -177,5 +177,3 @@ instance ValidateMessage BuyName where , isAuthorCheck "Owner" msg buyNameBuyer ] ~~~ - -[Next: Keeper](Keeper.md) diff --git a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/04-Keeper.md b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/04-Keeper.md index 5ae099f5..c3d3c707 100644 --- a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/04-Keeper.md +++ b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/04-Keeper.md @@ -120,5 +120,3 @@ eval = mapError BA.makeAppError . evalNameservice DeleteWhois name -> BA.delete storeKey name ) ~~~ - -[Next: Query](Query.md) diff --git a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/05-Query.md b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/05-Query.md index 90325ebf..278c97cd 100644 --- a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/05-Query.md +++ b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/05-Query.md @@ -43,5 +43,3 @@ server = Here `RouteT` is a type family that can build a server from the `Api` type to handle incoming requests. It is similar to how `servant` works, and is largely vendored from that codebase. Note that more advanced queries are possible other than just serving what is in storage. For example you might want to use joins to fulfill requests or use query parameters in the url. These are all possible, but we won't go into details here as they are not used in the app. - -[Next: Router](Router.md) diff --git a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/06-Module.md b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/06-Module.md index 94450f97..ef4f01de 100644 --- a/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/06-Module.md +++ b/hs-abci-docs/nameservice/tutorial/Tutorial/Nameservice/06-Module.md @@ -76,5 +76,3 @@ Note the constraints on `r`: This is saying that we can run this module in any context for which `r` has the effects from `BaseApp`, `Token`, and `Nameservice`. This is how we explicitly declare module dependencies, by using the constraint system. Other than that, there is nothing really to note. We are just collecting the pieces we have already defined in one place. - -[Next: Application](Application.md) diff --git a/hs-abci-docs/package.yaml b/hs-abci-docs/package.yaml index d4c71d57..43e5f156 100644 --- a/hs-abci-docs/package.yaml +++ b/hs-abci-docs/package.yaml @@ -1,7 +1,7 @@ name: kepler version: 1.0.0.0 github: "f-o-a-m/kepler" -license: BSD3 +license: Apache author: "f-o-a-m" maintainer: "martin@foam.space" copyright: "2020 FOAM" diff --git a/hs-abci-docs/simple-storage/README.md b/hs-abci-docs/simple-storage/README.md index da7e6542..9ffd955b 100644 --- a/hs-abci-docs/simple-storage/README.md +++ b/hs-abci-docs/simple-storage/README.md @@ -19,5 +19,5 @@ it will build an image for simple-storage and launch it in a docker network with a tendermint-core node. ## Application Messages -The application uses a protobuf file to define its [transaction messages](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-examples/simple-storage/protos/simple-storage/messages.proto). Thus if you would like to post transactions to this application via RPC, you will need to first consume -this profobuf file. You can follow the pattern in the test suite using hs-tendermint-client. \ No newline at end of file +The application uses a protobuf file to define its [transaction messages](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-docs/simple-storage/protos/simple-storage/messages.proto). Thus if you would like to post transactions to this application via RPC, you will need to first consume +this profobuf file. You can follow the pattern in the test suite using hs-tendermint-client. diff --git a/hs-abci-docs/simple-storage/package.yaml b/hs-abci-docs/simple-storage/package.yaml index 38cddd95..23ab2344 100644 --- a/hs-abci-docs/simple-storage/package.yaml +++ b/hs-abci-docs/simple-storage/package.yaml @@ -1,15 +1,15 @@ name: simple-storage version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-abci-examples/simple-storage" +github: "f-o-a-m/kepler/hs-abci-docs/simple-storage" license: Apache author: Martin Allen maintainer: "martin@foam.space" -copyright: "2019 Martin Allen" +copyright: "2020 Martin Allen" extra-source-files: - protos/**/*.proto -description: Please see the README on GitHub at +description: Please see the README on GitHub at default-extensions: - DeriveGeneric diff --git a/hs-abci-extra/README.md b/hs-abci-extra/README.md index fc5ae47e..589cb793 100644 --- a/hs-abci-extra/README.md +++ b/hs-abci-extra/README.md @@ -4,4 +4,4 @@ The goal here is to provide common features and example middleware implementatio ## Example using middleware -There is a small example using the Logger middleware [here](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-examples/simple-storage). \ No newline at end of file +There is a small example using the Logger middleware [here](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-docs/simple-storage). diff --git a/hs-abci-extra/package.yaml b/hs-abci-extra/package.yaml index 224ff151..48c320e6 100644 --- a/hs-abci-extra/package.yaml +++ b/hs-abci-extra/package.yaml @@ -1,23 +1,16 @@ name: hs-abci-extra version: 0.1.0.0 -github: "https://github.com/f-o-a-m/hs-abci-server" -license: BSD3 -author: "Author name here" -maintainer: "example@example.com" -copyright: "2019 Author name here" +github: "https://github.com/f-o-a-m/kepler/hs-abci-server" +license: Apache +author: "Martin Allen" +maintainer: "martin@foam.space" +copyright: "2020 Martin Allen" extra-source-files: - README.md - ChangeLog.md -# Metadata used when publishing your package -# synopsis: Short description of your package -# category: Web - -# To avoid duplicated efforts in documentation and dealing with the -# complications of embedding Haddock markup inside cabal files, it is -# common to point users to the README.md file. -description: Please see the README on GitHub at +description: Please see the README on GitHub at dependencies: - base >= 4.7 && < 5 diff --git a/hs-abci-sdk/README.md b/hs-abci-sdk/README.md index 7f86b20a..894308fc 100644 --- a/hs-abci-sdk/README.md +++ b/hs-abci-sdk/README.md @@ -1,13 +1,13 @@ # hs-abci-sdk ## Introduction -This package lays out an SDK for rapidly developing blockchain applications in haskell backed by the Tendermint replication engine. It relies on the [hs-abci-server](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-server) to communicate to Tendermint core via the ABCI protocol. +This package lays out an SDK for rapidly developing blockchain applications in haskell backed by the Tendermint replication engine. It relies on the [hs-abci-server](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-server) to communicate to Tendermint core via the ABCI protocol. ## Requirements ### libsecp256k You will need to have the `libsecp256k` `C` library installed on your machine to build this package, or anything depedning on it, as it is not statically linked to its haskell wrapper. You -can find instructions for this [here](https://github.com/f-o-a-m/hs-abci#libsecp256k1). +can find instructions for this [here](https://github.com/f-o-a-m/kepler/tree/master/INSTALL.md#libsecp256k1). ## Architecture @@ -20,7 +20,7 @@ The SDK makes heavy use of an effects system to separate different components of ### Application Specific Effects It is assumed that you will want to define your own application specific effects, for example -in the way that the [Nameservice example app](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-examples/nameservice) does. Application specific effects are useful for defining module level storage capabilities, custom errors and handling, and explicit dependencies on other modules' effects. There are many hooks in this SDK to facilitate compiling application effects +in the way that the [Nameservice example app](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-docs/nameservice) does. Application specific effects are useful for defining module level storage capabilities, custom errors and handling, and explicit dependencies on other modules' effects. There are many hooks in this SDK to facilitate compiling application effects to `BaseApp`. For examples, see `Tendermint.SDK.Errors` or `Tendermint.SDK.Store`. ### Core Effects @@ -31,6 +31,6 @@ a context for executing database transactions, and various buffers and vars to f ## Example Applications There are currenlty two official example applications -1. [Simple Storage](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-examples/simple-storage): This is a trivial application developed around a single module that allows get and set operations on an integer value. +1. [Simple Storage](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-docs/simple-storage): This is a trivial application developed around a single module that allows get and set operations on an integer value. -2. [Nameservice](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-examples/nameservice): This is an implementation of the official example application for the [cosmos-sdk](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice). It is built to support a simple name resolution market place. +2. [Nameservice](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-docs/nameservice): This is an implementation of the official example application for the [cosmos-sdk](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice). It is built to support a simple name resolution market place. diff --git a/hs-abci-sdk/package.yaml b/hs-abci-sdk/package.yaml index d6ca53bd..f8eb57e2 100644 --- a/hs-abci-sdk/package.yaml +++ b/hs-abci-sdk/package.yaml @@ -1,12 +1,12 @@ name: hs-abci-sdk version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-abci-sdk" +github: "f-o-a-m/kepler/hs-abci-sdk" license: Apache author: Martin Allen maintainer: "martin@foam.space" -copyright: "2019 Martin Allen" +copyright: "2020 Martin Allen" -description: Please see the README on GitHub at +description: Please see the README on GitHub at extra-source-files: - protos/**/*.proto diff --git a/hs-abci-server/README.md b/hs-abci-server/README.md index 41f83cea..9ea6bb48 100644 --- a/hs-abci-server/README.md +++ b/hs-abci-server/README.md @@ -1,7 +1,7 @@ # hs-abci-server The `hs-abci-server` package defines the types and methods for serving an ABCI application. See -the [example application](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-example) as a guide for how you can use this package. +the [example application](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-example) as a guide for how you can use this package. ## Application types The application type `App m` is defined as a newtype @@ -39,4 +39,4 @@ type Middleware m = App m -> App m ``` This is useful for hooking in things like metrics, loggers, etc. You can find some out-of-the-box middleware solutions in -the [hs-abci-extra](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-extra) package. +the [hs-abci-extra](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-extra) package. diff --git a/hs-abci-server/package.yaml b/hs-abci-server/package.yaml index 802b70c6..6c86099a 100644 --- a/hs-abci-server/package.yaml +++ b/hs-abci-server/package.yaml @@ -1,12 +1,12 @@ name: hs-abci-server version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-abci-server" +github: "f-o-a-m/kepler/hs-abci-server" license: Apache author: "Martin Allen" maintainer: "martin@foam.space" -copyright: "2019 Martin Allen" +copyright: "2020 Martin Allen" -description: Please see the README on GitHub at +description: Please see the README on GitHub at default-extensions: - NamedFieldPuns diff --git a/hs-abci-test-utils/package.yaml b/hs-abci-test-utils/package.yaml index b3486172..aaeb5f0f 100644 --- a/hs-abci-test-utils/package.yaml +++ b/hs-abci-test-utils/package.yaml @@ -1,22 +1,15 @@ name: hs-abci-test-utils version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-abci-test-utils" -license: BSD3 -author: "Author name here" -maintainer: "example@example.com" -copyright: "2019 Author name here" +github: "f-o-a-m/kepler/hs-abci-test-utils" +license: Apache +author: "Martin Allen" +maintainer: "martin@foam.space" +copyright: "2020 Martin Allen" extra-source-files: - README.md -# Metadata used when publishing your package -# synopsis: Short description of your package -# category: Web - -# To avoid duplicated efforts in documentation and dealing with the -# complications of embedding Haddock markup inside cabal files, it is -# common to point users to the README.md file. -description: Please see the README on GitHub at +description: Please see the README on GitHub at default-extensions: - DataKinds diff --git a/hs-abci-types/README.md b/hs-abci-types/README.md index b5166717..a4ff944e 100644 --- a/hs-abci-types/README.md +++ b/hs-abci-types/README.md @@ -2,9 +2,8 @@ This module provides haskell bindings for the Tendermint ABCI message types defined in [tendermint/tendermint/abci/types/types.proto](https://github.com/tendermint/tendermint/blob/v0.32.2/abci/types/types.proto#L3). - ## Under the hood -We use [proto-lens](https://github.com/google/proto-lens) to generate all the types from files in the [protos](https://github.com/f-o-a-m/hs-abci/tree/master/hs-abci-types/protos) directory, but the generated code is a bit brutal to use directly. This package defines a more user friendly version using Control.Lens.Wrapped. This way we still use proto-lens for encoding/decoding protocol messages while users can work with nicer types defined here. +We use [proto-lens](https://github.com/google/proto-lens) to generate all the types from files in the [protos](https://github.com/f-o-a-m/kepler/tree/master/hs-abci-types/protos) directory, but the generated code is a bit brutal to use directly. This package defines a more user friendly version using Control.Lens.Wrapped. This way we still use proto-lens for encoding/decoding protocol messages while users can work with nicer types defined here. ## JSON Again, Tendermint protocol messages are defined with protobuf files and use protobuf codecs. However, we still supply `ToJSON`/`FromJSON` instances of the types for communicating with tendermint json-rpc server and because they are generally useful. diff --git a/hs-abci-types/package.yaml b/hs-abci-types/package.yaml index 8cec6e5c..ffd03e8b 100644 --- a/hs-abci-types/package.yaml +++ b/hs-abci-types/package.yaml @@ -1,15 +1,15 @@ name: hs-abci-types version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-abci-types" +github: "f-o-a-m/kepler//hs-abci-types" license: Apache author: "Martin Allen" maintainer: "martin@foam.space" -copyright: "2019 Martin Allen" +copyright: "2020 Martin Allen" extra-source-files: - protos/**/*.proto -description: Please see the README on GitHub at +description: Please see the README on GitHub at custom-setup: dependencies: diff --git a/hs-iavl-client/package.yaml b/hs-iavl-client/package.yaml index e2f32258..bbb2149a 100644 --- a/hs-iavl-client/package.yaml +++ b/hs-iavl-client/package.yaml @@ -1,15 +1,15 @@ name: hs-iavl-client version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-iavl-client" +github: "f-o-a-m/kepler/hs-iavl-client" license: Apache author: "Martin Allen" maintainer: "martin@foam.space" -copyright: "2019 Martin Allen" +copyright: "2020 Martin Allen" extra-source-files: - protos/**/*.proto -description: Please see the README on GitHub at +description: Please see the README on GitHub at custom-setup: dependencies: diff --git a/hs-tendermint-client/package.yaml b/hs-tendermint-client/package.yaml index 08df8389..c904a58e 100644 --- a/hs-tendermint-client/package.yaml +++ b/hs-tendermint-client/package.yaml @@ -1,19 +1,12 @@ name: hs-tendermint-client version: 0.1.0.0 -github: "f-o-a-m/hs-abci/hs-tendermint-client" -license: BSD3 -author: "Author name here" -maintainer: "example@example.com" -copyright: "2019 Author name here" +github: "f-o-a-m/kepler/hs-tendermint-client" +license: Apache +author: "Martin Allen" +maintainer: "martin@foam.spacem" +copyright: "2020 FOAM" -# Metadata used when publishing your package -# synopsis: Short description of your package -# category: Web - -# To avoid duplicated efforts in documentation and dealing with the -# complications of embedding Haddock markup inside cabal files, it is -# common to point users to the README.md file. -description: Please see the README on GitHub at +description: Please see the README on GitHub at default-extensions: - NamedFieldPuns