From 006d6d6bdf7dd371ac4b35a73379dff8428ea17a Mon Sep 17 00:00:00 2001 From: Martin Klepsch Date: Tue, 20 Mar 2018 13:58:53 +0100 Subject: [PATCH] update contract building docs + add decision record --- README.md | 25 +++-------- contracts/README.md | 31 ++++++++++++++ build_contracts.sh => contracts/build.sh | 0 ...include-compiled-web3j-contracts-in-git.md | 42 +++++++++++++++++++ project.clj | 9 +--- 5 files changed, 79 insertions(+), 28 deletions(-) create mode 100644 contracts/README.md rename build_contracts.sh => contracts/build.sh (100%) create mode 100644 doc/decisions/0003-include-compiled-web3j-contracts-in-git.md diff --git a/README.md b/README.md index ced4f88..8266b37 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ The `develop` branch is automatically deployed here. - [Prerequisites](#prerequisites) - [Application config](#application-config) - [GitHub integration](#github-integration) +- [Contracts](#contracts) - [Running](#running) - [Testing](#testing) - [More info](#more-info) @@ -37,26 +38,6 @@ psql postgres -c "CREATE USER commiteth WITH PASSWORD 'commiteth';" psql postgres -c "CREATE DATABASE commiteth;" ``` -### solc - -Solidity compiler [0.4.15](https://github.com/ethereum/solidity/releases/tag/v0.4.15) is required and needs to be in $PATH. -Detailed [installation instructions for various platforms](https://solidity.readthedocs.io/en/develop/installing-solidity.html) can be found in the official Solidity documentation. - -``` -brew install https://raw.githubusercontent.com/ethereum/homebrew-ethereum/de1da16f7972a899fc8dd1f3f04299eced6f4312/solidity.rb -brew pin solidity -``` - -### web3j - -Web3j [2.3.0](https://github.com/web3j/web3j/releases/tag/v2.3.0) is required and the command line tools need to be in $PATH. -Installation instructions for the command line tools can be found in the [Web3j Command Line Tools documentation](https://docs.web3j.io/command_line.html). - -``` -brew install https://raw.githubusercontent.com/web3j/homebrew-web3j/881cf369b551a5f2557bd8fb02fa8b7b970256ca/web3j.rb -brew pin web3j -``` - ## Application config Make sure to create `/config-dev.edn` and populate it correctly, which is based on `env/dev/resources/config.edn`. Description of config fields is given below: @@ -91,6 +72,10 @@ Follow the steps [here](https://developer.github.com/apps/building-oauth-apps/cr ### GitHub App Follow the steps [here](https://developer.github.com/apps/building-github-apps/creating-a-github-app/). Be sure to specify `:server-address` + `/webhook-app` as "Webhook URL", and `:webhook-secret` as "Webhook Secret". +## Contracts + +All information related to development of OpenBounty smart contracts can be found in [`contracts/`](/contracts/) + ## Running ### Ethereum node diff --git a/contracts/README.md b/contracts/README.md new file mode 100644 index 0000000..f92dc0e --- /dev/null +++ b/contracts/README.md @@ -0,0 +1,31 @@ +# OpenBounty Contracts + +This directory contains all the underlying smart contracts used by the OpenBounty platform. + +- A script `contracts/build.sh` is part of this repository and can be used to +compile the contracts and copy Java interfaces into `src/java/`. + +In order to run the script the following dependencies have to be met: + +- [solc](#solc) +- [web3j](#web3j) + +### solc + +Solidity compiler [0.4.15](https://github.com/ethereum/solidity/releases/tag/v0.4.15) is required and needs to be in $PATH. +Detailed [installation instructions for various platforms](https://solidity.readthedocs.io/en/develop/installing-solidity.html) can be found in the official Solidity documentation. + +``` +brew install https://raw.githubusercontent.com/ethereum/homebrew-ethereum/de1da16f7972a899fc8dd1f3f04299eced6f4312/solidity.rb +brew pin solidity +``` + +### web3j + +Web3j [2.3.0](https://github.com/web3j/web3j/releases/tag/v2.3.0) is required and the command line tools need to be in $PATH. +Installation instructions for the command line tools can be found in the [Web3j Command Line Tools documentation](https://docs.web3j.io/command_line.html). + +``` +brew install https://raw.githubusercontent.com/web3j/homebrew-web3j/881cf369b551a5f2557bd8fb02fa8b7b970256ca/web3j.rb +brew pin web3j +``` \ No newline at end of file diff --git a/build_contracts.sh b/contracts/build.sh similarity index 100% rename from build_contracts.sh rename to contracts/build.sh diff --git a/doc/decisions/0003-include-compiled-web3j-contracts-in-git.md b/doc/decisions/0003-include-compiled-web3j-contracts-in-git.md new file mode 100644 index 0000000..44ca86e --- /dev/null +++ b/doc/decisions/0003-include-compiled-web3j-contracts-in-git.md @@ -0,0 +1,42 @@ +# 0003. Include Compiled Web3j Contracts in Git + +| Date | Tags | +|---|---| +| 2018-03-20 | contracts, tooling | + + +## Status + +Accepted + +## Context + +The OpenBounty project utilizes smart contracts to make certain core +aspects of it's product work without centralized trust. + +In order to develop the platform a Java interface to these contracts needs to +be built beforehand. To create those interfaces various tools are required +(`web3j` & `solc`), often in specific versions that are not easily available +via widespread package managers. + +This hurdle also applies to any other situations where the application is set +up from scratch, e.g. continuous integration. + +## Decision + +Instead of forcing every contributor to install those tools we will include +the compiled Java interfaces in our Git repository. This removes a significant +setup cost and hopefully allows people to get going much faster. + +Installing `web3j` and `solc` will only be required when hacking on the +contracts itself which are much more stable than the majority of the code. + +An alternative would be implementing scripts that install those tools in a +platform independent manner but this would require more work. Once we have +the time or someone wants to work on creating those scripts we can easily +revert the decision outlined in this document. + +## Consequences + +- The compiled Java interfaces may get out of date. + This could perhaps be addressed by some clever use of checksums. diff --git a/project.clj b/project.clj index d531a19..c4b6de5 100644 --- a/project.clj +++ b/project.clj @@ -66,20 +66,13 @@ :plugins [[lein-cprop "1.0.1"] [migratus-lein "0.4.1"] [lein-cljsbuild "1.1.7"] - [lein-auto "0.1.2"] [lein-less "1.7.5"] - [lein-shell "0.5.0"] [lein-sha-version "0.1.1"]] :less {:source-paths ["src/less"] :target-path "resources/public/css"} - ;; :auto {"build-contracts" {:file-pattern #"\.(sol)\n" - ;; :paths ["./contracts"]}} - - ;; :aliases {"build-contracts" ["shell" "./build_contracts.sh"]} - :ring {:destroy commiteth.scheduler/stop-scheduler} :uberjar-exclusions [#"public/README.md" #"public/cards.html"] @@ -94,7 +87,7 @@ :profiles {:uberjar {:jvm-opts ["-server" "-Dconf=config-prod.edn"] :omit-source true - :prep-tasks [#_"build-contracts" "javac" "compile" ["cljsbuild" "once" "min"] ["less" "once"]] + :prep-tasks ["javac" "compile" ["cljsbuild" "once" "min"] ["less" "once"]] :cljsbuild {:builds {:min