Guía de inicio rápido

Dingo

Un nodo de datos de la blockchain Cardano escrito en Go que participa activamente en las comunicaciones de red en la blockchain Cardano utilizando la familia de mini-protocolos Node-to-Node de la Red Ouroboros.

⚠️ Este es un trabajo en progreso y actualmente está en desarrollo activo

---

En esta guía te guiaremos a través de la descarga del binario de Dingo y todos los pasos necesarios para ejecutar el nodo Dingo en la red Cardano Preview. Para comenzar, sigue los pasos a continuación.

✅ Esta guía asume una configuración típica de Linux. Por favor ajusta los comandos y rutas según sea necesario.

---

Paso 1 - Descargar Binario de Dingo

Descarga la última versión desde la página de versiones de Dingo.

⚠️ Ajusta la versión y la arquitectura para que coincidan con tu sistema.

mkdir -p ~/dingo
cd ~/dingo
  wget https://github.com/blinklabs-io/dingo/releases/download/v0.86.0/dingo-v0.86.0-linux-amd64.tar.gz -O - | tar -xz

Puedes verificar que el binario funciona ejecutando:

./dingo version

Alternativa: instalar con npm

Como alternativa al archivo comprimido, instala el paquete @blinklabs/dingo. La instalación requiere Node.js 22 o posterior. El paquete admite Linux, FreeBSD y macOS en arquitecturas x64/amd64 o arm64.

npm install --global @blinklabs/dingo
dingo --help

El paquete descarga el binario nativo correspondiente, valida su suma de comprobación SHA-256 y lo instala de forma atómica. El instalador solo sigue recursos de lanzamiento aprobados a través de HTTPS. Rechaza las URL que no usan HTTPS o no están permitidas, las URL con credenciales o puertos diferentes de 443 y los destinos de redirección o los resultados de DNS que resuelven a direcciones privadas o de uso especial. Para usarlo sin una instalación global:

npx @blinklabs/dingo --help

Después de una instalación global, usa dingo en lugar de ./dingo en los pasos restantes.

Ejecutar una DevNet local de un solo nodo

El comando inicia la DevNet local con un solo nodo:

./dingo devnet

Una instalación global de npm permite ejecutar dingo devnet; sin una instalación global, npx ejecuta:

npx @blinklabs/dingo devnet

De forma predeterminada, Dingo guarda la configuración, las claves de prueba y la base de datos en un directorio temporal privado. Dingo elimina ese directorio cuando el nodo termina, incluso después de Ctrl+C. Cada ejecución inicia una cadena nueva y deja intacto el directorio actual.

Dingo instala el faucet local con los archivos faucet.skey, faucet.vkey y faucet.addr en cardano/keys/. En una ejecución temporal, Dingo crea estos archivos en cardano/keys/ dentro del directorio temporal privado. En una ejecución persistente, Dingo los deja disponibles en <data-dir>/cardano/keys/. El archivo faucet.addr recibe 900,000 ADA de prueba en el génesis (900_000_000_000 lovelace). Dingo instala las credenciales con permisos exclusivos del propietario.

El parámetro --data-dir permite conservar una cadena para reutilizarla:

./dingo devnet --data-dir ./.dingo-devnet

Al repetir este comando, Dingo reanuda esa cadena. El estado se restablece con:

./dingo devnet --data-dir ./.dingo-devnet --reset

Al reanudar una ejecución persistente sin --reset, Dingo restaura y actualiza únicamente las credenciales del faucet, sin restablecer las credenciales del productor, la asignación del génesis ni los datos de la cadena. Usa --reset para recrear intencionalmente el estado administrado por Dingo.

La primera ejecución requiere un directorio vacío. Dingo coloca un marcador antes de crear la base de datos, la configuración generada y las copias de las claves de prueba. --reset solo recrea las rutas que administra Dingo y conserva otros archivos del directorio. Dingo rechaza otra ejecución que use el mismo directorio, incluido un intento de restablecerlo mientras el nodo está en ejecución. Estas claves y esta red solo sirven para pruebas locales; el uso con fondos reales queda excluido.

---

Paso 2 - Crear archivo de configuración dingo.yaml

Para consultar todos los ajustes de Dingo v0.86.0, sus valores predeterminados y sus alternativas de entorno y línea de comandos, consulta la referencia de configuración (en inglés). Descarga el dingo.yaml.example correspondiente a la versión v0.86.0 como punto de partida para tu configuración.

