Merge pull request #7 from barnjamin/abi-examples

Abi examples

Author: robdmoore

template_content/playground/abi/README.md

@@ -0,0 +1,9 @@
+ABI Examples
+------------
+
+Demonstrates some usage of the PyTeal ABI types.
+
+ABI Types are defined in the [ARC-4 spec](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md) and are very useful for a standard encoding of complex types. They allow for easier interoperability with other contracts that use the same encoding. 
+
+
+See https://pyteal.readthedocs.io/en/stable/abi.html for more information on the PyTeal types.

template_content/playground/abi/application.py

@@ -0,0 +1,16 @@
+import beaker
+import pyteal as pt
+
+
+from named_tuple_blueprint import named_tuple_blueprint
+from array_blueprint import array_blueprint
+
+app = beaker.Application("ABIExample")
+app.apply(named_tuple_blueprint)
+app.apply(array_blueprint)
+
+
+@app.external
+def echo(v: pt.abi.String, *, output: pt.abi.String) -> pt.Expr:
+    """echos the string back unchanged"""
+    return output.set(v)

template_content/playground/abi/array_blueprint.py

@@ -0,0 +1,124 @@
+from typing import Literal
+
+import beaker
+import pyteal as pt
+
+
+# util method for converting an Int to u16 bytes
+def to_u16(i: pt.Expr) -> pt.Expr:
+    return pt.Suffix(pt.Itob(i), pt.Int(6))
+
+
+def array_blueprint(app: beaker.Application) -> None:
+    @app.external
+    def sum_dynamic_array(
+        v: pt.abi.DynamicArray[pt.abi.Uint64], *, output: pt.abi.Uint64
+    ) -> pt.Expr:
+        """sums the array of ints"""
+        return pt.Seq(
+            # Use a scratch var to store the running sum
+            (running_sum := pt.ScratchVar(pt.TealType.uint64)).store(pt.Int(0)),
+            # Iterate over the elements of the array
+            pt.For(
+                (i := pt.ScratchVar()).store(pt.Int(0)),
+                i.load() < v.length(),
+                i.store(i.load() + pt.Int(1)),
+            ).Do(
+                # Access the element with square bracket annotation
+                # and call `use` on it to use the value since its a
+                # computed type like tuple elements
+                v[i.load()].use(
+                    lambda val: running_sum.store(running_sum.load() + val.get())
+                )
+            ),
+            # Set the value we're returning
+            output.set(running_sum.load()),
+        )
+
+    # While its not advisable to make heavy use dynamic ABI
+    # types within the logic of the contract due to the inefficient
+    # access to elements, below are some examples of how you
+    # might construct a larger array from 2 smaller ones
+    @app.external
+    def concat_static_arrays(
+        a: pt.abi.StaticArray[pt.abi.Uint64, Literal[3]],
+        b: pt.abi.StaticArray[pt.abi.Uint64, Literal[3]],
+        *,
+        output: pt.abi.StaticArray[pt.abi.Uint64, Literal[6]],
+    ) -> pt.Expr:
+        # Static arrays are easy to concat since there is no
+        # length prefix or offsets to track. The typing of the
+        # value includes the length explicitly.
+        return output.decode(pt.Concat(a.encode(), b.encode()))
+
+    @app.external
+    def concat_dynamic_arrays(
+        a: pt.abi.DynamicArray[pt.abi.Uint64],
+        b: pt.abi.DynamicArray[pt.abi.Uint64],
+        *,
+        output: pt.abi.DynamicArray[pt.abi.Uint64],
+    ) -> pt.Expr:
+        """demonstrate how two dynamic arrays of static elements could be concat'd"""
+        # A Dynamic array of static types is encoded as:
+        # [uint16 length, element 0, element 1]
+        # so to concat them, we must remove the 2 byte length prefix
+        # from each, and prepend the new length (of elements!) as 2 byte integer
+        return output.decode(
+            pt.Concat(
+                pt.Suffix(pt.Itob(a.length() + b.length()), pt.Int(6)),
+                pt.Suffix(a.encode(), pt.Int(2)),
+                pt.Suffix(b.encode(), pt.Int(2)),
+            )
+        )
+
+    @app.external
+    def concat_dynamic_string_arrays(
+        a: pt.abi.DynamicArray[pt.abi.String],
+        b: pt.abi.DynamicArray[pt.abi.String],
+        *,
+        output: pt.abi.DynamicArray[pt.abi.String],
+    ) -> pt.Expr:
+        """demonstrate how two dynamic arrays of dynamic elements could be concat'd"""
+        # NOTE: this is not efficient (clearly), static types should
+        # always be preferred if possible. Otherwise use some encoding
+        # other than the abi encoding, which is more for serializing/deserializing data
+
+        # A Dynamic array of dynamic types is encoded as:
+        # [uint16 length, uint16 pos elem 0, uint16 pos elem 1, elem 0, elem 1]
+        # so to concat them, we must remove the 2 byte length prefix
+        # from each, and prepend the new length (of elements!) as 2 byte integer
+        return pt.Seq(
+            # Make a couple bufs for the header (offsets) and elements
+            (_head_buf := pt.ScratchVar()).store(
+                pt.Suffix(pt.Itob(a.length() + b.length()), pt.Int(6))
+            ),
+            # Take the element contents of the 2 arrays
+            (_tail_buf := pt.ScratchVar()).store(
+                pt.Concat(
+                    # strip length and positions, now its [elem0, elem1, elem2]
+                    pt.Suffix(a.encode(), pt.Int(2) + (pt.Int(2) * a.length())),
+                    pt.Suffix(b.encode(), pt.Int(2) + (pt.Int(2) * b.length())),
+                )
+            ),
+            # Create the offset value we'll use for the position header
+            # we know the first string will start at 2 * combined length
+            (offset := pt.ScratchVar()).store(((a.length() + b.length()) * pt.Int(2))),
+            # We'll track the current string we're working on here
+            (curr_str_len := pt.ScratchVar()).store(pt.Int(0)),
+            (cursor := pt.ScratchVar()).store(pt.Int(0)),
+            pt.While(
+                (cursor.load() + curr_str_len.load()) <= pt.Len(_tail_buf.load())
+            ).Do(
+                # Add the offset for this string to the head buf
+                _head_buf.store(pt.Concat(_head_buf.load(), to_u16(offset.load()))),
+                # Get the length of the current string + 2 bytes for uint16 len
+                curr_str_len.store(
+                    pt.ExtractUint16(_tail_buf.load(), cursor.load()) + pt.Int(2)
+                ),
+                # update our cursor to point to the next str element
+                cursor.store(cursor.load() + curr_str_len.load()),
+                # update our offset similarly
+                offset.store(offset.load() + curr_str_len.load()),
+            ),
+            output.decode(pt.Concat(_head_buf.load(), _tail_buf.load())),
+        )

