code_standards

Spamoor Code Standards

Critical Development Rules

🚨 NEVER use the root wallet directly in scenarios - it's shared across all running scenarios and direct usage will cause nonce conflicts.

🚨 NEVER use go-ethereum's bound contracts for transactions - they manage nonces independently and will conflict with Spamoor's nonce tracking. Always use BuildBoundTx pattern.

🚨 ALWAYS spread transactions across multiple wallets - Ethereum clients have limits on pending transactions per sender (typically 64-1000).

🚨 ALWAYS respect context cancellation - scenarios must stop all operations when context is cancelled.

🚨 ALWAYS call onComplete() in ProcessNextTxFn - required for scenario.RunTransactionScenario transaction counting.

🚨 NEVER assume receipt is non-nil in OnComplete - handle cancellation and replacement transaction scenarios properly.

Go Language Standards

Naming Conventions

• Package names: lowercase, no underscores (e.g., spamoor, txbuilder)
• Types: PascalCase for exported, camelCase for unexported
• Functions/Methods: PascalCase for exported, camelCase for unexported
• Variables: camelCase for local, PascalCase for exported package-level
• Constants: PascalCase for exported, camelCase for unexported
• Scenario names: lowercase with hyphens (e.g., deploy-destruct)
• Well-known wallets: lowercase with hyphens (e.g., deployer, token-owner)

File Organization

• One main type per file when possible
• Group related functionality in the same file
• Use descriptive filenames that match primary functionality
• Scenario directories: scenarios/<scenario-name>/
• Each scenario has its own package named after the scenario
• Contract bindings in contract/ subdirectory

Code Structure Patterns

Scenario Implementation

// Standard scenario structure with all common options
type ScenarioOptions struct {
    // Transaction Control
    TotalCount  uint64 `yaml:"total_count"`  // Total transactions (0 = unlimited)
    Throughput  uint64 `yaml:"throughput"`   // Transactions per slot
    MaxPending  uint64 `yaml:"max_pending"`  // Maximum concurrent pending
    MaxWallets  uint64 `yaml:"max_wallets"`  // Maximum child wallets
    
    // Gas Configuration
    BaseFee     uint64 `yaml:"base_fee"`     // Base fee in gwei
    TipFee      uint64 `yaml:"tip_fee"`      // Priority fee in gwei
    GasLimit    uint64 `yaml:"gas_limit"`    // Gas limit per transaction
    
    // Client Control
    ClientGroup string `yaml:"client_group"` // Preferred client group
    
    // Logging
    LogTxs      bool   `yaml:"log_txs"`      // Log individual transactions
    
    // Scenario-specific options...
}

type Scenario struct {
    options    ScenarioOptions
    logger     *logrus.Entry
    walletPool *spamoor.WalletPool
}

var ScenarioName = "scenario-name"
var ScenarioDefaultOptions = ScenarioOptions{
    TotalCount:  0,
    Throughput:  10,
    MaxPending:  0,
    MaxWallets:  0,
    BaseFee:     20,
    TipFee:      2,
    GasLimit:    21000,
    ClientGroup: "",
    LogTxs:      false,
}