← Todos os posts

11 min de leitura

Como usar a CardanoWall sem o site

O site é uma interface, não o produto inteiro. Você pode publicar e verificar registros Label 309 por uma CLI, pelos SDKs, por uma API de gateway, por um aplicativo de desktop ou pelo seu próprio serviço.

Você pode usar a CardanoWall sem nunca abrir o site. Os mesmos registros de Proof of Existence (prova de existência) podem ser criados, publicados e verificados a partir de uma ferramenta de linha de comando, de um SDK no código da sua aplicação, de uma API de gateway, de um aplicativo de desktop ou de um serviço que você mesmo executa. O site é apenas uma das frentes sobre um padrão aberto — o Label 309 — e o padrão é o que realmente importa.

Essa distinção é o ponto central. Muitas vezes, o Proof of Existence não é uma ação humana isolada. Ele pertence a um pipeline de build, a uma rotina de conformidade, a um sistema de proveniência de IA, a um fluxo de trabalho de provas jurídicas ou a um produto construído por outra pessoa. Nada disso deveria exigir que alguém clicasse por uma única interface web.

O que o site realmente faz?

O site torna o Proof of Existence acessível. Ele oferece um compositor visual, uma visão da conta e do saldo, páginas de registro, gerenciamento de identidade, um fluxo de upload e uma publicação guiada. Para a maioria das pessoas, é o lugar certo para começar.

Mas ele não deveria ser a única forma de usar o padrão. Se uma prova só funciona quando uma pessoa clica por uma interface, ela não pode se tornar infraestrutura. Empresas precisam de automação. Pessoas que desenvolvem precisam de APIs e SDKs. Equipes de operações e de segurança precisam de fluxos de trabalho repetíveis e roteirizáveis. Algumas pessoas querem seus registros e arquivos na própria máquina. Alguns operadores querem executar todo o pipeline por conta própria.

O aplicativo web é a porta da frente. Ele não é o prédio inteiro.

Quais são as outras formas de usar?

Há várias, e todas convergem para o mesmo artefato — um registro Label 309 padrão, ancorado na Cardano, que qualquer pessoa pode verificar de forma independente:

  • o aplicativo web da CardanoWall;
  • a ferramenta de linha de comando cardanowall, de código aberto;
  • os SDKs oficiais (TypeScript, Python, Rust) para o código da sua aplicação;
  • uma API de gateway Label 309, acessada com um token por conta;
  • o CardanoWall Desktop, o cliente local-first de código aberto;
  • um gateway que você mesmo hospeda;
  • o seu próprio produto construído sobre um gateway.

A interface pode mudar. O formato da prova não. Todo esse código é aberto em github.com/cardanowall, licenciado sob Apache-2.0, com o texto da especificação sob CC-BY-4.0.

Quando devo usar a API de gateway?

Use a API quando publicar ou ler provas precisa fazer parte de um sistema, e não ser uma etapa manual. Por exemplo:

  • um produto SaaS cria uma prova para cada documento de cliente;
  • um pipeline de build publica evidências de lançamento após cada build;
  • uma plataforma de IA ancora lotes de saídas geradas;
  • um sistema de conformidade publica um instantâneo de controle diário;
  • um fluxo de trabalho sela evidências para destinatários específicos;
  • um painel interno lê o status de publicação e o saldo da conta;
  • a integração de um parceiro envia registros sem tocar na interface da CardanoWall.

O caminho da API permite que o seu software chame um gateway diretamente enquanto você mantém a sua própria experiência de usuário. O próprio aplicativo web e o worker da CardanoWall acessam o gateway por exatamente esses endpoints públicos — não há porta privada, então tudo o que o produto de referência faz, você também pode fazer. Se quiser se aprofundar aqui, veja construa sobre a API da CardanoWall.

Como funcionam os tokens e escopos da API?

Um gateway distingue dois tipos de credencial, e mantê-los separados é a coisa mais importante a acertar.

Tokens de conta agem como um dos seus usuários. O seu backend gera um token de curta duração para uma conta específica e a chamada prossegue sob ele: solicitar uma cotação, fazer upload de conteúdo, publicar, ler o saldo dessa conta. São esses os tokens — e as chaves de API construídas sobre o mesmo modelo — que pertencem a scripts, jobs de CI e integrações. Eles são deliberadamente restritos. O conjunto atual de escopos é pequeno e desenhado para um propósito:

  • poe:create — solicitar cotações, fazer upload de conteúdo, publicar registros;
  • poe:read — ler registros e o status de publicação;
  • inbox:read — ler o marcador de sincronização da Inbox cifrada;
  • account:read — ler o saldo da conta.

