[Composite] Draft AIP for ADAMANT Group Chats & Channels

[metalisk]

Summary

Draft an ADAMANT Improvement Proposal in Adamant-im/AIPs for ADAMANT Group Chats and Channels in the classic blockchain messaging model, where every message is a blockchain transaction.

The AIP should define interoperable group/community and channel semantics for ADAMANT clients and node APIs, including group identity, membership, roles, moderation, paid/free access, message fees, subscription economics, notifications, and the node architecture needed to support this safely.

This issue is scoped to the current permanent blockchain-backed messaging model first. Integration with the planned alternative messaging architecture in #194 must be treated as a separate follow-up discussion after that architecture is selected.

Details

Background

ADAMANT currently supports classic one-to-one chats where a message is a transaction:

• Message transactions use transaction type 8 (CHAT_MESSAGE) from helpers/transactionTypes.js.
• The encrypted payload is stored in transaction.asset.chat.message.
• transaction.asset.chat.own_message stores the nonce needed for decryption.
• transaction.asset.chat.type distinguishes legacy, ordinary, rich, and signal message payloads.
• Message fees are calculated in logic/chat.js, currently using constants.fees.chat_message for modern messages and constants.fees.old_chat_message for legacy messages.
• Chat data is stored in the chats table and exposed through sql/chats.js, modules/chats.js, modules/chatrooms.js, schema/chats.js, and schema/chatrooms.js.
• Current chatroom APIs are pairwise: modules/chatrooms.js derives dialogs from sender/recipient pairs and validates request paths as U.../U....
• Address validation currently accepts only U addresses in helpers/z_schema.js.
• WebSocket subscriptions in modules/clientWs/transactionSubscription.js match transactions by sender/recipient address and transaction or asset chat type.

Group chats and channels require a protocol-level design before implementation because they affect transaction validation, address formats, fees, membership state, moderation state, node APIs, schemas, client interoperability, and possibly balances or fee distribution.

Source material to review

• AIP process and required sections: https://github.com/Adamant-im/AIPs/blob/master/AIPS/aip-1.md
• AIP-4 Basic Encrypted Messages: https://aips.adamant.im/AIPS/aip-4
• AIP-5 Rich Content Messages: https://aips.adamant.im/AIPS/aip-5
• AIP-14 Chatrooms API: https://aips.adamant.im/AIPS/aip-14
• AIP-16 Quote/reply messages: https://aips.adamant.im/AIPS/aip-16
• AIP-17 Reactions to Messages: https://aips.adamant.im/AIPS/aip-17
• Deleted messages task: [Composite] Draft AIP for deleted messages #195
• Archived/deleted/SPAM dialogs task: [Composite] Draft AIP for archived, deleted, and SPAM dialogs #199
• Optional free messaging architecture task: [Composite] Draft AIP for optional free messaging architecture #194
• ADAMANT node repository: https://github.com/Adamant-im/adamant
• API schema repository: https://github.com/Adamant-im/adamant-schema
• Documentation repository: https://github.com/Adamant-im/docs
• ADAMANT chats and chatrooms API docs: https://docs.adamant.im/api-endpoints/chatrooms.html
• ADAMANT message types: https://docs.adamant.im/api-types/message-types.html
• ADAMANT transaction types: https://docs.adamant.im/api-types/transaction-types.html

Product taxonomy to define

The AIP should define ADAMANT-native terms before specifying transaction formats:

• Community: all allowed members can read and write.
• Channel: all allowed members can read, but only administrators and/or moderators can publish.
• Open group/channel: any user can join according to public protocol rules.
• Closed group/channel: users can join only by invitation or administrator approval.
• Moderated/administered group/channel: administrators and moderators can perform protocol-defined moderation actions.
• Unmoderated group/channel: governance is based on prior agreement between participants; it must not be open, because there is no public moderator path for abuse response.

The AIP should be explicit about whether "group chat" is a generic umbrella term and whether G... and C... addresses distinguish communities and channels or only identify group-like entities with metadata specifying the mode.

