Protocol and Packet Structure Reference

All communication between Spigot servers and Nexus Core uses JSON packets published over Redis pub/sub channels. As of v1.5.1, both directions are signed: inbound packets from Spigot must carry security fields, and outbound responses from Nexus Core also include timestamp, nonce, and sig.

Incoming Packet (Spigot to Nexus Core)

{
  "protocol": 100,
  "source": "pvp-1",
  "type": "GET_DATA",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "timestamp": 1756900000000,
  "nonce": "b7f2b1b0-4b3b-4e29-9e2b-6b8f2b1b0b7f",
  "sig": "base64-hmac-sha256-signature"
}

Fields

number

required

The numeric addon ID registered with Nexus Core. Corresponds to the value returned by addonId() on the target DataAddon.

string

required

An identifier for the Spigot server sending the packet (e.g. "pvp-1", "lobby", "admin"). Passed to handleRequest() as the source parameter.

string

required

The RequestType value identifying the operation to perform. One of: GET_DATA, SET_DATA, REMOVE_DATA, INCREMENT_DATA, UPDATE_DATA, RANKING, RANK_FINDER, BROADCAST, LOAD_CACHE.

object

required

The request payload. Must include the isId field value for single-document operations. For SET_DATA, include all fields to write.

number

required

The sender’s current Unix time in milliseconds. Must be within 5 minutes of Nexus Core’s server clock.

string

required

A single-use UUID string for replay protection. Each nonce can only appear once within the timestamp window.

string

Base64-encoded HMAC-SHA256 signature over all packet fields except sig itself, computed using NEXUS_SIGNING_KEY. Required when NEXUS_SIGNING_KEY is configured on Nexus Core.

Outgoing Packet (Nexus Core to Spigot)

Since v1.5.1, responses from Nexus Core are also signed using the MessageAuth system. All DataAddon publish operations and heartbeat messages include timestamp, nonce, and sig.

{
  "protocol": 100,
  "source": "nexus",
  "type": "BROADCAST",
  "target": "pvp-1",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kills": 142,
    "deaths": 38,
    "balance": 2500.75,
    "isPremium": true
  },
  "timestamp": 1756900000123,
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sig": "base64-hmac-sha256-signature"
}

Fields

number

The numeric addon ID echoed from the original request.

string

Always "nexus" for responses originating from Nexus Core.

string

The response type. Typically "BROADCAST" for data responses routed back to the requesting server.

string

The source value from the original request packet. Nexus Core publishes the response to this server’s Redis channel.

object

The response payload containing the complete document fields as stored in MongoDB.

number

Unix milliseconds at the time Nexus Core signed and published the response. Added in v1.5.1.

string

A single-use UUID generated by Nexus Core for this response. Added in v1.5.1.

string

Base64-encoded HMAC-SHA256 signature over all response fields except sig itself, signed with NEXUS_SIGNING_KEY. Added in v1.5.1.

Version History for Packet Format

Version	Change
v1.5	Added `sig`, `timestamp`, `nonce` fields to inbound packets
v1.5.1	Added `sig`, `timestamp`, `nonce` fields to outbound responses (via `MessageAuth`)

Security — how signatures are validated and generated
Request Types — all valid type field values
Request Lifecycle — how packets flow from receipt to response

Get Started

Core Concepts

Building Addons

Reference

Protocol and Packet Structure Reference

Incoming Packet (Spigot to Nexus Core)

Fields

Outgoing Packet (Nexus Core to Spigot)

Fields

Version History for Packet Format

​Incoming Packet (Spigot to Nexus Core)

​Fields

​Outgoing Packet (Nexus Core to Spigot)

​Fields

​Version History for Packet Format

​Related Topics

Incoming Packet (Spigot to Nexus Core)

Fields

Outgoing Packet (Nexus Core to Spigot)

Fields

Version History for Packet Format

Related Topics