Quick Start

Plugins for the StarkNet Ethereum L2 networks.

Dependencies

python3 version 3.8 or greater, python3-dev

Installation

via `pip`

You can install the latest release via pip:

pip install ape-starknet

via `setuptools`

You can clone the repository and use setuptools for the most up-to-date version:

git clone https://github.com/ApeWorX/ape-starknet.git
cd ape-starknet
python3 setup.py install

Quick Usage

Account Management

Accounts are used to execute transactions and sign call data. Accounts are smart contracts in Starknet.

Out of the box, ape-starknet comes with development accounts. Access them like this:

from ape import accounts

container = accounts.containers["starknet"]
owner = container.test_accounts[0]

See the section below about Testing to learn more about test accounts.

Learn more about accounts by following the accounts guide.

Declare and Deploy Contracts

In Starknet, you can declare contract types by publishing them to the chain. This allows other contracts to create instances of them using the deploy system call.

To declare a contract using ape-starknet, do the following (in a script or console):

from ape import accounts, project

account = accounts.load("<MY_STARK_ACCOUNT>")
declaration = account.declare(project.MyContract)
print(declaration.class_hash)

Then, you can use the deploy method to deploy the contracts. NOTE: The deploy method in ape-starknet makes an invoke-function call against the Starknet public UDC contract. Learn more about UDC contracts here.

from ape import accounts, project

# This only works if `project.MyContract` was declared previously.
# The class hash is not necessary as an argument. Ape will look it up.
account = accounts.load("<MY_STARK_ACCOUNT>")
account.deploy(project.MyContact)

You can also deploy contracts by doing:

from ape import accounts, project

account = accounts.load("<MY_STARK_ACCOUNT>")
my_contract = project.MyContract.deploy(sender=account)

Learn more about deploying contracts like factory contracts by following the contracts guide

Contract Interaction

After you have deployed your contracts, you can begin interacting with them. deploy methods return a contract instance from which you can call methods on:

from ape import project

contract = project.MyContract.deploy(sender=account)

# Interact with deployed contract
receipt = contract.my_mutable_method(123)
value = contract.my_view_method()

You can access the return data from a mutable method’s receipt:

receipt = contract.my_mutable_method(123)
result = receipt.return_value

Include a sender to delegate the transaction to an account contract:

from ape import accounts

account = accounts.load("my_account")
receipt = contract.my_mutable_method(123, sender=account)

NOTE: Currently, to pass in arrays as arguments, you have to also include the array size beforehand:

receipt = contract.store_my_list(3, [1, 2, 3])

Testing

Accounts

You can use starknet-devnet accounts in your tests.

import pytest
import ape


@pytest.fixture
def devnet_accounts():
    return ape.accounts.containers["starknet"].test_accounts


@pytest.fixture
def owner(devnet_accounts):
    return devnet_accounts[0]

Additionally, any accounts deployed in the local network are not saved to disk and are ephemeral.

import pytest
import ape


@pytest.fixture(scope="session")
def ephemeral_account():
    accounts = ape.accounts.containers["starknet"]
    accounts.deploy_account("ALIAS")

    # This account only exists in the devnet and is not a key-file account.
    return accounts.load("ALIAS")

Paying Fees

Starknet fees are currently paid in ETH, which is an ERC-20 on the Starknet chain. To check your account balance (in ETH), use the balance property on the account:

from ape import accounts

acct = accounts.load("Alias")
print(acct.balance)

If your account has a positive balance, you can begin paying fees!

To pay fees, you can either manually set the max_fee kwarg on an invoke-transaction:

receipt = contract.my_mutable_method(123, max_fee=2900000000000)

NOTE: By not setting the max_fee, it will automatically get set to the value returned from the provider estimate_gas_cost() call. You do not need to call estimate_gas_cost() explicitly.

Mainnet Alpha Whitelist Deployment Token

Currently, to deploy to Alpha-Mainnet, your contract needs to be whitelisted. You can provide your WL token in a variety of ways.

Via Python code:

from ape import project

my_contract = project.MyContract.deploy(token="MY_TOKEN")

Via an Environment Variable:

export ALPHA_MAINNET_WL_DEPLOY_TOKEN="MY_TOKEN"

Development

This project is in development and should be considered a beta. Things might not be in their final state and breaking changes may occur. Comments, questions, criticisms and pull requests are welcomed.