From 5b3a568a07cbb547784ce77617993c5c60607258 Mon Sep 17 00:00:00 2001 From: Jozef Henzl Date: Tue, 25 Jun 2019 20:10:54 +0200 Subject: [PATCH] Updated documentation --- .circleci/Makefile | 3 +++ .circleci/images/develop/Dockerfile | 11 +++++++++++ BUILD-qemu.md | 2 +- README.md | 23 +++++++++++++++++++---- eth/address.h | 4 ++++ eth/sign.h | 13 ++++++++++++- eth/transaction.h | 10 +++++++++- eth/web3.h | 8 +++++++- eth/web3_jsonp.h | 4 ++++ requirements.txt | 2 +- wallet/wallet.c | 2 +- zephyr-wallet/compat.h | 3 +++ zephyr-wallet/config.h | 4 ++-- zephyr-wallet/erc20_shell.h | 2 ++ zephyr-wallet/http_utils.h | 6 ++++++ zephyr-wallet/sensor_service.h | 2 ++ zephyr-wallet/shell_modules.h | 2 ++ zephyr-wallet/sntp_shell.h | 2 ++ zephyr-wallet/upload.h | 2 ++ zephyr-wallet/utils.h | 7 ++++++- zephyr-wallet/wallet.h | 2 ++ zephyr-wallet/web3_shell.h | 3 +++ 22 files changed, 104 insertions(+), 13 deletions(-) create mode 100644 .circleci/Makefile create mode 100644 .circleci/images/develop/Dockerfile diff --git a/.circleci/Makefile b/.circleci/Makefile new file mode 100644 index 0000000..d665824 --- /dev/null +++ b/.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 diff --git a/.circleci/images/develop/Dockerfile b/.circleci/images/develop/Dockerfile new file mode 100644 index 0000000..f4a35a7 --- /dev/null +++ b/.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 diff --git a/BUILD-qemu.md b/BUILD-qemu.md index 655578e..4955ba4 100644 --- a/BUILD-qemu.md +++ b/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) diff --git a/README.md b/README.md index 10ac242..3c7c5fd 100644 --- a/README.md +++ b/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 git@github.com: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 git@github.com: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 diff --git a/eth/address.h b/eth/address.h index 7862e0c..433e633 100644 --- a/eth/address.h +++ b/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 diff --git a/eth/sign.h b/eth/sign.h index 9299574..7280b3f 100644 --- a/eth/sign.h +++ b/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); diff --git a/eth/transaction.h b/eth/transaction.h index b9d2ceb..35c13c8 100644 --- a/eth/transaction.h +++ b/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); diff --git a/eth/web3.h b/eth/web3.h index b402859..c51f3f1 100644 --- a/eth/web3.h +++ b/eth/web3.h @@ -11,6 +11,8 @@ 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; @@ -18,9 +20,13 @@ typedef struct { 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 diff --git a/eth/web3_jsonp.h b/eth/web3_jsonp.h index 2f31062..f6050be 100644 --- a/eth/web3_jsonp.h +++ b/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 diff --git a/requirements.txt b/requirements.txt index b77c01a..3eee9fe 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ web3 -eth_abi eth_utils click +protobuf diff --git a/wallet/wallet.c b/wallet/wallet.c index cdf50f9..455cd10 100644 --- a/wallet/wallet.c +++ b/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() { diff --git a/zephyr-wallet/compat.h b/zephyr-wallet/compat.h index 9172e54..2daeaba 100644 --- a/zephyr-wallet/compat.h +++ b/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 diff --git a/zephyr-wallet/config.h b/zephyr-wallet/config.h index fd8c70f..862078c 100644 --- a/zephyr-wallet/config.h +++ b/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" diff --git a/zephyr-wallet/erc20_shell.h b/zephyr-wallet/erc20_shell.h index f52c980..fa71d54 100644 --- a/zephyr-wallet/erc20_shell.h +++ b/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 diff --git a/zephyr-wallet/http_utils.h b/zephyr-wallet/http_utils.h index c6cde89..092d268 100644 --- a/zephyr-wallet/http_utils.h +++ b/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, diff --git a/zephyr-wallet/sensor_service.h b/zephyr-wallet/sensor_service.h index 74c2d70..2561af1 100644 --- a/zephyr-wallet/sensor_service.h +++ b/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); diff --git a/zephyr-wallet/shell_modules.h b/zephyr-wallet/shell_modules.h index 94a7410..3dc9462 100644 --- a/zephyr-wallet/shell_modules.h +++ b/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 diff --git a/zephyr-wallet/sntp_shell.h b/zephyr-wallet/sntp_shell.h index 293fb63..12131bd 100644 --- a/zephyr-wallet/sntp_shell.h +++ b/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 diff --git a/zephyr-wallet/upload.h b/zephyr-wallet/upload.h index 31933d0..e0cbe32 100644 --- a/zephyr-wallet/upload.h +++ b/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 diff --git a/zephyr-wallet/utils.h b/zephyr-wallet/utils.h index 633a619..03baa36 100644 --- a/zephyr-wallet/utils.h +++ b/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 diff --git a/zephyr-wallet/wallet.h b/zephyr-wallet/wallet.h index 758ce42..3e2c8e5 100644 --- a/zephyr-wallet/wallet.h +++ b/zephyr-wallet/wallet.h @@ -10,6 +10,8 @@ extern "C" { #endif +// wallet manipulation functions + typedef struct { uint8_t k[32]; } privkey_t; diff --git a/zephyr-wallet/web3_shell.h b/zephyr-wallet/web3_shell.h index ce4f9bf..612a4c9 100644 --- a/zephyr-wallet/web3_shell.h +++ b/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