genlayer-test 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

{genlayer_test-0.6.0.dist-info → genlayer_test-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: genlayer-test
-Version: 0.6.0
+Version: 0.8.0
 Summary: GenLayer Testing Suite
 Author: GenLayer
 License-Expression: MIT
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pytest
 Requires-Dist: setuptools>=77.0
-Requires-Dist: genlayer-py==0.8.1
+Requires-Dist: genlayer-py==0.9.0
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: pyyaml
 Requires-Dist: python-dotenv
@@ -308,6 +308,7 @@ When this flag is enabled, all contracts deployed and all write transactions wil
 - **State Injection & Consensus Simulation** – Modify contract states dynamically and simulate consensus scenarios for advanced testing.
 - **Prompt Testing & Statistical Analysis** – Evaluate and statistically test prompts for AI-driven contract execution.
 - **Scalability to Security & Audit Tools** – Designed to extend into security testing and smart contract auditing.
+- **Custom Transaction Context** – Set custom validators with specific LLM providers and models, and configure GenVM datetime for deterministic testing scenarios.
 
 ## 📚 Examples
 
@@ -387,6 +388,7 @@ def test_deployment():
         args=["initial_value"],  # Constructor arguments
         account=get_default_account(),  # Account to deploy from
         consensus_max_rotations=3,  # Optional: max consensus rotations
+        transaction_context=None,  # Optional: custom transaction context
     )
     
     # Contract is now deployed and ready to use
@@ -419,7 +421,9 @@ def test_read_methods():
     contract = factory.deploy()
 
     # Call a read-only method
-    result = contract.get_storage(args=[]).call()
+    result = contract.get_storage(args=[]).call(
+        transaction_context=None,  # Optional: custom transaction context
+    )
     
     # Assert the result matches the initial value
     assert result == "initial_value"
@@ -446,6 +450,7 @@ def test_write_methods():
         consensus_max_rotations=3,  # Optional: max consensus rotations
         wait_interval=1,  # Optional: seconds between status checks
         wait_retries=10,  # Optional: max number of retries
+        transaction_context=None,  # Optional: custom transaction context
     )
     
     # Verify the transaction was successful
@@ -609,6 +614,7 @@ def test_analyze_method():
         config=None,                # Optional: provider-specific config
         plugin=None,                # Optional: plugin name
         plugin_config=None,         # Optional: plugin configuration
+        genvm_datetime="2024-01-15T10:30:00Z",  # Optional: GenVM datetime in ISO format
     )
     
     # Access analysis results
@@ -757,6 +763,214 @@ def test_with_mocked_llm(setup_validators):
 - The `setup_validators` fixture handles the mock setup when provided with a mock_response
 - Mocking is particularly useful for CI/CD pipelines where deterministic results are required
 
