uniswap_auto_clp/doc/PYTHON_BLOCKCHAIN_REVIEW_GUIDELINES.md

Python Blockchain Development & Review Guidelines

Overview

This document outlines the standards for writing, reviewing, and deploying Python scripts that interact with EVM-based blockchains (Ethereum, Arbitrum, etc.). These guidelines prioritize capital preservation, transaction robustness, and system stability.

---

1. Transaction Handling & Lifecycle

High-reliability transaction management is the core of a production bot. Never "fire and forget."

1.1. Timeout & Receipt Management

• Requirement: Never send a transaction without immediately waiting for its receipt or tracking its hash.
• Why: The RPC might accept the tx, but it could be dropped from the mempool or stuck indefinitely.
• Code Standard:

  # BAD
  w3.eth.send_raw_transaction(signed_txn.rawTransaction)
  
  # GOOD
  tx_hash = w3.eth.send_raw_transaction(signed_txn.rawTransaction)
  try:
      receipt = w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)
  except TimeExhausted:
      # Handle stuck transaction (bump gas or cancel)
      handle_stuck_transaction(tx_hash)
  

1.2. Verification of Success

• Requirement: Explicitly check receipt.status == 1.
• Why: A transaction can be mined (success=True) but execution can revert (status=0).
• Code Standard:

  if receipt.status != 1:
      raise TransactionRevertedError(f"Tx {tx_hash.hex()} reverted on-chain")
  

1.3. Gas Management & Stuck Transactions

• Requirement: Do not hardcode gas prices. Use dynamic estimation.
• Mechanism:
  • For EIP-1559 chains (Arbitrum/Base/Mainnet), use maxFeePerGas and maxPriorityFeePerGas.
  • Implement a "Gas Bumping" mechanism: If a tx is not mined in X seconds, resubmit with 10-20% higher gas using the same nonce.

1.4. Nonce Management

• Requirement: In high-frequency loops, track the nonce locally.
• Why: w3.eth.get_transaction_count(addr, 'pending') is often slow or eventually consistent on some RPCs, leading to "Nonce too low" or "Replacement transaction underpriced" errors.

---

2. Financial Logic & Precision

2.1. No Floating Point Math for Token Amounts

• Requirement: NEVER use standard python float for calculating token amounts or prices involved in protocol interactions.
• Standard: Use decimal.Decimal or integer math (Wei).
• Why: 0.1 + 0.2 != 0.3 in floating point. This causes dust errors and "Insufficient Balance" reverts.

  # BAD
  amount = balance * 0.5 
  
  # GOOD
  amount = int(Decimal(balance) * Decimal("0.5"))
  

2.2. Slippage Protection

• Requirement: Never use 0 for amountOutMinimum or sqrtPriceLimitX96 in production.
• Standard: Calculate expected output and apply a config-defined slippage (e.g., 0.1%).
• Why: Front-running and sandwich attacks will drain value from amountOutMin: 0 trades.

2.3. Approval Handling

• Requirement: Check allowance before approving.
• Standard:
  • Verify allowance >= amount.
  • If allowance == 0, approve.
  • Note: Some tokens (USDT) require approving 0 before approving a new amount if an allowance already exists.

---

3. Security & Safety

3.1. Secrets Management

• Requirement: No private keys or mnemonics in source code.
• Standard: Use .env files (loaded via python-dotenv) or proper secrets managers.
• Review Check: grep -r "0x..." . to ensure no keys were accidentally committed.

3.2. Address Validation

• Requirement: All addresses must be checksummed before use.
• Standard:

  # Input
  target_address = "0xc364..."
  
  # Validation
  if not Web3.is_address(target_address):
      raise ValueError("Invalid address")
  checksum_address = Web3.to_checksum_address(target_address)
  

3.3. Simulation (Dry Run)

• Requirement: For complex logic (like batch swaps), use contract.functions.method().call() before .build_transaction().
• Why: If the .call() fails (reverts), the transaction will definitely fail. Save gas by catching logic errors off-chain.

---

4. Coding Style & Observability

4.1. Logging

• Requirement: No print() statements. Use logging module.
• Standard:
  • INFO: High-level state changes (e.g., "Position Opened").
  • DEBUG: API responses, specific calc steps.
  • ERROR: Stack traces and critical failures.
• Traceability: Log the Transaction Hash immediately upon sending, not after waiting. If the script crashes while waiting, you need the hash to check the chain manually.

4.2. Idempotency & State Recovery

• Requirement: Scripts must be restartable without double-spending.
• Standard: Before submitting a "Open Position" transaction, read the chain (or hedge_status.json) to ensure a position isn't already open.

4.3. Type Hinting

• Requirement: Use Python type hints for clarity.
• Standard:

  def execute_swap(
      token_in: str, 
      amount: int, 
      slippage_pct: float = 0.5
  ) -> str: # Returns tx_hash
  

---

5. Review Checklist (Copy-Paste for PRs)

• Secrets: No private keys in code?
• Math: Is Decimal or Integer math used for all financial calcs?
• Slippage: Is amountOutMinimum > 0?
• Timeouts: Does wait_for_transaction_receipt have a timeout?
• Status Check: Is receipt.status checked for success/revert?
• Gas: Are gas limits and prices dynamic/reasonable?
• Addresses: Are all addresses Checksummed?
• Restartability: What happens if the script dies halfway through?