@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,225 @@
+# ARC-4: Application Binary Interface
+
+[ARC4](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md) defines a set of encodings and behaviors for authoring and interacting with an Algorand Smart Contract. It is not the only way to author a smart contract, but adhering to it will make it easier for other clients and users to interop with your contract.
+
+To author an arc4 contract you should extend the `ARC4Contract` base class.
+
+```python
+from algopy import ARC4Contract
+
+class HelloWorldContract(ARC4Contract):
+    ...
+```
+
+## ARC-32 and ARC-56
+
+[ARC32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) extends the concepts in ARC4 to include an Application Specification which more holistically describes a smart contract and its associated state.
+
+ARC-32/ARC-56 Application Specification files are automatically generated by the compiler for ARC4 
+contracts as `<ContractName>.arc32.json` or `<ContractName>.arc56.json`
+
+## Methods
+
+Individual methods on a smart contract should be annotated with an `abimethod` decorator. This decorator is used to indicate a method which should be externally callable. The decorator itself includes properties to restrict when the method should be callable, for instance only when the application is being created or only when the OnComplete action is OptIn.
+
+A method that should not be externally available should be annotated with a `subroutine` decorator.
+
+Method docstrings will be used when outputting ARC-32 or ARC-56 application specifications, the following docstrings styles are supported ReST, Google, Numpydoc-style and Epydoc.
+
+```python
+from algopy import ARC4Contract, subroutine, arc4
+
+
+class HelloWorldContract(ARC4Contract):
+    @arc4.abimethod(create=False, allow_actions=["NoOp", "OptIn"], name="external_name")
+    def hello(self, name: arc4.String) -> arc4.String:
+        return self.internal_method() + name
+
+    @subroutine
+    def internal_method(self) -> arc4.String:
+        return arc4.String("Hello, ")
+```
+
+## Router
+
+Algorand Smart Contracts only have two possible programs that are invoked when making an ApplicationCall Transaction (`appl`). The "clear state" program which is called when using an OnComplete action of `ClearState` or the "approval" program which is called for all other OnComplete actions.
+
+Routing is required to dispatch calls handled by the approval program to the relevant ABI methods. When extending `ARC4Contract`, the routing code is automatically generated for you by the PuyaPy compiler.  
+
+## Types
+
+ARC4 defines a number of [data types](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md#types) which can be used in an ARC4 compatible contract and details how these types should be encoded in binary.
+
+Algorand Python exposes these through a number of types which can be imported from the `algopy.arc4` module. These types represent binary encoded values following the rules prescribed in the ARC which can mean operations performed directly on these types are not as efficient as ones performed on natively supported types (such as `algopy.UInt64` or `algopy.Bytes`)
+
+Where supported, the native equivalent of an ARC4 type can be obtained via the `.native` property. It is possible to use native types in an ABI method and the router will automatically encode and decode these types to their ARC4 equivalent.
+
+### Booleans
+
+**Type:** `algopy.arc4.Bool`  
+**Encoding:** A single byte where the most significant bit is `1` for `True` and `0` for `False`  
+**Native equivalent:** `builtins.bool`  
+
+### Unsigned ints
+
+**Types:** `algopy.arc4.UIntN` (<= 64 bits) `algopy.arc4.BigUIntN` (> 64 bits)  
+**Encoding:** A big endian byte array of N bits  
+**Native equivalent:** `algopy.UInt64` or `puya.py.BigUInt`  
+
+Common bit sizes have also been aliased under `algopy.arc4.UInt8`, `algopy.arc4.UInt16` etc. A uint of any size between 8 and 512 bits (in intervals of 8bits) can be created using a generic parameter. It can be helpful to define your own alias for this type. 
+
+```python
+import typing as t
+from algopy import arc4
+
+UInt40: t.TypeAlias = arc4.UIntN[t.Literal[40]]
+```
+
+### Unsigned fixed point decimals
+
+**Types:** `algopy.arc4.UFixedNxM` (<= 64 bits) `algopy.arc4.BigUFixedNxM` (> 64 bits)  
+**Encoding:** A big endian byte array of N bits where `encoded_value = value / (10^M)`  
+**Native equivalent:** _none_  
+
+```python
+import typing as t
+from algopy import arc4
+
+Decimal: t.TypeAlias = arc4.UFixedNxM[t.Literal[64], t.Literal[10]]
+```
+
+### Bytes and strings
+
+**Types:** `algopy.arc4.DynamicBytes` and `algopy.arc4.String`  
+**Encoding:** A variable length byte array prefixed with a 16-bit big endian header indicating the length of the data  
+**Native equivalent:** `algopy.Bytes` and `algopy.String`  
+
+Strings are assumed to be utf-8 encoded and the length of a string is the total number of bytes, _not the total number of characters_. 
+
+### Static arrays
+
+**Type:** `algopy.arc4.StaticArray`  
+**Encoding:** See [ARC4 Container Packing](#ARC4-Container-Packing)  
+**Native equivalent:** _none_  
+
+An ARC4 StaticArray is an array of a fixed size. The item type is specified by the first generic parameter and the size is specified by the second. 
+
+```python
+import typing as t
+from algopy import arc4
+
+FourBytes: t.TypeAlias = arc4.StaticArray[arc4.Byte, t.Literal[4]]
+```
+
+
+### Address
+**Type:** `algopy.arc4.Address`  
+**Encoding:** A byte array 32 bytes long
+**Native equivalent:** [`algopy.Account`](#algopy.Account)  
+
+Address represents an Algorand address's public key, and can be used instead of `algopy.Account` when needing to
+reference an address in an ARC4 struct, tuple or return type. It is a subclass of `arc4.StaticArray[arc4.Byte, typing.Literal[32]]`
+
+### Dynamic arrays
+
+**Type:** `algopy.arc4.DynamicArray`  
+**Encoding:** See [ARC4 Container Packing](#ARC4-Container-Packing)  
+**Native equivalent:** _none_  
+
+An ARC4 DynamicArray is an array of a variable size. The item type is specified by the first generic parameter. Items can be added and removed via `.pop`, `.append`, and `.extend`. 
+
+The current length of the array is encoded in a 16-bit prefix similar to the `arc4.DynamicBytes` and `arc4.String` types
+
+```python
+import typing as t
+from algopy import arc4
+
+UInt64Array: t.TypeAlias = arc4.DynamicArray[arc4.UInt64]
+```
+
+### Tuples
+
+**Type:** `algopy.arc4.Tuple`  
+**Encoding:** See [ARC4 Container Packing](#ARC4-Container-Packing)  
+**Native equivalent:** `builtins.tuple`  
+
+ARC4 Tuples are immutable statically sized arrays of mixed item types. Item types can be specified via generic parameters or inferred from constructor parameters.
+
+### Structs
+
+**Type:** `algopy.arc4.Struct`  
+**Encoding:** See [ARC4 Container Packing](#ARC4-Container-Packing)  
+**Native equivalent:** `typing.NamedTuple`
+
+ARC4 Structs are named tuples. The class keyword `frozen` can be used to indicate if a struct can be mutated. 
+Items can be accessed and mutated via names instead of indexes. Structs do not have a `.native` property,
+but a NamedTuple can be used in ABI methods are will be encoded/decode to an ARC4 struct automatically.
+
+```python
+import typing
+
+from algopy import arc4
+
+Decimal: typing.TypeAlias = arc4.UFixedNxM[typing.Literal[64], typing.Literal[9]]
+
+class Vector(arc4.Struct, kw_only=True, frozen=True):
+    x: Decimal
+    y: Decimal
+```
+
+### ARC4 Container Packing
+
+ARC4 encoding rules are detailed explicitly in the [ARC](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md#encoding-rules). A summary is included here.
+
+Containers are composed of a head and tail portion. 
+ - For dynamic arrays, the head is prefixed with the length of the array encoded as a 16-bit number. This prefix is not included in offset calculation
+ - For fixed sized items (eg. Bool, UIntN, or a StaticArray of UIntN), the item is included in the head
+ - Consecutive Bool items are compressed into the minimum number of whole bytes possible by using a single bit to represent each Bool
+ - For variable sized items (eg. DynamicArray, String etc), a pointer is included to the head and the data is added to the tail. This pointer represents the offset from the start of the head to the start of the item data in the tail.
+
+
+### Reference types
+
+**Types:** `algopy.Account`, `algopy.Application`, `algopy.Asset`, `algopy.gtxn.PaymentTransaction`, `algopy.gtxn.KeyRegistrationTransaction`, `algopy.gtxn.AssetConfigTransaction`, `algopy.gtxn.AssetTransferTransaction`, `algopy.gtxn.AssetFreezeTransaction`, `algopy.gtxn.ApplicationCallTransaction` 
+
+The ARC4 specification allows for using a number of [reference types](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md#reference-types) in an ABI method signature where this reference type refers to...
+ - another transaction in the group
+ - an account in the accounts array (`apat` property of the transaction)
+ - an asset in the foreign assets array (`apas` property of the transaction)
+ - an application in the foreign apps array (`apfa` property of the transaction)
+
+These types can only be used as parameters, and not as return types.
+
+```python
+from algopy import (
+    Account,
+    Application,
+    ARC4Contract,
+    Asset,
+    arc4,
+    gtxn,
+)
+
+class Reference(ARC4Contract):
+    @arc4.abimethod
+    def with_transactions(
+        self,
+        asset: Asset,
+        pay: gtxn.PaymentTransaction,
+        account: Account,
+        app: Application,
+        axfr: gtxn.AssetTransferTransaction        
+    ) -> None:
+        ...
+
+```
+### Mutability
+
+To ensure semantic compatability the compiler will also check for any usages of mutable ARC4 types (arrays and structs) and ensure that any additional references are copied using the `.copy()` method.
+
+Python values are passed by reference, and when an object (eg. an array or struct) is mutated in one place, all references to that object see the mutated version. In Python this is managed via the heap. 
+In Algorand Python these mutable values are instead stored on the stack, so when an additional reference is made (i.e. by assigning to another variable) a copy is added to the stack.
+Which means if one reference is mutated, the other references would not see the change.
+In order to keep the semantics the same, the compiler forces the addition of `.copy()` each time a new reference to the same object to match what will happen on the AVM.
+
+Struct types can be indicated as `frozen` which will eliminate the need for a `.copy()` as long as the struct also contains no mutable fields (such as arrays or another mutable struct)

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

@@ -0,0 +1,26 @@
+# Python builtins
+
+Some common python builtins have equivalent `algopy` versions, that use an [`UInt64`](#algopy.UInt64) instead of a native `int`.
+
+## len
+
+The `len()` builtin is not supported, instead `algopy` types that have a length have a `.length` property of type [`UInt64`](#algopy.UInt64). This is primarily
+due to `len()` always returning `int` and the CPython implementation enforcing that it returns _exactly_ `int`.
+
+## range
+
+The `range()` builtin has an equivalent [`algopy.urange`](#algopy.urange) this behaves the same as the python builtin except that it returns
+an iteration of [`UInt64`](#algopy.UInt64) values instead of `int`.
+
+## enumerate
+
+The `enumerate()` builtin has an equivalent [`algopy.uenumerate`](#algopy.uenumerate) this behaves the same as the python builtin except that it returns
+an iteration of [`UInt64`](#algopy.UInt64) index values and the corresponding item.
+
+## reversed
+
+The `reversed()` builtin is supported when iterating within a `for` loop and behaves the same as the python builtin.
+
+## types
+
+See [here](./lg-types.md#python-built-in-types)

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

@@ -0,0 +1,142 @@
+# Calling other applications
+
+The preferred way to call other smart contracts is using [`algopy.arc4.abi_call`](#algopyarc4abi_call), [`algopy.arc4.arc4_create`](#algopyarc4arc4_create) or 
+[`algopy.arc4.arc4_update`](#algopyarc4arc4_update). These methods support type checking and encoding of arguments, decoding of results, group transactions,
+and in the case of `arc4_create` and `arc4_update` automatic inclusion of approval and clear state programs.
+
+## `algopy.arc4.abi_call`
+
+[`algopy.arc4.abi_call`](#algopy.arc4.abi_call) can be used to call other ARC4 contracts, the first argument should refer to
+an ARC4 method either by referencing an Algorand Python [`algopy.arc4.ARC4Contract`](#algopy.arc4.ARC4Contract) method,
+an [`algopy.arc4.ARC4Client`](#algopy.arc4.ARC4Client) method generated from an ARC-32 app spec, or a string representing
+the ARC4 method signature or name.
+The following arguments should then be the arguments required for the call, these arguments will be type checked and converted where appropriate.
+Any other related transaction parameters such as `app_id`, `fee` etc. can also be provided as keyword arguments.
+
+If the ARC4 method returns an ARC4 result then the result will be a tuple of the ARC4 result and the inner transaction.
+If the ARC4 method does not return a result, or if the result type is not fully qualified then just the inner transaction is returned.
+
+```python
+from algopy import Application, ARC4Contract, String, arc4, subroutine
+
+class HelloWorld(ARC4Contract):
+    
+    @arc4.abimethod()
+    def greet(self, name: String) -> String:
+        return "Hello " + name
+
+@subroutine
+def call_existing_application(app: Application) -> None:
+    greeting, greet_txn = arc4.abi_call(HelloWorld.greet, "there", app_id=app)
+    
+    assert greeting == "Hello there"
+    assert greet_txn.app_id == 1234
+```
+
+
+### Alternative ways to use `arc4.abi_call`
+
+#### ARC4Client method 
+
+A ARC4Client client represents the ARC4 abimethods of a smart contract and can be used to call abimethods in a type safe way
+
+ARC4Client's can be produced by using `puyapy --output-client=True` when compiling a smart contract 
+(this would be useful if you wanted to publish a client for consumption by other smart contracts)
+An ARC4Client can also be be generated from an ARC-32 application.json using `puyapy-clientgen` 
+e.g. `puyapy-clientgen examples/hello_world_arc4/out/HelloWorldContract.arc32.json`, this would be
+the recommended approach for calling another smart contract that is not written in Algorand Python or does not provide the source
+
+```python
+from algopy import arc4, subroutine
+
+class HelloWorldClient(arc4.ARC4Client):
+    
+    def hello(self, name: arc4.String) -> arc4.String: ...
+
+@subroutine
+def call_another_contract() -> None:
+    # can reference another algopy contract method
+    result, txn = arc4.abi_call(HelloWorldClient.hello, arc4.String("World"), app=...)
+    assert result == "Hello, World"
+```
+
+#### Method signature or name
+
+An ARC4 method selector can be used e.g. `"hello(string)string` along with a type index to specify the return type.
+Additionally just a name can be provided and the method signature will be inferred e.g.
+
+```python
+from algopy import arc4, subroutine
+
+
+@subroutine
+def call_another_contract() -> None:
+    # can reference a method selector
+    result, txn = arc4.abi_call[arc4.String]("hello(string)string", arc4.String("Algo"), app=...)
+    assert result == "Hello, Algo"
+    
+    # can reference a method name, the method selector is inferred from arguments and return type
+    result, txn = arc4.abi_call[arc4.String]("hello", "There", app=...)
+    assert result == "Hello, There"
+```
+
+
+## `algopy.arc4.arc4_create`
+
+[`algopy.arc4.arc4_create`](#algopy.arc4.arc4_create) can be used to create ARC4 applications, and will automatically populate required fields for app creation (such as approval program, clear state program, and global/local state allocation).
+
+Like [`algopy.arc4.abi_call`](lg-transactions.md#arc4-application-calls) it handles ARC4 arguments and provides ARC4 return values.
+
+If the compiled programs and state allocation fields need to be customized (for example due to [template variables](#within-other-contracts)), 
+this can be done by passing a [`algopy.CompiledContract`](#algopy.CompiledContract) via the `compiled` keyword argument.
+
+```python
+from algopy import ARC4Contract, String, arc4, subroutine
+
+class HelloWorld(ARC4Contract):
+    
+    @arc4.abimethod()
+    def greet(self, name: String) -> String:
+        return "Hello " + name
+
+@subroutine
+def create_new_application() -> None:
+    hello_world_app = arc4.arc4_create(HelloWorld).created_app
+
+    greeting, _txn = arc4.abi_call(HelloWorld.greet, "there", app_id=hello_world_app)
+    
+    assert greeting == "Hello there"
+```
+
+## `algopy.arc4.arc4_update`
+
+[`algopy.arc4.arc4_update`](#algopy.arc4.arc4_update) is used to update an existing ARC4 application and will automatically populate the required approval and clear state program fields.
+
+Like [`algopy.arc4.abi_call`](lg-transactions.md#arc4-application-calls) it handles ARC4 arguments and provides ARC4 return values.
+
+If the compiled programs need to be customized (for example due to (for example due to [template variables](#within-other-contracts)), 
+this can be done by passing a [`algopy.CompiledContract`](#algopy.CompiledContract) via the `compiled` keyword argument.
+
+```python
+from algopy import Application, ARC4Contract, String, arc4, subroutine
+
+class NewApp(ARC4Contract):
+    
+    @arc4.abimethod()
+    def greet(self, name: String) -> String:
+        return "Hello " + name
+
+@subroutine
+def update_existing_application(existing_app: Application) -> None:
+    hello_world_app = arc4.arc4_update(NewApp, app_id=existing_app)
+    
+    greeting, _txn = arc4.abi_call(NewApp.greet, "there", app_id=hello_world_app)
+    
+    assert greeting == "Hello there"
+```
+
+## Using `itxn.ApplicationCall`
+
+If the application being called is not an ARC4 contract, or an application specification is not available,
+then [`algopy.itxn.ApplicationCall`](#algopy.itxn.ApplicationCall) can be used. This approach is generally more verbose
+than the above approaches, so should only be used if required. See [here](./lg-transactions.md#create-an-arc4-application-and-then-call-it) for an example 

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

@@ -0,0 +1,70 @@
+# Compiling to AVM bytecode
+
+The PuyaPy compiler can compile Algorand Python smart contracts directly into AVM bytecode. 
+Once compiled, this bytecode can be utilized to construct AVM Application Call transactions both on and off chain.
+
+## Outputting AVM bytecode from CLI
+
+The `--output-bytecode` option can be used to generate `.bin` files for smart contracts and logic signatures, producing an approval and clear program for each smart contract.
+
+## Obtaining bytecode within other contracts
+
+The [`compile_contract`](#algopy.compile_contract) function takes an Algorand Python smart contract class and returns a [`CompiledContract`](#algopy.CompiledContract),
+The global state, local state and program pages allocation parameters are derived from the contract by default, but can be overridden.
+This compiled contract can then be used to create an [`algopy.itxn.ApplicationCall`](#algopy.itxn.ApplicationCall) transaction or used with the [ARC4](#arc4-contracts) functions.  
+
+The [`compile_logicsig`](#algopy.compile_logicsig) takes an Algorand Python logic signature and returns a [`CompiledLogicSig`](#algopy.CompiledLogicSig), which can be used to
+verify if a transaction has been signed by a particular logic signature.
+
+## Template variables
+Algorand Python supports defining [`algopy.TemplateVar`](#algopy.TemplateVar) variables that can be substituted during compilation.
+
+For example, the following contract has `UInt64` and `Bytes` template variables.
+```{code-block} python
+:caption: templated_contract.py
+from algopy import ARC4Contract, Bytes, TemplateVar, UInt64, arc4
+
+
+class TemplatedContract(ARC4Contract):
+
+    @arc4.abimethod
+    def my_method(self) -> UInt64:
+        return TemplateVar[UInt64]("SOME_UINT")
+
+    @arc4.abimethod
+    def my_other_method(self) -> Bytes:
+        return TemplateVar[Bytes]("SOME_BYTES")
+```
+
+When compiling to bytecode, the values for these template variables must be provided. These values can be provided via the CLI, 
+or through the `template_vars` parameter of the [`compile_contract`](#algopy.compile_contract) and [`compile_logicsig`](#algopy.compile_logicsig) functions.
+
+### CLI
+
+The `--template-var` option can be used to [define](compiler.md#defining-template-values) each variable.
+
+For example to provide the values for the above example contract the following command could be used
+`puyapy --template-var SOME_UINT=123 --template-var SOME_BYTES=0xABCD templated_contract.py`
+
+### Within other contracts
+
+The functions [`compile_contract`](#algopy.compile_contract) and [`compile_logicsig`](#algopy.compile_logicsig) both have an optional `template_vars` parameter
+which can be used to define template variables. Variables defined in this manner take priority over variables defined on the CLI.
+
+```python
+from algopy import Bytes, UInt64, arc4, compile_contract, subroutine
+
+from templated_contract import TemplatedContract
+
+@subroutine
+def create_templated_contract() -> None:
+    compiled = compile_contract(
+        TemplatedContract,
+        global_uints=2, # customize allocated global uints
+        template_vars={ # provide template vars
+            "SOME_UINT": UInt64(123),
+            "SOME_BYTES": Bytes(b"\xAB\xCD")
+        },
+    )
+    arc4.arc4_create(TemplatedContract, compiled=compiled)
+```

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

@@ -0,0 +1,87 @@
+# Control flow structures
+
+Control flow in Algorand Python is similar to standard Python control flow, with support for if statements, while loops, for loops, and match statements.
+
+## If statements
+
+If statements work the same as Python. The conditions must be an expression that evaluates to bool, which can include a [String or Uint64](./lg-types.md) among others.
+
+```python
+if condition:
+    # block of code to execute if condition is True
+elif condition2:
+    # block of code to execute if condition is False and condition2 is True
+else:
+    # block of code to execute if condition and condition2 are both False
+```
+
+[See full example](https://github.com/algorandfoundation/puya/blob/main/test_cases/simplish/contract.py).
+
+## Ternary conditions
+
+Ternary conditions work the same as Python. The condition must be an expression that evaluates to bool, which can include a [String or Uint64](./lg-types.md) among others.
+
+```python
+value1 = UInt64(5)
+value2 = String(">6") if value1 > 6 else String("<=6")
+```
+
+## While loops
+
+While loops work the same as Python. The condition must be an expression that evaluates to bool, which can include a [String or Uint64](./lg-types.md) among others.
+
+You can use `break` and `continue`.
+
+```python
+while condition:
+    # block of code to execute if condition is True
+```
+
+Note: we don't currently have support for while-else statements.
+
+[See full example](https://github.com/algorandfoundation/puya/blob/main/test_cases/unssa/contract.py#L32-L83).
+
+## For Loops
+
+For loops are used to iterate over sequences, ranges and [ARC-4 arrays](./lg-arc4.md). They work the same as Python.
+
+Algorand Python provides functions like `uenumerate` and `urange` to facilitate creating sequences and ranges; in-built Python `reversed` method works with these.
+
+-   `uenumerate` is similar to Python's built-in enumerate function, but for UInt64 numbers; it allows you to loop over a sequence and have an automatic counter.
+-   `urange` is a function that generates a sequence of Uint64 numbers, which you can iterate over.
+-   `reversed` returns a reversed iterator of a sequence.
+
+Here is an example of how you can use these functions in a contract:
+
+```python
+test_array = arc4.StaticArray(arc4.UInt8(), arc4.UInt8(), arc4.UInt8(), arc4.UInt8())
+
+# urange: reversed items, forward index
+
+for index, item in uenumerate(reversed(urange(4))):
+    test_array[index] = arc4.UInt8(item)
+
+assert test_array.bytes == Bytes.from_hex("03020100")
+```
+
+Note: we don't currently have support for for-else statements.
+
+[See full](https://github.com/algorandfoundation/puya/blob/main/test_cases/reversed_iteration/contract.py) [examples](https://github.com/algorandfoundation/puya/blob/main/test_cases/nested_loops/contract.py).
+
+## Match Statements
+
+Match statements work the same as Python and work for [...]
+
+```python
+match value:
+    case pattern1:
+        # block of code to execute if pattern1 matches
+    case pattern2:
+        # block of code to execute if pattern2 matches
+    case _:
+        # Fallback
+```
+
+Note: Captures and patterns are not supported. Currently, there is only support for basic case/switch functionality; pattern matching and guard clauses are not currently supported.
+
+[See full example](https://github.com/algorandfoundation/puya/blob/main/test_cases/match/contract.py).

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

@@ -0,0 +1,36 @@
+# Error handling and assertions
+
+In Algorand Python, error handling and assertions play a crucial role in ensuring the correctness and robustness of smart contracts.
+
+## Assertions
+
+Assertions allow you to immediately fail a smart contract if a [Boolean statement or value](./lg-types.md#bool) evaluates to `False`. If an assertion fails, it immediately stops the execution of the contract and marks the call as a failure.
+
+In Algorand Python, you can use the Python built-in `assert` statement to make assertions in your code.
+
+For example:
+
+```python
+@subroutine
+def set_value(value: UInt64):
+    assert value > 4, "Value must be > 4"
+```
+
+### Assertion error handling
+
+The (optional) string value provided with an assertion, if provided, will be added as a TEAL comment on the end of the assertion line. This works in concert with default AlgoKit Utils app client behaviour to show a TEAL stack trace of an error and thus show the error message to the caller (when source maps have been loaded).
+
+## Explicit failure
+
+For scenarios where you need to fail a contract explicitly, you can use
+the [`op.err()`](#algopy.op.err) operation. This operation causes the TEAL program to immediately 
+and unconditionally fail.
+
+Alternatively [`op.exit(0)`](#algopy.op.exit) will achieve the same result. A non-zero value will
+do the opposite and immediately succeed.
+
+## Exception handling
+
+The AVM doesn't provide error trapping semantics so it's not possible to implement `raise` and `catch`.
+
+For more details see [Unsupported Python features](lg-unsupported-python-features.md#raise-tryexceptfinally).

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

@@ -0,0 +1,46 @@
+# Logging
+
+Algorand Python provides a [`log` method](./api-algopy.md#algopy.log) that allows you to emit debugging and event information as well as return values from your contracts to the caller.
+
+This `log` method is a superset of the [AVM `log` method](./lg-ops.md) that adds extra functionality:
+
+-   You can log multiple items rather than a single item
+-   Items are concatenated together with an optional separator (which defaults to: `""`)
+-   Items are automatically converted to bytes for you
+-   Support for:
+    -   `int` literals / module variables (encoded as raw bytes, not ASCII)
+    -   `UInt64` values (encoded as raw bytes, not ASCII)
+    -   `str` literals / module variables (encoded as UTF-8)
+    -   `bytes` literals / module variables (encoded as is)
+    -   `Bytes` values (encoded as is)
+    -   `BytesBacked` values, which includes [`String`](./api-algopy.md#algopy.String), [`BigUInt`](./api-algopy.md#algopy.BigUInt), [`Account`](./api-algopy.md#algopy.Account) and all of the [ARC-4 types](./api-algopy.arc4.md) (encoded as their underlying bytes values)
+
+Logged values are [available to the calling client](https://developer.algorand.org/docs/rest-apis/algod/#pendingtransactionresponse) and attached to the transaction record stored on the blockchain ledger.
+
+If you want to emit ARC-28 events in the logs then there is a [purpose-built function for that](./lg-arc28.md).
+
+Here's an example contract that uses the log method in various ways:
+
+```python
+from algopy import BigUInt, Bytes, Contract, log, op
+
+class MyContract(Contract):
+    def approval_program(self) -> bool:
+        log(0)
+        log(b"1")
+        log("2")
+        log(op.Txn.num_app_args + 3)
+        log(Bytes(b"4") if op.Txn.num_app_args else Bytes())
+        log(
+            b"5",
+            6,
+            op.Txn.num_app_args + 7,
+            BigUInt(8),
+            Bytes(b"9") if op.Txn.num_app_args else Bytes(),
+            sep="_",
+        )
+        return True
+
+    def clear_state_program(self) -> bool:
+        return True
+```