Usa la CLI de CardanoWall en CI/CD y scripts

Recurre a la CLI cardanowall cuando la prueba de existencia tenga que ejecutarse dentro de un script en lugar de un navegador. Está pensada para la automatización: pasa --json para obtener datos legibles por máquina en stdout, trata stderr como diagnósticos y ramifica según un pequeño conjunto de códigos de salida estables. Con eso basta para integrarla en CI/CD, en tus pipelines de publicación, en trabajos de cumplimiento y en herramientas internas de auditoría.

La CLI puede verificar registros sin una cuenta de CardanoWall, publicar pruebas a través de cualquier gateway Label 309, firmar registros en local, derivar una identidad a partir de una semilla, construir y comprobar pruebas de Merkle, y leer un Inbox sellado. Es la misma herramienta de código abierto que cualquiera puede ejecutar, publicada en crates.io con el binario cardanowall —sin alias cw—, y el código fuente vive en github.com/cardanowall.

¿Por qué usar la CLI en lugar del sitio web?

El sitio web está hecho para personas. La automatización necesita otra cosa:

comandos deterministas que puedas ejecutar sin supervisión;
salida legible por máquina;
códigos de salida estables sobre los que ramificar;
ninguna sesión de navegador que conducir;
configuración explícita del gateway en lugar de una cuenta con sesión iniciada;
secretos leídos desde stdin, un archivo o una variable de entorno, nunca tecleados en un mensaje interactivo;
registros que puedas archivar junto al trabajo.

Eso es exactamente lo que te da la CLI, y mantiene la prueba cerca del sistema que realmente produce el material probatorio.

¿Cómo verifico una prueba en un script?

La verificación es el comando más fácil de automatizar y el más útil para ejecutar en cualquier sitio:

cardanowall verify <tx-hash> --json

Verificar no requiere una cuenta de CardanoWall ni un operador de gateway. Lee los metadatos de la transacción desde un explorador público de Cardano (compatible con Koios o Blockfrost), opcionalmente obtiene el contenido desde gateways públicos de Arweave o IPFS, valida el registro y comprueba cualquier firma. Ese es justamente el sentido del estándar: una prueba que verificaste una vez sigue siendo verificable de forma independiente por cualquiera, sin confiar en el emisor, en su dominio ni en su servidor.

Para un control más estricto, apúntala a tu propia fuente de datos y fija una profundidad de confirmación:

cardanowall verify <tx-hash> \
  --cardano-gateway https://api.koios.rest/api/v1 \
  --threshold 20 \
  --json

Los datos van a stdout y los diagnósticos van a stderr, así que la composición de comandos se mantiene limpia:

if cardanowall verify "$TX_HASH" --json > verify-report.json; then
  echo "proof verified"
else
  code=$?
  echo "verification did not pass, exit code: $code" >&2
fi

Para profundizar en lo que comprueba realmente un verificador, consulta cómo verificar un registro Label 309.

¿Qué significan los códigos de salida?

Ramifica según el código de salida en lugar de analizar el texto legible por humanos: el código ya te dice la clase de resultado:

Código	Significado
`0`	válido / éxito
`1`	fallo de clase integridad (falló una comprobación criptográfica o estructural)
`2`	fallo de clase red o resultado no verificable (un error de obtención o de transporte)
`3`	pendiente: normalmente, confirmaciones insuficientes
`4`	error de entrada de la CLI (argumentos incorrectos o falta una entrada obligatoria)

Para verify, los códigos 0–3 se corresponden directamente con el veredicto del verificador —valid, failed, unverifiable y pending, respectivamente—, de modo que rige el mismo contrato tanto si lees el código de salida como el informe --json.

Eso le da a la automatización una política clara:

0: continúa.
1: haz fallar el trabajo; falló la comprobación de la prueba o del contenido.
2: reintenta o marca la ejecución como no concluyente.
3: espera y reintenta tras más confirmaciones.
4: corrige el script o sus entradas.

En un flujo de publicación, no trates pending como un éxito. Una prueba pendiente puede confirmarse más tarde, pero todavía no es final.

