Class MarmotGroup<THistory, TMedia>

constructor

• new MarmotGroup<
      THistory extends BaseGroupHistory
      | undefined = undefined,
      TMedia extends BaseGroupMedia | undefined = undefined,
  >(
      state: ClientState,
      options: MarmotGroupOptions<THistory, TMedia>,
  ): MarmotGroup<THistory, TMedia>

  Type Parameters

  • THistory extends BaseGroupHistory | undefined = undefined

    The type of the history store to use for the group, must implement the BaseGroupHistory interface. (Default is no history store)

  • TMedia extends BaseGroupMedia | undefined = undefined

  Parameters

  • state: ClientState
  • options: MarmotGroupOptions<THistory, TMedia>

  Returns MarmotGroup<THistory, TMedia>

Readonlyciphersuite

dirty

Readonlyhistory

idStr

Readonlymedia

Readonlynetwork

Readonlysigner

Readonlystore

groupData

• get groupData(): MarmotGroupData | null

  Returns MarmotGroupData | null

id

• get id(): Uint8Array<ArrayBufferLike>

  Returns Uint8Array<ArrayBufferLike>

relays

• get relays(): string[] | undefined

  Returns string[] | undefined

state

• get state(): ClientState

  Read the current group state

  Returns ClientState

• set state(newState: ClientState): void

  Overrides the current group state

  Parameters

  • newState: ClientState

  Returns void

  Warning

  It is not recommended to use this

unappliedProposals

• get unappliedProposals(): UnappliedProposals

  Returns UnappliedProposals

commit

• commit(
      options?: {
          extraProposals?: (
              | Proposal
              | ProposalAction<Proposal>
              | (Proposal | ProposalAction<Proposal>)[]
          )[];
          proposalRefs?: string[];
          welcomeRecipients?: WelcomeRecipient[];
      },
  ): Promise<Record<string, PublishResponse>>

  Creates a commit from proposals and sends it to the group.

  Proposal sources (can be combined):

  • extraProposals — inline Proposal values and/or ProposalAction factories (each factory receives ProposalContext).
  • proposalRefs — keys into state.unappliedProposals for proposals already held in state.

  If extraProposals or proposalRefs is present on options (including as an empty array), the commit uses exactly the merged, resolved list in array order (extraProposals first, then each ref in proposalRefs). Two empty arrays means a no-proposal commit. If neither property is set, the MLS layer commits every proposal currently in state.unappliedProposals.

  Requires a group admin. Publishes the commit to group relays and updates local state after an ACK. When MLS returns a welcome and welcomeRecipients is non-empty, sends gift-wrapped Welcome rumors (only after the commit ACK, per MIP-02).

  Parameters

  • Optionaloptions: {
        extraProposals?: (
            | Proposal
            | ProposalAction<Proposal>
            | (Proposal | ProposalAction<Proposal>)[]
        )[];
        proposalRefs?: string[];
        welcomeRecipients?: WelcomeRecipient[];
    }

    • OptionalextraProposals?: (Proposal | ProposalAction<Proposal> | (Proposal | ProposalAction<Proposal>)[])[]

      Flattened in order; function entries are async factories; resolved proposals are ordered before any from proposalRefs.

    • OptionalproposalRefs?: string[]

      Lookup keys on state.unappliedProposals; an unknown key throws.

    • OptionalwelcomeRecipients?: WelcomeRecipient[]

      Per-recipient key-package metadata for MLS Welcome delivery after adds; see WelcomeRecipient.

  Returns Promise<Record<string, PublishResponse>>

  Per-relay publish responses for the commit group event

decryptMedia

• decryptMedia(
      encrypted: Uint8Array,
      attachment: MediaAttachment,
  ): Promise<StoredMedia>

  Decrypts a MIP-04 v2 media attachment downloaded from Blossom.

  On the first call for a given file the plaintext bytes are derived via key-derivation + ChaCha20-Poly1305 decryption and stored in {@link media}. Subsequent calls for the same attachment.sha256 are served directly from the cache, skipping key-derivation entirely.

  Parameters

  • encrypted: Uint8Array
  • attachment: MediaAttachment

  Returns Promise<StoredMedia>

