CU-864ej3bwe - Change Neo3Boa Documentation describing the features (…

…first iteration)

boa3/builtin/compile_time/__init__.py

@@ -16,6 +16,14 @@ def CreateNewEvent(arguments: List[Tuple[str, type]] = [], event_name: str = '')
     """
     Creates a new event.
 
+    >>> new_event: Event = CreateNewEvent(
+    ...     [
+    ...        ('name', str),
+    ...        ('amount', int)
+    ...     ],
+    ...     'New Event'
+    ... )
+
     :param arguments: the list of the events args' names and types
     :type arguments: List[Tuple[str, type]]
     :param event_name: custom name of the event. It's filled with the variable name if not specified
@@ -30,6 +38,39 @@ def public(name: str = None, safe: bool = True, *args, **kwargs):
     """
     This decorator identifies which methods should be included in the abi file.
 
+    >>> @public     # this method will be added to the abi
+    ... def callable_function() -> bool:
+    ...     return True
+    {
+        "name": "callable_function",
+        "offset": 0,
+        "parameters": [],
+        "safe": false,
+        "returntype": "Boolean"
+    }
+
+    >>> @public(name='callableFunction')     # the method will be added with the different name to the abi
+    ... def callable_function() -> bool:
+    ...     return True
+    {
+        "name": "callableFunction",
+        "offset": 0,
+        "parameters": [],
+        "safe": false,
+        "returntype": "Boolean"
+    }
+
+    >>> @public(safe=True)      # the method will be added with the safe flag to the abi
+    ... def callable_function() -> bool:
+    ...     return True
+    {
+        "name": "callable_function",
+        "offset": 0,
+        "parameters": [],
+        "safe": true,
+        "returntype": "Boolean"
+    }
+
     :param name: Identifier for this method that'll be used on the abi. If not specified, it'll be the same
      identifier from Python method definition
     :type name: str
@@ -45,6 +86,12 @@ def metadata(*args):
     """
     This decorator identifies the function that returns the metadata object of the smart contract.
     This can be used to only one function. Using this decorator in multiple functions will raise a compiler error.
+
+    >>> @metadata   # this indicates that this function will have information about the smart contract
+    ... def neo_metadata() -> NeoMetadata:      # needs to return a NeoMetadata
+    ...     meta = NeoMetadata()
+    ...     meta.name = 'NewContractName'
+    ...     return meta
     """
     pass
 
@@ -53,6 +100,15 @@ def contract(script_hash: ByteString):
     """
     This decorator identifies a class that should be interpreted as an interface to an existing contract.
 
+    >>> @contract('0xd2a4cff31913016155e38e474a2c06d08be276cf')
+    ... class GASInterface:
+    ...     @staticmethod
+    ...     def symbol() -> str:
+    ...         pass
+    ... @public
+    ... def main() -> str:
+    ...     return "Symbol is " + GASInterface.symbol()
+
     :param script_hash: Script hash of the interfaced contract
     :type script_hash: str or bytes
     """
@@ -73,6 +129,16 @@ def display_name(name: str):
     This decorator identifies which methods from a contract interface should have a different identifier from the one
     interfacing it. It only works in contract interface classes.
 
+    >>> @contract('0xd2a4cff31913016155e38e474a2c06d08be276cf')
+    ... class GASInterface:
+    ...     @staticmethod
+    ...     @display_name('totalSupply')
+    ...     def total_supply() -> int:      # the smart contract will call "totalSupply", but when writing the script you can call this method whatever you want to
+    ...         pass
+    ... @public
+    ... def main() -> int:
+    ...     return GASInterface.total_supply()
+
     :param name: Method identifier from the contract manifest.
     :type name: str
     """
@@ -83,6 +149,15 @@ class NeoMetadata:
     """
     This class stores the smart contract manifest information.
 
+    >>> @metadata
+    ... def neo_metadata() -> NeoMetadata:
+    ...     meta = NeoMetadata()
+    ...     meta.name = 'NewContractName'
+    ...     meta.add_permission(methods=['onNEP17Payment'])
+    ...     meta.add_trusted_source("0x1234567890123456789012345678901234567890")
+    ...     meta.date = "2023/05/30"    # this property will end up inside the extra property
+    ...     return meta
+
     :ivar name: the smart contract name. Will be the name of the file by default;
     :vartype type name: str
     :ivar supported_standards: Neo standards supported by this smart contract. Empty by default;
@@ -152,6 +227,12 @@ def add_trusted_source(self, hash_or_address: str):
         """
         Adds a valid contract hash, valid group public key, or the '*' wildcard to trusts.
 
+        >>> self.add_trusted_source("0x1234567890123456789012345678901234abcdef")
+
+        >>> self.add_trusted_source("035a928f201639204e06b4368b1a93365462a8ebbff0b8818151b74faab3a2b61a")
+
+        >>> self.add_trusted_source("*")
+
         :param hash_or_address: a contract hash, group public key or '*'
         :type hash_or_address: str
         """
