documentation

Signed-off-by: Angelo De Caro <adc@zurich.ibm.com>

Author: adecaro

cmd/tokengen/README.md

@@ -1,157 +1,53 @@
 # Tokengen
 
-`tokengen` is an utility for generating Fabric Token-SDK material. 
-It is provided as a means of preconfiguring public parameters, token chaincode, and so. 
-It would normally not be used in the operation of a production network.
+`tokengen` is a utility for generating Fabric Token-SDK material, such as public parameters, token chaincode packages, and other cryptographic artifacts. 
 
-## Syntax
+It is primarily used for pre-configuring development and testing environments.
 
-The `tokengen` command has five subcommands, as follows:
+## Build
 
-- artifacts
-- certifier-keygen
-- gen
-- help
-- version
-
-## tokengen artifacts
-
-This command is used to centrally generate key material and configuration files.
-It takes in input a `topology` file, in `yaml` format, that describes the topologies of the networks involved.
-An example can be found [`here`](./samples/topology/fungible.yaml). 
-Topology files can be edited directly or they can be generated programmatically as shown [`here`](./samples/topology/fungible.go). 
-
-```
-Read topology from file and generates artifacts.
-
-Usage:
-tokengen artifacts [flags]
-
-Flags:
--h, --help              help for artifacts
--o, --output string     output folder (default "./testdata")
--p, --port int          host starting port (default 20000)
--t, --topology string   topology file in yaml format
-```
-
-## tokengen certifier-keygen
-
-```
-Gen Token Certifier Key Pair.
-
-Usage:
-  tokengen certifier-keygen [flags]
-
-Flags:
-  -d, --driver string   driver (zkatdlognogh.v1) (default "zkatdlognogh.v1")
-  -h, --help            help for certifier-keygen
-  -o, --output string   output folder (default ".")
-  -p, --pppath string   path to the public parameters file
-```
-
-## tokengen gen
-
-The `tokengen gen` command has two subcommands, as follows:
-
-- fabtoken.v1: generates the public parameters for the fabtoken driver
-- zkatdlognogh.v1: generates the public parameters for the zkatdlognogh.v1 driver
-
-## tokengen gen fabtoken.v1
-
-```
-Usage:
-  tokengen gen fabtoken.v1 [flags]
-
-Flags:
-  -a, --auditors strings   list of auditor MSP directories containing the corresponding auditor certificate
-      --cc                 generate chaincode package
-  -h, --help               help for fabtoken.v1
-  -s, --issuers strings    list of issuer MSP directories containing the corresponding issuer certificate
-  -o, --output string      output folder (default ".")
-  -v, --version uint       allows the caller of tokengen to override the version number put in the public params
-```
-
-The public parameters are stored in the output folder with name `fabtokenv1_pp.json`.
-If version is overridden, then file name will be `("fabtokenv%d_pp.json", version)`.
-
-### tokengen gen zkatdlognogh.v1
+To build `tokengen`, run the following command from the root of the repository:
 
+```bash
+make tokengen
 ```
-Usage:
-  tokengen gen zkatdlognogh.v1 [flags]
 
-Flags:
-  -r, --aries               flag to indicate that aries should be used as backend for idemix
-  -a, --auditors strings    list of auditor MSP directories containing the corresponding auditor certificate
-  -b, --bits uint           bits is used to define the maximum quantity a token can contain (default 64)
-      --cc                  generate chaincode package
-  -x, --extra stringArray   extra data in key=value format, where value is the path to a file containing the data to load and store in the key
-  -h, --help                help for zkatdlognogh.v1
-  -i, --idemix string       idemix msp dir
-  -s, --issuers strings     list of issuer MSP directories containing the corresponding issuer certificate
-  -o, --output string       output folder (default ".")
-  -v, --version uint        allows the caller of tokengen to override the version number put in the public params
-``` 
+The binary will be generated in the `$GOROOT/bin` directory.
 
-The public parameters are stored in the output folder with name `zkatdlognoghv1_pp.json`.
-If version is overridden, then file name will be `("zkatdlognogh%d_pp.json", version)`.
+## Usage
 
-### tokengen update zkatdlognogh.v1
+The `tokengen` tool uses a command-line interface with several subcommands. You can always use the `--help` flag to see available options for any command.
 
-This command takes an existing `zkatdlognoghv1_pp.json` and allows you to update the issuer and/or auditor certificates, while keeping the public parameters intact.
-
-```
-Usage:
-  tokengen update zkatdlognogh.v1 [flags]
-
-Flags:
-  -a, --auditors strings    list of auditor MSP directories containing the corresponding auditor certificate
-  -x, --extra stringArray   extra data in key=value format, where is the path to a file containing the data to load and store in the key
-  -h, --help                help for zkatdlognogh.v1
-  -i, --input string        path of the public param file
-  -s, --issuers strings     list of issuer MSP directories containing the corresponding issuer certificate
-  -o, --output string       output folder (default ".")
-  -v, --version uint        allows the caller of tokengen to override the version number put in the public params
+```bash
+tokengen [command] --help
 ```
 
