Como construir um produto sobre um gateway Label 309

Para construir um recurso de Proof of Existence (prova de existência) sem operar uma blockchain você mesmo, você constrói sobre um gateway. Um gateway Label 309 é o motor de publicação por trás de um produto de Proof of Existence: ele faz o trabalho operacional pesado — cotações, uploads, submissão de transações na Cardano, confirmação, tratamento de reorganizações da cadeia, indexação de registros, saldos de conta, financiamento de armazenamento, chaves de API e webhooks — e expõe tudo isso por HTTP puro. O seu produto chama esses endpoints e cuida de tudo o que os seus usuários realmente veem: a interface, a relação de cobrança, o fluxo de trabalho do domínio e a marca.

O núcleo do gateway é código aberto, e o CardanoWall é o produto de referência construído sobre ele. A parte útil para desenvolvedores é que não há porta dos fundos: o CardanoWall acessa o gateway pelos mesmos endpoints públicos que você usaria, então qualquer padrão que funcione para o produto de referência funciona para você.

Quem deve construir sobre um gateway?

Construa sobre um gateway se você quer a Proof of Existence dentro de um produto, e não como uma ação manual que um usuário executa em um site.

Bons casos de uso incluem:

produtos de notarização de documentos;
arquivos de evidências de conformidade;
plataformas de proveniência de IA e governança de conjuntos de dados;
sistemas de prova de integração contínua;
ferramentas de provas jurídicas;
portais de divulgação cifrada;
serviços de autenticidade de mídia;
ferramentas internas de auditoria corporativa;
páginas de prova de editores.

Em todos esses casos, os usuários não querem pensar em construção de transações na Cardano, financiamento de UTxO, créditos de armazenamento ou confirmações na cadeia. Eles querem um fluxo de trabalho que produza provas duráveis e verificáveis. O gateway torna esse fluxo possível sem que a sua equipe precise virar operadora de infraestrutura Cardano.

De que cuida o gateway, e de que cuida o seu produto?

A separação é o ponto central, então vale dizê-la sem rodeios. O gateway é dono do plano base — o pipeline de publicação e todo o estado de dinheiro, cadeia e armazenamento por trás dele:

cotação, upload e publicação;
construção, submissão, confirmação, tratamento de reorganizações e reembolsos de transações na Cardano em caso de falha permanente;
uploads de conteúdo e de texto cifrado para o armazenamento, além do financiamento de armazenamento por trás deles;
um índice compartilhado de registros na cadeia que cobre todos os registros Label 309 da rede;
saldos de conta e os lançamentos contábeis que os movimentam;
precificação cambial e margens;
credenciais de API e entrega de webhooks.

Isso é trabalho de infraestrutura. Tem que ser preciso, observável e entediante em produção. A sua aplicação não deve reimplementá-lo, a menos que operar um gateway seja de fato o seu trabalho — e, se for, veja opere o seu próprio gateway.

O seu produto é dono do plano do fornecedor — tudo aquilo que tem a forma de um produto:

contas e sessões de usuário;
integração inicial e cobrança;
permissões do produto;
a sua interface e os seus e-mails;
a precificação que você apresenta aos clientes;
conceitos de domínio como "caso", "lançamento", "conjunto de dados" ou "pacote de evidências";
modelos de leitura construídos a partir dos eventos do gateway;
fluxos de trabalho de suporte.

O gateway não precisa saber que uma prova pertence a um processo judicial, a uma execução de treinamento de modelo, a um pacote trimestral de conformidade ou a uma edição de revista. Ele só precisa publicar registros Label 309 corretos e manter o estado operacional ao redor deles. Essa separação mantém ambos os sistemas mais limpos: o seu produto pode ser reconstruído ou ter a marca trocada sem tocar no estado de cadeia ou de dinheiro, e o gateway pode ser atualizado sem saber que o seu produto existe.

Como você chama o plano de dados em nome de um usuário?

