PCG library implemented using Algorand Python
Project description
lib-pcg-algopy
This project has been generated using AlgoKit. See below for default getting started instructions.
Setup
Pre-requisites
- Python 3.12 or later
- Docker (only required for LocalNet)
For interactive tour over the codebase, download vsls-contrib.codetour extension for VS Code, then open the
.codetour.json
file in code tour extension.
Initial setup
- Clone this repository locally
- Install pre-requisites:
- Make sure to have Docker installed and running on your machine.
- Install
AlgoKit
- Link: The recommended version is the latest available. Ensure you can executealgokit --version
and get2.0.0
or later. - Bootstrap your local environment; run
algokit bootstrap all
within this folder, which will:- Install
Poetry
- Link: The minimum required version is^1.7
. Ensure you can executepoetry -V
and get1.2
+ - Run
poetry install
in the root directory, which will set up a.venv
folder with a Python virtual environment and also install all Python dependencies - Copy
.env.template
to.env
- Install
- Run
algokit localnet start
to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - Run
algokit project bootstrap all
to install all project dependencies (unless executed duringalgokit init
).
- Open the project and start debugging / developing via:
- Terminal
- Run
algokit project run build
to build all contracts in the project - Run
algokit project deploy localnet
to deploy all contracts to the local Algorand network.
- Run
- VS Code (Launch Configurations)
- Open the repository root in VS Code
- Install recommended extensions
- Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
Note If using Windows: Before running for the first time you will need to select the Python Interpreter.
- Open the command palette (Ctrl/Cmd + Shift + P)
- Search for
Python: Select Interpreter
- Select
./.venv/Scripts/python.exe
- JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition)
- Open the repository root in the IDE
- It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
- Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to JetBrains forums.
- Terminal
Subsequently
- If you update to the latest source code and there are new dependencies you will need to run
algokit bootstrap all
again - Follow step 3 above
For guidance on
smart_contracts
folder and adding new contracts to the project please see README on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD)
This project uses GitHub Actions to define CI/CD workflows, which are located in the .github/workflows folder.
Please note, if you instantiated the project with --workspace flag in
algokit init
it will automatically attempt to move the contents of the.github
folder to the root of the workspace.
AlgoKit Workspaces
To define custom algokit project run
commands refer to documentation. This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
Debugging Smart Contracts
This project is optimized to work with AlgoKit AVM Debugger extension. To activate it:
Refer to the commented header in the __main__.py
file in the smart_contracts
folder.
If you have opted in to include VSCode launch configurations in your project, you can also use the Debug TEAL via AlgoKit AVM Debugger
launch configuration to interactively select an available trace file and launch the debug session for your smart contract.
For information on using and setting up the AlgoKit AVM Debugger
VSCode extension refer here. To install the extension from the VSCode Marketplace, use the following link: AlgoKit AVM Debugger extension.
Setting up GitHub for CI/CD workflow and TestNet deployment
- Every time you have a change to your smart contract, and when you first initialize the project you need to build the contract and then commit the
smart_contracts/artifacts
folder so the output stability tests pass - Decide what values you want to use for the
allow_update
,allow_delete
and theon_schema_break
,on_update
parameters specified incontract.py
. When deploying to LocalNet these values are both set to allow update and replacement of the app for convenience. But for non-LocalNet networks the defaults are more conservative. These default values will allow the smart contract to be deployed initially, but will not allow the app to be updated or deleted if is changed and the build will instead fail. To help you decide it may be helpful to read the AlgoKit Utils app deployment documentation or the AlgoKit smart contract deployment architecture. - Create a Github Environment named
Test
. Note: If you have a private repository and don't have GitHub Enterprise then Environments won't work and you'll need to convert the GitHub Action to use a different approach. Ignore this step if you pickedStarter
preset. - Create or obtain a mnemonic for an Algorand account for use on TestNet to deploy apps, referred to as the
DEPLOYER
account. - Store the mnemonic as a secret
DEPLOYER_MNEMONIC
in the Test environment created in step 3. - The account used to deploy the smart contract will require enough funds to create the app, and also fund it. There are two approaches available here:
- Either, ensure the account is funded outside of CI/CD. In Testnet, funds can be obtained by using the Algorand TestNet dispenser and we recommend provisioning 50 ALGOs.
- Or, fund the account as part of the CI/CD process by using a
DISPENSER_MNEMONIC
GitHub Environment secret to point to a separateDISPENSER
account that you maintain ALGOs in (similarly, you need to provision ALGOs into this account using the TestNet dispenser).
Continuous Integration
For pull requests and pushes to main
branch against this repository the following checks are automatically performed by GitHub Actions:
- Python dependencies are audited using pip-audit
- Code formatting is checked using Black
- Linting is checked using Ruff
- Types are checked using mypy
- Python tests are executed using pytest
- Smart contract artifacts are built
- Smart contract artifacts are checked for output stability
- Smart contract is deployed to a AlgoKit LocalNet instance
Continuous Deployment
For pushes to main
branch, after the above checks pass, the following deployment actions are performed:
- The smart contract(s) are deployed to TestNet using AlgoNode.
Please note deployment is also performed via
algokit deploy
command which can be invoked both via CI as seen on this project, or locally. For more information on how to usealgokit deploy
please see AlgoKit documentation.
Tools
This project makes use of Algorand Python to build Algorand smart contracts. The following tools are in use:
-
Algorand - Layer 1 Blockchain; Developer portal, Why Algorand?
-
AlgoKit - One-stop shop tool for developers building on the Algorand network; docs, intro tutorial
-
Algorand Python - A semantically and syntactically compatible, typed Python language that works with standard Python tooling and allows you to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM); docs, examples
-
AlgoKit Utils - A set of core Algorand utilities that make it easier to build solutions on Algorand.
-
Poetry: Python packaging and dependency management.- Black: A Python code formatter.- Ruff: An extremely fast Python linter.
-
mypy: Static type checker.
-
pytest: Automated testing.
-
pip-audit: Tool for scanning Python environments for packages with known vulnerabilities.
-
pre-commit: A framework for managing and maintaining multi-language pre-commit hooks, to enable pre-commit you need to run
pre-commit install
in the root of the repository. This will install the pre-commit hooks and run them against modified files when committing. If any of the hooks fail, the commit will be aborted. To run the hooks on all files, usepre-commit run --all-files
. It has also been configured to have a productive dev experience out of the box in VS Code, see the .vscode folder.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for lib_pcg_algopy-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 979175c2cff70f65621f0fd72db21c6da286a6d031e8617464ba6950f1011a30 |
|
MD5 | 92ace1eb8e8a5f1167be2570455048e4 |
|
BLAKE2b-256 | 37d0ee5aae1768d20cafc50518abc4a5a2efe17e220e3eccea6588b6baa5736e |