-## tokengen pp
+### Core Commands
 
-The `tokengen pp` command has the following subcommands:
+- **`artifacts`**: Generates key material and configuration files from a topology description (YAML).
+- **`gen`**: Generates public parameters for specific drivers (e.g., `fabtoken.v1`, `zkatdlognogh.v1`).
+- **`update`**: Updates certificates within existing public parameters.
+- **`pp print`**: Inspects and prints human-readable details of a public parameters file.
+- **`certifier-keygen`**: Generates key pairs for token certifiers.
+- **`version`**: Displays the build version information.
 
-- print: Inspect public parameters
-
-### tokengen pp print
-
-```
-Usage:
-  tokengen pp print [flags]
-
-Flags:
-  -h, --help           help for print
-  -i, --input string   path of the public param file
-```
-
-## tokengen help
+### Examples
 
+#### Generate Public Parameters for FabToken
+```bash
+tokengen gen fabtoken.v1 --auditors ./msp/auditor --issuers ./msp/issuer --output ./params
 ```
-Help provides help for any command in the application.
-Simply type tokengen help [path to command] for full details.
 
-Usage:
-  tokengen help [command] [flags]
-
-Flags:
-  -h, --help   help for help
+#### Inspect Public Parameters
+```bash
+tokengen pp print --input ./params/fabtokenv1_pp.json
 ```
 
-## tokengen version
-
+#### Generate Artifacts from Topology
+```bash
+tokengen artifacts --topology ./topology.yaml --output ./artifacts
 ```
-Print current version of tokengen.
 
-Usage:
-  tokengen version [flags]
+## Configuration
 
