dchain/CHANGELOG.md

DChain CHANGELOG

Consolidated record of what landed. Replaces the now-deleted REFACTOR_PLAN.md, NODE_ONBOARDING.md, and ROADMAP.md — every numbered item there is either shipped (listed below) or explicitly deferred.

---

Production-ready stack (shipped)

Consensus & chain

• PBFT multi-sig validator admission. ADD_VALIDATOR requires ⌈2/3⌉ cosigs from the current set + candidate must have ≥ MinValidatorStake (1 T) locked via STAKE. Same gate on forced REMOVE_VALIDATOR; self- removal stays unilateral.
• Equivocation slashing. SLASH tx with reason=equivocation carries both conflicting PREPARE/COMMIT messages as evidence; ValidateEquivocation verifies on-chain — any node can report, no trust. Offender's stake is burned and they're evicted from the set.
• Liveness tracking. PBFT records per-validator last-seen seqNum; LivenessReport() + MissedBlocks() surface stalemates. Exposed via dchain_max_missed_blocks Prometheus gauge.
• Fair mempool. Per-sender FIFO queues drained round-robin into proposals; one spammer can't starve others.
• Block-reward fix. Synthetic BLOCK_REWARD transactions use From="" so self-validators don't appear to pay themselves in history.

Storage & stability

• Re-entrant-deadlock fix. Dedicated configMu and nativeMu separate from c.mu — applyTx can safely read config/native registry while AddBlock holds the write lock.
• BadgerDB tuning. WithValueLogFileSize(64 MiB) + WithNumVersionsToKeep(1)
  • background StartValueLogGC every 5 minutes + one-shot CompactNow() at startup. Reclaims gigabytes from upgraded nodes automatically.
• TipIndex() — lock-free reads so /api/blocks and /api/txs/recent never hang even when AddBlock is stuck.
• Chronological tx index (txchron:<block20d>:<seq04d>). RecentTxs runs in O(limit) instead of O(empty blocks) — important when tps is low.
• WASM VM timeout + WithCloseOnContextDone. Any contract call aborts at 30 s hard cap; gas metering evasion can no longer freeze the chain.

Native contracts

• native:username_registry (v2.1.0). Replaces WASM registry — 100× faster, no VM failure surface. register(name) requires exact tx.Amount = 10 000 µT (burned, visible in history). Min length 4, lowercase a-z 0-9 _ -, first char letter, reserved words blacklist.
• Native dispatcher in applyTx → checks native:* IDs first, falls through to WASM VM otherwise. ABI JSON + contract metadata surfaced via /api/contracts/:id with "native": true flag.
• Well-known auto-discovery. /api/well-known-contracts returns canonical contract IDs indexed by ABI name; native always wins. Client auto-syncs on connect.

WebSocket gateway (push-based UX)

• GET /api/ws — persistent bidirectional JSON-framed connection.
• Topics: blocks, tx, addr:<pub>, inbox:<x25519>, contract_log, contract:<id>, typing:<x25519>.
• auth op. Client signs server-issued nonce with Ed25519; hub binds connection to pubkey so scoped subscriptions (addr:*, inbox:*, typing:*) are accepted only for owned identities.
• submit_tx op. Low-latency tx submission with correlated submit_ack frame; removes the HTTP round-trip. Client falls back to POST /api/tx automatically if WS is down.
• Typing indicators. Ephemeral typing op, authenticated, scoped to recipient. Mobile client shows "печатает…" in chat header.
• Per-connection quotas. Max 10 connections / IP, 32 subs / connection. Bounded outbox drops oldest on overflow with {event:"lag"} notice.
• Fanout mirrors SSE. eventBus dispatches to SSE + WS + future consumers from one emit site.

Relay mailbox

• Push notifications. Mailbox.SetOnStore hook → wsHub.EmitInbox(...) on every fresh envelope. Client's useMessages subscribes instead of polling every 3 s.
• Relay TTL. REGISTER_RELAY and HEARTBEAT (from registered relays) refresh a relayhb:<pub> timestamp; /api/relays filters anything older than 2 hours. Stale relays are delisted automatically.

Node onboarding

• --join <url1,url2,…> — multi-seed bootstrap. Tries each URL in order, persists the live list to <db>/seeds.json on first success so subsequent restarts don't need the CLI flag.
• /api/network-info — one-shot payload (chain_id, genesis_hash, validators, peers, contracts, stats) for joiners.
• /api/peers — live libp2p peer list with multiaddrs.
• Genesis-hash verification. A node with expected hash aborts if its local block 0 doesn't match (protection against forged seeds). Override with --allow-genesis-mismatch for migrations.
• Gap-fill on gossip. Blocks with b.Index > tip+1 trigger SyncFromPeerFull to the gossiping peer (rate-limited 1 per peer per minute). Nodes recover from brief outages without restart.

