zkPoD-lib

zkPoD-lib is the underlying core library for zkPoD system. It fully implements PoD (proof of delivery) protocol and also provides a CLI interface together with Golang bindings.

zkPoD-lib has four main parts as followed.

pod_setup - Generates public parameters of system
pod_publish - Publish utility to preprocess data and calculate authenticators
pod_core - Core implementations of different zkPoD trading features
pod_go - Golang bindings for pod_setup and pod_core functions

Related zkPoD projects

zkPoD-node Node application written in Golang for sellers (Alice) and buyers (Bob). It deals with communication, smart contract calling, data transferring, and other zkPoD protocol interactions.
zkPoD-contract Smart contracts for zkPoD Decentralized Exchange.

Dependencies

We would recommend Ubuntu 18.04 for convenience. The default GCC on Ubuntu 16.04 is outdated and you may encounter some annoying issues.

GCC 7.3 or above (If you upgrade GCC manually from an old version like GCC5, you should re-install the boost library.)
Go 1.12
Boost 1.69.0 or newer
OpenMP 5.3.1 or newer

# For Ubuntu
sudo apt-get install libomp-dev
sudo apt-get install libcrypto++-dev
sudo apt-get install libboost-all-dev
sudo apt-get install libgmp-dev

# For macOS
brew install libcryptopp
brew install boost
brew install gmp

Build

# Download zkPoD-lib code
mkdir zkPoD && cd zkPoD
git clone https://github.com/sec-bit/zkPoD-lib.git

# Pull libsnark submodule
cd zkPoD-lib
git submodule init && git submodule update
cd depends/libsnark
git submodule init && git submodule update

# Build libsnark
mkdir build && cd build
# - On Ubuntu
cmake -DCMAKE_INSTALL_PREFIX=../../install -DMULTICORE=ON -DWITH_PROCPS=OFF -DWITH_SUPERCOP=OFF -DCURVE=MCL_BN128 ..
# - Or on macOS ref https://github.com/scipr-lab/libsnark/issues/99#issuecomment-367677834
CPPFLAGS=-I/usr/local/opt/openssl/include LDFLAGS=-L/usr/local/opt/openssl/lib PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig cmake -DCMAKE_INSTALL_PREFIX=../../install -DMULTICORE=OFF -DWITH_PROCPS=OFF -DWITH_SUPERCOP=OFF -DCURVE=MCL_BN128 -DUSE_ASM=OFF ..
make && make install

# Build zkPoD-lib
cd ../../..
make

# These files should be generated after successful build.
# pod_setup/pod_setup
# pod_publish/pod_publish
# pod_core/libpod_core.so
# pod_core/pod_core

Usage

pod_setup

$ ./pod_setup -h

command line options:
  -h [ --help ]                         Use -h or --help to list all arguments
  -o [ --output_path ] arg (=zksnark_key)
                                        Provide the output path
  -c [ --count ] arg (=1024)            Provide the count
  -v [ --verbose ] arg (=0)             Enable libff log

Use pod_setup to generate zkPoD zkSNARK public parameters.

./pod_setup

zksnark_key is generated after a successful setup.

pod_publish

$ ./pod_publish -h
command line options:
  -h [ --help ]                         Use -h or --help to list all arguments
  ---d data_dir -m table -f file -o output_dir -t table_type -k keys
                                        publish table file
  ---d data_dir -m plain -f file -o output_dir -c column_num
                                        publish plain file
  -d [ --data_dir ] arg (=.)            Provide the configure file dir
  -m [ --mode ] arg (=plain)            Provide pod mode (plain, table)
  -f [ --publish_file ] arg             Provide the file which want to publish
  -o [ --output_dir ] arg               Provide the publish path
  -t [ --table_type ] arg (=csv)        Provide the publish file type in table
                                        mode (csv)
  -c [ --column_num ] arg (=1023)       Provide the column number per
                                        block(line) in plain mode (default
                                        1023)
  -k [ --vrf_colnum_index ] arg         Provide the publish file vrf key column
                                        index positions in table mode (for
                                        example: -k 0 1 3)
  -u [ --unique_key ] arg               Provide the flag if publish must unique
                                        the key in table mode (for example: -u
                                        1 0 1)
  --omp_thread_num arg (=0)             Provide the number of the openmp
                                        thread, 1: disable openmp, 0: default.

Use pod_publish to preprocess target data.

zkPoD supports two modes: binary mode and table mode.

binary mode
table mode (CSV files)

# binary mode
./pod_publish -m plain -f test.txt -o plain_data -c 1024

# table mode
./pod_publish -m table -f test1000.csv -o table_data -t csv -k 0 1

Check the output folder after publishing.

pod_core

$ ./pod_core -h
command line options:
  -h [ --help ]              Use -h or --help to list all arguments
  -d [ --data_dir ] arg (=.) Provide the configure file dir
  -m [ --mode ] arg          Provide pod mode (plain, table)
  -a [ --action ] arg        Provide action (range_pod, ot_range_pod,
                             vrf_query, ot_vrf_query...)
  -p [ --publish_dir ] arg   Provide the publish dir
  -o [ --output_dir ] arg    Provide the output dir
  --demand_ranges arg        Provide the demand ranges
  --phantom_ranges arg       Provide the phantom range(plain mode)
  -k [ --query_key ] arg     Provide the query key name(table mode)
  -v [ --key_value ] arg     Provide the query key values(table mode, for
                             example -v value_a value_b value_c)
  -n [ --phantom_key ] arg   Provide the query key phantoms(table mode, for
                             example -n phantoms_a phantoms_b phantoms_c)
  --omp_thread_num arg       Provide the number of the openmp thread, 1:
                             disable openmp, 0: default.
  -c [ --use_c_api ]
  --test_evil
  --dump_ecc_pub

pod_core supports several mode combinations. We have atomic-swap, atomic-swap-vc and complaint trade mode for binary and table files. Moreover, we could employ oblivious transfer, OT mode, for privacy-preserving download. Furthermore, we are allowed to do vrf_query of structured table data, which could be combined with OT mode for the private query.

./pod_core -m plain -a complaint_pod -p plain_data -o plain_output --demand_ranges 0-2

./pod_core -m plain -a atomic_swap_pod -p plain_data -o plain_output --demand_ranges 1-10

./pod_core -m plain -a atomic_swap_pod_vc -p plain_data -o plain_output --demand_ranges 1-10

./pod_core -m table -a ot_vrf_query -p table_data -o table_output -k "Emp ID" -v 313736 964888 abc -n 350922 aaa eee bbb

Check here for more CLI interface examples. You could look over each test for detailed protocol implementation.

pod_go

A simple Golang wrapper for zkPoD-lib is provided for easier library integration.

cd pod_go
export GO111MODULE=on
make test

All tests should pass as expected. You could check over tests to learn about usage.

Learn more?

White paper: an overview introduction of the zkPoD system.
Technical paper: a document with theoretic details to those who are interested in the theory we are developing.
Community: join us on Discord and follow us on Twitter please!

License

zkPoD-lib is released under the terms of the MIT license. See LICENSE for more information or see https://opensource.org/licenses/MIT.

sec-bit / zkPoD-lib