⚔️ LEDGER QUEST

A Nintendo-style 8-bit adventure game that showcases Formance Ledger features through gameplay.

"The Evil Auditor tried to rewrite the Ledger. But the Hash Chain exposed his fraud. Only the Ledger Knight can verify the truth and restore order."

---

⚡ Quick Start

Option A — Standalone (no dependencies)

# Just open it in a browser
open index.html

Option B — With a local dev server

npx serve . -p 3000
# Open http://localhost:3000

Option C — Connected to a real Formance Ledger

# Start a Formance Ledger on port 3068
docker run -p 3068:3068 ghcr.io/formancehq/ledger:latest serve

# Then open the game — it auto-connects and creates a ledger in the "ledgerquest" bucket
open index.html

When connected to a real ledger, the HUD shows a green LIVE indicator and every in-game transaction is mirrored as a real Formance Ledger transaction you can query via the API. Each game session creates a unique ledger named ledgerquest-<timestamp> inside the ledgerquest bucket:

# List ledgers to find the current game session
curl http://localhost:3068/v2/ | jq '.cursor.data[] | .name'
# → "ledgerquest-1773413892220"

# Use the ledger name from above in all queries:
LEDGER="ledgerquest-1773413892220"

# See all game transactions
curl http://localhost:3068/v2/$LEDGER/transactions | jq

# Check the hero's account
curl http://localhost:3068/v2/$LEDGER/accounts/hero:wallet | jq

# Check an enemy's account
curl http://localhost:3068/v2/$LEDGER/accounts/courtyard:s1 | jq

---

🎮 Controls

Key	Action
Arrow Keys / WASD	Move
Space	Attack (sword swing)
E	Interact (talk to NPCs, open chests)
F	Throw Fire Bomb (if carrying bombs)
T	Time Rewind (in Temple, requires Temporal Insight)
E (Holy Ledger)	Open the Sacred Ledger terminal (requires all 3 Integrity Sigils)
Shift (hold)	Fast-forward dialog (4× speed, auto-advance)
M	Mute / Unmute music (SFX stay on)
ESC	Pause / Resume
Enter	Start game / advance dialog

---

📖 Story

The Kingdom of Formance runs on a magical ledger that records every gold coin flowing through the realm. The Evil Auditor tried to falsify the kingdom's records, but the Hash Chain detected every lie — and the Ledger sealed itself for verification. Three Integrity Sigils — proof fragments scattered across the Mint — must be recovered to verify the chain's integrity. You play as the Ledger Knight, tasked with fighting through enemies, collecting sigils, freeing the imprisoned Time Monk, and proving the truth of every transaction.

Your journey begins in the Hall of Origins, where the Ledger Sage teaches you the way of the ledger and a Farmer begs you to catch his runaway Golden Goose. In the Courtyard, you'll battle slimes, chase the goose for golden eggs, and trade with the Blacksmith — whose forge runs on Numscript scrolls, the ledger's scripting language. Each purchase triggers a treasure chest pop animation as your items are forged.

Deeper in, the Wizard of Worlds reveals the power of the world account — an infinite wellspring from which gold is born and to which it returns. The Ghost Twins (Debit & Credit) perform a live multi-posting transaction — your gold flows through three accounts in a single atomic scroll. The mischievous Refund Imp offers to bulk-revert every coin monsters ever stole from you… for a price.

Below lies the Forgotten Crypt, where a Ghost Banker teaches the lesson of INSUFFICIENT_FUNDS — what happens when you try to spend more than you have. The Ledger rejects the transaction entirely: no partial moves, no negative balances. Beyond the Wizard's sealed gate, the Temple of Time awaits — where Temporal Wraiths guard an imprisoned Time Monk who holds the secret of bi-temporality: the power to record transactions with past effective dates. Free him, and he grants you the ability to see through time itself — the Ledger replays all that followed from the new event.

