Contact

Description
Specification
Interpretation
Examples
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
}