💰 Solana USDC Payroll Template

Open-source template for processing payroll payments in USDC on Solana blockchain

🌟 Features

• ✅ Batch USDC Payments - Process multiple payments from a CSV file
• ✅ Dry Run Mode - Test payments without sending real transactions
• ✅ Error Handling - Automatic retries and detailed error reporting
• ✅ Transaction Logging - Save all payment results to JSON
• ✅ Balance Checking - Verify sufficient funds before processing
• ✅ Customizable - Easy configuration via environment variables
• ✅ Production Ready - Built with TypeScript and best practices

📋 Prerequisites

• Node.js v16 or higher
• npm or yarn
• Solana wallet with some SOL for transaction fees
• USDC tokens in your wallet (for production payments)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/solana-usdc-payroll-template.git
cd solana-usdc-payroll-template

2. Install Dependencies

npm install

3. Configure Environment

cp .env.example .env

Edit .env with your configuration:

SOLANA_NETWORK=devnet
SOLANA_RPC_URL=https://api.devnet.solana.com
PAYER_PRIVATE_KEY=your_base58_private_key_here
USDC_MINT_ADDRESS=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
DRY_RUN=true
CSV_FILE_PATH=./examples/employees.csv

4. Prepare Your CSV

Create or edit examples/employees.csv:

employee_name,wallet_address,amount,description
Alice Johnson,5ZWj7a1f8tWkjBESHKgrLmXshuXxqeY9SYcfbshpAqPG,1500.00,December Salary
Bob Smith,7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU,2000.00,December Salary

5. Run Payroll (Dry Run)

npm start

This will simulate payments without sending them.

6. Run Real Payments

When ready, set DRY_RUN=false in .env, then:

npm start

📁 Project Structure

solana-usdc-payroll-template/
├── src/
│   ├── config.ts          # Configuration management
│   ├── payroll.ts         # Core payment logic
│   ├── utils.ts           # Helper functions
│   └── index.ts           # Main entry point
├── examples/
│   ├── employees.csv      # Sample employee list
│   └── .env.example       # Example environment variables
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

⚙️ Configuration

Environment Variables

Variable	Description	Default	Required
SOLANA_NETWORK	Network to use (devnet/mainnet-beta)	devnet	No
SOLANA_RPC_URL	RPC endpoint URL	-	Yes
PAYER_PRIVATE_KEY	Your wallet's private key (base58)	-	Yes
USDC_MINT_ADDRESS	USDC token mint address	-	Yes
DRY_RUN	Simulate without sending (true/false)	true	No
CSV_FILE_PATH	Path to CSV file	./examples/employees.csv	No
MAX_RETRIES	Transaction retry attempts	3	No
BATCH_DELAY	Delay between payments (ms)	1000	No

USDC Mint Addresses

• Devnet: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
• Mainnet: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

📊 CSV Format

Your CSV file must have these columns:

Column	Description	Example
employee_name	Employee's name	Alice Johnson
wallet_address	Solana wallet address	5ZWj7a1f8t...
amount	Amount in USDC	1500.00
description	Payment description	December Salary

🔐 Security Best Practices

1. Never commit .env file - It contains your private key
2. Use environment-specific keys - Different keys for dev/prod
3. Test on devnet first - Always test before mainnet
4. Keep private keys secure - Store in password manager
5. Monitor transaction results - Check all signatures on Solscan
6. Limit wallet balance - Don't keep more USDC than needed

🛠️ Common Use Cases

Running on Mainnet

1. Change SOLANA_NETWORK=mainnet-beta
2. Update SOLANA_RPC_URL to mainnet RPC
3. Use mainnet USDC mint address
4. Fund your wallet with SOL and USDC
5. Set DRY_RUN=false

Getting Devnet USDC

# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/v1.17.0/install)"

# Get devnet SOL
solana airdrop 2

# Use a faucet for devnet USDC (search "Solana devnet USDC faucet")

Generating a New Wallet

# Using Solana CLI
solana-keygen new --no-bip39-passphrase --outfile keypair.json

# Get the private key in base58
solana-keygen pubkey keypair.json

📝 Scripts

Command	Description
npm start	Run payroll processor
npm run build	Compile TypeScript to JavaScript
npm run dry-run	Force dry run mode

🔍 Troubleshooting

"Insufficient balance" error

• Check your USDC balance matches the total payment amount
• Ensure you have SOL for transaction fees (~0.005 SOL per transaction)

"Invalid wallet address" error

• Verify wallet addresses in CSV are valid Solana addresses
• Check for extra spaces or special characters

"Transaction failed" error

• Check your internet connection
• Verify RPC endpoint is responding
• Try reducing BATCH_DELAY or increasing MAX_RETRIES

"Cannot find module" error

• Run npm install again
• Delete node_modules and package-lock.json, then reinstall

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This software is provided "as is" without warranty of any kind. Use at your own risk. Always test thoroughly on devnet before using with real funds on mainnet.

🙏 Acknowledgments

• Built with Solana Web3.js
• Uses SPL Token standard
• Inspired by the need for simple, open-source crypto payroll solutions

📞 Support

• Create an Issue
• Star ⭐ this repo if you find it helpful!

---

Made with ❤️ for the Solana community