docs(toolkit): clarify lite snapshot trace exclusion

Author: halibobo1205

plugins/README.md

@@ -75,7 +75,7 @@ DB lite provides lite database, parameters are compatible with previous `LiteFul
 - `-fn | --fn-data-path`: The database path to be split or merged.
 - `-ds | --dataset-path`: When operation is `split`,`dataset-path` is the path that store the `snapshot` or `history`, when
   operation is `split`, `dataset-path` is the `history` data path.
-- `--exclude-historical-balance`: Only used with `operate=split -t snapshot`, default: false. When set to true, `balance-trace` and `account-trace` are excluded from the lite snapshot. The flag has functional impact only when the source full node ran with `historyBalanceLookup=true` (off by default; most operators are unaffected). **WARNING:** for nodes that had `historyBalanceLookup=true`, this loss is permanent — a lite node booted from such a snapshot cannot answer historical balance lookups (`getBlockBalance` / `getAccountBalance`), and running `merge` afterwards will NOT restore the feature. If you need historical balance lookup on the resulting lite node, do **not** enable this flag. `split -t history` and `merge` ignore this flag.
+- `--exclude-historical-balance`: Only used with `operate=split -t snapshot`, default: false. When set to true, `balance-trace` and `account-trace` are excluded from the lite snapshot. The flag has functional impact only when the source full node ran with `historyBalanceLookup=true` (off by default; most operators are unaffected). **WARNING:** for nodes that had `historyBalanceLookup=true`, this loss is permanent — a lite node booted from such a snapshot cannot safely serve historical balance lookups (`getBlockBalance` may fail, and `getAccountBalance` may return `balance=0` when `account-trace` data is missing), and running `merge` afterwards will NOT restore the feature. If you need historical balance lookup on the resulting lite node, do **not** enable this flag. `split -t history` and `merge` ignore this flag.
 - `-h | --help`: Provide the help info.
 
 ### Examples:
@@ -87,7 +87,7 @@ DB lite provides lite database, parameters are compatible with previous `LiteFul
   #split and get a snapshot dataset
   java -jar Toolkit.jar db lite -o split -t snapshot --fn-data-path output-directory/database --dataset-path /tmp
   #split and get a snapshot dataset without balance-trace / account-trace (smaller snapshot;
-  #historical balance lookup will be permanently unavailable on the resulting lite node)
+  #historical balance lookup cannot be safely served on the resulting lite node)
   java -jar Toolkit.jar db lite -o split -t snapshot --fn-data-path output-directory/database --dataset-path /tmp --exclude-historical-balance
   #split and get a history dataset
   java -jar Toolkit.jar db lite -o split -t history --fn-data-path output-directory/database --dataset-path /tmp

plugins/src/main/java/common/org/tron/plugins/DbLite.java

@@ -120,11 +120,12 @@ enum Type { snapshot, history }
           + "This flag only has a functional impact when the source full node ran with "
           + "`historyBalanceLookup=true` (off by default; most operators are unaffected). "
           + "WARNING: when historyBalanceLookup was enabled, this loss is permanent: a lite "
-          + "node booted from such a snapshot cannot answer historical balance lookups "
-          + "(getBlockBalance / getAccountBalance), and running merge afterwards will NOT "
-          + "restore the feature. If you need to keep historyBalanceLookup working on the "
-          + "resulting lite node, do NOT enable this flag. `split -t history` and `merge` "
-          + "ignore this flag.",
+          + "node booted from such a snapshot cannot safely serve historical balance lookups "
+          + "(getBlockBalance may fail, and getAccountBalance may return balance=0 when "
+          + "account-trace data is missing). Running merge afterwards will NOT restore the "
+          + "feature. If you need to keep historyBalanceLookup working on the resulting "
+          + "lite node, do NOT enable this flag. `split -t history` and `merge` ignore "
+          + "this flag.",
       order = 5)
   private boolean excludeHistoricalBalance;
 
@@ -143,8 +144,8 @@ public Integer call() {
     try {
       switch (this.operate) {
         case split:
-          warnIfExcludingHistoricalBalance();
           if (Type.snapshot == this.type) {
+            warnIfExcludingHistoricalBalance();
             generateSnapshot(fnDataPath, datasetPath);
           } else if (Type.history == type) {
             generateHistory(fnDataPath, datasetPath);
@@ -307,12 +308,14 @@ private void warnIfExcludingHistoricalBalance() {
         + "will be excluded from the lite snapshot. This only matters when the source full "
         + "node ran with historyBalanceLookup=true (off by default; most operators are "
         + "unaffected). When that switch was enabled, this loss is permanent: lite nodes "
-        + "booted from this snapshot cannot answer historical balance lookups "
-        + "(getBlockBalance / getAccountBalance), and running merge afterwards will NOT "
-        + "restore the feature. If you need to keep historyBalanceLookup working on the "
-        + "resulting lite node, do NOT use this flag.";
+        + "booted from this snapshot cannot safely serve historical balance lookups "
+        + "(getBlockBalance may fail, and getAccountBalance may return balance=0 when "
+        + "account-trace data is missing). Running merge afterwards will NOT restore the "
+        + "feature. If you need to keep historyBalanceLookup working on the resulting "
+        + "lite node, do NOT use this flag.";
     logger.warn(msg);
-    spec.commandLine().getErr().println(msg);
+    spec.commandLine().getErr().println(spec.commandLine().getColorScheme()
+        .errorText(msg));
   }
 
   private List<String> getSnapshotDbs(String sourceDir) {
@@ -786,4 +789,3 @@ public long getSnapshotMaxNum() {
 }
 
 
-

plugins/src/test/java/org/tron/plugins/DbLiteTest.java

@@ -71,7 +71,7 @@ public void shutdown() throws InterruptedException {
     context.close();
   }
 
-  public void init(String dbType) throws IOException {
+  public void init(String dbType, boolean historyBalanceLookup) throws IOException {
     dbPath = folder.newFolder().toString();
     Args.setParam(new String[] {
         "-d", dbPath, "-w", "--p2p-disable", "true", "--storage-db-engine", dbType},
@@ -80,6 +80,7 @@ public void init(String dbType) throws IOException {
     Args.getInstance().setAllowAccountStateRoot(1);
     Args.getInstance().setRpcPort(PublicMethod.chooseRandomPort());
     Args.getInstance().setRpcEnable(true);
+    Args.getInstance().setHistoryBalanceLookup(historyBalanceLookup);
     databaseDir = Args.getInstance().getStorage().getDbDirectory();
     // init dbBackupConfig to avoid NPE
     Args.getInstance().dbBackupConfig = DbBackupConfig.getInstance();
@@ -99,7 +100,8 @@ public void testTools(String dbType, int checkpointVersion, boolean excludeHisto
       throws InterruptedException, IOException {
     logger.info("dbType {}, checkpointVersion {}, excludeHistoricalBalance {}",
         dbType, checkpointVersion, excludeHistoricalBalance);
-    init(dbType);
+    boolean historyBalanceLookup = excludeHistoricalBalance;
+    init(dbType, historyBalanceLookup);
     final String[] argsForSnapshot = excludeHistoricalBalance
         ? new String[] {"-o", "split", "-t", "snapshot", "--fn-data-path",
             dbPath + File.separator + databaseDir, "--dataset-path",