+### Custom Transaction Context
+
+The GenLayer Testing Suite allows you to customize the transaction execution environment by providing a `transaction_context` parameter with custom validators and GenVM datetime settings.
+
+#### Using Transaction Context
+
+Set custom validators and GenVM datetime for deterministic testing:
+
+```python
+from gltest import get_contract_factory, get_validator_factory
+
+def test_with_custom_transaction_context():
+    factory = get_contract_factory("MyContract")
+    validator_factory = get_validator_factory()
+    
+    # Create custom validators
+    validators = validator_factory.batch_create_validators(
+        count=3,
+        stake=10,
+        provider="openai",
+        model="gpt-4o",
+        config={"temperature": 0.7, "max_tokens": 1000},
+        plugin="openai-compatible",
+        plugin_config={"api_key_env_var": "OPENAI_API_KEY"}
+    )
+    
+    # Create transaction context with custom validators and datetime
+    transaction_context = {
+        "validators": [v.to_dict() for v in validators],
+        "genvm_datetime": "2024-03-15T14:30:00Z"  # ISO format datetime
+    }
+    
+    # Deploy with custom context
+    contract = factory.deploy(
+        args=["initial_value"],
+        transaction_context=transaction_context
+    )
+    
+    # Call methods with custom context
+    result = contract.read_method().call(
+        transaction_context=transaction_context
+    )
+    
+    # Write operations with custom context
+    tx_receipt = contract.write_method(args=["value"]).transact(
+        transaction_context=transaction_context
+    )
+```
+
+#### Mock Validators with Transaction Context
+
+Combine mock validators with custom datetime for fully deterministic tests:
+
+```python
+def test_with_mocked_context():
+    factory = get_contract_factory("LLMContract")
+    validator_factory = get_validator_factory()
+    
+    # Define mock LLM responses
+    mock_response = {
+        "nondet_exec_prompt": {
+            "analyze this": "positive sentiment"
+        },
+        "eq_principle_prompt_comparative": {
+            "values match": True
+        }
+    }
+    
+    # Create mock validators
+    mock_validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_llm_response=mock_response
+    )
+    
+    # Set up deterministic context
+    transaction_context = {
+        "validators": [v.to_dict() for v in mock_validators],
+        "genvm_datetime": "2024-01-01T00:00:00Z"  # Fixed datetime for reproducibility
+    }
+    
+    # Deploy and test with deterministic context
+    contract = factory.deploy(transaction_context=transaction_context)
+    
+    # All operations will use the same mocked validators and datetime
+    result = contract.analyze_text(args=["analyze this"]).transact(
+        transaction_context=transaction_context
+    )
+    # Result will consistently return "positive sentiment"
+```
+
+### Custom Validators
+
+The GenLayer Testing Suite includes a `get_validator_factory()` function that allows you to create custom validators with specific configurations for testing different LLM providers and consensus scenarios.
+
+#### Creating Custom Validators
+
+```python
+from gltest import get_validator_factory
+
+def test_with_custom_validators():
+    factory = get_validator_factory()
+    
+    # Create validators with different LLM providers
+    openai_validator = factory.create_validator(
+        stake=10,
+        provider="openai",
+        model="gpt-4o",
+        config={"temperature": 0.8, "max_tokens": 2000},
+        plugin="openai-compatible",
+        plugin_config={"api_key_env_var": "OPENAI_API_KEY"}
+    )
+    
+    ollama_validator = factory.create_validator(
+        stake=8,
+        provider="ollama",
+        model="mistral",
+        config={"temperature": 0.5},
+        plugin="ollama",
+        plugin_config={"api_url": "http://localhost:11434"}
+    )
+    
+    # Use validators in your tests
+    validators = [openai_validator, ollama_validator]
+    # Configure your test environment with these validators
+```
+
+#### Batch Creation
+
+Create multiple validators with the same configuration:
+
+```python
+def test_batch_validators():
+    factory = get_validator_factory()
+    
+    # Create 5 validators with identical configuration
+    validators = factory.batch_create_validators(
+        count=5,
+        stake=8,
+        provider="openai",
+        model="gpt-4o",
+        config={"temperature": 0.7, "max_tokens": 1000},
+        plugin="openai-compatible",
+        plugin_config={"api_key_env_var": "OPENAI_API_KEY"}
+    )
+```
+
+#### Mock Validators
+
+For deterministic testing, create mock validators that return predefined responses:
+
+```python
+def test_with_mock_validators():
+    factory = get_validator_factory()
+    
+    # Define mock responses
+    mock_response = {
+        "nondet_exec_prompt": {
+            "What is 2+2?": "4",
+            "Explain quantum physics": "It's complicated"
+        },
+        "eq_principle_prompt_comparative": {
+            "values must match": True
+        },
+        "eq_principle_prompt_non_comparative": {
+            "Is this valid?": True
+        }
+    }
+    
+    # Create a single mock validator
+    mock_validator = factory.create_mock_validator(mock_response)
+    
+    # Create multiple mock validators
+    mock_validators = factory.batch_create_mock_validators(
+        count=5,
+        mock_llm_response=mock_response
+    )
+```
+
+#### Validator Methods
+
+Each validator object provides useful methods:
+- `to_dict()`: Convert validator to dictionary format for API calls
+- `clone()`: Create an identical copy of the validator
+- `batch_clone(count)`: Create multiple identical copies
+
+Example:
+```python
+def test_validator_cloning():
+    factory = get_validator_factory()
+    
+    # Create a base validator
+    base_validator = factory.create_validator(
+        stake=10,
+        provider="openai",
+        model="gpt-4o",
+        config={"temperature": 0.7},
+        plugin="openai-compatible",
+        plugin_config={"api_key_env_var": "OPENAI_API_KEY"}
+    )
+    
+    # Clone it to create identical validators
+    cloned = base_validator.clone()
+    multiple_clones = base_validator.batch_clone(3)
+    
+    # Convert to dictionary for API usage
+    validator_dict = base_validator.to_dict()
+```
+
 ## 📝 Best Practices
 
 1. **Test Organization**

{genlayer_test-0.6.0.dist-info → genlayer_test-0.8.0.dist-info}/RECORD

@@ -1,25 +1,27 @@
-genlayer_test-0.6.0.dist-info/licenses/LICENSE,sha256=che_H4vE0QUx3HvWrAa1_jDEVInift0U6VO15-QqEls,1064
-gltest/__init__.py,sha256=qoBV3IgDJr8uh9262XsWNMhi-ilkSgMqKVC9FVMk7cw,372
+genlayer_test-0.8.0.dist-info/licenses/LICENSE,sha256=che_H4vE0QUx3HvWrAa1_jDEVInift0U6VO15-QqEls,1064
+gltest/__init__.py,sha256=49112x2CLdYwvCbBZ1laJmMk0NQ7S3u5YUbxPefqhrk,454
 gltest/accounts.py,sha256=HUmWguJMolggQaZNRPw-LGlRlQCjLLdUanKRowMv6pI,812
 gltest/assertions.py,sha256=0dEk0VxcHK4I7GZPHxJmz-2jaA60V499gOSR74rZbfM,1748
 gltest/clients.py,sha256=1dX6wmG3QCevQRLbSaFlHymZSb-sJ5aYwet1IoX2nbA,1554
 gltest/exceptions.py,sha256=deJPmrTe5gF33qkkKF2IVJY7lc_knI7Ql3N7jZ8aLZs,510
 gltest/fixtures.py,sha256=EJXmqcC3LD03v07mepacFl58lAdhbLj6bP5rtALYISk,2507
 gltest/logging.py,sha256=jAkHsuMm-AEx1Xu1srU6W-0YzTwXJB48mCK-OVzAiN4,342
-gltest/types.py,sha256=Kj6UuTpRXkA4c5ystKfwgXuCiRJ1VMkbgvP7Auvznhw,184
+gltest/types.py,sha256=H32fHrU5aFMaPHXgEWcHAmLWOZ9pBFVp8PK_ncpVOgM,940
 gltest/utils.py,sha256=-gHhjrS7i_GhDG3sKOq2qsTtYBt4HHgXHEXh-3RB_rI,573
 gltest/artifacts/__init__.py,sha256=qTt3TE19gVNWnQLUlt5aDe4nNvJ2YJ1jzDkMmYIsCG0,194
 gltest/artifacts/contract.py,sha256=KChpmfjZod_0dVB8y-dvWz6IVm7QlIJsgG2ArtvVDaU,6457
 gltest/contracts/__init__.py,sha256=A9bvEtYOoqoHS8TLlFBfmNOnfwdsJPEf-AZuikagCHM,166