Roles and permissions

Define a deterministic role model:

• Administrator: can delete or archive the group according to protocol rules, appoint or remove administrators, appoint or remove moderators, change mutable settings, invite or approve members, moderate messages and members.
• Moderator: can moderate messages and members within limits set by administrators.
• User/member: can read and, in communities, write if membership and payment rules allow it.

The AIP should specify:

• how administrators are appointed at creation;
• whether the creator is always an administrator;
• whether administrators can remove the creator;
• whether role changes are reversible;
• how role changes are ordered if conflicting transactions appear in the same block;
• what happens if all administrators are removed or lose access;
• how closed unmoderated groups change membership if no administrator exists.

Moderation and deletion model

The design must not claim that historical blockchain data can be erased. Message deletion and moderation should be defined as tombstone or filtering semantics over persistent transactions, consistent with #195.

The AIP should define:

• message deletion by original sender;
• message deletion by administrator or moderator;
• member ban or mute;
• group/channel deletion or closure;
• whether deleted messages are hidden, replaced with a placeholder, or returned through a raw-history API flag;
• whether moderation markers are private encrypted Rich messages, public node-indexable control transactions, or both;
• how nodes and clients process moderation markers before rendering a group timeline;
• whether nodes should reject new messages from banned users after the ban transaction is confirmed;
• behavior for unconfirmed messages and WebSocket delivery around bans, moderation, and role changes.

Public moderation markers may be necessary for legal and abuse-response reasons in open communities and channels, but they leak moderation metadata. The AIP should compare private and public approaches, then justify the selected one.

Group identity and address model

The notes propose group or channel addresses such as G22324532453564364432534 or C22324532453564364432534. This is consensus and API visible, because current address validation accepts only U....

The AIP should compare at least these identity models:

• Synthetic group address derived deterministically from the group creation transaction ID.
• Group address derived from a group public key.
• Multisignature-backed owner account plus a separate group address.
• Full account-like group address with balances, transfers, username, and voting capabilities.

Recommended initial direction to evaluate:

• Use a deterministic synthetic G... or C... address for group identity and routing.
• Do not allow group addresses to forge, vote, or sign arbitrary transactions in the first protocol version.
• If a group needs a treasury or betting/pool behavior, define it as an explicit group treasury sub-protocol with deterministic administrator or multisig withdrawal rules.
• Treat full account-like behavior, voting, and login under a group address as a later high-risk extension, because it affects account semantics, authorization, balances, and governance.

The AIP must define whether group public usernames such as super_chat are mandatory at creation, globally unique, mutable, transferable, and protected from collision with user/delegate usernames.

Message and transaction model

The AIP should define whether group messages reuse transaction type 8 or introduce new transaction types. Candidate direction:

• Add explicit group transaction types for consensus-visible state:
  • group/channel creation;
  • group settings update;
  • member invite, join request, approval, leave, removal, ban, mute;
  • role assignment and revocation;
  • subscription payment or renewal;
  • moderation/tombstone;
  • optional group treasury operation.
• Define how a normal group message is represented:
  • either a new group-message transaction type;
  • or type 8 with a G... or C... recipientId and new validation rules.
• Preserve existing one-to-one type 8 transaction bytes, IDs, signatures, and fees unless the AIP explicitly defines a height-gated protocol upgrade.

If existing type 8 is extended, the AIP must explain how old nodes and old clients behave when they see a G... or C... recipient. If new transaction types are added, the AIP must define transaction bytes, fee calculation, dbRead/dbSave, API schema fields, and block validation rules.

Encryption and read access

Classic ADAMANT messages are encrypted to a recipient account. Groups need a different key model.

The AIP should define:

• group epoch keys or sender keys for encrypted group content;
• how open groups expose read access without giving nodes plaintext;
• how closed groups distribute keys to approved members;
• how channels protect publisher/admin keys;
• how member removal or ban rotates keys for future messages;
• how old messages remain decryptable or become unavailable after membership changes;
• how multi-device accounts receive group keys;
• what metadata remains public on-chain even when payloads are encrypted.

