FAQ & Reward Receiver Setup

This page explains how votes work on Hytale Server List and how to enable vote rewards with the site's HTTP plus RSA receiver contract.

How voting works

When a player votes, the site validates the request (including anti-spam cooldown checks) and increments your server's vote totals.

Players can vote once every 24 hours per server. After voting, you'll need to wait until the cooldown expires before voting again for the same server.

If you configure the reward receiver settings, we will also attempt to deliver a vote notification to your server so you can award in-game rewards.

Reward receiver setup (step-by-step)

1) Choose a receiver on your server host

You need a public HTTP receiver that can accept vote notifications and trigger rewards. This project currently sends vote notifications using an HTTP POST to your configured port.

If you're using a standard Votifier plugin (TCP-based) you may need an adapter/plugin that matches this site's delivery format.

2) Pick a public port

Select a port (example: 8192) and ensure your firewall allows inbound traffic to that port on the same host your receiver runs on.

3) Generate an RSA keypair

Your server-side receiver should generate an RSA keypair. You will paste the public key into your server listing on this site.

What to paste into the dashboard

Paste the base64 content of your RSA public key (without the BEGIN/ENDlines). This matches how vote delivery is built in the API.

4) Enter settings on your server listing

Go to Dashboard → Add/Edit Server and fill in:

Receiver Port

The port your receiver listens on

Receiver Public Key

Base64 RSA public key (no header/footer)

5) Test a vote

Visit your server page and submit a vote. The vote will always update counts; vote delivery runs in a best-effort manner and is retried automatically if your receiver is unavailable.

Troubleshooting

Votes increase but rewards do not trigger

Confirm your receiver is reachable from the public internet on the configured port, and that it supports the site's vote delivery format (RSA encrypted payload, base64, via HTTP POST).

Port is open but nothing arrives

Verify firewall rules and that the receiver is bound to the correct interface (not localhost-only). If you're using a hosting panel, also confirm the port is allowed.

Key format issues

Paste only the base64 public key content. Do not include any header/footer lines.

Manage your server settings

Reward Receiver API

When a player votes, we send an RSA-encrypted JSON payload via HTTP POST to your configured port. Your receiver must decrypt the payload and respond appropriately.

Request Format

We POST to http://<your-ip>:<votifier-port>/

// Headers
Content-Type: application/json
X-Batch-Rewards: true  // Present for batch deliveries

// Body (RSA-encrypted, base64-encoded)
// After decryption, you'll get:
{
  "rewards": [
    {
      "username": "player123",
      "timestamp": 1704567890,
      "serviceName": "Hytale Server List",
      "address": "1.2.3.4"
    }
  ]
}

Response Options

Your server must respond with JSON to acknowledge receipt. The response determines retry behavior:

Option 1: All Received (Success)

{ "status": "received" }

All rewards delivered successfully. We stop retrying.

Option 2: Partial Success

{
  "status": "partial",
  "pending": ["player456", "player789"]
}

Only listed usernames still need rewards. We'll retry those.

Option 3: Error / No Response

{ "status": "error", "message": "..." }
// OR timeout / connection refused

We'll retry all rewards with exponential backoff.

Decryption Example (Hytale Java Plugin)

import javax.crypto.Cipher;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import org.json.*;

public class VoteReceiver {
    private PrivateKey privateKey;
    
    public void loadPrivateKey(String base64Key) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(base64Key);
        PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
        KeyFactory kf = KeyFactory.getInstance("RSA");
        this.privateKey = kf.generatePrivate(spec);
    }
    
    public String handleVoteRequest(String base64Body) throws Exception {
        // Decrypt payload
        byte[] encrypted = Base64.getDecoder().decode(base64Body);
        Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
        cipher.init(Cipher.DECRYPT_MODE, privateKey);
        byte[] decrypted = cipher.doFinal(encrypted);
        String json = new String(decrypted);
        
        // Parse JSON
        JSONObject payload = new JSONObject(json);
        JSONArray rewards = payload.getJSONArray("rewards");
        
        // Process each reward
        for (int i = 0; i < rewards.length(); i++) {
            JSONObject reward = rewards.getJSONObject(i);
            String username = reward.getString("username");
            giveReward(username);
        }
        
        // Return success
        return "{\"status\": \"received\"}";
    }
    
    private void giveReward(String username) {
        // Your reward logic here
    }
}

Retry & Expiry

If your server is offline or doesn't respond, we automatically queue the reward for retry with exponential backoff.

Retry Schedule

1min → 5min → 15min → 1hr → 4hr → 12hr → 24hr → 48hr → 72hr

Max Attempts

10 attempts over ~7 days

Expiry

Pending rewards expire after 7 days

Batch Size

Up to 50 rewards per request

Important: Votes are always counted immediately. Reward delivery is separate and retried independently. Your server ranking won't be affected by delivery failures.