Metadata Viewer

O que é o Metadata Viewer

Os tipos de registro que a Rede Carrot escreve um a um no registry público — um MassID, um Certificado, um Recibo de Compra de Crédito ou um Recibo de Aposentadoria de Crédito — carregam cada um um documento de proveniência endereçado por conteúdo e armazenado no IPFS. A entrada on-chain guarda a referência, não o conteúdo de proveniência. Ela não é vazia de dados — um Certificado acompanha na cadeia seus montantes total, comprado, aposentado e disponível, e um recibo registra as partes, os montantes e as alocações de certificado —, mas a cadeia de custódia por trás do registro é o que vive no IPFS. Tokens de crédito fungíveis também têm documento de metadados próprio, que descreve o crédito, e não uma unidade ou compra individual. O viewer também abre esses documentos ERC20.

O Metadata Viewer (viewer.carrot.eco) é a ferramenta que segue essa referência e renderiza o documento por trás dela. Ele pode ler a URI de metadados do token no smart contract ou abrir um documento diretamente, para então conferir sua estrutura contra o schema que o próprio registro declara — tudo no navegador de quem está lendo.

Ele responde uma pergunta mais estreita que a do Carrot Registry: não "o que este registro significa em contexto", e sim "o que exatamente este registro diz, e ele concorda com a cadeia". Ele não é, por si só, prova de que um registro está íntegro — o que ele confere é mais estreito que isso, e a diferença está detalhada abaixo.

Como abrir um registro

O viewer lê sua entrada a partir da URL, então qualquer registro pode ser linkado diretamente. Na maioria das vezes quem lê chega por um link já gerado pela plataforma (veja Onde esses links aparecem); o contrato da URL está documentado aqui para que um registro também possa ser aberto à mão.

Por endereço de contrato. Para um registro ERC721, a forma canônica é endereçada pela tripla endereço do contrato, rede e identificador do token:

https://viewer.carrot.eco/?contractAddress=0x<endereço>&network=polygon&tokenId=<token id>

network aceita polygon para a mainnet pública da Polygon (chain ID 137) e amoy para a rede de testes Polygon Amoy (chain ID 80002). O host é o mesmo nas duas — o viewer escolhe a rede por esse parâmetro, e endereços e identificadores de token são locais a cada cadeia, então network precisa nomear a cadeia em que o registro foi escrito.

Por tipo de registro. Para os tipos de registro ERC721 abaixo, na mainnet, o viewer consegue resolver o endereço do contrato sozinho, através do ContractRegistry on-chain, então um tipo de registro substitui o endereço:

https://viewer.carrot.eco/?recordType=mass-id&network=polygon&tokenId=<token id>

Por referência IPFS. Um documento de metadados ou de proveniência também pode ser aberto diretamente pelo seu identificador de conteúdo, sem saber qual contrato o guarda:

https://viewer.carrot.eco/?cid=<cid>

Use essa entrada também para um documento de crédito fungível: cole seu CID, URI ipfs:// ou URL de gateway em IPFS CID, ou use o parâmetro cid da URL acima. Créditos não são opções do seletor recordType e não usam um identificador de token NFT.

Quando o documento fornece uma identidade on-chain suportada, o viewer também pode ler esse contrato para conferir sua referência e seu histórico de publicação. Um CID isolado não comprova vínculo com um contrato.

O viewer também aceita um documento colado ou enviado da máquina de quem está lendo, e é isso que dá sentido a essa ida e volta: dá para saber se um documento que chegou até você corresponde ao documento atual para o qual o contrato e o token do próprio registro apontam.

Onde esses links aparecem

Links do viewer são gerados sempre que um registro é apresentado como evidência:

• O Certificado de Impacto — o PDF emitido para uma compra de créditos — lista os registros públicos daquele pedido na seção Registros públicos, cada um deles um link para o viewer: os recibos de compra e de aposentadoria do pedido. Toda compra é aposentada quando é liquidada, então o PDF lista os dois.
• Registros de certificado carregam um link do viewer para a sua própria entrada no registry, ao lado do link do explorador de blockchain para o mesmo token.

Um Certificado de Impacto emitido é um documento fixo: os links impressos nele são escritos no momento da emissão e nunca são reescritos, então cada um continua apontando para o registro para o qual foi emitido.

O que o registro fixa

Dependendo do tipo de registro, seu formato pode incluir estas âncoras de integridade, independentemente de qualquer ferramenta lê-las:

• O schema, fixado de três formas — uma URL com a versão, uma referência IPFS para esse schema e o hash SHA-256 da versão exata contra a qual o registro foi escrito. Os schemas de registro da Carrot são open source em carrot-foundation/schemas.
• Um hash de auditoria — um hash SHA-256 gravado no momento da emissão, para que quem tenha os dados de origem — enviados pelos Integradores — possa reconciliá-los com o registro publicado. Quem lê o registro público não consegue recalculá-lo apenas a partir dele, porque o documento publicado é tarjado (veja abaixo).
• Uma referência ao build do viewer — veja a seção final desta página.