-Flags:
-  -h, --help   help for version
-```
+`tokengen` can also be configured via environment variables prefixed with `CORE_`. For example, `CORE_LOGGING_LEVEL=debug` will set the logging level to debug.

cmd/tokengen/cobra/artifactgen/artifactgen_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// TestWriteTopologies tests the WriteTopologies function.
 func TestWriteTopologies(t *testing.T) {
 	tempDir := t.TempDir()
 	fileName := filepath.Join(tempDir, "topologies.yaml")

cmd/tokengen/cobra/artifactgen/gen/gen.go

@@ -19,14 +19,17 @@ import (
 	"gopkg.in/yaml.v2"
 )
 
+// Topology represents a topology.
 type Topology struct {
 	Type string `yaml:"type,omitempty"`
 }
 
+// Topologies represents a list of topologies.
 type Topologies struct {
 	Topologies []Topology `yaml:"topologies,omitempty"`
 }
 
+// T represents a list of topologies.
 type T struct {
 	Topologies []interface{} `yaml:"topologies,omitempty"`
 }
@@ -35,7 +38,7 @@ var topologyFile string
 var output string
 var port int
 
-// Cmd returns the Cobra Command for Version
+// Cmd returns the Cobra Command for generating artifacts.
 func Cmd() *cobra.Command {
 	// Set the flags on the node start command.
 	flags := cobraCommand.Flags()
@@ -85,6 +88,7 @@ func gen(args []string) error {
 	return nil
 }
 
+// LoadTopologies loads topologies from the given raw byte slice.
 func LoadTopologies(raw []byte) ([]api.Topology, error) {
 	names := &Topologies{}
 	if err := yaml.Unmarshal(raw, names); err != nil {

cmd/tokengen/cobra/artifactgen/gen/gen_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// TestCmd tests the Cmd function.
 func TestCmd(t *testing.T) {
 	cmd := Cmd()
 	assert.NotNil(t, cmd)
@@ -28,6 +29,7 @@ func TestCmd(t *testing.T) {
 	})
 }
 
+// TestGen tests the gen function and LoadTopologies.
 func TestGen(t *testing.T) {
 	tempDir := t.TempDir()
 

cmd/tokengen/cobra/artifactgen/testdata/topology.go

@@ -16,6 +16,7 @@ import (
 	"github.com/hyperledger-labs/fabric-token-sdk/integration/token/fungible/views"
 )
 
+// Topology returns a list of topologies for testing.
 func Topology(tokenSDKDriver string, sdks ...node.SDK) []api.Topology {
 	// Fabric
 	fabricTopology := fabric.NewDefaultTopology()

cmd/tokengen/cobra/artifactgen/utils.go

@@ -15,10 +15,12 @@ import (
 	"gopkg.in/yaml.v2"
 )
 
+// Topologies represents a list of topologies.
 type Topologies struct {
 	Topologies []api.Topology `yaml:"topologies,omitempty"`
 }
 
+// WriteTopologies writes the given topologies to the specified file.
 func WriteTopologies(fileName string, topologies []api.Topology, perm fs.FileMode) error {
 	raw, err := yaml.Marshal(&Topologies{Topologies: topologies})
 	if err != nil {

cmd/tokengen/cobra/certfier/keypairgen.go

@@ -23,7 +23,7 @@ var driver string
 var ppPath string
 var output string
 
-// KeyPairGenCmd returns the Cobra Command for the Certifier KeyGen
+// KeyPairGenCmd returns the Cobra Command for generating a Token Certifier Key Pair.
 func KeyPairGenCmd() *cobra.Command {
 	var cobraCommand = &cobra.Command{
 		Use:   "certifier-keygen",
@@ -48,7 +48,7 @@ func KeyPairGenCmd() *cobra.Command {
 	return cobraCommand
 }
 
-// keyPairGen
+// keyPairGen generates a certifier key-pair.
 func keyPairGen() error {
 	// TODO:
 	// 1. load public parameters from ppPath

cmd/tokengen/cobra/certfier/keypairgen_test.go

@@ -15,12 +15,14 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// TestKeyPairGenCmd tests the KeyPairGenCmd function.
 func TestKeyPairGenCmd(t *testing.T) {
 	cmd := KeyPairGenCmd()
 	assert.NotNil(t, cmd)
 	assert.Equal(t, "certifier-keygen", cmd.Use)
 }
 
+// TestKeyPairGen tests the keyPairGen function.
 func TestKeyPairGen(t *testing.T) {
 	wd, _ := os.Getwd()
 	testdataPath := filepath.Join(wd, "..", "..", "testdata", "zkatdlognoghv1_pp.json")
@@ -53,6 +55,7 @@ func TestKeyPairGen(t *testing.T) {
 	})
 }
 
+// TestCobraCommand tests the Cobra command for generating certifier key pairs.
 func TestCobraCommand(t *testing.T) {
 	wd, _ := os.Getwd()
 	testdataPath := filepath.Join(wd, "..", "..", "testdata", "zkatdlognoghv1_pp.json")

cmd/tokengen/cobra/pp/cc/cc.go

@@ -18,7 +18,7 @@ import (
 	"github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors"
 )
 
-// GeneratePackage generates the chaincode package for the given raw public parameters
+// GeneratePackage generates the chaincode package for the given raw public parameters.
 func GeneratePackage(raw []byte, outputDir string) error {
 	t, err := template.New("node").Funcs(template.FuncMap{
 		"Params": func() string { return base64.StdEncoding.EncodeToString(raw) },

cmd/tokengen/cobra/pp/cc/cc_test.go

@@ -7,10 +7,11 @@ SPDX-License-Identifier: Apache-2.0
 package cc
 
 import (
-	"testing"
 	"github.com/stretchr/testify/assert"
+	"testing"
 )
 
+// TestGeneratePackage tests the GeneratePackage function.
 func TestGeneratePackage(t *testing.T) {
 	t.Run("fail_package", func(t *testing.T) {
 		// Providing an invalid path should make PackageChaincode fail.