cardano-nft-vending-machine 0.5.0b4

Library to perform NFT mints automatically on the Cardano blockchain

cardano-nft-vending-machine

A simple CNFT mint-and-vend machine Python library that leverages ``cardano-cli``

:warning: IMPORTANT

Interactions on the Cardano blockchain involve REAL CURRENCY AND SHOULD NOT BE TREATED LIGHTLY. Some principles:

• Never send money to an address you don't know and can't validate
• Keys should be stored on servers that have as little attack surface (e.g., iptables blacklists) as possible
• Open source software should always be audited -- UTSL!
• There are NO WARRANTIES WHATSOEVER WITH THIS PACKAGE -- use at your own risk

Quickstart

This project contains Library bindings that can be installed using the standard wheel mechanism. See the script quickstart section for how to run from CLI.

Library Usage

The library consists of several Python objects representing the mint process. The sample below shows how one could run an infinite CNFT vending machine on mainnet for a 10₳ mint (gross of fees and rebates) with their NFT:

# There are several sample whitelist implementations in cardano.wt.whitelist or you can implement your own
whitelist = SingleUseWhitelist('/path/to/whitelisted/assets/directory')

# The Mint object below represents your Mint policy and specifies price, and donation in Lovelace (both can be 0)
mint = Mint('<POLICY_ID>', 10000000, 1000000, '/path/to/nft/json/metadata', '/path/to/mint/script', '/path/to/mint.skey', whitelist)

# Blockfrost is used in the code to validate where the UTXO sent to the payment address came from
blockfrost_api = BlockfrostApi('<BLOCKFROST_PROJ_ID>', mainnet=True)

# CardanoCli is a wrapper around the cardano-cli command (used as a utility without any interaction with the network)
cardano_cli = CardanoCli(protocol_params='/path/to/protocol.json')

# NftVendingMachine vends NFTs and needs to be called repeatedly (with a 25-vend max) so long as the mint period is open
nft_vending_machine = NftVendingMachine('addr_payment', '/path/to/payment.skey', 'addr_profit', 25, mint, blockfrost_api, cardano_cli, mainnet=True)

# The following simple loop carries the state of already-completed UTXOs to avoid double spending errors and uses a do-wait-check loop
already_completed = set()
while _program_is_running:
    nft_vending_machine.vend('/path/to/output/dir', 'locking_subdir_name', 'metadata_subdir_name', already_completed)
    time.sleep(WAIT_TIMEOUT)

main.py

There is a sample vending machine script that is included in the src/ directory to show how to invoke the library components. Use -h to see detailed help or use a command like below:

    python3 main.py \
            --payment-addr <PAYMENT_ADDR> \
            --payment-sign-key /FULL/PATH/TO/payment.skey \
            --profit-addr <PROFIT_ADDR> \
            [--mint-price <PRICE_LOVELACE> | --free-mint] \
            --mint-script /FULL/PATH/TO/policy.script \
            --mint-sign-key /FULL/PATH/TO/policy.skey \
            --mint-policy $(cat /FULL/PATH/TO/policyID) \
            --blockfrost-project <BLOCKFROST_PROJECT_ID> \
            --metadata-dir metadata/ \
            --output-dir output/ \
            --single-vend-max <MAX_SINGLE_VEND> \
            [--vend-randomly] \
            [--no-whitelist | \
              [--single-use-asset-whitelist <WHITELIST_DIR> | --unlimited-asset-whitelist <WHITELIST_DIR>]] \
            [--donation]
            [--mainnet]

Installation

This package is available from PyPI and can be installed using pip3. Python <3.8 is currently unsupported at this time.

pip3 install cardano-nft-vending-machine

APIs

All API documentation is auto-generated from pydoc3-formatted multi-line strings in the source code. A mirror of master is hosted on Github Pages.

Build

Building this project creates a .whl file for uploading to PyPI or installing locally on a server. All output is, by default, stored to dist/. To build, run:

python3 -m build

Test

To enhance the output of tests, we recommend installing pytest-clarity:

pip3 install pytest-clarity

Tests are stored in the tests subdirectory and are run using pytest. Before invoking the tests you will need to create files at tests/secrets/blockfrost-preprod.key and tests/secrets/blockfrost-preview.key with the respective network keys to make sure the test suite can access the test network blockchains (see blockfrost.io docs for more details). Then, to invoke the tests:

python3 -m pytest -vv

By default tests will run on the preprod Cardano network. To test against mainnet or the preview Cardano network you can use the TEST_ON_MAINNET or TEST_ON_PREVIEW environment variables as follows:

TEST_ON_PREVIEW=true python3 -m pytest -vv

Pull requests to master require 0 failing tests in order to be merged.

Code Coverage

We use coverage to measure code coverage from our pytests across the code base. To run a full test suite with code coverage metrics, invoke:

python3 -m coverage run --source=src/ --branch -m pytest -vv

Note that you must separately generate the report on your CLI using the following:

python3 -m coverage html

We aim to maintain 80% coverage (lines + branches) if possible.

Documentation

Documentation is stored in multi-line comments inside the source code and should be generated using the pdoc3 package as follows:

pdoc3 --html -o docs/ src/cardano