O que o viewer confere

O viewer informa separadamente estrutura, referências on-chain e histórico de publicação. O sucesso de uma conferência não comprova as demais:

• Estrutura — Para versões de schema suportadas, a validação usa os validadores incluídos no build do viewer. Para uma versão principal anterior ou uma versão mais recente que o build, ele pode validar contra o documento do schema declarado: uma cópia histórica embutida quando disponível, ou uma cópia buscada por HTTPS ou IPFS. A validação não se limita às versões incluídas no build. Se não puder ser executada, o registro permanece sem conferência; a ausência de schema declarado aparece como No schema declared. Uma falha ao carregar o schema declarado pode impedir a abertura do registro. Um documento que falha na validação ainda pode ser exibido com seus problemas estruturais; exibi-lo não significa que passou. A validação estrutural não garante que um build antigo do viewer renderize campos introduzidos depois.
• Ida e volta on-chain — Para um documento ERC721, o viewer lê a URI de metadados do contrato e do token nomeados no documento. Com uma referência IPFS, ele pode distinguir o documento atual, um documento usado anteriormente por aquele token, uma divergência e um histórico que não conseguiu estabelecer. O JSON colado ou enviado é comparado com o documento atual buscado por essa URI; essa comparação isolada não comprova uso histórico. Essa conferência não roda para um documento carregado pelo formulário de contrato, pois o documento já veio daquele contrato. O histórico de publicação ERC20 confere separadamente a tokenURI() atual do contrato de crédito, sem um identificador de token NFT.
• Rede — As leituras on-chain suportam Polygon e Amoy. Elas exigem uma identidade de cadeia suportada; um rótulo de ambiente isolado não estabelece a cadeia. Uma conferência on-chain indisponível não comprova que o documento está errado.

O viewer não recalcula nenhum dos hashes do registro, e não verifica se os bytes devolvidos por um gateway realmente correspondem ao identificador de conteúdo solicitado. O endereçamento por conteúdo torna essa conferência possível — qualquer alteração no documento produz um identificador diferente — mas ela é feita por quem lê, buscando o identificador através de um cliente que valida endereçamento por conteúdo, ou fixando o documento novamente no IPFS e comparando os identificadores.

Documentos de proveniência são públicos, então atributos pessoais e comercialmente sensíveis são omitidos ou mascarados antes da publicação: um atributo marcado como privado fica de fora do documento publicado por completo, e um que continua público mas é sinalizado como sensível é publicado mascarado, com o valor completo preservado para auditores. O que o viewer renderiza é o registro publicado — a cadeia de custódia como ela foi liberada para publicação. A visibilidade é definida por evento, além de por atributo, então um evento marcado como privado fica ausente do documento por completo; o que você está lendo não é necessariamente o histórico operacional completo que um auditor vê.

Histórico de publicação e revisões

A seção Publication history (histórico de publicação) lê eventos TokenURIUpdated antigos e revisados de registros ERC721 e créditos ERC20. Quando o evento fornece essas informações, os detalhes da versão mostram a URI predecessora, o operador e a razão declarada, além da transação e do horário do bloco quando disponível. O operador é o endereço registrado pelo contrato, e não uma lista dos signatários individuais de uma multisig.

Um documento antigo continua aberto naquela versão; o viewer pode oferecer um link para a versão atual. A cobertura do histórico é informada separadamente. Em particular, a URI inicial de metadados de um crédito não é anunciada por um evento de URI na inicialização, então seu histórico pode estar incompleto mesmo quando a atualização atual e sua predecessora são encontradas. Falhas ou limites na leitura de logs também deixam lacunas; eles não comprovam que uma atualização nunca aconteceu.

Um documento pode conter uma declaração revision com previous_uri, uma razão e alterações por campo. O valor comparison: verified ou comparison: unavailable é uma declaração do publicador. Quando a predecessora pode ser recuperada, o viewer compara os documentos de forma independente e mostra valores antes/depois, contradições e alterações não cobertas pela declaração. Essa comparação não comprova a veracidade da razão registrada. Se a predecessora não puder ser lida, não há comparação disponível; o viewer não inventa valores antigos nem infere operações ausentes.

O viewer também é verificável

Uma ferramenta de verificação pela qual só o autor pode responder desloca o problema de confiança em vez de resolvê-lo. Um documento de proveniência pode embutir uma referência IPFS para o próprio build do viewer, fixando a ferramenta por endereço de conteúdo junto do documento. Quando essa referência está presente, quem lê pode executar o build referenciado em vez da cópia servida em viewer.carrot.eco. Nem todo documento inclui esse pin; metadados de créditos fungíveis podem omiti-lo.

Onde ele se encaixa

Três superfícies apresentam os mesmos fatos em profundidades diferentes:

O Registry é onde quem lê começa, partindo de uma pergunta sobre impacto. O Metadata Viewer é onde essa pessoa chega quando a pergunta passa a ser se um registro específico se sustenta por conta própria.

Saiba mais sobre o Carrot Registry · Saiba mais sobre a criação de registros no registry