feat(token): on-chain token transfers, canonical burn, sharded logs_root proofs

Success-gated QRC-20/721 transfer events are folded into the 2f+1 QC-certified
Checkpoint.logs_root (active from genesis), giving trustless light-client receipts.

- logs_root is SHARDED: the window root is a merkle over per-block sub-roots (stored
  at apply), so the macroblock seal folds ~90 roots and /logs/proof is a 2-level proof
  that touches ONE block, not O(window). Mobile QcLightClient verifies both levels.
- Canonical burn address 0000000000000000000eon00000000000000036877022 (provably
  unspendable): QRC-20/721 transfer-to-it is a real burn (supply reduced / token
  destroyed + exact deposit refund); native QNC becomes non-circulating; mint-to-burn
  rejected. /public/stats reports burn_address + qnc_burned.
- VM: deterministic tree-wide MAX_LOGS_PER_TX cap (traps -> reverts tx, shared CallState
  counter) + higher LOG_FUEL_BASE bound the per-window merkle against emit_log spam.
- Node: reorg-consistent token-transfer index (cursor-paged, resume-watermark prune),
  decoded RPC feeds with oldest_available retention honesty, and a light
  contract-metadata read (no O(holders) account clone).
- Mobile: trustless 2-level inclusion verify (a QC-root mismatch -> rejected, never
  confirmed), a QC-verified trust badge gated on wallet-trusted decimals, no
  node-supplied logo loaded as <Image>.
- Explorer: token-transfer tab/pages, anchor-corroborated backward-height reconcile
  (no spurious DB wipe on node restart), composite SQL indexes, shared amount/logo utils.
- External qnet-loadtest harness: confirmed-TPS + finality latency + 2-level proof sampling.

Validated: qnet-consensus 91, qnet-state 131, qnet-vm 22, qnet-integration check clean,
qnet-loadtest 5; mobile babel + explorer tsc clean. Consensus-structure change -> fresh
genesis (logs_root_required gate=0, no mixed-binary).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: AIQnetLab

.gitignore

@@ -687,3 +687,9 @@ dev-scratch/
 # Build artifacts (never track)
 *.rlib
 *.tsbuildinfo
