Adds fiat currency information to payment invoices and ledger entries.
This allows for tracking the fiat value of transactions and provides a more complete financial picture. Calculates the fiat amount proportionally based on the user's balance and includes the fiat currency, amount, and exchange rates in the invoice's extra data. This data is then extracted and added to the ledger entry's metadata when recording the payment.
Implements a mechanism to cancel pending background tasks
when the extension is stopped. This ensures proper cleanup and
prevents potential issues with lingering tasks.
Implements a background task that listens for paid invoices
and automatically records them in the accounting system. This
ensures payments are captured even if the user closes their
browser before the client-side polling detects the payment.
Introduces a new `get_journal_entry_by_reference` function to
improve idempotency when recording payments.
Adds support for on-chain Bitcoin payments by:
- Introducing a new `Assets:Bitcoin:OnChain` account.
- Updating the `SettleReceivable` and `PayUser` models to include `txid` for storing transaction IDs.
- Modifying the API endpoints to handle `btc_onchain` as a valid payment method and associate it with the new account.
This allows tracking on-chain Bitcoin transactions separately from Lightning Network payments.
Ensures consistent formatting of fiat currency, amount,
and exchange rates in the `api_settle_receivable` and
`api_pay_user` API endpoints.
Specifically, it:
- Converts fiat currency to uppercase.
- Formats fiat amount to three decimal places.
- Calculates and includes fiat and BTC rates.
Creates a markdown file to provide guidance to Claude Code (claude.ai/code) when interacting with the Castle Accounting codebase.
This document outlines project overview, architecture, key files, database schema, transaction flows, API endpoints, development notes, and other crucial information. It aims to improve Claude's ability to understand and assist with code-related tasks.
Uses usernames instead of user IDs in the audit log and
approval request listings to improve readability. If a user
is not found, it displays a truncated version of the user ID.
Adds a date field to expense entries for better tracking and reporting.
This allows users to specify the date of the expense transaction,
providing more accurate financial records.
Ensures that the currency field defaults to EUR in both the expense and receivable dialogs.
This provides a better user experience by pre-selecting a common currency, preventing the user from having to manually choose it every time.
Updates the exchange rate calculation to rely solely on the
current exchange rate when a valid fiat amount is not available.
Removes the hardcoded default exchange rate fallback and instead
displays a user-friendly warning message when fetching the exchange
rate fails. This informs the user that fiat currency conversions
might be unavailable.
Fetches the current BTC/EUR exchange rate from the CoinGecko API and uses it to calculate fiat values.
This ensures more accurate currency conversions, especially for expenses and payments. A fallback to a default rate is included in case the API is unavailable.
Implements the ability for the super user (Castle) to pay other users for expenses or liabilities.
Introduces a new `PayUser` model to represent these payments, along with API endpoints to process and record them.
Integrates a "Pay User" button into the user list, allowing the super user to initiate payments through either lightning or manual methods (cash, bank transfer, check).
Adds UI elements and logic for handling both lightning payments (generating invoices and paying them) and manual payment recording.
This functionality allows Castle to manage and settle debts with its users directly through the application.
Enhances the receivable settlement dialog by providing a default description based on the selected payment method, improving clarity for users.
Filters the user balance display to only show users with outstanding balances, making the interface cleaner and more focused for super users.
Updates the `api_settle_receivable` function to ensure all journal entries are recorded in satoshis, regardless of the currency used for payment.
This change standardizes the journal entries to match the receivable account balance, simplifying reconciliation. It also enforces that `amount_sats` must be provided when settling with fiat currency to correctly calculate the sats equivalent.
Adds support for settling receivables with fiat currencies
like EUR and USD, in addition to sats.
Updates the settlement dialog to handle fiat amounts and
exchange rates, defaulting to cash payment when a fiat balance
exists.
Modifies the API to accept currency and amount_sats parameters
and adjust the journal entry accordingly, converting the fiat amount
to minor units (e.g., cents) for accounting purposes.
Standardizes lightning account name to "Assets:Bitcoin:Lightning" for consistency.
Updates the database and code to reflect this change, ensuring that payment processing and account management use the new name.
Prevents polling of receivable dialog after settlement.
Replaces the generic QR code generation with the lnbits-qrcode component.
This simplifies the code and utilizes a component specifically designed for LNbits applications.
Removes the input field for the invoice string as it is no longer necessary.
Allows administrators to generate payment invoices on behalf of specific users.
This is useful for handling settlement invoices in certain scenarios.
The changes include:
- Adding a `user_id` field to the generate payment invoice request model
- Updating the API endpoint to accept the `user_id` parameter
- Implementing checks to ensure only superusers can generate invoices for other users
- Updating the memo and extra data to reflect the target user
Implements the ability for users to settle their outstanding balance
using a Lightning Network invoice.
Generates an invoice on the Castle wallet and polls for payment,
automatically recording the transaction once payment is detected.
The UI is updated to display the invoice and handle the payment process.
Implements a "Settle Receivable" feature for super users to record manual payments from users who owe money.
Introduces a dialog for inputting payment details (amount, method, description, reference), triggers an API call to record the transaction, and updates user balances and transaction history.
This is for non-lightning payments like cash, bank transfers, or checks.
Moves the "Quick Actions" card to the top of the dashboard for better user accessibility and discoverability.
Removes the duplicate card at the bottom.
Refactors the accounting logic into a clean, testable core module, separating business logic from database operations.
This improves code quality, maintainability, and testability by creating a dedicated `core/` module, implementing `CastleInventory` for position tracking, moving balance calculations to `core/balance.py`, and adding comprehensive validation in `core/validation.py`.
Implements balance assertions, reconciliation API endpoints, a reconciliation UI dashboard, and automated daily balance checks.
This provides comprehensive reconciliation tools to ensure accounting accuracy and catch discrepancies early.
Updates roadmap to mark Phase 2 as complete.
Improves balance assertion creation by handling Decimal types correctly for database insertion.
It also fixes a validation issue in the UI where the expected balance was not correctly validated as a required field and initializes the value to 0.
Adds balance assertion functionality to enable admins to verify accounting accuracy.
This includes:
- A new `balance_assertions` table in the database
- CRUD operations for balance assertions (create, get, list, check, delete)
- API endpoints for managing balance assertions (admin only)
- UI elements for creating, viewing, and re-checking assertions
Also, reorders the implementation roadmap in the documentation to reflect better the dependencies between phases.
Ensures that only cleared entry lines are included when
calculating fiat balances by filtering based on the
journal entry's flag. Excludes pending, flagged, and
voided entries
Adds an admin approval workflow for user-submitted expenses. This ensures that only valid expenses affect user balances.
The workflow includes pending expense states, admin approval/rejection actions, balance filtering, and UI updates.
Implements expense approval functionality, allowing superusers to review and approve or reject expense entries.
This includes:
- Filtering account balance calculations and user balance calculations to only include cleared journal entries.
- Adding API endpoints to retrieve pending expense entries and approve/reject them.
- Updating the UI to display pending expenses to superusers and provide actions to approve or reject them.
This ensures better control over expenses within the system.
Marks Phase 1 as complete in the documentation.
Updates the transaction list in the UI to display transaction status flags and metadata, enhancing user understanding of each transaction.
Implements core improvements from Phase 1 of the Beancount patterns adoption:
- Uses Decimal for fiat amounts to prevent floating point errors
- Adds a meta field to journal entries for a full audit trail
- Adds a flag field to journal entries for transaction status
- Migrates existing account names to a hierarchical format
This commit introduces a database migration to add the `flag` and `meta` columns to the `journal_entries` table. It also includes updates to the models, CRUD operations, and API endpoints to handle the new fields.
Provides detailed documentation for the Castle Accounting extension, including architecture, transaction flows, balance calculation, API endpoints, and future improvements.
Documents design patterns inspired by Beancount, such as immutable data structures, plugin architecture, and balance assertions, with recommendations for adoption in the Castle extension.
Includes an implementation roadmap, security considerations, performance considerations, and a migration path for existing data.
Improves clarity by displaying "Payable" or "Receivable" badges on entries
in the transaction list.
The badge color depends on whether the user is a superuser, indicating
the direction of the transaction from the user's perspective.
This helps users quickly understand which transactions are owed to them
and which they owe.
Improves the display of user balances in the admin panel by including the username alongside the user ID. This provides a more user-friendly and easily identifiable representation of user data.
The username is fetched from the user table, and if no username is set the first 16 characters of the user id is shown.
Ensures that account creation utilizes the user ID
associated with the wallet, rather than directly
relying on the wallet identifier. This aligns account
ownership more accurately.
Ensures that only the super user can access and modify manual payment requests via the admin API endpoints. This enhances security by preventing unauthorized access to sensitive administrative functions.
Removes dependency on `check_super_user` helper function, instead directly comparing the wallet user with the configured super user in lnbits settings.
Renames database migration functions to correct a numbering error.
The original migration `m002_add_metadata_column` was removed in a previous commit,
but the subsequent migrations were not renamed to reflect this, leading to
incorrect numbering. This change corrects the function names to ensure
proper sequential execution during database migrations.
Enables users to request manual payments from the Castle and provides admin functions to approve or reject these requests.
Introduces the `manual_payment_requests` table and related CRUD operations.
Adds API endpoints for creating, retrieving, approving, and rejecting manual payment requests.
Updates the UI to allow users to request payments and for admins to review pending requests.
For super users, the balance view now displays the net position
(liabilities - receivables) of the Castle. The journal view
shows all entries across all users.
The settings are now loaded first to determine if the user is a
super user.
Improves user experience by visually indicating entries that represent outstanding payments owed by users.
This change introduces a "Pending Payment" badge for receivable entries in the transaction list. A receivable entry is determined by checking if the entry contains a debit line item against an account receivable account. This provides immediate visual feedback to the user, highlighting transactions requiring their action.
Updates journal entry retrieval to filter entries based on
the user's accounts rather than the user ID.
This ensures that users only see journal entries that
directly affect their accounts.
Also displays fiat amount in journal entries if available in
the metadata.
Extends user balance information to include fiat currency balances,
calculated based on entry line metadata and account types.
This allows for a more comprehensive view of user balances,
including both satoshi and fiat currency holdings.
Updates the castle index template and API to display fiat balances.
Improves the reliability of payment status updates by ensuring that the payment polling interval is properly cleared when a payment dialog is closed, when a payment is submitted, or when a new payment dialog is opened. This prevents multiple polling intervals from running simultaneously, which could lead to incorrect payment status updates.
Adds a watch to clear interval when the pay dialog closes.
Adds functionality for users to pay their Castle balance by generating and paying a Lightning invoice.
This includes:
- Adding API endpoints for invoice generation and payment recording.
- Updating the frontend to allow users to initiate the invoice payment process.
- Passing the wallet's `inkey` to the frontend for payment status checks.
Implements a feature that allows users to pay their outstanding balance via Lightning.
The changes include:
- Adds the UI elements for invoice generation and display, including QR code.
- Integrates backend endpoints to generate and record payments.
- Adds polling mechanism to track payments and update balance.
- Creates new database models to support manual payment requests.
Updates the receivable entry model and related API endpoints to use the user's ID instead of the user's wallet ID.
This change simplifies user identification and ensures consistency throughout the application.
Implements the ability to record receivables (user owes the castle).
Adds API endpoint for creating receivable entries, which includes currency conversion to satoshis if fiat currency is provided.
Integrates a UI component (receivable dialog) for superusers to record debts owed by users, enhancing financial tracking capabilities.
Implements functionality for super users to view a breakdown of outstanding balances for all users.
This includes:
- Adding an API endpoint to fetch all user balances.
- Updating the frontend to display these balances in a table, accessible only to super users.
- Modifying the balance calculation for the current user to reflect the total owed by or to the castle for super users.
This provides super users with a comprehensive view of the castle's financial position.
