feat: add env.timestamp property (#368)

* feat: add timestamp to env as shortcut to patch object
* docs: document `env.timestamp()`
* Create test_env_timestamp.py

---------

Co-authored-by: Charles Cooper <cooper.charles.m@gmail.com>

boa/environment.py

@@ -371,3 +371,12 @@ def time_travel(
 
         self.evm.patch.timestamp += seconds
         self.evm.patch.block_number += blocks
+
+    # EVM API - access to evm.patch attributes
+    @property
+    def timestamp(self) -> int:
+        return self.evm.patch.timestamp
+
+    @timestamp.setter
+    def timestamp(self, val: int) -> None:
+        self.evm.patch.timestamp = val

docs/api/env/env.md

@@ -2,15 +2,19 @@
 
 ### Description
 
-TODO
-<!-- A wrapper class around py-evm which provides a "contract-centric" API. TODO more details on the singleton architecture in [boa-singleton-env](../../explain/singleton_env.md). -->
+A wrapper class around py-evm which provides a "contract-centric" API. More details on the environment architecture in [boa-singleton-env](../../explain/singleton_env.md).
 
-### Attributes
+---
 
-- `eoa`: The account to use as `msg.sender` for top-level calls and `tx.origin` in the context of state mutating function calls.
-- `chain`: The global py-evm chain instance.
+## `timestamp`
 
----
+!!! property "`boa.env.timestamp`"
+
+    **Description**
+
+    Returns the internal pyevm timestamp. Should be equal to evaluating `block.timestamp`.
+
+    Uses the low level `boa.env.patch` object to ensure that changes to the are rolled back after exiting `boa.env.anchor()` blocks.
 
 ## `alias`
 
@@ -35,7 +39,7 @@ TODO
 
     **Description**
 
-    A context manager which snapshots the state and the vm, and reverts to the snapshot on exit.
+    A context manager which snapshots the state and the vm, and reverts to the snapshot on exit. Properties in the low-level `boa.env.patch` object are also rolled back after exiting the context manager.
 
     ---
 

tests/unitary/test_env_timestamp.py

@@ -0,0 +1,26 @@
+import time
+
+import boa
+
+
+def test_env_timestamp():
+    assert boa.env.timestamp == boa.env.evm.patch.timestamp
+
+    tmp = boa.env.timestamp
+    with boa.env.anchor():
+        boa.env.timestamp += 1
+        # check patch is updated
+        assert boa.env.timestamp == boa.env.evm.patch.timestamp
+        assert tmp + 1 == boa.env.timestamp
+
+    # check reset to prior value after anchor
+    assert tmp == boa.env.timestamp
+    # sanity check
+    assert boa.env.timestamp == boa.env.evm.patch.timestamp
+
+
+def test_timestamp_correctness():
+    # amount of "timer slack" to allow in the CI since it may take some
+    # time between when boa.env is initialized and when this test is run.
+    timer_slack = 60
+    assert abs(boa.env.timestamp - time.time()) < timer_slack, "bad time"