> ## Documentation Index
> Fetch the complete documentation index at: https://nexus-core.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocol and Packet Structure Reference

> Reference for the JSON packet format exchanged between Spigot servers and Nexus Core over Redis pub/sub, including all security fields in both directions.

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)

```json theme={null}
{
  "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

<ParamField path="protocol" type="number" required>
  The numeric addon ID registered with Nexus Core. Corresponds to the value returned by `addonId()` on the target DataAddon.
</ParamField>

<ParamField path="source" type="string" required>
  An identifier for the Spigot server sending the packet (e.g. `"pvp-1"`, `"lobby"`, `"admin"`). Passed to `handleRequest()` as the `source` parameter.
</ParamField>

<ParamField path="type" type="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`.
</ParamField>

<ParamField path="data" type="object" required>
  The request payload. Must include the `isId` field value for single-document operations. For `SET_DATA`, include all fields to write.
</ParamField>

<ParamField path="timestamp" type="number" required>
  The sender's current Unix time in milliseconds. Must be within 5 minutes of Nexus Core's server clock.
</ParamField>

<ParamField path="nonce" type="string" required>
  A single-use UUID string for replay protection. Each nonce can only appear once within the timestamp window.
</ParamField>

<ParamField path="sig" type="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.
</ParamField>

## 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`.

```json theme={null}
{
  "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

<ResponseField name="protocol" type="number">
  The numeric addon ID echoed from the original request.
</ResponseField>

<ResponseField name="source" type="string">
  Always `"nexus"` for responses originating from Nexus Core.
</ResponseField>

<ResponseField name="type" type="string">
  The response type. Typically `"BROADCAST"` for data responses routed back to the requesting server.
</ResponseField>

<ResponseField name="target" type="string">
  The `source` value from the original request packet. Nexus Core publishes the response to this server's Redis channel.
</ResponseField>

<ResponseField name="data" type="object">
  The response payload containing the complete document fields as stored in MongoDB.
</ResponseField>

<ResponseField name="timestamp" type="number">
  Unix milliseconds at the time Nexus Core signed and published the response. Added in v1.5.1.
</ResponseField>

<ResponseField name="nonce" type="string">
  A single-use UUID generated by Nexus Core for this response. Added in v1.5.1.
</ResponseField>

<ResponseField name="sig" type="string">
  Base64-encoded HMAC-SHA256 signature over all response fields except `sig` itself, signed with `NEXUS_SIGNING_KEY`. Added in v1.5.1.
</ResponseField>

## 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`) |

## Related Topics

* [Security](/concepts/security) — how signatures are validated and generated
* [Request Types](/concepts/request-types) — all valid `type` field values
* [Request Lifecycle](/reference/request-lifecycle) — how packets flow from receipt to response


## Related topics

- [Nexus Core Changelog](/reference/changelog.md)
- [Packet Security and Replay Protection in Nexus Core](/concepts/security.md)
- [DataAddon API Reference](/addons/data-addon-api.md)
- [Request Lifecycle in Nexus Core](/reference/request-lifecycle.md)
- [Request Types in Nexus Core](/concepts/request-types.md)