forked from aiolabs/libra
Rename Castle Accounting extension to Libra
Full identifier rename: module path lnbits.extensions.castle →
lnbits.extensions.libra, DB ext_castle → ext_libra, URL prefix
/castle/ → /libra/, manifest id castle → libra, fava ledger slug
default castle-ledger → libra-ledger, Beancount source metadata
castle-api → libra-api and link prefixes castle-{entry,tx}- →
libra-{entry,tx}-, column castle_wallet_id → libra_wallet_id, all
Python/JS/HTML identifiers (castle_ext, CastleSettings,
castle_reference, castleWalletConfigured, etc.).
Display name "Castle Accounting" → "Libra" (the scales/balance
metaphor — fits double-entry bookkeeping).
No backward compat: production hosts will be force-updated. Old
castle-prefixed Beancount metadata in existing Fava ledgers is
historical; new entries use libra-* prefixes going forward.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
9c577c740c
commit
c174cda48d
44 changed files with 953 additions and 953 deletions
|
|
@ -8,21 +8,21 @@
|
|||
|
||||
## Overview
|
||||
|
||||
The `sats-equivalent` metadata field is Castle's solution for **dual-currency tracking** in a fiat-denominated ledger. It preserves Bitcoin (satoshi) amounts alongside fiat currency amounts without violating accounting principles or creating multi-currency complexity in position balances.
|
||||
The `sats-equivalent` metadata field is Libra's solution for **dual-currency tracking** in a fiat-denominated ledger. It preserves Bitcoin (satoshi) amounts alongside fiat currency amounts without violating accounting principles or creating multi-currency complexity in position balances.
|
||||
|
||||
### Quick Summary
|
||||
|
||||
- **Purpose**: Track Bitcoin/Lightning amounts in a EUR-denominated ledger
|
||||
- **Location**: Beancount posting metadata (not position amounts)
|
||||
- **Format**: String containing absolute satoshi amount (e.g., `"337096"`)
|
||||
- **Primary Use**: Calculate user balances in satoshis (Castle's primary currency)
|
||||
- **Primary Use**: Calculate user balances in satoshis (Libra's primary currency)
|
||||
- **Key Principle**: Satoshis are for reference; EUR is the actual transaction currency
|
||||
|
||||
---
|
||||
|
||||
## The Problem: Dual-Currency Tracking
|
||||
|
||||
Castle needs to track both:
|
||||
Libra needs to track both:
|
||||
1. **Fiat amounts** (EUR, USD) - The actual transaction currency
|
||||
2. **Bitcoin amounts** (satoshis) - The Lightning Network settlement currency
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ Castle needs to track both:
|
|||
- ❌ Complicate traditional accounting reconciliation
|
||||
- ❌ Make fiat-based reporting difficult
|
||||
|
||||
**Castle's Philosophy**: Record transactions in their **actual currency**, with Bitcoin as supplementary data.
|
||||
**Libra's Philosophy**: Record transactions in their **actual currency**, with Bitcoin as supplementary data.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -88,7 +88,7 @@ if fiat_currency and fiat_amount:
|
|||
|
||||
### Primary Use Case: User Balances
|
||||
|
||||
Castle's core function is tracking **who owes whom** in satoshis. The `sats-equivalent` metadata enables this.
|
||||
Libra's core function is tracking **who owes whom** in satoshis. The `sats-equivalent` metadata enables this.
|
||||
|
||||
**Flow** (`fava_client.py:220-248`):
|
||||
|
||||
|
|
@ -147,7 +147,7 @@ SELECT account, sum(meta["sats-equivalent"]) WHERE account ~ 'User-5987ae95'
|
|||
-- Error: BQL cannot access metadata
|
||||
```
|
||||
|
||||
### Why Castle Accepts This Trade-off
|
||||
### Why Libra Accepts This Trade-off
|
||||
|
||||
**Performance Analysis** (see `docs/BQL-BALANCE-QUERIES.md`):
|
||||
1. **Caching solves the bottleneck**: 60-80% performance improvement from caching account/permission lookups
|
||||
|
|
@ -196,9 +196,9 @@ See `docs/BQL-PRICE-NOTATION-SOLUTION.md` for full analysis.
|
|||
|
||||
**User Action**: "I paid €36.93 cash for groceries"
|
||||
|
||||
**Castle's Internal Representation**:
|
||||
**Libra's Internal Representation**:
|
||||
```python
|
||||
# User provides or Castle calculates:
|
||||
# User provides or Libra calculates:
|
||||
fiat_amount = Decimal("36.93") # EUR
|
||||
fiat_currency = "EUR"
|
||||
amount_sats = 39669 # Calculated from exchange rate
|
||||
|
|
@ -232,16 +232,16 @@ line = CreateEntryLine(
|
|||
# - Apply sign: -36.93 is negative → sats = -39669
|
||||
# - Accumulate: user_balance_sats += -39669
|
||||
|
||||
# Result: negative balance = Castle owes user
|
||||
# Result: negative balance = Libra owes user
|
||||
```
|
||||
|
||||
**User Balance Response**:
|
||||
```json
|
||||
{
|
||||
"user_id": "5987ae95",
|
||||
"balance": -39669, // Castle owes user 39,669 sats
|
||||
"balance": -39669, // Libra owes user 39,669 sats
|
||||
"fiat_balances": {
|
||||
"EUR": "-36.93" // Castle owes user €36.93
|
||||
"EUR": "-36.93" // Libra owes user €36.93
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -306,7 +306,7 @@ The `sats-equivalent` is the **exact satoshi amount at transaction time**. It do
|
|||
|
||||
### 3. Separate Fiat and Sats Balances
|
||||
|
||||
Castle tracks TWO independent balances:
|
||||
Libra tracks TWO independent balances:
|
||||
- **Satoshi balance**: Sum of `sats-equivalent` metadata (primary)
|
||||
- **Fiat balances**: Sum of EUR/USD position amounts (secondary)
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue