Levante su propia pasarela

Verificar un registro de Label 309 no le pide nada a nadie: sin cuenta, sin servidor, sin clave. Publicar es la otra mitad: coloca una transacción en Cardano, y eso tiene un coste. La pasarela es la pieza que lo paga. Guarda la billetera de Cardano con fondos que ancla el registro (y una billetera de Arweave para los archivos sellados), construye y envía la transacción, la sigue hasta su consolidación y devuelve los registros para su verificación autónoma.

La mayor parte del tiempo apuntará su SDK o su CLI a la pasarela de otra persona. Pero todo el backend es de código abierto —label-309-gateway, un único binario de Rust más Postgres—, así que puede levantar la suya. Levante una para uso privado con sus propias apps u opere una como servicio de pago para otros: es multiinquilino por diseño, con muchas cuentas y claves de API bajo una sola instancia. Esta guía lo lleva desde cero hasta una primera cotización con precio usando el Docker Compose de referencia.

Antes de empezar

Necesita Docker y Docker Compose, y un host con unos cuantos gigabytes de disco libre. Todo lo que sigue apunta a la red preprod de Cardano: la postura segura para poner en marcha un despliegue. Pasar a mainnet es un cambio deliberado que hará más adelante, una vez que el despliegue tenga fondos y esté verificado.

Consiga el código y escriba la configuración

Clone el repositorio y trabaje desde deploy/, donde se encuentra el docker-compose.yml de referencia. Copie la configuración de ejemplo y edítela para su despliegue: red, banda de comisiones, almacenamiento y precios:

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

El ejemplo está comentado y ya apunta a preprod, así que arranca tal cual para una primera ejecución.

Cree el llavero

Cada clave de firma que usa la pasarela vive en un único archivo de llavero cifrado con age. Créelo y luego añada una clave de Cardano (preprod), una clave de Arweave y una clave de envoltura de webhooks. Estos pasos de keyring ejecutan directamente el binario gateway: el llavero está pensado para crearse en una máquina de confianza y copiar al contenedor únicamente su archivo cifrado, así que para este paso concreto consiga una compilación de release del repositorio.

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

Cada paso add- imprime la dirección que acaba de crear. Añada fondos a las dos direcciones impresas: la dirección de Cardano paga las comisiones de anclaje y la dirección de Arweave financia los créditos de almacenamiento de los archivos sellados. Luego establezca la contraseña de la base de datos que lee el compose:

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

Póngala en marcha

Aprovisione primero el operador. Esto aplica las migraciones e imprime el secreto raíz una sola vez: guárdelo en un lugar seguro, es la credencial maestra del plano de control:

docker compose run --rm gateway operator bootstrap --label acme

Luego arranque Postgres y la pasarela:

docker compose up -d

Registre una billetera, una cuenta y una clave

El compose no publica ningún puerto del host a propósito: el plano de datos y el plano de control comparten un mismo socket, de modo que exponerlo expondría también el plano de control. Maneje el plano de control desde dentro del contenedor. Abra una shell:

docker compose exec gateway sh

Apúntelo al plano de control local con el secreto raíz que imprimió bootstrap, luego registre la billetera de Cardano con fondos (la dirección que imprimió keyring add-cardano), cree una cuenta, acredítela y genere una clave de API del plano de datos con alcance para publicar:

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create imprime la clave de API que gobierna el plano de datos. Eso, junto con la URL base, es todo lo que necesita una app.

Obtenga su primera cotización

Para llegar al plano de datos desde el host durante la configuración, descomente el mapeo de ports de loopback (127.0.0.1:8080:8080) en docker-compose.yml y vuelva a ejecutar docker compose up -d: solo loopback, nunca 0.0.0.0. Luego fije un precio con la clave de API que acaba de generar:

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

La respuesta lleva un quote_id válido durante 15 minutos, junto con un desglose de costes. Una llamada de publicación consume ese quote_id de forma atómica junto con el cargo al saldo: la misma forma en dos pasos —fijar un precio y luego enviar— que usan las guías del SDK. Su pasarela está operativa.

Qué hacer a continuación

El binario en ejecución sirve su propia referencia de API interactiva: el plano de datos en /api/v1/docs y el plano de control en /control/v1/docs, cada uno renderizado por completo sin conexión. Dos documentos del repositorio profundizan más: el manual del operador cubre la financiación, las credenciales, la semántica del dinero y las operaciones del día a día, y la guía del integrador cubre cómo construir un producto encima.

El plano de datos de su pasarela es exactamente lo que las guías del SDK y la CLI llaman una URL base. Sustituya https://your-gateway.example por la dirección que ahora controla, reparta claves de API y publique su primera PoE a través de un backend que es enteramente suyo.