{"id":50911001,"url":"https://github.com/crystaldaking/finance-core","last_synced_at":"2026-06-16T10:01:49.017Z","repository":{"id":361917432,"uuid":"1256431866","full_name":"crystaldaking/finance-core","owner":"crystaldaking","description":"Framework-agnostic PHP financial core for money, assets, ledgering, fees, audit, events and idempotency.","archived":false,"fork":false,"pushed_at":"2026-06-01T20:22:25.000Z","size":92,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T21:17:41.986Z","etag":null,"topics":["accounting","finance","fintech","idempotency","ledger","money","php","sdk"],"latest_commit_sha":null,"homepage":"https://github.com/crystaldaking/finance-core","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crystaldaking.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T19:18:01.000Z","updated_at":"2026-06-01T20:22:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/crystaldaking/finance-core","commit_stats":null,"previous_names":["crystaldaking/finance-core"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/crystaldaking/finance-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystaldaking%2Ffinance-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystaldaking%2Ffinance-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystaldaking%2Ffinance-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystaldaking%2Ffinance-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crystaldaking","download_url":"https://codeload.github.com/crystaldaking/finance-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystaldaking%2Ffinance-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34400456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","finance","fintech","idempotency","ledger","money","php","sdk"],"created_at":"2026-06-16T10:01:47.491Z","updated_at":"2026-06-16T10:01:49.007Z","avatar_url":"https://github.com/crystaldaking.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Crystal Finance Core\n\n`crystaldaking/finance-core` is a framework-agnostic PHP 8.5 financial core for applications that need safe money arithmetic, network-aware assets, double-entry ledgering, explainable fees, audit context, domain events, and idempotency primitives.\n\nIt can be used in PSPs, crypto acquiring systems, internal finance platforms, corporate accounting tools, reconciliation workers, CLI jobs, and plain PHP services. It is not a Laravel package, PSP application, database schema, report engine, tax engine, or UI.\n\nPayment workflows, provider integrations, webhooks, refunds, chargebacks, payouts, and settlement flows belong in a future package such as `crystaldaking/payments-core`.\n\n## Installation\n\n```bash\ncomposer require crystaldaking/finance-core\n```\n\n## Core Principles\n\n- No floating point arithmetic for financial values.\n- Assets are explicit and network-aware: `USDT@TRON` and `USDT@ETHEREUM` are different assets.\n- Ledger balances are derived from entries. This package does not store balances directly.\n- Ledger transactions are append-only domain facts and must balance per asset.\n- The core has no Laravel, Symfony, Doctrine ORM, Carbon, database, queue, or framework dependency.\n- Public APIs use explicit value objects instead of framework models or magic arrays.\n\n## Money\n\n```php\nuse Crystal\\Finance\\Core\\Money\\AssetRegistry;\nuse Crystal\\Finance\\Core\\Money\\Money;\nuse Crystal\\Finance\\Core\\Money\\Percentage;\nuse Crystal\\Finance\\Core\\Money\\RoundingMode;\n\n$registry = AssetRegistry::default();\n\n$amount = Money::of('100.00', 'EUR', $registry);\n$fee = $amount-\u003epercentage(Percentage::of('2.5'), RoundingMode::HalfUp);\n$total = $amount-\u003eplus($fee);\n\n$usdtTron = Money::of('10.000000', 'USDT@TRON', $registry);\n$usdtEthereum = Money::of('10.000000', 'USDT@ETHEREUM', $registry);\n```\n\n`$usdtTron` and `$usdtEthereum` cannot be added together because they are different assets.\n\n## Fees\n\n```php\nuse Crystal\\Finance\\Core\\Fee\\FeeCalculator;\nuse Crystal\\Finance\\Core\\Fee\\FeeContext;\nuse Crystal\\Finance\\Core\\Fee\\FeeRule;\nuse Crystal\\Finance\\Core\\Money\\Money;\nuse Crystal\\Finance\\Core\\Money\\Percentage;\n\n$rule = FeeRule::make()\n    -\u003epercent(Percentage::of('2.5'), label: 'service_fee')\n    -\u003efixed(Money::of('0.30', 'EUR', $registry), label: 'fixed_charge')\n    -\u003emin(Money::of('1.00', 'EUR', $registry))\n    -\u003emax(Money::of('50.00', 'EUR', $registry));\n\n$result = (new FeeCalculator())-\u003ecalculate(\n    Money::of('100.00', 'EUR', $registry),\n    $rule,\n    FeeContext::make('invoice_collection', ['customer' =\u003e 'customer_123']),\n);\n\n$result-\u003egross();      // 100.00 EUR\n$result-\u003etotalFee();   // 2.80 EUR\n$result-\u003enet();        // 97.20 EUR\n$result-\u003ebreakdown();  // explainable fee lines\n```\n\n## Ledger\n\n```php\nuse Crystal\\Finance\\Core\\Ledger\\LedgerAccountId;\nuse Crystal\\Finance\\Core\\Ledger\\LedgerReference;\nuse Crystal\\Finance\\Core\\Ledger\\LedgerTransaction;\nuse Crystal\\Finance\\Core\\Ledger\\LedgerTransactionType;\nuse Crystal\\Finance\\Core\\Ledger\\LedgerValidator;\nuse Crystal\\Finance\\Core\\Money\\Money;\n\n$transaction = LedgerTransaction::make(\n    LedgerTransactionType::Transfer,\n    LedgerReference::manual('transfer_123'),\n)\n    -\u003edebit(\n        LedgerAccountId::fromString('cash:main'),\n        Money::of('100.00', 'EUR', $registry),\n    )\n    -\u003ecredit(\n        LedgerAccountId::fromString('equity:owner'),\n        Money::of('100.00', 'EUR', $registry),\n    );\n\n(new LedgerValidator())-\u003eassertValid($transaction);\n```\n\n## Idempotency\n\n```php\nuse Crystal\\Finance\\Core\\Idempotency\\IdempotencyKey;\nuse Crystal\\Finance\\Core\\Idempotency\\IdempotencyScope;\nuse Crystal\\Finance\\Core\\Idempotency\\PayloadFingerprint;\n\n$scope = IdempotencyScope::fromString('ledger:append');\n$key = IdempotencyKey::fromString('request_12345678');\n$fingerprint = PayloadFingerprint::fromArray([\n    'reference' =\u003e 'transfer_123',\n    'amount' =\u003e '100.00',\n    'asset' =\u003e 'EUR',\n]);\n```\n\nConcrete Redis, SQL, cache, and lock implementations live outside this package.\n\n## Quality\n\n```bash\ncomposer qa\ncomposer coverage\ncomposer mutation\n```\n\nThe QA suite validates Composer metadata, coding style, PHPStan max level, Psalm strict analysis, PHPUnit unit tests, and architecture boundaries. The hardening suite adds line coverage and mutation testing:\n\n```bash\ncomposer hardening\n```\n\n## Examples\n\nThe `examples/` directory contains executable real-life usage scenarios:\n\n- network-aware money boundaries and high-precision crypto minor units\n- SaaS cost-center allocation with deterministic residual handling\n- corporate expense journals\n- multi-asset treasury ledger entries\n- invoice fee calculation with explainable breakdown lines\n- merchant collection ledger posting with audit, event, and idempotency fingerprint\n- reversal-based correction workflow\n- idempotent ledger command execution\n- FX conversion with explicit rounding\n- audit event recording for outbox-style integrations\n\n`examples/06-platform-fee-ledger-posting.php` is the integration proof: it combines money, fees, ledger posting, audit context, a domain event, and an idempotency fingerprint in one merchant finance scenario.\n\nSee `examples/README.md` for the full runnable scenario list.\n\n## Release Governance\n\n- Backward compatibility policy: `docs/backward-compatibility.md`\n- Public API contract: `docs/public-api.md`\n- Release checklist: `docs/release/checklist.md`\n- Changelog: `CHANGELOG.md`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystaldaking%2Ffinance-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrystaldaking%2Ffinance-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystaldaking%2Ffinance-core/lists"}