@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:testing-guide:signature-testing.md

@@ -0,0 +1,73 @@
+# Smart Signature Testing
+
+Test Algorand smart signatures (LogicSigs) with ease using the Algorand Python Testing framework.
+
+```{testsetup}
+import algopy
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Define a LogicSig
+
+Use the `@logicsig` decorator to create a LogicSig:
+
+```{testcode}
+from algopy import logicsig, Account, Txn, Global, UInt64, Bytes
+
+@logicsig
+def hashed_time_locked_lsig() -> bool:
+    # LogicSig code here
+    return True  # Approve transaction
+```
+
+## Execute and Test
+
+Use `AlgopyTestContext.execute_logicsig()` to run and verify LogicSigs:
+
+```{testcode}
+with context.txn.create_group([
+    context.any.txn.payment(),
+]):
+    result = context.execute_logicsig(hashed_time_locked_lsig, algopy.Bytes(b"secret"))
+
+assert result is True
+```
+
+`execute_logicsig()` returns a boolean:
+
+-   `True`: Transaction approved
+-   `False`: Transaction rejected
+
+## Pass Arguments
+
+Provide arguments to LogicSigs using `execute_logicsig()`:
+
+```{testcode}
+result = context.execute_logicsig(hashed_time_locked_lsig, algopy.Bytes(b"secret"))
+```
+
+Access arguments in the LogicSig with `algopy.op.arg()` opcode:
+
+```{testcode}
+@logicsig
+def hashed_time_locked_lsig() -> bool:
+    secret = algopy.op.arg(0)
+    expected_hash = algopy.op.sha256(algopy.Bytes(b"secret"))
+    return algopy.op.sha256(secret) == expected_hash
+
+# Example usage
+secret = algopy.Bytes(b"secret")
+assert context.execute_logicsig(hashed_time_locked_lsig, secret)
+```
+
+For more details on available operations, see the [coverage](../coverage.md).
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:testing-guide:state-management.md

@@ -0,0 +1,104 @@
+# State Management
+
+`algorand-python-testing` provides tools to test state-related abstractions in Algorand smart contracts. This guide covers global state, local state, boxes, and scratch space management.
+
+```{testsetup}
+import algopy
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Global State
+
+Global state is represented as instance attributes on `algopy.Contract` and `algopy.ARC4Contract` classes.
+
+```{testcode}
+class MyContract(algopy.ARC4Contract):
+    def __init__(self):
+        self.state_a = algopy.GlobalState(algopy.UInt64, key="global_uint64")
+        self.state_b = algopy.UInt64(1)
+
+# In your test
+contract = MyContract()
+contract.state_a.value = algopy.UInt64(10)
+contract.state_b.value = algopy.UInt64(20)
+```
+
+## Local State
+
+Local state is defined similarly to global state, but accessed using account addresses as keys.
+
+```{testcode}
+class MyContract(algopy.ARC4Contract):
+    def __init__(self):
+        self.local_state_a = algopy.LocalState(algopy.UInt64, key="state_a")
+
+# In your test
+contract = MyContract()
+account = context.any.account()
+contract.local_state_a[account] = algopy.UInt64(10)
+```
+
+## Boxes
+
+The framework supports various Box abstractions available in `algorand-python`.
+
+```{testcode}
+class MyContract(algopy.ARC4Contract):
+    def __init__(self):
+        self.box_map = algopy.BoxMap(algopy.Bytes, algopy.UInt64)
+
+    @algopy.arc4.abimethod()
+    def some_method(self, key_a: algopy.Bytes, key_b: algopy.Bytes, key_c: algopy.Bytes) -> None:
+        self.box = algopy.Box(algopy.UInt64, key=key_a)
+        self.box.value = algopy.UInt64(1)
+        self.box_map[key_b] = algopy.UInt64(1)
+        self.box_map[key_c] = algopy.UInt64(2)
+
+# In your test
+contract = MyContract()
+key_a = b"key_a"
+key_b = b"key_b"
+key_c = b"key_c"
+
+contract.some_method(algopy.Bytes(key_a), algopy.Bytes(key_b), algopy.Bytes(key_c))
+
+# Access boxes
+box_content = context.ledger.get_box(contract, key_a)
+assert context.ledger.box_exists(contract, key_a)
+
+# Set box content manually
+with context.txn.create_group():
+    context.ledger.set_box(contract, key_a, algopy.op.itob(algopy.UInt64(1)))
+```
+
+## Scratch Space
+
+Scratch space is represented as a list of 256 slots for each transaction.
+
+```{testcode}
+class MyContract(algopy.Contract, scratch_slots=(1, 2, algopy.urange(3, 20))):
+    def approval_program(self):
+        algopy.op.Scratch.store(1, algopy.UInt64(5))
+        assert algopy.op.Scratch.load_uint64(1) == algopy.UInt64(5)
+        return True
+
+# In your test
+contract = MyContract()
+result = contract.approval_program()
+
+assert result
+scratch_space = context.txn.last_group.get_scratch_space()
+assert scratch_space[1] == algopy.UInt64(5)
+```
+
+For more detailed information, explore the example contracts in the `examples/` directory, the [coverage](../coverage.md) page, and the [API documentation](../api.md).
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:testing-guide:subroutines.md

