diff --git a/status/raw/url-data.md b/status/raw/url-data.md new file mode 100644 index 0000000..5c7bdea --- /dev/null +++ b/status/raw/url-data.md @@ -0,0 +1,157 @@ +--- +title: STATUS-URL-DATA +name: Status URL Data +status: raw +category: Standards Track +tags: +editor: Felicio Mununga +contributors: + - Aaryamann Challani +--- + +## Abstract + +This document specifies serialization, compression, and +encoding techniques used to transmit data within URLs in the context of Status protocols. + +## Motivation + +When sharing URLs, +link previews often expose metadata to the websites behind those links. +To reduce reliance on external servers for providing appropriate link previews, +this specification proposes a standard method for encoding data within URLs. + +## Terminology + +- Community: Refer to [STATUS-COMMUNITIES](../56/communities.md) +- Channel: Refer to terminology in [STATUS-COMMUNITIES](../56/communities.md) +- User: Refer to terminology in [STATUS-COMMUNITIES](../56/communities.md) +- Shard Refer to terminology in [51/WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) + +## Wire Format + +```protobuf +syntax = "proto3"; + +message Community { + // Display name of the community + string display_name = 1; + // Description of the community + string description = 2; + // Number of members in the community + uint32 members_count = 3; + // Color of the community title + string color = 4; + // List of tag indices + repeated uint32 tag_indices = 5; +} + +message Channel { + // Display name of the channel + string display_name = 1; + // Description of the channel + string description = 2; + // Emoji of the channel + string emoji = 3; + // Color of the channel title + string color = 4; + // Community the channel belongs to + Community community = 5; + // UUID of the channel + string uuid = 6; +} + +message User { + // Display name of the user + string display_name = 1; + // Description of the user + string description = 2; + // Color of the user title + string color = 3; +} + +message URLData { + // Community, Channel, or User + bytes content = 1; + uint32 shard_cluster = 2; + uint32 shard_index = 3; +} +``` + +## Implementation + +The above wire format describes the data encoded in the URL. +The data MUST be serialized, compressed, and encoded using the following standards: + +Encoding + +- [Base64url](https://datatracker.ietf.org/doc/html/rfc4648) + +### Compression + +- [Brotli](https://datatracker.ietf.org/doc/html/rfc7932) + +### Serialization + +- [Protocol buffers version 3](https://protobuf.dev/reference/protobuf/proto3-spec/) + +### Implementation Pseudocode + +Encoding + +Encoding the URL MUST be done in the following order: + +```protobuf +raw_data = {User | Channel | Community} +serialized_data = protobuf_serialize(raw_data) +compressed_data = brotli_compress(serialized_data) +encoded_url_data = base64url_encode(compressed_data) +``` + +The `encoded_url_data` is then used to generate a signature using the private key. + +#### Decoding + +Decoding the URL MUST be done in the following order: + +```protobuf +url_data = base64url_decode(encoded_url_data) +decompressed_data = brotli_decompress(url_data) +deserialized_data = protobuf_deserialize(decompressed_data) +raw_data = deserialized_data.content +``` + +The `raw_data` is then used to construct the appropriate data structure +(User, Channel, or Community). + +### Example + +- See + + + +## Discussions + +- See + +## Proof of concept + +- See + + + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +1. [Proposal Google Sheet](https://docs.google.com/spreadsheets/d/1JD4kp0aUm90piUZ7FgM_c2NGe2PdN8BFB11wmt5UZIY/edit?usp=sharing) +2. [Base64url](https://datatracker.ietf.org/doc/html/rfc4648) +3. [Brotli](https://datatracker.ietf.org/doc/html/rfc7932) +4. [Protocol buffers version 3](https://protobuf.dev/reference/protobuf/proto3-spec/) +5. [STATUS-URL-SCHEME](./url-scheme.md) + +