@@ -179,6 +260,9 @@ def add_group(self, pub_key: str, signature: str):
         """
         Adds a pair of public key and signature to the groups in the manifest.
 
+        >>> self.add_group("031f64da8a38e6c1e5423a72ddd6d4fc4a777abe537e5cb5aa0425685cda8e063b",
+        ...                "fhsOJNF3N5Pm3oV1b7wYTx0QVelYNu7whwXMi8GsNGFKUnu3ZG8z7oWLfzzEz9pbnzwQe8WFCALEiZhLD1jG/w==")
+
         :param pub_key: public key of the group
         :type pub_key: str
         :param signature: signature of the contract hash encoded in Base64
@@ -204,6 +288,12 @@ def add_permission(self, *, contract: str = IMPORT_WILDCARD, methods: Union[List
         """
         Adds a valid contract and a valid methods to the permissions in the manifest.
 
+        >>> self.add_permission(methods=['onNEP17Payment'])
+
+        >>> self.add_permission(contract='0x3846a4aa420d9831044396dd3a56011514cd10e3', methods=['get_object'])
+
+        >>> self.add_permission(contract='0333b24ee50a488caa5deec7e021ff515f57b7993b93b45d7df901e23ee3004916')
+
         :param contract: a contract hash, group public key or '*'
         :type contract: str
         :param methods: a list of methods or '*'

boa3/builtin/contract/__init__.py

@@ -24,6 +24,18 @@
 The NEP-5 transfer event that will be triggered whenever a token is transferred, minted or burned. It needs the 
 addresses of the sender, receiver and the amount transferred.
 
+>>> Nep5TransferEvent(b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',  # when calling, it will return None, but the event will be triggered
+...                   b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0', 100)
+{
+    'name': 'transfer',
+    'script hash': b'\\xee\\xc3\\x12\\xfd\\x12\\x95\\x84\\44\\x7f\\xb8\\xed\\x41\\xdc\\x86\\x33\\x95\\x10\\x10\\x9f\\x85',
+    'state': {
+        'from': b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',
+        'to': b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0',
+        'amount': 100
+    }
+}
+
 :meta hide-value:
 """
 
@@ -40,6 +52,19 @@
 The NEP-11 Transfer event that will be triggered whenever a token is transferred, minted or burned. It needs the 
 addresses of the sender, receiver, amount transferred and the id of the token.
 
+>>> Nep11TransferEvent(b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',  # when calling, it will return None, but the event will be triggered
+...                    b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0', 1, '01')
+{
+    'name': 'Transfer',
+    'script hash': b'\\x13\\xb4\\x51\\xa2\\x1c\\x10\\x12\\xd6\\x13\\x12\\x19\\x0c\\x15\\x61\\x9b\\x1b\\xd1\\xa2\\xf4\\xb2',
+    'state': {
+        'from': b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',
+        'to': b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0',
+        'amount': 1,
+        'tokenId': '01'
+    }
+}
+
 :meta hide-value:
 """
 
@@ -56,13 +81,29 @@
 The NEP-17 Transfer event that will be triggered whenever a token is transferred, minted or burned. It needs the 
 addresses of the sender, receiver and the amount transferred.
 
+>>> Nep17TransferEvent(b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',  # when calling, it will return None, but the event will be triggered
+...                    b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0', 100)
+{
+    'name': 'Transfer',
+    'script hash': b'\\x17\\xe3\\xca\\x91\\xca\\xb7\\xaf\\xdd\\xe6\\xba\\x07\\xaa\\xba\\xa1\\x66\\xab\\xcf\\x00\\x04\\x50',
+    'state': {
+        'from': b'\\xd1\\x17\\x92\\x82\\x12\\xc6\\xbe\\xfa\\x05\\xa0\\x23\\x07\\xa1\\x12\\x55\\x41\\x06\\x55\\x10\\xe6',
+        'to': b'\\x18\\xb7\\x30\\x14\\xdf\\xcb\\xee\\x01\\x30\\x00\\x13\\x9b\\x8d\\xa0\\x13\\xfb\\x96\\xac\\xd1\\xc0',
+        'amount': 100
+    }
+}
+
 :meta hide-value:
 """
 
 
 def abort():
     """
     Aborts the execution of a smart contract.
+
+    >>> abort()     # abort doesn't return anything by itself, but the execution will stop and the VMState will be FAULT
+    VMState.FAULT
+
     """
     pass
 
@@ -90,6 +131,12 @@ def to_script_hash(data_bytes: Any) -> bytes:
     """
     Converts a data to a script hash.
 
+    >>> to_script_hash(ECPoint(bytes(range(33))))
+    b'\\x12\\xc8z\\xfb3k\\x1e4>\\xb3\\x83\\tK\\xc7\\xdch\\xe5\\xee\\xc7\\x98'
+
+    >>> to_script_hash(b'1234567891')
+    b'\\x4b\\x56\\x34\\x17\\xed\\x99\\x7f\\x13\\x22\\x67\\x40\\x79\\x36\\x8b\\xa2\\xcd\\x72\\x41\\x25\\x6d'
+
     :param data_bytes: data to hash
     :type data_bytes: Any
     :return: the script hash of the data