feat(cli): enhance ChainListCmd with JSON output and <epoch> placehol…

…der support (#12691)

* docs: Update format flag usage with valid placeholders for ChainListCmd

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* feat: Add <json_tipset> placeholder for JSON encoding of the tipset

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* style: Fix formatting in chain.go for consistency and readability

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* fix: Change JSON encoding to single line without indentation

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* docs: Update Usage for format flag to remove placeholder explanations

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* feat: Rename 'height' flag to 'epoch' in ChainListCmd and update usage

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* add changelog

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* docs: Update CLI options in lotus documentation for clarity and detail

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

* fix changelog

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

---------

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

CHANGELOG.md

@@ -2,7 +2,10 @@
 
 # UNRELEASED
 
-# UNRELEASED v1.32.0
+- Add json output of tipsets to `louts chain list`. ([filecoin-project/lotus#12691](https://github.com/filecoin-project/lotus/pull/12691))
+
+# UNRELEASED v.1.32.0
+
 
 See https://github.com/filecoin-project/lotus/blob/release/v1.32.0/CHANGELOG.md
 

cli/chain.go

@@ -581,12 +581,12 @@ var ChainListCmd = &cli.Command{
 	Aliases: []string{"love"},
 	Usage:   "View a segment of the chain",
 	Flags: []cli.Flag{
-		&cli.Uint64Flag{Name: "height", DefaultText: "current head"},
+		&cli.Uint64Flag{Name: "epoch", Aliases: []string{"height"}, DefaultText: "current head"},
 		&cli.IntFlag{Name: "count", Value: 30},
 		&cli.StringFlag{
 			Name:  "format",
-			Usage: "specify the format to print out tipsets",
-			Value: "<height>: (<time>) <blocks>",
+			Usage: "specify the format to print out tipsets using placeholders: <epoch>, <time>, <blocks>, <weight>, <tipset>, <json_tipset>\n",
+			Value: "<epoch>: (<time>) <blocks>",
 		},
 		&cli.BoolFlag{
 			Name:  "gas-stats",
@@ -932,7 +932,9 @@ func handleHamtAddress(ctx context.Context, api v0api.FullNode, r cid.Cid) error
 }
 
 func printTipSet(format string, ts *types.TipSet, afmt *AppFmt) {
-	format = strings.ReplaceAll(format, "<height>", fmt.Sprint(ts.Height()))
+	format = strings.ReplaceAll(format, "<epoch>", fmt.Sprint(ts.Height()))
+	format = strings.ReplaceAll(format, "<height>", fmt.Sprint(ts.Height())) // backwards compatibility
+
 	format = strings.ReplaceAll(format, "<time>", time.Unix(int64(ts.MinTimestamp()), 0).Format(time.Stamp))
 	blks := "[ "
 	for _, b := range ts.Blocks() {
@@ -948,6 +950,16 @@ func printTipSet(format string, ts *types.TipSet, afmt *AppFmt) {
 
 	format = strings.ReplaceAll(format, "<tipset>", strings.Join(sCids, ","))
 	format = strings.ReplaceAll(format, "<blocks>", blks)
+	if strings.Contains(format, "<json_tipset>") {
+		jsonTipset, err := json.Marshal(ts)
+		if err != nil {
+			// should not happen
+			afmt.Println("Error encoding tipset to JSON:", err)
+			return
+		}
+		format = strings.ReplaceAll(format, "<json_tipset>", string(jsonTipset))
+	}
+
 	format = strings.ReplaceAll(format, "<weight>", fmt.Sprint(ts.Blocks()[0].ParentWeight))
 
 	afmt.Println(format)

documentation/en/cli-lotus.md

@@ -1731,11 +1731,12 @@ USAGE:
    lotus chain list [command options] [arguments...]
 
 OPTIONS:
-   --height value  (default: current head)
-   --count value   (default: 30)
-   --format value  specify the format to print out tipsets (default: "<height>: (<time>) <blocks>")
-   --gas-stats     view gas statistics for the chain (default: false)
-   --help, -h      show help
+   --epoch value, --height value  (default: current head)
+   --count value                  (default: 30)
+   --format value                 specify the format to print out tipsets using placeholders: <epoch>, <time>, <blocks>, <weight>, <tipset>, <json_tipset>
+       (default: "<epoch>: (<time>) <blocks>")
+   --gas-stats  view gas statistics for the chain (default: false)
+   --help, -h   show help
 ```
 
 ### lotus chain get