Dingo incluye configuraciones de red de Cardano integradas (archivos de génesis y config.json) para preview, preprod, mainnet y prime-testnet. Las configuraciones integradas usan config.json, excepto prime-testnet, que usa configuration.yaml. No necesitas descargarlas por separado.

Crea un archivo dingo.yaml en tu directorio dingo. La variable $HOME se expandirá automáticamente a la ruta de tu directorio de inicio:

cat <<EOF > ~/dingo/dingo.yaml
# Ruta de datos compartida para los almacenes locales de blob y metadata.
databasePath: "$HOME/dingo/.dingo"

# Plugins de almacenamiento y API
plugins:
  storage:
    blob:
      provider: "badger"
      config:
        # Directorio de datos opcional de Badger. Cuando no se define, se usa databasePath.
        # dataDir: "$HOME/dingo/.dingo/badger"
    metadata:
      provider: "sqlite"
      config:
        # Directorio de datos opcional de SQLite. Cuando no se define, se usa databasePath.
        # dataDir: "$HOME/dingo/.dingo/metadata.db"

  api:
    blockfrost:
      provider: "builtin"
      config:
        port: 0
    mesh:
      provider: "builtin"
      config:
        port: 0
    utxorpc:
      provider: "builtin"
      config:
        port: 0

# Mempool
# plugins.mempool.config.capacity es una anulación opcional, no un ajuste requerido.
# Predeterminado: 1 MiB para el modo Praos y el modo serve normal, y 25 MiB para el modo Musashi.
# Deja la clave comentada o omítela para usar el valor predeterminado del modo.
# plugins:
#   mempool:
#     config:
#       capacity: 1048576

# Mithril
mithril:
  aggregatorUrl: ""
  cleanupAfterLoad: true
  enabled: true
  verifyCertificates: true
  # En v1, pinnedDigest usa un digest de instantánea; en v2 usa un hash de artefacto de base de datos de Cardano. Dingo usa este valor solo en un arranque nuevo con una base de datos vacía.
  # pinnedDigest: ""

# Network
# Límite total de conexiones NtC. Predeterminado: 100. Dingo ignora los valores no positivos.
maxNtCConns: 100
# Alias de CLI: --max-ntc-conns. Variable de entorno: DINGO_MAX_NTC_CONNS.
# Límite de conexiones NtC por dirección IP. Predeterminado: 5. Dingo ignora los valores no positivos.
maxNtCConnectionsPerIP: 5
# Alias de CLI: --max-ntc-connections-per-ip. Variable de entorno: DINGO_MAX_NTC_CONNECTIONS_PER_IP.
bindAddr: "0.0.0.0"
# La dirección de métricas es independiente de bindAddr y, de forma predeterminada, usa loopback.
# Alias de CLI: --metrics-bind-addr. Variable de entorno: DINGO_METRICS_BIND_ADDR.
metricsBindAddr: "127.0.0.1"
metricsPort: 12798
# metricsPort: 0 desactiva el listener de métricas.
# Alias de CLI: --health-port. Variable de entorno: DINGO_HEALTH_PORT.
# healthPort: 0 desactiva el listener de salud.
healthPort: 12799
# Alias de CLI: --health-ready-gap-slots. Variable de entorno: DINGO_HEALTH_READY_GAP_SLOTS.
healthReadyGapSlots: 1000
debugPort: 0
network: "preview"
privateBindAddr: "127.0.0.1"
privatePort: 3002
relayPort: 3001
socketPath: "$HOME/dingo/dingo.socket"


# Storage
barkBaseUrl: ""
barkPort: 0
storageMode: "core"
EOF

📝 Deja debugPort en 0 salvo que se necesite perfilado. debugPort controla un listener pprof opcional, sigue separado de metricsPort y permanece deshabilitado con 0.

💡 Las APIs solo arrancan dentro de storageMode: "api", y asignar 0 a un puerto desactiva esa API.

midnight:
  serverEnabled: false
  reflectionEnabled: false
  allowInsecureRemote: false
  port: 50051
  host: "127.0.0.1"
  authTokenPolicyId: ""
  authTokenAssetName: ""
storageMode: "api"
plugins:
  api:
    blockfrost:
      provider: "builtin"
      config:
        port: 3000
    mesh:
      provider: "builtin"
      config:
        port: 8080
    utxorpc:
      provider: "builtin"
      config:
        port: 9090

