# GL

Darano's independent, append-only general-ledger service. It preserves every
committed wallet value movement so financial state can be reconstructed when a
blockchain or provider is unavailable.

The implementation contract and invariants are defined in [DESIGN.md](DESIGN.md).

For an independent PostgreSQL + ledger API + dashboard deployment with no
blockchain network access, see [Standalone General Ledger](deployment/STANDALONE.md).
The [authority API](deployment/AUTHORITY_API.md) provides an authenticated,
persisted GL-only toggle, internal journal execution, and per-user balances.

Generate protobufs, test, and build with:

```bash
make generate
make test
make build
```

Run the ledger API and dashboard as separate processes:

```bash
go run ./cmd/gl -conf ./gl.cfg.toml
go run ./cmd/dashboard -conf ./dashboard.cfg.toml
```

For live reload, install [Air](https://github.com/air-verse/air) and run `air`
from the repository root. The checked-in `.air.toml` rebuilds and restarts both
processes together.

The read-only network explorer is served on `http://localhost:8080` by default:

The header includes English/Persian localization and a persistent light/dark
theme toggle that initially follows the operating-system preference.

- `/` shows network totals and recent committed journals;
- `/assets` ranks the top positive user holders for recently active assets;
- `/holders` combines a user's available and frozen balance and activity for one asset;
- `/transactions` shows paginated recent transactions, filters them by user/wallet and effect type, and finds journals by exact blockchain transaction hash or internal journal ID;
- `/accounts` rebuilds a ledger account balance and activity history.

The gRPC service owns schema migrations. The dashboard is read-only, uses its
own `dashboard.cfg.toml`, and does not run migrations.

AdminPanel settlement review supports `IgnoreSettlement` through the authenticated
GL admin connection. Operators with `ledgerops.retry_kuknossettlement` can review an
unlocked `MANUAL_REVIEW` or `RETRYABLE` settlement and record a reason to close it.
GL atomically sets `IGNORED`, records the actor/reason/status transition in
`kuknos_settlement_operator_audits`, and resolves linked open reconciliation issues.
The original error and signed payload remain available as evidence. Ignored
settlements are terminal, cannot be retried, and leave the attention queue.
Dismissal does not confirm a payment or reverse funds; IRT withdrawal reservations
still require financial reconciliation.

Deploy the updated GL service first so its startup applies migration
`000007_ignore_settlement.up.sql` and exposes the RPC, then deploy Wallet and
AdminPanel. An older GL service rejects the command; AdminPanel preserves the
review form and shows the error rather than reporting a successful dismissal.

Run the dashboard load test against a started dashboard with:

```bash
make load-test LOADTEST_ARGS='-duration 30s -concurrency 50'
```

Use `-paths` to exercise known explorer records as well as the overview, for
example `-paths '/,/transactions?q=KNOWN_HASH,/accounts?class=USER_AVAILABLE&owner_type=user&owner_id=17&asset_id=9'`.

Run the fixed 10-person, 10,000,000-transfer GL conservation scenario with:

```bash
make gl-redistribution-load-test
Asset number: 7
```

It starts with one person holding 10,000, uses random transfer values while
protecting a minimum of 45 per person, and verifies that the final ten balances
still sum to exactly 10,000.