Tamper-Evident Digital Udhaar (Credit) Ledger for a Kirana Store (Python, MySQL)

SahiKhata is a tamper-evident digital version of the udhaar bahi-khata — the ruled credit register that sits behind the counter of almost every Indian kirana store, where the shopkeeper writes down what each regular customer takes on credit and strikes it off when cash is paid. Pages tear, entries get overwritten, amounts are disputed at the end of the month, and the register is the only copy in existence.

This project rebuilds that register as a small web application with one property a paper book can never have: the entries cannot be quietly altered. Every credit sale and repayment is hashed with SHA-256 and linked to the hash of the previous entry. At closing time the day's entries are sealed into a block whose header carries the previous block's hash and a small simulated proof-of-work — the same pattern a real blockchain uses, implemented in plain Python on top of MySQL.

A Verify Chain screen recomputes the whole chain on demand and pinpoints the exact record where any tampering happened, which makes a memorable live demo for the viva.

The stack is deliberately beginner-friendly: Python and Flask for the application, MySQL for storage, with the hash functions coming from Python's built-in hashlib. This is a simulated blockchain — there is no public network or cryptocurrency — which is exactly the depth an individual BCSP-064 project should attempt and defend.

A neighbourhood kirana store extends credit to its regular customers through a paper udhaar register. The register is the single, unbacked copy of who owes what, and it offers no protection: a page can be torn out, an amount overwritten after the fact, a repayment strike-off disputed, or an employee quietly erase a debt. At month end the shopkeeper hand-tallies the book, and every mismatch becomes an argument that neither side can prove. Even when the store moves to Excel or a simple billing app, the same integrity problem remains, because any row of a spreadsheet or database table can be edited silently.

There is a need for a ledger that is append-only in practice — where recording a sale is easy but secretly altering or deleting a past record becomes impossible to hide — together with customer statements, dues reports and backups, at a cost and complexity a single-shopkeeper business can afford.

Abstract

SahiKhata is an individual BCA final-year project that digitises the credit (udhaar) register of a neighbourhood kirana store as a tamper-evident, hash-chained ledger. Each credit sale and repayment is recorded as an event that carries its own SHA-256 hash and the hash of the previous event. At day end the events are sealed into blocks linked by block hashes, with a simulated proof-of-work. A verification routine can prove the ledger has not been altered and locate any tampering precisely. The application is built with Python, Flask and MySQL.

Introduction

The udhaar register is one of the oldest databases in India. A typical store has 100–300 regular customers; the shopkeeper records a few dozen credit entries a day and settles accounts weekly or monthly. The register works, but it offers no integrity: a page can be torn out, an amount overwritten, a repayment strike-off disputed, or a dispute settled by whoever remembers best. The shopkeeper also has no backups — losing the book loses the entire receivables list.

Existing System

• Credit entries live in a paper register; repayments are struck off with a pen.
• Any party with physical access can alter or remove a record without a trace.
• Month-end totals are calculated by hand, causing reconciliation disputes.
• There is no customer-wise statement, no dues report and no backup.
• Computerised alternatives (Excel sheets, basic billing apps) fix the arithmetic but not the integrity problem: a cell or row can still be edited silently.

Proposed System

• A web application where the shopkeeper (and a limited assistant role) record credit sales and repayments.
• Every ledger event stores a canonical representation, its SHA-256 hash, and the hash of the previous event, forming a hash chain.
• A nightly/optional close the day action seals the day's events into a block whose header contains the previous block's hash, a Merkle-style summary root and a nonce found by a small proof-of-work simulation (hash must start with two zeros).
• A Verify Chain page recomputes all hashes and reports the first inconsistent event or block, proving tampering.
• Customer statements, outstanding-dues reports, daily closing summaries and CSV export.
• Secure login with hashed passwords, session timeout and an audit log of privileged actions.

Feasibility Study

• Technical: Python's standard library provides hashlib and hmac; Flask and MySQL are installed with a few commands and run comfortably on an i3 laptop. All logic is local — no blockchain node, cloud account or internet dependency is needed for the demo.
• Economic: Zero licence cost; everything is open source.
• Operational: The interface mirrors the mental model of the register (customer page, add entry, settle up). A shopkeeper needs one short walkthrough; the assistant role is read-and-add only.

In scope

• A single store with two roles: Shopkeeper (full control) and Assistant (add entries only).
• Customers managed by name and phone number — no government ID numbers are stored.
• Credit-sale events and repayment events, both hash-chained in one ledger.
• Close-the-day sealing into blocks with the simulated proof-of-work.
• Verify Chain audit page, customer statements, dues report, daily summary, CSV export.
• Designed for a few thousand events per year — the scale of one shop.

Out of scope (v1)

• A public blockchain, cryptocurrency, wallets or any real distributed network.
• WhatsApp/SMS payment reminders and online payment collection.
• Multi-store or franchise deployment.
• Barcode scanning and inventory management.
• Handwritten-register import (future scope).

The project follows the Waterfall model with a verification checkpoint at the end of each phase. This suits an individual, part-time IGNOU project because the requirements are small and stable (one shop, two roles, one ledger), the developer works alone, and each phase produces a reviewable document for the guide.