The AIP should avoid inventing new cryptographic primitives. If the design needs modern group encryption beyond the current NaCl box model, it should evaluate MLS-style group epochs or a simpler explicitly scoped first version, then describe the security tradeoffs.

Fees, subscriptions, and economics

The AIP should specify all economic rules deterministically.

Creation:

• group/channel creation is paid;
• the fee goes to nodes through the standard fee path unless a future protocol upgrade says otherwise;
• creation fee may depend on group type, openness, moderation mode, username registration, and treasury support.

Per-message fees:

• standard message fee;
• increased message fee;
• possible fee exemptions for administrators or moderators;
• channel mode where only administrators pay to publish;
• mode where all writers pay;
• mode where the administrator pays for user-visible free reading or subsidized messages.

Subscriptions:

• free subscription;
• paid subscription;
• lifetime subscription;
• monthly subscription;
• yearly subscription;
• renewal, expiration, refund, and grace-period behavior.

Distribution of extra message fees and subscriptions:

• distributed to nodes as ordinary fees;
• distributed to participants according to deterministic rules;
• transferred to the group creator or administrator, for example paid news channels.

Any non-standard distribution changes account balances and must define exact apply/undo behavior, replay safety, rounding, ordering, and SQL/state coupling. Rewarding participants by attention or audience size is especially sensitive and must avoid spam incentives, self-dealing, and non-deterministic ranking.

Notifications

Notification preferences should likely be user-local settings, not consensus state:

• notify only for administrator messages;
• notify for all messages;
• notify for no messages.

The AIP should define how clients store these preferences, for example encrypted KVS or local-only cache, and how WebSocket/push services respect them without leaking unnecessary social-graph metadata.

Proposed node architecture

The AIP should include an implementation architecture for this repository. A candidate architecture to evaluate:

• Add a new consensus activation height for group/channel transaction validation.
• Add group-specific transaction types or a clearly versioned extension of type 8.
• Add logic modules for group creation, settings, membership, roles, subscriptions, moderation, and group messages.
• Add deterministic state mirrors, for example mem_groups, mem_group_members, mem_group_roles, mem_group_subscriptions, mem_group_moderation, and optional mem_group_treasury.
• Add SQL tables, migrations, and full transaction views for group state and group messages.
• Update account/address validation to support G... and/or C... only after activation.
• Update modules/chats.js and/or introduce modules/groupChats.js for listing and fetching group timelines.
• Update modules/chatrooms.js to support pairwise dialogs and group/channel entries without breaking existing /api/chatrooms/:userId/:companionId behavior.
• Update WebSocket subscription logic to support group addresses, group timelines, and moderation/control events.
• Update transaction pool filtering so unconfirmed group messages respect current role, membership, subscription, and ban state.
• Update adamant-schema for new transaction, group, membership, moderation, and API response shapes.
• Update docs with endpoint behavior, examples, fees, and backwards compatibility notes.

The implementation should keep state mutations inside existing sequencing semantics (sequence, dbSequence, balancesSequence) and must not introduce non-deterministic ordering in validation, fee distribution, membership checks, or moderation checks.

Required design questions

• Should this be one broad AIP, or should it be split into focused AIPs for group identity, membership/moderation, group messages, economics/subscriptions, and treasury behavior?
• Are G... and C... both needed, or should one group address prefix plus metadata be used?
• Can a group/channel be deleted, or only closed with a permanent tombstone?
• Can unmoderated closed groups change membership after creation, and if yes, who authorizes it?
• Should open groups require public moderation markers for abuse response?
• Should group addresses hold balances in the first version?
• Should group addresses ever vote or act like normal users?
• How are group keys created, rotated, backed up, and recovered?
• How do clients show historical messages after a member leaves, is removed, or is banned?
• How are group/channel usernames reserved, renamed, transferred, or released?
• How do paid subscriptions interact with bans and moderation?
• How are extra fees rounded and distributed under replay and rollback?
• Which APIs return raw blockchain history versus moderated/filtered timelines?
• What is the migration and compatibility behavior for old nodes and clients?

