Updated documentation

Author: pcppcp

.circleci/Makefile

@@ -0,0 +1,3 @@
+build:
+	docker build . -f images/ubuntu_1804/Dockerfile -t anyledger/base
+	docker build . -f images/develop/Dockerfile -t anyledger/develop

.circleci/download_solc.sh

@@ -2,8 +2,8 @@
 
 set -e
 set -x
-SOLC_URL_LINUX='https://github.com/ethereum/solidity/releases/download/v0.4.23/solc-static-linux'
-SOLC_VERSION='v0.4.23'
+SOLC_VERSION='v0.5.10'
+SOLC_URL_LINUX="https://github.com/ethereum/solidity/releases/download/${SOLC_VERSION}/solc-static-linux"
 
 fail() {
     if [[ $- == *i* ]]; then

.circleci/images/develop/Dockerfile

@@ -0,0 +1,11 @@
+#
+# dockerfile for "developer" image
+#
+FROM anyledger/base:latest
+
+WORKDIR /home/circleci
+ENV HOME /home/circleci
+
+COPY build_zephyr_nrf52840_pca10056.sh /home/circleci
+RUN chmod +x build_zephyr_nrf52840_pca10056.sh
+RUN ./build_zephyr_nrf52840_pca10056.sh

BUILD-qemu.md

@@ -27,7 +27,7 @@ This document describes how to start `anyledger-wallet` project using a QEMU vir
 
 2) build the wallet
 
-`$ mkdir build && cd build && cmake -GNinja  -DBOARD=qemu_x86 -DBUILD_XCOMPILE=1 ../ && ninja`
+`$ mkdir build && cd build && cmake -GNinja  -DBOARD=qemu_x86 -DBUILD_XCOMPILE=1 ../examples/wallet && ninja`
 
 ## part three: play with the wallet
 1) run the emulator (the wallet prompt should appear immediately)

README.md

@@ -53,13 +53,14 @@ A working `solc` should be available in your `$PATH`. See the [Installation inst
 
 ### x86 build
 
-This build is used to develop and test the wallet library on your desktop.
+This build is used to develop and test the wallet library on your desktop. It does not include any working application - its purpose is to provide a compileable framework
+for unit testing of the individual components on POSIX system. You should always start with this build if you plan to do any changes to the core components.
 
 1) clone wallet repo
 `git clone [email protected]:AnyLedger/anyledger-wallet.git && cd anyledger-wallet`
 
 2) create build directory and generate build targets
-`mkdir build && cd build && cmake -GNinja ../`
+`mkdir build && cd build && cmake -GNinja ../examples/tests`
 
 3) compile the library & run the tests
 `ninja && ctest`
@@ -69,15 +70,29 @@ This build is used to develop and test the wallet library on your desktop.
 Prerequisites: a working zephyr SDK (at least v0.9.5), see [here](https://docs.zephyrproject.org/latest/getting_started/getting_started.html) for instructions. 
 Please make sure you can compile and flash at least blinky example before building the wallet.
 
+Before using the actual hardware, you will probably want to test the functionality using the zephyr's QEMU image. (Use `-DBOARD=x86_qemu` when running `cmake`)
+
 1) clone wallet repo to the zephyr's `samples` directory
 `mkdir samples/anyledger/ && git clone [email protected]:AnyLedger/anyledger-wallet.git`
 
 2) create build directory and generate build targets
-`cd samples/anyledger/anyledger-wallet/build && cmake -GNinja  -DBOARD=nrf52840_pca10056 -DBUILD_XCOMPILE=1  ../`
+`mkdir -p samples/anyledger/anyledger-wallet/build && cd samples/anyledger/anyledger-wallet/build && cmake -GNinja  -DBOARD=nrf52840_pca10056 -DBUILD_XCOMPILE=1  ../examples/wallet`
 
