AgrarianGameArchive/Docs/EconomyAndAgrDesignDocument.md

# Agrarian Economy And AGR Design Document

## Purpose

Agrarian's economy should grow from the same survival foundation as the rest of
the game. Players should first trade because labor, time, risk, storage,
location, skills, and local resources matter. AGR can eventually add community
and real-world value, but it must not weaken the survival loop, create
pay-to-win pressure, or force legal/compliance decisions before the game is
ready.

This document defines the MVP economy direction, what AGR does and does not do
early, and the design guardrails for later account, wallet, ledger, and market
systems.

## Design Principles

- Survival access must never depend on AGR.
- Early economy starts with barter, ownership transfer, and transaction logs.
- Labor, distance, scarcity, time, skill, storage, spoilage, and trust are the
  first economic forces.
- The server owns all authoritative trades, ownership changes, and economy
  records.
- AGR must not buy combat dominance, survival immunity, exclusive resources, or
  unearned progression.
- No loot boxes, gambling loops, or fragmented paid DLC economy.
- Any real-money, token, wallet, or marketplace behavior requires legal and
  compliance review before public use.
- Economy data should be auditable enough to investigate duplication, fraud,
  griefing, and support disputes.

## Economy Progression

Agrarian's economy should emerge in stages.

### Stage 1: Survival Barter

The first playable economy is direct barter between players or through a simple
barter container.

Useful early goods:

- water containers;
- cooked or preserved food;
- sticks, stone, fiber, hide, and wood;
- basic tools;
- shelter materials;
- medicine or first-aid ingredients when added;
- local map knowledge and discovered safe routes.

This stage does not need coins, prices, shops, or AGR. It needs secure transfer,
ownership, and logs.

### Stage 2: Local Specialization

As survival stabilizes, players should benefit from specializing:

- toolmaker;
- hunter;
- fisher;
- gatherer;
- builder;
- farmer;
- livestock keeper;
- hauler;
- scout;
- guard;
- record keeper.

The economy becomes more interesting when not every player can efficiently do
everything at once.

### Stage 3: Settlements And Trust

Once settlements exist, trade expands through:

- shared storage;
- permissions;
- claims;
- reputation;
- contracts;
- local laws;
- debt or favor records;
- public trade posts.

Trust should be local and earned. A player may have a strong reputation in one
settlement and be unknown or disliked elsewhere.

### Stage 4: Regional Trade

Regional economy should come from real distance and tile differences:

- coastal vs inland resources;
- mountain, forest, river, and grassland advantages;
- travel time and carrying capacity;
- road, boat, horse, cart, tractor, and vehicle logistics;
- weather and seasonal risk;
- spoilage and preservation.

Distance-based economy pressure is valuable because the world is intended to
grow by real terrain tiles. A resource should not feel globally available just
because one tile has it.

### Stage 5: AGR Utility

AGR should only enter meaningful gameplay after the core economy is already fun
without it. AGR can later support community value, account-linked services,
event participation, marketplace rails, creator/community rewards, or other
approved utility, but those uses must be designed around fairness and compliance.

## MVP Economy Scope

The MVP economy should prove only the smallest useful loop:

- a player can offer items for trade;
- another player can accept or reject the trade;
- the server validates both inventories;
- ownership changes atomically;
- both players receive the correct result;
- a transaction record is written;
- the result survives persistence if the world is saved.

Acceptable MVP implementations:

- direct player-to-player trade window;
- barter container with explicit owner and recipient rules;
- admin/test command to create a known trade scenario.

The simplest implementation should be chosen when development reaches the trade
feature. For the current foundation stage, the important outcome is the data
contract and guardrails.

## MVP Non-Goals

Do not include these in the first playable MVP:

- real-money marketplace;
- AGR token transfers;
- wallet custody;
- blockchain confirmation requirements;
- player-run auction house;
- automated regional prices;
- global bank;
- paid boosts;
- purchasable survival advantages;
- staking, yield, or speculative mechanics;
- cash-out flows;
- cross-game asset promises.

## Trade Flow

Direct trade flow:

1. Player A requests a trade with Player B.
2. Server verifies both players are alive, connected, close enough, and allowed
   to trade.
