81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# 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.
|