Skip to content
You are reading GoQuorum development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Privacy Groups

Tessera supports operations related to privacy groups such as managing privacy group data and handling transactions that are intended for a privacy group. However, there might be different in behaviours depending on which mode Tessera is running on. See client mode

Types of privacy group:

  1. Legacy
  2. Pantheon
  3. Resident

A unique privacyGroupId is used to identify individual privacy groups.

For private transactions sent to a privacy group, the corresponding privacyGroupId is stored alongside the transaction.

Note

Once created, the members of a privacy group cannot be changed. To add or remove members, a new privacy group must be created.

Privacy groups are currently supported by Hyperledger Besu, which maintains a private state per privacy group.

An example of a privacy group and its related data:

{
    "privacyGroupId": "jufzisK63xbXDciV0FW1uAi3vXFDNNJpf/M3lUhMiU0=",
    "name": "groupA",
    "description": "A description of this group",
    "type": "PANTHEON",
    "members": [
      "98FhPni7u6YspDGcOLl/LgQQwwGPGY4ddm3hmogsqF8=",
      "dzkrEhkHZ/IjHEaQ6teVTU/kMjiwXTI6Ooljcb56w1M="
    ]
}

Legacy Privacy Group

Tessera will automatically create a legacy privacy group when a private transaction is sent to a list of recipient public keys using privateFor.

When returning private transaction data to a Besu client (as part of a /receive response), the legacy privacyGroupId will also be returned.

The legacy privacyGroupId is generated by hashing the list of recipient keys. For a given set of recipients, there can be only one legacy privacy group.

Note

Besu and Tessera will generate the same legacy privacyGroupId from the same list of recipients.

Pantheon Privacy Group

Tessera supports API methods that enable the creation of pantheon privacy groups from a compatible blockchain client (for example Besu).

Upon creation, the privacy group is distributed to all members ahead of transaction processing.

When a private transaction contains a privacyGroupId, the transaction payload is distributed to all the members of the privacy group.

The pantheon privacyGroupId is generated by hashing the list of recipient keys plus a random seed. This means that for a given set of recipients, there can be many pantheon privacy groups.

Resident Privacy Group

The concept of resident privacy group was introduced to accommodate GoQuorum multiple private states feature. A resident group contains a list of member keys that are locally managed, and those members will share the same private state.

Key differences between a resident group and other types of privacy group:

  • A resident group can only contain local keys and no remote key is permitted
  • The name of the resident group will be used as the group identifier
  • Resident groups can be configured via Tessera configuration file, however multiplePrivacyStates feature will have to be switched on. See configuration section for more details

A number of validations will be performed against the resident group configuration during Tessera startup (when multiplePrivacyStates feature is switched on):

  • All members of resident groups must be locally managed by the node.
  • A member cannot be configured to belong to more than 1 resident group at any time (all history considered)
  • All keys configured must belong to a resident group and NO key can be left out.

Database Storage

A new table called PRIVACY_GROUP is added to Tessera’s database to store Privacy Group data.

DDLs are provided along with release notes to create new privacy group tables.

Example

CREATE TABLE PRIVACY_GROUP(ID LONGVARBINARY NOT NULL, LOOKUP_ID LONGVARBINARY NOT NULL, DATA LONGVARBINARY NOT NULL, TIMESTAMP BIGINT, PRIMARY KEY (ID));

Before being persisted into the database, privacy group data is encoded using BinaryEncoder (the same mechanism Tessera uses to encode its EncodedPayload data).

API Versioning

A node running a version of Tessera that does not support privacy groups will not be able to understand requests containing privacyGroupId. This could cause inconsistency of data being persisted on different nodes.

Hence, API version 3.0 has been introduced. Tessera will include the privacy group in the encoded payload in /push to only those recipients supporting correct version, else the transaction is failed with PrivacyGroupNotSupportedException.

Privacy Group APIs

Privacy group compatible blockchain clients (for example Besu) can be used to create, delete, find, and retrieve privacy groups. Tessera’s Q2T API adds support for these operations. Please refer to API reference for more details.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can discuss issues and obtain free support on Tessera Slack channel.
For paid professional support by ConsenSys, contact us at quorum@consensys.net