A fault-tolerant distributed bank — Multi-Paxos consensus over gRPC, catch-up recovery, and concurrent transaction processing. Built from scratch in Java with Spring Boot.

A distributed transaction processing system that uses a modified Multi-Paxos protocol to achieve consensus across 5 replica servers. When a server has insufficient balance for a transaction, it triggers a Paxos round to reconcile state across the cluster, then applies the agreed-upon transaction block. Includes a catch-up mechanism for lagging nodes and exponential back-off for concurrent proposer conflicts.

Skills demonstrated: Distributed systems · Consensus protocols · gRPC · Protobuf · Concurrent programming · Fault tolerance

I implemented the full Paxos consensus pipeline and supporting infrastructure:

• Modified Prepare/Promise phase — Extended the protocol to detect follower lag, proposer lag, and concurrent ballot clashes. Acceptor logic returns special ballot codes (-10, -20, -30, -40) to signal catch-up needs or back-off.
• Async Prepare/Accept/Commit — Used CompletableFuture and gRPC deadlines to run consensus phases in parallel across all 5 nodes, with majority quorum (3) and configurable timeouts.
• Catch-up mechanism — Dedicated worker thread and gRPC service for lagging nodes to fetch missing transaction blocks from a target server and commit them locally before rejoining Paxos.
• Transaction processing worker — Background ScheduledExecutorService that dequeues transactions and triggers Paxos when balance is insufficient, with retry logic for CatchUpInProgressException, ConcurrentPaxosRoundException, and PaxosMajorityFailedException.
• Protobuf schema — Defined consensus.proto and catchup.proto for Prepare, Promise, Accept, Commit, and catch-up RPCs.

The BankServer/BankClient scaffolding, gRPC stubs, and basic transaction enqueue flow were provided; I designed and implemented the consensus logic, state machine, and recovery paths.

flowchart TB
    subgraph Client["BankClient"]
        TC[TransactionController]
        CSV[CSVTransactionReader]
        TC --> CSV
    end

    subgraph Servers["5 Replica Servers (gRPC)"]
        direction TB
        TS[TransactionService]
        CS[ConsensusService]
        CU[CatchUpService]
    end

    subgraph Consensus["Paxos Pipeline"]
        direction LR
        P[Prepare] --> Pr[Promise]
        Pr --> A[Accept]
        A --> C[Commit]
    end

    subgraph Workers["Background Workers"]
        TW[Transaction Worker]
        CW[CatchUp Worker]
    end

    TC -->|sendTransactionSet| TS
    TS -->|enqueue| TW
    TW -->|insufficient balance| Consensus
    Consensus --> CS
    CW -->|requestCatchUp| CU
    CU -->|blocks| CW

┌─────────────┐     gRPC      ┌──────────────────────────────────────────────────┐
│ BankClient  │ ──────────────▶│ BankServer (×5 replicas)                         │
│ (CSV input) │               │   ├── TransactionService (enqueue)               │
└─────────────┘                │   ├── ConsensusService (Prepare/Accept/Commit)    │
                              │   ├── CatchUpService (sync lagging nodes)         │
                              │   └── Workers: transaction queue, catch-up loop   │
                              └──────────────────────────────────────────────────┘

Java 11 · Spring Boot 2.5 · gRPC · Protocol Buffers · Lombok · Maven

Prerequisites: Java 11, Maven

1. Build and run 5 server replicas (one per host/port):

cd BankServer
mvn clean compile
# Run 5 instances, each with different grpc.server.port (e.g. 9091–9095)

2. Configure server ports in BankServer/src/main/resources/application.yml:

grpc:
  host: <host-machine>   # e.g. localhost or target platform hostname
  port1: 9091
  port2: 9092
  port3: 9093
  port4: 9094
  port5: 9095
  server:
    port: 9089   # Override per instance

3. Run the client with a CSV transaction file:

cd BankClient
mvn clean compile exec:java -Dexec.mainClass="org.koatech.bankclient.BankClientApplication"
# Or pass CSV path via your environment / config

4. CSV format (example): Each row defines a transaction set; columns include live servers and transaction tuples. See BankClient/src/main/resources/transactions.csv for a sample.

MIT — see LICENSE for details.