destroy

• destroy(): Promise<void>

  Destroys the group and purges the group history

  Returns Promise<void>

encryptMedia

• encryptMedia(
      blob: Blob,
      metadata: {
          alt?: string;
          blurhash?: string;
          dimensions?: string;
          filename: string;
          size?: number;
          type?: string;
      },
  ): Promise<{ attachment: MediaAttachment; encrypted: Uint8Array }>

  Encrypts a media file for sharing in a group message (MIP-04 v2).

  Derives the per-file key from the current MLS epoch, encrypts with ChaCha20-Poly1305, and returns the ciphertext alongside a fully populated MediaAttachment ready to be serialised into an imeta tag via createImetaTagForAttachment from applesauce.

  Caller responsibilities:

  1. Upload encrypted to Blossom (or any content-addressed store).
  2. Set attachment.url to the resulting upload URL.
  3. Pass attachment (with url) to createImetaTagForAttachment and include the resulting tag on the group message rumor.

  Parameters

  • blob: Blob
  • metadata: {
        alt?: string;
        blurhash?: string;
        dimensions?: string;
        filename: string;
        size?: number;
        type?: string;
    }

  Returns Promise<{ attachment: MediaAttachment; encrypted: Uint8Array }>

ingest

• ingest(
      events: NostrEvent[],
      options?: {
          _errors?: { error: unknown; eventId: string }[];
          maxRetries?: number;
          retryCount?: number;
      },
  ): AsyncGenerator<IngestResult>

  ingests an array of group messages and applies commits to the group state.

  Processing happens in two stages:

  1. Process all non-commit messages (proposals, application messages)
     • If a message fails to process, it's added to unreadable for retry
  2. Process commits according to MIP-03 (sorted by epoch, timestamp, event id)
     • Commits advance the epoch and update the group state

  After both stages, recursively retry unreadable messages until no more can be read. Events that can never be processed are yielded as UnreadableIngestResult.

  Parameters

  • events: NostrEvent[]

    Array of Nostr events containing encrypted MLS messages

  • Optionaloptions: {
        _errors?: { error: unknown; eventId: string }[];
        maxRetries?: number;
        retryCount?: number;
    }

    • Optional Internal_errors?: { error: unknown; eventId: string }[]

      Flat list of { eventId, error } entries accumulated across all retry rounds. Passed by reference so every recursive call appends to the same array, giving the final unreadable yield the full history.

    • OptionalmaxRetries?: number

      Maximum number of retry attempts (default: 5)

    • OptionalretryCount?: number

      Current retry attempt count (internal use)

  Returns AsyncGenerator<IngestResult>

  Yields

  IngestResult - The result of processing the event

inviteByKeyPackageEvent

• inviteByKeyPackageEvent(
      keyPackageEvent: NostrEvent,
  ): Promise<Record<string, PublishResponse>>

  Invites a user to the group using their KeyPackage event (kind 443).

  This method:

  1. Validates the KeyPackage event (kind 443)
  2. Validates that the credential identity matches the event pubkey
  3. Builds an Add proposal using the KeyPackage
  4. Commits the proposal
  5. After commit ack, sends a Welcome message to the invitee via NIP-59 gift wrap

  Parameters

  • keyPackageEvent: NostrEvent

    The KeyPackage event (kind 443 or kind 30443) for the user to invite

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

  Throws

  Error if the event is not a key package kind or if the credential identity doesn't match

leave

