Rode o seu próprio gateway

Verificar um registro Label 309 não exige nada de ninguém — sem conta, sem servidor, sem chave. Publicar é a outra metade: coloca uma transação na Cardano, e isso tem um custo. O gateway é a peça que paga essa taxa. É ele que guarda a carteira Cardano financiada que ancora o registro (e uma carteira Arweave para os arquivos selados), constrói e envia a transação, acompanha-a até a confirmação e devolve os registros para verificação independente.

Na maioria das vezes, você aponta o seu SDK ou a sua CLI para o gateway de outra pessoa. Mas todo o backend é de código aberto — label-309-gateway, um único binário Rust mais o Postgres — então você pode rodar o seu. Suba um só para você e para os seus próprios aplicativos ou ofereça o seu como serviço pago para outras pessoas: ele é multi-inquilino por natureza, com várias contas e chaves de API sob uma única instância. Este guia leva você do zero à sua primeira cotação com preço usando o Docker Compose de referência.

Antes de começar

Você precisa do Docker e do Docker Compose e de um host com alguns gigabytes de disco livre. Tudo o que vem a seguir tem como alvo a preprod da Cardano — a postura segura para colocar uma implantação no ar. Migrar para a mainnet é uma mudança deliberada que você faz depois, quando a implantação já estiver financiada e verificada.

Obtenha o código e escreva a configuração

Clone o repositório e trabalhe a partir de deploy/, onde fica o docker-compose.yml de referência. Copie a configuração de exemplo e edite-a para a sua implantação — rede, faixa de taxas, armazenamento e precificação:

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

O exemplo vem comentado e já tem a preprod como alvo, então ele sobe como está em uma primeira execução.

Crie o chaveiro

Toda chave de assinatura que o gateway usa fica em um único arquivo de chaveiro criptografado com age. Crie-o e, em seguida, adicione uma chave Cardano (preprod), uma chave Arweave e uma chave de encapsulamento de webhooks. Estes passos de keyring executam o binário gateway diretamente — a ideia é que o chaveiro seja criado em uma máquina confiável e que apenas o seu arquivo criptografado seja copiado para dentro do contêiner, então baixe um build de release do repositório só para este passo.

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 passo add- imprime o endereço que acabou de criar. Financie os dois endereços impressos: o endereço Cardano paga as taxas de ancoragem e o endereço Arweave financia créditos de armazenamento para os arquivos selados. Depois, defina a senha do banco de dados que o compose lê:

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

Suba tudo

Primeiro, provisione o operador. Isso aplica as migrações e imprime o segredo raiz uma única vez — guarde-o em local seguro, pois é a credencial mestra do plano de controle:

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

Depois, inicie o Postgres e o gateway:

docker compose up -d

Registre uma carteira, uma conta e uma chave

O compose não expõe nenhuma porta no host de propósito: os planos de dados e de controle compartilham um mesmo socket, então expô-lo exporia também o plano de controle. Conduza o plano de controle de dentro do contêiner. Abra um shell:

docker compose exec gateway sh

Aponte-o para o plano de controle local com o segredo raiz que o bootstrap imprimiu, depois registre a carteira Cardano financiada (o endereço que o keyring add-cardano imprimiu), crie uma conta, credite-a e emita uma chave de API do plano de dados com escopo para publicação:

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

O key create imprime a chave de API que dá acesso ao plano de dados. Ela, junto com a URL base, é tudo o que um aplicativo precisa.

Faça sua primeira cotação

Para alcançar o plano de dados a partir do host durante a configuração, descomente o mapeamento de ports de loopback (127.0.0.1:8080:8080) no docker-compose.yml e rode docker compose up -d de novo — apenas loopback, nunca 0.0.0.0. Depois, trave um preço com a chave de API que você acabou de emitir:

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}'

A resposta traz um quote_id válido por 15 minutos, além de um detalhamento de custos. Uma chamada de publicação consome esse quote_id de forma atômica junto com o débito no saldo — o mesmo formato em duas etapas, travar um preço e depois enviar, que os guias de SDK usam. Seu gateway está no ar.

Próximos passos

O binário em execução serve a sua própria referência de API interativa — o plano de dados em /api/v1/docs e o plano de controle em /control/v1/docs, cada um renderizado totalmente offline. Dois documentos no repositório vão mais fundo: o manual do operador cobre financiamento, credenciais, a semântica do dinheiro e as operações do dia a dia, e o guia do integrador cobre a construção de um produto por cima.

O plano de dados do seu gateway é exatamente o que os guias de SDK e CLI chamam de URL base. Troque https://your-gateway.example pelo endereço que agora está sob o seu controle, distribua chaves de API e publique sua primeira PoE por meio de um backend que é inteiramente seu.