Essa é toda a superfície programática, e ela é restrita de propósito. Um widget de painel somente leitura precisa apenas de account:read. Um job de publicação precisa de poe:create. Nenhum precisa do outro. Não existe, intencionalmente, nenhum escopo de decifração no servidor: selar e abrir são operações no cliente, então as chaves privadas do destinatário nunca chegam a um gateway e nenhuma chave de API jamais poderia autorizar o servidor a ler conteúdo selado em seu nome. Da mesma forma, um job de CI nunca deveria guardar o Identity Seed de um usuário, a menos que a assinatura local seja uma parte deliberada do seu próprio design, sob os seus próprios controles — sementes e chaves privadas permanecem no cliente por design e não são algo que um gateway jamais veja.

Credenciais de operador são o segundo tipo, e não são chaves de API. Elas autorizam o plano de controle — provisionar contas, aplicar ajustes de saldo quando a sua cobrança recebe dinheiro, definir margens, gerar os tokens de conta acima. Elas devem viver apenas em um backend confiável, nunca em um navegador, em um aplicativo móvel ou em um script. Um token de conta vazado deveria ser um incômodo de curta duração; uma credencial de operador vazada seria um incidente de verdade.

A regra prática: entregue aos clientes o token restrito ao escopo de conta de que eles precisam e mantenha a autoridade de operador atrás do seu próprio backend.

Quando devo usar a CLI?

Use a ferramenta de linha de comando quando uma prova pertencer a um script. O binário cardanowall é agnóstico quanto ao gateway e raw-seed-first, o que o torna uma escolha natural para:

  • verificar um registro localmente, sem abrir nenhum site;
  • construir e checar provas Merkle sobre muitos arquivos;
  • assinar registros;
  • enviar registros a partir de automação;
  • sincronização da Inbox e decifração por tentativa a partir do terminal.

A CLI importa sobretudo porque mantém o Proof of Existence perto dos sistemas que geram os artefatos. Um pipeline de build pode calcular o hash das suas saídas e publicar um registro como parte do lançamento. Um job de conformidade pode registrar um manifesto diário. Um usuário local pode verificar um registro offline. O site é ótimo para pessoas; a CLI é ótima para operações repetíveis. Para padrões e exemplos, veja use a CLI em automação.

Quando devo usar um SDK?

Use um SDK quando o Label 309 deve fazer parte da sua aplicação. Os SDKs em TypeScript, Python e Rust ajudam a construir registros, calcular o hash de conteúdo, verificar transações, assinar fora do host, selar e decifrar payloads, derivar identidade a partir de uma semente e conversar com qualquer gateway.

O sentido de ter três SDKs não é comodidade — é interoperabilidade. Eles são gêmeos idênticos em bytes, validados contra os mesmos vetores de teste canônicos, de modo que um registro publicado ou assinado por um verifica de forma idêntica sob os outros. É assim que um padrão aberto continua sendo um padrão aberto, em vez de se fragmentar em formatos "compatíveis" mutuamente incompatíveis. Uma propriedade útil que vale destacar: o verificador autônomo precisa apenas dos metadados da transação, opcionalmente dos bytes do conteúdo e de um explorador público da Cardano — nenhum servidor emissor fica no caminho de confiança.

Quando devo usar o Desktop em vez do site?

Use o aplicativo de desktop quando a propriedade local importa. O CardanoWall Desktop é um cliente de código aberto, multiplataforma e offline-first, construído em Rust com Tauri sobre o SDK em Rust, e funciona como um cliente de e-mail: ele oferece a você

  • cofres de identidade locais e cifrados;
  • acesso offline a tudo o que já foi sincronizado;
  • descoberta de Inbox selada e texto cifrado em cache na sua própria máquina;
  • busca local sobre o índice público de registros;
  • múltiplas identidades e a sua escolha de provedor de gateway.

O site continua rápido e prático, enquanto o aplicativo de desktop é o melhor lugar quando você quer que seus registros, identidades e arquivos em cache vivam localmente e continuem funcionando sem rede. Para muitas pessoas, a resposta será os dois. Há mais sobre o design em CardanoWall Desktop e provas offline.

Quando devo hospedar meu próprio gateway?

Hospede por conta própria quando quiser operar o pipeline de publicação você mesmo — por conformidade, estrutura de custos, volume, política de tratamento de dados, controle de infraestrutura ou estratégia de produto.

