Snapshots

Os content servers irão periodicamente compilar resumos das entidades ativas que estão hospedando, chamados snapshots. Eles são arquivos regulares files e podem ser baixados usando seu identificador.

Snapshots são criados diariamente, semanalmente, mensalmente e anualmente. Cada um contém o conjunto de entidades ativas que mudaram desde o snapshot anterior para esse intervalo.

Snapshots conterão versões conflitantes das mesmas entidades (ou seja, diferentes manifest files associados ao mesmo pointer) conforme são atualizados. Ao examiná-los, os clientes devem manter a versão presente no snapshot mais recente. Como os content servers podem excluir arquivos inativos, versões antigas de entidades não são garantidas para download.

Quando um novo snapshot replaces os mais antigos (por exemplo, um snapshot semanal que combina uma série de diários), seus metadados indicam quais arquivos anteriores são substituídos para que os clientes não precisem baixá-los.

O conjunto completo de entidades ativas pode ser descoberto combinando todos os snapshots disponíveis (mais abaixo há mais detalhes), mantendo a entidade mais recente referenciada por cada pointer descoberto ao longo do caminho.

Você pode experimentar com snapshots usando código funcional na practice seção.

Descobrindo Snapshots

Para localizar o conjunto atual de snapshots, use o snapshots endpoint. A resposta contém um array de itens com estes campos:

Campo	Valor
generationTimestamp	O timestamp Unix UTC quando este snapshot foi criado.
hash	O snapshot file.
numberOfEntities	O número de entradas no arquivo de snapshot.
replacedSnapshotHashes	Um array com os hash de quaisquer snapshots substituídos por este.
timeRange.initTimestamp	O timestamp Unix UTC (em milissegundos) para o início do intervalo do snapshot.
timerange.endTimestamp	O timestamp Unix UTC (em milissegundos) para o fim do intervalo do snapshot.

Por exemplo:

{
  "generationTimestamp": 1684979298844,
  "hash": "bafybeiflmm46nr4vv2h3wuzbx3pukcz7ju4fhbfzt6yxmoo533uktlgru4",
  "numberOfEntities": 12345,
  "replacedSnapshotHashes": [ "bafybeicw6x75ieaxfwynekbyhpcsgctpjkt6cb4j6oa7s57qjj6e4b5phd" ],
  "timeRange": {
     "initTimestamp": 1684281600000,
     "endTimestamp": 1684886400000
  }
}

Baixando Snapshots

Usando o hash campo de um snapshot, os clientes podem baixar o associado contendo entidades criadas ou atualizadas nesse intervalo de tempo.

Os arquivos de snapshot começam com esta linha exata:

### Decentraland json snapshot

Depois disso, cada linha é um documento JSON descrevendo uma entity com os seguintes campos:

Campo	Valor
entityId	O identificador imutável para esta entity.
entityType	Um de cena, perfil, wearable, emote, store ou outfits.
pointers	Um array de pointers que resolvem (ou costumavam resolver) para esta entidade.
entityTimestamp	O timestamp Unix UTC (em milissegundos) quando esta entidade foi enviada.
authChain	O auth_chain para esta entidade.

Uma entrada típica se parece com isto:

{
  "entityId": "bafkreigrvaqynmiglpvewwhn2yd63q5dvagrrt5jbhimzvbrn5kimj5zne",
  "entityType": "wearable",
  "pointers": ["urn:decentraland:matic:collections-v2:0x11a6879861f36cbad632a4e7226816a16139fb33:0"],
  "entityTimestamp": 1671117456129,
  "authChain": [
    // ... authentication chain payloads and signatures
  ]
}

Se você pretende analisar um snapshot linha por linha, lembre-se de pular (ou, melhor ainda, validar) a primeira com o cabeçalho, e esteja pronto para lidar com uma linha vazia no final do arquivo.

Iniciando um Índice de Entidades

Clientes que queiram indexar o conjunto inteiro de entidades ativas devem processar todos os snapshots atualmente disponíveis, e manter a mais recente entity para cada pointer.

A estratégia mais simples é processar os snapshots em ordem reversa cronológica (ou seja, do mais recente para o mais antigo), ignorando pointers que já foram descobertos, a fim de manter a referência para a entidade mais recente.

Em pseudo-código:

# Baixe o conjunto atual de snapshots e ordene-os do mais novo ao mais antigo:
snapshots = get_snapshots()
snapshots.sort('timeRange.initTimestamp', DESCENDING)

seen_pointers = set()

# Processe os snapshots, mantendo a entidade mais nova para cada pointer:
for snapshot in snapshots:
    items = get_snapshot_items(snapshot) 

    for item in items:
        if any(pointer in seen_pointers for pointer in item.pointers):
            discard(item)
        else:
            keep(item)
            seen_pointers.update(item.pointers)

Como entidades individuais podem ser referenciadas por múltiplos pointers (como é comum com cenas), todos eles devem ser verificados antes de decidir manter ou descartar o item.

Os arquivos de snapshot para os intervalos de tempo maiores podem ser muito grandes. Para propósitos de desenvolvimento e experimentação que não exigem indexar o conjunto inteiro de entidades, é recomendável usar os snapshots menores. O conjunto resultante de entidades será incompleto, mas válido.

Atualizando um Índice de Entidades

Clientes que mantêm um índice de entidades atualizado podem fazer chamadas periódicas ao snapshots endpoint, e determinar se devem baixar cada arquivo considerando:

• O snapshot identificado por hash já foi baixado?

• Está hash na replacedSnapshotHashes lista de outro snapshot que já foi baixado?

• O timeRange é relevante para os propósitos atuais?

Se quaisquer novos snapshots precisarem ser processados, a mesma estratégia acima pode ser usada para atualizar um conjunto de dados existente.

Exemplos

Na practice seção, você encontrará exemplos de código que funcionam com o sistema de snapshots.