Deployment

.travis.yml

@@ -0,0 +1,25 @@
+matrix:
+  include:
+    - language: go
+      go: 1.13.1
+      env:
+        - GO111MODULE=on
+      before_script:
+        - cd golang
+        - curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh| sh -s -- -b $(go env GOPATH)/bin v1.20.0
+        - make install
+      script:
+        - make lint
+        - go test ./x/relay/keeper
+        - go test ./x/relay/types
+        - go test -mod=readonly  `go list ./cli_test/...`
+
+    - language: node_js
+      node_js: 10.14.2
+      before_script:
+        - cd solidity
+        - npm install -g truffle
+        - npm install
+      script:
+        - npm run lint
+        - npm run test

README.md

@@ -4,8 +4,8 @@ This is a Bitcoin Relay. It uses 1 + 1/n slots per header relayed (n is
 currently 4), and 2 slots to externalize useful information (best chain tip and
 best shared ancestor of latest reorg).
 
-At present, only a Solidity implementation is available, but we intend to add
-more implementations soon :)
+Implementations are available in Solidity (for EVM chains) and Golang using the
+cosmos-sdk framework.
 
 ### How does it work?
 
@@ -43,11 +43,8 @@ reducing calldata gas costs.
 
 ### Project Notes
 
-The Python relay mainter in `./relay/` is not thoroughly tested, and does not
-yet support the cosmos-sdk relay.
+Complete relays are available in Solidity, for EVM-based chains (like Ethereum)
+and Golang using the cosmos-sdk framework.
 
-### How do I develop for it?
-
-install `pipenv` and `pyenv`
-
-$ pipenv install --python=$(pyenv which python3.7)
+The Python relay mainter in `./maintainer/` is not thoroughly tested, and does
+not yet support the cosmos-sdk relay.

golang/.gitignore

@@ -0,0 +1,3 @@
+*.test
+
+/x/relay/keeper/coverage.out

golang/EXTENDING.md

@@ -0,0 +1,110 @@
+## Adding new functionality
+
+This is a cosmos-sdk module. It can be extended with new messages and/or
+queries. Generally, this module is feature-complete, and should not be
+extended. The main exception is the WIP hooks system on proof validation. All
+other functionality should likely be put into a separate module.
+
+### Integrating with other modules
+
+The relay keeper keeps a reference to an object that implements the following
+interface (found in `x/types/types.go`).
+
+```go
+type ProofHandler interface {
+	HandleValidProof(ctx sdk.Context, filled FilledRequests, requests []ProofRequest)
+}
+```
+
+The `FilledRequests` struct contains an `SPVProof` and supporting information
+about the transaction that fulfills the request.
+It can be found in `x/types/validator.go`. `requests []ProofRequest` is a slice
+of `ProofRequest`s that have been filled.
+
+When the keeper validates a proof, it will call the `HandleValidProof` function
+with the valid `FilledRequests` struct and the `ProofRequests` that have been
+filled.
+
+First, instantiate a `handler` that fulfills the `ProofHandler` interface. Then
+add an instance of `relay.Keeper` to your app in `app.go`. It can be
+instantiated as follows:
+
+```go
+handler = types.NewNullHandler()  // or your preferred handler
+
+app.relayKeeper = relay.NewKeeper(
+  keys[relay.StoreKey],
+  app.cdc,
+  true,
+  handler
+)
+```
+
+After that, the relay can be accessed via the Keeper's public interface.
+
+### Extending this module
+
+In order to extend this module, follow these steps:
+
+## How to add a view function (queries)
+1. Add necessary getter(s) in `x/relay/keeper/keeper.go`
+1. Add response type to `x/relay/types/querier.go`
+    1. Add new string tag for the new query
+    1. Response type is a struct with the return values
+    1. Implement `String()` for the response type
+1. Add function to querier `x/relay/keeper/querier.go`
+    1. Add new `query___` function
+    1. Add new case block to `switch` in `NewQuerier()`
+1. Add to CLI  
+    1. add to `x/relay/client/cli/query.go`
+      1. `func GetCmd______`
+      1. returns a `cobra.Command` object
+      1. define `Use` `Example` `Short` `Long` `Args` and `RunE`
+      1. `RunE` parses args, returns errors, and calls `cliCtx.QueryWithData`
+      1. parses the output and returns it with `cliCtx.PrintOutput`
+1. Add to REST
+    1. add to `x/relay/client/rest/query.go`
+    1. new function `_____Handler`
+      1. parse args and build structs
+      1. cliCtx.QueryWithData
+      1. return errors with `rest.WriteErrorResponse`
+      1. return query result with `rest.PostProcessResponse`
+    1. add GET route to `x/relay/client/rest/rest.go`
+      1. new `s.HandleFunc` with the route and arguments
+      1. `.Methods("GET")`
+      1. duplicate for optional args (see `isancestor` for example)
+
+
+## How to add a non-view function (messages)
+1. Add necessary getters/setters in `x/relay/keeper/keeper.go`
+1. Add msg type in `x/relay/types/msgs.go`
+    1. Message type is a struct with the arguments
+    1. Implement `New___()`
+    1. Implement `GetSigners()` <--- Ask me about this later
+    1. Implement `Type()`
+    1. Implement `ValidateBasic()`
+    1. Implement `GetSignBytes()`
+    1. Implement `Route()`
+1. Add to handler
+    1. Add new `handle____` function
+    1. Add new case block to `switch` in `NewHandler()`
+1. Add aliases in `x/relay/alias.go`
+    1. Add alias in `var` block
+    1. Add alias in `type` block
+1. Add to CLI  
+    1. add to `x/relay/client/cli/tx.go`
+      1. `func GetCmd______`
+      1. returns a `cobra.Command` object
+      1. define `Use` `Example` `Short` `Long` `Args` and `RunE`
+      1. `RunE` parses args, returns errors, and calls `utils.GenerateOrBroadcastMsgs`
+1. Add to REST
+    1. add to `x/relay/client/rest/tx.go`
+      1. new http request struct `______Req`
+        1. `BaseReq` + the struct from `x/relay/types/msgs.go`
+      1. new function `_____Handler`
+        1. parse args and build structs
+        1. return errors with `rest.WriteErrorResponse`
+        1. make the tx with `utils.WriteGenerateStdTxResponse`
+    1. add POST route to `x/relay/client/rest/rest.go`
+      1. new `s.HandleFunc` with the route and arguments
+      1. `.Methods("POST")`

