PHPackages amreljako/laravel-ledger-guard - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. amreljako/laravel-ledger-guard ActiveLibrary[Security](/categories/security) amreljako/laravel-ledger-guard ============================== A highly secure, tamper-evident financial ledger and double-entry wallet system for Laravel with built-in anti-race condition mechanisms. v1.0.0(yesterday)00MITPHPPHP ^8.1 Since Jun 18Pushed yesterdayCompare [ Source](https://github.com/amreljako/laravel-ledger-guard)[ Packagist](https://packagist.org/packages/amreljako/laravel-ledger-guard)[ RSS](/packages/amreljako-laravel-ledger-guard/feed)WikiDiscussions main Synced today READMEChangelogDependencies (2)Versions (2)Used By (0) Laravel LedgerGuard =================== [](#laravel-ledgerguard) [![Latest Version on Packagist](https://camo.githubusercontent.com/edf763613510ac9ba1e6e2e986e5e5ed107c7bf29e421c1f0f45265b279d7f79/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d72656c6a616b6f2f6c61726176656c2d6c65646765722d67756172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/amreljako/laravel-ledger-guard)[![GitHub Stars](https://camo.githubusercontent.com/281820f479cd9f7adbdba7b4e802cfa27df7edd9f4987b620881f0aa2d2335a0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f616d72656c6a616b6f2f6c61726176656c2d6c65646765722d67756172642e7376673f7374796c653d666c61742d737175617265)](https://github.com/amreljako/laravel-ledger-guard/stargazers)[![Total Downloads](https://camo.githubusercontent.com/8b429c82bbf515c6cdb3f28a22d4ef5d3e684676b374b7b71aec6b6429e57b71/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d72656c6a616b6f2f6c61726176656c2d6c65646765722d67756172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/amreljako/laravel-ledger-guard)[![License](https://camo.githubusercontent.com/efb2fdd2e41d821963b4366f4ca41b40091393238fc921d6cac679ea0c90480c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d72656c6a616b6f2f6c61726176656c2d6c65646765722d67756172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/amreljako/laravel-ledger-guard/license) **Laravel LedgerGuard** is a highly secure, production-grade, and tamper-evident financial ledger system for Laravel. Unlike traditional wallet packages that simply increment/decrement a `balance` column, LedgerGuard utilizes a strict **Double-Entry Bookkeeping** architecture combined with **Blockchain-like cryptographic chaining** and **Pessimistic Locking** to completely eliminate financial fraud, race conditions, and unauthorized database manipulation. --- The Threat Model & Architecture ----------------------------------- [](#the-threat-model--architecture) Traditional database structures for wallets are inherently insecure against multi-threaded application exploits or insider threats. LedgerGuard introduces an immutable infrastructure layer to protect financial records: ThreatStandard Wallet DesignLedgerGuard**Race Conditions / Double Spending**Vulnerable during high-concurrency requests (e.g., fast sequential API calls).Employs strict database **Pessimistic Locking (`lockForUpdate`)** to queue concurrent transactions safely.**Direct Database Tampering**If an attacker or malicious insider alters a balance directly in the DB, the system accepts it blindly.**Tamper-Evident Hashing Chain:** Every transaction is cryptographically chained to the previous one via SHA-256. Any manual alteration breaks the chain and triggers an instant lockdown.**Negative Balance Exploit**Relies solely on application-level checks, which can be bypassed via asynchronous requests.Enforces strict `unsignedDecimal` constraints at the database engine level, making negative data insertion physically impossible.**Data Leakage / Privacy**Transaction metadata (e.g., bank notes, user references) is stored in plaintext.Metadata payloads are automatically encrypted at rest using **AES-256-GCM**.--- Key Features ------------ [](#key-features) - **Polymorphic Flexibility:** Attach financial wallets to *any* Eloquent model (`User`, `Vendor`, `Company`, etc.) seamlessly using Morph relations. - **Immutable Ledger Records:** Financial logs are legally immutable; the Eloquent model explicitly blocks `update` and `delete` actions at the kernel level. - **Automatic Account Freezing:** Instantly locks and freezes a ledger with custom alerts if malicious data integrity degradation is spotted during runtime audits. - **Full Audit Trail:** Every single transaction automatically tracks the originator's IP Address and User-Agent out-of-the-box. --- Installation ------------ [](#installation) Install the package via Composer: ``` composer require amreljako/laravel-ledger-guard ``` Publish and run the secure migrations: ``` php artisan vendor:publish \ --provider="Amreljako\LedgerGuard\LedgerGuardServiceProvider" \ --tag="ledger-guard-migrations" php artisan migrate ``` Optionally publish the config file: ``` php artisan vendor:publish \ --provider="Amreljako\LedgerGuard\LedgerGuardServiceProvider" \ --tag="ledger-guard-config" ``` --- Configuration ------------- [](#configuration) The published configuration file will be located at `config/ledger-guard.php`: ``` return [ /* |-------------------------------------------------------------------------- | Default Currency |-------------------------------------------------------------------------- | The default ISO currency code used when creating a new ledger wallet. */ 'default_currency' => 'EGP', /* |-------------------------------------------------------------------------- | Auto-Freeze on Tamper |-------------------------------------------------------------------------- | When enabled, the package will instantly freeze the ledger if any | cryptographic chain misalignment or direct database manipulation | is detected. */ 'auto_freeze_on_tamper' => true, ]; ``` --- Usage & Quick Start ----------------------- [](#usage--quick-start) ### 1. Prepare Your Model [](#1-prepare-your-model) Add the `HasLedger` trait to any Eloquent model you wish to grant a secure financial wallet: ``` namespace App\Models; use Illuminate\Foundation\Auth\User as Authenticatable; use Amreljako\LedgerGuard\Traits\HasLedger; class User extends Authenticatable { use HasLedger; } ``` --- ### 2. Credit Money (Deposits / Inbound) [](#2-credit-money-deposits--inbound) To safely deposit funds into a model's ledger: ``` use Amreljako\LedgerGuard\Facades\LedgerGuard; // Fetch or create user ledger for a specific currency $ledger = $user->ledger()->firstOrCreate(['currency' => 'EGP']); // Safely credit funds with encrypted tracking metadata LedgerGuard::credit($ledger, 1500.50, [ 'reference_id' => 'TXN_99821', 'gateway' => 'Paymob', 'description' => 'Wallet Top up via Credit Card', ]); ``` --- ### 3. Debit Money (Secure Purchases / Payouts) [](#3-debit-money-secure-purchases--payouts) To safely deduct funds from a wallet, wrapped automatically inside a database transaction with Pessimistic Locking: ``` use Amreljako\LedgerGuard\Facades\LedgerGuard; use Illuminate\Support\Facades\Log; try { $ledger = $user->ledger()->where('currency', 'EGP')->first(); LedgerGuard::debit($ledger, 250.00, [ 'order_id' => 'ORD_5541', 'item' => 'Cyberpunk Minimalist Hooded Jacket', ]); echo "Payment successful! Balance securely updated."; } catch (\Exception $e) { // Automatically catches Insufficient Funds, Frozen Accounts, // or Tampered Chains Log::alert("Transaction blocked: " . $e->getMessage()); } ``` --- ### 4. Fetch the Audited Balance [](#4-fetch-the-audited-balance) Calculates the real-time balance via double-entry arithmetic while simultaneously auditing the entire cryptographic signature chain: ``` // Returns a float representing the absolute safe balance $secureBalance = $user->walletBalance('EGP'); ``` --- Mathematical Cryptographic Chain -------------------------------- [](#mathematical-cryptographic-chain) Each record inside the `ledger_transactions` table computes a rolling cryptographic signature: $$\\text{Current Hash} = \\text{SHA256}(\\text{ledger\_id} \\parallel \\text{type} \\parallel \\text{amount} \\parallel \\text{previous\_hash} \\parallel \\text{APP\_KEY})$$ If an attacker gains direct access to your SQL database and attempts to alter a transaction amount, the ledger's mathematical equilibrium breaks. Upon the next balance calculation or transaction request, LedgerGuard: 1. Flags the anomaly 2. Halts execution 3. Freezes the account 4. Throws a Security Violation Exception ### Health Score 39 — LowBetter than 85% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 1d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/101364453?v=4)[Amr Elsayed](/maintainers/amreljako)[@amreljako](https://github.com/amreljako) --- Top Contributors [![amreljako](https://avatars.githubusercontent.com/u/101364453?v=4)](https://github.com/amreljako "amreljako (1 commits)") ### Embed Badge ![Health badge](/badges/amreljako-laravel-ledger-guard/health.svg) ``` [![Health](https://phpackages.com/badges/amreljako-laravel-ledger-guard/health.svg)](https://phpackages.com/packages/amreljako-laravel-ledger-guard) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[spatie/laravel-health Monitor the health of a Laravel application 87411.3M152](/packages/spatie-laravel-health)[yajra/laravel-oci8 Oracle DB driver for Laravel via OCI8 8723.1M23](/packages/yajra-laravel-oci8)[pressbooks/pressbooks Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS. 45344.0k1](/packages/pressbooks-pressbooks)[api-platform/laravel API Platform support for Laravel 59156.3k11](/packages/api-platform-laravel)[rapidez/core Rapidez Core 1822.4k65](/packages/rapidez-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)