# 🔑 Key Serialization

## Information

The Key Serialization add-on stamps every physical crate key with a unique serial stored in the item's hidden data. Players never see it. Once a key opens a crate, its serial is spent, and any other copy carrying that serial is deleted the moment it is found. Duplication glitches, creative copies and NBT-edited keys stop being worth anything.

Because every key is unique, serialized keys no longer stack. Giving 10 keys fills 10 slots, and anything that does not fit is dropped at the player's feet the same way a full inventory always is.

👉 [You can buy this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/key-serialization-addon)

## Installation&#x20;

To install this add-on, you can either:
- Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server.
- Download the plugin with the add-on selected during the downloading.

> **Warning:**
The add-on requires the Premium edition. Virtual keys are not affected, since they never exist as items.

## How It Works

* **Giving keys.** Every physical key handed out by a command, a reward, a refund or an offline delivery gets a fresh serial, which is saved to the plugin's database.
* **Opening a crate.** The serial of the key used is marked as spent before any reward is given. If that serial was already spent, for example by a copy used a moment earlier, the opening gives no rewards.
* **Finding copies.** A copy whose serial is spent, revoked or was never handed out is removed when a player joins, clicks it, moves it, drags it, swaps it to the hotbar, drops it, picks it up, opens a chest holding it, or a hopper tries to move it. Two copies of the same serial found together, including a stack of two, are cut down to one.
* **Old keys.** Keys given out before the add-on was installed get a serial the first time they show up in a player's inventory, so nothing a player already owns is lost.

When a copy is removed, the player is told, staff with the alert permission get a message naming the player, the key, the serial and where it was found, the console logs it, and a Discord webhook can receive it as an embed.

## Networks

On MySQL, MariaDB or PostgreSQL every server sharing the database also shares the serials. A key used on one server dies on all of them within the sync interval, and the database itself refuses to spend the same serial twice, so two servers can never both pay out for one key. On SQLite the serials stay on the one server.

## Commands

| Command | Description | Permission |
| --- | --- | --- |
| `/crates serial check` | Shows the history of the key you are holding: who it was given to and when, and who used it, when and on which crate. | `phoenixcrates.command.serial` |
| `/crates serial lookup <serial>` | Shows the same history for any serial. | `phoenixcrates.command.serial` |
| `/crates serial revoke <serial>` | Spends a serial by hand, so every copy of that key is removed when found. | `phoenixcrates.command.serial` |

Taking keys with `/crates takeKey` revokes their serials too, so copies of the taken keys die as well.

## Permissions

| Permission | Description |
| --- | --- |
| `phoenixcrates.keyserialization.alerts` | Receive a message whenever a duplicated or invalid key is removed. |

## Settings

> **Info:**
The settings live in PhoenixCrates/key-serialization.yml. The switches, the checks and the Discord webhook can also be changed in game from Editor > Add-ons > Key Serialization.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Turns every check off without uninstalling the add-on. |
| `serialize-old-keys` | `true` | Gives a serial to keys handed out before the add-on was installed. |
| `notify-player` | `true` | Tells a player when a duplicated key is removed from them. |
| `alert-staff` | `true` | Sends removals to staff with the alert permission. |
| `checks.containers` | `true` | Checks chests, barrels, shulker boxes and other containers when they are opened. |
| `checks.hoppers` | `true` | Stops hoppers from picking up or moving dead copies. |
| `checks.dropped-items` | `true` | Stops dead copies from appearing as dropped items. |
| `checks.ender-chest-on-join` | `true` | Also checks the ender chest when a player joins. |
| `discord.webhook-url` | empty | A Discord webhook that receives an embed for every key caught: the player, key, serial, where it was found, who it was given to and who used it first. Empty turns it off. |
| `discord.username` | `PhoenixCrates` | The name the webhook posts under. |
| `discord.server-name` | `Server` | Shown in the footer, so a network can tell its servers apart. |
| `discord.color` | `12131840` | The embed color as a decimal number. |
| `discord.batch-seconds` | `5` | Alerts are collected and posted together this often, up to 10 per message. |
| `discord.per-minute` | `20` | The most messages posted in one minute. Alerts over the limit wait for the next slot. |
| `discord.max-queued` | `200` | The most alerts kept waiting. Older ones are skipped beyond this, and the next message says how many. |
| `performance.network-sync-interval-seconds` | `5` | How often a server reads serials used or given out on other servers. |
| `performance.network-sync-clock-margin-seconds` | `30` | How far back each sync looks, to cover clocks that differ between servers. |
| `performance.unknown-serial-recheck-seconds` | `10` | How long a serial the database does not know is given before it is treated as forged, so a key given out on another server a moment ago is never removed by mistake. |
| `performance.dead-serial-cache-size` | `10000` | How many spent serials each server remembers before it has to ask the database again. |
| `performance.lookup-batch-size` | `500` | How many serials are looked up in one database query. |
| `performance.write-retry-seconds` | `30` | How long a database write is retried before giving up. |
| `performance.key-material-refresh-seconds` | `30` | How often the add-on rereads which materials your keys use. |
| `performance.join-scan-delay-ticks` | `40` | How long after joining the player's inventory is checked, so inventory sync plugins finish first. |

> **Info:**
Only items made of a material one of your keys uses are ever read, so the checks cost almost nothing for every other item.

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/key-serialization