caudal/README.md

<div align="center">

<img src="programa/cartera/web/icono.svg" width="96" alt="">

# Caudal

**Tus inversiones y tu bitcoin, llevados en tu casa.**

Fondos, acciones, pisos y fincas, Letras y bonos, planes de pensiones, cuentas
y bitcoin leído desde tu propio nodo, en un solo sitio. Cuánto vale todo,
cuánto has ganado de verdad y lo que hay que declarar en España.

[Instalar](#instalar) · [Qué hace](#qué-hace) · [Tu privacidad](#tu-privacidad) · [Apoyar el proyecto](#apoyar-el-proyecto) · [Contacto](#contacto)

</div>

<p align="center"><img src="docs/resumen.png" width="760" alt="Resumen de Caudal con la cartera de ejemplo: patrimonio neto, valor, ganancia, rentabilidad, evolución y reparto"></p>

## Qué hace

- 📈 **Todo junto y al día.** Fondos, ETF, acciones, planes de pensiones,
  cuentas y criptomonedas, con sus precios de cada día, la rentabilidad real
  (la de un depósito equivalente) y cómo ha ido creciendo lo aportado.
- 🏠 **Pisos, garajes y fincas.** Su valor se estima solo (el índice de
  vivienda del INE y el precio de la tierra del Ministerio de Agricultura,
  por cultivo, secano o regadío), con el alquiler que se apunta cada mes, la
  hipoteca y lo que deja para la renta.
- 🏦 **Letras, bonos y depósitos.** Cupones y vencimiento se apuntan solos y,
  si cotizan, su precio de mercado sale de BME. También cuentas de bróker
  con su resultado anual.
- ₿ **Bitcoin desde tu nodo.** Le das la clave pública de tus monederos (o
  direcciones sueltas) y Caudal lee los movimientos de **tu** servidor
  Electrum o directamente de tu Bitcoin Core o Knots, también por Tor. Te
  propone qué apuntar de cada transacción.
- 🧾 **Lo que hay que declarar.** Ganancias y pérdidas por FIFO, la regla de
  la recompra, dividendos y su retención, la minería como actividad
  económica y lo que costaría ponerse al día de años sin declarar. Con las
  reglas de cada territorio: **común, Álava, Bizkaia, Gipuzkoa y Navarra**,
  y la cita de cada norma.
- 💬 **«Cuéntame».** Escribe «ayer aporté 100 € al plan» y Caudal prepara la
  operación para que la revises.
- 🔎 **Cada inversión, con su ficha:** su gráfica y lo que pagarías a Hacienda
  si la vendieras hoy, con todo lo demás del año en cuenta.
- 📱 **En el ordenador y en el móvil**, con la misma cartera: enlaza otro
  Caudal con tu servidor leyendo un QR, sin teclear la contraseña.

<table>
<tr>
<td width="62%"><img src="docs/fiscal.png" alt="Pestaña Fiscal: el ejercicio en pocas palabras y la cuota del ahorro"></td>
<td><img src="docs/movil.png" alt="Caudal en el móvil"></td>
</tr>
</table>

Puedes probarlo todo con la **cartera de ejemplo** que trae, sin apuntar nada
tuyo: al abrirla, un recorrido de cinco notas te enseña lo principal. Al
empezar con lo tuyo te pregunta qué tienes y dónde declaras, y te prepara una
lista de primeros pasos que se va marcando sola.

## Instalar

| Dónde | Cómo |
|---|---|
| **Start9 (StartOS)** | Descarga el `.s9pk` de [Versiones](https://codeberg.org/esetheyers/caudal/releases) e instálalo en **System → Sideload**. |
| **Linux** | Descarga el instalable de [Versiones](https://codeberg.org/esetheyers/caudal/releases): elige carpeta y te deja un lanzador en el menú. |
| **Umbrel** | Añade la tienda del autor, `https://codeberg.org/esetheyers/umbrel-apps`, en **App Store → ⋯ → Community App Stores**. |
| **Android** | En pruebas: el `.apk` llegará a [Versiones](https://codeberg.org/esetheyers/caudal/releases) cuando esté probado en teléfonos de verdad. Se abrirá con la huella o el PIN del teléfono. |
| **Windows y Mac** | De momento, constrúyelo en tu equipo: `empaquetado\escritorio\construir.ps1` (Windows) o `sh empaquetado/escritorio/construir.sh` (Mac). |
| **Docker** | `docker build -t caudal . && docker run -d -p 8080:8080 -v caudal-datos:/data caudal` |
| **Cualquier ordenador o un USB** | Python 3.10 o posterior y `bash abrir_app.sh`. Detalles en `programa/LEEME.md`. |

En un servidor se entra con una contraseña que creas la primera vez. En tu
ordenador solo atiende en el propio equipo.

## Tu privacidad

- 🏠 **Tus datos no salen de tu casa.** No hay cuenta, ni nube, ni telemetría.
- 🔑 **Nunca pide claves privadas.** Para bitcoin basta la clave pública.
- 🔒 **Cifrado opcional**, con una sola contraseña y una clave de recuperación.
- 🌐 **Lo único que sale a internet son los precios**: Caudal pregunta a
  fuentes públicas (Morningstar, Yahoo, CoinGecko, LS Exchange y un cambio de
  divisa) por los identificadores de lo que tienes, nunca por las cantidades.
  Sin conexión funciona igual; solo dejan de moverse los precios.

## Comprobar lo que descargas

Cada versión va con un manifiesto de huellas firmado con PGP. Cómo
comprobarlo, con Sparrow o con dos órdenes, en `VERIFICAR.md`. La clave del
autor es `esetheyers.asc` (`esetheyers <esetheyers@huveme.com>`):

```
3648 41BA B31F 9D0F 3D07  5629 C34F 1F5D 7116 CA10
```

## Apoyar el proyecto

Caudal es gratis y lo seguirá siendo. Si te ahorra tiempo, puedes mandar
unos sats a

<p align="center"><img src="docs/donar.svg" width="180" alt="Código QR de esetheyers@huveme.com"><br><code>esetheyers@huveme.com</code></p>

Escríbela tal cual en tu monedero: vale como dirección Lightning y, en los
monederos con BIP 353, también como oferta BOLT12 o dirección de pagos
silenciosos. Gracias.

## Contacto

- **Fallos e ideas:** abre una [incidencia](https://codeberg.org/esetheyers/caudal/issues).
  Para enseñar un fallo usa la cartera de ejemplo: no publiques tus datos ni
  capturas con tus cifras.
- **Lo demás:** esetheyers@huveme.com (puedes cifrar con la clave de arriba).

Las propuestas de código son bienvenidas; antes de una grande, abre una
incidencia para comentarla. Las condiciones están en `AVISO.md`.

<details>
<summary><b>Pruebas</b></summary>

```
cd programa && python3 -m unittest discover -s pruebas
```

Se pasan enteras sin internet, con una cartera ficticia.

</details>

## Licencia

AGPL-3.0 o posterior (`LICENSE`). Sin ninguna garantía: la parte fiscal es
una ayuda para preparar tu declaración, no asesoría fiscal.

Hecho por esetheyers con Claude (Anthropic).