Smart Contract Deployment System

This project provides a simple system for compiling and deploying Solidity smart contracts using Python and web3.py.

Project Structure

.
├── contracts/           # Directory containing Solidity smart contracts
├── build/              # Generated build files
│   ├── abi/           # Contract ABIs
│   └── bytecode/      # Contract bytecodes
├── scripts/           # Interaction scripts
├── deploy.py          # Deployment script
├── requirements.txt   # Python dependencies
└── .env              # Environment variables (create this file)

Prerequisites

• Python 3.7+
• A running Ethereum node (local or remote)
• An Ethereum account with sufficient funds for deployment

Installation

1. Clone the repository:

git clone <repository-url>
cd <repository-name>

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Configuration

Create a .env file in the project root with the following variables:

PRIVATE_KEY=your_private_key_here
NETWORK_URL=your_network_url_here  # e.g., http://127.0.0.1:8545 for local Ganache

Important: Never commit your .env file or share your private key.

Usage

The deployment script (deploy.py) supports the following command-line arguments:

• contract_path: Path to the smart contract file (required)
• --network: Network URL (default: from .env file or http://127.0.0.1:8545)
• --private-key: Private key for deployment (default: from .env file)
• --solc-version: Solidity compiler version (default: 0.8.0)

Examples

1. Deploy using environment variables:

python deploy.py contracts/NumberSet.sol

2. Deploy with specific network and private key:

python deploy.py contracts/NumberSet.sol --network http://127.0.0.1:8545 --private-key YOUR_PRIVATE_KEY

3. Deploy with specific Solidity version:

python deploy.py contracts/NumberSet.sol --solc-version 0.8.0

Build Output

The script generates the following files in the build directory:

• build/{contract_name}_compiled.json: Full compilation output
• build/abi/{contract_name}.json: Contract ABI
• build/bytecode/{contract_name}.json: Contract bytecode
• build/{contract_name}_address.txt: Deployed contract address

Smart Contracts

NumberSet Contract

A simple contract that implements a number set with basic operations.

SpendingGuard Contract

A contract that implements spending guardrails with the following features:

• Only the contract owner can perform operations
• Deposit and withdraw ETH
• Spend ETH with guardrails:
  • Maximum 3 spends per day
  • Maximum 1 ETH per spend
  • Maximum 0.1 ETH per day for entertainment category
• Spending categories:
  • Entertainment (restricted to 0.1 ETH per day)
  • Shopping
  • Food
  • Other
• Reset daily spending count (owner only)
• View contract balance and spending statistics

Usage

python scripts/spending_guard.py --contract-address <ADDRESS> [options] <command> [args]

Options:

• --contract-address: Contract address (required)
• --network: Network URL (default: from .env file or http://127.0.0.1:8545)
• --private-key: Private key for transactions (default: from .env file)

Commands:

• deposit <amount>: Deposit ETH to the contract
• withdraw <amount>: Withdraw ETH from the contract
• spend <amount> <recipient> [--category]: Spend ETH to a recipient
  • --category: Optional spending category (Entertainment, Shopping, Food, Other)
  • If category is not specified, defaults to Other
• reset: Reset daily spending count (owner only)
• balance: Get contract balance
• spending-count: Get today's spending count
• entertainment-spent: Get today's entertainment spending
• can-spend <amount> [--category]: Check if can spend amount
  • --category: Optional spending category (Entertainment, Shopping, Food, Other)
  • If category is not specified, defaults to Other

Examples:

1. Deposit ETH:

python scripts/spending_guard.py --contract-address 0x123... deposit 1.0

2. Spend ETH with Entertainment category:

python scripts/spending_guard.py --contract-address 0x123... spend 0.05 0x456... --category Entertainment

3. Spend ETH with Shopping category:

python scripts/spending_guard.py --contract-address 0x123... spend 0.5 0x456... --category Shopping

4. Spend ETH without category (defaults to Other):

python scripts/spending_guard.py --contract-address 0x123... spend 0.5 0x456...

5. Reset daily spending:

python scripts/spending_guard.py --contract-address 0x123... reset

6. Check balance:

python scripts/spending_guard.py --contract-address 0x123... balance

7. Check spending count:

python scripts/spending_guard.py --contract-address 0x123... spending-count

8. Check entertainment spending:

python scripts/spending_guard.py --contract-address 0x123... entertainment-spent

9. Check if can spend in Entertainment category:

python scripts/spending_guard.py --contract-address 0x123... can-spend 0.05 --category Entertainment

10. Check if can spend without category (defaults to Other):

python scripts/spending_guard.py --contract-address 0x123... can-spend 0.5

Spending Rules:

1. General Rules:

   • Maximum 3 spends per day
   • Maximum 1 ETH per spend
   • Owner-only operations

2. Entertainment Category:

   • Maximum 0.1 ETH per day
   • Tracks spending separately from other categories
   • Resets daily with other spending limits

3. Other Categories (Shopping, Food, Other):

   • No additional restrictions beyond general rules
   • Tracks total spending count only

NumberGuessingGame Contract

A casino-style number guessing game with the following features:

• Owner can set a winning number (1-100) and deposit ETH as the prize
• Players can guess numbers by paying 1/10 of the prize amount
• Wrong guesses add to the prize pool
• Correct guess wins the entire prize pool
• Owner can track game statistics and reset the game
• Automatic tracking of unique players and total attempts

Usage

python scripts/number_guessing_game.py --contract-address <ADDRESS> [options] <command> [args]

Options:

• --contract-address: Contract address (required)
• --network: Network URL (default: from .env file or http://127.0.0.1:8545)
• --private-key: Private key for transactions (default: from .env file)

Commands:

• start <winning_number> <winner_amount>: Start a new game
• guess <number>: Make a guess
• reset <new_winning_number> <new_winner_amount>: Reset the game
• stats: Get game statistics
• check-player <address>: Check if a player has played

Examples:

1. Start a new game:

python scripts/number_guessing_game.py --contract-address 0x123... start 42 1.0

2. Make a guess:

python scripts/number_guessing_game.py --contract-address 0x123... guess 42

3. Reset the game:

python scripts/number_guessing_game.py --contract-address 0x123... reset 7 2.0

4. Check game statistics:

python scripts/number_guessing_game.py --contract-address 0x123... stats

5. Check if a player has played:

python scripts/number_guessing_game.py --contract-address 0x123... check-player 0x456...

Smart Contract Interaction

The project includes a script (scripts/number_set.py) to interact with the deployed NumberSet contract. This script provides a command-line interface for all contract operations.

Usage

python scripts/number_set.py --contract-address <ADDRESS> [options] <command> [args]

Options:

• --contract-address: Contract address (required)
• --network: Network URL (default: from .env file or http://127.0.0.1:8545)
• --private-key: Private key for transactions (default: from .env file)

Commands:

• add <number>: Add a number to the set
• remove <number>: Remove a number from the set
• contains <number>: Check if a number exists
• list: Get all numbers in the set
• size: Get the size of the set

Examples

1. Add a number:

python scripts/number_set.py --contract-address 0x123... add 42

2. Check if a number exists:

python scripts/number_set.py --contract-address 0x123... contains 42

3. List all numbers:

python scripts/number_set.py --contract-address 0x123... list

4. Get set size:

python scripts/number_set.py --contract-address 0x123... size

Error Handling

The script includes error handling for:

• Missing private key
• Missing network URL
• Network connection issues
• Contract compilation errors

Security Notes

1. Never commit your .env file
2. Never share your private key
3. Use a test network for development
4. Ensure your account has sufficient funds for deployment

EscrowService Contract

A secure escrow service contract that facilitates transactions between customers and service providers with dispute resolution capabilities.

Features:

• Create escrow sessions with unique IDs
• Verify session status and funds
• Confirm service completion
• Raise and handle disputes
• 50-50 split option for disputed funds
• Track disputed sessions
• Track open sessions
• Owner-only session listing

Usage

python scripts/escrow_service.py --contract-address <ADDRESS> [options] <command> [args]

Options:

• --contract-address: Contract address (required)
• --network: Network URL (default: from .env file or http://127.0.0.1:8545)
• --private-key: Private key for transactions (default: from .env file)

Commands:

• create <session_string> <amount>: Create a new escrow session
• verify <session_string>: Verify session status and funds
• confirm <session_string>: Confirm service completion
• dispute <session_string> <reason>: Raise a dispute
• accept <session_string>: Accept a dispute (service provider only)
• challenge <session_string>: Challenge a dispute (service provider only)
• details <session_string>: Get session details
• list-disputed: List all disputed sessions (service provider only)
• list-open: List all open sessions (service provider only)

Examples:

1. Create a new escrow session (as customer):

python scripts/escrow_service.py --contract-address 0x123... create "session123" 1.0

2. Verify session status (as service provider):

python scripts/escrow_service.py --contract-address 0x123... verify "session123"

3. Confirm service completion (as customer):

python scripts/escrow_service.py --contract-address 0x123... confirm "session123"

4. Raise a dispute (as customer):

python scripts/escrow_service.py --contract-address 0x123... dispute "session123" "Service not provided"

5. Accept dispute (as service provider):

python scripts/escrow_service.py --contract-address 0x123... accept "session123"

6. Challenge dispute (as service provider):

python scripts/escrow_service.py --contract-address 0x123... challenge "session123"

7. View session details:

python scripts/escrow_service.py --contract-address 0x123... details "session123"

8. List disputed sessions (service provider only):

python scripts/escrow_service.py --contract-address 0x123... list-disputed

9. List open sessions (service provider only):

python scripts/escrow_service.py --contract-address 0x123... list-open

Session States:

1. Active:

   • Newly created session
   • Funds are held in escrow
   • Can be confirmed or disputed
   • Listed in open sessions

2. Confirmed:

   • Service completed successfully
   • Funds released to service provider
   • Session is resolved
   • Removed from open sessions

3. Disputed:

   • Customer raised a dispute
   • Funds held until resolution
   • Can be accepted or challenged
   • Listed in disputed sessions
   • Removed from open sessions

4. Resolved:

   • Either confirmed, accepted, or challenged
   • Funds distributed accordingly
   • Session is closed
   • Removed from both disputed and open sessions

Security Features:

1. Access Control:

   • Only customer can confirm or dispute
   • Only service provider can accept or challenge
   • Only service provider can list all sessions
   • Session IDs are unique and immutable

2. Fund Security:

   • Funds held securely in escrow
   • No partial withdrawals
   • Clear resolution paths

3. Dispute Resolution:

   • Clear dispute process
   • 50-50 split option
   • Transparent fund distribution

4. Session Management:

   • Automatic tracking of open sessions
   • Automatic tracking of disputed sessions
   • Automatic cleanup of resolved sessions
   • Owner-only session listing

Contributing

Feel free to submit issues and enhancement requests!