Quick Start

cd naka3/playbooks/three-miners && ./three-miners.sh snapshot create

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

python3 tests/example-transfer.py

Exception Hierarchy

Exception
  └── StacksException (base)
      ├── StacksAPIException
      │   └── StacksHTTPException
      ├── StacksCLIException
      ├── StacksValidationException
      └── StacksNetworkException
          └── StacksTimeoutException

1. StacksException (Base exception) - Base exception for all Stacks-related errors - Parent class for all other custom exceptions
2. StacksAPIException - Inherits from: StacksException - Purpose: General API-related exceptions - Used for: Unexpected API parsing errors
3. StacksHTTPException - Inherits from: StacksAPIException - Purpose: HTTP-specific API exceptions - Extra attributes: status_code, error_details - Used for: HTTP errors, API response failures (4xx, 5xx status codes)
4. StacksCLIException - Inherits from: StacksException - Purpose: CLI-related exceptions - Extra attributes: return_code, stderr - Used for: Blockstack CLI command failures
5. StacksValidationException - Inherits from: StacksException - Purpose: Data validation exceptions - Used for: Invalid data/parameter validation failures, Pydantic errors
6. StacksNetworkException - Inherits from: StacksException - Purpose: Network/connection related exceptions - Used for: Network connectivity issues, connection errors
7. StacksTimeoutException - Inherits from: StacksNetworkException - Purpose: Timeout-specific exceptions - Used for: Operation timeouts (confirmation waits, miner startup, etc.)

pip packages

Pydantic is a Python library for data validation and parsing using type hints. We're using it for:

1. Type-safe data models - All classes like Account, TransferInfo, DeploymentInfo inherit from BaseModel
2. Automatic validation - Ensures data types are correct when creating objects
3. IDE autocompletion - Provides full IntelliSense support
4. JSON serialization/deserialization - Easy conversion to/from JSON

Black is an opinionated formatter that automatically fixes code style issues like spacing, line breaks, and quote consistency. Common usage:

• black . - Format all Python files in current directory
• black --line-length 100 . - Use 100 char line limit instead of default 88

Logger

To see debug logs, you need to set the LOG_LEVEL environment variable to debug:

LOG_LEVEL=debug python3 tests/example-transfer.py

This will show all log levels including debug messages. The available log levels are:

• LOG_LEVEL=debug - Shows everything (debug, info, warning, error)
• LOG_LEVEL=info - Shows info, warning, error (default)
• LOG_LEVEL=warning - Shows only warning and error
• LOG_LEVEL=error - Shows only error messages

You can also set it for the current session: export LOG_LEVEL=debug python3 tests/example-transfer.py

The debug messages will appear with the format: [21:19:02][DEBG] Debug information here

Stop signal for tests in /tests

The RecipeFailedException is now available throughout your codebase for any scenario where you need explicit control over test failure and cleanup. It includes:

• step: Which step failed (for debugging)
• details: Specific error details
• Inherits from StacksException: Maintains your exception hierarchy

Use it wherever you need to explicitly escape from a try block and trigger cleanup in test scenarios. It's perfect for recipe/test failures that need special handling.