@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,248 @@
+# Transactions
+
+Algorand Python provides types for accessing fields of other transactions in a group, as well as
+creating and submitting inner transactions from your smart contract.
+
+The following types are available:
+
+| Group Transactions                                                   | Inner Transaction Field sets                     | Inner Transaction                                                              |
+| -------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| [PaymentTransaction](algopy.gtxn.PaymentTransaction)                 | [Payment](algopy.itxn.Payment)                   | [PaymentInnerTransaction](algopy.itxn.PaymentInnerTransaction)                 |
+| [KeyRegistrationTransaction](algopy.gtxn.KeyRegistrationTransaction) | [KeyRegistration](algopy.itxn.KeyRegistration)   | [KeyRegistrationInnerTransaction](algopy.itxn.KeyRegistrationInnerTransaction) |
+| [AssetConfigTransaction](algopy.gtxn.AssetConfigTransaction)         | [AssetConfig](algopy.itxn.AssetConfig)           | [AssetConfigInnerTransaction](algopy.itxn.AssetConfigInnerTransaction)         |
+| [AssetTransferTransaction](algopy.gtxn.AssetTransferTransaction)     | [AssetTransfer](algopy.itxn.AssetTransfer)       | [AssetTransferInnerTransaction](algopy.itxn.AssetTransferInnerTransaction)     |
+| [AssetFreezeTransaction](algopy.gtxn.AssetFreezeTransaction)         | [AssetFreeze](algopy.itxn.AssetFreeze)           | [AssetFreezeInnerTransaction](algopy.itxn.AssetFreezeInnerTransaction)         |
+| [ApplicationCallTransaction](algopy.gtxn.ApplicationCallTransaction) | [ApplicationCall](algopy.itxn.ApplicationCall)   | [ApplicationCallInnerTransaction](algopy.itxn.ApplicationCallInnerTransaction) |
+| [Transaction](algopy.gtxn.Transaction)                               | [InnerTransaction](algopy.itxn.InnerTransaction) | [InnerTransactionResult](algopy.itxn.InnerTransactionResult)                   |
+
+## Group Transactions
+
+Group transactions can be used as ARC4 parameters or instantiated from a group index.
+
+### ARC4 parameter
+
+Group transactions can be used as parameters in ARC4 method
+
+For example to require a payment transaction in an ARC4 ABI method:
+
+```python
+import algopy
+
+
+class MyContract(algopy.ARC4Contract):
+
+    @algopy.arc4.abimethod()
+    def process_payment(self: algopy.gtxn.PaymentTransaction) -> None:
+        ...
+```
+
+### Group Index
+
+Group transactions can also be created using the group index of the transaction.
+If instantiating one of the type specific transactions they will be checked to ensure the transaction is of the expected type.
+[Transaction](algopy.gtxn.Transaction) is not checked for a specific type and provides access to all transaction fields
+
+For example, to obtain a reference to a payment transaction:
+
+```python
+import algopy
+
+
+@algopy.subroutine()
+def process_payment(group_index: algopy.UInt64) -> None:
+    pay_txn = algopy.gtxn.PaymentTransaction(group_index)
+    ...
+```
+
+## Inner Transactions
+
+Inner transactions are defined using the parameter types, and can then be submitted individually by calling the
+`.submit()` method, or as a group by calling [`submit_txns`](#algopy.itxn.submit_txns)
+
+### Examples
+
+#### Create and submit an inner transaction
+
+```python
+from algopy import Account, UInt64, itxn, subroutine
+
+
+@subroutine
+def example(amount: UInt64, receiver: Account) -> None:
+    itxn.Payment(
+        amount=amount,
+        receiver=receiver,
+        fee=0,
+    ).submit()
+```
+
+#### Accessing result of a submitted inner transaction
+
+```python
+from algopy import Asset, itxn, subroutine
+
+
+@subroutine
+def example() -> Asset:
+    asset_txn = itxn.AssetConfig(
+        asset_name=b"Puya",
+        unit_name=b"PYA",
+        total=1000,
+        decimals=3,
+        fee=0,
+    ).submit()
+    return asset_txn.created_asset
+```
+
+#### Submitting multiple transactions
+
+```python
+from algopy import Asset, Bytes, itxn, log, subroutine
+
+
+@subroutine
+def example() -> tuple[Asset, Bytes]:
+    asset1_params = itxn.AssetConfig(
+        asset_name=b"Puya",
+        unit_name=b"PYA",
+        total=1000,
+        decimals=3,
+        fee=0,
+    )
+    app_params = itxn.ApplicationCall(
+        app_id=1234,
+        app_args=(Bytes(b"arg1"), Bytes(b"arg1"))
+    )
+    asset1_txn, app_txn = itxn.submit_txns(asset1_params, app_params)
+    # log some details
+    log(app_txn.logs(0))
+    log(asset1_txn.txn_id)
+    log(app_txn.txn_id)
+
+    return asset1_txn.created_asset, app_txn.logs(1)
+```
+
+#### Create an ARC4 application, and then call it
+
+```python
+from algopy import Bytes, arc4, itxn, subroutine
+
+HELLO_WORLD_APPROVAL: bytes = ...
+HELLO_WORLD_CLEAR: bytes = ...
+
+
+@subroutine
+def example() -> None:
+    # create an application
+    application_txn = itxn.ApplicationCall(
+        approval_program=HELLO_WORLD_APPROVAL,
+        clear_state_program=HELLO_WORLD_CLEAR,
+        fee=0,
+    ).submit()
+    app = application_txn.created_app
+
+    # invoke an ABI method
+    call_txn = itxn.ApplicationCall(
+        app_id=app,
+        app_args=(arc4.arc4_signature("hello(string)string"), arc4.String("World")),
+        fee=0,
+    ).submit()
+    # extract result
+    hello_world_result = arc4.String.from_log(call_txn.last_log)
+```
+
+#### Create and submit transactions in a loop
+
+```python
+from algopy import Account, UInt64, itxn, subroutine
+
+
+@subroutine
+def example(receivers: tuple[Account, Account, Account]) -> None:
+    for receiver in receivers:
+        itxn.Payment(
+            amount=UInt64(1_000_000),
+            receiver=receiver,
+            fee=0,
+        ).submit()
+```
+
+### Limitations
+
+Inner transactions are powerful, but currently do have some restrictions in how they are used.
+
+#### Inner transaction objects cannot be passed to or returned from subroutines
+
+```python
+from algopy import Application, Bytes, itxn, subroutine
+
+
+@subroutine
+def parameter_not_allowed(txn: itxn.PaymentInnerTransaction) -> None:
+    # this is a compile error
+    ...
+
+
+@subroutine
+def return_not_allowed() -> itxn.PaymentInnerTransaction:
+    # this is a compile error
+    ...
+
+
+@subroutine
+def passing_fields_allowed() -> Application:
+    txn = itxn.ApplicationCall(...).submit()
+    do_something(txn.txn_id, txn.logs(0))  # this is ok
+    return txn.created_app  # and this is ok
+
+
+@subroutine
+def do_something(txn_id: Bytes):  # this is just a regular subroutine
+    ...
+```
+
+#### Inner transaction parameters cannot be reassigned without a `.copy()`
+
+```python
+from algopy import itxn, subroutine
+
+
+@subroutine
+def example() -> None:
+    payment = itxn.Payment(...)
+    reassigned_payment = payment  # this is an error
+    copied_payment = payment.copy()  # this is ok
+```
+
+#### Inner transactions cannot be reassigned
+
+```python
+from algopy import itxn, subroutine
+
+
+@subroutine
+def example() -> None:
+    payment_txn = itxn.Payment(...).submit()
+    reassigned_payment_txn = payment_txn  # this is an error
+    txn_id = payment_txn.txn_id  # this is ok
+```
+
+#### Inner transactions methods cannot be called if there is a subsequent inner transaction submitted or another subroutine is called.
+
+```python
+from algopy import itxn, subroutine
+
+
+@subroutine
+def example() -> None:
+    app_1 = itxn.ApplicationCall(...).submit()
+    log_from_call1 = app_1.logs(0)  # this is ok
+
+    # another inner transaction is submitted
+    itxn.ApplicationCall(...).submit()
+    # or another subroutine is called
+    call_some_other_subroutine()
+
+    app1_txn_id = app_1.txn_id  # this is ok, properties are still available
+    another_log_from_call1 = app_1.logs(1)  # this is not allowed as the array results may no longer be available, instead assign to a variable before submitting another transaction
+```

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

@@ -0,0 +1,319 @@
+# Types
+
+Algorand Python exposes a number of types that provide a statically typed representation of the behaviour that is possible on the Algorand Virtual Machine.
+
+```{contents} Types
+:local:
+:depth: 3
+:class: this-will-duplicate-information-and-it-is-still-useful-here
+```
+
+## AVM types
+
+The most basic [types on the AVM](https://developer.algorand.org/docs/get-details/dapps/avm/teal/specification/#stack-types)
+are `uint64` and `bytes[]`, representing unsigned 64-bit integers and byte arrays respectively.
+These are represented by [`UInt64`](./#uint64) and [`Bytes`](./#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`](./#biguint) in Algorand Python.
+
+### UInt64
+
+[`algopy.UInt64`](#algopy.UInt64) represents the underlying AVM `uint64` type.
+
+It supports all the same operators as `int`, except for `/`, you must use `//` for truncating
+division instead.
+
+```python
+# you can instantiate with an integer literal
+num = algopy.UInt64(1)
+# no arguments default to the zero value
+zero = algopy.UInt64()
+# zero is False, any other value is True
+assert not zero
+assert num
+# Like Python's `int`, `UInt64` is immutable, so augmented assignment operators return new values
+one = num
+num += 1
+assert one == 1
+assert num == 2
+# note that once you have a variable of type UInt64, you don't need to type any variables
+# derived from that or wrap int literals
+num2 = num + 200 // 3
+```
+
+[Further examples available here](https://github.com/algorandfoundation/puya/blob/main/test_cases/stubs/uint64.py).
+
+### Bytes
+
+[`algopy.Bytes`](#algopy.Bytes) represents the underlying AVM `bytes[]` type. It is intended
+to represent binary data, for UTF-8 it might be preferable to use [String](#string).
+
+```python
+# you can instantiate with a bytes literal
+data = algopy.Bytes(b"abc")
+# no arguments defaults to an empty value
+empty = algopy.Bytes()
+# empty is False, non-empty is True
+assert data
+assert not empty
+# Like Python's `bytes`, `Bytes` is immutable, augmented assignment operators return new values
+abc = data
+data += b"def"
+assert abc == b"abc"
+assert data == b"abcdef"
+# indexing and slicing are supported, and both return a Bytes
+assert abc[0] == b"a"
+assert data[:3] == abc
+# check if a bytes sequence occurs within another
+assert abc in data
+```
+
+```{hint}
+Indexing a `Bytes` returning a `Bytes` differs from the behaviour of Python's bytes type, which
+returns an `int`.
+```
+
+```python
+# you can iterate
+for i in abc:
+    ...
+# construct from encoded values
+base32_seq = algopy.Bytes.from_base32('74======')
+base64_seq = algopy.Bytes.from_base64('RkY=')
+hex_seq = algopy.Bytes.from_hex('FF')
+# binary manipulations ^, &, |, and ~ are supported
+data ^= ~((base32_seq & base64_seq) | hex_seq)
+# access the length via the .length property
+assert abc.length == 3
+```
+
+```{note}
+See [Python builtins](lg-builtins.md#len---length) for an explanation of why `len()` isn't supported.
+```
+
+[See a full example](https://github.com/algorandfoundation/puya/blob/main/test_cases/stubs/bytes.py).
+
+### String
+
+[`String`](#algopy.String) is a special Algorand Python type that represents a UTF8 encoded string.
+It's backed by `Bytes`, which can be accessed through the `.bytes`.
+
+It works similarly to `Bytes`, except that it works with `str` literals rather than `bytes`
+literals. Additionally, due to a lack of AVM support for unicode data, indexing and length
+operations are not currently supported (simply getting the length of a UTF8 string is an `O(N)`
+operation, which would be quite costly in a smart contract). If you are happy using the length as
+the number of bytes, then you can call `.bytes.length`.
+
+```python
+# you can instantiate with a string literal
+data = algopy.String("abc")
+# no arguments defaults to an empty value
+empty = algopy.String()
+# empty is False, non-empty is True
+assert data
+assert not empty
+# Like Python's `str`, `String` is immutable, augmented assignment operators return new values
+abc = data
+data += "def"
+assert abc == "abc"
+assert data == "abcdef"
+# whilst indexing and slicing are not supported, the following tests are:
+assert abc.startswith("ab")
+assert abc.endswith("bc")
+assert abc in data
+# you can also join multiple Strings together with a seperator:
+assert algopy.String(", ").join((abc, abc)) == "abc, abc"
+# access the underlying bytes
+assert abc.bytes == b"abc"
+```
+
+[See a full example](https://github.com/algorandfoundation/puya/blob/main/test_cases/stubs/string.py).
+
+### BigUInt
+
+[`algopy.BigUInt`](#algopy.BigUInt) represents a variable length (max 512-bit) unsigned integer stored
+as `bytes[]` in the AVM.
+
+It supports all the same operators as `int`, except for power (`**`), left and right shift (`<<`
+and `>>`) and `/` (as with `UInt64`, you must use `//` for truncating division instead).
+
+Note that the op code costs for `bigint` math are an order of magnitude higher than those for
+`uint64` math. If you just need to handle overflow, take a look at the wide ops such as `addw`,
+`mulw`, etc - all of which are exposed through the [`algopy.op`](#algopy.op) module.
+
+Another contrast between `bigint` and `uint64` math is that `bigint` math ops don't immediately
+error on overflow - if the result exceeds 512-bits, then you can still access the value via
+`.bytes`, but any further math operations will fail.
+
+```python
+# you can instantiate with an integer literal
+num = algopy.BigUInt(1)
+# no arguments default to the zero value
+zero = algopy.BigUInt()
+# zero is False, any other value is True
+assert not zero
+assert num
+# Like Python's `int`, `BigUInt` is immutable, so augmented assignment operators return new values
+one = num
+num += 1
+assert one == 1
+assert num == UInt64(2)
+# note that once you have a variable of type BigUInt, you don't need to type any variables
+# derived from that or wrap int literals
+num2 = num + 200 // 3
+```
+
+[Further examples available here](https://github.com/algorandfoundation/puya/blob/main/test_cases/stubs/biguint.py).
+
+### bool
+
+The semantics of the AVM `bool` bounded type exactly match the semantics of Python's built-in `bool` type
+and thus Algorand Python uses the in-built `bool` type from Python.
+
+Per the behaviour in normal Python, Algorand Python automatically converts various types to `bool` when they
+appear in statements that expect a `bool` e.g. `if`/`while`/`assert` statements, appear in Boolean expressions
+(e.g. next to `and` or `or` keywords) or are explicitly casted to a bool.
+
+The semantics of `not`, `and` and `or` are special [per how these keywords work in Python](https://docs.python.org/3/reference/expressions.html#boolean-operations)
+(e.g. short circuiting).
+
+```python
+a = UInt64(1)
+b = UInt64(2)
+
+c = a or b
+d = b and a
+
+e = self.expensive_op(UInt64(0)) or self.side_effecting_op(UInt64(1))
+f = self.expensive_op(UInt64(3)) or self.side_effecting_op(UInt64(42))
+
+g = self.side_effecting_op(UInt64(0)) and self.expensive_op(UInt64(42))
+h = self.side_effecting_op(UInt64(2)) and self.expensive_op(UInt64(3))
+
+i = a if b < c else d + e
+if a:
+    log("a is True")
+```
+
+[Further examples available here](https://github.com/algorandfoundation/puya/blob/main/test_cases/stubs/uint64.py).
+
+### Account
+
+[`Account`](#algopy.Account) represents a logical Account, backed by a `bytes[32]` representing the
+bytes of the public key (without the checksum). It has various account related methods that can be called from the type.
+
+Also see [`algopy.arc4.Address`](#algopy.arc4.Address) if needing to represent the address as a distinct type.
+
+
+### Asset
+
+[`Asset`](#algopy.Asset) represents a logical Asset, backed by a `uint64` ID.
+It has various asset related methods that can be called from the type.
+
+### Application
+
+[`Application`](#algopy.Application) represents a logical Application, backed by a `uint64` ID.
+It has various application related methods that can be called from the type.
+
+## Python built-in types
+
+Unfortunately, the [AVM types](#avm-types) don't map to standard Python primitives. For instance,
+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.
+
+In saying that, there are many places where built-in Python types can be used and over time the places these types can be used are expected to increase.
+
+### bool
+
+[Per above](#bool) Algorand Python has full support for `bool`.
+
+### tuple
+
+Python tuples are supported as arguments to subroutines, local variables, return types.
+
+### typing.NamedTuple
+
+Python named tuples are also supported using [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple).
+
+```{note}
+Default field values and subclassing a NamedTuple are not supported
+```
+
+```python
+import typing
+
+import algopy
+
+
+class Pair(typing.NamedTuple):
+    foo: algopy.Bytes
+    bar: algopy.Bytes
+```
+
+### None
+
+`None` is not supported as a value, but is supported as a type annotation to indicate a function or subroutine
+returns no value.
+
+### int, str, bytes, float
+
+The `int`, `str` and `bytes` built-in types are currently only supported as [module-level constants](./lg-modules.md) or literals.
+
+They can be passed as arguments to various Algorand Python methods that support them or
+when interacting with certain [AVM types](#avm-types) e.g. adding a number to a `UInt64`.
+
+`float` is not supported.
+
+## Template variables
+
+Template variables can be used to represent a placeholder for a deploy-time provided
+value. This can be declared using the `TemplateVar[TYPE]` type where `TYPE` is the
+Algorand Python type that it will be interpreted as.
+
+```python
+from algopy import BigUInt, Bytes, TemplateVar, UInt64, arc4
+from algopy.arc4 import UInt512
+
+
+class TemplateVariablesContract(arc4.ARC4Contract):
+    @arc4.abimethod()
+    def get_bytes(self) -> Bytes:
+        return TemplateVar[Bytes]("SOME_BYTES")
+
+    @arc4.abimethod()
+    def get_big_uint(self) -> UInt512:
+        x = TemplateVar[BigUInt]("SOME_BIG_UINT")
+        return UInt512(x)
+
+    @arc4.baremethod(allow_actions=["UpdateApplication"])
+    def on_update(self) -> None:
+        assert TemplateVar[bool]("UPDATABLE")
+
+    @arc4.baremethod(allow_actions=["DeleteApplication"])
+    def on_delete(self) -> None:
+        assert TemplateVar[UInt64]("DELETABLE")
+```
+
+The resulting TEAL code that PuyaPy emits has placeholders with `TMPL_{template variable name}`
+that expects either an integer value or an encoded bytes value. This behaviour exactly
+matches what
+[AlgoKit Utils expects](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/app-deploy.md#compilation-and-template-substitution).
+
+For more information look at the API reference for [`TemplateVar`](./api-algopy.md#algopy.TemplateVar).
+
+## ARC-4 types
+
+ARC-4 data types are a first class concept in Algorand Python. They can be passed into ARC-4
+methods (which will translate to the relevant ARC-4 method signature), passed into subroutines, or
+instantiated into local variables. A limited set of operations are exposed on some ARC-4 types, but
+often it may make sense to convert the ARC-4 value to a native AVM type, in which case you can use
+the `native` property to retrieve the value. Most of the ARC-4 types also allow for mutation e.g.
+you can edit values in arrays by index.
+
+Please see the [reference documentation](./api-algopy.arc4.md) for the different classes that can
+be used to represent ARC-4 values or the [ARC-4 documentation](./lg-arc4.md) for more information
+about ARC-4.

package/dist/resources/knowledge/taxonomy/puya:docs:lg-unsupported-python-features.md

@@ -0,0 +1,52 @@
+# Unsupported Python features
+
+## raise, try/except/finally
+
+Exception raising and exception handling constructs are not supported.
+
+Supporting user exceptions would be costly to implement in terms of op codes.
+
+Furthermore, AVM errors and exceptions are not "catch-able", they immediately terminate the 
+program.
+
+Therefore, there is very little to no benefit of supporting exceptions and exception handling.
+
+The preferred method of raising an error that terminates is through the use of
+[assert statements](lg-errors.md).
+
+## with
+
+Context managers are redundant without exception handling support.
+
+## async
+
+The AVM is not just single threaded, but all operations are effectively "blocking", rendering 
+asynchronous programming effectively useless. 
+
+## closures & lambdas
+
+Without the support of function pointers, or other methods of invoking an arbitrary function,
+it's not possible to return a function as a closure. 
+
+Nested functions/lambdas as a means of repeating common operations within a given function may be 
+supported in the future.
+
+## global keyword
+
+Module level values are only allowed to be [constants](lg-modules.md#module-constants). No
+rebinding of module constants is allowed. It's not clear what the meaning here would be, since
+there's no real arbitrary means of storing state without associating it with a particular contract.
+If you do have need of such a thing, take a look at [gload_bytes](#algopy.op.gload_bytes)
+or [gload_uint64](#algopy.op.gload_uint64) if the contracts are within the same transaction,
+otherwise [AppGlobal.get_ex_bytes](#algopy.op.AppGlobal.get_ex_bytes)
+and [AppGlobal.get_ex_uint64](#algopy.op.AppGlobal.get_ex_uint64).
+
+## Inheritance (outside of contract classes)
+
+Polymorphism is also impossible to support without function pointers, so data classes (such as
+[arc4.Struct](#algopy.arc4.Struct)) don't currently allow for inheritance. Member functions there
+are not supported because we're not sure yet whether it's better to not have inheritance but allow
+functions on data classes, or to allow inheritance and disallow member functions.
+
+Contract inheritance is a special case, since each concrete contract is compiled separately, true
+polymorphism isn't required as all references can be resolved at compile time.