Collect all three Integrity Sigils to unseal the Holy Ledger — an interactive terminal that lets you browse every account, transaction, and chain block in the kingdom — then face the Evil Auditor in the Treasury to verify the ledger's integrity once and for all.

---

🧑‍🤝‍🧑 Characters

🛡️ The Ledger Knight (Player)

    ██
   ████
  ██▓▓██        hero:wallet
  ██▓▓██        ───────────
   ████         GOLD: ???
  ██████        SIGIL: 0/3
  █ ▓▓ █
  █ ▓▓ █

• Account: hero:wallet
• The hero whose every action is recorded on-chain. Your gold balance, input/output volumes, and transaction history are displayed on the HUD in real-time. When carrying SHIELD, a blue shield overlay appears on the sprite.

🧙 Ledger Sage

• Location: Hall of Origins — Role: Tutorial NPC
• Explains the basics: transactions, accounts, and how the ledger tracks everything. Hints at the three Integrity Sigils and the Temple of Time.

🌾 Farmer

• Location: Hall of Origins — Role: Quest giver
• His Golden Goose has escaped to the Courtyard! Catch it for a golden egg.

🪿 Golden Goose

• Location: The Courtyard (roaming) — Role: Chase mini-game
• A fast-moving golden goose that flees when you get close. Catch it to receive a golden egg (GOLD from world). Gets faster each time you catch it.

🚶 Wandering Pilgrim

• Location: The Courtyard — Role: Lore NPC
• A traveler who has heard of the Temple of Time and the imprisoned monk.

⚒️ Blacksmith — NUMSCRIPT SHOWCASE

 ┌─────────────────────────────────┐
 │  THE BLACKSMITH'S FORGE         │
 │                                 │
 │  🛡️ Shield Pack (3) .... 30G    │
 │  💣 Fire Bombs (5) .... 40G     │
 │  🌀 Swirl Scroll ..... 50G     │
 │                                 │
 │  send [GOLD 30]                 │
 │    (source = @hero:wallet       │
 │     destination = @shop:forge)  │
 │  send [SHIELD 3]                │
 │    (source = @shop:forge        │
 │     destination = @hero:wallet) │
 └─────────────────────────────────┘

• Account: shop:forge — Location: The Courtyard
• Every purchase executes a Numscript scroll — Formance Ledger's domain-specific language for multi-asset atomic transfers. The dialog shows actual Numscript code: multiple send blocks in one script, each moving a different asset, executed atomically.

🔮 Wizard of Worlds — THE WORLD ACCOUNT

• Account: world — Location: Wizard's Chamber
• In Formance Ledger, the world account represents external funds entering the system. Any transaction from world creates money; any transaction to world destroys it. The wizard gives you 100 GOLD — watch the transaction receipt float up!

👻 Ghost Twins — MULTI-POSTING TRANSACTIONS

• Location: Wizard's Chamber
• Two spectral figures (Debit & Credit) who perform a live multi-posting transaction: Debit takes 1 GOLD from you, passes it to Credit, and Credit gives you back 2 GOLD — three accounts, three movements, one atomic scroll. They demonstrate that a single transaction can chain multiple source→destination postings atomically.

😈 Refund Imp — BULK REVERT

• Location: Wizard's Chamber
• A mischievous green imp who can reverse all damage-penalty transactions at once — a bulk revert. Every coin monsters stole from you is returned in one spell. Costs HP with escalating price: 1 HP first use, 2 HP second, 3 HP third, etc.

💀 Ghost Banker — INSUFFICIENT_FUNDS

• Account: ghost:vault — Location: The Forgotten Crypt
• A spectral banker who tried to spend more gold than they had. The Ledger refused the transaction — INSUFFICIENT_FUNDS. Now they haunt the crypt, doomed to replay their failed transaction for eternity. On first encounter, the ghost attempts to send 1,000 GOLD (with only 5 in their vault) — you see the red TX REJECTED animation. Then they send what they actually have: 5 GOLD. The lesson: the Ledger only moves what truly exists in the source account.

