pikaro/txoko-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: pikaro/txoko-dashboard:a6fe438b0612916e72934a0a565ea9a8508bfc7f
Branches Tags
pikaro/txoko-dashboard:main
pikaro/txoko-dashboard:v1.13.0 pikaro/txoko-dashboard:v1.12.1
...
compare: pikaro/txoko-dashboard:2abcdee144ef40026adb3d4607827769fea0f6e1
Branches Tags
pikaro/txoko-dashboard:main
pikaro/txoko-dashboard:v1.13.0 pikaro/txoko-dashboard:v1.12.1
15 Commits
a6fe438b06 ... 2abcdee144
Author SHA1 Message Date
Aitor 2abcdee144 fix: pinear versión de Babel standalone en el CDN (7.23.10) 2026-07-16 22:24:51 +02:00
Aitor 50c19ebc9f fix: pasada de calidad sobre el módulo Peritaje forense 
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.
 2026-07-16 15:03:00 +02:00
Aitor a5d58dadd4 fix: podar solo la rama de custodio, no la transacción entera 
Cuando un salto se detenía por custodyStop (entidad conocida, hot
wallet, o tope de tx_count), se descartaban los DOS outputs de esa
transacción, no solo el que disparó la parada — un pago normal junto
a un depósito de exchange en la misma tx se perdía igual. Mixer,
dilución y el tope global de nodos siguen bloqueando la transacción
entera (afectan a todos sus outputs por igual, por construcción); un
custodio es propiedad de UNA dirección concreta y ahora se evalúa por
dirección: `custodyByAddr` sustituye al `custodyStop` único, y solo
esa dirección se excluye del encolado y de la semilla CIOH. El nodo
sigue guardando `custodyStop` (primera coincidencia, para el texto
del informe) y el nuevo `custodyAddrs` (todas), y el texto de las
conclusiones pasa a nombrar la dirección concreta en vez de "la
transacción", que ya no es preciso cuando otra rama sigue su curso.

Verificado en navegador: los dos casos de regresión ya usados
(salto simple, cadena de peeling de 3 saltos) dan resultado idéntico
entre el modo automático y el modo por saltos, sin cambios. Caso
nuevo dedicado — un salto con un output de custodio (79.828 tx) junto
a un output normal — confirma que la rama normal se sigue explorando
un salto más, sus fondos aparecen correctamente como localizados,
la dirección de custodio recibe una sola petición (nunca se pagina),
y el CIOH atribuye la rama continuada sin incluir la del custodio.
Caso de dilución confirma que ese stop sigue bloqueando ambos
outputs, sin regresión.
 2026-07-16 14:42:45 +02:00
Aitor 4280274239 docs: actualizar CHANGELOG/README para el rastreo a demanda 
Refleja el cambio de modelo del peritaje forense: de "automático
acotado con seguir más saltos" a "a demanda, salto a salto, con
control manual del usuario", más el tope de tx_count como cinturón
de seguridad adicional. El mecanismo antiguo "seguir más saltos (+4)"
ya no existe en el código — se documenta el que lo reemplaza.
 2026-07-16 14:26:05 +02:00
Aitor 7f3e2b5abc feat: rastreo forense a demanda — salto a salto, botón "seguir el rastro" 
PeritajeForense pasa de "un clic, rastreo automático completo" a "un
clic por salto": el usuario ve el progreso (salto actual, tx
exploradas, ramas pendientes, ramas terminales) y decide cuándo
avanzar, igual que ya funciona el rastro de procedencia hacia atrás
(RastroProcedencia). El rastreo se guarda en un ref mutable
(traceRef) entre clics — initForensicTrace + advanceForensicHop del
commit anterior encajan directamente, sin cambios.

"Iniciar rastreo forense" ahora también ejecuta el primer salto (un
clic para ver algo). "Generar informe" está disponible desde el
primer salto, no solo al terminar, y puede volver a pulsarse en
cualquier momento — incluida la declaración del afectado, editable
mientras el rastreo sigue en marcha. Los campos txid/vout/importe se
deshabilitan una vez iniciado (no tienen efecto a mitad de rastreo);
el tope de saltos y la declaración siguen editables.

Quita el mecanismo antiguo "seguir más saltos (+4)": ya no tiene
sentido con control manual salto a salto, y el texto de ramas
truncadas por el tope se reescribe para no prometer una reanudación
que el motor no soporta (una rama ya truncada no se puede retomar
suelta).

Verificado en navegador con un servidor HTTP local que sirve la
cadena de peeling de 3 saltos ya usada en pruebas anteriores,
pulsando "seguir el rastro" cuatro veces manualmente: el progreso
avanza correctamente salto a salto (1→2→3→4), termina con "rastro
completo", y el informe generado es idéntico en contenido al que
produce el modo automático (misma cadena de peeling CERTEZA, mismas
direcciones atribuidas, mismos fondos sin gastar). Export JSON/MD y
"Limpiar" verificados sin errores de consola.
 2026-07-16 14:24:29 +02:00
