@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/puya:README.md

@@ -0,0 +1,72 @@
+# Algorand Python
+
+Algorand Python is a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that works with standard Python tooling.
+
+Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy.
+
+[Documentation](https://algorandfoundation.github.io/puya/) | [Language guide](https://algorandfoundation.github.io/puya/language-guide.html)
+
+## Installation
+
+### Recommended method
+
+The easiest way to use Algorand Python is to instantiate a template with AlgoKit via:
+
+```algokit init -t python```
+
+This will give you a full development environment with intellisense, linting, automatic formatting, breakpoint debugging, deployment and CI/CD.
+
+A sample smart contract will be placed under `PROJECT_NAME/projects/PROJECT_NAME/smart_contracts/SMART_CONTRACT_NAME/contract.py` (replacing `PROJECT_NAME` and `SMART_CONTRACT_NAME` with the values you chose during the template wizard.)
+
+### Manual Alternative
+
+Alternatively, if you want to start from scratch you can do the following:
+
+1. Ensure you have Python 3.12+
+2. Install [AlgoKit CLI](https://github.com/algorandfoundation/algokit-cli?tab=readme-ov-file#install)
+3. Check you can run the compiler:
+    ```shell
+    algokit compile py -h
+    ```
+4. Install Algorand Python into your project `poetry add algorand-python`
+5. Create a contract in a (e.g.) `contract.py` file:
+    ```python
+    from algopy import ARC4Contract, arc4
+    class HelloWorldContract(ARC4Contract):
+        @arc4.abimethod
+        def hello(self, name: arc4.String) -> arc4.String:
+            return "Hello, " + name
+    ```
+
+## Usage
+
+1. Navigate to your contract and compile it:
+    ```shell
+    algokit compile py contract.py
+    ```
+2. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system!
+3. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file:
+    ```shell
+    algokit compile py contract.py --output-arc32 --no-output-teal
+    ```
+4. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI:
+    ```shell
+    algokit generate client HelloWorldContract.arc32.json --output client.py
+    ```
+5. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](https://algorandfoundation.github.io/puya/).
+
+## Examples
+
+There are [many](https://github.com/algorandfoundation/puya/tree/main/examples) [examples](https://github.com/algorandfoundation/puya/tree/main/test_cases) in this repo, here are some of the more useful ones that showcase what
+is possible.
+
+-   [hello world](https://github.com/algorandfoundation/puya/tree/main/examples/hello_world/contract.py)
+-   [hello world (ARC4)](https://github.com/algorandfoundation/puya/tree/main/examples/hello_world_arc4/contract.py)
+-   [voting](https://github.com/algorandfoundation/puya/tree/main/examples/voting/voting.py)
+-   [AMM](https://github.com/algorandfoundation/puya/tree/main/examples/amm/contract.py)
+-   [auction](https://github.com/algorandfoundation/puya/tree/main/examples/auction/contract.py)
+-   [non-ABI calculator](https://github.com/algorandfoundation/puya/tree/main/examples/calculator/contract.py)
+-   [local storage](https://github.com/algorandfoundation/puya/tree/main/examples/local_state/local_state_contract.py)
+
+The compiled output is available under the `out/` directory alongside these, e.g. the approval
+TEAL for `voting` is available at [examples/voting/out/VotingRoundApp.approval.teal](https://github.com/algorandfoundation/puya/blob/main/examples/voting/out/VotingRoundApp.approval.teal).

package/dist/resources/knowledge/taxonomy/puya:docs:algopy_testing:index.md

@@ -0,0 +1,15 @@
+# Algorand Python Testing
+
+`algorand-python-testing` is a companion package to [Algorand Python](https://github.com/algorandfoundation/puya) that enables efficient unit testing of Algorand Python smart contracts in an offline environment. This package emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface.
+
+The `algorand-python-testing` package provides:
+
+-   A simple interface for fast and reliable unit testing
+-   An offline testing environment that simulates core AVM functionality
+-   A familiar Pythonic experience, compatible with testing frameworks like [pytest](https://docs.pytest.org/en/latest/), [unittest](https://docs.python.org/3/library/unittest.html), and [hypothesis](https://hypothesis.readthedocs.io/en/latest/)
+
+> **NOTE**: This package is currently in **preview** and should be used with caution until the first stable release.
+
+## Quick Start
+
+To get started refer to the [official documentation](https://algorandfoundation.github.io/algorand-python-testing/).

package/dist/resources/knowledge/taxonomy/puya:docs:api-algopy.arc4.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api-algopy.arc4.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:api-algopy.gtxn.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api-algopy.gtxn.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:api-algopy.itxn.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api-algopy.itxn.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:api-algopy.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api-algopy.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:api-algopy.op.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api-algopy.op.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:api.md

@@ -0,0 +1,6 @@
+
+ ⛅️ wrangler 3.99.0 (update available 4.10.0)
+---------------------------------------------
+
+Downloading "puya:docs:api.md" from "plausibleai".
+Download complete.

package/dist/resources/knowledge/taxonomy/puya:docs:compiler.md

@@ -0,0 +1,239 @@
+# PuyaPy compiler
+
+The PuyaPy compiler is a multi-stage, optimising compiler that takes Algorand Python and prepares it for execution on the AVM. PuyaPy ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy (among other formats).
+
+The PuyaPy compiler is based on the [Puya compiler architecture](#compiler-architecture), which allows for multiple frontend languages to leverage the majority of the compiler logic so adding new frontend languages for execution on Algorand is relatively easy.
+
+## Compiler installation
+
+The minimum supported Python version for running the PuyaPy compiler is 3.12.
+
+There are three ways of installing the PuyaPy compiler.
+
+1. You can install [AlgoKit CLI](https://github.com/algorandfoundation/algokit-cli?tab=readme-ov-file#install) and you can then use the `algokit compile py` command.
+2. You can install the PuyaPy compiler into your project and thus lock the compiler version for that project:
+    ```shell
+    pip install puyapy
+    # OR
+    poetry add puyapy --group=dev
+    ```
+    Note: if you do this then when you use`algokit compile py` within that project directory it will invoke the installed compiler rather than a global one.
+3. You can install the compiler globally using [pipx](https://pipx.pypa.io/stable/):
+    ```shell
+    pipx install puya
+    ```
+
+Alternatively, it can be installed per project. For example, if you're using [poetry](https://python-poetry.org),
+you can install it as a dev-dependency like so:
+
+If you just want to play with some examples, you can clone the repo and have a poke around:
+
+```shell
+git clone https://github.com/algorandfoundation/puya.git
+cd puya
+poetry install
+poetry shell
+# compile the "Hello World" example
+puyapy examples/hello_world
+```
+
+## Using the compiler
+
+To check that you can run the compiler successfully after installation, you can run the
+help command:
+
+```
+puyapy -h
+# OR
+algokit compile py -h
+```
+
+To compile a contract or contracts, just supply the path(s) - either to the .py files themselves,
+or the containing directories. In the case of containing directories, any (non-abstract) contracts
+discovered therein will be compiled, allowing you to compile multiple contracts at once. You can
+also supply more than one path at a time to the compiler.
+
+e.g. either `puyapy my_project/` or `puyapy my_project/contract.py` will work to compile a single contract.
+
+## Compiler architecture
+
+The PuyaPy compiler is based on the Puya compiler architecture, which allows for multiple frontend languages to leverage the majority of the compiler logic so adding new frontend languages for execution on Algorand is relatively easy.
+
+The PuyaPy compiler takes Algorand Python through a series of transformations with each transformation serving a specific purpose:
+
+    Python code
+        -> Python Abstract Syntax Tree (AST)
+        -> MyPy AST
+        -> Puya AST (AWST)
+        -> Intermediate Representation (IR) in SSA form
+        -> Optimizations (multiple rounds)
+        -> Destructured IR
+        -> Optimizations (multiple rounds)
+        -> Memory IR (MIR)
+        -> Optimizations (multiple rounds)
+        -> TealOps IR
+        -> Optimizations (multiple rounds)
+        -> TEAL code
+        -> AVM bytecode
+
+While this may appear complex, splitting it in this manner allows for each step to be expressed in a simple form to do one thing (well) and allows us to make use of industry research into compiler algorithms and formats.
+
+## Type checking
+
+The first and second steps of the [compiler pipeline](#compiler-architecture) are significant to note, because it's where we perform type checking. We leverage [MyPy](https://mypy-lang.org/) to do this, so we recommend that you install and use the latest version of MyPy in your development environment to get the best typing information that aligns to what the PuyaPy compiler expects. This should work with standard Python tooling e.g. with Visual Studio Code, PyCharm, et. al.
+
+The easiest way to get a productive development environment with Algorand Python is to instantiate a template with AlgoKit via `algokit init -t python`. This will give you a full development environment with intellisense, linting, automatic formatting, breakpoint debugging, deployment and CI/CD.
+
+Alternatively, you can construct your own environment by configuring MyPy, Ruff, etc. with the same configuration files [used by that template](https://github.com/algorandfoundation/algokit-python-template).
+
+The MyPy config that PuyaPy uses is in [compile.py](https://github.com/algorandfoundation/puya/blob/main/src/puya/compile.py#L79)
+
+## Compiler usage
+
+The options available for the compile can be seen by executing `puyapy -h` or `algokit compile py -h`:
+
+```
+puyapy [-h] [--version] [-O {0,1,2}]
+    [--output-teal | --no-output-teal] [--output-arc32 | --no-output-arc32]
+    [--output-client | --no-output-client] [--out-dir OUT_DIR]
+    [--log-level {notset,debug,info,warning,error,critical}] [-g {0,1,2}] [--output-awst | --no-output-awst]
+    [--output-ssa-ir | --no-output-ssa-ir] [--output-optimization-ir | --no-output-optimization-ir]
+    [--output-destructured-ir | --no-output-destructured-ir] [--output-memory-ir | --no-output-memory-ir]
+    [--target-avm-version {10}]
+    [--locals-coalescing-strategy {root_operand,root_operand_excluding_args,aggressive}]
+    PATH [PATH ...]
+```
+
+### Options
+
+| Option                                                   | Description                                                                                                                                                           | Default                 |
+|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|
+| `-h`, `--help`                                           | Show the help message and exit                                                                                                                                        | N/A                     |
+| `--version`                                              | Show program's version number and exit                                                                                                                                | N/A                     |
+| `-O {0,1,2}` <br />`--optimization-level {0,1,2}`        | Set optimization level of output TEAL / AVM bytecode                                                                                                                  | `1`                     |
+| `--output-teal`, `--no-output-teal`                      | Output TEAL                                                                                                                                                           | `True`                  |
+| `--output-arc32`, `--no-output-arc32`                    | Output {contract}.arc32.json ARC-32 app spec file if the contract is an ARC-4 contract                                                                                | `True`                  |
+| `--output-arc56`, `--no-output-arc56`                    | Output {contract}.arc56.json ARC-56 app spec file if the contract is an ARC-4 contract                                                                                | `False`                 |
+| `--output-client`, `--no-output-client`                  | Output Algorand Python contract client for typed ARC4 ABI calls                                                                                                       | `False`                 |
+| `--output-bytecode`, `--no-output-bytecode`              | Output AVM bytecode                                                                                                                                                   | `False`                 |
+| `--out-dir OUT_DIR`                                      | The path for outputting artefacts                                                                                                                                     | Same folder as contract |
+| `--log-level {notset,debug,info,warning,error,critical}` | Minimum level to log to console                                                                                                                                       | `info`                  |
+| `-g {0,1,2}`, `--debug-level {0,1,2}`                    | Output debug information level<br /> `0` = No debug annotations <br /> `1` = Output debug annotations <br /> `2` = Reserved for future use, currently the same as `1` | `1`                     |
+| `--template-var`                                         | Allows specifying template values. Can be used multiple times, see below for examples                                                                                 | N/A                     |
+| `--template-vars-prefix`                                 | Prefix to use for template variables                                                                                                                                  | "TMPL_"                 |
+
+### Defining template values
+
+[Template Variables](#algopy.TemplateVar), can be replaced with literal values during compilation to bytecode using the `--template-var` option.
+Additionally, Algorand Python functions that create AVM bytecode, such as [compile_contract](#algopy.compile_contract) and [compile_logicsig](#algopy.compile_logicsig), can also provide the specified values.
+
+#### Examples of Variable Definitions
+
+The table below illustrates how different variables and values can be defined:
+
+| Variable Type                     | Example Algorand Python                          | Value definition example |
+|--------------------------|-------------------------------------------|--------------------------|
+| [UInt64](#algopy.UInt64) | `algopy.TemplateVar[UInt64]("SOME_INT")`  | `SOME_INT=1234`          |
+| [Bytes](#algopy.Bytes)   | `algopy.TemplateVar[Bytes]("SOME_BYTES")` | `SOME_BYTES=0x1A2B`      |
+| [String](#algopy.String) | `algopy.TemplateVar[String]("SOME_STR")`  | `SOME_STR="hello"`       |
+
+All template values specified via the command line are prefixed with "TMPL_" by default. 
+The default prefix can be modified using the `--template-vars-prefix` option.
+
+### Advanced options
+
+There are additional compiler options that allow you to tweak the behaviour in more advanced ways or tweak the output to receive intermediate representations from the compiler pipeline. Most users won't need to use these options unless exploring the inner workings of the compiler or performing more advanced optimisations.
+
+| Option                                                                               | Description                                                                                                                       | Default        |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `--output-awst`, `--no-output-awst`                                                  | Output parsed result of Puya Abstract Syntax Tree (AWST)                                                                          | `False`        |
+| `--output-ssa-ir`, `--no-output-ssa-ir`                                              | Output the Intermediate Representation (IR) in Single Static Assignment (SSA) form before optimisations form                      | `False`        |
+| `--output-optimization-ir`, `--no-output-optimization-ir`                            | Output the IR after each optimization step                                                                                        | `False`        |
+| `--output-destructured-ir`, `--no-output-destructured-ir`                            | Output the IR after SSA destructuring and before Memory IR (MIR)                                                                  | `False`        |
+| `--output-memory-ir`, `--no-output-memory-ir`                                        | Output Memory IR (MIR) before lowering to TealOps IR                                                                              |                |
+| `--target-avm-version {10}`                                                          | Target AVM version for the output                                                                                                 | `10`           |
+| `--locals-coalescing-strategy {root_operand,root_operand_excluding_args,aggressive}` | Strategy choice for out-of-ssa local variable coalescing. The best choice for your app is best determined through experimentation | `root_operand` |
+
+## Sample `pyproject.toml`
+
+A sample `pyproject.toml` file with known good configuration is:
+
+```ini
+[tool.poetry]
+name = "algorand_python_contract"
+version = "0.1.0"
+description = "Algorand smart contracts"
+authors = ["Name <name@domain.tld>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+algokit-utils = "^2.2.0"
+python-dotenv = "^1.0.0"
+algorand-python = "^1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+black = { extras = ["d"], version = "*" }
+ruff = "^0.1.6"
+mypy = "*"
+pytest = "*"
+pytest-cov = "*"
+pip-audit = "*"
+pre-commit = "*"
+puyapy = "^1.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 120
+select = [
+  "E",
+  "F",
+  "ANN",
+  "UP",
+  "N",
+  "C4",
+  "B",
+  "A",
+  "YTT",
+  "W",
+  "FBT",
+  "Q",
+  "RUF",
+  "I",
+]
+ignore = [
+  "ANN101", # no type for self
+  "ANN102", # no type for cls
+]
+unfixable = ["B", "RUF"]
+
+[tool.ruff.flake8-annotations]
+allow-star-arg-any = true
+suppress-none-returning = true
+
+[tool.pytest.ini_options]
+pythonpath = ["smart_contracts", "tests"]
+
+[tool.mypy]
+files = "smart_contracts/"
+python_version = "3.12"
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+strict_equality = true
+strict_concatenate = true
+disallow_any_unimported = true
+disallow_any_expr = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+```

package/dist/resources/knowledge/taxonomy/puya:docs:index.md

@@ -0,0 +1,63 @@
+# Algorand Python
+
+Algorand Python is a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that works with standard Python tooling.
+
+Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy.
+
+## Quick start
+
+The easiest way to use Algorand Python is to instantiate a template with AlgoKit via `algokit init -t python`. This will give you a full development environment with intellisense, linting, automatic formatting, breakpoint debugging, deployment and CI/CD.
+
+Alternatively, if you want to start from scratch you can do the following:
+
+1. Ensure you have Python 3.12+
+2. Install [AlgoKit CLI](https://github.com/algorandfoundation/algokit-cli?tab=readme-ov-file#install)
+3. Check you can run the compiler:
+    ```shell
+    algokit compile py -h
+    ```
+4. Install Algorand Python into your project `poetry add algorand-python`
+5. Create a contract in a (e.g.) `contract.py` file:
+    ```python
+    from algopy import ARC4Contract, arc4
+    class HelloWorldContract(ARC4Contract):
+        @arc4.abimethod
+        def hello(self, name: arc4.String) -> arc4.String:
+            return "Hello, " + name
+    ```
+6. Compile the contract:
+    ```shell
+    algokit compile py contract.py
+    ```
+7. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system!
+8. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file:
+    ```shell
+    algokit compile py contract.py --output-arc32 --no-output-teal
+    ```
+9. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI:
+    ```shell
+    algokit generate client HelloWorldContract.arc32.json --output client.py
+    ```
+10. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](https://algorandfoundation.github.io/puya/).
+
+## Programming with Algorand Python
+
+To get started developing with Algorand Python, please take a look at the [Language Guide](./language-guide.md).
+
+## Using the PuyaPy compiler
+
+To see detailed guidance for using the PuyaPy compiler, please take a look at the [Compiler guide](./compiler.md).
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+hidden: true
+---
+
+language-guide
+principles
+api
+compiler
+algopy_testing/index
+```

package/dist/resources/knowledge/taxonomy/puya:docs:language-guide.md

@@ -0,0 +1,86 @@
+# Language Guide
+
+Algorand Python is conceptually two things:
+
+1. A partial implementation of the Python programming language that runs on the AVM.
+2. A framework for development of Algorand smart contracts and logic signatures, with Pythonic
+   interfaces to underlying AVM functionality.
+
+You can install the Algorand Python types from PyPi:
+
+> `pip install algorand-python`
+
+or
+
+> `poetry add algorand-python`
+
+---
+
+As a partial implementation of the Python programming language, it maintains the syntax and
+semantics of Python. The subset of the language that is supported will grow over time, but it will
+never be a complete implementation due to the restricted nature of the AVM as an execution
+environment. As a trivial example, the `async` and `await` keywords, and all associated features,
+do not make sense to implement.
+
+Being a partial implementation of Python means that existing developer tooling like IDE syntax
+highlighting, static type checkers, linters, and auto-formatters, will work out-of-the-box. This is
+as opposed to an approach to smart contract development that adds or alters language elements or
+semantics, which then requires custom developer tooling support, and more importantly, requires the
+developer to learn and understand the potentially non-obvious differences from regular Python.
+
+The greatest advantage to maintaining semantic and syntactic compatibility, however, is only
+realised in combination with the framework approach. Supplying a set of interfaces representing
+smart contract development and AVM functionality required allows for the possibility of
+implementing those interfaces in pure Python! This will make it possible in the near future for you
+to execute tests against your smart contracts without deploying them to Algorand, and even step
+into and break-point debug your code from those tests.
+
+The framework provides interfaces to the underlying AVM types and operations. By virtue of the AVM
+being statically typed, these interfaces are also statically typed, and require your code to be as
+well.
+
+The most basic types on the AVM are `uint64` and `bytes[]`, representing unsigned 64-bit integers
+and byte arrays respectively. These are represented by [`UInt64`](#algopy.UInt64) and
+[`Bytes`](#algopy.Bytes) in Algorand Python. There are further "bounded" types supported by the AVM
+which are backed by these two simple primitives. For example, `bigint` represents a variably sized
+(up to 512-bits), unsigned integer, but is actually backed by a `bytes[]`. This is represented by
+[`BigUInt`](#algopy.BigUInt) in Algorand Python.
+
+Unfortunately, none of these types map to standard Python primitives. In Python, an `int` is
+unsigned, and effectively unbounded. A `bytes` similarly is limited only by the memory available,
+whereas an AVM `bytes[]` has a maximum length of 4096. In order to both maintain semantic
+compatibility and allow for a framework implementation in plain Python that will fail under the
+same conditions as when deployed to the AVM, support for Python primitives is
+[limited](lg-types.md#python-built-in-types).
+
+For more information on the philosophy and design of Algorand Python, please see
+["Principles"](principles.md#principles).
+
+If you aren't familiar with Python, a good place to start before continuing below is with the
+[official tutorial](https://docs.python.org/3/tutorial/index.html). Just beware that as mentioned
+above, [not all features are supported](./lg-unsupported-python-features.md).
+
+## Table of Contents
+
+```{toctree}
+---
+maxdepth: 3
+---
+
+lg-structure
+lg-types
+lg-control
+lg-modules
+lg-builtins
+lg-errors
+lg-storage
+lg-logs
+lg-transactions
+lg-ops
+lg-opcode-budget
+lg-arc4
+lg-arc28
+lg-calling-apps
+lg-compile
+lg-unsupported-python-features
+```

package/dist/resources/knowledge/taxonomy/puya:docs:lg-arc28.md

@@ -0,0 +1,53 @@
+# ARC-28: Structured event logging
+
+[ARC-28](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0028.md) provides a methodology for structured logging by Algorand smart contracts. It introduces the concept of Events, where data contained in logs may be categorized and structured.
+
+Each Event is identified by a unique 4-byte identifier derived from its `Event Signature`. The Event Signature is a UTF-8 string comprised of the event's name, followed by the names of the [ARC-4](./lg-arc4.md) data types contained in the event, all enclosed in parentheses (`EventName(type1,type2,...)`) e.g.:
+
+```
+Swapped(uint64,uint64)
+```
+
+Events are emitting by including them in the [log output](./lg-logs.md). The metadata that identifies the event should then be included in the ARC-4 contract output so that a calling client can parse the logs to parse the structured data out. This part of the ARC-28 spec isn't yet implemented in Algorand Python, but it's on the roadmap.
+
+## Emitting Events
+
+To emit an ARC-28 event in Algorand Python you can use the `emit` function, which appears in the `algopy.arc4` namespace for convenience since it heavily uses ARC-4 types and is essentially an extension of the ARC-4 specification. This function takes care of encoding the event payload to conform to the ARC-28 specification and there are 3 overloads:
+
+-   An [ARC-4 struct](./lg-arc4.md), from what the name of the struct will be used as a the event name and the struct parameters will be used as the event fields - `arc4.emit(Swapped(a, b))`
+-   An event signature as a [string literal (or module variable)](./lg-types.md), followed by the values - `arc4.emit("Swapped(uint64,uint64)", a, b)`
+-   An event name as a [string literal (or module variable)](./lg-types.md), followed by the values - `arc4.emit("Swapped", a, b)`
+
+Here's an example contract that emits events:
+
+```python
+from algopy import ARC4Contract, arc4
+
+class Swapped(arc4.Struct):
+    a: arc4.UInt64
+    b: arc4.UInt64
+
+class EventEmitter(ARC4Contract):
+    @arc4.abimethod
+    def emit_swapped(self, a: arc4.UInt64, b: arc4.UInt64) -> None:
+        arc4.emit(Swapped(b, a))
+        arc4.emit("Swapped(uint64,uint64)", b, a)
+        arc4.emit("Swapped", b, a)
+```
+
+It's worth noting that the ARC-28 event signature needs to be known at compile time so the event name can't be a dynamic type and must be a static string literal or string module constant. If you want to emit dynamic events you can do so using the [`log` method](./lg-logs.md), but you'd need to manually construct the correct series of bytes and the compiler won't be able to emit the ARC-28 metadata so you'll need to also manually parse the logs in your client.
+
+Examples of manually constructing an event:
+
+```python
+# This is essentially what the `emit` method is doing, noting that a,b need to be encoded
+#   as a tuple so below (simple concat) only works for static ARC-4 types
+log(arc4.arc4_signature("Swapped(uint64,uint64)"), a, b)
+
+# or, if you wanted it to be truly dynamic for some reason,
+#   (noting this has a non-trivial opcode cost) and assuming in this case
+#   that `event_suffix` is already defined as a `String`:
+event_name = String("Event") + event_suffix
+event_selector = op.sha512_256((event_name + "(uint64)").bytes)[:4]
+log(event_selector, UInt64(6))
+```