From 9bcf27e95646878b9686a04c0c9c8bc2be9b5b54 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Fri, 20 Dec 2024 17:29:38 -0800 Subject: [PATCH] add more concepts --- docs/pages/index.mdx | 10 +-- docs/pages/intro/faq.md | 2 +- docs/pages/network/network-faq.md | 42 ---------- docs/pages/protocol/consent.md | 89 +++++++++++++++++++++ docs/pages/protocol/encryption.md | 68 ++++++++++++++++ docs/pages/protocol/identity.md | 126 ++++++++++++++++++++++++++++++ docs/pages/protocol/network.md | 39 +++++++++ vocs.config.tsx | 24 ++++-- 8 files changed, 346 insertions(+), 54 deletions(-) delete mode 100644 docs/pages/network/network-faq.md create mode 100644 docs/pages/protocol/consent.md create mode 100644 docs/pages/protocol/encryption.md create mode 100644 docs/pages/protocol/identity.md create mode 100644 docs/pages/protocol/network.md diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 95a7e38..45fb323 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -34,16 +34,16 @@ import "../styles.css"; isExternal={true} /> diff --git a/docs/pages/intro/faq.md b/docs/pages/intro/faq.md index 2b175df..4bf254a 100644 --- a/docs/pages/intro/faq.md +++ b/docs/pages/intro/faq.md @@ -76,7 +76,7 @@ See the [XMTP brand guidelines](https://github.com/xmtp/brand) GitHub repo. ## Network -See [Network FAQ](/network/network-faq). +For FAQ about the XMTP network, see [XMTP network](/protocol/network). ## Fees diff --git a/docs/pages/network/network-faq.md b/docs/pages/network/network-faq.md deleted file mode 100644 index 9e94d60..0000000 --- a/docs/pages/network/network-faq.md +++ /dev/null @@ -1,42 +0,0 @@ -# FAQ about the XMTP network - -To follow and provide feedback on the engineering work covered in this FAQ, see the [Replication tracking task](https://github.com/xmtp/xmtpd/issues/118) in the [xmtpd repo](https://github.com/xmtp/xmtpd). - -## Is the XMTP network decentralized? - -**A testnet of the decentralized XMTP network was launched in early December 2024.** 🎉 - -- To learn about the testnet and how the XMTP network will be decentralized, see [Decentralizing XMTP](https://xmtp.org/decentralizing-xmtp). -- To learn about xmtpd (XMTP daemon), the node software that powers the testnet and will power the mainnet of the decentralized XMTP network, see the [xmtpd repo](https://github.com/xmtp/xmtpd). -- To learn about how xmtpd can be run on Helm and Terraform infrastructure, see the [xmtpd-infrastructure repo](https://github.com/xmtp/xmtpd-infrastructure). - -All of the nodes in the `dev` and `production` XMTP network environments are still operated by [Ephemera](https://ephemerahq.com/) (the company) and powered by [xmtp-node-go](https://github.com/xmtp/xmtp-node-go). - -These nodes in the `dev` and `production` XMTP network environments operate in US jurisdiction in compliance with Office of Foreign Assets Control (OFAC) sanctions and Committee on Foreign Investment in the United States (CFIUS) export compliance regulations. Accordingly, IP-based geoblocking is in place for the following countries/territories: - -- Cuba -- Iran -- North Korea -- Syria -- The Crimea, Donetsk People’s Republic, and Luhansk People’s Republic regions of Ukraine - -## Is XMTP a blockchain? - -The testnet of the decentralized XMTP network includes two distributed systems: - -- The XMTP broadcast network -- The XMTP appchain, which is an L3 blockchain securing all metadata that require strict ordering. - -To learn more, see [Decentralizing XMTP](https://xmtp.org/decentralizing-xmtp). - -The `dev` and `production` XMTP network environments do not use a blockchain. Nodes in these networks run software to store and transfer messages between blockchain accounts. For secure and reliable delivery of messages, the nodes participate in a consensus mechanism. - -## Will I be able to run my own XMTP node? - -At this time, not everyone will be able to run an XMTP node in the production decentralized XMTP network. - -To learn more, see [Decentralizing XMTP](https://xmtp.org/decentralizing-xmtp). - -## Does XMTP have a token? - -XMTP does not currently have a token. Disregard any information regarding airdrops or token sales. If and when an official token is introduced, announcements will be made exclusively through XMTP's official channels. diff --git a/docs/pages/protocol/consent.md b/docs/pages/protocol/consent.md new file mode 100644 index 0000000..b247a2c --- /dev/null +++ b/docs/pages/protocol/consent.md @@ -0,0 +1,89 @@ +# Consent in XMTP + +:::info[Key takeaways] + +- **What is consent?** Simply put, consent is who you allow and who you block +- **Why it matters:** Your choices about who can message you should be private and work across all apps +- **How it works:** Each wallet maintains a private, encrypted list of allowed and blocked addresses +- **Future-proof:** XMTP is making it easier to manage messaging permissions while keeping your choices private + +::: + +## Understand consent + +Consent in XMTP manages who can message you across all apps you use: + +**For direct messages**, it's about who you allow and who you block: + +- Allow certain addresses to message you +- Block addresses you don't want to hear from + +**For group chats**, it's about which groups you want to participate in: + +- Join the group to receive its messages +- Block to stop receiving messages from the group + +In both cases, new messages and invites stay in your message requests until you make a decision. + +## Privacy-first design + +Your choices about who can message you are private. This means: + +- Only you can see who you've allowed or blocked +- Your choices are encrypted and visible only to you +- No one else can see your messaging preferences +- Blocked users don't know they're blocked + +## How consent works + +The XMTP network maintains three private states for each potential messaging relationship: + +```rust +pub enum ConsentState { + Unknown, // Default state for new contacts + Allowed, // Contacts you've allowed + Denied, // Contacts you've blocked +} +``` + +:::note[Implementation note] + +Currently, consent preferences are client-side filters—they help apps determine which messages to show in your inbox, but don't prevent message transmission at the network level. + +To learn about future plans to implement network-level consent enforcement, see [The future of consent](https://xmtp.org/roadmap#the-future-of-consent). + +::: + +When you receive a new message, it appears in your message requests. Apps typically show: + +- Main inbox: Messages from allowed addresses and joined groups +- Message requests: New messages and invites you haven't decided about +- Hidden: Messages from blocked addresses and groups + +## FAQ + +### If I block someone, will they know? + +No, blocked users aren't notified of their status. From their perspective, it appears the same as if you haven't responded to their message. + +### Can I revoke consent after granting it? + +Yes, you can always privately revoke consent. The other party won't be notified, but you'll no longer see their messages. + +### What happens if someone I blocked is in a group chat with me? + +Apps typically show you that the blocked user sent a message but protect you from its content with a "tap to unhide" option. However, the exact UI implementation may vary by app. + +### Does blocking someone remove our message history? + +No, blocking only affects new messages. Previous conversations remain in your app but may be hidden from view depending on the app's design. + +### What happens when someone messages me from a different wallet than before? + +Each wallet address is treated separately for consent purposes. If someone messages you from a new address, that message will appear in your message requests, even if you've allowed their other address. + +### Can I mute conversations? + +No. Currently, you cannot mute conversations. + +To learn about future plans to add muting capabilities to the protocol, see [The future of consent](https://xmtp.org/roadmap#the-future-of-consent). diff --git a/docs/pages/protocol/encryption.md b/docs/pages/protocol/encryption.md new file mode 100644 index 0000000..7b1f0bf --- /dev/null +++ b/docs/pages/protocol/encryption.md @@ -0,0 +1,68 @@ +# Encryption in XMTP + +:::info[Key takeaways] + +- **Protecting your privacy:** End-to-end encryption secures both your message content and metadata +- **Why it matters:** Your messages stay private with the same security as Signal and WhatsApp +- **How it works:** Uses the IETF-standard Messaging Layer Security (MLS) protocol +- **Future-proof:** MLS provides better efficiency than previous protocols, helping keep network costs low + +::: + +## End-to-end encrypted messaging + +When you send a message with XMTP, it's encrypted from the moment you hit send until it's decrypted on your recipient's device. This end-to-end encryption ensures that no one in between—not even the XMTP network itself—can read your messages. The encryption process protects both the content of your messages and their integrity, creating a secure channel between you and your recipients. + +## Privacy by design + +Your privacy in XMTP goes beyond just encrypting message content. The protocol also protects metadata—information about who is messaging whom, when messages are sent, and how conversations are structured. While network nodes can see when encrypted messages are transmitted and their size, both message content and recipient information are encrypted. This means nodes can't determine who sent messages or who they're for, keeping your communication patterns private. + +## Security that matches the best + +XMTP provides the same strong security properties that users expect from apps like Signal and WhatsApp. The protocol provides forward secrecy, which means that even if someone gains access to current encryption keys, they can't read any past messages. And if a key is ever compromised, the system quickly recovers by rotating keys and establishing new secure connections, providing what's known as post-compromise security. + +## The technology behind it + +### Messaging Layer Security + +The [Messaging Layer Security](https://messaginglayersecurity.rocks/) (MLS) protocol is the next generation of secure messaging, recently standardized by the Internet Engineering Task Force (IETF). It builds on the security foundations established by the Signal protocol (used in Signal and WhatsApp). With extensive security research and review behind it, MLS was designed for wide adoption across the messaging industry. + +XMTP chose MLS for its combination of strong security and efficient operation. Its streamlined group key management helps keep network costs low, making it particularly well-suited for decentralized messaging. + +:::note[See the code] + +XMTP's implementation of MLS is open source and can be found at https://github.com/xmtp/libxmtp/tree/main/xmtp_mls + +::: + +When you start a conversation in XMTP, MLS automatically manages your encryption keys and conversation security. The protocol handles creating new conversations, adding or removing participants, and regularly updating encryption keys to maintain security. Every message you send is encrypted with the latest keys. + +## FAQ + +### Can XMTP read my messages? + +No, messages are encrypted end-to-end. Only participants in a conversation have the keys to decrypt the messages in it. + +### How does XMTP's encryption compare to Signal or WhatsApp? + +XMTP provides the same security properties (forward secrecy and post-compromise security) as Signal and WhatsApp, using the newer, more efficient MLS protocol. + +### Can others see who I'm messaging with? + +No. Message recipients are encrypted, so even network nodes cannot see who is messaging whom. Nodes can only see timing and size of encrypted messages. + +### What happens if I lose access to my wallet? + +You'll need to start new conversations from your new wallet. Messages sent to your old wallet address can't be decrypted without access to that wallet. + +### Are group messages as secure as direct messages? + +Yes, MLS provides the same security properties for both group and direct messages. In fact, MLS is particularly efficient for group messaging. + +### What if I suspect my wallet is compromised? + +Due to forward secrecy, even if someone gains access to your wallet, they can't read your past messages. You should start using a new wallet immediately - this ensures they won't be able to read future messages either. + +### How does encryption work across different apps? + +All XMTP apps use the same MLS protocol, ensuring consistent encryption across the ecosystem. diff --git a/docs/pages/protocol/identity.md b/docs/pages/protocol/identity.md new file mode 100644 index 0000000..a0fdba0 --- /dev/null +++ b/docs/pages/protocol/identity.md @@ -0,0 +1,126 @@ +# Identity in XMTP + +:::info[Key takeaways] + +- **Why it matters:** Your messaging identity starts private by default, letting you maintain separate personas or unify them as you choose +- **How it works:** Each wallet gets its own standalone inbox, with the option to link them under one identity +- **Future-proof:** Identity moves to the XMTP appchain in 2025, providing trustless censorship resistance. To learn more, see [The future of identity](https://xmtp.org/roadmap#the-future-of-identity). + +::: + +## Private by default + +Identity in XMTP is privacy-first, letting you reveal only what you choose, when you choose. Each wallet you activate starts with a private, standalone inbox that no one can link with your other inboxes, wallets, or onchain activity. At any time, you can associate your inbox with new wallets to make their activity part of your messaging identity and give them access to send and receive messages for you. + +For example, you might start with a single anonymous wallet for a memecoin holder chat, connect a wallet with your ENS name when you're ready to be found, or add a vault wallet to showcase your NFT collection. Once linked, these wallets share a unified inbox and let you receive messages through any of their associated names or addresses -- all while giving cryptographic proof to senders that you are the owner. + +## How identity works + +:::tip[Technical specification] + +For the complete technical specification of XMTP's identity system, see [XIP-46: Multi-Wallet Identity](https://github.com/xmtp/XIPs/blob/main/XIPs/xip-46-multi-wallet-identity.md). This XIP defines the protocol-level implementation of Inbox IDs, identity actions, permission hierarchies, and migration from XMTP v2. + +::: + +XMTP identity operates at the wallet address level, using cryptographic signatures to manage associations between wallets. These associations are controlled through XMTP `IdentityAction` operations: + +```rust +message IdentityAction { + oneof kind { + CreateInbox create_inbox = 1; // Create a new identity + AddAssociation add = 2; // Associate a new wallet + RevokeAssociation revoke = 3; // Remove a wallet association + ChangeRecoveryAddress change_recovery_address = 4; // Change the recovery address + } +} +``` + +Identity operations create public records that prove you own the associated wallets. The wallet first used to create the association becomes the recovery wallet. Any linked wallet can add new associations, but only this recovery wallet can remove them or designate a new recovery wallet. + +While XMTP works purely with wallet addresses, applications handle the connection to human-readable identities, resolving addresses to ENS names, Lens handles, or other web3 usernames to create user-friendly experiences. Messages sent to any of these identifiers are automatically routed to the unified inbox of their associated wallet. + +### Privacy considerations for onchain identity + +The default separation between wallets provides strong privacy guarantees. Users who choose to link wallets should be aware that these associations become visible onchain. For maximum privacy, users should maintain separate XMTP inboxes for sensitive communications. Apps built for these users can merge their inboxes locally. Research into privacy-preserving unlinkable associations is ongoing. + +## Composability + +XMTP identity associations enable developers to build new experiences around messaging. Here are the two main patterns: + +### Inbox discovery + +Looking up a user’s XMTP inbox using any of their wallet addresses or ENS names. + +- NFT marketplace notifications for bids +- DAO governance communications +- Group chat creation based on contract interactions + +### Address discovery + +Retrieving all wallet addresses and names associated with an XMTP inbox. + +- Web3 contact cards with ENS, Base, Farcaster, and Lens names +- Blockchain name display for conversation partners +- Cross-address identity verification + +## FAQ + +### What differentiates XMTP’s approach to identity? What are its benefits? + +Unlike traditional systems that bind user identity to a proprietary namespace, XMTP’s identity model leverages existing namespaces while prioritizing privacy. Users can choose which wallets to link, maintaining privacy by default, and consolidate their chosen names into a single messaging inbox. + +Benefits for users: + +- Private identity by default +- Receive all your messages without switching apps +- Communicate using any name you own + +Benefits for apps and services: + +- No need to build and maintain your own messaging system +- No need to integrate a new namespace +- If you have a namespace, XMTP makes it more valuable by extending its reach to more apps +- Users can communicate using all their names without switching to other apps +- Users can access existing agents and mini-apps developed by the XMTP community + +### How secure is this system? What happens if one of my linked wallets gets compromised? + +XMTP requires cryptographic signatures for every identity operation and maintains strict validation rules. The system protects against replay attacks by tracking all previously seen signatures, and each action must be properly authorized according to the key hierarchy. If a wallet linked to an identity is compromised, the recovery wallet can unlink it to protect the inbox. By default, the recovery wallet is the first wallet that created the identity. + +### How do I recover my identity? What if I lose access to my recovery wallet? + +The first wallet associated with an identity becomes the recovery wallet. This recovery wallet is the only one that can remove other wallet associations. It can also change the recovery address to a different wallet address. If access to the recovery wallet is lost, you can continue using your inbox with other linked wallets, but you won’t be able to revoke other wallet associations in case of compromise. + +As a last resort, you can create a new inbox and associate your wallet addresses to it. This ensures continued messaging access, though previous messages tied to the original inbox will remain inaccessible. + +### Can smart wallets or other smart contracts have XMTP identities? + +Any EIP-4337 smart wallet can create or link to an XMTP identity and send or receive messages. Other smart contracts can also do this if they support EIP-1271. + +### What is the maximum number of wallets that can be linked to an identity? + +The XMTP identity system has a maximum limit of 256 wallets that can be linked to a single identity. Revocations and recovery address changes count toward this limit. + +### How does wallet linking work across chains? + +Currently, XMTP supports only EVM chains. Messages sent to any address are delivered to its associated inbox, regardless of the network used by the app. + +To learn about future plans to extend support to wallets on non-EVM ecosystems, see [The future of identity](https://xmtp.org/roadmap#the-future-of-identity). + +### Are there any rate limits for identity operations? + +Yes, Ephemera’s centralized service has rate limits in place to ensure system stability under heavy usage. + +To learn about future plans for rate limiting identity operations, see [The future of identity](https://xmtp.org/roadmap#the-future-of-identity). + +### What costs are associated with identity operations? + +Currently, wallet linking and unlinking operations are free. + +To learn about future plans around identity operation costs, see [The future of identity](https://xmtp.org/roadmap#the-future-of-identity). + +### How public is my identity association history? + +Identity association history is currently public and viewable through the XMTP SDKs. + +To learn about future plans around putting identity association history onchain, see [The future of identity](https://xmtp.org/roadmap#the-future-of-identity). diff --git a/docs/pages/protocol/network.md b/docs/pages/protocol/network.md new file mode 100644 index 0000000..ad444bb --- /dev/null +++ b/docs/pages/protocol/network.md @@ -0,0 +1,39 @@ +# XMTP network + +**A testnet of the decentralized XMTP network was launched in early December 2024.** 🎉 To learn about testnet operation and how the XMTP network will be decentralized, see [The future of decentralization](https://xmtp.org/roadmap#the-decentralization-of-xmtp). + +xmtpd (XMTP daemon) is the node software that powers the testnet and will power the mainnet of the decentralized XMTP network. To learn more, see the [xmtpd repo](https://github.com/xmtp/xmtpd). + +xmtpd can be run on Helm and Terraform infrastructure. To learn more, see the [xmtpd-infrastructure repo](https://github.com/xmtp/xmtpd-infrastructure). + +**All of the nodes in the `dev` and `production` XMTP network environments are still operated by [Ephemera](https://ephemerahq.com/)** (the company) and powered by [xmtp-node-go](https://github.com/xmtp/xmtp-node-go). + +These nodes in the `dev` and `production` XMTP network environments operate in US jurisdiction in compliance with Office of Foreign Assets Control (OFAC) sanctions and Committee on Foreign Investment in the United States (CFIUS) export compliance regulations. Accordingly, IP-based geoblocking is in place for the following countries/territories: + +- Cuba +- Iran +- North Korea +- Syria +- The Crimea, Donetsk People’s Republic, and Luhansk People’s Republic regions of Ukraine + +## FAQ + +### Is XMTP a blockchain? + +The `dev` and `production` XMTP network environments do not use a blockchain. Nodes in these networks run software to store and transfer messages between blockchain accounts. For secure and reliable delivery of messages, the nodes participate in a consensus mechanism. + +To learn about how the plan to decentralize the XMTP network includes use of a blockchain, see [The future of decentralization](https://xmtp.org/roadmap#the-future-of-decentralization). + +### Will I be able to run my own XMTP node? + +At this time, not everyone will be able to run an XMTP node in the production decentralized XMTP network. + +To learn more, see [The future of decentralization](https://xmtp.org/roadmap#the-future-of-decentralization). + +### Does XMTP have a token? + +At this time there is no XMTP token and anyone who is trying to sell you one is trying to scam you. + +If this changes, this FAQ will be updated with more details and an update will be shared from the [official XMTP X account](https://x.com/xmtp_). Do not trust any announcements from other channels. + +For more FAQ about decentralization, see [The future of decentralization](https://xmtp.org/roadmap#the-decentralization-of-xmtp). diff --git a/vocs.config.tsx b/vocs.config.tsx index bd783a7..3b95d88 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -180,22 +180,34 @@ export default defineConfig({ link: "https://messagekit.ephemerahq.com/", items: [], // Add this line }, - { - text: "Network FAQ", - link: "/network/network-faq", - }, { text: "Protocol concepts", collapsed: false, items: [ { - text: "XMTP MLS protocol spec", - link: "/protocol/specs", + text: "Encryption", + link: "/protocol/encryption", + }, + { + text: "Identity", + link: "/protocol/identity", + }, + { + text: "Consent", + link: "/protocol/consent", + }, + { + text: "Network", + link: "/protocol/network", }, { text: "Wallet signatures", link: "/protocol/signatures", }, + { + text: "XMTP MLS protocol spec", + link: "/protocol/specs", + }, { text: "XIPs", link: "/protocol/xips",