DepChain is a simplified permissioned blockchain system with high dependability guarantees.
This repository contains documentation and source code for this Highly Dependable Systems (SEC) project.
The REPORT document provides an overview of the key technical decisions, our implementation and some tests we performed. This remaining README explains how to run the project.
- This project uses
Java 21,Maven,Python(scripts for hashing public key and genesis file hash) andjq(for JSON manipulation).
First of all, you need to generate the configuration files (with the membership), to generate the membership files and the genesis file.
For this, we assume you have the jq command available (we use it for JSON manipulation).
To generate the configuration files:
cd scripts
./createMembership.shWithout this, mvn clean install will fail because it runs tests that require the configuration files.
However, mvn clean install -DskipTests will work.
This also generates the genesis-file.json that will be necessary to generate the genesis block.
From the root directory of the project, run the following command:
mvn clean installThis can take some time (around 3 minutes) since it will run the tests.
If you want to ignore the tests, run the following command instead:
mvn clean install -DskipTestsIf you just wish to test the project, skip to the Testing the Project section.
First of all, you need to generate the configuration file (with the membership). To do that, run the following command:
cd scripts
./createMembership.shTo run the members:
cd member
./startMembers.shYou can check each member's log at the member/logs directory.
To run a client (it's very important to pass it a name for a client that exists in the createMembership.s
8463
h's
client list, like paulo, joao or pedro, since they're the ones that we generate private and public keys for).
You can add more clients to the createMembership.sh script, but don't forget to run the script to regenerate the configuration files.
cd client
mvn compile exec:java -Dexec.args="2000 paulo 0"The third argument is the client's byzantine behaviour. It can be:
- 0: no byzantine behaviour
- 1: fakes signatures
- 2: performs replay attacks
Now, at the client, you can send these types of messages to the server (CoinType is either ISTCoin or DepCoin):
QUIT | EXIT: exits the clientHELP: prints the help info<CoinType> BALANCE <address><CoinType> TRANSFER <address> <amount>"ISTCoin TRANSFER_FROM <owner> <to> <amount>"ISTCoin APPROVE <spender> <amount>"ISTCoin ALLOWANCE <owner> <spender>"ISTCoin BLACKLIST <address>"ISTCoin UNBLACKLIST <address>"ISTCoin ISBLACKLISTED <address>"
Note that the majority of operations are only available for ISTCoin.
Member Tests
Go to the member directory:
cd memberTo run all tests:
mvn testTo run a specific test (example with the regular test):
mvn test -Dtest=RegularTest#testBlockChainNormalBehaviourThe tests that we have are:
Byzantine Client
testWithWrongSignatureClient(inByzantineClientTest): tests the system with a Byzantine client that sends a fake signaturetestWithReplayAttackClient(inByzantineClientTest): tests the system with a Byzantine client that waits for a block to be decided, grabs a transaction, and attempts to send a request to replay the transaction
Byzantine Member
testConsensusWithIgnoringByzantine(inByzantineClientTest): tests the system with a Byzantine member that ignores all messagestestConsensusWithSpamByzantine(inSpamMemberTest): tests the system with a Byzantine member that sends a lot of equal messages (READs, STATEs, etc...)testConsensusWithMemberFakeSignature(inFakeSignatureMemberTest): tests the system with a Byzantine member that sends messages with fake signatures. We assert if the fake signature is detected, if the consensus still works and the transactions are decided correctlytestConsensusWithWrongState(inWrongStateMemberTest): tests the system with a Byzantine member that sends a wrong state message in the second instance. We assert if the consensus still works (that the same transaction isn't executed twice)
Regular Test
testBlockChainNormalBehaviour: tests the normal behaviour of the blockchain, sending transfers between all clients and checking if the allowance mechanism is working properly
TODO: remove?
testConsensusWithWrongWriteAcceptByzantine: tests the consensus algorithm with a Byzantine member that sends wrong WRITEs and ACCEPTstestConsensusWithByzantinePerfectLink: tests the consensus algorithm when all members have a Byzantine perfect link, where messages can be lost, duplicated, reordered or corrupted.
Contract Tests From root:
cd contractTo run all tests:
mvn testThe tests that we have check if:
- The contract outputs normal info (name, symbol, decimals)
- The blacklist functionality works
- The
transferandtransferFromprimitives work as expected - The
blacklistandunblacklistprimitives work as expected
To manually run tests and test the program, use this command to launch all members (no Byzantine):
./startMembers.shOr this command if you want a Byzantine member to be present:
./membersWithByzatine.sh <byzantineBehaviour>Where <byzantineBehaviour> can be one of the following:
- '0': normal
- '1': ignore messages
- '2': send a wrong state message
- '3': fake signature
- '4': replay signature (Don't use this one, it's not working as intended)
- '5': spam messages (STATEs, WRITEs...)
- '6': send wrong writes and accepts
Afterwards (very important to be paulo, joao, pedro or some client that you generated the keys for), run the client:
cd client
mvn compile exec:java -Dexec.args="2000 paulo 0"Send requests:
ISTCoin transfer <address> <amount>
ISTCoin balance <address>
[...]Check the logs at the member/logs directory.