nips/20.md

NIP-20
======

Connection Limitations
----------------------

`draft` `optional`

Upon connection, and at any point during the connection, the Relay can send a `LIMITS` payload to the Client reflecting the current state of the user's rights in the relay. 

```json
["LIMITS", { <limit_properties> }]
``` 

Where `limit_properties` includes properties that are specifically designed to change the way Clients communicate. Options are: 

- `can_write: <true|false>`, If false, Clients MUST NOT publish events to the relay. 
- `can_read: <true|false>`, If true, Clients MUST NOT send `REQ` commands to the relay.
<br/><br/>
- `accepted_event_kinds: [<unsigned int>, <unsigned int>, ...]`, Clients MUST filter publishing events by these types.
- `blocked_event_kinds: [<unsigned int>, <unsigned int>, ...]`, Clients MUST remove these types from publishing actions.
<br/><br/>
- `min_pow_difficulty: <int>`: Clients MUST filter publishing events if they don't have at least this PoW bit difficulty.
<br/><br/>
- `max_message_length: <int>`, Clients MUST filter publishing events and crop/chunk `REQ` filters by this length.
- `max_subscriptions: <int>`, Clients MUST reduce the number of subscriptions to this amount.
- `max_filters: <int>`, Clients MUST crop/chunk `REQ` filters by this amount.
- `max_limit: <int>`, Clients MUST clump each filter's `limit` value to this number and use `since` and `until` to get additional results.
- `max_event_tags: <int>`, Clients MUST filter publishing events by this `.tags` length.
- `max_content_length: <int>`, Clients MUST filter publishing events by this `.content` length.
<br/><br/>
- `created_at_lower_limit: <unix timestamp>`, Clients MUST filter publishing events whose `.created_at` is smaller than this number
- `created_at_upper_limit: <unix timestamp>`, Clients MUST filter publishing events whose `.created_at` is bigger than this number
<br/><br/>
- `filter_rate_limit: <int, milliseconds>`: Clients MUST debounce filter changes after this amount in milliseconds.
- `publishing_rate_limit: <int, milliseconds>`: Clients MUST debounce publishing events by this amount in milliseconds.
<br/><br/>
- `required_tags: [ [ <key>, <value, optional> ], [ <key>, <value, optional> ] ]`, Clients MUST filter publishing events that don't include all listed tag names and values.

This payload SHOULD be cached in the Client's Relay connection object and updated as many times as the relay requests. Clients should use the information here to apply filters when sending events and `REQs` to the relay.