@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,182 @@
+# Algorand Python Testing
+
+[![docs-repository](https://img.shields.io/badge/url-repository-74dfdc?logo=github&style=flat.svg)](https://github.com/algorandfoundation/algorand-python-testing/)
+[![learn-AlgoKit](https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand&mac=flat.svg)](https://developer.algorand.org/algokit/)
+[![github-stars](https://img.shields.io/github/stars/algorandfoundation/algorand-python-testing?color=74dfdc&logo=star&style=flat)](https://github.com/algorandfoundation/algorand-python-testing)
+[![visitor-badge](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgorand-python-testing&countColor=%2374dfdc&style=flat)](https://developer.algorand.org/algokit/)
+
+`algorand-python-testing` is a companion package to [Algorand Python](https://github.com/algorandfoundation/puya) that enables efficient unit testing of Algorand Python smart contracts in an offline environment. This package emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface.
+
+The `algorand-python-testing` package provides:
+
+-   A simple interface for fast and reliable unit testing
+-   An offline testing environment that simulates core AVM functionality
+-   A familiar Pythonic experience, compatible with testing frameworks like [pytest](https://docs.pytest.org/en/latest/), [unittest](https://docs.python.org/3/library/unittest.html), and [hypothesis](https://hypothesis.readthedocs.io/en/latest/)
+
+## Quick Start
+
+`algopy` is a prerequisite for `algorand-python-testing`, providing stubs and type annotations for Algorand Python syntax. It enhances code completion and type checking when writing smart contracts. Note that this code isn't directly executable in standard Python interpreters; it's compiled by `puya` into TEAL for Algorand Network deployment.
+
+Traditionally, testing Algorand smart contracts involved deployment on sandboxed networks and interacting with live instances. While robust, this approach can be inefficient and lacks versatility for testing Algorand Python code.
+
+Enter `algorand-python-testing`: it leverages Python's rich testing ecosystem for unit testing without network deployment. This enables rapid iteration and granular logic testing.
+
+> **NOTE**: While `algorand-python-testing` offers valuable unit testing capabilities, it's not a replacement for comprehensive testing. Use it alongside other test types, particularly those running against the actual Algorand Network, for thorough contract validation.
+
+### Prerequisites
+
+-   Python 3.12 or later
+-   [Algorand Python](https://github.com/algorandfoundation/puya)
+
+### Installation
+
+`algorand-python-testing` is distributed via [PyPI](https://pypi.org/project/algorand-python-testing/). Install the package using `pip`:
+
+```bash
+pip install algorand-python-testing
+```
+
+or using `poetry`:
+
+```bash
+poetry add algorand-python-testing
+```
+
+### Testing your first contract
+
+Let's write a simple contract and test it using the `algorand-python-testing` framework.
+
+#### Contract Definition
+
+```{testcode}
+import algopy
+from algopy import arc4
+
+class VotingContract(algopy.ARC4Contract):
+    def __init__(self) -> None:
+        self.topic = algopy.GlobalState(algopy.Bytes(b"default_topic"), key="topic", description="Voting topic")
+        self.votes = algopy.GlobalState(
+            algopy.UInt64(0),
+            key="votes",
+            description="Votes for the option",
+        )
+        self.voted = algopy.LocalState(algopy.UInt64, key="voted", description="Tracks if an account has voted")
+
+    @arc4.abimethod
+    def set_topic(self, topic: arc4.String) -> None:
+        self.topic.value = topic.bytes
+
+    @arc4.abimethod
+    def vote(self, pay: algopy.gtxn.PaymentTransaction) -> arc4.Bool:
+        assert algopy.op.Global.group_size == algopy.UInt64(2), "Expected 2 transactions"
+        assert pay.amount == algopy.UInt64(10_000), "Incorrect payment amount"
+        assert pay.sender == algopy.Txn.sender, "Payment sender must match transaction sender"
+
+        _value, exists = self.voted.maybe(algopy.Txn.sender)
+        if exists:
+            return arc4.Bool(False)  # Already voted
+        self.votes.value += algopy.UInt64(1)
+        self.voted[algopy.Txn.sender] = algopy.UInt64(1)
+        return arc4.Bool(True)
+
+    @arc4.abimethod(readonly=True)
+    def get_votes(self) -> arc4.UInt64:
+        return arc4.UInt64(self.votes.value)
+
+    def clear_state_program(self) -> bool:
+        return True
+```
+
+#### Test Definition
+
+```{testcode}
+from collections.abc import Generator
+import pytest
+from algopy_testing import AlgopyTestContext, algopy_testing_context
+from algopy import arc4
+
+# Create a test context
+with algopy_testing_context() as context:
+
+    # Initialize the contract
+    contract = VotingContract()
+
+    # Test vote function
+    voter = context.default_sender
+    payment = context.any.txn.payment(
+        sender=voter,
+        amount=algopy.UInt64(10_000),
+    )
+
+    result = contract.vote(payment)
+    print(f"Vote result: {result.native}")
+    print(f"Total votes: {contract.votes.value}")
+    print(f"Voter {voter} voted: {contract.voted[voter]}")
+
+    # Test set_topic function
+    new_topic = context.any.arc4.string(10)
+    contract.set_topic(new_topic)
+    print(f"New topic: {new_topic.native}")
+    print(f"Contract topic: {contract.topic.value}")
+
+    # Test get_votes function
+    contract.votes.value = algopy.UInt64(5)
+    votes = contract.get_votes()
+    print(f"Current votes: {votes.native}")
+```
+
+```{testoutput}
+:hide:
+
+Vote result: True
+Total votes: 1
+Voter ... voted: 1
+New topic: ...
+Contract topic: ...
+Current votes: 5
+```
+
+This example demonstrates key aspects of testing with `algorand-python-testing` for ARC4-based contracts:
+
+1. ARC4 Contract Features:
+
+    - Use of `algopy.ARC4Contract` as the base class for the contract.
+    - ABI methods defined using the `@arc4.abimethod` decorator.
+    - Use of ARC4-specific types like `arc4.String`, `arc4.Bool`, and `arc4.UInt64`.
+    - Readonly method annotation with `@arc4.abimethod(readonly=True)`.
+
+2. Testing ARC4 Contracts:
+
+    - Creation of an `ARC4Contract` instance within the test context.
+    - Use of `context.any.arc4` for generating ARC4-specific random test data.
+    - Direct invocation of ABI methods on the contract instance.
+
+3. Transaction Handling:
+
+    - Use of `context.any.txn` to create test transactions.
+    - Passing transaction objects as parameters to contract methods.
+
+4. State Verification:
+    - Checking global and local state changes after method execution.
+    - Verifying return values from ABI methods using ARC4-specific types.
+
+> **NOTE**: Thorough testing is crucial in smart contract development due to their immutable nature post-deployment. Comprehensive unit and integration tests ensure contract validity and reliability. Optimizing for efficiency can significantly improve user experience by reducing transaction fees and simplifying interactions. Investing in robust testing and optimization practices is crucial and offers many benefits in the long run.
+
+### Next steps
+
+To dig deeper into the capabilities of `algorand-python-testing`, continue with the following sections.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+hidden: true
+---
+
+testing-guide/index
+examples
+coverage
+faq
+api
+algopy
+```

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

@@ -0,0 +1,96 @@
+# ARC4 Types
+
+These types are available under the `algopy.arc4` namespace. Refer to the [ARC4 specification](https://arc.algorand.foundation/ARCs/arc-0004) for more details on the spec.
+
+```{hint}
+Test context manager provides _value generators_ for ARC4 types. To access their _value generators_, use `{context_instance}.any.arc4` property. See more examples below.
+```
+
+```{note}
+For all `algopy.arc4` types with and without respective _value generator_, instantiation can be performed directly. If you have a suggestion for a new _value generator_ implementation, please open an issue in the [`algorand-python-testing`](https://github.com/algorandfoundation/algorand-python-testing) repository or contribute by following the [contribution guide](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
+```
+
+```{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__()
+```
+
+## Unsigned Integers
+
+```{testcode}
+from algopy import arc4
+
+# Integer types
+uint8_value = arc4.UInt8(255)
+uint16_value = arc4.UInt16(65535)
+uint32_value = arc4.UInt32(4294967295)
+uint64_value = arc4.UInt64(18446744073709551615)
+
+... # instantiate test context
+# Generate a random unsigned arc4 integer with default range
+uint8 = context.any.arc4.uint8()
+uint16 = context.any.arc4.uint16()
+uint32 = context.any.arc4.uint32()
+uint64 = context.any.arc4.uint64()
+biguint128 = context.any.arc4.biguint128()
+biguint256 = context.any.arc4.biguint256()
+biguint512 = context.any.arc4.biguint512()
+
+# Generate a random unsigned arc4 integer with specified range
+uint8_custom = context.any.arc4.uint8(min_value=10, max_value=100)
+uint16_custom = context.any.arc4.uint16(min_value=1000, max_value=5000)
+uint32_custom = context.any.arc4.uint32(min_value=100000, max_value=1000000)
+uint64_custom = context.any.arc4.uint64(min_value=1000000000, max_value=10000000000)
+biguint128_custom = context.any.arc4.biguint128(min_value=1000000000000000, max_value=10000000000000000)
+biguint256_custom = context.any.arc4.biguint256(min_value=1000000000000000000000000, max_value=10000000000000000000000000)
+biguint512_custom = context.any.arc4.biguint512(min_value=10000000000000000000000000000000000, max_value=10000000000000000000000000000000000)
+```
+
+## Address
+
+```{testcode}
+from algopy import arc4
+
+# Address type
+address_value = arc4.Address("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ")
+
+# Generate a random address
+random_address = context.any.arc4.address()
+
+# Access native underlaying type
+native = random_address.native
+```
+
+## Dynamic Bytes
+
+```{testcode}
+from algopy import arc4
+
+# Dynamic byte string
+bytes_value = arc4.DynamicBytes(b"Hello, Algorand!")
+
+# Generate random dynamic bytes
+random_dynamic_bytes = context.any.arc4.dynamic_bytes(n=123) # n is the number of bits in the arc4 dynamic bytes
+```
+
+## String
+
+```{testcode}
+from algopy import arc4
+
+# UTF-8 encoded string
+string_value = arc4.String("Hello, Algorand!")
+
+# Generate random string
+random_string = context.any.arc4.string(n=12) # n is the number of bits in the arc4 string
+```
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

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

@@ -0,0 +1,223 @@
+# AVM Types
+
+These types are available directly under the `algopy` namespace. They represent the basic AVM primitive types and can be instantiated directly or via _value generators_:
+
+```{note}
+For 'primitive `algopy` types such as `Account`, `Application`, `Asset`, `UInt64`, `BigUint`, `Bytes`, `Sting` with and without respective _value generator_, instantiation can be performed directly. If you have a suggestion for a new _value generator_ implementation, please open an issue in the [`algorand-python-testing`](https://github.com/algorandfoundation/algorand-python-testing) repository or contribute by following the [contribution guide](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
+```
+
+```{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__()
+```
+
+## UInt64
+
+```{testcode}
+# Direct instantiation
+uint64_value = algopy.UInt64(100)
+
+# Instantiate test context
+...
+
+# Generate a random UInt64 value
+random_uint64 = context.any.uint64()
+
+# Specify a range
+random_uint64 = context.any.uint64(min_value=1000, max_value=9999)
+```
+
+## Bytes
+
+```{testcode}
+# Direct instantiation
+bytes_value = algopy.Bytes(b"Hello, Algorand!")
+
+
+# Instantiate test context
+...
+
+# Generate random byte sequences
+random_bytes = context.any.bytes()
+
+# Specify the length
+random_bytes = context.any.bytes(length=32)
+```
+
+## String
+
+```{testcode}
+# Direct instantiation
+string_value = algopy.String("Hello, Algorand!")
+
+# Generate random strings
+random_string = context.any.string()
+
+# Specify the length
+random_string = context.any.string(length=16)
+```
+
+## BigUInt
+
+```{testcode}
+# Direct instantiation
+biguint_value = algopy.BigUInt(100)
+
+# Generate a random BigUInt value
+random_biguint = context.any.biguint()
+```
+
+## Asset
+
+```{testcode}
+# Direct instantiation
+asset = algopy.Asset(asset_id=1001)
+
+# Instantiate test context
+...
+
+# Generate a random asset
+random_asset = context.any.asset(
+    creator=...,  # Optional: Creator account
+    name=...,  # Optional: Asset name
+    unit_name=...,  # Optional: Unit name
+    total=...,  # Optional: Total supply
+    decimals=...,  # Optional: Number of decimals
+    default_frozen=...,  # Optional: Default frozen state
+    url=...,  # Optional: Asset URL
+    metadata_hash=...,  # Optional: Metadata hash
+    manager=...,  # Optional: Manager address
+    reserve=...,  # Optional: Reserve address
+    freeze=...,  # Optional: Freeze address
+    clawback=...  # Optional: Clawback address
+)
+
+# Get an asset by ID
+asset = context.ledger.get_asset(asset_id=random_asset.id)
+
+# Update an asset
+context.ledger.update_asset(
+    random_asset,
+    name=...,  # Optional: New asset name
+    total=...,  # Optional: New total supply
+    decimals=...,  # Optional: Number of decimals
+    default_frozen=...,  # Optional: Default frozen state
+    url=...,  # Optional: New asset URL
+    metadata_hash=...,  # Optional: New metadata hash
+    manager=...,  # Optional: New manager address
+    reserve=...,  # Optional: New reserve address
+    freeze=...,  # Optional: New freeze address
+    clawback=...  # Optional: New clawback address
+)
+```
+
+## Account
+
+```{testcode}
+# Direct instantiation
+raw_address = 'PUYAGEGVCOEBP57LUKPNOCSMRWHZJSU4S62RGC2AONDUEIHC6P7FOPJQ4I'
+account = algopy.Account(raw_address) # zero address by default
+
+# Instantiate test context
+...
+
+# Generate a random account
+random_account = context.any.account(
+    address=str(raw_address),  # Optional: Specify a custom address, defaults to a random address
+    opted_asset_balances={},  # Optional: Specify opted asset balances as dict of assets to balance
+    opted_apps=[],  # Optional: Specify opted apps as sequence of algopy.Application objects
+    balance=...,  # Optional: Specify an initial balance
+    min_balance=...,  # Optional: Specify a minimum balance
+    auth_address=...,  # Optional: Specify an auth address
+    total_assets=...,  # Optional: Specify the total number of assets
+    total_assets_created=...,  # Optional: Specify the total number of created assets
+    total_apps_created=...,  # Optional: Specify the total number of created applications
+    total_apps_opted_in=...,  # Optional: Specify the total number of applications opted into
+    total_extra_app_pages=...,  # Optional: Specify the total number of extra
+)
+
+# Generate a random account that is opted into a specific asset
+mock_asset = context.any.asset()
+mock_account = context.any.account(
+    opted_asset_balances={mock_asset: 123}
+)
+
+# Get an account by address
+account = context.ledger.get_account(str(mock_account))
+
+# Update an account
+context.ledger.update_account(
+    mock_account,
+    balance=...,  # Optional: New balance
+    min_balance=...,  # Optional: New minimum balance
+    auth_address=context.any.account(),  # Optional: New auth address
+    total_assets=...,  # Optional: New total number of assets
+    total_created_assets=...,  # Optional: New total number of created assets
+    total_apps_created=...,  # Optional: New total number of created applications
+    total_apps_opted_in=...,  # Optional: New total number of applications opted into
+    total_extra_app_pages=...,  # Optional: New total number of extra application pages
+    rewards=...,  # Optional: New rewards
+    status=...  # Optional: New account status
+)
+
+# Check if an account is opted into a specific asset
+opted_in = account.is_opted_in(mock_asset)
+```
+
+## Application
+
+```{testcode}
+# Direct instantiation
+application = algopy.Application()
+
+# Instantiate test context
+...
+
+# Generate a random application
+random_app = context.any.application(
+    approval_program=algopy.Bytes(b''),  # Optional: Specify a custom approval program
+    clear_state_program=algopy.Bytes(b''),  # Optional: Specify a custom clear state program
+    global_num_uint=algopy.UInt64(1),  # Optional: Number of global uint values
+    global_num_bytes=algopy.UInt64(1),  # Optional: Number of global byte values
+    local_num_uint=algopy.UInt64(1),  # Optional: Number of local uint values
+    local_num_bytes=algopy.UInt64(1),  # Optional: Number of local byte values
+    extra_program_pages=algopy.UInt64(1),  # Optional: Number of extra program pages
+    creator=context.default_sender  # Optional: Specify the creator account
+)
+
+# Get an application by ID
+app = context.ledger.get_app(app_id=random_app.id)
+
+# Update an application
+context.ledger.update_app(
+    random_app,
+    approval_program=...,  # Optional: New approval program
+    clear_state_program=...,  # Optional: New clear state program
+    global_num_uint=...,  # Optional: New number of global uint values
+    global_num_bytes=...,  # Optional: New number of global byte values
+    local_num_uint=...,  # Optional: New number of local uint values
+    local_num_bytes=...,  # Optional: New number of local byte values
+    extra_program_pages=...,  # Optional: New number of extra program pages
+    creator=...  # Optional: New creator account
+)
+
+# Patch logs for an application. When accessing via transactions or inner transaction related opcodes, will return the patched logs unless new logs where added into the transaction during execution.
+test_app = context.any.application(logs=b"log entry" or [b"log entry 1", b"log entry 2"])
+
+# Get app associated with the active contract
+class MyContract(algopy.ARC4Contract):
+    ...
+
+contract = MyContract()
+active_app = context.ledger.get_app(contract)
+```
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

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

@@ -0,0 +1,58 @@
+# Concepts
+
+The following sections provide an overview of key concepts and features in the Algorand Python Testing framework.
+
+## Test Context
+
+The main abstraction for interacting with the testing framework is the [`AlgopyTestContext`](../api-context.md#algopy_testing.AlgopyTestContext). It creates an emulated Algorand environment that closely mimics AVM behavior relevant to unit testing the contracts and provides a Pythonic interface for interacting with the emulated environment.
+
+```python
+from algopy_testing import algopy_testing_context
+
+def test_my_contract():
+    # Recommended way to instantiate the test context
+    with algopy_testing_context() as ctx:
+        # Your test code here
+        pass
+    # ctx is automatically reset after the test code is executed
+```
+
+The context manager interface exposes three main properties:
+
+1. `ledger`: An instance of `LedgerContext` for interacting with and querying the emulated Algorand ledger state.
+2. `txn`: An instance of `TransactionContext` for creating and managing transaction groups, submitting transactions, and accessing transaction results.
+3. `any`: An instance of `AlgopyValueGenerator` for generating randomized test data.
+
+For detailed method signatures, parameters, and return types, refer to the following API sections:
+- [`algopy_testing.LedgerContext`](../api.md)
+- [`algopy_testing.TransactionContext`](../api.md)
+- [`algopy_testing.AVMValueGenerator`, `algopy_testing.TxnValueGenerator`, `algopy_testing.ARC4ValueGenerator`](../api.md)
+
+The `any` property provides access to different value generators:
+
+- `AVMValueGenerator`: Base abstractions for AVM types. All methods are available directly on the instance returned from `any`.
+- `TxnValueGenerator`: Accessible via `any.txn`, for transaction-related data.
+- `ARC4ValueGenerator`: Accessible via `any.arc4`, for ARC4 type data.
+
+These generators allow creation of constrained random values for various AVM entities (accounts, assets, applications, etc.) when specific values are not required.
+
+```{hint}
+Value generators are powerful tools for generating test data for specified AVM types. They allow further constraints on random value generation via arguments, making it easier to generate test data when exact values are not necessary.
+
+When used with the 'Arrange, Act, Assert' pattern, value generators can be especially useful in setting up clear and concise test data in arrange steps.
+
+They can also serve as a base building block that can be integrated/reused with popular Python property-based testing frameworks like [`hypothesis`](https://hypothesis.readthedocs.io/en/latest/).
+```
+
+## Types of `algopy` stub implementations
+
+As explained in the [introduction](index.md), `algorand-python-testing` _injects_ test implementations for stubs available in the `algorand-python` package. However, not all of the stubs are implemented in the same manner:
+
+1. **Native**: Fully matches AVM computation in Python. For example, `algopy.op.sha256` and other cryptographic operations behave identically in AVM and unit tests. This implies that the majority of opcodes that are 'pure' functions in AVM also have a native Python implementation provided by this package. These abstractions and opcodes can be used within and outside of the testing context.
+
+2. **Emulated**: Uses `AlgopyTestContext` to mimic AVM behavior. For example, `Box.put` on an `algopy.Box` within a test context stores data in the test manager, not the real Algorand network, but provides the same interface.
+
+3. **Mockable**: Not implemented, but can be mocked or patched. For example, `algopy.abi_call` can be mocked to return specific values or behaviors; otherwise, it raises a `NotImplementedError`. This category covers cases where native or emulated implementation in a unit test context is impractical or overly complex.
+
+For a full list of all public `algopy` types and their corresponding implementation category, refer to the [Coverage](coverage.md) section.
+```