🌐 REDISTRIBUTE THE SOVEREIGN ECONOMY

📦 WHAT'S IN THE PACKAGE

The Sovereign Economy is a complete, self-contained virtual marketplace. Here's everything included:

⚙️ INSTALLATION: New World Setup

1 Prerequisites. Node.js 18+, SQLite3, Express.js. Your server needs dbAll, dbGet, dbRun helpers and requireLogin / requireAdmin middleware (adapt to your auth).

2 Extract the package.

tar -xzf sovereign-economy-v1.tar.gz
cd sovereign-economy

3 Create the tables.

sqlite3 your-database.db < schema.sql

4 Seed items and settings.

sqlite3 your-database.db < seed_items.sql
sqlite3 your-database.db < seed_settings.sql

5 Integrate API routes. The routes in server_routes.js reference these helpers — implement or adapt:

• getSettings() / setSettings() — key-value settings store
• economyEnabled(system) — checks economy_{system}_enabled === '1'
• getItemDef(defId) — fetch from economy_items
• userOwnsItem(userId, defId, qty) — sum inventory
• userCoins(userId) — sum ledger
• transferCoins(from, to, amount, reason) — atomic ledger entries
• transferItem(from, to, defId, qty) — atomic FIFO inventory move
• sendMail(userId, subject, body, itemsJson, coins) — insert into economy_mail
• economyRateLimit(userId, action, maxPerMinute) — in-memory throttle

6 Add the views. Copy view functions from views.js into your template system. Required: economyPanels, adminEconomy, intaglioGallery, creatorsHandbook, economyGuide.

7 Copy the three.js module. Place economy-pickup.js in your public directory.

8 Start the auction expiry job. Call resolveExpiredAuctions() every 5 minutes via setInterval or your scheduler.

9 Verify. Visit /api/economy/health — all tables should report "ok".

🎛️ CONFIGURATION: Make It Yours

After installation, customize for your world:

• Currency name — change economy_currency_name in settings. "Coins", "Credits", "Shards" — whatever fits your world.
• Item prices — update price_cents in economy_items to match your world's economy scale.
• Add your own items — follow the five-question framework in the Creator's Handbook. Keep the intaglio style or develop your own visual language.
• Crafting recipes — edit the CRAFTING_RECIPES array to add your own chains.
• Vendor placement — put vendors at meaningful locations in your 3D world.
• Battle pass seasons — name them for your world's lore and calendar.

🔄 SYNCHRONIZATION: Stay Connected

Your world can synchronize with the sovereign world (this one) at three levels. Choose what fits:

Level 1: Item Definition Sync (one-way)

Pull the latest item definitions from the sovereign world to keep your catalog current.

# Export from sovereign:
sqlite3 /opt/epistles/data/epistles.db   "SELECT def_id, name, description, kind, price_cents, stackable    FROM economy_items ORDER BY id;" > items.csv

# Import to your world (adapt to your tooling):

Run this monthly, or when new sets are announced. Your local prices and custom items are preserved — only new def_ids are added.

Level 2: Cross-World Mail

Send items and coins between worlds via API bridge. Both servers need a shared API key.

// On World A: export a gift
POST https://world-b.example.com/api/federation/receive
Headers: { "X-Federation-Key": "shared-secret" }
Body: {
  "from_world": "world-a",
  "to_user": "player-name-or-id",
  "subject": "Gift from World A",
  "items": [{ "def_id": "kings-intaglio-seal", "qty": 1 }],
  "coins": 1000
}

// On World B: implement /api/federation/receive
// Validate key → look up user → call sendMail() → return { ok: true }

Level 3: Shared Auction House (two-way)

The most ambitious: a unified marketplace across worlds. Listings from all worlds appear in one place.

This requires:

• A central auction index (or each world polls the others)
• Cross-world escrow (items held on origin world until sale completes)
• Settlement protocol (coins transferred via federation API on sale)
• Agreed fee split (suggested: 3% origin world, 2% listing world)

🤝 FEDERATION PROTOCOL

For worlds that want deep integration, follow this protocol:

Identity

Each world has a unique world_id (e.g. sovereign-prime, your-world-name). Include it in all cross-world messages.

Item Namespace

Item def_ids are globally unique. Prefix custom items with your world: myworld-custom-sword. Sovereign items use unprefixed IDs.

Trust Model

• Verify, don't trust. Each world validates incoming transfers independently.
• Idempotency. Every cross-world transfer has a unique ID. If retried, the receiver checks for duplicates.
• Reversibility. Failed transfers roll back on both sides. No partial states.
• Audit trail. Log every federation event with timestamps on both worlds.

Version Compatibility

Check manifest.json version before syncing. Major version changes may break compatibility — test in isolation first.

📜 TERMS OF REDISTRIBUTION

Questions about redistribution? Contact the sovereign world admin.