Aitor b9477c6139 feat: tope de tx_count como cinturón de seguridad en el peritaje 
LARGE_ADDR_TX_COUNT=5000: si el perfil de una dirección de salida
tiene chain_stats.tx_count por encima del umbral, se trata como
custodio presunto (stopReason="exchange", byVolume:true) aunque el
heurístico de perfil no la clasifique "hot_wallet" (p.ej. residual
momentáneamente alto en el momento de la consulta). No cuesta
peticiones extra — chain_stats ya se pide para el perfil de toda
dirección de salida nueva.

Cierra el hueco identificado en la auditoría previa: sin este tope,
una dirección enorme no detectada por el heurístico se encolaría para
el siguiente salto, y findSpendingTx intentaría paginar hasta 200 de
sus transacciones (8 páginas × 8s de timeout, ~64s en el peor caso)
buscando una entre decenas de miles, sin ninguna posibilidad realista
de encontrarla.

El texto del informe distingue este caso: es HECHO (medida de
protección, con el tx_count real citado), no INFERENCIA sobre quién
controla la dirección — a diferencia de una parada por ENTITY_INDEX o
por el heurístico de hot wallet, aquí no se afirma nada sobre la
naturaleza de la dirección.

Verificado en navegador con un caso sintético diseñado para que el
heurístico de perfil NO dispare (residual del 100%, fuera del umbral
<0.05) pero con tx_count=79.828 (el caso real que se va a probar): el
tope se activa correctamente y la dirección enorme recibe EXACTAMENTE
1 petición (el perfil barato) — nunca se llega a paginar su historial.
 2026-07-16 13:57:09 +02:00
Aitor 039c916f55 refactor: buildForensicGraph a avance por saltos (initForensicTrace + advanceForensicHop) 
Separa el motor en tres piezas para poder pausar entre saltos: crear
el estado del rastreo (initForensicTrace), avanzar UN salto completo
(advanceForensicHop, con el mismo throttling por lotes BATCH=5/
PAUSE=120ms de siempre dentro de ese salto) y ensamblar el
ForensicGraph desde el estado en cualquier momento, completo o
parcial (finalizeForensicGraph). buildForensicGraph se mantiene como
caso trivial que llama advanceForensicHop en bucle — modo automático
de una sola pasada, sin cambio de comportamiento.

Prepara el terreno para que la UI (pestaña Peritaje) deje que el
usuario decida cuándo seguir al siguiente salto, en vez de que el
motor drene todas las ramas sin vigilancia. Es la primera de las
protecciones acordadas contra el estrés al nodo con direcciones de
volumen enorme (hot wallets de exchange).

Verificado: balance de sintaxis + node --check sobre el fragmento
puro. En navegador, los dos casos sintéticos ya usados (salto simple,
cadena de peeling de 3 saltos) dan resultado IDÉNTICO byte a byte
entre el modo automático (buildForensicGraph) y el modo por saltos
manual (initForensicTrace + advanceForensicHop en bucle) — grafo,
clusters, cadenas de peeling y conclusiones del informe coinciden.
También verificado que finalizeForensicGraph + buildForensicReport
funcionan correctamente sobre estado PARCIAL (tras un solo salto, sin
terminar el rastreo), que es justo lo que necesitará la UI a demanda.
 2026-07-16 13:52:02 +02:00
Aitor d8c1e845b3 docs: documentar módulo Peritaje forense implementado 
CHANGELOG (1.10.0) y README reflejan que el peritaje forense ya está
implementado, no solo especificado: qué hace, qué heurísticas reutiliza
y cuáles son nuevas, el marco HECHO/INFERENCIA/DECLARACION, y la
limitación conocida de depender de /api/address/{addr}/txs en vez de
/outspend (el backend Mempool self-hosted no lo expone).
 2026-07-16 12:51:30 +02:00
Aitor fcc19c31e1 feat: peritaje forense — pestaña UI y componente PeritajeForense 
Nueva pestaña "PERITAJE" junto a las existentes. Formulario de entrada
(txid:vout, importe estimado robado opcional, declaración en texto
libre), botón "Iniciar rastreo forense" con progreso por salto, y
render completo del informe (resumen, declaración, cronología,
direcciones atribuidas, fondos sin gastar, aviso de ramas truncadas
con botón "seguir más saltos", conclusiones, recomendaciones,
metodología, anexo de verificación) con export JSON/MD inline, mismo
patrón que el informe de wallet.

Verificado en navegador (servidor estático local):
- Balance de sintaxis del bloque Babel correcto, sin errores de
  transpilación JSX en consola.
