VerChain

Check the last release (v0.5.0)

---

This project is a Blockchain-Based Credential 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 Credential)
• 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

Prerequisites: Python 3.11+.

pip install -e . -r requirements.txt

Run a node

cd source
python main.py

main.py starts a node on P2P port 8000; its HTTP API listens on the P2P port plus 10000 (http://localhost:18000, Swagger UI at /docs). The first start creates and mines the genesis block in storage/.

In Python code, create a Verchain instance and choose either startup entry point:

from core.verchain import Verchain

verchain = Verchain("Blockchain", "localhost", 8000, isBootstrap=False)
verchain.start()      # Start the P2P network; the API starts during initialization
# or: verchain.cli.start()  # CLI entry point; CLI commands are being added

The node's HTTP server is managed by VerchainAPI; API and CLI processing is handled by the VerchainProcessor service.

Register a credential

The credential is uploaded as a PDF. Only hashes are stored on-chain.

curl -X POST http://localhost:18000/register \
  -F "user.name=Alice" -F "user.nationalNumber=123456" -F "user.phone=5551234" \
  -F "user.age=24" -F "user.email=alice@example.com" -F "user.birth=2002-01-01" \
  -F "credential.documentID=101" \
  -F "issuer.name=JPUF" -F "issuer.issuerID=3423" \
  -F "credential.document=@diploma.pdf;type=application/pdf"

Verify ownership

Upload the same PDF with the same IDs:

curl -X POST http://localhost:18000/check \
  -F "username=Alice" -F "userID=123456" -F "documentID=101" \
  -F "issuer=JPUF" -F "issuerID=3423" \
  -F "document=@diploma.pdf;type=application/pdf"
# "APPROVED"

A changed file or a wrong documentID returns 404 (Credential-not-found). See docs/API.md for every endpoint and response.

Settings

settings.yml controls the mining difficulty, the upload limit and the performance mode. SAFE re-validates the whole chain on every insert; FAST validates only the new block.

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
• Contact email: basharmithan@gmail.com

To be added

• System CLI.