API y servicios de archivo de Dingo
API de aplicaciones
Sección titulada «API de aplicaciones»Las interfaces REST compatibles con Blockfrost, Mesh/Rosetta, UTxO RPC y Kupo de Dingo atienden a clientes de aplicaciones. Requieren storageMode: api, que conserva el historial de transacciones para las consultas. Configura cada servicio bajo plugins.api; establece su puerto en 0 para desactivarlo.
| Interfaz | Protocolo | Puerto predeterminado |
|---|---|---|
| API compatible con Blockfrost | HTTP/REST | 3000 |
| Mesh (Rosetta) | HTTP/REST | 8080 |
| UTxO RPC | Connect/gRPC y HTTP | 9090 |
| API compatible con Kupo | HTTP/REST | Predeterminado: port: 0 (desactivado); ejemplo del proveedor integrado: 1442 |
Kupo utiliza el proveedor integrado. Actívalo con storageMode: api y un puerto distinto de cero. Por ejemplo:
storageMode: apiplugins: api: kupo: provider: builtin config: port: 1442La opción --kupo-provider=builtin selecciona el proveedor integrado desde la línea de comandos. La clave YAML del puerto es plugins.api.kupo.config.port; la variable de entorno correspondiente es DINGO_PLUGINS_API_KUPO_CONFIG_PORT. El proveedor sigue el ciclo normal de inicio y parada del nodo.
Por ejemplo, activa los proveedores integrados de Blockfrost y UTxO RPC en dingo.yaml:
storageMode: apiplugins: api: blockfrost: provider: builtin config: port: 3000 host: 127.0.0.1 maxConcurrentMutations: 4 maxConcurrentMutationsPerClient: 1 utxorpc: provider: builtin config: port: 9090 host: "127.0.0.1"Solicitudes de modificación de Blockfrost
Sección titulada «Solicitudes de modificación de Blockfrost»El proveedor integrado de Blockfrost escucha en 127.0.0.1 de forma predeterminada. No hereda el bindAddr raíz salvo que plugins.api.blockfrost.config.host esté explícitamente vacío. Establece un host concreto para exponerlo en otra interfaz.
Las solicitudes de modificación son anónimas y no requieren credenciales. Dingo deja sin límite cada opción que se omite o se establece en 0: maxConcurrentMutations controla el límite global y maxConcurrentMutationsPerClient, el límite por cliente. Un valor positivo activa el límite correspondiente. Dingo permite configurar un límite positivo por cliente aunque el límite global permanezca desactivado. Cuando maxConcurrentMutations es positivo, maxConcurrentMutationsPerClient debe ser menor o igual que ese valor.
Las siguientes rutas aceptan solicitudes anónimas:
| Ruta | Autenticación y admisión |
|---|---|
POST /api/v0/tx/submit | Acepta solicitudes anónimas y consume capacidad de admisión de modificaciones. |
POST /api/v0/utils/txs/evaluate | Acepta solicitudes anónimas y consume capacidad de admisión de modificaciones. |
POST /api/v0/utils/txs/evaluate/utxos | Acepta solicitudes anónimas y consume capacidad de admisión de modificaciones. |
Conserva la validación de las solicitudes. Dingo comprueba la capacidad antes de leer el cuerpo de la solicitud y solo acepta la solicitud cuando todos los límites habilitados tienen capacidad: el límite global del servidor y, si se configura, el límite del cliente remoto. Si se agota un límite habilitado, Dingo devuelve HTTP 429 con Retry-After: 1. Cuando ambos límites se omiten o se establecen en 0, Dingo no devuelve este 429 por admisión.
Las rutas de modificación aceptan acceso HTTP sin TLS. Conserva el host de loopback predeterminado salvo que decidas expresamente permitir el acceso externo a estas operaciones.
Este sitio incluye la referencia de configuración completa de v0.94.1 y el archivo dingo.yaml.example correspondiente. Utiliza archivos de configuración de la misma versión que el programa; las opciones de los proveedores pueden cambiar entre versiones.
Acceso seguro a las API
Sección titulada «Acceso seguro a las API»La dirección de escucha compartida de las API se aplica a los proveedores seleccionados, incluido Kupo. El proveedor integrado de UTxO RPC escucha en 127.0.0.1 de forma predeterminada. Una dirección de escucha compartida más amplia no cambia este valor. Para permitir el acceso remoto, establece explícitamente plugins.api.utxorpc.config.host. Los ajustes api.tls y api.auth definen valores predeterminados compartidos. Cada proveedor puede sustituir cualquiera de estas políticas en su bloque plugins.api.<name>.config. La configuración TLS específica del proveedor tiene prioridad sobre la compartida.
La autenticación compartida de las API está desactivada de forma predeterminada. Las rutas de modificación del proveedor integrado de Blockfrost aceptan solicitudes anónimas. Los límites de admisión de modificaciones solo se aplican a esas rutas de Blockfrost, no a todas las rutas del servicio.
Cuando actives la autenticación por token, envía Authorization: Bearer <token>. Las rutas HTTP y Connect/gRPC de UTxO RPC también utilizan el token Bearer.
La autenticación se aplica a todas las rutas del servicio, incluidas las comprobaciones de estado. Configura las sondas para enviar el token o utiliza una comprobación TCP si no pueden adjuntar credenciales. Dingo rechaza al inicio los pares de certificado y clave TLS incompletos y no registra el contenido de tokens ni claves.
También puedes situar las API detrás de un proxy inverso o una pasarela de API. Elige un único lugar para terminar TLS y autenticar las solicitudes, y ajusta la política del servicio de Dingo a esa implementación.
Tráfico de archivo de Bark
Sección titulada «Tráfico de archivo de Bark»Bark es un protocolo de archivo entre nodos Dingo, independiente de las API de aplicaciones. Un nodo de archivo puede servir bloques históricos desde almacenamiento de objetos compatible con URL firmadas. Un nodo con caducidad del historial puede recurrir a un archivo Bark cuando caduquen sus archivos de bloques locales antiguos; consulta Arranque y mantenimiento de datos.
Bark no incorpora autenticación para el tráfico de archivo ordinario. Mantenlo en una red de confianza. Ese tráfico sigue separado del LifecycleService opcional.
LifecycleService de Bark
Sección titulada «LifecycleService de Bark»Bark puede exponer un LifecycleService remoto para gestionar el ciclo de vida del nodo. Está desactivado de forma predeterminada. Actívalo con barkLifecycleEnabled: true, --bark-lifecycle-enabled o DINGO_BARK_LIFECYCLE_ENABLED=true.
Antes de iniciar el nodo, configura estos ajustes:
- Establece
barkPorten un puerto distinto de cero mediante--bark-portoDINGO_BARK_PORT. - Establece
barkHostpara elegir la interfaz de red mediante--bark-hostoDINGO_BARK_HOST. Si queda vacío, Bark escucha en0.0.0.0.
El LifecycleService está disponible mediante HTTP sin TLS y no requiere certificados de cliente ni listas de operadores para GetStatus, Stop ni Restart. GetStatus es de solo lectura. Stop y Restart son operaciones destructivas: Stop solicita una parada ordenada y Restart solicita una parada ordenada seguida de un reinicio. Restart no está disponible en plataformas que no sean Unix.
Cuando barkHost expone el servicio fuera de loopback, aplica controles de red para limitar el acceso al LifecycleService.
Bark solo acepta URL firmadas de descarga de bloques cuando su origen HTTPS normalizado coincide con el origen HTTPS normalizado configurado o con un origen de descarga permitido explícitamente. El origen normalizado incluye el esquema, el host en minúsculas y el puerto efectivo. Bark aplica la misma política a los destinos de las redirecciones.
De forma predeterminada, barkBlockDownloadAllowPrivateAddresses es false, por lo que Bark rechaza los destinos de descarga de bloques cuya dirección resuelta sea privada o de uso especial. Establece barkBlockDownloadAllowPrivateAddresses en true, usa --bark-block-download-allow-private-addresses o configura DINGO_BARK_BLOCK_DOWNLOAD_ALLOW_PRIVATE_ADDRESSES=true para permitir esas direcciones únicamente en los destinos de descarga de bloques. Esta opción no desactiva la lista de orígenes permitidos, la exigencia de HTTPS ni la validación de redirecciones.
Para las solicitudes de descarga de bloques, Bark no utiliza los ajustes de proxy HTTP del entorno ni las funciones de conexión proporcionadas por el llamador. Estas reglas solo se aplican a las descargas de bloques; el cliente RPC de Bark, configurado por separado, sigue gestionando las llamadas RPC de archivo.
Docs authored by Doc Holiday