Um gateway auto-hospedado ainda publica registros Label 309 padrão; a diferença é que você executa o serviço que cota, faz upload, envia, confirma, indexa e contabiliza a publicação. O gateway é um único binário Rust de código aberto mais Postgres, com seu próprio construtor de transações Cardano que constrói, envia, confirma, lida com reorganizações de cadeia e faz reembolso automático em caso de falha permanente.

Hospedar por conta própria não é "grátis". Você ainda paga os custos subjacentes da Cardano e do Arweave, e assume a responsabilidade operacional de executá-lo. O que você remove é qualquer dependência de um gateway CardanoWall hospedado para publicar. Veja execute o seu próprio gateway e o que é um gateway Label 309?.

Posso construir meu próprio produto sobre um gateway?

Sim — e essa separação é exatamente o motivo de o gateway ser uma camada própria, distinta do aplicativo web. Você pode construir um produto de notarização, um portal de evidências, um arquivo de conformidade, uma ferramenta de publicação, um serviço de proveniência de IA ou um painel interno sobre um gateway Label 309.

O gateway é dono do plano base: cadeia, armazenamento, precificação, o índice compartilhado de registros na cadeia, saldos e status de publicação. O seu produto é dono do plano de fornecedor: usuários, cobrança, UI, fluxos de trabalho, notificações, suporte e qualquer significado específico do produto que você atribua aos registros. Isso permite que muito mais produtos compartilhem um único padrão de prova sem que cada equipe precise se tornar uma operadora de transações e armazenamento Cardano. O passo a passo está em construa sobre um gateway Label 309.

Posso verificar sem usar a CardanoWall?

Esse é o objetivo, e é a razão mais forte para que o resto exista. A verificação não pode depender do site da CardanoWall. Qualquer pessoa deveria conseguir ler os metadados da transação, reconstruir o registro Label 309, validar a sua estrutura, checar quaisquer assinaturas do registro, recalcular o hash do conteúdo e — com a chave certa — decifrar um registro selado localmente.

Uma prova que só um site consegue verificar é uma prova fraca. SDKs abertos, uma CLI aberta e uma especificação aberta são o que torna uma prova Label 309 verificável por qualquer pessoa, incluindo terceiros que nunca tocam na CardanoWall. Se quiser fazer isso você mesmo, comece por verifique um registro Label 309.

E quanto à precificação?

Mudar a interface não elimina o custo subjacente. Quer você publique a partir do site, do aplicativo de desktop, da CLI, da API ou do seu próprio produto, alguém ainda paga taxas reais de transação da Cardano mais qualquer armazenamento usado para arquivos ou texto cifrado. Um gateway hospedado acrescenta uma margem por cima para cobrir operações, financiamento, infraestrutura e suporte, então o preço é o repasse de custo mais essa margem.

Se você usa o gateway hospedado da CardanoWall, usa o seu modelo de saldo pré-pago e precificação. Se hospeda por conta própria, opera e financia o seu próprio gateway diretamente. De qualquer forma, o padrão torna o registro portátil — ele não torna blockchains ou armazenamento gratuitos. O raciocínio está detalhado em por que publicar tem um preço.

Um limite importante

Uma prova Label 309 mostra que bytes específicos existiam até um determinado momento público e que não mudaram desde então. Ela não prova quem é o autor do conteúdo, quem é o dono, se ele é verdadeiro ou se alguém tem direitos sobre ele. Um registro selado mantém o seu texto claro legível apenas pelos detentores da chave pretendidos, mas não pode garantir anonimato e não pode impedir que um destinatário vaze o texto claro depois de tê-lo decifrado. Tenha esse limite em mente, qualquer que seja a interface a partir da qual você publica.

A versão curta

A CardanoWall não é apenas um site. O site é a interface humana mais fácil; o gateway é a camada de publicação; a CLI e os SDKs são as superfícies para quem desenvolve; o aplicativo de desktop é o cliente local e offline-first; a auto-hospedagem é o caminho do operador. Todos produzem a mesma coisa: um registro Label 309 padrão que pode ser verificado fora da interface que o criou.

Escolha a interface que combina com o trabalho. Use o site para pessoas, a CLI para scripts, os SDKs para produtos, a API para sistemas e um gateway auto-hospedado quando o que você precisa é independência de fornecedor ou controle operacional.

Leitura adicional

developersapigatewayself-hosting