API surface & security

• Rate limiter (node/api_guards.go). Per-IP token bucket on /api/tx and /v2/chain/transactions: 10 tx/s, burst 20.
• Request-size cap. /api/tx body ≤ 64 KiB.
• Timestamp validation. ±1 h window on submit, refuses clock-skewed or replayed txs.
• Humanised errors in client. humanizeTxError translates 429 / 400+timestamp / 400+signature / network-failure into Russian user- facing text.

Observability & ops

• Prometheus /metrics. Zero-dep in-tree implementation (node/metrics.go) with counters (blocks, txs, submit accepted/rejected), gauges (ws connections, peer count, max missed blocks), histogram (block commit seconds).
• Load test. cmd/loadtest — N concurrent WS clients with auth + scoped subs + TRANSFER at rate. Validates chain advances, reject rate, ws-drop count. Smoke at 20 clients × 15 s → 136 accepted / 0 rejected.
• Structured logging. --log-format=text|json flag. JSON mode routes both slog.* and legacy log.Printf through one JSON handler for Loki/ELK ingestion.
• Observer mode. --observer (env DCHAIN_OBSERVER) disables PBFT producer + heartbeat + auto-relay-register; node still gossips and serves HTTP/WS. For horizontally-scaling read-only API frontends.

Deployment

• deploy/single/ — one-node production bundle:
  • Same Dockerfile.slim as the cluster variant.
  • Compose stack: 1 node + Caddy + optional Prometheus/Grafana.
  • Supports three operator-chosen access modes:
    • Public (no token) — anyone can read + submit.
    • Public reads, token-gated writes (DCHAIN_API_TOKEN set) — reads stay open, submit tx requires Authorization: Bearer.
    • Fully private (DCHAIN_API_TOKEN + DCHAIN_API_PRIVATE) — every endpoint requires the token.
  • Runbook covers three scenarios: genesis node, joiner, private.
• deploy/prod/ — 3-validator cluster for federations/consortiums.
• Access-token middleware in node/api_guards.go:
  • withWriteTokenGuard gates POST /api/tx and WS submit_tx.
  • withReadTokenGuard gates reads when --api-private is set.
  • WS upgrade applies the same check; submit_tx ops on a non-authenticated connection are rejected with submit_ack rejected.
• All CLI flags accept DCHAIN_* env fallbacks for Docker-driven configuration, including the new DCHAIN_API_TOKEN / DCHAIN_API_PRIVATE.

Client (React Native / Expo)

• WebSocket module lib/ws.ts with reconnect, auto-resubscribe, auto-auth on reconnect.
• useBalance, useContacts, useMessages — all push-based with HTTP polling fallback after 15 s disconnect.
• useWellKnownContracts — auto-syncs settings.contractId with node's canonical registry.
• Safe-area-aware layout throughout. Tab bar no longer hides under home indicator on iPhone.
• Username purchase UI with live validation (min 4, first letter, charset).
• Transaction detail sheet with system-tx handling (BLOCK_REWARD shows "Сеть" as counterpart, not validator's self-pay).

---

Deliberately deferred

• Split blockchain/chain.go into state/, applytx/, mempool/, index/, events/ subpackages. A ~2.5k-line single-file refactor is high risk; to be attempted after the chain has been running in prod long enough that regressions there would be caught fast.
• Full p2p/ rewrite with typed event channel. The libp2p integration works; event-bus was added at the node layer instead (see node/events.go).
• Full mempool admission pricing (gas-priced priority queues). Current fair round-robin works within spam-proofing needs.

---

Compatibility notes

• BadgerDB tuning is compatible with databases created by previous versions; the first run reclaims old value-log space via CompactNow().
• AddValidatorPayload / RemoveValidatorPayload gained a cosigs field; older payloads without it still parse (default empty), but will fail the ⌈2/3⌉ threshold on chains with >1 validator.
• BLOCK_REWARD transactions changed from From=validator to From="". Old indexed records keep their previous From; new ones use the new shape. Explorer/client handle both.
• Registration fee for usernames moved from internal ctx.Debit to tx.Amount. The WASM username_registry is superseded by native:username_registry; well-known endpoint returns the native version as canonical.