+
+# Explorer app TypeScript source libs are real code, not Python build artifacts (override the generic `lib/` ignore above)
+!applications/qnet-explorer/frontend/lib/
+!applications/qnet-explorer/frontend/lib/**
+!applications/qnet-explorer/frontend/src/lib/
+!applications/qnet-explorer/frontend/src/lib/**

Cargo.lock

@@ -7,6 +7,7 @@ members = [
     "core/qnet-sharding",
     "core/qnet-vm",
     "development/qnet-integration",
+    "development/qnet-loadtest",
     "audit"
 ]
 resolver = "2"

Cargo.toml

@@ -1307,6 +1307,17 @@ pub struct SimpleMempool {
 - **Pool #3**: Activation QNC redistributed to all nodes
 - **Decimals**: 9 (1 QNC = 10^9 nanoQNC)
 
+**Canonical Burn Address (all QNet tokens):**
+
+```
+0000000000000000000eon00000000000000036877022
+```
+
+- **Nothing-up-my-sleeve**: the address body is all zeros with a valid checksum; addresses derive from SHA512(pubkey), so no key can ever map to it — provably unspendable forever
+- **QRC-20**: transferring to it is a REAL burn recognized by the protocol — holder debited, `total_supply` reduced, `total_burned` increased 1:1, a `burn` event emitted. Works for ANY token, including non-burnable ones (the opt-in `burnable` flag only gates the token's own `burn` method)
+- **QRC-721 (NFT)**: transferring to it destroys the token — ownership record removed, storage deposits refunded, a `burn` event emitted
+- **Native QNC**: accumulates unspendably at the address and is excluded from circulating supply (`circulating = total_supply − qnc_burned`, reported by `/api/v1/public/stats`). Burned QNC still counts against the 2^32 emission cap — burning never re-opens emission headroom
+
 ### 7.2 Sharp Drop Halving Innovation
 
 **Revolutionary Emission Schedule:**

QNet_Whitepaper.md

@@ -1905,6 +1905,17 @@ curl http://localhost:8003/api/v1/transactions/{hash}
 - `GET /api/v1/token/{address}` - Get token info (name, symbol, decimals, supply)
 - `GET /api/v1/token/{address}/balance/{holder}` - Get token balance for holder
 
+**Token Transfers (decoded, effect-sourced events):**
+- `GET /api/v1/account/{address}/token-transfers?limit=&before=` - QRC-20/721 transfers for an address (cursor-paged)
+- `GET /api/v1/token/{contract}/transfers?limit=&before=` - Transfers for one token (cursor-paged)
+- `GET /api/v1/token-transfers?from=&to=&limit=&after=` - Height-range feed for indexers (`truncated` + `next_cursor`)
+- `GET /api/v1/logs/proof?tx_hash=&log_index=` - Light-client merkle inclusion proof against the QC-certified `logs_root`
+
+**Canonical Burn Address:**
+- `0000000000000000000eon00000000000000036877022` - well-known, provably unspendable (all-zeros body, no key can derive it)
+- Sending ANY QRC-20 (even non-burnable) or QRC-721 here is a REAL on-chain burn: supply reduced / token destroyed, `burn` event emitted
+- Sending native QNC here removes it from circulation permanently; `GET /api/v1/public/stats` reports `burn_address` + `qnc_burned` (circulating = total_supply − qnc_burned)
+
 **Blockchain Data:**
 - `GET /api/v1/block/latest` - Get latest block
 - `GET /api/v1/block/{height}` - Get block by height

README.md

@@ -612,6 +612,61 @@ export async function searchQrc20DeploysByText(needle: string, limit: number = 2
   return result.rows;
 }
 
+// ============================================================================
+// TOKEN TRANSFERS (decoded, effect-sourced index — populated by sync-service)
+// ============================================================================
+
+// One decoded transfer log. `amount` is a u64 base-unit value; PostgreSQL returns
+// NUMERIC as a string, so it stays exact past 2^53 — scale it with the token's
+// decimals via formatTokenAmount, never Number(). from==''⇒mint, to==''⇒burn.
+export interface TokenTransferRow {
+  tx_hash: string;
+  log_index: number;
+  contract: string;
+  from_address: string;
+  to_address: string;
+  amount: string;
+  kind: string;
+  std: string;
+  token_id: string;
+  block: number;
+  timestamp: number;
+}
+
+// All transfers touching an address (as sender or recipient), newest first. A UNION of two single-column
+// branches — not `from = $1 OR to = $1` — so each side is an index-ordered, LIMIT-bounded scan on its
+// (address, block DESC, log_index DESC) composite index (an OR across two columns cannot use either index
+// for ordering and forces a full BitmapOr fetch + sort). UNION dedupes a self-transfer (from == to == $1).
+export async function getAddressTokenTransfers(address: string, limit: number = 50): Promise<TokenTransferRow[]> {
+  validateAddress(address);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) limit = 50;
+  const result = await query<TokenTransferRow>(
+    `SELECT * FROM (
+       (SELECT * FROM token_transfers WHERE from_address = $1 ORDER BY block DESC, log_index DESC LIMIT $2)
+       UNION
+       (SELECT * FROM token_transfers WHERE to_address = $1 ORDER BY block DESC, log_index DESC LIMIT $2)
+     ) u
+     ORDER BY block DESC, log_index DESC
+     LIMIT $2`,
+    [address, limit]
+  );
+  return result.rows;
+}
+
+// All transfers of one token contract, newest first.
+export async function getContractTokenTransfers(contract: string, limit: number = 50): Promise<TokenTransferRow[]> {
+  validateAddress(contract);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) limit = 50;
+  const result = await query<TokenTransferRow>(
+    `SELECT * FROM token_transfers
+     WHERE contract = $1
+     ORDER BY block DESC, log_index DESC
+     LIMIT $2`,
+    [contract, limit]
+  );
+  return result.rows;
+}
+
 export async function closePool(): Promise<void> {
   if (pool) {
     await pool.end();