Saltar al contenido

Billetera con nodo completo

Esta guía cubre la instalación, los modos de ejecución, la configuración, la compilación desde el código fuente, los paquetes macOS y la resolución de problemas de la billetera con nodo completo de Bursa.

Descarga el archivo correspondiente a tu plataforma desde las versiones de Bursa. Los archivos publicados siguen este patrón de nombres:

bursa-wallet-<version>-<os>-<arch>.<ext>
PlataformaArchivoInstalación
macOS arm64 (Apple Silicon).pkgApple firma y notariza el instalador, que instala Bursa.app.
Windows amd64 o arm64.msiWindows firma el instalador.
Linux amd64 o arm64.tar.gzExtrae el archivo para ejecutar la versión con ventana nativa.
FreeBSD amd64 o arm64.tar.gzExtrae el archivo y ejecuta la versión sin ventana nativa en el navegador. FreeBSD no proporciona una versión con ventana nativa.

En Linux o FreeBSD, extrae el archivo y ejecuta el programa bursa-wallet incluido:

Ventana de terminal
tar xzf bursa-wallet-<version>-<os>-<arch>.tar.gz
./bursa-wallet

Después de instalar el paquete macOS o Windows, abre Bursa desde el menú de aplicaciones, o ejecuta directamente el programa:

Ventana de terminal
bursa-wallet

Selecciona la red con -n o --network:

Ventana de terminal
bursa-wallet -n mainnet
bursa-wallet --network musashi

Las redes admitidas son mainnet, preprod, preview, musashi y dijkstra. Bursa selecciona la red en este orden: primero -n o --network, después BURSA_NETWORK y, si ambos faltan, preview; por tanto, la opción de línea de comandos tiene prioridad sobre BURSA_NETWORK. Bursa rechaza los nombres de red desconocidos y los argumentos posicionales adicionales, por lo que la billetera no se inicia en esos casos.

La versión de escritorio abre una ventana nativa. La versión sin ventana nativa sirve la interfaz en loopback, en 127.0.0.1:8090; abre en el navegador la URL completa y autenticada que imprime el proceso, con un formato similar a http://127.0.0.1:<puerto>/#session=<token>. El fragmento #session=... establece una capacidad de sesión local al proceso: la interfaz extrae el valor, elimina el fragmento del historial y lo envía en la cabecera X-Bursa-Session de POST /session; después usa esa cabecera en las solicitudes protegidas. La sesión permanece solo en la memoria de la interfaz. Una recarga de la página elimina la sesión en memoria; después, hay que volver a abrir la URL completa de lanzamiento o reiniciar la billetera de escritorio para establecer una sesión nueva. La billetera escucha en loopback, en 127.0.0.1:8090.

La clave pública de la extensión identifica el emparejamiento. La confirmación requiere comparar la huella o el código que muestra la extensión con el código de confirmación de Bursa Settings para verificar que la autorización corresponde a la extensión esperada.

Para cada solicitud, el conector obtiene un desafío nuevo y de un solo uso. Firma el desafío para esa solicitud usando el método HTTP, la ruta y el cuerpo exactos, y envía el desafío en X-Bursa-Challenge junto con la firma en X-Bursa-Signature. Bursa ya no acepta X-Bursa-Token.

El flujo de eventos del conector usa tickets de evento de corta duración y de un solo uso. Al reconectar, el conector obtiene un ticket nuevo. Al quitar o reemplazar el emparejamiento, Bursa invalida de inmediato y de forma permanente la autorización anterior y cualquier trabajo pendiente del conector.

La primera ejecución sincroniza el nodo integrado. El modo predeterminado mithril arranca desde una instantánea cuando la red seleccionada tiene configuración de agregador de Mithril; de lo contrario, Bursa omite el arranque de Mithril y sincroniza desde la génesis. musashi y dijkstra no tienen configuración de agregador de Mithril. BURSA_SYNC=genesis también fuerza la sincronización desde la génesis. La billetera conserva sus datos bajo ~/.bursa-wallet/<network>/.

Establece las variables de entorno antes de la primera ejecución para inicializar la configuración:

VariableValor predeterminadoEfecto
BURSA_NETWORKpreviewSelecciona una red Cardano y determina el directorio de datos. También admite musashi y dijkstra. La opción -n o --network tiene prioridad sobre esta variable.
BURSA_SYNCmithrilBURSA_SYNC=genesis reproduce la cadena desde el principio en lugar de arrancar desde una instantánea de Mithril.
BURSA_LEANfalseActiva el almacenamiento reducido, que poda los datos históricos de la cadena para ahorrar disco.
BURSA_CONNECTORfalseActiva el backend del conector de dApps.

La billetera conserva los ajustes configurados mediante su interfaz tras la primera ejecución. Cuando un ajuste ya está almacenado, tiene prioridad sobre la variable de entorno.

Instala Go 1.26 o posterior y Node 22. Ejecuta los comandos desde la raíz del repositorio.

Compila los recursos web y el binario predeterminado en Go puro:

Ventana de terminal
make wallet

El comando escribe el binario en ui/bursa-wallet. Esta versión sirve la interfaz por loopback y admite compilación cruzada.

Compila la versión con ventana nativa:

Ventana de terminal
make wallet-webview

Este objetivo requiere CGO, herramientas de compilación C y las cabeceras de desarrollo de webview de la plataforma:

  • macOS: WKWebView.
  • Windows: WebView2.
  • Linux: cabeceras de desarrollo webkit2gtk para compilar y libayatana-appindicator3 para ejecutar. Una compilación con la etiqueta webview necesita ambas para funcionar con soporte de bandeja.

Para los mantenedores de MSI que incluyan el bootstrapper Evergreen de WebView2, el bootstrapper debe tener una firma Authenticode válida. Cuando no se proporciona WEBVIEW2_SHA256, el firmante debe ser Microsoft Corporation. Cuando se proporciona WEBVIEW2_SHA256, el hash fija el artefacto aceptado, pero la firma Authenticode válida sigue siendo obligatoria.

La versión webview no admite compilación para otra arquitectura. Compílala en una máquina con la arquitectura de destino. En Linux puede utilizar webkit2gtk-4.1; el Makefile proporciona una adaptación de pkg-config cuando el enlace del proyecto original solicita 4.0.

Crea un paquete para pruebas locales:

Ventana de terminal
make bundle-macos

Este objetivo genera un .pkg con firma ad hoc. Para generar el paquete de publicación firmado y notarizado:

Ventana de terminal
make pkg-macos

El objetivo pkg-macos requiere los secretos de firma y notarización de Apple.

La sincronización es lenta o parece detenida

Sección titulada «La sincronización es lenta o parece detenida»
  1. Abre Settings → Diagnostics para comprobar el estado del nodo, los pares y la sincronización.
  2. Exporta los registros de diagnóstico o consulta directamente ~/.bursa-wallet/<network>/logs/bursa-wallet.log.

Instala webkit2gtk y sus cabeceras de desarrollo para la versión webview. Instala también libayatana-appindicator3 antes de ejecutar una compilación con la etiqueta webview. Si el sistema no dispone de webview, utiliza la versión de navegador en Go puro y abre la dirección de loopback.

Activa el almacenamiento reducido en la primera ejecución:

Ventana de terminal
BURSA_LEAN=true bursa-wallet

Este modo hace caducar los datos históricos de la cadena y reduce el espacio ocupado en disco.


Doc Holiday logo

Docs authored by Doc Holiday