3. Each player proposes item stacks from authoritative inventory.
4. Server locks the proposed items for the trade session.
5. Both players confirm.
6. Server revalidates inventories and item locks.
7. Server applies the exchange atomically.
8. Server writes a transaction record.
9. Server replicates updated inventories and trade result.

Barter-container flow:

1. Owner places items into a trade container or offer record.
2. Owner defines allowed recipient, settlement, or open offer scope.
3. Recipient places requested goods or accepts a posted exchange.
4. Server validates contents, ownership, permissions, and item state.
5. Server transfers ownership atomically.
6. Server writes a transaction record.

Rules:

- No client-authored inventory edits.
- No partial completion unless the trade type explicitly allows it.
- Locked trade items cannot be consumed, dropped, destroyed, or traded again.
- Disconnects cancel unconfirmed trades and unlock items.
- Confirmed trades must either fully apply or fully fail.

## Ownership Transfer

Ownership matters for support, permissions, settlements, theft rules, and
future legal/governance systems.

Minimum ownership fields:

```text
OwnerId
OwnerType
ItemOrObjectId
TileId
AcquiredAt
AcquisitionReason
SourceTransactionId
RecordVersion
```

Owner types can start simple:

- player;
- container;
- settlement;
- unowned/world.

Future owner types may include household, guild, town, government, market, or
contract escrow.

## Transaction Logging

Economy records should be append-only where practical. The goal is not full
financial infrastructure in the MVP; the goal is enough auditability to debug,
restore, and investigate.

Minimum transaction record:

```text
TransactionId
TransactionType
CreatedAt
TileId
ServerId
Participants
Inputs
Outputs
Status
FailureReason
GameBuildVersion
RecordVersion
```

Transaction types:

- direct_trade;
- barter_container_trade;
- admin_grant;
- admin_remove;
- crafting_output;
- resource_harvest;
- ownership_transfer;
- settlement_storage_deposit;
- settlement_storage_withdrawal.

MVP logs can be local structured files or database records depending on the
persistence implementation chosen at that time. Long term, economy logs should
move toward database-backed append-only records.

## Pricing And Value

MVP should not need hardcoded global prices. Early value comes from usefulness
and scarcity.

Avoid early global price tables because:

- different regions should value resources differently;
- player skill and labor should matter;
- spoilage and travel cost are contextual;
- a central price table can flatten the economy before it has a chance to
  emerge.

Useful future value signals:

- local trade history;
- settlement bulletin boards;
- scarcity indicators;
- rough admin/debug economy reports;
- distance and transport cost estimates.

## AGR Role In MVP

AGR in the MVP is design-only and placeholder-level unless explicitly approved
later.

AGR may do in MVP:

- appear in documentation as the future community-value layer;
- reserve data fields where future AGR-linked transactions might reference an
  account or ledger;
- support internal design discussions about fairness, compliance, and account
  linking;
- remain disabled in gameplay builds.

AGR must not do in MVP:

- buy food, water, weapons, shelter, land, claims, resources, livestock, or
  progression;
- replace barter or survival labor;
- create a paid advantage;
- require players to create a wallet;
- require blockchain/network connectivity to play;
- expose real-money value inside the game UI;
- be marketed as investment utility;
- be used in public testing without legal/compliance review.

## Wallet And Account Approach

Do not add wallet custody to the game client in the MVP.

Recommended direction:

- keep gameplay accounts separate from wallet identity at first;
- design an account-to-wallet bridge outside the Unreal client;
- prefer optional linking when real AGR utility is ready;
- avoid storing private keys, seed phrases, wallet passwords, or API tokens in
  game saves, config files, source control, or Unreal assets;
- require explicit legal/security review before choosing custodial or
  non-custodial flows.

Custodial vs non-custodial decision:

- MVP decision: deferred.
- Default until review: no wallet custody in game.
- Any future custodial system requires security, compliance, recovery, fraud,
  support, and jurisdiction review.
- Any future non-custodial system requires UX, loss-risk, transaction clarity,
  and support policy review.

## Testnet And Devnet

If AGR integration prototypes begin before public utility, use a devnet or
testnet-style environment only.

Rules:

