sitemap.xml llms.txt
Skip to main content

Consensus Functions

Use the Consensus adapter to manage consensus barriers.

Importing the adapter​

To use the functions of the Consensus adapter, import it as shown:
import { consensusAdapter } from 'epicenter-libs';

The consensusAdapter namespace exports functions that make calls to the Consensus API.

learn more

For descriptions of the objects used by the Consensus adapter functions, read Consensus entities.

Create​

Create barrier​

The create() function creates a new consensus barrier for a world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Accepts optional routing options and consensus‑specific settings.
  • Constructs a POST request to the /consensus/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Initializes a consensus barrier with expected roles and default actions.
  • Returns a BarrierReadOutView object representing the newly created barrier.
Function signature
export async function create<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    expectedRoles: Record<R, number>,
    defaultActions: Record<R, Actionable[]>,
    optionals: {
        ttlSeconds?: number;
        transparent?: boolean;
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world you are creating a consensus barrier in.
  • name (string): Unique string to name a set of consensus barriers.
  • stage (string): Unique string to name one stage within the set of consensus barriers.
  • expectedRoles (Record<R, number>): Identifies the set of roles expected to arrive at the barrier with the number of participants in each role.
  • defaultActions (Record<R, Actionable[]>): A map of roles to the default actions for them represented by an array of Actionable objects.
  • optionals (optional):
    • ttlSeconds (number): The time limit for this barrier.
    • transparent (boolean): If true, all default actions are sent; if false, only one is sent.
    • allowChannel (boolean): Enables push notifications for this barrier (available for projects with phylogeny SILENT or later).
    • RoutingOptions: Network call options overrides.

Return value​

A promise that resolves to a BarrierReadOutView object representing the newly created barrier.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.create(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  {
    ROLE1: 1,
    ROLE2: 1,
    ROLE3: 2,
  },
  {
    ROLE1: [{ name: 'step', arguments: [] }],
    ROLE2: [{ name: 'step', arguments: [] }],
    ROLE3: [{ name: 'step', arguments: [] }],
  },
  {
    ttlSeconds: 3600,
    transparent: true,
    allowChannel: true,
  }
);

Retrieve​

Load barrier​

Retrieves a specific consensus barrier by world key, name and stage.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The load() function:

Function signature
export async function load<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world you are loading a consensus barrier from.
  • name (string): Unique string that names a set of consensus barriers.
  • stage (string): Unique string specifying which barrier to load within the set.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a BarrierReadOutView object describing the loaded barrier.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

const barrier = await consensusAdapter.load(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

List by name​

Retrieves all consensus barriers that share the same name within a given world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The list() function:

Function signature
export async function list<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>[]>

Parameters​

  • worldKey (string): World key for the world you are retrieving consensus barriers from.
  • name (string): Unique string specifying which set of consensus barriers to retrieve.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to an array of BarrierReadOutView objects representing the barriers in the set.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

const barriers = await consensusAdapter.list(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS'
);

View barriers for group​

To allow a facilitator to check barrier status across multiple worlds, use the collectInGroup() function. It retrieves multiple consensus barriers across multiple worlds within a group or episode.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to
    /consensus/in/{GROUP_NAME}
    or
    /consensus/in/{GROUP_NAME}/{EPISODE_NAME}.
  • Accepts a map of world keys to barrier name/stage pairs.
  • Returns an array of BarrierReadOutView objects for the requested barriers.
Function signature
export async function collectInGroup<R extends WorldRole = WorldRole>(
    barrierMap: BarrierMap,
    groupName: string,
    optionals: {
        episodeName?: string;
    } & RoutingOptions = {},
): Promise<BarrierReadOutView<R>[]>

Parameters​

  • barrierMap (BarrierMap): A map of world keys to { name, stage } pairs identifying which barriers to retrieve.
  • groupName (string): Name of the group containing the worlds.
  • optionals (optional):
    • episodeName (string): Name of the episode within the group.
    • RoutingOptions: Network call options overrides.

Return value​

A promise that resolves to an array of BarrierReadOutView objects for the requested barriers.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

const barriers = await consensusAdapter.collectInGroup(
  {
    '00000173078afb05b4ae4c726637167a1a9e': { name: 'SUBMISSIONS', stage: 'ROUND1' },
    '00000173078afb05b4ae4c726637167a1b2f': { name: 'SUBMISSIONS', stage: 'ROUND1' },
  },
  'my-group-name',
  { episodeName: 'my-episode-name' }
);

Manage​

Update default actions​

Updates the default actions for the current participant on a transparent consensus barrier.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The updateDefaults() function:

  • Constructs a PATCH request to the /consensus/actions/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Updates the default actions originally defined in .create() for the current user.
  • Only works on barriers where transparent: true.
  • Returns the updated BarrierReadOutView object.
Function signature
export async function updateDefaults<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    actions: Record<R, Actionable[]>,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming one stage of the barrier set.
  • actions (Record<R, Actionable[]>): List of default actions to update for the current user represented by an array of Actionable objects.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a BarrierReadOutView object representing the updated barrier.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.updateDefaults(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  {
    ROLE1: [{ name: 'message', value: 'DEFAULT MESSAGE 2', objectType: 'set' }]
  }
);

Submit actions​

Submits the actions for the current participant and marks them as arrived. May trigger the barrier if this is the last participant to arrive.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The submitActions() function:

  • Constructs a POST request to the /consensus/publish/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Sends the user's actions to the consensus barrier.
  • Marks the user as having arrived.
  • If transparent was set to true during creation, actions are sent directly to the model.
  • Returns a consensus response object with triggered: true for the final user to submit. This field is virtual and not stored in the database.
Function signature
export async function submitActions(
    worldKey: string,
    name: string,
    stage: string,
    actions: Actionable[],
    optionals: {
        message?: string;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {},
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming one stage of the barrier set.
  • actions (Actionable[]): List of action objects to submit.
  • optionals (optional):
    • message (string): Optional message stored in the barrier arrival entity.
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the submission.
    • RoutingOptions: Network call options overrides.

Return value​

A promise that resolves to the server response. For the final submitting user, the response includes triggered: true.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.submitActions(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  [{ name: 'step', arguments: [] }],
  { message: 'Student side submission!' }
);

Undo submission for current user​

Removes the logged-in user from the list of participants who have arrived at a consensus barrier, allowing them to resubmit.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The undoSubmit() function:

  • Constructs a DELETE request to the /consensus/arrival/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns the updated BarrierReadOutView object.
Function signature
export async function undoSubmit<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world containing the targeted barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which barrier to undo submission for.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to the updated BarrierReadOutView object.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.undoSubmit(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Undo submission for given user​

The undoSubmitFor() function allows a facilitator to remove a participant from the list of arrivals for a specific consensus barrier. This enables that user to redo their submission.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a DELETE request to the /consensus/untrigger/{WORLD_KEY}/{NAME}/{STAGE}/{USER_KEY} endpoint.
  • Returns undefined on success.
Function signature
export async function undoSubmitFor(
    worldKey: string,
    name: string,
    stage: string,
    userKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters​

  • worldKey (string): World key for the world containing the barrier.
  • name (string): Unique string identifying the set of consensus barriers.
  • stage (string): Unique string to specify which barrier to undo the submission for.
  • userKey (string): The user whose arrival is being removed.
  • optionals (RoutingOptions, optional): Network call options overrides.

Return value​

A promise that resolves to undefined if the operation succeeds.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.undoSubmitFor(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  '0000017cb60ad697e109dcb11cdd4cfcdd1d'
);

Trigger arrival for participant​

The triggerFor() function forces the arrival of a participant to a consensus barrier submitting the default actions for them. Useful for testing or making decisions for absent participants.

note

Requires facilitator-level permissions.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /consensus/trigger/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns a generic response object.
Function signature
export async function triggerFor(
    worldKey: string,
    name: string,
    stage: string,
    userKey: string,
    actions: {
        name: string;
        arguments: string | number | Record<string, unknown>[];
    }[],
    optionals: {
        message?: string;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the targeted barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming the stage of the targeted barrier.
  • userKey (string): Key of the user whose arrival is being triggered.
  • actions ({ name: string; arguments: string | number | Record<string, unknown>[] }[]): List of default actions to submit on behalf of the user.
  • optionals (Type: { message?: string; ritual?: keyof typeof RITUAL } & RoutingOptions = {}): Optional routing options and metadata:
    • message (string): Optional message describing the facilitator-triggered submission.
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the triggered arrival.

Return value​

A promise that resolves to a generic response object. The structure may vary depending on the consensus configuration.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.triggerFor(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  '0000017cb60ad697e109dcb11cdd4cfcdd1d',
  [{ name: 'step', arguments: [] }],
  { message: 'Facilitator Triggered this submission!' }
);

Remove role expectation​

The removeRoleExpectationFor() function removes a role expectation from a consensus barrier based on the specified user’s assigned role.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a DELETE request to the /consensus/expectation/{WORLD_KEY}/{NAME}/{STAGE}/{USER_KEY} endpoint.
  • Returns undefined on success.
Function signature
export async function removeRoleExpectationFor(
    worldKey: string,
    name: string,
    stage: string,
    userKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters​

  • worldKey (string): World key for the world containing the barrier.
  • name (string): Unique string identifying the set of consensus barriers.
  • stage (string): Unique string identifying the specific barrier stage.
  • userKey (string): The user whose role expectation will be removed.
  • optionals (RoutingOptions, optional): Network call options overrides.

Return value​

A promise that resolves to undefined if the operation succeeds.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.removeRoleExpectationFor(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  '0000017cb60ad697e109dcb11cdd4cfcdd1d'
);

Force close barrier​

The forceClose() function checks the timer. If time has ran out, it marks the consensus barrier as complete. Closing the barrier triggers default actions for any roles that have not arrived.

note

Requires facilitator-level permissions.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /consensus/close/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns the server response.
Function signature
export async function forceClose(
    worldKey: string,
    name: string,
    stage: string,
    optionals: {
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {},
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier to close.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which stage of the barrier set to close.
  • optionals (optional):
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the closure event.
    • RoutingOptions: Network call options overrides.

Return value​

A promise that resolves to unknown.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.forceClose(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Pause timer​

The pause() function pauses the timer for a timed consensus barrier.

When paused, the timer stops counting down and the remaining time is preserved. This operation only applies to barriers that have the ttlSeconds property set.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to the /consensus/pause/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns the updated BarrierReadOutView object.
Function signature
export async function pause<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string) – Unique identifier of the world containing the consensus barrier
  • name (string) – Barrier name
  • stage (string) – Barrier stage
  • optionals (RoutingOptions): RoutingOptions – Additional routing options

Return value​

Returns a promise that resolves to a BarrierReadOutView object.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.pause(
    '00000173078afb05b4ae4c726637167a1a9e',
    'SUBMISSIONS',
    'ROUND1',
);

Resume timer​

The resume() function resumes the timer for a paused consensus barrier.

When resumed, the timer continues counting down from the point where it was paused. This operation only applies to barriers that have the ttlSeconds property set.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to the /consensus/pause/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns the updated BarrierReadOutView object.
Function signature
export async function resume<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string) – Unique identifier of the world containing the consensus barrier
  • name (string) – Barrier name
  • stage (string) – Barrier stage
  • optionals (RoutingOptions): RoutingOptions – Additional routing options

Return value​

Returns a promise that resolves to a BarrierReadOutView object.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.resume(
    '00000173078afb05b4ae4c726637167a1a9e',
    'SUBMISSIONS',
    'ROUND1',
);

Delete​

Delete barrier​

Deletes a consensus barrier specified by a world key, name, and stage.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The deleteBarrier() function:

  • Constructs a DELETE request to the /consensus/{WORLD_KEY}/{NAME}/{STAGE} endpoint.
  • Returns the deleted BarrierReadOutView object.
Function signature
export async function deleteBarrier<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world containing the barrier to delete.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which barrier to delete.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to the deleted BarrierReadOutView object.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.deleteBarrier(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Delete by name​

Deletes all consensus barriers with the same name in a world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The deleteAll() function:

  • Constructs a DELETE request to the /consensus/{WORLD_KEY}/{NAME} endpoint.
  • Returns the deleted barriers as BarrierReadOutView objects.
Function signature
export async function deleteAll<R extends WorldRole = WorldRole>(
    worldKey: string,
    name: string,
    optionals: RoutingOptions = {},
): Promise<BarrierReadOutView<R>>

Parameters​

  • worldKey (string): World key for the world containing the barriers to delete.
  • name (string): Unique string naming the set of consensus barriers to remove.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to BarrierReadOutView.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.deleteAll(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS'
);