template_content/playground/abi/build.py

@@ -0,0 +1,17 @@
+# Build the sample contract in this directory using Beaker and output to ./artifacts
+from pathlib import Path
+
+import application
+
+
+def build() -> Path:
+    """Build the beaker app, export it to disk, and return the Path to the app spec file"""
+    app_spec = application.app.build()
+    output_dir = Path(__file__).parent / "artifacts"
+    print(f"Dumping {app_spec.contract.name} to {output_dir}")
+    app_spec.export(output_dir)
+    return output_dir / "application.json"
+
+
+if __name__ == "__main__":
+    build()

template_content/playground/abi/demo.py

@@ -0,0 +1,36 @@
+import application
+from beaker import client, sandbox
+
+
+def main() -> None:
+    acct = sandbox.get_accounts().pop()
+    algod_client = sandbox.get_algod_client()
+    app_client = client.ApplicationClient(
+        algod_client, application.app, signer=acct.signer
+    )
+    app_id, app_address, _ = app_client.create()
+    print(f"Deployed Application ID: {app_id} Address: {app_address}")
+
+    result = app_client.call("sum_tuple_elements_with_use", t=(123, 456))
+    print(f"{result.method.name} returned {result.return_value}")
+
+    result = app_client.call("sum_tuple_elements_with_store_into", t=(123, 456))
+    print(f"{result.method.name} returned {result.return_value}")
+
+    result = app_client.call("sum_dynamic_array", v=[1, 2, 3, 4, 5, 6])
+    print(f"{result.method.name} returned {result.return_value}")
+
+    result = app_client.call("concat_dynamic_arrays", a=[1, 2, 3], b=[4, 5, 6])
+    print(f"{result.method.name} returned {result.return_value}")
+
+    result = app_client.call("concat_static_arrays", a=[1, 2, 3], b=[4, 5, 6])
+    print(f"{result.method.name} returned {result.return_value}")
+
+    result = app_client.call(
+        "concat_dynamic_string_arrays", a=["a", "b", "c"], b=["d", "e", "f"]
+    )
+    print(f"{result.method.name} returned {result.return_value}")
+
+
+if __name__ == "__main__":
+    main()

template_content/playground/abi/named_tuple_blueprint.py

