Skip to main content Link Search Menu Expand Document (external link)

Contact

Table of contents

  1. Description
  2. Specification
  3. Interpretation
  4. Examples
    1. Following
    2. Unfollowing
    3. Blocking
    4. Unblocking
    5. Unfollowing and unblocking
  5. See also

Description

Contact messages are one of the main concepts within the Secure Scuttlebutt ecosystem. Each contact message describes a connection in the social graph.

See the section about following feeds in the protocol guide.

Specification

The contact message is a JSON object with the fields described in the following table.

Field Description
type
A string always set to "contact".
contact
A string which must be set to the id of the feed in the at-sign feed id format.
following

Boolean. Optional. If it is set then it must be set to true or false. If it is not set then it should be ommited and it should not be set to null.

If set to true specifies that this contact is now being followed.

If set to false specifies that this contact is no longer being followed.

blocking

Boolean. Optional. If it is set then it must be set to true or false. If it is not set then it should be ommited and it should not be set to null.

If set to true specifies that this contact is now being blocked.

If set to false specifies that this contact is no longer being blocked.

pub
Work in progress...

Notes:

  • Either following or blocking must be set. Messages without following or blocking set are invalid.
  • Both following and blocking may be set but certain combinations of them don’t make much sense.
  • Malformed messages which use strings "true" and "false" instead of booleans in following and blocking fields exist in the wild. They should be treated as invalid and disregarded.
  • Some feeds contain contact messages with a contact field matching the id of the feed. This is most likely due to some clients following their own feed during initialization. Logically this doesn’t make much sense.

Interpretation

Each contact message specifies a set of operations which should be perfomed on a contact object in order to update it. The following operations exist:

  • follow
  • unfollow
  • block
  • unblock

The field following determines if a contact message carries the follow or unfollow operations. The field blocking determines if a contact message carries the block or unblock operations.

The following table explains how to interpret various values of following and blocking fields to build a list of operations to perform:

Value of the
following
field
Value of the
blocking
field
Interpretation
null or not set null or not set The message is invalid. It doesn't specify any operations.
true null or not set Operations:
  • follow
false null or not set Operations:
  • unfollow
null or not set true Operations:
  • block
null or not set false Operations:
  • unblock
true true Operations:
  • follow
  • block

Note: this makes little sense logically as it is unclear why you would want to follow and block someone in one step but it is possible to process this message therefore it is theoretically valid.

false false Operations:
  • unfollow
  • unblock

In practice the contact data stored by Secure Scuttlebutt clients for a tuple of (author, contact) can be imagined as an object with two fields:

  • a boolean field which describes if a user is being followed
  • a boolean fields which describes if a user is being blocked

This is very similar to the contact messages themselves. Initially both fields are false. The follow and block operations set the fields to true. The unfollow and unblock operations set the fields to false. In order to build the contact information pertaining to a specific (author, contact) pair all contact messages for this pair must be processed in order. Whenever a contact message is encountered the following steps need to be taken:

  • if the contact message contains the follow action then the contact is marked as being followed
  • if the contact message contains the unfollow action then the contact is no longer marked as followed
  • if the contact message contains the block action then the contact is marked as blocked
  • if the contact message contains the unblock action then the contact is no longer marked as blocked

The social graph information is usually constructed in the following way:

  • when walking the graph the edges are traversed only if they are marked as being followed but not as being blocked
  • if the specific feed is marked as blocked by the local feed (hops == 0) then any edges pointing to it are never traversed

Note: this implies that for any feed other than the local feed (hops == 0) blocking is simply equivalent to unfollowing for the purpose of the social graph construction. That information can however be presented differently in user interfaces.

Examples

Following

The following message describes that a user was followed.

{
    "type": "contact",
    "contact": "@sxlUkN7dW/qZ23Wid6J1IAnqWEJ3V13dT6TaFtn5LTc=.ed25519",
    "following": true
}

Unfollowing

The following message describes that a user is no longer being followed.

{
    "type": "contact",
    "contact": "@sxlUkN7dW/qZ23Wid6J1IAnqWEJ3V13dT6TaFtn5LTc=.ed25519",
    "following": false
}

Blocking

The following message describes that a user was blocked.

{
    "type": "contact",
    "contact": "@sxlUkN7dW/qZ23Wid6J1IAnqWEJ3V13dT6TaFtn5LTc=.ed25519",
    "blocking": true
}

Unblocking

The following message describes that a user is no longer being blocked.

{
    "type": "contact",
    "contact": "@sxlUkN7dW/qZ23Wid6J1IAnqWEJ3V13dT6TaFtn5LTc=.ed25519",
    "blocking": false
}

Unfollowing and unblocking

The following message describes that a user is no longer being blocked and followed.

{
    "type": "contact",
    "contact": "@sxlUkN7dW/qZ23Wid6J1IAnqWEJ3V13dT6TaFtn5LTc=.ed25519",
    "following": false,
    "blocking": false
}

See also