Sarmatia Economy System — specification

Core premise: simulates the economy of the Polish-Lithuanian Commonwealth (16th–17th century) in a simplified form.

Status legend:

• ✅ Implemented — works in-game
• 🔄 In progress — partially implemented
• 📋 Planned — on the roadmap
• 💡 Idea — to discuss

---

1. Vision and general principles

The system simulates the economy of the First Polish-Lithuanian Commonwealth in the 16th–17th century. The game is turn-based — each turn equals one calendar month, so a year consists of 12 turns. Calculations rely on a deterministic RNG seeded with the Hive block ID at turn close — anyone can verify results retroactively. The game places great emphasis on the proper balance of earnings and expenses, also adding mechanisms for burning money. The system is based on the HBD currency.

Key blockchain accounts:

Account	Role
sarmatia.app ✅	Chancellery — pays players (serf earnings), collects fees for parcels, new villages, and technologies
sarmatiapay 📋	Foreign trade — exclusively. In the future a connector between countries (when additional game versions exist)
sarmatia.gov ✅	The Crown — collects taxes, issues edicts, governs the capital (Warsaw)
null ✅	HBD burning — church costs, prayers, Crown building development

---

2. Turns and settlement mechanics

2.1 Action Points ✅

• Each player receives 10 Action Points (AP) per turn
• Points can be split between: production, construction, prayer, trade and transport
• By default all points go to production (if the player changes nothing)

2.2 Order of end-of-turn settlements ✅

