feat: puya debugger support; algokit v7 updates (#71)

* feat: migrating to latest beta prereleases of utils, utils-debug and generator
* chore: disabling mypy in tests and artifacts folders for python generator cases
* chore: pinning mypy to 1.11.0; to be resolved in separate pr
* chore: temporary setting puya installation from puya debugging branch
* chore: temporary setting per branch install of algokit-utils-py with puya debugging
* docs: tweak to ensure debugging docs are included on starter presets too
* chore: refresh puya installation
* chore: update to the latest packages
* chore: add support for utils v7

---------

Co-authored-by: Neil Campbell <neil.campbell@makerx.com.au>

Author: aorumbayev

.github/workflows/check-python.yaml

@@ -44,6 +44,11 @@ jobs:
           # set git user and email as test invoke git
           git config --global user.email "actions@github.com" && git config --global user.name "github-actions"
 
+      - name: Setup Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
       - name: Run tests
         shell: bash
         run: |

examples/generators/production_python_smart_contract_python/README.md

@@ -77,15 +77,7 @@ By default the template creates a single `HelloWorld` contract under hello_world
 
 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}`. 
 
-To generate a new `.env` or `.env.{target_network}` file, run `algokit generate env-file`### Continuous Integration / Continuous Deployment (CI/CD)
-
-This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [.github/workflows](`.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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
+To generate a new `.env` or `.env.{target_network}` file, run `algokit generate env-file`
 
 ### Debugging Smart Contracts
 
@@ -94,7 +86,15 @@ Refer to the commented header in the `__main__.py` file in the `smart_contracts`
 
 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](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). To install the extension from the VSCode Marketplace, use the following link: [AlgoKit AVM Debugger extension](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).
