Build with Marmot
The Marmot Protocol combines Nostr, MLS, and Blossom for decentralized encrypted messaging. Use the MDK to build compatible clients without implementing the protocol from scratch.
Quick Start (Rust)
The MDK (Marmot Development Kit) is a modular Rust SDK. Requires Rust 1.90.0+ and SQLite.
git clone https://github.com/marmot-protocol/mdk.git
cd mdk
cargo build
cargo test --features mip04MDK Crate Structure
| Crate | Purpose |
|---|---|
| mdk-core | Main library: MLS implementation, Nostr integration, group management |
| mdk-storage-traits | Storage abstraction layer (implement for custom backends) |
| mdk-memory-storage | In-memory storage for development and testing |
| mdk-sqlite-storage | SQLite-based persistent storage with encryption (production use) |
Nostr Event Kinds
Marmot clients must subscribe to and publish these event kinds:
| Kind | Purpose | Notes |
|---|---|---|
| 443 | KeyPackage | Public invitation card for async group joins. TLS-serialized, base64 encoded. |
| 444 | Welcome | Sent to new members when added to a group. Wrapped in NIP-59 gift wrap. |
| 445 | Group Event | ChaCha20-Poly1305 encrypted group messages (proposals, commits, application messages) published with fresh ephemeral keypairs. |
| 447 | Token Request | Push notification token exchange (MIP-05). |
| 448 | Token List Response | Push notification token list (MIP-05). |
| 449 | Token Removal | Remove push notification token (MIP-05). |
| 10050 | Relay List | User's preferred relays for notifications. |
| 10051 | KeyPackage Relay List | Relays where user publishes KeyPackages. |
Default Ciphersuite
All Marmot clients must support this ciphersuite:
MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519X25519 for key exchange, AES-128-GCM for encryption, SHA-256 for hashing, Ed25519 for signatures.
Identity Model
- Nostr keypairs are used for identity (32-byte public key as
BasicCredential) - MLS signing keys are separate from Nostr identity keys
- Compromise of a Nostr identity does not give access to MLS group messages
- Each device is a separate MLS leaf node (multi-device support)
Basic Client Flow
- Generate identity: Create or import a Nostr keypair
- Publish KeyPackage: Create an MLS KeyPackage and publish it as a kind:443 event to relays listed in the user's kind:10051 event
- Create a group: Initialize an MLS group with the Marmot Group Data Extension (0xF2EE), then invite members by consuming their KeyPackages
- Send Welcome: After committing an Add proposal, send a Welcome message (kind:444) wrapped in NIP-59 gift wrap
- Send messages: Derive the 32-byte group event key from
exporter_secret, encrypt the serialized MLS message with ChaCha20-Poly1305 using a random nonce, then publishbase64(nonce || ciphertext)as kind:445 with a fresh ephemeral keypair - Receive messages: Subscribe to kind:445 events filtered by the group's
htag, decodebase64(nonce || ciphertext), decrypt with ChaCha20-Poly1305, and process the MLS message
MIP Status
The Marmot Protocol is specified through MIPs (Marmot Improvement Proposals):
| MIP | Title | Status | Required |
|---|---|---|---|
| MIP-00 | Credentials and KeyPackages | Review | Yes |
| MIP-01 | Group Construction and Marmot Group Data Extension | Review | Yes |
| MIP-02 | Welcome Events | Review | Yes |
| MIP-03 | Group Messages | Review | Yes |
| MIP-04 | Encrypted Media (Blossom + ChaCha20-Poly1305) | Review | No |
| MIP-05 | Push Notifications | Draft | No |
Full specifications: github.com/marmot-protocol/marmot
Known Limitations
- Welcome messages currently exceed relay size limits above approximately 150 group members. Work is underway on "light" Welcome support for larger groups.
- The project is in beta. Protocol specifications are in review status.
TypeScript (marmot-ts)
For web or Node.js applications, marmot-ts is an early-stage TypeScript implementation:
git clone https://github.com/marmot-protocol/marmot-ts.gitmarmot-ts is under active development and not yet feature-complete.
Key Dependencies
| Library | Purpose | Repository |
|---|---|---|
| OpenMLS | Rust MLS implementation | github.com/openmls/openmls |
| rust-nostr | Nostr protocol support | github.com/rust-nostr/nostr |
| Blossom | Content-addressed media storage | github.com/hzrd149/blossom |
Repositories
| Repository | Purpose | Language | License |
|---|---|---|---|
| whitenoise | Flutter mobile client | Dart | AGPL-3.0 |
| whitenoise-rs | Rust backend library with OpenMLS | Rust | AGPL-3.0 |
| marmot | Protocol specification (MIPs) | N/A | MIT |
| mdk | Marmot Development Kit (modular Rust SDK) | Rust | MIT |
| marmot-ts | TypeScript implementation (early stage) | TypeScript | MIT |
All repositories: github.com/marmot-protocol