Reconcile

A proof of concept settlement and reconciliation system built with Haskell.

Overview

Reconcile is a financial reconciliation system designed to demonstrate the power and safety of Haskell for building robust financial applications. It implements a domain-driven design approach with a strong focus on type safety, immutability, and validation.

This project was created as part of a self-learning initiative to explore whether Haskell can effectively handle complex financial and commercial applications. The results have been promising, showing that Haskell's strong type system and functional approach provide excellent guarantees for financial data processing.

Project Structure

The project is organized into several key components:

• Domain Layer (src/domain): Core business concepts and rules
• Persistence Layer (src/persistence): PostgreSQL database integration
• OnChain Layer (src/onchain): Plutus smart contracts and blockchain integration
• API Layer (planned): REST API for interacting with the system
• Reconciliation Engine (planned): Core reconciliation logic

Key Features

• Type-Safe Financial Models: Comprehensive domain models for financial entities
• PostgreSQL Persistence: Robust database layer with advanced features
• Currency Handling: Support for all ISO 4217 currencies with proper decimal handling
• Card Processing: Secure handling of card details with validation
• Transaction Management: Flexible transaction model supporting various payment types

Technical Highlights

• Domain-Driven Design: Clear separation of domain and infrastructure concerns
• Strong Type Safety: Leveraging Haskell's type system to prevent runtime errors
• Immutable Data Structures: Ensuring data integrity throughout the application
• Comprehensive Validation: Validation at all levels of the application
• Optimized Database Access: Computed columns and strategic indexing for performance

Future Plans

• Reconciliation DSL: A domain-specific language for defining reconciliation rules
• Payment Processor Integration: Modules to read transactions from various payment processors
• Cloud Deployment: Integration with AWS or other cloud platforms through Docker or Kubernetes
• Reporting Engine: Advanced reporting capabilities for financial analysis
• Real-time Processing: Stream processing for continuous reconciliation

Getting Started

Prerequisites

• GHC 9.6.6 or later
• PostgreSQL 12 or later
• Cabal 3.10.2.0 or later
• Git
• Autotools (autoconf, automake, libtool) for building cryptographic libraries

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/reconcile.git
   cd reconcile
   

2. Run the build script to set up cryptographic libraries and build the project:

   ./build.sh
   

   This script:

   • Builds the BLST library (BLS12-381 signatures) from source
   • Builds the secp256k1 library (used in Bitcoin, Ethereum, and Cardano) from source
   • Builds the libsodium library (general-purpose cryptographic library) from source
   • Installs these libraries locally in the project's lib directory
   • Runs cabal update and cabal build

   These cryptographic libraries will be used in future development for Plutus smart contracts and Cardano blockchain integration.

   Build Script Options:

   ./build.sh [options]
   
   Options:
     clean    Clean previous builds before building
     test     Run tests after building
     verbose  Show detailed build output
   
   Examples:
     ./build.sh              # Just build the project (quiet by default)
     ./build.sh test         # Build and run tests (quiet by default)
     ./build.sh clean        # Clean and build (quiet by default)
     ./build.sh verbose      # Build with detailed output
     ./build.sh clean test   # Clean, build, and run tests (quiet by default)
   

   Note: These cryptographic libraries are required dependencies. The build script is the recommended way to install them correctly for your platform.

   Important: To use cabal commands directly (outside of the build script), you need to set up direnv as described in the next section. This ensures that the necessary environment variables are available to find the cryptographic libraries. Without proper environment setup, direct cabal commands will fail when trying to build the project.

Environment Setup with direnv

The build script automatically generates a .envrc file for use with direnv, which allows you to use cabal commands directly without going through the build script.

1. Install direnv:

   # macOS with Homebrew
   brew install direnv
   
   # Linux (Ubuntu/Debian)
   sudo apt-get install direnv
   

2. Add direnv hook to your shell: Add this line to your shell configuration file (.bashrc, .zshrc, etc.):

   eval "$(direnv hook bash)"  # or zsh, fish, etc.
   

   Then restart your shell or run source ~/.zshrc (or equivalent).

3. Allow direnv in your project directory:

   cd reconcile
   direnv allow
   

4. Using with VSCode: If you use VSCode, install the direnv extension for proper integration. This is essential for the Haskell Language Server extension to work correctly with this project:

   • The Haskell Language Server needs access to the cryptographic library paths
   • Without the direnv extension, VSCode won't be able to resolve Cardano dependencies
   • After installing the extension, restart VSCode and ensure you've run direnv allow in the project directory
   • You should see a notification that direnv has been loaded when you open the project
   • Note: The Haskell Language Server may take longer than usual to initialize (up to several minutes) due to the complex cryptographic library dependencies. This is normal and only happens during the initial load or after major changes.

After setting up direnv and running direnv allow, you can use cabal commands directly in your terminal or editor, and they will have access to all the necessary environment variables for the cryptographic libraries.

Running Tests

To run tests, use the build script with the test parameter:

./build.sh test

Project Status

This project is currently in the proof-of-concept stage. The core domain model and persistence layer are functional, but many planned features are still under development.

Why Haskell for Financial Applications?

Haskell offers several advantages for financial applications:

1. Type Safety: Catch errors at compile time rather than runtime
2. Immutability: Prevent unintended data modifications
3. Referential Transparency: Make code easier to reason about and test
4. Concurrency: Handle multiple operations safely
5. Correctness: Express complex business rules clearly and correctly

This project demonstrates that Haskell can effectively handle the complexities of financial reconciliation systems while providing strong guarantees about correctness.