npm package: @lasergun-protocol/contracts
Description: Anonymous token transfer system with zero-knowledge privacy
Author: Ilya A. Shlyakhovoy
Latest version: 1.1.1

# Anonymous Shield Smart Contracts

## Overview

Anonymous Shield is a privacy-preserving smart contract system that enables anonymous transfers and storage of ERC20 tokens on Ethereum and compatible networks. The system uses commitment-based cryptography to hide balances and transaction details while maintaining full functionality.

## Features

- **Privacy-First**: Balances and transaction details are hidden using cryptographic commitments
- **Anonymous Transfers**: Send tokens to recipients without revealing sender identity
- **Auto-Consolidation**: Maintain single active Shield per user for optimal UX
- **Gas Optimized**: Efficient operations with minimal gas costs
- **Secure**: Multi-role access control and emergency pause functionality
- **Upgradeable**: UUPS proxy pattern for future improvements
- **Fee System**: Configurable fees for shield/unshield operations

## Architecture

### Core Components

1. **Shields**: Commitment-based token storage with hidden balances
2. **Shield/Unshield**: Convert between public and private tokens
3. **Transfers**: Anonymous peer-to-peer token transfers
4. **Consolidation**: Merge multiple Shields into one

### Privacy Model

```
Public Tokens → Shield → Private Shield → Transfer → Private Shield → Unshield → Public Tokens
     ↑                      ↓                           ↓                         ↑
  Visible             Hidden Balance              Hidden Balance           Visible
```

## Quick Start

### Prerequisites

- Node.js >= 16.0.0
- npm or yarn

### Installation

```bash
# Clone repository
git clone https://github.com/lasergun-protocol/contracts
cd anonymous-Shield-contracts

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

# Compile contracts
npm run compile
```

### Testing

```bash
# Run all tests
npm test

# Run tests with gas reporting
npm run test:gas

# Run coverage
npm run test:coverage
```

### Deployment

```bash
# Deploy to local network
npm run node  # In separate terminal
npm run deploy:localhost

# Deploy to testnet
npm run deploy:mumbai

# Deploy to mainnet
npm run deploy:polygon
```

## Contract API

### Core Functions

#### `deposit(uint256 amount, address token, bytes32 commitment)`
Convert public tokens to private Shield (Shield operation)

#### `redeem(bytes32 secret, uint256 redeemAmount, bytes32 newCommitment)`
Convert private Shield to public tokens (Unshield operation)

#### `createShieldForRecipient(bytes32 secret, uint256 amount, address recipient, bytes32 recipientCommitment)`
Transfer portion of Shield to another user

#### `consolidate(bytes32[] secrets, bytes32 newCommitment)`
Merge multiple Shields into single Shield

### View Functions

#### `getShieldInfo(bytes32 commitment) → (bool exists, address token, uint256 amount, uint256 timestamp, bool spent)`
Get Shield details

#### `getShieldBalance(bytes32 secret, address token) → uint256`
Check Shield balance for specific secret

#### `generateCommitment(bytes32 secret, address recipient) → bytes32`
Generate commitment hash

## Security Features

### Access Control
- **ADMIN_ROLE**: System administration
- **FEE_MANAGER_ROLE**: Fee configuration
- **PAUSER_ROLE**: Emergency pause/unpause
- **UPGRADER_ROLE**: Contract upgrades

### Emergency Functions
- **Pause/Unpause**: Stop all operations in emergency
- **Emergency Withdraw**: Admin can only withdraw collected fees
- **Upgrade Protection**: Multi-role authorization required

### Audit Status
- Internal security review completed
- External audit pending
- Bug bounty program planned

## Gas Costs

| Operation | Estimated Gas | Notes |
|-----------|---------------|-------|
| Deposit | ~150,000 | First-time deposit |
| Redeem | ~120,000 | Full amount |
| Transfer | ~180,000 | Including remainder |
| Consolidate (2) | ~170,000 | Two Shields |
| Consolidate (10) | ~400,000 | Maximum Shields |

## Testing

### Test Categories

- **Unit Tests**: Individual function testing
- **Integration Tests**: Cross-function workflows  
- **Gas Tests**: Gas optimization verification
- **Security Tests**: Attack vector prevention
- **Upgrade Tests**: Proxy upgrade compatibility

### Running Specific Tests

```bash
# Unit tests only
npm test -- --grep "Unit"

# Gas optimization tests
npm test -- --grep "Gas"

# Security tests
npm test -- --grep "Security"
```

## Contract Verification

### Polygon Mainnet
- **Proxy**: `0x...` ([View on PolygonScan](https://polygonscan.com/address/0x...)) )

### Amoy Testnet
- **Proxy**: `0x7a9046293dF17d2ec81eF4606376bFE1b45A2f18` ([View on PolygonScan](https://mumbai.polygonscan.com/address/0x7a9046293dF17d2ec81eF4606376bFE1b45A2f18)) 

## 🔧 Development

### Code Quality

```bash
# Lint Solidity code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run prettier

# Security analysis
npm run security
```

### Project Structure

```
contracts/
├── LaserGun.sol     # Main contract
├── interfaces/              # Contract interfaces
├── libraries/               # Utility libraries
└── mocks/                   # Test contracts

scripts/
├── deploy.js               # Deployment script
├── upgrade.js              # Upgrade script
└── utils/                  # Helper functions

test/
└── LaserGun.test.js # Core tests
```

## Security Considerations

### Known Limitations
- Frontend must track user commitments locally
- Requires external secret sharing for transfers  
- Gas costs increase with number of Shields to consolidate

### Best Practices
- Always use strong randomness for secrets
- Implement proper secret sharing mechanisms
- Monitor for unusual gas usage patterns
- Keep emergency procedures documented

## Contributing

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

### Development Guidelines
- Write comprehensive tests for new features
- Follow existing code style and patterns
- Update documentation for API changes
- Ensure all tests pass before submitting

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

 

## Disclaimer

This software is provided "as is" without warranty. Use at your own risk. Always conduct thorough testing before deploying to mainnet.