NIP-29

Time-Based Sync

draft optional author:vitorpamplona

This document describes a simple relay filter extension to allow event database syncing between relays and clients. It works for both client-relay and relay-relay scenarios when the majority of the events have been downloaded in a previous session.

Motivation

Clients that keep a local database (either in memory or in disk) wish to update that database with any new events from each relay. Currently, the only way to know if the client is up-to-date is to re-download all events. This NIP allows a client to request a hash for each week of records from the relay. If the local hash matches the remote hash for the week, the client is up-to-date. If the hash is different, the client can request to download all events in that week using the regular since and until filters.

Sync Protocol

The client sends a WEEKLY-HASHES message to the relay with a subscription ID and appropriate filters for the content to be checked.

Request:

[
    "WEEKLY-HASHES",
    <subscription ID string>,
    <nostr filter>, <nostr filter2>, <nostr filter3>
]

The relay calculates weekly hashs and responds with a sequence of

Response:

[
    "WEEKLY-HASH",
    <subscription ID string>,
    <week in "YYYY-ww" format>,
    <SHA256(JSON.stringify([event1.id, event2.id, event3.id, ...])) in hex>
]

Compare the receiving hashes with those stored locally and if different create the filter to download all events from that week (in GMT) again.

Weekly Hash calculation

The weekly hash MUST happen in the client and in the relay in the exact same way:

Apply all filters in a subscription to the database
Sort all events by .created_at
Group by a formatted .created_at as YYYY-ww in GMT, where ww is the week of the year
For each group, create an array of event ids: [id1, id2, id3], JSON-serialize it and hash it using SHA-256
Return a list of the formatted .created_at and the hashes.

Why weekly?

Simplicity. We could do a recursive approach where the Client sends the format it wants to wants to use (e.g: YYYY, YYYY-ww, YYYY-MM, YYYY-MM-dd, YYYY-MM-ddHH, YYYY-MM-ddHHmm). This flexibility allows for some cost savings but adds complexity to the implementation of this NIP.

2.3 KiB Raw Blame History