# COM API Reference

## Contents

* [AssemblyResolver](#tvbaseinfrastructureassemblyresolver)
* [ComGuids](#tvbasecomguids)
* [IReceipt](#tvbasereceiptsireceipt)
  * [Timestamp](#pvbasereceiptsireceipttimestamp)
* [IVerificationResult](#tvbaseiverificationresult)
  * [VerificationFindings](#pvbaseiverificationresultverificationfindings)
  * [VerificationPassed](#pvbaseiverificationresultverificationpassed)
* [IWeb3Receipt](#tvbasereceiptsiweb3receipt)
  * [Timestamp](#pvbasereceiptsiweb3receipttimestamp)
  * [TransactionHash](#pvbasereceiptsiweb3receipttransactionhash)
* [IvBaseBuilder](#tvbaseivbasebuilder)
  * [CreateDataset(client,name,objectType)](#mvbaseivbasebuildercreatedatasetvbaseivbaseclientsystemstringvbaseobjecttypes)
  * [CreateDatasetFromJson(client,json)](#mvbaseivbasebuildercreatedatasetfromjsonvbaseivbaseclientsystemstring)
  * [CreateForwarderClient(forwarderUrl,apiKey,privateKey)](#mvbaseivbasebuildercreateforwarderclientsystemstringsystemstringsystemstring)
* [IvBaseClient](#tvbaseivbaseclient)
  * [DefaultUser](#pvbaseivbaseclientdefaultuser)
  * [AddNamedSet(name)](#mvbaseivbaseclientaddnamedsetsystemstring)
  * [AddSet(setCid)](#mvbaseivbaseclientaddsetsystemstring)
  * [AddSetObject(setCid,objectCid)](#mvbaseivbaseclientaddsetobjectsystemstringsystemstring)
  * [UserNamedSetExists(user,name)](#mvbaseivbaseclientusernamedsetexistssystemstringsystemstring)
  * [VerifyUserObject(user,objectCid,timestamp)](#mvbaseivbaseclientverifyuserobjectsystemstringsystemstringsystemint64)
  * [VerifyUserSetObjects(user,setCid,userSetObjectsCidSum)](#mvbaseivbaseclientverifyusersetobjectssystemstringsystemstringsystemstring)
* [IvBaseDataset](#tvbaseivbasedataset)
  * [AddRecord(recordData)](#mvbaseivbasedatasetaddrecordsystemobject)
  * [ToJson()](#mvbaseivbasedatasettojson)
  * [VerifyCommitments()](#mvbaseivbasedatasetverifycommitments)
* [ObjectTypes](#tvbaseobjecttypes)
* [ReceiptConverter](#tvbaseinfrastructurereceiptconverter)
  * [ToCom(receipt)](#mvbaseinfrastructurereceiptconvertertocomvbasecorereceipt)
* [SecurityProtocolHelper](#tvbaseinfrastructuresecurityprotocolhelper)
  * [ResetSecurityProtocol()](#mvbaseinfrastructuresecurityprotocolhelperresetsecurityprotocol)
* [ShimInstaller](#tvbaseinfrastructureshiminstaller)
* [Utils](#tvbaseutils)
  * [PreprocessException(action,logger)](#mvbaseutilspreprocessexceptionsystemactionmicrosoftextensionsloggingilogger)
  * [PreprocessException(ex)](#mvbaseutilspreprocessexceptionsystemexception)
  * [PreprocessException\`\`1(func,logger)](#mvbaseutilspreprocessexception1systemfunc0microsoftextensionsloggingilogger)

## AssemblyResolver `type` <a href="#tvbaseinfrastructureassemblyresolver" id="tvbaseinfrastructureassemblyresolver"></a>

**Namespace**

vBase.Infrastructure

**Summary**

Some dependencies are referenced transitively multiple times with different versions. Only the latest version is available in the application folder. To resolve older versions at runtime and return the latest version, we use the AssemblyResolver class.

## ComGuids `type` <a href="#tvbasecomguids" id="tvbasecomguids"></a>

**Namespace**

vBase

**Summary**

Contains the GUIDs for the COM interfaces and classes.

## IReceipt `type` <a href="#tvbasereceiptsireceipt" id="tvbasereceiptsireceipt"></a>

**Namespace**

vBase.Receipts

**Summary**

Represents a transaction receipt.

### Timestamp `property` <a href="#pvbasereceiptsireceipttimestamp" id="pvbasereceiptsireceipttimestamp"></a>

**Summary**

The transaction timestamp in Unix time format (seconds).

## IVerificationResult `type` <a href="#tvbaseiverificationresult" id="tvbaseiverificationresult"></a>

**Namespace**

vBase

**Summary**

Represents the result of a verification operation.

### VerificationFindings `property` <a href="#pvbaseiverificationresultverificationfindings" id="pvbaseiverificationresultverificationfindings"></a>

**Summary**

A collection of verification findings.

### VerificationPassed `property` <a href="#pvbaseiverificationresultverificationpassed" id="pvbaseiverificationresultverificationpassed"></a>

**Summary**

Indicates whether the verification passed.

## IWeb3Receipt `type` <a href="#tvbasereceiptsiweb3receipt" id="tvbasereceiptsiweb3receipt"></a>

**Namespace**

vBase.Receipts

**Summary**

WEB3-specific receipt. Additionally to the base timestamp, it contains the transaction hash.

In COM interfaces can inherit from one another. However, the .NET implementation that exposes the .NET interface to COM does not support inheritance. Therefore, you must replicate any interface members in a base interface to the derived interface. The interop code does not look at base interface types when building the exposed COM interface.

### Timestamp `property` <a href="#pvbasereceiptsiweb3receipttimestamp" id="pvbasereceiptsiweb3receipttimestamp"></a>

**Summary**

The transaction timestamp in Unix time format (seconds).

### TransactionHash `property` <a href="#pvbasereceiptsiweb3receipttransactionhash" id="pvbasereceiptsiweb3receipttransactionhash"></a>

**Summary**

The transaction hash.

## IvBaseBuilder `type` <a href="#tvbaseivbasebuilder" id="tvbaseivbasebuilder"></a>

**Namespace**

vBase

**Summary**

COM does not support constructors with parameters, so we need to use a factory method to create the objects.

### CreateDataset(client,name,objectType) `method` <a href="#mvbaseivbasebuildercreatedatasetvbaseivbaseclientsystemstringvbaseobjecttypes" id="mvbaseivbasebuildercreatedatasetvbaseivbaseclientsystemstringvbaseobjecttypes"></a>

**Summary**

Create a COM visible dataset object.

**Returns**

Newly created dataset object.

**Parameters**

| Name       | Type                                                                                                      | Description                                             |
| ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| client     | [vBase.IvBaseClient](#tvbaseivbaseclient)                                                                 | vBase client.                                           |
| name       | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The name of the dataset.                                |
| objectType | [vBase.ObjectTypes](#tvbaseobjecttypes)                                                                   | Type of the objects that will be stored in the dataset. |

### CreateDatasetFromJson(client,json) `method` <a href="#mvbaseivbasebuildercreatedatasetfromjsonvbaseivbaseclientsystemstring" id="mvbaseivbasebuildercreatedatasetfromjsonvbaseivbaseclientsystemstring"></a>

**Summary**

Create a COM visible dataset object.

**Returns**

Newly created dataset object.

**Parameters**

| Name   | Type                                                                                                      | Description                                                  |
| ------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| client | [vBase.IvBaseClient](#tvbaseivbaseclient)                                                                 | vBase client.                                                |
| json   | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | Json that contains all data records, and dataset properties. |

### CreateForwarderClient(forwarderUrl,apiKey,privateKey) `method` <a href="#mvbaseivbasebuildercreateforwarderclientsystemstringsystemstringsystemstring" id="mvbaseivbasebuildercreateforwarderclientsystemstringsystemstringsystemstring"></a>

**Summary**

Create a COM visible client for the vBase API.

**Returns**

Newly created client object.

**Parameters**

| Name         | Type                                                                                                      | Description        |
| ------------ | --------------------------------------------------------------------------------------------------------- | ------------------ |
| forwarderUrl | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | Forwarder API url. |
| apiKey       | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | API key.           |
| privateKey   | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | Private key.       |

## IvBaseClient `type` <a href="#tvbaseivbaseclient" id="tvbaseivbaseclient"></a>

**Namespace**

vBase

**Summary**

COM visible client interface for the vBase API. It's a shim between the COM client and the vBase.Core client class.

### DefaultUser `property` <a href="#pvbaseivbaseclientdefaultuser" id="pvbaseivbaseclientdefaultuser"></a>

**Summary**

Return the default user address used in vBase transactions.

### AddNamedSet(name) `method` <a href="#mvbaseivbaseclientaddnamedsetsystemstring" id="mvbaseivbaseclientaddnamedsetsystemstring"></a>

**Summary**

Creates a commitment for a set with a given name. The set will be added for the account associated with the client object.

**Parameters**

| Name | Type                                                                                                      | Description          |
| ---- | --------------------------------------------------------------------------------------------------------- | -------------------- |
| name | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The name of the set. |

### AddSet(setCid) `method` <a href="#mvbaseivbaseclientaddsetsystemstring" id="mvbaseivbaseclientaddsetsystemstring"></a>

**Summary**

Records a set commitment.

**Parameters**

| Name   | Type                                                                                                      | Description                                     |
| ------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| setCid | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The HEX encoded CID (hash) identifying the set. |

### AddSetObject(setCid,objectCid) `method` <a href="#mvbaseivbaseclientaddsetobjectsystemstringsystemstring" id="mvbaseivbaseclientaddsetobjectsystemstringsystemstring"></a>

**Summary**

Adds a record to the dataset.

**Returns**

The transaction timestamp of the record addition in Unix time format (seconds).

**Parameters**

| Name      | Type                                                                                                      | Description                                        |
| --------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| setCid    | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | HEX encoded CID for the set containing the object. |
| objectCid | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | HEX encoded CID of the object to record.           |

### UserNamedSetExists(user,name) `method` <a href="#mvbaseivbaseclientusernamedsetexistssystemstringsystemstring" id="mvbaseivbaseclientusernamedsetexistssystemstringsystemstring"></a>

**Summary**

Checks if a named dataset exists.

**Returns**

True if the set with the given name exists; False otherwise.

**Parameters**

| Name | Type                                                                                                      | Description                                           |
| ---- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| user | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The address for the user who recorded the commitment. |
| name | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The name of the set.                                  |

### VerifyUserObject(user,objectCid,timestamp) `method` <a href="#mvbaseivbaseclientverifyuserobjectsystemstringsystemstringsystemint64" id="mvbaseivbaseclientverifyuserobjectsystemstringsystemstringsystemint64"></a>

**Summary**

Verifies an object commitment previously recorded.

**Returns**

True if the commitment has been verified successfully; False otherwise.

**Parameters**

| Name      | Type                                                                                                      | Description                                                            |
| --------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| user      | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The address for the user who recorded the commitment.                  |
| objectCid | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The HEX encoded CID of the object.                                     |
| timestamp | [System.Int64](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.Int64)   | The timestamp of the object's creation, in Unix time format (seconds). |

### VerifyUserSetObjects(user,setCid,userSetObjectsCidSum) `method` <a href="#mvbaseivbaseclientverifyusersetobjectssystemstringsystemstringsystemstring" id="mvbaseivbaseclientverifyusersetobjectssystemstringsystemstringsystemstring"></a>

**Summary**

Verifies an object commitment previously recorded.

**Returns**

True if the commitment has been verified successfully; False otherwise.

**Parameters**

| Name                 | Type                                                                                                      | Description                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| user                 | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The address for the user who recorded the commitment. |
| setCid               | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The CID for the set containing the object.            |
| userSetObjectsCidSum | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.String) | The sum of all object hashes for the user set.        |

## IvBaseDataset `type` <a href="#tvbaseivbasedataset" id="tvbaseivbasedataset"></a>

**Namespace**

vBase

**Summary**

Represents a set of records created on the Validity Base platform.

### AddRecord(recordData) `method` <a href="#mvbaseivbasedatasetaddrecordsystemobject" id="mvbaseivbasedatasetaddrecordsystemobject"></a>

**Summary**

Adds a record to the dataset.

**Parameters**

| Name       | Type                                                                                                      | Description    |
| ---------- | --------------------------------------------------------------------------------------------------------- | -------------- |
| recordData | [System.Object](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.Object) | Record to add. |

### ToJson() `method` <a href="#mvbaseivbasedatasettojson" id="mvbaseivbasedatasettojson"></a>

**Summary**

Serializes the dataset to a JSON string.

**Returns**

JSON string that can be deserialized using vBase SDK on any other platform.

**Parameters**

This method has no parameters.

### VerifyCommitments() `method` <a href="#mvbaseivbasedatasetverifycommitments" id="mvbaseivbasedatasetverifycommitments"></a>

**Summary**

Verifies if all records in the dataset were actually created on the Validity Base platform at the specified timestamps.

**Returns**

Validation result: A collection of errors. For each record that was not found on the Validity Base platform, or was added with a different timestamp, there will be a separate error item in the collection. Additionally, an error item will be added if the dataset on the Validity Base platform contains more records than exist in this client-side dataset.

**Parameters**

This method has no parameters.

## ObjectTypes `type` <a href="#tvbaseobjecttypes" id="tvbaseobjecttypes"></a>

**Namespace**

vBase

**Summary**

Types of objects that can be stored in a dataset.

## ReceiptConverter `type` <a href="#tvbaseinfrastructurereceiptconverter" id="tvbaseinfrastructurereceiptconverter"></a>

**Namespace**

vBase.Infrastructure

**Summary**

Converts between [Receipt](#tvbasecorereceipt) and COM-compatible [IReceipt](#tvbasereceiptsireceipt).

### ToCom(receipt) `method` <a href="#mvbaseinfrastructurereceiptconvertertocomvbasecorereceipt" id="mvbaseinfrastructurereceiptconvertertocomvbasecorereceipt"></a>

**Summary**

Converts a [Receipt](#tvbasecorereceipt) to a [IReceipt](#tvbasereceiptsireceipt).

**Returns**

The converted receipt.

**Parameters**

| Name    | Type                                     | Description             |
| ------- | ---------------------------------------- | ----------------------- |
| receipt | [vBase.Core.Receipt](#tvbasecorereceipt) | The receipt to convert. |

## SecurityProtocolHelper `type` <a href="#tvbaseinfrastructuresecurityprotocolhelper" id="tvbaseinfrastructuresecurityprotocolhelper"></a>

**Namespace**

vBase.Infrastructure

**Summary**

When running the shim in the VBA environment, we observed on some machines that the security protocol is explicitly set to Ssl3 or Tls. Such a configuration is incompatible with TLS 1.2, which is the protocol used by the Forwarder server. Experimentally, we found that setting the security protocol to 0 (SystemDefault) does not resolve the issue. Setting explicitly to Tls12 does.

### ResetSecurityProtocol() `method` <a href="#mvbaseinfrastructuresecurityprotocolhelperresetsecurityprotocol" id="mvbaseinfrastructuresecurityprotocolhelperresetsecurityprotocol"></a>

**Summary**

Updates the security protocol to Tls12.

**Parameters**

This method has no parameters.

## ShimInstaller `type` <a href="#tvbaseinfrastructureshiminstaller" id="tvbaseinfrastructureshiminstaller"></a>

**Namespace**

vBase.Infrastructure

**Summary**

It's important to register the assembly using both versions of regasm—32-bit and 64-bit. Even though the Excel process is 64-bit, it seems that the VBA execution process is 32-bit, so it doesn't recognize the registrations in the 64-bit registry.

## Utils `type` <a href="#tvbaseutils" id="tvbaseutils"></a>

**Namespace**

vBase

**Summary**

Utility methods.

### PreprocessException(action,logger) `method` <a href="#mvbaseutilspreprocessexceptionsystemactionmicrosoftextensionsloggingilogger" id="mvbaseutilspreprocessexceptionsystemactionmicrosoftextensionsloggingilogger"></a>

**Summary**

Executes an action and logs any exceptions that occur. Additionally, converts the exception into a VBA-friendly exception.

**Parameters**

| Name   | Type                                                                                                      | Description        |
| ------ | --------------------------------------------------------------------------------------------------------- | ------------------ |
| action | [System.Action](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.Action) | Action to execute. |
| logger | [Microsoft.Extensions.Logging.ILogger](#tmicrosoftextensionsloggingilogger)                               | Logger.            |

### PreprocessException(ex) `method` <a href="#mvbaseutilspreprocessexceptionsystemexception" id="mvbaseutilspreprocessexceptionsystemexception"></a>

**Summary**

Converts a regular .NET exception into a VBA-friendly exception with all relevant information aggregated into the exception message. This improves the user experience in a VBA environment, where the error object does not include the stack trace or the original exception type.

**Returns**

A VBA-friendly exception with aggregated information.

**Parameters**

| Name | Type                                                                                                            | Description             |
| ---- | --------------------------------------------------------------------------------------------------------------- | ----------------------- |
| ex   | [System.Exception](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.Exception) | The original exception. |

### PreprocessException\`\`1(func,logger) `method` <a href="#mvbaseutilspreprocessexception1systemfunc0microsoftextensionsloggingilogger" id="mvbaseutilspreprocessexception1systemfunc0microsoftextensionsloggingilogger"></a>

**Summary**

Executes a function and logs any exceptions that occur. Additionally, converts the exception into a VBA-friendly exception.

**Returns**

Function execution result.

**Parameters**

| Name   | Type                                                                                                         | Description          |
| ------ | ------------------------------------------------------------------------------------------------------------ | -------------------- |
| func   | [System.Func{\`\`0}](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1\&l=EN-US\&k=k:System.Func) | Function to execute. |
| logger | [Microsoft.Extensions.Logging.ILogger](#tmicrosoftextensionsloggingilogger)                                  | Logger.              |

**Generic Types**

| Name | Description           |
| ---- | --------------------- |
| T    | Function return type. |