A PSYC application which is reachable and interconnected with other PSYC applications is called a node in the PSYC network. A node always has both a protocol root and an entity root. It may also provide further entities of varying kind.


A PSYC node which is not reachable from the outside by other PSYC nodes is called a leaf. Clients are usually leaves.


A server is a common terminus for a PSYC node implementing any of person entities, place entities or context functionality. They may provide several functions beyond these, too.


There are two concepts of root in PSYC. Depending on architectural choices, both roots, the protocol root and the entity root MAY be implemented in the same place in the source code, or not.

Root entity

The root entity in a server or application is the object that comes without anything behind the / in its uniform, as in psyc:// It performs jobs like authentication. This root is a full PSYC entity.

Protocol root

The protocol root instead leaves out the / as in psyc:// It is used for negotiation for example in circuits and thus operates on the routing layer. If a packet is sent, and either the source or destination is not explicitly or implicitly addressed, the protocol root is intended.


An entity is any object that can be addressed by a uniform using the appropriate protocol, in most cases either a person entity or a place entity. Entities in PSYC must have:

  • state: the own state and the state of other PSYC entities. A state is usually a set of persistent PSYC variables.
  • trust network: know who the entity trusts and who it can ask for second hand trust.

Entity Behavior

There is a set of basic entity types, which implement a specific behaviour to meet the needs of a chat network. These are the specified entities PSYC currently knows:

Provided for in the spec, but not currently implemented:

Some entities implement a command interface, to let users actually do something with the entities (like setting the topic of a place).


Each entity has at least one context, which is reachable via his uniform. Some entities, like the person entity, offer multiple sub contexts, called channels, which are addressed by the channel part of its uniform. For example, if psyc:// is the UNI of the person entity, the context where presence updates are multicast, may have the uniform psyc://

Just like an anchor in HTTP URIs, the channel is not a new entity itself but merely defines a different view on the original entity's context. Channels define a variation in routing and its logic (typically a subset of the entity's subscribers), but do not need new subscription procedures as they inherit the trust relationships of the owning entity. Receiving entities are required to accept these messages immediately as if sent by the entity.

For a list of predefined channels, look at the specification of the entity types. Further channels can be provided and named freely, according to the needs of the application.

Channel inheritance

Channel names are bound to rules for keywords and define their own keyword namespace for the purpose of defining standardized compact channel names like p for _presence. Channel inheritance is defined as follows: Any subscriber of a subchannel is also regarded as the subscriber of the parent channel and the context as a whole, and thus receives traffic transmitted to it, but a subscriber of a subchannel does not receive traffic directed to a completely different subchannel. Examples:

A subscriber to psyc:// will receive packets transmitted to psyc://, psyc:// and psyc:// but not to psyc://

A subscriber to psyc:// will receive packets on psyc:// and psyc:// but neither psyc:// nor psyc://

Channel state inheritance

This affects also the way state is seen by subscribers of various channels. A subchannel may have a differing member list from its parent channel by applying its own modifications to it. Modifications to the parent channel still affect all of the subchannels. Member lists just being an example, as they are not required for channel routing and currently only serve informational purposes.

Here's an example how this can be useful. Consider a news company that provides headlines and discussion channels. It may want to allow its subscribers to select certain themes. It would find it useful to keep general information like a company logo in a top-level state like psyc://, then provide theme headlines in channels like psyc://, and allowing users to subscribe psyc://, where they not only receive the psyc:// headlines, but are additionally permitted to talk about them without disturbing the subscribers of the parent channels. This gives the company the possibility to make important global announcements on psyc:// without having to send copies to a whole stack of chatrooms, because the top channel has all subscribers right there.

the UNL

the Uniform Network Location is the effective IP address where a user agent (a client) or other mobile entity is operating for a user (or other UNI), usually in combination with an allocated port number. UNLs are volatile, as the current IP number of a client changes frequently, and are typically given to trusted friends for peer-to-peer activity. Usually the UNL points to the root entity of the user's client.

Example: psyc://localhost:4711/

NOTE: How locations work and how they are linked to the identity is not covered in this Specification

the UNI

the Uniform Network Identification is a permanent uniform of an entity in the PSYC network. Something you can print on your business card or publish in other Internet media. In some cases the entity answering at a UNI will forward or redirect messages to a location addressed by a UNL, in other cases the entity is self-sufficient. UNIs are primarily employed by identities and places.

Example: psyc://


A location is generally a person's client, but it may be any piece of software with a variable address linked to any identity providing some service.

A UNL is used to address a location, it usually reveals a user's current IP address, as for example in psyc://

NOTE: How locations work and how they are linked to the identity is not handled in this Specification


An identity is a linkable entity, typically a person entity, but a service identity may be linkable, too.

A UNI is used to address an identity and the home server is where a user's own identity resides.

physical source

The physical source of a packet is either the _source or, if the _source is not given, _context.

logical source

To determine where the message came from _logically_ you need to get the logical source. The logical source of a packet is in this order (first hit counts): _source_relay, _source, _context.

logical target

The logical target of a packet is either the _context or, if _context is not set, the _target.

logical context

To determine which logical context the message belongs to you have to determine the logical context. It is found in this order (first hit counts): _context, _source_relay, _source.

See logical source above to determine who the sender of the message was.