ResilientDB is a High Throughput Yielding Permissioned Blockchain Fabric founded by ExpoLab at UC Davis in 2018. ResilientDB advocates a system-centric design by adopting a multi-threaded architecture that encompasses deep pipelines. Further, ResilientDB separates the ordering of client transactions from their execution, which allows it to process messages out-of-order.
The latest ResilientDB documentation, including a programming guide, is available on our blog repository. This README file provides basic setup instructions.
Ubuntu 20+
Next, we show how to quickly build ResilientDB and deploy 4 replicas and 1 client proxy on your local machine. The proxy acts as an interface for all the clients. It batches client requests and forwards these batches to the replica designated as the leader. The 4 replicas participate in the PBFT consensus to order and execute these batches. Post execution, they return the response to the leader.
Install dependencies:
./INSTALL.sh
Run ResilientDB (Providing a Key-Value Service):
./service/tools/kv/server_tools/start_kv_service.sh
Build Interactive Tools:
bazel build service/tools/kv/api_tools/kv_service_tools
ResilientDB supports two types of functions: version-based and non-version-based. Version-based functions will leverage versions to protect each update, versions must be obtained before updating a key.
Note: Version-based functions are not compatible with non-version-based functions. Do not use both in your applications.
We show the functions below and show how to use kv_service_tools to test the function.
Obtain the value of key with a specific version v.
kv_service_tools --config config_file --cmd get_with_version --key key --version v
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get_with_version |
| key | the key you want to obtain |
| version | the version you want to obtain. (If the v is 0, it will return the latest version |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get_with_version --key key1 --version 0
Results:
get key = key1, value = value: “v2” version: 2
Set value to the key key based on version v.
kv_service_tools --config config_file --cmd set_with_version --key key --version v --value value
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | set_with_version |
| key | the key you want to set |
| version | the version you have obtained. (If the version has been changed during the update, the transaction will be ignored) |
| value | the new value |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd set_with_version --key key1 --version 0 --value v1
Results:
set key = key1, value = v3, version = 2 done, ret = 0
current value = value: “v3” version: 3
Obtain the update history of key key within the versions [v1, v2].
kv_service_tools --config config_file --cmd get_history --key key --min_version v1 --max_version v2
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get_history |
| key | the key you want to obtain |
| min_version | the minimum version you want to obtain |
| max_version | the maximum version you want to obtain |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get_history --key key1 --min_version 1 --max_version 2
Results:
get history key = key1, min version = 1, max version = 2
value =
item {
key: “key1”
value_info {
value: “v1”
version: 2
}
}
item {
key: “key1”
value_info {
value: “v0”
version: 1
}
}
Obtain the recent top_number history of the key key.
kv_service_tools --config config_path --cmd get_top --key key --top top_number
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get_top |
| key | the key you want to obtain |
| top | the number of the recent updates |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get_top --key key1 --top 1
Results:
key = key1, top 1
value =
item {
key: “key1”
value_info {
value: “v2”
version: 3
}
}
Obtain the values of the keys in the ranges [key1, key2]. Do not use this function in your practice code
kv_service_tools --config config_file --cmd get_key_range_with_version --min_key key1 --max_key key2
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get_key_range_with_version |
| min_key | the minimum key |
| max_key | the maximum key |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get_key_range_with_version --min_key key1 --max_key key3
Results:
min key = key1 max key = key2
getrange value =
item {
key: “key1”
value_info {
value: “v0”
version: 1
}
}
item {
key: “key2”
value_info {
value: “v1”
version: 1
}
}
Set value to the key key.
kv_service_tools --config config_file --cmd set --key key --value value
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | set |
| key | the key you want to set |
| value | the new value |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd set --key key1 --value value1
Results:
set key = key1, value = v1, done, ret = 0
Obtain the value of key.
kv_service_tools --config config_file --cmd get --key key
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get |
| key | the key you want to obtain |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get --key key1
Results:
get key = key1, value = “v2”
Obtain the values of the keys in the ranges [key1, key2]. Do not use this function in your practice code
kv_service_tools --config config_path --cmd get_key_range --min_key key1 --max_key key2
| parameters | descriptions |
|---|---|
| config | the path of the client config which points to the db entrance |
| cmd | get_key_range |
| min_key | the minimum key |
| max_key | the maximum key |
Example:
bazel-bin/service/tools/kv/api_tools/kv_service_tools --config service/tools/config/interface/service.config --cmd get_key_range --min_key key1 --max_key key3
Results:
getrange min key = key1, max key = key3
value = [v3,v2,v1]
We also provide access to a deployment script that allows deployment on distinct machines.
Install Docker
Before getting started, make sure you have Docker installed on your system. If you don't have Docker already, you can download and install it from the official Docker website.
Pull the Latest ResilientDB Image
Choose the appropriate ResilientDB image for your machine's architecture:
For amd architecture, run:
docker pull expolab/resdb:amd64
For Apple Silicon (M1/M2) architecture, run:
docker pull expolab/resdb:arm64
Run a Container with the Pulled Image
Launch a Docker container using the ResilientDB image you just pulled:
For amd architecture, run:
docker run -d --name myserver expolab/resdb:amd64
For Apple Silicon (M1/M2) architecture, run:
docker run -d --name myserver expolab/resdb:arm64
Test with Set and Get Commands Exec into the running server:
docker exec -it myserver bash
Verify the functionality of the service by performing set and get operations provided above functions.