O plano de dados (/api/v1/*) é a API voltada à conta. Use-o sempre que a ação acontecer em nome de um usuário ou de uma conta:

cotar uma publicação;
fazer upload de conteúdo ou de texto cifrado;
publicar um registro;
ler um saldo ou o ledger da conta;
listar, buscar ou verificar registros públicos;
registrar webhooks com escopo de conta.

Em um produto que é um wrapper, o seu backend emite um account token de curta duração para a conta de gateway do usuário, e o cliente chama o plano de dados apenas com os escopos de que precisa. Os escopos são o limite de permissões: uma tela de publicação precisa de poe:create, um widget de saldo precisa de account:read, e os endpoints de registros públicos não precisam de credencial nenhuma — eles atendem chamadores anônimos, que é o que faz do índice um bem público em vez de uma visão por cliente.

Os tokens têm curta duração por design (uma hora, por padrão). Emita um por sessão e reemita ao expirar, para que um token vazado seja um problema de uma hora em vez de um incidente. E nunca envie credenciais de operador para o navegador — essa é a única regra que a próxima seção existe para proteger.

Como você chama o plano de controle como operador?

O plano de controle (/control/v1/*) é apenas para backends confiáveis e operadores. Use-o para:

criar contas de gateway e habilitá-las ou desabilitá-las;
aplicar ajustes de ledger depois que o seu sistema de cobrança recebe o dinheiro;
definir margens por conta;
emitir account tokens e chaves de API;
registrar o firehose de webhooks do operador;
registrar e gerenciar carteiras e fontes de financiamento de armazenamento;
ler estado de auditoria e operacional.

Esse plano vive atrás do seu backend. Trate as credenciais de operador como segredos de produção com autoridade de gasto — porque é o que elas têm. Um token de operador de curta duração (24 horas, por padrão) cuida da administração do dia a dia; um único segredo raiz, guardado em um cofre de segredos, fica reservado para as poucas operações que registram carteiras e fontes de armazenamento.

O plano de controle é como o seu sistema de cobrança e o saldo pré-pago do gateway permanecem conectados. Um pagamento é bem-sucedido no seu sistema e, em seguida, o seu backend aplica um ajuste de ledger idempotente à conta de gateway. Esse é todo o trilho de crédito, e as próximas duas seções explicam por que ele é construído exatamente assim.

Por que você não deve consultar as tabelas do gateway diretamente?

Porque o schema não é um contrato — a API HTTP e os webhooks é que são.

O motor do gateway é dono dos próprios schemas Postgres (cw_core e cw_api). O seu produto não deve lê-los nem escrevê-los, mesmo quando ambos os sistemas compartilham a mesma instância Postgres. A coexistência de schemas é uma forma de implantação suportada, mas a fronteira é o schema, não o banco de dados: esses schemas do motor são internos e podem mudar sem aviso, enquanto os planos HTTP e o firehose são estáveis. Se você atravessar essa fronteira, uma atualização rotineira do gateway pode quebrar o seu produto silenciosamente.

Se você precisa de dados que a API não expõe, trate isso como uma lacuna da API a ser levantada — não como uma licença para fazer joins entre schemas.

Como você constrói as suas próprias telas a partir dos eventos do gateway?

Todo produto precisa das próprias visões: registros enviados, histórico de clientes, saldos, falhas de publicação, linhas do tempo de casos, pacotes de evidências, painéis de auditoria. Não construa isso fazendo polling de cada linha nem fazendo joins nas entranhas do gateway.

Em vez disso, registre webhooks e projete os eventos nas suas próprias tabelas. O gateway expõe um firehose de operador — todo evento de ciclo de vida na instância — além de assinaturas de webhook com escopo de conta para fluxos mais restritos. Uma visão de "itens enviados" é o exemplo canônico: consuma os eventos de status de publicação, projete-os na sua própria tabela e renderize a partir dela.

A entrega é garantida pelo menos uma vez, então torne a sua projeção idempotente. Um modelo de leitura prático pode usar como chave:

o id do evento ou o id da entrega (para que uma reentrega seja um no-op);
o id do registro no gateway;
o hash final da transação;
o seu próprio id de usuário;
o seu próprio id de objeto de domínio;
status e carimbos de tempo.

A sua interface então renderiza a partir das suas próprias tabelas, enquanto o gateway permanece a autoridade sobre o gasto, o ciclo de vida da publicação e os fatos da cadeia. Cada entrega é assinada; verifique a assinatura e imponha uma janela de tolerância de carimbo de tempo antes de confiar em um evento.

Como o dinheiro deve fluir entre a sua cobrança e o gateway?

Mantenha o modelo simples: o saldo do gateway é o saldo gastável, e o seu sistema de cobrança é apenas uma das formas de o dinheiro chegar até ele.

O seu trilho de cobrança pode receber pagamentos com cartão, faturas, pagamentos em cripto, créditos corporativos manuais ou concessões. O gateway não precisa saber de nada disso. O padrão limpo é:

O seu sistema de cobrança confirma um pagamento.
O seu backend aplica um ajuste de ledger idempotente à conta de gateway, com chave no id do pagamento.
O saldo do gateway aumenta.
Operações futuras de publicação e upload debitam esse saldo.
Se uma publicação falha permanentemente, o próprio gateway reverte o débito.

Disso decorrem duas consequências. Primeiro, a idempotência importa porque os pipelines de cobrança entregam pelo menos uma vez: passe o próprio id do pagamento como referência do ajuste, e cinco entregas de um mesmo pagamento creditam o saldo uma vez só. Segundo, não espelhe o ledger do gateway na sua própria tabela e trate o espelho como verdade para decisões de gasto — faça cache dele para renderização se precisar, mas leia o gateway sempre que a decisão de fato movimentar dinheiro. Como o gateway emite os próprios reembolsos, você também não deve construir um caminho de reembolso do lado do fornecedor para falhas de publicação; isso causaria um reembolso duplicado.

Onde cada tipo de chave deve viver?

Um gateway nunca deve precisar do Identity Seed de um usuário. O cliente ou o SDK consegue calcular o hash do conteúdo, cifrar cargas seladas e assinar registros localmente; o gateway apenas publica os bytes finalizados do registro e submete a transação na Cardano. (Para entender por que essa fronteira importa de ponta a ponta, veja por que as chaves nunca saem do dispositivo.)

Uma integração completa tem várias classes distintas de chave, e o erro a evitar é achatá-las em um único "segredo de API". Elas têm raios de impacto muito diferentes:

Identity Seeds de usuário e chaves privadas de destinatário — a identidade criptográfica do usuário, que pertence à borda da rede;
chaves de assinatura de registro derivadas dessa identidade;
chaves de API de conta e account tokens de curta duração — que pertencem ao produto ou ao contexto de cliente que precisa delas;
tokens de operador e o segredo raiz — que pertencem apenas a backends confiáveis;
as próprias chaves de assinatura Cardano e de armazenamento do gateway, e os seus segredos de assinatura de webhook — que pertencem ao keyring do gateway.

Mapeie cada classe para o menor lugar capaz de mantê-la, e um único vazamento permanece contido.

Quando você deve hospedar o gateway por conta própria em vez de usar um hospedado?

Hospede por conta própria quando a independência operacional importa mais que a conveniência.

Um gateway hospedado é o caminho mais simples para a maioria das integrações: você publica por meio de um serviço pronto, sobre superfícies de API padrão, e nunca executa operações de cadeia ou de armazenamento você mesmo. Hospedar por conta própria troca essa simplicidade por controle — o seu próprio financiamento de carteira Cardano, o seu próprio financiamento de armazenamento, as suas próprias políticas de operador, a sua própria disponibilidade e dependências de rede, as suas próprias margens, a sua própria fronteira de conformidade e nenhuma dependência de um terceiro para publicar.

Mas controle também é responsabilidade. Hospedar por conta própria significa que você financia ADA e créditos de armazenamento, protege o keyring, opera o Postgres, monitora provedores de cadeia, cuida de backups, rotaciona credenciais, gerencia webhooks e responde a incidentes. Isso elimina uma dependência de fornecedor; não elimina o trabalho operacional. Operar o seu próprio gateway detalha o que isso de fato envolve.

O que os seus usuários devem ver em uma prova?

A maioria dos usuários deve ver os conceitos do seu produto primeiro. Eles se importam com "publicar evidência", "selar este arquivo", "provar este instantâneo de conjunto de dados" ou "ancorar este lançamento". Eles não deveriam ter de ler uma especificação de metadados para usar o produto.

Ainda assim, toda visão de prova deve expor os fatos que tornam a afirmação verificável de forma independente:

o hash da transação;
o tempo de bloco e o status de confirmação;
o algoritmo de hash e o digest;
a chave pública de quem assinou, quando o registro está assinado;
as URIs de armazenamento, quando presentes;
o status de destinatário selado, quando relevante;
a raiz Merkle e a prova de folha, quando o registro agrupa vários arquivos;
o próprio veredito da verificação.

É assim que o produto continua agradável de usar sem esconder a afirmação criptográfica que está por baixo.

Como você evita prender o seu produto a um único gateway?

O gateway ajuda você a publicar; ele nunca deve se tornar a prova.

O registro na cadeia é metadados Label 309, e a verificação foi projetada para funcionar a partir de apenas três entradas: os metadados da transação, opcionalmente os bytes do conteúdo e um explorador público da Cardano — com as chaves do destinatário acrescentadas somente para decifrar registros selados. Nenhum servidor de emissor fica nesse caminho de confiança. Se o seu gateway desaparecer amanhã, um registro válido ainda deve verificar com ferramentas independentes. Vale lembrar, também, o que uma prova dessas afirma e o que não afirma: ela mostra que estes bytes exatos existiam até um tempo público, não que qualquer afirmação sobre eles seja verdadeira, de sua propriedade ou autorizada.

Construa o seu produto em torno dessa promessa:

armazene os hashes das transações de forma durável;
permita que os usuários exportem relatórios de verificação e baixem pacotes de evidências;
mantenha as listas de folhas Merkle e as suas provas;
documente como verificar um registro fora da sua interface;
evite campos privados que só o seu backend consegue interpretar.

Essa é a diferença entre "temos uma linha no banco de dados" e "produzimos uma prova que qualquer um pode conferir".

Leitura adicional

O que é um gateway Label 309? e opere o seu próprio gateway — o gateway pelo lado do operador.
Construa sobre a API do CardanoWall e use a CLI em automação — as superfícies voltadas a desenvolvedores em mais detalhe.
Por que publicar tem um preço — o que o saldo pré-pago de fato paga.
O Label 309 é código aberto — o padrão e o seu código de referência.
O padrão de código aberto vive em label309.org; o gateway, os SDKs e a CLI estão em github.com/cardanowall. O Label 309 foi submetido ao processo de CIP da Cardano e está em análise pelos editores de CIP como uma proposta da categoria Metadata.