- Validación del formulario (txid vacío/inválido, nodo no conectado)
  funciona.
- Motor completo probado con datos sintéticos vía consola: caso simple
  (1 salto, cambio detectado correctamente, 2 ramas terminan en UTXO
  sin gastar) y caso de cadena de peeling de 3 saltos (detectada con
  certeza CERTEZA, direcciones de cambio atribuidas con fundamento
  correcto, 4 fondos sin gastar localizados en las hojas).

Cierra la implementación del módulo Peritaje descrito en TRASPASO.md.
 2026-07-16 12:43:32 +02:00
Aitor 6f3ca4ed7a feat: peritaje forense — generador de informe (buildForensicReport) 
Ensambla las secciones de la plantilla (spec en TRASPASO.md) sobre el
grafo de buildForensicGraph: resumen, declaración del afectado,
cronología, direcciones atribuidas (CIOH + cambio detectado + huella
estable), fondos sin gastar, conclusiones numeradas, recomendaciones
(con el aviso anti-estafa de "recuperación" fijo cuando hay
declaración), metodología y anexo de verificación.

Marco HECHO/INFERENCIA/DECLARACION aplicado en cada afirmación; el
export a JSON/MD queda para la UI (mismo patrón inline que el informe
de wallet, sin función compartida hoy).

También: buildForensicGraph ahora guarda origin.analysis y
node.changeAddress (dirección resuelta, no el índice) para que el
informe no tenga que reindexar en addresses.out, que al deduplicar
podría desalinearse con el orden real de vout.
 2026-07-16 12:27:18 +02:00
Aitor 6fcffb2096 feat: peritaje forense — motor de rastreo multi-salto (buildForensicGraph) 
Rastreo hacia adelante desde {txid,vout} siguiendo TODOS los outputs de
cada salto (no solo el presunto cambio) porque los fondos pueden
repartirse en varias ramas; cada rama se detiene de forma
independiente. Condiciones de parada: CoinJoin real, dilución (3+
direcciones de entrada no relacionadas), entidad conocida o perfil de
hot wallet no indexado, UTXO sin gastar, límite de saltos.

findSpendingTx implementa el fallback ya verificado en la sesión
anterior (TRASPASO.md): este backend Mempool no expone /outspend, así
que se recorre /api/address/{addr}/txs buscando la tx cuyo vin
referencia el txid:vout de origen — mismo patrón de paginación y
throttling por lotes que scanWallet.

detectPeelingChains cierra el hueco que el check `peeling` de
analyzeTx ya señalaba (confirmar una cadena requiere mirar hacia
adelante): reconstruye tramos de nodos 1-in/2-out conectados por la
señal de cambio combinada, sube a CERTEZA con 3+ saltos y huella de
wallet estable.

MAX_NODES=80 como red de seguridad aparte de maxHops, para no hammer
el nodo del usuario si un salto desemboca en una tx con muchos
outputs. Verificado: balance de sintaxis del bloque Babel y
node --check sobre el fragmento JS puro del motor.
 2026-07-16 12:22:28 +02:00
Aitor ee817a8c9b feat: peritaje forense — cambio conductual y comparación de huella 
behavioralChangeGuess: para cada output, si se gasta rápido (≤6
bloques) o queda quieto (no gastado todavía). combineChangeSignals
cruza esto con la señal estructural de guessChangeOutput — sube la
certeza cuando coinciden, reporta la discrepancia en vez de forzar
una conclusión cuando no.

compareFingerprints compara la huella de detectWallets entre dos
saltos consecutivos del rastro: un cambio de huella es
INFERENCIA/POSIBLE de cambio de actor o entrada en infraestructura
de un servicio, nunca CERTEZA.
 2026-07-16 12:13:05 +02:00
Aitor 2e97a6b822 feat: peritaje forense — heurística de perfil de dirección 
addressProfile(addr, addrInfo, addrTxs) clasifica personal vs hot
wallet usando chain_stats (residual/tx_count) y detección de barrido
automático (recibe y reenvía 1-in/1-out sin cambio, pocos bloques
después). No identifica al custodio, solo el patrón de comportamiento;
la atribución a un exchange concreto sigue viniendo de ENTITY_INDEX.

Primera pieza nueva del módulo Peritaje (spec en TRASPASO.md), sobre
la base de los refactors de unionFindCluster y guessChangeOutput.
 2026-07-16 12:11:53 +02:00
Aitor 133e292aab refactor: extraer guessChangeOutput de analyzeTx (señales A-F de cambio) 
Autocontenida para poder llamarse por salto desde el futuro motor de
rastreo forense, que necesita saber qué output concreto seguir (no solo
si el cambio es identificable). analyzeTx delega en ella sin cambio de
comportamiento — mismas señales, mismos umbrales, mismo texto.
 2026-07-16 12:10:09 +02:00
