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.

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.

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.

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.

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.

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 page, and the API documentation.

ctx_manager.__exit__(None, None, None)