documentation update (#1314)

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

Author: adecaro

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Fabric Token SDK
+
+We welcome contributions to the Fabric Token SDK!
+
+Note that we follow the [LFDT Charter](https://www.lfdecentralizedtrust.org/about/charter). 
+All new inbound code contributions to the project shall be made under the Apache License, Version 2.0. 
+All outbound code will be made available under the Apache License, Version 2.0.
+
+## Code of Conduct
+
+Please note that we have a [Code of Conduct](CODE_OF_CONDUCT.md). Please follow it in all your interactions with the project.
+
+## How to Contribute
+
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** locally.
+3.  **Create a new branch** for your feature or bugfix.
+4.  **Make your changes**.
+5.  **Run tests** (see [Testing Guide](docs/development/testing.md)) to ensure your changes don't break anything.
+6.  **Commit your changes** using the sign-off flag (`-s`).
+7.  **Push your branch** to your fork.
+8.  **Submit a Pull Request** (PR) to the `main` branch of the upstream repository.
+
+## Good first issues
+
+We maintain a set of issues labeled "good first issue" to help new contributors find approachable tasks and get started quickly. 
+If you're contributing for the first time, please consider picking one of these issues:
+
+- Browse the current list here: https://github.com/hyperledger-labs/fabric-token-sdk/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22
+- Leave a comment on the issue saying you'd like to work on it and ask to be assigned.
+- If you need clarification or guidance, ask on our Discord channel (`#fabric-token-sdk`) or comment on the issue — maintainers and community members are happy to help.
+- Keep your first PR small and focused. Follow the project guidelines: run tests, sign your commits (`-s`), and rebase to keep a linear history.
+
+## Detailed Development Guidelines
+
+Please refer to the [Development Guidelines](docs/development/development.md) for detailed information on:
+
+*   **Commit Sign-off**: All commits must be signed off (`git commit -s`).
+*   **Linear History**: We use rebase workflow, not merge commits.
+*   **Coding Standards**: See [docs/development/general.md](docs/development/general.md) and [docs/development/idiomatic.md](docs/development/idiomatic.md) for Go coding standards.
+
+## Reporting Issues
+
+If you find a bug or have a feature request, please search the [Issues](https://github.com/hyperledger-labs/fabric-token-sdk/issues) to see if it has already been reported. If not, please open a new issue.
+
+## Community
+
+Join us on [Discord](https://discord.gg/hyperledger) in the `#fabric-token-sdk` channel.

Makefile

@@ -27,52 +27,62 @@ include $(TOP)/fungible.mk
 all: install-tools install-softhsm checks unit-tests #integration-tests
 
 .PHONY: install-tools
+# install tools required for development and testing
 install-tools:
 # Thanks for great inspiration https://marcofranssen.nl/manage-go-tools-via-go-modules
 	@echo Installing tools from tools/tools.go
 	@cd tools; cat tools.go | grep _ | awk -F'"' '{print $$2}' | xargs -tI % go install %
 	@$(MAKE) install-linter-tool
 
 .PHONY: download-fabric
+# download fabric binaries
 download-fabric:
 	./ci/scripts/download_fabric.sh $(FABRIC_BINARY_BASE) $(FABRIC_VERSION) $(FABRIC_CA_VERSION)
 
 .PHONY: unit-tests
+# run standard unit tests
 unit-tests:
 	@go test -cover $(shell go list ./... | grep -v '/integration/' | grep -v 'regression')
 	cd integration/nwo/; go test -cover ./...
 	cd token/services/storage/db/kvs/hashicorp/; go test -cover ./...
 
 .PHONY: unit-tests-race
+# run unit tests with race detection
 unit-tests-race:
 	@export GORACE=history_size=7; go test -race -cover $(shell go list ./... | grep -v '/integration/'  | grep -v 'regression')
 	cd integration/nwo/; go test -cover ./...
 
 .PHONY: unit-tests-regression
+# run regression unit tests
 unit-tests-regression:
 	@go test -race -timeout 0 -cover $(shell go list ./... | grep -v '/integration/' | grep 'regression')
 
 .PHONY: install-softhsm
+# install softhsm for testing
 install-softhsm:
 	./ci/scripts/install_softhsm.sh
 
 .PHONY: docker-images
+# build/pull docker images needed for testing
 docker-images: fabric-docker-images monitoring-docker-images testing-docker-images
 
 .PHONY: testing-docker-images
+# pull docker images for testing (postgres, vault)
 testing-docker-images:
 	docker pull postgres:16.2-alpine
 	docker tag postgres:16.2-alpine fsc.itests/postgres:latest
 	docker pull hashicorp/vault
 
 .PHONY: fabric-docker-images
+# pull fabric docker images
 fabric-docker-images:
 	docker pull hyperledger/fabric-baseos:$(FABRIC_TWO_DIGIT_VERSION)
 	docker image tag hyperledger/fabric-baseos:$(FABRIC_TWO_DIGIT_VERSION) hyperledger/fabric-baseos:latest
 	docker pull hyperledger/fabric-ccenv:$(FABRIC_TWO_DIGIT_VERSION)
 	docker image tag hyperledger/fabric-ccenv:$(FABRIC_TWO_DIGIT_VERSION) hyperledger/fabric-ccenv:latest
 
 .PHONY: monitoring-docker-images
+# pull monitoring docker images (explorer, prometheus, grafana, jaeger)
 monitoring-docker-images:
 	docker pull ghcr.io/hyperledger-labs/explorer-db:latest
 	docker pull ghcr.io/hyperledger-labs/explorer:latest
@@ -81,29 +91,35 @@ monitoring-docker-images:
 	docker pull cr.jaegertracing.io/jaegertracing/jaeger:2.12.0
 
 .PHONY: integration-tests-nft-dlog
+# run nft integration tests with idemix
 integration-tests-nft-dlog:
 	cd ./integration/token/nft/dlog; export FAB_BINS=$(FAB_BINS); ginkgo $(GINKGO_TEST_OPTS) .
 
 .PHONY: integration-tests-nft-fabtoken
+# run nft integration tests with fabtoken
 integration-tests-nft-fabtoken:
 	cd ./integration/token/nft/fabtoken; export FAB_BINS=$(FAB_BINS); ginkgo $(GINKGO_TEST_OPTS) .
 
 .PHONY: integration-tests-dvp-fabtoken
+# run dvp integration tests with fabtoken
 integration-tests-dvp-fabtoken:
 	cd ./integration/token/dvp/fabtoken; export FAB_BINS=$(FAB_BINS); ginkgo $(GINKGO_TEST_OPTS) .
 
 .PHONY: integration-tests-dvp-dlog
+# run dvp integration tests with idemix
 integration-tests-dvp-dlog:
 	cd ./integration/token/dvp/dlog; export FAB_BINS=$(FAB_BINS); ginkgo $(GINKGO_TEST_OPTS) .
 
 
 .PHONY: tidy
+# tidy up go modules
 tidy:
 	@go mod tidy
 	cd tools; go mod tidy
 	cd token/services/storage/db/kvs/hashicorp; go mod tidy
 
 .PHONY: clean
+# clean up docker artifacts and generated files
 clean:
 	docker network prune -f
 	docker container prune -f
@@ -132,41 +148,50 @@ clean:
 	rm -rf ./integration/token/fungible/update/testdata/
 
 .PHONY: clean-fabric-peer-images
+# clean up fabric peer images
 clean-fabric-peer-images:
 	docker images -a | grep "_peer.org" | awk '{print $3}' | xargs docker rmi
 	docker images -a | grep "_peer_" | awk '{print $3}' | xargs docker rmi
 
 .PHONY: tokengen
+# install tokengen tool
 tokengen:
 	@go install ./cmd/tokengen
 
 .PHONY: traceinspector
+# install traceinspector tool
 traceinspector:
 	@go install ./token/services/benchmark/cmd/traceinspector
 
 .PHONY: memcheck
+# install memcheck tool
 memcheck:
 	@go install ./token/services/benchmark/cmd/memcheck
 
 .PHONY: idemixgen
+# install idemixgen/txgen tool
 txgen:
 	@go install github.com/IBM/idemix/tools/idemixgen
 
 .PHONY: clean-all-containers
+# clean up all docker containers
 clean-all-containers:
 	@if [ -n "$$(docker ps -aq)" ]; then docker rm -f $$(docker ps -aq); else echo "No containers to remove"; fi
 
 .PHONY: lint
+# run various linters
 lint:
 	@echo "Running Go Linters..."
 	golangci-lint run --color=always --timeout=4m
 
 .PHONY: lint-auto-fix
+# run linters with auto-fix
 lint-auto-fix:
 	@echo "Running Go Linters with auto-fix..."
 	golangci-lint run --color=always --timeout=4m --fix
 
 .PHONY: install-linter-tool
+# install golangci-lint
 install-linter-tool:
 	@echo "Installing golangci Linter"
 	@curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(HOME)/go/bin v2.8.0

README.md

@@ -12,9 +12,10 @@ The `Fabric Token SDK` provides a collection of APIs and services that streamlin
 The project will be subject to rapid changes to complete the open-sourcing process, and  the list of features.
 
 # Useful Links
-
-- [`Documentation`](docs/tokensdk.md): The design principles of the Fabric Token SDK.
+ 
+- [`Documentation`](docs/README.md): The entry point for the Fabric Token SDK documentation.
 - [`Development`](docs/development/development.md): All about the development guidelines.
+- [`Contributing`](CONTRIBUTING.md): How to contribute to the project.
 - [`Fabric Samples`](https://github.com/hyperledger/fabric-samples/tree/main/token-sdk) Token SDK sample application is the
   quickest way to get a full network running with a REST API to issue, transfer and redeem tokens right away.
 - [`Benchmarks`](./docs/benchmark/benchmark.md): Benchmark guidelines and reports.
@@ -26,44 +27,6 @@ The project will be subject to rapid changes to complete the open-sourcing proce
 - [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client): The Token SDK leverages the 
   `Fabric Smart Client` for transaction orchestration, storing tokens and wallets, and more. Check it out.
 
-# Getting started
-
-Clone the code and make sure it is on your `$GOPATH`.
-(Important: we assume in this documentation and default configuration that your `$GOPATH` has a single root-directory!).
-Sometimes, we use `$FTS_PATH` to refer to the Fabric Token SDK repository in your filesystem.
-
-```bash
-export FTS_PATH=$GOPATH/src/github.com/hyperledger-labs/fabric-token-sdk
-git clone https://github.com/hyperledger-labs/fabric-token-sdk.git $FTS_PATH
-```
-
-## Further information
-
-Fabric Token SDK uses a system called `NWO` from Fabric Smart Client for its integration tests and samples to programmatically create a fabric network along with the fabric-smart-client nodes. The current version of fabric that is tested can be found in the project [Makefile](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/Makefile) set in the `FABRIC_VERSION` variable.
-
-In order for a fabric network to be able to be created you need to ensure you have downloaded the appropriate version of the hyperledger fabric binaries from [Fabric Releases](https://github.com/hyperledger/fabric/releases) and unpack the compressed file onto your file system. This will create a directory structure of /bin and /config. You will then need to set the environment variable `FAB_BINS` to the `bin` directory. For example if you unpacked the compressed file into `/home/name/fabric` then you would
-
-```bash
-export FAB_BINS=/home/name/fabric/bin
-```
-
-Do not store the fabric binaries within your fabric-token-sdk cloned repo as this will cause problems running the samples and integration tests as they will not be able to install chaincode.
-
-Almost all the samples and integration tests require the fabric binaries to be downloaded and the environment variable `FAB_BINS` set to point to the directory where these binaries are stored. One way to ensure this is to execute the following in the root of the fabric-token-sdk project
-
-```shell
-make download-fabric
-export FAB_BINS=$PWD/../fabric/bin
-```
-
-You can also use this to download a different version of the fabric binaries for example
-
-```shell
-FABRIC_VERSION=2.5 make download-fabric
-```
-
-If you want to provide your own versions of the fabric binaries then just set `FAB_BINS` to the directory where all the fabric binaries are stored.
-
 # Additional Resources
 
 - (March 17, 2022) [`Hyperledger in-Depth: Tokens in Hyperledger Fabric: What’s possible today and what’s coming`](https://www.hyperledger.org/learn/webinars/hyperledger-in-depth-tokens-in-hyperledger-fabric-whats-possible-today-and-whats-coming):
@@ -102,13 +65,9 @@ The Fabric Token SDK has evolved beyond its initial focus on Hyperledger Fabric.
 
 With a robust Fabric Token SDK, developing secure and efficient enterprise-grade tokenized applications becomes a reality, offering flexibility for developers to choose the platform that best suits their needs.
 
-# Development
-
-For additional information about the development of the Token SDK, visit this [`section`](./docs/development/development.md).
-
 # License
 
 This project is licensed under the Apache 2 License - see the [`LICENSE`](LICENSE) file for details
 
 [`fabric-token-sdk` Issues]: https://github.com/hyperledger-labs/fabric-token-sdk/issues
-[GitHub discussions]: https://github.com/hyperledger-labs/fabric-token-sdk/discussions
+[#fabric-token-sdk in Discord]: https://discord.gg/hyperledger

ci/scripts/download_fabric.sh

@@ -18,7 +18,7 @@ download() {
 }
 
 pullBinaries() {
-    ARCH=$(echo "$(uname -s|tr '[:upper:]' '[:lower:]'|sed 's/mingw64_nt.*/windows/')-$(uname -m |sed 's/x86_64/amd64/g')" |sed 's/darwin-arm64/darwin-amd64/g')
+    ARCH=$(echo "$(uname -s | tr '[:upper:]' '[:lower:]' | sed 's/mingw64_nt.*/windows/')-$(uname -m | tr '[:upper:]' '[:lower:]' | sed 's/x86_64/amd64/g; s/aarch64/arm64/g; s/^armv8.*$/arm64/g')" | sed 's/darwin-arm64/darwin-amd64/g')
     MARCH=$(uname -m)
     local VERSION=$1
     local CA_VERSION=$2

docs/README.md

@@ -0,0 +1,25 @@
+# Fabric Token SDK Documentation
+
+Welcome to the Fabric Token SDK documentation.
+
+## Core Concepts
+
+*   [**Token SDK Overview**](tokensdk.md): Start here to understand the architecture, key concepts (Tokens, Wallets, Privacy), and layers of the SDK.
+*   [**Token API**](tokenapi.md): The high-level API for interacting with tokens.
+*   [**Token API Usage**](token_sdk_usage.md): API Usage Guide.
+*   [**Driver API**](driverapi.md): The interface for building token drivers.
+*   [**Core Token**](core-token.md): Core token definitions.
+*   [**Services**](services.md): Additional services like transaction assembly.
+
+## Development
+
+If you are developing *using* the SDK or contributing *to* the SDK, check out the [Development](development/development.md) section.
+
+*   [General Guidelines](development/general.md)
+*   [Idiomatic Go](development/idiomatic.md)
+*   [Testing](development/testing.md)
+
+## Guides & Tutorials
+
+*   [Fabric Smart Client](https://github.com/hyperledger-labs/fabric-smart-client): The underlying platform.
+*   [Fabric Samples](https://github.com/hyperledger/fabric-samples/tree/main/token-sdk): Runnable examples.

docs/development/development.md

@@ -10,6 +10,7 @@ This page contains link to the development guidelines and more.
 - [Monitoring](./monitoring.md)
 - [Mock Files Generation](./mock.md)
 - [Tools: tokengen](./tokengen.md)
+- [Makefile Guide](./makefile.md)
 
 ## Useful resources
 

docs/development/makefile.md

@@ -0,0 +1,70 @@
+# Makefile Guide
+
+This document explains the targets available in the `Makefile` for the Fabric Token SDK. The Makefile allows you to automate common tasks such as installing tools, running tests, and managing Docker images.
+
+## Setup & Installation
+
+These targets help you set up your development environment.
+
+| Target | Description |
+| :--- | :--- |
+| `make install-tools` | Installs necessary Go tools (linters, generators, etc.) defined in `tools/tools.go`. It also installs `golangci-lint`. |
+| `make download-fabric` | Downloads Hyperledger Fabric binaries. You can specify `FABRIC_VERSION` and `FABRIC_CA_VERSION` env vars to control the versions. |
+| `make install-softhsm` | Installs SoftHSM for testing hardware security module integration. |
+
+## Testing
+
+These targets run various test suites.
+
+### Unit Tests
+
+| Target | Description |
+| :--- | :--- |
+| `make unit-tests` | Runs standard unit tests for the SDK, excluding integration and regression tests. |
+| `make unit-tests-race` | Runs unit tests with the Go race detector enabled. |
+| `make unit-tests-regression` | Runs regression tests. |
+
+### Integration Tests
+
+The SDK has several integration test targets. Some common ones include:
+
+| Target | Description |
+| :--- | :--- |
+| `make integration-tests-nft-dlog` | Runs NFT integration tests with Idemix driver. |
+| `make integration-tests-nft-fabtoken` | Runs NFT integration tests with FabToken driver. |
+| `make integration-tests-dvp-fabtoken` | Runs Delivery vs Payment (DvP) integration tests with FabToken. |
+| `make integration-tests-dvp-dlog` | Runs DvP integration tests with Idemix. |
+
+(See the `Makefile` for the full list of integration test targets).
+
+## Docker Images
+
+These targets build or pull Docker images required for testing and development.
+
+| Target | Description |
+| :--- | :--- |
+| `make docker-images` | Pulls all necessary images (Fabric, monitoring, testing). |
+| `make fabric-docker-images` | Pulls Hyperledger Fabric images. |
+| `make testing-docker-images` | Pulls images like Postgres and Vault for testing. |
+| `make monitoring-docker-images` | Pulls monitoring tools like Prometheus, Grafana, Jaeger, and Explorer. |
+
+## Maintenance
+
+These targets help keep your project clean and tidy.
+
+| Target | Description |
+| :--- | :--- |
+| `make tidy` | Runs `go mod tidy` in all modules to ensure dependencies are clean. |
+| `make clean` | cleans up Docker artifacts (containers, volumes, networks) and removes generated test output directories. **Use with caution as it removes Docker volumes.** |
+| `make clean-all-containers` | Removes all running and stopped Docker containers. |
+| `make clean-fabric-peer-images` | Removes Docker images related to Fabric peers. |
+| `make lint` | Runs `golangci-lint` to check code quality. |
+| `make lint-auto-fix` | Runs `golangci-lint` and automatically fixes issues where possible. |
+
+## Tools Generation
+
+| Target | Description |
+| :--- | :--- |
+| `make tokengen` | Installs the `tokengen` tool. |
+| `make traceinspector` | Installs the `traceinspector` tool. |
+| `make memcheck` | Installs the `memcheck` tool. |