1. Roll global events per voivodeship (deterministic, based on block_id)
2. Roll local events per parcel (prayers modify weights)
3. Building production (seasonal modifiers + voivodeship event + local event multiplicatively)
4. Construction progress from active upgrades (build actions → completion percent)
5. Prayer progress (prayer actions → percent)
6. Resource consumption by buildings + substitution
7. Recalculate serf population (growth/decline + bonus from local events)
8. Special local effects (e.g., jugglers' visit → -1 serf)
9. Income and taxes (capitation/land tax deducted from payout)
10. Auto HBD payout from sarmatia.app to player accounts
11. Close turn and open the next

2.3 Global events ✅

Rolled once per turn for each voivodeship. State prayers from the Church Holdings in the capital (section 10.5) can modify weights of global voivodeship events.

2.4 Local events ✅

Rolled independently of voivodeship events, once per turn per parcel. Probability weights modified by active prayers (Blessing increases positives, Protection decreases negatives) from local church.

Stacking with voivodeship: if both affect the same resource — effect is multiplicative.
Example: voivodeship drought (-30% grain) + local minor drought (-15% grain) = -40.5% grain.

---

3. Resources and population

3.1 Basic resources ✅

• 🌾 Grain (agri) — plant food
• 🐄 Livestock (animal) — animal products
• 🪵 Timber (wood) — construction resource
• 👨‍🌾 Serfs (serfs) — labor force and income source
• 💰 HBD — native Hive blockchain currency

3.2 Serfs ✅

• Consume all 3 basic resources (via buildings)
• Produce money: 0.001 HBD per serf per turn (paid by sarmatia.app)
• Growth: +10% per turn (min 1) if all resources available and free cottage slots exist
• Decline: -10% (min 1) if resource shortages persist ≥2 turns
• Manor cap: lvl 1 = 20, each next lvl = +2 (10% of 20)
• Cottage cap: number_of_cottages × 2 slots
• Effective cap = min(manor_cap, cottage_cap)
• NFT attribute: ±10% growth modifier (per parcel)

3.3 Idle serfs ✅

• Each building has serfsPerLevel (Farmlands/Livestock/Forest = 1, Workshop = 2)
• Cottages do not employ — they only house
• Idle = serfs - employed by active (enabled) buildings
• Starting a building upgrade requires ≥1 idle serf
• Disabling a building frees its serfs

3.4 Resource substitution ✅

When a building lacks its required resource — uses a substitute (whichever is most available):

Missing	Substitute	Ratio
grain	livestock	1:1
grain	timber	1:1
livestock	grain	2:1
livestock	timber	1:1
timber	grain	3:1
timber	livestock	2:1

---

4. Estates (parcels) and villages

4.1 Parcels ✅

Each parcel is an NFT with unique attributes. Attributes randomized at minting in the range -10% to +10% (per resource + per serfs).

• Total negative cap: -15%
• Maximum 2 negative attributes
• Attributes: agri_mod, animal_mod, wood_mod, serf_mod

4.2 Parcel types ✅

Type	Owner	Properties
player	player	Standard, serf production, taxes
capital	sarmatia.gov	Capital (Warsaw), Crown buildings, no serfs
royal_estate	sarmatia.gov	📋 Royal estates — future

4.3 Villages ✅

• Each parcel has at least one village
• First village = parcel NFT name (e.g., "Sztutowo", "Warszawa")
• Village count limit = Manor lvl (lvl 1 = 1 village, lvl 5 = 5 villages)
• Village capacity = 35–80 building slots (random at founding)
• Founding additional village = 1 HBD to sarmatia.app (Keychain transfer)
• Village location on map = geo_lat/geo_lng (pin)
• New villages receive: 5 cottages + 5 serfs + 50/30/30 starting resources (no Manor, no Church)

4.4 Per-village resources ✅

Resources and serfs are assigned to a village, not to the parcel:

• Each village has its own agri/animal/wood/serfs
• Warehouses in village → capacity for that village only
• Farmlands/Livestock/Forest → produce to that village
• Cottages → house serfs of that village only
• HBD (hbd_pending) is at the parcel level (single player wallet)

4.5 Building slot in a village ✅

• 1 building lvl = 1 slot
• 1 cottage = 1 slot
• Slot limit from village's capacity_limit

---

5. Player buildings

5.1 Building list

Building	Start	Produces	Consumes	Serfs	Seasons
🌾 Farmlands	lvl 1	grain (10/lvl)	livestock 1, timber 0.5	1/lvl	turns 3-10; 3/4/9/10: -10%, 5-8: +10%
🐄 Livestock	lvl 1	livestock (6/lvl)	grain 3, timber 1	1/lvl	1/2/11/12: -10%, rest: +5%
🌲 Forestry Complex	lvl 1	timber (4/lvl)	grain 1, livestock 1	1/lvl	constant
🔨 Workshop	lvl 0	+1% efficiency/lvl	grain 2, livestock 1, timber 1	2/lvl	constant
📦 Warehouses	lvl 1	+50 cap/lvl	—	0	constant
🏰 Manor	lvl 1	technologies, edicts, serf cap	—	0	initial village only
🏚 Cottages	5 units	2 serfs/unit, +0.001 HBD/serf	0.3 grain, 0.1 livestock, 0.05 timber	0	constant
⛪ Church	lvl 0	prayers	—	0	one per parcel
🌬 Windmill	lvl 0	(decoration, planned: bonus to farmland)	—	0	one per village, max lvl 1
🐎 Stable	lvl 0	caravans (resource transport between villages)	grain 4, livestock 1, timber 1	1/lvl + 1/100 cargo units	constant
⚔ Barracks	lvl 0	military (📋)	—	tba	disabled

5.2 Build costs ✅

5.3 Upgrade mechanics ✅

1. Click "Upgrade" → validation (resources, village slot, ≥1 idle serf)
2. Resources deducted immediately from village (HBD via Keychain for Church)
3. Building enters is_upgrading=1 with target_level
4. Player allocates build actions to that specific building
5. Each turn rolls progress per getBuildRoll(targetLvl, points)
6. After reaching 100% — level += 1, flags cleared, status active
7. Cancelling an upgrade refunds 50% of resources

5.4 Action points ✅

5.5 Enabling/disabling buildings ✅

• Every built building can be disabled (except Manor and Cottages)
• Disabled: doesn't produce, doesn't consume, frees serfs
• Allows juggling workers (e.g., free serfs for construction)

---

6. Church and prayers

6.1 Church ✅

• One per parcel (placeholder lvl 0 created at purchase)
• 6 levels with historical names:
  1. Chapel
  2. Filial Church
  3. Parish Church
  4. Collegiate Church (requires stone)
  5. Cathedral (requires stone)
  6. Archcathedral (requires stone)

6.2 Local prayers ✅

Two prayer types, can both be active simultaneously. Affect only local parcel events — don't change voivodeship-level events (those are modified only by state prayers from Church Holdings in the capital).

Type	Effect
🙏 Blessing	Increases weights of positive local events
🛡️ Protection	Decreases weights of negative local events

Mechanics:

• Activation: Keychain transfer 0.01 × 3^church_lvl HBD to null
  • Chapel (lvl 1): 0.030 HBD
  • Archcathedral (lvl 6): 7.290 HBD
• Progress: AP per prayer type, like construction
• Duration: after completion lasts 2 × church_lvl turns
• Efficiency: each lvl = +1pt% prayer effect

---

7. Player treasury and payouts

7.1 Treasury ✅

• Parcel treasury = HBD balance of player's Hive account (read-only via api.hive.blog)
• Cache 60s to avoid spamming the API
• After Keychain transfer cache is invalidated

7.2 Auto-payouts ✅

After turn processing:

• gross = serfs × 0.001 HBD
• capitation = serfs × rate (if enabled)
• land_tax = sum(levels) × rate (if enabled)
• net = gross - min(taxes, gross) (clamped to 0)
• Pay net from sarmatia.app → player Hive account
• Taxes → sarmatia.gov account

7.3 Costly operations (Keychain) ✅

Operation	Target	Amount
Church construction	null	3^lvl HBD
Prayer activation	null	0.01 × 3^lvl HBD
Founding a village	sarmatia.app	min 1 HBD
Buy parcel (Chancellery)	sarmatia.app	per pricelist
Buy parcel (player)	seller	listing price
Fundraiser contribution ✅	sarmatia.gov	any (no per-turn limit)
Technology adoption 📋	sarmatia.app	0.01 × 1.5^lvl HBD
Quarter Tax 📋	sarmatia.gov	min 0.001 HBD/year

---

8. Trade

8.0 Shared trade and transport limit (Phase 4.6.1+) ✅

Base limit: 100 units per resource for each player, counted separately (grain/livestock/timber).
Each AP allocated to trade/caravans gives 10% of the limit = 10 units per resource.

• 1 AP → 10 units
• 5 AP → 50
• 10 AP → 100 (full base limit)

Shared AP budget: actions of type trade (foreign trade — Phase 4.6.2) and caravan (caravans — Phase 4.6.1) draw from the same player AP pool (10/turn). For caravans the limit applies separately per direction (out_X ≤ limit AND in_X ≤ limit) — the wagon can be full both ways.

In the future the limit may be expanded by trade technology at the Academy (Phase 4.4).

8.1 Foreign merchants ✅ (sell) / 📋 (buy)

Fixed prices (HBD/unit):

Direction	Grain	Livestock	Timber
Player sells (100% success)	0.001	0.002	0.003
Buy from merchants	0.030	0.060	0.090

Buy limit = resources available at the state level (state_market lvl).
Tariff = percentage taken on transactions (to sarmatia.gov).

8.2 Royal Market 📋

• Offers from players + sarmatia.gov
• Lists filtered by resource, sorted by price/quantity
• Ability to split AP across various offers
• Market tax = percentage of transaction to sarmatia.gov

8.3 Direct exchange (barter) 📋

• Resource for resource, no conversion
• Possible turnover tax

---

9. Taxes

9.1 Definitions ✅ (structure) / 🔄 (collection, Quarter Tax)

Tax	Base	Period	Status
Capitation	serfs in parcel	each turn	✅ deducted from payout
Land tax	sum of all building levels	each turn	✅ deducted from payout
Quarter Tax	player, fixed amount	once a year (turn 1)	📋 Keychain payment to sarmatia.gov
Market tax	% of market transactions	per transaction	📋
Tariff	% of merchant transactions	per transaction	📋

9.2 Collection method ✅

• Capitation + land tax = automatic deduction from payout (player gets net)
• Maximum collected = gross income (clamped to 0)
• Turn report shows breakdown

9.3 Quarter Tax — enforcement 📋

• Non-payment by turn 6 → -50 merit points
• Negative merit < 0 at year start → enforcement in resources (per foreign merchant ratios)
• No resources → debt up to losing the parcel buildings("ruin")

---

10. The Crown (sarmatia.gov)

10.1 Architecture ✅

The capital = parcel of type capital with is_capital=1. Owned by default by sarmatia.gov. In the future ownership change is possible (siege/election).

Crown Treasury = HBD balance of sarmatia.gov from Hive (read-only).

10.2 Crown buildings ✅ (config) / 🔄 (upgrades via fundraiser)

Each Crown building stands in the capital village (Warsaw). Uses fundraiser mechanics instead of one-time cost.

Building	Function	Max lvl	Fundraiser cost	Start
🏛 Palace	Edicts, taxes	10	50 × lvl² HBD	lvl 1
🎓 Academy	Technologies	10	40 × lvl² HBD	lvl 0
⛪ Church Holdings	State prayers (effect on global events)	10	30 × lvl² HBD	lvl 0
🏛 Royal Market	Foreign merchant limit	10	25 × lvl² HBD	lvl 0
📦 State Warehouses	Trade interventions	10	20 × lvl² HBD	lvl 0
🐎 State Stable	State caravans (capital transport)	10	20 × lvl² HBD	lvl 1 ✅

State Stable (state_stable) is a separate type from stable (players) — upgrade
cost in HBD via fundraiser, like other state_*. The Crown starts at lvl 1 — state
transport works from the start of the game. Consumes flat upkeep 4/1/1 × lvl per turn.

10.3 Fundraisers ✅ (Phase 4.2 implemented)

Full flow described in section 17. Quick overview:

• sarmatia.gov opens a fundraiser (UI in Crown view or civic)
• HBD goal = govBuildingFundraiserCost(type, target_lvl) = base × lvl²
• Every citizen-player (Manor lvl ≥ 1 + active parcel) can contribute via Keychain
• Contributions go to @sarmatia.gov (Crown treasury, NOT to null)
• 1 HBD = 10 merit points (Math.floor); the Crown is exempt (operates state budget)
• After reaching the goal → status funded, the Crown clicks "Start construction" → flags is_upgrading=1 on the building
• Multi-turn construction with Crown AP (capital_build) → _processCapitalBuildings increases progress via getCapitalBuildRoll
• At 100% progress → level += 1, fundraiser closed_at = NOW()
• Cancellation by the Crown: status cancelled, contributions are NOT refunded (players keep merit)

10.4 Edicts ✅ (config) / 📋 (UI + activation)

Only one edict active at a time in the entire state.

Edict usage stages:

1. Unlock — HBD cost from treasury (one-time)
2. Activation — HBD cost + Crown player AP

Unlock progression: every 2 Palace lvls → new edict "tier".

Edict	Palace	Duration	Cooldown	Effect
Production support I	lvl 1	3 turns	—	+5% production
Production support II	lvl 3	3 turns	—	+10% production
Production support III	lvl 5	3 turns	—	+15% production + 5% serf earnings
Infrastructure works I	lvl 1	3 turns	—	+5pt to construction roll
Infrastructure works II	lvl 3	3 turns	—	+10pt to roll
Infrastructure works III	lvl 5	3 turns	—	+15pt to roll + 5% cheaper (resources)
Levée en masse	lvl 5	3 turns	—	placeholder (military module)
Great Sejm (edict)	lvl 7	12 turns	24 turns	-10% edict costs + -10% gov building costs + +10% production

⚠ Note: "Great Sejm (edict)" is a short-term economic effect issued from the Palace — don't confuse it with the proper Sejm (phase 4.7), which is a separate voting mechanism with envoys.

10.5 State prayers (Church Holdings) 📋

Activated by the King (sarmatia.gov) from the Church Holdings in the capital.
Affect weights of global (voivodeship) events — unlike player churches, which only affect local parcel events.

Mechanics analogous to local prayers but one level up:

• Activation: HBD cost from Crown treasury to null (large scale)
• Progress: Crown action points (analogously to local prayers)
• After completion: bonus active for X turns (depending on Church Holdings lvl)

Type	Effect
🙏 State Blessing	Increases weights of positive global events in all voivodeships
🛡 State Protection	Decreases weights of negative global events in all voivodeships

Efficiency: each Church Holdings lvl = +1pt% weight modification.

Stacking with local prayers:

• State prayers → global event weights (bumper crop, drought, plague, pestilence, forest fire)
• Local prayers → local event weights (minor effects)
• Both can be active at once — they affect different layers

10.6 Sejm — voting mechanism 📋 (Phase 4.7)

Independent of Palace edicts. Simulates the historical Great Sejm of the Polish-Lithuanian Commonwealth.

Representative democracy:

• Each voivodeship elects envoys in a local sejmik (only parcel owners from that voivodeship vote)
• Envoy term: tba (e.g. 12 turns)
• Only envoys vote at Sejm sessions

Opening a Sejm session:

• Initiated by sarmatia.gov (e.g., once a year) or by majority of envoys
• Session lasts X turns — during this time envoys vote on proposals

Possible proposals:

• Extraordinary taxes (e.g., war tax, coronation tax)
• Change of tax rates (capitation, land tax, quarter tax)
• Approving/blocking royal edicts
• Election of Hetman, Chancellor (future)
• In case of throne vacancy — call for royal election (phase 4.8)

Planned DB tables:

• eco_envoys (envoy, voivodeship, term)
• eco_sejm_sessions (session, status, opened_in_turn)
• eco_sejm_proposals (proposals + votes)
• eco_sejm_votes (envoy, proposal, vote)

10.7 Technologies (Academy) 📋

Three paths:

• Infrastructure — +1pt% construction efficiency + increases village cap per lvl
• Trade — turnover limit: (1/526) × lvl² × 10 units
• Administrative — +1pt% edict efficiency per lvl

Each Academy lvl unlocks 5 tech levels to research.

Costs:

• Research (by the Crown): 1 × 1.5^lvl − 1 HBD to sarmatia.app
• Player adoption: 0.01 × 1.5^lvl HBD to sarmatia.app

---

11. Merit points

11.1 Sources of points

Source	Points	Status
Fundraiser contribution	1 HBD = 10 pt (Math.floor(amount × 10))	✅
Quarter Tax not paid by turn 6	-50 pt	📋
Holding envoy office	tba	📋
Special edicts	tba	📋

Exception: the sarmatia.gov account (the Crown) does NOT receive merit for fundraiser contributions — it operates the state budget, merit points apply to citizens, not the office.

11.2 Usage

• ✅ Visible in the civic tab (top 10 + player ranking, link to /galeria-slaw)
• 📋 Top 10 by merit → candidates for royal election (Phase 4.8)
• 📋 Vote weight in the voivodeship sejmik (Phase 4.7)
• 📋 Priority in trade / enforcement
• 💡 In future: family prestige, access to offices

---

12. Phase roadmap

Implemented ✅

• Phase 1 — Economy foundation: parcels, villages, buildings, resources, serfs, taxes, foreign trade (sell), turn system
• Phase 2 — Estate system expansion: "Upgrade" mechanic, unit-based cottages, church + prayers, blockchain treasury, founding villages
• Phase 3 — Crown architecture: capital as parcel, 5 Crown buildings, edict config, fundraiser schema

Implemented (continuation)

• Phase 4.2 — Fundraisers ✅: opening fundraisers by the Crown, Keychain contributions (players → Hive account@sarmatia.gov), automatic merit (1 HBD = 10 merit), multi-turn construction with AP (capital_build), finalization in _processFundraisers — see section 17
• Phase 4.3 — Edicts ✅: unlocking (Keychain), multi-turn Palace deliberations (HBD start + AP per turn), effects in TurnProcessor (productionMultiplier, serfIncomeMultiplier, buildRollBonus), cooldown
• Phase 4.6.1 — Transport (caravans) ✅: new type stable (player, resources) + state_stable (Crown, HBD), eco_caravans table, 3 endpoints launch/cancel/list, _processCaravans with phases outbound→at_dest→return→completed, Haversine + 80km/turn, drivers 1/100 max(out,in), new 🐎 Transport tab, launch modal with live calculations — see section 19
• Harder rolls for the capital ✅: getCapitalBuildRoll (5×AP min, 40+10×AP max) — used for edict deliberations, Crown building construction, in the future for technologies and state prayers
• Stylized modals ✅: Modal.js (showInfo/showError/showWarning/showConfirm/showActions) replaces native alert/confirm — Promise-based, Sarmatian climate (Caudex/Brygada 1918, gold-light)
• Village visualization ✅: stylized board (Variant B), village_bg.webp background + sprites per type with lvl thresholds, animations (smoke/rotor/lumberjack), cottage scaling (5 slots) and farmland (4 zones), animated "construction site" construction.webp (1.4 MB animated WebP) — see section 15
• Mobile tabbar as icons-only ✅: (max-width: 700px) hides tab text, larger icon, title attribute for long-press
• Civic tab ✅: civic affairs — fundraisers, edict, treasury, top 10 merit, placeholders for Quarter Tax/sejmik/election — see section 18
• Windmill as decorative building ✅: new type with animated rotor blades, max lvl 1, one per village; in the future will give bonus to Farmlands (section 5.1)

Planned 📋

• Phase 4.4 — Technologies (Academy): 3 paths, tree, per-player adoption
• Phase 4.5 — State prayers (Church Holdings)
• Phase 4.6.2 — Foreign trade (via Stable + Royal Market): foreign merchants, shared limit with caravans (10u/AP/resource), Quarter Tax via Keychain
• Phase 4.6.3 — Allied caravans: cross-parcel transport, route map on main view, barter with allies
• Phase 4.7 — Sejm and envoys: local elections (sejmiks), representative democracy, additional Sejm taxes
• Phase 4.8 — Royal election: top 10 merit, citizen voting, posting key transfer
• "Ruin" mechanic (inactive parcel): loss of citizen rights (no civic tab access), when parcel is inactive too long

Pre-launch 🚀 (before opening for real payments)

• Phase 5.0 — NFT integration (Hive Engine): minting parcels with attributes, GeoJSON ↔ NFT_id mapping, transfer at purchase
• Phase 5.1 — Purchase process (EU e-commerce): full checkout flow, GDPR, terms, invoices (see section 14)

Distant horizon 💡

• Phase 6 — Cities and guilds: membership, mining concessions, advanced resources (stone, metals), NFT products
• Phase 7 — Battle module: barracks, units, battles, alliances, capital sieges
• Phase 8 — International trade: sarmatiapay connector, second country (e.g., German Empire), real resource exchange between games