Quickstart

Creating a new project

To create a new project, you can run the following command:

mox init my_project

And this will create a new project in a new my_project directory. If you want to create a project in a directory that already has files/folders in it, run:

mox init my_project --force

If you use VSCode, you can also use:

mox init my_project --vscode

Which will create a .vscode folder to help make working with VSCode easier.

Let’s check out the files and folders moccasin has created:

Note

MacOS users may need to install tree with brew install tree. You can of course, just not install tree and skip this tree command.

Run the following commands:

cd my_project
tree .

You’ll get an output like:

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

This is a minimal project structure that moccasin creates.

  • README.md is a markdown file that you can use to describe your project.

  • moccasin.toml is a configuration file that moccasin uses to manage the project.

  • script is a directory that contains scripts that you can use to deploy your project.

  • src is a directory that contains your vyper smart contracts.

  • tests` is a directory that contains your tests.

If you run tree . -a, you’ll also see the “hidden” files.

  • .gitignore is a file that tells git which files to ignore.

  • .gitattributes is a file that tells git how to handle line endings.

  • .coveragerc is a file that tells pytest how to handle coverage.

Deploying a contract

Now, unlike other frameworks, with moccasin, we never need to compile! Moccasin uses titanoboa under the hood to compile contracts quickly on the fly. Let’s open our deploy.py file and look inside.

from src import Counter

def deploy():
    counter = Counter.deploy()
    print("Starting count: ", counter.number())
    counter.increment()
    print("Ending count: ", counter.number())
    return counter

def moccasin_main():
    return deploy()

We can see a python script that will:

  1. Deploy our Counter contract.

  2. Print the starting count inside the contract.

  3. Increment the count.

  4. Print the ending count inside the contract.

We can run this script to the titanoboa pyevm (a local network that simulates ethereum) by running:

mox run deploy

And we’ll get an output like:

Running run command...
Starting count:  0
Ending count:  1

Awesome! This is how easy it is to run scripts with your smart contracts.

Running tests

Under the hood, moccasin uses pytest, and you can use a lot of your favorite pytest command line commands. If you just run:

mox test

You’ll get an output like:

Running test command...
=================================== test session starts ===================================
platform darwin -- Python 3.11.9, pytest-8.3.2, pluggy-1.5.0
rootdir: /your/path/my_project
plugins: cov-5.0.0, hypothesis-6.108.5, titanoboa-0.2.1
collected 1 item

tests/test_counter.py .                                                             [100%]

==================================== 1 passed in 0.01s ====================================

Note

If you want to add python dependencies to your moccasin project, see: virtual environments documentation.

But that’s it! You’ve now successfully gotten your first package up and going!