-gltest/contracts/contract.py,sha256=hYuugaV_gNFk58mGyLRPKkKVKIjsCDlVpKLvwRBf7sM,6743
-gltest/contracts/contract_factory.py,sha256=SCmhp2DRfD8FRejOqa6-_UF-yJaJr0ShB9lDkLLBzU0,8264
-gltest/contracts/contract_functions.py,sha256=5gNQYzN47rCJtmcMtUkl4ZK-yDifdZup2YhtlFlrx7E,2203
+gltest/contracts/contract.py,sha256=jLF_ojSM6IIbdGO2_DhsO79r2wZ2Z8eBAJRrZk2qVTI,7748
+gltest/contracts/contract_factory.py,sha256=PpWh4mKf1hDMv_yms5lwFV_EoXxXiuNfdXbwD74hbAU,8929
+gltest/contracts/contract_functions.py,sha256=W6Dpw1z-n9EeJxlNtIbeVnzpv4BPABhtgmgjnS8-P0w,2573
 gltest/contracts/method_stats.py,sha256=zWWjvf7K5VC4yrHpDIR717VF7LYp1RaZ1Hr_RZvWxJA,5150
-gltest/contracts/stats_collector.py,sha256=fuCc8L8hd0tsVGzH4adtZWwPa7ORf0A0zR5Dt1w92Qk,9033
+gltest/contracts/stats_collector.py,sha256=iwsnoYo5aZbI4SVMH7dR-5CQgkglExXfsvaUDpwcdss,9286
 gltest/contracts/utils.py,sha256=TTXgcXn9BuRIlKJrjwmU7R3l1IgXsXk2luM-r3lfbbg,296
 gltest/helpers/__init__.py,sha256=I7HiTu_H7_hP65zY6Wl02r-5eAMr2eZvqBVmusuQLX4,180
 gltest/helpers/fixture_snapshot.py,sha256=bMgvlEVQBGIQzj7NOyosXWlphI1H2C1o75Zo0C-kGfQ,1931
 gltest/helpers/take_snapshot.py,sha256=-QkaBvFG4ZsNKv_nCSEsy5Ze1pICOHxVhReSeQmZUlY,1276
+gltest/validators/__init__.py,sha256=AXboXORF5a8MVtG7jWMT1fJcwGXNzcX6txXQstwX2EU,152
+gltest/validators/validator_factory.py,sha256=fpb-YyAKuWo4-pXBjrZ_TApYLsm6HHa6kGpbFByRucs,3886
 gltest_cli/logging.py,sha256=WXVhfq9vT6FtV_jxDqGEGia1ZWSIUKAfmWRnZd_gWQk,1266
 gltest_cli/main.py,sha256=Ti2-0Ev1x5_cM0D1UKqdgaDt80CDHEQGtdRne2qLm4M,53
 gltest_cli/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -40,21 +42,24 @@ tests/examples/contracts/log_indexer.py,sha256=Nlf8XUt13ujam3k6hbbVrPHK-KJ366Csz
 tests/examples/contracts/multi_read_erc20.py,sha256=28qYqn191Ro3rP7YJtZwL6Sc7JDXTeh8_QoqvdVPdqM,864
 tests/examples/contracts/multi_tenant_storage.py,sha256=ceq3X4E7pkvSdy7eQMhAoHme4KFedjAcpkfUYBmcgVM,1941
 tests/examples/contracts/read_erc20.py,sha256=RgH269F0x482WuLLYcacBnZsGJjhgJp6sG_33cV6Z-w,454
+tests/examples/contracts/simple_time_contract.py,sha256=-9p_umlzUW5X2NL6IknO6Khs_114izSWifP5D2bWCMo,2512
 tests/examples/contracts/storage.py,sha256=3DD3qvzb0JkVcBtu240e5kaZWgkh-bu6YExqBUYvfaw,501
 tests/examples/contracts/user_storage.py,sha256=2W2Iv-hQZMkAaPl2RY_F-OeJpD4IlPxgWzN6e1bTkKE,649
 tests/examples/contracts/wizard_of_coin.py,sha256=Y8daPpoSKdM8wfbCPOIgEdpkLIA1ZMmeg6Hu5fBB-kU,1624
 tests/examples/contracts/multi_file_contract/__init__.py,sha256=xDn_wS62GhCmnYoI6xIqlic2i882SoPnR2TEauKc9tQ,575
 tests/examples/contracts/multi_file_contract/other.py,sha256=jHDtjUL3eAUgE6yOYKFw_RfAH7kIwk8CvxUjbWHNruk,236
+tests/examples/tests/test_custom_validators.py,sha256=ounk3fBqDexAI3eRUqscMqKf5vz77tbSxW4Cz8tzfF0,2172
 tests/examples/tests/test_football_prediction_market.py,sha256=f2hfDK76WrNJZtFkTPKoPRR6bkmFLEssnlwwltSnU9A,1111
 tests/examples/tests/test_intelligent_oracle_factory.py,sha256=sL26aeb84XpJPCSUSIX3yrbwQE8GZtvNcsaKTpngFmY,7611
 tests/examples/tests/test_invalid_deploy.py,sha256=pppM8_Vn4DXcWq9iyJXb0SpZnKXkIyJxoIDW5ApCS94,814
 tests/examples/tests/test_llm_erc20.py,sha256=zb5F_7NgvZXhvqL2nULwzuTT6LGDprSy0WgrdjY7pZc,2096
