@badzz88/baileys 8.5.4 → 8.5.5

package/lib/Socket/messages-recv.js

@@ -37,6 +37,8 @@ const makeMessagesRecvSocket = config => {
 		signalRepository,
 		query,
 		upsertMessage,
+		getUSyncDevices,
+		createParticipantNodes,
 		resyncAppState,
 		onUnexpectedError,
 		assertSessions,
@@ -46,36 +48,33 @@ const makeMessagesRecvSocket = config => {
 		uploadPreKeys,
 		sendPeerDataOperationMessage,
 		messageRetryManager,
-		issuePrivacyTokens,
-		getUSyncDevices,
-		createParticipantNodes,
-		newsletterServerIdCache
+		issuePrivacyTokens
 	} = sock
 	const getLIDForPN = signalRepository.lidMapping.getLIDForPN.bind(signalRepository.lidMapping)
-	
+	// Track when the socket fully opens so pending pre-connect messages are treated as history
 	const socketCreatedAt = Math.floor(Date.now() / 1000)
 	let isConnected = false
-	
+	/** this mutex ensures that each retryRequest will wait for the previous one to finish */
 	const retryMutex = (0, make_mutex_1.makeMutex)()
 	const msgRetryCache =
 		config.msgRetryCounterCache ||
 		new node_cache_1.default({
-			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.MSG_RETRY, 
+			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.MSG_RETRY, // 1 hour
 			useClones: false
 		})
 	const callOfferCache =
 		config.callOfferCache ||
 		new node_cache_1.default({
-			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.CALL_OFFER, 
+			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.CALL_OFFER, // 5 mins
 			useClones: false
 		})
 	const placeholderResendCache =
 		config.placeholderResendCache ||
 		new node_cache_1.default({
-			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.MSG_RETRY, 
+			stdTTL: Defaults_1.DEFAULT_CACHE_TTLS.MSG_RETRY, // 1 hour
 			useClones: false
 		})
-	
+	// Debounce identity-change session refreshes per JID to avoid bursts
 	const identityAssertDebounce = new node_cache_1.default({ stdTTL: 5, useClones: false })
 	let sendActiveReceipts = false
 	const fetchMessageHistory = async (count, oldestMsgKey, oldestMsgTimestamp) => {
@@ -102,8 +101,8 @@ const makeMessagesRecvSocket = config => {
 			logger.debug({ messageKey }, 'already requested resend')
 			return
 		} else {
-			
-			
+			// Store original message data so PDO response handler can preserve
+			// metadata (LID details, timestamps, etc.) that the phone may omit
 			await placeholderResendCache.set(messageKey?.id, msgData || true)
 		}
 		await (0, Utils_1.delay)(2000)
@@ -127,7 +126,11 @@ const makeMessagesRecvSocket = config => {
 		}, 8000)
 		return sendPeerDataOperationMessage(pdoMessage)
 	}
-	
+	/**
+	 * Request a Waffle (Meta-account) linking nonce from the paired phone.
+	 * The phone responds via a PeerDataOperationRequestResponseMessage containing
+	 * a WaffleNonceFetchResponse with the nonce needed for Meta account linking.
+	 */
 	const requestWaffleNonce = async () => {
 		if (!authState.creds.me?.id) {
 			throw new boom_1.Boom('Not authenticated')
@@ -136,18 +139,27 @@ const makeMessagesRecvSocket = config => {
 			peerDataOperationRequestType: index_js_1.proto.Message.PeerDataOperationRequestType.WAFFLE_LINKING_NONCE_FETCH
 		})
 	}
