ns-banking — NullSect Banking

A server-authoritative banking ecosystem for FiveM: ATMs on every machine of the map, configurable bank branches, IBAN transfers, savings with interest, fixed-term deposits, a simulated crypto market and a simulated stock market, shared and business accounts, statements, receipts, an activity feed, admin tools and an immutable audit trail.

Crypto and stock prices are simulated in-game values generated by the server for roleplay. Nothing in this resource is connected to a real market or a real wallet.

Highlights

One money path. Every movement (deposit, withdrawal, transfer, savings, deposits, trades, jobs, exports, admin) goes through one journaled executor: idempotency key → framework debit → one database transaction → refund on failure.
Database-enforced integrity. Unsigned balances, guarded ledger inserts and unique references make overdrafts, double payouts and replays fail inside the transaction (verified against MariaDB, incl. truly concurrent requests).
Your framework stays the source of truth for the personal account: the current account balance is the framework bank money, so salaries, shops and phones keep working. Savings, shared/business accounts, deposits and holdings live in ns-banking's own tables.
Offline-safe transfers. Money sent to an offline player waits as a durable credit and is applied once when they load in.
Restart-safe jobs. Interest, maturities and dividends use deterministic references: never paid twice.
Premium NUI. Dark fintech design, local Inter font, EN/TR, locale-aware money / date / percent formatting, charts, receipts, statements, a streamlined ATM screen.
Frameworks: Qbox, QBCore, ESX (legacy 1.9+) and standalone hooks through the ns-core bridge.
Targeting: ox_target, qb-target or a built-in prompt (no hard dependency).

Requirements


Required	`oxmysql`, MariaDB 10.2+ / MySQL 8.0+ (InnoDB)
Framework	Qbox, QBCore or ESX legacy (auto-detected) — or standalone hooks in `config.lua`
Optional	`ox_lib` (notifications / text UI), `ox_target` or `qb-target`

Documentation

File	Contents
INSTALLATION.md	dependencies, load order, `server.cfg`, database, permissions, upgrade, tests, troubleshooting
CONFIGURATION.md	every option of `config.lua`, `data/branches.lua`, `data/markets.lua`
ARCHITECTURE.md	design decisions, atomicity model, RPC contract, recovery procedure
ASSETS.md	ATM / card artwork: sizes, AI image prompts, hotspot calibration
CHANGELOG.md	version history

Integration (exports)

exports['ns-banking']:GetIban(src)                         -- personal IBAN
exports['ns-banking']:GetAccount(iban)                     -- { iban, type, name (privacy-masked), status }
exports['ns-banking']:GetBusinessBalance('police')
exports['ns-banking']:AddBusinessMoney('police', 500, 'fine')          -- trusted resources only
exports['ns-banking']:RemoveBusinessMoney('mechanic', 200, 'parts')    -- trusted resources only
exports['ns-banking']:ChargePlayer(src, 150, 'speeding', 'police')     -- trusted; personal bank -> business
exports['ns-banking']:Transfer(src, iban, 1000, 'rent')                -- trusted; e.g. a phone banking app
exports['ns-banking']:LogExternal(src, 2500, 'Paycheck')               -- trusted; history line only

Money exports return ok, referenceOrErrorKey; see INSTALLATION.md §6 for police / business / job / phone integration.

Development standards

Built on ns-core 1.0.1 (core/, never edited by hand). The shared NullSect standards (architecture, security, development workflow, release) live in ns-core/docs/; ARCHITECTURE.md here holds the ns-banking decisions only. UI screenshots (EN / TR) are in outputs/ — not part of a release package.