Core Module
The Core module (marmot-ts/core) implements the Marmot v2 protocol layer, providing the fundamental building blocks for privacy-preserving group messaging. It bridges MLS (Message Layer Security) cryptographic operations with Nostr's decentralized event distribution, and is wire-compatible with the darkmatter reference implementation.
What's in the Core Module
The Core module is responsible for:
- Protocol Implementation: MLS group operations following the Marmot v2 specifications (MIP-00 through MIP-03)
- Identity Bridging: Converting Nostr public keys to MLS credentials, including the account identity proof app component (
0x8009,marmot.member.account-identity-proof.v2) - Message Encryption: Group events (kind 445) encrypted with a per-epoch MIP-03 key; Welcome messages gift-wrapped via NIP-59
- Key Package Management: Creating and handling cryptographic material for member addition
- State Serialization: Encoding/decoding group state for persistence
Key Dependencies
- ts-mls - RFC 9420 compliant MLS implementation; a fork bundled with the package and exposed through
@internet-privacy/marmot-ts/mls - applesauce-core / applesauce-common - Nostr event handling, NIP-44, and gift-wrap helpers
- @noble/hashes, @noble/curves, @noble/ciphers - Cryptographic primitives
- @hpke/core - HPKE for MLS key encapsulation
Installation
import {
createCredential,
generateKeyPackage,
createGroup,
// ... other exports
} from "@internet-privacy/marmot-ts";Topics
Protocol Constants & Concepts
Learn about Nostr event kinds, extension types, and core protocol concepts like app components.
Credentials
Understand how Nostr identities are converted to MLS credentials.
Key Packages
Generate and manage key packages for adding members to groups.
Groups
Create and initialize MLS groups with Marmot metadata.
Messages
Handle message encryption, decryption, commit ordering, and application messages.
Members
Query and manage group membership, including multi-device support.
Welcome Messages
Create and process Welcome messages for new members.
Key Package Distribution
Publish and discover key packages using Nostr events.
Client State
Manage and serialize MLS group state for persistence.
Complete API documentation for all Core module functions.
When to Use Core
Use the Core module when you need:
- Fine-grained control over MLS operations
- Custom client implementations with specific requirements
- Protocol extensions or implementing new MIPs
- Research and experimentation with the protocol
- Understanding of the underlying protocol layer
For most applications, use the Client module instead, which provides a higher-level API built on top of Core.
Protocol Compliance
The Core module implements the following Marmot Improvement Proposals: