Skip to content

AGENTS.md

Latest commit

 

History

History
234 lines (189 loc) · 8.31 KB

AGENTS.md

File metadata and controls

234 lines (189 loc) · 8.31 KB

Fabric Token SDK

Performance Tip: Use Ctrl+F to jump to sections using anchor links (e.g., #building-and-running)

🚀 Quick Reference Commands

Testing

  • make unit-tests - Run unit tests
  • make unit-tests-race - Unit tests with race detector
  • make integration-tests-fabtoken-fabric-t1 - Fabtoken integration tests
  • make integration-tests-dlog-fabric-t1 TEST_FILTER="T1" - ZK integration tests with T1 filter

Development & CI Preparation

  • make fmt - Format code using gofmt
  • make lint - Check code style
  • make lint-auto-fix - Auto-fix linting issues (recommended pre-commit)
  • make install-tools - Install development dependencies
  • make checks - Run all pre-CI checks (license, fmt, vet, etc.)
  • make download-fabric - Download Fabric binaries
  • make docker-images - Prepare Docker images
  • make testing-docker-images - Prepare test Docker images

Maintenance

  • make clean - Remove build artifacts
  • make clean-all-containers - Remove Docker containers
  • make tidy - Synchronize Go dependencies
  • go generate ./... - Generate mocks

📁 Project Structure

token/
├── core/          # Driver implementations (fabtoken, zkatdlog)
├── driver/        # Interface definitions (ports)
├── services/      # High-level services (identity, network, ttx, storage)
└── sdk/           # Public API entry points
integration/
├── nwo/           # Network Orchestrator for test networks
└── token/         # Actual test suites (fungible, nft, dvp, etc.)

🔧 Development Workflow

1. Setup (One-time)

make install-tools
make download-fabric
export FAB_BINS=$PWD/../fabric/bin
make docker-images
make testing-docker-images

2. Daily Development

# Code quality
make lint-auto-fix
make checks

# Testing
make unit-tests          # Standard
make unit-tests-race     # With race detection
make integration-tests-fabtoken-fabric-t1  # Integration tests

3. Debugging

# Performance profiling
go test -cpuprofile=cpu.out ./...
go test -memprofile=mem.out ./...

# Focused testing
make integration-tests-dlog-fabric TEST_FILTER="T1"

🐛 Troubleshooting Quick Reference

  • Chaincode packaging failed: Verify FAB_BINS is set correctly and points to valid Fabric binaries
  • Docker errors: Run make testing-docker-images
  • Linting errors on commit: Run make lint-auto-fix
  • Test timeouts: Increase Docker resource allocation
  • Permission denied: chmod +x on Fabric binaries in $FAB_BINS
  • Container conflicts: make clean-all-containers
  • Go module issues: make tidy
  • Mock generation failures: make install-tools (ensures counterfeiter is installed)

🔄 CI Workflow Overview

To ensure your commits pass CI automatically, understand what runs:

🔧 Pre-Merge Checks (GitHub Actions)

All PRs and pushes to main trigger these workflows:

  1. Checks Job (Prerequisite):

    • License verification
    • Code formatting (gofmt, goimports)
    • Static analysis (govet, staticcheck, ineffassign, misspell)
    • Run locally with: make checks

  2. Unit Testing:

    • Race detector enabled tests
    • Regression tests
    • Coverage reporting to Coveralls

  3. Integration Testing (Extensive Matrix):

    • Fabtoken (cleartext tokens): t1-t5
    • ZKATDLog (privacy tokens): t1-t13
    • Fabric-X, Interop, NFT, DVP, Update tests
    • Stress tests
    • All with coverage reporting

  4. Separate Workflows:

    • golangci-lint: Comprehensive linting (30 min timeout)
    • Markdown links: Validates all doc links
    • CodeQL: Security analysis (weekly + on push/PR)

💡 Best Practices for CI Success

  • Always run make checks and make lint-auto-fix before committing
  • Verify FAB_BINS is set for integration test compatibility
  • Address all linting and static check warnings promptly
  • Keep dependencies updated with make tidy

🏗️ Architecture Overview

Core Patterns

  • Driver Pattern: Swappable token technologies via interfaces in token/driver
  • Service Pattern: Encapsulated high-level logic in token/services
  • TTX Service: Orchestrates token transaction lifecycle (Request → Assemble → Sign → Commit)

Key Technologies

  • Go 1.24+
  • Hyperledger Fabric
  • Fabric Smart Client (FSC)
  • Idemix/zkatdlog (privacy)
  • Mathlib
  • Ginkgo (testing framework)
  • Cobra (CLI framework)

🧪 Testing Strategy

Unit Tests

  • Located alongside implementation code (*_test.go)
  • Use testify for assertions (assert for values, require for error handling)
  • Prefer table-driven tests for service logic
  • Use context struct pattern to minimize mock boilerplate

Integration Tests

  • Located in integration/ directory
  • Utilize Network Orchestrator (NWO) for ephemeral Fabric networks
  • Use TEST_FILTER environment variable with Ginkgo labels for focused testing
  • Example: TEST_FILTER="T1" runs only tests with T1 label

Mocking Best Practices

  • Generate mocks with counterfeiter (go generate ./...)
  • Use disabled.Provider for metrics to avoid nil panics
  • Use noop.NewTracerProvider() for tracing
  • Employ Context Struct + Setup Helper pattern (see token/services/ttx for example)

📝 Development Conventions

Coding Standards

  • Error Handling: Handle errors explicitly; avoid blank identifier for errors
  • Interfaces: Define small, focused interfaces on consumer side; favor composition
  • Concurrency: Use goroutines and channels; avoid shared state; validate with race detector
  • Globals: Avoid global variables for testability
  • Documentation: All exported functions MUST have Godoc comments

Git Workflow

  • DCO Sign-off: All commits MUST be signed off (git commit -s)
  • Linear History: Use rebase workflow; avoid merge commits
  • License: Apache License, Version 2.0

Plan Documentation (Workflow Rule)

Before implementing any task:

  1. Create plan.md in project root with:
    • Clear goal description
    • Numbered implementation steps
    • "Implementation Progress" section with [ ] Pending checkboxes
  2. Update immediately when completing steps: [x] Done + brief change notes
  3. Log blockers/decisions under ## Notes & Decisions
  4. Mark plan as ✅ COMPLETE when finished

🔍 Debugging & Advanced Testing

Log Locations

  • Integration Tests: System temp directory (/tmp/fsc-integration-<random>/...)
  • Containers: docker logs <container_name>
  • Persisted Logs: Temporarily modify test to use NewLocalTestSuite (outputs to ./testdata)

Debugging Techniques

  • Manual Inspection: Use time.Sleep() or pause loops in tests to inspect Docker state
  • Network Preservation: Check for no-cleanup option or manually comment test suite cleanup
  • Focused Tests: Modify It(...) to FIt(...) to focus, or XIt(...) to skip (never commit these changes)

📚 Key Files & Directories

  • Makefile: Central control hub - read to discover targets
  • go.mod: Project dependencies
  • tools/tools.go: Tool dependencies source of truth (install with make install-tools)
  • token/: Core SDK logic
  • integration/: Integration tests and Network Orchestrator

🔄 CI Workflow Overview

To ensure your commits pass CI automatically, understand what runs:

🔧 Pre-Merge Checks (GitHub Actions)

All PRs and pushes to main trigger these workflows:

  1. Checks Job (Prerequisite):

    • License verification
    • Code formatting (gofmt, goimports)
    • Static analysis (govet, staticcheck, ineffassign, misspell)
    • Run locally with: make checks

  2. Unit Testing:

    • Race detector enabled tests
    • Regression tests
    • Coverage reporting to Coveralls

  3. Integration Testing (Extensive Matrix):

    • Fabtoken (cleartext tokens): t1-t5
    • ZKATDLog (privacy tokens): t1-t13
    • Fabric-X, Interop, NFT, DVP, Update tests
    • Stress tests
    • All with coverage reporting

  4. Separate Workflows:

    • golangci-lint: Comprehensive linting (30 min timeout)
    • Markdown links: Validates all doc links
    • CodeQL: Security analysis (weekly + on push/PR)

💡 Best Practices for CI Success

  • Always run make checks and make lint-auto-fix before committing
  • Verify FAB_BINS is set for integration test compatibility
  • Address all linting and static check warnings promptly
  • Keep dependencies updated with make tidy