nips/29.md

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:
```js
[
    "WEEKLY-HASHES",
    <subscription ID string>,
    <nostr filter>, <nostr filter2>, <nostr filter3>
]
```

The relay calculates weekly hashs and responds with a sequence of 

Response:
```js
[
    "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: 

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

### Why weekly? 

Simplicity. We could do a recursive approach where the Client chooses the format (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.