+For information on using and setting up the `AlgoKit AVM Debugger` VSCode extension refer [here](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). To install the extension from the VSCode Marketplace, use the following link: [AlgoKit AVM Debugger extension](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).### Continuous Integration / Continuous Deployment (CI/CD)
+
+This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [.github/workflows](`.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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
 
 #### Setting up GitHub for CI/CD workflow and TestNet deployment
 

examples/generators/production_python_smart_contract_python/pyproject.toml

@@ -7,7 +7,7 @@ readme = "README.md"
 
 [tool.poetry.dependencies]
 python = "^3.12"
-algokit-utils = "^2.3.0"
+algokit-utils = { git = "https://github.com/algorandfoundation/algokit-utils-py.git", branch = "feat/puya-debugging" }
 python-dotenv = "^1.0.0"
 algorand-python = "^2.0.0"
 algorand-python-testing = "^0.4.0"
@@ -21,7 +21,7 @@ pytest = "*"
 pytest-cov = "*"
 pip-audit = "*"
 pre-commit = "*"
-puyapy = "*"
+puyapy = { git = "https://github.com/algorandfoundation/puya.git", branch = "main" }
 
 [build-system]
 requires = ["poetry-core"]
@@ -57,7 +57,7 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 warn_return_any = true
 strict_equality = true
-strict_concatenate = true
+extra_checks = true
 disallow_any_unimported = true
 disallow_any_expr = true
 disallow_any_decorated = true

examples/generators/production_python_smart_contract_python/smart_contracts/_helpers/build.py

@@ -31,7 +31,7 @@ def build(output_dir: Path, contract_path: Path) -> Path:
             contract_path.absolute(),
             f"--out-dir={output_dir}",
             "--output-arc32",
-            "--debug-level=0",
+            "--output-source-map",
         ],
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,

examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/deploy-config.ts.j2

@@ -1,33 +1,33 @@
 import * as algokit from '@algorandfoundation/algokit-utils'
-import { {{ contract_name.split('_')|map('capitalize')|join }}Client } from '../artifacts/{{ contract_name }}/{{ contract_name.split('_')|map('capitalize')|join }}Client'
+import { {{ contract_name.split('_')|map('capitalize')|join }}Factory } from '../artifacts/{{ contract_name }}/{{ contract_name.split('_')|map('capitalize')|join  }}Client'
 
 // Below is a showcase of various deployment options you can use in TypeScript Client
 export async function deploy() {
   console.log('=== Deploying {{ contract_name.split('_')|map('capitalize')|join }} ===')
 
   const algorand = algokit.AlgorandClient.fromEnvironment()
   const deployer = await algorand.account.fromEnvironment('DEPLOYER')
-  
-  const appClient = algorand.client.getTypedAppClientByCreatorAndName({{ contract_name.split('_')|map('capitalize')|join }}Client, {
-    sender: deployer,
-    creatorAddress: deployer.addr,
-  })
 
-  const app = await appClient.deploy({
-    onSchemaBreak: 'append',
-    onUpdate: 'append',
+  const factory = algorand.client.getTypedAppFactory({{ contract_name.split('_')|map('capitalize')|join }}Factory, {
+    defaultSender: deployer.addr,
   })
 
+  const { appClient, result } = await factory.deploy({ onUpdate: 'append', onSchemaBreak: 'append' })
+
   // If app was just created fund the app account
-  if (['create', 'replace'].includes(app.operationPerformed)) {
+  if (['create', 'replace'].includes(result.operationPerformed)) {
     await algorand.send.payment({
-      amount: algokit.algos(1),
+      amount: (1).algo(),
       sender: deployer.addr,
       receiver: app.appAddress,
     })
   }
 
-  const method = 'hello'
-  const response = await appClient.hello({ name: 'world' })
-  console.log(`Called ${method} on ${app.name} (${app.appId}) with name = world, received: ${response.return}`)
+  const method = 'hello'  
+  const response = await appClient.send.hello({
+    args: { name: 'world' },
+  })
+  console.log(
+    `Called ${method} on ${appClient.appClient.appName} (${appClient.appClient.appId}) with name = world, received: ${response.return}`,
+  )
 }

examples/generators/production_python_smart_contract_typescript/README.md

@@ -78,15 +78,7 @@ By default the template creates a single `HelloWorld` contract under hello_world
 
 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}`. 
 
-To generate a new `.env` or `.env.{target_network}` file, run `algokit generate env-file`### Continuous Integration / Continuous Deployment (CI/CD)
-
-This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [.github/workflows](`.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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
+To generate a new `.env` or `.env.{target_network}` file, run `algokit generate env-file`
 
 ### Debugging Smart Contracts
 
@@ -95,7 +87,15 @@ Refer to the commented header in the `index.ts` file in the `smart_contracts` fo
 
 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](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). To install the extension from the VSCode Marketplace, use the following link: [AlgoKit AVM Debugger extension](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).
+For information on using and setting up the `AlgoKit AVM Debugger` VSCode extension refer [here](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). To install the extension from the VSCode Marketplace, use the following link: [AlgoKit AVM Debugger extension](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).### Continuous Integration / Continuous Deployment (CI/CD)
+
+This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [.github/workflows](`.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](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
 
 #### Setting up GitHub for CI/CD workflow and TestNet deployment
 

examples/generators/production_python_smart_contract_typescript/package.json

@@ -10,15 +10,16 @@
     "format": "prettier --write ."
   },
   "engines": {
-    "node": ">=18.0",
+    "node": ">=20.0",
     "npm": ">=9.0"
   },
   "dependencies": {
-    "@algorandfoundation/algokit-utils": "^6.0.2",
-    "algosdk": "^2.7.0"
+    "@algorandfoundation/algokit-utils": "^7.0.0",
+    "@algorandfoundation/algokit-utils-debug": "^1.0.2",
+    "algosdk": ">=2.9.0 <3.0"
   },
   "devDependencies": {
-    "@algorandfoundation/algokit-client-generator": "^3.0.3",
+    "@algorandfoundation/algokit-client-generator": "^4.0.0",
     "@types/jest": "^29.5.11",
     "dotenv": "^16.0.3",
     "prettier": "^2.8.4",

examples/generators/production_python_smart_contract_typescript/pyproject.toml

@@ -7,7 +7,7 @@ readme = "README.md"
 
 [tool.poetry.dependencies]
 python = "^3.12"
-algokit-utils = "^2.3.0"
+algokit-utils = { git = "https://github.com/algorandfoundation/algokit-utils-py.git", branch = "feat/puya-debugging" }
 python-dotenv = "^1.0.0"
 algorand-python = "^2.0.0"
 algorand-python-testing = "^0.4.0"
@@ -18,7 +18,7 @@ ruff = "^0.1.6"
 mypy = "1.11.0"
 pip-audit = "*"
 pre-commit = "*"
-puyapy = "*"
+puyapy = { git = "https://github.com/algorandfoundation/puya.git", branch = "main" }
 
 [build-system]
 requires = ["poetry-core"]
@@ -51,7 +51,7 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 warn_return_any = true
 strict_equality = true
-strict_concatenate = true
+extra_checks = true
 disallow_any_unimported = true
 disallow_any_expr = true
 disallow_any_decorated = true

examples/generators/production_python_smart_contract_typescript/smart_contracts/_helpers/build.py

@@ -31,7 +31,7 @@ def build(output_dir: Path, contract_path: Path) -> Path:
             contract_path.absolute(),
             f"--out-dir={output_dir}",
             "--output-arc32",
-            "--debug-level=0",
+            "--output-source-map",
         ],
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,

examples/generators/production_python_smart_contract_typescript/smart_contracts/cool_contract/deploy-config.ts

@@ -1,33 +1,33 @@
 import * as algokit from '@algorandfoundation/algokit-utils'
-import { CoolContractClient } from '../artifacts/cool_contract/CoolContractClient'
+import { CoolContractFactory } from '../artifacts/cool_contract/CoolContractClient'
 
 // Below is a showcase of various deployment options you can use in TypeScript Client
 export async function deploy() {
   console.log('=== Deploying CoolContract ===')
 
   const algorand = algokit.AlgorandClient.fromEnvironment()
   const deployer = await algorand.account.fromEnvironment('DEPLOYER')
-  
-  const appClient = algorand.client.getTypedAppClientByCreatorAndName(CoolContractClient, {
-    sender: deployer,
-    creatorAddress: deployer.addr,
-  })
 
-  const app = await appClient.deploy({
-    onSchemaBreak: 'append',
-    onUpdate: 'append',
+  const factory = algorand.client.getTypedAppFactory(CoolContractFactory, {
+    defaultSender: deployer.addr,
   })
 
+  const { appClient, result } = await factory.deploy({ onUpdate: 'append', onSchemaBreak: 'append' })
+
   // If app was just created fund the app account
-  if (['create', 'replace'].includes(app.operationPerformed)) {
+  if (['create', 'replace'].includes(result.operationPerformed)) {
     await algorand.send.payment({
-      amount: algokit.algos(1),
+      amount: (1).algo(),
       sender: deployer.addr,
       receiver: app.appAddress,
     })
   }
 
-  const method = 'hello'
-  const response = await appClient.hello({ name: 'world' })
-  console.log(`Called ${method} on ${app.name} (${app.appId}) with name = world, received: ${response.return}`)
+  const method = 'hello'  
+  const response = await appClient.send.hello({
+    args: { name: 'world' },
+  })
+  console.log(
+    `Called ${method} on ${appClient.appClient.appName} (${appClient.appClient.appId}) with name = world, received: ${response.return}`,
+  )
 }

examples/generators/production_python_smart_contract_typescript/smart_contracts/hello_world/deploy-config.ts

@@ -1,5 +1,5 @@
 import * as algokit from '@algorandfoundation/algokit-utils'
-import { HelloWorldClient } from '../artifacts/hello_world/HelloWorldClient'
+import { HelloWorldFactory } from '../artifacts/hello_world/HelloWorldClient'
 
 // Below is a showcase of various deployment options you can use in TypeScript Client
 export async function deploy() {
@@ -8,26 +8,26 @@ export async function deploy() {
   const algorand = algokit.AlgorandClient.fromEnvironment()
   const deployer = await algorand.account.fromEnvironment('DEPLOYER')
 
-  const appClient = algorand.client.getTypedAppClientByCreatorAndName(HelloWorldClient, {
-    sender: deployer,
-    creatorAddress: deployer.addr,
+  const factory = algorand.client.getTypedAppFactory(HelloWorldFactory, {
+    defaultSender: deployer.addr,
   })
 
-  const app = await appClient.deploy({
-    onSchemaBreak: 'append',
-    onUpdate: 'append',
-  })
+  const { appClient, result } = await factory.deploy({ onUpdate: 'append', onSchemaBreak: 'append' })
 
   // If app was just created fund the app account
-  if (['create', 'replace'].includes(app.operationPerformed)) {
+  if (['create', 'replace'].includes(result.operationPerformed)) {
     await algorand.send.payment({
-      amount: algokit.algos(1),
+      amount: (1).algo(),
       sender: deployer.addr,
-      receiver: app.appAddress,
+      receiver: appClient.appAddress,
     })
   }
 
-  const method = 'hello'
-  const response = await appClient.hello({ name: 'world' })
-  console.log(`Called ${method} on ${app.name} (${app.appId}) with name = world, received: ${response.return}`)
+  const method = 'hello'  
+  const response = await appClient.send.hello({
+    args: { name: 'world' },
+  })
+  console.log(
+    `Called ${method} on ${appClient.appClient.appName} (${appClient.appClient.appId}) with name = world, received: ${response.return}`,
+  )
 }

examples/generators/production_python_smart_contract_typescript/smart_contracts/index.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { consoleLogger } from '@algorandfoundation/algokit-utils/types/logging'
 import * as algokit from '@algorandfoundation/algokit-utils'
+// import { registerDebugEventHandlers } from '@algorandfoundation/algokit-utils-debug' // Uncomment to enable persisting artifacts required by AlgoKit AVM Debugger
 
 // Uncomment the debug and traceAll options to enable auto generation of AVM Debugger compliant sourceMap and simulation trace file.
 // Learn more about using AlgoKit AVM Debugger to debug your TEAL source codes and inspect various kinds of Algorand transactions in atomic groups -> https://github.com/algorandfoundation/algokit-avm-vscode-Debugger
@@ -11,6 +12,7 @@ algokit.Config.configure({
   //  debug: true,
   //  traceAll: true,
 })
+// registerDebugEventHandlers() // Uncomment to enable persisting artifacts required by AlgoKit AVM Debugger
 
 // base directory
 const baseDir = path.resolve(__dirname)