-3) compile & flash the firmware
+3) for hardware builds, compile & flash the firmware
 `ninja && ninja flash`
 
 ## Using AnyLedger wallet
 
 To start AnyLedger wallet using a QEMU virtual machine, [see here](https://github.com/AnyLedger/anyledger-wallet/blob/master/BUILD-qemu.md).
+
+## Project structure
+
+- `abi_compiler` - python tool for compiling Ethereum ABI definition into a C code
+- `eth` - ethereum transaction utilities
+- `utils` - string manipulation, JSON en+de-coding, run-length encoding, uint256 manipulators
+- `examples` - examples of the actual apps
+- `sawtooth` - Hyperledger sawtooth utilities
+- `thirdparty` - CMakeFiles for 3rd party modules
+- `tools` - random helper scripts
+- `wallet` - MacOs compatibility hack
+- `zephyr-wallet` - Zephyr-specific code for the AnyLedger wallet

eth/address.h

@@ -12,7 +12,11 @@ extern "C" {
 typedef struct {
     uint8_t a[20];
 } address_t;
+
+// ETH privkey to address conversion
 int privkey_to_ethereum_address(const uint8_t *privkey, address_t *addr_out);
+
+// derive address from a signature (ecrecover)
 int address_from_signature(const uint8_t *data, size_t data_len, const signature_t *signature, address_t *addr_out);
 
 #ifdef __cplusplus

eth/sign.h

@@ -17,10 +17,21 @@ typedef struct {
     uint8_t v;
 } signature_t;
 
-// signature is 32 bytes
+// sign a data using provided @privkey
+// @param privkey: privkey to use
+// @param data: data to sign
+// @param data_len: length of the data
+// @param signature: signature is stored here. The parameter must have size of at least 65 bytes
 int eth_sign(const uint8_t *privkey, const uint8_t *data, size_t data_len, uint8_t *signature);
+// create a keccak256 digest of a data
+// @param data: data to digest
+// @param data_len: length of the data
+// @param digest: digest is stored here. The parameter must have size of at least 32 bytes.
 int eth_digest_message(const uint8_t *data, size_t data_len, uint8_t *digest);
+
+// sign keccak256(data). the signature parameter must have size of at least 65 bytes.
 int eth_sign_data_rawsig(const uint8_t *privkey, const uint8_t *data, size_t data_len, uint8_t *signature);
+// sign keccak256(data) and store the signature as r, v, s values
 int eth_sign_data(const uint8_t *privkey, const uint8_t *data, size_t data_len, signature_t *out);
 
 int privkey_to_pubkey(const uint8_t *privkey, uint8_t *pubkey);

eth/transaction.h

@@ -16,6 +16,7 @@ extern "C" {
 #endif
 #define SIGNATURE_LENGTH 64
 
+// a generic ethereum transaction
 typedef struct {
     uint32_t nonce;
     uint32_t gas_price;
@@ -26,20 +27,27 @@ typedef struct {
     size_t data_len;
 } transaction_t;
 
+// ethereum transaction hash
 typedef struct {
     uint8_t h[32];
 } tx_hash_t;
 
+// basic transaction receipt
 typedef struct {
     uint64_t blockNumber;
     uint8_t status;
 } tx_receipt_t;
 
+// set 'to' parameter of the transaction
+// @param to_hex: ASCII-encoded address
 int tx_set_to(transaction_t *tx, const char *to_hex);
+// set 'value' parameter of the transaction (64bit)
+// @param val: value
 void tx_set_value_u64(transaction_t *tx, uint64_t val);
 
+// encode an ethereum transaction and store result in the buffer
 int tx_encode(const transaction_t *tx, const signature_t *sig, uint8_t *buf, size_t buf_size);
-// create pre-EIP155 tx
+// create pre-EIP155 signed tx
 int tx_encode_sign(const transaction_t *tx, const uint8_t *privkey, uint8_t *buf, size_t buf_size);
 
 

eth/web3.h

@@ -11,16 +11,22 @@
 extern "C" {
 #endif
 
+// Module that generates JSON-RPC strings for querying the state of an ethereum network
+
 typedef struct {
     uint8_t *buf;
     size_t buf_size;
     size_t buf_used;
     uint32_t req_id;
 } web3_ctx_t;
 
+// initialize the web3 module
+// @param web3: web3 context to use
+// @param buf: buffer to use for the outgoing requests
+// @param buf_size: buffer size
 void web3_init(web3_ctx_t *web3, uint8_t *buf, size_t buf_size);
 
-// what to filter out when assembling tx JSON
+// tx flags: what to filter out when assembling tx JSON
 #define TX_NO_FROM      1 << 0
 #define TX_NO_GAS       1 << 1
 #define TX_NO_GASPRICE  1 << 2

eth/web3_jsonp.h

@@ -12,6 +12,8 @@
 extern "C" {
 #endif
 
+// JSON-RPC reply decoder
+
 typedef struct {
     long code;
     const char *message;
@@ -22,7 +24,9 @@ typedef struct {
     jsonrpc_error_t error;
 } jsonrpc_result_t;
 
+// decode 'hexencoded' result (i.e. result of a eth_blockNumber call)
 int jsonrpc_decode_hexencoded(uint8_t *buf, size_t buf_size, jsonrpc_result_t *result, uint256_t *out);
+// decode transaction receipt
 int jsonrpc_decode_txreceipt(uint8_t *buf, size_t buf_size, jsonrpc_result_t *result, tx_receipt_t *out);
 
 #ifdef __cplusplus