Updated documentation

.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/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

requirements.txt

@@ -1,4 +1,4 @@
 web3
-eth_abi
 eth_utils
 click
+protobuf

wallet/wallet.c

@@ -1,5 +1,5 @@
 // hotfix for MACOS wallet library build
-// at least one source is required to build archives together
+// at least one source is required to build an archive
 
 void empty_function()
 {

zephyr-wallet/compat.h

@@ -7,6 +7,9 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// to provide rand() function for the trezor-library
+// note: this function is actually not used anywhere at the moment
 int rand();
 
 #ifdef __cplusplus

zephyr-wallet/config.h

@@ -1,7 +1,6 @@
 /*
- * Copyright (c) 2017 Intel Corporation
- *
  * SPDX-License-Identifier: Apache-2.0
+ * Zephyr configuration
  */
 
 #define APP_REQ_TIMEOUT K_SECONDS(10)
@@ -19,6 +18,7 @@
 #define SERVER_ADDR CONFIG_NET_CONFIG_PEER_IPV4_ADDR
 #endif
 
+// LWM2M settings
 #define CLIENT_MANUFACTURER	    "AnyLedger"
 #define CLIENT_MODEL_NUMBER	    "AnyLedger Wallet 0.1"
 #define CLIENT_SERIAL_NUMBER	"0001"

zephyr-wallet/erc20_shell.h

@@ -7,6 +7,8 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// Shell module for ERC20 token functionality
 void erc20_shell_register();
 
 #ifdef __cplusplus

zephyr-wallet/http_utils.h

@@ -7,12 +7,18 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// helper functions for the http service
+
+// callback for HTTP replies
 void http_received(struct http_ctx *ctx,
 			  struct net_pkt *pkt,
 			  int status,
 			  u32_t flags,
 			  const struct sockaddr *dst,
 			  void *user_data);
+
+// do a synchronous HTTP request
 int do_sync_http_req(struct http_ctx *ctx,
 			    enum http_method method,
 			    const char  *url,

zephyr-wallet/sensor_service.h

@@ -9,6 +9,8 @@
 extern "C" {
 #endif
 
+// shell utilities for the DHT sensor queries
+
 void sensor_shell_register();
 int get_sensor_data(int32_t *temperature, int32_t *humidity);
 

zephyr-wallet/shell_modules.h

@@ -8,6 +8,8 @@
 extern "C" {
 #endif
 
+// call this to register all AL shell modules
+
 void wallet_register_shell_modules();
 
 #ifdef __cplusplus

zephyr-wallet/sntp_shell.h

@@ -7,6 +7,8 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// NTP queries from the shell
 void sntp_shell_register();
 
 #ifdef __cplusplus

zephyr-wallet/upload.h

@@ -7,6 +7,8 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// shell module for data-to-chain uploader service
 void upload_shell_register();
 
 #ifdef __cplusplus

zephyr-wallet/utils.h

@@ -17,13 +17,18 @@ extern "C" {
 #define FMT_FIXED           1 << 0   // use fixed integer length (0 is used as a prefix)
 #define FMT_NO_TRAIL_ZERO   1 << 1   // remove trailing zeros
 
+// printk() helpers
+// hex-encoded data
 void printk_hex(const struct shell *shell, const uint8_t *data, size_t data_len);
 #define printk_hex_nl(shell, data, len) printk_hex(shell, data, len); shell_fprintf(shell, SHELL_NORMAL, "\n");
+// uint256
 void printk_uint256(const struct shell *shell, const uint256_t *v);
+// uint256 as fixed point int
 void printk_uint256_int(const struct shell *shell, const uint256_t *v, uint8_t decimals, uint8_t fmt);
+void shell_print_decimal_u256(const struct shell *shell, const uint256_t *val, uint8_t decimals);
 
+// read uint64_t from a ascii buffer
 int shell_get_uint64(const char *argval, uint64_t *out);
-void shell_print_decimal_u256(const struct shell *shell, const uint256_t *val, uint8_t decimals);
 #ifdef __cplusplus
 }
 #endif

zephyr-wallet/wallet.h

@@ -10,6 +10,8 @@
 extern "C" {
 #endif
 
+// wallet manipulation functions
+
 typedef struct {
     uint8_t k[32];
 } privkey_t;

zephyr-wallet/web3_shell.h

@@ -7,6 +7,9 @@
 #ifdef  __cplusplus
 extern "C" {
 #endif
+
+// shell module for calling web3 JSON-RPC
+
 void web3_shell_register();
 
 #ifdef __cplusplus