-	
-	const requestCompanionCanonicalNonce = async registrationTraceId => {
+	/**
+	 * Request a Companion Canonical User nonce from the paired phone.
+	 * Used during companion linking to canonicalize the user identity across devices.
+	 * The phone responds with a CompanionCanonicalUserNonceFetchResponse (nonce + waFbid).
+	 *
+	 * @param {string} [registrationTraceId] - Optional trace ID for this registration attempt.
+	 */
+	const requestCompanionCanonicalNonce = async (registrationTraceId) => {
 		if (!authState.creds.me?.id) {
 			throw new boom_1.Boom('Not authenticated')
 		}
 		return sendPeerDataOperationMessage({
 			companionCanonicalUserNonceFetchRequest: registrationTraceId ? { registrationTraceId } : {},
-			peerDataOperationRequestType:
-				index_js_1.proto.Message.PeerDataOperationRequestType.COMPANION_CANONICAL_USER_NONCE_FETCH
+			peerDataOperationRequestType: index_js_1.proto.Message.PeerDataOperationRequestType.COMPANION_CANONICAL_USER_NONCE_FETCH
 		})
 	}
-	
+	/**
+	 * Request a Companion Meta nonce from the paired phone.
+	 * Used during Meta-account companion linking flow.
+	 * The phone responds with a CompanionMetaNonceFetchResponse (nonce).
+	 */
 	const requestCompanionMetaNonce = async () => {
 		if (!authState.creds.me?.id) {
 			throw new boom_1.Boom('Not authenticated')
@@ -156,138 +168,57 @@ const makeMessagesRecvSocket = config => {
 			peerDataOperationRequestType: index_js_1.proto.Message.PeerDataOperationRequestType.COMPANION_META_NONCE_FETCH
 		})
 	}
-	
-	
-	const handleMexNotification = async node => {
-		const updateNodes = (0, WABinary_1.getBinaryNodeChildren)(node, 'update')
-		if (!updateNodes.length) {
-			logger.debug({ node }, 'mex notification with no update children')
+	// Handles mex newsletter notifications
+	const handleMexNewsletterNotification = async node => {
+		const mexNode = (0, WABinary_1.getBinaryNodeChild)(node, 'mex')
+		if (!mexNode?.content) {
+			logger.warn({ node }, 'Invalid mex newsletter notification')
 			return
 		}
-		for (const updateNode of updateNodes) {
-			const opName = updateNode.attrs?.op_name
-			if (!opName) continue
-			let payload
-			try {
-				const raw = updateNode.content?.text ?? updateNode.content?.toString?.()
-				payload = raw ? JSON.parse(raw) : null
-			} catch (e) {
-				logger.error({ err: e, opName }, 'failed to parse mex update payload')
-				continue
-			}
-			if (!payload?.data) {
-				logger.debug({ opName }, 'mex update with no data field')
-				continue
-			}
-			const d = payload.data
-			switch (opName) {
-				case 'NotificationNewsletterUpdate': {
-					
-					const upd = d.xwa2_notify_newsletter_on_metadata_update
-					if (upd?.id) {
-						ev.emit('newsletter-settings.update', {
-							id: upd.id,
-							update: upd.thread_metadata?.settings ?? {}
-						})
-					}
-					break
-				}
-				case 'NotificationNewsletterJoin': {
-					
-					const upd = d.xwa2_notify_newsletter_on_join
-					if (upd?.id) {
-						ev.emit('newsletter-participants.update', {
-							id: upd.id,
-							author: node.attrs.from,
-							user: (0, WABinary_1.jidNormalizedUser)(node.attrs.from),
-							new_role: upd.viewer_metadata?.role ?? 'SUBSCRIBER',
-							action: 'join',
-							metadata: upd.thread_metadata
-						})
-					}
-					break
-				}
-				case 'NotificationNewsletterMuteChange': {
-					
-					const upd = d.xwa2_notify_newsletter_on_mute_change
-					if (upd?.id) {
-						ev.emit('newsletter-settings.update', {
-							id: upd.id,
-							update: { mute: upd.mute }
-						})
-					}
-					break
-				}
-				case 'NotificationNewsletterUserSettingChange': {
-					
-					const upd = d.xwa2_notify_newsletter_on_user_setting_change
-					if (upd?.id && upd.setting) {
+		let data
+		try {
+			data = JSON.parse(mexNode.content.toString())
+		} catch (error) {
+			logger.error({ err: error, node }, 'Failed to parse mex newsletter notification')
+			return
+		}
+		const operation = data?.operation
+		const updates = data?.updates
+		if (!updates || !operation) {
+			logger.warn({ data }, 'Invalid mex newsletter notification content')
+			return
+		}
+		logger.info({ operation, updates }, 'got mex newsletter notification')
+		switch (operation) {
+			case 'NotificationNewsletterUpdate':
+				for (const update of updates) {
+					if (update.jid && update.settings && Object.keys(update.settings).length > 0) {
 						ev.emit('newsletter-settings.update', {
-							id: upd.id,
-							update: { userSetting: upd.setting }
+							id: update.jid,
+							update: update.settings
 						})
 					}
-					break
 				}
-				case 'NotificationNewsletterAdminPromote': {
-					
-					const upd = d.xwa2_notify_newsletter_on_admin_promote
-					if (upd?.id) {
+				break
+			case 'NotificationNewsletterAdminPromote':
+				for (const update of updates) {
+					if (update.jid && update.user) {
 						ev.emit('newsletter-participants.update', {
-							id: upd.id,
+							id: update.jid,
 							author: node.attrs.from,
-							user: upd.user,
+							user: update.user,
 							new_role: 'ADMIN',
 							action: 'promote'
 						})
 					}
-					break
-				}
-				case 'NotificationGroupMemberLinkPropertyUpdate': {
-					
-					const upd = d.xwa2_notify_group_on_prop_change
-					if (upd?.id && upd.properties?.member_link_mode !== undefined) {
-						ev.emit('groups.update', [
-							{
-								id: upd.id,
-								memberAddMode: upd.properties.member_link_mode
-							}
-						])
-					}
-					break
-				}
-				case 'NotificationGroupLimitSharingPropertyUpdate': {
-					
-					const upd = d.xwa2_notify_group_on_prop_change
-					if (upd?.id && upd.properties?.limit_sharing !== undefined) {
-						ev.emit('groups.update', [
-							{
-								id: upd.id,
-								limitSharing: upd.properties.limit_sharing
-							}
-						])
-					}
-					break
 				}
-				case 'NotificationGroupMemberShareGroupHistoryModePropertyUpdate': {
-					
-					const upd = d.xwa2_notify_group_on_prop_change
-					if (upd?.id && upd.properties?.member_share_group_history_mode !== undefined) {
-						ev.emit('groups.update', [
-							{
-								id: upd.id,
-								memberShareHistoryMode: upd.properties.member_share_group_history_mode
-							}
-						])
-					}
-					break
-				}
-				default:
-					logger.debug({ opName, from: node.attrs.from }, 'unhandled mex op')
-			}
+				break
+			default:
+				logger.info({ operation, data }, 'Unhandled mex newsletter notification')
+				break
 		}
 	}
-	
+	// Handles newsletter notifications
 	const handleNewsletterNotification = async node => {
 		const from = node.attrs.from
 		const child = (0, WABinary_1.getAllBinaryNodeChildren)(node)[0]
@@ -337,9 +268,7 @@ const makeMessagesRecvSocket = config => {
 					})
 				}
 				break
-			case 'message': {
-				const viewCount = child.attrs.view_count !== undefined ? +child.attrs.view_count : undefined
-				const impressionCount = child.attrs.impression_count !== undefined ? +child.attrs.impression_count : undefined
+			case 'message':
 				const plaintextNode = (0, WABinary_1.getBinaryNodeChild)(child, 'plaintext')
 				if (plaintextNode?.content) {
 					try {
@@ -352,16 +281,11 @@ const makeMessagesRecvSocket = config => {
 							key: {
 								remoteJid: from,
 								id: child.attrs.message_id || child.attrs.server_id,
-								
-								
-								fromMe: false
+								fromMe: false // TODO: is this really true though
 							},
 							message: messageProto,
 							messageTimestamp: +child.attrs.t
 						}).toJSON()
-						
-						if (viewCount !== undefined) fullMessage.views = viewCount
-						if (impressionCount !== undefined) fullMessage.impressions = impressionCount
 						await upsertMessage(fullMessage, 'append')
 						logger.info('Processed plaintext newsletter message')
 					} catch (error) {
@@ -369,44 +293,23 @@ const makeMessagesRecvSocket = config => {
 					}
 				}
 				break
-			}
-			case 'live_updates': {
-				
-				
-				
-				const messagesNode = (0, WABinary_1.getBinaryNodeChild)(child, 'messages')
-				const msgTs = messagesNode?.attrs?.t ? +messagesNode.attrs.t : undefined
-				for (const msgNode of (0, WABinary_1.getBinaryNodeChildren)(messagesNode ?? child, 'message')) {
-					const serverId = msgNode.attrs.server_id
-					const fwdNode = (0, WABinary_1.getBinaryNodeChild)(msgNode, 'forwards_count')
-					const forwardsCount = fwdNode?.attrs?.count !== undefined ? +fwdNode.attrs.count : undefined
-					const reactionsNode = (0, WABinary_1.getBinaryNodeChild)(msgNode, 'reactions')
-					const reactions = (0, WABinary_1.getBinaryNodeChildren)(reactionsNode ?? msgNode, 'reaction').map(r => ({
-						code: r.attrs.code,
-						count: +r.attrs.count
-					}))
-					ev.emit('newsletter.live-update', {
-						id: from,
-						server_id: serverId,
-						timestamp: msgTs,
-						forwardsCount,
-						reactions
-					})
-				}
+			case 'live_updates':
+				// Live view count / engagement update
+				const liveCount = parseInt(child.attrs.count || child.content?.toString() || '0', 10)
+				ev.emit('newsletter.live-update', {
+					id: from,
+					server_id: child.attrs.message_id || child.attrs.server_id,
+					liveViewers: liveCount,
+					timestamp: child.attrs.t ? +child.attrs.t : undefined
+				})
 				break
-			}
-			case 'pin': {
-				const pinnedServerId = child.attrs.message_id || child.attrs.server_id
-				const isPinned = child.attrs.action !== 'unpin'
+			case 'pin':
 				ev.emit('newsletter.pin', {
 					id: from,
-					server_id: pinnedServerId,
-					pinned: isPinned
+					server_id: child.attrs.message_id || child.attrs.server_id,
+					pinned: child.attrs.action !== 'unpin'
 				})
-				
-				ev.emit('newsletters.update', [{ id: from, pinnedMessage: isPinned ? pinnedServerId : null }])
 				break
-			}
 			case 'category':
 				ev.emit('newsletter-settings.update', {
 					id: from,
@@ -426,92 +329,8 @@ const makeMessagesRecvSocket = config => {
 				break
 		}
 	}
-	
-	
-	const handleNewsletterStatus = async node => {
-		const { id, from, server_id, t, is_sender, offline, type, edit } = node.attrs
-		const serverId = server_id ? +server_id : undefined
-		const timestamp = t ? +t : undefined
-		const isSender = is_sender === 'true'
-		const offlineIndex = offline !== undefined ? +offline : undefined
-		
-		if (id && serverId != null) {
-			newsletterServerIdCache?.set(id, serverId)
-		}
-
-		
-		const metaNode = (0, WABinary_1.getBinaryNodeChild)(node, 'meta')
-		const meta = metaNode
-			? {
-					...(metaNode.attrs.msg_edit_t ? { editedAt: +metaNode.attrs.msg_edit_t } : {}),
-					...(metaNode.attrs.original_msg_t ? { originalTimestamp: +metaNode.attrs.original_msg_t } : {}),
-					...(metaNode.attrs.interaction_type ? { interactionType: metaNode.attrs.interaction_type } : {}),
-					...(metaNode.attrs.parent_server_id ? { parentServerId: +metaNode.attrs.parent_server_id } : {}),
-					...(metaNode.attrs.response_server_id ? { responseServerId: +metaNode.attrs.response_server_id } : {})
-				}
-			: undefined
-
-		
-		const viewsNode = (0, WABinary_1.getBinaryNodeChild)(node, 'views_count')
-		const viewsCount = viewsNode?.attrs?.count !== undefined ? +viewsNode.attrs.count : undefined
-		const responsesNode = (0, WABinary_1.getBinaryNodeChild)(node, 'responses_count')
-		const responsesCount = responsesNode?.attrs?.count !== undefined ? +responsesNode.attrs.count : undefined
-		const reactionsNode = (0, WABinary_1.getBinaryNodeChild)(node, 'reactions')
-		const reactionCounts = (0, WABinary_1.getBinaryNodeChildren)(reactionsNode ?? { content: [] }, 'reaction').map(
-			r => ({ code: r.attrs.code, count: +r.attrs.count })
-		)
-
-		let content = null
-		let mediaType = undefined
-
-		if (type === 'reaction') {
-			const reactionNode = (0, WABinary_1.getBinaryNodeChild)(node, 'reaction')
-			content = { type: 'reaction', code: reactionNode?.attrs?.code }
-		} else if (type === 'text' || type === 'media') {
-			const plaintextNode = (0, WABinary_1.getBinaryNodeChild)(node, 'plaintext')
-			if (type === 'media') mediaType = plaintextNode?.attrs?.mediatype
-			if (edit === '7' || edit === '8') {
-				content = { type: 'revoke', edit }
-			} else if (plaintextNode?.content) {
-				try {
-					const buf = Buffer.isBuffer(plaintextNode.content)
-						? plaintextNode.content
-						: Buffer.from(plaintextNode.content)
-					const message = index_js_1.proto.Message.decode(buf).toJSON()
-					content = { type, message, ...(mediaType ? { mediaType } : {}) }
-				} catch (err) {
-					logger.error({ err }, 'Failed to decode newsletter status plaintext')
-					content = { type, raw: true, ...(mediaType ? { mediaType } : {}) }
-				}
-			}
-		}
-
-		
-		const ackType = type === 'reaction' ? 'reaction' : edit ? 'revoke' : type
-		await sendNode({
-			tag: 'ack',
-			attrs: { id, to: from, class: 'status', type: ackType || 'text' },
-			content: undefined
-		})
-
-		ev.emit('newsletter.status', {
-			id: from,
-			messageId: id,
-			serverId,
-			timestamp,
-			isSender,
-			...(offlineIndex !== undefined ? { offlineIndex } : {}),
-			...(meta ? { meta } : {}),
-			...(viewsCount !== undefined ? { viewsCount } : {}),
-			...(responsesCount !== undefined ? { responsesCount } : {}),
-			...(reactionCounts.length ? { reactionCounts } : {}),
-			content
-		})
-	}
 	const sendMessageAck = async (node, errorCode) => {
-		
-		
-		const stanza = (0, stanza_ack_1.buildAckStanza)(node, errorCode, authState.creds.me?.id)
+		const stanza = (0, stanza_ack_1.buildAckStanza)(node, errorCode, authState.creds.me.id)
 		logger.debug({ recv: { tag: node.tag, attrs: node.attrs }, sent: stanza.attrs }, 'sent ack')
 		await sendNode(stanza)
 	}
@@ -678,7 +497,15 @@ const makeMessagesRecvSocket = config => {
 		await query(stanza)
 	}
 
-	
+	/**
+	 * Re-encrypt call key for a device that reconnected mid-call.
+	 * Source: OutgoingSignalingHandler.java enc_rekey / rekeyEncryptionTask
+	 *
+	 * @param {string} callId - Active call ID
+	 * @param {string} callFrom - JID of the call creator
+	 * @param {Buffer} encryptedKeyBytes - Re-encrypted call session key bytes
+	 * @param {number} [count=0] - Retry counter (0–4)
+	 */
 	const rekeyCall = async (callId, callFrom, encryptedKeyBytes, count = 0) => {
 		const stanza = {
 			tag: 'call',
@@ -707,7 +534,14 @@ const makeMessagesRecvSocket = config => {
 		await query(stanza)
 	}
 
-	
+	/**
+	 * Join a call via an invite link.
+	 * Source: OutgoingSignalingHandler.java link_join tag
+	 *
+	 * @param {string} callId - Call ID from the link
+	 * @param {string} callCreator - JID of the call creator
+	 * @param {string} linkToken - Token from the call link
+	 */
 	const joinCallLink = async (callId, callCreator, linkToken) => {
 		const stanza = {
 			tag: 'call',
@@ -730,7 +564,13 @@ const makeMessagesRecvSocket = config => {
 		await query(stanza)
 	}
 
-	
+	/**
+	 * Query info about a call link before joining.
+	 * Source: OutgoingSignalingHandler.java link_query tag
+	 *
+	 * @param {string} callLinkCode - The call link code to query
+	 * @param {string} to - JID to send the query to
+	 */
 	const queryCallLink = async (callLinkCode, to) => {
 		const stanza = {
 			tag: 'call',
@@ -753,19 +593,19 @@ const makeMessagesRecvSocket = config => {
 		const { key: msgKey } = fullMessage
 		const msgId = msgKey.id
 		if (messageRetryManager) {
-			
+			// Check if we've exceeded max retries using the new system
 			if (messageRetryManager.hasExceededMaxRetries(msgId)) {
 				logger.debug({ msgId }, 'reached retry limit with new retry manager, clearing')
 				messageRetryManager.markRetryFailed(msgId)
 				return
 			}
-			
+			// Increment retry count using new system
 			const retryCount = messageRetryManager.incrementRetryCount(msgId)
-			
+			// Use the new retry count for the rest of the logic
 			const key = `${msgId}:${msgKey?.participant}`
 			await msgRetryCache.set(key, retryCount)
 		} else {
-			
+			// Fallback to old system
 			const key = `${msgId}:${msgKey?.participant}`
 			let retryCount = (await msgRetryCache.get(key)) || 0
 			if (retryCount >= maxMsgRetryCount) {
@@ -780,12 +620,12 @@ const makeMessagesRecvSocket = config => {
 		const retryCount = (await msgRetryCache.get(key)) || 1
 		const { account, signedPreKey, signedIdentityKey: identityKey } = authState.creds
 		const fromJid = node.attrs.from
-		
+		// Check if we should recreate the session
 		let shouldRecreateSession = false
 		let recreateReason = ''
 		if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1) {
 			try {
-				
+				// Check if we have a session with this JID
 				const sessionId = signalRepository.jidToSignalProtocolAddress(fromJid)
 				const hasSession = await signalRepository.validateSession(fromJid)
 				const result = messageRetryManager.shouldRecreateSession(fromJid, hasSession.exists)
@@ -793,7 +633,7 @@ const makeMessagesRecvSocket = config => {
 				recreateReason = result.reason
 				if (shouldRecreateSession) {
 					logger.debug({ fromJid, retryCount, reason: recreateReason }, 'recreating session for retry')
-					
+					// Delete existing session to force recreation
 					await authState.keys.set({ session: { [sessionId]: null } })
 					forceIncludeKeys = true
 				}
@@ -802,9 +642,9 @@ const makeMessagesRecvSocket = config => {
 			}
 		}
 		if (retryCount <= 2) {
-			
+			// Use new retry manager for phone requests if available
 			if (messageRetryManager) {
-				
+				// Schedule phone request with delay (like whatsmeow)
 				messageRetryManager.schedulePhoneRequest(msgId, async () => {
 					try {
 						const requestId = await requestPlaceholderResend(msgKey)
@@ -816,7 +656,7 @@ const makeMessagesRecvSocket = config => {
 					}
 				})
 			} else {
-				
+				// Fallback to immediate request
 				const msgId = await requestPlaceholderResend(msgKey)
 				logger.debug(`sendRetryRequest: requested placeholder resend for message ${msgId}`)
 			}
@@ -838,9 +678,8 @@ const makeMessagesRecvSocket = config => {
 							id: node.attrs.id,
 							t: node.attrs.t,
 							v: '1',
-							
-							
-							error: '1'
+							// ADD ERROR FIELD
+							error: '0'
 						}
 					},
 					{
@@ -878,14 +717,17 @@ const makeMessagesRecvSocket = config => {
 			logger.info({ msgAttrs: node.attrs, retryCount }, 'sent retry receipt')
 		}, authState?.creds?.me?.id || 'sendRetryRequest')
 	}
-	
+	/**
+	 * Fire-and-forget tctoken re-issuance after a peer's device identity changed.
+	 * Runs in parallel with the session refresh (not after it).
+	 */
 	const reissueTcTokenAfterIdentityChange = from => {
 		void (async () => {
 			const normalizedJid = (0, WABinary_1.jidNormalizedUser)(from)
 			const tcJid = await (0, tc_token_utils_1.resolveTcTokenJid)(normalizedJid, getLIDForPN)
 			const tcTokenData = await authState.keys.get('tctoken', [tcJid])
 			const senderTs = tcTokenData?.[tcJid]?.senderTimestamp
-			if (senderTs == null || (0, tc_token_utils_1.isTcTokenExpired)(senderTs)) {
+			if (senderTs === null || senderTs === undefined || (0, tc_token_utils_1.isTcTokenExpired)(senderTs)) {
 				return
 			}
 			logger.debug({ jid: normalizedJid, senderTimestamp: senderTs }, 'identity changed, re-issuing tctoken')
@@ -933,21 +775,8 @@ const makeMessagesRecvSocket = config => {
 			}
 		}
 	}
-	
-	
-	const storeParticipantLidPairs = participants => {
-		const pairs = []
-		for (const p of participants || []) {
-			if (p.phoneNumber) pairs.push({ lid: p.id, pn: p.phoneNumber })
-			else if (p.lid) pairs.push({ lid: p.lid, pn: p.id })
-		}
-		if (!pairs.length) return
-		signalRepository.lidMapping
-			.storeLIDPNMappings(pairs)
-			.catch(error => logger.debug({ error }, 'failed to store LID/PN mappings from group notification'))
-	}
 	const handleGroupNotification = (fullNode, child, msg) => {
-		
+		// TODO: Support PN/LID (Here is only LID now)
 		const actingParticipantLid = fullNode.attrs.participant
 		const actingParticipantPn = fullNode.attrs.participant_pn
 		const actingParticipantUsername = fullNode.attrs.participant_username
@@ -961,7 +790,6 @@ const makeMessagesRecvSocket = config => {
 				msg.messageStubType = Types_1.WAMessageStubType.GROUP_CREATE
 				msg.messageStubParameters = [metadata.subject]
 				msg.key = { participant: metadata.owner, participantAlt: metadata.ownerPn }
-				storeParticipantLidPairs(metadata.participants)
 				ev.emit('chats.upsert', [
 					{
 						id: metadata.id,
@@ -1000,6 +828,7 @@ const makeMessagesRecvSocket = config => {
 				const stubType = `GROUP_PARTICIPANT_${child.tag.toUpperCase()}`
 				msg.messageStubType = Types_1.WAMessageStubType[stubType]
 				const participants = (0, WABinary_1.getBinaryNodeChildren)(child, 'participant').map(({ attrs }) => {
+					// TODO: Store LID MAPPINGS
 					return {
 						id: attrs.jid,
 						phoneNumber:
@@ -1008,21 +837,19 @@ const makeMessagesRecvSocket = config => {
 								: undefined,
 						lid: (0, WABinary_1.isPnUser)(attrs.jid) && (0, WABinary_1.isLidUser)(attrs.lid) ? attrs.lid : undefined,
 						username: attrs.participant_username || attrs.username || undefined,
-						admin: attrs.type || null,
-						uuid: attrs.uuid || attrs.participant_uuid || undefined
+						admin: attrs.type || null
 					}
 				})
 				if (
 					participants.length === 1 &&
-					
-					
+					// if recv. "remove" message and sender removed themselves
+					// mark as left
 					((0, WABinary_1.areJidsSameUser)(participants[0].id, actingParticipantLid) ||
 						(0, WABinary_1.areJidsSameUser)(participants[0].id, actingParticipantPn)) &&
 					child.tag === 'remove'
 				) {
 					msg.messageStubType = Types_1.WAMessageStubType.GROUP_PARTICIPANT_LEAVE
 				}
-				storeParticipantLidPairs(participants)
 				msg.messageStubParameters = participants.map(a => JSON.stringify(a))
 				break
 			case 'subject':
@@ -1072,51 +899,13 @@ const makeMessagesRecvSocket = config => {
 				break
 			case 'revoked_membership_requests':
 				const isDenied = (0, WABinary_1.areJidsSameUser)(affectedParticipantLid, actingParticipantLid)
-				if ((0, WABinary_1.isLidUser)(affectedParticipantLid) && (0, WABinary_1.isPnUser)(affectedParticipantPn)) {
-					storeParticipantLidPairs([{ id: affectedParticipantLid, phoneNumber: affectedParticipantPn }])
-				}
+				// TODO: LIDMAPPING SUPPORT
 				msg.messageStubType = Types_1.WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
 				msg.messageStubParameters = [
 					JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }),
 					isDenied ? 'revoked' : 'rejected'
 				]
 				break
-			case 'sibling_link': {
-				const linkedGroupJid = (0, WABinary_1.getBinaryNodeChild)(child, 'group')?.attrs?.jid || child.attrs?.jid
-				ev.emit('groups.update', [
-					{
-						id: fullNode.attrs.from,
-						siblingGroupLinked: linkedGroupJid || true,
-						author: actingParticipantLid,
-						authorPn: actingParticipantPn
-					}
-				])
-				break
-			}
-			case 'sibling_unlink': {
-				const unlinkedGroupJid = (0, WABinary_1.getBinaryNodeChild)(child, 'group')?.attrs?.jid || child.attrs?.jid
-				ev.emit('groups.update', [
-					{
-						id: fullNode.attrs.from,
-						siblingGroupUnlinked: unlinkedGroupJid || true,
-						author: actingParticipantLid,
-						authorPn: actingParticipantPn
-					}
-				])
-				break
-			}
-			case 'clear_history': {
-				const historyClearTimestamp = child.attrs?.t ? +child.attrs.t : (0, Date)()
-				ev.emit('groups.update', [
-					{
-						id: fullNode.attrs.from,
-						historyClearTimestamp,
-						author: actingParticipantLid,
-						authorPn: actingParticipantPn
-					}
-				])
-				break
-			}
 		}
 	}
 	const normalizeNotificationParticipant = async (jid, groupData) => {
@@ -1250,12 +1039,21 @@ const makeMessagesRecvSocket = config => {
 		}
 	}
 
-	
+	/**
+	 * Handle incoming interop notifications (type="interop").
+	 *
+	 * The APK emits these for:
+	 *  - stella_interop_enabled / stella_ios_enabled  → feature-flag toggles
+	 *  - ig_professional / ig_handle / followers       → Instagram profile data updates
+	 *  - fbid:thread / fbid:devices                   → Meta thread/device association
+	 *  - peer_device_presence                         → interop contact online/offline
+	 *  - group membership changes in interop groups   → add/remove/promote events
+	 */
 	const handleInteropNotification = (node, child) => {
 		const childTag = child?.tag
 		const attrs = child?.attrs || {}
 
-		
+		// Feature flag: server toggled stella_interop_enabled or stella_ios_enabled
 		if (childTag === 'feature') {
 			const feature = attrs.name
 			const enabled = attrs.value === 'true' || attrs.value === '1'
@@ -1264,7 +1062,7 @@ const makeMessagesRecvSocket = config => {
 			return
 		}
 
-		
+		// Instagram profile data pushed for an interop contact
 		if (childTag === 'ig_profile') {
 			const contactUpdate = {
 				id: (0, WABinary_1.jidNormalizedUser)(node.attrs.from),
@@ -1277,28 +1075,26 @@ const makeMessagesRecvSocket = config => {
 			return
 		}
 
-		
+		// peer_device_presence — interop contact came online or went offline
 		if (childTag === 'peer_device_presence') {
 			const jid = attrs.jid || (0, WABinary_1.jidNormalizedUser)(node.attrs.from)
 			const presence = attrs.type === 'unavailable' ? 'unavailable' : 'available'
-			const isIosInterop = !!authState.creds.interopIosEnabled
-			logger.debug({ jid, presence, isIosInterop }, '[interop] peer_device_presence')
-			ev.emit('presence.update', { id: jid, presences: { [jid]: { lastKnownPresence: presence } }, isIosInterop })
+			logger.debug({ jid, presence }, '[interop] peer_device_presence')
+			ev.emit('presence.update', { id: jid, presences: { [jid]: { lastKnownPresence: presence } } })
 			return
 		}
 
-		
+		// fbid:thread / fbid:devices — Meta thread or device list association
 		if (childTag === 'fbid_thread' || childTag === 'fbid_devices') {
-			const isIosInterop = !!authState.creds.interopIosEnabled
-			logger.debug({ childTag, attrs, from: node.attrs.from, isIosInterop }, '[interop] fbid association update')
-			ev.emit('interop.fbid-update', { type: childTag, jid: node.attrs.from, attrs, isIosInterop })
+			logger.debug({ childTag, attrs, from: node.attrs.from }, '[interop] fbid association update')
+			ev.emit('interop.fbid-update', { type: childTag, jid: node.attrs.from, attrs })
 			return
 		}
 
-		
+		// Interop group membership changes (add / remove / promote / demote)
 		if (childTag === 'participants') {
 			const groupJid = node.attrs.from
-			const action = attrs.type 
+			const action = attrs.type // 'add' | 'remove' | 'promote' | 'demote'
 			const participants = (0, WABinary_1.getBinaryNodeChildren)(child, 'participant').map(p => p.attrs.jid)
 			logger.info({ groupJid, action, participants }, '[interop] group participants update')
 			ev.emit('group-participants.update', { id: groupJid, participants, action })
@@ -1318,24 +1114,10 @@ const makeMessagesRecvSocket = config => {
 				await handleNewsletterNotification(node)
 				break
 			case 'mex':
-				await handleMexNotification(node)
+				await handleMexNewsletterNotification(node)
 				break
 			case 'w:gp2':
-				if (child?.tag === 'groups_dirty') {
-					
-					
-					const dirtyGroupJids = (0, WABinary_1.getBinaryNodeChildren)(child, 'group')
-						.map(g => g.attrs.jid)
-						.filter(Boolean)
-					if (dirtyGroupJids.length) {
-						ev.emit(
-							'groups.update',
-							dirtyGroupJids.map(jid => ({ id: jid }))
-						)
-					}
-					break
-				}
-				
+				// TODO: HANDLE PARTICIPANT_PN
 				const groupData = await getNotificationGroupData(node)
 				handleGroupNotification(node, child, result)
 
@@ -1348,39 +1130,26 @@ const makeMessagesRecvSocket = config => {
 			case 'encrypt':
 				await handleEncryptNotification(node)
 				break
-			case 'devices': {
-				
-				
-				
-				const addNode = (0, WABinary_1.getBinaryNodeChild)(node, 'add')
-				const removeNode = (0, WABinary_1.getBinaryNodeChild)(node, 'remove')
-				const changedNode = addNode || removeNode
-				if (!changedNode) {
-					logger.debug({ node }, 'devices hash refresh, no add/remove list to report')
-					break
-				}
-				const isAdded = !!addNode
-				const devices = (0, WABinary_1.getBinaryNodeChildren)(changedNode, 'device')
-				const deviceOwnerJid = from
+			case 'devices':
+				const devices = (0, WABinary_1.getBinaryNodeChildren)(child, 'device')
+				const deviceOwnerJid = child.attrs.jid || child.attrs.lid
 				const deviceData = devices.map(d => ({
 					id: d.attrs.jid,
 					lid: d.attrs.lid,
-					
-					keyIndex: d.attrs['key-index'] ? +d.attrs['key-index'] : undefined,
+					keyIndex: d.attrs.key_index ? +d.attrs.key_index : undefined,
 					platform: d.attrs.platform || undefined,
 					isCompanion: d.attrs.companion === 'true' || undefined
 				}))
-				const isSelf =
-					(0, WABinary_1.areJidsSameUser)(from, authState.creds.me?.id) ||
-					(0, WABinary_1.areJidsSameUser)(from, authState.creds.me?.lid)
-				if (isSelf) {
-					logger.info({ deviceData, isAdded }, 'my own devices changed')
-				}
-				if (deviceOwnerJid) {
-					ev.emit('devices.update', { id: deviceOwnerJid, devices: deviceData, isSelf, added: isAdded })
+				if (
+					(0, WABinary_1.areJidsSameUser)(child.attrs.jid, authState.creds.me.id) ||
+					(0, WABinary_1.areJidsSameUser)(child.attrs.lid, authState.creds.me.lid)
+				) {
+					logger.info({ deviceData }, 'my own devices changed')
+					ev.emit('devices.update', { id: deviceOwnerJid, devices: deviceData, isSelf: true })
+				} else if (deviceOwnerJid) {
+					ev.emit('devices.update', { id: deviceOwnerJid, devices: deviceData, isSelf: false })
 				}
 				break
-			}
 			case 'server_sync':
 				const update = (0, WABinary_1.getBinaryNodeChild)(node, 'collection')
 				if (update) {
@@ -1388,18 +1157,13 @@ const makeMessagesRecvSocket = config => {
 					await resyncAppState([name], false)
 				}
 				break
-			case 'picture': {
+			case 'picture':
 				const setPicture = (0, WABinary_1.getBinaryNodeChild)(node, 'set')
 				const delPicture = (0, WABinary_1.getBinaryNodeChild)(node, 'delete')
-				const pictureOwnerJid = (0, WABinary_1.jidNormalizedUser)(node?.attrs?.from)
-				if (!pictureOwnerJid) {
-					
-					logger.debug({ node }, 'picture notification missing "from", skipping contacts.update')
-					break
-				}
+				// TODO: WAJIDHASH stuff proper support inhouse
 				ev.emit('contacts.update', [
 					{
-						id: pictureOwnerJid,
+						id: (0, WABinary_1.jidNormalizedUser)(node?.attrs?.from) || (setPicture || delPicture)?.attrs?.hash || '',
 						imgUrl: setPicture ? 'changed' : 'removed'
 					}
 				])
@@ -1416,7 +1180,6 @@ const makeMessagesRecvSocket = config => {
 					}
 				}
 				break
-			}
 			case 'account_sync':
 				if (child.tag === 'disappearing_mode') {
 					const newDuration = +child.attrs.duration
@@ -1432,60 +1195,18 @@ const makeMessagesRecvSocket = config => {
 						}
 					})
 				} else if (child.tag === 'blocklist') {
-					
-					
-					
-					sock.fetchBlocklist().catch(error => logger.warn({ error }, 'failed to refresh blocklist after account_sync'))
-				} else if (child.tag === 'devices') {
-					
-					
-					const dhash = child.attrs.dhash
-					const deviceNodes = (0, WABinary_1.getBinaryNodeChildren)(child, 'device')
-					const keyIndexListNode = (0, WABinary_1.getBinaryNodeChild)(child, 'key-index-list')
-					const devices = deviceNodes.map(d => ({
-						jid: d.attrs.jid ? String(d.attrs.jid) : undefined,
-						keyIndex: d.attrs['key-index'] ? +d.attrs['key-index'] : undefined
-					}))
-					logger.info({ dhash, deviceCount: devices.length }, 'account devices list synced')
-					ev.emit('account.devices-synced', {
-						dhash,
-						devices,
-						keyIndexListTimestamp: keyIndexListNode?.attrs?.ts ? +keyIndexListNode.attrs.ts : undefined,
-						keyIndexList: keyIndexListNode?.content ? Buffer.from(keyIndexListNode.content) : undefined
-					})
-				}
-				break
-			case 'disappearing_mode': {
-				
-				
-				const newDuration = +child.attrs.duration
-				const timestamp = +child.attrs.t
-				logger.info({ newDuration }, 'updated account disappearing mode')
-				ev.emit('creds.update', {
-					accountSettings: {
-						...authState.creds.accountSettings,
-						defaultDisappearingMode: {
-							ephemeralExpiration: newDuration,
-							ephemeralSettingTimestamp: timestamp
-						}
+					const blocklists = (0, WABinary_1.getBinaryNodeChildren)(child, 'item')
+					for (const { attrs } of blocklists) {
+						const blocklist = [attrs.jid]
+						const type = attrs.action === 'block' ? 'add' : 'remove'
+						ev.emit('blocklist.update', { blocklist, type })
 					}
-				})
-				break
-			}
-			case 'contacts': {
-				
-				
-				const updateChild = (0, WABinary_1.getBinaryNodeChild)(node, 'update')
-				if (updateChild?.attrs?.jid) {
-					ev.emit('contacts.update', [{ id: (0, WABinary_1.jidNormalizedUser)(updateChild.attrs.jid) }])
-				} else {
-					logger.debug({ node }, 'contacts list changed (hash/sync signal), no per-contact jid to update')
 				}
 				break
-			}
 			case 'business':
+				// SMB privacy / data-sharing settings sync push
+				// (WhatsApp Web: WASmaxInBizSettingsSyncPrivacySettingRequest)
 				if (child?.tag === 'privacy') {
-					
 					ev.emit('business.privacy-settings-sync', {
 						jid: from,
 						categories: (0, WABinary_1.getBinaryNodeChildren)(child, 'category').map(c => ({
@@ -1494,37 +1215,11 @@ const makeMessagesRecvSocket = config => {
 						})),
 						attrs: child.attrs
 					})
-				} else if (child?.tag === 'profile') {
-					
-					ev.emit('contacts.update', [
-						{
-							id: (0, WABinary_1.jidNormalizedUser)(child.attrs.jid || from),
-							businessProfileTag: child.attrs.tag
-						}
-					])
-				} else if (child?.tag === 'verified_name') {
-					
-					ev.emit('contacts.update', [
-						{
-							id: (0, WABinary_1.jidNormalizedUser)(child.attrs.jid || from),
-							verifiedName: {
-								verifiedLevel: child.attrs.verified_level,
-								serial: child.attrs.serial,
-								version: child.attrs.v
-							}
-						}
-					])
-				} else if (child?.tag === 'remove') {
-					
-					
-					if (child.attrs.jid) {
-						ev.emit('contacts.update', [{ id: (0, WABinary_1.jidNormalizedUser)(child.attrs.jid), isBusiness: false }])
-					}
 				}
 				break
 			case 'hosted':
-				
-				
+				// Coexistence (WhatsApp <-> Messenger/Instagram) onboarding/offboarding push
+				// (WhatsApp Web: WASmaxInCoexistenceOnboarding/OffboardingNotification)
 				if (child?.tag === 'onboarding_status') {
 					ev.emit('coexistence.update', {
 						jid: from,
@@ -1542,28 +1237,18 @@ const makeMessagesRecvSocket = config => {
 				break
 			case 'link_code_companion_reg':
 				const linkCodeCompanionReg = (0, WABinary_1.getBinaryNodeChild)(node, 'link_code_companion_reg')
-				const refBuffer = (0, WABinary_1.getBinaryNodeChildBuffer)(linkCodeCompanionReg, 'link_code_pairing_ref')
-				const primaryIdentityPublicKeyBuffer = (0, WABinary_1.getBinaryNodeChildBuffer)(
-					linkCodeCompanionReg,
-					'primary_identity_pub'
+				const ref = toRequiredBuffer(
+					(0, WABinary_1.getBinaryNodeChildBuffer)(linkCodeCompanionReg, 'link_code_pairing_ref')
 				)
-				const primaryEphemeralPublicKeyWrappedBuffer = (0, WABinary_1.getBinaryNodeChildBuffer)(
-					linkCodeCompanionReg,
-					'link_code_pairing_wrapped_primary_ephemeral_pub'
+				const primaryIdentityPublicKey = toRequiredBuffer(
+					(0, WABinary_1.getBinaryNodeChildBuffer)(linkCodeCompanionReg, 'primary_identity_pub')
+				)
+				const primaryEphemeralPublicKeyWrapped = toRequiredBuffer(
+					(0, WABinary_1.getBinaryNodeChildBuffer)(
+						linkCodeCompanionReg,
+						'link_code_pairing_wrapped_primary_ephemeral_pub'
+					)
 				)
-				if (
-					refBuffer === undefined ||
-					primaryIdentityPublicKeyBuffer === undefined ||
-					primaryEphemeralPublicKeyWrappedBuffer === undefined
-				) {
-					
-					
-					logger.debug({ id: node.attrs.id, type: node.attrs.type }, 'skipping empty link code companion registration')
-					break
-				}
-				const ref = toRequiredBuffer(refBuffer)
-				const primaryIdentityPublicKey = toRequiredBuffer(primaryIdentityPublicKeyBuffer)
-				const primaryEphemeralPublicKeyWrapped = toRequiredBuffer(primaryEphemeralPublicKeyWrappedBuffer)
 				const codePairingPublicKey = await decipherLinkPublicKey(primaryEphemeralPublicKeyWrapped)
 				const companionSharedKey = Utils_1.Curve.sharedKey(
 					authState.creds.pairingEphemeralKeyPair.private,
@@ -1638,7 +1323,7 @@ const makeMessagesRecvSocket = config => {
 				await handlePrivacyTokenNotification(node)
 				break
 			case 'security':
-				
+				// Security notifications (compromised session, location change alerts)
 				const securityType = child?.tag || node.attrs.type
 				const securityData = {
 					type: securityType,
@@ -1650,7 +1335,7 @@ const makeMessagesRecvSocket = config => {
 				ev.emit('security.alert', securityData)
 				break
 			case 'identity':
-				
+				// Identity change notifications — peer changed their identity key
 				const identityJid = node.attrs.from
 				const identityNewKey = child?.content ? Buffer.from(child.content) : undefined
 				ev.emit('identity.update', {
@@ -1660,7 +1345,7 @@ const makeMessagesRecvSocket = config => {
 				})
 				break
 			case 'server':
-				
+				// Server-issued notifications (config changes, client config refresh)
 				const serverTag = child?.tag
 				if (serverTag === 'config') {
 					const configData = {}
@@ -1669,7 +1354,7 @@ const makeMessagesRecvSocket = config => {
 					}
 					ev.emit('server.config', configData)
 				} else if (serverTag === 'app_state_key') {
-					
+					// Server pushed a new app-state key — trigger resync
 					logger.info('server pushed app state key update')
 					await resyncAppState(['critical_block', 'regular_high', 'regular_low'], false)
 				} else {
@@ -1677,7 +1362,7 @@ const makeMessagesRecvSocket = config => {
 				}
 				break
 			case 'status':
-				
+				// Contact status (about) change notification
 				const statusOwner = node.attrs.from
 				const statusText = child?.content ? child.content.toString() : undefined
 				if (statusOwner && statusText !== undefined) {
@@ -1690,7 +1375,7 @@ const makeMessagesRecvSocket = config => {
 				}
 				break
 			case 'usync':
-				
+				// USync result push from server
 				const usyncResults = (0, WABinary_1.getBinaryNodeChildren)(child || node, 'user')
 				if (usyncResults.length) {
 					const updates = usyncResults
@@ -1707,12 +1392,12 @@ const makeMessagesRecvSocket = config => {
 				}
 				break
 			case 'interop':
-				
-				
-				
-				
-				
-				
+				// Interop-related server notifications — covers:
+				//   stella_interop_enabled / stella_ios_enabled feature flags
+				//   ig_professional / ig_handle / followers (Instagram account data)
+				//   fbid:thread / fbid:devices (Meta thread/device references)
+				//   peer_device_presence updates
+				//   group membership changes in interop groups
 				handleInteropNotification(node, child)
 				break
 		}
@@ -1720,7 +1405,10 @@ const makeMessagesRecvSocket = config => {
 			return result
 		}
 	}
-	
+	/**
+	 * In-memory cache of storage JIDs with stored tctokens, seeded from the persisted index.
+	 * Used to coalesce writes during a session; pruning always re-reads the persisted index.
+	 */
 	const tcTokenKnownJids = new Set()
 	const tcTokenIndexLoaded = (async () => {
 		try {
@@ -1761,7 +1449,7 @@ const makeMessagesRecvSocket = config => {
 		const tokensNode = (0, WABinary_1.getBinaryNodeChild)(node, 'tokens')
 		if (!tokensNode) return
 		const from = (0, WABinary_1.jidNormalizedUser)(node.attrs.from)
-		
+		// WA Web uses: senderLid ?? toLid(from) for the storage key
 		const senderLid =
 			node.attrs.sender_lid && (0, WABinary_1.isLidUser)((0, WABinary_1.jidNormalizedUser)(node.attrs.sender_lid))
 				? (0, WABinary_1.jidNormalizedUser)(node.attrs.sender_lid)
@@ -1800,30 +1488,31 @@ const makeMessagesRecvSocket = config => {
 		const newValue = ((await msgRetryCache.get(key)) || 0) + 1
 		await msgRetryCache.set(key, newValue)
 	}
-	const sendMessagesAgain = async (key, ids, retryNode) => {
+	const sendMessagesAgain = async (key, ids, retryNode, receiptNode) => {
 		const remoteJid = key.remoteJid
 		const participant = key.participant || remoteJid
 		const retryCount = +retryNode.attrs.count || 1
-		
+		const msgId = ids[0]
+		// Try to get messages from cache first, then fallback to getMessage
 		const msgs = []
 		for (const id of ids) {
 			let msg
-			
+			// Try to get from retry cache first if enabled
 			if (messageRetryManager) {
 				const cachedMsg = messageRetryManager.getRecentMessage(remoteJid, id)
 				if (cachedMsg) {
 					msg = cachedMsg.message
 					logger.debug({ jid: remoteJid, id }, 'found message in retry cache')
-					
+					// Mark retry as successful since we found the message
 					messageRetryManager.markRetrySuccess(id)
 				}
 			}
-			
+			// Fallback to getMessage if not found in cache
 			if (!msg) {
 				msg = await getMessage({ ...key, id })
 				if (msg) {
 					logger.debug({ jid: remoteJid, id }, 'found message via getMessage')
-					
+					// Also mark as successful if found via getMessage
 					if (messageRetryManager) {
 						messageRetryManager.markRetrySuccess(id)
 					}
@@ -1831,16 +1520,57 @@ const makeMessagesRecvSocket = config => {
 			}
 			msgs.push(msg)
 		}
-		
-		
-		
+		// if it's the primary jid sending the request
+		// just re-send the message to everyone
+		// prevents the first message decryption failure
 		const sendToAll = !(0, WABinary_1.jidDecode)(participant)?.device
-		
+		const sessionId = signalRepository.jidToSignalProtocolAddress(participant)
+		let injectedFromBundle = false
+		if (typeof signalRepository.injectE2ESession === 'function' && typeof Utils_1.extractE2ESessionFromRetryReceipt === 'function') {
+			const bundle = Utils_1.extractE2ESessionFromRetryReceipt(receiptNode)
+			if (bundle) {
+				try {
+					await signalRepository.injectE2ESession({ jid: participant, session: bundle })
+					injectedFromBundle = true
+					logger.debug({ participant, retryCount }, 'injected session from retry receipt key bundle')
+				} catch (error) {
+					logger.warn({ error, participant }, 'failed to inject session from retry receipt')
+				}
+			}
+		}
+		if (!injectedFromBundle && signalRepository.getSessionInfo) {
+			const receivedRegId = (0, WABinary_1.getBinaryNodeChildUInt)(receiptNode, 'registration', 4)
+			if (typeof receivedRegId === 'number' && Number.isInteger(receivedRegId)) {
+				const info = await signalRepository.getSessionInfo(participant)
+				if (info && info.registrationId !== 0 && info.registrationId !== receivedRegId) {
+					logger.info(
+						{ participant, stored: info.registrationId, received: receivedRegId },
+						'reg id mismatch on retry without bundle, deleting session'
+					)
+					await authState.keys.set({ session: { [sessionId]: null } })
+				}
+			}
+		}
+		const BASE_KEY_CHECK_RETRY = 2
+		if (msgId && messageRetryManager && signalRepository.getSessionInfo) {
+			const info = await signalRepository.getSessionInfo(participant)
+			if (info) {
+				if (retryCount === BASE_KEY_CHECK_RETRY) {
+					messageRetryManager.saveBaseKey(sessionId, msgId, info.baseKey)
+				} else if (retryCount > BASE_KEY_CHECK_RETRY) {
+					if (messageRetryManager.hasSameBaseKey(sessionId, msgId, info.baseKey)) {
+						logger.warn({ participant, retryCount }, 'base key collision on retry, forcing fresh session')
+						await authState.keys.set({ session: { [sessionId]: null } })
+					}
+					messageRetryManager.deleteBaseKey(sessionId, msgId)
+				}
+			}
+		}
+		// Check if we should recreate session for this retry
 		let shouldRecreateSession = false
 		let recreateReason = ''
-		if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1) {
+		if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1 && !injectedFromBundle) {
 			try {
-				const sessionId = signalRepository.jidToSignalProtocolAddress(participant)
 				const hasSession = await signalRepository.validateSession(participant)
 				const result = messageRetryManager.shouldRecreateSession(participant, hasSession.exists)
 				shouldRecreateSession = result.recreate
@@ -1853,7 +1583,9 @@ const makeMessagesRecvSocket = config => {
 				logger.warn({ error, participant }, 'failed to check session recreation for outgoing retry')
 			}
 		}
-		await assertSessions([participant], true)
+		if (!injectedFromBundle) {
+			await assertSessions([participant], true)
+		}
 		if ((0, WABinary_1.isJidGroup)(remoteJid)) {
 			await authState.keys.set({ 'sender-key-memory': { [remoteJid]: null } })
 		}
@@ -1902,59 +1634,14 @@ const makeMessagesRecvSocket = config => {
 			const items = (0, WABinary_1.getBinaryNodeChildren)(content[0], 'item')
 			ids.push(...items.map(i => i.attrs.id))
 		}
-		
-		
-		if (attrs.type === 'media-retry') {
-			const mediaRetryNode =
-				(0, WABinary_1.getBinaryNodeChild)(node, 'media-retry') ||
-				(0, WABinary_1.getBinaryNodeChild)(node, 'media_retry')
-			ev.emit('messages.media-retry', {
-				ids,
-				from: attrs.from,
-				participant: attrs.participant,
-				t: attrs.t,
-				retryAttrs: mediaRetryNode?.attrs
-			})
-			await sendMessageAck(node).catch(ackErr => logger.error({ ackErr }, 'failed to ack media-retry receipt'))
-			return
-		}
-		
-		
-		if (attrs.type === 'server-error') {
-			const errorNode = (0, WABinary_1.getBinaryNodeChild)(node, 'error')
-			ev.emit('messages.server-error', {
-				ids,
-				from: attrs.from,
-				participant: attrs.participant,
-				t: attrs.t,
-				errorCode: errorNode?.attrs?.code || attrs.error_code,
-				errorText: errorNode?.attrs?.text || errorNode?.content?.toString?.()
-			})
-			await sendMessageAck(node).catch(ackErr => logger.error({ ackErr }, 'failed to ack server-error receipt'))
-			return
-		}
-		
-		
-		
-		if (attrs.receipt_agg) {
-			ev.emit('receipt.batched', {
-				ids,
-				from: attrs.from,
-				participant: attrs.participant,
-				type: attrs.type,
-				t: attrs.t,
-				receiptAgg: attrs.receipt_agg
-			})
-			
-		}
 		try {
 			await Promise.all([
 				receiptMutex.mutex(async () => {
 					const status = (0, Utils_1.getStatusFromReceiptType)(attrs.type)
 					if (
 						typeof status !== 'undefined' &&
-						
-						
+						// basically, we only want to know when a message from us has been delivered to/read by the other person
+						// or another device of ours has read some messages
 						(status >= index_js_1.proto.WebMessageInfo.Status.SERVER_ACK || !isNodeFromMe)
 					) {
 						if ((0, WABinary_1.isJidGroup)(remoteJid) || (0, WABinary_1.isJidStatusBroadcast)(remoteJid)) {
@@ -1983,7 +1670,7 @@ const makeMessagesRecvSocket = config => {
 						}
 					}
 					if (attrs.type === 'retry') {
-						
+						// correctly set who is asking for the retry
 						key.participant = key.participant || attrs.from
 						const retryNode = (0, WABinary_1.getBinaryNodeChild)(node, 'retry')
 						if (ids[0] && key.participant && (await willSendMessageAgain(ids[0], key.participant))) {
@@ -1991,7 +1678,7 @@ const makeMessagesRecvSocket = config => {
 								try {
 									await updateSendMessageAgainCount(ids[0], key.participant)
 									logger.debug({ attrs, key }, 'recv retry request')
-									await sendMessagesAgain(key, ids, retryNode)
+									await sendMessagesAgain(key, ids, retryNode, node)
 								} catch (error) {
 									logger.error(
 										{ key, ids, trace: error instanceof Error ? error.stack : 'Unknown error' },
@@ -2090,11 +1777,11 @@ const makeMessagesRecvSocket = config => {
 		const groupJid = node.attrs.from
 		const communityJid = linkedParentMap[groupJid]
 		const encNode = (0, WABinary_1.getBinaryNodeChild)(node, 'enc')
-		
+		// TODO: temporary fix for crashes and issues resulting of failed msmsg decryption
 		if (encNode?.attrs.type === 'msmsg') {
-			
-			
-			
+			// await sendMessageAck(node, Utils_1.NACK_REASONS.MissingMessageSecret)
+			// return
+			// Pre-populate botMessageSecrets from store so msmsg can be decrypted after restart
 			if (getMessage) {
 				const metaNode = (0, WABinary_1.getBinaryNodeChild)(node, 'meta')
 				const targetId = metaNode?.attrs?.target_id
@@ -2132,7 +1819,7 @@ const makeMessagesRecvSocket = config => {
 				)
 			}
 			const alt = msg.key.participantAlt || msg.key.remoteJidAlt
-			
+			// store new mappings we didn't have before
 			if (!!alt) {
 				const altServer = (0, WABinary_1.jidDecode)(alt)?.server
 				const primaryJid = msg.key.participant || msg.key.remoteJid
@@ -2145,32 +1832,6 @@ const makeMessagesRecvSocket = config => {
 					await signalRepository.lidMapping.storeLIDPNMappings([{ lid: primaryJid, pn: alt }])
 					await signalRepository.migrateSession(alt, primaryJid)
 				}
-			} else if (msg.key.addressingMode === 'lid') {
-				
-				
-				
-				
-				const primaryJid = msg.key.participant || msg.key.remoteJid
-				if ((0, WABinary_1.isLidUser)(primaryJid)) {
-					try {
-						const pn = await signalRepository.lidMapping.getPNForLID(primaryJid)
-						
-						
-						
-						const pnJid = pn ? (0, WABinary_1.jidNormalizedUser)(pn) : ''
-						if (pnJid) {
-							if ((0, WABinary_1.isJidGroup)(msg.key.remoteJid)) {
-								msg.key.participantAlt = pnJid
-							} else {
-								msg.key.remoteJidAlt = pnJid
-							}
-							logger.debug({ lid: primaryJid, pn: pnJid }, 'recovered alt JID from LID mapping store')
-						}
-					} catch (err) {
-						
-						logger.warn({ err, lid: primaryJid }, 'failed to recover alt JID from LID mapping store')
-					}
-				}
 			}
 			await messageMutex.mutex(async () => {
 				await decrypt()
@@ -2191,7 +1852,7 @@ const makeMessagesRecvSocket = config => {
 				if (msg.key?.remoteJid && msg.key?.id && msg.message && messageRetryManager) {
 					messageRetryManager.addRecentMessage(msg.key.remoteJid, msg.key.id, msg.message)
 				}
-				
+				// message failed to decrypt
 				if (msg.messageStubType === index_js_1.proto.WebMessageInfo.StubType.CIPHERTEXT && msg.category !== 'peer') {
 					if (msg?.messageStubParameters?.[0] === Utils_1.MISSING_KEYS_ERROR_TEXT) {
 						if (isInteropNode) logger.warn({ id: msg.key.id }, '[interop] decrypt failed: MISSING_KEYS')
@@ -2199,8 +1860,8 @@ const makeMessagesRecvSocket = config => {
 						return sendMessageAck(node, Utils_1.NACK_REASONS.ParsingError)
 					}
 					if (msg.messageStubParameters?.[0] === Utils_1.NO_MESSAGE_FOUND_ERROR_TEXT) {
-						
-						
+						// Message arrived without encryption (e.g. CTWA ads messages).
+						// Check if this is eligible for placeholder resend (matching WA Web filters).
 						const unavailableNode = (0, WABinary_1.getBinaryNodeChild)(node, 'unavailable')
 						const unavailableType = unavailableNode?.attrs?.type
 						if (
@@ -2221,18 +1882,18 @@ const makeMessagesRecvSocket = config => {
 							acked = true
 							return sendMessageAck(node)
 						}
-						
-						
-						
-						
+						// Request the real content from the phone via placeholder resend PDO.
+						// Upsert the CIPHERTEXT stub as a placeholder (like WA Web's processPlaceholderMsg),
+						// and store the requestId in stubParameters[1] so users can correlate
+						// with the incoming PDO response event.
 						const cleanKey = {
 							remoteJid: msg.key.remoteJid,
 							fromMe: msg.key.fromMe,
 							id: msg.key.id,
 							participant: msg.key.participant
 						}
-						
-						
+						// Cache the original message metadata so the PDO response handler
+						// can preserve key fields (LID details etc.) that the phone may omit
 						const msgData = {
 							key: msg.key,
 							messageTimestamp: msg.messageTimestamp,
@@ -2257,9 +1918,9 @@ const makeMessagesRecvSocket = config => {
 							})
 						acked = true
 						await sendMessageAck(node)
-						
+						// Don't return — fall through to upsertMessage so the stub is emitted
 					} else {
-						
+						// Skip retry for expired status messages (>24h old)
 						if ((0, WABinary_1.isJidStatusBroadcast)(msg.key.remoteJid)) {
 							const messageAge = (0, Utils_1.unixTimestampSeconds)() - (0, Utils_1.toNumber)(msg.messageTimestamp)
 							if (messageAge > Defaults_1.STATUS_EXPIRY_SECONDS) {
@@ -2274,14 +1935,14 @@ const makeMessagesRecvSocket = config => {
 						const errorMessage = msg?.messageStubParameters?.[0] || ''
 						const isPreKeyError = errorMessage.includes('PreKey')
 						logger.debug(`[handleMessage] Attempting retry request for failed decryption`)
-						
+						// Handle both pre-key and normal retries in single mutex
 						await retryMutex.mutex(async () => {
 							try {
 								if (!ws.isOpen) {
 									logger.debug({ node }, 'Connection closed, skipping retry')
 									return
 								}
-								
+								// Handle pre-key errors with upload and delay
 								if (isPreKeyError) {
 									logger.info({ error: errorMessage }, 'PreKey error detected, uploading and retrying')
 									try {
@@ -2300,7 +1961,7 @@ const makeMessagesRecvSocket = config => {
 								}
 							} catch (err) {
 								logger.error({ err, isPreKeyError }, 'Failed to handle retry, attempting basic retry')
-								
+								// Still attempt retry even if pre-key upload failed
 								try {
 									const encNode = (0, WABinary_1.getBinaryNodeChild)(node, 'enc')
 									await sendRetryRequest(node, !encNode)
@@ -2318,34 +1979,34 @@ const makeMessagesRecvSocket = config => {
 					}
 					const isNewsletter = (0, WABinary_1.isJidNewsletter)(msg.key.remoteJid)
 					if (!isNewsletter) {
-						
+						// no type in the receipt => message delivered
 						let type = undefined
 						let participant = msg.key.participant
 						if (communityJid) {
 							msg.communityJid = communityJid
 						}
 						if (category === 'peer') {
-							
+							// special peer message
 							type = 'peer_msg'
 						} else if (msg.key.fromMe) {
-							
+							// message was sent by us from a different device
 							type = 'sender'
-							
+							// need to specially handle this case
 							if ((0, WABinary_1.isLidUser)(msg.key.remoteJid) || (0, WABinary_1.isLidUser)(msg.key.remoteJidAlt)) {
-								participant = author 
+								participant = author // TODO: investigate sending receipts to LIDs and not PNs
 							}
 						} else if (!sendActiveReceipts) {
 							type = 'inactive'
 						}
 						acked = true
-						
+						// Pass sts from the original stanza for interop contacts (BirdyChat/Haiket)
 						const interopSts = (0, WABinary_1.isInteropUser)(msg.key.remoteJid) ? node.attrs.sts : undefined
 						await sendReceipt(msg.key.remoteJid, participant, [msg.key.id], type, interopSts)
-						
+						// send ack for history message
 						const isAnyHistoryMsg = (0, Utils_1.getHistoryMsg)(msg.message)
 						if (isAnyHistoryMsg) {
 							const jid = (0, WABinary_1.jidNormalizedUser)(msg.key.remoteJid)
-							await sendReceipt(jid, undefined, [msg.key.id], 'hist_sync') 
+							await sendReceipt(jid, undefined, [msg.key.id], 'hist_sync') // TODO: investigate
 						}
 					} else {
 						acked = true
@@ -2407,19 +2068,6 @@ const makeMessagesRecvSocket = config => {
 			}
 		}
 	}
-	
-	
-	
-	const parseGroupCallRoster = groupInfoNode =>
-		(0, WABinary_1.getBinaryNodeChildren)(groupInfoNode, 'user').map(userNode => ({
-			jid: userNode.attrs.jid,
-			state: userNode.attrs.state,
-			userPn: userNode.attrs.user_pn,
-			devices: (0, WABinary_1.getBinaryNodeChildren)(userNode, 'device').map(d => ({
-				jid: d.attrs.jid,
-				platform: d.attrs.platform
-			}))
-		}))
 	const handleCall = async node => {
 		try {
 			const { attrs } = node
@@ -2447,88 +2095,20 @@ const makeMessagesRecvSocket = config => {
 				}
 			}
 			if (status === 'offer') {
-				const videoNode = (0, WABinary_1.getBinaryNodeChild)(infoChild, 'video')
-				const audioNodes = (0, WABinary_1.getBinaryNodeChildren)(infoChild, 'audio')
-				const silenceNode = (0, WABinary_1.getBinaryNodeChild)(infoChild, 'silence')
-				call.isVideo = !!videoNode
+				call.isVideo = !!(0, WABinary_1.getBinaryNodeChild)(infoChild, 'video')
 				call.isGroup = infoChild.attrs.type === 'group' || !!infoChild.attrs['group-jid']
 				call.groupJid = infoChild.attrs['group-jid']
-				
-				call.isLightweight = infoChild.attrs.lightweight === '1'
-				if (silenceNode?.attrs?.reason) {
-					call.silenceReason = silenceNode.attrs.reason
-				}
-				
-				
-				if (audioNodes.length) {
-					call.audioCodecs = audioNodes.map(n => ({ enc: n.attrs.enc, rate: n.attrs.rate ? +n.attrs.rate : undefined }))
-					call.audioCodec = audioNodes[0].attrs.enc
-				}
-				if (videoNode?.attrs?.dec) {
-					call.videoCodec = videoNode.attrs.dec
-				}
-				
-				const encNode = (0, WABinary_1.getBinaryNodeChild)(infoChild, 'enc')
-				if (encNode?.content) {
-					try {
-						const encType = encNode.attrs.type || 'msg'
-						const ciphertext = Buffer.isBuffer(encNode.content) ? encNode.content : Buffer.from(encNode.content)
-						const decrypted = await signalRepository.decryptMessage({ jid: attrs.from, type: encType, ciphertext })
-						const unpadded = (0, Utils_1.unpadRandomMax16)(decrypted)
-						const callMsg = index_js_1.proto.Message.decode(unpadded)
-						if (callMsg?.call?.callKey?.length) {
-							call.callKey = Buffer.from(callMsg.call.callKey)
-						}
-					} catch (e) {
-						logger.debug({ e }, 'failed to decrypt call enc')
-					}
-				}
 				await callOfferCache.set(call.id, call)
-			} else if (status === 'waiting_room_request') {
-				call.peerJid = infoChild.attrs.from || infoChild.attrs['peer-jid'] || infoChild.attrs['user-jid']
 			}
 			const existingCall = await callOfferCache.get(call.id)
-			
+			// use existing call info to populate this event
 			if (existingCall) {
 				call.isVideo = existingCall.isVideo
 				call.isGroup = existingCall.isGroup
 				call.callerPn = call.callerPn || existingCall.callerPn
 			}
-			
-			if (status === 'peer_state') {
-				const stateChild = (0, WABinary_1.getBinaryNodeChild)(infoChild, 'peer_state')
-				call.state = stateChild?.attrs?.state || infoChild.attrs?.state
-			} else if (status === 'group_info') {
-				call.payload = infoChild.attrs
-				call.participants = parseGroupCallRoster(infoChild)
-			} else if (status === 'video_state') {
-				const vsChild = (0, WABinary_1.getBinaryNodeChild)(infoChild, 'video_state')
-				const enabledRaw = vsChild?.attrs?.enabled ?? infoChild.attrs?.enabled
-				call.enabled = enabledRaw === 'true' || enabledRaw === '1'
-			} else if (status === 'enc_rekey') {
-				const rekeyChild =
-					(0, WABinary_1.getBinaryNodeChild)(infoChild, 'enc-rekey') ||
-					(0, WABinary_1.getBinaryNodeChild)(infoChild, 'enc_rekey')
-				if (rekeyChild?.content && Buffer.isBuffer(rekeyChild.content)) {
-					try {
-						call.rekeyPayload = (0, Utils_1.decodeE2eRekeyPayload)(rekeyChild.content)
-					} catch (e) {
-						logger.debug({ e }, 'failed to decode enc-rekey payload in handleCall')
-					}
-				}
-			}
-			
-			if (
-				status === 'reject' ||
-				status === 'accept' ||
-				status === 'timeout' ||
-				status === 'terminate' ||
-				status === 'reject_do_not_disturb' ||
-				status === 'mic_permission_denied' ||
-				status === 'camera_permission_denied' ||
-				status === 'remote_busy' ||
-				status === 'remote_offline'
-			) {
+			// delete data once call has ended
+			if (status === 'reject' || status === 'accept' || status === 'timeout' || status === 'terminate') {
 				await callOfferCache.del(call.id)
 			}
 			await normalizeCallEventJids(call, infoChild)
@@ -2539,32 +2119,15 @@ const makeMessagesRecvSocket = config => {
 			await sendMessageAck(node).catch(ackErr => logger.error({ ackErr }, 'failed to ack call'))
 		}
 	}
-	
-	
-	
-	
-	const CALL_STATE_TAGS = new Set([
-		'offer',
-		'offer_notice',
-		'terminate',
-		'accept',
-		'reject',
-		'preaccept',
-		'accept_ack',
-		'enc-rekey',
-		'enc_rekey',
-		'peer_state',
-		'group_info',
-		'video_state',
-		'video_state_ack',
-		'flow_control',
-		'mute_v2',
-		'waiting_room_request'
-	])
+	// Some accounts receive call signalling as TOP-LEVEL stanzas (<offer>, <terminate>,
+	// <mute_v2>, <transport>, … each with a call-id) instead of wrapped in <call>.
+	// This additively handles those: emit a 'call' event for state stanzas and ack ALL
+	// of them (otherwise WhatsApp keeps redelivering). The <call> path above is untouched.
+	const CALL_STATE_TAGS = new Set(['offer', 'offer_notice', 'terminate', 'accept', 'reject', 'preaccept'])
 	const handleStandaloneCallStanza = async node => {
 		try {
 			if (!CALL_STATE_TAGS.has(node.tag)) {
-				return 
+				return // media/relay signalling (transport, video, duration, mute_v2, lobby, …): ack only
 			}
 			const { attrs } = node
 			const status = (0, Utils_1.getCallStatusFromNode)(node)
@@ -2580,24 +2143,9 @@ const makeMessagesRecvSocket = config => {
 				status
 			}
 			if (status === 'offer') {
-				const videoNode = (0, WABinary_1.getBinaryNodeChild)(node, 'video')
-				const audioNodes = (0, WABinary_1.getBinaryNodeChildren)(node, 'audio')
-				const silenceNode = (0, WABinary_1.getBinaryNodeChild)(node, 'silence')
-				call.isVideo = !!videoNode
+				call.isVideo = !!(0, WABinary_1.getBinaryNodeChild)(node, 'video')
 				call.isGroup = attrs.type === 'group' || !!attrs['group-jid']
 				call.groupJid = attrs['group-jid']
-				call.isLightweight = attrs.lightweight === '1'
-				if (silenceNode?.attrs?.reason) {
-					call.silenceReason = silenceNode.attrs.reason
-				}
-				
-				if (audioNodes.length) {
-					call.audioCodecs = audioNodes.map(n => ({ enc: n.attrs.enc, rate: n.attrs.rate ? +n.attrs.rate : undefined }))
-					call.audioCodec = audioNodes[0].attrs.enc
-				}
-				if (videoNode?.attrs?.dec) {
-					call.videoCodec = videoNode.attrs.dec
-				}
 				if (callId) {
 					await callOfferCache.set(callId, call)
 				}
@@ -2608,45 +2156,7 @@ const makeMessagesRecvSocket = config => {
 				call.isGroup = existingCall.isGroup
 				call.callerPn = call.callerPn || existingCall.callerPn
 			}
-			
-			if (status === 'peer_state') {
-				const stateChild = (0, WABinary_1.getBinaryNodeChild)(node, 'peer_state')
-				call.state = stateChild?.attrs?.state || attrs?.state
-			} else if (status === 'group_info') {
-				call.payload = attrs
-				call.participants = parseGroupCallRoster(node)
-			} else if (status === 'video_state') {
-				const vsChild = (0, WABinary_1.getBinaryNodeChild)(node, 'video_state')
-				const enabledRaw = vsChild?.attrs?.enabled ?? attrs?.enabled
-				call.enabled = enabledRaw === 'true' || enabledRaw === '1'
-			} else if (status === 'enc_rekey') {
-				const rekeyChild =
-					(0, WABinary_1.getBinaryNodeChild)(node, 'enc-rekey') || (0, WABinary_1.getBinaryNodeChild)(node, 'enc_rekey')
-				if (rekeyChild?.content && Buffer.isBuffer(rekeyChild.content)) {
-					try {
-						call.rekeyPayload = (0, Utils_1.decodeE2eRekeyPayload)(rekeyChild.content)
-					} catch (e) {
-						logger.debug({ e }, 'failed to decode enc-rekey payload in standalone call stanza')
-					}
-				}
-			} else if (status === 'mute') {
-				
-				
-				
-				call.muted = node.attrs['mute-state'] === '1'
-			}
-			if (
-				callId &&
-				(status === 'reject' ||
-					status === 'accept' ||
-					status === 'timeout' ||
-					status === 'terminate' ||
-					status === 'reject_do_not_disturb' ||
-					status === 'mic_permission_denied' ||
-					status === 'camera_permission_denied' ||
-					status === 'remote_busy' ||
-					status === 'remote_offline')
-			) {
+			if (callId && (status === 'reject' || status === 'accept' || status === 'timeout' || status === 'terminate')) {
 				await callOfferCache.del(callId)
 			}
 			await normalizeCallEventJids(call, node)
@@ -2659,26 +2169,26 @@ const makeMessagesRecvSocket = config => {
 	}
 	const handleBadAck = async ({ attrs }) => {
 		const key = { remoteJid: attrs.from, fromMe: true, id: attrs.id }
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
+		// WARNING: REFRAIN FROM ENABLING THIS FOR NOW. IT WILL CAUSE A LOOP
+		// // current hypothesis is that if pash is sent in the ack
+		// // it means -- the message hasn't reached all devices yet
+		// // we'll retry sending the message here
+		// if(attrs.phash) {
+		// 	logger.info({ attrs }, 'received phash in ack, resending message...')
+		// 	const msg = await getMessage(key)
+		// 	if(msg) {
+		// 		await relayMessage(key.remoteJid!, msg, { messageId: key.id!, useUserDevicesCache: false })
+		// 	} else {
+		// 		logger.warn({ attrs }, 'could not send message again, as it was not found')
+		// 	}
+		// }
+		// error in acknowledgement,
+		// device could not display the message
 		if (attrs.error) {
 			if (attrs.error === Utils_1.SERVER_ERROR_CODES.MissingTcToken) {
-				
-				
-				
+				// 463 = account restricted + no tctoken for this contact.
+				// WA Web prevents this client-side (disables compose bar).
+				// No retry — retrying worsens the restriction by counting as another "reach out" to an unknown contact.
 				logger.warn(
 					{ msgId: attrs.id, from: attrs.from },
 					'error 463: account restricted or missing tctoken for contact'
@@ -2700,54 +2210,23 @@ const makeMessagesRecvSocket = config => {
 					}
 				}
 			])
-			
-			
-			
-			
-			
-			
-			
-			
-			
-			
-			
-			
-			
+			// resend the message with device_fanout=false, use at your own risk
+			// if (attrs.error === '475') {
+			// 	const msg = await getMessage(key)
+			// 	if (msg) {
+			// 		await relayMessage(key.remoteJid!, msg, {
+			// 			messageId: key.id!,
+			// 			useUserDevicesCache: false,
+			// 			additionalAttributes: {
+			// 				device_fanout: 'false'
+			// 			}
+			// 		})
+			// 	}
+			// }
 		}
 	}
-	const handleChatstate = async node => {
-		const { from, state } = node.attrs
-		if (!from) return
-		const isTyping = state === 'typing'
-		ev.emit('presence.update', [
-			{
-				id: from,
-				presences: {
-					[from]: isTyping ? 'composing' : 'paused'
-				}
-			}
-		])
-	}
-	const handlePresence = async node => {
-		const { from, type } = node.attrs
-		if (!from || !type) return
-		const presenceMap = {
-			available: 'available',
-			unavailable: 'unavailable'
-		}
-		const presence = presenceMap[type] || type
-		ev.emit('presence.update', [
-			{
-				id: from,
-				presences: {
-					[from]: presence
-				},
-				lastSeen: node.attrs.t ? Number(node.attrs.t) * 1000 : undefined
-			}
-		])
-	}
-	
-	
+	/// processes a node with the given function
+	/// and adds the task to the existing buffer if we're buffering events
 	const processNodeWithBuffer = async (node, identifier, exec) => {
 		ev.buffer()
 		await execTask()
@@ -2786,7 +2265,7 @@ const makeMessagesRecvSocket = config => {
 	const setNodeLoggerListener = () => {
 		return latestNodeInMemory
 	}
-	
+	// recv a message
 	ws.on('CB:message', async node => {
 		nodelogger(node)
 		await processNode('message', node, 'processing message', handleMessage)
@@ -2795,35 +2274,10 @@ const makeMessagesRecvSocket = config => {
 		nodelogger(node)
 		await processNode('call', node, 'handling call', handleCall)
 	})
-	
+	// additive: top-level call-signalling stanzas (some accounts send these instead of <call>)
 	for (const callTag of [
-		'offer',
-		'offer_notice',
-		'terminate',
-		'accept',
-		'reject',
-		'preaccept',
-		'accept_ack',
-		'enc-rekey',
-		'enc_rekey',
-		'peer_state',
-		'group_info',
-		'video_state',
-		'video_state_ack',
-		'flow_control',
-		'transport',
-		'video',
-		'duration',
-		'mute_v2',
-		'lobby',
-		'heartbeat',
-		'relaylatency',
-		'link_query',
-		'waiting_room_request',
-		
-		
-		
-		'group_update'
+		'offer', 'offer_notice', 'terminate', 'accept', 'reject', 'preaccept',
+		'transport', 'video', 'duration', 'mute_v2', 'lobby', 'heartbeat', 'relaylatency', 'link_query'
 	]) {
 		ws.on('CB:' + callTag, node => {
 			nodelogger(node)
@@ -2838,18 +2292,6 @@ const makeMessagesRecvSocket = config => {
 		nodelogger(node)
 		await processNode('notification', node, 'handling notification', handleNotification)
 	})
-	ws.on('CB:status', async node => {
-		nodelogger(node)
-		await handleNewsletterStatus(node).catch(error => onUnexpectedError(error, 'handling newsletter status'))
-	})
-	ws.on('CB:chatstate', async node => {
-		nodelogger(node)
-		await handleChatstate(node).catch(error => onUnexpectedError(error, 'handling chatstate'))
-	})
-	ws.on('CB:presence', async node => {
-		nodelogger(node)
-		await handlePresence(node).catch(error => onUnexpectedError(error, 'handling presence'))
-	})
 	ws.on('CB:ack,class:message', node => {
 		nodelogger(node)
 		handleBadAck(node).catch(error => onUnexpectedError(error, 'handling bad ack'))
@@ -2879,7 +2321,7 @@ const makeMessagesRecvSocket = config => {
 			return
 		}
 		nodelogger(call)
-		
+		// missed call + group call notification message generation
 		if (call.status === 'timeout' || (call.status === 'offer' && call.isGroup)) {
 			const msg = {
 				key: {
@@ -2915,7 +2357,7 @@ const makeMessagesRecvSocket = config => {
 			sendActiveReceipts = isOnline
 			logger.trace(`sendActiveReceipts set to "${sendActiveReceipts}"`)
 		}
-		
+		// Daily cleanup of expired tctokens (mirrors WA Web's CLEAN_TC_TOKENS task)
 		if (isOnline) {
 			const now = Date.now()
 			const DAY_MS = 24 * 60 * 60 * 1000