diff --git a/diagrams/HLSDK.mermaid b/diagrams/HLSDK.mermaid new file mode 100644 index 000000000..5cd8926b7 --- /dev/null +++ b/diagrams/HLSDK.mermaid @@ -0,0 +1,24 @@ +block-beta + columns 4 + block:group1:2 + columns 2 + Android LibXMTP + end + space:2 + + block:group3:2 + columns 2 + React C["LibXMTP"] + end + space + Node["XMTP Node"] + block:group2:2 + columns 2 + iOS B["LibXMTP"] + end + group1-->Node + Node-->group1 + group2-->Node + Node-->group2 + group3-->Node + Node-->group3 \ No newline at end of file diff --git a/diagrams/add-remove.mermaid b/diagrams/add-remove.mermaid index f0d8cca15..6199a07d7 100644 --- a/diagrams/add-remove.mermaid +++ b/diagrams/add-remove.mermaid @@ -4,36 +4,37 @@ sequenceDiagram participant Charlie participant LibXMTP participant Node - + Note left of Alice: Remove Charlie - Alice->>LibXMTP: group.removeMembers(Charlie) + Alice->>LibXMTP: group.remove_members(Charlie) + LibXMTP->>+Node: get-identity-updates(Charlie) + Node-->>-LibXMTP: installation_key:Charlie + credential_identity:Charlie LibXMTP->>Node: send-group-message(REMOVE_MEMBER:installation_key:Charlie) - Alice->>+LibXMTP: group.messages() + Alice->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: REMOVE_MEMBER:Charlie LibXMTP-->>-Alice: "Charlie has been removed from the group" - Bob->>+LibXMTP: group.messages() + Bob->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: REMOVE_MEMBER:Charlie LibXMTP-->>-Bob: "Charlie has been removed from the group" Note left of Alice: Add Charlie - Bob->>LibXMTP: addMembers(Charlie) + Alice->>LibXMTP: addMembers(Charlie) LibXMTP->>+Node: get-identity-updates(Charlie) Node-->>-LibXMTP: installation_key:Charlie + credential_identity:Charlie LibXMTP->>Node: send-group-message(ADD_MEMBER:installation_key:Charlie) - Bob->>+LibXMTP: group.messages() + Alice->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: ADD_MEMBER:Charlie - LibXMTP-->>-Bob: "Charlie has been added to the group" - Alice->>+LibXMTP: group.messages() + LibXMTP-->>-Alice: "Charlie has been added to the group" + Bob->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: ADD_MEMBER:Charlie - LibXMTP-->>-Alice: "Charlie has been added to the group" - Charlie->>+LibXMTP: syncGroups() + LibXMTP-->>-Bob: "Charlie has been added to the group" + Charlie->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Charlie) Node-->>-LibXMTP: WelcomeMessages() - LibXMTP-->>-Charlie: "Alice has added you to a group" - Charlie->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() \ No newline at end of file + Charlie->>+LibXMTP: conversations.list() + LibXMTP-->>-Charlie: List of groups including new group \ No newline at end of file diff --git a/diagrams/create-client.mermaid b/diagrams/create-client.mermaid new file mode 100644 index 000000000..c122d9ae6 --- /dev/null +++ b/diagrams/create-client.mermaid @@ -0,0 +1,14 @@ +sequenceDiagram + participant Alice + participant LibXMTP + participant Node + + Note over Alice,LibXMTP: These calls are coming from higher-level SDKs on behalf of users + Note over Alice,Node: Step 1 (Account Creation) & 2 (Initial Keying Material) of MLS group creation combined + Alice->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Alice: client + Alice->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Alice: text to be signed for register_identity + Alice->>LibXMTP: client.register_identity(recoverable_wallet_signature) + LibXMTP->>+Node: register_installation(key_package:Alice) + Node-->>-LibXMTP: installation_key:Alice \ No newline at end of file diff --git a/diagrams/diagrams.md b/diagrams/diagrams.md index 150209072..ee658f2f9 100644 --- a/diagrams/diagrams.md +++ b/diagrams/diagrams.md @@ -4,6 +4,8 @@ The sequence diagrams stored here are for documenting LibXMTP's group chat imple The diagrams represent the creation of a group chat between Alice, Bob, and Charlie, our implmentation of [Figure 2](https://messaginglayersecurity.rocks/mls-architecture/draft-ietf-mls-architecture.html#fig-group-formation-example) from [The Messaging Layer Security (MLS) Architecture](https://messaginglayersecurity.rocks/mls-architecture/draft-ietf-mls-architecture.html) spec. +Note: calls into LibXMTP with the `conversations.` prefix use the [Conversations](https://github.com/xmtp/libxmtp/blob/204b35a337daf2a9f2ed0cb20199e254d0a7493a/bindings_ffi/src/mls.rs#L188) protocol, and calls with a `group.` prefix use the [Group](https://github.com/xmtp/libxmtp/blob/204b35a337daf2a9f2ed0cb20199e254d0a7493a/bindings_ffi/src/mls.rs#L315) protocol. + * *form-group.mermaid* - Covers Steps 1-4 of forming a group. In LibXMTP, steps 1 and 2 happen at the same time, and steps 3 and 4 can also be consolidated by calling `newGroup()` with multiple participants. * *send-recieve.mermaid* - Covers sending and receiving messages to the newly formed group. * *add-remove.mermaid* - Covers adding and removing group members. @@ -21,18 +23,30 @@ sequenceDiagram Note over Alice,Charlie: These calls are coming from higher-level
SDKs on behalf of users Note over Alice,Node: Step 1 (Account Creation) & 2 (Initial Keying Material) of MLS group creation combined - Alice->>LibXMTP: create_client(encryption_key, account_address) + Alice->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Alice: client + Alice->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Alice: text to be signed for register_identity + Alice->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Alice) Node-->>-LibXMTP: installation_key:Alice - Bob->>LibXMTP: create_client(encryption_key, account_address) + Bob->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Bob: client + Bob->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Bob: text to be signed for register_identity + Bob->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Bob) Node-->>-LibXMTP: installation_key:Bob - Charlie->>LibXMTP: create_client(encryption_key, account_address) + Charlie->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Charlie: client + Charlie->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Charlie: text to be signed for register_identity + Charlie->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Charlie) Node-->>-LibXMTP: installation_key:Charlie Note over Alice,Node: Step 3 (Adding Bob) & 4 (Adding Charlie) of MLS group creation - Alice->>LibXMTP: newGroup(Bob, Charlie) + Alice->>LibXMTP: conversations.create_group(Bob, Charlie) LibXMTP->>+Node: get-identity-updates(Bob) Node-->>-LibXMTP: installation_key:Bob + credential_identity:Bob LibXMTP->>+Node: get-identity-updates(Charlie) @@ -40,18 +54,16 @@ sequenceDiagram LibXMTP->>Node: fetch-key-packages(installation_keys: Bob + Charlie) Node-->>LibXMTP: KeyPackages(Bob+Charlie) LibXMTP->>Node: send-welcome-messages(KeyPackages:Bob + Charlie) - Bob->>+LibXMTP: syncGroups() + Bob->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Bob) Node-->>-LibXMTP: WelcomeMessages() - LibXMTP-->>-Bob: "Alice has added you to a group" - Bob->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() - Charlie->>+LibXMTP: syncGroups() + Bob->>+LibXMTP: conversations.list() + LibXMTP-->>-Bob: List of groups including new group + Charlie->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Charlie) Node-->>-LibXMTP: WelcomeMessages() - LibXMTP-->>-Charlie: "Alice has added you to a group" - Charlie->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() + Charlie->>+LibXMTP: conversations.list() + LibXMTP-->>-Charlie: List of groups including new group ``` ## Send and Receive Messages @@ -60,7 +72,6 @@ sequenceDiagram sequenceDiagram participant Alice participant Bob - participant Charlie participant LibXMTP participant Node @@ -69,10 +80,11 @@ sequenceDiagram LibXMTP->>Node: send-group-messages(SEND_MESSAGE:"Hello, group!") Note left of Alice: Receive Message - Bob->>+LibXMTP: group.messages() - LibXMTP->>+Node: query-group-messages(group_id) - Node-->>-LibXMTP: "Hello, group!" - LibXMTP->>-Bob: "Hello, group!" + Bob->>LibXMTP: group.sync() + LibXMTP->>Node: query-group-messages(group_id) + Node-->>LibXMTP: "Hello, group!" + Bob->>LibXMTP: group.find_messages() + LibXMTP->>Bob: "Hello, group!" ``` ## Add and Remove Group Members @@ -84,39 +96,37 @@ sequenceDiagram participant Charlie participant LibXMTP participant Node - + Note left of Alice: Remove Charlie - Alice->>LibXMTP: group.removeMembers(Charlie) + Alice->>LibXMTP: group.remove_members(Charlie) LibXMTP->>Node: send-group-message(REMOVE_MEMBER:installation_key:Charlie) - Alice->>+LibXMTP: group.messages() + Alice->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: REMOVE_MEMBER:Charlie LibXMTP-->>-Alice: "Charlie has been removed from the group" - Bob->>+LibXMTP: group.messages() + Bob->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: REMOVE_MEMBER:Charlie LibXMTP-->>-Bob: "Charlie has been removed from the group" Note left of Alice: Add Charlie - Bob->>LibXMTP: addMembers(Charlie) + Alice->>LibXMTP: add_members(Charlie) LibXMTP->>+Node: get-identity-updates(Charlie) Node-->>-LibXMTP: installation_key:Charlie + credential_identity:Charlie LibXMTP->>Node: send-group-message(ADD_MEMBER:installation_key:Charlie) - Bob->>+LibXMTP: group.messages() + Alice->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: ADD_MEMBER:Charlie - LibXMTP-->>-Bob: "Charlie has been added to the group" - Alice->>+LibXMTP: group.messages() + LibXMTP-->>-Alice: "Charlie has been added to the group" + Bob->>+LibXMTP: group.sync() LibXMTP->>+Node: query-group-messages(group_id) Node->>-LibXMTP: ADD_MEMBER:Charlie - LibXMTP-->>-Alice: "Charlie has been added to the group" - Charlie->>+LibXMTP: syncGroups() + LibXMTP-->>-Bob: "Charlie has been added to the group" + Charlie->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Charlie) Node-->>-LibXMTP: WelcomeMessages() LibXMTP-->>-Charlie: "Alice has added you to a group" - Charlie->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() ``` ## Sync Installations diff --git a/diagrams/form-group.mermaid b/diagrams/form-group.mermaid index d418deb43..025a3ca25 100644 --- a/diagrams/form-group.mermaid +++ b/diagrams/form-group.mermaid @@ -7,18 +7,30 @@ sequenceDiagram Note over Alice,Charlie: These calls are coming from higher-level
SDKs on behalf of users Note over Alice,Node: Step 1 (Account Creation) & 2 (Initial Keying Material) of MLS group creation combined - Alice->>LibXMTP: create_client(encryption_key, account_address) + Alice->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Alice: client + Alice->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Alice: text to be signed for register_identity + Alice->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Alice) Node-->>-LibXMTP: installation_key:Alice - Bob->>LibXMTP: create_client(encryption_key, account_address) + Bob->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Bob: client + Bob->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Bob: text to be signed for register_identity + Bob->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Bob) Node-->>-LibXMTP: installation_key:Bob - Charlie->>LibXMTP: create_client(encryption_key, account_address) + Charlie->>+LibXMTP: create_client(encryption_key, account_address) + LibXMTP-->>-Charlie: client + Charlie->>+LibXMTP: client.text_to_sign() + LibXMTP-->>-Charlie: text to be signed for register_identity + Charlie->>LibXMTP: client.register_identity(recoverable_wallet_signature) LibXMTP->>+Node: register_installation(key_package:Charlie) Node-->>-LibXMTP: installation_key:Charlie Note over Alice,Node: Step 3 (Adding Bob) & 4 (Adding Charlie) of MLS group creation - Alice->>LibXMTP: newGroup(Bob, Charlie) + Alice->>LibXMTP: conversations.create_group(Bob, Charlie) LibXMTP->>+Node: get-identity-updates(Bob) Node-->>-LibXMTP: installation_key:Bob + credential_identity:Bob LibXMTP->>+Node: get-identity-updates(Charlie) @@ -26,15 +38,13 @@ sequenceDiagram LibXMTP->>Node: fetch-key-packages(installation_keys: Bob + Charlie) Node-->>LibXMTP: KeyPackages(Bob+Charlie) LibXMTP->>Node: send-welcome-messages(KeyPackages:Bob + Charlie) - Bob->>+LibXMTP: syncGroups() + Bob->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Bob) Node-->>-LibXMTP: WelcomeMessages() - LibXMTP-->>-Bob: "Alice has added you to a group" - Bob->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() - Charlie->>+LibXMTP: syncGroups() + Bob->>+LibXMTP: conversations.list() + LibXMTP-->>-Bob: List of groups including new group + Charlie->>+LibXMTP: conversations.sync() LibXMTP->>+Node: query-welcome-messages(installation_key:Charlie) Node-->>-LibXMTP: WelcomeMessages() - LibXMTP-->>-Charlie: "Alice has added you to a group" - Charlie->>LibXMTP: rotate_key_packages() - LibXMTP->>Node: upload-key-package() \ No newline at end of file + Charlie->>+LibXMTP: conversations.list() + LibXMTP-->>-Charlie: List of groups including new group diff --git a/diagrams/send-receive.mermaid b/diagrams/send-receive.mermaid index 08344b88c..93e92554f 100644 --- a/diagrams/send-receive.mermaid +++ b/diagrams/send-receive.mermaid @@ -1,7 +1,6 @@ sequenceDiagram participant Alice participant Bob - participant Charlie participant LibXMTP participant Node @@ -10,7 +9,8 @@ sequenceDiagram LibXMTP->>Node: send-group-messages(SEND_MESSAGE:"Hello, group!") Note left of Alice: Receive Message - Bob->>+LibXMTP: group.messages() - LibXMTP->>+Node: query-group-messages(group_id) - Node-->>-LibXMTP: "Hello, group!" - LibXMTP->>-Bob: "Hello, group!" \ No newline at end of file + Bob->>LibXMTP: group.sync() + LibXMTP->>Node: query-group-messages(group_id) + Node-->>LibXMTP: "Alice: Hello, group!" + Bob->>LibXMTP: group.find_messages() + LibXMTP-->>Bob: "Alice: Hello, group!" \ No newline at end of file