types: support txn.Access transaction constructor (#580)

Author: algorandskiy

algosdk/app_access.py

@@ -0,0 +1,229 @@
+from collections import OrderedDict
+from os import access
+from typing import List, Optional, Tuple, Union
+
+from algosdk import encoding
+from algosdk.box_reference import BoxReference
+
+
+def translate_to_resource_references(
+    app_id: int,
+    accounts: Optional[List[str]] = None,
+    foreign_assets: Optional[List[int]] = None,
+    foreign_apps: Optional[List[int]] = None,
+    boxes: Optional[List[Tuple[int, bytes]]] = None,
+    holdings: Optional[List[Tuple[int, str]]] = None,
+    locals: Optional[List[Tuple[int, str]]] = None,
+) -> List["ResourceReference"]:
+    """
+    Convert accounts, apps, assets, boxes, holdings, locals into list of ResourceReference
+    that is suitable for txn.Access field creation.
+
+    Args:
+        app_id (int): current application id
+        accounts (list[string], optional): list of additional accounts involved in call
+        foreign_apps (list[int], optional): list of other applications (identified by index) involved in call
+        foreign_assets (list[int], optional): list of assets involved in call
+        boxes(list[(int, bytes)], optional): list of tuples specifying app id and key for boxes the app may access
+        holdings (list[int, str], optional): lists of tuples specifying the asset holdings to be accessed during evaluation of the application;
+            zero (empty) address means sender
+        locals (list[int, str], optional): lists of tuples specifying the local states to be accessed during evaluation of the application;
+            zero (empty) address means sender
+    """
+    access: List["ResourceReference"] = []
+
+    def ensure(target: "ResourceReference") -> int:
+        for idx, a in enumerate(access):
+            if (
+                a.address == target.address
+                and a.asset_id == target.asset_id
+                and a.app_id == target.app_id
+            ):
+                return idx + 1
+        access.append(target)
+        return len(access)
+
+    for account in accounts or []:
+        ensure(ResourceReference(address=account))
+
+    for asset in foreign_assets or []:
+        ensure(ResourceReference(asset_id=asset))
+
+    for app in foreign_apps or []:
+        ensure(ResourceReference(app_id=app))
+
+    for asset, addr in holdings or []:
+        addr_idx = 0
+        if addr:
+            addr_idx = ensure(ResourceReference(address=addr))
+        asset_idx = ensure(ResourceReference(asset_id=asset))
+        access.append(
+            ResourceReference(
+                holding_reference=HoldingRef(
+                    asset_index=asset_idx, addr_index=addr_idx
+                )
+            )
+        )
+
+    for app, addr in locals or []:
+        app_idx = 0
+        if app and app != app_id:
+            app_idx = ensure(ResourceReference(app_id=app))
+        addr_idx = 0
+        if addr:
+            addr_idx = ensure(ResourceReference(address=addr))
+        access.append(
+            ResourceReference(
+                locals_reference=LocalsRef(
+                    app_index=app_idx, addr_index=addr_idx
+                )
+            )
+        )
+
+    for app, name in boxes or []:
+        app_idx = 0
+        if app and app != app_id:
+            app_idx = ensure(ResourceReference(app_id=app))
+        access.append(
+            ResourceReference(
+                box_reference=BoxReference(app_index=app_idx, name=name)
+            )
+        )
+
+    return access
+
+
+class ResourceReference:
+    def __init__(
+        self,
+        address: Optional[str] = None,
+        asset_id: Optional[int] = None,
+        app_id: Optional[int] = None,
+        box_reference: Optional[BoxReference] = None,
+        holding_reference: Optional["HoldingRef"] = None,
+        locals_reference: Optional["LocalsRef"] = None,
+    ):
+        self.app_id = app_id
+        self.address = address
+        self.asset_id = asset_id
+        self.box_reference = box_reference
+        self.holding_reference = holding_reference
+        self.locals_reference = locals_reference
+
+    def dictify(self):
+        d = dict()
+        if self.address:
+            d["d"] = encoding.decode_address(self.address)
+        if self.asset_id:
+            d["s"] = self.asset_id
+        if self.app_id:
+            d["p"] = self.app_id
+        if self.box_reference:
+            d["b"] = self.box_reference.dictify()
+        if self.holding_reference:
+            d["h"] = self.holding_reference.dictify()
+        if self.locals_reference:
+            d["l"] = self.locals_reference.dictify()
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return ResourceReference(
+            address=encoding.encode_address(d["d"]) if "d" in d else "",
+            asset_id=d["s"] if "s" in d else None,
+            app_id=d["p"] if "p" in d else None,
+            box_reference=BoxReference.undictify(d["b"]) if "b" in d else None,
+            holding_reference=(
+                HoldingRef.undictify(d["h"]) if "h" in d else None
+            ),
+            locals_reference=LocalsRef.undictify(d["l"]) if "l" in d else None,
+        )
+
+    def __eq__(self, value):
+        if not isinstance(value, ResourceReference):
+            return False
+        return (
+            self.address == value.address
+            and self.asset_id == value.asset_id
+            and self.app_id == value.app_id
+            and self.box_reference == value.box_reference
+            and self.holding_reference == value.holding_reference
+            and self.locals_reference == value.locals_reference
+        )
+
+
+class LocalsRef:
+    """
+    Represents a local reference in txn.Access with an app index and address index.
+
+    Args:
+        app_index (int): index of the application in the access array
+        addr_index (int): index of the address in the access array
+    """
+
+    def __init__(self, app_index: int, addr_index: int):
+        self.app_index = app_index
+        self.addr_index = addr_index
+
+    def dictify(self):
+        d = dict()
+        if self.app_index:
+            d["p"] = self.app_index
+        if self.addr_index:
+            d["d"] = self.addr_index
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return LocalsRef(
+            d["p"] if "p" in d else 0,
+            d["d"] if "d" in d else 0,
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, LocalsRef):
+            return False
+        return (
+            self.app_index == other.app_index
+            and self.addr_index == other.addr_index
+        )
+
+
+class HoldingRef:
+    """
+    Represents a holding reference in txn.Access with an asset index and address index.
+
+    Args:
+        asset_index (int): index of the asset in the access array
+        addr_index (int): index of the address in the access array
+    """
+
+    def __init__(self, asset_index: int, addr_index: int):
+        self.asset_index = asset_index
+        self.addr_index = addr_index
+
+    def dictify(self):
+        d = dict()
+        if self.asset_index:
+            d["s"] = self.asset_index
+        if self.addr_index:
+            d["d"] = self.addr_index
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return HoldingRef(
+            d["s"] if "s" in d else 0,
+            d["d"] if "d" in d else 0,
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, HoldingRef):
+            return False
+        return (
+            self.asset_index == other.asset_index
+            and self.addr_index == other.addr_index
+        )

algosdk/transaction.py

@@ -2,11 +2,15 @@
 import binascii
 import msgpack
 from enum import IntEnum
-from typing import List, Union, Optional, cast
+from typing import cast, List, Optional, Tuple, Union
 from collections import OrderedDict
 
 from algosdk import account, constants, encoding, error, logic
 from algosdk.box_reference import BoxReference
+from algosdk.app_access import (
+    translate_to_resource_references,
+    ResourceReference,
+)
 from algosdk.v2client import algod, models
 from nacl.exceptions import BadSignatureError
 from nacl.signing import SigningKey, VerifyKey
@@ -1555,6 +1559,11 @@ class ApplicationCallTxn(Transaction):
         foreign_assets (list[int], optional): list of assets involved in call
         extra_pages (int, optional): additional program space for supporting larger programs.  A page is 1024 bytes.
         boxes(list[(int, bytes)], optional): list of tuples specifying app id and key for boxes the app may access
+        use_access (bool, optional): whether to use access lists for the application
+        holdings (list[int, str], optional): lists of tuples specifying the asset holdings to be accessed during evaluation of the application;
+            zero (empty) address means sender
+        locals (list[int, str], optional): lists of tuples specifying the local states to be accessed during evaluation of the application;
+            zero (empty) address means sender
 
     Attributes:
         sender (str)
@@ -1574,6 +1583,7 @@ class ApplicationCallTxn(Transaction):
         foreign_assets (list[int])
         extra_pages (int)
         boxes (list[(int, bytes)])
+        resources (list[ResourceReference])
     """
 
     def __init__(
@@ -1595,6 +1605,10 @@ def __init__(
         rekey_to=None,
         extra_pages=0,
         boxes=None,
+        use_access=None,
+        holdings=None,
+        locals=None,
+        resources=None,
     ):
         Transaction.__init__(
             self, sender, sp, note, lease, constants.appcall_txn, rekey_to
@@ -1606,13 +1620,44 @@ def __init__(
         self.approval_program = self.teal_bytes(approval_program)
         self.clear_program = self.teal_bytes(clear_program)
         self.app_args = self.bytes_list(app_args)
-        self.accounts = accounts if accounts else None
-        self.foreign_apps = self.int_list(foreign_apps)
-        self.foreign_assets = self.int_list(foreign_assets)
         self.extra_pages = extra_pages
-        self.boxes = BoxReference.translate_box_references(
-            boxes, self.foreign_apps, self.index
-        )
+        self.accounts: Optional[List[str]] = None
+        self.foreign_apps: Optional[List[int]] = None
+        self.foreign_assets: Optional[List[int]] = None
+        self.boxes: Optional[List[Tuple[int, bytes]]] = None
+        self.resources: Optional[List[ResourceReference]] = None
+
+        if resources and (
+            accounts
+            or foreign_apps
+            or foreign_assets
+            or boxes
+            or holdings
+            or locals
+        ):
+            raise ValueError(
+                "cannot specify both resources and other access fields"
+            )
+
+        if resources:
+            self.resources = resources
+        elif use_access:
+            self.resources = translate_to_resource_references(
+                app_id=self.index,
+                accounts=accounts,
+                foreign_assets=foreign_assets,
+                foreign_apps=foreign_apps,
+                boxes=boxes,
+                holdings=holdings,
+                locals=locals,
+            )
+        else:
+            self.accounts = accounts if accounts else None
+            self.foreign_apps = self.int_list(foreign_apps)
+            self.foreign_assets = self.int_list(foreign_assets)
+            self.boxes = BoxReference.translate_box_references(
+                boxes, self.foreign_apps, self.index
+            )
         if not sp.flat_fee:
             mf = constants.min_txn_fee if sp.min_fee is None else sp.min_fee
             self.fee = max(self.estimate_size() * self.fee, mf)
@@ -1664,6 +1709,8 @@ def dictify(self):
             d["apsu"] = self.clear_program
         if self.app_args:
             d["apaa"] = self.app_args
+        if self.extra_pages:
+            d["apep"] = self.extra_pages
         if self.accounts:
             d["apat"] = [
                 encoding.decode_address(account_pubkey)
@@ -1673,10 +1720,10 @@ def dictify(self):
             d["apfa"] = self.foreign_apps
         if self.foreign_assets:
             d["apas"] = self.foreign_assets
-        if self.extra_pages:
-            d["apep"] = self.extra_pages
         if self.boxes:
             d["apbx"] = [box.dictify() for box in self.boxes]
+        if self.resources:
+            d["al"] = [ap.dictify() for ap in self.resources]
 
         d.update(super(ApplicationCallTxn, self).dictify())
         od = OrderedDict(sorted(d.items()))
@@ -1697,7 +1744,14 @@ def _undictify(d):
             "approval_program": d["apap"] if "apap" in d else None,
             "clear_program": d["apsu"] if "apsu" in d else None,
             "app_args": d["apaa"] if "apaa" in d else None,
-            "accounts": d["apat"] if "apat" in d else None,
+            "accounts": (
+                [
+                    encoding.encode_address(account_bytes)
+                    for account_bytes in d["apat"]
+                ]
+                if "apat" in d
+                else None
+            ),
             "foreign_apps": d["apfa"] if "apfa" in d else None,
             "foreign_assets": d["apas"] if "apas" in d else None,
             "extra_pages": d["apep"] if "apep" in d else 0,
@@ -1706,12 +1760,12 @@ def _undictify(d):
                 if "apbx" in d
                 else None
             ),
+            "resources": (
+                [ResourceReference.undictify(ref) for ref in d["al"]]
+                if "al" in d
+                else None
+            ),
         }
-        if args["accounts"]:
-            args["accounts"] = [
-                encoding.encode_address(account_bytes)
-                for account_bytes in args["accounts"]
-            ]
         return args
 
     def __eq__(self, other):