golang/Makefile

@@ -0,0 +1,33 @@
+PACKAGES=$(shell go list ./... | grep -v '/simulation')
+
+VERSION := $(shell echo $(shell git describe --tags) | sed 's/^v//')
+COMMIT := $(shell git log -1 --format='%H')
+
+ldflags = -X github.com/cosmos/cosmos-sdk/version.Name=Relay \
+	-X github.com/cosmos/cosmos-sdk/version.ServerName=relayd \
+	-X github.com/cosmos/cosmos-sdk/version.ClientName=relaycli \
+	-X github.com/cosmos/cosmos-sdk/version.Version=$(VERSION) \
+	-X github.com/cosmos/cosmos-sdk/version.Commit=$(COMMIT)
+
+BUILD_FLAGS := -ldflags '$(ldflags)'
+
+all: lint install
+
+install: go.sum
+	go install -mod=readonly $(BUILD_FLAGS) ./cmd/relayd
+	go install -mod=readonly $(BUILD_FLAGS) ./cmd/relaycli
+
+go.sum: go.mod
+	@echo "--> Ensure dependencies have not been modified"
+	GO111MODULE=on go mod verify
+
+lint:
+	golangci-lint run
+	@find . -name '*.go' -type f -not -path "./vendor*" -not -path "*.git*" | xargs gofmt -d -s
+	go mod verify
+
+test:
+	@go test -mod=readonly $(PACKAGES)
+
+init:
+	./scripts/init_chain.sh

golang/README.md

@@ -0,0 +1,114 @@
+## cosmos-sdk Bitcoin Relay
+
+This is a full-featured Bitcoin relay module for cosmos-sdk chains. It indexes
+Bitcoin headers, provides information about the latest-known state of the
+Bitcoin chain, and validates SPV Proofs against its view of the chain. It is a
+critical component for many Cosmos applications to interact with Bitcoin.
+
+For more information about the relay's architecture see the `README.md` in the
+repo's root directory.
+
+## Building the daemon and cli
+
+```sh
+$ make
+# To additionally install them in your `$GOPATH/bin` directory:
+$ make install
+```
+
+## Running tests
+
+Run the unit tests as follows:
+
+```sh
+$ go test ./x/...
+```
+
+See the README in `./cli_test` for instructions on running the integration
+tests.
+
+Instructions for setting up manual testing can be found in the README in
+`./scripts`.
+
+## Project Status
+
+- [X] Milestone 1
+- [X] Milestone 2
+- - [X] Expose best-known digest
+- - [X] Expose LCA of reorg
+- - [X] Follow API of existing Solidity Relay
+- - [X] Validate SPV Proofs
+- - [X] `ProvideProof` message
+- [ ] Milestone 3
+- - [X] Provide tooling for manual testing (scripts, docs, json test files)
+- - [X] Integration Tests
+- - [ ] Document relay design & architecture
+- - [X] Document public interface
+- - [X] Provide hooks to execute tasks + dispatch messages
+- - [ ] Add a basic web dashboard with Relay health
+
+
+## API
+
+Cosmos modules expose messages, which modify state, and queries, which read
+state.
+
+### Queries
+
+Queries are available via CLI or REST. For more information, see the
+descriptions in the CLI.
+
+| Query | Description |
+| ----- | ----------- |
+| IsAncestor | Deteremine if a block is an ancestor of another |
+| GetRelayGenesis | Get the trusted root of the relay |
+| GetLastReorgLCA | Get the LCA of the latest reorg |
+| GetLastReorgLCA | Get the best digest known to the relay |
+| FindAncestor | Find the nth ancestor of a block|
+| IsMostRecentCommonAncestor | Determine if a block is the LCA of two headers|
+| HeaviestFromAncestor | Check which of two descendents is heaviest from the LCA |
+| GetRequest | Get details of an SPV Proof Request|
+| CheckProof | Check the syntactic validity of an SPV Proof |
+| CheckRequests | Perform CheckProof and check the SPV Proof against a set of Requests |
+
+### Messages
+
+Messages are available via CLI or REST. For more information, see the
+descriptions in the CLI.
+
+| Message | Description |
+| ------- | ----------- |
+| IngestHeaderChain | Add a chain of headers to the relay |
+| IngestDifficultyChange | Add a chain of headers to the relay with a difficulty change|
+| MarkNewHeaviest | Mark a new best-known chain tip |
+| NewRequest | Register a new SPV Proof request |
+| ProvideProof | Provide a proof that satisfies 1 or more requests |
+
+## Project Overview
+
+### Keeper
+High-level overview of the project structure within the `keeper` file.
+
+#### Keeper.go
+Instantiates a `keeper` (what handles interaction with the store and contains most of the core functionality of the module). It also handles the genesis state for the relay.
+
+#### Headers.go
+Handles the storage and validation of Bitcoin Headers and Header Chains.
+
+#### Chain.go
+Checks and updates information about the chain.  Provides functionality to ensure we are using the heaviest chain.
+
+#### Links.go
+Sets and retrieves data about each link in the chain.  This is most commonly used to check information about ancestors.
+
+#### Requests.go
+Stores, retrieves, and validates requests.
+
+#### Validator.go
+Contains validation functions.  Currently, this can validate SPV Proofs and Requests.
+
+#### Handler.go
+Handles messages.
+
+#### Querier.go
+Handles queries.