- no mainnet transactions in early gameplay builds;
- no irreversible player-value transactions during gameplay prototyping;
- test credentials stay out of Git;
- test ledgers are clearly marked as non-production;
- transaction IDs are logged for debugging but do not drive survival outcomes.

## Confirmation Rules

Future AGR-linked actions should never block basic survival play.

If a future feature needs external confirmation:

- show a pending state outside critical survival loops;
- keep the game server authoritative for in-game item changes;
- time out clearly;
- reconcile duplicate or failed confirmations;
- log the external reference ID;
- never let the client claim confirmation without server verification.

## In-Game Ledger Rules

The in-game ledger is not the same as an external chain or payment network.

The game ledger should track:

- gameplay trades;
- ownership changes;
- admin grants/removals;
- settlement storage changes;
- future market offers;
- references to external AGR events if and when approved.

The game ledger should not store:

- private keys;
- seed phrases;
- wallet passwords;
- payment card data;
- raw personal financial data.

## Anti-Abuse And Fairness

Economy abuse will happen if the systems matter.

Required protections:

- server-authoritative inventory and ownership;
- atomic trade application;
- item locks during pending trades;
- transaction logs;
- admin-visible audit trail;
- duplicate transaction detection;
- rate limits for market-style endpoints when added;
- clear rollback/support procedure for confirmed exploit cases.

Gameplay fairness protections:

- no paid dominance;
- no purchasable survival immunity;
- no exclusive resource classes sold for money;
- no paid fast travel that invalidates logistics;
- no AGR-only tools required for normal progression.

## Legal And Compliance Gates

AGR or real-money utility cannot move beyond design/prototype until the project
has reviewed:

- company/payment setup;
- EULA and terms;
- privacy policy;
- age/content rating implications;
- tax/reporting implications;
- virtual currency/token rules;
- consumer protection and refund expectations;
- sanctions/geographic restrictions if relevant;
- marketplace/storefront rules for Steam, Epic, and other platforms;
- marketing language restrictions.

This document is a design guide, not legal advice.

## Data Boundaries

Economy data belongs with server-side persistence and audit records. Item
definitions remain in data assets. Tile metadata remains in the tile registry.

Persist economy records:

- transaction logs;
- ownership records;
- trade offers;
- settlement storage events;
- account link references once approved.

Do not persist economy records in:

- tile package cache;
- generated terrain packages;
- client-only UI settings;
- source-controlled secrets;
- raw Unreal starter/prototype assets.

## Implementation Roadmap

Near-term implementation order:

1. Add item ownership fields where needed for placed objects and containers.
2. Add transaction record shape to persistence.
3. Add admin/debug transaction logging for inventory grants/removals.
4. Add simple barter container or direct trade flow.
5. Add server-authoritative item locking for pending trades.
6. Add trade smoke tests.
7. Add settlement/container permissions.
8. Add local reputation and dispute/audit tooling.
9. Revisit AGR account/wallet bridge only after core economy is stable.

## Testing Gates

Minimum trade test:

1. Start a multiplayer session with two players.
2. Give each player a known item stack.
3. Start a trade.
4. Confirm both sides.
5. Verify inventories update correctly on server and clients.
6. Save and restart.
7. Verify ownership and inventory state persist.
8. Verify a transaction record exists.

Minimum abuse test:

1. Attempt to trade an item the player does not own.
2. Attempt to alter inventory client-side during trade.
3. Disconnect during an unconfirmed trade.
4. Attempt duplicate confirmation.
5. Confirm items are not duplicated, lost, or transferred without validation.

Minimum AGR safety test before any public feature:

1. Confirm AGR gameplay utility is disabled unless explicitly enabled.
2. Confirm no wallet secrets exist in saves, configs, logs, or assets.
3. Confirm survival gameplay works without account/wallet linking.
4. Confirm legal/compliance checklist has an owner before public exposure.

## Open Questions

- Whether the first trade implementation should be a direct player trade window
  or a barter container.
- Exact persistence backend for transaction logs once multiplayer saves mature.
- Final account provider and platform account timing.
- Whether AGR ever touches in-game item exchange directly or remains a
  community/account/service layer.
- Final custodial vs non-custodial wallet approach after legal/security review.