E-Bills

Core for Bitcredit project.

Backend

Make sure to have at least Rust version 1.77 as well as a recent version of the toolchain installed. Furthermore protobuf and openssl are necesssary.

On Ubuntu

# Install libs
sudo apt install -y protobuf-compiler libclang-dev libssl-dev pkg-config build-essential

On Fedora

# Install libs
sudo dnf install -y make automake gcc gcc-c++ kernel-devel clang-devel
sudo dnf install -y openssl-devel pkgconf-pkg-config @development-tools
sudo dnf install -y protobuf-compiler

On Windows

# Using MSYS2 terminal
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make mingw-w64-x86_64-llvm 
pacman -S mingw-w64-x86_64-protobuf base-devel pkgconf

For installation of Openssl use vcpkg:

# In vcpkg directory
vcpkg install openssl:x64-windows

# Set Openssl environment variables:
set OPENSSL_DIR=C:\<path>\<to>\vcpkg\packages\openssl_x64-windows
set OPENSSL_LIB_DIR=%OPENSSL_DIR%\lib
set OPENSSL_INCLUDE_DIR=%OPENSSL_DIR%\include

Finally build the backend

cargo build

# or with embedded db
cargo build --features embedded-db

Start the backend server in development mode:

# Run with defaults
RUST_LOG=info cargo run

# configure listening ports and addresses
RUST_LOG=info cargo run -- --http-port 8001 --http-address 0.0.0.0

# Configuration can also be set via environment variables
export P2P_PORT=1909
export P2P_ADDRESS=0.0.0.0

# Run with embedded database feature, data stored in data/surreal
cargo run --features embedded-db -- --surreal-db-connection rocksdb://data/surreal

Frontend

Make sure to have a recent version of Node.js installed.

Build the frontend:

cd frontend
npm install --legacy-peer-deps
npm run build

Development

Start the app in development mode with frontend and backend hot reloading (requires two terminals):

# Terminal 1
RUST_LOG=info cargo watch -x run  # watch can be installed with cargo install cargo-watch

# Terminal 2
cd frontend
npm run start

Tests

You can run the existing tests using the following commands:

// without logs
cargo test

// with logs - (env_logger needs to be activated in the test to show logs)
RUST_LOG=info cargo test -- --nocapture

API docs

OpenApi specs and a Swagger UI are available at http://localhost:8000/swagger-ui/ when running the service.

Docker

The docker build requires no dependencies other than docker or podman. It can also be used to run multiple instances of the app on different ports for testing the P2P functionality.

Build a standalone docker image

Build the image:

# The image name can be changed to whatever you want
docker build -t <image-name> .

Launch the image:

docker run -p 8000:8000 -p 1908:1908 -e RUST_LOG=info <image-name>

You should be able to open the app at http://127.0.0.1:8000/bitcredit/

Run with docker-compose

Build and launch the app with docker-compose running on a different port than the default 8000:

# run in foreground, can be stopped using CTRL+C
docker-compose up

# run in background, can be stopped using docker-compose stop
docker-compose up -d

# rebuild the image
docker-compose build

If you use the above commands, the application state (identity, bills, contacts) will persist between sessions. However, if you use docker-compose down, or docker-compose rm, the existing container gets removed, along with it's state. Of course, rebuilding the image also removes the application state.

SurrealDB

For development it is advised to use a local SurrealDB instance running as a separate service as compile times are quite long. In production builds SurrealDB will be available as an embedded database in the application. SurrealDB listens on port 8000 by default which is the same as the default port for the application so make sure to change the SurrealDB port or application port before running the services.

Connect to SurrealDB

When the application has been built with the embedded-db feature, it allows to use the application with a rocksdb://path/to/db connection string otherwise you need to connect the the database via web-socket like: ws://localhost:8800.

Run SurrealDB for development

# build the application with surrealdb embedded
cargo build --features embedded-db

# start surrealdb container included in docker-compose.yml (listening 8800)
docker-compose up -d surrealdb

# with surrealdb installed on your local machine (listening on port 8800)
surrealdb start --unauthenticated --bind 127.0.0.1:8800

Explore the database with Surrealist

To work with and explore the database, you can use Surrealist which is an interactive interface for SurrealDB.

Contribute

Check out the project contributing guide.