Package vbase-py
vbase
A Python library for interacting with the validityBase (vBase) platform
class vbase.ForwarderCommitmentService(endpoint_url: str, api_key: str, private_key: str | None = None, commitment_service_json_file_name: str | None = 'CommitmentService.json')
Bases: Web3CommitmentService
Commitment service accessible using a forwarder API endpoint.
add_object(object_cid: str)
Record an object commitment. This is a low-level function that operates on object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: object_cid – The CID identifying the object.
Returns: The commitment log containing commitment receipt info.
add_set(set_cid: str)
Records a set commitment. This is a low-level function that operates on set hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: set_cid – The CID identifying the set.
Returns: The commitment log containing commitment receipt info.
add_set_object(set_cid: str, object_cid: str)
Records a commitment for an object belonging to a set of objects. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The CID for the set containing the object.
object_cid – The object hash to record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_batch(set_cid: str, object_cids: List[str])
Records a batch of commitments for objects belonging to a set. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The hashes of the sets containing the objects.
object_cids – The hashes to record.
Returns: The commitment logs containing commitment receipts.
add_sets_objects_batch(set_cids: List[str], object_cids: List[str])
Records a batch of commitments for objects belonging to sets. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
Returns: The commitment logs containing commitment receipts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The dictionary of arguments.
static get_init_args_from_env(dotenv_path: str | None = None)
Worker function to load the environment variables.
Parameters: dotenv_path – The .env file path, if any.
Returns: The dictionary of construction arguments.
user_set_exists(user: str, set_cid: str)
Checks whether a given set exists for a user.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID identifying the set.
Returns: True if the set exists for the user; False otherwise.
verify_user_object(user: str, object_cid: str, timestamp: str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
object_cid – The CID identifying the object.
timestamp – The timestamp of the commitment.
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_set_objects(user: str, set_cid: str, user_set_object_cid_sum: str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID for the set containing the object.
user_set_object_cid_sum – The sum of all object hashes for the user set
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_sets(user: str, user_set_cid_sum: str)
Verifies set commitments previously recorded by the user. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
user_set_cid_sum – The sum of all set hashes for the user.
Returns: True if the commitment has been verified successfully; False otherwise.
class vbase.ForwarderCommitmentServiceTest(endpoint_url: str, api_key: str, private_key: str | None = None, commitment_service_json_file_name: str | None = 'CommitmentServiceTest.json')
Bases: ForwarderCommitmentService, CommitmentServiceTest
Test commitment service accessible using a forwarder API endpoint.
add_object_with_timestamp(object_cid: str, timestamp: str)
Test shim to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
object_cid – The CID identifying the object.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_object_with_timestamp(set_cid: str, object_cid: str, timestamp: str)
Test shim to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the object.
object_cid – The CID to record.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_with_timestamps_batch(set_cid: str, object_cids: List[str], timestamps: List[str])
Test shim to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment logs containing commitment receipts.
add_sets_objects_with_timestamps_batch(set_cids: List[str], object_cids: List[str], timestamps: List[str])
Test shim to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment logs containing commitment receipts.
clear_set_objects(set_cid: str)
Clear all records (objects) for a user’s set. Used to clear state when testing. Only supported by test contracts.
Parameters: set_cid – Hash identifying the set.
clear_sets()
Clear all sets for the user. Used to clear state when testing. Only supported by test contracts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The dictionary of arguments.
class vbase.MongoUtils(dotenv_path: str | None = None)
Bases: object
vBase MongoDB client wrapper Abstracts common vBase data availability layer operations.
get_commitment_service_addr(network: str = 'localhost', commitment_service_contract_name: str = 'CommitmentServiceTest')
Get the CommitmentService contract address from MongoDB.
Parameters:
network – The CommitmentService contract network name.
commitment_service_contract_name – The CommitmentService contract class name.
Returns: The CommitmentService contract address.
static get_dict_ds_filter(dict_ds: dict)
Get filter for a dataset.
Parameters: dict_ds – The dictionary representation of the dataset.
Returns: The dictionary with the filter fields of the dataset that uniquely identify it.
read_ds_dict(dict_ds_filter: dict)
Write a dataset to MongoDB.
Parameters: dict_ds_filter – The dictionary filter for the dataset.
write_ds_dict(dict_ds: dict)
Write a dataset to MongoDB.
Parameters: dict_ds – The dictionary representation of the dataset.
class vbase.VBaseClient(commitment_service: CommitmentService)
Bases: object
Provides Python validityBase (vBase) access.
add_named_set(name: str)
Creates a commitment for a set with a given name. This function abstracts the low-level commitment of set creation.
Parameters: name – The name of the set.
Returns: The commitment log containing commitment receipt info.
add_object(object_cid: str)
Record an object commitment. This is a low-level function that operates on object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: object_cid – The CID identifying the object.
Returns: The commitment log containing commitment receipt info.
add_set(set_cid: str)
Records a set commitment. This is a low-level function that operates on set hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: set_cid – The CID (hash) identifying the set.
Returns: The commitment log containing commitment receipt info.
add_set_object(set_cid: str, object_cid: str)
Records a commitment for an object belonging to a set of objects. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The CID for the set containing the object.
object_cid – The object hash to record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_batch(set_cid: str, object_cids: List[str])
Records a batch of commitments for objects belonging to a set. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The CID of the set containing the objects.
object_cids – The hashes to record.
Returns: The commitment log list containing commitment receipts.
add_sets_objects_batch(set_cids: List[str], object_cids: List[str])
Records a batch of commitments for objects belonging to sets. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
Returns: The commitment log list containing commitment receipts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The constructed vBase client object.
get_default_user()
Return the default user address used in vBase transactions.
Returns: The default user address used in vBase transactions.
get_named_set_cid(name: str)
Converts a set name to a hash. Abstracts the hashing implementation from the upper layers.
Parameters: name – The name of the set.
Returns: The CID for the name.
get_sim_t()
Get the simulation timestamp.
Returns: If in simulation, the sim timestamp; None otherwise.
in_sim()
Get the simulation state.
Returns: True if vBase is in a simulation; False otherwise.
run_pit_sim(ts: DatetimeIndex, callback: Callable[[], int | float | dict | DataFrame])
Runs a point-in-time (PIT) simulation. PIT simulation executes callback for each t specified letting the callback see world state as it existed at that t.
Parameters:
ts – Times/timestamps for which callback should be called and PIT world state simulated.
callback – The callback to call.
Returns: The aggregated output of all callback invocations.
user_named_set_exists(user: str, name: str)
Checks whether a set with a given name exists for the calling user. This function abstracts the low-level commitment of named set creation.
Parameters:
user – The address for the user who recorded the commitment.
name – The name of the set.
Returns: True if the set with the given name exists; False otherwise.
user_set_exists(user: str, set_cid: str)
Checks whether a given set exists for the calling user. This function abstracts the low-level commitment of named set creation.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID (hash) identifying the set.
Returns: True if the set with the given hash exists; False otherwise.
verify_user_named_sets(user: str, names: List[str])
Verifies the completeness of a list of named sets.
Parameters:
user – Address for the user who recorded the commitment.
names – Names of user sets.
Returns: True if the names comprise all named sets committed by the user; False otherwise.
verify_user_object(user: str, object_cid: str, timestamp: Timestamp | str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
object_cid – The CID identifying the object.
timestamp – The timestamp of the commitment.
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_set_objects(user: str, set_cid: str, user_set_objects_cid_sum: str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID for the set containing the object.
user_set_objects_cid_sum – The sum of all object hashes for the user set
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_sets(user: str, user_sets_cid_sum: str)
Verifies set commitments previously recorded by the user. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
user_sets_cid_sum – The sum of all set hashes for the user.
Returns: True if the commitment has been verified successfully; False otherwise.
class vbase.VBaseClientTest(commitment_service: CommitmentServiceTest)
Bases: VBaseClient
Provides Python validityBase (vBase) access with test methods. Test methods allow clearing state and bootstrapping objects with pre-defined timestamps.
add_object_with_timestamp(object_cid: str, timestamp: Timestamp | str)
Test method to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
object_cid – The CID identifying the object.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_object_with_timestamp(set_cid: str, object_cid: str, timestamp: Timestamp | str)
Test method to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the object.
object_cid – The CID to record.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_with_timestamps_batch(set_cid: str, object_cids: List[str], timestamps: List[Timestamp])
Test method to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment log list containing commitment receipts.
add_sets_objects_with_timestamps_batch(set_cids: List[str], object_cids: List[str], timestamps: List[Timestamp])
Test method to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment log list containing commitment receipts.
clear_named_set_objects(name: str)
Clear all records (objects) for a user’s named set.
Parameters: name – Name of the set to clear.
clear_set_objects(set_cid: str)
Clear all records (objects) for a user’s set. Used to clear state when testing. Only supported by test contracts.
Parameters: set_cid – Hash identifying the set.
clear_sets()
Clear all sets for the user. Used to clear state when testing. Only supported by test contracts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The constructed vBase client object.
static normalize_pd_timestamp(timestamp: Timestamp | str)
Normalize Pandas timestamp converting it to a string representation that is serializable.
Parameters: timestamp – A representation of a pd.Timestamp object.
Returns: The string representation of a pd.Timestamp.
class vbase.VBaseDataset(vbc: VBaseClient | VBaseClientTest, name: str | None = None, record_type: Type[VBaseObject] | None = None, init_dict: dict | None = None, init_json: str | None = None)
Bases: ABC
Provides Python vBase dataset access. Implements base functionality shared across datasets regardless of record type. Record-specific logic is implemented in the record class.
add_record(record_data: any)
Add a record to a VBaseDataset object.
Parameters: record_data – The record datum.
Returns: The commitment log containing commitment receipt info.
add_record_with_timestamp(record_data: any, timestamp: Timestamp | str)
Test shim to add a record to a VBaseDataset object with a given timestamp. Only supported by test contracts.
Parameters:
record_data – The record datum.
timestamp – Timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_records_batch(record_data_list: List[any])
Add a list of records to a VBaseDataset object. This function will typically be called to backfill a dataset history:
Producer creates records for 1/1, 1/2, 1/3.
On 1/4 methodology changes.
Producer back-fills history for 1/1, 1/2, 1/3 and adds their commitments.
Parameters: record_data_list – The list of records’ data.
Returns: The commitment log list containing commitment receipts.
add_records_with_timestamps_batch(record_data_list: List[any], timestamps: List[Timestamp | str])
Test shim to add a batch of records with timestamps to a VBaseDataset object. Only supported by test contracts.
Parameters:
record_data_list – The list of records’ data.
timestamps – The list of timestamps to force for the records.
Returns: The commitment log list containing commitment receipts.
get_last_record()
Get the last/latest record for the dataset.
Returns: The last/latest record prior to the current time:
If not in a simulation, this is the last known record.
If within a simulation, this is the last record with a timestamp less than or equal to the sim t.
If all records are after the current time, returns None.
get_last_record_data()
Get the last/latest record’s data for the dataset.
Returns: The last/latest record data prior to the current time using get_last_record() semantics.
get_records()
Get all records for the dataset.
Returns: All record up to the current time:
If not in a simulation, returns all records.
If within a simulation, returns records with a timestamp less than or equal to the sim t.
If all records are after the current time, returns None.
static get_set_cid_for_dataset(dataset_name: str)
Generate set hash for a named dataset. May be called to post commitments without instantiating a dataset object.
Parameters: dataset_name – The dataset name.
Returns: The CID for the dataset.
get_timestamps()
Get all record timestamps.
Returns: The timestamps for all dataset records.
to_dict()
Return dictionary representation of the dataset.
Returns: The dictionary representation of the dataset.
to_json()
Return JSON representation of the dataset.
Returns: The JSON representation of the dataset.
to_pd_object()
Convert dataset to a Pandas object. This default method works for most datasets. Datasets that need special handling will override this method.
Returns: The pd.Series object representing the dataset.
verify_commitments() -> (<class 'bool'>, typing.List[str])
Verify commitments for all dataset records.
Returns: A tuple containing success and log:
success: true if all record commitments have been verified; false otherwise
l_log: a list log of verification explaining any failures
class vbase.VBaseDatasetAsync(vbc: VBaseClient | VBaseClientTest, name: str | None = None, record_type: Type[VBaseObject] | None = None, init_dict: dict | None = None, init_json: str | None = None)
Bases: VBaseDataset
Provides Python vBase dataset async access. Asynchronous dataset wraps synchronous dataset object to support async operations using asyncio.
async add_record_async(record_data: any)
Add a record to a VBase dataset object asynchronously. Offloads add_record execution to the default event loop’s executor.
Parameters: record_data – The record datum.
Returns: The commitment log containing commitment receipt info.
async add_record_with_timestamp_async(record_data: any, timestamp: Timestamp | str)
Test shim to add a record to a VBaseDataset object with a given timestamp asynchronously. Only supported by test contracts. Offloads add_record_with_timestamp execution to the default event loop’s executor.
Parameters:
record_data – The record datum.
timestamp – Timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
async add_records_batch_async(record_data_list: List[any])
Add a record to a VBase dataset object asynchronously. Offloads add_record execution to the default event loop’s executor.
Parameters: record_data_list – The list of records’ data.
Returns: The commitment log list containing commitment receipts.
async add_records_with_timestamps_batch_async(record_data_list: List[any], timestamps: List[Timestamp | str])
Test shim to add a batch of records with timestamps to a VBaseDataset object asynchronously. Only supported by test contracts. Offloads add_records_with_timestamps_batch execution to the default event loop’s executor.
Parameters:
record_data_list – The list of records’ data.
timestamps – The list of timestamps to force for the records.
Returns: The commitment log list containing commitment receipts.
async classmethod create(*args, **kwargs)
Creates a vBase dataset object asynchronously. A static async factory method that delegates to the synchronous constructor. Offloads VBaseDataset constructor execution to the default event loop’s executor.
Parameters:
args – Arguments passed to the VBaseDataset constructor.
kwargs – Arguments passed to the VBaseDataset constructor.
Returns: The created dataset.
async verify_commitments_async() -> (<class 'bool'>, typing.List[str])
Verify commitments for all dataset records asynchronously. Offloads verify_commitments execution to the default event loop’s executor.
Returns: A tuple containing success and log:
success: true if all record commitments have been verified; false otherwise
l_log: a list log of verification explaining any failures
class vbase.VBaseFloatObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
A float object Floats are committed as fixed-point integers to support ZKPs.
cid : str | None
data : Any
static get_cid_for_data(record_data: float)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBaseIntObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
An integer object
cid : str | None
data : Any
static get_cid_for_data(record_data: int)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBaseJsonObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
A JSON string object
cid : str | None
data : Any
static get_cid_for_data(record_data: str)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBaseObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: ABC
Provides basic Python vBase object features. Implements base functionality shared across various objects and dataset records. Children implement object-specific logic.
cid : str | None
data : Any
get_cid()
Return the content identifier (CID) for the object. Calculates the CID if necessary and caches it for subsequent queries.
Returns: The CID generated.
abstract static get_cid_for_data(record_data: Any)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBasePortfolioObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
A portfolio object Each portfolio is a dictionary with symbol/id keys and weight values.
cid : str | None
data : Any
static get_cid_for_data(record_data: dict)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBasePrivateFloatObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
A float object that preserves object privacy Each object comprises a float value and a string salt.
cid : str | None
data : Any
static get_cid_for_data(record_data: Tuple[int, str])
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBasePrivateIntObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
An integer object that preserves object privacy Each object comprises an integer value and a string salt. The user-specified random salt preserves privacy of the data with low entropy. To verify the object, users must specify the preimage with salts. The source datasets to be validated will be commonly stored as a spreadsheet with two columns.
cid : str | None
data : Any
static get_cid_for_data(record_data: Tuple[int, str])
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.VBaseStringObject(init_data: Any | None = None, init_dict: Dict | None = None, init_json: str | None = None)
Bases: VBaseObject
A string integer object
cid : str | None
data : Any
static get_cid_for_data(record_data: str)
Generate a content identifier (CID) for an object with given data. The method may be called to post commitments without instantiating an object. The encapsulation of different digital objects and their CID calculation is a primary job of an object.
Parameters: record_data – The object data. Allows calculating a CID without instantiating an object.
Returns: The CID generated.
class vbase.Web3HTTPCommitmentService(endpoint_url: str, commitment_service_address: str, private_key: str | None = None, commitment_service_json_file_name: str | None = 'CommitmentService.json', inject_geth_poa_middleware: bool = False)
Bases: Web3CommitmentService
Commitment service accessible using Web3.HTTPProvider. Without private key support, this class will only support operations on a test node.
add_object(object_cid: str)
Record an object commitment. This is a low-level function that operates on object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: object_cid – The CID identifying the object.
Returns: The commitment log containing commitment receipt info.
add_set(set_cid: str)
Records a set commitment. This is a low-level function that operates on set hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters: set_cid – The CID identifying the set.
Returns: The commitment log containing commitment receipt info.
add_set_object(set_cid: str, object_cid: str)
Records a commitment for an object belonging to a set of objects. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The CID for the set containing the object.
object_cid – The object hash to record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_batch(set_cid: str, object_cids: List[str])
Records a batch of commitments for objects belonging to a set. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cid – The hashes of the sets containing the objects.
object_cids – The hashes to record.
Returns: The commitment logs containing commitment receipts.
add_sets_objects_batch(set_cids: List[str], object_cids: List[str])
Records a batch of commitments for objects belonging to sets. This is a low-level function that operates on set and object hashes. It does not specify how a hash is built and does not provide a schema for hashing complex information.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
Returns: The commitment logs containing commitment receipts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The dictionary of arguments.
static get_init_args_from_env(dotenv_path: str | None = None)
Worker function to load the environment variables.
Parameters: dotenv_path – The .env file path, if any.
Returns: The dictionary of construction arguments.
user_set_exists(user: str, set_cid: str)
Checks whether a given set exists for a user.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID identifying the set.
Returns: True if the set exists for the user; False otherwise.
verify_user_object(user: str, object_cid: str, timestamp: str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
object_cid – The CID identifying the object.
timestamp – The timestamp of the commitment.
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_set_objects(user: str, set_cid: str, user_set_object_cid_sum: str)
Verifies an object commitment previously recorded. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID for the set containing the object.
user_set_object_cid_sum – The sum of all object hashes for the user set
Returns: True if the commitment has been verified successfully; False otherwise.
verify_user_sets(user: str, user_set_cid_sum: str)
Verifies set commitments previously recorded by the user. This is a low-level function that operates on object hashes.
Parameters:
user – The address for the user who recorded the commitment.
user_set_cid_sum – The sum of all set hashes for the user.
Returns: True if the commitment has been verified successfully; False otherwise.
class vbase.Web3HTTPCommitmentServiceTest(endpoint_url: str | None = None, commitment_service_address: str | None = None, private_key: str | None = None, commitment_service_json_file_name: str | None = 'CommitmentServiceTest.json', inject_geth_poa_middleware: bool = False)
Bases: Web3HTTPCommitmentService, CommitmentServiceTest
Test commitment service accessible using Web3.HTTPProvider.
add_object_with_timestamp(object_cid: str, timestamp: str)
Test shim to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
object_cid – The CID identifying the object.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_object_with_timestamp(set_cid: str, object_cid: str, timestamp: str)
Test shim to record an object commitment with a given timestamp. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the object.
object_cid – The CID to record.
timestamp – The timestamp to force for the record.
Returns: The commitment log containing commitment receipt info.
add_set_objects_with_timestamps_batch(set_cid: str, object_cids: List[str], timestamps: List[str])
Test shim to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cid – The CID of the set containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment logs containing commitment receipts.
add_sets_objects_with_timestamps_batch(set_cids: List[str], object_cids: List[str], timestamps: List[str])
Test shim to record a batch of object commitment with a timestamps. Only supported by test contracts.
Parameters:
set_cids – The hashes of the sets containing the objects.
object_cids – The hashes to record.
timestamps – The timestamps to force for the records.
Returns: The commitment logs containing commitment receipts.
clear_set_objects(set_cid: str)
Clear all records (objects) for a user’s set. Used to clear state when testing. Only supported by test contracts.
Parameters: set_cid – Hash identifying the set.
clear_sets()
Clear all sets for the user. Used to clear state when testing. Only supported by test contracts.
static create_instance_from_env(dotenv_path: str | None = '.env')
Creates an instance initialized from environment variables. Syntactic sugar for initializing new commitment objects using settings stored in a .env file or in environment variables.
Parameters: dotenv_path – Path to the .env file. Below is the default treatment that should be appropriate in most scenarios:
If dotenv_path is specified, attempt to load environment variable from the file. Ignore failures and default to the environment variables.
If called with no arguments, use default “.env” path.
If None dotenv_path is specified, default to the environment variables.
Returns: The dictionary of arguments.
class vbase.Web3HTTPIndexingService(commitment_services: List[Web3HTTPCommitmentService])
Bases: IndexingService
Indexing service accessible using Web3.HTTPProvider. Wraps RPC node event indexing to support commitment indexing operations.
static create_instance_from_env_json_descriptor(dotenv_path: str | None = None)
Creates an instance initialized from an environment variable containing a JSON descriptor. Syntactic sugar for initializing a new indexing service object using settings stored in a .env file or in environment variables. This method is especially useful for constructing complex indexers using multiple commitment service defined using complex JSON.
Parameters: dotenv_path – Path to the .env file. If path is not specified, does not load the .env file.
Returns: The IndexingService created.
static create_instance_from_json_descriptor(is_json: str)
Creates an instance initialized from a JSON descriptor. This method is especially useful for constructing complex indexers using multiple commitment service defined using complex JSON.
Parameters: is_json – The JSON string with the initialization data.
Returns: The IndexingService created.
find_objects(object_cid: str)
Returns the list of receipts for object commitments. Find and returns individual object commitments irrespective of the set they may have been committed to.
Parameters: object_cid – The CID for the object.
Returns: The list of commitment receipts for all object commitments.
find_user_set_objects(user: str, set_cid: str)
Returns the list of receipts for user set commitments.
Parameters:
user – The address for the user who recorded the commitment.
set_cid – The CID for the set containing the object.
Returns: The list of commitment receipts for all user set commitments.
vbase.get_default_logger(name: str)
Get default logger for a given name.
Parameters: name – The logger name.
Returns: The logger object.
Last updated