-tests/examples/tests/test_llm_erc20_analyze.py,sha256=ccWQenEOG-U4TJdu-0i-3qNM4xRRCHSr3Iwz7pxknws,1729
+tests/examples/tests/test_llm_erc20_analyze.py,sha256=rVnC3iQW_1J3P6cczEVOOG84K6ldCzlZbMO9WXQdRds,1849
 tests/examples/tests/test_log_indexer.py,sha256=46AqL7qquNc9GX2wxFxVcQXLqruMnPmxXl1yeB0-KZ4,2869
 tests/examples/tests/test_multi_file_contract.py,sha256=1Emj6ze4f-OrpxvqExeJhPHjK0cNAQW54MXf6fy2Yuc,469
 tests/examples/tests/test_multi_read_erc20.py,sha256=pSZUxoB33Z2EBtcvXxfUgwGSi_h7ryPoovkiNIfNAVQ,3713
 tests/examples/tests/test_multi_tenant_storage.py,sha256=8B3tjnRbT8ATN5obtWkGsN3nOtBU9OSjuaH9aEat3vc,2935
 tests/examples/tests/test_read_erc20.py,sha256=vLGQwguaNnT497nSq-vt4LrXj4ehn5ZSgfPt0GVFoPc,1254
+tests/examples/tests/test_simple_time_contract.py,sha256=HQCJNheFyaHh73jZHyGOhNItzg045o8XsW-jLnNp-xc,3199
 tests/examples/tests/test_storage.py,sha256=y46nPjM-Jd9FVJmaNE29RPqamzxVwYtPPWE_GlXUsls,774
 tests/examples/tests/test_user_storage.py,sha256=wk0r0AXfKNgI7Eeyc8noNlJKvZBFXDbXTQE_u19XxBQ,2927
 tests/examples/tests/test_wizard_of_coin.py,sha256=AOQTanDsfZt9zIGkqZass_4BsGcVKTHzqRejN4KhSPI,854
@@ -70,8 +75,8 @@ tests/gltest_cli/config/test_config_integration.py,sha256=vPTzr3_h9UMw7m72HogBJE
 tests/gltest_cli/config/test_general_config.py,sha256=UHtSwVnso-ZwNtYM0Z4v2sCLKwyrVbHlk6b1leVfV84,14703
 tests/gltest_cli/config/test_plugin.py,sha256=COrEK5tHP1BSzanWbZHmN3EQgE9VuTcPvB95pgOvKS4,7974
 tests/gltest_cli/config/test_user.py,sha256=JxR655oUFoM9quWQO68CVPKRpT0TMpzS3bF6j6NWyT4,14401
-genlayer_test-0.6.0.dist-info/METADATA,sha256=uHgafSUvII1G16UbdZ-26QwmtaV86EX1Pk-VwXsZAxs,32466
-genlayer_test-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-genlayer_test-0.6.0.dist-info/entry_points.txt,sha256=RWPcSArBpz_G4BYioh5L8Q8hyClRbSgzLimjcWMp-BQ,94
-genlayer_test-0.6.0.dist-info/top_level.txt,sha256=-qiGZxTRBytujzgVcKpxjvQ-WNeUDjXa59ceGMwMpko,24
-genlayer_test-0.6.0.dist-info/RECORD,,
+genlayer_test-0.8.0.dist-info/METADATA,sha256=6LQF4o37U3qg9rmmLLoZps0XpC0T5gFsg_l4NZr7z4g,39178
+genlayer_test-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+genlayer_test-0.8.0.dist-info/entry_points.txt,sha256=RWPcSArBpz_G4BYioh5L8Q8hyClRbSgzLimjcWMp-BQ,94
+genlayer_test-0.8.0.dist-info/top_level.txt,sha256=-qiGZxTRBytujzgVcKpxjvQ-WNeUDjXa59ceGMwMpko,24
+genlayer_test-0.8.0.dist-info/RECORD,,

gltest/__init__.py

@@ -8,6 +8,8 @@ from gltest.clients import (
     get_gl_client,
 )
 from gltest.contracts import get_contract_factory