@@ -0,0 +1,62 @@
+# Subroutines
+
+Subroutines allow direct testing of internal contract logic without full application calls.
+
+```{testsetup}
+import algopy
+import algopy_testing
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Overview
+
+The `@algopy.subroutine` decorator exposes contract methods for isolated testing within the Algorand Python Testing framework. This enables focused validation of core business logic without the overhead of full application deployment and execution.
+
+## Usage
+
+1. Decorate internal methods with `@algopy.subroutine`:
+
+```{testcode}
+from algopy import subroutine, UInt64
+
+class MyContract:
+    @subroutine
+    def calculate_value(self, input: UInt64) -> UInt64:
+        return input * UInt64(2)
+```
+
+2. Test the subroutine directly:
+
+```{testcode}
+def test_calculate_value(context: algopy_testing.AlgopyTestContext):
+    contract = MyContract()
+    result = contract.calculate_value(UInt64(5))
+    assert result == UInt64(10)
+```
+
+## Benefits
+
+-   Faster test execution
+-   Simplified debugging
+-   Focused unit testing of core logic
+
+## Best Practices
+
+-   Use subroutines for complex internal calculations
+-   Prefer writing `pure` subroutines in ARC4Contract classes
+-   Combine with full application tests for comprehensive coverage
+-   Maintain realistic input and output types (e.g., `UInt64`, `Bytes`)
+
+## Example
+
+For a complete example, see the `simple_voting` contract in the [examples](../examples.md) section.
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:testing-guide:transactions.md

@@ -0,0 +1,200 @@
+# Transactions
+
+The testing framework follows the Transaction definitions described in [`algorand-python` docs](https://algorand-python.readthedocs.io/en/latest/algorand_sdk/transactions.html). This section focuses on _value generators_ and interactions with inner transactions, it also explains how the framework identifies _active_ transaction group during contract method/subroutine/logicsig invocation.
+
+```{testsetup}
+import algopy
+import algopy_testing
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Group Transactions
+
+Refers to test implementation of transaction stubs available under `algopy.gtxn.*` namespace. Available under [`algopy.TxnValueGenerator`](../api.md) instance accessible via `context.any.txn` property:
+
+```{mermaid}
+graph TD
+    A[TxnValueGenerator] --> B[payment]
+    A --> C[asset_transfer]
+    A --> D[application_call]
+    A --> E[asset_config]
+    A --> F[key_registration]
+    A --> G[asset_freeze]
+    A --> H[transaction]
+```
+
+```{testcode}
+... # instantiate test context
+
+# Generate a random payment transaction
+pay_txn = context.any.txn.payment(
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    receiver=context.any.account(),  # Required
+    amount=algopy.UInt64(1000000)  # Required
+)
+
+# Generate a random asset transfer transaction
+asset_transfer_txn = context.any.txn.asset_transfer(
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    receiver=context.any.account(),  # Required
+    asset_id=algopy.UInt64(1),  # Required
+    amount=algopy.UInt64(1000)  # Required
+)
+
+# Generate a random application call transaction
+app_call_txn = context.any.txn.application_call(
+    app_id=context.any.application(),  # Required
+    app_args=[algopy.Bytes(b"arg1"), algopy.Bytes(b"arg2")],  # Optional: Defaults to empty list if not provided
+    accounts=[context.any.account()],  # Optional: Defaults to empty list if not provided
+    assets=[context.any.asset()],  # Optional: Defaults to empty list if not provided
+    apps=[context.any.application()],  # Optional: Defaults to empty list if not provided
+    approval_program_pages=[algopy.Bytes(b"approval_code")],  # Optional: Defaults to empty list if not provided
+    clear_state_program_pages=[algopy.Bytes(b"clear_code")],  # Optional: Defaults to empty list if not provided
+    scratch_space={0: algopy.Bytes(b"scratch")}  # Optional: Defaults to empty dict if not provided
+)
+
+# Generate a random asset config transaction
+asset_config_txn = context.any.txn.asset_config(
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    asset_id=algopy.UInt64(1),  # Optional: If not provided, creates a new asset
+    total=1000000,  # Required for new assets
+    decimals=0,  # Required for new assets
+    default_frozen=False,  # Optional: Defaults to False if not provided
+    unit_name="UNIT",  # Optional: Defaults to empty string if not provided
+    asset_name="Asset",  # Optional: Defaults to empty string if not provided
+    url="http://asset-url",  # Optional: Defaults to empty string if not provided
+    metadata_hash=b"metadata_hash",  # Optional: Defaults to empty bytes if not provided
+    manager=context.any.account(),  # Optional: Defaults to sender if not provided
+    reserve=context.any.account(),  # Optional: Defaults to zero address if not provided
+    freeze=context.any.account(),  # Optional: Defaults to zero address if not provided
+    clawback=context.any.account()  # Optional: Defaults to zero address if not provided
+)
+
+# Generate a random key registration transaction
+key_reg_txn = context.any.txn.key_registration(
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    vote_pk=algopy.Bytes(b"vote_pk"),  # Optional: Defaults to empty bytes if not provided
+    selection_pk=algopy.Bytes(b"selection_pk"),  # Optional: Defaults to empty bytes if not provided
+    vote_first=algopy.UInt64(1),  # Optional: Defaults to 0 if not provided
+    vote_last=algopy.UInt64(1000),  # Optional: Defaults to 0 if not provided
+    vote_key_dilution=algopy.UInt64(10000)  # Optional: Defaults to 0 if not provided
+)
+
+# Generate a random asset freeze transaction
+asset_freeze_txn = context.any.txn.asset_freeze(
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    asset_id=algopy.UInt64(1),  # Required
+    freeze_target=context.any.account(),  # Required
+    freeze_state=True  # Required
+)
+
+# Generate a random transaction of a specified type
+generic_txn = context.any.txn.transaction(
+    type=algopy.TransactionType.Payment,  # Required
+    sender=context.any.account(),  # Optional: Defaults to context's default sender if not provided
+    receiver=context.any.account(),  # Required for Payment
+    amount=algopy.UInt64(1000000)  # Required for Payment
+)
+```
+
+## Preparing for execution
+
+When a smart contract instance (application) is interacted with on the Algorand network, it must be performed in relation to a specific transaction or transaction group where one or many transactions are application calls to target smart contract instances.
+
+To emulate this behaviour, the `create_group` context manager is available on [`algopy.TransactionContext`](../api.md) instance that allows setting temporary transaction fields within a specific scope, passing in emulated transaction objects and identifying the active transaction index within the transaction group
+
+```{testcode}
+import algopy
+from algopy_testing import AlgopyTestContext, algopy_testing_context
+
+class SimpleContract(algopy.ARC4Contract):
+    @algopy.arc4.abimethod
+    def check_sender(self) -> algopy.arc4.Address:
+        return algopy.arc4.Address(algopy.Txn.sender)
+...
+
+# Create a contract instance
+contract = SimpleContract()
+# Use active_txn_overrides to change the sender
+test_sender = context.any.account()
+with context.txn.create_group(active_txn_overrides={"sender": test_sender}):
+    # Call the contract method
+    result = contract.check_sender()
+assert result == test_sender
+
+# Assert that the sender is the test_sender after exiting the
+# transaction group context
+assert context.txn.last_active.sender == test_sender
+# Assert the size of last transaction group
+assert len(context.txn.last_group.txns) == 1
+```
+
+## Inner Transaction
+
+Inner transactions are AVM transactions that are signed and executed by AVM applications (instances of deployed smart contracts or signatures).
+
+When testing smart contracts, to stay consistent with AVM, the framework \_does not allow you to submit inner transactions outside of contract/subroutine invocation, but you can interact with and manage inner transactions using the test context manager as follows:
+
+```{testcode}
+class MyContract(algopy.ARC4Contract):
+    @algopy.arc4.abimethod
+    def pay_via_itxn(self, asset: algopy.Asset) -> None:
+        algopy.itxn.Payment(
+            receiver=algopy.Txn.sender,
+            amount=algopy.UInt64(1)
+        ).submit()
+
+... # setup context (below assumes available under 'context' variable)
+
+# Create a contract instance
+contract = MyContract()
+
+# Generate a random asset
+asset = context.any.asset()
+
+# Execute the contract method
+contract.pay_via_itxn(asset=asset)
+
+# Access the last submitted inner transaction
+payment_txn = context.txn.last_group.last_itxn.payment
+
+# Assert properties of the inner transaction
+assert payment_txn.receiver == context.txn.last_active.sender
+assert payment_txn.amount == algopy.UInt64(1)
+
+# Access all inner transactions in the last group
+for itxn in context.txn.last_group.itxn_groups[-1]:
+    # Perform assertions on each inner transaction
+    ...
+
+# Access a specific inner transaction group
+first_itxn_group = context.txn.last_group.get_itxn_group(0)
+first_payment_txn = first_itxn_group.payment(0)
+```
+
+In this example, we define a contract method `pay_via_itxn` that creates and submits an inner payment transaction. The test context automatically captures and stores the inner transactions submitted by the contract method.
+
+Note that we don't need to wrap the execution in a `create_group` context manager because the method is decorated with `@algopy.arc4.abimethod`, which automatically creates a transaction group for the method. The `create_group` context manager is only needed when you want to create more complex transaction groups or patch transaction fields for various transaction-related opcodes in AVM.
+
+To access the submitted inner transactions:
+
+1. Use `context.txn.last_group.last_itxn` to access the last submitted inner transaction of a specific type.
+2. Iterate over all inner transactions in the last group using `context.txn.last_group.itxn_groups[-1]`.
+3. Access a specific inner transaction group using `context.txn.last_group.get_itxn_group(index)`.
+
+These methods provide type validation and will raise an error if the requested transaction type doesn't match the actual type of the inner transaction.
+
+## References
+
+-   [API](../api.md) for more details on the test context manager and inner transactions related methods that perform implicit inner transaction type validation.
+-   [Examples](../examples.md) for more examples of smart contracts and associated tests that interact with inner transactions.
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

