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 são registros do registry, mas não carregam documento de proveniência próprio e o viewer não os abre.

O Metadata Viewer (viewer.carrot.eco) é a ferramenta que segue essa referência e renderiza o documento por trás dela. Ele lê a URI de metadados do token diretamente do smart contract, busca o documento no IPFS e o confere 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. A forma canônica. Um registro é endereçado 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. 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 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>

Isso ainda lê a cadeia: o registro nomeia o próprio contrato e token, e a conferência de ida e volta descrita abaixo relê esse contrato para confirmar que o documento bate. O que o identificador poupa é ter que saber o endereço.

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ê é o mesmo que o contrato e o token do próprio registro resolvem.

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: o recibo de compra e, quando o pedido foi aposentado na mesma transação, o recibo de aposentadoria. Um pedido aposentado depois, em transação separada, gera o recibo de aposentadoria após a emissão do PDF.
• 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

As âncoras de integridade do registro fazem parte do seu formato e existem 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

Três conferências rodam, e cada uma reporta o seu próprio status. Elas são mais estreitas que as âncoras acima, e a diferença importa se você depende delas:

• Estrutura — O documento é validado contra a cópia do schema fixada no build do viewer, casada pela URL de schema que o registro declara. Quando um registro declara uma versão que o build não carrega, o viewer reporta não conferido estruturalmente em vez de validar, e campos introduzidos depois daquele build não são renderizados.
• Ida e volta on-chain — Quando um documento é aberto pela referência IPFS, ou colado ou enviado, o viewer relê a URI de metadados do contrato e do token que o próprio registro nomeia e exige que ela resolva para o mesmo documento: verified ou mismatch. É a conferência mais forte que o viewer faz. Ela não roda quando o registro é aberto por endereço de contrato, porque nesse caso o documento veio daquele contrato desde o início.
• Rede — A rede embutida no registro precisa ser uma das duas cadeias suportadas; caso contrário o registro é rejeitado.

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ê.

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. Todo registro de proveniência da Carrot embute uma referência IPFS para o próprio build do viewer, de modo que a ferramenta que lê o registro fica fixada por endereço de conteúdo, exatamente como o documento que ela lê. Quem não quiser confiar na cópia servida em viewer.carrot.eco pode executar o build referenciado.

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