Add contribution token

[joelamouche]

Add Contribution Token (TGC) and Batch Minting Infrastructure

Summary

This PR introduces the TheGuildContributionToken (TGC), an upgradeable ERC20 token for rewarding contributions within The Guild ecosystem. It includes deployment scripts, batch minting capabilities, comprehensive tests, and helper scripts for streamlined operations.

Changes

🆕 New Contracts & Scripts

• src/TheGuildContributionToken.sol: Upgradeable ERC20 token (UUPS) with:

  • Standard minting (mint)
  • Minting with reason (mintWithReason) that emits MintedWithReason event
  • Batch minting (batchMint, batchMintWithReason)
  • Owner-only access control

• script/DeployTGC.s.sol: Deterministic deployment script using CREATE2:

  • Deploys implementation and ERC1967 proxy with fixed salt
  • Properly initializes proxy so deployer EOA becomes owner (not CREATE2 factory)
  • Logs proxy, implementation, and deployer addresses

• script/MintTGCFromJson.s.sol: Batch minting script from JSON:

  • Parses JSON file with mint entries (recipient, amount, reason)
  • Supports hex string reasons via vm.parseBytes
  • Dry-run mode for validation
  • Defaults to contribution-tokens-latest.json

• script/UpgradeTGCImplementation.s.sol: Upgrade script for UUPS proxy

• test/TheGuildContributionToken.t.sol: Comprehensive test suite:

  • Metadata validation (name, symbol, decimals)
  • Ownership checks
  • Minting functionality
  • MintedWithReason event emission
  • Batch minting operations

🔧 Improvements to Existing Scripts

• run_batch_contribution_tokens.sh:
  • New helper script for batch TGC minting
  • Defaults to contribution-tokens-latest.json
  • Validates required environment variables (PRIVATE_KEY, RPC_URL, TGC_PROXY_ADDRESS)
  • Supports dry-run mode

📚 Documentation

• Added comprehensive TGC documentation to README.md:
  • Contract overview and key functions
  • Deployment instructions
  • Batch minting JSON format and usage
  • Upgrade procedures
  • Environment variables reference
• Updated deployment addresses section with TGC proxy address

Technical Details

Deterministic Deployment

The DeployTGC script uses CREATE2 with salt "theguild_tgc_v_0.1.2" for deterministic addresses across networks. The proxy is deployed without initialization data, then initialize() is called directly from the deployer EOA to ensure proper ownership setup.

JSON Parsing Fix

The batch minting script correctly handles hex string reasons in JSON by:

1. Parsing as string using stdJson.readString
2. Converting to bytes using vm.parseBytes

This ensures hex strings like "0x476974687562..." are properly decoded.

Testing

• ✅ All new tests pass (forge test)
• ✅ Dry-run mode validated for batch minting
• ✅ Deployment script tested on Amoy testnet

Deployment

TGC has been deployed to Polygon Amoy:

• Proxy: 0x14d403EaE3E0b2E2dc6379C9729Df6906fF38bE7
• Salt: "theguild_tgc_v_0.1.2"

Usage Examples

Deploy TGC

export PRIVATE_KEY=your_private_key
forge script script/DeployTGC.s.sol:DeployTGC \
  --rpc-url <your_rpc_url> \
  --broadcast

Batch Mint from JSON

export PRIVATE_KEY=your_private_key
export TGC_PROXY_ADDRESS=0x14d403EaE3E0b2E2dc6379C9729Df6906fF38bE7
export RPC_URL=https://polygon-amoy.infura.io/v3/...

# Dry run
./run_batch_contribution_tokens.sh true

# Production
./run_batch_contribution_tokens.sh false

Breaking Changes

None. This is a new feature addition.

Related Issues

• Implements Contribution Token specification
• Enables batch distribution of contribution rewards
• Provides upgradeable token infrastructure for future enhancements

[tusharshah21]

Enhancement: Reason String Encoder Utility

POV:
Currently, the contribution-tokens-latest.json requires hex-encoded reasons (e.g., 0x4769746875622068616e646c65206572726f7273).
This creates friction when:

• Manually creating new mint batches
• Documenting what reasons represent
• Collaborating with non-technical team members

Proposal:
Create a helper script to auto-generate hex-encoded reasons:

node scripts/encodeReasons.js --input contributions.csv --output contribution-tokens-latest.json

can we do this, both were just a suggestion to make it more reliable. The cover is pretty optimal already if I am not wrong though! Thanks

[joelamouche]

@tusharshah21

Enhancement: Reason String Encoder Utility

excellent suggestion!
But instead of adding a utility I think I will just do the conversion in the script that way we have one single file with explicit text reasons

[tusharshah21]

Understood, LGTM now