PHPackages bugfix666/crypto-balance-wallet - 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. [Utility & Helpers](/categories/utility) 4. / 5. bugfix666/crypto-balance-wallet ActiveLibrary[Utility & Helpers](/categories/utility) bugfix666/crypto-balance-wallet =============================== Wallet and balance management for crypto applications (Laravel package) v1.0.5(1w ago)013↓100%GPL-3.0-onlyPHPPHP ^8.4 Since Jun 1Pushed 1w agoCompare [ Source](https://github.com/bugfix666/crypto-balance-wallet)[ Packagist](https://packagist.org/packages/bugfix666/crypto-balance-wallet)[ RSS](/packages/bugfix666-crypto-balance-wallet/feed)WikiDiscussions main Synced 1w ago READMEChangelog (2)DependenciesVersions (3)Used By (0) Crypto Balance Wallet ===================== [](#crypto-balance-wallet) [![Latest Version on Packagist](https://camo.githubusercontent.com/8e5b912a1cf00189eb17ce95a620f39ad194b5adbbd4245a76d39c57df7ecb55/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6275676669783636362f63727970746f2d62616c616e63652d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bugfix666/crypto-balance-wallet)[![Total Downloads](https://camo.githubusercontent.com/420cb9331fa4630ec004d2721d125d767152add55ead1cce829f5c4daced7544/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6275676669783636362f63727970746f2d62616c616e63652d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bugfix666/crypto-balance-wallet)[![License](https://camo.githubusercontent.com/62ecfe3c0a11cbe1166bc68e5232767282a0fac6d3595680b2abd6c305263a86/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6275676669783636362f63727970746f2d62616c616e63652d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bugfix666/crypto-balance-wallet)![PHP](https://camo.githubusercontent.com/25012e98b640e282284d84348b9c496c315c270928666c27e504e5fa10802102/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342b2d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)![Laravel](https://camo.githubusercontent.com/cefd0d247fb4898c829a8e41b76d9663721d33c7b486e081b00e91141ca83051/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31322d4646324432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)![Redis](https://camo.githubusercontent.com/884e70f90235fd633782fb5b9c83c8df2d688a7b22697a6943cdbd1b939d39cd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f52656469732d51756575652d7265643f6c6f676f3d7265646973266c6f676f436f6c6f723d7768697465) Manage cryptocurrency wallets and balances with **hold mechanism** (two-phase transactions) – ideal for crypto exchanges, payment systems, and financial applications. --- πŸš€ Features ---------- [](#-features) - βœ… **Credit/Debit operations** with precise decimal math (BCMath) - βœ… **Hold / Commit / Cancel** pattern (two‑phase transactions) - βœ… **Currency precision** per wallet (BTC 18 decimals, USDT 2, etc.) - βœ… **Atomic balance updates** using database locks - βœ… **Eloquent models** with proper relationships - βœ… **Repository pattern** for easy mocking and extension - βœ… **Artisan commands** for CLI deposits/withdrawals - βœ… **Ready-to-use HTTP API** (optional) - βœ… **Laravel 12+** support --- πŸ“¦ Installation -------------- [](#-installation) ``` composer require bugfix666/crypto-balance-wallet ``` ### 1. Publish migrations (recommended) [](#1-publish-migrations-recommended) ``` php artisan vendor:publish --tag=wallet-migrations php artisan migrate ``` ### 2. Publish configuration [](#2-publish-configuration) ``` php artisan vendor:publish --tag=wallet-config ``` This creates `config/wallet.php` where you can define precision per currency, blockchain mappings, etc. --- βš™οΈ Configuration ---------------- [](#️-configuration) Edit `config/wallet.php`: ``` return [ 'precision' => [ 'BTC' => 18, 'ETH' => 18, 'USDT' => 2, 'TRX' => 6, ], 'blockchain_map' => [ 'BTC' => 'bitcoin', 'ETH' => 'ethereum', 'TRX' => 'tron', ], ]; ``` > **Note:** The package uses `WalletCurrencyEnum` and `BlockchainEnum` from its own namespace. You can override them via config if needed. --- 🧠 Core Concepts --------------- [](#-core-concepts) ### Two‑Phase Transaction (Hold Pattern) [](#twophase-transaction-hold-pattern) StateDescription`HOLD`Funds are reserved (debit) or added (credit) but not finalised`COMPLETE`Confirms the operation – no further balance change`CANCELED`Reverts a HOLD operation, returning funds**Credit (deposit)** example: 1. Create HOLD β†’ balance increases immediately 2. Later `COMPLETE` or `CANCELED` (only changes operation state) **Debit (withdrawal)** example: 1. Create HOLD β†’ balance decreases immediately (reserved) 2. Later `COMPLETE` (no change) or `CANCELED` (returns funds) > ⚠️ Always perform the second call (COMPLETE/CANCELED) using the **same Operation object** returned by the first call. --- πŸ”§ Usage ------- [](#-usage) ### Using the `WalletService` (recommended) [](#using-the-walletservice-recommended) ``` use Bugfix666\CryptoBalanceWallet\Services\WalletService; use Bugfix666\CryptoBalanceWallet\Enums\OpStateEnum; $walletService = app(WalletService::class); $walletUuid = '550e8400-e29b-41d4-a716-446655440000'; // Deposit $100.00 immediately (COMPLETE) $operation = $walletService->addBalance('100.00', $walletUuid, OpStateEnum::OS_COMPLETE); // Deposit with hold (to be confirmed later) $holdOperation = $walletService->addBalance('50.00', $walletUuid, OpStateEnum::OS_HOLD); // Later: confirm the hold $completedOp = $walletService->addBalance('50.00', $walletUuid, OpStateEnum::OS_COMPLETE, $holdOperation); // Or cancel the hold (refund) $canceledOp = $walletService->addBalance('50.00', $walletUuid, OpStateEnum::OS_CANCELED, $holdOperation); ``` ### Withdrawals (debit) [](#withdrawals-debit) ``` // Reserve $30.00 (HOLD) $holdOp = $walletService->subBalance('30.00', $walletUuid, OpStateEnum::OS_HOLD); // Confirm the withdrawal $completedOp = $walletService->subBalance('30.00', $walletUuid, OpStateEnum::OS_COMPLETE, $holdOp); // Or cancel (return funds to wallet) $canceledOp = $walletService->subBalance('30.00', $walletUuid, OpStateEnum::OS_CANCELED, $holdOp); ``` --- πŸ§ͺ Testing --------- [](#-testing) ``` composer test ``` The package uses **Orchestra Testbench** for isolated testing. You can also run the original feature tests (after publishing) inside your Laravel project: ``` php artisan test --filter=WalletTest ``` --- πŸ“‚ Package Structure ------------------- [](#-package-structure) ``` src/ β”œβ”€β”€ Contracts/ # Repository interfaces β”œβ”€β”€ Enums/ # OpStateEnum, OpTypeEnum, CurrencyEnum, BlockchainEnum β”œβ”€β”€ Exceptions/ # Wallet & User exceptions β”œβ”€β”€ Models/ # Wallet, Operation β”œβ”€β”€ Repositories/ # WalletRepository, OperationRepository, PrecisionRepository β”œβ”€β”€ Services/ # WalletService, OperationService, UserService β”œβ”€β”€ DTO/ # OperationDTO, PrecisionDTO β”œβ”€β”€ Console/Commands/ # DepositCommand, WithdrawCommand, ListWalletsCommand β”œβ”€β”€ Jobs/ # BalanceProcessCallbackJob (async) └── Providers/ # WalletServiceProvider ``` --- πŸ” Error Handling ---------------- [](#-error-handling) All exceptions extend Laravel’s base exceptions where possible. Typical exceptions: ExceptionWhen thrown`WalletNotFoundException`Wallet UUID does not exist`NotEnoughFundsException`Insufficient balance for debit`InvalidOperationStateException`Trying to complete/cancel non‑HOLD operation`ProcessingAmountIsInvalidException`Amount is zero, negative, or below minimum`WalletCurrencyPrecisionNotSetException`Missing precision configuration for currency`WalletRollbackException`Database rollback failed during cancel--- 🧩 Requirements -------------- [](#-requirements) - PHP 8.4+ - Laravel 12+ - BCMath PHP extension - Database with row locking support (MySQL 8+, PostgreSQL) --- 🀝 Contributing -------------- [](#-contributing) 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing`) 3. Run `composer install` and `composer test` to ensure tests pass 4. Commit your changes 5. Open a Pull Request Please follow [PSR-12](https://www.php-fig.org/psr/psr-12/) and use `composer pint` for code style. --- πŸ“„ License --------- [](#-license) **GPL-3.0-only** – see [LICENSE](LICENSE) file for details. --- ❓ FAQ ----- [](#-faq) **Q: How do I create a wallet for a user?** A: Use the `Wallet::create()` method after ensuring your User model exists. The package does **not** enforce a specific `User` model – you can attach wallets to any model via `user_id`. **Q: Can I use different precision per wallet of the same currency?** A: Yes – implement your own `PrecisionRepositoryInterface` and bind it in your service provider. The default implementation reads from `config/wallet.php`. **Q: Are operations automatically cleaned up?** A: No – HOLD operations stay forever. You should implement a scheduled job to cancel stale holds if needed. **Q: Is this safe for high‑concurrency?** A: Yes – all critical sections use `SELECT ... FOR UPDATE` row‑locks inside database transactions. --- πŸ“« Support --------- [](#-support) Open an issue on [GitHub Issues](https://github.com/bugfix666/crypto-balance-wallet/issues) or contact `appscenter@proton.me`. --- **Built with ❀️ by bugfix666** *Stable, auditable, and production‑ready.* ### Health Score 43 β€” FairBetter than 89% of packages Maintenance98 Actively maintained with recent releases Popularity8 Limited adoption so far Community3 Small or concentrated contributor base Maturity52 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 Every ~0 days Total 2 Last Release 9d ago ### Community --- Top Contributors [![bugfix666](https://avatars.githubusercontent.com/u/151177991?v=4)](https://github.com/bugfix666 "bugfix666 (9 commits)") --- Tags balancecomposer-packagecryptocurrencylaravelledgerphpphp84wallet ### Embed Badge ![Health badge](/badges/bugfix666-crypto-balance-wallet/health.svg) ``` [![Health](https://phpackages.com/badges/bugfix666-crypto-balance-wallet/health.svg)](https://phpackages.com/packages/bugfix666-crypto-balance-wallet) ``` PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)