Implementing Raft Consensus Protocol for ResilientDB

Wed, 26 Aug 2026 00:00:00 +0000

Distributed systems are powerful and prevalent tools in today’s computing landscape. Properly coordinating these systems requires some mechanism to do so, that being a consensus protocol. Because many consensus protocols exist to target different use cases, it is beneficial for a distributed database to support different protocols. While ResilientDB already contains multiple Byzantine Fault Tolerant algorithms, it has not contained a Crash Fault Tolerant algorithm until now. ResilientDB’s Raft implementation fills this gap, allowing for a more favorable asymptotic message complexity compared to Byzantine Fault Tolerant protocols at the cost of no longer tolerating malicious behavior.

Background

Consensus

Oftentimes, it can be beneficial to leverage the power of multiple computers in multiple locations to solve a computational problem. This may be useful to enable lower latency for users in different locations, handle a higher load, and allow for operations to continue even if individual machines stop working. However, there is one large problem with computation on a distributed system: how do the machines agree on which data values to use during computation? This is the problem of consensus in distributed systems.

Solving this problem is non-trivial. The CAP theorem shows that no matter what algorithm or design is used, if messages are allowed to be arbitrarily delayed or dropped, it cannot be guaranteed that all clients will receive the same response to the same request. Tradeoffs have to be made based on the needs of the system and the users.

Fault Tolerance

One consideration when designing a consensus protocol is the kinds of faults that are tolerated in the system. Crash Fault Tolerant (CFT) protocols tolerate machines crashing or stopping. Byzantine Fault Tolerant (BFT) protocols allow for faults as well as malicious (Byzantine) behavior. A Byzantine machine may lie or actively act against the goal of the group. If a cluster has f faulty nodes, a CFT algorithm must have at least 2f + 1 nodes in total (less than half of the nodes can be faulty). A BFT algorithm must have at least 3f + 1 nodes in total (less than one third of the nodes can be faulty or Byzantine). One well-known BFT algorithm is Practical Byzantine Fault Tolerance (PBFT).

What is Raft?

Raft is a consensus protocol used in many existing software systems, including etcd (used by Kubernetes), Kafka, and MongoDB. It has been battle-tested in production since it was first published in 2014. The ResilientDB project on GitHub has had an open issue since October 2023 requesting that Raft be added to its portfolio of available consensus protocols. This Raft implementation aims to fulfill this feature request.

Raft is the first CFT protocol available within ResilientDB. This comes with several benefits: a ResilientDB Raft deployment can function with only 3 replicas instead of the current minimum of 4, and transaction throughput should, in theory, degrade less sharply than PBFT as the number of replicas increases, thanks to Raft’s more favorable asymptotic message complexity (O(n)) compared to the PBFT family of protocols (O(n²)). The performance overhead of cryptography in BFT protocols is also fairly high, so latency improvements can be expected with Raft as well.

Figure 1. Animation of the Flow of the Raft Consensus Protocol
c: client | T: Transaction | L: leader | F: follower

In Raft, a leader receives transactions from the client, adds them to its log, and forwards them to followers in an AppendEntries Remote Procedure Call (RPC). The followers execute that procedure to add the entry to their log, and respond to the leader to inform them if the RPC succeeded or failed. The leader waits until it has reached quorum on that transaction, requiring responses from at least f + 1 nodes, before committing the transaction to be executed. Then the client is informed, and in future AppendEntries RPCs, the commit index is updated so followers know to commit and execute the transaction.

Raft Leader Elections

In Raft, leaders are supposed to send out heartbeats periodically to maintain their leadership status. All followers maintain a timeout window, and randomly pick a time to wait within that window. Without the follower receiving an AppendEntries RPC from the leader within the time window, it is assumed that the leader is no longer available. The follower will transition to a candidate, increment its term, and send out RequestVote RPCs to all other computers. A computer will respond with a yes vote if:

The replica has not already voted for another computer this term
The candidate’s term and log are at least as up to date as the replica’s own.

Replicas decide if a follower’s log is more recent based upon the index and the term of the last entry in their logs. If the terms of the last entries are different, then the more up-to-date log is the one with the most recent term. If the terms of the last entries are the same, then the more up-to-date log is the one with the highest last log index.

Because at least f + 1 nodes are required to win an election, and entries are committed once f + 1 machines have replicated them, a node can only be elected as leader if its log contains every committed entry.

Initial Raft Implementation

Implementation Strategy and Architecture

Figure 2. How Raft Fits into ResilientDB

Raft needs to fit into ResilientDB’s existing codebase. It interacts with the TransactionExecutor to execute transactions and add them to the database, the ReplicaCommunicator for replica messaging, and the Recovery class. Raft also will have access to built-in benchmarking support through PerformanceManager, to easily measure throughput and latency.

Figure 3. Raft Architecture

The Raft implementation consists of several core components. The consensus object receives messages from the ReplicaCommunicator, and depending on what type of message it is, calls the appropriate Raft function to handle it. Messages can be transactions from a client, or RPCs and RPC responses. These RPCs include AppendEntries, RequestVote, and InstallSnapshot. Raft requires certain data to be durably stored on disk, necessitating the use of RaftRecovery. Specific details on RaftRecovery and the InstallSnapshot RPC are discussed in Persistence and Snapshots.

The Raft object has the logic to send heartbeats and start leader elections, but it needs these events to be triggered at appropriate times. This is handled by the LeaderElectionManager.

The LeaderElectionManager operates in two different modes, leader mode and follower mode. The LeaderElectionManager keeps a timer to invoke certain functions when the timer has elapsed. For leaders, the Raft object tells the LeaderElectionManager every time a message is broadcast to all replicas, which refreshes the duration of the timer. If the LeaderElectionManager times out for a leader, then it forces a heartbeat to be sent.

For followers, the Raft object tells the LeaderElectionManager every time an RPC is received, which refreshes the duration of the timer. If the LeaderElectionManager times out for a follower, then it forces the follower to transition to a candidate and start an election, requesting votes from all other replicas.

Leader In-Flight Message Throttling

The network can become overwhelmed if too many messages are sent unnecessarily. To help mitigate this, there are multiple ways to limit the number of messages sent at once. The first is a cap on message size and the number of entries in a single message. Once that cap would be exceeded, the current message is sent as-is and the remaining entries are sent in one or more additional messages. Additionally, there is a limit on the number of messages allowed to be in flight (from the leader to followers), meaning sent but not yet acknowledged by a follower. Once that limit is reached, no messages other than heartbeats are sent to that follower until it responds or a timeout is reached.

If a timeout occurs, all in-flight messages are presumed lost, and the follower’s next index is reset to its match index (the index of the last entry the follower is known to have).

Follow-up Raft Improvements

The initial implementation included basic log replication, heartbeats, timeouts, and leader elections. However, it was missing several key features described in Diego Ongaro and John Ousterhout’s Raft Paper. The main omissions were persisting each server’s state to disk, and the ability to create and send snapshots to followers that have fallen behind.

In addition to these required features, the implementation had no tests, and the initial benchmarking was performed on a single local machine. After testing on multiple remote machines, throughput issues surfaced, which are addressed in Throughput Improvements.

Persistence

To guarantee the safety of the protocol, Raft requires certain information to be persisted to disk on stable storage before responding to RPCs. This includes the log entries themselves, as well as some extra metadata. ResilientDB’s Recovery class was expanded to support Raft’s needs while maintaining existing behavior for PBFT.

Since the log information that needs to be stored differs between Raft and PBFT, the Recovery class was split into a RecoveryBase and two derived classes, PBFTRecovery and RaftRecovery. Most of the required work was the same, but since different data needs to be stored, different function arguments need to be used. This led to the use of the Curiously Recurring Template Pattern (CRTP), which is well suited to this case since the object type is known at compile time. The base class takes the derived class, as well as the argument types of some functions, as template parameters. This lets the code that reads and writes the individual elements of the Write-Ahead Log (WAL) live entirely in the base class, while the derived classes define which elements are written and in what order.

The extra metadata is stored separately from RecoveryBase’s WAL in RaftRecovery’s own metadata.dat file. This metadata includes the current term, the replica that was voted for in the current term (if any), and the index and term of the last log entry included in any snapshot. Unlike a log, this data doesn’t need to retain history. It only needs to reflect the current state, so it can be overwritten any time it changes. The data is first written to a temporary file, then renamed to metadata.dat.

Snapshots

In a Raft instance, since a follower can be arbitrarily far behind the leader, the entire state of the log must be kept if no precautions have been taken. Without some way to compact this information, the log can grow indefinitely. This problem can be solved by using snapshots to enable log compaction. Snapshots also speed up catching up a follower that has fallen far behind the leader’s log.

Figure 4. Raft Snapshot Flow

In Raft, snapshots contain the current state of the state machine as is, without retaining all of the instructions to get to that point. For ResilientDB, this state is effectively just the database already being used (such as LevelDB). To decide when a checkpoint is to be taken, ResilientDB uses a timer as well as a “checkpoint sequence.” Every 60 seconds (a customizable amount), a thread checks to see if the checkpoint sequence has been updated. This checkpoint sequence is updated after every 1,000 transactions executed, based on a function callback in TransactionExecutor. When the check occurs, if the checkpoint sequence is different from the cached value from the last time it was checked, that triggers the database to be flushed to disk, and the WAL rotates to a new file. Then, the Raft class is notified and truncates the prefix of the log corresponding to that snapshot. Rather than immediately removing every snapshotted entry from the log, a configurable buffer keeps some of them in place.

When a leader knows a follower has fallen behind, it queues a snapshot for that follower. A separate snapshot queue thread reads the queue and sends the InstallSnapshot RPC out. Each snapshot is serialized to a byte string, stored to disk, and then sent to the follower in chunks. The leader waits for the follower to receive and respond to each chunk before sending the next.

During the period between a follower being sent its first chunk of a snapshot and the leader receiving confirmation that the follower has received the last chunk of the snapshot, the leader does not initiate new checkpoints, which pauses prefix truncation until the snapshot completes. This prevents a follower from finishing one snapshot only to immediately need another, because the entry it needs next has already been truncated from the log.

NO-OP Entries

As part of Raft’s safety guarantees, a leader can only directly commit entries from its own term. The specification for Raft addresses this by having the leader submit a blank no-operation (NO-OP) entry at the start of its term. While this was originally described as a step toward supporting read-only transactions, it also solved a specific issue in ResilientDB’s testing harness, where the client can only have a finite number of transactions in flight that have not yet been committed. If all of these transactions have been sent out and a leader election then occurs, no new transactions would be added to the log or committed. Without a NO-OP entry at the start of each term, this would cause progress to stall indefinitely.

Raft Transaction Batching

Another mechanism that was tested to try to address network congestion was to have the leader batch transactions before sending them to followers. When batching is enabled, the leader waits until a set time threshold elapses before sending newly received transactions to followers. In practice, this only helped when transaction bandwidth was not already saturated, so it is currently disabled.

Tests

Around 100 test cases were added for the Raft implementation. This includes tests for Raft and RaftRecovery, as well as for existing components touched by the new Recovery class, such as MemoryDB and LevelDB. Most of the tests are unit tests written for the sending and receiving of each RPC (AppendEntries, RequestVote, and InstallSnapshot) as well as their responses. Additionally, there are some integration tests to verify how Raft and RaftRecovery work together. These tests write to the WAL and metadata file, let the Raft object go out of scope, and then verify that data is restored properly.

Throughput Improvements

Benchmarking began after the initial implementation was fully complete. However, throughput was significantly lower than expected. The following changes address this:

Follower State

Sending a single message at a time and waiting for a response before sending the next is far too slow, so pipelining was added to achieve reasonable throughput. The leader continues sending new transactions as they arrive, without waiting for acknowledgment of previous messages. However, this can overwhelm the network, and the problem compounds whenever a follower fails to add entries to its log for any reason. For example, a single message received out of order causes all subsequent messages to be rejected until the missing entry is resent. The in-flight limits discussed previously mitigate this somewhat, but not completely.

Figure 5. Follower State

To help solve this, the design borrows an approach inspired by the follower progress tracking in etcd’s Raft implementation. For each follower, the leader tracks which of three states it is in: REPLICATE, PROBE, or SNAPSHOT. While a follower is in the REPLICATE state, the leader continues to forward that follower new log entries up to the in-flight limit, assuming everything is being received correctly. If the leader gets a failure response, it sets the follower’s state to PROBE, assumes all in-flight messages were lost, and waits for a response before trying to catch the follower up again. No messages other than heartbeats are sent to a follower while it is in the PROBE state. Once the follower responds, the leader does one of two things: if the missing entry has not been truncated, it sets the follower’s state back to REPLICATE and sends the missing entry. If the entry has been truncated, it sets the state to SNAPSHOT and queues a snapshot for that follower.

This lets the leader use pipelined log replication normally when there are no issues, while avoiding overwhelming the network once a failure occurs. Once the leader has confirmed the follower’s log state, it can resume normal operations.

Asynchronous WAL Writing

Because the log must be persisted to disk before responding to an AppendEntries RPC, the WAL needs to be flushed to disk regularly, which can be expensive. Initially, writes were done every time a leader received a transaction from a client, or every time a follower received an AppendEntries RPC with one or more log entries. This proved prohibitively expensive, especially with multiple threads receiving transactions.

A separate WalWriterLoop thread solves this by batching records and performing one fsync per batch. This request to add a log entry to the WAL returns a std::future that the Raft implementation waits on before responding to an AppendEntries RPC. When a leader receives a transaction from the client, it will add it to its log and then forward the transaction to followers immediately. The std::future it receives from RaftRecovery will be waited on after forwarding. Logically, the transaction is only required to be persisted to disk before committing it. Instead, the std::future is checked after the messages have been sent to the ReplicaCommunicator, which is sufficient to hide the latency from the required disk I/O.

Fast Log Backtracking

If a follower cannot accept a leader’s AppendEntries RPC, one option is for the leader to decrement its index one entry at a time and try again. Unfortunately, this is impractical with pipelining, since the point where a message was dropped or received out of order may be many thousands of log entries back during periods of high bandwidth. To address this, the Raft paper describes an optional optimization that lets the leader and follower back up one term at a time instead of one entry at a time, allowing for much faster backtracking to the correct log index at which to resume replication. This accelerated log backtracking, while not very well specified in the original Raft paper, can be found in more detail in Jon Gjengset’s Students’ Guide to Raft.

In Raft, when a leader sends an AppendEntries RPC, it includes the index and term of the entry directly preceding the first log entry sent in the RPC. For example, if the log only contains entries from term 1, when the leader sends entries beginning at index 6, the previous log index is 5, and the previous log term is 1. If the follower contains an entry at that index at that term, it is guaranteed the follower’s log is identical to the leader’s up until that point.

If the follower’s log contains an entry at that index from a different term, the follower must reject that message and reply with the first log index of that term (the one in its log). For example, say that a follower’s log only contains entries from term 1, and it receives an AppendEntries RPC with a previous log index of 5 and previous log term of 2. At index 5 in the follower’s log, the follower has a conflicting term of 1. So, it will reverse through its log and return the first index from the conflicting term, which is index 1. If the leader’s log does not contain any entries from the conflicting term, it will begin sending entries at the conflicting index. If the leader’s log does have entries with that conflicting term, the leader will begin sending entries at the index after the last entry in its log that matches the conflicting term.

If the follower’s log is simply too short, then it can return the conflicting index as the length of its log, and the leader can try to continue from there. This will either lead to successful replication or one of the previous cases with a conflicting term.

Performance Manager Changes

Additionally, changes were made to the client’s PerformanceManager to allow multiple threads to generate transactions for the consensus cluster. This is not a change to the Raft implementation itself, but part of the benchmarking infrastructure within ResilientDB. While benchmarking the Raft implementation, one client using one thread did not generate enough transactions to saturate bandwidth. Previously, multiple threads could be created to send out transactions, but generating them was still done by only one thread. Additionally, a semaphore class was added to prevent the threads generating transactions from getting too far ahead of the threads sending them out.

Evaluation

The evaluation was performed remotely on CloudLab using four d430 machines for the Raft nodes. These computers have an Intel Xeon Processor E5-2630v3 2.4 GHz CPU, and 64 GB RAM. Experiments were run for 120 seconds. For all experiments, 3 runs were done, and the average throughput and average latency were recorded for each run. Only the run with the median average throughput was used. In these experiments, the client computer requests transactions to be added to the database, and the leader responds to the client once a transaction has been committed to being executed. For the evaluation, no leader elections occurred. The following config file was used for these runs, with max_process_txn being varied across the different runs:

{
  "client_batch_num": 100,
  "enable_viewchange": false,
  "recovery_enabled": false,
  "not_need_signature": true,
  "max_client_complaint_num": 10,
  "max_process_txn": 2048,
  "worker_num": 8,
  "input_worker_num": 5,
  "output_worker_num": 5,
  "recovery_ckpt_time_s": 60,
  "min_client_receive_num": 1,
  "raft_follower_batch_timeout_ms": 0
}

Note that in the following tables, the in-flight Transaction limit (max_process_txn in the config file) is different from the discussion on in-flight messages previously. The previous limit was on the number of unacknowledged messages sent from a leader to a follower. This in-flight limit is on the number of unacknowledged messages, each message being a batch of 100 transactions, from a client to the Raft cluster. This second type of in-flight limit is to prevent the client from overwhelming the Raft cluster.

Comparison vs HotStuff-1

(a) Throughput vs. maximum in-flight transactions

(b) Latency vs. maximum in-flight transactions

(c) Throughput vs. latency

Figure 6. Performance evaluation of the Raft implementation.

Here, we can see that Raft appears to reach its saturation point around 2,048 maximum in-flight transactions. At this point, the bandwidth of the Raft cluster is fully saturated. As the number of transactions in the system increases, latency increases dramatically, and throughput drops.

Comparisons were run against HotStuff-1, another BFT protocol available in ResilientDB. Setting recovery_enabled set to false disables writing the WAL and metadata to stable storage, as well as snapshotting. As a result, the prefix of the log is not truncated. The choices to use 4 nodes and no recovery (no WAL, no storing of metadata) were made to compare to HotStuff-1, which requires a minimum of 4 nodes, and also operates fully in memory. Both protocols have their own saturation point due to their own bottlenecks. Table 1 shows that, when bandwidth is fully saturated for both protocols, Raft achieves almost 6x higher throughput with just over 9x better latency.

Metric	Raft	HotStuff-1
Maximum in-flight transactions from client	2048	3
Average throughput (transactions/second)	588,596	104,080
Average latency (ms)	0.288	2.611

Table 1. Comparison between Raft and HotStuff-1 at their saturation point

Effect of Persistence

Figure 7. Raft evaluation with Snapshotting and Persistence enabled.

However, even with recovery enabled, Raft achieves nearly identical throughput and latency for values of max_process_txn around the saturation point. While this extra bookkeeping does have some overhead, the current settings do not fully utilize the available CPU threads, and the batching of WAL writes has minimized the effect of this overhead.

Scalability

Figure 8. Raft Scalability with different numbers of replicas (n).

Figure 8 illustrates the impact that the number of replicas has on the performance of Raft. An increase in the number of replicas leads to an increase in latency and an overall decrease in throughput. In Raft, the latency is generally bottlenecked by the leader. The leader needs to forward all transactions, and keep track of when quorum is reached for each transaction. This work grows linearly with respect to the number of replicas. However, there is also a constant component of the work that runs concurrently with the previous work, like disk I/O and network round-trip time. Since the system is saturated with client transactions, throughput decreases as latency increases. This causes the shape of the curve to be flatter at lower replica counts and steeper as the number of replicas increases.

Commands to Execute

Here are the commands to download ResilientDB and prepare all requirements:

sudo apt update
sudo apt install git psmisc
git clone https://github.com/apache/incubator-resilientdb.git
cd incubator-resilientdb/
./INSTALL.sh
./service/tools/kv/server_tools/start_kv_service.sh
bazel build service/tools/kv/api_tools/kv_service_tools
cd scripts/deploy/
touch config/key.conf

To run the Raft performance script locally on only a single machine, use:

./performance_local/raft_performance.sh config/kv_performance_server_local.conf

To run the evaluation remotely, several changes will need to be made:

Make sure the machine you are running the performance evaluation script on is able to connect via ssh key to the remote machines.
Change the contents of scripts/deploy/config/key.conf to point to the directory of the ssh key on the machine running the performance evaluation script, as shown in scripts/deploy/config/key_example.conf
(Optional) Change the existing file in scripts/deploy/config/raft.config to match the desired config, or pass the separate config file as the second argument to raft_performance.sh
Change the IP addresses in scripts/deploy/config/kv_performance_server.conf to the IP addresses of the remote machines.
Change the user and home directory in scripts/deploy/script/env.sh to match the user and home directory on all of the machines you will ssh into.
In scripts/deploy/, run ./performance/raft_performance.sh config/kv_performance_server.conf <optional_config_file>

This script will build the needed binaries on the current machine and scp them to the other machines, so no setup should be needed on them.

In order to view more detailed log information, the following steps can be taken:

(Optional) If you would like to examine the individual log files, go to scripts/deploy/performance/run_performance.sh and uncomment the line #rm -rf result_*_log
(Optional) If you would like to see the more verbose VLOG lines, on the line where the server binary is actually run underneath the # Start server comment in scripts/deploy/script/deploy.sh, change ./${server_bin} server.config to ./${server_bin} --v=3 server.config

If you want to view detailed log information for the local version, instead modify the files scripts/deploy/performance_local/run_performance.sh and scripts/deploy/script/deploy_local.sh

The Raft and RaftRecovery tests can be run with:

bazel test //platform/consensus/ordering/raft/algorithm:all --test_timeout=20
bazel test //platform/consensus/recovery:raft_recovery_test --test_timeout=60

Conclusion

Raft is a well-known and well-tested consensus algorithm used in many real-world applications. While the specification for Raft does describe the protocol, many implementation details are left to the reader. This is especially true for an implementation that integrates with a large existing codebase while maintaining compatibility and sharing code with other consensus protocols. On top of needing to ensure correctness, engineering and design effort had to be put in for several different components. Decisions had to be made to decide how to share RecoveryBase code with PBFT, to minimize lock contention in a multi-threaded environment through techniques like batching the WAL writes, and to add extra tracking of individual follower state to allow for more effective usage of pipelining AppendEntries RPCs.

Now, ResilientDB contains a CFT protocol with a different trust model than the BFT protocols. When the situation calls for a protocol where all involved computers can be trusted, this allows for better asymptotic complexity for messages sent as well as no need for cryptographic signatures. However, there is still work to be done for the Raft implementation.

Future Work

Further Throughput Improvements: When runs are done past Raft’s saturation point at 2,048 maximum in-flight transactions, the latency spikes as expected, but throughput goes down. One plausible explanation for this is that once a leader’s capacity to receive more transactions from the client is full, the buffer holding these transactions before they get added to the log becomes overwhelmed and degrades performance. It is future work to investigate this in more detail.

Additionally, others have implemented optimizations to increase Raft throughput in various scenarios, such as Multi-Raft or Fast Raft.
Membership Changes: Enable the safe addition or removal of servers from the cluster dynamically, without shutting down the system or halting operations.
Read-Only Operations: Allow read-only operations without writing anything to the log. Some groundwork has already been laid by having leaders commit a blank NO-OP entry at the start of their term, as described in the Raft paper, which is a step toward this.

Acknowledgements

The initial development of the Raft implementation was accomplished through the combined effort of five ResilientDB community members: Josh Hutton, Jim Brower, Nachiket Subbaraman, Vinoth Gopikrishnan, and Yuhua Huang. The engineering effort described in Initial Raft Implementation contains work done by the group. Additionally, initial versions of the written sections in Background and Initial Raft Implementation were created by the group. The second section, Follow-up Raft Improvements, and the Evaluation document the additional work Josh Hutton completed individually afterward.

The World’s First Blockchain-Backed Drawing App? Introducing ResCanvas.

Fri, 05 Jun 2026 00:00:00 +0000

The Existing Problem

Drawing is an important aspect of art and free expression within a variety of domains to express new ideas and valuable works of creativity. Tools such as MS Paint allow for drawing to be achievable on the computer, with online tools extending that functionality over the cloud where users can share and collaborate on drawings and other digital works of art. Both Google’s Drawing and Canva’s Draw application have a sharable canvas page where registered users can draw, and Figma has also been quite popular due to its wide array of features and ease of use.

As you can see, drawing tools are everywhere, from quick doodle apps running on your computer to full fledged cloud design suites hosted over the cloud. But beneath the convenience lies a hidden cost: centralization. When you draw on a typical web platform, your work and your identity, are stored on a server you don’t control. Your art can be censored, your actions monitored, your data analyzed or sold.

At the same time, creativity has never been more collaborative. Artists sketch together, communities brainstorm visually, and teams rely on whiteboards to communicate ideas.

But existing online platforms store the drawing and user data centrally, making personal data easily trackable by their respective companies, and easily sharable to other third parties such as advertisers. The drawings can be censored by both private and public entities, including government agencies. Privacy is important, yet online collaboration is an essential part of many user’s daily workflow.

Even the famous Reddit r/place board, while being massively collaborative as a pixel based canvas, relies on fully centralized state and exposes all user activity to the platform.

Creativity thrives only when ideas can be freely expressed. But freedom requires autonomy, and autonomy requires decentralization.

So we asked a simple question:

Why can’t collaborative creativity be both expressive and decentralized?

Our Solution: ResCanvas

That question led to ResCanvas - a fully decentralized, real-time drawing platform powered by ResilientDB, a high performance blockchain database engineered for trust on a global scale. The canvas drawing board is the core feature of ResCanvas, designed to allow users to perform drawings all while being censorship resistant. It is simple to use, yet it allows for infinite possibilities. To our knowledge, ResCanvas is the world’s first drawing and creativity platform that combines the key breakthroughs in database decentralization brought forth by a blockchain based database, ResilientDB, with the power of expression that comes with art, bridging the gap between the arts and the sciences.

ResCanvas is designed to seamlessly integrate drawings with the familiarity of online contribution between users using effective synchronization of each user’s canvas drawing page. This allows for error-free consistency even when multiple users are drawing all at the same time.

Multiple users are able to collaborate on a single canvas, and just as many things in life have strength in numbers, so too are the users on a canvas. One user could be working on one key part of a drawing while other users can finish the remaining parts in a collaborative manner.

The key feature of ResCanvas is defined by having all drawings stored persistently within ResilientDB in a stroke by stroke manner. Each stroke is individually cached via in-memory data store using Redis serving as the frontend cache, hosted on a trusted node of your choice. This ensures that the end user is able to receive all the strokes from the other users regardless of the response latency of ResilientDB, which greatly enhances performance for the end user.

In essence, all users will see each other’s strokes under a decentralized context and without any reliance on a centralized server for processing requests and storing data.

ResCanvas works seamlessly, with the familiarity of the drawing tools you already use, without the issues of surveillance, control, or central ownership.

Detailed Architecture and Concepts

To turn decentralized creativity into a reality, our application consists of several major components.

The first one is the frontend (React), which handles drawing input, local smoothing/coalescing of strokes, UI state (tools, color, thickness), optimistic local rendering, and Socket.IO for real-time updates. Thus the frontend handles the user facing side of ResCanvas and ensures a smooth UX while ensuring communication between this frontend layer and the backend. This layer also handles the storage of auth tokens in localStorage and its API wrappers (like frontend/src/api/) automatically attach JWT access tokens to all protected requests as well. The most important aspect of this layer in terms of security is that the frontend does not perform authentication or authorization logic, since it simply presents credentials and tokens to the backend.

This brings us to the backend (Flask + Flask-SocketIO), which serves as the authoritative security boundary and data handler for the application. The backend validates all JWT tokens server-side using middleware, enforces room membership and permissions, verifies client-side signatures for secure rooms, encrypts/decrypts strokes for private/secure rooms, commits transactions to ResilientDB via GraphQL, and also retrieves data as needed according to the frontend’s request. All protected API routes and Socket.IO connections require valid JWT access tokens sent via Authorization: Bearer <token> header. Since the backend performs all security checks, clients cannot bypass authentication or authorization and must go through the backend for all sensitive requests. Furthermore, when working with private or secure rooms, the backend handles encryption/decryption and room key management as well.

Going into deeper detail with regards to the backend, it interacts with several other key components.

The first one is ResilientDB, the persistent, decentralized, immutable transaction log where strokes are ultimately stored, and the core essence of this application. Strokes are written as transactions so the full history is auditable and censorship-resistant. Through the resilient-python-cache library, ResilientDB synchronizes data blocks with MongoDB (canvasCache). MongoDB is a warm persistent cache and queryable replica of strokes so the backend can serve reads without contacting ResilientDB directly for every request, and can be hosted on any node that users trust. This essentially serves as a secure sync bridge that mirrors ResilientDB into MongoDB.

From MongoDB, our backend handles the syncronization of data with Redis, which is a short-lived, in-memory store keyed by room for fast read/write and undo/redo operations. Redis is intentionally ephemeral as it allows quick synchronization of live sessions while ResilientDB acts as the long-term durable store. Just like MongoDB, this Redis cache can be hosted by any trusted node, and thus ensures that security and privacy guarantees of ResilientDB are still preserved while ensuring fast performance. It can be said that our backend is also another sync bridge layer, that of between MongoDB and Redis.

Data Model and Stroke Format

ResCanvas uses a simple, compact stroke model that is end-to-end friendly for network transport and decentralized commits. A typical base stroke data payload (JSON) contains the following data:

drawingId: unique per-user or per-drawing session
userId: author id (when available/allowed)
color: hex or named value
lineWidth: numeric stroke thickness
pathData: an array of (x,y) points, optionally compressed (delta-encoded)
timestamp: client-side timestamp for ordering and replay
metadata: optional fields for signing, encryption info, transform/offsets, custom brush styles, .etc

Undo/Redo and Edit History

Despite the decentralized, blockchain backed nature of ResCanvas, users can still leverage the functionality they know and love, including undoing and redoing operations. Undo/redo is implemented through per-room, per-user stacks stored in Redis. Each user action that mutates the canvas pushes an entry to the user’s undo stack and updates the live room state in Redis. Redo pops from a redo stack and applies the strokes again via the same commit flow (including related signing and encryption rules).

Because ResilientDB is immutable, undo/redo on the client is implemented as additional strokes that semantically represent an “undo” (for example, through a delta or a tombstone stroke) by using a separate metadata layer that signals removal in replay. The visible client behavior is immediate, while the authoritative history in ResilientDB preserves the full append only log.

Consistency, Concurrency and Ordering

Multiple users can draw simultaneously since the system is designed for eventual consistency with low-latency broadcast, where each stroke is broadcast immediately via Socket.IO to all connected room participants. This allows the application to provide near real-time feedback. The backend attempts to persist strokes to ResilientDB and caches (Redis/MongoDB). If ResilientDB write is delayed, clients still see strokes from the Socket.IO broadcast and from Redis while waiting for the backend to finishing writing the stroke data.

Ordering is primarily guided by timestamps and the sequence of commits in ResilientDB. When replaying history, the authoritative order comes from the ResilientDB transaction log so all data and their ordering is preserved even if the canvas itself is cleared, strokes are undone, or even if the entire canvas room is deleted by the user.

ResilientDB Theory

ResilientDB is used as an immutable, decentralized transaction log. There are several key properties that we rely on.

The first one is that of immutability, where once a stroke is committed, it cannot be altered silently. This increases trust and accountability. The second one is decentralization, since no single host controls the persistent copy of strokes, reducing censorship and central data harvesting. The third key property that we rely on is auditability as the entire canvas history can be inspected and verified against the ResilientDB ledger. This ensures transparency as anyone can view and verify the user’s drawing history and actions taken on the application, and serves as a key deterrent against malicious activity on the canvas.

By treating each stroke as a transaction, we now achieve a chronological, tamper-evident history of canvas changes. Anyone can verify and review the changes to the canvas as the ground truth source of information. The sync bridge mirrors transactions into MongoDB so read queries don’t need to hit ResilientDB for every request, while Redis caching further enhances the performance from the UX standpoint by caching the data from MongoDB on an in-memory basis within a trusted node. Removal operations such as undo and redo, as well as clear canvas/room deletions are simulated using time stamp markers to achieve the same effects without altering the historical backend data as well.

This hierarchical relationship between ResilientDB, MongoDB, and Redis essentially serves as an unique balance between user experience, security, and privacy.

Public Rooms vs Private Rooms vs Secure Rooms

In ResCanvas, options are provided to meet the diverse needs of users. One way we achieve this is through the three different types of canvas rooms that users can create.

The first kind is public rooms, which allow anyone to access and draw in them, and so all the data is publically accessible by all registered users without needing to perform decryption and obtaining an access key to the room.

In private rooms, access is restricted as only invited users or those with the room key can join such rooms. Strokes are encrypted so only members with the room key can decrypt and access them. The backend participates in wrapping/unwrapping room keys using ROOM_MASTER_KEY_B64. This allows users who want additional privacy while drawing contents containing sensitive or personal information to be able to do so without the risk of exposing all their raw drawings to the general public.

Secure rooms go further and expand upon the protections of private rooms by requiring client-side signing of strokes with a cryptographic wallet (such as ResVault). Each stroke is signed by the user’s wallet private key and the signature is stored with the stroke. This enables verifiable authorship since anyone can confirm a stroke was created by the owner of a given wallet address.

Putting cryptographic signatures into use, secure rooms work as follows (assuming ResVault is used):

User connects cryptographic wallet via the frontend UI and grants signing permissions.
When drawing in a secure room, the frontend prepares the stroke payload and asks ResVault to sign the serialized stroke or a deterministic hash of it.
The signed payload (signature + public key or address) is sent to the backend along with the stroke.
The backend verifies the signature before accepting and committing the stroke to persistent storage.

Security, Privacy and Threat Model

ResCanvas aims to improve user privacy and resist centralized censorship, and so we mitigated several threats in our application.

One of the most significant threats that many web based applications face today is the danger of central server compromise, since many existing applications are based on a centralized sever and store important data there. However, in ResCanvas, persistent data is stored on ResilientDB and mirrored to MongoDB, which reduces a single point of failure due to the decentralized nature of ResilientDB.

We also prevent data harvesting by a platform operator from occurring in the first place as decentralized storage and client-side signing for secure rooms reduce linkability and provide verifiability. This ensures that user’s data is not being collected for third party usage, for instance, which could result in data being leveraged for commercial purposes and malicious intent. This assurance in user’s data security is also guaranteed through our prevention of client-side authentication bypasses. All authentication, authorization, and access control logic runs server-side, rather on the client’s front end. The backend middleware validates tokens, checks permissions, and enforces room access rules. Even the most malicious of clients cannot manipulate or circumvent security checks because of this middleware.

Other security protections that ResCanvas offers includes handling the situation where there could be token theft via XSS. We manage this risk by having refresh tokens be stored in HttpOnly cookies that cannot be accessed by JavaScript, protecting long-lived sessions from cross-site scripting attacks. Additionally, we prevent CSRF attacks by having refresh cookies use SameSite attribute. Using this kind of attribute prevents cross-site request forgery from occurring. We also prevent signature forgery for secure rooms since the backend verifies cryptographic signatures server-side. This protection ensures that strokes cannot be attributed to users who didn’t create them in the first place.

Despite these significant protections that ResCanvas offers, there are several key trade-offs and assumptions that are worth mentioning.

For instance, there is still a risk that the application can suffer from frontend device compromise. While the backend enforces all security decisions, if a user’s device or browser is compromised, attackers could steal access tokens from localStorage or wallet keys before signing. So access tokens are short-lived (15 minutes by default) to minimize exposure and refresh tokens in HttpOnly cookies are protected from JavaScript access.

The core functionality of ResCanvas also depends on the availability of ResilientDB. ResilientDB endpoints and GraphQL commit endpoints used by the backend must remain available and trusted by backend operators. If those services are compromised, ledger inclusion or availability may be affected. However, the probability of this occurring is extremely low due to the decentralized, blockchain nature of ResilientDB.

Furthermore, certain backend layers and services, such as Redis and MongoDB, rely on the user’s level of backend trust. Users must trust the backend operators to correctly implement and enforce security policies, and also ensure that those backend layers and services are running on trusted nodes. Having nodes that are trustworthy to the user is essential as the backend has access to certain data such as unencrypted strokes for public rooms.

Frontend Design and User Experience

While ResCanvas is powered by a decentralized backend architecture, the user experience is intentionally designed to feel familiar and approachable. The frontend serves as the main interaction layer between users and the underlying ResilientDB-powered system. Instead of exposing users directly to blockchain transactions, caching layers, or synchronization logic, the interface presents ResCanvas as a clean collaborative drawing workspace.

The ResCanvas frontend is organized around a canvas-first layout. The central canvas workspace occupies the majority of the screen so that drawing remains the primary user activity. This design choice helps users focus on creative expression while keeping supporting controls available around the workspace. Drawing input is captured directly from the canvas area and converted into structured stroke data that can later be submitted to the backend, cached, synchronized, and persisted through the system.

On the left side of the interface, ResCanvas provides a compact vertical toolbar for drawing controls and canvas operations. This toolbar maintains important UI state such as the selected tool, brush size, and color. It also exposes drawing-related actions such as tool selection, undo/redo operations, and other canvas controls. By keeping these controls compact and visually separated from the main drawing area, the interface reduces clutter and preserves more usable space for the canvas itself.

At the top of the interface, the application displays navigation and user context. The breadcrumb-style room information helps users understand which canvas room they are currently working in, while the account area fetches and displays user information after login or registration. This connects the authentication flow with the main drawing experience and gives users a clear sense of where they are inside the application.

On the right side, the interface includes a drawing history panel. This panel helps surface the historical nature of ResCanvas by showing previous drawing activity associated with the current room. While the backend and ResilientDB preserve the deeper operation history, the frontend presents this concept in a way that users can understand visually. This supports one of the core ideas of ResCanvas: the canvas is not just a final image, but an evolving history of user contributions.

The bottom navigation bar connects ResCanvas to broader project resources, including help pages, blog content, metrics, analytics, benchmark dashboards, and overview statistics. These links help present ResCanvas as a more complete application rather than a standalone drawing prototype. They also make it easier for users, developers, and evaluators to explore the surrounding ResilientDB ecosystem.

Overall, the frontend design bridges the gap between a technically complex decentralized backend and a simple user-facing drawing experience. Users interact with familiar concepts such as a canvas, toolbar, room navigation, drawing history, and account controls, while the system behind the interface handles authentication, real-time synchronization, caching, persistent storage, and blockchain-backed operation history.

ResCanvas Setup Guide

Want to deploy and run ResCanvas locally right on your own machine? This guide provides complete instructions to deploy ResCanvas locally, including setup for the cache layer, backend, and frontend.

Prerequisites

Before starting, ensure the following dependencies are installed:

Python ≥ 3.10 and ≤ 3.12
Node.js (LTS version via nvm install --lts)
npm (latest version)
Redis
MongoDB Atlas account with a working connection URI

Step 0: MongoDB Account Setup

Go to https://account.mongodb.com/account/login and log in or register.
Create a project and cluster (if not already existing).
Within your cluster, click Connect → Drivers and copy the connection string from Step 3
Keep this MongoDB connection URI handy. You will use it in later .env files.

Step 1: Clone the Repository

git clone https://github.com/ResilientApp/ResCanvas.git
cd ResCanvas

Check your Python installation:

python3 --version

Step 2: Resilient Python Cache (First Terminal Window)

This cache layer synchronizes strokes between MongoDB and ResilientDB.

Setup

cd backend/incubator-resilientdb-resilient-python-cache/
pip install resilient-python-cache

Create a .env file in this directory with the following content (replace everything between brackets):

MONGO_URL = "[URI_COPIED_FROM_MONGODB_CONNECTION]"
MONGO_DB = "canvasCache"
MONGO_COLLECTION = "strokes"

Start the Cache Service

python3 example.py

This starts a MongoDB caching service that syncs data with ResilientDB via the resilientdb://crow.resilientdb.com endpoint defined in cache.py.

Step 3: Backend Setup (Second Terminal Window)

The backend handles authentication, REST APIs, and interfaces with ResilientDB.

Create Virtual Environment & Install Dependencies

cd backend/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Generate Keys

python gen_keys.py

Copy the printed public and private keys.

Create .env File

Create a new .env under the backend/ folder with the following contents (replace values between brackets):

MONGO_ATLAS_URI=[URI_COPIED_FROM_MONGODB_CONNECTION]
SIGNER_PUBLIC_KEY=[PUBLIC_KEY_COPIED_FROM_GEN_KEYS_PY]
SIGNER_PRIVATE_KEY=[PRIVATE_KEY_COPIED_FROM_GEN_KEYS_PY]
RESILIENTDB_BASE_URI=https://crow.resilientdb.com
RESILIENTDB_GRAPHQL_URI=https://cloud.resilientdb.com/graphql

Step 4: Redis Setup

Redis is required for caching and backend operations.

macOS (Homebrew)

brew install redis
brew services start redis

Ubuntu (APT)

sudo apt-get update
sudo apt-get install -y redis-server
sudo systemctl restart redis.service

Verify Redis

redis-cli ping

Expected output: PONG

Optional Fix (bcrypt Error)

If you encounter bcrypt issues, run:

pip install 'passlib>=1.7.4' 'bcrypt>=4.1.2,<5'

Start the Backend

python app.py

Step 5: Frontend Setup (Third Terminal Window)

The frontend provides the ResCanvas web UI.

cd frontend/
nvm install --lts
nvm use --lts
npm i -g npm
npm install
npm start

The app should now be running at http://localhost:[...]

ResTier: A Tiered Storage Engine for ResilientDB using IPFS

Tue, 02 Jun 2026 00:00:00 +0000

ResTier: A Tiered Storage Engine with IPFS Cold Storage for ResilientDB

Exploratory Systems Lab Jun 02, 2026

ResTier is a tiered storage engine for ResilientDB that extends the permissioned blockchain fabric with hot/warm/cold storage tiers, using IPFS as a scalable cold-storage backend. The engine transparently migrates historical data from local storage (MemoryDB or LevelDB) to IPFS, providing unbounded storage growth with zero write-path latency overhead and O(1) cold-read performance via an in-memory secondary index.

Motivation

ResilientDB is a high-throughput permissioned blockchain fabric that orders and executes client transactions through PBFT consensus. By default, all blockchain state, i.e. every key-value pair, every version, is persisted indefinitely in local LevelDB storage. As the ledger accumulates history, storage grows unboundedly: every transaction, every checkpoint, every version remains on disk. For production deployments that process millions of transactions, this increases the costs multifold to vertically scale the number of SSDs for all resilientdb nodes.

Existing storage backends offer no mechanism to offload cold or archival data. Operators face a choice between expensive vertical scaling (larger disks) or manual data pruning, which breaks the blockchain’s immutability guarantees. What is needed is a storage system that can seamlessly migrate historical data to cheaper, scalable storage while keeping recent data on fast local storage—all without changing the application’s query interface or the consensus protocol.

IPFS (InterPlanetary File System) is a natural fit for the cold tier. It is decentralized, content-addressed (CIDs are cryptographic hashes of the data), trustless (content is mathematically verified), provides built-in deduplication, replicates across nodes via peer-to-peer gossip, and carries no vendor lock-in. By combining IPFS with ResilientDB’s existing MemoryDB and LevelDB tiers, we can build a storage engine that is both scalable and transparent.

The key goals of ResTier are:

Unbounded storage growth: Historical data automatically migrates to IPFS, freeing local disk space.
Zero write-path overhead: The hot write path is untouched; migration runs asynchronously.
Transparent cold reads: Applications use the same GetValue API; cold data is fetched from IPFS automatically.
No consensus changes: Each PBFT replica migrates independently; no cross-replica coordination is needed.

Architecture Overview

ResTier organizes storage into two data storage tiers and one index manifest tier that form a hierarchy of decreasing performance and increasing capacity:

Each PBFT replica runs its own IPFS sidecar and maintains its own manifest index. There is no cross-node coordination for migration—each replica independently decides when and what to migrate. Consensus guarantees that all replicas converge to the same application state regardless of the storage backend.

Four Storage Modes

ResTier supports four deployment modes to accommodate different use cases:

Mode	Backend	Hot Tier	Warm Tier	Cold Tier	Use Case
0	MEMORYDB	MemoryDB	—	—	Dev/testing, fastest access
1	LEVELDB	LevelDB	—	—	Production, small datasets
2	TIERED	LevelDB	LevelDB (manifest)	IPFS	Production, large data
3	TIERED	MemoryDB	LevelDB (manifest)	IPFS	High-throughput, crash-tolerant

Modes 2 and 3 are the primary focus. They enable unbounded storage growth by offloading cold data to IPFS while keeping hot data on fast local storage.

Write Path: Zero Overhead by Design

The write path is deliberately kept simple. When a client submits a transaction through PBFT consensus, the execution layer calls TieredStorage::SetValueWithSeq(key, value, seq). This method writes only to the hot storage tier:

Client → PBFT Consensus → KVExecutor → TieredStorage::SetValueWithSeq
                                              │
                                              ▼
                                       hot_storage_.SetValueWithSeq
                                              │
                                              ▼
                                    MemoryDB or LevelDB (immediate)
                                              │
                                              ▼
                                     max_seq_ updated (atomically)

The warm LevelDB (which stores the manifest index) is not touched on the write path. This is a deliberate design decision: writing to LevelDB on every transaction would add 20–50µs of latency. By deferring all manifest updates to the asynchronous migration thread, ResTier ensures that the write-path latency is identical to the underlying hot storage when the tiering were not enabled (memorydb or leveldb).

Checkpoint tracking differs by hot tier:

LevelDB hot tier: Uses LevelDB’s native UpdateLastCkpt(seq) mechanism, which fires on every write via SetValueWithSeq.
MemoryDB hot tier: Tracks max_seq_ atomically as a simple counter. There is no warm-write overhead.

Read Path: Transparent Auto-Fallback

The read path implements a three-level cascade: hot storage is checked first, then warm (LevelDB manifest), and finally cold (IPFS). The fallback is completely transparent to the application:

GetValue(key)
    │
    ├── HOT (MemoryDB/LevelDB) ─── found? ──► Return value
    │
    └── not found ──► COLD (IPFS)
                        │
                        ▼
                InMemoryHashIndex.Get(key) or WARM (LevelDB Manifest Index) → CID
                        │
                        ▼
                    IPFS::Cat(CID)
                        │
                        ▼
                    Return value

The cold-read path uses an in-memory secondary index (InMemoryHashIndex, backed by std::unordered_map) to map keys to their IPFS CIDs. Lookups are O(1) here. This is extremely faster than any IPFS network operation, so the index is never the bottleneck.

Benchmark measurements confirm this:

Hot read (MemoryDB): 2µs p50
Hot read (LevelDB): 15µs p50
Index lookup: 1µs p50
Cold read (IPFS Cat, loopback): 4ms p50 (This latency for historical reads is the tradeoff for cheaper storage. But from the client’s perspective this latency might get hidden because of higher network latency between client -> resilientdb client proxy -> resilientdb nodes)

Migration Flow: Asynchronous Background Thread

Data migration from hot storage to IPFS runs in a background thread inside TieredStorage. This design was chosen over a separate sidecar process because LevelDB’s LOCK file prevents concurrent access from multiple processes.

TieredStorage constructor → StartMigration()
    │
    ▼
If tiering enabled + IPFS available:
    ├── 1. Create InMemoryHashIndex
    ├── 2. Load Manifest from warm LevelDB → populate index
Background thread: MigrationLoop() ─ poll every N seconds
    │
    ▼
MigrateColdData()
    │
    ├── 1. Get checkpoint from hot storage
    ├── 2. Calculate cold threshold: seq <= (checkpoint - watermark × threshold)
    ├── 3. Scan hot storage via GetAllItemsWithSeq()
    ├── 4. For each eligible key:
    │       ├── Upload to IPFS via POST /api/v0/add → get CID
    │       ├── Add CID to InMemoryHashIndex
    │       ├── Save manifest to warm LevelDB
    │       ├── Delete key from hot storage
    │       │   └── (LRU cache invalidated for LevelDB hot tier)
    │       └── Unpin stale CID in case of value updates to existing key to prevent bloating in IPFS due to stale data
    │
    └── 5. Sleep until next poll interval

Key Design Decisions

Cursor optimization (last_migrated_seq_): On each migration cycle, only keys with sequence numbers between last_migrated_seq_ and the cold threshold are eligible. This avoids a full scan of the hot storage on every cycle. The cursor is persisted to warm storage after each successful cycle, so crash recovery resumes from the last saved position rather than scanning from seq 0.

Safe delete with DeletableStorage interface: Deletion from the hot tier is mediated through a pure virtual DeletableStorage interface. TieredStorage uses dynamic_cast<DeletableStorage*> to check whether the hot storage backend supports deletion at runtime. This avoids friend class coupling and remains extensible to future backends.

LRU cache invalidation: When operating in LevelDB→IPFS mode (Mode 2), the hot tier has an LRU block cache. After DeleteKey removes a key from LevelDB, block_cache_->Remove(key) is called to ensure stale cache entries don’t serve pre-migration values. This bug was caught and fixed during testing.

Race Condition Safety (Concurrent Reads During Migration)

The migration thread operates concurrently with read requests. Four possible race windows were analyzed:

Window	State	GET Behavior	Safe?
After IPFS upload, before index add	Data in IPFS + hot, NOT in index	Hits hot → correct	✅
After index add, before hot delete	Data in IPFS + index + hot	Hits hot → correct	✅
After hot delete	Data in IPFS + index only	Index lookup → CID → IPFS Cat	✅

A stress test with 10 concurrent readers, 100 keys, and 60 seconds of continuous reads during active migration cycles confirmed zero mismatches in both Mode 2 and Mode 3.

Secondary Index Design

The secondary index (manifest) tracks where each key resides in IPFS and provides the CID needed for cold-data retrieval. It is stored in two places:

In-memory: InMemoryHashIndex backed by std::unordered_map for O(1) lookups.
Persisted: A LevelDB manifest database (<db_path>_manifest_db) that is written after each successful migration cycle and loaded on startup.

The manifest maintains range mappings for efficient range queries:

message IndexManifest {
  message RangeMapping {
    string start_key = 1;
    string end_key = 2;
    string ipfs_cid = 3;
    uint64 min_checkpoint = 4;
    uint64 max_checkpoint = 5;
  }
  repeated RangeMapping range_mappings = 1;
  uint64 total_keys = 2;
  uint64 cold_keys = 3;
  int64 last_updated_timestamp = 4;
}

The index is stored in the warm LevelDB using reserved key patterns:

Key Pattern	Description
`_tiered_manifest`	IndexManifest proto with range mappings
`_last_migrated_seq`	Persisted migration cursor for crash recovery
`_migration_status`	Last migration timestamp

Crash Recovery

On restart, TieredStorage rebuilds the InMemoryHashIndex from the persisted manifest in warm LevelDB. This ensures that all previously migrated keys remain accessible via IPFS even though the in-memory index was lost.

Four crash scenarios are handled:

Crash before manifest save: The orphan CID in IPFS is harmless (pinned data with no index entry). On restart, the key is re-migrated—the GetIndexCID check prevents re-upload since the old CID is not in the rebuilt index.
Crash after manifest save, before hot delete: The key exists in both hot storage and IPFS. On restart, GetIndexCID(key) returns the CID, so migration skips this key. GET returns the value from hot storage (correct, same value exists in both tiers).
Crash after hot delete: The key exists only in IPFS. The manifest is intact, so cold reads work normally.
Crash during migration, LevelDB block cache: The block cache is process-local and lost on crash. No stale entries survive restart.

In all cases, zero data loss is guaranteed. At worst, a key exists in multiple tiers (safe duplicate).

Benchmark Results

All benchmarks were run with 4 PBFT replicas and 1 client proxy on localhost, with IPFS daemon on loopback (127.0.0.1:5001). Timers are inserted at the storage layer using std::chrono::high_resolution_clock.

All values in microseconds (µs) unless noted:

Mode	Metric	100 Keys (p50/p95/p99)	1000 Keys (p50/p95/p99)
0 MemoryDB	Write	1 / 3 / 6	1 / 3 / 5
	Read	2 / 2 / 3	2 / 3 / 4
1 LevelDB	Write	23 / 39 / 185	23 / 43 / 64
	Read	15 / 30 / 42	17 / 30 / 47
2 LevelDB→IPFS	Hot write	24 / 71 / 141	26 / 62 / 106
	Hot read	15 / 31 / 42	18 / 30 / 50
	Index lookup	1 / 3 / 4	1 / 3 / 4
	IPFS Add	36752 / 60610 / 74283	33586 / 56612 / 67585
	Cold read	4212 / 11257 / 12525	3878 / 5351 / 5668
3 MemoryDB→IPFS	Hot write	1 / 2 / 5	1 / 3 / 6
	Hot read	2 / 2 / 3	2 / 3 / 4
	Index lookup	1 / 3 / 4	1 / 3 / 4
	IPFS Add	35241 / 58970 / 78638	35074 / 38556 / 55948
	Cold read	4341 / 5932 / 6106	4135 / 5537 / 6639

Key Findings

Tiering adds zero hot-path overhead: Mode 0 vs Mode 3 and Mode 1 vs Mode 2 show identical hot write and read latencies. The TieredStorage wrapper delegates directly to the underlying hot storage with no measurable overhead.
Index lookup is not a bottleneck: At 1µs p50, index lookups are 1000–37000× faster than any IPFS operation. The std::unordered_map provides O(1) lookups regardless of key count.
IPFS Add dominates migration: At ~35ms per key, IPFS upload is the bottleneck by two orders of magnitude. This is expected—IPFS is a content-addressed storage network, not a local filesystem. For bulk migration, batching and parallelism would improve throughput.
Cold reads are viable for archival: At ~4ms on loopback IPFS, cold reads are acceptable for infrequent access to historical data. In geo-distributed deployments, expect 50–200ms depending on network topology.
MemoryDB is 23× faster than LevelDB for writes: 1µs vs 24µs p50. Mode 3 (MemoryDB→IPFS) provides the best write throughput while retaining the ability to offload cold data.

Configuration

ResTier is configured via JSON protobuf messages in the server config file. Here is an example for Mode 3 (MemoryDB→IPFS):

{
  "storage_config": {
    "backend": 2,
    "ipfs_info": {
      "api_endpoint": "127.0.0.1:5001",
      "enabled": true,
      "gateway_endpoint": "127.0.0.1:8080",
      "timeout_ms": 30000,
      "max_retries": 3
    },
    "tiered_info": {
      "cold_threshold_checkpoint": 2,
      "enabled": true,
      "poll_interval_seconds": 5,
      "batch_size": 10,
      "auto_migration_enabled": true,
      "hot_backend": 0
    }
  }
}

Configuration Parameters

Parameter	Default	Description
`backend`	0 (MEMORYDB)	Storage mode: 0=MEMORYDB, 1=LEVELDB, 2=TIERED
`hot_backend`	0 (MEMORYDB)	Hot tier when `backend=TIERED`: 0=MEMORYDB, 1=LEVELDB
`cold_threshold_checkpoint`	2	Checkpoints to wait before data becomes eligible for migration
`poll_interval_seconds`	60	How often the migration thread checks for eligible data
`batch_size`	1000	Maximum keys migrated per cycle
`auto_migration_enabled`	false	Enables the background migration thread
`api_endpoint`	—	IPFS Kubo API endpoint (e.g., `127.0.0.1:5001`)

How to Build and Run

Prerequisites

Ubuntu 20+ with Bazel installed
Docker (for IPFS Kubo container)
LevelDB support: build with --define enable_leveldb=True

Step 1: Start IPFS Daemon

docker run -d --name ipfs-test -p 5001:5001 -p 8080:8080 -p 4001:4001 ipfs/kubo:latest

Step 2: Build

bazel build //service/kv:kv_service //service/tools/kv/api_tools:kv_service_tools \
    --define enable_leveldb=True

Step 3: Generate Certificates

./service/tools/kv/server_tools/generate_keys_and_certs.sh

Step 4: Start the Cluster

The checkpoint watermark is hardcoded to 5 (every 5 transactions triggers a checkpoint). With cold_threshold_checkpoint: 1, data becomes eligible for migration after ~10 transactions.

# Start 4 replicas + 1 client proxy
nohup bazel-bin/service/kv/kv_service service/tools/config/server/server_tiered.config \
    service/tools/data/cert/node1.key.pri service/tools/data/cert/cert_1.cert > server0.log 2>&1 &
# ... repeat for nodes 2-4 and client proxy (node 5)

Step 5: Write and Verify

# Write data
for i in $(seq 1 15); do
    bazel-bin/service/tools/kv/api_tools/kv_service_tools \
        --config service/tools/config/interface/service.config \
        --cmd set --key "test_$i" --value "val_$i"
done

# Wait for migration (sleep 10 seconds), then read cold data
bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get --key test_1
# → returns "val_1" (served from IPFS after migration)

Next Steps

ResTier is fully functional and validated for small-to-medium (100k) key counts. The following enhancements are planned:

Configurable checkpoint watermark: Currently hardcoded to 5 in platform/config/resdb_config.h. Making it configurable via TieredStorageConfig will allow predictable migration behavior across deployment environments.
Access-based tiering: Evict based on LRU access patterns instead of checkpoint age.
Compression: Compress data before IPFS upload to reduce cold storage costs.
Multi-node consistency verification: Validate that all PBFT replicas converge to identical state after independent migration.

Conclusion

ResTier demonstrates that tiered storage with IPFS cold storage can be integrated into a PBFT-based permissioned blockchain with zero write-path overhead and transparent read-path fallback. The architecture—background migration thread, O(1) in-memory secondary index, four storage modes, and interface-based hot eviction—provides a solid foundation for unbounded storage growth in ResilientDB deployments.

The system has been validated through extensive testing: end-to-end migration cycles, cold and hot reads, concurrent reads during migration (zero mismatches), crash recovery, LRU cache invalidation, stale-CID deduplication on key updates, and latency benchmarks across all four modes. ResTier is ready for production evaluation in large-scale ResilientDB deployments.

*Built on Apache ResilientDB

IPFS Kubo

PBFT Consensus*

This work is licensed under a Attribution-NonCommercial 4.0 International license.

Deep Observe: Building AI Assisted Observability for Consensus Protocols

Mon, 25 May 2026 00:00:00 +0000

Distributed databases and blockchain systems depend on consensus protocols to maintain consistency, yet few tools exist for observing protocol behavior in live deployments. Existing approaches typically rely on static simulation, offline trace replay, or intrusive instrumentation—each of which is costly and falls short of capturing runtime execution.

DeepObserve addresses this gap as an observability framework for Apache ResilientDB. As part of the DeepObserve project, we present two eBPF-based applications—ResView and ResLens—that instrument running systems with minimal code changes. Each runs as a sidecar, decoupling telemetry from the database execution path and providing low-code, language-agnostic instrumentation. DeepObserve also exposes these tools through MCP servers, enabling AI agents to connect, query runtime behavior, visualize subprotocol execution, and inspect call-stack flamegraphs.

Motivation

Observability is defined as the degree to which the internal state of a system can be inferred from its external outputs. These outputs—logs, metrics, and traces—enable operators to gauge system health, measure performance, and evaluate compliance with service-level objectives (SLOs).

Despite its importance, achieving effective observability in production distributed systems remains challenging. Conventional instrumentation relies on language-specific SDKs that embed telemetry logic directly alongside application logic. Each observability goal typically requires a dedicated toolchain: consensus visualization may depend on high-volume log ingestion through systems such as Loki or Elasticsearch, while continuous profiling requires Grafana Pyroscope or language-specific profilers. This fragmentation increases operational complexity and often forces trade-offs between visibility and performance.

Approach

DeepObserve is built on two core design decisions: running observability as a sidecar, and using eBPF for instrumentation. Together, they keep telemetry out of the database hot path while still providing protocol-aware visibility at runtime.

Why a Sidecar Pattern

In conventional observability setups, telemetry logic lives inside the application—timestamps are recorded in consensus handlers, statistics are serialized and pushed over websockets, and profiling hooks are woven through storage and execution code. This co-location creates several problems. Instrumentation competes with consensus logic for CPU and memory on the critical path, changes to observability require modifying and redeploying the database itself, and enabling or disabling telemetry often means recompilation or runtime configuration deep inside the system.

DeepObserve moves all of this into a sidecar process that runs alongside ResilientDB without sharing its execution context. The database exposes lightweight trace dispatch points; the sidecar attaches externally, collects events, and serves them to visualization frontends and MCP servers. When observability is not needed, the sidecar can be stopped entirely—the database continues running unaffected. This separation also means each observability concern (consensus tracing, continuous profiling) can evolve independently, as its own deployable unit, without destabilizing the core system.

How eBPF Enables Low-Code Instrumentation

eBPF (extended Berkeley Packet Filter) is a Linux kernel technology that allows sandboxed programs to attach dynamically to kernel and user-space execution points. For DeepObserve, the key capability is uprobes—probes that fire when specific user-space functions are invoked. We define minimal trace dispatch functions at consensus and storage boundaries in ResilientDB. When a probe is attached, eBPF captures function arguments, timestamps, and thread metadata at the point of execution. When no probe is attached, these dispatch points compile down to near-zero overhead.

This model replaces large amounts of hand-written instrumentation. The original ResView data collection path required over 600 lines of in-process telemetry code embedded across the consensus layer. The eBPF-based approach reduces this to lightweight hooks under 250 lines, with the sidecar handling collection, aggregation, and export. Because probes attach at the binary level rather than through language-specific SDKs, the same pattern extends to other subsystems and, in principle, to other consensus implementations—without rewriting application logic for each observability goal.

Applications

As part of the DeepObserve project, we present two applications:

ResView — traces and visualizes client requests through consensus protocol stages in real time.
ResLens — provides continuous CPU and memory profiling with call-stack flamegraphs for ResilientDB runtime analysis.

Both run as eBPF sidecars and are accessible to AI agents through MCP servers.

Architecture

The diagram below shows the general DeepObserve architecture: trace dispatch hooks in ResilientDB, eBPF probe attachment in the sidecar, and export to visualization frontends and MCP servers.

Figure 1. DeepObserve pipeline—ResilientDB trace hooks feed eBPF sidecars, which export telemetry to visualization frontends and MCP-connected agents.

At a high level, a client request enters ResilientDB and flows through the consensus layer. At each instrumented stage, a trace dispatch function emits metadata (sequence number, message type, sender, timestamp). The eBPF sidecar captures these events via uprobes, correlates them by request, and forwards structured traces to the ResView frontend. ResLens follows the same sidecar model but attaches profiling probes to capture CPU and call-stack samples, which are aggregated into flamegraphs. Both applications are exposed to AI agents through the DeepObserve MCP server, described below.

ResView

ResView is DeepObserve’s consensus visualization application. It traces individual client requests through the full lifecycle of a consensus protocol and renders protocol-aware diagrams from live execution data.

Features

Traces and visualizes requests through any consensus algorithm; our primary focus is PBFT (Practical Byzantine Fault Tolerance).
Visualizes each protocol stage—PRE-PREPARE, PREPARE, COMMIT, and others.
Visualizes PBFT sub-protocols such as commitment and view change.
Displays real-time message flow and timing information between replicas and clients.
Measures latency across consensus stages and quorum formation.
Helps observe leader changes and faulty replica behavior.
MCP-enabled interface allows AI agents to autonomously trigger workloads and visualize PBFT execution flows.
Migrates a manually instrumented visualization module (600+ LOC) to extensible eBPF hooks (<250 LOC).

Design

ResView’s instrumentation pipeline has three layers: lightweight hooks in the consensus code, modular eBPF probe programs in the sidecar, and consumers that render or query the parsed output.

Why hooks are needed. ResilientDB’s consensus layer is written in C++, where function names are mangled at compile time. eBPF uprobes cannot reliably attach to mangled symbols in a portable way, so we add a thin layer of trace dispatch hooks—just a few lines of formatting code per consensus stage. These hooks are called directly from the consensus logic (e.g., pre-prepare, prepare, commit, view change) and expose stable, unmangled entry points for the sidecar to attach to.

A trace hook is a minimal extern "C" function marked noinline, with arguments passed through inline assembly so eBPF uprobes can read them from registers:

__attribute__((noinline)) void resdb_trace_pbft_commit_state(
    uint64_t req_ptr, uint64_t seq, uint64_t meta, uint64_t proxy_id,
    int64_t epoch_ns) {
  asm volatile("" : : "r"(req_ptr), "r"(seq), "r"(meta), "r"(proxy_id),
               "r"(epoch_ns)
               : "memory");
}

The hook is invoked from consensus logic at the point of interest. Metadata—message type, sender, and replica ID—is packed into a single 64-bit value before the call:

int Commitment::ProcessCommitMsg(std::unique_ptr<Context> context,
                                 std::unique_ptr<Request> request) {
  // ...
  uint64_t seq = request->seq();
  uint64_t req_ptr = reinterpret_cast<uint64_t>(request.get());
  uint64_t meta_commit_recv = ResdbTracePackMeta(
      static_cast<uint32_t>(request->type()),
      static_cast<uint32_t>(request->sender_id()),
      static_cast<uint32_t>(config_.GetSelfInfo().id()));

  resdb_trace_pbft_commit_recv(
      req_ptr, seq, meta_commit_recv, proxy_id, ResdbTraceEpochNs());

  CollectorResultCode ret =
      message_manager_->AddConsensusMsg(context->signature, std::move(request));
  if (ret == CollectorResultCode::STATE_CHANGED) {
    uint64_t meta_commit_state = ResdbTracePackMeta(
        static_cast<uint32_t>(Request::TYPE_COMMIT), /*sender_id=*/0,
        static_cast<uint32_t>(config_.GetSelfInfo().id()));
    resdb_trace_pbft_commit_state(req_ptr, seq, meta_commit_state, proxy_id,
                                  ResdbTraceEpochNs());
  }
  return ret == CollectorResultCode::INVALID ? -2 : 0;
}

Sidecar and bpftrace modules. When ResView starts, the sidecar spawns a bpftrace listener for the running ResilientDB process. We define separate bpf programs for each module, each targeting a specific sub-protocol or consensus stage—commitment, view change, request intake, and others. Each module registers an uprobe on the corresponding trace dispatch hook. For example, the commitment module attaches to resdb_trace_pbft_commit_state and unpacks the packed metadata at probe time:

uprobe:/home/ubuntu/production/incubator-resilientdb/bazel-bin/service/kv/kv_service:resdb_trace_pbft_commit_state
{
  $meta = arg2;
  $type = $meta & 0xffffffff;
  $sender = ($meta >> 32) & 0xffff;
  $self = ($meta >> 48) & 0xffff;
  printf("%llu %lld %d %d commit_state %lu sender=%u self=%u proxy=%lu req=0x%lx type=%u\n",
         nsecs, arg4, pid, tid, arg1, $sender, $self, arg3, arg0, $type);
}

From probe to consumer. When a hook is invoked, the attached uprobe captures the event metadata (sequence number, message type, sender and replica IDs, timestamp) and emits it as structured log output. The sidecar parses these events, correlates them by request and replica, and reconstructs the per-request consensus timeline. The parsed traces are then exposed to downstream consumers—the ResView UI, MCP servers, and AI agents—without the database process handling any of the collection or serialization logic.

The previous ResView implementation collected statistics in-process: a data structure inside the consensus layer recorded stage timestamps and message arrivals, then pushed JSON over a websocket to the frontend. This required over 600 lines of telemetry code embedded across the consensus hot path. The eBPF redesign reduces the in-process footprint to under 250 lines of lightweight hooks—the database only declares where to trace; the sidecar and bpftrace modules decide what to capture and how to present it.

Screenshots

Figure 2. Normal-case PBFT message flow with Replica 3 as primary. All four replicas are healthy and participate across every protocol phase.
View in ResView

Figure 3. Consensus timeline for Transaction #4391 as observed by Replica 1, with per-stage latencies across pre-prepare, prepare, commit, and execution.
View in ResView

Figure 4. PBFT execution under replica failure—Replica 3 is faulty while Replica 4 serves as primary and the remaining replicas continue toward quorum.
View in ResView

Figure 5. View change triggered by Replica 3's failure. Replicas run leader election and elect Replica 4 as the new primary before broadcasting a new view.
View in ResView

Commit a transaction, then trace the resulting PBFT flow (seq 4027)
View in ResView

Retry after stopping the primary—trace captures view change (seq 4029)
View in ResView

Figure 6. The MCP trace_request tool runs after commit_key_value and opens the ResView UI for user visualization.

ResLens

ResLens is DeepObserve’s continuous profiling application. It captures CPU and memory behavior of a running ResilientDB deployment and presents call-stack flamegraphs and performance metrics through a web-based dashboard.

Features

Continuous CPU and memory profiling of ResilientDB processes with minimal overhead.
Real-time flamegraph generation for identifying hot paths in consensus and storage code.
Call-stack–level visibility into execution, correlated with request activity.
eBPF-based sampling that avoids intrusive in-process profilers.
Sidecar deployment—profiling can be enabled or disabled without restarting the database.
MCP-enabled interface allows AI agents to fetch flamegraphs and query performance data at runtime.

Design

ResLens follows the same sidecar architecture as ResView, but targets continuous profiling rather than consensus tracing. Profiling runs externally from the ResilientDB process—the database does not need to embed profilers or expose custom hooks beyond being a target process for the sidecar to attach to.

Pyroscope and eBPF profiling. ResLens builds on Pyroscope, an open-source continuous profiling platform. We use an older version of Pyroscope specifically for its ad-hoc eBPF profiler, which supports attaching to a process that is already running without restart or recompilation. The sidecar configures Pyroscope’s eBPF spy tool to attach to the live ResilientDB process and sample CPU call stacks at runtime.

Server and client. Pyroscope provides two components that ResLens orchestrates as part of the sidecar. The server runs locally and exposes interactive flamegraphs on port 4040. The client is configured to target the ResilientDB process—when attached, it continuously collects stack samples and forwards them to the server for aggregation and visualization. The ResLens frontend reads from this Pyroscope server to render flamegraphs and profiling metrics in the dashboard.

AI-accessible flamegraph analysis. To enable AI agents to reason over profiling data, ResLens converts flamegraphs into a structured text representation using pprof. The exported markdown captures the call-stack hierarchy and sample counts in a format that MCP-connected agents can parse and query—allowing natural-language questions such as which functions dominate CPU time during consensus execution, without requiring the agent to interpret raw binary profile data or interact with the Pyroscope UI directly.

Screenshots

Figure 7. Split view pairing a ranked execution-time table with an interactive flamegraph, where each bar's width reflects CPU time spent in that function.
View in ResLens

Figure 8. Sandwich view centered on InternalConsensusCommit, with callers above and callees below—useful for tracing which functions a hot path invokes and what invokes it.
View in ResLens

Figure 9. From profile to source code—selecting View Code on a flamegraph span (top) opens a GitHub search for that function's definition in the ResilientDB repository (bottom).
View in ResLens

Structured profile summary—flat and cumulative sample percentages per function

AI-assisted analysis—bottlenecks grouped by network I/O, cryptography, and polling

Figure 10. Two ways to interpret the same CPU profile: a deterministic summary when AI is unavailable (left), and an AI-generated breakdown that categorizes bottlenecks and suggests optimizations (right).
View in ResLens

Figure 11. The MCP trace_profile tool opens a web browser and queries the flamegraph to answer user queries—in this case, identifying SetValue as the function used to commit values in the PBFT flow.
View in ResLens

MCP Implementation

AI agents interact with DeepObserve through an MCP server built on FastMCP. Rather than exposing ResView and ResLens as separate endpoints, the server acts as an MCP hub—a single interface that combines database operations, observability UI tools, and proxied integrations with external MCP servers such as Prometheus and Grafana.

The entry point is server.py, which registers three layers of capability:

Database tools (src/database/tools.py) — commit_key_value and get_key_value submit and retrieve transactions against ResilientDB through a REST client, returning structured responses that include the sequence number assigned to each commit.
Observability UI tools — tools such as trace_request and trace_profile return MCP UI resources that embed live ResView and ResLens URLs directly in the agent’s chat interface. When an agent calls trace_request with a sequence number, the tool constructs a filtered ResView URL and returns it as an embeddable resource—the client opens the visualizer without the user navigating manually. Similarly, trace_profile opens ResLens with query parameters so the agent can inspect flamegraph data while answering performance questions.
Proxied MCP servers (src/mcp_hub/proxy.py) — external servers for Prometheus and Grafana are mounted with prefixed tool names (e.g., prometheus_query), giving agents access to metrics and dashboards through the same hub.

This design enables multi-step agent workflows entirely through natural language. An agent can call commit_key_value to insert a transaction, read the returned sequence number, invoke trace_request to open the PBFT visualization for that request, and then call trace_profile to inspect which functions dominated CPU time—all without leaving the conversation. The server runs over SSE transport on port 3500 by default and can be deployed via Docker using the configuration in the repository.

Conclusion

DeepObserve shows that observability for consensus protocols does not require heavy in-process instrumentation or protocol-agnostic trace pipelines. By combining eBPF sidecars with MCP-accessible tooling, ResView and ResLens provide protocol-aware visualization and continuous profiling for ResilientDB—with under 250 lines of lightweight hooks, decoupled sidecar deployment, and an interface that both developers and AI agents can use to understand runtime behavior at the granularity of individual requests and function calls.

The demonstrations in this post cover the full path from motivation to implementation: normal and fault-tolerant PBFT execution, view change sub-protocols, flamegraph analysis across multiple view modes, and agent-driven workflows that commit transactions and immediately visualize the results. Together, these pieces form a practical observability stack for distributed consensus—one that stays out of the hot path while making live protocol behavior legible to humans and machines alike.

Source Code

The DeepObserve MCP server, deployment configuration, and tool implementations are available in the DeepObserve repository. Live demos are available at ResView and ResLens.

Demo Video

Watch the full walkthrough on YouTube.

ResPulse: Performance Regression Detection and Explanation for ResilientDB

Fri, 22 May 2026 00:00:00 +0000

In the world of distributed systems and blockchain infrastructure, performance monitoring isn’t just helpful, it’s essential. Today, we’re excited to introduce ResPulse: A comprehensive performance monitoring and regression detection system, a sophisticated tool designed specifically for monitoring PBFT consensus performance in real-world deployments.

The Challenge: Monitoring PBFT Consensus Performance

Modern blockchain systems like ResilientDB rely on complex consensus protocols that must maintain both security and performance under varying conditions. Traditional monitoring approaches often fall short when it comes to:

Understanding consensus-specific metrics like PBFT phase timing and replica coordination overhead
Detecting performance regressions before they impact production workloads
Providing actionable insights that help developers optimize consensus parameters
Correlating performance degradation with specific code changes or system conditions

ResPulse addresses these challenges head-on with a comprehensive solution built specifically for ResilientDB’s PBFT implementation.

Architecture Overview

ResPulse consists of four main components:

Figure 1: System architecture showing the main components and data flow

1. Performance Testing Engine (`perf_test.sh`)

At the core of our system is a bash-based performance testing engine that:

Executes realistic transaction workloads against ResilientDB endpoints
Captures detailed timing metrics using curl’s built-in timing capabilities
Measures end-to-end latency including TCP connection time, server processing time, and response transfer time
Supports configurable test parameters for different workload patterns

The testing engine generates structured timing data that captures every aspect of request processing:

# Example: Running 100 performance tests with version tagging
bash perf_test.sh 100 "v2.1.0-optimization-branch"

2. Advanced Metrics Analysis (`analyze.py` & `analyze_record.py`)

Our analysis engine transforms raw timing data into meaningful performance insights:

Core Metrics Calculation

Total Latency: End-to-end request completion time
Consensus Time: Server-side processing time (PBFT phases, queuing, execution)
TCP Connect Time: Network connection establishment overhead
Transfer Time: Response payload transmission time
Throughput: Requests per second under sequential load
Success Rate: Percentage of successfully completed transactions

Statistical Analysis

The system computes comprehensive statistical summaries including:

Mean, median, min, max values
Standard deviation for variance analysis
P95 and P99 percentiles for tail latency detection
Historical baseline comparisons with percentage change calculations

AI-Powered Analysis Integration

A breakthrough feature of our system is its integration with Deepseek AI for intelligent performance analysis:

# AI analysis replaces traditional pattern recognition
ai_analysis = get_ai_analysis(record, baseline, period_label)

The AI system:

Analyzes complex performance patterns that simple thresholds might miss
Provides contextualized recommendations specific to PBFT consensus optimization
Generates human-readable reports explaining performance bottlenecks
Adapts analysis based on historical trends and system behavior patterns

3. Real-Time Dashboard (`regression_UI`)

Built with React and Recharts, our dashboard provides:

Figure 2: Main dashboard showing real-time performance metrics and trends

Interactive Visualizations

Time-series charts showing latency, throughput, and consensus timing trends
Configurable time ranges from 24 hours to all-time historical data
Anomaly detection highlighting unusual performance values
Baseline comparison overlays for regression identification

Live Monitoring Features

Real-time status cards displaying current system health
Auto-refresh capabilities with configurable intervals
Detailed drill-down views for individual test runs
Performance trend analysis with statistical summaries Figure 3: The system’s analysis of a test run
Key Dashboard Components

// Main monitoring dashboard with comprehensive metrics
export default function ResilientDBMonitor() {
  // Features include:
  // - Live connection status and performance metrics
  // - Interactive charts with anomaly detection
  // - Historical baseline comparison
  // - Auto-refresh with manual override capability
}

4. Intelligent Alerting System

Our alerting system provides proactive monitoring with:

Automated Regression Detection

The system automatically:

Compares current performance against historical baselines
Detects statistical anomalies using configurable thresholds
Identifies performance degradation across multiple metrics simultaneously
Calculates regression severity based on multiple warning signals

Configurable Baseline Periods

A key innovation in our alerting system is flexible baseline comparison periods for scheduled tests. Instead of being locked to a fixed timeframe, users can now choose the most appropriate historical baseline:

1 Week: Ideal for detecting short-term performance changes and immediate impact assessment
1 Month: Balances recent trends with sufficient statistical stability
3 Months: Provides robust baseline for quarterly performance evaluation
6 Months: Default option offering comprehensive long-term trend analysis
1 Year: Maximum historical context for annual performance reviews

Intelligent Data Validation

The system automatically validates data availability for each baseline period:

Minimum threshold enforcement: Requires at least 3 historical results for meaningful statistical comparison
Real-time availability checking: UI dynamically shows available vs. insufficient data periods
Data count indicators: Displays the exact number of historical results available for each timeframe
Smart defaults: Automatically selects the most appropriate available period if user’s choice lacks sufficient data

Flexible Notification System

Originally built with Resend, we’ve recently migrated to Nodemailer for greater flexibility:

// Multi-provider email support
function createTransporter() {
  const provider = process.env.EMAIL_PROVIDER || "gmail";

  switch (provider.toLowerCase()) {
    case "gmail": return nodemailerGmailTransport();
    case "outlook": return nodemailerOutlookTransport();
    case "smtp": return nodemailerCustomSMTP();
  }
}

Scheduled Monitoring

Configurable test schedules (hourly, daily, weekly, monthly)
Automatic regression detection after each scheduled test
Email notifications with detailed performance analysis
Rich HTML reports showing performance trends and recommendations

Figure 4: Scheduling Tests and Alert System Figure 5: Automated regression alert with detailed performance metrics

Key Features and Innovations

1. PBFT-Specific Metrics

Our system is uniquely designed for PBFT consensus monitoring:

Consensus Phase Timing: Distinguishes between network overhead and actual consensus processing
Replica Coordination Analysis: Identifies bottlenecks in multi-replica coordination
Batch Processing Metrics: Analyzes the impact of batching parameters on throughput
Tail Latency Detection: Identifies consensus stalls and synchronization delays

2. AI-Powered Analysis

The integration with Deepseek AI represents a significant advancement in performance analysis:

# AI generates contextualized performance insights
prompt = f"""
You are a ResilientDB performance expert. Analyze these PBFT consensus metrics:
- Average Latency: {record.get('avg_latency_ms')}ms
- Throughput: {record.get('throughput_rps')} req/s
- Server Wait Time: {record.get('consensus_time_ms', {}).get('mean')}ms

Provide specific technical recommendations for PBFT optimization.
"""

The AI system provides:

Context-aware recommendations based on PBFT consensus theory
Root cause analysis for performance bottlenecks
Optimization suggestions for consensus parameters
Performance trend interpretation with actionable insights

Figure 6: AI-generated performance analysis with actionable recommendations

3. Comprehensive Regression Detection

Our regression detection algorithm analyzes multiple dimensions:

const METRICS = [
  { id: "latency",    field: "avg_latency_ms",    lowerBetter: true  },
  { id: "consensus",  field: "consensus_ms_mean", lowerBetter: true  },
  { id: "throughput", field: "throughput_rps",    lowerBetter: false },
  { id: "success",    field: "success_rate",      lowerBetter: false },
];

The system:

Calculates dynamic baselines from recent performance history
Applies configurable thresholds for each metric type
Considers metric interdependencies for holistic analysis
Generates severity scores based on multiple regression signals

4. Developer-Friendly Integration

The system is designed for seamless integration into development workflows:

Easy Setup and Configuration

# Simple environment-based configuration
EMAIL_PROVIDER=gmail
EMAIL_USER=your-email@gmail.com
DEEPSEEK_API_KEY=your-deepseek-key

# Run performance tests
bash perf_test.sh 1000 "feature-branch-testing"

MongoDB Integration

Persistent storage of all performance data
Efficient querying for historical analysis
Scalable data architecture supporting long-term trend analysis

RESTful API

// Express.js backend with comprehensive API endpoints
app.get('/api/results', getResults);           // Historical data
app.post('/api/results/:id/analyze', analyzeResult); // AI analysis
app.get('/api/schedule', getScheduleConfig);   // Monitoring configuration

Technical Architecture Decisions

Choice of Technologies

Our technology stack reflects careful consideration of performance monitoring requirements:

Python for analysis: Leverages scientific computing libraries for statistical analysis
Node.js for backend: Provides excellent performance for real-time data processing
React for frontend: Enables responsive, interactive data visualization
MongoDB for storage: Offers flexible schema for evolving metrics collection

Performance Considerations

The monitoring system itself is optimized for minimal overhead:

Efficient data collection using curl’s native timing capabilities
Asynchronous processing to avoid blocking performance tests
Intelligent caching for dashboard responsiveness
Configurable refresh intervals balancing freshness with resource usage

Scalability Design

The system architecture supports growing monitoring needs:

Horizontal scaling of backend services
Database sharding for high-volume data storage
Modular component design enabling feature expansion
API-first architecture supporting multiple frontend clients

Getting Started

Setting up ResPulse is straightforward:

Prerequisites

A ResilientDB GraphQL instance running locally. For setup instructions, see the ResilientDB GraphQL README.
Python 3.x with required packages
Node.js 18+ for backend services
MongoDB instance for data persistence

Installation Steps

Clone the repository:

git clone https://github.com/resilientdb/incubator-resilientdb
cd ecosystem/monitoring/resPulse

Configure environment variables:

# Backend configuration
cp backend/.env.example backend/.env
# Edit with your MongoDB URI, email settings, AI API keys

Start the services:

# Backend API
cd backend && npm install && npm start

# Frontend dashboard
cd resPulse_UI && npm install && npm run dev

Run your first performance test: Open the dashboard in your browser and click the “Run Test” button to execute your first performance benchmark.

Configuration Options

The system supports extensive configuration:

Test parameters: Request count, endpoint URLs, payload customization
Analysis settings: AI API configuration, statistical thresholds
Alerting setup: Email providers, notification schedules, regression thresholds
Dashboard preferences: Time ranges, metrics display, refresh intervals

Future Developments

We’re continuously expanding the monitoring system’s capabilities:

Automated Pull Request Testing

One of the most exciting planned features is automated performance testing triggered by code changes. This system will:

Monitor Repository Changes: Using GitHub webhooks or CI/CD pipeline integration, automatically detect when Pull Requests are created or updated that modify ResilientDB core components.

Triggered Testing: Automatically execute performance benchmarks against the proposed changes, comparing results with baseline performance metrics from the main branch.

Performance Impact Analysis: Generate detailed reports showing whether code changes improve, degrade, or maintain performance across key metrics like consensus latency, throughput, and resource utilization.

Implementation Approach: This can be implemented by integrating with GitHub Actions or similar CI/CD platforms, where the performance testing suite runs as part of the PR validation process. The system would deploy the proposed changes in a controlled environment, run the existing performance test suite, and automatically post results as PR comments.

This automated approach ensures that performance regressions are caught early in the development cycle, maintaining ResilientDB’s performance standards while enabling rapid development iteration.

Other Developments

Custom metrics integration for application-specific monitoring
Enhanced AI analysis with multi-model comparison capabilities

Contributing and Community

ResPulse is part of the Apache ResilientDB project and welcomes community contributions:

Feature requests and bug reports via GitHub Issues
Code contributions through pull requests with performance validation
Documentation improvements to support broader adoption
Performance testing across different deployment scenarios

Conclusion

ResPulse represents a significant advancement in blockchain infrastructure monitoring. By combining PBFT-specific metrics collection, AI-powered analysis, and comprehensive regression detection, it provides developers and operators with the tools they need to maintain optimal performance in distributed consensus systems.

Whether you’re developing new features for ResilientDB, operating a production deployment, or researching consensus protocol optimizations, this monitoring system provides the insights and automation needed to ensure peak performance.

The system’s modular architecture, comprehensive documentation, and active community support make it an ideal choice for organizations looking to implement robust performance monitoring for their ResilientDB infrastructure.

Ready to get started? Visit our GitHub repository for installation instructions and documentation. Join our community and help us build the future of blockchain performance monitoring.

About ResilientDB

ResilientDB is a high-performance permissioned blockchain fabric designed for modern distributed applications. With its focus on PBFT consensus and optimal performance, ResilientDB provides the foundation for secure, scalable blockchain solutions. Learn more at resilientdb.com.

ResInsight: AI-Driven Developer Onboarding for ResilientDB

Wed, 15 Apr 2026 00:00:00 +0000

The Problem:

Today’s business applications are complex in nature with interleaved tech stacks with a mix of libs & frameworks, code bases are evolving rapidly on composable & interoperable stacks. E.g. code delivered 3-months back might look very different depending on the issues resolved or features built or new tech stack inclusion For an unknown/new repo, there is no choice than to rely on README pages and manual code browsing. For an existing repo, one must browse through the commit logs to understand changes in each file and the associated impact. Thus, code repositories (repo here onwards) have become increasingly difficult to build understanding on the functional dependencies. But you might be thinking that ChatGPT or Claude can do this so easily so why is this tool required? You are correct. Let us explore it through a story first and then deep dive:

My First Quarter Experience

During my first quarter at UC Davis, I took ECS 265, a course focused on distributed database systems and blockchain technology using ResilientDB. Like many of my classmates, I came in with limited exposure to distributed systems. We were tasked with understanding ResilientDB’s architecture, its consensus protocols, and building projects using the existing applications.

The learning curve was real. ResilientDB is a powerful, well-architected blockchain platform, its sophistication is one of its greatest strengths. But that same sophistication meant there was a lot to understand: from Byzantine fault tolerance theory to the practical aspects of getting a development environment running.

Many of us found ourselves in a cycle: reading through documentation, trying to set things up, hitting errors we didn’t understand, and then relying on groupmates who had managed to get their environments working. Some students spent most of the quarter developing on their teammate’s setup rather than their own, not because they didn’t want to figure it out, but because troubleshooting took time away from actually learning the concepts and building projects.

This wasn’t anyone’s fault. ResilientDB, as an active research platform, evolves quickly, which is excellent for pushing blockchain innovation forward. But it also means documentation and setup procedures are constantly catching up. The platform’s comprehensiveness is a feature, not a bug. However, for newcomers, this creates a genuine challenge.

Where Existing AI Tools Failed Us

Here’s what made this harder: we couldn’t just ask ChatGPT or Claude for help.

When you ask ChatGPT about ResilientDB:

It gives you generic blockchain advice that may or may not apply to our specific implementation
It hallucinates repository structures that don’t exist in ResilientDB
It can’t access actual code from our repositories to verify its suggestions
It provides outdated setup instructions based on whatever documentation it found during training
It doesn’t know about ResilientDB-specific applications like Debitable, Arrayán, or ResCounty
It can’t distinguish between theoretical PBFT and how ResilientDB actually implements it

The fundamental gap: General-purpose AI tools lack context about your specific codebase. They’re trained on public data but have no connection to your actual repositories, your project’s conventions, or your domain-specific implementations.

This gap becomes especially challenging for research platforms where:

Code evolves faster than public documentation can keep up
Internal applications and recent features aren’t well-represented in AI training data
Setup procedures vary based on specific use cases and environments
Understanding requires connecting theoretical concepts (like PBFT consensus) with their actual implementation in your codebase

But can’t I just describe what I need to an AI and have it build the solution? Here’s why that doesn’t solve the core problem:

The Knowledge Problem: ChatGPT doesn’t know about your specific codebase. It can’t tell you which files implement consensus in ResilientDB, where transaction processing actually happens, or how different modules connect, because it’s never analyzed your repositories.

The Access Problem: AI chat tools can’t authenticate to your repositories, can’t make GitHub API calls on your behalf, and can’t maintain persistent indexes of your evolving code.

The Integration Problem: Even if you copy-paste code snippets to ChatGPT, it processes them in isolation. It can’t build a knowledge graph of your entire repository, maintain vector embeddings for semantic search across your whole codebase, or track dependencies and relationships across files.

The Consistency Problem: Every time you ask ChatGPT about your code, you need to provide context again. There’s no persistent memory of your codebase structure, previous analyses, or the specific questions you’ve already explored. ChatGPT has a memory which is limited and once its full you need to clear it. If you have any questions, you will have to give the entire context again and repeat the process.

The Verification Problem: When ChatGPT suggests something about ResilientDB’s implementation, how do you know if it’s accurate? There’s no way to trace its answer back to actual code or verify it against current repository state.

What we needed wasn’t just an AI tool that could answer questions, we needed a tool that’s connected to our actual codebase and can retrieve, analyze, and verify information from our specific repositories and applications.

The Solution: ResInsight MCP Server

ResInsight bridges this gap by connecting AI agents directly to your GitHub repositories through the Model Context Protocol (MCP). Instead of asking ChatGPT general questions and getting generic answers, you can now ask questions like:

“Show me all files related to transaction processing in ResilientDB”
“How does the PBFT consensus implementation connect to the executor layer?”
“What are the dependencies for the Debitable application?”

And get answers based on your actual codebase, not generic blockchain knowledge.

What Makes ResInsight Different

1. Repository-Aware Intelligence

ResInsight doesn’t guess, it knows. When you ask about a feature, it:

Searches your actual codebase using semantic embeddings
Analyzes the real file structure from your GitHub repository
Provides answers based on current code, not outdated documentation

2. Hybrid Search Architecture

Traditional code search is limited to exact keyword matching. ResInsight combines:

FAISS Vector Search: Understands code semantically (“find Byzantine fault tolerance logic” finds relevant code even without exact keywords)
NetworkX Knowledge Graphs: Maps structural relationships between files, showing you how modules actually connect

This means you can ask conceptual questions (“where does transaction validation happen?”) and get accurate results.

3. Domain-Specific ResilientDB Knowledge

ResInsight includes a curated knowledge base covering:

Setup procedures for all 14+ ResilientDB applications
Architectural explanations connecting theory to implementation
PBFT consensus mechanisms specific to ResilientDB
Performance benchmarks and optimization strategies

When you ask about ResilientDB concepts, you get answers from expert-curated content, not generic blockchain information scraped from the internet.

4. Private Repository Access

Unlike public AI tools that only work with open-source code, ResInsight:

Authenticates with GitHub to access your private repositories
Works with internal lab projects and course assignments using authentication
Respects your access permissions, you only see repos you have access to

5. Tool-First Design

Every capability is exposed as a discrete tool that can be inspected, tested, and verified. Instead of opaque AI responses, you get:

Explicit tool calls showing what data was retrieved
Reproducible results, same query always returns same data
No hallucination, answers come from actual repository data, not AI imagination

Core Capabilities

Repository Analysis

ResInsight provides comprehensive repository analysis through specialized tools:

File Navigation: Quickly understand repository structure without manually browsing hundreds of files. The system intelligently handles both small and large repositories, automatically switching between API strategies for optimal performance.

Semantic Code Search: Find code by meaning, not just keywords. Using sentence transformers and FAISS indexing, ResInsight understands that “Byzantine fault tolerance handling” and “BFT consensus logic” refer to similar concepts.

Function Extraction: Get instant overview of what a file does by extracting its function definitions, class structures, and key components, without reading hundreds of lines of code.

Setup Assistance

One of the most time-consuming aspects of working with new codebases is getting your environment configured correctly. ResInsight automates this:

Dockerfile Analysis: Instead of manually parsing Docker commands, ResInsight breaks down Dockerfile instructions step-by-step, explaining dependencies and configuration choices.

Interactive Troubleshooting: When you hit setup errors, ResInsight can analyze error messages in the context of your specific repository and provide targeted solutions.

Environment Validation: Verify that your setup matches repository requirements before you waste time debugging environment issues.

Dependency Visualization

Understanding how code is organized is crucial for effective development. ResInsight generates visual dependency graphs showing:

Module import relationships
Component interconnections
Architectural patterns

This visual representation helps you quickly grasp code organization that would take hours to piece together manually.

ResilientDB Knowledge Base

The integrated knowledge base provides instant answers to common ResilientDB questions:

“How do I set up Debitable?” → Step-by-step guide with prerequisites and configuration “What is Arrayán?” → Application overview, use cases, and integration points “How does PBFT work in ResilientDB?” → Consensus mechanism explained with implementation details

This eliminates the frustration of searching through multiple repositories and documentation sources.

Real Impact: Before and After

Scenario: First-Time Repository Setup

The Traditional Experience:

In ECS 265, getting ResilientDB running locally was often the first major hurdle. The process typically went like this:

Read through README files across multiple repositories
Try following setup instructions
Hit environment-specific errors that weren’t documented
Search for error messages online (often finding nothing ResilientDB-specific)
Ask classmates or wait for TA office hours
Eventually get it working through trial and error, or develop on a groupmate’s setup

This could take 2-3 days of a student’s time, not learning distributed systems concepts, but wrestling with configuration issues.

With ResInsight:

The same student can now ask: “How do I set up ResilientDB locally?”

ResInsight:

Analyzes the actual Dockerfile from the repository
Breaks down each installation step with context
Explains what each dependency does and why it’s needed
Provides troubleshooting guidance for common environment issues
Answers follow-up questions as they arise during setup

Result: 4-6 hours to a working environment, with the student understanding why each step matters, not just following commands blindly.

The Real Impact: More time spent learning distributed systems and building projects, less time fighting with Docker and dependency versions.

Scenario: Understanding Code Architecture

The Traditional Experience:

When tasked with understanding how a feature works in ResilientDB (say, transaction processing), students typically:

Manually browsed through repository files, trying to guess which ones were relevant
Attempted to piece together module relationships from import statements
Searched for specific implementations across multiple files
Asked senior developers or TAs to explain the architecture
Spent hours building mental models that could have been generated in minutes

For someone new to distributed systems, connecting these pieces, understanding both what the code does and why it’s structured that way, was genuinely challenging.

With ResInsight:

A student can now ask: “Show me files related to transaction processing in ResilientDB”

ResInsight:

Performs semantic search across the codebase
Returns relevant files ranked by actual relevance to the concept
Generates a dependency graph showing how components connect
Answers follow-ups like “How does this connect to the consensus layer?”

Then ask: “Explain how PBFT is implemented here”

ResInsight:

Pulls explanation from the ResilientDB-specific knowledge base
Shows which actual files implement different PBFT phases
Connects theoretical concepts to practical implementation

Result: Understanding in minutes instead of hours, with the ability to verify everything against actual code.

The Real Impact: Students can explore the codebase independently, at their own pace, building understanding incrementally rather than waiting for explanations.

Scenario: Exploring ResilientDB Applications

The Traditional Experience:

When assigned to work with a ResilientDB application like Debitable or Arrayán:

Clone the repository and hope the README is current
Try to understand dependencies by reading package.json or requirements.txt
Look for example code or tutorials (often finding none)
Attempt setup following possibly outdated instructions
Debug environment issues specific to that application
Eventually piece together understanding through experimentation

This exploration phase could consume significant time that should have been spent on project development.

With ResInsight:

A student working on Debitable can ask: “What is Debitable and how does it integrate with ResilientDB?”

ResInsight:

Retrieves curated overview from the ResilientDB knowledge base
Explains Debitable’s purpose, architecture, and key features
Shows the file structure and identifies key components
Provides setup guidance specific to Debitable’s requirements
Answers follow-ups about GraphQL integration, data models, or specific features

Then ask: “Show me how Debitable handles data uploads”

ResInsight:

Uses semantic search to find relevant React components
Identifies files like DataUploader.jsx, InventoryPage.jsx
Shows how these connect to ResilientDB API calls

Result: From zero understanding to basic comprehension in 15-20 minutes, with confidence to start building.

The Real Impact: Students spend their time building features and experimenting with blockchain concepts, not deciphering project structure.

Technical Architecture

Model Context Protocol (MCP)

ResInsight is built on the Model Context Protocol, which provides a standardized way for AI applications to connect with external data sources. This architecture enables:

Persistent Context: Repository data is indexed once and queried many times
Tool Composition: Multiple specialized tools work together for complex queries
Extensibility: New tools can be added without changing the core system
Vendor Agnostic: Works with Claude, could support other LLMs

Search and Retrieval System

The hybrid search architecture combines complementary approaches:

Vector Embeddings (FAISS):

Code chunks converted to 768-dimensional embeddings
Semantic similarity search enables conceptual queries
Fast retrieval even with millions of code chunks

Knowledge Graphs (NetworkX):

File dependencies mapped as directed graphs
Import relationships explicitly modeled
Structural queries like “what imports this module?”

Repository Indexing:

Intelligent chunking maintains context
Metadata tracking preserves file/line information
Incremental updates for large repositories

Authentication and Security

Security is built into every layer:

MCP Token Authentication: All client requests require valid tokens
GitHub PAT Authorization: Read-only repository access
Environment-Based Secrets: No credentials in code
Request Validation: All inputs sanitized and validated

How to Use ResInsight

ResInsight can be used in two ways: connect to the hosted ResilientDB deployment, or run your own local copy if you want to self-host or modify the server.

Option 1: Use the hosted ResilientDB deployment

If you only want to use ResInsight, you do not need to clone the repository. Point your MCP client at the hosted HTTP endpoint:

http://52.45.172.212:8005/mcp

Important details:

Use the /mcp endpoint directly.
The server is running in Docker as resinsight with port mapping 8005:8005.
Use an MCP client that supports HTTP transport, such as Cursor or Claude Desktop.
Add the Bearer token issued by the lab to your client configuration.
Do not rely on / or /mcp/tools; those paths are not the supported client entry point.

Option 2: Run it locally

If you want to run your own instance, clone the repository and start the MCP server locally:

Clone the repo and move into the ResInsight directory.
Create and activate a Python virtual environment.
Install dependencies from requirements.txt.
Create a .env file with your GITHUB_TOKEN and a locally chosen MCP_TOKEN.
Start the server with python server.py, or build and run the Docker image if you prefer containers.

For local use, your MCP client should send the same MCP_TOKEN value that the server reads from .env. For cloud use, the client must send the Expo Lab team-issued token for the hosted endpoint.

MCP client configuration

Now, to configure an MCP client use one of the following two options depending on the option that you chose above to run the application:

Use command-based MCP configuration only when you are running ResInsight locally (self-hosted):

 {
     "mcpServers": {
         "resinsight": {
             "command": "python",
             "args": ["C:/path/to/incubator-resilientdb/ecosystem/ai-tools/mcp/ResInsight/server.py"],
             "env": {
                 "GITHUB_TOKEN": "ghp_...",
                 "MCP_TOKEN": "your_local_secret_or_team_issued_token"
             }
         }
     }
 }

In this python + server.py setup, do not place the /mcp URL inside args. The args field is only the local script path.

HTTP transport clients like Claude

If your application supports native remote HTTP MCP entries, configure the deployed endpoint like this:

 {
     "url": "http://52.45.172.212:8005/mcp",
     "headers": {
         "Authorization": "Bearer MCP_TOKEN"
     }
 }

For Claude use:

 {
     "mcpServers": {
         "ResInsight: AI-driven developer onboarding ecosystem": {
             "command": "npx",
             "args": [
                 "-y",
                 "mcp-remote",
                 "http://52.45.172.212:8005/mcp",
                 "--header",
                 "Authorization: Bearer MCP_TOKEN"
             ],
             "env": {
                 "MCP_REMOTE_CONFIG_DIR": "C:/Users/your-user/.mcp-auth"
             }
         }
     }
 }

 `MCP_REMOTE_CONFIG_DIR` is optional. Keep it only if you want to control where bridge auth/session files are stored.

Important: keep a space after Bearer in the header value (Authorization: Bearer ...).

The direct Claude local setup (python + server.py) remains the preferred self-hosted option. The deployed endpoint should be configured with the /mcp URL in the remote HTTP settings (or bridge argument), not in Python script args.

For local self-hosted runs, replace the hosted URL with http://localhost:8005/mcp and use the token from your own .env file.

Note: command + args appears in both modes. For local mode, command launches `python server.py`. For deployed mode in some clients, command launches an HTTP bridge tool (such as `mcp-remote`) that forwards to the `/mcp` URL.

Measuring Success

The real measure of ResInsight’s impact isn’t in technical metrics, it’s in changed developer experiences:

Time Savings: Tasks that took days now take hours. Questions that required waiting for senior developers get answered immediately.

Independence: New developers can explore and learn at their own pace, without constantly interrupting others.

Confidence: When setup actually works the first time, when you understand why code is structured a certain way, when you can find what you need, that confidence compounds over time.

Knowledge Access: Information that was previously locked in senior developers’ experience is now available to everyone.

What’s Next

ResInsight represents a first step toward making sophisticated codebases more accessible. Future directions include:

Automated PR Analysis: Intelligent code review suggestions based on repository conventions and patterns

Interactive Learning Paths: Guided tutorials that adapt based on your questions and progress

Team Knowledge Sharing: Capture and share team-specific insights and best practices

Multi-Repository Understanding: Answer questions that span multiple related repositories

A Note on Scope

ResInsight is designed for a specific problem: helping developers understand and work with existing codebases. It’s not trying to replace developers, automate all coding tasks, or solve every development challenge.

What it does do is eliminate the frustrating parts of onboarding, the hours spent searching for the right file, the days debugging environment setup, the uncertainty about whether you’re understanding things correctly.

By handling these mechanical tasks, ResInsight lets developers focus on what matters: understanding concepts, building features, and solving real problems.

Getting Involved/Contact

ResInsight is open source and available to the ResilientDB community. If you’re a student taking ECS 265, a lab member working on ResilientDB projects, or a researcher exploring the platform, you can start using ResInsight today.

For access, contact kunjalagrawal2002@gmail.com or Prof. Sadoghi at msadoghi@expolab.org / msadoghi@ucdavis.edu.

The code is available at: ResInsight

Contributions are welcome, whether it’s improving the knowledge base, adding new tools, or enhancing search capabilities.

Acknowledgments

This project was inspired by the collaborative spirit of the ExpoLab community. Special thanks to:

Fellow ECS 265 students who helped me clearly understand what issues they faced when they took ECS 265 and when they started working with ResilientDB.
ExpoLab team for supporting this work
Professor Mohammad Sadoghi for his guidance throughout the project.

Conclusion

ResInsight was born from a genuine need I experienced as a student learning distributed systems and blockchain technology. It’s not trying to replace the excellent work being done by the ResilientDB team, the growing documentation efforts, or the collaborative spirit of the ExpoLab community.

Instead, ResInsight addresses a specific gap: the mechanical obstacles that slow down learning. It handles the frustrating parts, finding the right file, understanding repository structure, debugging setup issues, so developers can focus on what matters: grasping distributed systems concepts, understanding consensus mechanisms, and building innovative applications.

What This Changes

For future ECS 265 students and new ResilientDB developers, ResInsight means:

Independence: Learn at your own pace without waiting for office hours or interrupting teammates Confidence: Verify your understanding against actual code, not guesses Efficiency: Spend time on concepts and projects, not configuration struggles
Accessibility: Expert knowledge available 24/7, not locked in senior developers’ heads

The Broader Picture

As ResilientDB continues to grow, more applications, more features, more complexity,tools like ResInsight become increasingly valuable. They ensure that the platform’s sophistication enhances rather than hinders its accessibility.

This is especially important for an academic research platform where:

New students join each quarter with varying backgrounds
Code evolves rapidly with cutting-edge research
Learning happens alongside building
Time spent stuck on setup is time not spent learning

Tags: #ResilientDB #DeveloperExperience #AI #MCP #Onboarding #ExpoLab

ResInsight is part of the ResilientDB ecosystem. Learn more about ResilientDB at expolab.resilientdb.com

Charitap: Transforming Spare Change into Social Impact

Wed, 25 Feb 2026 00:00:00 +0000

Giving back shouldn’t be difficult, yet many potential donors are held back by a lack of transparency, and the friction of complicated donation processes. Traditional models often pressure individuals to make large, one-time contributions, which can feel overwhelming and lead to a total deterrent from regular giving.

Charitap changes this narrative by making philanthropy effortless.

Useful Links

Website is live at: https://charitap-frontend.vercel.app

Code Repository: https://github.com/ResilientApp/Charitap

Presentation Slides: https://github.com/ResilientApp/Charitap/blob/chrome-extension/Presentation%20-%20Charitap.pdf

Demo: https://drive.google.com/file/d/1hs5s6Y1NnB4djBBSIoU4bPaFRvC6t5Mp/view?usp=sharing

The Motivation: Why We Built This

Many people genuinely want to help but struggle to choose charities wisely or track exactly where their funds go.

The "Milk" Use Case: Low-Pressure Philanthropy Imagine the simplicity of a routine trip to the grocery store. You buy a gallon of milk for $3.60. In a traditional setting, you might be asked to donate $5 or $10 at the register, which feels like a "pressure point."

With Charitap, you don’t even have to think about it. The system automatically detects the purchase and "rounds up" the transaction to $4.00. That $0.40 difference, essentially just "spare change" is quietly set aside. You walk away with your milk, knowing you’ve contributed to a cause you love without it ever impacting your daily budget or requiring a conscious decision at the checkout line. It turns the act of living into an act of giving.

The Charitap Journey: From Checkout to Change

Step 1: Users sign up or log in to their personal impact portal. This is where your journey of giving begins.

Seamless signup experience with Google OAuth

Step 2: Charitap works silently in the background. When you visit any of the millions of supported e-commerce sites and reach the checkout, the extension springs to life.

Charitap automatically detects your cart total on sites like Amazon or Shopify and offers to round up your spare change.

Step 3: One-Click Impact & Celebration With a single click on the "✓" button, your donation is processed. To celebrate your kindness, the screen bursts with confetti, providing instant confirmation that you’ve made a difference.

Making the world better, one cent at a time

Step 4: Head back to the Charitap dashboard to see the big picture. Here, you can track your total donations, see how many "round-ups" you’ve completed, and view your impact trends over time.

Your personal command center for tracking the power of your collective kindness.

Step 5: The Activity page provides a detailed Ledger of every transaction. Each entry is linked to a ResilientDB blockchain ID, providing 100% proof of your donation.

Every cent is logged on an immutable blockchain for you to verify.

Step 6: Nominate your favorite charities, update your profile, and manage your account to ensure your philanthropy is as personal as it is impactful.

Customizing your experience to support the causes that matter most to you.

Core Features at a Glance

Universal Compatibility: Charitap is built with a sophisticated detection engine that automatically recognizes checkout and payment pages across millions of websites. Whether you are shopping on Amazon, Shopify-powered boutiques, or eBay, Charitap intelligently identifies the moment you’re about to pay and offers a way to give back.
Blockchain-Backed Trust: In an era where trust is everything, Charitap leads with transparency. Every single donation is recorded on ResilientDB, a high-performance blockchain. This ensures that every cent you donate is immutable and traceable, providing total peace of mind that your contribution is reaching its intended destination.
Premium “Glassmorphic” UI/UX: The extension features a premium floating widget designed with modern glassmorphism and vibrant gradients. It stays out of your way until it’s needed, appearing only during the final steps of your purchase with smooth, subtle animations.
Privacy-First Filtering & Smart Cooldowns: Charitap respects your digital space. It is programmed to exclude non-shopping sites like Instagram, Facebook, and Gmail to prevent intrusive popups. Furthermore, it features an intelligent cooldown system; if you choose to skip a donation, the widget politely stays hidden for an hour to avoid "notification fatigue."
Real-Time Impact Dashboard: Connected to a robust backend, Charitap tracks your lifetime impact. Users can see their total contributions, the number of "round-ups" completed, and their verified blockchain transaction history, allowing you to see the tangible weight of your collective kindness over time.

Technical Deep Dive: The Hybrid Architecture

Charitap is a multi-layered system designed to bridge the gap between traditional finance (fiat) and decentralized ledgers.

1. The Frontend Stack

ReactJS & Tailwind CSS: Powers the responsive dashboard for a modern, high-performance user experience.
Google OAuth & JWT: Ensures secure, one-tap login for users.
Chrome Extension (Manifest v3): Built to be lightweight and secure, monitoring DOM elements on specific retail sites to capture transaction totals.

2. The Server Engine

Node.js & Express: The central nervous system that coordinates between the extension, the database, and the blockchain.
Node-Cron: A scheduled processor that "collects" the small round-up entries. To minimize transaction fees on the payment side, this job batches your change until it reaches a threshold before triggering a transfer.
MongoDB: Stores off-chain metadata like user preferences and charity profiles for lightning-fast retrieval on the dashboard.

3. The Financial & Blockchain Layer

Stripe Connect: We use Stripe’s enterprise-grade infrastructure to handle the actual movement of money from your bank to the charity.
ResilientDB (The Truth Layer): While Stripe handles the USD, ResilientDB provides the Proof. Every donation is logged via a GraphQL endpoint to an immutable KV store, creating a permanent audit trail.

Beyond Logging: Smart Contracts & Verification

While ResilientDB provides an immutable log of "what happened," Charitap utilizes Smart Contracts to add a layer of functional logic and automated receipts.

ResContract: The Digital Receipt System

In the Charitap ecosystem, every donation isn’t just a number; it’s a verifiable event. We use ResContract to mint Digital Donation Receipts:

Automated Minting: The moment Stripe confirms a transfer, the server triggers a smart contract on the ResilientDB chain.
Mathematical Integrity: The contract ensures that the total "Impact" displayed on your dashboard matches the actual state recorded on the blockchain. This prevents any central authority (including us) from altering your donation history or misreporting figures.

Steps to Run the System

Prerequisites

Node.js (v16+)
MongoDB (Local or Atlas)
ResilientDB instance (Local or Remote)
Stripe Account (Test mode keys)

Installation

Clone the repository git clone https://github.com/ResilientApp/Charitap.git
Install Frontend Dependencies cd src
npm install
Install Backend Dependencies cd backend
npm install

Environment Setup

Create .env files and add the necessary keys:

MONGODB_URI
STRIPE_SECRET_KEY
RESILIENTDB_URL
(Other necessary environment variables, refer to the example env)

Run the Application

Backend: cd backend && npm run dev
Frontend: npm start (from root)

Contributions

Aman Dwivedi: Built the Chrome Extension and the roundup logic for logging user transactions into the database. Integrated Smart Contracts to mint donation receipts for user-charity transactions.
Dhairye Gala: Constructed the NodeJS server, providing API endpoints for the frontend and Chrome extension. Setup the payment flow from the user bank account to the charity’s account using Stripe Connect.
Himanshu Nimonkar: Engineered the React/Tailwind dashboard with real-time Chart.js visualizations for tracking donation impact. Integrated Google OAuth, Stripe, and a GraphQL-powered ResilientDB public ledger for immutable transaction transparency.

Our Mission

Developed at the Expolab (UC Davis) by Aman Dwivedi, Dhairye Gala, and Himanshu Nimonkar, Charitap is a proof-of-concept for the future of "Resilient" finance. Under the guidance of Professor Mohammad Sadoghi, we are proving that even the smallest change can change the world when it is backed by a foundation of transparency and high-performance distributed systems.

Ready to turn your shopping into a force for good? Start small, give big with Charitap.

ResShare: A Decentralized File Sharing Network Built on ResilientDB and IPFS

Mon, 02 Feb 2026 00:00:00 +0000

ResShare is a decentralized file sharing application that allows users to securely store, share, and manage their files using Resilient DB technology. The application now features an AI-powered chatbot that can answer questions about your uploaded documents using Retrieval-Augmented Generation (RAG).

Motivation

With the rapid advancement of personal computing hardware, modern users now routinely own devices equipped with hundreds of gigabytes—or even multiple terabytes—of local storage. However, in practice, a significant portion of this storage capacity remains underutilized. For most users, less than half of their available disk space is actively used, leaving a vast amount of idle storage resources scattered across personal computers worldwide.

At the same time, existing cloud storage solutions rely heavily on centralized infrastructures, which introduce concerns related to cost, scalability, data ownership, single points of failure, and long-term sustainability. Users are required to entrust their data to centralized providers, often with limited transparency or control over how their data is stored, replicated, or accessed.

The core motivation behind ResShare is to bridge this gap by transforming unused local storage into a collectively shared, decentralized storage network. Instead of letting idle disk space go to waste, ResShare enables users to contribute their surplus storage capacity to a peer-to-peer ecosystem, where storage is shared, replicated, and managed in a decentralized and fault-tolerant manner.

By building on ResilientDB for reliable metadata management and IPFS for content-addressed distributed storage, ResShare aims to create a storage system that is not only efficient and scalable, but also resilient to failures and censorship. In this model, storage becomes a shared community resource rather than a centralized service, aligning incentives across users while preserving data ownership and privacy.

Ultimately, ResShare envisions a future where personal devices collaboratively form a decentralized storage backbone—leveraging existing, underutilized resources to provide a more sustainable, trustworthy, and user-centric alternative to traditional cloud storage systems.

Features

Core Features

User Authentication (Sign up, Login, Logout)
File Upload and Download
Folder Creation and Management
File Sharing between Users
Secure File Storage using IPFS
User Account Management

AI Document Assistant

Intelligent Document Q&A: Ask questions about your uploaded files
Multi-format Support: Works with PDF, DOCX, and TXT files
Semantic Search: Finds relevant information across all your documents
Privacy-First: Your data stays isolated and secure
Source Attribution: See which documents were used to answer your questions

Tech Stack

Frontend: React.js with Material-UI
Backend: Python Flask
Storage: ResilientDB for Metadata storage and IPFS for File Storage
Authentication: Session-based authentication
AI/ML:
- Sentence Transformers for embeddings
- FAISS for vector search
- Gemini GPT (optional) or local models for response generation
- LangChain for text processing

Prerequisites

Python 3.8+
Node.js 16+ and npm
IPFS daemon running locally
(Optional) Gemini API key for enhanced AI responses

Installation

Clone the repository:

git clone https://github.com/NoBugInMyCode/ResShareDeployable.git
cd ResShareDeployable

Install backend dependencies:
```
pip install -r requirements.txt
```
Install frontend dependencies:
```
cd frontend
npm install
cd ..
```

Set up AI features (Optional but recommended):

# For enhanced AI responses, set your Gemini API key
export GOOGLE_API_KEY="your-gemini-api-key-here"

Running the Application

Start the IPFS daemon:
```
ipfs daemon
```
To install IPFS Cluster Service, please refer to this link
Start the backend server:
```
python app.py
```
Start the frontend development server:
```
cd frontend
npm start
```

The application will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:5000

Using the AI Chatbot

Getting Started with AI

Upload Documents: Upload PDF, DOCX, or TXT files through the normal file upload process
Navigate to AI Chat: Click the “AI Chat” button in the navigation bar
Ask Questions: Type questions about your documents and get intelligent responses

Example Queries

“What are the main findings in my research paper?”
“Summarize the key points from my meeting notes”
“What does my contract say about payment terms?”
“Find information about project deadlines”

Supported File Types for AI

PDF: Research papers, reports, contracts
DOCX: Word documents, meeting notes, proposals
TXT: Plain text files, code documentation, notes

AI Features

Smart Chunking: Documents are intelligently split into semantic chunks
Vector Search: Uses advanced embeddings to find relevant content
Source Attribution: Shows which files and sections were used for answers
Privacy Preserved: Each user’s AI data is completely isolated

Configuration

Basic Configuration (No API key required)

The AI chatbot works out of the box with:

Local sentence transformer models for embeddings
FAISS for fast vector search
Simple extractive responses

Enhanced Configuration (With Gemini)

For higher quality responses, set up Gemini:

export GOOGLE_API_KEY="sk-your-key-here"

Usage

Standard File Operations

Create a new account using the sign-up feature
Log in to your account
Create folders to organize your files
Upload files to your folders
Share files with other users
Download shared files from other users

AI-Powered Features

Upload Text Documents: Upload PDF, DOCX, or TXT files
Wait for Processing: Files are automatically processed for AI search
Ask Questions: Use the AI Chat interface to query your documents
Get Intelligent Answers: Receive responses with source attribution
Explore Knowledge Base: View statistics about your indexed documents

Architecture

RAG Pipeline

File Upload → Text Extraction → Chunking → Embedding → Vector DB Storage
                                                            ↓
User Query → Query Embedding → Vector Search → Context → LLM → Response

Components

Text Extractors: PDF (PyPDF2), DOCX (python-docx), TXT (UTF-8)
Chunking: LangChain RecursiveCharacterTextSplitter
Embeddings: Google Gemini API (gemini-embedding-001) with configurable dimensions (768/1536/3072)
Vector DB: FAISS with per-user isolation
LLM: Gemini 2.5 Flash (optional) or extractive fallback

Implementing Raft Consensus Protocol for ResilientDB

Sat, 06 Dec 2025 00:00:00 +0000

What is Raft?

Raft is a consensus protocol used in many existing software systems including Kubernetes, Kafka, and MongoDB. It has been battle-tested in many circumstances since it was first described in 2013. The ResilientDB project on GitHub has had an open issue since October 2023 for Raft to be added to the portfolio of available consensus protocols. We aim to fulfill this feature request.

Raft is a crash fault tolerant (CFT) protocol, and would be the first non-Byzantine fault tolerant (BFT) consensus protocol available within ResilientDB, which does come with benefits. A ResilientDB deployment would be able to function with only 3 replicas instead of the current minimum of 4 replicas. ResilientDB transaction throughput would scale far better with the number of replicas increases due to the preferable asymptotic message complexity of Raft (O(n)) compared to the PBFT family of protocols (O(n²)). The performance overhead of cryptography in the BFT protocols is also quite high, so latency improvements can also be expected while using Raft.

Figure 1. Picture describing Raft Protocol

How It Differs from PBFT

Figure 2. Table comparing Raft vs PBFT

Useful Links

Official Raft consensus protocol paper: https://raft.github.io/raft.pdf
Protocol is currently in this repo: https://github.com/hammerface/incubator-resilientdb/tree/raft

Our Implementation Strategy and Architecture

For our implementation, we chose to build on existing consensus protocol code, considering both PBFT and PoE, and ultimately selecting PoE for its simpler and more extensible design. The Consensus class exposes a ProcessCustomConsensus() method that lets us send custom message types through the RPC dispatcher, which in turn allows us to reuse existing components for database access and client notifications via TransactionManager, as well as replica messaging via ReplicaCommunicator. Our approach also benefits from built-in benchmarking support through the PerformanceManager module.

Figure 3. Implementation Architecture

1. Append Entries RPC - Log Replication

In Raft, log replication is driven by the leader: whenever a client sends a command, the leader appends it to its own log and then sends AppendEntries RPCs to followers to copy the new log entries. Followers accept an entry only if it follows a log prefix that matches the leader’s (same term and index), which keeps logs consistent across the cluster. Once a majority of followers have stored an entry, the leader commits it and applies it to the state machine, then notifies followers so they can commit it too. Catchup happens naturally for slow or rebooted followers: the leader keeps sending them AppendEntries starting from their nextIndex until their log matches the leader’s, filling in any missing or outdated entries along the way.

Our Implementation Logs

Figure 4. Append Entries Logs

2. Leader Election

In Raft, leader elections occur when servers do not hear from the current leader within their timeout window. Each server starts as a follower. If a follower doesn’t receive a heartbeat or log entry from a leader within a timeout, it becomes a candidate, increments its term, and asks the other servers for votes. Servers will vote for at most one candidate per term, and they only vote for a candidate whose log is at least as up to date as their own. If a candidate receives votes from a majority, it becomes the new leader and immediately starts sending heartbeats to assert its authority and prevent new elections. If there’s a tie (no one gets a majority), everyone times out again with slightly randomized timers and the election is retried until a leader is chosen.

Figure 5. Leader Election Diagram

Our Implementation Logs

Figure 6. Aggregated Excerpts about Leader Election from the Logs

Commands to Execute

Here are the commands to download Resilient DB, build it, and run the RAFT and PBFT performance scripts:

sudo apt update
sudo apt-get install git
sudo apt install psmisc
git clone https://github.com/apache/incubator-resilientdb.git
cd incubator-resilientdb/
./INSTALL.sh
./service/tools/kv/server_tools/start_kv_service.sh
bazel build service/tools/kv/api_tools/kv_service_tools
cd scripts/deploy/
touch config/key.conf
./performance_local/raft_performance.sh config/kv_performance_server_local.conf
./performance_local/pbft_performance.sh config/kv_performance_server_local.conf

Benchmarks

Here is our output after running both of the performance scripts, with PBFT results gathered using the main branch:

Note, both configurations have the minimum number of nodes for f = 1 (the client is included as a node, so 4 replicas for PBFT and 3 replicas for Raft).

PBFT:

calculate results, number of nodes: 5
max throughput: 44660
average throughput: 20871.272727272728
max latency: 0.000144599
average latency: 0.000107366275

Raft:

calculate results, number of nodes: 4
max throughput: 104418
average throughput: 45385.2
max latency: 8.15001e-05
average latency: 6.7288925e-05

Raft outperforms PBFT both in terms of throughput and latency, by roughly double. We ran into issues with the leader election with 4 Raft nodes, which we are still looking into.

Looking Ahead

-Batching - Groups multiple client transactions into a single Append Entry RPC to significantly boost throughput and reduce network overhead.

-State Persistence - Saves critical data (current term, vote, and log) related to the protocol itself to stable storage (in ResilientDB).

-Snapshots - Replaces old log entries with a compact file of the current state to prevent the log from consuming all available memory and to allow followers to catch up quicker.

-Membership Changes - Enables the safe addition or removal of servers from the cluster dynamically without shutting down the system or halting operations.

-Inconsistent progress stalls - We appear to have some inconsistencies with the leader elections where the leader is chosen but does not appear to make progress. How often this state occurs seems to vary based on the number of nodes. This needs to be investigated.

GraphQ-LLM: AI Query Tutor for ResilientDB

Sat, 06 Dec 2025 00:00:00 +0000

Introduction

GraphQ-LLM is an intelligent AI assistant that helps developers learn, understand, and optimize GraphQL queries for ResilientDB. Built with Retrieval-Augmented Generation (RAG) and integrated with the ResilientApp ecosystem, it provides real-time explanations, suggestions, and performance insights for your GraphQL queries.

🎯 What is GraphQ-LLM?

GraphQ-LLM is a comprehensive AI tutor that transforms how developers interact with GraphQL APIs. Instead of searching through documentation or trial-and-error query writing, developers can ask questions in natural language or paste their queries to get:

Detailed Explanations: Understand what each query does, how fields work, and what to expect in responses
Efficiency Metrics: See estimated execution time, resource usage, and complexity scores
Documentation Context: Access relevant ResilientDB and GraphQL documentation through semantic search

🏗️ How It Works

Architecture Overview

Core Components

RAG System (Retrieval-Augmented Generation)
- Stores GraphQL documentation in ResilientDB with vector embeddings
- Uses semantic search to find relevant documentation chunks
- Combines retrieved context with LLM for accurate, contextual responses
AI Explanation Service
- Detects whether input is a GraphQL query or natural language question
- For queries: Analyzes structure, fields, operations, and provides explanations
- For questions: Retrieves relevant docs and generates comprehensive answers
Efficiency Estimator
- Calculates query complexity scores
- Estimates execution time and resource usage
- Provides real-time metrics when ResLens is enabled

🚀 Key Features

1. Intelligent Query Explanation

Paste any GraphQL query and get a detailed breakdown:

{
  getTransaction(id: "123") {
    id
    asset
    amount
  }
}

Response includes:

What the query does (in plain English)
How each field and operation works
Expected response format
Common use cases

2. Natural Language Q&A

Ask questions like:

“How do I retrieve a transaction by ID in GraphQL?”
“What is the difference between query and mutation?”
“How can I optimize my GraphQL queries?”

The system retrieves relevant documentation and provides comprehensive answers with examples.

3. Query Optimization Suggestions

Get actionable recommendations:

Remove unused fields
Use field aliases for clarity
Add filters to reduce result size
Optimize nested queries

4. Performance Metrics

See efficiency scores, estimated execution times, and resource usage to understand query performance at a glance.

5. Chatbot Interface

Clean interface for interacting back and forth with the AI in a chat.

📦 Setup Overview

GraphQ-LLM is fully dockerized for easy deployment. Here’s what you need:

Prerequisites

Docker & Docker Compose - For running all services
Node.js 18+ - For local development (optional)
Gemini API Key - For LLM capabilities (get from Google AI Studio)
Nexus Repository - Separate Next.js frontend (use the forked version with GraphQ-LLM integration: sophiequynn/nexus)
ResLens Repositories - Optional performance monitoring (use forked versions: sophiequynn/incubator-resilientdb-ResLens and sophiequynn/incubator-resilientdb-ResLens-Middleware)

Quick Start

Clone and Install

git clone <graphq-llm-repo>
cd graphq-llm
npm install

Configure Environment

# Create .env file and add your Gemini API key
LLM_PROVIDER=gemini
LLM_API_KEY=your_gemini_api_key_here
RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql

Clone ResLens Forks (Optional - for performance monitoring)

# Clone ResLens Frontend
git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens.git ResLens
   
# Clone ResLens Middleware
git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git ResLens-Middleware

Note: These forks include Dockerfile and configuration updates for GraphQ-LLM integration.

Start Services with Docker

# Start ResilientDB (database + GraphQL server)
docker-compose -f docker-compose.dev.yml up -d resilientdb
   
# Start GraphQ-LLM Backend
docker-compose -f docker-compose.dev.yml up -d graphq-llm-backend
   
# (Optional) Start ResLens for performance monitoring
docker-compose -f docker-compose.dev.yml up -d reslens-middleware reslens-frontend

Ingest Documentation

npm run ingest:graphql
# This loads all GraphQL docs into ResilientDB for RAG

Set Up Nexus Frontend
- Clone the forked Nexus repository (includes GraphQ-LLM integration):
```
git clone https://github.com/sophiequynn/nexus.git
cd nexus
npm install
```
- Note: This fork already includes all GraphQ-LLM integration files - no manual setup needed!
- Start with npm run dev
Access the Tool
- Open http://localhost:3000/graphql-tutor in your browser
- Start querying or asking questions!

Service Architecture

All services run in Docker containers:

ResilientDB (Port 18000, 5001) - Database with GraphQL server
GraphQ-LLM Backend (Port 3001) - HTTP API for Nexus integration
GraphQ-LLM MCP Server - For MCP client integration (stdio transport)
ResLens Middleware (Port 3003) - Performance monitoring API (optional)
ResLens Frontend (Port 5173) - Performance monitoring UI (optional)

💡 How It Helps Developers

Learning GraphQL

New to GraphQL? GraphQ-LLM explains:

Query syntax and structure
Field selection and arguments
Mutations vs queries
Schema exploration
Best practices

Query Effeciency

Working on performance? Get:

Complexity analysis
Field selection recommendations
Execution time estimates
Resource usage insights
Historical query comparisons (with ResLens)

Troubleshooting

Stuck on an error? The system helps:

Understand query structure issues
Find relevant documentation
Compare with similar working queries
Get optimization suggestions

🔧 Technology Stack

Backend: Node.js/TypeScript with RAG architecture
LLM: Gemini 2.5 Flash Lite (configurable: DeepSeek, OpenAI, Anthropic, Hugging Face, local models)
Embeddings: Local (Xenova/all-MiniLM-L6-v2) or Hugging Face API
Database: ResilientDB for vector storage and document chunks
Frontend: Next.js (Nexus integration)
Monitoring: ResLens for real-time performance metrics
Protocol: MCP (Model Context Protocol) for secure AI tool integration

🌐 Integration with ResilientApp Ecosystem

GraphQ-LLM is designed to work seamlessly with:

ResilientDB: The underlying blockchain database
Nexus: The ResilientApp frontend platform
ResLens: Performance monitoring and profiling tools

Together, these tools provide a complete development and monitoring experience for ResilientDB applications.

📚 Documentation & Resources

Complete setup instructions are available in:

TEAM_SETUP.md - Step-by-step setup guide (includes Nexus fork setup)
TEST_DOCKER_SERVICES.md - Service verification guide
QUERY_TUTOR_EXAMPLES.md - Example queries and questions
NEXUS_UI_EXTENSION_GUIDE.md - Frontend integration guide (reference only - fork already includes integration)

📦 Fork Information

GraphQ-LLM uses forked versions of external repositories that include GraphQ-LLM-specific modifications:

Nexus Fork

Fork Repository: sophiequynn/nexus
Original Repository: ResilientApp/nexus
Integration Status: The fork includes all GraphQ-LLM UI components and API routes
Setup: Simply clone the fork - no additional modifications needed!

ResLens Forks

ResLens Frontend Fork: sophiequynn/incubator-resilientdb-ResLens
ResLens Middleware Fork: sophiequynn/incubator-resilientdb-ResLens-Middleware
Original Repository: Apache ResLens
Integration Status: Forks include Dockerfile updates, additional routes (CpuPage, MemoryPage, QueryStats), and improved configuration
Setup: Clone both forks - Docker Compose will use them automatically via absolute paths

🎓 Example Use Cases

Scenario 1: Learning GraphQL

Input:

"What is GraphQL and how do I write a basic query?"

Output: Comprehensive explanation with examples, documentation references, and links to relevant guides.

Scenario 2: Explaining a Query

Input:

{
  getTransaction(id: "abc123") {
    id
    asset
    amount
  }
}

Output:

Detailed breakdown of what this query does
Explanation of each field
Expected response format
Use cases and examples

Scenario 3: Optimizing Performance

Input:

{
  getTransaction(id: "test") {
    id version amount uri type publicKey signerPublicKey operation metadata asset
  }
}

Output:

Efficiency score: 75/100
Optimization suggestions: “Consider selecting only needed fields”
Estimated execution time: 45ms
Complexity: Medium

🎯 Conclusion

GraphQ-LLM bridges the gap between complex GraphQL documentation and practical query writing. By combining AI-powered explanations, semantic search, and performance monitoring, it provides developers with an intelligent assistant that makes learning and optimizing GraphQL queries effortless.

Whether you’re a GraphQL beginner or an experienced developer looking to optimize queries, GraphQ-LLM offers the insights and recommendations you need to write better, faster, and more efficient queries for ResilientDB.

Ready to get started? Follow the complete setup guide in TEAM_SETUP.md from our GitHub and begin exploring the power of AI-assisted GraphQL development in ResilientDB!

For detailed setup instructions, troubleshooting, and advanced configuration, see the complete documentation in the repository.

Nexus: An Agentic Rag Assistant for ResilientDB and Distibuted Systems Research

Thu, 13 Nov 2025 00:00:00 +0000

Nexus: An Agentic RAG Assistant for ResilientDB and Distributed Systems

Overview

Nexus is a Next.js-based agentic Retrieval-Augmented Generation (RAG) assistant tailored for Apache ResilientDB, blockchain, and distributed systems. It combines LlamaIndex (TypeScript) orchestration, DeepSeek for reasoning, Gemini Embedding 001 for retrieval, and Supabase (Postgres + pgvector) for persistent storage and memory, delivering grounded answers with clear citations.

Motivation

The research landscape is dense; answers must be verifiable and source-linked.
Traditional keyword tools don’t synthesize across documents.
Researchers need multi-document reasoning, persistent context, and the ability to pull in external updates when needed.

Key Features

Research and Code modes:
- Research Mode: Single NexusAgent with search_documents and search_web tools, streams tool usage transparently and surfaces source badges in the preview panel (inline footnotes are on the roadmap)
- Code Mode (experimental): Multi-agent workflow via CodeAgent class:
  - PlannerAgent: Retrieves document content and analyzes for implementation details
  - PseudoCodeAgent: Creates structured pseudocode from research findings
  - CodeAgent: Generates final production-ready code in selected language (TypeScript, Python, C++)
  - Features automatic handoffs between agents and live streaming of each phase
Document selection:
- Single-document focus for deep reading.
- Multi-document selection for synthesis and comparison.
Tool-aware agent:
- search_documents: semantic retrieval from Supabase pgvector (scoped to selected docs).
- search_web: Tavily for up-to-date or out-of-corpus facts.
Session-scoped memory with short-term and long-term capabilities:
- Short-term memory: FIFO queue of recent messages within token limits (30,000 tokens, 70% ratio for chat history)
- Long-term memory: Implemented via two memory blocks:
  - robustFactExtractionBlock: Extracts and stores durable facts using DeepSeek (max 10 facts, priority 1)
  - vectorBlock: Stores and retrieves session-scoped memory in Supabase pgvector (priority 2, top-k=3)
Streaming with tool transparency:
- The API streams deltas and tool lifecycle events so the UI can interleave “thinking” steps and tool badges.

System Architecture

Ingestion Pipeline

Nexus implements a sophisticated document ingestion pipeline using LlamaIndex’s IngestionPipeline with multiple transformation stages to prepare raw PDFs for efficient retrieval:

Transformation Pipeline Details:

Document Parsing: LlamaParseReader converts PDFs to structured JSON with page metadata, handling complex layouts, tables, and figures
Node Parsing: MarkdownNodeParser processes the markdown content from LlamaParse into structured document nodes
Text Chunking: SentenceSplitter with chunk size 768 tokens and 20-token overlap maintains semantic coherence while creating retrievable segments
Metadata Extraction: SummaryExtractor automatically generates summaries and extracts key metadata for each chunk
Embedding Generation: Gemini Embedding 001 converts text chunks into high-dimensional vectors for semantic similarity search
Vector Storage: Embeddings and metadata are stored in Supabase pgvector with HNSW indexing for fast retrieval

Caching Strategy: The system maintains a parsed_documents table in Supabase to track parsing status, avoiding re-processing of already ingested files and enabling incremental updates.

This pipeline ensures that each PDF is transformed into semantically meaningful, searchable chunks with rich metadata and high-quality embeddings for precise retrieval.

Streaming and Tooling

Stack

Frontend: Next.js (React) chat UI + PDF/source preview panel
API: Next.js Route Handlers under /api/research/*
Orchestration: LlamaIndex (TypeScript)
Vector Storage: Supabase (Postgres + pgvector) via @llamaindex/supabase
LLM: DeepSeek (deepseek-chat) via @llamaindex/deepseek
Embeddings: Gemini Embedding 001 via @llamaindex/google
Web Search: Tavily

How it Works (at a glance)

Select documents (single or multiple).
The UI calls /api/research/prepare-index → PDFs parsed with LlamaParse → transformed and embedded → stored in pgvector.
Ask a question; the UI calls /api/research/chat → the agent chooses tools → streams tokens and events → UI displays content and source attributions.

Research Agent

Code Composer Agent

Run Locally

Prerequisites:
- Node.js 18+
- Supabase project with pgvector enabled
- Create two tables (or reuse defaults):
  - llamaindex_vector_embeddings
  - llamaindex_memory_embeddings
- API keys:
  - DEEPSEEK_API_KEY
  - GEMINI_API_KEY
  - LLAMA_CLOUD_API_KEY (for LlamaParse)
  - TAVILY_API_KEY
  - SUPABASE_URL and SUPABASE_ANON_KEY (or SUPABASE_SERVICE_ROLE_KEY)
- GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI, GOOGLE_REFRESH_TOKEN (for Drive access)
Environment
.env.local

DEEPSEEK_API_KEY=...
DEEPSEEK_MODEL=deepseek-chat

GEMINI_API_KEY=...
LLAMA_CLOUD_API_KEY=...
TAVILY_API_KEY=...

SUPABASE_URL=...
SUPABASE_ANON_KEY=...         or SUPABASE_SERVICE_ROLE_KEY=...
SUPABASE_VECTOR_TABLE=llamaindex_vector_embeddings
SUPABASE_MEMORY_TABLE=llamaindex_memory_embeddings

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=...
GOOGLE_REFRESH_TOKEN=...

Install and run

npm install
npm run dev
open http://localhost:3000/research

Connect document sources
- Share the desired folders with the Google account tied to your refresh token.
- Update the folder IDs inside src/app/api/research/documents/route.ts if you need different collections.
- Uploaded PDFs in those Drive folders appear automatically in the in-app library once credentials are configured.
Use the app
- Select one or more documents in the sidebar.
- Wait for “Preparing documents…” to complete (ingestion runs via /api/research/prepare-index).
- Ask questions. The agent retrieves from your selected docs and lists sources within the preview panel.

Memory Design (Session-Scoped)

Nexus implements the LlamaIndex Memory framework with both short-term and long-term memory capabilities:

Short-term Memory:

Token-limited FIFO queue (30,000 tokens total, 70% allocated to chat history)
When chat history exceeds the ratio, the framework automatically trims the oldest short-term messages while leaving long-term memory blocks intact
Maintains recent conversational context within the session

Long-term Memory (via Memory Blocks):

robustFactExtractionBlock (priority 1): Extracts durable, reusable facts using DeepSeek LLM, stores up to 10 facts with automatic summarization when limit is exceeded
vectorBlock (priority 2): Stores and retrieves session-scoped memory batches in Supabase pgvector (keyed by sessionId), uses hybrid similarity search with top-k=3 retrieval

Benefits:

Coherence across turns and sessions without relying on raw chat transcripts
Scalable across instances via persistent vector storage
Automatic memory management with priority-based truncation when token limits are exceeded

Current Limitations

Code Mode is experimental and best for structured, implementation-focused prompts.
Corpus is intentionally scoped to ResilientDB and related systems to ensure high-quality retrieval.
Requires cloud APIs (DeepSeek, LlamaParse, Gemini, Tavily); offline mode is not supported out-of-the-box.

Future Work

Inline citation markers and highlighting in the PDF preview panel
- Add [^id]-style footnotes to responses and allow clicking to jump to the referenced passage/page range.
Custom selective context
- Let users include/exclude sections (e.g., Methods only), set per-query filters, or re-rank top-k nodes.
Advanced reranking
- Integrate implementation-aware reranking for code-generation workflows (leveraging the CodeComposer pipeline).
Multimodal parsing
- Tables, figures, and chart-aware extraction for richer question answering.
Proactive discovery
- Recommend relevant new papers based on ongoing sessions and research interests.

Closing

Nexus brings together a modern TS-first stack, robust retrieval, transparent tool use, and session memory to create a reliable research copilot for distributed systems.

Navigating ResilientDB's C++ Codebase: Empowering Contributors with Modern Tooling

Thu, 24 Jul 2025 00:00:00 +0000

Navigating ResilientDB’s C++ Codebase: Empowering Contributors with Modern Tooling

ResilientDB is a high-performance blockchain platform written in modern C++17. If you’ve worked with C++ before, you know that managing large codebases can be challenging—not just because of the language’s complexity, but also due to the tools used to build and organize the project. In the C++ world, build systems play a crucial role: they take care of compiling source files, managing dependencies, and producing the final executable. While CMake is a popular choice for many open-source projects, ResilientDB uses Bazel—a powerful build tool developed at Google that excels at handling complex, multi-language codebases with many modules and dependencies.

Understanding how a build system works is essential for any C++ developer. A build system automates the process of transforming source code into binaries, managing everything from compilation flags to linking libraries. This is especially important in large projects, where manual compilation would be error-prone and time-consuming. CMake is widely used for this purpose, but Bazel offers advanced features for scaling to very large codebases and supporting multiple languages.

Modern development environments (IDEs) offer features like Intellisense, autocomplete, and code navigation, which are powered by language servers and configuration files that describe how the code is built. These features are not just conveniences—they are essential for stepping through code, debugging, and understanding how different parts of a project fit together. They make it much easier to dive into the details of an implementation, accelerate feature development, and lower the barrier for new contributors.

However, Bazel doesn’t natively generate the configuration files (like compile_commands.json) that many IDEs and language servers rely on for these features. This can make it difficult to get full code intelligence and navigation in editors like VSCode or CLion when working with Bazel-based projects.

To solve this, we integrated a tool called Hedronvision’s Bazel Compile Commands Extractor. This tool generates a compile_commands.json file based on the current state of your Bazel build. This file is often called a Compilation Database and helps tools to generate intellisense. With this file in place, you can use a Language Server Protocol (LSP) extension in your editor to unlock powerful, interactive code exploration—making it easy to step through functions, debug, and contribute to the core engine.

In this post, I’ll show you how to set up your environment so you can:

Effortlessly navigate the ResilientDB codebase
Unlock powerful autocomplete and code exploration features
Lower the barrier for new contributors to jump into C++ development

Let’s make contributing to ResilientDB accessible to everyone—because the more eyes and ideas we have, the stronger the project becomes.

Setting up Intellisense for ResilientDB’s C++ Projects

Setting up ResilientDB Core

Follow the steps in the Build and Deploy ResilientDB to setup the resilientdb project.

1. Generate compile_commands.json with Hedronvision

Once your ResilientDB project is set up, you can generate the compile_commands.json file by running the following command from your project root:

bazel run @hedron_compile_commands//:refresh_all

This will create or update the compile_commands.json file, which is essential for enabling full-featured code navigation and autocomplete in your IDE.

2. Install clangd (C++ Language Server)

If you’re using VS Code, simply install the clangd extension from the Extensions marketplace. VS Code will handle the installation of clangd for you—no manual setup required.

3. Configure your editor to use clangd

Most modern editors (like VSCode, Neovim, or CLion) support clangd via extensions or built-in integration. For VSCode:

Install the clangd extension.
Open your ResilientDB project folder in VSCode.
The extension should automatically detect your compile_commands.json file and enable code navigation, autocomplete, and other features.
You will see a progress bar at the bottom of your screen displaying the progress of indexing. This step is essentially the LSP extension trying to crawl through your code and configuring the autocomplete.

4. Handling Missing Autocomplete for Some Modules

While the steps above will enable autocomplete and code navigation for most of the codebase, you may occasionally notice that some modules or files are missing autocomplete or show errors. This usually happens when certain parts of the project haven’t been built yet, so their compilation information isn’t included in the compile_commands.json file.

To resolve this:

Identify the module or target that’s missing autocomplete (for example, a storage engine or a smart contract library).
Navigate to the folder containing the relevant BUILD file.
Build the target using Bazel:

bazel build //path/to/your/target

For example, to build the storage engine module:

bazel build chain/storage/leveldb

After building the target, restart the clangd extension in your editor. This will prompt clangd to re-index the codebase, and autocomplete should now work for the newly built modules.

Now you’re ready to explore, debug, and contribute to ResilientDB with full code intelligence support!

Setting up ResilientDB GraphQL Proxy Server

The same steps can be used for generating a Compilation Database. Follow the instructions in the Build and Deploy GraphQL Proxy. Once the bazel build process is completed, use this command to generate the compile_commands.json file and start hacking.

bazel run @hedron_compile_commands//:refresh_all

Since the Proxy Server contains code written in both C++ and Python, we recommend installing the following VS Code extensions for full Intellisense support:

clangd — for C++ code navigation and autocomplete
Python — for Python code navigation and autocomplete

How do we use these tools internally?

At ResilientDB, we rely heavily on Intellisense and advanced code navigation tools to work efficiently within our large and evolving codebase. By leveraging AI-powered editors like Cursor and GitHub Copilot, our team can quickly understand unfamiliar parts of the project, receive intelligent code suggestions, and even generate boilerplate or complex code snippets on the fly. This is especially valuable as we work on ambitious projects, such as developing a new storage engine and exploring ways to make our architecture pluggable for different storage backends to suit various use cases. Intellisense, combined with robust debugging and benchmarking workflows, enables us to iterate rapidly, catch issues early, and keep a sharp focus on both performance and developer productivity as we expand the capabilities of ResilientDB.

Debugging, Profiling, and Observability

Stay tuned! Next week, we’ll be adding a detailed section on how to enable debugging and profiling flags in Bazel, as well as how to use ResLens’s flamegraph feature for observability and performance analysis. This will include practical steps, example commands, and tips for getting the most out of these powerful tools.

Building Resilient Apps with ResilientDB & ResVault

Thu, 13 Mar 2025 00:00:00 +0000

The ResilientDB Fullstack makes it easy to build and interact with blockchain-powered applications. At its core, it uses ResilientDB for high-speed transaction processing and ResVault as a wallet interface for seamless interactions. Web apps can connect effortlessly using the ResVault web SDK, while developers also get SDK support for Python, Rust, and TypeScript, making it simple to integrate ResilientDB into different applications. Whether you’re building for the web or other platforms, ResilientDB Fullstack provides the tools to get started quickly and efficiently.

Core Components of a Resilient App

Your Decentralized App (dApp) – Built on ResilientDB to enable trustless, high-throughput transactions.
ResVault – A secure wallet interface that connects users to your dApp via the ResVault web SDK.
ResilientDB GraphQL Server – Provides an intuitive API layer for interacting with blockchain data.
ResilientDB KV/Smart Contract Service – A robust key-value store and smart contract execution engine, combined with Crow HTTP Server and SDK support for Python, TypeScript, and Rust.

Prerequisites

Docker - Setup Instructions

Setting Up ResilientDB in Minutes

Getting started with ResilientDB is incredibly simple with ResilientDB-Ansible, which automates the setup of the Crow HTTP server and GraphQL API. A cross-platform GUI installer with Tauri is also in the works to make deployment even easier.

Quick Setup Instructions

Clone the ResilientDB-Ansible repository:

git clone https://github.com/ResilientEcosystem/resilientdb-ansible
cd resilientdb-ansible

Build the Docker image:
```
docker build -t resilientdb-ansible .
```

Run the container with required privileges:

docker run --privileged -v /sys/fs/cgroup:/sys/fs/cgroup:ro -p 80:80 -p 18000:18000 -p 8000:8000 resilientdb-ansible

Once the container is running, you can access:

ResilientDB Crow HTTP Server at http://localhost/crow (Exposed port 18000)
ResilientDB GraphQL API at http://localhost/graphql (Exposed port 8000)

This setup automatically configures ResilientDB with 4 replicas and 1 client, with Nginx handling routing inside the container.

Set Up ResVault: Your Gateway to ResilientDB

ResVault is a Chrome extension wallet for ResilientDB, allowing users to commit and retrieve data, manage accounts, and track transactions, all through the ResilientDB GraphQL server. Think of it as Metamask for ResilientDB, but tailored for high-throughput blockchain applications.

Features

Core Wallet Functionality

Create Account - Generate new wallet accounts with secure key management
Delete Account - Remove accounts with proper cleanup
Login/Logout - Secure authentication system
Submit Transactions - Send transactions to ResilientDB network
Transaction Logging - Complete transaction history and audit trail
User Profiles - Manage multiple user identities
Multi-account Support - Handle multiple wallet accounts simultaneously

Smart Contract Integration (v1.2.0)

Contract Deployment - Deploy Solidity smart contracts directly from the wallet
Address Ownership - Contracts are deployed using your wallet address for proper ownership
GraphQL Integration - Seamless communication with ResilientDB smart contract service
Solidity Compilation - Automatic compilation of Solidity contracts before deployment
Enhanced Error Handling - Improved debugging and error reporting for contract operations
Network Flexibility - Connect to mainnet or your local ResilientDB server

Security & Performance

Secure Key Management - Ed25519 key pairs with proper encryption
Transaction Validation - Built-in validation for all operations
Network Connectivity - Support for custom ResilientDB network endpoints
Real-time Updates - Live transaction status and balance updates

Pending Features:

Install ResVault

Via Chrome Web Store (Recommended)

🎉 ResVault is now available on Chrome Web Store!

Install ResVault from Chrome Web Store

Build ResVault from Source

Prerequisite

You need Node.js v16.20.2 for the build. The recommended way to manage multiple Node.js versions is using nvm.

Clone the ResVault Repository

git clone https://github.com/apache/incubator-resilientdb-resvault
cd incubator-resilientdb-resvault

Install Dependencies

npm install

Build the Wallet

npm run build

Verify Successful Build

If everything goes well, you’ll see this message:

The build folder is ready to be deployed.
You may serve it with a static server:

  serve -s build

Find out more about deployment here:

  https://cra.link/deployment

The wallet build will be available in the build directory inside incubator-resilientdb-resvault

Now, you’re all set to use ResVault as your secure wallet for ResilientDB transactions!

Add build to chrome

Once you have generated the build:

Open chrome and navigate to chrome://extensions/
Make sure developer mode is enabled using the toggle button.
Finally, load the extension by clicking on load unpacked button and then select the build directory that was created in the previous step.
Now you can open the wallet from the extension button and start using it!

Integrating ResVault SDK with Your Resilient App

If you’re looking for the simplest way to build a ResilientDB-powered React or Vue application with ResVault SDK integration, create-resilient-app is the tool for you!

Why Use `create-resilient-app`?

Scaffold a new ResilientDB app with React or Vue in seconds.
Supports both JavaScript and TypeScript for flexibility.
Automatically integrates ResVault SDK, so you can start interacting with ResilientDB right away.
No manual setup, just run a single command!

Installation & Setup

You don’t need to install anything globally. Just run:

npx create-resilient-app

Running the command without any flags will launch an interactive prompt.

You’ll be asked:

Project Name – Give your app a name.
Framework – Choose between React or Vue.
Language – Choose between JavaScript or TypeScript.

One-Command Setup

Skip the prompts by specifying options directly:

npx create-resilient-app --name my-app --framework react --language typescript

Example Commands

Create a React app with TypeScript:

npx create-resilient-app --name my-react-app --framework react --language typescript

Create a Vue app with JavaScript:

npx create-resilient-app --name my-vue-app --framework vue --language javascript

Project Setup & Running

After the project is generated, navigate to your project directory:

cd my-app

Then install the required dependencies:

npm install

Start Your Project

For React:

npm start

For Vue:

npm run dev

Now, you can customize your app and start building powerful ResilientDB-powered decentralized applications.

Next Steps: Connect Your Resilient App to ResVault

Now that you’ve set up your first Resilient App, it’s time to connect it to ResVault and start interacting with ResilientDB.

Open Your Resilient App

Navigate to your Resilient App in your browser.

Open ResVault & Create an Account

Open the ResVault extension in your browser.
If you haven’t created an account yet, set a secure password and let ResVault generate your keys securely.

Choose a Network in ResVault and Connect

Once at the ResVault Dashboard, click the dropdown menu at the top.
By default, it is set to ResilientDB Mainnet, which connects to ResilientDB Cloud (cloud.resilientdb.com/graphql).
If you are running ResilientDB locally, select ResilientDB Localnet from the dropdown.
On the right side of the dropdown, you’ll see a site icon, click on it once to connect ResVault to your Resilient App.

Inside your Resilient App, click Sign In Via ResVault.
ResVault will prompt you to approve the transaction.
Once approved, ResVault will sign the transaction using your keys and send it to ResilientDB.
Your app will receive a callback confirming successful authentication and will be redirected to the authenticated page.
Now, you can send more transactions by submitting the form inside the authenticated page (with any JSON data as well).

Submit Transactions from the Authenticated Page

Now that you’re authenticated, you can send more transactions using the form inside the authenticated page.
The form allows you to submit any JSON data, which will be securely signed and sent to ResilientDB.

You’re now fully connected to ResilientDB via ResVault! Whether on Mainnet (Cloud) or Localnet, you can authenticate, send transactions, and interact with decentralized applications seamlessly.

Smart Contract Usage

Deploying Contracts

Navigate to the Contract tab in ResVault
Enter your ResilientDB server URL:
- Mainnet: Use the production ResilientDB endpoint
- Local Development: Use your local server (e.g., http://localhost:8400)
- Custom Server: Use any ResilientDB instance (e.g., http://your-server:8400)
Paste your Solidity contract code
Provide constructor arguments if needed
Click Deploy - the contract will be deployed using your wallet address

Client-Side Indexing Support in ResilientDB for Filtering in Your Resilient App

When building ResilientDB-powered applications, efficient data retrieval is crucial. If your Resilient App needs a filtering functionality, you can index ResilientDB transaction data on the client side using MongoDB. This tutorial will guide you through setting up real-time synchronization with MongoDB using ResilientDB’s WebSocket and HTTP APIs for efficient querying.

Prerequisites

MongoDB - Setup Instructions

Why Client-Side Indexing?

Efficient filtering of ResilientDB transactions for dApps.
Real-time sync using WebSocket and HTTP.
Query transactions based on public keys, timestamps, asset JSON, or metadata.
Automatic reconnection, batching, and concurrency handling.

Syncing ResilientDB Data to MongoDB for Efficient Filtering

Install the Required Library

For Node.js, install:

npm install resilient-node-cache

For Python, install:

pip install resilient-python-cache

Configure MongoDB and ResilientDB

Before syncing, ensure MongoDB is running and configure your connection settings:

Node.js Configuration (sync.js)

const { WebSocketMongoSync } = require('resilient-node-cache');

const mongoConfig = {
  uri: 'mongodb://localhost:27017',
  dbName: 'myDatabase',
  collectionName: 'myCollection',
};

/* resilientdb://localhost/crow to sync localnet */
const resilientDBConfig = {
  baseUrl: 'resilientdb://crow.resilientdb.com',
  httpSecure: true,
  wsSecure: true,
};

const sync = new WebSocketMongoSync(mongoConfig, resilientDBConfig);

sync.on('connected', () => {
  console.log('WebSocket connected.');
});

sync.on('data', (newBlocks) => {
  console.log('Received new blocks:', newBlocks);
});

sync.on('error', (error) => {
  console.error('Error:', error);
});

sync.on('closed', () => {
  console.log('Connection closed.');
});

(async () => {
  try {
    await sync.initialize();
    console.log('Synchronization initialized.');
  } catch (error) {
    console.error('Error during sync initialization:', error);
  }
})();

Python Configuration (sync.py)

import asyncio
from resilient_python_cache import ResilientPythonCache, MongoConfig, ResilientDBConfig

async def main():
    mongo_config = MongoConfig(
        uri="mongodb://localhost:27017",
        db_name="myDatabase",
        collection_name="myCollection"
    )

    # resilientdb://localhost/crow to sync localnet
    resilient_db_config = ResilientDBConfig(
        base_url="resilientdb://crow.resilientdb.com",
        http_secure=True,
        ws_secure=True
    )

    cache = ResilientPythonCache(mongo_config, resilient_db_config)

    cache.on("connected", lambda: print("WebSocket connected."))
    cache.on("data", lambda new_blocks: print("Received new blocks:", new_blocks))
    cache.on("error", lambda error: print("Error:", error))
    cache.on("closed", lambda: print("Connection closed."))

    try:
        await cache.initialize()
        print("Synchronization initialized.")
        await asyncio.Future()  # Run indefinitely
    except Exception as error:
        print("Error during sync initialization:", error)
    finally:
        await cache.close()

if __name__ == "__main__":
    asyncio.run(main())

Fetch Transactions by Public Key

Once transactions are synced to MongoDB, you can query them efficiently using the public key of the owner.

Node.js Query (fetchTransactions.js)

const { MongoClient } = require('mongodb');

const mongoConfig = {
  uri: 'mongodb://localhost:27017',
  dbName: 'myDatabase',
  collectionName: 'myCollection',
};

const targetPublicKey = "8LUKr81SmkdDhuBNAHfH9C8G5m6Cye2mpUggVu61USbD";

(async () => {
  const client = new MongoClient(mongoConfig.uri);

  try {
    await client.connect();
    const db = client.db(mongoConfig.dbName);
    const collection = db.collection(mongoConfig.collectionName);

    console.log('Connected to MongoDB for fetching transactions.');

    // Create an index for faster querying
    const indexName = await collection.createIndex({ "transactions.value.inputs.owners_before": 1 });
    console.log(`Index created: ${indexName}`);

    const pipeline = [
      { $unwind: "$transactions" },
      { $unwind: "$transactions.value.inputs" },
      { $match: { "transactions.value.inputs.owners_before": targetPublicKey } },
      { $sort: { "transactions.value.asset.data.timestamp": -1 } },
      { $project: { transaction: "$transactions", _id: 0 } }
    ];

    const transactions = await collection.aggregate(pipeline).toArray();
    console.log(`Transactions:`, JSON.stringify(transactions, null, 2));

  } catch (error) {
    console.error('Error fetching transactions:', error);
  } finally {
    await client.close();
  }
})();

Python Query (fetch_transactions.py)

from pymongo import MongoClient

mongo_config = {
    "uri": "mongodb://localhost:27017",
    "db_name": "myDatabase",
    "collection_name": "myCollection",
}

target_public_key = "8LUKr81SmkdDhuBNAHfH9C8G5m6Cye2mpUggVu61USbD"

client = MongoClient(mongo_config["uri"])
db = client[mongo_config["db_name"]]
collection = db[mongo_config["collection_name"]]

print("Connected to MongoDB for fetching transactions.")

# Create an index for optimized querying
index_name = collection.create_index("transactions.value.inputs.owners_before")
print(f"Index created: {index_name}")

# Define aggregation pipeline to fetch transactions by public key
pipeline = [
    {"$unwind": "$transactions"},
    {"$unwind": "$transactions.value.inputs"},
    {"$match": {"transactions.value.inputs.owners_before": target_public_key}},
    {"$sort": {"transactions.value.asset.data.timestamp": -1}},
    {"$project": {"transaction": "$transactions", "_id": 0}}
]

transactions = list(collection.aggregate(pipeline))

if transactions:
    print("Transactions:", transactions)
else:
    print(f"No transactions found for publicKey: {target_public_key}")

client.close()

Now, your Resilient App can efficiently filter transactions based on user-specific data without slow queries to the blockchain.

Using ResilientDB GraphQL for Transactions and Queries

ResilientDB provides a GraphQL API for seamless interaction with the blockchain, allowing you to send transactions and fetch transaction details efficiently.

Accessing ResilientDB GraphQL

For Localnet: ResilientDB GraphQL is available at:
```
http://localhost/graphql
```
For Mainnet (ResilientDB Cloud):
```
https://cloud.resilientdb.com/graphql
```

ResVault uses this GraphQL API internally to send transactions using stored keys. You can also use it directly in your application.

Sending a Transaction via GraphQL

You can send a transaction to ResilientDB using the postTransaction mutation.

Mutation Example

mutation {
  postTransaction(data: {
    operation: "CREATE"
    amount: 50632
    signerPublicKey: "8fPAqJvAFAkqGs8GdmDDrkHyR7hHsscVjes39TVVfN54"
    signerPrivateKey: "5R4ER6smR6c6fsWt3unPqP6Rhjepbn82Us7hoSj5ZYCc"
    recipientPublicKey: "ECJksQuF9UWi3DPCYvQqJPjF6BqSbXrnDiXUjdiVvkyH"
    asset: {
      data: {
        time: 1690881023169
      }
    }
  }) {
    id
  }
}

Explanation:

operation: "CREATE" defines the type of transaction.
amount: 50632 specifies the transaction value.
signerPublicKey & signerPrivateKey: Used for transaction signing.
recipientPublicKey: Defines the recipient of the transaction.
asset: Stores additional transaction data (any JSON).

🔹 Expected Response:

{
  "data": {
    "postTransaction": {
      "id": "f1df753f782dccd7e345175f67a3f8026113b1074724b202f24aa9073644ab47"
    }
  }
}

The response includes the transaction ID, which can be used to fetch details later.

Fetching a Transaction by ID

You can retrieve transaction details using the getTransaction query.

Query Example

query {
  getTransaction(id: "f1df753f782dccd7e345175f67a3f8026113b1074724b202f24aa9073644ab47") {
    id
    version
    amount
    metadata
    operation
    asset
    publicKey
    uri
    type
    signerPublicKey
  }
}

Explanation:

id: Transaction ID (retrieved from the previous mutation).

Expected Response:

{
  "data": {
    "getTransaction": {
      "id": "f1df753f782dccd7e345175f67a3f8026113b1074724b202f24aa9073644ab47",
      "version": "2.0",
      "amount": 50632,
      "metadata": null,
      "operation": "CREATE",
      "asset": {
        "data": {
          "time": 1690881023169
        }
      },
      "publicKey": "ECJksQuF9UWi3DPCYvQqJPjF6BqSbXrnDiXUjdiVvkyH",
      "uri": "ni:///sha-256;ORrcs4QnlphyiTL69-rcLNPNV_SfaCgmg7ywRhGgYBM?fpt=ed25519-sha-256&cost=131072",
      "type": "ed25519-sha-256",
      "signerPublicKey": "8fPAqJvAFAkqGs8GdmDDrkHyR7hHsscVjes39TVVfN54"
    }
  }
}

Note: Two transactions will have identical IDs if all the fields in the postTransaction mutation are exactly the same. This is because ResilientDB deterministically generates transaction IDs based on the input fields, ensuring consistency across identical transactions.

What You Can Do with ResilientDB GraphQL

Send transactions using postTransaction.
Retrieve transactions by ID using getTransaction.
Use it in ResVault for transaction signing.
Directly interact with ResilientDB via GraphQL instead of manually handling HTTP requests.

Congratulations! Your first Resilient App now has all the essential components set up! You’re now ready to build, authenticate, and interact seamlessly with ResilientDB. Happy coding!

Demo video

Coming soon!

Getting Started with Smart Contract on ResilientDB

Fri, 14 Feb 2025 00:00:00 +0000

Here we illustrate how to run a smart contract on Nexres locally. We provide step-by-step tutorials to set up locally with 4 nodes and use the built-in smart contract service.

Install

Following the instruction install tutorial to initial the environment that runs a Key-Value Service locally. If you are using our cloud, you can ignore the system install section.

Smart Contract Install

It contains three steps if you want to deploy your contract and execute its functions in ResilientDB: Create the contract account, deploy the contract, and execute the functions.

The ‘contract_service_tools’ provides access to the system by providing a JSON file and the service config.

contract_service_tools

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c ServiceConfig –config_file=JSON Path

Parameters:

-c the client configuration path
–config_file the JSON file describing the actions

Create a Owner Account

For creating an account, the JSON file is simply to provide the action:

{
  "command":"create_account",
}

Command:

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c service/tools/config/interface/service.config –config_file=service/tools/kv/api_tools/create.js

Response:

Then, you will see the result

   create account: address: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"

Deploy Your Contract

Contract

Nexres only handles the JSON description of the contract source code. We use solc, a tool from Solidity, to obtain the JSON file. Currently, we only support solidity version is larger than 0.5.0 (solidity >= 0.5.0)

We provide token.sol as an example below:

solc –evm-version homestead –combined-json bin,hashes –pretty-json –optimize token.sol > token.json

Once get your json contract, you can find the contract name(“token.sol:Token”) and its function hashes under the contract name section in the file.

token.sol：

pragma solidity >= 0.5.0;

// Transfer tokens from the contract owner
contract Token {
  mapping (address => uint256) balances;

  event Transfer(address indexed _from, address indexed _to, uint256 _value);

  constructor(uint256 s) public {
    balances[msg.sender] = s;
  }

  // Get the account balance of another account with address _owner
  function balanceOf(address _owner) public view returns (uint256) {
    return balances[_owner];
  }

  // Send _value amount of tokens to address _to
  function transfer(address _to, uint256 _value) public returns (bool) {
    if (balances[msg.sender] >= _value) {
      balances[msg.sender] -= _value;
      balances[_to] += _value;
      emit Transfer(msg.sender, _to, _value);
      return true;
    }
    else
    {
      return false;
    }
  }
}

token.json

{
  "contracts":
  {
    "token.sol:Token":
    {
      "bin": "608060405234801561001057600080fd5b506040516101fe3803806101fe8339818101604052602081101561003357600080fd5b5051336000908152602081905260409020556101aa806100546000396000f3fe608060405234801561001057600080fd5b5060043610610052577c0100000000000000000000000000000000000000000000000000000000600035046370a082318114610057578063a9059cbb1461008f575b600080fd5b61007d6004803603602081101561006d57600080fd5b5035600160a060020a03166100cf565b60408051918252519081900360200190f35b6100bb600480360360408110156100a557600080fd5b50600160a060020a0381351690602001356100ea565b604080519115158252519081900360200190f35b600160a060020a031660009081526020819052604090205490565b33600090815260208190526040812054821161016b573360008181526020818152604080832080548790039055600160a060020a03871680845292819020805487019055805186815290519293927fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef929181900390910190a350600161016f565b5060005b9291505056fea265627a7a72315820600579dee5d66ea3489085c4cb41116045ba977cb4804caac8d5f24e248e337064736f6c63430005100032",
      "hashes":
      {
        "balanceOf(address)": "70a08231",
        "transfer(address,uint256)": "a9059cbb"
      }
    }
  },
  "version": "0.5.16+commit.9c3226ce.Linux.g++"
}

Deploy JSON file

Now we generate the JSON for the deployment. The JSON file contains the command (“deploy”), the contract location, the contract section in the JSON file, the owner_address address who owns the contract (we have created in the previous step), and the initial parameters, which can be empty.

{
  "command":"deploy",
  "contract_path": "service/tools/kv/api_tools/example_contract/token.json",
  "contract_name": "token.sol:Token",
  "init_params": "1000",
  "owner_address": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
}

Command:

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c service/tools/config/interface/service.config –config_file=service/tools/kv/api_tools/deploy.js

Response:

Then you will see the response:

deploy contract:
owner_address: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
contract_address: "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1"
contract_name: "token.sol:Token"

Execute Contract

Now we generate the JSON for the execution. The JSON file contains the command (“execute”), the contract address, the caller address who owns the contract, the function name, and the parameters to run the function.

{
  "command":"execute",
  "contract_address": "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1",
  "caller_address": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8",
  "func_name":"transfer(address,uint256)",
  "params":"0x1be8e78d765a2e63339fc99a66320db73158a35a,100"
}

Command:

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c service/tools/config/interface/service.config –config_file=service/tools/kv/api_tools/execute.js

Response:

Once it is done, you will see the result:

0x0000000000000000000000000000000000000000000000000000000000000001

Using Key-Value Interfaces

The Key-Value interfaces provide the API to access the accounts: get_balance and set_balance.

The JSON files and corresponding commands are shown as below:

{
  "command":"get_balance",
  "address":"0x1be8e78d765a2e63339fc99a66320db73158a35a"
}

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c service/tools/config/interface/service.config –config_file=service/tools/kv/api_tools/get_balance.js

{
  "command":"set_balance",
  "address":"0x1be8e78d765a2e63339fc99a66320db73158a35a",
  "balance":"2000"
}

bazel-bin/service/tools/kv/api_tools/contract_service_tools -c service/tools/config/interface/service.config –config_file=service/tools/kv/api_tools/set_balance.js

Notice

The accounts do not need to be created using the API before being used. However, if the account is used to deploy the contract, it must first be created by the API to register in the contract database.

Future Work

Apply the authorization for the execution that verifies the owner to execute its contracts, like using the signatures.

VoteChain 2.0 - Decentralizing Voting with Blockchain, One Vote at a Time

Mon, 09 Dec 2024 00:00:00 +0000

Overview

VoteChain 2.0 builds on the foundation of the original ResilientApp VoteChain, utilizing ResilientDB’s scalable blockchain infrastructure to create a customizable and secure voting platform. The enhanced app includes customizable voting, voting history, and a results page and discussion panel for each poll. ResVault now provides blockchain-based authentication and enables authorized voting and discussion access. ResilientDB’s blockchain guarantees data integrity, anonymity, and privacy, positioning VoteChain as a scalable solution for institutions seeking transparent yet customizable feedback mechanisms.

Figure 1. VoteChain Home Screen

Motivation

While the original ResilientApp VoteChain was designed for government-level elections, we recognized an opportunity to bring the benefits of secure, transparent voting to smaller communities. Research into voting fairness in the gaming community inspired the idea of decentralized, transparent voting to prevent fraud and build trust. To address these issues, we envisioned a solution that seamlessly blends security with user-friendly functionality that encourages collaboration and engagement. Leveraging ResilientDB’s robust blockchain capabilities, we developed VoteChain 2.0 — a secure, decentralized platform tailored for community use.

Key Features

Secure and Transparent Elections
Single Voting Instance
Immutable Votes
User-Friendly Interface
NEW! User Authentication with ResVault
NEW! Customizable Voting
NEW! Participate in Discussion Panels
NEW! View Poll Results & Personal Vote History

Figure 2. Key Features of VoteChain 2.0

System Architecture

Figure 3. System Architecture of VoteChain 2.0

Tech Stack

ResilientDB - Provides secure, transparent, and tamper-resistant data storage for voting.
GraphQL - Efficient data querying with APIs for transaction operations.
React.js - Builds interactive user interfaces.
Material UI - Ensures responsive design across devices.
Node.js - Handles server-side logic and API communication.
ResVault - Manages user authentication securely.
MongoDB - Organizes poll-related data (topics, votes, messages).

Screenshots

Home Screen

Figure 4. Home Screen

Figure 5. Login Page

Create Polls Screen

Figure 6. Create Poll Screen

Results Screen

Figure 7. Results Screen

Preparation

Install ResVault Chrome Extension

Google Chrome is available on macOS, Linux, and Windows platforms. Please refer to the official Google installation guide based on your platform.

Clone the ResVault repo to get started:

 git clone https://github.com/ResilientApp/ResVault.git
 cd ResVault

Create the build folder in the repository:
```
 npm install
 npm run build
```
Load the extension in Chrome:
- Open chrome://extensions/ in Google Chrome and toggle Developer mode on.
- Click on Load unpacked.
- Select the build folder you just created.
- You should see the ResVault extension in Chrome.

Steps to Run the System

Requirements

Node.js: Download and install Node.js from Node.js Downloads based on your platform.
npm (Node Package Manager): npm is included with Node.js. Verify installation:
```
 node --version
 npm --version
```

Running VoteChain

Clone the VoteChain Git repository to your local machine:

 git clone https://github.com/ItsBaiShiXi/VoteChain.git
 cd VoteChain

Install required dependencies:
```
 npm install
```
Once the dependencies are installed successfully:
- Open a terminal and run the following command to start the backend:
```
   npm run start-backend
```
- Open another terminal and run the following command to start the frontend:
```
   npm start
```
- This will launch the application, and you can access it in your web browser.
Connect the ResVault Chrome extension. You can now anonymously log in to VoteChain through ResVault.

Figure 1. Connecting ResVault to VoteChain

Contributors

Shengzhe Zhang
Xin Tang
Madelyn Nguyen
Zixuan Weng
Xiuyuan Qi

PetChain

Sun, 08 Dec 2024 00:00:00 +0000

Built on the ResilientDB fabric, PetChain provides secure lost-and-found tracking, seamless health record management, streamlined ownership transfer, and automated pet insurance processing, ensuring reliability in pet care.

Project Overview

Motivation

The pet industry, valued at around $150 billion in the U.S. alone, faces critical challenges in pet identification, health record management, and delays in insurance processing. As a team of pet owners and technology enthusiasts, we’ve experienced various challenges in pet ownership—ranging from the frustration of delayed insurance disbursements during emergencies to difficulties accessing reliable information on pet ownership transfers. These shared experiences underscored the need for a unified, secure system that offers pet owners faster and better transparent solutions. This need drove us to develop PetChain, a blockchain-based platform designed to holistically address these issues and enhance the overall pet ownership experience.

Why PetChain?

Scalable and Reliable: PetChain, powered by ResilientDB, delivers a robust platform designed to scale effortlessly with increasing data and users, maintaining high performance and fault tolerance.
Streamlined Lost-and-Found and Ownership Transfers: Leveraging blockchain technology, PetChain enables swift and secure reunification of lost pets with their owners while simplifying the transfer of pet ownership.
Automated Insurance Processing: PetChain uses smart contracts to automate insurance claims, ensuring faster, more efficient, and error-free processes.
Secure and Transparent: Blockchain-based storage ensures pet identification and ownership data remain tamper-proof, fostering trust and transparency in pet care.

Feature Set

Landing Page

SignUp Page

User and Pet Registration

The registration and login workflow in PetChain uses JWT tokens for secure authentication and role-based access control. Passwords are hashed using bcrypt and stored securely in the database. A tamper-proof ownership hash, created using the owner’s custom ID and unique petId with SHA-256, is stored in ResDB for blockchain traceability, while pet details are saved in MongoDB for quick retrieval. Owners can retrieve pet details via the getPetDetails API, ensuring a secure and efficient process for pet registration and ownership validation.

Pet registration event logged in ResDB:

(2024-12-09 11:05:19) [INFO    ] Request: 127.0.0.1:45068 0x7fccdc002870 HTTP/1.1 POST /v1/transactions/commit
I20241209 03:05:19.347833 652360 crow_service.cpp:158] body: {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","ownershipHash":"a44f3f6cb0c0efc4671f254ffe1eeb28a09ae7dfc820f5be21e85c38c2eef74c","timeStamp":"2024-12-09T11:05:19.326Z","status":"active","event":"register pet"}}
I20241209 03:05:19.349356 652360 crow_service.cpp:180] Set OWNER_1733742092244 to {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","ownershipHash":"a44f3f6cb0c0efc4671f254ffe1eeb28a09ae7dfc820f5be21e85c38c2eef74c","timeStamp":"2024-12-09T11:05:19.326Z","status":"active","event":"register pet"}}

User DashBoard

Register Pet

Lost and Found

Figure 1. Sequence Diagram for Lost and Found Service

When a pet goes missing, the owner can report it by clicking the “Lost” button in the user interface, triggering a POST request to the petLostandFound() API. This API updates the pet’s status in MongoDB and generates a unique LostHash using the pet ID, owner ID, and event details, which is then securely stored in ResDB.

(2024-12-09 11:05:19) [INFO    ] Response: 0x7fccdc002870 /v1/transactions/commit 201 0
(2024-12-09 11:06:38) [INFO    ] Request: 127.0.0.1:39276 0x7fccdc000c20 HTTP/1.1 POST /v1/transactions/commit
I20241209 03:06:38.358037 652359 crow_service.cpp:158] body: {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","lostHash":"0d753f137b9725f0bc7b8e29d376f4ff9ae67ff946a8fea7a301695dae293de9","timeStamp":"2024-12-09T11:06:38.354Z","status":"active","event":"lost pet"}}
I20241209 03:06:38.358719 652359 crow_service.cpp:180] Set OWNER_1733742092244 to {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","lostHash":"0d753f137b9725f0bc7b8e29d376f4ff9ae67ff946a8fea7a301695dae293de9","timeStamp":"2024-12-09T11:06:38.354Z","status":"active","event":"lost pet"}}

Mark Pet as Lost

When the pet is found by someone, they can submit the pet’s details via the “Found” feature in the UI, prompting the searchLostPet() API to generate a FoundHash. The system then retrieves the LostHash from ResDB, performs validation and updates the pet’s status to “found,” completing the process of reuniting the pets with its owner.

(2024-12-09 11:08:41) [INFO    ] Request: 127.0.0.1:35466 0x7fccdc002870 HTTP/1.1 POST /v1/transactions/commit
I20241209 03:08:41.755368 652360 crow_service.cpp:158] body: {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","foundHash":"8c85e9e98417656cdbc5172bfac80aa7bde53deda0fd44f8d8d519646cfeb240","timeStamp":"2024-12-09T11:08:41.752Z","status":"active","event":"found pet"}}
I20241209 03:08:41.755961 652360 crow_service.cpp:180] Set OWNER_1733742092244 to {"id":"OWNER_1733742092244","value":{"pet_id":"PET_1733742319324","foundHash":"8c85e9e98417656cdbc5172bfac80aa7bde53deda0fd44f8d8d519646cfeb240","timeStamp":"2024-12-09T11:08:41.752Z","status":"active","event":"found pet"}}

Found Pet

Notify Owner

Pet-Health Management

Health Record Management: Owners can record vaccination history, allergies, minor illnesses, and past treatments for their pets.

Veterinarian Access: A dedicated Veterinarian Profile interface allows vets to view pet health records by entering the pet ID.

Vet Portal

Ownership Transfer

Figure 2. Sequence Diagram for Ownership Transfer

The ownership transfer process in PetChain ensures a secure and seamless experience. When the “Transfer Ownership” button is clicked, a POST request initiates the transfer by generating an approval token, saving the transfer request in MongoDB, and sending an email notification to the new owner’s email using Nodemailer. The email contains an approval link that, when clicked, triggers a POST request to validate the transfer. This involves fetching pet details and ownership hashes from MongoDB and ResDB, validating the data, and generating a transfer hash upon success. The event is logged in ResDB, MongoDB is updated with the new owner’s details, and the new owner is redirected to the website with a success message. In case of validation failure, the transfer is rejected, and the owner is notified via a dialog box.

(2024-12-09 11:25:14) [INFO    ] Request: 127.0.0.1:38158 0x7fccdc002870 HTTP/1.1 POST /v1/transactions/commit
I20241209 03:25:14.258247 652360 crow_service.cpp:158] body: {"id":"OWNER_1733743246179","value":{"pet_id":"PET_1733742319324","ownershipTransfer":{"oldOwnerId":"OWNER_1733742092244","newOwnerId":"OWNER_1733743246179"},"transferHash":"0e3da49f70790cc3d2a761319c8e2432507d36c312f390ef0850f8803701ff99","timeStamp":"2024-12-09T11:25:14.255Z","status":"completed","event":"ownership transfer"}}
I20241209 03:25:14.258463 652360 crow_service.cpp:180] Set OWNER_1733743246179 to {"id":"OWNER_1733743246179","value":{"pet_id":"PET_1733742319324","ownershipTransfer":{"oldOwnerId":"OWNER_1733742092244","newOwnerId":"OWNER_1733743246179"},"transferHash":"0e3da49f70790cc3d2a761319c8e2432507d36c312f390ef0850f8803701ff99","timeStamp":"2024-12-09T11:25:14.255Z","status":"completed","event":"ownership transfer"}}

Initiate Request

Dialog pop up for owner

Approval Request to NewOwner

Old Owner View

Smart Contract Based Insurance Processing

The insurance service in PetChain provides two main functionalities: Add Insurance and Claim Insurance. In the Add Insurance process, a POST API maps a pet’s details (pet ID) to a policy’s information, including the policy number and coverage type. This information is securely stored in MongoDB, finalizing the policy addition. In the Claim Insurance process, a POST API integrates with a smart contract to handle claims in two stages: Pre-Approval, which verifies eligibility based on policy details, and Approval, which calculates the reimbursement amount by considering the coverage type and deductibles. This approach ensures a secure, efficient, and transparent insurance workflow.

Figure 3. Sequence Diagram for Insurance Processing

Add Insurance

Claim Insurance

Technical Specifications

System Architecture

This section outlines how the core components of the PetChain platform are integrated to deliver seamless functionality. The Node.js back-end is used to manage and mediate between the databases and contract services. MongoDB is used for quick retrieval of user, pet, health, and insurance data, while ResDB stores important hashes, IDs, and events for secure blockchain operations. Smart contracts ensure automated and transparent processes like insurance management, and the front-end provides an intuitive interface for interaction with all system features.

Figure 4. Architecture Diagram

Technology Stack

Frontend: React, MaterialUI
Backend: Node.js, Express.js, HardHat, ethers.js, Solidity, Nodemailer
Databases: ResilientDB, MongoDB

Steps to Run the System

Prerequisites

Download NodeJS from here and ensure that it’s added to PATH.

Setup ResilientDB and start KV Service

git clone https://github.com/apache/incubator-resilientdb.git resilientdb
cd resilientdb
./INSTALL.sh
./service/tools/kv/server_tools/start_kv_service.sh

Setup Crow HTTP Service

git clone https://github.com/ResilientApp/ResilientDB-GraphQL.git
cd ResilientDB-GraphQL
bazel build service/http_server/crow_service_main
bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

Running the application

Git clone the repositories linked below into individual folders. Navigate to project directories and run the following command in each.
```
npm install
```

Create a .env file in the backend folder and enter the following:

EMAIL_USER=<email-address>
EMAIL_PASS=<app-password-for-email-account>
JWT_SECRET=<token>
CONTRACT_ADDRESS=<contract-address>
ACCOUNT_ADDRESS=<contract-account-address>
DB_URL=<mongo-db-url>
PRIVATE_KEY=<private-key-for-contract-deployment>

Run the following command in each folder (frontend and backend) to get the application running.
```
npm start
```
Navigate to http://localhost:3001/ to launch application in web browser.

About Team

Sakshi Singh
Ansha Prashanth
Neha Pradeep
Sarika Dinesh

Coinsensus

Sun, 08 Dec 2024 00:00:00 +0000

Coincensus: Split Bills and Track Balances, Powered by ResilientDB

![Photo by GoMoney](https://gomoney.global/blog/worry-less-about-the-bill-when-you-split-it-with-gomoney/)

Managing group expenses and financial transactions is often tedious, error-prone, and vulnerable to privacy breaches with traditional methods. Centralized platforms lack transparency, risk data breaches, and fail to provide secure, real-time updates. This creates a need for a decentralized, transparent, and user-friendly solution to ensure trust, automate calculations, and securely manage group expenses. Coinsensus addresses these challenges with blockchain technology and a seamless interface, redefining expense management.

What is Coincensus?

Coinsensus, a blockchain-based bill management platform powered by ResilientDB, is designed to create a trustless and transparent system for expense tracking among friends and groups. By leveraging blockchain technology’s decentralized and tamper-resistant nature, the project ensures secure and reliable monitoring of debts and lending without relying on a central authority.

Through integrating ResilientDB¹, a high-performance blockchain framework that uses Practical Byzantine Fault Tolerant Consensus Protocol (PBFT)² internally, the system achieves fault tolerance, low latency, and scalability, guaranteeing data integrity even in environments prone to network failures or malicious attacks.

![Photo by Apache ResilientDB **(Incubating)*](https://cdn-images-1.medium.com/max/2000/11yJUI8me1QqUwrQAIlpYrQ.png)

Additionally, Coinsensus also automates balance calculations and updates while maintaining an immutable transaction history, addressing ineﬃciencies in manual record-keeping and vulnerabilities in centralized systems. This product aims to redefine financial technology by oﬀering a resilient, decentralized solution³ that prioritizes data privacy and transparency for the users.

Why Coinsensus?

Strengthens Transaction Management with ResilientDB: Our integration with ResilientDB significantly enhances Coinsensus’ ability to manage financial transactions with unparalleled trust and transparency. Leveraging ResilientDB’s decentralized framework, the platform ensures fault tolerance and robust data integrity, even during network disruptions and malicious activities. This integration provides users with a secure, resilient, and high-performance system, redefining the reliability of payment management.
Streamlined Group Expense Tracking: The core of our application is a robust system for automatic and transparent expense sharing among group members or individuals. Each transaction is securely recorded on the blockchain, creating an immutable and tamper-proof ledger while enabling real-time balance updates. This eliminates the need for manual record-keeping, enhancing eﬃciency, accuracy, and trust within the group and individuals.
User-Friendly Interface: Our frontend application, developed using ReactJS, delivers a seamless and engaging user experience. With an intuitive and user-friendly design, it empowers users to eﬃciently manage their transactions, whether it’s adding expenses, tracking real-time balances, or accessing a detailed transaction history. The application ensures smooth navigation and functionality, making group expense management eﬀortless and accessible for all users.

Architecture Overview

Tools and Development

Coinsensus combines modern front-end frameworks, efficient backend solutions, and powerful blockchain technology to deliver a seamless and secure expense management platform. Here’s an overview of the tools that brought this product to life.

React with TypeScript: Used to develop a highly interactive and scalable user interface, combining React’s flexibility with TypeScript’s type safety for robust front-end development.
Tailwind CSS: Simplified the styling process with its utility-first approach, allowing for the creation of a sleek, responsive, and consistent UI design.
FastAPI: Powered the backend with a high-performance API framework, ensuring efficient data handling and secure communication between the client and server.
ResilientDB: Implemented as the blockchain framework, providing fault tolerance, scalability, and low-latency transaction management for secure and reliable expense tracking¹.
SQLite: A second database used to store the public keys of all the users, which will be eventually used to update the transaction (money sent and received) from both ends.
GIT & GitHub: Enabled version control and collaboration, ensuring smooth teamwork and reliable code management throughout the development process.
JIRA: Facilitated task tracking and project management, helping the team stay organized, manage sprints, and deliver features efficiently over six sprints of one week each.

Design Flow of Coincensus

Coincensus Workflow

New Users: Register an account by providing personal details, then proceed to the landing page after successful registration.
Existing Users: Log in with credentials to directly access the home page.

After the authentication procedure, the application redirects to the landing page where we can see recent transactions, add expenses, check groups, and settle payments. Access the side menu, which includes the following sections:

Activity: View recent transactions.
Friends: Add new friends and view balances related to friends.
Account: Customize user settings like theme preferences and currency.

3. Activity Section

View a summary of recent financial transactions for quick updates.

4. Friend Management

Add Friends: Add friends to enable expense tracking and settlement.
View Balance for Friends: Monitor individual balances with friends
Settle Up: If a user decides to settle balances, process the payment directly. After payment, update the ledger.

5. Adding and Splitting Expenses

Select Expense Type: Choose a group for shared costs or choose specific friends for one-on-one expenses.
Enter Details: Add expense specifics like amount and description.
Choose Split Type: Distribute the amount evenly or allocate costs as per user input.

Save the transaction, which updates the blockchain ledger in real time.

6. Account Settings

Edit Profile: Update user information like name and avatar.
Light/Dark Theme: Toggle between themes for a personalized interface.
Currency Settings: Customize currency preferences based on user location.
7. Transaction Processing
Every action, such as adding an expense or settling balances, updates the tamper-proof blockchain ledger using ResilientDB. This ensures real-time synchronization and transparency. Each transaction is saved securely on the blockchain, ensuring an immutable and auditable history.

8. Caching

Using lightweight fast access SQLite DB to cache frequently queried data to decrease latency.

9. Error Handling and Validation

Include mechanisms to validate user input and resolve errors (e.g., insufficient funds or incorrect splits).

Impact

**Decentralized Trust and Data Security: **By using blockchain with ResilientDB, Coinsensus ensures secure, immutable transactions, reducing reliance on centralized platforms and minimizing the risk of data breaches, giving users more control over their financial data.
**Efficient Financial Reconciliation: **Coinsensus automates balance and transaction calculations, eliminating manual reconciliation, reducing human error, and saving time for individuals and groups, leading to smoother financial settlements.
**Encourages Financial Literacy: **By automating calculations and providing transparent transaction histories, Coinsensus promotes financial awareness and better decision-making, helping users improve their financial literacy.

Project Demo

A short project video demo showcasing the implementation of Coinsensus:

Demo link: https://youtu.be/O51VAFmH8Vw

Conclusion

Coinsensus demonstrates the power of blockchain technology in finance and expense management. By combining decentralization, automation, and an intuitive interface, the platform resolves inefficiencies and builds trust among users. This project sets the stage for more resilient, secure, and transparent financial management solutions, offering a significant step forward in financial technology.

Future Work

**User Features: **Automate feature for real-time notifications for payment reminders and updates and facilitate connecting with friends in the application.
Integration and Interoperability: Integrate Coincensus with third-party payment gateways for transaction settlements.
User Experience Enhancements: Integrate a chatbot feature powered by NLP (Natural Language Processing), to assist users with bill management queries.
Advanced Security: Develop fraud detection and reporting algorithms to flag malicious or suspicious activities while recording payment transactions.
Community Engagement: Build and integrate features for group budgeting, enabling users to set financial goals and track progress collaboratively.

References

[1] Apache ResilientDB: Global-Scale Sustainable Blockchain Fabric https://resilientdb.apache.org/ [2] Gupta S, Hellings J , Sadoghi M. (2021). Fault-Tolerant Distributed Transactions on Blockchain, Synthesis Lectures on Data Management, February 2021, Vol. 16, No. 1 , Pages 1–268 [https://doi.org/10.2200/S01068ED1V01Y202012DTM065] [3] Nakamoto, S. (2008). “Bitcoin: A Peer-to-Peer Electronic Cash System” [https://bitcoin.org/bitcoin.pdf]

Thank you for exploring Coincensus with us! We encourage you to experiment with ResilientDB’s features in your projects too!

Credits

Go through the detailed code, @coinsensus-frontend & @coinsensus-backend

Happy Blockchaining!

Click here to check out more blogs on ResilientDB. [@blog.resilientdb](https://blog.resilientdb.com/)

ResMark - Revolutionizing Attendance and Quiz Tracking

Sun, 08 Dec 2024 00:00:00 +0000

What is ResMark?

ResMark is system designed to streamline attendance and quiz monitoring in educational institutions by integrating geolocation technology with the robust security of blockchain. Built on ResilientDB and ResVault, this system offers a secure and tamper-proof solution to ensure fairness and accuracy in tracking students’ attendance and quiz submissions. Using HTML5 Geolocation and JavaScript, ResMark determines the coordinates of the classroom location and verifies whether a student’s request originates within a 50-meter proximity of the class. If the student is physically present within this geofenced area, they are granted access to mark their attendance and proceed to take the quiz. By combining geofencing and blockchain, ResMark eliminates fraudulent attempts at remote check-ins or quiz submissions, ensuring that attendance and quiz participation are strictly tied to physical presence.

ResMark - In Action!

Youtube

Architecture Diagram

Below is a diagram showing the architecture of ResMark and the high-level structure:

Figure 1. Diagram displaying the architecture of ResMark and how data is passed between the different services.

The diagram above shows the overall architecture of ResMark and the way various services interact with each other. The user can be either the Student or Professor. Users will login to the system using ResVault. ResVault is used to authenticate and let the user into the system. The request is then sent from the user’s browser to the GraphQL server which communicates with ResilientDB using the Resilient JS SDK. ResilientDB is used as the primary blockchain to store the public key and transaction details having attendance, quiz answers. MongoDB is used as a second database for custom indexing. The server interacts with MongoDB for data fetching and adding. To allow the sync between MondoDB and Resilient DB, the resilient-node-cache package is used.

Flowchart

Below Flowchart shows overall flow of the application with both Admin (Professor) and User (Student) flow.

Figure 2. Diagram displaying the flowchart of ResMark showing how the user interacts with the system.

Technology stack

Web Application: ReactJS, HTML5/CSS3, JavaScript, TailwindCSS
Backend: NodeJS, ExpressJS, Python, GraphQL
Database: ResilientDB (blockchain), MongoDB, resilient-node-cache (package for syncing)
APIs: HTML5 Geolocation API

Screenshots

Authentication with ResVault

Figure 3. Displaying the screenshot of user logging in via ResVault.

Marking Attendance

Figure 4. Displaying the screenshot of the mark attendance page where initially the system asks for location permission.

Figure 5. Displaying the screenshot of the mark attendance page when student can mark attendance only if present within the class boundaries

Figure 6. Displaying the screenshot of the mark attendance page when student cannot mark attendance outside of the class boundaries

Attempting the Quiz

Figure 7. Screenshot displaying the UI for attempting the quiz where student location is not within bounds.

Figure 8. Screenshot displaying the UI for attempting the quiz only displayed when the User location is within the classroom proximity.

Student Dashboard

Figure 9. Screenshot displaying Student dashboard showing the overall status of all the quizzes taken by the student, courses registered and the attendance in classes along with the score.

Running the Application

Prerequisites

Before running the ResMark application, you need to start KV service on the ResDB backend and the SDK and setup the ResVault.

ResilientDB

Clone the resilientDB repository and follow the instructions to set it up:

git clone https://github.com/apache/incubator-resilientdb

Setup KV Service:

./service/tools/kv/server_tools/start_kv_service.sh

SDK

Clone the GraphQL Repository and follow the instructions on the ReadMe to set it up:

Install GraphQL:

git clone https://github.com/ResilientApp/ResilientDB-GraphQL

Setup SDK:

bazel build service/http_server:crow_service_main

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

ResVault

git clone https://github.com/apache/incubator-resilientdb-resvault

Steps -

Generate the build file
Enable developr mode and unpack the build file in chrome extensions.
Register on ResVault

Running the ResMark Application

Clone the repo and open it in a new folder.

git clone https://github.com/preyashyadav/resmark-v1/
cd resmark-v1

For syncing between ResDB and mongoDB package called resilient-node-cache. To install this -

npm i resilient-node-cache

Install other dependencies

npm install

To run the code -

ResMark - Client

cd client
npm start

Application will be deployed on http://localhost:3000.

ResMark - Server

cd server
npm start

Server runs on http://localhost:5000 in development mode.

Future Work

1. Integration with University Schedule Builder -

ResMark can be integrated with the university’s Schedule Builder app to automatically retrieve class locations and course schedules of the student.

2. Canvas Integration -

ResMark can be further integrated with Canvas or similar LMS platforms to directly post quiz grades and attendance records, ensuring real-time updates and accessibility for both students and instructors.

3. Mobile Application Development -

ResMark can be expanded to develop a mobile application for on-the-go access, allowing students and professors to interact seamlessly with the platform via their smartphones.

Source Code Repositories:

ResMark
ResilientDB
GraphQL
ResVault

Presentation Slides:

Slides

Contributions:

Fullstack Development - Preyash Yadav (https://preyashyadav.com)
Frontend development - Sanjana Mali, Hemang Singh
Backend Development - Akanksha Kulkarni, Varun Singh

University of California, Davis
CA

ResIdentity Document Signer

Sun, 08 Dec 2024 00:00:00 +0000

Powered by the robust ResilientDB fabric, ResIdentity secures crucial documents with a tamper-proof signing process that ensures verifiable integrity and heightened protection.

Project Overview

Background

What ResIdentity Does
ResIdentity is a document signing application that allows users to securely authenticate and upload PDFs for signing. The digests of these signed PDFs are committed to the ResilientDB blockchain, which ensures that each document’s signature remains unaltered. Users can then download their signed PDFs as needed.

Additionally, ResIdentity enables users to upload signed PDFs for verification. During this process, the application checks the ResilientDB blockchain for a matching digest of the signed document to verify its authenticity.

Motivation

Why We Built ResIdentity
The need for secure and reliable document signing cannot be overstated. Traditional platforms, while prevalent, often fail to meet the necessary standards for handling sensitive documents like insurance contracts, loan paperwork, employment offers, etc. These platforms typically rely on centralized servers, which, if compromised, can expose personal information at the risk of theft or alteration. Such centralized systems are vulnerable to service disruptions owing to a single point of failure. This can impact the availability of critical services when they are most needed, causing operational delays, user frustration and reduced trust. Furthermore, privacy is another concern with conventional document signing solutions. Users must entrust their sensitive information to third-party providers, who manage and control all aspects of data security, leaving them withwith little control over their own data.

ResIdentity was built to address these vulnerabilities by leveraging the power of blockchain technology.

What Sets Us Apart

By using the ResilientDB blockchain to store document digests, ResIdentity ensures that each document’s signature is immutable and verifiable. This decentralized approach eliminates single points of failure, enhances data security, and gives users full control over their documents. The blockchain’s inherent transparency also means that every transaction is auditable, providing a layer of accountability and trust that traditional platforms cannot match.

Through ResIdentity, we aim to restore confidence in digital transactions and empower users with a tool that upholds the integrity and privacy of their documents, redefining the standards for document security in the digital world.

Feature Set

Registration

A user’s interaction with ResIdentity begins at Registration, which features a straightforward interface that requires information such as an email address, a secure password, etc. for registration. A public-private keypair is generated after successful registration and is stored at the client’s machine; the public key is stored in MongoDB.

Returning users can quickly enter their email address and password to continue their secure journey on our platform. Upon login, users are redirected to a dashboard which presents the options to upload a PDF, verify an already signed PDF and logout.

Upload PDFs

Our minimalist Upload PDF interface ensures a clear and direct user experience, allowing you to quickly upload your PDF for signing or verification with just a click.

Sign PDFs

ResIdentity’s PDF Signing UI displays the document uploaded in the previous step on the right for confirmation. On the left, it prompts the user to re-enter their password for additional security before affixing their signature to the document.

Download PDFs

When the signed document is retrieved from ResIdentity’s backend service, this interface faciliates its saving on the user’s machine.

Verify Signed PDFs

Users can quickly verify the authenticity of signed PDFs with by simply uploading their signed documents to ensure that they are genuine and unaltered.

User Guide

Setup

Dependencies: Docker Compose, ResilientDB

To build and launch ResIdentity Server, run:
```
docker-compose up -d --build
```

If ResilientDB’s KVService doesn’t start by default, run:

docker exec resid-core-backend bash -c "cd /resdb && chmod +x INSTALL.sh && chmod +x service/tools/kv/server_tools/start_kv_service.sh && ./INSTALL.sh && service/tools/kv/server_tools/start_kv_service.sh"

To verify the status of KV Service, run:

curl -X POST -d '{"id":"key1","value":"value1"}' 127.0.0.1:18000/v1/transactions/commit
curl 127.0.0.1:18000/v1/transactions/key1

The server should be running on http://localhost:8000/. Visit http://localhost:8000/api to verify its status.

Usage (Screenshots)

User Registration

Upload, Sign & Download

Viewing the Signature

Verifying Signature Authenticity

Tech Specs

Technology Stack

Frontend Frameworks:
Next.js, Tailwind CSS
Backend Frameworks:
ResilientDB, Docker, Python FastAPI, MongoDB, AWS S3

Architecture

Sequence Diagrams

User Registration

PDF Upload, Signing and Download

Signature Verification

About The Developers

Sachin Shankar Balasubramanyam: A first-year MSCS student at UC Davis, Sachin earned his Computer Science degree from PES University, Bengaluru, in 2023. He was the lead engineer at a VC-funded AI startup, with expertise in software architecture, Python, and web development, essential for ResIdentity’s client application.
Ananya Pandey: Ananya is an MSCS student at UC Davis. She earned her Bachelor’s in Computer Science from PES University, Bengaluru, in 2018. With over five years of software development experience at Zebra Technologies and Expedia Group, she specializes in Android/AOSP, 802.11 protocols, Node.js, Spring Boot, and AWS, focusing on backend services for ResIdentity.
Anish Kataria: Anish is pursuing an MS in Computer Science at UC Davis, with a Bachelor’s in Computer Science from VIIT, Pune (2023). Formerly an Associate Software Engineer at LogicMonitor, he focused on backend development with Golang, Docker, Kubernetes, and scalable microservices. Anish is dedicated to the client application for ResIdentity.
Shyam Varahagiri: Shyam is a first-year MSCS student at UC Davis and graduated from Manipal University Jaipur in 2024 with a BTech in Information Technology. He worked 11 months at Tata Elxsi as an MLOps Developer, using Docker, Kubernetes, and Python, and has frontend experience with React and Typescript. Shyam works on ResIdentity’s backend.
Kiransingh Pal: Kiran, an MSCS student at UC Davis with a Bachelor’s in Electronics and Telecommunications from Pune Institute of Computer Technology, has two years at miniOrange, leading Cloud Access Security projects, building cross-browser extensions, and working with MERN, Golang, Docker, and Kubernetes. Skilled in blockchain and multi-wallet solutions, Kiran focuses on client app development for ResIdentity.

ResAuc, Engineering Transparency in Every Bid.

Sun, 08 Dec 2024 00:00:00 +0000

ResAuc is a decentralized online auction platform built on blockchain technology (ResellientDB), ensuring transparent, secure, and anonymous bidding. Experience fair auctions with real-time updates and user-centric features.

Contributors: Dhairye Gala, Himanshu Nimonkar, Sayali Lokhande, Shray Arora, Shreyas Shah

Project Link: ResAuc

Presentation Link: PPT

Introduction

Motivation

Since ancient times, auctions have been an important component of trade that facilitates the exchange of commodities and services. Conventional auction houses have long served as go-betweens for buyers and sellers, providing platforms for people to participate in auctions online, in-person, or hybrid formats. Sellers usually submit their items to auction houses for evaluation and appraisal; the auction company receives a commission for these services. These auction houses make transactions easier, but they limit the accessibility and fairness of the auction process by introducing problems with cost, inefficiencies, and potential bias. Furthermore, the dependence on actual locations and centralized systems may hinder the growth of traditional auctions, which causes challenges in adapting to modern demands.

Gap

A decentralized auction system that provides a more fair, transparent, and economical setting is becoming increasingly necessary as our reliance on digital platforms grows. By eliminating intermediaries, a decentralized auction platform would provide buyers and sellers more freedom. These platforms are also in line with the principles of distributed ledger technologies (DLTs) and blockchain, which have gained popularity due to their capacity to provide transactions with immutability, security, and transparency [1]. In addition to lowering risks like fraud and manipulation, these technologies ensure that buyers and sellers can engage in transactions without the assistance of a reliable third party.

Existing centralized auction platforms, such as eBay, often struggle with trust issues and high service fees. This further highlights the need for a decentralized solution [2]. Moreover, traditional auction systems often face problems related to bidding transparency and transaction recording. The development of decentralized platforms leverages the strengths of blockchain and DLTs to address these limitations. In particular, these platforms will provide transparency through an immutable ledger, thus allowing all transactions to be publicly recorded and available for verification.

Problem Statement

Our project, ResAuc is a decentralized auction platform that integrates ResilientDB [3] to transparently record all transactions, allowing for greater user control. Sellers can independently list their items, set minimum bids, and finalize sales with the highest bidder, while buyers participate in a secure, anonymous, and fair environment. Moreover, the platform is being developed with key features such as user profile management, real-time bid tracking, and a feature that enables sellers to close sales with the highest bidder. This report discusses the objectives and development of ResAuc, its integration with ResilientDB, its architecture and the working of ResAuc.

Objectives

ResAuc provides a decentralized, transparent, and secure platform for both buyers and sellers in an effort to improve the online auction process. Built on the foundation of ResilientDB, the platform prioritizes user control and efficiency by eliminating intermediaries and promoting direct communication to facilitate auctions. The primary objectives of ResAuc are:

Transparency: Makes use of ResilientDB’s blockchain-backed architecture, which offers an immutable ledger to record all events, which enables secure and transparent auction transactions.
Decentralization: By eliminating the need for third parties to participate in auctions, users can communicate with one another directly, which lowers overhead costs.
User Centric Experience: Provides a user-friendly platform that enables users to manage transactions with real-time updates, and create detailed auction listings and place bids.
Live Bid Updates: Incorporates live bid tracking to keep users informed of the current auction status.
Anonymity for Buyers: Maintains the privacy of bidders and sellers to prevent bias and manipulation.
Purchase & Sale History: Provides a comprehensive history of the items and prices that users have bought and sold.

Market Opportunity

The online auction industry has seen exponential growth in recent years, driven by the rise of E-commerce and the increasing comfort of users engaging in digital transactions. The global online auction market was valued at approximately 568.94 billion USD in 2023 and is projected to grow at a compound annual growth rate (CAGR) of 9.21%, reaching 934.25 billion USD by 2032 [4]. Global platforms like eBay and Christie’s online auctions have demonstrated the demand for such systems. However, these centralized platforms frequently face problems including high costs, trust issues, and limited flexibility for users. The market opportunity for a decentralized auction platform like ResAuc lies in addressing these shortcomings. Blockchain technology offers a transformative solution by decentralizing the auction process and eliminating the need for conventional intermediaries. A blockchain-based platform gives sellers access to a bidder pool. Transactions are recorded on a secure and distributed ledger, providing an immutable and transparent history of every auction event. In addition to improving trust and accountability, this decentralized approach significantly reduces operational costs, which can be as high as 10–20% in traditional auction systems. Because all transactions can be audited on the public ledger, fraud [5], a persistent concern in traditional systems is mitigated. The transparency of blockchain ensures that every participant has equal access to the bidding process. Furthermore, blockchain allows for almost rapid settlement using cryptocurrencies, whereas traditional auction houses can take days or weeks to settle deals because of human processing and reliance on financial institutions. With its ability to address these issues, a blockchain-based auction platform like ResAuc capitalizes on a significant market opportunity. In addition to eliminating the high costs and inefficiencies associated with traditional auction houses, it also introduces a transparent and user-friendly system made to meet the changing demands of buyers and sellers in a globalized economy. ResAuc provides an affordable alternative that appeals to both sellers seeking maximum value for their items and buyers looking for fair competition without concerns of fraud. Furthermore, leveraging blockchain technology through ResilientDB establishes ResAuc as an innovative platform that aligns with the increasing demand for secure and transparent digital marketplaces.

Architecture Overview

Figure 1 shows the system architecture along with the technologies used for building ResAuc. The following subsections discuss each of them in detail.

Backend

The backend of the system is built using Node.js and Express.js to provide a robust and scalable architecture that supports asynchronous handling of multiple user requests. The backend architecture uses Express.js as the API layer, acting as a bridge between the frontend, backend logic, and databases. Express.js ensures efficient communication by handling incoming HTTP requests, processing them through the middleware and routing layers, and sending appropriate responses. User registration and login functionalities are implemented using bcrypt for secure password hashing. The authorization mechanism ensures users can interact only with their own data when appropriate. Additionally, the backend also manages bid processing and auction listings. By entering information such as the item title, description, minimum bid amount, and image (Base64 encoded), users can create new listings. It also lets users place bids on items listed by others while imposing restrictions like minimum bid value and highest bid validation. The backend also offers user-specific features, such as retrieving listings created or purchased by a user and marking items as sold upon completion of transactions. The backend updates the database to reflect the sale status of the item after an auction is finalized. This is the GitHub repository for the backend code.

The frontend interacts with the backend through RESTful APIs, facilitating seamless communication and data exchange. This connection allows users to perform actions like posting bids, creating auction listings, and viewing purchased or listed items. The APIs ensure real-time updates and transaction processing, thus enhancing the user experience by providing immediate feedback on actions such as bid placement and transaction confirmation.

Figure 1: System Architecture

The APIs are divided into four categories: User Management, Listing Management, Bidding, and Transaction Tracking.

User Management
- register: Manages user registration by checking whether the username already exists. If not, it generates a new user with the provided username and password and saves it to the database.
- login: Handles user login by verifying the entered username and password. It checks if the user exists in the database and compares the password with the stored hash.
Listing Management
- new-listing: Creates a new listing by validating fields such as title, description, minBidValue, username, and image. After that, it stores the modified user information and adds the new listing to the user’s profile.
- all-listings: Retrieves all listings from all users by first fetching all users from the database, then extracting and concatenating their listings into a single array.
- my-listings: Retrieves the listings of a specific user based on the username provided.
- delete-listing: Allows a user to delete a specific listing. It removes the listing from the user’s profile and updates the database.
- sell-item: Allows a user to sell an item by selecting the highest bid. It first ensures that there are bids placed on the listing, then marks the item as sold, recording the final selling price and the buyer’s username in the soldTo field (not displayed on the ledger to maintain anonymity).
Bidding
- post-bid: Allows a user to place a bid on a listing. It ensures that the user is not bidding on their own listing, that the first bid meets the minimum bid value, and that subsequent bids are higher than the current highest bid.
Transaction Tracking
- bought-by-me: Retrieves all items purchased by a specific user by checking which listings have the soldTo field matching the provided username. It returns an array of items bought by the user from all sellers.
- sold-by-me: Retrieves all items sold by a specific user. It checks if the user exists, filters through their listings to find the ones marked as sold, and returns the list of sold items.

Table 1 provides a list of the key APIs, grouped by their respective categories.

Table 1: List of APIs

All the information is stored on the MongoDB database while the ledger records information about new listings, bids and deleted listings.

Frontend

Frontend of the ResAuc platform is designed with a user-friendly interface leveraging React and Bootstrap for responsive layouts. It primarily serves the core functionalities for user login/registration, auction listings, and bid placements. While ExpoLab [6] provides skeletons in both Vue.js and React.js for integration with the ResVault [7] browser extension, React.js was chosen for its robust library ecosystem, flexibility, and component reusability. React’s component-based approach enables the efficient reuse of UI elements, which streamlines development and ensures consistency across the application. To further enhance functionality, the frontend integrates with the ResVault browser extension. This enables secure transaction handling and blockchain interactions.

The frontend features secure login and registration forms that handle user authentication. Users can view, create, and participate in auctions through an interactive interface. A personalized dashboard allows users to view all listings, their active listings, bids, and auction history. It provides quick access to the user’s auction activities, including items they are selling, bidding on, or have won. Listings are displayed with details like title, description, minimum bid, and current bid status. This is the GitHub repository for the frontend code.

Database

The backend of the auction platform uses two databases, namely MongoDB and ResilientDB. MongoDB is used as the primary NoSQL database for real-time storage and retrieval of data such as creating new listings, deleting listings, placing bids, user profiles, and bid history. Its flexible schema allows for seamless handling of frequently updated records, which is crucial for an active auction environment where data such as bids and listings changes. ResilientDB is integrated into the system to address the need for transparency and accountability. It is used to maintain a ledger of completed auctions. When a listing is made, a bid is placed, or an item is sold, ResilientDB is leveraged to record these events in a tamper-proof manner, ensuring that users can trust the integrity of the auction result.

ResilientDB and its integration with ResAuc

ResilientDB is a decentralized, fault-tolerant database designed to provide transparency and security for online transactions. It is particularly well-suited for applications like ResAuc, where trust and security are essential. ResilientDB plays a crucial role in the backend architecture of ResAuc by providing a decentralized and transparent method for recording transactions. The frontend integrates with ResilientDB via the ResVaultSDK. ResVaultSDK acts as an intermediary that enables the frontend to communicate with the ResVault browser extension. Through ResVaultSDK, the transaction data is securely sent from the frontend to the browser extension, which then posts the transaction to the ledger. The SDK enables secure communication with the decentralized database, allowing users to initiate transactions by sending messages such as bids or purchases. The integration ensures that transactions are processed securely and are immutable once committed. Once the transaction is processed, the user receives a response showing whether the transaction was successful or failed. This response is reflected in the frontend through a modal, thus ensuring that users are notified immediately of the transaction status.

Authentication Mechanism

The authentication mechanism in ResAuc leverages ResVault, to ensure secure user access. This is shown in Figure 2. ResVault is a Chrome extension that serves as a wallet for ResilientDB. Figure 2: Authentication via ResVault
The authentication process for the platform is divided into two parts:

ResVault Extension Authentication: This authentication leverages the preexisting authentication mechanism provided by the skeleton framework. It ensures that the ResVault extension is properly connected to the ResDB mainnet. This establishes a secure communication channel between the client and the blockchain network.
User Authentication: This part handles user-specific authentication for the app. It interacts with MongoDB to retrieve user data and bid information, verifying the user’s credentials and ensuring that the appropriate data is accessed for actions such as placing bids and managing listings. Figure 3: Transaction Form

Working of ResAuc

In this section, we describe the different views of ResAuc and the detailed working of the application. The sketch of the top to down working is illustrated in Figure 4. Figure 4: High-level Working of ResAuc

User Registration & Login: When users first visit ResAuc, they are given the option to either sign up for a new account or log in with existing credentials. New users can create an account by entering a username and password as shown in Figure 5a. Returning users can enter their credentials to access the platform on the login page as shown in Figure 5b. Figure 5: User Registration & Login
Dashboard: After logging in, users are presented with the dashboard, as showcased in Figure 6. This view displays a list of ongoing auctions with details such as item description, minimum bid value, current bid amounts and item image. Users can browse through the auctions to view the items up for bidding and then place bids on them. A seller cannot place a bid on the item they have listed themselves. There is a common navbar for all pages from where a user can navigate to the dashboard, my listings, new listing, items sold, items bought and logout of the account. Figure 6: Dashboard
Listing Items for Auction: As shown in Figure 7, users can access the New Listing button where they can provide the details about the item such as item title, description, minimum bid value and also upload an image of the item. Upon submitting the form, the item details are securely stored on ResilientDB. The item is then visible to all users on the dashboard under all listings. Figure 7: Create New Listing
My Listings View: Under My Listings, users can see a consolidated view of all the items they have listed for auction. Users can monitor the progress of their active auctions, delete a listing if needed and sell the item to the highest bidder if they feel they are getting a sufficient amount for their item. This section is shown in Figure 8a. However, users cannot delete a listing that has already been sold. Once an item has been sold, the ”Sell Item” button will be replaced with ”Sold” for that particular item. This is shown in Figure 8b. Figure 8: My Listings
Items Sold View: On this page, as depicted in Figure 9, sellers can view the items that have been successfully sold through ResAuc. It includes details such as the item information and the final selling price. This helps users keep a record of their transactions for reference. Figure 9: Items Sold
Items Bought View: Buyers can use this section to view the items they have purchased through the platform. It includes information about the item and the price that the item was bought for. This is shown in Figure 10. Figure 10: Items Bought

Future Work

Future developments to ResAuc will focus on addressing current issues and improving the user experience even further. The following are important areas for improvement:

Identity Verification: To lower the risk of fraudulent activities, implement mechanisms to verify the identity of both buyers and sellers to authenticate their legitimacy.
Seller Bidding Restrictions: Put limitations to prevent sellers from using several accounts controlled by the same user to bid on their own listings. This could involve identity verification techniques or IP-based tracking.
Payment Gateway Integration: To manage transactions between the buyers and sellers, integrate a secure payment gateway.

Conclusion

In conclusion, ResAuc effectively uses ResilientDB’s features to meet the demand for a decentralized, transparent, and secure online auction platform. The platform enables users to conduct transactions directly by eliminating the need for intermediaries.

The backend plays an essential role in managing transactions, keeping track of auction records, and ensuring secure communication between users and the blockchain database. The React.js based frontend, integrated with ResVault for authentication and transaction validation, ensures seamless user interactions and real-time updates. Users can easily create listings, place bids, and manage their auctions with the frontend and backend working together to provide an effective system.

While ResAuc accomplishes its main objectives, it also identifies areas for improvement, such as improved fraud detection, identity verification, and additional user-focused features. ResAuc demonstrates how blockchain-based solutions may revolutionize conventional auction systems and open the door to innovative, transparent, and safe e-commerce ecosystems.

Contributions

Shreyas Shah (Frontend + Database Engineering): React.js Frontend Skeleton, Database Architecture, ResVault Integration with React.js, Integration of Web App
Dhairye Gala (Backend Engineering): Node.js with Express.js Backend, Integration of Web App
Shray Arora (FullStack Engineering): Node.js with Express.js Backend, Frontend Skeleton
Himanshu Nimonkar (Frontend Engineering): React.js Frontend Beautification, Feature Additions, Integration of Web App
Sayali Lokhande (FullStack Engineering): Database Architecture, Node.js Final Fixes, ResVault Integration

References

[1] B. Liu, ”Overview of the Basic Principles of Blockchain,” 2021 International Conference on Intelligent Computing, Automation and Applications (ICAA), Nanjing, China, 2021, pp. 588–593, https://doi.org/10.1109/10.1109/ICAA53760.2021.00108
[2] E. Chiquito, U. Bodin, O. Schel´en and a. Ahmed Afif Monrat, ”Digitalized and Decentralized Open-Cry Auctioning: Key Properties, Solution Design, and Implementation,” in IEEE Access, vol. 12, pp. 64686–64700, 2024, https://doi.org/10.1109/ACCESS.2024.3395791
[3] Suyash Gupta, Sajjad Rahnama, Jelle Hellings, and Mohammad Sadoghi. 2020. ResilientDB: Global Scale Resilient Blockchain Fabric. Proc. VLDB Endow. 13, 6 (feb 2020), 868–883, https://doi.org/10.14778/3380750.3380757
[4] Market, “Online Auction Market Size, Share — Trends Analysis Latest,” Marketresearchfuture.com, 2023. https://www.marketresearchfuture.com/reports/online-auction-market-22699
[5] Agarwal, Udit & Rishiwal, Vinay & Tanwar, Sudeep & Yadav, Mano. (2023). Blockchain and crypto forensics: Investigating crypto frauds. International Journal of Network Management. 34. 1–32. https://doi.org/10.1002/nem.2255
[6] ”Mohammad Sadoghi — ExpoLab”, Expolab.org, 2023. https://expolab.org/
[7] E. S. Lab, “Getting started with ResVault — incubator-resilientdb-blog,” Resilientdb.com, Sep. 21, 2023. https://blog.resilientdb.com/2023/09/21/ResVault.html (accessed Dec. 06, 2024).

ResArtifact - Resilient based Artifact Repository

Sun, 08 Dec 2024 00:00:00 +0000

ResVault is a novel decentralized tool that utilizes blockchain technology to track and store valuable artifact information securely. We have applied a blockchain-based distributed database, ResilientDB, for digital and physical artifact repositories for museums, auction houses, institutions, and individuals. ResArtifact will be available for all users to review its transactions on a collection page displaying each artifact’s name, image, and description. Each artifact will contain a ledger of all transactions that provides its precedence of location, date moved, and changes in condition. This information is available for the public to learn about an artifact or determine whether a claimed artifact is valid and make an update.

Since each transaction is important in proving an artifact’s validity, we must ensure that only authenticated users can add artifacts. Institutions or individuals that own artifacts will have access to a secure account that allows them to add new artifacts, view their private collections, and transfer artifacts. They will also be able to view the history of their individual artifacts. Without needing a login, a user can view the collection of all artifacts from all users and search for artifacts as well. This accessibility to both the general public and authorized users allows everyone to use the ResArtifact.

Figure 1. Image describing ResArtifact

Useful Links

Code Repository - https://github.com/ResilientApp/ResArtifact
Presentation Slides - https://docs.google.com/presentation/d/1SRIOvvB1Q6AJXESoSLsloJ1OOTNwrJiL6jXSrmAEMBg/edit?usp=sharing
Demo Video: https://drive.google.com/file/d/132lPbKemscHogvfnuNQIpsq9pLJg3BRZ/view?usp=sharing

Problem Identified

Our market opportunity is to provide art museums and collectors with a way to verify and conduct transactions on valuable art pieces. We believe that there currently is no decentralized platform to host transactions for art pieces and that ResArtifact will provide both security to this market. Furthermore, there will be general interest from art enthusiasts who won’t have access to creating and logging transactions but will be able to search for artifacts and view them.

Solution

To solve this problem we use blockchain technology, which has already been successfully applied in similar fields such as land registries. This improves the security of the database by preserving essential information about all known artifacts. A registrar for artifacts is extremely valuable as the documentation for an artifact’s history is directly tied to its value. All entries into the database must be authenticated and data will not be lost thanks to the redundancy of all distributed nodes owning the most current ledger. Institutions may purchase or trade artifacts without worry of fakes thanks to the ledger’s information on the validity of the piece as well as any changes in ownership. Art enthusiasts may also know whether the original artifact is available for public viewing.

Technology Stack

React.js
Backend: ResilientDb GraphQL server, MongoDB
Database: ResilientDB

Figure 2. Technology Stack of ResArtifact

Architecture

Figure 3. Sequence Diagram of Adding an Artifact

Figure 4. Sequence Diagram of Transferring an Artifact

Figure 5. High-Level Design of Artifact

Features and User Guide

Home Page

Figure 6. Home Page

Figure 7. What we offer through ResArtifact

Getting Started: To access the dashboard, users need to log in using Resvault. After a user is authenticated, they will be brought to the Dashboard page.

Figure 8. Login Page

Straightforward actions: This Dashboard gives users to option to add a new artifact or view their personal collection.

Figure 9. Dashboard

Inventory

Easy Addition Process: Allows users to easily add an artifact by inputting an artifact’s information: name, unique ID, place of origin, origin year, artifact description, condition, curator ID, museum ID, recipient’s public key, and an image URL.

Search

Figure 10. Add Artifact Page

View Personal Inventory: Shows an exclusive inventory of artifacts that only the user has added. Users can transfer any artifact in their personal inventory to another user.

Figure 11. View Artifact Page

Seamless Transfer: In case a user wants to transfer an artifact to another user, they can update the artifact’s information and easily send it.

Figure 12. Transfer Artifact Page

Inventory View: Shows a detailed display of updated inventory information on all artifacts that any user has added.

Figure 13. Artifact Collection Page

Individual Artifact View: Shows all the information stored for an artifact.

Figure 14. Individual Artifact Information Page

History: Shows the history of an artifact with all past information about it.

Figure 15. Artifact Transaction History

Demo Video

Steps to run the system

Alright, folks, this is just the beginning — it’s like looking at a tall mountain, but trust us, we’re going to climb it together and reach the top. You’ve got this!

Before we jump into setting up ResilientDB, let’s quickly check that we have all the prerequisites in place.

Ensure you have the following installed and configured before proceeding:

Node 20.17.0

Bazel 6.0.0

Python 3.10

Ubuntu 22.04

MongoDB 7.0.15

With these prerequisites in place, we can move on to the setup.

Setup Crow HTTP server, SDK, and GraphQL server

Clone the ResilientDB repository:

git clone https://github.com/resilientdb/resilientdb.git

Navigate into the ResilientDB directory:

cd resilientdb

Install the required dependencies:

sh INSTALL.sh

Start the ResilientDB KV Service (Take a short break, folks! The first time might take a few minutes!):

./service/tools/kv/server_tools/start_kv_service.sh

Setup Crow HTTP server, SDK, and GraphQL server

Clone the ResilientDB GraphQL repository:

git clone https://github.com/ResilientDB-GraphQL

Navigate into the ResilientDB-GraphQL directory:

cd ResilientDB-GraphQL

Install the Crow dependencies:

sudo apt update
sudo apt install build-essential
sudo apt install python3.10-dev
sudo apt install apt-transport-https curl gnupg

Build the Crow HTTP server (this might take a few minutes the first time, so kick back, relax, and maybe stretch your legs while it does its thing!):

bazel build service/http_server:crow_service_main

Start the Crow HTTP server:

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/service.config service/http_server/server_config.config

Create virtual environment for the Python SDK:

python3 -m venv venv –without-pip

Activate the virtual environment:

source venv/bin/activate

Install pip in the virtual environment for the Python dependencies:

curl https://bootstrap.pypa.io/get-pip.py | python

Install the Python dependencies:

pip install -r requirements.txt

Start the GraphQL server:

python3 app.py

Setup Wallet

This is your key to ResArtifact

Here is the link to setup ResVault

Setup MongoDB

All you need to do is set up MongoDB, and don’t worry about the rest — the resilient-node-cache will take care of everything else for you!

Refer to this guide to install MongoDB in 7 simple steps

Check if MongoDB is Running using :

sudo systemctl status mongod

Contributions:

The team members of this project are Alyssa Yee, Amy Vu, Alexander Gao, Zijin Cui, Guransh Anand. Alyssa Yee is the leader of our project and has handled submitting all assignments and has supported backend transactions. Amy led the frontend development and connected the frontend application to the backend. Alexander supported the frontend development and strategic planning for features of the application. Guransh managed the backend development, which includes setting up transactions, making custom transactions required for this application, and testing the functionality on a sample frontend. Zijin Cui is gathering and organizing reference materials needed for this project.

Resilient Vote

Sun, 08 Dec 2024 00:00:00 +0000

ResVote: A Scalable and Secure Online Voting System Built on ResilientDB

Our Motivation

Traditional voting systems, such as in-person voting and mail-in ballots, are often slow, prone to errors, and vulnerable to fraud. These methods are labor-intensive and struggle to handle large-scale elections efficiently.
Resilient Vote leverages ResilientDB to create a secure, scalable online voting platform. The system guarantees confidentiality, integrity, and transparency, ensuring that elections are both reliable and tamper-proof.

Our Goals

Project Goals and Objectives

The primary goal of Resilient Vote is to develop a secure and scalable voting system that addresses the limitations of traditional voting methods. By using ResilientDB as the underlying database, we aim to create a system that is not only reliable but also capable of handling large-scale elections efficiently.

Key objectives of our project include:

Scalability: Build a platform that can handle a high volume of voters and election data without compromising performance.
Security: Ensure the confidentiality and integrity of votes through cryptographic techniques and tamper-proof storage.
Transparency: Provide clear and accessible visualizations of election data to ensure transparency and accountability in the voting process.
Automation: Eliminate the need for manual vote counting by automating the vote tallying process, reducing errors and human intervention.
Ease of Use: Develop a user-friendly web interface that makes the voting process seamless for voters, administrators, and election officials.

Technical Approach

To build Resilient Vote, we designed a secure, scalable, and user-friendly system by leveraging modern technologies and distributed database solutions. Our approach integrates a web-based front end, a robust back-end API, and a fault-tolerant database system powered by ResilientDB.

System Architecture

The system is divided into three main components:

Front-End (React & XML-RPC):
- The user interface is built using React, ensuring a responsive and interactive experience for voters, administrators, and general users.
- For communication between the front end and the back end, we use XML-RPC (Extensible Markup Language Remote Procedure Call). XML-RPC allows the front-end React application to interact with the back-end services securely and efficiently. By using this protocol, the system can send method calls to the server and receive responses, ensuring smooth data exchange and integration between the user interface and the database.
- This approach provides a lightweight solution for data transmission, making it easy to implement in a distributed environment while maintaining high security and reliability.
Back-End (ResilientDB Crow Service & ORM):
- The back-end uses ResilientDB Crow Service and ResilientDB ORM to interact with the database. The Crow Service ensures that the system is fault-tolerant and highly available, with data securely stored and accessible across distributed nodes.
- The ResilientDB ORM simplifies the database interactions by abstracting CRUD operations into Python-friendly methods, reducing boilerplate code and making it easier to manage votes and election data efficiently.
Database (ResilientDB & MongoDB):
- ResilientDB serves as the primary database, providing a distributed, fault-tolerant system to store and manage votes securely. Key features of ResilientDB, such as parallel processing, system crash resilience, and robust security, ensure data integrity and high availability, making it the perfect solution for a scalable voting system.
- MongoDB is used as a caching layer for the transactions. It stores temporary data related to votes and election activities, helping to reduce latency and improve system performance by offloading frequent read and write operations from ResilientDB. MongoDB serves as a fast, scalable cache to ensure that the system can handle high volumes of requests during peak voting periods.
Randomized Vote Generator based-on Property-based Testing:
- To ensure the reliability and robustness of the voting system, we use the Hypothesis library, a property-based testing tool for simulating election events. With Hypothesis, we generate random election scenarios, including creating voters, elections, and votes. This enables us to test the system under various conditions and verify that it behaves as expected.
- By stress-testing the system with large-scale, simulated data, Hypothesis helps identify edge cases and potential issues, ensuring that Resilient Vote performs accurately and securely under diverse scenarios.

Deployment Tutorial From Scratch

In order to provide more complete examples for beginners who are interested in participating in distributed database projects, we have improved the project documentation to deliver a project guide from scratch.

Python

We recommend using conda to manage python environment.

conda create -n "resdb" python=3.10.0 ipython
conda activate resdb
pip install -r requirements.txt

Get ResilientDB Dependencies

To save some time, we also provide a docker image that has all the dependencies installed.

docker pull yfhecs/rsdb
docker run -d -p 18000:18000 --name resdb yfhecs/rsdb

If you choose to use docker, you can skip the following steps. Please wait a few minutes for the docker container to start. You can check if it is ready by the follow command:

❯ curl -X POST -d '{"id":"key1","value":"value1"}' localhost:18000/v1/transactions/commit
id: key1

❯ curl 127.0.0.1:18000/v1/transactions/key1
{"id":"key1","value":"value1"}

You can also find the related dockerfile in the ./docker directory.

ResilientDB

The following commands will clone and build ResilientDB, and then starts 4 replicas and 1 client. Each replica instantiates a key-value store.

git clone https://github.com/apache/incubator-resilientdb.git resilientdb
cd resilientdb
./INSTALL.sh
./service/tools/kv/server_tools/start_kv_service.sh

Graph QL

git clone https://github.com/apache/incubator-resilientdb-graphql.git resilientdb-graphql
cd resilientdb-graphql
sh ./INSTALL.sh
pip install -r requirements.txt

Running Crow service (HTTP endpoints)

bazel build service/http_server/crow_service_main
bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

ResVote Server

source ./env.sh
python app/serve.py

ResVote TUI Client

source ./env.sh
python app/tui.py

Results & Achievements

The development of Resilient Vote has yielded significant progress in both the Virtual Vote Generator and Data Visualizations, two core features of the system.

Virtual Vote Generator

One of the key innovations of our project is the Virtual Vote Generator, developed using the Hypothesis library. This tool simulates large-scale election events by automatically generating random voting data. It creates virtual voters, assigns them different identity attributes (such as age, gender, region, race, education level, timestamp etc.), and simulates voting in various election scenarios.

The Virtual Vote Generator serves three main purposes:

Stress Testing: It helps simulate high volumes of votes to ensure the system can handle large-scale elections without performance degradation.
System Validation: The generator validates that the system handles diverse voting scenarios correctly, ensuring data consistency across distributed nodes.
Demographic Analysis: By generating voters with varied attributes, the system can examine how different demographics might influence election outcomes, thus guiding more informed decision-making.

This feature is essential for testing the resilience and scalability of the system before it’s deployed in real-world elections.

Data Visualizations

The system includes a powerful data visualization component that provides a clear and interactive view of the election results. The visualizations include a variety of charts and graphs that are automatically updated as votes are cast. Key features of the data visualization component include:

Real-Time Election Results: As votes are cast, the system displays real-time updates in the form of bar charts, pie charts, and line graphs.
Voter Demographics: The system visualizes the distribution of votes across different voter demographics, such as age groups, gender, regions, race, education level and other attributes. For each attribute, we make overall visualization based on total voters.

https://yfhe.net/images/ResVote/ResVote_React.png


Candidate Distribution	Age Distribution	Gender Distribution


Region Distribution	Race Distribution	Education Distribution

And we also make grouped analysis of different candidates for better comparison.


Age Grouped Bar Chart	Gender Grouped Bar Chart	Region Grouped Bar Chart

| | | |:-------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------:| | Race Grouped Bar Chart | Education Grouped Bar Chart |

Trend Analysis: The visualizations show trends in voting over time, helping administrators understand voter participation patterns.

These visualizations not only enhance the transparency of the voting process but also make it easier to interpret the results and track the progress of elections.

By combining these two powerful features—automated voting simulations and real-time, interactive data visualizations—Resilient Vote provides a robust platform for conducting scalable, transparent, and efficient elections.

Feasibility Analysis

While the Virtual Vote Generator was initially designed to produce synthetic data for stress-testing and validation, its underlying structure closely mirrors that of real-world voting data. By leveraging randomized yet controlled attribute assignments—gender, region, age, race, education level—the generator ensures broad coverage of realistic scenarios. This design principle allows the transition from testing scenarios to actual election data to be seamless.

In practice, once real votes start coming in, the same code paths and visualization routines used for generated data can be directly applied to genuine voting records. Since the generator’s outputs and real votes share the same data schema, all existing analytic and graphical methods remain valid. The rich set of demographic and temporal charts that clarify patterns in synthetic elections will likewise provide meaningful insights when applied to real voter populations. In other words, the visualizations that help us pinpoint unexpected trends or correlations in randomized testing scenarios are just as effective in highlighting authentic voter behaviors, preferences, and participation patterns.

By maintaining this consistent data format and analysis approach, Resilient Vote ensures that lessons learned from simulation inform actual voting events. As a result, insights gained during development translate into actionable understanding and enhanced transparency once real ballots are being cast.

Future Plans

As we continue to develop Resilient Vote, there are several key areas we plan to improve and enhance:

1. UI Enhancement and Front-End & Back-End Integration Upgrade

Our primary focus for future development is to enhance the user interface with more user-friendly operating logic and strengthen the integration between the front-end and back-end. While the current system is functional, we aim to improve the overall user experience by ensuring a seamless flow of data between the front-end and back-end, making the platform more responsive and efficient.

2. Real-Time Visualization of Vote Trends

We will take the data visualization features a step further by incorporating real-time vote trends during elections. This will allow voters and administrators to track the election results dynamically, providing insights into voter participation and trends as the voting progresses.

3. Enhanced User Registration Security

We will implement more robust security measures like Multi-factor authentication (MFA) to protect user identities and prevent unauthorized access. In addition, we plan to achieve advanced encryption methods to protect personal information and prevent data breaches.

About Team

ECS 265 Distributed Database Systems Fall 2024
Professor Mohammad Sadoghi TA Daikai Kang

Team Members:

Tyler Culp
Jason Eissayou
Simon Draeger
Yifeng He
Jicheng Wang
Boqi Zhao

University of California, Davis
Davis, CA

MemLens - Continuous Profiling tool for ResilientDB

Sat, 07 Dec 2024 00:00:00 +0000

What is MemLens?

MemLens is a comprehensive CPU and memory profiler designed for ResilientDB, offering granular, real-time performance insights through continuous profiling. By integrating advanced profiling tools and aggregating data from various system and process specific sources, MemLens provides a robust platform for database-specific metrics.

Our platform delivers detailed insights into the inner workings of the database, empowering users to optimize system performance effectively. Key metrics include cache hit ratios, storage and disk performance, CPU usage, call stack visualizations, dependency graphs, and more. The integration of continuous profiling ensures that performance trends and anomalies can be identified over time, enabling proactive optimization and system tuning.

MemLens represents an ambitious and evolving vision to bridge the gap between high-level performance monitoring and low-level system insights. We are proud to share a packaged version that highlights the potential of this innovative tool and are committed to ongoing improvements to push the boundaries of database profiling.

Key Highlights

Integrated Terminal Playground: Provides a seamless terminal-like interface for retrieving (GET) and storing (SET) values directly within ResilientDB, enhancing ease of use for developers and operators.
Real-Time Flame Graphs: Automatically generates detailed flame graphs for memory and CPU profiling, paired with in-depth call stack analysis for processes to identify bottlenecks and optimize performance.
Custom LevelDB Metrics: Incorporates Custom C++ hooks to expose critical LevelDB metrics not available by default, such as:
- Cache hit ratios.
- Storage engine metrics, including the number of SST tables and file counts at each level.
Interactive Web-Based Frontend: Features a user-friendly, web-based interface for exploring performance insights interactively, making profiling data accessible and actionable.
Unified Profiling Dashboard: Aggregates data from multiple profiling tools into a cohesive dashboard, offering a single, unified view of system performance.
Optimized for Linux: Designed to be lightweight and highly efficient, ensuring minimal overhead and smooth operation on Linux-based systems.

Architecture

Below is a architecture diagram of MemLens:

Figure 1. Diagram displaying the architecture of MemLens and how profiling metrics are collected.

The diagram can be broken down as follows. A client request for a particular metric is made by the client to the middleware. This layer acts as a data aggregation platform which collects metrics from the ResDB environment. The various data sources include time series data from node_exporter, call stack data from pyroscope, storage engine metrics from hooks integrated into ResDB’s CPP source code. ResDB Graphql service is also running to interface GET and SET API calls via HTTP requests.

Metrics

Call Stack Visualization

Figure 2. Flamegraph showing Call Stack when a transaction is retrieved

Flamegraph showing the call stack when a Get method is called on ResilientDB’s key value store. This graph shows the function caller which is invoked by the ResilientDB-GraphQL service and is serviced at the end by the storage engine which is LevelDB. The storage engine calls the in-memory LRU cache to check for cache hits and when not found calls its internal functions to retrieve the key value pair.

CPU Usage

Figure 3. Line Graph showing showing CPU usage of ResDB KV Service over a period of 6 hours

Linegraph showing the CPU usage of ResDB’s KV Service over a period of 6 hours. This data is collected from process-exporter which is used to profile individual processes and export metrics through prometheus. We run process-exporter as systemd process to ensure persistent monitoring.

Storage Engine Metrics

Figure 4. Dashboard showing storage engine metrics.

Dashboard showing storage engine metrics, like cache hit ratio, approximate database size of leveldb, snapshot of process metrics like RSS, number of block reads and number of block writes. Each metric has a information tooltip which can be used to display more information about the metrics.

Disk Metrics

Figure 4. Dashboard showing Disk metrics.

Dashboard showing disk metrics like time spent during IO, disk read and write data, disk IOPS (Input and Output operations per second) and disk average wait time. These metrics are exposed by node_exporter and are exporter through prometheus. We run node_exporter as systemd process to ensure persistent monitoring.

Dependency Analyzer

Figure 5. Dependency Graph for ResDB's KV Service.

Dependency Graph for ResDB’s KV Service obtained by running the command bazel query --notool_deps --noimplicit_deps "deps(//service/kv:kv_service, $(depth))". The value of depth can be selected among 2,3 and 4. This generated a deeper dependency graph with links to libraries and other dependent services.

Data Collection

MemLens uses a data aggregation layer, a thin HTTP service which sits between the Visualizer and the ResDB environment. As the name suggests this aggregation layer collects data from various profiling tools and exposes a single platform for the frontend to request data. We chose this architecture as it would allows us to scale this system by introducing a time series databases in the future and collect data over a period of time and analyze trends and gauge behaviour.

Data Sources

MemLens leverages a wide range of tools and integrations to provide detailed, real-time performance insights for ResilientDB. By utilizing data from various industry-standard sources, MemLens offers a holistic view of system performance. Below is an overview of the key data sources:

1. LevelDB CPP Hooks

Purpose: Provides access to internal statistics and performance metrics of LevelDB.
Integration: Custom hooks enable MemLens to monitor and profile critical metrics such as:
- Cache hit/miss ratios.
- Read/write latencies.
- Compaction stats and storage utilization.
Benefits: Delivers database-specific insights that help optimize LevelDB’s storage layer performance.

2. Node Exporter

Purpose: Collects hardware and operating system metrics.
Integration: Node Exporter gathers low-level system data such as:
- CPU utilization and system load.
- Memory usage (heap, stack, swap).
- Disk I/O and network throughput.
Benefits: Provides a baseline for understanding system resource utilization alongside database performance.

3. Process Exporter

Purpose: Monitors resource usage at the process level.
Integration: Tracks resource usage specific to ResilientDB processes, including:
- Per-process CPU and memory consumption.
- Process life cycles and thread usage.
Benefits: Enables granular profiling of ResilientDB, isolating bottlenecks at the process level.

4. Pyroscope

Purpose: Enables continuous profiling for CPU and memory usage.
Integration: Captures detailed call stacks and resource usage trends over time, including:
- Hot path identification for CPU-intensive operations.
- Memory allocation and garbage collection patterns.
Benefits: Provides a time-series view of performance, enabling developers to pinpoint and resolve inefficiencies effectively.

5. Prometheus

Purpose: Collects and queries time-series data.
Integration: Custom Prometheus hooks gather both standard and database-specific metrics such as:
- Query execution latencies.
- Disk write/read performance.
- Custom database events for fine-grained profiling.
Benefits: Delivers a unified and extensible monitoring solution, enabling seamless visualization through dashboards like Grafana.

Demo Video

Usage

Prerequisites

Before running the MemLens application, you need to start kv service on the ResDB backend and the sdk.

ResilientDB

Git clone the MemLens backend repository, a fork of ResilientDB and follow the instructions to set it up:

git clone https://github.com/harish876/incubator-resilientdb

Setup KV Service:

./service/tools/kv/server_tools/start_kv_service_monitoring.sh

SDK

Git clone the GraphQL Repository and follow the instructions on the README to set it up:

Install GraphQL:

git clone https://github.com/ResilientApp/ResilientDB-GraphQL

Setup SDK:

bazel build service/http_server:crow_service_main

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

Middleware

Git clone the MemLens Middleware Repository:

Install MemLens Middleware:

git clone https://github.com/harish876/MemLens-middleware

Setup MemLens Middleware:

npm install
npm run start

Monitoring tools

Follow this link to setup prometheus, grafana and a few other monitoring tools used in this application.

With these 3 services running, the MemLens front end can now send aggregate metrics from the middleware.

Running the MemLens Application

Clone the repo and open in a new folder.

git clone https://github.com/Bismanpal-Singh/MemLens
npm install

Run the below code to start the app and load the script.

npm run dev

Using the MemLens Application

Once MemLens has been started, go to http://localhost:5173

You will see a landing page with a brief description of the project and on scrolling down will see a brief of the PBFT protocol, and a explorer card to access the dashboard.

Once the dashboard page has loaded, it will make an API call to the middleware running on http://localhost:3002 to check if the middleware is active and running. If the middleware is running and all profiling tools are installed then , the dashboard switches to a Live mode which fetches live data from the middleare. If no accompanying backend services are running, then the app switches to a Offline mode which loads snapshots of data collected by the team. This mode could be used for exploration and familiarising with the interface.

The dashboard has 3 tabs, Memory Tracker, CPU and Bazel Build. The memory tracker loads a playground which is a terminal emulator to GET and SET values into the KV store. A dashboard card dedicated to storage engine metrics and disk metrics. Each graphical card can be be refreshed which will refresh the data. The CPU tab displays a CPU Line graph which displays a graphical view of CPU usage over a period of time, and a accompanying flamegraph to display the call stack. The line graph can be highlighted into in order to magnify the CPU usage over that specific time window and the flamegraph automatically updates according to the time frame chosen. The bazel build tab displays a dependency graph showcasing the dependencies for the KV service and a select menu to dynamically change the depth of the graph output and the command run to generate the visualized build data.

Future Work

Package, installation and setup of monitoring tools into a bash script or ansible playbook.
Remote setup of MemLens middleware and migrating the current setup to an AWS EC2 instance or Linode.
Set up profiling tools on a Raspberry Pi and collect metrics.
Development of eBPF profiler from scratch and integrating it into code, instead of using a sandboxed profiling environment.
Stabilising metric collection and develop a remote mode to push data into InfluxDB or equivalent time series database to analyze trends.

Designed the project architecture and proposed innovative feature ideas.
Integrated profiling tools and developed C++ hooks to export LevelDB statistics, memory metrics, and explored alternatives like integrating an LMDB storage layer.
Developed a middleware layer to ensure seamless end-to-end connectivity between the monitoring environment and the frontend.
Implemented frontend features including Flamegraph visualization, the ability to toggle between Live and Offline modes, and a terminal emulator.
Created scripts to bootstrap monitoring tools and set up the profiling environment efficiently.
Authored comprehensive project documentation, estimated timelines, conducted research on existing tools, tested feasibility, and explored ideas that were ultimately not included in the final implementation.

Bisman:

Collaborated on designing and conceptualizing the frontend’s look and feel, exploring component libraries and frameworks, and testing feature feasibility.
Designed the UI/UX architecture, including the skeleton, contexts, and pages. Developed the primary PBFT diagram, set up graph component skeletons, and styled the application for cohesive functionality and aesthetics.
Created and integrated key frontend components such as the Navbar, links, INFO tags on graphs, and refresh button functionality. Incorporated Live and Offline modes seamlessly into the frontend.
Led the full-stack integration of Disk Metric cards, including middleware API development and frontend implementation. Developed reusable components for graph display and utilities for efficient data fetching.
Architected and managed frontend features, ensuring project milestones were met consistently while maintaining high standards of quality and usability.

George:

Contributed to project ideation, exploring profiling tools and assessing the feasibility of various features.
Led efforts to expand the project scope, introducing support for additional facets such as running ResilientDB on Raspberry Pi.
Addressed and resolved challenges in setting up ResilientDB on Raspberry Pi, including testing multiple Pi versions and stabilizing overheating issues.
Maintained a project tracker to monitor progress, manage tasks, and ensure timely delivery of milestones.
Set up comprehensive documentation for GitHub repositories, enabling clear guidance for contributors and maintaining project standards.

Krishna:

Polished the visual design and functionality of the application, including creating a sliding button link for a smoother user experience. Assisted team during the presentation by ensuring the frontend was presentation-ready.
Supported the development of frontend components, enhancing usability and visual appeal while ensuring seamless integration with the backend.
Played a key role in developing features like Bazel build visualization to enhance project debugging and performance monitoring capabilities.

Notable Contributions

Shreya - For designing the MemLens logo, bringing creativity and a design to the project.

ResCash

Tue, 03 Dec 2024 00:00:00 +0000

Introduction

ResCash: A Secure and User-Friendly Financial Accounting Solution

In our increasingly digital world, managing finances effectively is critical for both individuals and businesses. ResCash addresses this challenge with a cutting-edge accounting application that is secure, efficient, and intuitive. Designed with individual users and freelancers in mind, ResCash leverages advanced technology to streamline transaction handling, budgeting, and financial reporting. It redefines the way financial management is approached by combining distributed accounting principles, ResilientDB integration, and secure transaction management for a seamless user experience.

Technologies That Power ResCash

ResCash is built on a modern and robust tech stack, ensuring scalability, reliability, and ease of use:

Frontend with React: A responsive and seamless user interface, delivering smooth interactions and intuitive navigation.
Backend with Node.js: A high-performance environment for efficient API handling and business logic implementation.
Database Integration:
- ResilientDB: A distributed database that provides top-notch security and reliability for critical financial data.
- MongoDB: A secondary database optimized for advanced features like sorting, filtering, and quick data indexing.
Authentication via ResVault: Ensures secure and controlled access to sensitive data, enhancing user trust.
Data Visualization: Interactive charts and dashboards make complex financial metrics, such as cash flow and net worth trends, easy to understand and actionable.

The Innovation

ResCash stands out by integrating distributed database technology with an intuitive user experience. It combines the reliability of ResilientDB with the flexibility of MongoDB, offering a platform that prioritizes data security, high availability, and advanced functionality. Detailed financial visualization tools and secure transaction management ensure ResCash meets the dynamic needs of modern users.

Why ResCash?

ResCash goes beyond traditional accounting tools by emphasizing security, transparency, and flexibility. Its advanced CRUD functionality, customizable reports, and real-time budgeting tools adapt to the diverse needs of individual users and freelancers. With ResCash, managing your finances isn’t just easier—it’s smarter, empowering users to take control with confidence and clarity.

Elevator Pitch

ResCash is the next generation of financial accounting tools, offering a secure, distributed, and user-centric platform. By integrating state-of-the-art technologies like ResilientDB and ResVault, ResCash ensures that your data is protected, accessible, and actionable. Whether you’re a individual user or a freelancer, ResCash simplifies complex financial tasks, giving you the insights and tools you need to succeed.

The Problem

The Commercial Opportunity: In an era where data security and transparency have become necessities for both bussiness man and college students, the ResCash accounting application sets out to redefine how individuals and small enterprises manage their financial records. Rather than relying on outdated methods prone to human error and data breaches, ResCash introduces cutting-edge blockchain-inspired solutions and distributed databases to ensure that every recorded transaction is secure and easy to use. While many competing appllications promise efficiency, few can match the level of data integrity and trust that come from a design philosophy centered on transparency and resilience. This quality positions ResCash as a credible choice for those who value long-term stability and security over quick, superficial fixes. There are too many college students and people who just starting working on their own small bussiness lacking of safety awareness in this society, becuase they still do not have much social experience. In that situation, ResCash provided a reliable way for them to manage their financial information in the absence of doubt. In our future plan, we can also cooperate with universities to build their own database, which increase the secuirty and customizability of ResCash.

Pain Points in Traditional Systems: Traditional accounting systems often leave users feeling uncertain about the sercurity and reliability of their financial data. Concerns over potential information theft and unauthorized access are widespread. With ResCash, these issues are addressed head-on. By employing a distributed database platform ResilientDB and MongoDB in this project, the application safeguards each transaction entry from spiteful interference. In doing so, it instills a sense of security and trust—key factors that appeal to college student and small bussiness man who want to maintain control over their financial information. ResCash’s capacity to preserve data integrity in any situation is one of its primary advantages. This distributed architecture is only little impacted by system failures and cyberattacks that would destroy a conventional, centralized database. Errors and interruptions barely affect the system’s overall performance because the data is duplicated and checked across several nodes. Knowing that their records are reliable and available whenever they’re needed allows users to log in.

Highlights of the ResCash: A distributed and secure strategy guarantees that the system remains operational and accessible even in the event of a single node failure or server interruption. Because of its resilience, data integrity is maintained and catastrophic outages that may ruin profits, undermine confidence, and damage a company’s brand are avoided. Additionally, teams can focus on strategic growth, innovative problem-solving, and strengthening client connections when they are freed from time-consuming troubleshooting by well-designed and effective solutions. Efficiency directly results in savings and a stronger competitive advantage; it is not a luxury.Investing in safe, distributed, and efficient solutions is ultimately a strategic decision that affects long-term trends and aids in businesses’ or college students quick adaptation, since the market is changing at a fast pace. Those that are prepared to reconsider their data management and security strategies and adopt methods that prioritize security and smooth efficiency will be rewarded in the future.

Our Solution

ResCash leverages cutting-edge technologies to provide a reliable, secure, and scalable cash flow management platform.

Foundational Technology

Distributed Database Architecture:
- Powered by ResilientDB, a state-of-the-art distributed database, ResCash ensures high availability, fault tolerance, and efficient transaction processing.
Cryptographic Key Integration:
- Cryptographic keys are utilized for secure user authentication and transaction management.
- Ensures immutable transaction records while protecting user data from unauthorized access.

Distributed System Security

Consensus-Based Validation:
- ResCash employs ResilientDB’s consensus protocols to validate transactions across distributed nodes, ensuring consistency and preventing fraudulent modifications.
End-to-End Encryption:
- Data transmitted between the client and the server is encrypted using industry-standard algorithms, protecting sensitive financial information from interception.
Access Control and Authentication:
- Secure authentication mechanisms, including the use of cryptographic keys and tokens, ensure that only authorized users can access or modify transaction records.
Fault Tolerance and Data Integrity:
- ResilientDB’s distributed replication ensures that transaction data is stored across multiple nodes. In the event of a node failure, data remains accessible and unaltered.
- Transaction logs are immutable, ensuring tamper-proof audit trails for regulatory compliance.
Periodic Security Audits:
- Regular audits and vulnerability assessments ensure that ResCash remains secure against evolving threats.

By integrating these distributed system security measures, ResCash provides a platform that not only ensures high performance but also guarantees data privacy, integrity, and availability, making it a reliable solution for financial management.

Core Features

Create Transactions: ResCash allows users to create detailed financial transactions with fields such as amount, category, transaction type, merchant, and payment method. Transactions are stored securely in ResilientDB for data integrity and MongoDB for efficient indexing.
Read Transactions: Users can view all transactions with advanced filtering options. The “Read” feature provides a structured display of transaction data, ensuring easy navigation and understanding. It supports personalized views based on user-specific data retrieved securely through token-based authentication.
Update Transactions: The update functionality allows users to modify existing transaction details, including amounts, categories, transaction type, merchant, and payment method, ensuring data consistency and accuracy.
Delete Transactions: ResCash implements a “soft delete” mechanism, marking transactions as inactive without permanently removing them in ResilientDB. This ensures data traceability while maintaining clean records for users.
Cash Flow Chart: The cash flow chart is a dynamic visualization tool that tracks the movement of funds over time. This feature provides a clear and comprehensive view of income, expenses, and net cash flow. Users can identify patterns, such as periods of liquidity surplus or deficit, enabling better financial planning. Income and expenses are categorized, helping users understand the sources of inflows and outflows. By monitoring cash flow, users can make informed decisions about spending, saving, or investing.
Net Worth Chart: The net worth chart provides a real-time snapshot of a user’s financial position by calculating the accumulation between income and expense. This feature is crucial for individuals and businesses to measure financial progress over time. Users can view how their net worth has evolved, with historical data displayed through an easy-to-read line chart.

Usage

Prerequisites

Install ResVault Chrome Extension
- Follow the instructions here.
- Ensure that the ResVault extension is connected to:
```
76.158.247.201:8070
```
  (You may substitute this URI with your own GraphQL server URI if needed.)
Install Node.js and npm
- Refer to the official guide.
- Confirm installation by running:
```
npm -v
```

Setting Up ResCash

Clone the ResCash Repository

git clone https://github.com/quiet98k/resCash

Navigate to the Root Directory
```
cd resCash
```
Set Up the Frontend
- Navigate to the frontend directory (same name as the root directory):
```
cd resCash
```
- Install dependencies:
```
npm install
```
- Start the frontend server:
```
npm start
```
Set Up the Backend
- Open a new terminal and return to the root directory:
```
cd resCash
```
- Navigate to the backend directory:
```
cd backend
```
- Create a .env file with the following configuration:
```
MONGODB_URI=****
MONGODB_DB_NAME=****
GRAPHQL_URI=****
CROW_SERVER_URI=****
```
  - MONGODB_URI: MongoDB connection URI (customizable).
  - MONGODB_DB_NAME: Database name.
  - GRAPHQL_URI: GraphQL server URI (include the /graphql suffix).
  - CROW_SERVER_URI: Crow server URI (must match the GraphQL URI).
- Install backend dependencies:
```
npm install
```
- Start the backend server:
```
npm start
```
Access the Application: Open your browser and navigate to:
```
http://localhost:3000/
```

Notes

Ensure all URIs are consistent between .env files and the ResVault extension.

Future Developments

1. Enhanced UI/UX Design

Objective: Improve the user interface and experience to make ResCash more intuitive, accessible, and visually appealing for all users.

Implementation Path:

User Research:
- Conduct user interviews and surveys to gather feedback on pain points and usability issues in the current design.
- Perform usability testing to identify areas for improvement.
UI Redesign:
- Revamp the interface with a clean, modern design using frameworks like Material UI.
- Prioritize ease of navigation with clear menu options and a step-by-step onboarding process for new users.
UX Enhancements:
- Simplify complex blockchain-related actions with user-friendly workflows.
- Add tooltips, animations, and explanations for blockchain concepts to educate users.
- Implement a dark mode for user customization.
Performance Optimization:
- Optimize the UI for speed by minimizing assets and using asynchronous data fetching to ensure smooth performance.
Testing and Iteration:
- Use A/B testing to experiment with different layouts and features.
- Continuously collect user feedback post-launch and iterate on the design.

2. Multi-Currency Support

Objective: Enable ResCash to handle transactions in multiple currencies.

Implementation Path:

Database Update:
- Extend the MongoDB schema to include currency fields for transactions.
- Store exchange rates in a separate collection for real-time updates.
Blockchain Integration:
- Enhance the smart contracts or backend logic to handle currency conversions when needed.
- Support multiple token standards (e.g., ERC-20 for Ethereum-based cryptocurrencies).
Frontend Changes:
- Add a dropdown menu for users to select their preferred currency.
- Display balances and transaction amounts in the selected currency.
- Implement a real-time currency converter using exchange rate APIs (e.g., CoinGecko).
ResVault Update:
- Modify the wallet extension to support multiple currency wallets.
- Allow users to switch between wallets and manage private keys for each currency.
Testing and Deployment:
- Conduct thorough testing to ensure accurate currency conversions and compatibility with blockchain protocols.
- Deploy the updates incrementally to avoid disruptions.

3. Smart Budgeting and Analytics

Objective: Introduce more budgeting tools and analytics to help users track and plan their spending more effectively.

Implementation Path:

Budgeting Feature:
- Allow users to set monthly or weekly spending limits in specific categories.
- Store user-defined budgets in MongoDB.
Transaction Categorization:
- Implement machine learning (ML) models to automatically categorize transactions based on descriptions or merchants.
- Use a library like TensorFlow.js for lightweight ML in the backend or frontend.
Analytics Dashboard:
- Create an interactive dashboard to display spending trends, savings, and projections.
- Include features like:
  - Monthly spending breakdown.
  - Alerts for overspending in certain categories.
  - Forecasting future expenses.
Notifications:
- Integrate email or push notifications to alert users about budget thresholds.
- Use Node.js libraries like Nodemailer or Firebase for notification delivery.
User Testing and Feedback:
- Deploy the feature to a small group of users for feedback.
- Iterate based on user input to refine the budgeting and analytics tools.

4. Mobile Application Development

Objective: Expand the reach of ResCash by creating a mobile application for Android and iOS.

Implementation Path:

Frontend Development:
- Use a cross-platform framework like React Native to build the app.
- Design a responsive and user-friendly interface optimized for smaller screens.
Backend API Optimization:
- Ensure the backend APIs are mobile-friendly by optimizing response times and minimizing data payloads.
- Use tools like GraphQL subscriptions for real-time updates on mobile devices.
Integration with ResVault:
- Develop a mobile version of ResVault.
- Ensure seamless interaction between the app and the wallet for signing transactions.
Testing and Deployment:
- Test the app on emulators and physical devices for compatibility.
- Publish the app on Google Play Store and Apple App Store, adhering to their guidelines for blockchain apps.
Push Notifications:
- Add push notifications for transaction confirmations, balance updates, and other alerts using Firebase Cloud Messaging.

The Team

Yiming Feng [ymfeng@ucdavis.edu]
- Implement Create Feature
- Implement Report Feature
- Application Testing and feature improvement
- Project management, coordinating between team members
Qingyue Yang [yqmyang@ucdavis.edu]
- The overall coding of the ResCash user interface frame
- Implement Home Page features
- Implement the Edit Feature
- Project management, creating project roadmap, and formatting reports
Alex Chen [yscchen@ucdavis.edu]
- Implement Delete Feature
- Develop Net Worth function and chart
Mark Le [ltble@ucdavis.edu]
- Implement Update Feature
- Develop Net Worth function and chart
Jennifer Liu [zijliu@ucdavis.edu]
- Implement user authentication
- Implement the backend of the Read Feature
Jiawen Zhang [nkzhang@ucdavis.edu]
- Implement the frontend of the Read Feature
- Implement the frontend of the CashFlow Feature

Dive into Smart Contracts with GraphQL API 🌐

Fri, 13 Sep 2024 00:00:00 +0000

Unlock the power of smart contracts with our GraphQL API. This guide will walk you through setting up and using the API to interact with smart contracts seamlessly.

Smart Contracts GraphQL API

Introduction

Welcome to the world of smart contracts on ResilientDB! Our GraphQL API provides a streamlined way to interact with smart contracts, making it easier than ever to create, deploy, and execute contracts. Whether you’re a seasoned developer or just getting started, this guide will help you navigate the setup and usage of the Smart Contracts GraphQL API.

Prerequisites

Before diving in, ensure you have the following:

ResilientDB: A running instance of ResilientDB with the smart contracts service running. More information and setup instructions can be found here: ResilientDB
ResContract CLI: Install the rescontract-cli tool globally. Follow the instructions in the ResContract CLI Repository to install and configure it.
```
npm install -g rescontract-cli
```
Node.js (version >= 15.6.0): Download and install Node.js version 15.6.0 or higher, as the application uses crypto.randomUUID() which was introduced in Node.js v15.6.0.
```
# You can check your Node.js version with:
node -v
```

The prerequisites listed above can be installed using the INSTALL.sh script:

   chmod +x INSTALL.sh
   ./INSTALL.sh

Check out this blog post to find out more about Smart Contracts on ResilientDB - Getting Started with Smart Contract on Nexres

Setting Up the GraphQL API

Step 1: Clone the Repository

Start by cloning the repository to your local machine:

git clone https://github.com/yourusername/smart-contracts-graphql.git
cd smart-contracts-graphql

Step 2: Install Dependencies

Install the necessary dependencies using npm:

npm install

Step 3: Start the Server

Launch the GraphQL API server:

node server.js

Your server will be up and running on port 8400. Access the GraphQL API at http://localhost:8400/graphql.

Exploring the GraphQL API

Our API supports several operations to manage and interact with smart contracts. Here’s a look at what you can do:

Create Account Generate a new account using a configuration file.

{
  createAccount(config: "path/to/config/file")
}

Add Address Add an existing address to the configuration.

{
  addAddress(
    config: "path/to/config/file",
    address: "0xAddressToAdd"
  )
}

Compile Contract Compile a smart contract from a source file and save the output.

{
  compileContract(source: "path/to/source/file")
}

Deploy Contract Deploy a compiled smart contract with specified parameters.

{
  deployContract(
    config: "path/to/config/file",
    contract: "path/to/contract/file",
    name: "contractName",
    arguments: "constructorArguments",
    owner: "ownerAddress"
  )
}

Execute Contract Execute a function of a deployed smart contract.

{
  executeContract(
    config: "path/to/config/file",
    sender: "senderAddress",
    contract: "contractAddress",
    functionName: "functionName",
    arguments: "functionArguments"
  )
}

Sample Queries

Here are some practical examples to get you started:

Create Account:

{
createAccount(config: "incubator-resilientdb/service/tools/config/interface/service.config")
}

Add Address:

{
addAddress(
  config: "incubator-resilientdb/service/tools/config/interface/service.config",
  address: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
)
}

Compile Contract:

{
compileContract(source: "token.sol")
}

Deploy Contract:

{
deployContract(
  config: "incubator-resilientdb/service/tools/config/interface/service.config",
  contract: "compiled_contracts/MyContract.json",
  name: "token.sol:Token",
  arguments: "1000",
  owner: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
)
}

Execute Contract:

{
executeContract(
  config: "incubator-resilientdb/service/tools/config/interface/service.config",
  sender: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8",
  contract: "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1",
  functionName: "transfer(address,uint256)",
  arguments: "0x1be8e78d765a2e63339fc99a66320db73158a35a,100"
)
}

Advanced Usage with Type Parameter

The API supports both “path” and “data” types for all mutations. The type parameter defaults to “path” and doesn’t have to be explicitly set.

Using type “path” (Default)

When using file paths, you don’t need to specify the type parameter:

mutation {
  createAccount(config: "../incubator-resilientdb/service/tools/config/interface/service.config")
}

Using type “data”

When passing configuration data directly, specify type: "data":

mutation {
  createAccount(
    config: "5 127.0.0.1 10005",
    type: "data"
  )
}

Note: The response formats differ between “path” and “data” types:

“path” type: Returns structured JSON objects
“data” type: Returns string responses with newlines

Sample Responses

Here are the expected responses for each mutation:

Create Account Response:

{
  "data": {
    "createAccount": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
  }
}

Add Address Response:

{
  "data": {
    "addAddress": "Address added successfully"
  }
}

Compile Contract Response:

{
  "data": {
    "compileContract": "Compiled successfully to /users/yourusername/smart-contracts-graphql/compiled_contracts/MyContract.json"
  }
}

Deploy Contract Response:

{
  "data": {
    "deployContract": {
      "ownerAddress": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8",
      "contractAddress": "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1",
      "contractName": "token.sol:Token"
    }
  }
}

Execute Contract Response:

{
  "data": {
    "executeContract": "Execution successful"
  }
}

Conclusion

The Smart Contracts GraphQL API simplifies the process of interacting with smart contracts on ResilientDB. By following this guide, you can set up the API and start making API calls to manage and execute your smart contracts efficiently. If you have any questions or run into any issues, don’t hesitate to reach out for support.

Happy coding! 🚀

Simplifying Database Interactions with ResDB ORM

Sat, 24 Aug 2024 00:00:00 +0000

ResDB ORM is a Python module designed to streamline interactions with ResilientDB’s key-value store database. It provides basic CRUD operations, making it easier for developers to integrate ResilientDB into their applications.

https://github.com/ResilientEcosystem/ResDB-ORM

🌐 Why Use ResDB ORM?

Interacting with databases can often involve writing repetitive and complex code, especially when it comes to handling basic operations such as creating, reading, updating, and deleting data. The ResDB ORM library aims to abstract these operations, allowing developers to focus on the business logic of their applications rather than the intricacies of database management.

Here are some key advantages of using ResDB ORM:

Ease of Use: ResDB ORM abstracts complex database interactions into simple Python methods.
Reduced Boilerplate Code: Developers can perform CRUD operations without writing repetitive SQL queries.

🔍 Features of ResDB ORM

CRUD Operations: ResDB ORM provides methods for creating, reading, updating, and deleting records.
Pythonic API: The library offers a Python-friendly interface that seamlessly integrates with other Python-based projects.
Error Handling: Includes built-in error handling mechanisms to manage exceptions during database operations.

👨🏻‍💻 Getting Started with ResDB ORM

Step 1: Installation

To start using ResDB ORM, follow the instructions available on the resdb-orm repository:

https://github.com/ResilientEcosystem/ResDB-ORM/blob/main/README.md

Step 2: Setting Up Your Project

Once ResDB ORM is installed, you can start using it in your Python project. Here’s a quick guide to get you started.

Importing ResDB ORM: Begin by importing the ResDB ORM module into your Python script:
```
 from resdb_orm import ResDBORM
```
Establishing a Connection: You need to establish a connection to your ResilientDB instance, update the config.yaml file with the crow server details:
```
 db = ResDBORM()
```
Performing CRUD Operations: With the connection established, you can now perform CRUD operations.
- Create: To create a new record in the database, use the create method:
```
 data = {"name": "abc", "age": 123}
 create_response = db.create(data)
```
- Read: To read data from the database, use the read method:
```
 read_response = db.read(create_response)
 print(read_response)
```
- Update: Updating an existing record is done using the update method:
```
 update_response = db.update(create_response, {"name": "def", "age": 456})
```
- Delete: To delete a record, use the delete method:
```
 delete_response = db.delete(create_response)
```

🎉 Conclusion

ResDB ORM simplifies database interactions for developers working with ResilientDB. By abstracting the complexities of database operations, it allows developers to focus on building robust and scalable applications. Whether you’re managing simple CRUD operations or complex version-based data, ResDB ORM provides a reliable and Pythonic solution.

Getting Started with ResContract CLI 🚀

Tue, 16 Jul 2024 00:00:00 +0000

This guide provides a comprehensive walkthrough of the ResContract CLI for managing smart contracts on ResilientDB. It covers installation, configuration, and usage of various commands to create accounts, compile contracts, deploy contracts, and execute contract functions.

ResContract CLI GitHub Repository

🌐 Smart Contracts on ResilientDB Today

ResilientDB now supports smart contracts, allowing developers to deploy and interact with decentralized applications seamlessly. Here’s an overview of the current state:

Simplified Workflow: The ResContract CLI provides an intuitive interface for managing smart contracts.
Comprehensive Commands: It includes commands for account creation, contract compilation, deployment, and execution.
Enhanced Logging: Improved logging for better debugging and auditing.

📈 Getting Started with ResContract CLI

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (version >= 14): Download and install Node.js
npm: Comes with Node.js. Ensure it’s up-to-date.
Solidity Compiler (solc): Required to compile smart contracts.

Installing `solc`

Linux (Ubuntu/Debian):

sudo add-apt-repository ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install -y solc

macOS:

brew update
brew upgrade
brew tap ethereum/ethereum
brew install solidity

ResilientDB: A running instance with the smart contracts service enabled.

Installing ResContract CLI

Install the ResContract CLI globally using npm:

npm install -g rescontract-cli

Configuration

Before using the ResContract CLI, you must set the ResDB_Home environment variable or provide the path to your ResilientDB installation in a config.yaml file. The CLI will not prompt you for this path and will exit with an error if it’s not set.

Option 1: Set ResDB_Home Environment Variable

Set the ResDB_Home environment variable to point to the directory where ResilientDB is installed.

Linux/macOS:

export ResDB_Home=/path/to/incubator-resilientdb

Add the above line to your .bashrc or .zshrc file to make it persistent.

Option 2: Use a config.yaml File

Create a config.yaml file in the same directory where you run the rescontract command or in your home directory.

Example config.yaml:

ResDB_Home: /path/to/incubator-resilientdb

Ensure the ResDB_Home path is correct.

Note: The CLI checks for config.yaml in the current directory first, then in your home directory.

👨🏻‍💻 Using the ResContract CLI

Command Overview

create: Create a new account.
compile: Compile a Solidity contract.
deploy: Deploy a smart contract.
execute: Execute a function within a deployed smart contract.
add_address: Add external addresses to the system.
list-deployments: List all deployed contracts.
clear-registry: Clear the deployment registry.

Creating a New Account

Command:

rescontract create --config <path_to_config>

Example:

rescontract create --config ../incubator-resilientdb/service/tools/config/interface/service.config

Sample Output:

0x3b706424119e09dcaad4acf21b10af3b33cde350

Compiling a Smart Contract

Command:

rescontract compile --sol <inputFile.sol> --output <outputFile.json>

Example:

rescontract compile --sol /users/gopuman/ResContract/token.sol --output output.json

Sample Output:

Compiled successfully to output.json

Deploying a Smart Contract

Command:

rescontract deploy --config <configPath> --contract <contract.json> \
--name <contractName> --arguments "<parameters>" --owner <ownerAddress>

Example:

rescontract deploy \
  --config ../incubator-resilientdb/service/tools/config/interface/service.config \
  --contract output.json \
  --name "/users/gopuman/ResContract/token.sol:Token" \
  --arguments "1000" \
  --owner "0x3b706424119e09dcaad4acf21b10af3b33cde350"

Sample Output:

owner_address: "0x3b706424119e09dcaad4acf21b10af3b33cde350"
contract_address: "0xc975ab41e0c2042a0229925a2f4f544747fd66cd"
contract_name: "/users/gopuman/ResContract/token.sol:Token"

Executing a Smart Contract Function

Command:

rescontract execute --config <configPath> --sender <senderAddress> \
--contract <contractAddress> --function-name "<functionSignature>" --arguments "<parameters>"

Example:

rescontract execute \
  --config ../incubator-resilientdb/service/tools/config/interface/service.config \
  --sender "0x3b706424119e09dcaad4acf21b10af3b33cde350" \
  --contract "0xc975ab41e0c2042a0229925a2f4f544747fd66cd" \
  --function-name "transfer(address,uint256)" \
  --arguments "0x4847155cbb6f2219ba9b7df50be11a1c7f23f829,100"

Sample Output:

Function executed successfully.

Adding External Addresses

Command:

rescontract add_address --config <path> --external-address <address>

Example:

rescontract add_address --config ../incubator-resilientdb/service/tools/config/interface/service.config \
--external-address 0xExternalAddress

Listing Deployed Contracts

Command:

rescontract list-deployments

Example:

rescontract list-deployments

This command displays all deployed contracts with their owner addresses, contract names, and contract addresses.

Clearing the Registry

Command:

rescontract clear-registry

Example:

rescontract clear-registry

Warning: This command permanently removes all deployment tracking information.

📋 Deployment Registry

The ResContract CLI automatically tracks all deployed contracts in a registry file located at ~/.rescontract_deployed_contracts.json. This registry provides several benefits:

Duplicate Prevention: Prevents deploying the same contract with the same owner and name
Contract Tracking: Maintains a record of all deployed contracts with their addresses
Easy Management: Use list-deployments to view all contracts and clear-registry to reset

The registry stores the following information for each deployment:

Owner address
Contract name
Contract address
Deployment timestamp

📝 Advanced Usage and Tips

Logging: The ResContract CLI logs important events and errors to ~/.rescontract-logs/cli.log.
Error Handling: If you encounter errors, check the logs for detailed information.
Permissions: Ensure you have the necessary permissions to execute commands and access files.
Registry Management: Use list-deployments to track your deployed contracts and clear-registry to reset when needed.
Duplicate Prevention: The registry automatically prevents deploying the same contract with the same owner and name.
Updating ResContract CLI: Keep your CLI up-to-date by running:

npm update -g rescontract-cli

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines to get started.

📄 License

This project is licensed under the Apache License

📚 Additional Resources

ResilientDB Documentation: ResilientDB GitHub Repository
Solidity Documentation: Solidity Official Site

ResChat

Fri, 31 May 2024 00:00:00 +0000

1. Project Description

1.1 Overview

In today’s life, when we try to send a message on most chat software, the message will first be sent to the central server, and then forwarded to the target user by the central server. The disadvantage of this is that all data will be captured and stored by the central server, which greatly increases the risk of data leakage and leakage of private information. Now, we will create a decentralized chat system based on the ResilientDB blockchain. This decentralized chat system does not store any personal information, and only the sender and recipient can encrypt and decrypt the message during the transmission of the message.

1.2 Key Features

Decentralized Architecture: Our system avoids the need for a central server. All messages are transmitted through ResilientDB blockchain.
Security: By using the combined encryption algorithm(RSA + AES), we can ensure that information cannot be easily cracked during blockchain transmission. Only the sender and recipient of the message can use their keys to encrypt and decrypt
Privacy-first Approach: User data is never stored on any central server. No chat history will be stored.
Open-source: To ensure utmost transparency and security, our system is fully open-source, allowing community participation and review.
Flexibility: Users can create their own ResilientDB blockchain and use ResChat as an intranet chatting software, or users can connect to the main blockchain and use ResChat as an internet chatting software.
Extremely low disk space usage: Users only need to store their private key locally, and everything else is stored in the blockchain.

2. Overall Idea

2.1 Message and Page

The key of messages is a custom class called Page. Page serves as a container to store and transfer messages. Each Page has 20 messages and each message has 7 different fields. When a page is full, a new page will be created.

Receiver’s public key: Who will receive this message, base on this we can identify who is the sender and receiver of this message.
Message type: TEXT or FILE to identify how to process this message.
Time stamp: When this message been sent.
Message type extension: Only in use when message type is FILE to store file name and extension such like testFile.pdf
Encrypted message: If message type is TEXT, this field will store the encrypted text string. If message type is FILE, this field will store a key(A ResilientDB key) and the corresponding value is IPFS filesystem’s hashes and their metadata that. In this way, it will not give a high pressure to the internet, and computing power. Users can choose to download the file or not.
Encrypted AES key with sender’s RSA public key: Use sender’s RSA public key to encrypt randomly generated AES key. So, sender can decrypt AES key with his/her RSA private key.
Encrypted AES key with receiver’s RSA public key: Use receiver’s RSA public key to encrypt the AES key. Only receiver can decrypt this message. In this approach, sender and receiver can both encrypt and decrypt certain message with their own RSA private keys without expose the keys to each other.

Both sender and receiver will obtain some shared pages. This project is using kv service of the ResilientDB, and the command line instructions are set key value and get key. The key part constructed with two fields page name and page number. The page name is constructed by sender and receiver’s username(sorted in ASCII order) to ensure that both receiver and sender will have the same page name. Page name will never change throughout the chatting. On the other hand, page number starts at 1, and it will increase by 1 everytime the page is full. ResChat will load most recent two pages everytime user start up the client(current page and current page -1) In this way, all chat history are stored on the chain(ResilientDB) and user can load as many as previous chatting history as he/she wants.

2.2 Encryption/Decryption

This project uses RSA + AES as the encryption algorithm. The message will be first encrypted by a randomly generated 16 bytes(128 bits) AES key. Then, this AES key will be encrypted by 2048 bits RSA public key(AES key will be encrypted twice, one with sender’s public key, another with receiver’s public key). In this approach, ResChat can achieve not only secure text messages transfer but also secure file transfer(RSA can not encrypt a string that is too long).

3. How to run

Install Anaconda
Install Bazel 5.0.0 on Ubuntu or Mac

Setup Anaconda Environment

conda create --name YOUR_ENV_NAME python=3.8
conda activate YOUR_ENV_NAME
cd ResChat
pip install -r requirements.txt

Build Bazel(Make sure run bazel build command with the Anaconda environment just crated )
```
cd ResChat
bazel build :pybind_kv_so
```

Run Front-end Service

cd frontend
npm run install
npm run start

Run Back-end Service
```
python3 http_request.py
```

4. Some screenshot

Login page
Chatting page

ResLenses

Tue, 21 May 2024 00:00:00 +0000

Project Overview:

The Res-Lenses page is an in browser UTXO heatmap visualization of the ResilientDB network and the Ethereum network. It utilizes the three.js 3D graphics library for the browser to visualize transaction activity across all possible pairs of addresses collected, allowing for the viewing of transaction activity in various configurations to best find patterns in UTXO movement.

Browsers this is known to work in (others may have difficulty): Microsoft Edge and Google Chrome

You may access the ResLenses app here and view the demo here.

Front End Overview

Getting Started on Page Launch

Opening the page up, you will initially view the top left corner of a very large grid representing transactions on the ResilientDB network. As you mouse around, you will notice green and blue lines pinpointing the block you are hovering. That block represents the transaction activity between two address as shown on the top left tab. As you will also notice, addresses implicity line the X and Y axis of the grid, and each block represents activity of the intersecting addresses. If the activity between two addresses is non-grey, then there is some activity, and double clicking on that block will pull up a tab on the left. In that tab, you can see all UTXO sent from one address to the other in a From and To relationship.

Scene Controls

The basis of the visualization is with the Three.js library, which allows for the creation and viewing of 3D scenes in the browser. The camera is fixed to face down on the grid and can be navigated using purely mouse controls.

Movement: Hold click and drag aronud to move through the 2D Grid. Clicking the Return to Origin button in the bottom left will return you to the top left corner of the grid. Chunks of blocks will load and unload as you move around, you may even see some chunks load in if moving quickly enough. Mouse dragging does not work when the mouse is hovering over UI.

Selection: Blocks that are moused over will display their From and To addresses in the top left tab with a summation of the transactions between the two addresses. Double clicking a block will focus and highlight it and open a tab to the left that displays all the transactions that occurred. Regular clicking anywhere will de-focus the block.

Bottom Bar Buttons

At the bottom of the page is a bar with five buttons. These allow for various configurations for visualizing the same data. Though the data can also be swapped between ResilientDB and the Ethereum Mainnet. Aside from the data selection button, all configurations are computer client side.

Return to Origin: Reset the position of the camera to the top left corner. If view mode is in bar mode, this simply moves the camera back to the far left.

Data: Selects the source of the data to view. Default is ResDB.

ResDB: ResilientDB data. All transactions that have occurred on the ResilientDB network with amounts involved.
Ethereum: Sampled data collected on the ethereum network. A sample of 48,000 transactions from the last 24 hours and all the addresses involved. Typically will have more addresses than transactions. Note that this will take a second to load.

Note: With Ethereum, there are typically more addresses than transactions, resulting in very sparse looking data. It is recommnded that this data is viewed with the Largest Transaction sorting scheme and or with the Symmetry setting set to true to bring forth more activity to the top left.

Sort: Selects the sorting method for the order in which the adddresses appear from left/top to right/bottom. Default is Transactions Total

Transactions Total: Addresses are sorted by the sum total of UTXO sent out.
Number of Transaction: Addresses are sorted by the total number of transactions they’ve sent out.
Largest Transaction: The address-to-address activity blocks are sorted first, then the addresses belonging to the largest activity are added first. This typically results in a diagonal pattern of blocks that slowly shrink from top left to bottom right.

For Ethererum, data would typically look like this with default settings:

There is basically nothing for a far range. You would need to search extensively to find the activity. But with Sort by Largest Transaction, you will get something like this:

View: Selects the viewing method of transaction activity. Default is Grid

Grid: This is the primary way to view transactions. Displays all pairwise activity between addresses as a 2D grid, forming a physical adjacency matrix of addresses to addresses with blocks as the activity between them.
Bar: This flattens all the transactions into a single block along the y axis, changing the view into a bar graph along a single axis. This gives the total activity of each address, with details on all transactions still available on the focus tab to the left when bars are selected.

This is the sparse Ethereum data with bar view. We can more aptly view the activity of the addresses.

Symmetry: Toggle for whether or not to combine transactions sent out and transactions recieved when computing blocks. Default it False

False: Transactions as asymmetrical, the transactions sent from and to and address are distinct.
True: Transactions are symmetrical, as in there is no distinction between transactions sent from or to an address, they are the same and just considered transactions between addresses.

Here is how the ResilientDB data looks with Sort by Largest Transaction with Symmetry set to false

Here is the same configuration except with Symmetry set to true. Notice how seemingly more activity shows up as transactions sent to and transactions recieved from addresses are compounded together to form the blocks. This is an alternative way to reduce visual sparsity in the data as it increases the value of many blocks while also giving new blocks to addresses that only receive transactions.

Back End Overview

Server

The backend is a Node.js Express app that runs on the ResilientDB cloud. It procures data from the ResilientDB and Ethereum Mainnet networks at regular intervals, processes and stores the data on the server, and provides endpoints for Res-Leneses to access that processed data.

Data collection

ResilientDB: Data is collected at a one hour interval from the https://crow.resilientdb.com/v1/transactions endpoint. This contains all transactions that have ever occurred on the ResilientDB network and is then processed for only From/To transactions with UTXO amounts. Processing cleans out the data of invalid JSON and bad transactions down to a set of addresses and transactions. A single file holds the processed ResilientDB data.

Ethereum Mainnet: Data is collected at a 30 minute inverval using the Bit Query API. Using this, the server collects 1000 transactions at a time per interval containing only transactions from that interval. Each interval correlates to a file holding transactions for that interval. Transactions 24 hours old are discarded every interval. This leaves the newest 48,000 transactions available at all times. Due to API limitations, this is the most data that can be collected per day. Processing is very simple with some naming tweaks as the API already provides relatively clean data.

Endpoints

There are two endpoints provided by the backend which the Res-Lenese front end utilizes, each to supply data for the ResilientDB network and the Ethereum Mainnet. The format of the data is listed as a list of all addresses involved and then all transactions. All configuration and reorganization of data is done client side on the front end.

https://res-lenses-backend.resilientdb.com/getData_RESDB: This provides the processed ResilientDB file containing all transactions with transactions times set as DateTime numbers.
https://res-lenses-backend.resilientdb.com/getData_ETH: This compiles all the data from all the Ethereum data files and send them. Transaction times are set as DateTime strings.

Transaction data is relatively simple, they contain the following:

From: Address UTXO is sent from
To: Address UTXO is sent to
Amount: Amount of UTXO sent
Timestamp: Time of transaction (Number for RESDB and String for ETH)

This is what you should see if you try to directly access https://res-lenses-backend.resilientdb.com/getData_RESDB.

Using the ResilientDB Desktop Wallet

Wed, 20 Dec 2023 00:00:00 +0000

This is a blog to help get started with the Desktop Wallet for Tx/Rx built on the Resilient DB network

Connecting to Resilient DB
Building the Frontend
Securing User Accounts
Familiarizing Yourself with Your Wallet
Future Plans for ResilientDB Desktop Wallet

Connecting to Resilient DB

There are a host of ways we can connect to the Resilient DB decentralized system:

Crow HTTP server
Python SDK
GraphQL

We chose the last option, GraphQL, as it it offers a high level and easy to implement API for a fast development cycle.

Mini SDK and Third Party Libraries

It’s hard to use raw HTTP requests for accessing GraphQL. It’s difficult to read and complicated to understand GraphQL documents.

To facilitate our development, we built a mini sdk using typescript and the open source library graphql-request.

Mutations

The primary mutation we implemented is postTransaction.

postTransation = async (
    amount: number,
    recipientPublicKey: string,
    data?: object,
    metadata?: string
): Promise<string> => {
    data = data || {};

    data = {
        ...data,
        time: Date.now(),
    };

    data = {
        ...data,
        client: {
            name: appName,
            version: appVersion,
        },
    };
    const doc = gql`
        mutation { postTransaction(data: {
            operation: "CREATE"
            amount: ${amount}
            signerPublicKey: "${this.user.publicKey}"
            signerPrivateKey: "${this.user.privateKey}"
            recipientPublicKey: "${recipientPublicKey}"
            asset: """{
                        "data":  ${JSON.stringify(data)},
                    }"""
            }) 
            {
                id
            }
        }
    `;

    const resp: { postTransaction: PostTransactionResult } =
        await this.client.request(doc);
    return resp.postTransaction.id;
};

postTransaction is responsible for sending RoKs between user accounts.

Here we allow for the developer to pass in arguments related relevant for sending tokens.

amount – the total number to tokens to send
recipientPublicKey – the public key of the recipient
metadata – optional metadata to pass in the transaction
data – other data to pass into the asset field

Queries

While we did implement quries such as getTransaction, the primary method we use to retrieve transactions data is the getFilteredTransactions query.

getFilteredTransactions = async (
    ownerPublicKey?: string,
    recipientPublicKey?: string
): Promise<FilteredTransaction[]> => {
    const doc = gql`
        query {getFilteredTransactions(filter: {
            ownerPublicKey: "${ownerPublicKey || ""}",
            recipientPublicKey: "${recipientPublicKey || ""}"
        }) {
            id
            version
            amount
            metadata
            operation
            asset
            publicKey
            uri
            type
        }}
    `;

    const resp: GetFilteredTransactionsResult = 
        await this.client.request(
            doc
        );

    return resp.getFilteredTransactions;
};

getFilteredTransactions allow us to retrieve the list of transactions either sent or received by our user.

We retrieve sent transactions by passing in the user’s public key as the ownerPublicKey.

Alternatively we retrieve transactions the user received by passing in their public key as the recipientPublicKey.

Processing

The GraphQL queries and transactions do not directly allow us to view the user’s wallet contents.

To do so we need additional processing.

getPastTransactions = async (): Promise<WalletGetTransactionsResult> => {
    const transactionsSent =
        await this.graphqlClient.getFilteredTransactions(
            this.user.publicKey
        );
    const transactionsReceived =
        await this.graphqlClient.getFilteredTransactions(
            null,
            this.user.publicKey
        );
    return {
        transactionsSent,
        transactionsReceived,
    };
};

This utility function allows us to retrieve all of the users transactions.

We pass in the user’s public key as the ownerPublicKey and the recipientPublicKey separately to receive both transactions sent and received.

getWalletContent = async () => {
    const { transactionsSent, transactionsReceived } =
        await this.getPastTransactions();

    return (
        transactionsReceived.reduce(
            (a, b) => ({ amount: a.amount + b.amount }),
            { amount: 0 }
        ).amount -
        transactionsSent.reduce(
            (a, b) => ({ amount: a.amount + b.amount }),
            { amount: 0 }
        ).amount
    );
};

To actually calculate the amount of RoKs in the user’s wallet:

We first add up the amount of RoKs received in all transactions, then subtract the amount of RoKs sent from the wallet to calculate the final amount.

Summary

We choose to use the GraphQL API in connecting to the Resilient DB instance due to it’s simplicity and use of use.

We created a Mini-SDK implementing functions for querying and mutating transactions.

We established a method for calculating the total amount of RoKs in the user’s wallet.

Further Resources

Building the Frontend

Technologies Used

React.js
Electron.js
GraphQL
Mantine
Theme Forest Template (Hexadash)

Why React.js?

Given the time constraint that we had, we had to make sure that we chose frameworks that all of our members were comfortable with! As all of us had experience with React before, we decided to go ahead with React, as opposed to other JavaScript frameworks like Angular or Vue.

We were also debating as to whether we should use React.js or React Native. However, once we eventually settled on the fact that we were going to make a Desktop app, and not a mobile app, React.js was an easy choice.

Why Electron.js

React.js is normally used for locally hosting a website that follows HTTP/HTTPS standards. However, we were aiming for a Desktop app, to make it easier to use for users. Similar to how Discord uses Electron to convert their web app into a desktop app, we used Electron.js on top of our React.js code to develop a desktop app instead of a web app.

Communicating between the frontend and backend

Given that we wanted to make our app functional, it was vital that there was a clear path for the frontend to talk to the backend. We did this using GraphQL. We called the GraphQL from the frontend, which then executed our queries on the backend, and efficiently returned the data back to the frontend.

Sample backend call for sending a transaction

if (amount !== "" && publicKey != "") {
  await api.transactions.postTransaction(
    parseInt(amount),
    publicKey,
    metaData ? { metadata: metaData } : undefined
  );
  open();
}

CSS templates/components

Once again, given the time constraint, we wanted to focus on the functionality of our app more than the design. As a result, we went on Theme Forest, and searched for potential templates we could use. We were looking for templates that had built-in designs for a dashboard and a sign in page, as that was the main part of our app.

We also used React components to make it easier to write CSS. Mantine has built in components for common things used in websites such as cards, checkboxes, or confirmation modals.

Overall, using these external libraries had both positives and negatives. As the theme forest library we chose had a huge number of files, it was hard to simply integrate their code into our repository. The library had a lot of dependencies and functions in other files that they relied on. As a result, we ended up only using the Theme Forest library for our sign in page, and wrote the CSS for the dashboard ourselves, with help from Mantine as well.

Example of a Mantine TextInput component

<TextInput
    placeholder="Enter amount"
    value={amount}
    onChange={(event) =>
        setAmount(
            event.currentTarget.value
        )
    }
    rightSectionPointerEvents="all"
    rightSection={
        <CloseButton aria-label="Clear input" onClick={() => setAmount("")} style= />
    }
    withErrorStyles={false}
    required
    error={
        amountError
            ? "Please fill out this field"
            : null
    }
/>

Securing User Accounts

If you’re wondering how we made our passwords secured, you’ve come to the right place! Our code was written in Nodejs.

You can access the 4 open source libraries that we implemented by importing the following:

nacl: Able to generate a new pair of public and private keys:

import nacl from "tweetnacl";

base58: Encodes or Decodes our password and returns a string

import base58 from "bs58";

crypto: Used to implement SHA512 and AES-256-CBC to hash and cipher/decipher passwords

import crypto from "crypto";

keytar: Acts like a keychain where we can store passwords and access them safe and easily

import keytar from "keytar";

Once you’ve imported all the necessary libraries, let’s dive into the functions that we’ve created to understand how we did it.

Generating Keys

Recalling from before, we were able to create a key pair with the use of nacl.

With the help of nacl, we will have two outputs with our variable pair, one being a public key and the other being a secret key.

Accessing them through the pair will get us our public and private keys.

static createKeyValPair = () => {
  const pair = nacl.sign.keyPair(); // keypair
  const publicKey = base58.encode(pair.publicKey); //public key
  const privateKey = base58.encode(pair.secretKey.slice(0, 32)); // private key
  return { publicKey, privateKey };
};

Hashing Password

With the help of the crypto library, we are able to use SHA512 to create a hash object and update the password and lastly putting it into hexadecimal format.

static hashPassword = (password: string) => {
  return crypto.createHash("sha512").update(password).digest("hex"); // hashes the password
};

Cipher and Decipher Password

Similarly like SHA512, we used the crypto library to use AES-256-CBC.

We first converted the password to a buffer out of ASCII.
We make sure that the password is exactly 32 bytes so it doesn’t throw any errors.
We create the cipher object using AES-256-CBC along with our paddedkeybytes and cipherIV.
Lastly, we update the cipher with the private key in UTF-8 encoding and produce the encrypted private key in hexadecimal format.

encryptPrivateKey = (password: string) => {
    const keybytes = Buffer.from(password, "ascii");
    if (keybytes.length > 32 || keybytes.length < 1) {
        throw new Error("Password must be between 1 and 32 bytes long");
    }
    const paddedKeyBytes = Buffer.concat([keybytes], 32);
    const cipher = crypto.createCipheriv(
        "aes-256-cbc",
        paddedKeyBytes,
        cipherIV
    );
    this.encryptedPrivateKey =
        cipher.update(this.privateKey, "utf8", "hex") + cipher.final("hex");
};

The Decipher functions reverses the ciphering process:

decryptPrivateKey = (password: string) => {
    const keybytes = Buffer.from(password, "ascii");
    const paddedKeyBytes = Buffer.concat([keybytes], 32);
    const decipher = crypto.createDecipheriv(
        "aes-256-cbc",
        paddedKeyBytes,
        cipherIV
    );
    this.privateKey =
        decipher.update(this.encryptedPrivateKey, "hex", "utf8") +
        decipher.final("utf8");
};

Keytar

After the user creates the account, the keys get saved into the keychain using keytar

writeUserAccountToFile = async () => {
    await keytar.setPassword(
        appName,
        this.username,
        JSON.stringify({
            passwordHash: this.passwordHash,
            publicKey: this.publicKey,
            encryptedPrivateKey: this.encryptedPrivateKey,
        })
    );
};

Familiarizing Yourself with Your Wallet

When you first launch our desktop wallet, things might look a little bit confusing. But don’t worry! We’ve made our wallet simple to understand and navigate. However, if you’re still lost, you’ve come to the right place to learn more.

Sign in / Register

When launched, the application will display the following:

As you can see, you have the option to register a new account with us, or log-in to an existing account in our database.

We’ll assume that you are a new user that has just registered an account. Once your account is created, you’ll be directed to your Dashboard.

Dashboard

Your dashboard is the main hub of your wallet. It’s where all of the wallet’s functionality can be accessed.

Here’s what the dashboard of a newly registered user looks like:

There are 3 important sections of your dashboard (circled in red above)

Your Past Transactions
Send a Transaction
View Keys

Your Past Transactions

This section of the application displays all previous transactions that your account has made. Naturally, for a new account, this section would be empty. However, as you accumulate transactions, they will start to display here, and you can scroll through all of them horizontally.

For example, this is what the dashboard for a highly-active account may look like:

Send a Transaction

There are 2 things you must have for a successful transaction:

Your recipient’s public key
The amount that you want to transfer

There is a third (optional) spot, reserved for metadata. This could include a brief description of the transaction, ex. Groceries or Pizza.

To send a transaction, you’ll have to ask your recipient for their public key first. Once you have that, do the following:

Paste the recipients public key
Enter the transfer amount
Add a description if you’d like

Then hit ‘Send’ and you’ll see a pop-up indicating a successful transfer.

To view the details of the transaction, just refresh the page, and it will pop up under ‘Your Past Transactions’.

View Your Account’s Keys

The ‘View Keys’ section displays some important information about your account. It holds sensitive information such as:

Account Balance
Public Key
Private Key

The account balance shows the money your account holds. It updates every time you make a transaction.

Your public key is what you give to others so they can pay you. Only give someone your public key if you know them and if they want to initiate a transfer to your account.

Your private key is sensitive information that is unique to your account and your account only.

NEVER give someone your private key. To ensure that your private key isn’t easily viewable, we’ve added a button that, when clicked, either shows or hides the private key for extra security.

Logging Out

To log out, simply click the button at the top right. This will securely save your information in our database which can easily be re-accessed by logging in.

Wrapping Up

Once again, thanks for choosing to use our Desktop Wallet for your financial needs. We hope this post gave you a better understanding of the features of your wallet to help you use it to its maximum potential.

If you have any further questions, don’t hesitate to contact us!

Future Plans for ResilientDB Desktop Wallet

In the dynamic world of digital currencies, the ResilientDB Desktop Wallet stands as a beacon of innovation. As we envision the future, our mission is to enhance accessibility, security, and user experience. Let’s delve into the exciting potential plans that await our desktop application.

App Store Deployment

Gone are the days of complex installations! Soon, users will find our desktop wallet on the app store, simplifying access for everyone. No more command lines or dependencies—just a seamless experience for all. We hope to soon have our application displayed right on the front page of the App Store.

Going Mobile

Imagine the freedom to manage your digital assets anytime, anywhere. Introducing the mobile version of our ResilientDB Desktop Wallet—a sleek and intuitive design tailored for on-the-go users. The mobile app mirrors the desktop features with enhanced mobile-friendly interfaces.

Currency Exchange at Your Fingertips

We’re breaking barriers by introducing a currency exchange option directly on the dashboard. Users can effortlessly convert or trade their funds, opening the door to financial flexibility. Registering your bank account seamlessly links your financial world with our wallet.

Fortifying Security

Protecting your assets is paramount. Our enhanced security features include a authentication via email or phone, ensuring each login is secure. Additionally, receive instant transaction alerts via email, offering real-time updates on your wallet activity.

As we embark on this journey, the ResilientDB Desktop Wallet is poised to revolutionize the digital currency landscape. Join us in this exciting chapter—try our wallet, share your thoughts, and be a part of the future we’re crafting together. The possibilities are endless, and the future is now.

Using the ResilientDB TypeScript SDK

Sun, 17 Dec 2023 00:00:00 +0000

Introduction to ResilientDB TypeScript SDK: Building Robust Applications

The digital era demands robust solutions that can handle data with precision, security, and flexibility. Blockchain technology is championing this revolution, and at the heart of many innovative applications is ResilientDB, a versatile distributed ledger that offers both trust and transparency.

In this in-depth look, we will explore the ResilientDB TypeScript SDK, an essential toolkit for developers seeking to leverage the ResilientDB platform in their JavaScript and TypeScript applications. Through the integration of GraphQL, the SDK simplifies interactions with the ResilientDB server, enabling easy queries and mutations to manage transactions effectively.

What Is ResilientDB?
Prerequisites
Installation
SDK
Clients
ResilientDB Client Methods
Types
SDK Demo Application
Use the SDK in 6 easy steps
Real-World Value and Implications
Conclusion

What Is ResilientDB?

ResilientDB is a distributed ledger infrastructure that emphasizes resilience, scalability, and decentralized control. It allows applications to perform transactions in a distributed environment with trust and transparency being paramount.

NPM Package: `resilientdb-javascript-sdk`

Before diving deep into the codebase, let’s address how to get the SDK into your project. The resilientdb-javascript-sdk is readily available on the NPM registry and can be included in your project with ease.

Prerequisites

Setup Node v18

Ensure you have Node v18 installed

>> node --version
v18.17.0

Setup ResilientDB-GraphQL (Run Locally)

If you would like to use your own ResilientDB replica set, you must run the ResilientDB stack along with ResilientDB-GraphQL. Instructions can be found here Otherwise, point the client to https://cloud.resilientdb.com.

Installation

To install the SDK, run the following command in your project directory:

npm install resilientdb-javascript-sdk

Introducing the SDK

The SDK comes with three main modules that form its core functionality. Each plays a significant role in ensuring a streamlined interface for communicating with the ResilientDB server.

Clients

The FetchClient and AxiosClient are two interchangeable network clients that ResilientDB utilizes to make HTTP requests to the ResilientDB server.

FetchClient (`FetchClient.ts`)

A lightweight client using the Fetch API. It’s optimal for environments where size and simplicity are key.

Example of initializing a FetchClient:

import { ResilientDB, FetchClient } from 'resilientdb-javascript-sdk';

const fetchClient = new FetchClient();

AxiosClient (`AxiosClient.ts`)

A feature-rich client based on axios. This client is suited for those who may need interceptors, progress indicators, or other advanced features provided by axios.

Example of initializing an AxiosClient:

import { ResilientDB, AxiosClient } from 'resilientdb-javascript-sdk';

const axiosClient = new AxiosClient();

ResilientDB Client (`ResilientDB.ts`)

The SDK’s main class provides a user-friendly interface to the ResilientDB server’s GraphQL API. It includes methods for retrieving, filtering, and posting transactions, as well as generating cryptographic key pairs.

Core Types (`types.ts`)

Defines the interfaces and types used throughout the SDK, ensuring type safety and developer experience.

ResilientDB Client Methods

Here’s a detailed look at each method provided by the ResilientDB client.

Transaction Retrieval Methods

Method	Input Parameters	Output	Description
`getTransaction`	`requestId: string`	`Promise<RetrieveTransaction>`	Retrieves a single transaction by its unique ID.
`getAllTransactions`	-	`Promise<RetrieveTransaction[]>`	Fetches all transactions.
`getFilteredTransactions`	`filter?: FilterKeys`	`Promise<RetrieveTransaction[]>`	Retrieves transactions that match the given filtering criteria.

FilterKeys: A type that includes optional fields for filtering transactions by ownerPublicKey and recipientPublicKey.

Transaction Mutation Methods

Method	Input Parameters	Output	Description
`postTransaction`	`transaction: PrepareAsset`	`Promise<CommitTransaction>`	Posts a new transaction to the ledger.
`updateTransaction`	`transaction: UpdateAsset`	`Promise<RetrieveTransaction>`	Updates an existing transaction.
`updateMultipleTransaction`	`transactions: UpdateAsset[]`	`Promise<RetrieveTransaction[]>`	Updates multiple transactions at once.

PrepareAsset: A type representing the necessary information to prepare a transaction for posting.
UpdateAsset: A type used for detailing the specifications required to update a transaction.
CommitTransaction: Represents the output of posting a new transaction, which includes, at minimum, the id of the committed transaction.

Key Generation Method

Method	Input Parameters	Output	Description
`static generateKeys()`	-	`{ publicKey: string; privateKey: string}`	Generates a pair of public and private keys for signing transactions.

Types

`NetworkClient`

export interface NetworkClient {
  request<TReturn extends object>(options: {
    url: string,
    headers?: Record<string, string>
  } & (
      | {
        method: 'GET',
      }
      | {
        method: 'POST',
        body: string | object
      }
    )): Promise<TReturn>
}

`RetrieveTransaction`

type RetrieveTransaction = {
  id: string;
  version: string;
  amount: number; // integer
  uri: string;
  type: string;
  publicKey: string;
  operation: string;
  metadata?: string | null;
  asset: string;
}

`CommitTransaction`

type CommitTransaction = {
  id: string;
}

`PrepareAsset`

type PrepareAsset = {
  operation: "CREATE" | string;
  amount: number;
  signerPublicKey: string;
  signerPrivateKey: string;
  recipientPublicKey: string;
  asset: object;
}

`UpdateAsset`

type UpdateAsset = {
  id: string;
  operation?: string | null;
  amount?: number | null; // int
  signerPublicKey: string;
  signerPrivateKey: string;
  recipientPublicKey?: string | null;
  asset?: string | null;
}

`FilterKeys`

type FilterKeys = {
  ownerPublicKey?: string | null;
  recipientPublicKey?: string | null;
}

`Keys`

type Keys = {
  publicKey: string
  privateKey: string
}

SDK Demo Application

Included within the SDK repository is a demo React application that showcases the SDK’s capabilities. The app allows users to filter transactions, post new transactions, and explore the core features of the ResilientDB TypeScript SDK.

Use the SDK in 6 easy steps

Step 1: Project Setup and SDK Installation

Set up a new TypeScript project and install the resilientdb-javascript-sdk package as well as TypeScript and the necessary types for Node.js.

mkdir resilientdb-ts-example
cd resilientdb-ts-example
npm init -y
npm install resilientdb-javascript-sdk
npm install typescript ts-node @types/node --save-dev

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  }
}

Step 2: Generating Keys

In the index.ts file:

import { ResilientDB } from 'resilientdb-javascript-sdk';

// Generate public and private keys
const { publicKey, privateKey } = ResilientDB.generateKeys();

console.log(`Public Key: ${publicKey}`);
console.log(`Private Key: ${privateKey}`);

Step 3: Initializing the Client

Continue editing the index.ts to initialize the client:

import { ResilientDB, FetchClient } from 'resilientdb-javascript-sdk';

// Initialize the client
const resilientDBClient = new ResilientDB("https://cloud.resilientdb.com", new FetchClient());

Step 4: Fetching and Filtering Transactions

Add functions to fetch all transactions and filter based on certain criteria.

// Fetch all transactions
async function getAllTransactions() {
  const transactions = await resilientDBClient.getAllTransactions();
  console.log('All Transactions:', transactions);
}

// Fetch transactions with filters
async function getFilteredTransactions() {
  const filter = {
    ownerPublicKey: publicKey,
    // recipientPublicKey can also be specified here.
  };
  const transactions = await resilientDBClient.getFilteredTransactions(filter);
  console.log('Filtered Transactions:', transactions);
}

getAllTransactions();
getFilteredTransactions();

Step 5: Posting and Updating Transactions

Add functions to post a new transaction and then update it.

// Post a new transaction
async function createTransaction() {
  const transactionData = {
    operation: "CREATE",
    amount: 100,
    signerPublicKey: publicKey,
    signerPrivateKey: privateKey,
    recipientPublicKey: publicKey, // For the sake of example, sending to self
    asset: { message: "Initial transaction" }
  };
  
  const transaction = await resilientDBClient.postTransaction(transactionData);
  console.log('Transaction posted:', transaction);
  
  return transaction.id; // We'll need the transaction ID to update it next
}

// Update the created transaction
async function updateTransaction(transactionId: string) {
  const updateData = {
    id: transactionId,
    amount: 150, // Updated amount
    signerPublicKey: publicKey,
    signerPrivateKey: privateKey,
    recipientPublicKey: publicKey, // Still sending to self
    asset: { message: "Updated transaction data" }
  };
  
  const updatedTransaction = await resilientDBClient.updateTransaction(updateData);
  console.log('Transaction updated:', updatedTransaction);
}

async function runDemo() {
  const transactionId = await createTransaction();
  await updateTransaction(transactionId);
}

runDemo();

Step 6: Running the Project

You can now run the project from the terminal:

npx ts-node index.ts

Real-World Value and Implications

By simplifying the integration and interaction with the ResilientDB server, the SDK opens the door to a plethora of applications. Whether you’re developing a finance app that requires ledger capabilities or seeking the immutability of blockchain for asset tracking, the ResilientDB TypeScript SDK is a capable starting point.

The versatility in choosing between the FetchClient and the AxiosClient ensures developers have the liberty to pick a client that best suits their specific needs, whether they prioritize speed and minimalism or extensive features.

Conclusion

The ResilientDB TypeScript SDK stands as a testament to the possibilities when modern web technologies meet blockchain principles. Through its approachable interface and adaptable architecture, the SDK demonstrates how applications can be built with resilience at their core, ready to scale and secure transactions across a distributed network.

Whether you’re an experienced blockchain developer or a newcomer to distributed ledger technology, the SDK provides the necessary tools to interface with the ResilientDB platform with confidence and ease.

The Emergence of Echo in the Gig Economy

Sun, 17 Dec 2023 00:00:00 +0000

The gig economy, with giants like Uber, Lyft, and Doordash, has transformed the employment landscape, offering flexibility and convenience. But with these benefits come challenges, especially in identity verification. The authenticity of contractors is crucial in maintaining operational integrity and user trust. Echo arises as a solution to streamline identity verification, enhancing trust and efficiency in the gig economy.

Challenges of Current Verification Systems

Present systems face issues like inconsistent processes, technological limitations, and privacy concerns. Scaling these systems is often inefficient, leading to bottlenecks. Echo addresses these problems by offering a universal, technologically advanced, and secure solution.

Echo’s Solution: Facial Recognition and Blockchain Integration

Echo integrates advanced facial recognition and ResilientDB blockchain technology, providing a robust framework for identity verification. Our system leverages the MXFace API for accurate facial recognition and mints NFTs on the blockchain for secure and transparent contractor history.

MXFace API call to compare 2 faces:

var  optionsFaceCompare = {

url: _apiUrl + 'verify',

method: 'POST',

headers: {

'subscriptionkey': _subscriptionKey,

'Content-Type': 'application/json'

},

json: {

encoded_image1: base64SingleFace,

encoded_image2: base64MultipleFace

},

rejectUnauthorized: false,

};

request(optionsFaceCompare, function (error, response) {

console.log("Response /verify");

if (error) {

console.log(error)

}

else {

console.log(response.body)

res.json(response.body);

}

});

User submits an image to be verified and minted

System Design: Simplicity and Security

The user interface of Echo focuses on ease of use, featuring a straightforward landing and login page. The system ensures privacy by keeping personal data like photos and personal information off the blockchain, only using them for identity comparison. Additionally, the use of Google Authentication allows for a streamlined and accessible way to view and verify and induvidudal.

Technical Implementation: MongoDB, ResilientDB, and React

Echo employs MongoDB for secure data storage, ResilientDB blockchain for verification tokens, and a React-based ledger page for user interaction. This blend of technologies ensures security, transparency, and ease of use.

MongoDB API call for creating an account using Google Authentication:

const createPerson = async (req, res) => {
  const { title, description, image, icon, Person, convos } = req.body;
  let emptyFields = [];
  if (!title) {
    emptyFields.push("title");
  }
  if (!Person || Person.length === 0) {
    emptyFields.push("Person");
  }
  if (emptyFields.length > 0) {
    return res.status(400).json({ error: "Please fill in all fields", emptyFields });
  }
  try {
    const user_id = req.user.id;
    const newPerson = await Person.create({
      title,
      description,
      image,
      icon,
      Person,
      convos,
      user_id
    });
    res.status(200).json(newPerson);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
};

This code allows us to store user information, in order to keep track of wallets using private and public keys, and to mint and access the NFTs later.

Python SDK calls to interact with ResilientDB (Flask):

Creating a New Key

@app.route("/create_key")
def create_key():  
    key = generate_keypair()
    print(key)
    key_dict = {
        "private": key[0],
        "public": key[1]
    }
    key_json = json.dumps(key_dict)
    return key_json

This route is responsible for generating a new key pair.

It uses the generate_keypair function to create a new private and public key.

The keys are then formatted into a JSON response, providing the user with their unique keys.

Minting an NFT

@app.route("/create_token", methods=["POST"])
def create_token():
    service, signer_public_key, signer_private_key, user_public_key = request.json['service'], adminkeys[1], adminkeys[0], request.json['user_public_key']
    utc_time = datetime.utcnow()
    utc_time_str = utc_time.isoformat()
    db = Resdb(db_root_url)
    token_data = {
        "data": {
            "start_time": utc_time_str,
            "service" : service,
        },
    }
    prepared_token_tx = db.transactions.prepare(
        operation="CREATE",
        signers=signer_public_key,
        recipients=[([user_public_key], 1)],
        asset=token_data, 
    )
    fulfilled_token_tx = db.transactions.fulfill(prepared_token_tx, private_keys=signer_private_key)
    db.transactions.send_commit(fulfilled_token_tx)
    response_data = {
        "transaction_id": fulfilled_token_tx["id"],
        "message": "Token created successfully",
    }
    return jsonify(response_data)

This POST route is crucial for creating a token that represents a particular service.

It extracts necessary data like the service name, public and private keys of the platform(Uber, Doordash, etc …) and user (contractor/driver) from the incoming JSON request.

A timestamp is added to the token data, ensuring each token is unique and time-bound (so we can determine when an induvidual is verified).

The token is then prepared and fulfilled using ResilientDB’s transaction functionalities (contacting the Crow server that ResDB is running on), securely associating the token with the user’s public key.

Upon successful creation, it returns a JSON response with the transaction ID and a success message.

Retrieving Minted NFTs

@app.route("/retrieve", methods=["POST"])
def get_nft():
    nft_data = db.transactions.retrieve(txid=key)
    if nft_data:
        return jsonify(nft_data)
    else:
        return jsonify({"error": "NFT not found"}), 404 

This POST route is designed for retrieving Non-Fungible Token (NFT) data.

It accepts a transaction ID (from the user’s wallet) and uses it to query the ResilientDB (again, the Crow server that ResDB is running on) for the corresponding NFT.

If the NFT is found, the data is returned in JSON format; otherwise, an error message is sent.

Once the entire process of minting and retrieving has been completed, the wallet is visible on the ledger page.

Echo Ledger Page

Why Choose Echo?

The choice of technologies like ResilientDB and MongoDB is rooted in their ability to offer transparency, security, and scalability. These attributes align with the dynamic needs of the gig economy, ensuring a robust and reliable verification process.

Evaluation Methodology

Echo integrates the Mxface facial recognition model, accessed via API, for identity verification. This process is central to our solution’s effectiveness in the gig economy.

The Future of Echo

Looking ahead, Echo aims to partner with leading gig delivery companies, enhancing the ledger with proprietary data. Our vision includes incorporating biometric data into the verification process for heightened security and accuracy.

Conclusions

Echo stands as a comprehensive solution to the challenges in the gig economy, offering a transparent, secure, and efficient system for identity verification. By leveraging blockchain technology and advanced facial recognition, Echo redefines trust and safety standards in this dynamic sector.

Next Steps: Expanding and Refining Echo

Our journey includes evolving the verification process and forging partnerships to broaden Echo’s impact in the gig economy. Staying at the forefront of technological innovation, we aim to refine and advance our system to meet and anticipate the evolving industry needs.

Further Resources and Demonstrations

For a deeper dive into Echo’s technical aspects, visit our GitHub repository.
View a demo of Echo’s functionality and user interface.

CrypGo, Accessibility on the Go!

Sun, 17 Dec 2023 00:00:00 +0000

CrypGo serves as a wallet for the Global-Scale Sustainable Blockchain Fabric ResilientDB. With CrypGo you can easily access your ResilientDB account, and submit and view transactions on the Go!

CrypGo Features and Screens:

Page 1: Login Page

The Login Page is a pivotal feature of CrypGo, designed to enhance user experience and security. Users can enter their login information, ensuring their public key remains constant with each login. We think this is a significant improvement over the existing Res-wallet system as it creates a key each time a user creates an ID. This static key approach simplifies the user experience by eliminating the need to track changing keys, thus reducing potential confusion and enhancing security. Our focus here is on creating an intuitive and secure login process that aligns with the best practices of user interface and experience design.

Page 2: Registration Page

The Registration Page marks the beginning of a user’s journey with CrypGo. It’s here where users set up their accounts by choosing a username and password. A unique public key is generated during registration, linked to the user’s login information. This key is crucial for user identification and transaction validation within the ResilientDB blockchain. We aim to make this process as streamlined and user-friendly as possible, ensuring that even those new to blockchain technology can easily navigate through the setup. This page is designed to be straightforward yet secure, prioritizing ease of use while maintaining rigorous data security standards.

Page 3: Dashboard

The Dashboard serves as the central hub of the CrypGo app, listing all features and functionalities. It includes user-centric buttons like “Get All Transactions” and “Set Transactions,” which lead to detailed transaction pages. The design of the Home Page emphasizes ease of navigation, allowing users to access various functionalities of the app effortlessly. The integration of these features is aimed at providing a comprehensive overview of the app’s capabilities, enhancing the user experience. Our goal is to ensure that this page is not only aesthetically pleasing but also intuitive, enabling users to utilize the app’s full potential with minimal effort.

Page 4: Get All Transactions

The ‘Get All Transactions’ page is a critical component of CrypGo, offering users a detailed view of their transaction history. This includes information on the amount, date, and time of each transaction. Users can interact with this page by selecting specific transactions for more detailed views or updating them as required. This feature is designed to provide a transparent and comprehensive record of users’ blockchain activities, enhancing their understanding and control over their digital assets. The interface is planned to be user-friendly, ensuring that even those unfamiliar with blockchain technology can easily navigate and understand their transaction history.

Page 5: Set Transactions

The ‘Set Transactions’ page allows users to initiate new transactions within the ResilientDB blockchain network. Here, users can input the transaction amount and submit it for processing. This feature is integral to the app, empowering users to engage with the blockchain actively. Our focus is on ensuring this process is intuitive, fast, and secure, catering to the needs of both seasoned blockchain users and newcomers. The page will be designed to provide clear instructions and feedback, ensuring a smooth transaction process. This includes error handling and confirmations to enhance user confidence and satisfaction with every transaction.

Page 6: Update Transactions

On the ‘Update Transactions’ page, users can modify existing transactions, a feature that adds flexibility and control over their digital assets. This process generates a new public key for the updated transaction, ensuring security and traceability. The design of this page is centered around user convenience and clarity, providing an easy-to-navigate interface for updating transaction details. It’s a testament to our commitment to offering a dynamic and adaptable platform that responds to the evolving needs of our users. By allowing transaction updates, we ensure that CrypGo remains a versatile and user-centric tool in the rapidly changing landscape of digital transactions.

Page 7: Get Transactions

The ‘Get Transactions’ page is dedicated to providing detailed information on individual transactions. Users can view key details such as Transaction ID, Amount, and Time created. This functionality is crucial for users who need to closely monitor and analyze specific transactions for various purposes, including auditing, reporting, or simply keeping track of their digital asset movements. The design of this page focuses on clarity and ease of access, presenting information in a user-friendly format. By offering a granular view of transactions, CrypGo empowers users with the information they need to make informed decisions regarding their digital assets.

Results:

How does CrypGo work?

CrypGo is directly connected to the Python SDK which is connected to the Crow HTTPS server which communicates with ResilientDB. Our Application runs similar to how ResVault works.

Running the Application

Installing and Setting Up the Expo Go App

Install the Expo Go App from the App Store. Expo Go is an application for iOS and Android that allows developers to quickly preview and test React Native apps on mobile devices during development. It connects with the Expo CLI to load up projects instantly, streamlining the development process by enabling live coding and debugging directly on a smartphone or tablet.

Running the App - CrypGo

Installing and Setting Up Xcode

Navigate and Download Xcode on the App Store on your iOS laptop devices.
Download the required packages for your designated mobile and laptop.

Creating a New ReactNative Project

Fork from our repository and then run the following command on an IDE:
```
npm install
```
The command used in the Node.js environment to install packages from the Node Package Manager (npm) registry. It reads the package.json file in the current directory to automatically install all the dependencies listed there, allowing developers to easily manage and share packages across different projects.
Navigate to the Frontend file using this command:
```
cd Frontend/
```

Running the Expo Simulator App

Simply type this command:
```
npx expo start
```
Since we are an iOS app, select “i”:
```
i
```
You are now all set to use the CrypGo App. With the CrypGo App now installed, you’re ready to embark on a seamless cryptocurrency tracking experience.

Conclusion

In conclusion, CrypGo presents a user-friendly gateway to ResilientDB, revolutionizing the management of user transactions at the tip of their fingers. With seamless account creation and secure login procedures, CrypGo empowers users to engage effortlessly with ResilientDB. Detailed transaction logging keeps everything transparent, helping users easily monitor their accounts. This mobile app marks a significant step towards accessibility, security, and convenience addition to the ResilientDB network. Looking forward, CrypGo aims to further enhance user experience, through the addition of a settings screen, and metadata to the SDK.

Future Work

Add more functions to check balance and view received transactions.
Adding metadata to each transaction such as time, date and name of transactions.
Adding user customisation to the mobile app such as the Settings page, and theme changes and making it more user-friendly
Improving the design implementations of the mobile application
Making a web application for CrypGo !!

Arrayán - A Resilient Blockchain-based Food Supply Chain

Wed, 13 Dec 2023 00:00:00 +0000

Arrayán is a revolutionary web application seamlessly integrated with the ResilientDB blockchain fabric, empowering industries to achieve end-to-end transparency in tracking products, by-products, and their historical journey across the supply chain. Tailored especially for the food sector, Arrayán offers an intuitive platform to visualize the lifecycle of goods from farm to retail, fostering accountability and trust at every stage.

Beyond traditional tracking, Arrayán redefines traceability as a driver of sustainability. The platform introduces a forward-thinking mechanism to reclaim and repurpose food by-products—such as stems, peels, and seeds—by securely documenting their origin, usage intent, and transfer timelines on the blockchain. This verifiable, tamper-proof data unlocks opportunities to scale the reuse of by-products as raw materials in sectors like cosmetics and clean energy production.

With seamless blockchain-backed agreements and instant access to tracking data through lightweight tools, Arrayán ensures a frictionless experience for producers, buyers, and consumers alike. It transforms traceability into a dynamic ecosystem for innovation, collaboration, and resource optimization—all while championing a more transparent and circular economy.

Figure 1. Picture describing Arrayán

Useful Links

Website is live at https://arrayan.resilientdb.com/
Code Repository - https://github.com/ResilientApp/Arrayan
Presentation Slides - https://github.com/apache/incubator-resilientdb-blog/blob/main/presentations/Arrayan.pdf
We have modified the existing ResilientDB-GraphQL APIs catering to the needs of a blockchain-based food supply chain and added a new API to fetch the products in the forked repo.

Problem Identified

Scientific evidence supports the potential of food by-products as valuable sources of molecules for the cosmetic industry. However, their utilization has been limited as the chemical composition and yield variability are influenced by factors such as variety, environmental conditions, and the methods of cultivation and processing. Currently, there is a lack of comprehensive traceability for most by-products, hindering the recording of crucial data. This absence of information results in a lack of standardization, contributing to uncertain yields and increased costs associated with the extraction and purification processes. A parallel challenge is observed in the use of by-products for hydrogen production and other upcycling applications.

Solution

This web application plays a pivotal role in meticulously tracing the generation of by-products at each stage. This granular information is instrumental in standardizing by-products, facilitating their upcycling on a larger scale, and pinpointing key areas where substantial amounts of by-products are produced. Our traceability-for-sustainability model not only offers a blueprint for companies to embrace circular economy models but also ensures compliance with regulations such as the Food Safety Modernization Act. The primary objective of the Food Safety Modernization Act is to enhance food safety. In the event of a foodborne incident, rapid tracking within 24 hours is mandated. The regulation emphasizes the necessity for companies to share information seamlessly across their supply chain, and blockchain emerges as a powerful tool to streamline this process. Arrayán stands as more than just a tracing tool; it is a catalyst for the food industry to not only meet regulatory requirements but also to potentially increase profitability from their by-products and reduce its environmental footprint. During the development of the application, we established a partnership with the teaching and research winery of UC Davis. To kick-start our journey, we are delivering a Proof of Concept utilizing the data generously provided by our collaborators.

Note: Arrayán also aligns with Senate Bill 1883, offering a pathway to compliance with this additional regulation.

Technology Stack

Web Application: Built using React JS, Create React App, React Official Website
Backend: ResilientDb GraphQL server, Python
Database: Powered by ResilientDB
Theme: BLK Design System React, BLK Design System Pro React

Architecture

The sequence diagrams of the inventory manager, product tracker, smart Contract and chrome extension below give an overview of the function triggers and the process of upload/claim.

Inventory Manager

Figure 2. Sequence Diagram of Inventory Manager

Product Tracker

Figure 3. Sequence Diagram of Product Tracker and Claim Workflow

Smart Contract

Figure 4. Sequence Diagram of Smart Contract

Tracker Chrome Extension

Figure 5. Sequence Diagram of Tracker Chrome Extension

Upon breaking the overall architecture, the user is authenticated and will be provided with a dashboard, current inventory, and product tracker.

Dashboard fetches data from the Google Firestore and displays the real-time data in sync with the ResilientDb.
After uploading the inventory from an Excel file or providing the manual input, transactions are constructed to the Schema required for the GraphQL server of ResilientDb, and POST_TRANSACTION mutation is used to save the data to the ResilientDb. Upon a successful response, transaction IDs are stored in the Google Firestore. Only transaction IDs and metadata are saved outside the ResilientDb, ensuring data transparency on the global-scale blockchain fabric — ResilientDb.
When a user searches for a product, the relevant transaction IDs are retrieved from Google Firestore, and point queries are made to ResilientDb. The complete food supply chain is displayed, detailing each stage. The system also allows users to claim byproducts generated during the process. Claimed byproducts are recorded as transactions on ResilientDb, with their transaction IDs securely stored in Google Firestore.

Figure 6. High level design of Arrayan

Features and User Guide

Home Page

Provides a general overview of the solution offered through the website.

Figure 7. Home Page

Getting Started: To access the portal’s features, users first need to register and log in. Once logged in, they can unlock functionalities such as inventory management and search capabilities.

Figure 8. Login Page

Live Inventory Visualization: The dashboard provides an instant, real-time representation of the current status of the inventory, ensuring up-to-the-moment insights.

Figure 9. Dashboard

Inventory

Seamless Upload Process: Allows consumers to easily upload Excel files containing inventory data. Multiple Excel files can be uploaded and loaded consecutively.

Figure 10. Upload Page

Inventory View: Shows a clear and accessible display of updated inventory information visible to consumers.

Figure 11. Inventory

Search

Search Option: Enables users to search and track any final product through the food supply chain.

Figure 12. Track your products and by-products

Visualizes Supply Chain: Provides a comprehensive supply chain mapping of each product’s entire supply chain and process details.

Figure 13. Visualize your product through the supply chain

Claiming By-Products: Consumers can easily claim by-products in the process, fostering a circular economy. This feature empowers consumers to actively participate in sustainable practices.

Figure 14. Claim by-products

Smart Contract

Smart Contract Page: Allows users to create a contract for a time period to automatically claim the byproduct of a particular product from a particular source. This avoids redundant visits to the website and makes the process automatic.

Figure 15. Smart Contract Page for Arrayán

View My Contracts: Allows the user to track their existing contracts which are valid.

Figure 16. View current contracts

Auto-Claim: On the search page, the user can easily view the available by-products to claim and also see if any by-product is already auto-claimed under the contract.

Figure 17. Auto-claimed by-products based on signed Contracts

Tracker Chrome Extension

Chrome Extension: Allows users to check the transparency of the system by getting the information from the blockchain based database, ResilientDB transaction id.

Figure 18. Popup UI of Arrayan chrome Extension

Figure 19. View of Report card based on Transaction ID provided

Demo Video<div class="extensions extensions--video">

</div>

Steps to run the system

Download NodeJS from here and ensure that it’s added to PATH.

Clone the repo of arrayan to get started:

git clone https://github.com/ResilientApp/Arrayan.git

Then navigate inside the ResVault directory:

cd arrayan

Install the dependencies:

npm install

Start the project:

npm start

Build the project:

npm run build

The above code uses online instance of Resilient DB and the application is ready to be launched. For further exploration, below steps can be followed to setup and play around with local instance.

Setup Python3.10

Ensure you have Python3.10, otherwise download it and set it up as default.

Setup ResilientDB

You will need to clone the ResilientDB repo to get started:

git clone https://github.com/resilientdb/resilientdb.git

Then navigate inside the ResilientDB directory:

cd resilientdb

Install dependencies:

sh INSTALL.sh

Run ResilientDB KV Service (this may take a few minutes for the first time):

./service/tools/kv/server_tools/start_kv_service.sh

Setup Crow HTTP server, SDK, and GraphQL server

You will need to clone the ResilientDB GraphQL repo to get started:

git clone https://github.com/Amoolya-Reddy/ResilientDB-GraphQL

Then navigate inside the ResilientDBGraphQL directory:

cd ResilientDB-GraphQL

Install the Crow dependencies:

sudo apt update sudo apt install build-essential sudo apt install python3.10-dev sudo apt install apt-transport-https curl gnupg

Build Crow HTTP server (this may take a few minutes for the first time):

bazel build service/http_server:crow_service_main

Start the Crow HTTP server:

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/service.config service/http_server/server_config.config

Create virtual environment for the Python SDK:

python3 -m venv venv –without-pip

Activate the virtual environment:

source venv/bin/activate

Install pip in the virtual environment for the Python dependencies:

curl https://bootstrap.pypa.io/get-pip.py | python

Install the Python dependencies:

pip install -r requirements.txt

Start the GraphQL server:

python3 app.py

Setup cited from ResVault

Contributions:

Amoolya Gali: Designed the overall architecture of the application, translating requirements into technical functionalities. Led the development of the frontend, including UI/UX design and animations, and implemented the Ag-GraphQL wrapper to interface with the existing ResilientDB-GraphQL server, setting up all necessary APIs. Built the real-time dashboard, implemented Excel file parsing for constructing transactions, and managed interactions with Google Firestore by developing all Firestore APIs. Delivered an intuitive food supply chain tracking system and completed the end-to-end claim workflow.
Mariana Larrañaga: Defined the project scope and high-level requirements as the founder of Arrayan. Conducted market research, pitched the product, and maintained active interactions with wineries and farmers, incorporating their input into the product. Served as the product manager, ensuring user needs were integrated into the development process and shaping the overall vision of Arrayan.
Other Contributors: Shravani Shete, Manali Modi, Tarun Tiwari, Srishti Singh

ResilientDB Blockchain Analyzer

Tue, 12 Dec 2023 00:00:00 +0000

What is the ResilientDB Blockchain Analyzer?

The ResilientDB Blockchain Analyzer offers a comprehensive visualization tool for transactions on the ResilientDB blockchain, similarly to Etherscan’s role for Ethereum. The two main features that the program offers are displaying all wallets connected to the ResilientDB blockchain, along with their respective transaction histories and offering a chronological visual representation of transactions, enabling easy tracking of transaction volume over time. It can also be used to help track the movement of illegally obtained funds or just to help see what transactions have been made on the blockchain. Currently the analyzer is already running live on the main instance of ResilientDB and can be viewed here.

Interfacing with ResilientDB

When the website is first accessed it will read the response from https://crow.resilientdb.com/v1/transactions and then save all of the transactions made on the blockchain as a single json file. The ResilientDB blockchain visualizer then displays transactions in the form of a tree. At the top of the tree will be a single node containing the original wallet ID and then below that will be nodes displaying all of the transactions made by that specific wallet ID. If you click on any of those transactions you can see all the subsequent transactions made by the recipient of the selected transaction. If no subsequent transaction had been made then the transaction will not show up as being clicked.

Data Collection

Data collection for homepage

If you run the python backend for the blockchain, then each time the webpage is accessed the flask script will download the blockchain’s json data and will store it under

./Finecharts/js/settings/transactions.json

This python backend and json file is necessary to make the graph on the homepage of the website display up to date data.

Data collection for tree.html

For tree.html the data is collected when the javascript code (tree.js) runs. This means that the data will be updated every time the page refreshed.

Viewing the Data

There are two graphs to display the data from the json file:

First we have a simple line griph that displays the transactions made within the last year with the month on the x-axis and the amount of transactions on the y-axis.

Figure 1. Image of the Transactions Graph.

The second way is the tree that was described above. You can track the transaction history coming from a single user’s wallet ID and follow the subsequent transactions.

Figure 2. Image of the Tree of Transactions.

Demo Video

Running the Application

Prerequisites

Before running the ResilientDB Blockchain Analyzer website, you need to start kv service on the ResDB backend and the sdk. We chose to run this on Google Cloud but any cloud service will work. You also must ensure that the way your data is stored in the json follows this format:

{
    "id": "Transaction id",
    "version": version,
    "inputs": [
        0: {
            "owners_before": [
                0: "ID of Sender Wallet"
            ]
        }
    ]
    "outputs": [
        0: {
            "public_keys": [
                0: "ID of Reciever Waller"
            ]
            "amount": "Transaction Amount"
        }
    ]
    "operation": operation,
    "asset": {
        "data": {
            "timestamp": "Timestamp in epoch time"
        }
    }
}

If your json structure does not follow this format go to Setting up the website frontend

Setting up the python backend

First you need to install apache2 using:

sudo apt install apache2

You will also need to install gunicorn using:

sudo pip install gunicorn

Then navigate to where your index.html folder is located, for google cloud it is under:

/var/www/http/

And delete index.html if present (we will replace this with the new home page).
Git Clone the ResDB-Chain-Analyzer Repository into this folder:

sudo git clone https://github.com/Richard-Voragen/ResDB-Chain-Analyzer/tree/main/ResDB-Chain-Analyzer

Next we need to ensure that the proper url’s are set to retrieve the json data from:

Inside of the App.py file modify the fields.

IP_ADDRESS_TO_TRANSACTIONS = 'URL that contains json of transactions'
IP_ADDRESS_TO_HOSTING_SITE = 'URL/Domain Name of hosting site'

Finally we need to run the flask script that will update transactions.json when a user visits the website:

Run this command from /var/www/http/ResDB-Chain-Analyzer:

sudo gunicorn -w 4 -b 0.0.0.0 app:app

If any changes need to be made by the user to the app.py file then you must first end the gunicorn task with:

sudo pkill gunicorn

Setting up the website frontend

Within the directory /var/www/http/ResDB-Chain-Analyzer/js/tree.js change to field at the top from:

"https://crow.resilientdb.com/v1/transactions" to the URL that contains json of transactions

Changing the default json formatting

First open the Javascript file located at: Install GraphQL:

/js/jsonFormat.js

Then modify the field to return their desired outputs: Install GraphQL:

get_id(jsonObj) : return the id of the transaction
get_sender(jsonObj) : return the sender of the transaction
get_recipient(jsonObj) : return the recipient of the transaction
get_amount(jsonObj) : return the quantity of the transaction
get_time(jsonObj) : return the time of the transaction

Source Code Repositories:

https://github.com/Richard-Voragen/ResDB-Chain-Analyzer
https://github.com/ResilientApp/ResilientDB-GraphQL

Contributions:

Voragen: Designed chronological tree visualization of tree data and javascript background. Created main code for parsing and handling of the chain transaction history on the JSON file.
Fennen: Designed front end of webpage, created monthly graph on front page of website, and handled JSON parsing for data displayed on the monthly graph.
Allyn: Set up backend infrastructure and handled initial chain interactions.

Getting Started with Rust SDK

Sun, 10 Dec 2023 00:00:00 +0000

We provide a Rust SDK for committing transactions to create and transfer assets. Despite NexRes being written in C++, users can interface with ResilientDB through Rust. This article assumes you have setup a ResilientDB instance that is accessible through HTTP requests and are familiar with Rust, we will walk you through basics of using ResilientDB in your first Rust project.

Prerequisites

Install Rust and Cargo

The easiest way to get Cargo is to install the current stable release of Rust by using rustup. Installing Rust using rustup will also install cargo. On Linux and macOS systems, this is done as follows:

curl https://sh.rustup.rs -sSf | sh

It will download a script, and start the installation. If everything goes well, you’ll see this appear:

Rust is installed now. Great!

On Windows, download and run rustup-init.exe. It will start the installation in a console and present the above message on success.

After this, you can use the rustup command to also install beta or nightly channels for Rust and Cargo.

You can find more informatin on rust on The Cargo Book.

Starting a new Rust Project and installing the SDK

You can start a new rust project through cargo with the following command:

cargo new resilientDB_test

You should now see a new folder generated named resilientDB_test.

$ cd resilientDB_test
$ tree .
.
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

You can get started with the Rust SDK in one of two ways:

You can simply run the following command:
```
cargo add resilientdb_rust_sdk
```
You can also add the following line to your Cargo.toml
```
resilientdb_rust_sdk = "0.1.1"
```

It’s that easy! You are now good to go with our SDK. Make sure you have a ResilientDB instance setup, for more info on that follow this blog. This tutorial also makes a graphql query to resdb, if you don’t have graphql setup take a look at this other blog.

Dependencies

You may need to install the following dependencies as our library has future return types, meaning some returns from our APIs would need to be unwrapped within an async function.

This is by design as we encourage users to handle errors on their end as many of the calls are made asynchrounously. Following good error handling practices would be beneficial to developing a secure application with ResilientDB. You can run obtain the dependencies through:

Running the following command

cargo add tokio serde serde_json reqwest

Adding this to your Cargo.toml file:

 tokio = { version = "1", features = ["full"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 reqwest = {version = "0.11.22", features = ["blocking", "json"]}

Developement

Import the SDK

Let’s build a sample program that makes a transactions and then fetches transactions to and from your ResilientDB instance. In your main.rs file import the SDK like so:

use resilientdb_rust_sdk::ResDB;

Initializing a ResDB object

Our first step to using the functions within the SDK is to create a ResDB object in main like so:

fn main() {
    let res_db = ResDB::new();

}

Creating Keypairs

Generating public/private keypairs is as easy as calling the generate_kepair() function provided in the crypto module of our sdk. The Key pair generation is done using the Ed25519 algorithm. Here’s how you would use this API:

let keypair = res_db.generate_keypair();
println!("Public Key: {:?}", keypair.0);
println!("Private Key: {:?}", keypair.1);

Transaction API - Committing

Currently the SDK support transaction commits through the graphql format. In our case, we will use the public and private key pairs that we generated using generate_keypair() function above. In the future we plan to add support for Struct and Hash map based transaction commits. Here’s how you would commit a transaction.

let data = format!("""r#"
"query": "mutation { postTransaction(data: \"\nsignerPrivateKey: \"\"\nrecipientPublicKey: \"ECJksQuF9UWi3DPCYvQqJPjF6BqSbXrnDiXUjdiVvkyH\"\nasset: \"\"\",\n          }}\"\"\"\n      }}) \n}}\n"
}}
"#""", keypair.0, keypair.1);


let endpoint = "http://YouResDBInstance.com";
match res_db.post_transaction_string(&data, endpoint).await {
    Ok(body) => println!("{}", body),
    Err(err) => eprintln!("Error: {}", err),
}

Transaction API - Fetching

We can fetch the transaction we just posted either using a struct to guide are JSON schema or a untyped Hash map. You would need to define a struct like so to pass into the get_all_transactions() functions:

use serde::Deserialize;
/** User Defined Struct for transaction endpoints **/ 

#[derive(Debug, serde::Deserialize)]
pub struct Transaction {
    pub inputs: Vec<Input>,
    pub outputs: Vec<Output>,
    pub operation: String,
    pub metadata: Option<serde_json::Value>,
    pub asset: Asset,
    pub version: String,
    pub id: String,
}

impl Default for Transaction {
    fn default() -> Self {
        Transaction {
            inputs: Vec::new(),
            outputs: Vec::new(),
            operation: String::new(),
            metadata: None,
            asset: Asset::default(),
            version: String::new(),
            id: String::new(),
        }
    }
}

#[derive(Debug, serde::Deserialize)]
pub struct Input {
    pub owners_before: Vec<String>,
    pub fulfills: Option<serde_json::Value>,
    pub fulfillment: String,
}

impl Default for Input {
    fn default() -> Self {
        Input {
            owners_before: Vec::new(),
            fulfills: None,
            fulfillment: String::new(),
        }
    }
}

#[derive(Debug, serde::Deserialize)]
pub struct Output {
    pub public_keys: Vec<String>,
    pub condition: Condition,
    pub amount: String,
}

impl Default for Output {
    fn default() -> Self {
        Output {
            public_keys: Vec::new(),
            condition: Condition::default(),
            amount: String::new(),
        }
    }
}

#[derive(Debug, serde::Deserialize)]
pub struct Condition {
    pub details: ConditionDetails,
    pub uri: String,
}

impl Default for Condition {
    fn default() -> Self {
        Condition {
            details: ConditionDetails::default(),
            uri: String::new(),
        }
    }
}

#[derive(Debug, serde::Deserialize)]
pub struct ConditionDetails {
    #[serde(rename = "type")]
    pub condition_type: String,
    pub public_key: String,
}

impl Default for ConditionDetails {
    fn default() -> Self {
        ConditionDetails {
            condition_type: String::new(),
            public_key: String::new(),
        }
    }
}

#[derive(Debug, serde::Deserialize)]
pub struct Asset {
    pub data: serde_json::Value,
}

impl Default for Asset {
    fn default() -> Self {
        Asset {
            data: serde_json::Value::Null,
        }
    }
}

Now that we have defined the JSON through structs, we can pass them to the get_all_transactions() function, along with that it will take our endpoint URL - this will be the local or remote URL to your ResilientDB instance.

async fn fetch_transactions(res_db: &ResDB) {
match res_db.get_all_transactions::<Transaction>("http://YouResDBInstance.com").await {
    Ok(transactions) => {
        for transaction in transactions {
            // Access and process each transaction
            println!("{:?}", transaction);
        }
    }
    Err(error) => {
        // Handle the error
        eprintln!("Error fetching transactions: {}", error);
    }
}
}

The struct defined may seem verbose, this is by design as we want to ensure that users are building type safe and fault tolerant applications using ResilientDB. While the struct defines the JSON schema it also comes with impl that constructors for the stucts. For those who want to interface with ResilientDB in an unstructured manner we also provide the Hash map varient of the same function.

    let data_map = HashMap::new();
    let res_db = ResDB::new();
    
    match res_db.get_all_transactions_map(
        "http://YouResDBInstance.com",
        data_map,
    )
    .await
    {
        Ok(map) => {
            // Access fields of the transaction (replace with the desired field)
            println!("{:?}", map[10]);
        }
        Err(error) => {
            // Handle the error
            eprintln!("Error: {}", error);
        }
    }

All the retrival functions provided by the SDK come in both Struct and Hash Map varients to provide the you with the choice between safety, type strictness and flexibility.

Blocks API

Similarly, the SDK offers APIs for interacting with blocks. You can fetch blocks by range, group them, or retrieve all blocks from a specified API endpoint. Below is an example of fetching all blocks:

let res_db = ResDB::new();
let data_map = HashMap::new();

// Call the asynchronous function to get blocks
match res_db
    .get_all_blocks_map("http://YouResDBInstance.com", data_map)
    .await
{
    Ok(blocks) => {
        if let Some(first_block) = blocks.first() {
            // Access fields of the first transaction (replace with the desired field)
            println!("{:?}", first_block);
        } else {
            println!("No transactions available");
        }
    }
    Err(error) => {
        // Handle the error
        eprintln!("Error: {}", error);
    }
}

Crypto operations

Our Crypto API also provides a convinient function to hash strings. Here is how you would use the function:

let data = "Hello, ResilientDB!";
let hashed_data = res_db.hash_data(data);
println!("Hashed Data: {}", hashed_data);

Conclusion

This guide provides a glimpse into the powerful features our ResilientDB Rust SDK offers for seamless integration into your Rust projects. Explore the full potential of ResilientDB, experiment with different APIs, and leverage the SDK’s capabilities to build robust and secure applications.

For more in-depth information and advanced features, refer to the official ResilientDB Rust SDK documentation.

Happy coding with ResilientDB and Rust!

ResView- Visualizing Resilient DB

Wed, 06 Dec 2023 00:00:00 +0000

What is ResView?

ResView is a tool for visualizing the PBFT process in Resilient DB. ResView is built on top of Resilient DB and gathers statistics from transactions to display in graphical form. ResView works on all transactions performed with local instances of Resilient DB, whether sent from ResView, another application, or in the ResilientDB terminal. Our goal for ResView is to enable greater understanding of the ResilientDB backend by people who want to learn more about how the PBFT consensus protocol works and the general flow of blockchain consensus, as well as developers who want to observe the status of ResilientDB and test their own applications/changes on the ResilientDB framework.

Below is a diagram showing the workflow of ResView and the high-level structure:

Figure 1. Diagram displaying the structure of ResView and how data is passed between the different services.

The diagram can be broken down as follows. An application sends a transaction to the GraphQL server, which parses the request and transforms it into a usable Request for ResilientDB. The GraphQL server then forwards this request to the ResilientDB instance, which performs the consensus protocol on the request then executes the request contents. During the process of inter-replica communication, data about the consensus protocol is collected. Once the transaction is completed, the ResilientDB service sends the consensus data along a websocket connected to ResView, which then collects and stores this data. Once ResView acquires the consensus data, ResView transforms and leverages it to create various diagrams which show what happened in the consensus process to the user.

Interfacing with ResilientDB

ResView offers both ways to interact with the ResilientDB architecture, as well as ways to visualize what is occurring in ResilientDB. Users are able to interact with ResilientDB through the application using the transaction forms and “make a replica faulty” buttons. Within the transaction forms, users input the data fields for the transaction they wish to send and press either set or get. Once this transaction is confirmed, it is sent via Axios to the sdk, which verifies the transaction and forwards it to the ReslientDB backend, where it is then processed and executed.

Figure 2. Image of the Transaction Form.

For the faulty buttons, when these are pressed, they send a signal to the corresponding the replica informing it to reject any transactions it receives, simulating a replica unable to receive messages. Before this addition, there was no method of forcing a replica to be faulty, making this a valuable addition for testing various cases and potential situations ResilientDB could face.

Data Collection

ResView collects the data for visualization directly from the ResilientDB application, as while transactions are being ran, a statistics data structure collects the contents of the transaction, timestamps of when each state was reached, and timestamps of when messages were received. These statistics are then grouped as a JSON, which is then sent out to the front end application. The reason the data is collected this way is to enable ResView to produce visualizations even without access to log files, as well as gather information regardless of who initiated the transaction.

Viewing the Data

On the application, users are able to select which transaction’s data they want to see diagrams of, as all data is stored as a history while the application is running. Once a transaction is selected, there are 3 viewable graphs: PBFT diagram, prepare messages vs time, and commit messages vs time. In order to select a transaction, it can be chosen from the list of performed transactions in the transaction table.

Figure 3. Transaction Table.

The PBFT diagram is dynamically constructed using the data collected from the replicas. The main data points utilized are the primary id, which signifies in the diagram where the client should send its request to, the timestamps of each state, as they identify that the replica reached that state and how long it took, and the existence of each replica’s data, as faulty replicas do not send their data to the front end. This allows the PBFT diagram to work with real time data and accurately convey the state of ResilientDB to the user, as well as the flow of the consensus protocol.

Figure 4. PBFT Diagram.

Both the prepare message vs time and commit message vs time graphs use a line graph containing a line of each replica’s message collection. The timestamps start from when a replica is first able to start sending messages, which the message collection times are relative to. The purpose of displaying lines from each replica is to easily compare the rates at which replicas collected messages to understand the relationship between them, as well as identify any potential issues with message collection. In order to focus on specific replicas, the user is also able to toggle the lines of any replica which reduces the amount of data of the graph being displayed.

Figure 5. Commit Message Graph.

The status of each of the replicas is also visible on the side of the application, showing which replicas are non-faulty and which are either faulty or unavailable. Previously, in order to tell which replicas were down, users had to go into the log file and see which replicas were not being updated actively or processing requests, but now users can easily see which replicas are available while sending transactions.

Figure 6. Replica Availability Status.

Demo Video

Running the Application

Prerequisites

Before running the ResView application, you need to start kv service on the ResDB backend and the sdk.

resilientdb

Git clone the ResView backend repository and follow the instructions to set it up:

git clone https://github.com/apache/incubator-resilientdb

Setup KV Service:

./service/tools/kv/server_tools/start_kv_service.sh

sdk

Git clone the GraphQL Repository and follow the instructions on the ReadMe to set it up:

Install GraphQL:

git clone https://github.com/ResilientApp/ResilientDB-GraphQL

Setup SDK:

bazel build service/http_server:crow_service_main

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

With these 2 services running, the ResView front end can now send transactions to the ResDB framework

Running the ResView Application

Clone the repo and open in a new folder.

npm install

Run the below code to start the app and load the script.

npm start

Using the ResView Application

Once ResView has been started, go to http://localhost:3000/pages/visualizer or https://resview.resilientdb.com/

Load KV_Service on resilient db once on the visualizer page, the web sockets should connect and log the “OPEN” message into the console 4 times.

Once on the visualizer page, send a transaction using the transaction form. Once the transaction’s data has been sent back, click on the various graphs to view the transaction data in a more comprehensive way. In order to select previous transactions, go to the transaction table and choose the specific transaction. In order to test different edge cases, set various replicas to faulty or not faulty and observe how the messages are now sent between replicas.

Future Work

Set up ResView on Cloud Instance to retrieve far more transaction data

Source Code Repositories:

https://github.com/ResilientApp/ResView
https://github.com/apache/incubator-resilientdb
https://github.com/ResilientApp/ResilientDB-GraphQL

Slides:

https://www.canva.com/design/DAGSGOyLh8g/pEC_FJgR6B_7RldsQBMrKQ/edit?utm_content=DAGSGOyLh8g&utm_campaign=designshare&utm_medium=link2&utm_source=sharebutton

Contributions:

Saipranav: Designed project architecture and workflow, feature ideas, coded the backend data collection, faulty replica toggles, configured all websockets, wrote JSON data parsing code, created Message vs Time graphs and line toggles, created sample transactions, setup all APIs, and added transaction sending and sdk incorporation.
Aunsh: Designed the front end UI/UX and architecture, skeleton, contexts, and pages, developed main PBFT diagram, setup graph component skeletons and general styling, look and functionality of the entire application. Also worked on adding tables, the home page, and seamless transition to viewing earlier transactions.

Deploying ResilientDB

Wed, 22 Nov 2023 00:00:00 +0000

This tutorial assumes that you have setup ResilientDB by following this blog. In order to get started with deploying ResilientDB and the extended applications on cloud you will need to follow the steps below.

Prerequisites

Create a Cloud instance

You can create a cloud instance on either AWS (EC2), GCP (Compute Engine), or choose any other Virtual Private Server (VPS). Ensure that you select the image as Ubuntu 22.04.

Setup ResilientDB and other repositories

Clone and Install the dependencies for ResilientDB, CROW HTTP Server, and GraphQL by following this [blog]((https://blog.resilientdb.com/2023/09/21/ResVault.html).

Purchase a domain and setup Cloudflare DNS

Go to Namecheap and purchase a domain. Then, once you have registered a domain click on Manage option and under DNS select custom DNS.
Then go to Cloudflare and create an account. Then, proceed to add the domain that you just registered. Add the two nameservers given by Cloudflare in the Namecheap Custom DNS. (This change might take a while to reflect)
Now, navigate to the DNS management page on the Cloudflare Dashboard and create the following five subdomain records:
- An A record with name crow and IPv4 address as the external IP of your cloud instance.
- An A record with name cloud and IPv4 address as the external IP of your cloud instance.
- An A record with name explorer and IPv4 address as the external IP of your cloud instance.
- An A record with name prometheus and IPv4 address as the external IP of your cloud instance.
- An A record with name monitoring and IPv4 address as the external IP of your cloud instance.

Setup Nginx

SSH into your cloud instance and install Nginx with the following command:

sudo apt update

sudo apt upgrade

sudo apt install nginx
Then, start and enable Nginx as a service:

sudo systemctl start nginx

sudo systemctl enable nginx
The next step is to create a configuration file, we are going to name it conf but you can name it whatever you want:

sudo nano /etc/nginx/sites-available/conf
Then, copy and paste the following configuration inside the file, make sure to edit yourdomain.com with your domain:

For the Flask app
server {
   listen 80;
   server_name cloud.yourdomain.com;

   location / {
       proxy_pass http://127.0.0.1:8000;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }
}

# For the Vite app
server {
   listen 80;
   server_name explorer.yourdomain.com;

   location / {
       proxy_pass http://127.0.0.1:8080;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }

   location /block {
       proxy_pass http://127.0.0.1:8080/;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }

   location /transactions {
       proxy_pass http://127.0.0.1:8080/;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }

   location /api/ {
       proxy_pass http://localhost:18000/;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection 'upgrade';
       proxy_set_header Host $host;
       proxy_cache_bypass $http_upgrade;
       proxy_redirect off;
   }
}

# For the CROW HTTP server
server {
    listen 80;
    server_name crow.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:18000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # CORS headers
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Origin, X-Requested-With, Content-Type, Accept' always;
    }
   location /blockupdatelistener {
        # Set up the proxy pass to your WebSocket server
        proxy_pass http://127.0.0.1:18000;

        # Upgrade headers for WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Set WebSocket specific headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # CORS headers
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Origin, X-Requested-With, Content-Type, Accept' always;

        # Handle WebSocket specific "OPTIONS" request
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' '*';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'Origin, X-Requested-With, Content-Type, Accept';
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain charset=UTF-8';
            add_header 'Content-Length' 0;
            return 204;
        }
    }
}

# For Prometheus
server {
   listen 80;
   server_name prometheus.yourdomain.com;

   location / {
       proxy_pass http://127.0.0.1:9090;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
   }

   access_log /var/log/nginx/prometheus.access.log;
   error_log /var/log/nginx/prometheus.error.log;
}

# For Grafana
# this is required to proxy Grafana Live WebSocket connections.
map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
}

upstream grafana {
 server localhost:3000;
}

server {
  listen 80;
  server_name monitoring.yourdomain.com;

  location / {
    proxy_set_header Host $http_host;
    proxy_pass http://grafana;
  }

# Proxy Grafana Live WebSocket connections.
  location /api/live/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $http_host;
    proxy_pass http://grafana;
  }
}

Save the configuration file by pressing ctrl+o and then exit the editor.
Enable the site configuration by running the following command:

sudo ln -s /etc/nginx/sites-available/conf /etc/nginx/sites-enabled/
Check for syntax errors using the command below:

sudo nginx -t
If everything is fine then restart Nginx to view the changes:

sudo systemctl restart nginx

Now, you can navigate to the different subdomains via your web browser and view the different services.

Using Docker Compose for ResilientDB and Python SDK

Utilize Docker images from the Docker Hub registry to effortlessly create instances of ResDB and the Python SDK.

Below is the docker-compose.yaml file. Switch amd64 to arm64 if you are on an Mac Silicon system.

version: "3"

services:

  resilientdb:
    image: expolab/resdb:amd64
    ports:
      - "10005:10005"

  sdk:
    image: expolab/sdk:amd64
    depends_on:
      - resilientdb

Execute the following command to launch ResilientDB and the SDK:

> docker-compose up

Once the command completes, access the SDK container and modify the URL within the test_driver.py file to connect to the created ResDB server.

Accessing the SDK container:

Use the following commands to identify the container ID and access the SDK container:

> docker ps -a

CONTAINER ID   IMAGE                 COMMAND             CREATED      STATUS                             PORTS                      NAMES
2a9251b89b6c   expolab/sdk:arm64     "./entrypoint.sh"   7 days ago   Up 23 seconds (health: starting)   18000/tcp                  sdk-sdk-1
e6ffad8d591c   expolab/resdb:arm64   "./entrypoint.sh"   8 days ago   Up 23 seconds                      0.0.0.0:10005->10005/tcp   sdk-resilientdb-1

> docker exec -it 2a9251b89b6c bash

Edit test_driver.py and replace db_root_url from http://127.0.0.1:18000 to http://resilientdb:10005:

> sed -i 's/db_root_url = "http:\/\/127.0.0.1:18000"/db_root_url = "http:\/\/resilientdb:10005"/' test_driver.py

This ensures that the SDK communicates correctly with the ResilientDB server.

Logging in ResilientDB

Sat, 18 Nov 2023 00:00:00 +0000

Overview

Logging is used to help ResilientDB to recover its local state after restarting. The state can be the one before it is shut down or the state from other replicas. When ResilientDB receives a request related to the consensus logic, it will be written to a log file by appending to the tail to guarantee written order. Requests in the log file will be the same as the requests received from the network. If the system uses multi-threads to process the requests, the written order is random but it guarantees that requests will be persistent to the disk before processing. Thus, if a system restarts and redo all the requests from the log file, it will produce the same state.

Storage Restriction

Since ResilientDB will redo the requests from the log, the storage needs to handle repeated requests. At least, it can go to the same state if producing the same operations from some points. For example, for the raw key-value service which provides only Get and Set interfaces. No matter from which point to redo the requests, as long as it is the logging point before its last update, it will reach the same state since all the Set requests will overwrite the previous records and only the last set will be kept.

Checkpoint Files

To reduce the size of the log file, it will be split into some small files. In most of the consensus protocols that support checkpoints, they will generate some stable checkpoints which indicates that the system can remove the logs before these checkpoints. In ResilientDB, a stable checkpoint is a sequence number that all the requests earlier than that number have been committed. Thus, the redo process can start from a stable checkpoint.

As the requests are out of order in the log files, each file will save the request information including the stable checkpoint, the minimum and the maximum sequence numbers of the requests in the files in their file names except the latest active one.

When loading the requests starting from a stable checkpoint S, start from the earliest file whose maximum sequence of the requests is less than S.

Consistency to Storage

Starting from a middle stable checkpoint could not guarantee the storage has executed all the requests before the checkpoint as the stable checkpoint generation and the storage execution are isolated.

To solve this problem, we switch to a new file only if the storage has executed all the requests whose sequences are less than the smallest stable checkpoint in the file. That means that, in one log file, there will be many stable checkpoints. We only consider the smallest one. In other words, we guarantee that when we finish log file A whose minimum stable checkpoint is X, all the requests with sequence numbers less than X have been committed.

So it is safe to redo the requests starting from A. However, because some requests will fall into the files before A, we need to find the starting log file using the maximum sequence number discussed above.

Recovery and Checkpoint Protocols in NexRes

Tue, 22 Aug 2023 00:00:00 +0000

The view-change protocol and checkpoint algorithm provide PBFT with liveness by allowing the system to make progress when the primary fails. In this blog, we introduce how we implement the PBFT view-change protocol and checkpoint algorithm in NexRes, list what Byzantine failures our current version is resilient to, and illustrate how our view-change protocol and checkpoint algorithm provide liveness in the presence of the failures.

We use the same model in the PBFT paper. There are $n = 3f+1$ replicas, at most $f$ of while can be Byzantine, where a Byzantine replica can have arbitrary malicious behavior.

view-change protocol

FAILURE DETECTION

In this section, we describe how PBFT in NexRes detects the failure of the primary $P$.

Client $C$ sends a request $T$ to the primary and sets a timer $t_c$.

replica_communicator_->SendMessage(*new_request, GetPrimary());
AddWaitingResponseRequest(std::move(new_request));

If $C$ receives $f+1$ valid responses for $T$ before $t_c$ expires, then $C$ considers $T$ as stable in the ledger.

CollectorResultCode ret =
    AddResponseMsg(context->signature, std::move(request),
                   [&](const Request& request,
                       const TransactionCollector::CollectorDataType*) {
                     response = std::make_unique<Request>(request);
                     return;
                   });
if (ret == CollectorResultCode::STATE_CHANGED) {
    RemoveWaitingResponseRequest(hash);
}

If not, $C$ broadcasts $T$ to all replicas.

  if(CheckTimeOut(client_timeout.hash)){
    auto request = GetTimeOutRequest(client_timeout.hash);
    if(request){
      replica_communicator_->BroadCast(*request);
    }
  }

When receiving $T$, if a replica $R$ is not the current primary, then it forwards to the current primary $P$ and sets a timer $t_r$.

if (config_.GetSelfInfo().id() != message_manager_->GetCurrentPrimary()) {
  replica_communicator_->SendMessage(*user_request,
                                message_manager_->GetCurrentPrimary());
  request_complained_.push(std::make_pair(std::move(context), std::move(user_request)));
  return -3;
}

When $t_r$ expires, $R$ checks if it has committed any request form $C$ since it starts $t_r$.

If not, $R$ requests a view-change.

  if(viewchange_timeout->type == ViewChangeTimerType::TYPE_COMPLAINT){
    if (status_ == ViewChangeStatus::NONE && viewchange_timeout->view == system_info_->GetCurrentView()) {
      if (viewchange_timeout->start_time >= message_manager_->GetLastCommittedTime(viewchange_timeout->proxy_id)) {
        checkpoint_manager_->TimeoutHandler();
      }
    }
  } 

REQUESTING A VIEW-CHANGE

Detecting the failure of the primary is not the only reason to request a view-change. Besides, if a replica $R$ receives f+1 VIEW-CHANGE messages of the current view from other replicas and $R$ has not requested a view-change in the current view, then $R$ requests a view-change as well.
```
size_t request_size = AddRequest(viewchange_message, request->sender_id());
if (request_size == config_.GetMaxMaliciousReplicaNum() + 1) {
  checkpoint_manager_->TimeoutHandler();
}
```

Once a view-change is requested, replicas process no more consensus messages and then proceed to construct the VIEW-CHANGE message and broadcast it to all the replicas at periodic intervals.

checkpoint_manager_->SetTimeoutHandler([&]() {
  if (status_ == ViewChangeStatus::NONE) {
    view_change_counter_ = 1;
  } else if (status_ == ViewChangeStatus::READY_NEW_VIEW) {
    view_change_counter_++;
  }
  if (ChangeStatue(ViewChangeStatus::READY_VIEW_CHANGE)) {
    SendViewChangeMsg();
  }
});

The VIEW-CHANGE message contains a set $S$ of requests that $R$ has prepared, which means that for each request $T\in S$, $R$ has received $2f+1$ PREPARE messages in support of $T$.

For each $T\in S$, the VIEW-CHANGE message includes a corresponding Prepare-Proof that contains the $2f+1$ digitally-signed PREPARE messages.

for (int i = 1; i <= max_seq; ++i) {
  if (message_manager_->GetTransactionState(i) >= TransactionStatue::READY_COMMIT) {
    std::vector<RequestInfo> proof_info =
        message_manager_->GetPreparedProof(i);
    auto txn = view_change_message.add_prepared_msg();
    txn->set_seq(i);
    for (const auto& info : proof_info) {
      auto proof = txn->add_proof();
      *proof->mutable_request() = *info.request;
      *proof->mutable_signature() = info.signature;
    }
  }
}

$R$ moves to the next view, broadcasts the VIEW-CHANGE message, and sets a timer $t_v$. If $R$ fails to receive $2f+1$ VIEW-CHANGE messages, then $R$ broadcasts the VIEW-CHANGE message for the current view again.

if(viewchange_timeout->type == ViewChangeTimerType::TYPE_VIEWCHANGE){
    if(status_ == ViewChangeStatus::READY_VIEW_CHANGE && viewchange_timeout->view == system_info_->GetCurrentView()){
    LOG(ERROR)<< "It is time to rebroadcast viewchange messages";
    ChangeStatue(ViewChangeStatus::VIEW_CHANGE_FAIL);
    checkpoint_manager_->TimeoutHandler();
  }
}

PROPOSING NEW-VIEW

If the replica $R$ receives $2f+1$ VIEW-CHANGE messages for the current view, $R$ sets a timer $t_n$.

If $R$ is the new primary $P’$, then $P’$ constructs and broadcasts a NEW-VIEW message.

size_t request_size = AddRequest(viewchange_message, request->sender_id());
if (request_size == config_.GetMinDataReceiveNum()) {
  if (IsNextPrimary(viewchange_message.view_number())) {
    SendNewViewMsg(viewchange_message.view_number());
  }
  else {
    StartNewViewTimer();
  }
}
ChangeStatue(ViewChangeStatus::READY_NEW_VIEW);

The NEW-VIEW message contains the $2f+1$ digitally-signed VIEW-CHANGE messages.

auto requests = viewchange_request_[view_number];
NewViewMessage new_view_message;
new_view_message.set_view_number(view_number);

std::map<uint64_t, std::string> new_view_request;  // <sequence, digest>
for (auto& it : requests) {
  ViewChangeMessage& msg = it.second;
  msg.set_view_number(view_number);
  *new_view_message.add_viewchange_messages() = msg;
}

STARTING A NEW VIEW

If $R$ fails to receive a valid NEW-VIEW message before $t_n$ expires, then $R$ requests one more view-change, enters the next view, and broadcasts VIEW-CHANGE message.

  if(viewchange_timeout->type == ViewChangeTimerType::TYPE_NEWVIEW){
    if(status_ == ViewChangeStatus::READY_NEW_VIEW && viewchange_timeout->view == system_info_->GetCurrentView()){
      checkpoint_manager_->TimeoutHandler();
    }
  }

If a valid NEW-VIEW message with the highest sequence number (round number) $max_s$ is received, then, for each sequence number $r < max_s$ with a valid Prepare-Proof, $R$ broadcasts the corresponding COMMIT message for round $r$, while for each sequence number $r’ < max_s$ without a valid Prepare-Proof, $R$ broadcasts PREPARE message of null value for round $r’$.

for (size_t i = 0; i < request_list.size(); ++i) {
  if (new_view_message.request(i).type() ==
      static_cast<int>(Request::TYPE_PRE_PREPARE)) {
    new_view_message.request(i);
    replica_communicator_->SendMessage(new_view_message.request(i),
                                       config_.GetSelfInfo());
  } else {
    replica_communicator_->BroadCast(new_view_message.request(i));
  }
}

CHECKPOINT ALGORITHM

We have introduced the view-change protocol above. However, view-change protocol cannot prevent malicious replicas from keeping up to $f$ non-faulty replicas in the dark. Malicious replicas do so by not sending any consensus messages replicas to the $f$ replicas. Thus, the $f$ non-faulty replicas cannot commit any new requests while other non-faulty replicas can.

To solve this problem, we need to implement the checkpoint algorithm.

SENDING CHECKPOINT

When initiating the system, we set a checkpoint watermark size value, such as 5. Then, every 5 consecutive rounds, a replica $R$ broadcasts a CHECKPOINT message with sequence number $r$, where $r$ is the highest sequence number of the 5 rounds, informing other replicas that it has committed and executed the requests in the last 5 rounds.
```
  if (current_seq == last_ckpt_seq + water_mark) {
    last_ckpt_seq = current_seq;
    BroadcastCheckPoint(last_ckpt_seq, last_hash, stable_hashs, stable_seqs);
  }
```

FETCHING UNKNOWN REQUESTS

If a replica $R$ receives $f+1$ valid CHECKPOINT messages of the same sequence number $r$ and the highest sequence number that $R$ has executed is $r’, r’<r$, then, $R$ needs to fetch the unknown requests behind round $r’$.
$R$ calls an interface to fetch the requests, asking the senders of the $f+1$ CHECKPOINT messages one by one until it fetches valid requests.
To check the validity of the fetched requests, $R$ verifies the hash and signatures.

If the fetched requests are valid, then $R$ commits and executes them.

  auto replicas_ = config_.GetReplicaInfos();
  for(auto &replica_: replicas_){
    auto requests = txn_accessor.GetRequestFromReplica(last_seq_ + 1, committable_seq, replica_);
      if (PassAllChecks(requests)) {
        for (auto& request: *requests) { 
          if (executor_) {
            executor_->Commit(std::make_unique<Request>(request));
          }
        }
        break;
      }
  }

STABLE CHECKPOINT

If a replica $R$ receives $2f+1$ valid CHECKPOINT messages of the same sequence number $r$. It means that at least $f+1$ non-faulty replicas have executed requests with sequence number $r$. And we consider $r$ as a stable checkpoint.

  if (it.second.size() >=
    static_cast<size_t>(config_.GetMinDataReceiveNum())) {
    stable_seq = it.first.first;
    stable_hash = it.first.second;
  }
      
  std::vector<SignatureInfo> votes;
  if (current_stable_seq_ < stable_seq) {
    votes = sign_ckpt_[std::make_pair(stable_seq, stable_hash)];
    stable_ckpt_.set_seq(stable_seq);
    stable_ckpt_.set_hash(stable_hash);
    stable_ckpt_.mutable_signatures()->Clear();
    for (auto vote : votes) {
      *stable_ckpt_.add_signatures() = vote;
    }
    current_stable_seq_ = stable_seq;
  }

A Stable-Checkpoint-Proof with sequence number $r$ can be considered as Prepare-Proof for all rounds before $r$ because a request committed by a non-faulty replica must have been prepared by at least $f+1$ non-faulty replicas. A Prepare-Proof for the request will definitely appear in at least one of the $2f+1$ VIEW-CHANGE messages in the NEW-VIEW message.

OPTIMIZING VIEW-CHANGE WITH CHECKPOINT

With the checkpoint algorithm, we can reduce the overhead of the view-change protocol. Instead of all Prepare-Proofs from the first round, a VIEW-CHANGE message contains a Stable-Checkpoint-Proof with the highest sequence number $r$ and all Prepare-Proofs with a higher sequence number $r’, r’>r$.

*view_change_message.mutable_stable_ckpt() =
    checkpoint_manager_->GetStableCheckpointWithVotes();
for (int i = view_change_message.stable_ckpt().seq() + 1; i <= max_seq; ++i) {
  if (message_manager_->GetTransactionState(i) >= TransactionStatue::READY_COMMIT) {
    std::vector<RequestInfo> proof_info =
        message_manager_->GetPreparedProof(i);
    ...
    ...
  }
}

RESILIENCE TO BYZANTINE BEHAVIORS

In this section, we list the Byzantine behaviors that our implementation is resilient to and illustrate how our implementation is equipped with resilience.

NON-RESPONSIVE PRIMARY

We consider a primary as non-responsive if it crashes or deliberately stops broadcasting new PRE-PREPARE messages. If the primary becomes non-responsive, then the client cannot receive responses and will complain. Thus, replicas will forward the complained requests to the primary and start a timer. If the primary keeps being non-responsive, then at least $2f+1$ non-faulty replicas will request a view-change and eventually enter a new view.

KEEPING REPLICAS IN THE DARK

Obviously, non-faulty replicas in the dark can catch up with other replicas via the checkpoint algorithm.

EQUIVOCATION

There are two cases when the primary equivocates in round $r$, which means that the primary sends different PRE-PREPARE messages to different replicas. In the first case, no request gets enough votes to be committed by a non-faulty replica, which is the same as the case when the primary becomes non-responsive. In the second case, there is one request that gets committed by some of the non-faulty replicas, which is the same as the case when the primary attempts to keep some replicas in the dark. From what we have illustrated for the two malicious behaviors above, we know that we are able to recover from both of the cases when the primary equivocates.

CONSECUTIVE FAULTY PRIMARIES

There can be consecutive Byzantine primaries in consecutive views. Thus, it is possible that the new primary is non-responsive as well and does not broadcast NEW-VIEW messages. To provide liveness in such a case, as mentioned before, non-faulty replicas will request a new view-change.

DUPLICATION

A byzantine primary or primaries in different views may broadcast PRE-PREPARE the same request twice, which we call duplication. To eliminate duplication, when proposing a new PRE-PREPARE message, non-faulty primaries check if the request is already proposed. And non-faulty replicas check if the request is already proposed when receiving a PRE-PREPARE message.

int Commitment::ProcessNewRequest(std::unique_ptr<Context> context,
                                  std::unique_ptr<Request> user_request) {
  ...
  if (duplicate_manager_->CheckAndAddProposed(user_request->hash())) {
    return -2;
  }
  ...                                  
}

int Commitment::ProcessProposeMsg(std::unique_ptr<Context> context,
                                  std::unique_ptr<Request> request) {
    ...
    if (duplicate_manager_->CheckAndAddProposed(request->hash())){
      LOG(INFO) << "The request is already proposed, reject";
      return -2;
    }
    ...
}

Using the NexRes Explorer

Sat, 06 May 2023 00:00:00 +0000

Our Explorer page is a tool for visualizing the NexRes blockchain. The Explorer displays specific blocks on the blockchain, transactions within the blocks, ledger configuration data, and a chart exposing transaction history.

Install

Go to our install tutorial for instructions on how to install NexRes.

Set Up

You will need to clone three repos to get started: resilientdb for the ResilientDB servers, sdk for the HTTP endpoints and websocket, and resilientdb.github.io for the webpage.

resilientdb

Install dependencies.

./INSTALL.sh

Start the KV servers with the example script. This script uses the example/kv_config.config file.

./service/tools/kv_service/service_tools/start_kv_service.sh

You will observe that four kv_server replicas have locally launched.

sdk

We use Crow, a C++ framework for creating HTTP or Websocket web services to connect NexRes to the Explorer.

In another terminal shell after starting KV Server, build the crow service from the sdk repo:

bazel build service/http_server/crow_service_main

Run the binary to start the service:

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

You will see this if successful:

  (2022-12-19 06:12:02) [INFO    ] Crow/master server is running at http://0.0.0.0:18000 using 16 threads
  (2022-12-19 06:12:02) [INFO    ] Call `app.loglevel(crow::LogLevel::Warning)` to hide Info level logs

resilientdb.github.io

In another terminal open the resilientdb.github.io repo and follow the steps below.

Switch to explorer branch

git fetch

git checkout explorer

Project Setup

npm install

Compile and Hot-Reload for Development

npm run dev

You will now be able to access a development server for resilientdb.com running at http://localhost:3000. Click on the explorer icon in the top right corner to migrate to http://localhost:3000/explorer.

NOTE: You must disable cross-origin restrictions in the browser where you open the development server.

Populating the Blockchain

At this point you will be able to see the ledger configuration data, but the transaction history chart and block table will be empty. The next step is populating the NexRes blockchain to view blocks and transactions using the Explorer.

You can use an API tester tool such as Talend API Tester for committing and getting transactions using the routes defined by our crow service.

You can also use curl commands to transfer data to and from the server. Here are some examples of the routes available.

For committing a transaction:

curl -X POST -d ‘{“id”:”samplekey”,”value”:”samplevalue”}’ localhost:18000/v1/transactions/commit

For getting the transaction:

curl localhost:18000/v1/transactions/samplekey

For getting all transactions:

curl localhost:18000/v1/transactions

Once you have set and get some transactions you will be able to see the blocks and the transactions within them in the table and chart.

There are currently two options for how the blocks table refreshes. The method that is used on the nexres branch uses a websocket and fetches the updated list of blocks whenever a new transaction is committed through the HTTP endpoints. The second option, which is available on the explorer-alternate-refresh branch, polls an updated list of blocks every five seconds. You may use whichever one suits your needs better.

Video Demo

Here is a video demo showing how to run and use the Explorer. The video assumes that all the dependencies have already been installed.

GeoBFT in NexRes

Tue, 07 Mar 2023 00:00:00 +0000

In this article, we present a comprehensive introduction to the Geo-Scale Byzantine Fault-Tolerant consensus protocol (GeoBFT) through the lens of the NexRes codebase. We will illustrate the algorithm of inter-cluster sharing and remote view-change of the protocol, and how to implement it on NexRes. We will also show the performance experiment results we got for GeoBFT on NexRes.

The challenges in Geo-scale blockchains

The traditional blockchain protocols like PBFT¹, rely on a single primary replica to coordinate all consensus decisions, and require a vast amount of global communication between all pairs of replicas, hence, they often attain low throughput, especially when the replicas are spread across a wide-area network or geographically large distances.

As the following figure shows, the global message latencies are at least 33-270 times higher than local latencies, while the maximum throughput is 10-151 times lower, both implying that the communication between regions is much more costly than communications within regions.

Figure 1. Real-world inter- and intra-cluster communication costs in terms of the ping round-trip times (which determines latency) and bandwidth (which determines throughput). These measurements are taken in Google Cloud using clusters of n1 machines (replicas) that are deployed in six different regions.

Geo-Scale Byzantine Fault-Tolerant consensus protocol (GeoBFT)

Here we present GeoBFT that uses topological information to group all replicas in a single region into a single cluster². GeoBFT assigns each client to a single cluster, and it operates in rounds, in each round, every cluster will be able to propose a single client request for execution. Each round consists of the three steps sketched in Figure 2: local replication, global sharing, and ordering and execution, which we further detail next.

Figure 2. Steps in a round of the GeoBFT protocol.

Local Replication

In the first step of GeoBFT, each round starts with each cluster replicating a client request T, to do so, GeoBFT relies on PBFT. In addition, when each non-faulty replica commits the proposed request, it will also construct a commit certificate $\langle T\rangle_{C}$ consisting of the client request and n-f > 2f identical COMMIT messages for $\langle T\rangle_{P_{C}}$ signed by distinct replicas. The following graph shows the normal-case workflow of round $\rho$ of PBFT within a cluster $C$: a client $c$ requests transaction $T$, the primary $P_{C}$ proposes this request to all local replicas, which prepare and commit this proposal, and, finally, all replicas can construct a commit certificate.

Figure 3. The normal-case working of round ρ of PBFT within a cluster C

Once a cluster has completed local replication of a client request, it proceeds with the second step: sharing the client request with all other clusters. After $C$ reaches local consensus on client request $\langle T\rangle_{P_{C}}$ in round $\rho$—enabling the construction of the commit certificate $[\langle T \rangle_{P_{C}}, \rho]$ that proves local consensus— $C$ needs to exchange this client request and the accompanying proof with all other clusters. The following graphs show the global sharing protocol used by $C_{1}$ to send $m := (\langle T \rangle_{P_{c}}, [ \langle T \rangle_{P_{c}}, \rho ])$ to $C_{2}$ and the pseudo-code of this protocol, which we will illustrate next.

Figure 4. The normal-case working of the global sharing protocol.

Figure 5. Pseudo Code of the normal-case global sharing protocol.

Let $m := (\langle T \rangle_{P_{c}}, [ \langle T \rangle_{P_{c}}, \rho ])$ be the message that some replica in cluster $C_{1}$ needs to send to some replicas $C_{2}$.

In the global phase, the primary $P_{C_{1}}$ sends $m$ to $f+1$ replicas in $C_{2}$. In the local phase, each non-faulty replica in $C_2$ that receives a well-formed m forwards m to all replicas in its cluster $C_{2}$.

There are two cases in which replicas in $C_{2}$ do not receive $m$ from $C_{1}$: either $P_{C_{1}}$ is faulty and did not send $m$ to $f+1$ replicas in $P_{C_{2}}$, or communication is unreliable, and messages are delayed or lost. In both cases, non-faulty replicas in $C_{2}$ initiate remote view-change to force primary replacement in $C_{1}$.

Remote View-Change

To recover from any failures, we provide a remote view-change protocol. To simplify the presentation, we focus on the case in which the primary of cluster $C_{1}$ fails to send $m := (\langle T \rangle_{P_{c}}, [ \langle T \rangle_{P_{c}}, \rho ])$ to replicas of $P_{C_{2}}$. As the following graph describes, our remote view-change protocol consists of four phases, which we detail next. This protocol is triggered when a cluster $C_{2}$ ∈ S expects a message from $C_{1}$ ∈ S, but does not receive this message in time.

First, non-faulty replicas in cluster $C_{2}$ detect the failure of the current primary $P_{C_{1}}$ of ${C_{1}}$ to send m. Note that although the replicas in $C_{2}$ have no information about the contents of message m, they are awaiting the arrival of a well-formed message m from $C_{1}$ in round $\rho$.
Second, the non-faulty replicas in $C_{2}$ initiate agreement on failure detection.
Third, after reaching an agreement, the replicas in $C_{2}$ send their request for a remote view-change to the replicas in $C_{1}$ in a reliable manner.
In the fourth and last phase, the non-faulty replicas in $C_{1}$ trigger a local view-change, replace $P_{C_{1}}$ , and instruct the new primary to resume global sharing with $C_{2}$.

Figure 6. The remote view-change protocol of GeoBFT.

Ordering and Execution

Once replicas of a cluster have chosen a client request for execution and have received all client requests chosen by other clusters, the final step is ordering and executing these client requests. In specific, in round $\rho$, any non-faulty replica that has valid requests from all clusters can move ahead and execute these requests. To put these client requests in a unique order, execute them, and inform the clients of the outcome, GeoBFT simply uses a pre-defined ordering on the clusters. For example, each replica executes the transactions in the order $[T_{1}, . . . , T_{z}]$. Once the execution is complete, each replica $R \in C_{i}, 1 \leq i \leq z$, informs the client $c_{i}$ of any outcome.

Implementation

Now we will give a brief overview of the implementation of the GeoBFT protocol in NexRes. To implement GeoBFT on NexRes, we will need to add a few modules: Local Executor, Global Executor, GeoBFT Consensus Service, and also adjust the Configuration, which we will introduce next. Below is the normal-case working graph of GeoBFT on NexRes.

Figure 7. The normal-case working of GeoBFT on NexRes

Configuration

To implement GeoBFT on NexRes, we need to first add a few fields in the configuration file, which specify the timeout for remote view-change, and the flag that indicates whether the local view-change is enabled.

{
  region: [
    {
      replicaInfo: {
        id:
        ip:
        port:
      },
      regionId: 1
    }
  ],
  selfRegionId: 1,
  rvc_timeout_ms: 60000,	 # Timeout for Remote View-Change
  enable_viewchange: true	 # View-Change Flag
}

Local Executor

After committing a local client request at the end of PBFT, the local executor will construct the commit certificate which is of TYPE_GEO_REQUEST, here we call it geo_request. The primary replica will be responsible for sending out the geo_request to every other cluster in the system. Specifically, for each round, the same geo_request will only need to be sent to f+1 replicas in each cluster.

void GeoTransactionExecutor::SendBatchGeoMessage(
    const std::vector<std::unique_ptr<Request>>& batch_geo_request) {
    // Construct geo_request
    std::unique_ptr<Request> geo_request = resdb::NewRequest(
      Request::TYPE_GEO_REQUEST, Request(), config_.GetSelfInfo().id(),
      config_.GetConfigData().self_region_id());
    ...	// set sequence number, proxy id, hash value, data in geo_request
	// Only for primary node, send out geo_request to other regions.
    if (config_.GetSelfInfo().id() == system_info_->GetPrimaryId()) {	
        for (const auto& region : config_data.region()) {
            if (region.region_id() == config_data.self_region_id())	continue;
            int max_faulty = (region.replica_info_size() - 1) / 3;		// maximum number of faulty replicas in this region
            int num_request_sent = 0;
            for (const auto& replica : region.replica_info()) {
                if (num_request_sent > max_faulty) {
                    break;
                }
                LOG(ERROR) << "send batch_geo_request to node " << replica.id();
                int ret = replica_client_->SendBatchMessage(batch_geo_request, replica);	// send to f + 1 replicas in the region
                if (ret >= 0) {
                    num_request_sent++;
                }
            }
        }
    }
}

Global Executor

After receiving a geo_request from another region, push it into order_queue_, which is storing the transactions that are not yet ordered. The global executor will constantly pop out geo_request from order_queue_, and add it to execute_map_, which is storing the transactions that are waiting to be executed by order. Then, the global executor will find the next transaction to execute in the execute_map_ according to the current round $\rho$. We use a thread to keep this ordering and execution process going.

std::map<std::pair<uint64_t, int>, std::unique_ptr<Request>> execute_map_;
std::thread order_thread_ = std::thread(&GeoGlobalExecutor::OrderRound, this);

int GeoGlobalExecutor::OrderGeoRequest(std::unique_ptr<Request> request) {
    order_queue_.Push(std::move(request));
	return 0;
}

void GeoGlobalExecutor::AddData() {
	auto request = order_queue_.Pop();	// Pop geo_request from order_queue_
	if (request == nullptr) {
		return;
  	}
    uint64_t seq_num = request->seq();
    int region_id = request->region_info().region_id();
	execute_map_[std::make_pair(seq_num, region_id)] = std::move(request);	// add geo_request to execute_map_
}

void GeoGlobalExecutor::OrderRound() {
	while (!IsStop()) {
    	AddData();	// Pop geo_request from order_queue_, add it to execute_map_
    	while (!IsStop()) {
			std::unique_ptr<Request> seq_map = GetNextMap();	// Get next geo_request to execute in the execute_map_
            if (seq_map == nullptr) {
                break;
            }
            Execute(std::move(seq_map));	// Execute the geo_request and reset the timer for remote view change.
    	}
  	}
}

The global executor also has $\mathcal{n-1}$ timers to trigger remote view-change in $\mathcal{n-1}$ other regions. Let $\mathcal{R} \in \mathcal{C_{1}}$ be the replica we are looking at. Upon receiving a geo_request from another region, the global executor will need to reset the timer for that region. When the timeout function is triggered, $\mathcal{R}$ will broadcast a drvc_request locally. After receiving $\mathcal{f+1}$ distinct drvc_request from other replicas in local cluster, $\mathcal{R}$ will also start to broadcast a drvc_request locally. After receiving $\mathcal{n-f}$ distinct drvc_request from other replicas in the local cluster, $\mathcal{R}$ will start to send a new type of request-rvc_request to $\mathcal{Q} \in \mathcal{C_{2}}$ with $id(\mathcal{Q})=id(\mathcal{R})$, with $C_{2}$ being the target cluster of this remote view-change.

void GeoGlobalExecutor::Execute(std::unique_ptr<Request> request) {
    ...
    // reset the timer for the region which the request came from.
    int region_id = request->region_info().region_id();
    if (next_region_ == 1){
      TryResetTimer(next_seq_, region_id);	
    }
    else{
      TryResetTimer(next_seq_+1, region_id);
    }
}

// detect failure of region rvc_target_region in round ρ, trigger RVC
void GeoGlobalExecutor::TriggerRVCLocalBroadcast(int rvc_target_region) {
    ...
    // broadcast drvc_request locally
    std::unique_ptr<Request> drvc_request = resdb::NewRequest(
        Request::TYPE_DRVC, Request(), config_.GetSelfInfo().id(),
        config_.GetConfigData().self_region_id());
    drvc_request->set_current_executed_seq(missing_seq);
    drvc_request->set_rvc_target_region(rvc_target_region);
    replica_client_->BroadCast(*drvc_request);
}

GeoBFT Consensus Service

To process those types of messages we mentioned (geo_request, drvc_request, rvc_request) we need to implement the GeoBFT Consensus Service as the entry for the process of those requests.

int ConsensusServiceGeoPBFT::ConsensusCommit(std::unique_ptr<Context> context,
                                             std::unique_ptr<Request> request) {
  switch (request->type()) {
    case Request::TYPE_GEO_REQUEST:
      return commitment_->GeoProcessCcm(std::move(context), std::move(request));		// Process geo_request
    case Request::TYPE_DRVC:
      return commitment_->ProcessDRVC(std::move(context), std::move(request));			// Process drvc_request
    case Request::TYPE_RVC:
      return commitment_->ProcessRVC(std::move(context), std::move(request));			// Process rvc_request
  }
  return ConsensusServicePBFT::ConsensusCommit(std::move(context), std::move(request));	// Norcal-case PBFT processing
}

int GeoPBFTCommitment::GeoProcessCcm(std::unique_ptr<Context> context,
                                     std::unique_ptr<Request> request) {
    ...	// filter of duplicate message
    // if the request comes from another region, do local broadcast
    if (sender_region_id != self_region_id) {
        std::unique_ptr<Request> broadcast_geo_req =
            resdb::NewRequest(Request::TYPE_GEO_REQUEST, *request,
                              config_.GetSelfInfo().id(), sender_region_id);
        replica_client_->BroadCast(*broadcast_geo_req);
    }
    // push the request into order_queue_
    return global_executor_->OrderGeoRequest(std::move(request));
}

int GeoPBFTCommitment::ProcessDRVC(std::unique_ptr<Context> context,
                                   std::unique_ptr<Request> request) {
    int missing_seq = request->current_executed_seq();
    int rvc_target_region = request->rvc_target_region();
    int drvc_sender_id = request->sender_id();
    ...	// filter of duplicate messages
    // when receives f+1 DRVC request: detect failure of region C in round
    // ρ broadcast DRvc(C, ρ) to all replicas in local region.
    int num_replicas = config_.GetReplicaNum();
    int max_faulty = (num_replicas - 1) / 3;
    if (drvc_map_[std::make_pair(rvc_target_region, missing_seq)].size() == max_faulty + 1) {
		global_executor_->TriggerRVCLocalBroadcast(rvc_target_region);
    }
    // when receives DRvc(C1, ρ) from n − f replicas, send Rvc(C1, ρ)_R to Q ∈ C1, id(R) = id(Q).
    if (drvc_map_[std::make_pair(rvc_target_region, missing_seq)].size() == num_replicas - max_faulty) {
        std::unique_ptr<Request> rvc_request = resdb::NewRequest(
            Request::TYPE_RVC, Request(), config_.GetSelfInfo().id(),
            config_.GetConfigData().self_region_id());
        rvc_request->set_current_executed_seq(missing_seq);
        rvc_request->set_rvc_target_region(rvc_target_region);
        ...	// find target_replica Q
        replica_client_->SendMessage(*rvc_request, target_replica);
    } 
}

int GeoPBFTCommitment::ProcessRVC(std::unique_ptr<Context> context,
                                  std::unique_ptr<Request> request) {
    uint64_t missing_seq = request->current_executed_seq();
	int sender_id = request->sender_id();
	int max_faulty = (config_.GetReplicaNum() - 1) / 3;
    ...	// filter of duplicate messages
    // If received f+1 idendical rvc from distinct replicas in C2, trigger local view change.
    if (rvc_map_[missing_seq].size() == max_faulty + 1) {
		viewchange_manager_->RunTimeoutFunc(missing_seq);
	}
    // Broadcast rvc locally.
    if (request->region_info().region_id() != config_.GetConfigData().self_region_id()) {
        std::unique_ptr<Request> rvc_request = resdb::NewRequest(
            Request::TYPE_RVC, Request(), config_.GetSelfInfo().id(),
            config_.GetConfigData().self_region_id());
        rvc_request->set_current_executed_seq(missing_seq);
        replica_client_->BroadCast(*rvc_request);
    }
}

Preliminary Experiments and Results

Experiment Setup

We ran all the experiments on AWS using:

t3.2xlarge
8 vCPU
64GB of RAM

Nexres ran on Ubuntu, 20.04 LTS, amd64 focal image build on 2022-09-14.

Throughput and Latency Performance

The first experiment is designed to test the maximum throughput and latency of GeoBFT and compare the result with PBFT performance under the same configuration. The throughput and latency of PBFT and GeoBFT with 4 clusters with different numbers of replicas are recorded. The replica number is set to 16, 32, 64, and 128.

From the figure below, we can see that as the system scales, the throughput decreases and the latency increases for both PBFT and GeoBFT. With respect to throughput, GeoBFT outperforms PBFT at all replica settings. In general, the average latency of GeoBFT is smaller than PBFT at all replica settings except for the 16-replica setting, and it is almost half of PBFT latency at the 128-replica setting.

Figure 8. Throughput and latency as a function of the number of replicas.

Impact of Primary Failure

In the second experiment, we measure the performance of GeoBFT when a single primary fails (in one of the two regions). The system configuration is 2 clusters with 16 replicas in each cluster, 32 replicas in total.

Figure 9 shows the throughput attained by GeoBFT when the primary of one cluster fails, and the replicas run the remote view change protocol to replace the faulty primary. The primary of one of the clusters fails at 45s, and the system’s average throughput starts decreasing; Later, GeoBFT again observes an increase in throughput at 60s.

Figure 9. GeoBFT's throughput under the primary failure of one cluster out of two.

References

Castro, Miguel, and Barbara Liskov. “Practical byzantine fault tolerance.” OsDI. Vol. 99. No. 1999. 1999. ↩
Suyash Gupta, Sajjad Rahnama, Jelle Hellings, and Mohammad Sadoghi. “ResilientDB: Global Scale Resilient Blockchain Fabric” URL: https://arxiv.org/abs/2002.00160 ↩

NexRes Durability Layer

Wed, 15 Feb 2023 00:00:00 +0000

We provide two databases to choose from to use for durable storage: LevelDB and RocksDB. Both are key-value stores based on log-structured merge (LSM) trees. LSM trees are optimized for write-heavy workloads, and consist of multiple levels, with the keys sorted at each level. The top level is called the memtable, where the most recently inserted data is kept in-memory. The two databases are similar, as RocksDB was initially built on top of LevelDB.

Install

If you don’t have NexRes installed already please check the install tutorial.

LevelDB vs RocksDB

Through testing we have found that NexRes works up to ~35-40% faster with LevelDB enabled than with RocksDB. When batched writes are enabled in the durable layer, performance increases by up to 3x with with LevelDB and up to around 2x with RocksDB. RocksDB also provides multiple features not in LevelDB, including allowing the user to set the number of worker threads used.

Configuration

We use Google’s Protobuf to specify the configurations for NexRes. You can configure following settings for the durable layer in a config file such as the one provided below:

LevelDB and RocksDB

enable_leveldb/enable_rocksdb
- Make sure to only set one of these to true at the same time
write_buffer_size_mb
write_batch_size
- Keep at 1 to use only individual writes. For batched writes, sizes of 100+ bring higher performance numbers
path
generate_unique_pathnames

RocksDB only

num_threads

example/kv_config.config

{
  region : {
    ...
  },
  ...
  rocksdb_info : {
    enable_rocksdb:false,
    num_threads:1,
    write_buffer_size_mb:32,
    write_batch_size:1,
    generate_unique_pathnames:true,
  },
  leveldb_info : {
    enable_leveldb:false,
    write_buffer_size_mb:128,
    write_batch_size:1,
    generate_unique_pathnames:true,
  },
}

Warning

Currently, reads are guaranteed to be correct when batched writes are enabled in the durable layer. This is because a read may access the old value of a key whose value is updated in a write that is in a batch that has not been committed yet.

If “path” is not set in the durability settings for RocksDB or LevelDB then default paths will be generated in the /tmp/ folder, which is cleared whenever the machine is shut down.

If you are testing NexRes on your local machine using localhost ip, then make sure to set generate_unique_pathnames to true, since multiple processes are not allowed to open up the same RocksDB/LevelDB directory at the same time. When generate_unique_pathnames is set to true, the durable layer uses the cert file names to generate separate directories for each port of the localhost ip.

For example, the process hosting a server with cert_1.cert will append “1” to its directory path. If the cert file name does not contain a number and generate_unique_pathnames is set, “0” will be appended to the path.

UTXO On NexRes

Sun, 12 Feb 2023 00:00:00 +0000

An unspent transaction output (UTXO) model helps us to make crypto transactions more efficient and it is a crucial core part in Bitcoin. In this document, we introduce the UTXO implementation on NexRes.

Crypto key

A Crypt key is a private-public key pair to provide the security of the transaction. We use ECDSA as the encoding algorithm and sign each message.

Wallet

Wallet manages the coins of each user. The address of each user is created by its public key, using bech32 as encoding as what Bitcoin does, also wrapped by ripemd160 and sha256.

address = bech32Encode(ripemd160(sha256(public key)))

UTXO

UTXO is a data structure representing a transaction of a wallet user, including some inputs and outputs. Each input is a transaction that transfers coins from other users. In the UTXO on NexRes, the input contains the input transaction ids and the output index of the output transaction that delivers coins to the user. All these input transactions are the available input of the current transaction, and the outputs indicate how to deliver these coins from these transactions. It contains the addresses of the delivered users, how many coins are to be delivered, and their public keys. The sum of the inputs should be larger than the sum of the outputs. The delta can be used as the gas fee.

Security

Each transaction will be signed by the address of the owner and the signatures can be verified by the public key inside its input transactions. Plus, the addresses of the input transactions should be the same as the address of the issue transaction. Therefore, it should guarantee that each transaction can only be spent once.

System Architecture

UTXO is running on NexRes and managed by its local UTXO Manager. Transactions will be included into a transaction block (tx block) and go through the consensus protocol by NexRes, then are saved locally into a transaction queue.

UTXO Manager iteratively fetches the transactions and executes the UTXO data in each transaction. All the valid UTXO data will be calculated as coins and saved into the user wallets so that they can view their accounts. What’s more, the transactions will be handled by a transaction pool so that not only the UTXO manager can keep checking whether the transaction has been spent or users can be able to trace the transaction history.

Getting Started On UTXO

Sun, 12 Feb 2023 00:00:00 +0000

Here we illustrate how to run the UTXO service on NexRes. We provide steps by steps tutorial to set up the UTXO service locally with 4 nodes and 1 client. We also provide tools to access the UTXO transactions and the user wallets.

Create a Wallet

Beginning using UTXO transactions on NexRes, we need to create a wallet by generating a private key, a public key, and an address corresponding to your wallet. Wallet addresses are encoded by bech32 which is also used for Bitcoin.

These are some steps to build your private-public keys and your address:

Go to the source folder which contains the WORKSPACE file.

Make sure bech32 has been installed which is used for the address encoding.

pip install bech32

Create your own private key. It will return a private key and a public key, encoded by ECDSA. In the example here, we will create two key pairs and two addresses.

bazel run //service/tools/utxo/wallet_tool/py:keys

  private key:303E020100301006072A8648CE3D020106052B8104000A0427302502010104202CB99BBB2AFEB7F48A574064091B34F24781C93AD8181A511C8DCFB2A111AD82
  public key:3056301006072A8648CE3D020106052B8104000A034200049C8FBD86EA4E38FD607CD3AC49FEB75E364B0C694EFB2E6DDD33ABED0BB1017575A79CC53EC6A052F839B4876E96FF9E4B08ECF23EC9CD495B82ECF9D95303BD

bazel run //service/tools/utxo/wallet_tool/py:keys

  private key:303E020100301006072A8648CE3D020106052B8104000A0427302502010104202BDCC4974026EC852F95D481AE8FEC3AC31E130AB6C78A32EB8410CCDCA4B337
  public key:3056301006072A8648CE3D020106052B8104000A03420004F838F3253A5224411D8951AA6EF2BB474EDD283EC088CD13D5404956C0A88079ECF539D9669A3D639A35BF9FD0F67ECBB3D332733C59B0272EB844405B6568D3

Create your wallet address based on the public key. This will return an bech32 address encoded from ripemd160(sha256(public_key))
bazel run //service/tools/utxo/wallet_tool/py:addr -- 3056301006072A8648CE3D020106052B8104000A034200049C8FBD86EA4E38FD607CD3AC49FEB75E364B0C694EFB2E6DDD33ABED0BB1017575A79CC53EC6A052F839B4876E96FF9E4B08ECF23EC9CD495B82ECF9D95303BD
```
  address: bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn
```
bazel run //service/tools/utxo/wallet_tool/py:addr -- 3056301006072A8648CE3D020106052B8104000A03420004F838F3253A5224411D8951AA6EF2BB474EDD283EC088CD13D5404956C0A88079ECF539D9669A3D639A35BF9FD0F67ECBB3D332733C59B0272EB844405B6568D3
```
  address: bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9
```

Start UTXO Service

Before starting the service, you need to assign a genesis coin to some addresses.

Modify the UTXO config to add coins.

service/tools/config/server/utxo_config.config

the field ‘out’ indicates the output of a UTXO.

{
  genesis_transactions: {
    transactions: {
        out:  {
            address : "bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn",
            value : 1000
            pub_key: "3056301006072A8648CE3D020106052B8104000A034200049C8FBD86EA4E38FD607CD3AC49FEB75E364B0C694EFB2E6DDD33ABED    0BB1017575A79CC53EC6A052F839B4876E96FF9E4B08ECF23EC9CD495B82ECF9D95303BD"
        }
    }
  }
}

Once you added the genesis coins, start the UTXO service.

./service/tools/utxo/service_tools/start_utxo_service.sh

Transfer your coins

First, we need to build the tools

bazel build service/tools/utxo/wallet_tool/cpp:utxo_client_tools

Then, run the tools to transfer the coins

bazel-bin/service/tools/utxo/wallet_tool/cpp/utxo_client_tools -c service/tools/utxo/wallet_tool/cpp/client_config.config -m transfer -t bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9 -d bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn -x 0 -v 100 -p 303E020100301006072A8648CE3D020106052B8104000A0427302502010104202CB99BBB2AFEB7F48A574064091B34F24781C93AD8181A511C8DCFB2A111AD82 -b 3056301006072A8648CE3D020106052B8104000A03420004F838F3253A5224411D8951AA6EF2BB474EDD283EC088CD13D5404956C0A88079ECF539D9669A3D639A35BF9FD0F67ECBB3D332733C59B0272EB844405B6568D3

-c	server config points to the client node
-m	function
-d	owner address
-t	address list to transfer (using “,” to split)
-x	input transaction id
-v	transfered value list of coins (using “,” to split)
-p	private key of the owner
-b	public key list of the delivered address (using “,” to split)

If it runs successfully, it returns the transaction id.

  E20230214 17:55:23.280972 39813 utxo_client_tools.cpp:61] execute result:
  1

Transfer your coins with multi addresses

bazel-bin/service/tools/utxo/wallet_tool/cpp/utxo_client_tools -c service/tools/utxo/wallet_tool/cpp/client_config.config -m transfer -t bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9,bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn -d bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn -x 0 -v 100,800 -p 303E020100301006072A8648CE3D020106052B8104000A0427302502010104202CB99BBB2AFEB7F48A574064091B34F24781C93AD8181A511C8DCFB2A111AD82 -b 3056301006072A8648CE3D020106052B8104000A03420004F838F3253A5224411D8951AA6EF2BB474EDD283EC088CD13D5404956C0A88079ECF539D9669A3D639A35BF9FD0F67ECBB3D332733C59B0272EB844405B6568D3,3056301006072A8648CE3D020106052B8104000A034200049C8FBD86EA4E38FD607CD3AC49FEB75E364B0C694EFB2E6DDD33ABED0BB1017575A79CC53EC6A052F839B4876E96FF9E4B08ECF23EC9CD495B82ECF9D95303BD

Get the transaction list

Obtain the transaction list from one of the replica nodes. The server config is different from the one used in the transfer, which uses the client one.

bazel-bin/service/tools/utxo/wallet_tool/cpp/utxo_client_tools -c service/tools/utxo/wallet_tool/cpp/server_config0.config -m list -e -1 -n 5

-c	server config points to the server node
-m	function
-e	last transaction id, or -1 points to the last one
-n	the number of utxos needed to be returned

  {"in":[{}],"out":[{"address":"bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9","value":"100"}],"address":"bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn","transactionId":"1"}
  {"out":[{"address":"bc1q09tk54hqfz5muzn9rgalfkdjfey8qpuhmzs5zn","value":"1000","spent":true}]}

Get the wallet value

bazel-bin/service/tools/utxo/wallet_tool/cpp/utxo_client_tools -c service/tools/utxo/wallet_tool/cpp/server_config0.config -m wallet -t bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9

-c	server config points to the server node
-m	function
-t	wallet address to be fetched

  E20230214 18:02:26.936648 41575 utxo_client_tools.cpp:76] address:bc1qd5ftrxa3vlsff5dl04nxg06ku6p4w6enk0cna9 get wallet value:100

Using the NexRes Python SDK

Wed, 01 Feb 2023 00:00:00 +0000

We provide a Python SDK for committing transactions to create and transfer assets. Despite NexRes being written in C++, the code for validating transactions is written in Python so that we can use the cryptoconditions library, which provides functionalities not available in any widely distributed C++ libraries currently.

Install NexRes and Python3.9+

Please check the install tutorial to install NexRes.

After this you will need some additional steps for pybind11 to work, as we are embedding the Python interpreter in the C++ code.

Make sure your Python version is 3.9+. Check the version with

python3 --version

In the .bazelrc file in your nexres directory, have the PYTHON_BIN_PATH reference the location of your python executable. For example, if you have Python installed at /home/ubuntu/.linuxbrew/bin/python3, then it will look like

build –action_env=PYTHON_BIN_PATH=”/home/ubuntu/.linuxbrew/bin/python3”

Then install the Python dev library for your corresponding Python version. These are used when the C++ binary is run.

sudo apt-get install python3.10-dev

If apt cannot find the dev library, you might not have deadsnakes added as a source. You can use the following commands to check your sources and add if needed:

ls /etc/apt/sources.list.d

sudo add-apt-repository ppa:deadsnakes/ppa

Setting Up Virtual Environment

It is heavily advised to set up a virtual Python environment so you do not disturb your system’s Python settings.

sudo apt-get install python3.10-venv

python3 -m venv venv

source venv/bin/activate

Then install the Python dependencies

pip install -r requirements.txt

If you wish to deactivate the virtual environment you can enter

deactivate

Running NexRes KV Service

NexRes needs to be running first for the SDK endpoints to connect to. Go to the resilientdb folder you have downloaded from the resilientdb repository.

Start the KV Service with the example script.

./service/tools/kv/server_tools/start_kv_service.sh

Running Crow Service

We use Crow, a C++ framework for creating HTTP or Websocket web services to connect our SDK to NexRes.

In another terminal shell after starting KV Server, go to the ResilientDB-GraphQL folder that you have downloaded from the ResilientDB-GraphQL repository, build the crow service:

bazel build service/http_server:crow_service_main

Run the binary to start the service:

bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config

You will see this if successful:

  (2022-12-19 06:12:02) [INFO    ] Crow/master server is running at http://0.0.0.0:18000 using 16 threads
  (2022-12-19 06:12:02) [INFO    ] Call `app.loglevel(crow::LogLevel::Warning)` to hide Info level logs

Running the SDK

Check your Python is up-to-date (3.9+)

python3 --version

If your Python version number is too low you may encounter type hinting issues when attempting to run the code

Activating virtual environment

source venv/bin/activate

Running the Driver

Examples of using the driver can be seen in test_sdk.py.

python3 test_sdk.py

You will see the output ‘The retrieved txn is successfully validated’ if successful.

Now you are set with the Python SDK. Below are the design details of the Python SDK.

Validation

Entrypoint

validator.py call the is_valid_tx(tx_dict) function with the transaction json (tx_dict) as the argument.

Transaction Validation Rules

A transaction is said to be valid if it satisfies certain conditions or rules.

We employ a simpler version of the transaction spec and validation rules specified by BigchainDB

JSON Schema Validation

The json structure of a transaction should be the transaction spec v2 of BigchainDB

The output.amount Rule

For all output.amount must be an integer between 1 and 9×10^18, inclusive. The reason for the upper bound is to keep amount within what a server can comfortably represent using a 64-bit signed integer, i.e. 9×10^18 is less than 2^63.

The Duplicate Transaction Rule

If a transaction is a duplicate of a previous transaction, then it’s invalid. A quick way to check that is by checking to see if a transaction with the same transaction ID is already stored. A transaction ID is the hash of the transaction.

The TRANSFER Transaction Rules

if a transaction is a TRANSFER transaction:

TODO: If an input attempts to fulfill an output that has already been fulfilled (i.e. spent or transferred) by a previous valid transaction, then the transaction is invalid. (You don’t have to check if the fulfillment string is valid.)
If two or more inputs (in the transaction being validated) attempt to fulfill the same output, then the transaction is invalid. (You don’t have to check any fulfillment strings.)
The sum of the amounts on the inputs must equal the sum of the amounts on the outputs. In other words, a TRANSFER transaction can’t create or destroy asset shares.

For all inputs, if input.fulfills points to:

a transaction that doesn’t exist, then it’s invalid.
a transaction that’s invalid, then it’s invalid. (This check may be skipped if invalid transactions are never kept.)
a transaction output that doesn’t exist, then it’s invalid.
a transaction with an asset ID that’s different from this transaction’s asset ID, then this transaction is invalid. (The asset ID of a CREATE transaction is the same as the transaction ID. The asset ID of a TRANSFER transaction is asset.id.) Note: The first two rules prevent double spending.

The input.fulfillment Rule

Regardless of whether the transaction is a CREATE or TRANSFER transaction: For all inputs, input.fulfillment must be valid.

Transactions

Transaction structure:

{
    "id": id,
    "version": version,
    "inputs": inputs,
    "outputs": outputs,
    "operation": operation,
    "asset": asset,
    "metadata": metadata
}

Tx ID: The ID of a transaction is the SHA3-256 hash of the transaction, loosely speaking. It’s a string. An example is:

"0e7a9a9047fdf39eb5ead7170ec412c6bffdbe8d7888966584b4014863e03518"

Version: 2.0 (TODO: remove)
Inputs

List of tx inputs
- Each tx input spends a previous tx output
- a CREATE tx must have exactly one input
- a TRANSFER tx should have at least one input
- Transaction inputs and outputs are the mechanism by which control or ownership of an asset
- Amounts of an asset are encoded in the outputs of a transaction, and each output may be spent separately
- To spend an output, the output’s condition must be met by an input that provides a corresponding fulfillment
- Each output may be spent at most once, by a single input
Example of a structure of an element in the input list
```
  {
      "fulfills": {
          "transaction_id": transaction_id,
          "output_index": output_index
      },
      "owners_before": [public_key_1, public_key_2, etc.],
      "fulfillment": fulfillment
  }
```
For create tx, the value for fulfills is None
- Owners_before: public keys
fulfillment: a str as per crypto conditions spec
- The basic steps to compute a fulfillment string are:
  1. Construct the fulfillment as per the crypto-conditions spec.
  2. Encode the fulfillment to bytes using the ASN.1 Distinguished Encoding Rules (DER)
  3. Encode the resulting bytes using “base64url” (not typical base64) as per RFC 4648, Section 5

Outputs

list of Tx outputs

Each output indicates the crypto-conditions which must be satisfied by anyone wishing to spend/transfer that output. It also indicates the number of shares of the asset tied to that output.

output eg:

  {
      "condition": condition,
      "public_keys": [public_key_1, public_key_2, etc.],
      "amount": amount
  }

Condition: its a list or array

  {
      "details": subcondition,
      "uri": uri
  }

subconditions:

ED25519-SHA-256 (We only care about this for NFTs!)
THRESHOLD-SHA-256

  {
      "type": "ed25519-sha-256",
      "public_key": "HFp773FH21sPFrn4y8wX3Ddrkzhqy4La4cQLfePT2vz7"
  }

uri: cost

  "uri": "ni:///sha-256;at0MY6Ye8yvidsgL9FrnKmsVzX0XrNNXFmuAPF4bQeU?fpt=ed25519-sha-256&cost=131072"

Code to compute the uri

  import base58
  from cryptoconditions import Ed25519Sha256
    
  pubkey = 'HFp773FH21sPFrn4y8wX3Ddrkzhqy4La4cQLfePT2vz7'
    
  # Convert pubkey to a bytes representation (a Python 3 bytes object)
  pubkey_bytes = base58.b58decode(pubkey)
    
  # Construct the condition object
  ed25519 = Ed25519Sha256(public_key=pubkey_bytes)
    
  # Compute the condition uri (string)
  uri = ed25519.condition_uri
  # uri should be:
  # 'ni:///sha-256;at0MY6Ye8yvidsgL9FrnKmsVzX0XrNNXFmuAPF4bQeU?fpt=ed25519-sha-256&cost=131072'

Asset

For a CREATE Tx

  {
      "data": {
          "desc": "Laundromat Fantastique",
          "address": "461B Grand Palace Road",
          "international_laundromat_identifier": "bx45-am-333",
          "known_issues": "No known issues. It's fantastique!"
      }
  }

it should just have the data key

For TRANSFER tx

the asset key will have: The id of the tx which has the asset

  {
      "id": "38100137cea87fb9bd751e2372abb2c73e7d5bcf39d940a5516a324d9c7fb88d"
  }

metadata

Bust be any valid associative array or dict (in python) or Null.

  {
      "timestamp": "1510850314",
      "weather_conditions": "So hot that our crayons melted.",
      "location": {
          "name": "Death Valley, California",
          "latitude": "36.457N",
          "longitude": "116.865W"
      }
  }

NOTE: We use the bigchainDB transaction spec v2.

Constructing a Transaction

Set a variable named version to a valid version value. (We need to remove this)
Set a variable named operation to a valid operation value.
Set a variable named asset to a valid asset value.
Set a variable named metadata to a valid metadata value.
Generate or get all the required public keys
Construct a list named outputs of all the outputs that should be in the transaction. (Note: Each output includes a condition.)
Construct a list named unfulfilled_inputs of all the inputs that should be in the transaction. All fulfillment strings should be set to None (We’re building an “unfulfilled transaction” first.)
Construct an associative array (dict) named unfulfilled_tx of the form:

{ "id": null, "version": version, "inputs": unfulfilled_inputs, "outputs": outputs, "operation": operation, "asset": asset, "metadata": metadata }

Note how unfulfilled_tx includes a key-value pair for the "id" key. The value must be your ctnull (e.g. None in Python).

Convert unfulfilled_tx to a serialized json named utx_json.

unicode, sorted keys

 import rapidjson
    
 # input_dict is a dictionary
 json_str = rapidjson.dumps(input_dict,
                             skipkeys=False,
                             ensure_ascii=False,
                             sort_keys=True)

Create inputs as a deep copy of unfulfilled_inputs.
For each input in inputs:
1. If fulfills is None (because this is a CREATE transaction, for example), then let string1 = utx_json, otherwise let string1 = utx_json + output_tx_id + output_index where output_tx_id is the transaction ID of the output that this input fulfills and + means concatenate the strings.
2. Convert string1 to bytes and call the result bytes1.
3. Compute the SHA3-256 hash of bytes1 and leave the result as bytes (i.e. don’t convert to a hex string). Call the result bytes_to_sign.
4. fulfill the associated crypto-condition using an implementation of crypto-conditions. You will need bytes_to_sign and one or more private keys (which are used to sign bytes_to_sign). The end result is usually some kind of fulfilled condition object. Compute the fulfillment string of that fulfilled condition object, and put that as the value of "fulfillment" for the input in question.
Construct a new associative array tx by making a deep copy of unfulfilled_tx.
In tx, change the value of "inputs" to the just-computed inputs (an array of fulfilled inputs).
Compute the transaction ID of tx. Call it id.

The final result (tx) is a valid fulfilled transaction (in the form of an associative array). To put it in the body of an HTTP POST request, you’ll have to convert it to a JSON string.

NexRes Grafana Dashboard Pipeline

Mon, 12 Dec 2022 00:00:00 +0000

During the early stage of development, it is often convenient to target a specific NexRes metric with an all-in-one metric visualization tool. This is easily achieved with the NexRes Dynamic Dashboard (NDD), which abstracts status metrics from NexRes and is presented by Grafana and Prometheus combination. In this post, I will go through how NDD has been designed, what the NDD pipeline looks like, and what is the future of NDD. So, let’s get started it!

Pain Points

Before NDD was developed, NexRes developers could only access status metrics by the log file. Since the current NexRes uses four replica nodes and one client node, the developer needs to open up 5 log files together to monitor the status of NexRes. In addition, log files are static, which means it is not loading in real time. These pain points dramatically reduce the development performance and easily lead to human error. As for all the issues mentioned above, we need a tool to visualize NexRes metrics for better development.

NexRes Dynamic Dashboard Pipeline

NexRes Dynamic Dashboard is our solution. NDD is a Grafana base dashboard for Nexres. It aims to provide a simple real-time interface for developers to monitor and diagnose Nexres. The data metrics is stored in the Prometheus time-series database and queried by Grafana using PromeQL. The system usage data is provided by Prometheus third-party exporter Node Exporter. Here is a simple pipeline archtecture image.

Prometheus is an open-source monitoring and alerting system that is widely used to monitor the performance of cloud-native applications. The Prometheus server collects metrics from the monitored applications and stores them in a time-series database, allowing users to query the data and create alerts based on specified conditions.
Grafana is an open-source platform for data visualization and monitoring. It allows users to create and share dashboards that display real-time data from various sources, such as Prometheus, InfluxDB, and Elasticsearch.
Prometheus-cpp is an open-source C++ library that provides an API for exposing and collecting metrics in a way that is compatible with Prometheus. It allows developers to instrument their C++ applications and servers with Prometheus-style metrics and to expose those metrics to Prometheus servers for collection and visualization.
Node Exporter is a standalone tool that provides an HTTP server that exposes Prometheus-compatible metrics about the host machine to be consumed by the Prometheus server. It runs as a daemon process on a host machine and collects a wide variety of metrics about the host’s hardware and operating system, including CPU and memory usage, disk and network I/O, and more.

Reason for choosing Prometheus

The reason we choose Prometehus is because it using pull mode to store the data. Pull mode refers to the way in which the Prometheus server fetches metrics from the targets it is monitoring. In pull mode, the Prometheus server periodically sends HTTP requests to a list of target URLs to scrape metrics from those targets.

With pull-based monitoring, the Prometheus server is in control of when and how often it gathers metrics from the targets it is monitoring. This allows for centralized control over the monitoring NexRes, and makes it easy to change the monitoring configuration for all targets at once.

Pull-based monitoring can scale more easily than push-based monitoring, as the Prometheus server is able to handle a large number of targets without being overwhelmed. As NexRes replica number can rapidly increase to above 100 nodes, this determation is base on future requirement.

The other reason for choosing prometheus is it support third parity exporter that able to show system status metrics and can be integrated to NexRes by using prometheus-cpp library.

NexRes and Prometheus

The Prometheus integration with your application is to use a third-party library called prometheus-cpp. This library provides a C++ client for Prometheus that can be used to instrument your application and expose metrics in the Prometheus format. As prometheus-cpp support bazel build tool, this made the integration even easilier since NexRes is also using bazel.

To allow Prometheus periodically collect the metrics from NexRes and store them in its time-series database, we developed “prometheus_handler” under statitics class to expose metrics in a format that Prometheus can scrape. Each replica is using different port for exposing their metrics, this allow Prometheus to collect all replicas data simultaneously.

Once the setup is finished, we need to connect Grafana to Prometheus for display NexRes metrics.

Grafana and Prometheus

Prometheus and Grafana are two popular tools used for monitoring and observability. Grafana is a visualization tool that can be used to create dashboards and graphs based on the data stored in Prometheus.

To use Prometheus and Grafana together, a common setup is to have Prometheus scraping metrics from various systems and then feeding that data into Grafana for visualization. This setup is often referred to as a “Prometheus-Grafana pipeline”. Here is the structure of this pipeline.

To create a Prometheus-Grafana pipeline, the first step is to install and configure Prometheus. This typically involves specifying the systems that Prometheus should scrape metrics from and setting up a storage backend for the collected metrics.

Once Prometheus is up and running, the next step is to install and configure Grafana. This involves setting up a data source that points to the Prometheus instance, as well as creating dashboards and graphs to visualize the data.

Once both Prometheus and Grafana are properly configured, they can be used together to monitor and visualize metrics from NexRes. Since all metrics should be properly collected if the NexRes and Prometheus has been connected. Developer can simply using PromQL in Grafana to query NexRes data and build the dashboard.

Please follow this blog to setup Grafana and Prometheus on your system.

Future Improvements

Support more time-series databases in NexRes

As the current phase of NexRes, the Prometheus time-series database is integrated. Since Grafana support various type of time-series databases, such as InfluxDB, OpenTSDB, Graphite, etc. To prevent unexpected things and be more user-friendly, we can develop an abstract layer in NexRes to support various databases. For example, there is “prometheus_handler” under the statistics class, we can have another class called “data_handler” and make “prometheus_handler” to be the subclass of “data_handler”. Following the same pattern, we can build “influx_handler”, and “graphite_handler” under this “data_handler” to support many time-series databases.

Introduce more performance numbers to the dashboard

Go though this google sheet, find out the metrics in TODO list that could introduce to NexRes.

Change embedded Grafana to HTTPs connection

Currently, the Grafana dashboard integrated in nesres.github.io is using http connection. This is a temporality solution that put http connection in https page is a not a secure method. We need to solve this problem in future interation.

Integrate dashboard into Nexres node manager

While Nexres Node Manager is finished, combine the functionality of cloud deployment installer with node manager.

Deploy Prometheus configuration by endpoint setup

This improvement also related to node manager. The current Prometheus configuration file only support 4 nexres replicas. If this number increase in the future, the configuration file and Grafana need to adject according to replica number.

Explore Grafana technique for better visualization

Introduce better visualization to Grafana dashboard.

RCC in NexRes

Tue, 06 Dec 2022 00:00:00 +0000

Here we illustrate why and how to implement RCC in NexRes, compare the RCC implementations in ResDB and NexRes and show the experiment results we got for RCC in NexRes.

The bottleneck in primary-backup BFT protocols

In traditional primary-backup protocols like PBFT¹, a single primary broadcasts client requests to all other replicas. Thus, as the following figure shows, there is an unbalanced overhead of sending messages between primary and backup replicas. As the number of replicas increases, the imbalance is exacerbated. And the system performance bottleneck can be the primary’s outgoing bandwidth when the system is of large scale.

Figure 1. Unbalanced Overhead Between Primary and Backup Replicas

Resilient Concurrent Consensus (RCC)

The Resilient Concurrent Consensus paradigm RCC has been proposed to turn any primary-backup consensus protocol into concurrent consensus by running multiple instances concurrently. RCC is designed with performance in mind and ensures increased resilience against failures².

RCC runs multiple primary-backup consensus instances concurrently, distributing the overhead of broadcasting client requests to other replicas and overcoming the performance bottleneck caused by the primary’s outgoing performance. As the following figure shows, in theory, running concurrent instances has an impressionable positive impact on system throughput.

Figure 2. The Promise of Concurrent Consensus

ResDB vs NexRes

As a global-scale sustainable blockchain fabric, ResilientDB offers a high-throughput yielding distributed ledger built upon scale-centric design principles to democratize and decentralize computation. And RCC has been implemented in ResDB, the older version of ResilientDB. In ResDB, only one thread is assigned to one instance and CPU resources cannot be fully utilized for PBFT or RCC with a small number of instances. So, even though in the Resdb, RCC shows better performance than PBFT, which is consistent with our theoretical expectation, the actual bottleneck of PBFT is CPU utilization rather than bandwidth.

NexRes, the next generation of ResilientDB, assigns multiple threads to one instance, fully utilizing CPU resources to process messages. Then, CPU utilization is not the bottleneck for PBFT in NexRes. Running PBFT in NexRes is capable of saturating the primary’s network bandwidth, which meets the prerequisite for leveraging RCC to improve system throughput.

Implementation

In this section, we will give a brief overview of the implementation of RCC in NexRes. To implement RCC with concurrent instances in Nexres, adjustments in five modules are required: Configuration, Client, Primary, Backup Replica, and Total Ordering.

Configuration

To implement RCC in NexRes, first, we need to make changes in the configuration file, which specifies the number of instances and the primaries in the configuration file.

In the current implementation, we have the first m replicas to be primaries in m-instance RCC.

{
  "region": [
    {
      "replicaInfo": [
					## omitted
      ],
      "regionId": 1
    }
  ],
  "selfRegionId": 1,
  "instance": 4	 # number of instances
}

Client

Clients send requests to all primaries evenly rather than a single primary as it does in PBFT.

uint32_t primary = total_num_ % config_.GetConfigData().instance() + 1;
replica_client_->SendMessage(*new_request, primary);

Primary

Running concurrent instances, replicas in RCC should be able to identify the instance of each message. Thus, for proposal messages, we need to use a field called instance to identify the instance of a proposal. With such a field, replicas can map messages to correct corresponding instances.

When broadcasting proposals, a primary needs to indicate its instance in the proposals.

client_request->set_instance(config_.GetSelfInfo().id());
replica_client_->BroadCast(*client_request);

Backup Replica

When receiving a proposal of instance i, a backup replica needs to check if it is exactly from the primary of instance i.

uint32_t instance_num = config_.GetConfigData().instance();
if ((uint32_t)(request->sender_id()) != request->instance() ||
    (uint32_t)(request->sender_id()) % instance_num != request->seq() % instance_num) 
{
    LOG(ERROR) << "the request is not from a correct primary. sender:"
               << request->sender_id() << " seq:" << request->seq();
    return -2;
 }

Total Ordering

Before executing committed client requests, RCC orders the committed requests between different instances in the same round. So we need a mechanism to determine the execution order of committed transactions in one round. Now we adopt the simplest one, ordering transactions in the same round based on instance id, from the lowest instance to the highest one.

Experiment and Results

Experiment Setup

The experiments are done in AWS. The configuration of the machines we used is shown as follows:

t3.2xlarge
8-vCPUs
32-GiB Memory
Maximum Bandwidth: 600MB/s

The experiments used up to 96 replicas and 4 clients.

Experiment 1 - Scalability

The first experiment is designed to compare the best-case throughput and outgoing bandwidth of RCC and PBFT of different replicas. The throughput and outgoing bandwidth of RCC and PBFT with different numbers of replicas are recorded. The replica number is set to 4, 16, 32, 64, and 96. The batch size is set to 400 and 800.

We denote RCC with batchsize B by RCC-B, and so does PBFT. As the system scales, throughput decreases. RCC-800 outperforms RCC-400, PBFT-800 and PBFT-400, when there are 96 replicas. From the right figure, we can see that PBFT-400 and PBFT-800 are bottlenecked by outgoing bandwidth. And the reason why RCC-400 has a lower performance than RCC-800 is that RCC-400 processes double number of consensus messages. Though RCC-400 gets rid of the bandwidth bottleneck, we’ve found RCC-400 happens to be bottlenecked by computing capability when there are 96 replicas by monitoring its CPU utilization, which is close to the maximal value i.e., 800%.

Figure 3. RCC Scalability Compared to PBFT

Experiment 2 - Batching

This experiment aims to test and record the throughput and outgoing bandwidth usage of PBFT and RCC with 64 or 96 replicas with different batch sizes. The batch size is set to 50, 100, 200, 400, and 800.

Experiment results show that increasing batch size benefits PBFT and RCC throughput when batch size increases from 50 to 400. Nonetheless, it makes no difference for PBFT when increasing batch size from 400 to 800, since PBFT is bottlenecked by outgoing bandwidth shown in Figure 6, while the throughput of RCC still increases.

Figure 4. Batching in RCC and PBFT

Experiment 3 - Larger Transaction Size

In this experiment, we test and record the throughput and outgoing bandwidth of RCC and PBFT, adopting transactions with different sizes but the same execution time. We test systems with 64 and 96 replicas, 1x, 8x, 16x, 24x, and 32x transaction sizes. We set the batchsize to 100.

As we can see from the figure, as the transaction size increases, limited by outgoing bandwidth, PBFT throughput decreases greatly. RCC also shows a throughput performance, but the throughput ratio between RCC and PBFT grows. We can safely draw the conclusion that RCC has a throughput advantage when processing transactions with large sizes.

Figure 5. Performance of RCC and PBFT with Larger Transaction Size

Experiment 4 - Concurrent Consensus

This experiment tests and records the throughput and outgoing bandwidth of RCC with 64 or 96 replicas with different numbers of instances. The batch size is set to 100 and we adopt a 32x transaction size.

In RCC, when there are 1, 2, or 4 instances, system performance is bottlenecked by the primaries’ outgoing bandwidth. As the number of instances increases, throughput increases linearly. The more instances RCC has, the more primaries share the overhead of broadcasting client transactions. With at least 8 instances, the primaries’ outgoing bandwidth is not saturated and the system throughput increases slightly with the instance number.

Figure 6. Effect of Concurrent Consensus on RCC

References

Castro, Miguel, and Barbara Liskov. “Practical byzantine fault tolerance.” OsDI. Vol. 99. No. 1999. 1999. ↩
Gupta, Suyash, Jelle Hellings, and Mohammad Sadoghi. “Rcc: Resilient concurrent consensus for high-throughput secure transaction processing.” 2021 IEEE 37th International Conference on Data Engineering (ICDE). IEEE, 2021. ↩

NexRes Grafana Dashboard Installation

Tue, 06 Dec 2022 00:00:00 +0000

Nexres Grafana Dashboard is a Grafana base dashboard for Nexres. It aims to provide a simple real-time interface for developers to monitor and diagnose Nexres. The data is stored in the Prometheus time-series database and queried by Grafana using PromeQL. The system usage data is provided by Prometheus third-party exporter Node Exporter.

Requirements

Using Nexres dynamic dashboard requires the installation of Prometheus, Node Exporter, Prometheus-cpp, and Grafana. It has been successfully tested with Bazel building in C++17 on Ubuntu 20.04.4 LTS (Windows 11 WSL) and Visual Studio Code.

Installation

Install Prometheus

go to https://prometheus.io/download/ download prometheus

tar xvfz (your-prometheus-tar-file)

Install node_exporter

go to https://github.com/prometheus/node_exporter download the lastest version of node_exporter from release

tar xvfz (your-node-exporter-tar-file)

Install grafana

wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"
sudo apt update 
sudo apt install grafana

Start grafana

sudo service grafana-server start
sudo service grafana-server enable

Default grafana port is 3000

Start the dashboard

Prometheus

Default prometheus port is 9090

./prometheus

Node_exporter

Default node exporter port is 9100

./node_exporter

Local Test

Change the exporter endpoint from the prometheus config (example) to the localhost:port port number can be found from the script (e.g. 8090)
Start prometheus, grafana, and node_exporter
Start the KV service using the script: service/tools/kv/server_tools/start_kv_service_monitoring.sh
Open the prometheus to check the service status: http://localhost:9090/targets?search=
Set up your grafana dashboard from http://locahost:3000/ A grafana dashboard template can be found here.

Remote Deploy

Set the exporter endpoint from the prometheus config with each deploy node (example)
Set node_exporter in each of the deploy node
Set the grafana export point in the deploy script scripts/deploy/script/deploy.sh#L21
Deploy the nodes

Deploy Grafana Dashboard On Oracle Cloud

Tue, 06 Dec 2022 00:00:00 +0000

This article will guide you on deploying NexRes Grafana Dashboard on an Oracle Cloud instance. Since Prometheus and node exporter cannot directly install using apt-get, installing these components is complicated and tedious. NexRes_Grafana_Installer provides an effortless experience to automatically deploy all the components for NexRes Grafana Dashboard on Oracle Cloud. Now let us dive in!

Requirements

This installer only tested on Oracle Cloud instance in ubuntu 20.04. Please adjust the script if you want to run it on AWS or local. Besure nexres is already installed on your instance and fully tested.

Clone nexres_grafana_installer

Clone the repositry in your home directry

https://github.com/jyu25utk/nexres_grafana_installer

Adjust start_nexres.sh

In default, if you cloned resilientdb repositry (nexres) in your home directry. The full directry address should be “/home/ubuntu/resilientdb”. If your nexres working directry is same as I mentioned above, jump to next step.

Otherwise, modify the “start_nexres.sh” file before you process to the next step. Change the following pathes according to your nexres configuration.

SERVER_PATH=/home/ubuntu/resilientdb/bazel-bin/kv_server/kv_server
SERVER_CONFIG=/home/ubuntu/resilientdb/example/kv_config.config
WORK_PATH=/home/ubuntu/resilientdb

Install!

Simply run command

sudo sh install_dashboard.sh

All components should automaticly install to your system!

Make sure to restart your instance using

sudo reboot

Test your dashboard

Find your public ip address, access your grafana interface by using broswer go to

(public ip address):3000

Setup your grafana dashboard as same as the local one

Access prometheus management interface by using broswer go to

(public ip address):9090

Implementing Raft Consensus Protocol for ResilientDB

Background

Consensus

Fault Tolerance

What is Raft?

Raft Leader Elections

Initial Raft Implementation

Implementation Strategy and Architecture

Leader In-Flight Message Throttling

Follow-up Raft Improvements

Persistence

Snapshots

NO-OP Entries

Raft Transaction Batching

Tests

Throughput Improvements

Follower State

Asynchronous WAL Writing

Fast Log Backtracking

Performance Manager Changes

Evaluation

Comparison vs HotStuff-1

Effect of Persistence

Scalability

Commands to Execute

Conclusion

Future Work

Acknowledgements

Further Reading

The World’s First Blockchain-Backed Drawing App? Introducing ResCanvas.

The Existing Problem

Our Solution: ResCanvas

Detailed Architecture and Concepts

Data Model and Stroke Format

Undo/Redo and Edit History

Consistency, Concurrency and Ordering

ResilientDB Theory

Public Rooms vs Private Rooms vs Secure Rooms

Putting cryptographic signatures into use, secure rooms work as follows (assuming ResVault is used):

Security, Privacy and Threat Model

Frontend Design and User Experience

ResCanvas Setup Guide

Prerequisites

Step 0: MongoDB Account Setup

Step 1: Clone the Repository

Step 2: Resilient Python Cache (First Terminal Window)

Setup

Start the Cache Service

Step 3: Backend Setup (Second Terminal Window)

Create Virtual Environment & Install Dependencies

Generate Keys

Create .env File

Step 4: Redis Setup

macOS (Homebrew)

Ubuntu (APT)

Verify Redis

Optional Fix (bcrypt Error)

Start the Backend

Step 5: Frontend Setup (Third Terminal Window)

ResTier: A Tiered Storage Engine for ResilientDB using IPFS

ResTier: A Tiered Storage Engine with IPFS Cold Storage for ResilientDB

Motivation

Architecture Overview

Four Storage Modes

Write Path: Zero Overhead by Design

Read Path: Transparent Auto-Fallback

Migration Flow: Asynchronous Background Thread

Key Design Decisions

Race Condition Safety (Concurrent Reads During Migration)

Secondary Index Design

Crash Recovery

Benchmark Results

Key Findings

Configuration

Configuration Parameters

How to Build and Run

Prerequisites

Step 1: Start IPFS Daemon

Step 2: Build

Step 3: Generate Certificates

1. Performance Testing Engine (`perf_test.sh`)

2. Advanced Metrics Analysis (`analyze.py` & `analyze_record.py`)

3. Real-Time Dashboard (`regression_UI`)