pikaro
29e8e184e8
Repaso crítico de los 11 commits del módulo (motor, tope de
seguridad, UI a demanda, generador de informe), buscando bugs e
inconsistencias más allá de la poda de ramas ya arreglada. Encontrado
y corregido:
- **Certeza de banda inalcanzable:** en la cronología del informe, el
ternario que decidía CERTEZA/PROBABLE/POSIBLE para la banda de cada
tx comparaba `analysis.score>=75` con `analysis.band==="ALTA"` —
la misma condición dos veces, porque analyzeTx define ALTA como
score>=75. La rama PROBABLE nunca podía darse. Ahora es
score>=90→CERTEZA / score>=45→PROBABLE / resto→POSIBLE, las tres
alcanzables.
- **entityMarks del origen siempre vacío:** buildForensicReport
llamaba marcasDeTx sobre `origin` (el resumen que devuelve
finalizeForensicGraph), que no lleva vin/vout — así que la fila de
origen en la cronología nunca podía mostrar coinbase/OFAC/minería/
exchange, aunque la tx real sí los tuviera. Ahora
finalizeForensicGraph calcula entityMarks sobre la tx cruda y lo
guarda en graph.origin.entityMarks. Verificado con una tx coinbase
sintética: antes daba [], ahora marca correctamente "⛏️ coinbase
(origen)".
- **`custodyStop.byVolume`/tx_count usaba el string "maxHops" como
stopReason** — el mismo valor que ya significaba "truncado por el
parámetro maxHops" en otro sitio (unspentTerminals), pero refería a
MAX_NODES (cinturón de seguridad distinto). Además nunca tenía
cobertura en el informe: un nodo detenido así no generaba ninguna
conclusión, desaparecía en silencio. Renombrado a "nodeLimit" y
añadida su conclusión en el informe.
- **`refTxid` calculado y nunca usado:** el fundamento "cambio
detectado" de cada dirección atribuida guardaba a qué tx se refería
pero ni la UI ni el export Markdown lo mostraban. Ahora ambos lo
citan.
- Comentario de cabecera huérfano tras el refactor a saltos (la
documentación general de "Motor de rastreo forense" quedó pegada
sin fusionar al comentario específico de initForensicTrace) —
consolidado en un único bloque coherente. Referencia de línea
obsoleta a scanWallet, quitada.
- UI: aviso cuando el informe mostrado quedó desactualizado (el
usuario siguió explorando más saltos después de generarlo).
Verificado en navegador: los tres casos de regresión ya usados dan
resultado idéntico (salto simple, cadena de peeling de 3 saltos,
custodio con rama normal continuando), más un caso nuevo con
`stopReason:"nodeLimit"` sintético que confirma que el informe genera
su conclusión sin errores, y el caso coinbase que confirma el fix de
entityMarks.
Txoko Node Dashboard
Suite de auditoría de privacidad Bitcoin para nodos propios.
your node, your rules — ninguna consulta sale de tu red.
Qué es
Txoko es una herramienta de auditoría de privacidad Bitcoin que corre sobre tu propio nodo. Analiza tus transacciones y te explica qué puede deducir un observador externo sobre tu actividad on-chain.
No es un explorador de bloques genérico. Es una herramienta para que el propietario de un nodo audite su propia privacidad con total control sobre sus datos.
Lo esencial: ninguna consulta sale de tu red. Todo el análisis ocurre en tu nodo y en tu navegador. No dependes de servicios externos ni expones qué transacciones o direcciones estás investigando.
Qué NO hace
Tan importante como saber qué hace es saber qué no hace:
- No envía datos a ningún servidor externo — ni analíticas, ni telemetría, ni consultas a APIs de terceros
- No toca claves privadas — el watch-only usa solo tu clave pública (xpub); no puede gastar fondos ni conoce tu semilla
- No identifica a otras personas — es una herramienta de auto-auditoría, no de vigilancia
- No da consejos de inversión — analiza privacidad on-chain, nada más
- No afirma más de lo que sabe — distingue siempre entre CERTEZA, PROBABLE e POSIBLE
- No tiene número de score exacto — muestra bandas (ALTA/MEDIA/BAJA); la precisión numérica sería falsa
- No muestra el contenido de OP_RETURN — solo informa de su presencia y tamaño
Cómo verificar que nada sale de tu red
El código es un único archivo HTML autocontenido. Puedes auditarlo tú mismo:
# Buscar cualquier llamada a dominios externos
grep -E "fetch\(|XMLHttpRequest|src=\"http|href=\"http" dashboard.html
Verás que todas las llamadas van a rutas relativas (/api/, /system/) que apuntan a tu propio nodo vía nginx. No hay ninguna llamada a dominios externos en el código de análisis.
Las únicas dependencias externas son las librerías del frontend (React, Babel) que se cargan desde CDN al abrir la página. Estas no reciben ningún dato de tus transacciones — solo sirven el código de la interfaz.
Funcionalidades
Auditoría de privacidad
- Análisis de transacción con más de 20 heurísticas ponderadas
- Detección de CoinJoin: Whirlpool (denominaciones fijas), WabiSabi (estructura de mezcla), CoinJoin genérico
- Detección de OP_RETURN: presencia y tamaño, sin mostrar contenido
- Detección de tipo legacy (P2PKH/P2SH) vs SegWit/Taproot
- Wallet fingerprinting: Bitcoin Core, Sparrow, BlueWallet, Taproot nativo y otros
- Detección de entidades: OFAC, pools de minería, exchanges conocidos (~745 direcciones)
- Rastro de procedencia: sigue cada input hacia atrás salto a salto, bajo demanda
- Distancia a entidad: a cuántos saltos está lo más cercano de cada tipo marcado
- Informe narrativo: qué puede deducir un analista, en prosa, sin jerga
- Bandas de privacidad con distinción explícita CERTEZA / PROBABLE / POSIBLE
- Exportación del informe en JSON y Markdown
Peritaje forense
- Rastreo de fondos robados o perdidos hacia adelante, salto a salto, desde una transacción de origen hasta un punto de parada natural (custodio identificado, dilución, CoinJoin, o fondos aún sin gastar)
- A demanda: tú decides cuándo se explora cada salto con el botón "Seguir el rastro" — nada corre sin que lo pidas, igual que el rastro de procedencia hacia atrás. Puedes generar el informe con lo explorado hasta ese momento, sin terminar el rastreo entero
- Tope de volumen de transacciones como cinturón de seguridad extra: una dirección con un historial enorme (típico de un hot wallet de exchange) detiene el rastro por precaución, para no intentar paginar decenas de miles de transacciones
- Reutiliza las heurísticas del analizador (CIOH, cambio, huella de wallet, entidades) y añade perfil de dirección (personal vs hot wallet), cambio conductual y comparación de huella entre saltos
- Confirma cadenas de peeling multi-salto, algo que el análisis de una sola transacción no puede hacer por sí solo
- Cada afirmación del informe se etiqueta como HECHO, INFERENCIA (con su propia certeza) o DECLARACIÓN — nunca se mezclan
- Informe exportable a JSON y Markdown con cronología, direcciones atribuidas, fondos sin gastar, conclusiones y metodología
- No identifica la identidad real de nadie; no envía nada a terceros — el informe es tuyo para decidir qué hacer con él
Integración con Sparrow
- Importación de etiquetas BIP-329: carga el
.jsonlque exporta Sparrow y muestra tus propias etiquetas junto al análisis. Se lee en memoria, no sale del navegador - Watch-only por xpub/zpub: pega tu Master Public Key y Txoko deriva tus direcciones en local para marcar, en cada transacción, qué outputs son tuyos (recepción o cambio). La derivación BIP32 está implementada sin librerías externas; el xpub nunca sale del navegador. Requiere HTTPS (ver nota más abajo)
Exploración on-chain
- UTXO Map con score de privacidad por moneda, exportable a CSV
- Explorador de bloques y búsqueda on-chain
- Mempool: stats, fees, fee intelligence, bloques proyectados
Monitor del nodo
- Estado de Bitcoin Core, sistema (CPU, RAM, disco) y logs en tiempo real
- Checklist de seguridad del nodo
Herramientas
- Conversor sat/BTC/fiat
- Validador de dirección
- Detector OP_RETURN
- Decodificador PSBT y transacción raw
Filosofía
- Sin dependencias externas de datos — todo viene de tu propio nodo
- Honestidad sobre la certeza — siempre distingue hechos de inferencias
- Informa, no aconseja — da el dato y la consecuencia; tú decides
- Calibrado al riesgo real — no alarma por lo normal; reserva la alerta para lo que importa
- Ligero por defecto — el rastro de procedencia es bajo demanda para no estresar el nodo
Requisitos
- Bitcoin Core con
txindex=1 - Mempool.space self-hosted (backend API)
- Fulcrum (índice Electrum, recomendado)
- nginx como proxy inverso
- Acceso via Tailscale, red local o similar
Probado sobre Ubuntu Server 24.04 con HP EliteDesk (i5, 32GB RAM, 2TB NVMe).
Instalación
1. Clonar el repositorio
git clone https://git.bitcointxoko.org/pikaro/txoko-dashboard.git
cd txoko-dashboard
2. Copiar el dashboard
cp dashboard.html /var/www/txoko/dashboard.html
# o donde lo sirvas con nginx
3. Copiar el backend de métricas
cp system-metrics.js /home/armg/txoko/system-metrics.js
Editar system-metrics.js y añadir tus credenciales RPC de Bitcoin Core
(el archivo del repo usa placeholders).
4. Configurar el servicio systemd
sudo cp txoko-metrics.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable txoko-metrics
sudo systemctl start txoko-metrics
5. Configurar nginx
Añadir a tu configuración de nginx:
# Dashboard
location /dashboard {
alias /var/www/txoko/dashboard.html;
}
# API Mempool (ajusta el puerto según tu instalación)
location /api/ {
proxy_pass http://localhost:8999;
}
# Métricas del sistema
location /system/ {
proxy_pass http://127.0.0.1:4082;
}
6. Abrir en el navegador
http://TU-IP-TAILSCALE:4080/dashboard
Introduce la URL de tu Mempool en el modal de configuración y empieza a analizar.
Estructura del repositorio
txoko-dashboard/
├── dashboard.html # Frontend completo (HTML + CSS + JS en un solo archivo)
├── system-metrics.js # Backend de métricas del nodo (Node.js)
├── txoko-metrics.service # Servicio systemd
├── README.md
├── SETUP.md
├── CHANGELOG.md
└── LICENSE
El frontend es un único archivo HTML autocontenido. Sin bundler, sin npm, sin proceso de build. Babel transpila el JSX en el navegador. Puedes auditarlo todo abriendo el archivo.
Limitaciones conocidas
- Watch-only requiere HTTPS — la derivación de direcciones desde el xpub usa la Web Crypto API del navegador, que solo está disponible en contextos seguros (HTTPS). Si sirves el dashboard por HTTP, esta función no estará disponible (el resto sí). Ver SETUP.md para configurar un certificado autofirmado. Las etiquetas BIP-329 funcionan por HTTP sin problema
- Watch-only solo Native SegWit (BIP84) — la derivación cubre wallets
wpkh(direcciones bc1q), que son la mayoría. Taproot (BIP86, bc1p) aún no está soportado - Análisis de transacción aislada — sin seguir el grafo completo, algunas heurísticas tienen techo. El rastro de procedencia amplía el contexto pero es bajo demanda y no exhaustivo
- Base de datos de entidades parcial — ~745 direcciones de exchanges, OFAC y minería. Cubre los casos más comunes; no es completa
- Fingerprinting conservador — requiere varias señales coincidentes; prefiere no detectar antes que detectar mal
- Sin análisis de red — no cruza datos con otros nodos ni mempool distribuida
- Peritaje forense sin
/outspend— el backend Mempool self-hosted no expone ese endpoint, así que cada salto se resuelve recorriendo el historial de la dirección receptora. Más peticiones que un/outspenddirecto, con throttling por lotes para no saturar el nodo
Historial de cambios
Los cambios de cada versión se documentan en CHANGELOG.md.
Contribuir
Proyecto en desarrollo activo. Issues y PRs bienvenidos.
Si encuentras un falso positivo en alguna heurística o tienes un caso de prueba interesante, abre un issue con el txid y lo que esperabas ver.
Licencia
MIT — ver LICENSE
₿ txoko · your node, your rules