@@ -0,0 +1,38 @@
+import beaker
+import pyteal as pt
+
+
+class StructyTuple(pt.abi.NamedTuple):
+    # Note that the type is wrapped in a `pt.abi.Field`
+    a: pt.abi.Field[pt.abi.Uint64]
+    b: pt.abi.Field[pt.abi.Uint64]
+
+
+def named_tuple_blueprint(app: beaker.Application) -> None:
+    @app.external
+    def sum_tuple_elements_with_use(
+        t: StructyTuple, *, output: pt.abi.Uint64
+    ) -> pt.Expr:
+        """sum the elements of the tuple with `use` and lambda"""
+        return pt.Seq(
+            (running_sum := pt.ScratchVar(pt.TealType.uint64)).store(pt.Int(0)),
+            # we can pass a lambda into the `use` method to access the value
+            # as the abi type it was declared as
+            t.a.use(lambda a: running_sum.store(running_sum.load() + a.get())),
+            t.b.use(lambda b: running_sum.store(running_sum.load() + b.get())),
+            output.set(running_sum.load()),
+        )
+
+    @app.external
+    def sum_tuple_elements_with_store_into(
+        t: StructyTuple, *, output: pt.abi.Uint64
+    ) -> pt.Expr:
+        """sum the elements of the tuple with `.set` on matching abi type"""
+        return pt.Seq(
+            # we can pass the tuple element into a `set` method for the same type
+            # under the covers this calls the `store_into` method on the element
+            # with the abi type as the argument
+            (a := pt.abi.Uint64()).set(t.a),
+            (b := pt.abi.Uint64()).set(t.b),
+            output.set(a.get() + b.get()),
+        )

template_content/playground/blueprint/README.md

@@ -0,0 +1,6 @@
+Blueprints
+----------
+
+Blueprints are a great way to reuse existing code. 
+
+See https://algorand-devrel.github.io/beaker/html/usage.html#code-reuse for more

template_content/playground/blueprint/demo.py

@@ -1,4 +1,3 @@
-from algokit_utils import LogicError
 import application
 from beaker import client, sandbox
 

template_content/playground/boxes/README.md

@@ -0,0 +1,8 @@
+Boxes
+-----
+
+Demonstrates some of the uses of the Layer 1 Storage primitive, Boxes.
+
+PyTeal provides the basics for working with Boxes, see more here: https://pyteal.readthedocs.io/en/stable/state.html#box-storage
+
+Beaker provides two higher level constructs for working with Boxes, see more here: https://algorand-devrel.github.io/beaker/html/boxes.html

template_content/playground/boxes/application.py

@@ -0,0 +1,79 @@
+import beaker
+import pyteal as pt
+from beaker import consts
+from beaker.lib import storage
+
+MAX_MEMBERS = 10
+
+
+class BoxExampleState:
+    # Declares a BoxMapping, where each key is an address and each value is a uint64
+    # every new key creates a new box.
+    balances = storage.BoxMapping(pt.abi.Address, pt.abi.Uint64)
+
+    # Declares a BoxList, where each element is a 32 byte array and
+    # creates a box with space for MAX_MEMBERS elements
+    members = storage.BoxList(pt.abi.Address, MAX_MEMBERS)
+
+    # Add a global state value to track the total count of elements in the box
+    member_count = beaker.GlobalStateValue(pt.TealType.uint64)
+
+
+app = beaker.Application("BoxExample", state=BoxExampleState())
+
+
+@app.external
+def bootstrap() -> pt.Expr:
+    return pt.Seq(
+        app.initialize_global_state(),
+        # create returns a bool value indicating if the box was created
+        # we just pop it here to discard it
+        pt.Pop(app.state.members.create()),
+    )
+
+
+@app.external
+def set_balance(addr: pt.abi.Address, amount: pt.abi.Uint64) -> pt.Expr:
+    """Sets the balance of an address"""
+    return app.state.balances[addr].set(amount)
+
+
+@app.external(read_only=True)
+def read_balance(addr: pt.abi.Address, *, output: pt.abi.Uint64) -> pt.Expr:
+    return output.decode(app.state.balances[addr].get())
+
+
+@app.external
+def add_member(addr: pt.abi.Address) -> pt.Expr:
+    """Adds a new member to the list"""
+    return pt.Seq(
+        pt.Assert(app.state.member_count < pt.Int(MAX_MEMBERS), comment="List is full"),
+        app.state.members[app.state.member_count].set(addr),
+        # Write a zero balance to the balance box
+        # for this address
+        app.state.balances[addr].set(pt.Itob(pt.Int(0))),
+        app.state.member_count.increment(),
+    )
+
+
+@app.external
+def fill_box(
+    box_name: pt.abi.String, box_data: pt.abi.DynamicArray[pt.abi.String]
+) -> pt.Expr:
+    return pt.BoxPut(box_name.get(), box_data.encode())
+
+
+def compute_min_balance(members: int):
+    """Compute the min balance for the app to hold the boxes we need"""
+    return (
+        consts.ASSET_MIN_BALANCE  # Cover min bal for member token
+        + (
+            consts.BOX_FLAT_MIN_BALANCE
+            + (pt.abi.size_of(pt.abi.Uint64) * consts.BOX_BYTE_MIN_BALANCE)
+        )
+        * members  # cover min bal for balance boxes we might create
+        + (
+            consts.BOX_FLAT_MIN_BALANCE
+            + (members * pt.abi.size_of(pt.abi.Address) * consts.BOX_BYTE_MIN_BALANCE)
+        )  # cover min bal for member list box
+    )