Testing approach: unit tests cover the pure hash/chain functions (known-vector tests for SHA-256, chain-tail update, block-header recomputation); tamper tests deliberately UPDATE a stored amount, re-run verification and assert that the exact event is reported; black-box test cases cover every screen with documented input/expected/actual columns.

SahiKhata is a three-tier web application:

1. Presentation tier — server-rendered Jinja templates styled with plain CSS, plus a little JavaScript for the statement print view. Works on the shop laptop and a phone browser.
2. Application tier — Flask blueprints (auth, customers, ledger, blocks, reports). All business rules — validation, canonical formatting, hashing, chain linking, block sealing, verification — live here, never in the browser.
3. Data tier — MySQL, accessed exclusively through parameterised queries. Ledger and block tables are effectively append-only: the application never issues UPDATE or DELETE on them.

flowchart LR
  U[Browser: Shopkeeper / Assistant] -->|HTTPS| F[Flask app]
  F --> A[Auth and session check]
  A --> C[Customers blueprint]
  A --> L[Ledger blueprint]
  A --> B[Blocks blueprint]
  L --> H[Hash-chain engine: SHA-256]
  B --> P[Proof-of-work simulation]
  H --> Q[Parameterised queries]
  Q --> DB[(MySQL)]
  B --> V[Verify-chain audit]

ER diagram

erDiagram
  USER ||--o{ LEDGER_EVENT : records
  CUSTOMER ||--o{ LEDGER_EVENT : "is involved in"
  BLOCK ||--o{ LEDGER_EVENT : seals

  USER {
    string id PK
    string username UK
    string passwordHash
    string role
  }
  CUSTOMER {
    string id PK
    string name
    string phone
    decimal outstanding
  }
  LEDGER_EVENT {
    string id PK
    string customerId FK
    string type
    string itemsSummary
    decimal amount
    datetime createdAt
    string entryHash
    string prevEntryHash
    string blockId FK
  }
  BLOCK {
    string id PK
    date blockDate
    string prevBlockHash
    string summaryRoot
    int nonce
    string blockHash
    int eventCount
  }

DFD — Level 0 (context diagram)

flowchart LR
  S([Shopkeeper]) --"credit sales, repayments, close day"--> SYS(("SahiKhata Ledger"))
  SYS --"statements, dues, verification result"--> S
  A2([Assistant]) --"credit sales only"--> SYS
  C([Customer]) --"cash repayment"--> S
  SYS --"printed statement"--> C

DFD — Level 1

flowchart TD
  S([Shopkeeper]) --> P6[6.0 Authenticate]
  P6 <--> D1[(D1 Users)]
  S --> P1[1.0 Record ledger event]
  A2([Assistant]) --> P1
  P1 <--> D2[(D2 Customers)]
  P1 <--> D3[(D3 Ledger Events)]
  S --> P2[2.0 Seal daily block]
  P2 <--> D3
  P2 <--> D4[(D4 Blocks)]
  S --> P3[3.0 Verify chain]
  D3 --> P3
  D4 --> P3
  P3 --"verification result"--> S
  S --> P4[4.0 Manage customers]
  P4 <--> D2
  S --> P5[5.0 Statements and reports]
  D2 --> P5
  D3 --> P5
  P5 --"statement / CSV"--> S

DFD — Level 2 (process 1.0 exploded)

flowchart TD
  S(["Shopkeeper / Assistant"]) --> P11["1.1 Validate entry form"]
  P11 --"rejected"--> S
  P11 --"validated event"--> P12["1.2 Build canonical string and compute SHA-256"]
  D3[(D3 Ledger Events)] --"current chain tip hash"--> P13["1.3 Link to previous hash"]
  P12 --> P13
  P13 --"event with hash and prevHash"--> P14["1.4 Append inside one transaction"]
  P14 --> D3
  P14 --"new outstanding"--> D2[(D2 Customers)]

Use-case diagram

flowchart LR
  S([Shopkeeper])
  A([Assistant])
  subgraph SK[SahiKhata]
    UC1(Login)
    UC2(Add customer)
    UC3(Record credit sale)
    UC4(Record repayment)
    UC5(Close day / seal block)
    UC6(Verify chain)
    UC7(Print statement)
    UC8(View dues and export CSV)
  end
  S --- UC1 & UC2 & UC3 & UC4 & UC5 & UC6 & UC7 & UC8
  A --- UC1 & UC3 & UC7

• External anchoring: publish each sealed block's hash as a QR code on the shop noticeboard, or optionally write it to a public blockchain testnet, so even a full local database rewrite can be detected against an external copy.
• Reminder integration: WhatsApp/SMS nudges for customers whose dues cross an age threshold.
• Register migration: photograph each page of the old paper register and semi-automatically seed the opening balances.
• Offline-first PWA so the app keeps working when the shop's broadband drops, syncing later.
• Migration path to a permissioned blockchain such as Hyperledger Fabric for a federation of stores — a natural upgrade story for the same project.