openclaw-algorand-plugin 0.5.0

package/skills/algorand-python/references/build-smart-contracts-storage.md

@@ -0,0 +1,452 @@
+# Algorand Python Storage Patterns
+
+Store data on-chain using GlobalState, LocalState, and Box storage in Algorand Python smart contracts.
+
+## When to use this reference
+
+Use this reference when:
+
+- Choosing between storage types for your contract
+- Implementing global or local state
+- Working with Box storage for larger data
+- Understanding MBR (Minimum Balance Requirement) costs
+
+## Storage Types Overview
+
+| Storage | Scope | Who Pays MBR | Max Size | Use Case |
+|---------|-------|--------------|----------|----------|
+| `GlobalState` | App-wide | App creator | 64 keys, 8KB total | Shared app data |
+| `LocalState` | Per-user | User (on opt-in) | 16 keys, 2KB total | Per-user data with opt-in |
+| `Box` | App-wide | App account | 32KB per box | Large single values |
+| `BoxMap` | Per-key | App account | 32KB per box | Per-user data without opt-in |
+| `BoxRef` | App-wide | App account | 32KB | Raw binary data, manual sizing |
+
+## GlobalState
+
+Store app-wide data accessible by all users. Two approaches available:
+
+### Simple Assignment (Recommended for Basic Use)
+
+```python
+from algopy import ARC4Contract, UInt64, Bytes, arc4
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        # Simple assignment - uses variable name as key
+        self.counter = UInt64(0)
+        self.name = Bytes(b"MyApp")
+        self.active = True
+
+    @arc4.abimethod
+    def increment(self) -> None:
+        self.counter += 1
+```
+
+### GlobalState Wrapper (For Advanced Control)
+
+```python
+from algopy import ARC4Contract, GlobalState, UInt64, Bytes, arc4
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        # With custom key and description (for ARC-32/56 app spec)
+        self.counter = GlobalState(
+            UInt64(0),
+            key="cnt",
+            description="Transaction counter"
+        )
+        # No default value - must set before reading
+        self.owner = GlobalState(Bytes)
+
+    @arc4.abimethod
+    def increment(self) -> UInt64:
+        self.counter.value += 1
+        return self.counter.value
+
+    @arc4.abimethod
+    def get_counter_safe(self) -> UInt64:
+        # Check if value exists
+        if self.counter:
+            return self.counter.value
+        return UInt64(0)
+
+    @arc4.abimethod
+    def get_with_default(self) -> Bytes:
+        # Get with fallback default
+        return self.owner.get(default=Bytes(b"unset"))
+
+    @arc4.abimethod
+    def get_maybe(self) -> tuple[UInt64, bool]:
+        # Returns (value, exists)
+        return self.counter.maybe()
+```
+
+### GlobalState Methods
+
+| Method | Description |
+|--------|-------------|
+| `.value` | Get/set the value (errors if not set) |
+| `.get(default)` | Get value or return default |
+| `.maybe()` | Returns `(value, exists)` tuple |
+| `bool(state)` | `True` if value is set |
+| `.key` | Access raw storage key |
+
+## LocalState
+
+Store per-user data. Requires user to opt-in to the application first.
+
+```python
+from algopy import ARC4Contract, LocalState, UInt64, Bytes, Account, Txn, arc4
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        self.user_balance = LocalState(UInt64, key="bal")
+        self.user_name = LocalState(Bytes)
+
+    @arc4.abimethod(allow_actions=["OptIn"])
+    def opt_in(self) -> None:
+        # Initialize local state on opt-in
+        self.user_balance[Txn.sender] = UInt64(0)
+
+    @arc4.abimethod
+    def deposit(self, amount: UInt64) -> None:
+        self.user_balance[Txn.sender] += amount
+
+    @arc4.abimethod
+    def get_balance(self, account: Account) -> UInt64:
+        # Direct access (fails if not opted in)
+        return self.user_balance[account]
+
+    @arc4.abimethod
+    def get_balance_safe(self, account: Account) -> UInt64:
+        # Check if account has local state
+        if account in self.user_balance:
+            return self.user_balance[account]
+        return UInt64(0)
+
+    @arc4.abimethod
+    def get_balance_default(self, account: Account) -> UInt64:
+        # Get with default
+        return self.user_balance.get(account, default=UInt64(0))
+
+    @arc4.abimethod
+    def get_balance_maybe(self, account: Account) -> tuple[UInt64, bool]:
+        # Returns (value, exists)
+        return self.user_balance.maybe(account)
+
+    @arc4.abimethod
+    def clear_balance(self, account: Account) -> None:
+        # Delete local state entry
+        del self.user_balance[account]
+```
+
+### LocalState Methods
+
+| Method | Description |
+|--------|-------------|
+| `state[account]` | Get/set value for account |
+| `state.get(account, default)` | Get value or return default |
+| `state.maybe(account)` | Returns `(value, exists)` tuple |
+| `account in state` | `True` if account has value |
+| `del state[account]` | Delete value for account |
+| `.key` | Access raw storage key |
+
+## Box Storage
+
+Store larger data without user opt-in. App account pays MBR.
+
+### Box (Single Value)
+
+```python
+from algopy import ARC4Contract, Box, UInt64, Bytes, arc4, String
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        # Box with compile-time constant key
+        self.config = Box(UInt64, key=b"config")
+        self.data = Box(Bytes, key=b"data")
+
+    @arc4.abimethod
+    def set_config(self, value: UInt64) -> None:
+        # Automatically creates box if needed
+        self.config.value = value
+
+    @arc4.abimethod
+    def get_config(self) -> UInt64:
+        # Check existence first
+        if self.config:
+            return self.config.value
+        return UInt64(0)
+
+    @arc4.abimethod
+    def get_config_maybe(self) -> tuple[UInt64, bool]:
+        return self.config.maybe()
+
+    @arc4.abimethod
+    def delete_config(self) -> None:
+        # Delete box to reclaim MBR
+        del self.config.value
+```
+
+### Box with Dynamic Key
+
+```python
+from algopy import ARC4Contract, Box, UInt64, String, arc4
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def create_named_box(self, name: String) -> None:
+        # Create box with dynamic key inside method
+        box = Box(UInt64, key=name.bytes)
+        box.value = UInt64(100)
+
+    @arc4.abimethod
+    def read_named_box(self, name: String) -> UInt64:
+        box = Box(UInt64, key=name.bytes)
+        if box:
+            return box.value
+        return UInt64(0)
+```
+
+### Box Methods
+
+| Method | Description |
+|--------|-------------|
+| `.value` | Get/set the box value |
+| `.get(default=...)` | Get value or return default |
+| `.maybe()` | Returns `(value, exists)` tuple |
+| `bool(box)` | `True` if box exists |
+| `del box.value` | Delete the box |
+| `.create(size=...)` | Create box with specific size |
+| `.length` | Get box length in bytes |
+| `.extract(start, length)` | Extract bytes from box |
+| `.replace(start, value)` | Replace bytes in box |
+| `.splice(start, stop, value)` | Splice bytes in box |
+
+### BoxMap (Per-Key Storage)
+
+Best for per-user data when you don't want to require opt-in.
+
+```python
+from algopy import ARC4Contract, BoxMap, UInt64, String, Account, Txn, arc4
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        # BoxMap with key type and value type
+        self.balances = BoxMap(Account, UInt64, key_prefix="bal_")
+        self.names = BoxMap(UInt64, String, key_prefix="name_")
+
+    @arc4.abimethod
+    def deposit(self, amount: UInt64) -> None:
+        sender = Txn.sender
+        if sender in self.balances:
+            self.balances[sender] += amount
+        else:
+            self.balances[sender] = amount
+
+    @arc4.abimethod
+    def get_balance(self, account: Account) -> UInt64:
+        if account in self.balances:
+            return self.balances[account]
+        return UInt64(0)
+
+    @arc4.abimethod
+    def get_balance_default(self, account: Account) -> UInt64:
+        return self.balances.get(account, default=UInt64(0))
+
+    @arc4.abimethod
+    def get_balance_maybe(self, account: Account) -> tuple[UInt64, bool]:
+        return self.balances.maybe(account)
+
+    @arc4.abimethod
+    def withdraw_all(self) -> UInt64:
+        sender = Txn.sender
+        balance = self.balances.get(sender, default=UInt64(0))
+        if balance > 0:
+            del self.balances[sender]  # Delete to reclaim MBR
+        return balance
+```
+
+### BoxMap Methods
+
+| Method | Description |
+|--------|-------------|
+| `map[key]` | Get/set value for key |
+| `map.get(key, default=...)` | Get value or return default |
+| `map.maybe(key)` | Returns `(value, exists)` tuple |
+| `key in map` | `True` if key exists |
+| `del map[key]` | Delete the box |
+| `.length(key)` | Get box length for key |
+| `.key_prefix` | Access raw key prefix |
+| `.box(key)` | Get Box proxy for key |
+
+### BoxRef (Raw Binary Data)
+
+For manual control over large binary data.
+
+```python
+from algopy import ARC4Contract, BoxRef, Bytes, UInt64, Txn, Global, arc4
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        self.blob = BoxRef(key=b"blob")
+
+    @arc4.abimethod
+    def create_blob(self, size: UInt64) -> bool:
+        # Manually create box with specific size
+        return self.blob.create(size=size)
+
+    @arc4.abimethod
+    def write_to_blob(self, offset: UInt64, data: Bytes) -> None:
+        self.blob.replace(offset, data)
+
+    @arc4.abimethod
+    def read_from_blob(self, offset: UInt64, length: UInt64) -> Bytes:
+        return self.blob.extract(offset, length)
+
+    @arc4.abimethod
+    def delete_blob(self) -> bool:
+        return self.blob.delete()
+```
+
+## Minimum Balance Requirement (MBR)
+
+### MBR Formulas
+
+**Global State:**
+```
+100,000 + (28,500 * NumUint) + (50,000 * NumByteSlice) microAlgos
+```
+
+**Local State (per opt-in):**
+```
+100,000 + (28,500 * NumUint) + (50,000 * NumByteSlice) microAlgos
+```
+
+**Box Storage:**
+```
+2,500 + (400 * (key_length + value_length)) microAlgos per box
+```
+
+### Box MBR Examples
+
+| Box Name | Size | MBR Cost |
+|----------|------|----------|
+| "a" (1 byte) | 100 bytes | 2,500 + 400×101 = 42,900 µAlgo |
+| "user" (4 bytes) | 1024 bytes | 2,500 + 400×1028 = 413,700 µAlgo |
+| 32-byte key | 8 bytes | 2,500 + 400×40 = 18,500 µAlgo |
+
+### Funding App Account for Boxes (CRITICAL)
+
+The app account must be funded BEFORE creating boxes.
+
+```python
+# In your deploy script or test setup:
+from algokit_utils import AlgorandClient
+
+algorand = AlgorandClient.from_environment()
+deployer = algorand.account.from_environment("DEPLOYER")
+
+# Deploy the contract
+factory = algorand.client.get_typed_app_factory(MyAppFactory)
+result = factory.deploy()
+
+# Fund app account for box MBR
+if result.operation_performed in ["create", "replace"]:
+    algorand.send.payment(
+        sender=deployer.address,
+        receiver=result.app_client.app_address,
+        amount=1_000_000  # 1 Algo for box storage
+    )
+```
+
+### Calculating MBR in Contract
+
+```python
+from algopy import ARC4Contract, UInt64, arc4
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def calculate_box_mbr(self, key_length: UInt64, value_length: UInt64) -> UInt64:
+        return UInt64(2500) + (key_length + value_length) * UInt64(400)
+```
+
+## Choosing Storage Type
+
+| Scenario | Recommended | Reason |
+|----------|-------------|--------|
+| App configuration | `GlobalState` | Simple, always available |
+| Per-user data, user pays | `LocalState` | User covers MBR on opt-in |
+| Per-user data, app pays | `BoxMap` | No opt-in needed |
+| Large single value | `Box` | Up to 32KB per box |
+| Large binary blob | `BoxRef` | Manual size control |
+| Dynamic key-value store | `BoxMap` | Flexible key types |
+
+## Common Mistakes
+
+### Forgetting to Fund App Account for Boxes
+
+```python
+# INCORRECT - Box creation fails if app not funded
+@arc4.abimethod
+def create_user(self, account: Account) -> None:
+    self.users[account] = UInt64(0)  # Fails: insufficient MBR
+
+# CORRECT - Fund app account before creating boxes
+# (Done externally via payment transaction)
+```
+
+### Not Checking Box Existence
+
+```python
+# INCORRECT - Fails if box doesn't exist
+@arc4.abimethod
+def get_value(self) -> UInt64:
+    return self.my_box.value  # Error if not set
+
+# CORRECT - Check first or use get/maybe
+@arc4.abimethod
+def get_value_safe(self) -> UInt64:
+    if self.my_box:
+        return self.my_box.value
+    return UInt64(0)
+
+# OR
+@arc4.abimethod
+def get_value_default(self) -> UInt64:
+    return self.my_box.get(default=UInt64(0))
+```
+
+### Not Deleting Boxes to Reclaim MBR
+
+```python
+# CORRECT - Delete boxes when no longer needed
+@arc4.abimethod
+def cleanup_user(self, account: Account) -> None:
+    if account in self.users:
+        del self.users[account]  # Reclaims MBR
+```
+
+### Using LocalState Without Opt-in Check
+
+```python
+# INCORRECT - Fails if user not opted in
+@arc4.abimethod
+def get_user_data(self, account: Account) -> UInt64:
+    return self.user_data[account]  # Error if not opted in
+
+# CORRECT - Check opt-in status
+@arc4.abimethod
+def get_user_data_safe(self, account: Account) -> UInt64:
+    if account in self.user_data:
+        return self.user_data[account]
+    return UInt64(0)
+```
+
+## References
+
+- [Algorand Python Storage Documentation](https://dev.algorand.co/algokit/languages/python/lg-storage/)
+- [Box Storage Concepts](https://dev.algorand.co/concepts/smart-contracts/storage/box/)
+- [Global Storage Concepts](https://dev.algorand.co/concepts/smart-contracts/storage/global/)
+- [Local Storage Concepts](https://dev.algorand.co/concepts/smart-contracts/storage/local/)
+- [Protocol Parameters (MBR)](https://dev.algorand.co/concepts/protocol/protocol-parameters/)