¿Cómo publico una prueba desde la automatización?

Publicar necesita un gateway, porque envía una transacción real de Cardano y descuenta de tu saldo en el gateway para pagar la comisión de la transacción y cualquier almacenamiento en Arweave. (Sobre por qué publicar cuesta algo, consulta por qué publicar tiene un precio.)

Calcula el hash de un archivo y ánclalo:

cardanowall submit \
  --file ./release-manifest.json \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY" \
  --json

Ancla un digest precalculado:

cardanowall submit --hash <64-hex-digest> --json

Ancla un lote de Merkle construido a partir de una lista de hojas:

cardanowall submit --merkle ./leaves.txt --json

Estos tres modos encajan limpiamente con patrones habituales de automatización. Un trabajo pequeño puede anclar un solo archivo. Un sistema de publicación puede anclar el digest de un manifiesto precalculado. Un sistema de alto volumen puede plegar muchos hashes de elementos en una única raíz de Merkle y publicar un solo registro. La primera pasada completa se cubre en publica tu primera prueba.

Ejecuta cardanowall <command> --help para obtener la lista de opciones oficial y acorde a tu versión: esa es siempre la última palabra sobre las opciones de tu instalación.

¿Cómo configuro los gateways una vez en lugar de en cada trabajo?

Fijar a fuego una URL de gateway y una clave de API en cada trabajo es frágil. En su lugar, la CLI guarda perfiles de gateway con nombre:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall gateway list

En CI, alimenta la clave desde stdin en lugar de responder a un mensaje interactivo:

cardanowall gateway add prod \
  --base-url https://your-gateway.example \
  --api-key-stdin < ./gateway-api-key.txt

El gateway del servicio se resuelve en un orden fijo: gana una opción explícita, luego la variable de entorno y luego el perfil activo. Ese reparto se adapta a ambos entornos: una persona desarrolladora puede apoyarse en un perfil guardado, mientras que CI inyecta CARDANOWALL_BASE_URL y CARDANOWALL_API_KEY y se salta por completo el archivo de configuración.

¿Cómo mantengo los secretos fuera de la línea de comandos?

Este es un error fácil de cometer, así que conviene ponérselo difícil. Nunca pongas una semilla de identidad o una clave de destinatario en bruto directamente en los argumentos del comando: argv se filtra al historial del shell, a los registros de CI y a los listados de procesos (ps).

Usa en su lugar una fuente de entrada segura:

--seed-stdin o --seed-file;
--secret-key-stdin o --secret-key-file;
una variable de entorno, solo cuando el manejo de secretos de tu CI esté limpio.

Por ejemplo, pasa la semilla por stdin:

printf '%s' "$CARDANOWALL_SEED" | \
  cardanowall submit --file ./manifest.json --seed-stdin --json

Un secreto debe provenir de exactamente una fuente; suministrarlo desde dos a la vez (digamos un --seed-file obsoleto más CARDANOWALL_SEED) es un error de entrada irrecuperable, de modo que un valor antiguo nunca puede tapar en silencio al que pretendías usar. Las opciones de argv --seed y --secret-key en bruto siguen existiendo para valores de prueba desechables, pero imprimen una advertencia de una línea en stderr cuando se usan. Trata esa advertencia como un control real, no como ruido. Y como las claves nunca necesitan viajar a un servidor para hacer este trabajo, la semilla permanece en la máquina que ejecuta el comando: el principio detrás de por qué las claves nunca salen del dispositivo.

¿Cómo firmo un registro en un pipeline?

Un registro firmado prueba no solo que el contenido existió, sino que la clave de un proyecto u organización concretos respondió por él. Las firmas de autoría siempre son opcionales en Label 309 —una prueba basada solo en el hash es igual de válida—, pero resultan útiles cuando importa la procedencia.

Para una firma local sencilla, adjunta la semilla de forma segura en la propia publicación:

cardanowall submit --file ./release.json --seed-stdin --json

Para entornos más estrictos, mantén la clave completamente fuera del host de compilación y firma en dos pasos:

