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

Readonlyhistory

idStr

Readonlymedia

ReadonlymediaService

Readonlynetwork

Readonlyruntime

Readonlysession

Readonlysigner

Readonlystore

convergenceStatus

• get convergenceStatus(): ConvergenceStatus

  The group's derived convergence status (group-state.md §Convergence status, B5): Syncing / Resolving / Settled / Blocked. Recomputed on read against the clock, so it advances to Settled once the quiescence window elapses with no further convergence-relevant input.

  Returns ConvergenceStatus

dirty

• get dirty(): boolean

  Returns boolean

forkTree

• get forkTree(): GroupHistoryTree

  The live full-fork history tree: every group state observed (the canonical branch and every fork), keyed by MLS confirmation tag. Exposes synchronous structural queries (node, childrenOf, tips, path, ancestors, lowestCommonAncestor) and async snapshot access (stateAt, commitMessageOf). For a serializable rendering snapshot use forkTreeView.

  Returns GroupHistoryTree

groupData

• get groupData(): MarmotGroupView | null

  Returns MarmotGroupView | null

id

• get id(): Uint8Array<ArrayBufferLike>

  Returns Uint8Array<ArrayBufferLike>

info

• get info(): MarmotGroupInfo

  Complete group info/debug model for chat panels and diagnostics.

  Returns MarmotGroupInfo

lifecycle

• get lifecycle(): GroupLifecycleState

  The group's lifecycle state (group-state.md). A new local commit may only be prepared while Stable; the commit flow moves through PendingPublish (commit prepared, publish unconfirmed) and Merging (publish acked, staged commit applying) and back to Stable.

  Returns GroupLifecycleState

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

decryptMedia

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

  Decrypts an encrypted-media-v1 attachment downloaded from a blob store.

  On the first call for a given file the plaintext bytes are derived via key-derivation + ChaCha20-Poly1305 decryption (after verifying the ciphertext and plaintext hashes) and stored in {@link media}. Subsequent calls for the same attachment.ciphertextSha256 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>

dispose

• dispose(): void

  Releases in-memory resources without touching persisted state (B5): cancels the settle-check timer and fails any queued outbound. Call on unload so a timer/promise does not outlive the cached instance.

  Returns void

encryptMedia

• encryptMedia(
      blob: Blob,
      metadata: EncryptMediaMetadata,
  ): Promise<{ attachment: MediaAttachment; encrypted: Uint8Array }>

  Encrypts a media file for sharing in a group message (encrypted-media-v1).

  Derives the per-file key from the current MLS epoch, encrypts with ChaCha20-Poly1305, and returns the ciphertext alongside a populated MediaAttachment (hashes, nonce, media type, filename) with no locators yet.

  Caller responsibilities:

  1. Upload encrypted to a blob store (ciphertextSha256 is the content id).
  2. Push a locator ({ kind, value }) onto attachment.locators.
  3. Serialize with encodeMediaImetaTag and include the tag on the rumor.

  Parameters

  • blob: Blob
  • metadata: EncryptMediaMetadata

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

evaluateKeyPackage

• evaluateKeyPackage(keyPackageEvent: NostrEvent): KeyPackageEligibility

  Evaluates whether a candidate's KeyPackage event (kind 30443) can be added to this group — cipher-suite match, required_capabilities, agent-text-stream-QUIC required_member_roles, and already-a-member. Use this before GroupsManager.invite to surface why a KeyPackage can't be added; an eligible: true result is safe to invite. Never throws.

  Parameters

  • keyPackageEvent: NostrEvent

  Returns KeyPackageEligibility

forkTreeView

• forkTreeView(): ForkTreeView

  A plain, serializable snapshot of the fork-history tree for debugging UIs — every node with its epoch, parent/children, tip flag, and whether it lies on the canonical path to the live tip (the branch convergence settled on, i.e. the node matching state). Computed on demand.

  Returns ForkTreeView

ingest

• ingest(
      events: NostrEvent[],
      options?: { maxRetries?: number },
  ): AsyncGenerator<DispositionedIngestResult>

  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: { maxRetries?: number }

  Returns AsyncGenerator<DispositionedIngestResult>

  Yields

  DispositionedIngestResult - The processing result plus its inbound-processing Disposition.

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 admin commits (see GroupsManager.commit), this operation is allowed for non-admin members.

  Returns Promise<Record<string, PublishResponse>>

sendProposal

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

  Sends a proposal to the group relays

  Parameters

  • proposal: Proposal

  Returns Promise<Record<string, PublishResponse>>

submitIntent

• submitIntent(intent: GroupSessionSendIntent): Promise<GroupPublishResult[]>

  Convergence-gated outbound entry point (B5). While convergence is Settled and the lifecycle allows outbound, the intent is built, encrypted, and published immediately. Otherwise it is queued and the returned promise stays pending until the quiescence window settles and the queue drains — so app payloads are held, and group-state commits are (re)generated only against the canonical post-settle state. leave() and the self_remove auto-committer bypass this gate by design (departures and convergence progress, not fresh local intents).

  Parameters

  • intent: GroupSessionSendIntent

  Returns Promise<GroupPublishResult[]>

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>>