Marmot-TS
    Preparing search index...

    Class MarmotGroup<THistory, TMedia>

    The main class for interacting with a MLS group

    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

    Hierarchy

    Index
    ciphersuite: CiphersuiteImpl

    The ciphersuite implementation to use for the group

    history: THistory

    The storage interface for the groups application message history

    idStr: string

    The group id as a hex string

    Dedicated canonical group-image source and retrieval service.

    media: TMedia

    The storage interface for the groups media

    mediaService: GroupMediaService<TMedia>

    Optional media helper for group encrypted attachments.

    The nostr relay pool to use for the group

    runtime: GroupRuntime

    Runtime publisher for driving session effects through transport.

    Protocol state owner for this group. Prefer this over convenience methods.

    signer: EventSigner

    The signer used for the clients identity

    The key-value backend where serialized group state bytes are persisted

    • 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

    • 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

    • 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

    • get profileSupport(): GroupProfileSupport

      Account-identity-proof profile support is orthogonal to membership status (D-11): a stored group whose GroupContext does not classify as the current profile (legacy, mixed, or missing the 0x8009 requirement) stays listable and destroy()-able, but every outbound send and every inbound event is refused. Delegates to session.profileSupport, which recomputes from the engine on every access.

      Returns GroupProfileSupport

    • get welcomeDeliveries(): readonly WelcomeDeliveryOutcome[]

      The FOUND-04 per-invitee Welcome delivery report: one entry per recipient a founding create attempted to deliver to, in delivery order.

      This is in-memory only and is lost on restart or crash (D-04). It is discoverable state, not a returned value or a thrown error — a caller that never reads it silently loses an invitee who is already a member at epoch 1. The only recovery is the spec's re-invite path: the founding creator MAY re-invite the unreachable member with a fresh KeyPackage against the now-canonical group (refs/marmot/protocol-core/publish-lifecycle.md lines 66-78). This is an accepted consequence of D-04 + D-10 + D-12, not an oversight (R-04).

      Returns readonly WelcomeDeliveryOutcome[]

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

      Pass the authenticated sourceParent from the processed message or session.mediaSourceForRumor(). Omission selects the current state only. Cached plaintext never bypasses ciphertext and metadata validation.

      Parameters

      • encrypted: Uint8Array
      • attachment: MediaAttachment
      • OptionalsourceParent: string

      Returns Promise<StoredMedia>

    • Fans out a founding Welcome to every invitee, one NostrWelcomeDelivery.deliverMany call reached directly through runtime.welcomeDelivery (D-05/D-07) — this bypasses GroupRuntime's publish path entirely, since a founding Add has no GroupPublishWork to drive. Retains the Welcome and author so a failed recipient can be retried later via retryWelcome. Fanout and retry settlement preserve success for the same encoded Welcome, author, recipient and KeyPackage event id. A replacement obligation has independent outcomes and retry work; older attempts settle only their own obligation. The report follows the most recently started fanout's order.

      Never throws and never saves: partial or total Welcome failure is a normal outcome (D-12), reported through pendingWelcomes rather than raised. GroupFactory.create refuses a founding create without valid group relays (CR-01), so on the factory path this group always carries relays; the group-relay list is forwarded both as each Welcome rumor's required relays tag and as deliver's inbox-lookup fallback, and a recipient whose own inbox lookup resolves empty still fails independently of the others.

      Parameters

      Returns Promise<readonly WelcomeDeliveryOutcome[]>

    • 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

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

      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.
      4. Preserve the returned expectedParent on the application send intent.

      Parameters

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

    • 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

    • 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 refs/marmot/protocol-core/group-messaging.md (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>

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

    • Group transport events received but not yet decrypted/processed into the fork-history tree — the engine's ingestion pool (oldest-first). Normally transient (a message awaiting its commit, a fork message awaiting its branch); they are retried as the tree grows. An entry that lingers is a received event the client could never read — a gap a full-history debugger surfaces, since the unlocking state never arrived.

      Returns NostrEvent[]

    • Consumes a durable at-most-once callback attempt; projection is authority.

      Returns Promise<void>

    • Realizes a persisted removal after the owning registry has attached its forwarding listeners. This is idempotent across concurrent loads and process restarts when a removal marker store is configured.

      Returns Promise<void>

    • Re-scores the persisted fork history against the current tip and switches to the canonical branch if a competing fork now wins (convergence.md), persisting a resulting switch. Candidates come from the forkTree, so a client that diverged onto a losing fork converges from disk without waiting for the network to re-deliver the winning branch. Called automatically on load; safe to call explicitly to force a re-evaluation.

      CR-06: the pass's results are routed through the SAME marker-clearing branch ingest uses, so a load-time rewind that supersedes the commit which removed us clears the persisted removed-inactive marker. Previously every result here was discarded, so the documented "called automatically on load" path could never clear it and a client restored to membership kept a stale marker that silently suppressed its next genuine removal.

      Returns Promise<void>

    • Remove all listeners, or those of the specified event.

      Parameters

      • Optionalevent: keyof MarmotGroupEvents<THistory, TMedia>

      Returns this

    • Resumes a durable terminal intent after hydration when preparation is eligible. Also the single seam #settleAndDrive uses to resume a pending request mid-session, so both resume paths share one predicate.

      Returns Promise<void>

    • Re-delivers one invitee's founding Welcome. Throws naming pubkey when there is no matching delivery outcome, or when no founding Welcome is retained (for instance after a restart) — this fails loudly rather than silently no-opping, since a silent no-op is exactly R-04's failure mode. When the matching entry already succeeded, returns it unchanged without performing another delivery. Overlapping retries share one attempt per recipient; failed or rejected attempts clear so a later call can retry.

      Deliberately has no epoch guard: RESEARCH Priority Finding #1 establishes that a late epoch-1 Welcome is safe because the joiner's backfill (GroupsManager#connectGroup) has no since bound, provided the group has relays. GroupFactory.create no longer produces relay-less founding groups (CR-01), so on the factory path the relays precondition always holds.

      Parameters

      • pubkey: string

      Returns Promise<WelcomeDeliveryOutcome>

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

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

      This is required by refs/marmot/protocol-core/joining.md 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>>

    • 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

      Returns Promise<GroupPublishResult[]>

    prefixed: string | boolean
    • Return an array listing the events for which the emitter has registered listeners.

      Returns (keyof MarmotGroupEvents<THistory, TMedia>)[]

    • Return the number of listeners listening to a given event.

      Parameters

      Returns number