VerChain

Check the last release (v0.3.0)

---

This project is a Blockchain-Based Identity Verification System, and it's main objective to enhance the security and privacy when it comes to digital credentials. By using the Blockchain technology we assure that the data won't be changed (immutable), decentralized and hashed in the blockchain so it won't be reviled to anyone.

System Objective

The system will act as a verifier that checks if a specific user owns a specific credential, this way the system won't store any credentials or user's personal information, applying the decentralization mechanism to ensure that the customer has his own information not the system.

What is a Peer-to-Peer Network

The Peer

A peer is a single computer or "node" that acts as both client and a server at the same time. Unlike a traditional setup where a client talks to a big central computer, in a P2P network, every participant has equal status and responsibilities.

The Ledger

The ledger is not a built-in feature of the library itself, but rather a data structure implemented inside the Node class to store the blockchain.

The library facilitates the connection between peers, but the ledger is the actual storage container for the CHID records.

Verification

During the "Verifying" path, the ledger acts as the reference point for the system:

• Querying: When a user requests verification, the system searches the ledger for a matching CHID hash.

• Ownership Check: The ledger provides the "proof" (the stored hash) that the system needs to perform the DECOwnershipCheck against the user's HID.

Initialization & Connection

• Node(host, port, id=None): Creates the node.
  • Usage: Uses the BlockchainAddress to set the host and port.
• start(): Spawns a background thread to listen for other nodes
• connect_with_node(host, port): Outbounds connection.
  • The system node uses this to join the blockchain network.

Communication

The networking functionality is done by the Network class which inherits the Node class to act as a peer.

• broadcast(data): Sends a dictionary to all connected peers.

  • Used to broadcast a newBlock after a successful registration.

• send(node, data): Sends data to one specific peer.

  • Used by a blockchain node to send a specific CHID back to the requester.

The "Callback" System

The library is event-driven. You don't pull data; you "react" to it by overriding these methods in the system.

node_message(self, connected_node, data) This is the most important function for the project. It is triggered whenever any data arrives, and the incoming data are handled by the Interaction class, that takes the Payload object.

• Parameters:
  • connected_node: The node object that sent the message.
  • data: The dictionary containing the custom protocol (e.g., action, childHash ). This is where the if/elif statements to handle Registration, Querying, or Verification Responses.

outbound_node_connected(self, connected_node): Gets triggered when an outbound node is connected to the network.

inbound_node_connected(self, connected_node): Runs when a node is connected to the network.

inbound_node_disconnected(self, connected_node): Runs when a connected node, is disconnected.

Key Principles

• Privacy: raw credentials remain off-chain and with the holder.
• Immutability: on-chain CHIDs are tamper-evident.
• Decentralization: blockchain acts as a shared ledger for references, not as a credential store.

Actors

• Holder (User): owns credentials and proves possession.
• Issuer (Authority): verifies real-world claims and issues credentials.
• Verifier (System): checks on-chain references to confirm ownership.

Data model

CHID (Credential Holder Identifier) is a compact reference stored on-chain:

CHID = "HID:CID:AUTHID"

• HID — Holder ID (derived from holder identity)
• CID — Credential ID (derived from credential data)
• AUTHID — Authority/Issuer ID

All IDs are deterministic hashes (e.g., SHA-256) generated by the system when actors/credentials are created or approved.

Workflow

1. Issuance: Authority verifies a holder and approves a credential.
2. CHID generation: system derives HID, CID, AUTHID and computes CHID.
3. On-chain registration: CHID is stored on the blockchain as a reference.

Usage (examples)

Prerequisites: Python 3.8+, install package in editable mode:

pip install -e .

Example Python usage (illustrative):

# Create the identities: User, Authority and the Identity.
fake_user = User(name="", nationalNumber=0, phone=0, age=0, email="", birth="")

user = User(name="Testing the Chain Validation - 2", nationalNumber=2312311,
            phone=444, age=24, email="", birth="")

issuer = Authority(name="JPUF", businessID=3423)

doc = Identity(user=user, issuer=issuer, image="", credentialID=333)

chid = CHID(user=user, credential=doc, issuer=issuer)

block = Block(data=chid)

Blockchain = Peer("blockchain", "localhost", 8281)


Blockchain.start()

Blockchain.registerBlock(block=block)

ownershipQwery = Qwery(user=user, credential=doc)

# Running the query
Blockchain.verifier.processQwery(ownershipQwery)

Blockchain.stop()

Development

• Install dependencies: pip install -r requirements.txt (or use pip install -e .)
• Run tests (if any): pytest

Contributing

Bug reports, issues and pull requests are welcome. Follow standard fork-and-PR workflow.

License

Specify the project license in LICENSE file.

Contact

Maintainer: Bashar Mithan Repository: https://github.com/BasharMithan/Blockchain-based-Identity-Verification-System

To be added

• System CLI.
• Image input handling