You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: examples/generators/production_python_smart_contract_python/README.md
+39-31Lines changed: 39 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,15 +14,18 @@ This project has been generated using AlgoKit. See below for default getting sta
14
14
### Initial Setup
15
15
16
16
#### 1. Clone the Repository
17
+
17
18
Start by cloning this repository to your local machine.
18
19
19
20
#### 2. Install Pre-requisites
21
+
20
22
Ensure the following pre-requisites are installed and properly configured:
21
23
22
24
-**Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/).
23
25
-**AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later.
24
26
25
27
#### 3. Bootstrap Your Local Environment
28
+
26
29
Run the following commands within the project folder:
27
30
28
31
-**Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+.
@@ -33,14 +36,16 @@ Run the following commands within the project folder:
33
36
### Development Workflow
34
37
35
38
#### Terminal
39
+
36
40
Directly manage and interact with your project using AlgoKit commands:
37
41
38
42
1.**Build Contracts**: `algokit project run build` compiles all smart contracts. You can also specify a specific contract by passing the name of the contract folder as an extra argument.
39
-
For example: `algokit project run build -- hello_world` will only build the `hello_world` contract.
43
+
For example: `algokit project run build -- hello_world` will only build the `hello_world` contract.
40
44
2.**Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. You can also specify a specific contract by passing the name of the contract folder as an extra argument.
41
-
For example: `algokit project deploy localnet -- hello_world` will only deploy the `hello_world` contract.
45
+
For example: `algokit project deploy localnet -- hello_world` will only deploy the `hello_world` contract.
46
+
47
+
#### VS Code
42
48
43
-
#### VS Code
44
49
For a seamless experience with breakpoint debugging and other features:
45
50
46
51
1.**Open Project**: In VS Code, open the repository root.
@@ -50,20 +55,22 @@ For a seamless experience with breakpoint debugging and other features:
50
55
-**Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run.
51
56
52
57
#### JetBrains IDEs
58
+
53
59
While primarily optimized for VS Code, JetBrains IDEs are supported:
54
60
55
61
1.**Open Project**: In your JetBrains IDE, open the repository root.
56
62
2.**Automatic Setup**: The IDE should configure the Python interpreter and virtual environment.
57
63
3.**Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds.
58
64
59
65
## AlgoKit Workspaces and Project Management
66
+
60
67
This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace.
61
68
62
69
## AlgoKit Generators
63
70
64
71
This template provides a set of [algokit generators](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) that allow you to further modify the project instantiated from the template to fit your needs, as well as giving you a base to build your own extensions to invoke via the `algokit generate` command.
65
72
66
-
### Generate Smart Contract
73
+
### Generate Smart Contract
67
74
68
75
By default the template creates a single `HelloWorld` contract under hello_world folder in the `smart_contracts` directory. To add a new contract:
69
76
@@ -75,7 +82,7 @@ By default the template creates a single `HelloWorld` contract under hello_world
75
82
76
83
### Generate '.env' files
77
84
78
-
By default the template instance does not contain any env files. Using [`algokit project deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/deploy.md) against `localnet` | `testnet` | `mainnet` will use default values for `algod` and `indexer` unless overwritten via `.env` or `.env.{target_network}`.
85
+
By default the template instance does not contain any env files. Using [`algokit project deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/deploy.md) against `localnet` | `testnet` | `mainnet` will use default values for `algod` and `indexer` unless overwritten via `.env` or `.env.{target_network}`.
79
86
80
87
To generate a new `.env` or `.env.{target_network}` file, run `algokit generate env-file`
81
88
@@ -98,50 +105,52 @@ To define custom `algokit project run` commands refer to [documentation](https:/
98
105
99
106
#### Setting up GitHub for CI/CD workflow and TestNet deployment
100
107
101
-
1. Every time you have a change to your smart contract, and when you first initialize the project you need to [build the contract](#initial-setup) and then commit the `smart_contracts/artifacts` folder so the [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md) tests pass
102
-
2. Decide what values you want to use for the `allow_update`, `allow_delete` and the `on_schema_break`, `on_update` parameters specified in [`contract.py`](./smart_contracts/hello_world/contract.py).
103
-
When deploying to LocalNet these values are both set to allow update and replacement of the app for convenience. But for non-LocalNet networks
104
-
the defaults are more conservative.
105
-
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.
106
-
To help you decide it may be helpful to read the [AlgoKit Utils app deployment documentation](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/app-deploy.md) or the [AlgoKit smart contract deployment architecture](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md#upgradeable-and-deletable-contracts).
107
-
3. Create a [Github Environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment) named `Test`.
108
-
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 picked `Starter` preset.
109
-
4. Create or obtain a mnemonic for an Algorand account for use on TestNet to deploy apps, referred to as the `DEPLOYER` account.
110
-
5. Store the mnemonic as a [secret](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-secrets)`DEPLOYER_MNEMONIC`
111
-
in the Test environment created in step 3.
112
-
6. 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:
113
-
* Either, ensure the account is funded outside of CI/CD.
114
-
In Testnet, funds can be obtained by using the [Algorand TestNet dispenser](https://bank.testnet.algorand.network/) and we recommend provisioning 50 ALGOs.
115
-
* Or, fund the account as part of the CI/CD process by using a `DISPENSER_MNEMONIC` GitHub Environment secret to point to a separate `DISPENSER` account that you maintain ALGOs in (similarly, you need to provision ALGOs into this account using the [TestNet dispenser](https://bank.testnet.algorand.network/)).
108
+
1. Every time you have a change to your smart contract, and when you first initialize the project you need to [build the contract](#initial-setup) and then commit the `smart_contracts/artifacts` folder so the [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md) tests pass
109
+
2. Decide what values you want to use for the `allow_update`, `allow_delete` and the `on_schema_break`, `on_update` parameters specified in [`contract.py`](./smart_contracts/hello_world/contract.py).
110
+
When deploying to LocalNet these values are both set to allow update and replacement of the app for convenience. But for non-LocalNet networks
111
+
the defaults are more conservative.
112
+
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.
113
+
To help you decide it may be helpful to read the [AlgoKit Utils app deployment documentation](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/app-deploy.md) or the [AlgoKit smart contract deployment architecture](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md#upgradeable-and-deletable-contracts).
114
+
3. Create a [Github Environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment) named `Test`.
115
+
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 picked `Starter` preset.
116
+
4. Create or obtain a mnemonic for an Algorand account for use on TestNet to deploy apps, referred to as the `DEPLOYER` account.
117
+
5. Store the mnemonic as a [secret](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-secrets)`DEPLOYER_MNEMONIC`
118
+
in the Test environment created in step 3.
119
+
6. 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:
120
+
- Either, ensure the account is funded outside of CI/CD.
121
+
In Testnet, funds can be obtained by using the [Algorand TestNet dispenser](https://bank.testnet.algorand.network/) and we recommend provisioning 50 ALGOs.
122
+
- Or, fund the account as part of the CI/CD process by using a `DISPENSER_MNEMONIC` GitHub Environment secret to point to a separate `DISPENSER` account that you maintain ALGOs in (similarly, you need to provision ALGOs into this account using the [TestNet dispenser](https://bank.testnet.algorand.network/)).
116
123
117
124
#### Continuous Integration
118
125
119
126
For pull requests and pushes to `main` branch against this repository the following checks are automatically performed by GitHub Actions:
120
-
- Python dependencies are audited using [pip-audit](https://pypi.org/project/pip-audit/)
121
-
- Code formatting is checked using [Black](https://github.com/psf/black)
122
-
- Linting is checked using [Ruff](https://github.com/charliermarsh/ruff)
123
-
- Types are checked using [mypy](https://mypy-lang.org/)
127
+
128
+
- Python dependencies are audited using [pip-audit](https://pypi.org/project/pip-audit/)
129
+
- Code formatting is checked using [Black](https://github.com/psf/black)
130
+
- Linting is checked using [Ruff](https://github.com/charliermarsh/ruff)
131
+
- Types are checked using [mypy](https://mypy-lang.org/)
124
132
- The base framework for testing is [pytest](https://docs.pytest.org/), and the project includes two separate kinds of tests:
125
133
--`Algorand Python` smart contract unit tests, that are run using [`algorand-python-testing`](https://pypi.org/project/algorand-python-testing/), which are executed in a Python intepreter emulating major AVM behaviour
126
134
-- Python `ApplicationClient` tests that are run against `algokit localnet` and test the behaviour in a real network enviornment
127
-
- Smart contract artifacts are built
128
-
- Smart contract artifacts are checked for [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md).
129
-
- Smart contract is deployed to a AlgoKit LocalNet instance
135
+
- Smart contract artifacts are built
136
+
- Smart contract artifacts are checked for [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md).
137
+
- Smart contract is deployed to a AlgoKit LocalNet instance
130
138
131
139
> NOTE: By default smart contract artifacts are compiled with `--debug-level` set to 0, to change this, modify the compiler invocation under `smart_contracts/_helpers/build.py`
132
140
133
141
#### Continuous Deployment
134
142
135
143
For pushes to `main` branch, after the above checks pass, the following deployment actions are performed:
136
-
- The smart contract(s) are deployed to TestNet using [AlgoNode](https://algonode.io).
144
+
145
+
- The smart contract(s) are deployed to TestNet using [AlgoNode](https://algonode.io).
137
146
138
147
> 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 use `algokit deploy` please see [AlgoKit documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md).
139
148
140
149
# Tools
141
150
142
151
This project makes use of Algorand Python to build Algorand smart contracts. The following tools are in use:
-[AlgoKit](https://github.com/algorandfoundation/algokit-cli) - One-stop shop tool for developers building on the Algorand network; [docs](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md), [intro tutorial](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/tutorials/intro.md)
146
155
-[Algorand Python](https://github.com/algorandfoundation/puya) - 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](https://github.com/algorandfoundation/puya), [examples](https://github.com/algorandfoundation/puya/tree/main/examples)
147
156
-[AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-py) - A set of core Algorand utilities that make it easier to build solutions on Algorand.
@@ -151,5 +160,4 @@ This project makes use of Algorand Python to build Algorand smart contracts. The
-[pip-audit](https://pypi.org/project/pip-audit/): Tool for scanning Python environments for packages with known vulnerabilities.
153
162
-[pre-commit](https://pre-commit.com/): 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, use `pre-commit run --all-files`.
154
-
It has also been configured to have a productive dev experience out of the box in [VS Code](https://code.visualstudio.com/), see the [.vscode](./.vscode) folder.
155
-
163
+
It has also been configured to have a productive dev experience out of the box in [VS Code](https://code.visualstudio.com/), see the [.vscode](./.vscode) folder.
-[AlgoKit](https://github.com/algorandfoundation/algokit-cli) - One-stop shop tool for developers building on the Algorand network; [docs](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md), [intro tutorial](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/tutorials/intro.md)
145
145
-[Algorand Python](https://github.com/algorandfoundation/puya) - 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](https://github.com/algorandfoundation/puya), [examples](https://github.com/algorandfoundation/puya/tree/main/examples)
146
146
-[AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-ts) - A set of core Algorand utilities that make it easier to build solutions on Algorand.
0 commit comments