Merge pull request #5 from LordGhostX/master

feat: organize documentation
NethermindEth · Jun 21, 2024 · bd80a65 · bd80a65
2 parents 273ff93 + 1efbc40
commit bd80a65
Show file tree

Hide file tree

Showing 24 changed files with 354 additions and 188 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .idea/
+.DS_Store
 
 # Venvs  -- Project & Benchmarks
 .venv/
@@ -10,7 +11,7 @@ benchmarks/*.json
 __pycache__
 
 # Docs
-_build/
+build/
 
 # Build
-dist/
+dist/
diff --git a/README.md b/README.md
@@ -1,23 +1,133 @@
 # Starknet ABI
 
-Starknet ABI is a Python library for encoding and decoding StarkNet contract calls and events.
-
-Built for efficient and rapid indexing of StarkNet transactions, Starknet ABI is simple and fast.
+Starknet ABI is a Python library for encoding and decoding Starknet contract calls and events. It is built for efficient and rapid indexing of Starknet transactions, offering simplicity and speed.
 
 ## Installation
 
+Once the library is stable, builds will be published to PyPi. In the meantime, you can follow the development installation instructions:
+
 ```bash
-pip install starknet-abi
+git clone https://github.com/nethermindEth/starknet-abi
+cd starknet-abi
+poetry env use python3.12  # Supports any version of python >= 3.10, but 3.12 is the fastest
+poetry install --all-extras
+```
+
+## Quickstart
+
+### Parse Starknet ABI JSON
+
+1. Get the [Starknet-ETH ABI JSON](https://voyager.online/class/0x05ffbcfeb50d200a0677c48a129a11245a3fc519d1d98d76882d1c9a1b19c6ed) from Voyager and save it to a file named `abi.json`.
+2. Create a `StarknetABI` instance from the ABI JSON file:
+
+```python
+import json
+from starknet_abi.core import StarknetAbi
+
+with open("abi.json") as f:
+    raw_abi = json.load(f)
+
+# Create a StarknetABI instance
+starknet_eth_abi = StarknetAbi.from_json(raw_abi, "starknet_eth", b"")
+
+# View the ABI functions
+print(starknet_eth_abi.functions)
+
+# View the ABI implemented interfaces
+print(starknet_eth_abi.implemented_interfaces)
 ```
 
-## Documentation
-[Starkent-ABI Docs](https://nethermindETH.github.io/starknet-abi)
+### Decode transaction calldata
+
+1. Decode core types:
+
+```python
+>>> from starknet_abi.decode import decode_core_type, StarknetCoreType
+>>> decode_core_type(StarknetCoreType.Bool, [0])
+False
+>>> decode_core_type(StarknetCoreType.U256, [12345, 0])
+12345
+>>> decode_core_type(StarknetCoreType.Felt, [256])
+'0x0000000000000000000000000000000000000000000000000000000000000100'
+```
 
+2. Decode from parameters:
+
+```python
+>>> from starknet_abi.decode import decode_from_params, StarknetCoreType, AbiParameter
+>>> decode_from_params(
+        [AbiParameter("a", StarknetCoreType.U32), AbiParameter("b", StarknetCoreType.U32)],
+        [123456, 654321]
+    )
+{'a': 123456, 'b': 654321}
+```
+
+3. Decode from types:
+
+```python
+>>> from starknet_abi.decode import decode_from_types, StarknetCoreType, StarknetArray
+>>> decode_from_types([StarknetArray(StarknetCoreType.U8), StarknetCoreType.Bool], [3, 123, 244, 210, 0])
+[[123, 244, 210], False]
+>>> decode_from_types(
+        [StarknetCoreType.ContractAddress, StarknetCoreType.U256, StarknetCoreType.Bool],
+        [0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7, 250_000, 0, 1]
+    )
+['0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7', 250000, True]
+```
+
+### Encode transaction calldata
+
+1. Encode core types:
+
+```python
+>>> from starknet_abi.encode import encode_core_type, StarknetCoreType
+>>> encode_core_type(StarknetCoreType.Bool, False)
+[0]
+>>> encode_core_type(StarknetCoreType.U256, 12345)
+[12345, 0]
+>>> encode_core_type(StarknetCoreType.Felt, "0x0000000000000000000000000000000000000000000000000000000000000100")
+[256]
+```
+
+2. Encode from parameters:
+
+```python
+>>> from starknet_abi.encode import encode_from_params, StarknetCoreType, AbiParameter
+>>> encode_from_params(
+        [AbiParameter("a", StarknetCoreType.U32), AbiParameter("b", StarknetCoreType.U32)],
+        {"a": 123456, "b": 654321}
+    )
+[123456, 654321]
+```
+
+3. Encode from types:
+
+```python
+>>> from starknet_abi.encode import encode_from_types, StarknetCoreType, StarknetArray
+>>> encode_from_types([StarknetArray(StarknetCoreType.U8), StarknetCoreType.Bool], [[123, 244, 210], False])
+[3, 123, 244, 210, 0]
+>>> encode_from_types(
+        [StarknetCoreType.ContractAddress, StarknetCoreType.U256, StarknetCoreType.Bool],
+        ["0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", 250000, True]
+    )
+[2087021424722619777119509474943472645767659996348769578120564519014510906823, 250000, 0, 1]
+```
+
+For detailed usage and API documentation, visit the [Starknet-ABI Docs](https://nethermindEth.github.io/starknet-abi).
 
 ## Features
-* Encode and decode StarkNet contract calls and events
-* Parse all versions of Cairo ABI JSON into shared datastructure
-* Identifying Type strings for each Functions allow you to detect which ABIs have identical types
-* Abi Decoding dispatcher
-  * Efficiently load thousands of indexed ABIs into memory
-  * Decoding Dispatcher Datastructure can be pickled and reused in data pipelines
+
+- **Encode and Decode**: Easily encode and decode Starknet contract calls and events.
+- **Comprehensive Parsing**: Parse all versions of Cairo ABI JSON into a shared data structure.
+- **Type Identification**: Identify type strings for each function, enabling the detection of ABIs with identical types.
+- **ABI Decoding Dispatcher**:
+  - Efficiently load thousands of indexed ABIs into memory.
+  - Pickle and reuse the decoding dispatcher data structure in data pipelines.
+
+## Contributing
+
+We value community contributions and are eager to support your involvement. If you encounter any bugs or have suggestions for new features, please [open an issue](https://github.com/NethermindEth/starknet-abi/issues/new) or submit a [pull request](https://github.com/NethermindEth/starknet-abi/pulls).
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
diff --git a/docs/source/Changelog.rst b/docs/source/Changelog.rst
diff --git a/docs/source/Quickstart.rst b/docs/source/Quickstart.rst
diff --git a/docs/source/api/ABI Types.rst → docs/source/api/ABI-Types.rst b/docs/source/api/ABI Types.rst → docs/source/api/ABI-Types.rst
@@ -1,8 +1,7 @@
-Abi Types
+ABI Types
 =========
 
-
-.. autoclass:: starknet_abi.decoding_types.AbiParameter
+.. autoclass:: starknet_abi.abi_types.AbiParameter
     :members:
     :exclude-members: __init__
 
@@ -16,4 +15,12 @@ Abi Types
 
 .. autoclass:: starknet_abi.decoding_types.AbiInterface
     :members:
-    :exclude-members: __init__
+    :exclude-members: __init__
+
+.. autoclass:: starknet_abi.decoding_types.DecodedFunction
+    :members:
+    :exclude-members: __init__
+
+.. autoclass:: starknet_abi.decoding_types.DecodedEvent
+    :members:
+    :exclude-members: __init__
diff --git a/docs/source/api/Core.rst b/docs/source/api/Core.rst
@@ -0,0 +1,6 @@
+Core
+====
+
+.. automodule:: starknet_abi.core
+    :members:
+    :exclude-members: __init__
diff --git a/docs/source/api/Decode.rst b/docs/source/api/Decode.rst
@@ -0,0 +1,6 @@
+Decode
+======
+
+.. automodule:: starknet_abi.decode
+    :members:
+    :exclude-members: __init__
diff --git a/docs/source/api/Decoding.rst b/docs/source/api/Decoding.rst
diff --git a/docs/source/api/Encode.rst b/docs/source/api/Encode.rst
@@ -0,0 +1,6 @@
+Encode
+======
+
+.. automodule:: starknet_abi.encode
+    :members:
+    :exclude-members: __init__
diff --git a/docs/source/api/Exceptions.rst b/docs/source/api/Exceptions.rst
@@ -3,4 +3,4 @@ Exceptions
 
 .. automodule:: starknet_abi.exceptions
     :members:
-
+    :exclude-members: __init__
diff --git a/docs/source/api/Parse.rst b/docs/source/api/Parse.rst
@@ -0,0 +1,6 @@
+Parse
+=====
+
+.. automodule:: starknet_abi.parse
+    :members:
+    :exclude-members: __init__
diff --git a/docs/source/api/Starknet Types.rst → docs/source/api/Starknet-Types.rst b/docs/source/api/Starknet Types.rst → docs/source/api/Starknet-Types.rst
@@ -1,11 +1,7 @@
 Starknet Types
 ==============
 
-Python Representations of Starknet Types that are present in ABIs.  Parsing Functions
-convert ABI Json into these Python Types.  Multiple versions of Cairo ABIs are parsed into
-the same format to make decoding and encoding seamless across versions, requiring only the
-ABI Parsing logic to change across versions
-
+Python representations of Starknet Types used in ABIs. Parsing functions convert ABI JSON into these Python types. Multiple versions of Cairo ABIs are parsed into the same format, ensuring seamless decoding and encoding across different versions, requiring only the ABI parsing logic to be updated for each new version.
 
 .. autoclass:: starknet_abi.abi_types.StarknetCoreType
     :members:
@@ -30,4 +26,3 @@ ABI Parsing logic to change across versions
 .. autoclass:: starknet_abi.abi_types.StarknetStruct
     :members:
     :exclude-members: __init__
-
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,7 +1,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../../starknet_abi"))
+sys.path.insert(0, os.path.abspath("../.."))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -40,12 +40,14 @@
 html_theme_options = {
     "show_toc_level": 2,
     "logo": {
-        "repository_url": "https://github.com/nethermindEth/starknet-abi",
-        "use_repository_button": True,
         "image_light": "_static/logo-light.svg",
         "image_dark": "_static/logo-dark.svg",
         "link": "https://nethermind.io",
     },
+    "use_repository_button": True,
+    "repository_url": "https://github.com/nethermindEth/starknet-abi",
+    "use_download_button": False,
+    "home_page_in_toc": True
 }
 
 html_static_path = ["_static"]