@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,90 @@
+# Module level constructs
+
+You can write compile-time constant code at a module level and then use them in place of [Python built-in literal types](./lg-types.md#python-built-in-types).
+
+For a full example of what syntax is currently possible see the [test case example](https://github.com/algorandfoundation/puya/blob/main/test_cases/module_consts/contract.py).
+
+## Module constants
+
+Module constants are compile-time constant, and can contain `bool`, `int`, `str` and `bytes`.
+
+You can use fstrings and other compile-time constant values in module constants too.
+
+For example:
+
+```python
+from algopy import UInt64, subroutine
+
+SCALE = 100000
+SCALED_PI = 314159
+
+@subroutine
+def circle_area(radius: UInt64) -> UInt64:
+    scaled_result = SCALED_PI * radius**2
+    result = scaled_result // SCALE
+    return result
+
+@subroutine
+def circle_area_100() -> UInt64:
+    return circle_area(UInt64(100))
+```
+
+## If statements
+
+You can use if statements with compile-time constants in module constants.
+
+For example:
+
+```python
+FOO = 42
+
+if FOO > 12:
+    BAR = 123
+else:
+    BAR = 456
+```
+
+## Integer math
+
+Module constants can also be defined using common integer expressions.
+
+For example:
+
+```python
+SEVEN = 7
+TEN = 7 + 3
+FORTY_NINE = 7 ** 2
+```
+
+## Strings
+
+Module `str` constants can use f-string formatting and other common string expressions.
+
+For example:
+
+```python
+NAME = "There"
+MY_FORMATTED_STRING = f"Hello {NAME}" # Hello There
+PADDED = f"{123:05}" # "00123"
+DUPLICATED = "5" * 3 # "555"
+```
+
+## Type aliases
+
+You can create type aliases to make your contract terser and more expressive.
+
+For example:
+
+```python
+import typing
+
+from algopy import arc4
+VoteIndexArray: typing.TypeAlias = arc4.DynamicArray[arc4.UInt8]
+
+Row: typing.TypeAlias = arc4.StaticArray[arc4.UInt8, typing.Literal[3]]
+Game: typing.TypeAlias = arc4.StaticArray[Row, typing.Literal[3]]
+Move: typing.TypeAlias = tuple[arc4.UInt64, arc4.UInt64]
+
+Bytes32: typing.TypeAlias = arc4.StaticArray[arc4.Byte, typing.Literal[32]]
+Proof: typing.TypeAlias = arc4.DynamicArray[Bytes32]
+```

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

@@ -0,0 +1,3 @@
+# Opcode budgets
+
+Algorand Python provides a helper method for increasing the [available opcode budget](https://developer.algorand.org/docs/get-details/dapps/avm/teal/#dynamic-operational-cost-of-teal-opcodes), see [`algopy.ensure_budget`](#algopy.ensure_budget).

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

@@ -0,0 +1,40 @@
+# AVM operations
+
+Algorand Python allows you to do express [every op code the AVM has available](https://developer.algorand.org/docs/get-details/dapps/avm/teal/specification/#operations) apart from ops that manipulate the stack (to avoid conflicts with the compiler), and `log` (to avoid confusion with the superior [Algorand Python log function](./lg-logs.md)). These ops are exposed via the [`algopy.op`](#algopy.op) submodule.
+We generally recommend importing this entire submodule so you can use intellisense to discover the available methods:
+
+```python
+from algopy import UInt64, op, subroutine
+
+@subroutine
+def sqrt_16() -> UInt64:
+    return op.sqrt(16)
+```
+
+All ops are typed using Algorand Python types and have correct static type representations.
+
+Many ops have higher-order functionality that Algorand Python exposes and would limit the need to reach for the underlying ops. For instance, there is first-class support for local and global storage so there is little need to use the likes of `app_local_get` et. al. But they are still exposed just in case you want to do something that Algorand Python's abstractions don't support.
+
+## Txn
+
+The `Txn` opcodes are so commonly used they have been exposed directly in the `algopy` module and can be easily imported to make it terser to access:
+
+```python
+from algopy import subroutine, Txn
+
+@subroutine
+def has_no_app_args() -> bool:
+    return Txn.num_app_args == 0
+```
+
+## Global
+
+The `Global` opcodes are so commonly used they have been exposed directly in the `algopy` module and can be easily imported to make it terser to access:
+
+```python
+from algopy import subroutine, Global, Txn
+
+@subroutine
+def only_allow_creator() -> None:
+    assert Txn.sender == Global.creator_address, "Only the contract creator can perform this operation"
+```

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

@@ -0,0 +1,222 @@
+# Storing data on-chain
+
+Algorand smart contracts have [three different types of on-chain storage](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/state/)
+they can utilise: [Global storage](#global-storage), [Local storage](#local-storage), [Box Storage](#box-storage), and [Scratch storage](#scratch-storage).
+
+The life-cycle of a smart contract matches the semantics of Python classes when you consider
+deploying a smart contract as "instantiating" the class. Any calls to that smart contract are made
+to that instance of the smart contract, and any state assigned to `self.` variables will persist
+across different invocations (provided the transaction it was a part of succeeds, of course). You can
+deploy the same contract class multiple times, each will become a distinct and isolated instance.
+
+During a single smart contract execution there is also the ability to use "temporary" storage
+either global to the contract execution via [Scratch storage](#scratch-storage), or local to
+the current method via [local variables and subroutine params](./lg-structure.md#subroutines).
+
+## Global storage
+
+Global storage is state that is stored against the contract instance and can be retrieved
+by key. There are [AVM limits to the amount of global storage that can be allocated to a contract](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/state/#global-storage).
+
+This is represented in Algorand Python by either:
+
+1. Assigning any [Algorand Python typed](./lg-types.md) value to an instance variable (e.g. `self.value = UInt64(3)`)
+2. Using an instance of `GlobalState`, which gives [some extra features](./api-algopy.md#algopy.GlobalState) to understand
+   and control the value and the metadata of it (which propagates to the ARC-32 app spec file)
+
+For example:
+
+```python
+self.global_int_full = GlobalState(UInt64(55), key="gif", description="Global int full")
+self.global_int_simplified = UInt64(33)
+self.global_int_no_default = GlobalState(UInt64)
+
+self.global_bytes_full = GlobalState(Bytes(b"Hello"))
+self.global_bytes_simplified = Bytes(b"Hello")
+self.global_bytes_no_default = GlobalState(Bytes)
+
+global_int_full_set = bool(self.global_int_full)
+bytes_with_default_specified = self.global_bytes_no_default.get(b"Default if no value set")
+int, is_set = self.global_int_simplified.maybe()
+error_if_not_set = self.global_int_no_default.value
+```
+
+These values can be assigned anywhere you have access to `self` i.e. any instance methods/subroutines. The information about
+global storage is automatically included in the ARC-32 app spec file and thus will automatically appear within
+any [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients).
+
+## Local storage
+
+Local storage is state that is stored against the contract instance for a specific account and can be retrieved
+by key and account address. There are [AVM limits to the amount of local storage that can be allocated to a contract](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/state/#local-storage).
+
+This is represented in Algorand Python by using an instance of [`LocalState`](./api-algopy.md#algopy.LocalState).
+
+For example:
+
+```python
+def __init__(self) -> None:
+    self.local = LocalState(Bytes)
+    self.local_with_metadata = LocalState(UInt64, key = "lwm", description = "Local with metadata")
+
+@subroutine
+def get_guaranteed_data(self, for_account: Account) -> Bytes:
+    return self.local[for_account]
+
+@subroutine
+def get_data_with_default(self, for_account: Account, default: Bytes) -> Bytes:
+    return self.local.get(for_account, default)
+
+@subroutine
+def get_data_or_assert(self, for_account: Account) -> Bytes:
+    result, exists = self.local.maybe(for_account)
+    assert exists, "no data for account"
+    return result
+
+@subroutine
+def set_data(self, for_account: Account, value: Bytes) -> None:
+    self.local[for_account] = value
+
+@subroutine
+def delete_data(self, for_account: Account) -> None:
+    del self.local[for_account]
+```
+
+These values can be assigned anywhere you have access to `self` i.e. any instance methods/subroutines. The information about
+local storage is automatically included in the ARC-32 app spec file and thus will automatically appear within
+any [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients).
+
+## Box storage
+
+We provide 3 different types for accessing box storage: [Box](./api-algopy.md#algopy.Box), [BoxMap](./api-algopy.md#algopy.BoxMap), and [BoxRef](./api-algopy.md#algopy.BoxBlob). We also expose raw operations via the [AVM ops](./lg-ops.md) module.
+
+Before using box storage, be sure to familiarise yourself with the [requirements and restrictions](https://developer.algorand.org/articles/smart-contract-storage-boxes/) of the underlying API.
+
+The `Box` type provides an abstraction over storing a single value in a single box. A box can be declared against `self`
+in an `__init__` method (in which case the key must be a compile time constant); or as a local variable within any 
+subroutine. `Box` proxy instances can be passed around like any other value. 
+
+Once declared, you can interact with the box via its instance methods.
+
+
+```python
+import typing as t
+from algopy import Box, arc4, Contract, op
+
+
+class MyContract(Contract):
+    def __init__(self) -> None:
+        self.box_a = Box(arc4.StaticArray[arc4.UInt32, t.Literal[20]], key=b"a")
+    
+    def approval_program(self) -> bool:
+        box_b = Box(arc4.String, key=b"b")
+        box_b.value = arc4.String("Hello")
+        # Check if the box exists
+        if self.box_a:
+            # Reassign the value
+            self.box_a.value[2] = arc4.UInt32(40)
+        else:
+            # Assign a new value
+            self.box_a.value = arc4.StaticArray[arc4.UInt32, t.Literal[20]].from_bytes(op.bzero(20 * 4))
+        # Read a value
+        return self.box_a.value[4] == arc4.UInt32(2)    
+```
+
+`BoxMap` is similar to the `Box` type, but allows for grouping a set of boxes with a common key and content type. 
+A custom `key_prefix` can optionally be provided, with the default being to use the variable name as the prefix. 
+The key can be a `Bytes` value, or anything that can be converted to `Bytes`. The final box name is the combination of `key_prefix + key`.
+
+```python
+from algopy import BoxMap, Contract, Account, Txn, String
+
+class MyContract(Contract):
+    def __init__(self) -> None:
+        self.my_map = BoxMap(Account, String, key_prefix=b"a_")
+    
+    def approval_program(self) -> bool:        
+        # Check if the box exists
+        if Txn.sender in self.my_map:
+            # Reassign the value
+            self.my_map[Txn.sender] = String(" World")
+        else:
+            # Assign a new value
+            self.my_map[Txn.sender] = String("Hello")
+        # Read a value
+        return self.my_map[Txn.sender] == String("Hello World")
+```
+
+`BoxRef` is a specialised type for interacting with boxes which contain binary data. In addition to being able to set and read the box value, there are operations for extracting and replacing just a portion of the box data which 
+is useful for minimizing the amount of reads and writes required, but also allows you to interact with byte arrays which are longer than the AVM can support (currently 4096).
+
+```python
+from algopy import BoxRef, Contract, Global, Txn
+
+
+class MyContract(Contract):
+    def approval_program(self) -> bool:
+        my_blob = BoxRef(key=b"blob")
+
+        sender_bytes = Txn.sender.bytes
+        app_address = Global.current_application_address.bytes
+        assert my_blob.create(8000)
+        my_blob.replace(0, sender_bytes)
+        my_blob.splice(0, 0, app_address)
+        first_64 = my_blob.extract(0, 32 * 2)
+        assert first_64 == app_address + sender_bytes
+        assert my_blob.delete()
+        value, exists = my_blob.maybe()
+        assert not exists
+        assert my_blob.get(default=sender_bytes) == sender_bytes
+        my_blob.create(sender_bytes + app_address)
+        assert my_blob, "Blob exists"
+        assert my_blob.length == 64
+        return True
+```
+
+
+
+If none of these abstractions suit your needs, you can use the box storage [AVM ops](./lg-ops.md) to interact with box storage. These ops match closely to the opcodes available on the AVM. 
+
+For example:
+
+```python
+op.Box.create(b"key", size)
+op.Box.put(Txn.sender.bytes, answer_ids.bytes)
+(votes, exists) = op.Box.get(Txn.sender.bytes)
+op.Box.replace(TALLY_BOX_KEY, index, op.itob(current_vote + 1))
+```
+
+See the [voting contract example](https://github.com/algorandfoundation/puya/tree/main/examples/voting/voting.py) for a real-world example that uses box storage.
+
+## Scratch storage
+
+To use stratch storage you need to [register the scratch storage that you want to use](./lg-structure.md#contract-class-configuration) and then you can use the scratch storage [AVM ops](./lg-ops.md).
+
+For example:
+
+```python
+from algopy import Bytes, Contract, UInt64, op, urange
+
+TWO = 2
+TWENTY = 20
+
+
+class MyContract(Contract, scratch_slots=(1, TWO, urange(3, TWENTY))):
+    def approval_program(self) -> bool:
+        op.Scratch.store(1, UInt64(5))
+
+        op.Scratch.store(2, Bytes(b"Hello World"))
+
+        for i in urange(3, 20):
+            op.Scratch.store(i, i)
+
+        assert op.Scratch.load_uint64(1) == UInt64(5)
+
+        assert op.Scratch.load_bytes(2) == b"Hello World"
+
+        assert op.Scratch.load_uint64(5) == UInt64(5)
+        return True
+
+    def clear_state_program(self) -> bool:
+        return True
+```

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

@@ -0,0 +1,283 @@
+# Program structure
+
+An Algorand Python smart contract is defined within a single class. You can extend other
+contracts (through inheritance), and also define standalone functions and reference them. This also
+works across different Python packages - in other words, you can have a Python library with common
+functions and re-use that library across multiple projects!
+
+## Modules
+
+Algorand Python modules are files that end in `.py`, as with standard Python. Sub-modules are
+supported as well, so you're free to organise your Algorand Python code however you see fit.
+The standard python import rules apply, including
+[relative vs absolute import](https://docs.python.org/3/reference/import.html#package-relative-imports)
+requirements.
+
+A given module can contain zero, one, or many smart contracts and/or logic signatures.
+
+A module can contain [contracts](#contract-classes), [subroutines](#subroutines),
+[logic signatures](#logic-signatures), and [compile-time constant code and values](lg-modules.md).
+
+## Typing
+
+Algorand Python code must be fully typed with
+[type annotations](https://docs.python.org/3/library/typing.html).
+
+In practice, this mostly means annotating the arguments and return types of all functions.
+
+## Subroutines
+
+Subroutines are "internal" or "private" methods to a contract. They can exist as part of a contract
+class, or at the module level so they can be used by multiple classes or even across multiple
+projects.
+
+You can pass parameters to subroutines and define local variables, both of which automatically get
+managed for you with semantics that match Python semantics.
+
+All subroutines must be decorated with `algopy.subroutine`, like so:
+
+```python
+def foo() -> None: # compiler error: not decorated with subroutine
+    ...
+
+@algopy.subroutine
+def bar() -> None:
+    ...
+```
+
+```{note}
+Requiring this decorator serves two key purposes:
+
+1. You get an understandable error message if you try and use a third party package that wasn't
+   built for Algorand Python
+1. It provides for the ability to modify the functions on the fly when running in Python itself, in
+   a future testing framework.
+```
+
+Argument and return types to a subroutine can be any Algorand Python variable type (except for  
+[some inner transaction types](lg-transactions.md#inner-transaction-objects-cannot-be-passed-to-or-returned-from-subroutines)
+).
+
+Returning multiple values is allowed, this is annotated in the standard Python way with `tuple`:
+
+```python
+@algopy.subroutine
+def return_two_things() -> tuple[algopy.UInt64, algopy.String]:
+    ...
+```
+
+Keyword only and positional only argument list modifiers are supported:
+
+```python
+@algopy.subroutine
+def my_method(a: algopy.UInt64, /, b: algopy.UInt64, *, c: algopy.UInt64) -> None:
+    ...
+```
+
+In this example, `a` can only be passed positionally, `b` can be passed either by position or by
+name, and `c` can only be passed by name.
+
+The following argument/return types are not currently supported:
+
+-   Type unions
+-   Variadic args like `*args`, `**kwargs`
+-   Python types such as `int`
+-   Default values are not supported
+
+## Contract classes
+
+An [Algorand smart contract](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/)
+consists of two distinct "programs"; an approval program, and a
+clear-state program. These are tied together in Algorand Python as a single class.
+
+All contracts must inherit from the base class `algopy.Contract` - either directly or indirectly,
+which can include inheriting from `algopy.ARC4Contract`.
+
+The life-cycle of a smart contract matches the semantics of Python classes when you consider
+deploying a smart contract as "instantiating" the class. Any calls to that smart contract are made
+to that instance of the smart contract, and any state assigned to `self.` will persist across
+different invocations (provided the transaction it was a part of succeeds, of course). You can
+deploy the same contract class multiple times, each will become a distinct and isolated instance.
+
+Contract classes can optionally implement an `__init__` method, which will be executed exactly
+once, on first deployment. This method takes no arguments, but can contain arbitrary code,
+including reading directly from the transaction arguments via [`Txn`](#algopy.op.Txn). This makes
+it a good place to put common initialisation code, particularly in ARC-4 contracts with multiple
+methods that allow for creation.
+
+The contract class body should not contain any logic or variable initialisations, only method
+definitions. Forward type declarations are allowed.
+
+Example:
+
+```python
+class MyContract(algopy.Contract):
+    foo: algopy.UInt64  # okay
+    bar = algopy.UInt64(1) # not allowed
+
+    if True: # also not allowed
+        bar = algopy.UInt64(2)
+```
+
+Only concrete (ie non-abstract) classes produce output artifacts for deployment. To mark a class
+as explicitly abstract, inherit from [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC).
+
+```{note}
+The compiler will produce a warning if a Contract class is implicitly abstract, i.e. if any
+abstract methods are unimplemented.
+```
+
+For more about inheritance and it's role in code reuse, see the section
+in [Code reuse](lg-code-reuse.md#inheritance)
+
+### Contract class configuration
+
+When defining a contract subclass you can pass configuration options to the `algopy.Contract`
+base class [per the API documentation](./api-algopy.md#algopy.Contract).
+
+Namely you can pass in:
+
+-   `name` - Which will affect the output TEAL file name if there are multiple non-abstract contracts
+    in the same file and will also be used as the contract name in the ARC-32 application.json instead of the class name.
+-   `scratch_slots` - Which allows you to mark a slot ID or range of slot IDs as "off limits" to Puya
+    so you can manually use them.
+-   `state_totals` - Which allows defining what values should be used for global and local uint and bytes storage values
+    when creating a contract and will appear in ARC-32 app spec.
+
+Full example:
+
+```python
+GLOBAL_UINTS = 3
+
+class MyContract(
+    algopy.Contract,
+    name="CustomName",
+    scratch_slots=[5, 25, algopy.urange(110, 115)],
+    state_totals=algopy.StateTotals(local_bytes=1, local_uints=2, global_bytes=4, global_uints=GLOBAL_UINTS),
+):
+    ...
+```
+
+### Example: Simplest possible `algopy.Contract` implementation
+
+For a non-ARC4 contract, the contract class must implement an `approval_program` and
+a `clear_state_program` method.
+
+As an example, this is a valid contract that always approves:
+
+```python
+class Contract(algopy.Contract):
+    def approval_program(self) -> bool:
+        return True
+
+    def clear_state_program(self) -> bool:
+        return True
+```
+
+The return value of these methods can be either a `bool` that indicates whether the transaction
+should approve or not, or a `algopy.UInt64` value, where `UInt64(0)` indicates that the transaction
+should be rejected and any other value indicates that it should be approved.
+
+### Example: Simple call counter
+
+Here is a very simple example contract that maintains a counter of how many times it has
+been called (including on create).
+
+```python
+class Counter(algopy.Contract):
+    def __init__(self) -> None:
+        self.counter = algopy.UInt64(0)
+
+    def approval_program(self) -> bool:
+        match algopy.Txn.on_completion:
+            case algopy.OnCompleteAction.NoOp:
+                self.increment_counter()
+                return True
+            case _:
+                # reject all OnCompletionAction's other than NoOp
+                return False
+
+    def clear_state_program(self) -> bool:
+        return True
+
+    @algopy.subroutine
+    def increment_counter(self) -> None:
+        self.counter += 1
+```
+
+Some things to note:
+
+-   `self.counter` will be stored in the application's [Global State](lg-storage.md#global-state).
+-   The return type of `__init__` must be `None`, per standard typed Python.
+-   Any methods other than `__init__`, `approval_program` or `clear_state_program` must be decorated
+    with `@subroutine`.
+
+### Example: Simplest possible `algopy.ARC4Contract` implementation
+
+And here is a valid ARC4 contract:
+
+```python
+class ABIContract(algopy.ARC4Contract):
+    pass
+```
+
+A default `@algopy.arc4.baremethod` that allows contract creation is automatically inserted if no
+other public method allows execution on create.
+
+The approval program is always automatically generated, and consists of a router which delegates
+based on the transaction application args to the correct public method.
+
+A default `clear_state_program` is implemented which always approves, but this can be overridden.
+
+### Example: An ARC4 call counter
+
+```python
+import algopy
+
+class ARC4Counter(algopy.ARC4Contract):
+    def __init__(self) -> None:
+        self.counter = algopy.UInt64(0)
+
+    @algopy.arc4.abimethod(create="allow")
+    def invoke(self) -> algopy.arc4.UInt64:
+        self.increment_counter()
+        return algopy.arc4.UInt64(self.counter)
+
+    @algopy.subroutine
+    def increment_counter(self) -> None:
+        self.counter += 1
+```
+
+This functions very similarly to the [simple example](#example-simple-call-counter).
+
+Things to note here:
+
+-   Since the `invoke` method has `create="allow"`, it can be called both as the method to create the
+    app and also to invoke it after creation. This also means that no default bare-method create will
+    be generated, so the only way to create the contract is through this method.
+-   The default options for `abimethod` is to only allow `NoOp` as an on-completion-action, so we
+    don't need to check this manually.
+-   The current call count is returned from the `invoke` method.
+-   Every method in an `AR4Contract` except for the optional `__init__` and `clear_state_program`
+    methods must be decorated with one of `algopy.arc4.abimethod`, `alogpy.arc4.baremethod`, or
+    `algopy.subroutine`. `subroutines` won't be directly callable through the default router.
+
+See the [ARC-4 section](lg-arc4.md) of this language guide for more info on the above.
+
+## Logic signatures
+
+[Logic signatures on Algorand](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/smartsigs/)
+are stateless, and consist of a single program. As such, they are implemented as functions in Algorand Python
+rather than classes.
+
+```python
+@algopy.logicsig
+def my_log_sig() -> bool:
+    ...
+```
+
+Similar to `approval_program` or `clear_state_program` methods, the function must take no
+arguments, and return either `bool` or `algopy.UInt64`. The meaning is the same: a `True`
+value or non-zero `UInt64` value indicates success, `False` or `UInt64(0)` indicates failure.
+
+Logic signatures can make use of subroutines that are not nested in contract classes.