Relation to #194

This AIP should solve classic ADAMANT blockchain group chats and channels first, where messages and control actions are transactions.

The AIP must include a short compatibility section for #194, but should not finalize implementation details for that alternative architecture yet. Once #194 selects a relay, temporary sidechain, embedded protocol, or another design, group chats and channels in that architecture should be discussed separately and may require a companion AIP.

Proposed AIP structure

• Preamble, with an editor-assigned AIP number.
• Simple Summary.
• Abstract.
• Motivation.
• Current ADAMANT messaging and chatroom model.
• Definitions: community, channel, open, closed, moderated, unmoderated.
• Requirements and non-goals.
• Threat, abuse, and prohibited-content model.
• Group identity and address specification.
• Roles and permission model.
• Membership and invitation flows.
• Message transaction specification.
• Group key and encryption model.
• Moderation and deleted-message semantics.
• Fees, subscriptions, and distribution rules.
• Group treasury and account-like behavior.
• Notification semantics.
• Node/API/WebSocket architecture.
• SQL/state/schema impact.
• Backwards compatibility and activation.
• Security and privacy considerations.
• Test cases.
• Implementations.
• Documentation/schema impact.
• References.
• Copyright waiver.

Checklist

• Draft the AIP in Adamant-im/AIPs, following AIP-1.
• Decide whether to keep one broad AIP or split it into smaller AIPs.
• Define group/channel terminology and address model.
• Define open/closed and moderated/unmoderated rules, including the rule that unmoderated chats cannot be open.
• Define administrator, moderator, and user/member permissions.
• Define group creation, settings update, username reservation, and deletion/closure.
• Define membership, invitations, join requests, approvals, leaves, removals, bans, and mutes.
• Define message transaction format for group messages and channel posts.
• Define encryption and key rotation for open and closed groups.
• Define moderation and deleted-message behavior, linking to [Composite] Draft AIP for deleted messages #195.
• Define paid/free creation, message fees, subscriptions, expiration, and fee distribution.
• Define whether group addresses can hold balances, receive transfers, manage a treasury, vote, or act like users.
• Define notification preferences and storage.
• Define required node architecture and API/schema changes.
• Define compatibility boundaries with [Composite] Draft AIP for optional free messaging architecture #194.
• Define activation, replay, rollback, and deterministic validation requirements.
• Define required tests for transaction validation, APIs, WebSocket events, SQL state, moderation, fees, subscriptions, and replay safety.
• Create linked implementation issues for adamant, adamant-schema, docs, PWA, and iOS after the AIP direction is accepted.

Verification

The task is complete when:

• A draft AIP PR exists in Adamant-im/AIPs.
• The draft follows AIP-1 structure.
• The draft is scoped to classic blockchain-backed ADAMANT messaging first.
• The draft defines group/channel terminology, roles, membership, moderation, fees, subscriptions, notifications, and address model.
• The draft describes a concrete architecture for this node repository.
• The draft identifies all consensus-impacting parts and requires activation-gated behavior.
• The draft states that the alternative architecture from [Composite] Draft AIP for optional free messaging architecture #194 needs separate discussion after that architecture is selected.
• The draft includes backwards compatibility, security/privacy considerations, abuse/prohibited-content considerations, and test cases.
• Companion issues or PRs are created for adamant, adamant-schema, docs, PWA, and iOS where needed.

Notes

• This is a protocol/design task, not an immediate implementation task.
• This feature touches consensus, transaction validation, address formats, balances, fees, APIs, schemas, client interoperability, privacy, and moderation. Maintainer review is required before implementation.
• No transaction bytes, IDs, signatures, fees, rewards, delegate ranking, slot timing, account semantics, or SQL state should change without an explicit AIP, activation plan, replay strategy, and tests.