• leave(): Promise<Record<string, PublishResponse>>

  Leaves the group by publishing a self-remove proposal for each of the caller's leaf nodes, then purging all local group data from storage.

  Per RFC 9420 §12.4 a member cannot commit a Remove targeting their own leaf. Instead, a Remove proposal is sent so that the next committer (e.g. an admin calling commit) can include it and finalise the departure. At least one relay must acknowledge the proposals before local state is destroyed; if no relay acks, an error is thrown and local state is preserved so the caller can retry.

  Unlike commit, this operation is allowed for non-admin members.

  Returns Promise<Record<string, PublishResponse>>

  The relay publish responses for the leave proposal event(s).

propose

• propose<Args extends unknown[], T extends Proposal | Proposal[]>(
      action: ProposalBuilder<Args, T>,
      ...args: Args,
  ): Promise<Record<string, PublishResponse>>

  Creates and publishes a proposal as a private MLS message.

  Type Parameters

  • Args extends unknown[]
  • T extends Proposal | Proposal[]

  Parameters

  • action: ProposalBuilder<Args, T>
  • ...args: Args

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

• propose<Args extends unknown[], T extends Proposal | Proposal[]>(
      action: ProposalAction<T>,
  ): Promise<Record<string, PublishResponse>>

  Creates and publishes a proposal as a private MLS message.

  Type Parameters

  • Args extends unknown[]
  • T extends Proposal | Proposal[]

  Parameters

  • action: ProposalAction<T>

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

save

• save(force?: boolean): Promise<void>

  Persists any pending changes to the group state in the store.

  Parameters

  • force: boolean = false

    When true, writes the current state even if dirty is false. Useful for persisting the initial state of a freshly constructed group (e.g. after createGroup / joinGroupFromWelcome / import) without having to mutate dirty externally.

  Returns Promise<void>

selfUpdate

• selfUpdate(): Promise<Record<string, PublishResponse>>

  Performs a self-update commit (no proposals) to rotate this member's leaf key material.

  This is required by MIP-02 for forward secrecy after joining from a Welcome.

  Unlike commit, this operation is allowed for non-admin members.

  Returns Promise<Record<string, PublishResponse>>

sendApplicationRumor

• sendApplicationRumor(rumor: Rumor): Promise<Record<string, PublishResponse>>

  Creates and sends an application message to the group.

  Application messages contain actual content shared within the group (e.g., chat messages, reactions, etc.). The inner Nostr event (rumor) must be unsigned and will be serialized according to the Marmot spec.

  Parameters

  • rumor: Rumor

    The unsigned Nostr event (rumor) to send as an application message

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

sendChatMessage

• sendChatMessage(
      content: string,
      tags?: string[][],
  ): Promise<Record<string, PublishResponse>>

  Creates and sends a kind 9 chat message to the group.

  This is a convenience wrapper around sendApplicationRumor that constructs the rumor for you. The message is encrypted via MLS and published as a kind 445 group event to the group's relays.

  Parameters

  • content: string

    The text content of the chat message

  • tags: string[][] = []

    Optional Nostr tags to include on the rumor

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

sendProposal

• sendProposal(proposal: Proposal): Promise<Record<string, PublishResponse>>

  Sends a proposal to the group relays

  Parameters

  • proposal: Proposal

  Returns Promise<Record<string, PublishResponse>>

StaticfromClientState

• fromClientState<
      THistory extends BaseGroupHistory
      | undefined = undefined,
      TMedia extends BaseGroupMedia | undefined = undefined,
  >(
      state: ClientState,
      options: Omit<MarmotGroupOptions<THistory, TMedia>, "ciphersuite"> & {
          cryptoProvider?: CryptoProvider;
      },
  ): Promise<MarmotGroup<THistory, TMedia>>

  Creates a new MarmotGroup instance from a ClientState object

  Type Parameters

  • THistory extends BaseGroupHistory | undefined = undefined
  • TMedia extends BaseGroupMedia | undefined = undefined

  Parameters

  • state: ClientState
  • options: Omit<MarmotGroupOptions<THistory, TMedia>, "ciphersuite"> & {
        cryptoProvider?: CryptoProvider;
    }

  Returns Promise<MarmotGroup<THistory, TMedia>>