Messaging Data Structures

syntax = "proto3";
package river;
option go_package = "github.com/towns-protocol/towns/protocol";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

/**
* StreamEvent is a single event in the stream.
*/
message StreamEvent {
    /**
     * Address of the creator of the event.
     * For user - address of the user's primary wallet.
     * For server - address of the server's keypair in staking smart contract.
     *
     * For the event to be valid:
     * If delegate_sig is present, creator_address must match delegate_sig.
     * If delegate_sig is not present, creator_address must match event signature in the Envelope.
     */
    bytes creator_address = 1;

     /**
      * delegate_sig allows event to be signed by device keypair
      * which is linked to the user's primary wallet.
      *
      * delegate_sig contains signature of the public key of the device keypair.
      * User's primary wallet is used to produce this signature.
      *
      * If present, for the event to be valid:
      * 1. creator_address must match delegate_sig's signer public key
      * 2. delegate_sig should be the signature of Envelope.signature's public key.
      *
      * Server nodes sign node-produced events with their own keypair and do not
      * need to use delegate_sig.
      */
    bytes delegate_sig = 2;

    /** Salt ensures that similar messages are not hashed to the same value. genId() from id.ts may be used. */
    bytes salt = 3;

    /** Hash of a preceding miniblock. Null for the inception event. Must be a recent miniblock */
    optional bytes prev_miniblock_hash = 4;

    /** CreatedAt is the time when the event was created.
    NOTE: this value is set by clients and is not reliable for anything other than displaying
    the value to the user. Never use this value to sort events from different users.  */
    int64 created_at_epoch_ms = 5;
 
    /** Variable-type payload.
      * Payloads should obey the following rules:
      * - payloads should have their own unique type
      * - each payload should have a oneof content field
      * - each payload should have an inception field inside the content oneof
      * - each payload should have a unique Inception type
      * - payloads can't violate previous type recursively to inception payload
    */
    oneof payload {
        MiniblockHeader miniblock_header = 100;
        CommonPayload common_payload = 101;
        SpacePayload space_payload = 102;
        ChannelPayload channel_payload = 103;
        UserPayload user_payload = 104;
        UserSettingsPayload user_settings_payload = 105;
        UserDeviceKeyPayload user_device_key_payload = 106;
        UserToDevicePayload user_to_device_payload = 107;
        MediaPayload media_payload = 108;
        DmChannelPayload dm_channel_payload = 109;
        GdmChannelPayload gdm_channel_payload = 110;
    }
}

/**
* SpacePayload
*/
message SpacePayload {
    message Snapshot {
        // inception
        Inception inception = 1;
        // streamId: Channel
        map<string, Channel> channels = 2;
        // userId: Membership
        map<string, Membership> memberships = 3;
        // userId: Username
        map<string, WrappedEncryptedData> usernames = 4;
        // userId: Displayname
        map<string, WrappedEncryptedData> display_names = 5;
    }
    
    message Inception {
        string stream_id = 1;
        StreamSettings settings = 2;
    }

    message Channel {
        ChannelOp op = 1;
        string channel_id = 2;
        EventRef origin_event = 3;
        EncryptedData channel_properties = 4;
    }

    oneof content {
        Inception inception = 1;
        Channel channel = 2;
        Membership membership = 3;
        EncryptedData username = 4;
        EncryptedData display_name = 5;
    }
}

/**
* ChannelPayload
*/
message ChannelPayload {
    message Snapshot {
        // inception
        Inception inception = 1;
        // userId: Membership
        map<string, Membership> memberships = 2;
    }
    
    message Inception {
        string stream_id = 1;
        string space_id = 3;
        /**
        * channel_name and channel_topic from this payload will be used to 
        * create associated with that channel space event for stream as we agreed
        * that channel names and topics will be delivered using space stream
        */
        EncryptedData channel_properties = 4;
        StreamSettings settings = 5;
    }

    oneof content {
        Inception inception = 1;
        EncryptedData message = 2;
        Membership membership = 3;
    }
}

/**
* DmChannelPayload
*/
message DmChannelPayload {
    message Snapshot {
        Inception inception = 1;
        map<string, Membership> memberships = 2;
        map<string, WrappedEncryptedData> usernames = 3;
        map<string, WrappedEncryptedData> display_names = 4;
    }

    message Inception {
        string stream_id = 1;
        string first_party_id = 2;
        string second_party_id = 3;
        StreamSettings settings = 4;
    }

    oneof content {
        Inception inception = 1;
        Membership membership = 2;
        EncryptedData message = 3;
        EncryptedData username = 4;
        EncryptedData display_name = 5;
    }
}

/**
* GdmChannelPayload
*/
message GdmChannelPayload {
    message Snapshot {
        Inception inception = 1;
        map<string, Membership> memberships = 2;
        map<string, WrappedEncryptedData> usernames = 3;
        map<string, WrappedEncryptedData> display_names = 4;
        WrappedEncryptedData channel_properties = 5;
    }

    message Inception {
        string stream_id = 1;
        EncryptedData channel_properties = 2;
        StreamSettings settings = 3;
    }

    oneof content {
        Inception inception = 1;
        Membership membership = 2;
        EncryptedData message = 3;
        EncryptedData username = 4;
        EncryptedData display_name = 5;
        EncryptedData channel_properties = 6;
    }
}

/**
* MediaPayload
*/
message MediaPayload {
    message Snapshot {
        Inception inception = 1;
    }
    
    message Inception {
        string stream_id = 1;
        string channel_id = 2;
        int32 chunk_count = 3;
        StreamSettings settings = 4;
    }

    message Chunk {
        bytes data = 1;
        int32 chunk_index = 2;
    }

    oneof content {
        Inception inception = 1;
        Chunk chunk = 2;
    }
}

message Membership {
    MembershipOp op = 1;
    string user_id = 2;
}

message EncryptedData {
    /**
    * Ciphertext of the encryption envelope.
    */
    string ciphertext = 1;
    /**
    * Encryption algorithm  used to encrypt this event.
    */
    string algorithm = 2;
    /**
    * Sender device public key identifying the sender's device.
    */
    string sender_key = 3;
    /**
    * The ID of the session used to encrypt the message.
    */
    string session_id = 4;

    /**
    * Optional checksum of the cleartext data.
    */
    optional string checksum = 5;
}

message WrappedEncryptedData {
    EncryptedData data = 1;
    int64 event_num = 2;
    bytes event_hash = 3;
}

enum MembershipOp {
    SO_UNSPECIFIED = 0;
    SO_INVITE = 1;
    SO_JOIN = 2;
    SO_LEAVE = 3;
}

enum ChannelOp {
    CO_UNSPECIFIED = 0;
    CO_CREATED = 1;
    CO_DELETED = 2;
    CO_UPDATED = 4;
}