golang/cli_test/README.md

@@ -0,0 +1,56 @@
+# Relay CLI Integration tests
+
+The relay cli integration tests live in this folder. You can run the full suite by running:
+
+```bash
+go test -mod=readonly -p 4 `go list ./cli_test/...`
+```
+
+ To run a single test run:
+ ```bash
+ go test -mod=readonly -p 4 `go list ./cli_test/...` -testify.m TestName
+ ```
+
+> NOTE: While the full suite runs in parallel, some of the tests can take up to a minute to complete
+
+### Test Structure
+
+This integration suite [uses a thin wrapper](https://godoc.org/github.com/cosmos/cosmos-sdk/tests) over the [`os/exec`](https://golang.org/pkg/os/exec/) package. This allows the integration test to run against built binaries (both `relayd` and `relaycli` are used) while being written in golang. This allows tests to take advantage of the various golang code we have for operations like marshal/unmarshal, crypto, etc...
+
+> NOTE: The tests will use whatever `relayd` or `relaycli` binaries are available in your `$GOPATH/bin`. You can check which binary will be run by the suite by running `which relayd` or `which relaycli`. If you have your `$GOPATH` properly setup they should be in `$GOPATH/bin/relay*`. This will ensure that your test uses the latest binary you have built
+
+Tests generally follow this structure:
+
+```go
+func (suite *UtilsSuite)  TestMyNewCommand() {
+    suite.T().Parallel()
+    f := InitFixtures(suite.T())
+
+    // start relayd server
+    proc := f.GDStart()
+    defer proc.Stop(false)
+
+    // Your test code goes here...
+
+    f.Cleanup()
+}
+```
+
+This boilerplate above:
+
+- Ensures the tests run in parallel. Because the tests are calling out to `os/exec` for many operations these tests can take a long time to run.
+- Creates `.relayd` and `.relaycli` folders in a new temp folder.
+- Uses `relaycli` to create test account for use in testing: `foo`
+- Creates a genesis file with coins (`1000footoken,1000feetoken,150stake`) controlled by the `foo` key
+- Generates an initial bonding transaction (`gentx`) to make the `foo` key a validator at genesis
+- Starts `relayd` and stops it once the test exits
+- Cleans up test state on a successful run
+
+### Notes when adding/running tests
+
+- Because the tests run against a built binary, you should make sure you build every time the code changes and you want to test again, otherwise you will be testing against an older version. If you are adding new tests this can easily lead to confusing test results.
+- The [`test_helpers.go`](./test_helpers.go) file is organized according to the format of `relaycli` and `relayd` commands. There are comments with section headers describing the different areas. Helper functions to call CLI functionality are generally named after the command (e.g. `relaycli query bestknowndigest` would be `QueryBestKnownDigest`). Try to keep functions grouped by their position in the command tree.
+- Test state that is needed by `tx` and `query` commands (`home`, `chain_id`, etc...) is stored on the `Fixtures` object. This makes constructing your new tests almost trivial. Each test needs unique Fixture to run in parallel
+- Sometimes if you exit a test early there can be still running `relayd` and `relaycli` processes that will interrupt subsequent runs. Still running `relayd` processes will block ports and prevent new tests from spinning up. You can ensure new tests spin up clean by running `pkill -9 relayd && pkill -9 relaycli` before each test run.
+- Most `query` and `tx` commands take a variadic `flags` argument. This pattern allows for the creation of a general function which is easily modified by adding flags.
+- `Tx*` functions follow a general pattern and return `(success bool, stdout string, stderr string)`. This allows for easy testing of multiple different flag configurations.