📝 Dingo requiere midnight.authTokenPolicyId y midnight.authTokenAssetName juntos o ambos vacíos. Si solo uno tiene valor, la validación de la configuración falla durante el arranque y Dingo no inicia. midnight.authTokenPolicyId debe tener 56 caracteres hexadecimales y decodificarse en 28 bytes. Dingo acepta un token de autenticación solo si el ID de política y el nombre del activo coinciden exactamente con los valores configurados.

📝 Para que Midnight sirva por gRPC, configure storageMode: "api", midnight.serverEnabled: true y un valor distinto de 0 en midnight.port. La indexación y el servicio son controles independientes. midnight.reflectionEnabled está deshabilitado de forma predeterminada; midnight.reflectionEnabled: true activa la reflexión y requiere midnight.serverEnabled: true. Dingo mantiene el servidor gRPC deshabilitado cuando midnight.serverEnabled es false. 127.0.0.1 es el host predeterminado, incluso cuando midnight.host está vacío. Dingo limita el texto plano a direcciones de loopback; para exponer el servicio en una dirección que no sea de loopback, active midnight.allowInsecureRemote: true para texto plano o configure tlsCertFilePath y tlsKeyFilePath para TLS.

💡 Configurar block-cache-size e index-cache-size a 0 con compression: false usa la caché de páginas del SO (mmap) en lugar de las cachés internas de BadgerDB. Esto reduce drásticamente el uso de memoria.

---

Paso 3 - Abrir Puertos

Cubriremos cómo agregar reglas de firewall UFW para los puertos que Dingo necesita.

💡 Consejo: UFW significa Uncomplicated Firewall y se usa para administrar reglas de firewall iptables (netfilter).

Para ver qué puertos están actualmente abiertos:

sudo ufw status numbered

Agregar puerto 3001 para comunicación Ouroboros Node to Node (NtN)

sudo ufw allow 3001/tcp

---

Paso 4 - Iniciar desde instantánea de Mithril

Dingo tiene un cliente Mithril integrado que descarga y carga una instantánea automáticamente. Esto ahorra horas de tiempo de sincronización en comparación con reproducir la cadena desde el génesis.

Ejecuta el siguiente comando desde tu directorio dingo:

cd ~/dingo
./dingo mithril sync --config ~/dingo/dingo.yaml

📝 mithril.downloadMaxTransientRetries controla los reintentos ante fallos transitorios en la descarga de arranque, como tiempos de espera de TLS, respuestas HTTP 429 y respuestas HTTP 5xx. El ejemplo usa el valor predeterminado de 10.

📝 El listener de salud usa el puerto 12799. Las rutas /health y /healthz son comprobaciones de actividad y verifican que el bucle de eventos responda. La ruta /readyz es la comprobación de disponibilidad: informa que el nodo está listo cuando se conoce la brecha de slots respecto a la punta de la red y no supera healthReadyGapSlots, la base de datos está disponible y, para los productores de bloques, el forjador está en ejecución y las credenciales se pueden usar; cuando corresponde, también requiere que KES remoto esté disponible. Informa que no está listo cuando la brecha no se conoce o supera ese límite, la base de datos no está disponible, no se cumplen los requisitos del productor de bloques o KES remoto no está disponible cuando corresponde. Dingo mantiene estas comprobaciones disponibles durante el arranque de Mithril.

Dingo:

1. Descargará la última instantánea de Mithril para tu red configurada
2. Verificará la cadena de certificados
3. Cargará la instantánea en la base de datos

Esto toma aproximadamente 10-15 minutos dependiendo de tu sistema y velocidad de red.

📝 Si omites este paso, Dingo se sincronizará desde el génesis al iniciarse, lo que toma significativamente más tiempo.

---

Paso 5 - Iniciar Dingo

Una vez que la instantánea de Mithril se haya cargado, inicia el nodo:

cd ~/dingo
./dingo serve --config ~/dingo/dingo.yaml

📝 La comprobación de salud del contenedor usa /health en el puerto 12799, no /metrics.

Deberías ver la salida del registro mostrando el nodo conectándose a los pares y sincronizando los bloques restantes para alcanzar la punta de la cadena.

---

¿Interesado en usar un servicio systemd para ejecutar un nodo Dingo y maximizar el tiempo de actividad reiniciando automáticamente el nodo Dingo cuando la computadora se reinicia?

Consulta nuestra guía sobre cómo crear un servicio de inicio para Dingo.

---

¡Felicidades, estás listo para comenzar a usar el nodo Dingo!

Aprende cómo interactuar con Dingo usando la CLI de Cardano.

---

Docs authored by Doc Holiday