Relations

A relation is a meta-object that defines how different kinds of objects may interact.

Descriptor

Relations are themselves objects: they have their own kind and are minted from a set. The Kind of Relation and the Set of Relation are genesis objects created during protocol initialization.

A relation’s descriptor is initialized with the following values:

Field	Value	Description
`flags`	`0`	Reserved flags
`rev`	`1`	Initially `1`, increments as the relation itself evolves
`krev`	`latest`	Revision of the Kind of Relation at creation (increments over time)
`srev`	`latest`	Revision of the Set of Relation at creation (increments over time)
`kind`	`3`	ID of the Kind of Relation
`set`	`3`	ID of the Set of Relation

Elements

Each relation has 7 elements, as specified in the Kind of Relation object's eltys field.

Index	Element	Mutable	Description
`0`	`code`	Yes	Address of the relation contract (reserved for future use)
`1`	`data`	Yes	Matter hash containing relation-specific data
`2`	`rule`	No	Encoded rule defining how the relation behaves
`3`	`adjs[0]`	Yes	Encoded adjacencies (part 1)
`4`	`adjs[1]`	Yes	Encoded adjacencies (part 2)
`5`	`adjs[2]`	Yes	Encoded adjacencies (part 3)
`6`	`adjs[3]`	Yes	Encoded adjacencies (part 4)

Adjacency

An adjacency specifies which kinds of objects a relation admits, and how many of each kind may participate.

struct Adjacency {
    uint16 degs;  // number of objects of this kind allowed
    uint48 kind;  // the kind of objects
}

Each adjacency can be compactly encoded as a single uint64:

uint64 adj = (uint64(degs) << 48) | kind;

The kind field has two special meanings; all other values refer to a registered kind ID:

0 — any kind not explicitly listed
0xFFFFFFFFFFFF — degs applies to the total number of objects in the relation

Adjacencies are stored in a relation’s adjs[i] fields, ordered by ascending kind ID.

Relation Data

The data field stores a matter hash referencing a piece of data associated with the relation.

Omni Registry

When a relation is registered in the Omni Registry, it receives a relation ID.
Its ID and revision can be compactly encoded into a single uint64:

uint64 compact = (uint64(rev) << 48) | id;

A relation is admitted by a kind if its compact ID appears in that kind’s rels[i] fields.