Group

A privacy group is a list of identities that should receive a private communication.

When you send a private message, you can specify the list of participants in-line and it will be resolved to a group. Or you can reference the group using its identifying hash.

The sender of a message must be included in the group along with the other participants. The sender receives an event confirming the message, just as any other participant would do.

The sender is included automatically in the group when members are specified in-line, if it is omitted.

Group identity hash

The identifying hash for a group is determined as follows:

• All identities are resolved to their DID.
• An organization name or identity UUID can be used on input
• The UUID of the node that should receive the data for each participant is determined (if not specified).
• The first node found that is in the same identity hierarchy as the participant identity, will be chosen.
• The list of participants is ordered by DID, with de-duplication of any identities.
• The namespace, name, and members array are then serialized into a JSON object, without whitespace.
• A SHA256 hash of the JSON object is calculated

Private messaging architecture

The mechanism that keeps data private and ordered, without leaking data to the blockchain, is summarized in the below diagram.

The key points are:

• Data is sent off-chain to all participants via the Data Exchange plugin
• The Data Exchange is responsible for encryption and off-chain identity verification
• Only parties that are involved in the privacy group receive the data
• Other parties are only able to view the blockchain transaction
• The hash and member list of the group are not shared outside of the privacy group
• The name of the group can be used as an additional salt in generation of the group hash
• The member list must be known by all members of the group to verify the blockchain transactions, so the full group JSON structure is communicated privately with the first message sent on a group
• The blockchain transaction is the source of truth for ordering
• All members are able to detect a blockchain transaction is part of a group they are a member of, from only the blockchain transaction - so they can block processing of subsequent messages until the off-chain data arrives (asynchronously)
• The ordering context for messages is masked on the blockchain, so that two messages that are for same group do not contain the same context
• The ordering context (topic+group) is combined with a nonce that is incremented for each individual sender, to form a message-specific hash.
• For each blockchain transaction, this hash can be compared against the expected next hash for each member to determine if it is a message on a known group - even without the private data (which might arrive later)

See NextPin for more information on the structure used for storing the next expected masked context pin, for each member of the privacy group.

Example

{
    "namespace": "ns1",
    "name": "",
    "members": [
        {
            "identity": "did:firefly:org/1111",
            "node": "4f563179-b4bd-4161-86e0-c2c1c0869c4f"
        },
        {
            "identity": "did:firefly:org/2222",
            "node": "61a99af8-c1f7-48ea-8fcc-489e4822a0ed"
        }
    ],
    "localNamespace": "ns1",
    "message": "0b9dfb76-103d-443d-92fd-b114fe07c54d",
    "hash": "c52ad6c034cf5c7382d9a294f49297096a52eb55cc2da696c564b2a276633b95",
    "created": "2022-05-16T01:23:16Z"
}

Field Descriptions

Field Name	Description	Type
namespace	The namespace of the group within the multiparty network	string
name	The optional name of the group, allowing multiple unique groups to exist with the same list of recipients	string
members	The list of members in this privacy group	Member[]
localNamespace	The local namespace of the group	string
message	The message used to broadcast this group privately to the members	UUID
hash	The identifier hash of this group. Derived from the name and group members	Bytes32
created	The time when the group was first used to send a message in the network	FFTime

Member

Field Name	Description	Type
identity	The DID of the group member	string
node	The UUID of the node that receives a copy of the off-chain message for the identity	UUID