UkweliDB ("truth" in Swahili) is a a tamper proof, verifiable, immutable database, written from scratch in Rust.
1.git clone https://github.com/elviscgn/UkweliDB 2.
cd UkweliDB
1. cd ukweli_cli 2.
cargo build --release
ukweli init
This creates:
~/.ukweli/default.ukweli- Your database file~/.ukweli/config.json- Configuration~/.ukweli/users/- User keypairs~/.ukweli/workflows/- Workflow definitions
Users have cryptographic keypairs for signing records.
| Create a user | ukweli user create thabo |
| List all users | ukweli user list |
| View user details | ukweli user show thabo |
| Simple record | ukweli record append "Thabo registered property #12345" --signers thabo |
| View all records | ukweli record list |
| View specific record | ukweli record show 1 |
| Verify chain integrity | ukweli record verify |
details...
In traditional databases, records can be edited after creation and without leaving a clear trail. For example, someone could change the outcome of a government procurement bid or a financial transaction. This is a problem because auditors reviewing the database later on will have no reliable way to determine whether data has been altered and is trustworthy.
To address this problem, we organize records into a cryptographically linked chain (taking heavy inspiration from how blockchain ensures immutability). Starting with the genesis record (the first record that everything starts from). Each record stores its data (the payload) and a hash of that payload and the hash of the previous record in the chain. This way the hash acts like a digital fingerprint and if you tried to change the payload of any record it would change the hash which in return will break the chain revealing that it was tampered with.
when verifying, this will immediately break and show us where the data was changed.
details...
Now the chain of hashes prevents people from quietly changing history, but we still have a problem; We can't tell who actually created a record nor can we prove who added what. This is where users and signatures come into play.
Every user in the system has a cryptographic key pair. A private key to sign records and a public key that anyone can use to verify that signature. When a user creates a record, they sign the record's hash, then the record keeps a list of their signatures so that later on anyone can check was this really created by these people
The first record is still the starting point, signed by the system. Every other record now shows who approved it. With the hash chain, this means you can’t alter the data or lie about who did it. Tampering breaks the chain, and signatures confirm who was responsible.
details...
So far we have a working ledger that is immutable and we can trace who signed what. However in real systems this isnt enough. Even if the right people signed a record, there still needs to be some rules on when things can happen. For example let's say I was writing a procurement system for the South African government. A tender wouldn't just jump around randomly it would move through something like call_for_bids to bidding_open then evaluation then awarded and so on. To implement this our db needs to have rules about when things happen.
To do this we'll implement a workflow engine. Instead of allowing any signed record, the ledger now has to check whether the action about to be logged makes sense based on the state of an entity.
Each box is a state and the diagram above shows the lifecycle of one entity, like a tender or a delivery. The arrows show the only way you are allowed to move. So you can't skip steps or go backwards unless the workflow allows it.
Initially I wanted this database to be for a goverment procurement system, given how rampant corruption is in my country. But then I wondered why not for other fields that need an immutable and verifiable db, so as a result workflows will be fully customisable with a .yaml file that engineers working in goverment or companies can use to customise our database to their use cases :)
Oversimplified example:
workflow:
name: procurement
version: 1
states:
- open
- awarded
transitions:
- from: open
to: awarded
action: award_contract
required_roles:
- procuring_officer
- finance_approver