add doc comments

Signed-off-by: ryanwolhuter <dev@ryanwolhuter.com>

src/plugins/oSnap/types.ts

@@ -242,6 +242,17 @@ export type OsnapPluginData = {
   safe: GnosisSafe | null;
 };
 
+/**
+ * Represents the data associated with an assertion on the Optimistic Oracle V3 subgraph.
+ * 
+ * @field `assertionId` field is the id of the assertion.
+ * @field `expirationTime` field is the time that the assertion's challenge period ends.
+ * @field `assertionHash` field is the transaction hash from when the assertion was made.
+ * @field `settlementHash` field is the transaction hash from when the assertion was settled.
+ * @field `disputeHash` field is the transaction hash from when the assertion was disputed.
+ * @field `assertionLogIndex` field is the log index of the transaction from when the assertion was made.
+ * @field `settlementResolution` field is whether or not the assertion was resolved in favor of the asserter.
+ */
 export type AssertionGql = {
   assertionId: string;
   expirationTime: string;
@@ -252,6 +263,15 @@ export type AssertionGql = {
   settlementResolution: boolean | null;
 };
 
+/**
+ * Represents the configuration of the Optimistic Governor module contract that was deployed for a given Safe.
+ * 
+ * @field `moduleAddress` field is the address of the specific Optimistic Governor module contract that was deployed for a given Safe.
+ * @field `oracleAddress` field is the address of the Optimistic Oracle V3 contract.
+ * @field `rules` rules for this Optimistic Governor contract.
+ * @field `minimumBond` field is the minimum bond that is required for an assertion to be made on this Optimistic Governor contract.
+ * @field `challengePeriod` field is the challenge period that is required for an assertion to be made on this Optimistic Governor contract.
+ */
 export type OGModuleDetails = {
   moduleAddress: string;
   oracleAddress: string;
@@ -260,13 +280,36 @@ export type OGModuleDetails = {
   challengePeriod: BigNumber;
 };
 
+/**
+ * Represents the collateral configuration for a given Optimistic Governor contract.
+ * 
+ * @field `erc20Contract` field is the ERC20 contract that is used for collateral.
+ * @field `address` field is the address of the ERC20 contract that is used for collateral.
+ * @field `symbol` field is the symbol of the ERC20 contract that is used for collateral.
+ * @field `decimals` field is the number of decimals that the ERC20 contract that is used for collateral has.
+ */
 export type CollateralDetails = {
   erc20Contract: Contract;
   address: string;
   symbol: string;
   decimals: BigNumber;
 };
 
+/**
+ * Event fired when an assertion is made on the Optimistic Oracle V3 contract.
+ * 
+ * @field `assertionId` field is the id of the assertion.
+ * @field `domainId` field is the domain id of the assertion.
+ * @field `claim` field is the claim of the assertion.
+ * @field `asserter` field is the address of the asserter.
+ * @field `callbackRecipient` field is the address of the callback recipient.
+ * @field `escalationManager` field is the address of the escalation manager.
+ * @field `caller` field is the address of the caller.
+ * @field `expirationTime` field is the time that the assertion's challenge period ends.
+ * @field `currency` field is the currency that the assertion is made in.
+ * @field `bond` field is the bond that is required for the assertion.
+ * @field `identifier` field is the identifier of the assertion.
+ */
 export type AssertionMadeEvent = Event & {
   args: {
     assertionId: string; // indexed
@@ -283,6 +326,18 @@ export type AssertionMadeEvent = Event & {
   };
 };
 
+/**
+ * Event fired when transactions are proposed on the Optimistic Governor contract.
+ * 
+ * @field `proposer` field is the address of the proposer.
+ * @field `proposalTime` field is the time that the proposal was made.
+ * @field `assertionId` field is the id of the assertion.
+ * @field `proposal` field is the proposal that was made.
+ * @field `proposalHash` field is the hash of the proposal.
+ * @field `explanation` field is the explanation of the proposal, which in the case of oSnap is the ipfs url.
+ * @field `rules` field is the rules of the proposal.
+ * @field `challengeWindowEvents` field is the challenge window events of the proposal.
+ */
 export type TransactionsProposedEvent = Event & {
   args: {
     proposer: string; // indexed
@@ -299,30 +354,55 @@ export type TransactionsProposedEvent = Event & {
   };
 };
 
+/**
+ * Event fired when an Optimistic Governor proposal's transactions are executed successfully.
+ * 
+ * @field `proposalHash` field is the hash of the proposal.
+ * @field `assertionId` field is the id of the assertion.
+ */
 export type ProposalExecutedEvent = Event & {
   args: {
     proposalHash: string; // indexed
     assertionId: string; // indexed
   };
 };
 
-export type AssertionDetails = {
+
+/**
+ * Represents the transaction hash and log index of an `AssertionMade` event.
+ * 
+ * We need these for generating a link to the assertion on the Optimistic Oracle dapp.
+ */
+export type AssertionTransactionDetails = {
   assertionHash: string;
   assertionLogIndex: string;
 };
 
+/**
+ * Represents the state of a proposal on the Optimistic Governor contract. When an assertion is associated with the proposal, we also include the assertion transaction hash and log index so that we can create a link to the assertion on the Optimistic Oracle dapp.
+ * 
+ * There are four states that a proposal can be in:
+ * 
+ * - `can-propose-to-og`: The user can propose transactions to the Optimistic Governor contract. This is the initial state of a proposal. We also indicate if this proposal has been disputed in the Oracle, so that we can warn the user to exercise caution and avoid losing their bond.
+ * 
+ * - `in-oo-challenge-period`: The user has proposed transactions to the Optimistic Governor contract, and the proposal is currently in the challenge period on the Optimistic Oracle contract. We also indicate when the challenge period ends, so that we can warn the user to wait until the challenge period ends before proposing new transactions.
+ * 
+ * - `can-request-tx-execution`: The user has proposed transactions to the Optimistic Governor contract, and the challenge period has ended. The user can now request that the Optimistic Governor contract execute the transactions.
+ * 
+ * - `transactions-executed`: The user has proposed transactions to the Optimistic Governor contract, the challenge period has ended, and the transactions have been executed by the Optimistic Governor contract.
+ */
 export type OGProposalState =
   | {
       status: 'can-propose-to-og';
       isDisputed: boolean;
     }
-  | (AssertionDetails & {
+  | (AssertionTransactionDetails & {
       status: 'in-oo-challenge-period';
       expirationTime: number;
     })
-  | (AssertionDetails & {
+  | (AssertionTransactionDetails & {
       status: 'can-request-tx-execution';
     })
-  | (AssertionDetails & {
+  | (AssertionTransactionDetails & {
       status: 'transactions-executed';
     });