reference docs

docs/book.toml

@@ -6,7 +6,7 @@ src = "src"
 title = "Simular Documentation"
 
 [output.html]
-default-theme = "Ayu"
+default-theme = "light"
 git-repository-url = "https://github.com/simular-fi/simular"
 git-repository-icon = "fa-github"
 

docs/src/getstarted.md

@@ -43,7 +43,7 @@ assert evm.get_balance(alice) == to_wei(1, "ether")
 ```
 
 ### Deploy and interact with a Contract
-Here how you can deploy and interact with a simple Contract
+Here's how you can deploy and interact with a simple Contract
 
 For this example, we'll use the following smart contract:
 ```javascript

docs/src/reference/pyabi.md

@@ -1 +1,220 @@
-# PyAbi API
+# PyAbi API
+Provides the ability to load and parse ABI files. It's primarily used to help extract the information needed to interact with smart contracts.  This is rarely used directly. See `Contracts` and `Utilities`.
+
+- [PyAbi API](#pyabi-api)
+  - [Import](#import)
+  - [Static functions](#static-functions)
+    - [load\_from\_json](#load_from_json)
+    - [load\_from\_parts](#load_from_parts)
+    - [load\_from\_human\_readable](#load_from_human_readable)
+  - [Methods](#methods)
+    - [has\_function](#has_function)
+    - [has\_fallback](#has_fallback)
+    - [has\_receive](#has_receive)
+    - [bytecode](#bytecode)
+    - [constructor\_input\_types](#constructor_input_types)
+    - [encode\_function\_input](#encode_function_input)
+
+
+## Import
+```python
+from simular import PyAbi
+```
+## Static functions
+You can create an instance of `PyAbi` by using one of the following static methods:
+
+### load_from_json
+Create an instance by loading a JSON file from a compiled Solidity contract. Expects a JSON file the includes an `abi` and `bytecode` entry.
+
+```python
+def load_from_json(abi: str) -> self
+```
+**Parameters**:
+- abi: an un-parsed json encoded file
+
+**Returns:** an instance of PyAbi
+
+Example:
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+```
+
+
+### load_from_parts
+Create an instance by loading a the json encoded abi information and contract bytecode.
+
+```python
+def load_from_parts(abi: str, bytecode: bytes) -> self
+```
+**Parameters**:
+- abi: an un-parsed json encoded file with just the abi information
+- bytecode: the contract bytecode
+
+**Returns:** an instance of PyAbi
+
+Example:
+```python
+with open('counter.abi') as f:
+    abi = f.read()
+
+with open('counter.bin') as f:
+    bytecode = f.read()
+
+bits = bytes.fromhex(bytecode)
+abi = PyAbi.load_from_json(abi, bits)
+```
+
+### load_from_human_readable
+Create an instance from a list of contract function descriptions
+
+```python
+def load_from_human_readable(items: typing.List[str]) -> self
+```
+**Parameters**:
+- items: is a list of `function desciptions`
+
+**Returns:** an instance of PyAbi
+
+A `function description` is shorthand way of describing the function name, inputs, and outputs.  The format is the form: 
+
+`function NAME(ARG TYPES) (RETURN TYPES)`
+Where: 
+- NAME: is the name of the function.
+- ARG TYPES: 0 or more of the require Solidity input types
+- RETURN TYPES: tuple of expected Solidity return types. This is not required if the function doesn't return anything.
+
+For example: 
+
+`'function hello() (uint256)'` is a solidity function named `hello` that takes no input arguments and returns an `uint256`
+
+
+`'function hello(address, uint256)'` is a solidity function named `hello` that takes 2 arguments, an `address`, and  `uint256` and returns nothing.
+
+Example:
+```python 
+abi = PyAbi.load_from_human_readable([
+    'function hello() (uint256)', 
+    'function hello(address, uint256)'])
+```
+
+
+## Methods
+
+### has_function
+Does the ABI include the function with the given name.
+
+```python
+def has_function(self, name: str) -> bool
+```
+**Parameters**:
+- items: is a list of `function desciptions`
+
+**Returns:** an instance of True | False
+
+Example
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+assert abi.has_function("increment")
+```
+
+
+### has_fallback
+Does the Contract define a [fallback function](https://docs.soliditylang.org/en/latest/contracts.html#fallback-function)
+
+```python
+def has_fallback(self) -> bool
+```
+**Returns:** an instance of True | False
+
+Example
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+assert not abi.has_fallback()
+```
+
+### has_receive
+Does the Contract define a [receive function](https://docs.soliditylang.org/en/latest/contracts.html#receive-ether-function)
+
+```python
+def has_receive(self) -> bool
+```
+**Returns:** an instance of True | False
+
+Example
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+assert not abi.has_receive()
+```
+
+### bytecode
+Return the byte from the ABI
+
+```python
+def bytecode(self) -> bytes | None
+```
+
+**Returns:** bytes or **None** if the bytecode wasn't set
+
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+abi.bytecode()
+```
+
+### constructor_input_types
+Return a list (if any) of the exopected constructor arguments.
+
+```python
+def constructor_input_types(self) -> typing.List[str] | None
+```
+**Returns:** a list of the Solidity types expected as arguments to the constructor.  Or **None** if the constructor doesn't take any arguments.
+
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+abi.constructor_input_types()
+```
+
+
+
+### encode_function_input
+Encode the function with any given input to call on the EVM. See [Function Encoding](https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding) for more details.
+
+```python
+def encode_function_input(self, 
+                          name: str, 
+                          args: typing.Tuple[Any]
+) -> typing.Tuple(bytes, typing.List[str])
+```
+**Parameters**:
+- name: of the contract method to encode
+- args: 0 or more arguments to pass to the method
+
+**Returns:** tuple: the encoded bytes and a list of the expected output types from calling the method
+
+```python
+with open('counter.json') as f:
+    raw = f.read()
+abi = PyAbi.load_from_json(raw)
+
+abi.encode_function_input(self, "increment", (1,))
+```
+
+
+
+

docs/src/reference/pyevm.md

@@ -11,7 +11,7 @@ Both versions are a Python class wrapper of the [REVM](https://github.com/blueal
 - [PyEvm API](#pyevm-api)
   - [Import](#import)
   - [Constructor](#constructor)
-  - [Shared methods](#shared-methods)
+  - [Common methods](#common-methods)
     - [get\_balance](#get_balance)
     - [create\_account](#create_account)
     - [transfer](#transfer)
@@ -20,23 +20,29 @@ Both versions are a Python class wrapper of the [REVM](https://github.com/blueal
     - [call](#call)
     - [dump\_state](#dump_state)
     - [view\_storage\_slot](#view_storage_slot)
+  - [PyEVMLocal](#pyevmlocal)
+    - [load\_state](#load_state)
 
 ## Import
 ```python
 from simular import PyEvmLocal, PyEvmFork
 ```
 
 ## Constructor
+
+Create an instance of the EVM with in-memory storage.
+
+**PyEvmLocal()**
 
-Create an instance of the EVM.
+Create an instance of the EVM with in-memory storage and the ability to pull state from a remote node.
 
+**PyEvmFork(url: str)** : 
 
-* **PyEvmLocal()** : takes no parameters
-* **PyEvmFork(url="http//...")** : 
-    - **parameters:** `url` : the http address to an Ethereum json-rpc endpoint.  Services such as `Infura` and `Alchemy` provide access to a json-rpc endpoint
+**Parameters:** 
+- `url` : The HTTP address of an Ethereum json-rpc endpoint.  Services such as `Infura` and `Alchemy` provide access to json-rpc endpoints
 
 
-## Shared methods
+## Common methods
 Both versions share the following methods:
 
 ### get_balance
@@ -162,7 +168,7 @@ evm.call('0x11..', b'661..')
 ```
 
 ### dump_state
-Export the current state of the EVM to a JSON encoded string
+Export the current state (snapshot) of the EVM to a JSON encoded string
 
 ```python
 def dump_state(self) -> str
@@ -196,6 +202,33 @@ evm = PyEvmLocal()
 value = evm.view_storage_slot('0x11...', 1)
 ```
 
+## PyEVMLocal
+`PyEVMLocal` has one additional method:
+
+### load_state
+Load state into the EVM from a snapshot. See [dump_state](#dump_state).
+
+```python
+def load_state(self, snapshot: str)
+```
+**Parameters**:
+- snapshot: the json file produced by `dump_state()`
+
+Example:
+```python
+evm = PyEvmLocal()
+
+with open('snapshot.json') as f:
+  snap = f.read()
+
+evm.dump_state(snap)
+```
+
+
+
+
+
+