AVM Boxes Ops in Pyteal

pyteal/__init__.pyi

@@ -43,6 +43,13 @@ __all__ = [
     "BitwiseNot",
     "BitwiseOr",
     "BitwiseXor",
+    "BoxCreate",
+    "BoxDelete",
+    "BoxExtract",
+    "BoxGet",
+    "BoxLen",
+    "BoxPut",
+    "BoxReplace",
     "Break",
     "Btoi",
     "Bytes",

pyteal/ast/__init__.py

@@ -27,6 +27,16 @@
 from pyteal.ast.app import App, AppField, OnComplete, AppParam
 from pyteal.ast.asset import AssetHolding, AssetParam
 from pyteal.ast.acct import AccountParam
+from pyteal.ast.box import (
+    BoxCreate,
+    BoxDelete,
+    BoxExtract,
+    BoxReplace,
+    BoxLen,
+    BoxGet,
+    BoxPut,
+)
+
 
 # inner txns
 from pyteal.ast.itxn import InnerTxnBuilder, InnerTxn, InnerTxnAction
@@ -146,6 +156,13 @@
     "LeafExpr",
     "Addr",
     "Bytes",
+    "BoxCreate",
+    "BoxDelete",
+    "BoxReplace",
+    "BoxExtract",
+    "BoxLen",
+    "BoxGet",
+    "BoxPut",
     "Int",
     "EnumInt",
     "MethodSignature",

pyteal/ast/app.py

@@ -1,5 +1,14 @@
 from typing import TYPE_CHECKING
 from enum import Enum
+from pyteal.ast.box import (
+    BoxCreate,
+    BoxDelete,
+    BoxExtract,
+    BoxReplace,
+    BoxLen,
+    BoxGet,
+    BoxPut,
+)
 
 from pyteal.types import TealType, require_type
 from pyteal.ir import TealOp, Op, TealBlock
@@ -181,7 +190,7 @@ def globalPut(cls, key: Expr, value: Expr) -> "App":
 
         Args:
             key: The key to write in the global application state. Must evaluate to bytes.
-            value: THe value to write in the global application state. Can evaluate to any type.
+            value: The value to write in the global application state. Can evaluate to any type.
         """
         require_type(key, TealType.bytes)
         require_type(value, TealType.anytype)
@@ -211,6 +220,82 @@ def globalDel(cls, key: Expr) -> "App":
         require_type(key, TealType.bytes)
         return cls(AppField.globalDel, [key])
 
+    @classmethod
+    def box_create(cls, name: Expr, size: Expr) -> BoxCreate:
+        """
+        Create a box with a given name and size.
+
+        Args:
+            name: The key used to reference this box. Must evaluate to a bytes.
+            size: The number of bytes to reserve for this box. Must evaluate to a uint64.
+        """
+        return BoxCreate(name, size)
+
+    @classmethod
+    def box_delete(cls, name: Expr) -> BoxDelete:
+        """
+        Deletes a box given it's name.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+        """
+        return BoxDelete(name)
+
+    @classmethod
+    def box_extract(cls, name: Expr, start: Expr, length: Expr) -> BoxExtract:
+        """
+        Extracts bytes in a box given its name, start index and stop index.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            start: The byte index into the box to start reading. Must evaluate to uint64
+            length: The byte length into the box from start to stop reading. Must evaluate to uint64
+        """
+        return BoxExtract(name, start, length)
+
+    @classmethod
+    def box_replace(cls, name: Expr, start: Expr, value: Expr) -> BoxReplace:
+        """
+        Replaces bytes in a box given its name, start index, and value.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            start: The byte index into the box to start writing. Must evaluate to uint64
+            value: The value to start writing at start index. Must evaluate to bytes
+        """
+        return BoxReplace(name, start, value)
+
+    @classmethod
+    def box_length(cls, name: Expr) -> MaybeValue:
+        """
+        Get the byte length of the box specified by its name.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+        """
+        return BoxLen(name)
+
+    @classmethod
+    def box_get(cls, name: Expr) -> MaybeValue:
+        """
+        Get the full contents of a box given its name.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+        """
+        return BoxGet(name)
+
+    @classmethod
+    def box_put(cls, name: Expr, value: Expr) -> BoxPut:
+        """
+        Write all contents to a box given its name.
+
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            value: The value to write to the box. Must evaluate to bytes
+        """
+        return BoxPut(name, value)
+
 
 App.__module__ = "pyteal"
 

pyteal/ast/box.py

@@ -0,0 +1,226 @@
+from typing import TYPE_CHECKING
+from pyteal.ast.maybe import MaybeValue
+from pyteal.errors import TealInputError
+
+from pyteal.types import TealType, require_type
+from pyteal.ir import TealOp, Op, TealBlock
+from pyteal.ast.expr import Expr
+
+if TYPE_CHECKING:
+    from pyteal.compiler import CompileOptions
+
+
+class BoxCreate(Expr):
+    """Create a box with a given name and size."""
+
+    def __init__(self, name: Expr, size: Expr) -> None:
+        """
+        Args:
+            name: The key used to reference this box. Must evaluate to a bytes.
+            size: The number of bytes to reserve for this box. Must evaluate to a uint64.
+        """
+
+        super().__init__()
+        require_type(name, TealType.bytes)
+        require_type(size, TealType.uint64)
+        self.name = name
+        self.size = size
+
+    def __teal__(self, options: "CompileOptions"):
+        if options.version < Op.box_create.min_version:
+            raise TealInputError(
+                f"BoxCreate not available on teal version {options.version} (first available {Op.box_create.min_version})"
+            )
+
+        return TealBlock.FromOp(
+            options, TealOp(self, Op.box_create), self.size, self.name
+        )
+
+    def __str__(self):
+        return f"(box_create {self.name} {self.size})"
+
+    def type_of(self):
+        return TealType.none
+
+    def has_return(self):
+        return False
+
+
+BoxCreate.__module__ = "pyteal"
+
+
+class BoxDelete(Expr):
+    """Deletes a box given it's name"""
+
+    def __init__(self, name: Expr) -> None:
+        """
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+        """
+        super().__init__()
+        require_type(name, TealType.bytes)
+        self.name = name
+
+    def __teal__(self, options: "CompileOptions"):
+        if options.version < Op.box_del.min_version:
+            raise TealInputError(
+                f"BoxDelete not available on teal version {options.version} (first available {Op.box_del.min_version})"
+            )
+
+        return TealBlock.FromOp(options, TealOp(self, Op.box_del), self.name)
+
+    def __str__(self):
+        return f"(box_del {self.name})"
+
+    def type_of(self):
+        return TealType.none
+
+    def has_return(self):
+        return False
+
+
+BoxDelete.__module__ = "pyteal"
+
+
+class BoxReplace(Expr):
+    """Replaces bytes in a box given its name, start index, and value"""
+
+    def __init__(self, name: Expr, start: Expr, value: Expr) -> None:
+        """
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            start: The byte index into the box to start writing. Must evaluate to uint64
+            value: The value to start writing at start index. Must evaluate to bytes
+        """
+        super().__init__()
+        require_type(name, TealType.bytes)
+        require_type(start, TealType.uint64)
+        require_type(value, TealType.bytes)
+        self.name = name
+        self.start = start
+        self.value = value
+
+    def __teal__(self, options: "CompileOptions"):
+        if options.version < Op.box_replace.min_version:
+            raise TealInputError(
+                f"BoxReplace not available on teal version {options.version} (first available {Op.box_del.min_version})"
+            )
+
+        return TealBlock.FromOp(
+            options, TealOp(self, Op.box_replace), self.name, self.start, self.value
+        )
+
+    def __str__(self):
+        return f"(box_replace {self.name} {self.start} {self.value})"
+
+    def type_of(self):
+        return TealType.none
+
+    def has_return(self):
+        return False
+
+
+BoxReplace.__module__ = "pyteal"
+
+
+class BoxExtract(Expr):
+    """Extracts bytes in a box given its name, start index and stop index."""
+
+    def __init__(self, name: Expr, start: Expr, length: Expr) -> None:
+        """
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            start: The byte index into the box to start reading. Must evaluate to uint64
+            length: The byte length into the box from start to stop reading. Must evaluate to uint64
+        """
+
+        super().__init__()
+        require_type(name, TealType.bytes)
+        require_type(start, TealType.uint64)
+        require_type(length, TealType.uint64)
+        self.name = name
+        self.start = start
+        self.length = length
+
+    def __teal__(self, options: "CompileOptions"):
+        if options.version < Op.box_extract.min_version:
+            raise TealInputError(
+                f"BoxExtract not available on teal version {options.version} (first available {Op.box_extract.min_version})"
+            )
+
+        return TealBlock.FromOp(
+            options, TealOp(self, Op.box_extract), self.name, self.start, self.length
+        )
+
+    def __str__(self):
+        return f"(box_extract {self.name} {self.start} {self.length})"
+
+    def type_of(self):
+        return TealType.bytes
+
+    def has_return(self):
+        return False
+
+
+BoxExtract.__module__ = "pyteal"
+
+
+def BoxLen(name: Expr) -> MaybeValue:
+    """
+    Get the byte length of the box specified by its name.
+
+    Args:
+        name: The key the box was created with. Must evaluate to bytes
+    """
+    require_type(name, TealType.bytes)
+    return MaybeValue(Op.box_len, TealType.uint64, args=[name])
+
+
+def BoxGet(name: Expr) -> MaybeValue:
+    """
+    Get the full contents of a box given its name.
+
+    Args:
+        name: The key the box was created with. Must evaluate to bytes
+    """
+    require_type(name, TealType.bytes)
+    return MaybeValue(Op.box_get, TealType.bytes, args=[name])
+
+
+class BoxPut(Expr):
+    """Write all contents to a box given its name."""
+
+    def __init__(self, name: Expr, value: Expr) -> None:
+        """
+        Args:
+            name: The key the box was created with. Must evaluate to bytes
+            value: The value to write to the box. Must evaluate to bytes
+        """
+
+        super().__init__()
+        require_type(name, TealType.bytes)
+        require_type(value, TealType.bytes)
+        self.name = name
+        self.value = value
+
+    def __teal__(self, options: "CompileOptions"):
+        if options.version < Op.box_put.min_version:
+            raise TealInputError(
+                f"BoxPut not available on teal version {options.version} (first available {Op.box_put.min_version})"
+            )
+
+        return TealBlock.FromOp(
+            options, TealOp(self, Op.box_put), self.name, self.value
+        )
+
+    def __str__(self):
+        return f"(box_put {self.name})"
+
+    def type_of(self):
+        return TealType.none
+
+    def has_return(self):
+        return False
+
+
+BoxPut.__module__ = "pyteal"