Moccasin

The moccasin.metamask_cli_integration module provides a decoupled layer that allows the Moccasin CLI to interact with the MetaMask browser extension. Instead of handling private keys directly in the CLI, this module delegates transaction signing and account management to the MetaMask UI.

Core Capabilities:

• Transaction Delegation: Pushes transaction requests to MetaMask for user confirmation and receives the resulting transaction hashes or errors.
• UI Management: Automatically launches and manages a MetaMask UI tab for network synchronization and account connection.
• Connection Monitoring: Uses a heartbeat mechanism to detect if the browser tab is closed unexpectedly.
• Security: Enhances security by avoiding direct private key handling within the CLI environment.

The data/metamask_ui directory contains a lightweight, Vanilla JavaScript frontend designed to be served by a Python backend. It facilitates interaction between the Moccasin CLI and the MetaMask browser extension for blockchain operations.

The architecture is modular to prevent circular dependencies and separate concerns into a clear hierarchy:

1. View Layer: elements.js (DOM references) and ui.js (visual manipulation).
2. State Layer: state.js (centralized global application state).
3. Logic/Service Layer: api.js (Python backend communication), metamask.js (MetaMask/window.ethereum interactions), and polling.js (background interval tasks).
4. Orchestration Layer: main.js (the entry point that binds the model, view, and services together).

Named contracts in Moccasin allow you to define deployment scripts, contract addresses by chain, and fixture settings for testing within your moccasin.toml configuration. This abstraction allows you to access contracts by a logical name in your Python scripts rather than hardcoding addresses.

To use a named contract, define it under a specific network in your moccasin.toml and access it via the active_network object in your scripts.

[networks.mainnet-fork.contracts]
usdc = { address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}

from moccasin.config import get_config

def print_contract_address():
    active_network = get_config().get_active_network()
    named_contract = active_network.get_named_contract("usdc")
    print(named_contract.address)

Moccasin provides built-in support for local development networks:

• pyevm: The basic EVM local network.
• eravm: The special ZKSync Era local network.

Note: For these local networks, you cannot manually set url, chain_id, fork, is_zksync, prompt_live, explorer_uri, or explorer_api_key. You can only set the default_account_name.

[networks.pyevm]
default_account_name = "anvil"

[networks.eravm]
default_account_name = "anvil"

A standard Moccasin project created via mox init includes the following directory structure:

• moccasin.toml: The main configuration file for Moccasin.
• src/: Contains your Vyper smart contracts.
• script/: Contains Python scripts used for deployment and interaction.
• tests/: Contains your test files (compatible with pytest).
• pyproject.toml: (Optional) Used for managing Python dependencies.
• .vscode/settings.json: (Optional) Contains VSCode-specific settings if --vscode was used.
• .coveragerc: Configuration for code coverage reporting.

.
├── README.md
├── moccasin.toml
├── script
│   ├── __init__.py
│   └── deploy.py
├── src
│   └── Counter.vy
└── tests
    ├── conftest.py
    └── test_counter.py

Moccasin recognizes a special function named moccasin_main. If this function exists in your script, Moccasin will execute it by default after running the rest of the script logic. This is useful for organizing your script execution flow.

Example:

from src import Counter

def deploy():
    counter = Counter.deploy()
    counter.increment()
    return counter

# Moccasin will automatically call this function
def moccasin_main():
    deploy()

If you do not specify a network via command line flags, moccasin defaults to using the pyevm network. This is a built-in network powered by titanoboa that serves as the core engine for moccasin simulations.

When running scripts on the pyevm network, the network is ephemeral: it exists only for the duration of your script execution. Any state or output you wish to persist must be handled manually within your script.

mox run deploy

Moccasin follows a specific hierarchy when resolving configuration values. When a value is requested, Moccasin checks sources in the following order (from highest priority to lowest):

1. Script: Values explicitly defined within your Python script.
2. Command Line: Flags and arguments passed via the CLI.
3. moccasin.toml: Settings defined in the dedicated TOML file.
4. pyproject.toml: Settings defined under the [tool.moccasin] section.
5. Defaults: The internal default values set by Moccasin.

This hierarchy allows you to maintain a base configuration in pyproject.toml or moccasin.toml while overriding specific values on the fly via the CLI or within specific scripts.

A typical Moccasin project follows a specific directory structure to manage contracts, scripts, and dependencies. While some directories are standard, others are optional or configurable via moccasin.toml.

Standard directory roles:

• src/: Contains your Vyper smart contracts.
• lib/: Contains Moccasin dependencies used inside your contracts.
• script/: Contains Python scripts used for deployment.
• tests/: Contains your test suite.
• out/: (Optional) Contains compiled contracts. Note that in Moccasin and Titanoboa, contracts are often compiled on the fly.
• moccasin.toml: The central configuration file for managing the project.

.
├── README.md
├── lib/
├── moccasin.toml
├── script/
├── src/
├── tests/
└── out/