Aitor e89fea499c refactor: extraer unionFindCluster de buildWalletReport a utilidad compartida 
Prepara la reutilización del union-find CIOH en el módulo de peritaje
forense (semilla = direcciones del actor rastreado en vez de mis
direcciones). Sin cambio de comportamiento en el informe de wallet.
 2026-07-16 12:06:25 +02:00
3 changed files with 1199 additions and 80 deletions
Expand all files Collapse all files
CHANGELOG.md
+58
View File
@@ -10,6 +10,64 @@ y el versionado sigue [Versionado Semántico](https://semver.org/lang/es/):
- **MENOR** — características nuevas que no rompen lo anterior
- **PARCHE** — arreglos de errores
---
## [1.10.0] — 2026-07-16
### Añadido
- Peritaje forense: nueva pestaña que rastrea fondos robados o perdidos hacia
adelante, salto a salto, desde una transacción de origen (`txid:vout`) hasta
un punto de parada natural — custodio identificado, dilución excesiva,
CoinJoin real, o fondos aún sin gastar. Todo el rastreo corre sobre tu
propio nodo (Bitcoin Core + Fulcrum + Mempool self-hosted), como el resto
de la app: ninguna consulta sale de tu red.
- Sigue todos los outputs de cada salto (no solo el presunto cambio),
porque los fondos pueden repartirse en varias ramas; cada rama se
detiene de forma independiente.
- **A demanda, salto a salto:** el rastreo no corre solo — tú decides
cuándo se explora el siguiente salto con el botón "Seguir el rastro",
viendo en todo momento cuántas transacciones se han explorado y
cuántas ramas quedan pendientes. Mismo espíritu que el rastro de
procedencia hacia atrás (RastroProcedencia), aplicado al rastreo hacia
adelante. Puedes generar el informe con lo explorado hasta ese momento,
sin necesidad de terminar el rastreo entero.
- Tope de volumen de transacciones (`tx_count`) como cinturón de
seguridad aparte del control manual: si una dirección de salida tiene
un historial extremadamente largo (miles de transacciones — típico de
un hot wallet de exchange), el rastro se detiene ahí por precaución
aunque el heurístico de perfil no la clasifique como custodio. Evita
que una sola rama intente paginar el historial completo de una
dirección con decenas de miles de transacciones.
- Reutiliza las heurísticas existentes del analizador (CIOH, detección de
cambio estructural, huella de wallet, CoinJoin, entidades conocidas) y
añade tres nuevas: perfil de dirección (personal vs hot wallet de
exchange), cambio conductual (se gasta rápido vs queda quieto) cruzado
con la señal estructural, y comparación de huella de software entre
saltos consecutivos.
- Confirma cadenas de peeling multi-salto: el check de patrón de pago
simple ya avisaba de que una sola transacción no basta para confirmar
una cadena — este módulo es lo que cierra ese hueco, siguiendo el rastro
hacia adelante de verdad.
- Marco de tres niveles en cada afirmación del informe: HECHO (dato
on-chain verificable), INFERENCIA (conclusión de una heurística, con su
propia sub-etiqueta CERTEZA/PROBABLE/POSIBLE) y DECLARACIÓN (lo que
cuenta el afectado, en un formulario de texto libre, siempre mostrado
aparte y nunca mezclado con los hechos).
- Informe con resumen, declaración del afectado, cronología, direcciones
atribuidas con su fundamento, fondos localizados sin gastar,
conclusiones numeradas, recomendaciones (con un aviso fijo contra
estafas de "recuperación de fondos" siempre que hay declaración),
metodología y anexo de verificación. Exportable a JSON y Markdown, igual
que el informe de wallet.
- No identifica la identidad real de nadie: como mucho llega a "hot wallet
de [exchange]" o "custodio no identificado". No hace denuncias ni envíos
automáticos a terceros — el informe es un documento que decides tú a
dónde llevar.
### Cambiado
- `unionFindCluster` (vinculación por CIOH) y `guessChangeOutput` (señales de
cambio estructural) se extrajeron de `buildWalletReport` y `analyzeTx`
respectivamente a funciones compartidas, sin cambio de comportamiento, para
que el peritaje forense las reutilice salto a salto.
---
## [1.9.0] — 2026-06-12
### Añadido
README.md
+11
View File
@@ -60,6 +60,16 @@ Las únicas dependencias externas son las librerías del frontend (React, Babel)
- 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 `.jsonl` que 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)
@@ -193,6 +203,7 @@ El frontend es un único archivo HTML autocontenido. Sin bundler, sin npm, sin p
- **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 `/outspend` directo, con throttling por lotes para no saturar el nodo
---
dashboard.html
+1130 -80
View File
File diff suppressed because it is too large Load Diff