🟢 Slime Enemies

   ████          Each slime has its own
  ██○○██         ledger account:
  ██████           courtyard:s1
  ██████           courtyard:s2
   ████            courtyard:s3
 Green  Blue  Red  Orange
  10G    15G  25G   20G

• Accounts: courtyard:s1, courtyard:s2, courtyard:s3, etc.
• When entering a room for the first time, all enemies are funded in a single multi-posting mint transaction. When you defeat a slime, an atomic transaction transfers their entire gold balance to your wallet.

👻 Temporal Wraiths & 🪲 Chrono Beetles

• Location: Temple of Time — Accounts: temple:tw1, temple:cb1, etc.
• Ghostly purple wraiths and armored cyan beetles that guard the Temple. Defeating all of them frees the Time Monk from his chains.

⏳ Time Monk — BI-TEMPORALITY

  ┌────────────────────────────────────┐
  │ Every deed has TWO moments:        │
  │                                    │
  │   📝 insertion date                │
  │      when it was WRITTEN           │
  │                                    │
  │   ⏰ effective date                │
  │      when it truly HAPPENED        │
  │                                    │
  │ A deed can be written TODAY...     │
  │ ...yet speak of something that     │
  │ happened YESTERDAY.                │
  └────────────────────────────────────┘

• Location: Temple of Time (imprisoned)
• Once freed, he teaches you about bi-temporality: every deed has two moments — when it was written (insertion date) and when it truly happened (effective date). Grants the Temporal Insight ability — press T to create a transaction with a past effective date. The Ledger replays all that followed from the new event, recomputing effectiveVolumes.

👑 The Evil Auditor — BOSS

     ▓█▓
    █████         treasury:boss
   ███○███        ─────────────
   ███████        HP: 15
   ███████        GOLD: 100
    █████

• Account: treasury:boss — Location: The Treasury
• A crowned dark-red slime boss who tried to rewrite the kingdom's transactions but was caught by the Hash Chain. Defeating it triggers the victory screen — "LEDGER INTEGRITY VERIFIED!" — with a full Ledger Report showing your final balance, total transactions, Integrity Sigils, and temporal insight status.

---

🗺️ Rooms

The game takes place in a single bucket called the-mint, with 6 connected rooms:

                          ┌───────────┐
                          │ TREASURY  │
                          │  (boss)   │
                          │  🔒 seal  │
                          └─────┬─────┘
                                │
┌────────────┐  ┌───────────┐  ┌┴──────────┐  ┌──────────────┐
│  HALL OF   ├──┤ COURTYARD ├──┤  WIZARD'S  ├──┤  TEMPLE OF   │
│  ORIGINS   │  │           │  │  CHAMBER   │  │    TIME      │
│  (start)   │  │ ⚒️ forge  │  │ 🔮 world  │  │  ⏳ monk     │
└────────────┘  └───────────┘  └┬──────────┘  │  📖 ledger   │
                                │              └──────────────┘
                          ┌─────┴─────┐
                          │ FORGOTTEN │
                          │   CRYPT   │
                          └───────────┘

1. Hall of Origins — mint:hall_of_origins

• Stone floor with red carpet. Ledger Sage, Farmer NPC, Integrity Sigil #1.
• Safe starting room. Talk to the Sage to learn the basics.

2. The Courtyard — mint:courtyard

• Grass + stone paths + water + bridges. 3 slime enemies, Golden Goose, Wandering Pilgrim, Blacksmith Grindak, Integrity Sigil #2.
• Your first combat zone. Defeat slimes, buy shields & bombs, chase the Goose!

3. Wizard's Chamber — mint:world_chamber

• Wood floor + red carpet. Wizard of Worlds, Ghost Twins, Refund Imp, Integrity Sigil #3.
• The path north to the Treasury is sealed — collect all three Integrity Sigils to break through.

4. The Forgotten Crypt — mint:crypt