+from gltest.validators import get_validator_factory
+
 
 __all__ = [
     "create_account",
@@ -16,4 +18,5 @@ __all__ = [
     "get_gl_client",
     "get_accounts",
     "get_default_account",
+    "get_validator_factory",
 ]

gltest/contracts/contract.py

@@ -7,7 +7,9 @@ from gltest.types import (
     GenLayerTransaction,
     TransactionStatus,
     TransactionHashVariant,
+    TransactionContext,
 )
+from genlayer_py.types import SimConfig
 from typing import List, Any, Optional, Dict, Callable
 from gltest_cli.config.general import get_general_config
 from .contract_functions import ContractFunction
@@ -25,14 +27,24 @@ def read_contract_wrapper(
 
     def call_method(
         transaction_hash_variant: TransactionHashVariant = TransactionHashVariant.LATEST_NONFINAL,
+        transaction_context: Optional[TransactionContext] = None,
     ):
         client = get_gl_client()
+        sim_config = None
+        if transaction_context:
+            try:
+                sim_config = SimConfig(**transaction_context)
+            except TypeError as e:
+                raise ValueError(
+                    f"Invalid transaction_context keys: {sorted(transaction_context.keys())}"
+                ) from e
         return client.read_contract(
             address=self.address,
             function_name=method_name,
             account=self.account,
             args=args,
             transaction_hash_variant=transaction_hash_variant,
+            sim_config=sim_config,
         )
 
     return ContractFunction(
@@ -59,6 +71,7 @@ def write_contract_wrapper(
         wait_retries: Optional[int] = None,
         wait_triggered_transactions: bool = False,
         wait_triggered_transactions_status: TransactionStatus = TransactionStatus.ACCEPTED,
+        transaction_context: Optional[TransactionContext] = None,
     ):
         """
         Transact the contract method.
@@ -80,6 +93,14 @@ def write_contract_wrapper(
             else False
         )
         client = get_gl_client()
+        sim_config = None
+        if transaction_context:
+            try:
+                sim_config = SimConfig(**transaction_context)
+            except TypeError as e:
+                raise ValueError(
+                    f"Invalid transaction_context keys: {sorted(transaction_context.keys())}"
+                ) from e
         tx_hash = client.write_contract(
             address=self.address,
             function_name=method_name,
@@ -88,6 +109,7 @@ def write_contract_wrapper(
             consensus_max_rotations=consensus_max_rotations,
             leader_only=leader_only,
             args=args,
+            sim_config=sim_config,
         )
         receipt = client.wait_for_transaction_receipt(
             transaction_hash=tx_hash,
@@ -113,6 +135,7 @@ def write_contract_wrapper(
         plugin: Optional[str] = None,
         plugin_config: Optional[Dict[str, Any]] = None,
         runs: int = 100,
+        genvm_datetime: Optional[str] = None,
     ):
         """
         Analyze the contract method using StatsCollector.
@@ -129,6 +152,7 @@ def write_contract_wrapper(
             config=config,
             plugin=plugin,
             plugin_config=plugin_config,
+            genvm_datetime=genvm_datetime,
         )
         sim_results = collector.run_simulations(sim_config, runs)
         return collector.analyze_results(sim_results, runs, sim_config)

gltest/contracts/contract_factory.py

@@ -15,6 +15,7 @@ from gltest.clients import (
     get_gl_hosted_studio_client,
     get_local_client,
 )
+from genlayer_py.types import SimConfig
 from .contract import Contract
 from gltest.logging import logger
 from gltest.types import TransactionStatus, GenLayerTransaction, CalldataEncodable
@@ -22,6 +23,7 @@ from gltest.assertions import tx_execution_failed
 from gltest.exceptions import DeploymentError
 from gltest_cli.config.general import get_general_config
 from gltest.utils import extract_contract_address
+from gltest.types import TransactionContext
 
 
 @dataclass
@@ -113,6 +115,7 @@ class ContractFactory:
         wait_transaction_status: TransactionStatus = TransactionStatus.ACCEPTED,
         wait_triggered_transactions: bool = False,
         wait_triggered_transactions_status: TransactionStatus = TransactionStatus.ACCEPTED,
+        transaction_context: Optional[TransactionContext] = None,
     ) -> Contract:
         """
         Deploy the contract and return a Contract instance (convenience method).
@@ -129,6 +132,7 @@ class ContractFactory:
             wait_transaction_status=wait_transaction_status,
             wait_triggered_transactions=wait_triggered_transactions,
             wait_triggered_transactions_status=wait_triggered_transactions_status,
+            transaction_context=transaction_context,
         )
 
         if tx_execution_failed(receipt):
@@ -147,6 +151,7 @@ class ContractFactory:
         wait_transaction_status: TransactionStatus = TransactionStatus.ACCEPTED,
         wait_triggered_transactions: bool = False,
         wait_triggered_transactions_status: TransactionStatus = TransactionStatus.ACCEPTED,
+        transaction_context: Optional[TransactionContext] = None,
     ) -> GenLayerTransaction:
         """
         Deploy the contract and return the transaction receipt.
@@ -170,12 +175,21 @@ class ContractFactory:
 
         client = get_gl_client()
         try:
+            sim_config = None
+            if transaction_context:
+                try:
+                    sim_config = SimConfig(**transaction_context)
+                except TypeError as e:
+                    raise ValueError(
+                        f"Invalid transaction_context keys: {sorted(transaction_context.keys())}"
+                    ) from e
             tx_hash = client.deploy_contract(
                 code=self.contract_code,
                 args=args,
                 account=account,
                 consensus_max_rotations=consensus_max_rotations,
                 leader_only=leader_only,
+                sim_config=sim_config,
             )
             tx_receipt = client.wait_for_transaction_receipt(
                 transaction_hash=tx_hash,

gltest/contracts/contract_functions.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from typing import Callable, Optional, Dict, Any
-from gltest.types import TransactionStatus, TransactionHashVariant
+from gltest.types import TransactionStatus, TransactionHashVariant, TransactionContext
 
 
 @dataclass
@@ -14,10 +14,14 @@ class ContractFunction:
     def call(
         self,
         transaction_hash_variant: TransactionHashVariant = TransactionHashVariant.LATEST_NONFINAL,
+        transaction_context: Optional[TransactionContext] = None,
     ):
         if not self.read_only:
             raise ValueError("call() not implemented for non-readonly method")
-        return self.call_method(transaction_hash_variant=transaction_hash_variant)
+        return self.call_method(
+            transaction_hash_variant=transaction_hash_variant,
+            transaction_context=transaction_context,
+        )
 
     def transact(
         self,
@@ -28,6 +32,7 @@ class ContractFunction:
         wait_retries: Optional[int] = None,
         wait_triggered_transactions: bool = False,
         wait_triggered_transactions_status: TransactionStatus = TransactionStatus.ACCEPTED,
+        transaction_context: Optional[TransactionContext] = None,
     ):
         if self.read_only:
             raise ValueError("Cannot transact read-only method")
@@ -39,6 +44,7 @@ class ContractFunction:
             wait_retries=wait_retries,
             wait_triggered_transactions=wait_triggered_transactions,
             wait_triggered_transactions_status=wait_triggered_transactions_status,
+            transaction_context=transaction_context,
         )
 
     def analyze(
@@ -49,6 +55,7 @@ class ContractFunction:
         plugin: Optional[str] = None,
         plugin_config: Optional[Dict[str, Any]] = None,
         runs: int = 100,
+        genvm_datetime: Optional[str] = None,
     ):
         if self.read_only:
             raise ValueError("Cannot analyze read-only method")
@@ -59,4 +66,5 @@ class ContractFunction:
             plugin=plugin,
             plugin_config=plugin_config,
             runs=runs,
+            genvm_datetime=genvm_datetime,
         )

gltest/contracts/stats_collector.py

@@ -29,6 +29,7 @@ class SimulationConfig:
     config: Optional[Dict[str, Any]] = None
     plugin: Optional[str] = None
     plugin_config: Optional[Dict[str, Any]] = None
+    genvm_datetime: Optional[str] = None
 
 
 @dataclass
@@ -103,7 +104,12 @@ class StatsCollector:
         self, sim_config: SimulationConfig
     ) -> Dict[str, Any]:
         """Execute a single simulation."""