cardanowall sign prepare --signer-pubkey <hex> --hash <hex>
cardanowall sign assemble --signer-pubkey <hex> --signature <hex> --in record.cbor

Ese reparto permite que un KMS, un HSM, una estación de trabajo sin conexión o un servicio de firma protegido produzcan la firma Ed25519, mientras el pipeline de automatización se encarga del ensamblado del registro y de la publicación sin tocar nunca la clave privada.

¿Cómo agrupo miles de artefactos en un solo registro?

Las raíces de Merkle son la forma en que un flujo de la CLI escala. En lugar de una transacción por artefacto, construye una lista de hojas y ancla la raíz:

cardanowall merkle build --in leaves.txt --json > merkle.json
cardanowall submit --merkle ./leaves.txt --json

Más adelante, prueba una sola hoja con su prueba de inclusión:

cardanowall merkle verify \
  --root <hex32> \
  --leaf <hex32> \
  --proof proof.json

Esto encaja muy bien con el material probatorio de publicaciones de CI/CD, lotes de contenido generado por IA, manifiestos de conjuntos de datos, instantáneas de cumplimiento, archivos de registros y paquetes de procedencia de medios. Guarda la lista de hojas y las pruebas de inclusión junto con el resto de tu material probatorio de publicación: la raíz en cadena es solo la mitad de la historia de verificación posterior. El patrón se cubre en profundidad en un registro para miles de archivos, y el enfoque de CI en pruebas en tu pipeline de CI/CD.

¿Cuándo debe la automatización manejar registros sellados?

La CLI también puede trabajar con PoE sellada: registros cifrados dirigidos a uno o varios destinatarios:

cardanowall inbox sync --seed-stdin
cardanowall inbox list --seed-stdin --json
cardanowall inbox decrypt <tx-hash> --secret-key-stdin

Ejecuta esto solo en máquinas autorizadas a custodiar la clave del destinatario. No metas una clave de destinatario en un entorno de CI genérico a menos que ese trabajo forme parte explícitamente de la frontera de procesamiento de confianza del destinatario. Descifrar también produce texto plano: un proceso que puede descifrar puede, en principio, filtrar lo que descifra, así que sitúa ese paso allí donde la clave ya tiene su lugar.

Para la mayor parte de la automatización pública verificarás pruebas firmadas o basadas solo en el hash, y nunca tocarás una clave de destinatario. Recurre a los comandos de Inbox sellado cuando estés construyendo una recepción privada de material probatorio, una entrega confidencial o un archivado controlado.

¿Qué debería archivar un trabajo de CI?

Archiva el informe de la prueba, no solo el hash de la transacción. Una buena ejecución conserva:

la versión de la CLI;
los argumentos del comando, con los secretos redactados;
el manifiesto de entrada o el digest del archivo;
el hash de la transacción;
la salida de publicación --json;
el informe de verificación --json;
la lista de hojas de Merkle y las pruebas de inclusión, si se usaron;
la identidad firmante de cualquier registro firmado;
los registros de reintento para los resultados pendientes o no verificables.

Eso da a los futuros auditores suficiente contexto para reproducir la comprobación sin que nadie tenga que reconstruir cómo se cableó un trabajo de publicación meses antes.

Un patrón práctico de publicación

Un trabajo de publicación puede tener esta forma:

Compila los artefactos.
Genera sumas de comprobación, SBOMs, atestaciones y un manifiesto de publicación.
Calcula el hash del manifiesto, o construye una lista de hojas de Merkle.
Publica con cardanowall submit.
Captura el hash de la transacción y espera las confirmaciones.
Ejecuta cardanowall verify.
Guarda los informes JSON junto con los artefactos de publicación.
Haz fallar la publicación con failed; reintenta o detente con pending y unverifiable.

Nada de esto es complicado, y ese es el punto. La prueba debería ser lo bastante aburrida como para ejecutarse en cada publicación.

Más lecturas

Construye sobre la API de CardanoWall: cuando un script no basta y quieres conducir el gateway directamente.
La CLI y los SDK de código abierto: github.com/cardanowall
El estándar Label 309: label309.org