• Dark stone floor. 3 slimes, 2 beetles, Ghost Banker NPC, 2 treasure chests, heart pickup.
• A dark underground crypt. The Ghost Banker teaches INSUFFICIENT_FUNDS protection. Fight enemies and loot chests before facing the boss.

5. The Treasury — mint:treasury

• Stone floor with gold piles and corruption vents. 2 red slimes, 1 orange slime, The Evil Auditor boss.
• The boss arena. Defeat all enemies and the Evil Auditor to win.

6. Temple of Time — mint:temple_of_time

• Marble floor + stained glass. 3 Temporal Wraiths, 2 Chrono Beetles, imprisoned Time Monk, Holy Ledger.
• Defeat all enemies to free the Monk. Use T for backdated transactions. Open the Holy Ledger with E once all 3 shards are collected.

---

📊 Ledger Features Showcased

Every game mechanic maps to a real Formance Ledger concept:

Game Mechanic	Ledger Feature	How It's Shown
💰 Collecting gold	Transactions with postings	Every coin pickup creates a { source, destination, asset, amount } posting
📊 HUD balance	Account balances	Real-time display of hero:wallet balance
📈 in/out volumes	Account volumes	HUD shows cumulative in: and out: for GOLD
🟢 Enemy accounts	Multi-account system	Each enemy has its own account; room entry mints GOLD to all enemies in one multi-posting TX
🔮 world wizard	The world account	Special account with infinite balance for fund creation
🧾 TX receipts	Transaction records	Floating receipts show TX ID and amount
🔗 LOG block counter	Append-only LOG (hash chain)	LOG:N in HUD grows with each TX
📦 Bucket label	Bucket isolation	HUD shows current bucket (the-mint)
🏷️ Room accounts	Hierarchical addresses	Addresses like mint:courtyard, courtyard:s1
📦 Chest opening	TX from world	Chests create world → hero:wallet transactions
⚔️ Enemy defeat	Atomic transfers	Enemy's full balance atomically transferred in one TX
👻 Ghost Twins	Multi-posting TX	Single TX with three postings: hero→debit→credit→hero, 3 accounts in 1 scroll
😈 Refund Imp	Bulk revert	All damage-penalty TXs reversed in one ritual
⏳ Time Rewind	Backdated transactions	Creates a TX with a past timestamp; response shows effectiveVolumes
🔷 Integrity Sigils	SHARD asset	Verification proof fragments tracked alongside GOLD
💀 Ghost Banker	INSUFFICIENT_FUNDS	Failed TX demo: source account can't go below zero
⚒️ Blacksmith shop	Numscript DSL	Purchase dialog shows send blocks for multi-asset atomic transfers
🛡️ Shield item	Multi-asset accounts	SHIELD asset consumed on damage via hero → world TX
💣 Fire Bombs	Asset consumption	BOMB asset tracked on ledger, each throw creates TX
🌀 Swirl Scroll	Asset-gated abilities	SWIRL asset unlocks combo ability
📖 Holy Ledger	Account/TX browsing	Interactive terminal to browse accounts, transactions, and chain integrity
🏆 Boss victory	Ledger report	Final screen shows balance, volumes, shards, temporal insight

🟢 LIVE Mode (Real Ledger Connection)

When a Formance Ledger is running on localhost:3068, the game:

1. Creates a ledgerquest-<timestamp> ledger in the ledgerquest bucket automatically
2. Mirrors every in-game transaction to the real API (POST /v2/ledgerquest-<timestamp>/transactions)
3. Uses force: true for world transactions (infinite source)
4. Sends backdated transactions with timestamp for bi-temporality (T key)
5. Shows a green LIVE dot in the HUD
6. Maintains a local simulation as the gameplay source of truth (API failures don't break the game)

You can query the real ledger during or after gameplay to see the full transaction history, account balances, and volumes — exactly as they would appear in a production financial system.

---

🏗️ Architecture

index.html (single file, ~5600 lines)
├── NES-inspired palette (custom dark theme, 20+ colors)
├── Pixel art sprite system (Link-style 16x16 sprites, 4 directions x 2 frames)
├── Simulated ledger engine (accounts, transactions, hash chain)
├── Real Ledger API client (fetch-based, fire-and-forget sync)
├── Web Audio music engine (5 themes: adventure, boss, temple, wizard, title)
├── Particle system (hit effects, gold sparkles, death explosions)
├── Dialog system (typewriter text, multi-line word wrap, choices, Shift fast-forward)
├── Tile-based room renderer (9 tile types including marble, stained glass)
├── Entity system (player, enemies, NPCs, items, Golden Goose AI)
├── Combat system (sword hitbox, knockback, damage, HP bars, power-ups, shield overlay, swirl AoE)
├── Bomb projectile system (throw, flight, AoE explosion, asset consumption)
├── Blacksmith shop system (Numscript DSL showcase, multi-asset atomic purchases: shields, bombs, swirl)
├── Decor system (torches, pillars, bookshelves, stained glass, portals, forge, anvil)
├── Holy Ledger terminal (interactive account/TX/chain browser after collecting all shards)
├── Breakable relic system (Integrity Sigil collectibles across 3 rooms)
├── Transaction animation system (floating receipts)
├── HUD (account info, volumes, LOG chain, shard count, API status)
├── Pause system (ESC to pause/resume, Web Audio suspend/resume)
├── Music mute toggle (M key, mutes theme only, SFX remain audible)
└── Game loop (60fps, requestAnimationFrame)

Canvas: 256×240 (classic NES resolution), scaled 3× to 768×720

No dependencies. Pure HTML5 Canvas + vanilla JavaScript. Works offline.

---

🛠️ Extending the Game

Adding a new room

Add an entry to the ROOMS object with a map (16×12 grid), npcs, enemies, items, decor, and exits. Add a breakable relic entry in BREAKABLE_DECOR if the room should contain a Integrity Sigil.

Adding a new enemy type

Add an entry to a room's enemies array. Set type, hp, gold, and color. The ledger auto-creates an account for each enemy. Add rendering logic in the enemy draw function.

Adding a new NPC

Add to a room's npcs array with id, name, lines (dialog), and optionally giveGold for gift transactions. Special NPC behaviors (like the Twins or Refund Imp) can be added with custom flags.

Adding a new music theme

Add a playThemeName() method to the AUDIO object using startLoop(name, bpm, totalBeats, scheduleFn). Update loadRoom() to trigger the theme for the appropriate room.

Modifying the ledger bucket

Change ledger.bucket and API.ledgerName to use a different bucket/ledger name.

---

📡 API Reference (When Connected)

Each game session creates a unique ledger named ledgerquest-<timestamp> (e.g. ledgerquest-1773413892220) in the ledgerquest bucket. Find the name first, then query away:

# Find your game ledger (most recent first)
curl http://localhost:3068/v2/ | jq '.cursor.data[] | .name'
# → "ledgerquest-1773413892220"

LEDGER="ledgerquest-1773413892220"

# List all game accounts
curl http://localhost:3068/v2/$LEDGER/accounts | jq

# Get hero's full account with volumes
curl "http://localhost:3068/v2/$LEDGER/accounts/hero:wallet?expand=volumes" | jq

# List all transactions
curl http://localhost:3068/v2/$LEDGER/transactions | jq

# Get a specific transaction with effective volumes
curl "http://localhost:3068/v2/$LEDGER/transactions/1?expand=effectiveVolumes" | jq

# Get aggregated balances
curl http://localhost:3068/v2/$LEDGER/aggregate/balances | jq

# Count total transactions
curl -I http://localhost:3068/v2/$LEDGER/transactions
# Look for the Count header

---

🙏 Credits

Built to showcase Formance Ledger — a programmable financial ledger for money-moving applications.

Game concept and implementation generated with Claude.