package/dist/resources/knowledge/taxonomy/puya:python:testing:examples:README.md

@@ -0,0 +1,56 @@
+# Algorand Python Testing examples
+
+This directory contains examples demonstrating how to use algorand-python-testing to test smart contracts written in Algorand Python.
+
+## Overview
+
+`algorand-python-testing` provides a powerful framework for unit testing Algorand smart contracts written in Algorand Python. It allows developers to emulate AVM behavior in a Python interpreter, making it easier to write and run tests for your Algorand applications.
+
+## Key Features
+
+1. **Test Environment Setup**: Use the `context` fixture to set up a test environment that emulates AVM behavior.
+2. **Arrange, Act, Assert Pattern**: Examples follow the 'arrange, act, assert' pattern for clear and structured tests.
+3. **Asset and Account Creation**: Easily create test assets and accounts using `context.any.asset` and `context.any.account`.
+4. **State Manipulation**: Test global and local state changes in your smart contracts.
+5. **ABI Method Testing**: Examples of how to test ABI methods in your smart contracts.
+
+## Quickstart
+
+To run the examples in a self-contained manner:
+
+1. Install [hatch](https://hatch.pypa.io/latest/)
+2. From the root of the repo, run:
+
+```bash
+hatch run examples:test examples/<example_directory>
+```
+
+Replace `<example_directory>` with the specific example you want to run (e.g., `auction`, `abi`, etc.).
+
+## Writing Tests
+
+When writing tests for your Algorand smart contracts:
+
+1. Use the `context` fixture to set up your test environment.
+2. Create test assets and accounts as needed using `context.any.asset` and `context.any.account`.
+3. Interact with your smart contract methods.
+4. Assert the expected outcomes, including state changes and transaction results.
+
+For detailed examples, refer to the individual test files in each example directory.
+
+## Contributing
+
+If you have additional examples or improvements, feel free to contribute by submitting a pull request.
+
+1. Follow the [contribution guidelines](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
+2. Create a new folder under `examples/` with your contract/signature and test files.
+3. If you are contributing a smart contract example make sure to name the file `contract.py`. For logic signatures, name it `signature.py`.
+4. For test files use `test_contract.py` or `test_signature.py` respectively.
+5. Use the default PR template when opening a PR, and describe what sort of example are you adding as well as which feature of `algorand-python-testing` it demonstrates.
+
+## Resources
+
+-   [Algorand Developer Documentation](https://developer.algorand.org/)
+-   [algorand-python](https://algorandfoundation.github.io/puya/)
+-   [algorand-python-testing](https://algorandfoundation.github.io/algorand-python-testing/)
+-   ['arrange, act, assert' patern](https://automationpanda.com/2020/07/07/arrange-act-assert-a-pattern-for-writing-good-tests/)

package/dist/resources/knowledge/taxonomy/puya:src:puya:ARCHITECTURE.md

@@ -0,0 +1,26 @@
+## Layers
+
+In top-down order:
+
+-   src/algopy-stubs/
+-   src/puya/
+    -   parse.py
+    -   awst/
+    -   awst_build/
+    -   ir/
+    -   mir/
+    -   teal/
+    -   ussemble/
+    -   compile.py
+
+Dependencies across layer boundaries should only be to something higher in the list.
+
+The data model flows from higher to lower levels like:
+
+    Python AST -> MyPy AST -> AWST -> IR -> MIR -> TEAL -> AVM bytecode
+
+## FAQ
+
+### There are too many things named "context"!?
+
+Yes

package/dist/resources/knowledge/taxonomy/puya:src:puyapy:_typeshed:README.md

@@ -0,0 +1,10 @@
+This is PuyaPy's custom typeshed, which is a curated subset of the official MyPy typeshed.
+It only includes the required stubs used by PuyaPy as this speeds up MyPy's parsing speed
+significantly.
+
+However this means certain python modules such as `enum` or `dataclasses` cannot be used in
+PuyaPy stubs unless this typeshed is updated.
+
+The contents of the typeshed are populated by the `scripts/vendor_mypy.py` script, which is used
+to vendor new versions of MyPy or to update the stubs included in this typeshed. So to add new
+stubs, update that script and rerun.

package/dist/resources/knowledge/taxonomy/puya:src:puyapy:_vendor:mypy:typeshed:stdlib:_typeshed:README.md

@@ -0,0 +1,34 @@
+# Utility types for typeshed
+
+This package and its submodules contains various common types used by
+typeshed. It can also be used by packages outside typeshed, but beware
+the API stability guarantees below.
+
+## Usage
+
+The `_typeshed` package and its types do not exist at runtime, but can be
+used freely in stubs (`.pyi`) files. To import the types from this package in
+implementation (`.py`) files, use the following construct:
+
+```python
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from _typeshed import ...
+```
+
+Types can then be used in annotations by either quoting them or
+using:
+
+```python
+from __future__ import annotations
+```
+
+## API Stability
+
+You can use this package and its submodules outside of typeshed, but we
+guarantee only limited API stability. Items marked as "stable" will not be
+removed or changed in an incompatible way for at least one year.
+Before making such a change, the "stable" moniker will be removed
+and we will mark the type in question as deprecated. No guarantees
+are made about unmarked types.

package/dist/resources/knowledge/taxonomy/puya:src:puyapy:awst_build:README.md

@@ -0,0 +1,13 @@
+## Architecture
+
+- no dependency on mypy past this point. We are insulated from either changes in mypy or changing to another parser
+- Validate as much as possible during conversion - most source information at this point & early validation means less error compounding causing confusion. 
+- This means fully normalised, and only what is required remains. Much easier to reason about this new ast when converting to ir
+- No python peculiarities eg a < b < c (which is the same as ((a < b) and (b < c)) _except_ that b is only evaluated once)
+  - e.g. a < func_with_side_effects() < c would be equivalent to (tmp = func_with_side_effects(); a < tmp and tmp < c)
+  - e.g., a and b and c *_returns_* the first one of (a, b, c) that is falsy or if all are truthy returns c, whilst only evaluating each of a, b, and c at most once (ie still short circuiting) 
+- Still high level though eg if else, not branch + go to 
+- All stubs fully resolved, ie no further dependence on “puyapy” component. This further insulates from python specifics. Maybe this ast can be target for other languages? Note: this includes any necessary ast code generation eg approval program for arc4
+- All types fully resolved & checked
+
+

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

@@ -0,0 +1,89 @@
+# Algorand Python framework - API for writing Algorand Python smart contracts
+
+## Installation
+
+The minimum supported Python version for writing Algorand Python smart contracts is 3.12.
+
+You can install the Algorand Python framework from PyPI into your project virtualenv:
+```shell
+pip install algorand-python
+```
+If you're using poetry for dependency and virutalenv management, you can add it that way with
+`poetry add algorand-python`.
+
+Once you have installed the Algorand Python framework, you can access the type definitions from the `algopy` module, e.g.
+```python
+from algopy import Contract
+```
+
+For more details on using this API and the puyapy compiler see https://algorandfoundation.github.io/puya/
+
+## Versioning
+
+The Algorand Python API follows [semver](https://semver.org/) principles, however since the compiler is very closely
+coupled with the stubs definition, it's worth noting the interplay.
+
+### Major
+An increase in the major version should only occur if existing contracts would fail to type-check
+after the update.
+
+Some examples of situations that might cause this:
+- Breaking changes to the signature of an existing function, such as a new parameter being added 
+  to an existing
+  method and no default value is provided.
+- Something has been renamed, or moved such that the import path has changed (excluding moving 
+  between private modules, indicated with a leading underscore).
+- Something has been removed.
+
+The first two examples would necessitate changes in the compiler itself as well, which should
+also be considered breaking changes, thus there would be a coinciding new major version of the 
+compiler.
+
+The third example may not necessitate a change to the compiler, although it probably would be 
+likely there is one to remove the supporting code, but either way, since it will also change
+the behaviour in terms of what version range of the stubs is supported, should also result in a
+new major version of the compiler.
+
+However, vice versa is not necessarily true: a new major version of the compiler may not require
+a new major version of the stubs. For example:
+- Any breaking change to the compiler that has no changes in the stubs.
+- The default value of a parameter has changed. This changes the meaning of existing code that
+  does not supply a default, thus requiring a major version bump of the compiler, but no 
+  existing contracts will fail to compile.
+
+### Minor
+When new functionality is added, the minor version should be bumped.
+
+Example situations:
+- A new high level API has been added.
+- A new parameter has been added to an existing method but a default value has been provided.
+- A new TEAL/AVM version has been released with new low-level op-codes that should be exposed.
+ 
+In each of these cases, there should be zero impact on whether existing contracts will compile
+or not. They all would also require a new compiler version to be released. Although the existing
+compiler version could continue to work with new stubs version, provided none of the new 
+functionality is used, for simplicity the compiler should be updated to require the new stubs 
+version as a minimum.
+
+### Patch
+When a bug in the stubs themselves is fixed, or a non-functional change is made (such as 
+changes to docstrings / documentation), the patch version should be bumped.
+
+Examples:
+- Docstrings added/removed/updated.
+- Type parameters that were incorrectly specified are fixed
+  ([concrete example](https://github.com/algorandfoundation/puya/issues/191)).
+- Adding something that was unintentionally omitted from the stubs, but is otherwise supported by 
+  the current compiler. 
+  Generally in these cases, the code would compile if a `# type: ignore[<error-code>]` was added 
+  ([concrete example](https://github.com/algorandfoundation/puya/issues/200)).
+
+In each of these cases, the new stubs should functional correctly when paired with the current
+release of the compiler.
+
+The second example is a slight break from semver principles, since this is not backwards 
+compatible, as existing contracts may fail to compile. However, those contracts should not have
+compiled in the first place. The minimum version of stubs supported by the compiler should be
+increased to this new patch release, however this will only take effect on the next release of the
+compiler itself. The current compiler release would detect the new stubs version as supported 
+though, and so users can update to that new version of the stubs once it is released.