-        config_dict = {
+        config_dict = {}
+
+        if sim_config.genvm_datetime is not None:
+            config_dict["genvm_datetime"] = sim_config.genvm_datetime
+
+        validator_info = {
             "provider": sim_config.provider,
             "model": sim_config.model,
         }
@@ -113,9 +119,10 @@ class StatsCollector:
             and sim_config.plugin is not None
             and sim_config.plugin_config is not None
         ):
-            config_dict["config"] = sim_config.config
-            config_dict["plugin"] = sim_config.plugin
-            config_dict["plugin_config"] = sim_config.plugin_config
+            validator_info["config"] = sim_config.config
+            validator_info["plugin"] = sim_config.plugin
+            validator_info["plugin_config"] = sim_config.plugin_config
+        config_dict["validators"] = [validator_info]
 
         return self.client.simulate_write_contract(
             address=self.contract_address,

gltest/types.py

@@ -6,3 +6,32 @@ from genlayer_py.types import (
     CalldataEncodable,
     TransactionHashVariant,
 )
+from typing import List, TypedDict, Dict, Any
+
+
+class MockedLLMResponse(TypedDict):
+    """Maps prompts to responses"""
+
+    # Prompt -> raw JSON string response
+    nondet_exec_prompt: Dict[str, str]
+
+    # Principle -> expected boolean
+    eq_principle_prompt_comparative: Dict[str, bool]
+    eq_principle_prompt_non_comparative: Dict[str, bool]
+
+
+class ValidatorConfig(TypedDict):
+    """Validator information."""
+
+    provider: str
+    model: str
+    config: Dict[str, Any]
+    plugin: str
+    plugin_config: Dict[str, Any]
+
+
+class TransactionContext(TypedDict, total=False):
+    """Context for transaction operations."""
+
+    validators: List[ValidatorConfig]  # List to create virtual validators
+    genvm_datetime: str  # ISO format datetime string

gltest/validators/__init__.py

@@ -0,0 +1,3 @@
+from .validator_factory import ValidatorFactory, Validator, get_validator_factory
+
+__all__ = ["ValidatorFactory", "Validator", "get_validator_factory"]

gltest/validators/validator_factory.py

@@ -0,0 +1,136 @@
+from gltest.types import MockedLLMResponse
+from dataclasses import dataclass
+from typing import Dict, Any, Optional, List
+from copy import deepcopy
+
+
+@dataclass
+class Validator:
+    stake: int
+    provider: str
+    model: str
+    config: Dict[str, Any]
+    plugin: str
+    plugin_config: Dict[str, Any]
+
+    # Mock configuration
+    mock_enabled: bool
+    mock_llm_response: Optional[MockedLLMResponse]
+
+    def to_dict(self) -> Dict[str, Any]:
+        normal_config = {
+            "stake": self.stake,
+            "provider": self.provider,
+            "model": self.model,
+            "config": deepcopy(self.config),
+            "plugin": self.plugin,
+            "plugin_config": deepcopy(self.plugin_config),
+        }
+        if not self.mock_enabled:
+            return normal_config
+
+        mock = self.mock_llm_response or {}
+        mock_config = {
+            "response": mock.get("nondet_exec_prompt", {}),
+            "eq_principle_prompt_comparative": mock.get(
+                "eq_principle_prompt_comparative", {}
+            ),
+            "eq_principle_prompt_non_comparative": mock.get(
+                "eq_principle_prompt_non_comparative", {}
+            ),
+        }
+        return {
+            **normal_config,
+            "plugin_config": {
+                **self.plugin_config,
+                "mock_response": mock_config,
+            },
+        }
+
+    def batch_clone(self, count: int) -> List["Validator"]:
+        return [self.clone() for _ in range(count)]
+
+    def clone(self) -> "Validator":
+        return Validator(
+            stake=self.stake,
+            provider=self.provider,
+            model=self.model,
+            config=deepcopy(self.config),
+            plugin=self.plugin,
+            plugin_config=deepcopy(self.plugin_config),
+            mock_enabled=self.mock_enabled,
+            mock_llm_response=deepcopy(self.mock_llm_response),
+        )
+
+
+class ValidatorFactory:
+    def __init__(self):
+        pass
+
+    def create_validator(
+        self,
+        stake: int,
+        provider: str,
+        model: str,
+        config: Dict[str, Any],
+        plugin: str,
+        plugin_config: Dict[str, Any],
+    ) -> Validator:
+        return Validator(
+            stake=stake,
+            provider=provider,
+            model=model,
+            config=deepcopy(config),
+            plugin=plugin,
+            plugin_config=deepcopy(plugin_config),
+            mock_enabled=False,
+            mock_llm_response=None,
+        )
+
+    def batch_create_validators(
+        self,
+        count: int,
+        stake: int,
+        provider: str,
+        model: str,
+        config: Dict[str, Any],
+        plugin: str,
+        plugin_config: Dict[str, Any],
+    ) -> List[Validator]:
+        return [
+            self.create_validator(
+                stake=stake,
+                provider=provider,
+                model=model,
+                config=config,
+                plugin=plugin,
+                plugin_config=plugin_config,
+            )
+            for _ in range(count)
+        ]
+
+    def create_mock_validator(self, mock_llm_response: MockedLLMResponse) -> Validator:
+        return Validator(
+            stake=8,
+            provider="openai",
+            model="gpt-4o",
+            config={"temperature": 0.75, "max_tokens": 500},
+            plugin="openai-compatible",
+            plugin_config={
+                "api_key_env_var": "OPENAIKEY",
+                "api_url": "https://api.openai.com",
+            },
+            mock_enabled=True,
+            mock_llm_response=deepcopy(mock_llm_response),
+        )
+
+    def batch_create_mock_validators(
+        self,
+        count: int,
+        mock_llm_response: MockedLLMResponse,
+    ) -> List[Validator]:
+        return [self.create_mock_validator(mock_llm_response) for _ in range(count)]
+
+
+def get_validator_factory() -> ValidatorFactory:
+    return ValidatorFactory()

tests/examples/contracts/simple_time_contract.py

@@ -0,0 +1,85 @@
+# {
+#   "Seq": [
+#     { "Depends": "py-lib-genlayer-embeddings:09h0i209wrzh4xzq86f79c60x0ifs7xcjwl53ysrnw06i54ddxyi" },
+#     { "Depends": "py-genlayer:1j12s63yfjpva9ik2xgnffgrs6v44y1f52jvj9w7xvdn7qckd379" }
+#   ]
+# }
+
+from datetime import datetime, timezone
+from genlayer import *
+
+
+class SimpleTimeContract(gl.Contract):
+    """
+    A simple contract that demonstrates time-based function availability.
+    """
+
+    start_date: str  # ISO format datetime string
+    data: str
+    is_active: bool
+
+    def __init__(self, start_datetime_iso: str):
+        """
+        Initialize the contract with a required start date (ISO 8601).
+        """
+        self.start_date = start_datetime_iso
+        self.is_active = False
+        self.data = ""
+
+    def _days_since_start(self) -> int:
+        """Calculate days elapsed since start date."""
+        current = datetime.now(timezone.utc)
+        start = datetime.fromisoformat(self.start_date)
+        print(f"Current: {current}, Start: {start}")
+        delta = current - start
+        print(f"Delta: {delta}")
+        return delta.days
+
+    @gl.public.write
+    def activate(self):
+        """
+        Activate the contract.
+        Only works if current date is after start date.
+        """
+        days = self._days_since_start()
+
+        if days < 0:
+            raise ValueError(
+                f"Cannot activate before start date. Days until start: {abs(days)}"
+            )
+
+        self.is_active = True
+
+    @gl.public.write
+    def set_data(self, value: str):
+        """
+        Set data in the contract.
+        Only works if contract is active and within 30 days of start.
+        """
+        if not self.is_active:
+            raise ValueError("Contract must be activated first")
+
+        days = self._days_since_start()
+
+        if days > 30:
+            raise ValueError(
+                f"Function expired. Was available for 30 days after start, now at day {days}"
+            )
+
+        self.data = value
+
+    @gl.public.view
+    def get_status(self) -> dict:
+        """Get current contract status."""
+        days = self._days_since_start()
+        current = datetime.now(timezone.utc)
+
+        return {
+            "start_date": self.start_date,
+            "current_time": current.isoformat(),
+            "days_since_start": days,
+            "is_active": self.is_active,
+            "data": self.data,
+            "can_activate": days >= 0 and not self.is_active,
+            "can_set_data": self.is_active and 0 <= days <= 30,
+        }

tests/examples/tests/test_custom_validators.py

@@ -0,0 +1,65 @@
+from gltest import get_contract_factory
+from gltest.assertions import tx_execution_succeeded
+from gltest import get_validator_factory
+from gltest.types import MockedLLMResponse
+import json
+
+
+def test_custom_validators():
+
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_validators(
+        count=5,
+        stake=8,
+        provider="openai",
+        model="gpt-4o",
+        config={"temperature": 0.75, "max_tokens": 500},
+        plugin="openai-compatible",
+        plugin_config={
+            "api_key_env_var": "OPENAIKEY",
+            "api_url": "https://api.openai.com",
+        },
+    )
+
+    factory = get_contract_factory("WizardOfCoin")
+    contract = factory.deploy(
+        args=[True],
+        transaction_context={"validators": [v.to_dict() for v in validators]},
+    )
+
+    transaction_response_call_1 = contract.ask_for_coin(
+        args=["Can you please give me my coin?"]
+    ).transact(transaction_context={"validators": [v.to_dict() for v in validators]})
+    assert tx_execution_succeeded(transaction_response_call_1)
+
+
+def test_custom_mocked_validators():
+    mock_llm_response: MockedLLMResponse = {
+        "nondet_exec_prompt": {
+            "wizard": json.dumps(
+                {
+                    "reasoning": "I am a grumpy wizard and I never give away my coins!",
+                    "give_coin": False,
+                }
+            ),
+        },
+        "eq_principle_prompt_comparative": {
+            "The value of give_coin has to match": True
+        },
+    }
+    validator_factory = get_validator_factory()
+    validators = validator_factory.batch_create_mock_validators(
+        count=5,
+        mock_llm_response=mock_llm_response,
+    )
+
+    factory = get_contract_factory("WizardOfCoin")
+    contract = factory.deploy(
+        args=[True],
+        transaction_context={"validators": [v.to_dict() for v in validators]},
+    )
+
+    transaction_response_call_1 = contract.ask_for_coin(
+        args=["Can you please give me my coin?"]
+    ).transact(transaction_context={"validators": [v.to_dict() for v in validators]})
+    assert tx_execution_succeeded(transaction_response_call_1)

tests/examples/tests/test_llm_erc20_analyze.py

@@ -1,4 +1,5 @@
 from gltest import get_contract_factory, get_default_account, create_account
+from datetime import datetime, timezone
 
 
 TOKEN_TOTAL_SUPPLY = 1000
@@ -21,7 +22,10 @@ def test_llm_erc20_analyze(setup_validators):
 
     # Transfer from User A to User B
     stats = contract.transfer(args=[TRANSFER_AMOUNT, from_account_b.address]).analyze(
-        provider="openai", model="gpt-4o", runs=3
+        provider="openai",
+        model="gpt-4o",
+        runs=3,
+        genvm_datetime=datetime.now(timezone.utc).isoformat(),
     )
 
     # Verify it's a MethodStatsSummary object

tests/examples/tests/test_simple_time_contract.py

@@ -0,0 +1,90 @@
+from gltest import get_contract_factory
+from datetime import datetime, timedelta, timezone
+from gltest.assertions import tx_execution_succeeded, tx_execution_failed
+
+
+def test_simple_time_contract():
+    """Test all time-based functionality in a single comprehensive test."""
+
+    factory = get_contract_factory("SimpleTimeContract")
+
+    # Test 1: Deploy with past start date (10 days ago)
+    now = datetime.now(timezone.utc)
+    past_date = (now - timedelta(days=10)).isoformat()
+    contract = factory.deploy(args=[past_date])
+
+    # Test 1: Check initial status (10 days after start)
+    status = contract.get_status().call()
+    assert status["is_active"] == False
+    assert status["days_since_start"] == 10
+    assert status["can_activate"] == True
+
+    # Test 2: Try to activate before start date (simulate going back in time)
+    before_start_date = now - timedelta(days=15)  # 5 days before start
+    before_start_date_receipt = contract.activate().transact(
+        transaction_context={
+            "genvm_datetime": before_start_date.isoformat(),
+        },
+    )
+    assert tx_execution_failed(before_start_date_receipt)
+
+    # Test 3: Activate after start date
+    activate_date = now - timedelta(days=5)  # 5 days after start (15 days ago + 10)
+    activate_receipt = contract.activate().transact(
+        transaction_context={
+            "genvm_datetime": activate_date.isoformat(),
+        },
+    )
+    assert tx_execution_succeeded(activate_receipt)
+
+    # Test 4: Verify activation and check status
+    status = contract.get_status().call(
+        transaction_context={
+            "genvm_datetime": activate_date.isoformat(),
+        },
+    )
+    assert status["is_active"] == True
+    assert status["days_since_start"] == 5
+    assert status["can_set_data"] == True
+
+    # Test 5: Set data within valid period (within 30 days)
+    set_data_date = now - timedelta(days=2)  # 8 days after start
+    test_data = "Test data within valid period"
+    set_data_receipt = contract.set_data(
+        args=[test_data],
+    ).transact(
+        transaction_context={
+            "genvm_datetime": set_data_date.isoformat(),
+        }
+    )
+    assert tx_execution_succeeded(set_data_receipt)
+
+    # Test 6: Verify data was set
+    status = contract.get_status().call(
+        transaction_context={
+            "genvm_datetime": set_data_date.isoformat(),
+        },
+    )
+    assert status["data"] == test_data
+    assert status["days_since_start"] == 8
+
+    # Test 7: Try to set data after 30 days (should fail)
+    expired_date = now + timedelta(days=25)  # 35 days after start
+    expired_date_receipt = contract.set_data(
+        args=["Should fail - expired"],
+    ).transact(
+        transaction_context={
+            "genvm_datetime": expired_date.isoformat(),
+        }
+    )
+    assert tx_execution_failed(expired_date_receipt)
+
+    # Test 8: Check status shows expired
+    status = contract.get_status().call(
+        transaction_context={
+            "genvm_datetime": expired_date.isoformat(),
+        },
+    )
+    assert status["is_active"] == True  # Still active
+    assert status["can_set_data"] == False  # But can't set data
+    assert status["days_since_start"] == 35