[SDK] feat: return block and tx_hash from getStatusEvents

.changeset/brown-yaks-flow.md

@@ -0,0 +1,7 @@
+---
+"@human-protocol/sdk": minor
+"@human-protocol/python-sdk": minor
+---
+
+Extended SDK to return block and tx hash for "getStatusEvents".
+Fixed "status" field in return value to be consistent in SDKs.

packages/apps/job-launcher/server/src/modules/cron-job/cron-job.service.spec.ts

@@ -885,7 +885,7 @@ describe('CronJobService', () => {
       escrowEventMock = {
         chainId: ChainId.LOCALHOST,
         escrowAddress: MOCK_ADDRESS,
-        status: EscrowStatus.Partial,
+        status: 'Partial',
       };
 
       jest.spyOn(repository, 'findOneByType').mockResolvedValue(null);

packages/apps/job-launcher/server/src/modules/cron-job/cron-job.service.ts

@@ -435,19 +435,19 @@ export class CronJobService {
         }
         if (!job || job.status === JobStatus.CANCELED) continue;
 
-        if (event.status === EscrowStatus.Cancelled) {
+        if (event.status === EscrowStatus[EscrowStatus.Cancelled]) {
           await this.jobService.cancelJob(job);
           continue;
         }
 
         let newStatus: JobStatus | null = null;
         if (
-          event.status === EscrowStatus.Partial &&
+          event.status === EscrowStatus[EscrowStatus.Partial] &&
           job.status !== JobStatus.PARTIAL
         ) {
           newStatus = JobStatus.PARTIAL;
         } else if (
-          event.status === EscrowStatus.Complete &&
+          event.status === EscrowStatus[EscrowStatus.Complete] &&
           job.status !== JobStatus.COMPLETED
         ) {
           newStatus = JobStatus.COMPLETED;

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/escrow/escrow_utils.py

@@ -143,12 +143,20 @@ class StatusEvent:
     """
 
     def __init__(
-        self, timestamp: int, status: str, chain_id: ChainId, escrow_address: str
+        self,
+        timestamp: int,
+        status: str,
+        chain_id: ChainId,
+        escrow_address: str,
+        block: str,
+        tx_hash: str,
     ):
         self.timestamp = timestamp * 1000
         self.status = status
         self.chain_id = chain_id
         self.escrow_address = escrow_address
+        self.block = int(block)
+        self.tx_hash = tx_hash
 
 
 class Payout:
@@ -473,6 +481,9 @@ def get_status_events(
         if filter.launcher and not Web3.is_address(filter.launcher):
             raise EscrowClientError("Invalid Address")
 
+        if filter.escrow_address and not Web3.is_address(filter.escrow_address):
+            raise EscrowClientError("Invalid Address")
+
         network = NETWORKS.get(filter.chain_id)
         if not network:
             raise EscrowClientError("Unsupported Chain ID")
@@ -481,12 +492,17 @@ def get_status_events(
 
         data = custom_gql_fetch(
             network,
-            get_status_query(filter.date_from, filter.date_to, filter.launcher),
+            get_status_query(
+                filter.date_from, filter.date_to, filter.launcher, filter.escrow_address
+            ),
             {
                 "status": status_names,
                 "from": int(filter.date_from.timestamp()) if filter.date_from else None,
                 "to": int(filter.date_to.timestamp()) if filter.date_to else None,
                 "launcher": filter.launcher.lower() if filter.launcher else None,
+                "escrowAddress": (
+                    filter.escrow_address.lower() if filter.escrow_address else None
+                ),
                 "first": filter.first,
                 "skip": filter.skip,
                 "orderDirection": filter.order_direction.value,
@@ -510,6 +526,8 @@ def get_status_events(
                 escrow_address=event["escrowAddress"],
                 status=event["status"],
                 chain_id=filter.chain_id,
+                block=event["block"],
+                tx_hash=event["txHash"],
             )
             for event in status_events
         ]

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/filter.py

@@ -302,6 +302,7 @@ class StatusEventFilter:
         date_from (Optional[datetime]): Filter events from this date.
         date_to (Optional[datetime]): Filter events until this date.
         launcher (Optional[str]): Launcher address to filter by.
+        escrow_address (Optional[str]): Escrow address to filter by.
         first (int): Number of items per page.
         skip (int): Number of items to skip for pagination.
         order_direction (OrderDirection): Sort order for results.
@@ -314,6 +315,7 @@ def __init__(
         date_from: Optional[datetime] = None,
         date_to: Optional[datetime] = None,
         launcher: Optional[str] = None,
+        escrow_address: Optional[str] = None,
         first: int = 10,
         skip: int = 0,
         order_direction: OrderDirection = OrderDirection.DESC,
@@ -326,6 +328,7 @@ def __init__(
         :param date_from: Optional start date for filtering.
         :param date_to: Optional end date for filtering.
         :param launcher: Optional launcher address to filter by.
+        :param escrow_address: Optional escrow address to filter by.
         :param first: Optional number of events per page. Default is 10.
         :param skip: Optional number of events to skip. Default is 0.
         :param order_direction: Optional order direction. Default is DESC.
@@ -342,6 +345,7 @@ def __init__(
         self.date_from = date_from
         self.date_to = date_to
         self.launcher = launcher
+        self.escrow_address = escrow_address
         self.first = first
         self.skip = skip
         self.order_direction = order_direction

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/gql/cancel.py

@@ -70,4 +70,6 @@ def get_cancellation_refund_by_escrow_query():
     }}
 }}
 {cancellation_refund_fragment}
-""".format(cancellation_refund_fragment=cancellation_refund_fragment)
+""".format(
+        cancellation_refund_fragment=cancellation_refund_fragment
+    )

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/gql/escrow.py

@@ -97,18 +97,24 @@ def get_escrow_query():
     }}
 }}
 {escrow_fragment}
-""".format(escrow_fragment=escrow_fragment)
+""".format(
+        escrow_fragment=escrow_fragment
+    )
 
 
 def get_status_query(
-    from_: datetime = None, to_: datetime = None, launcher: str = None
+    from_: datetime = None,
+    to_: datetime = None,
+    launcher: str = None,
+    escrow_address: str = None,
 ):
     return """
 query getStatus(
     $status: [String!]!
     $from: Int
     $to: Int
     $launcher: String
+    $escrowAddress: String
     $orderDirection: String
     $first: Int
     $skip: Int
@@ -119,20 +125,25 @@ def get_status_query(
             {from_clause}
             {to_clause}
             {launcher_clause}
+            {escrow_address_clause}
         }}
         orderBy: timestamp
         orderDirection: $orderDirection
         first: $first
         skip: $skip
     ) {{
-        id
         escrowAddress
         timestamp
         status
+        block
+        txHash
     }}
 }}
 """.format(
         from_clause="timestamp_gte: $from" if from_ else "",
         to_clause="timestamp_lte: $to" if to_ else "",
         launcher_clause=f"launcher: $launcher" if launcher else "",
+        escrow_address_clause=(
+            f"escrowAddress: $escrowAddress" if escrow_address else ""
+        ),
     )

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/gql/reward.py

@@ -14,4 +14,6 @@
     }}
 }}
 {reward_added_event_fragment}
-""".format(reward_added_event_fragment=reward_added_event_fragment)
+""".format(
+    reward_added_event_fragment=reward_added_event_fragment
+)

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/gql/transaction.py

@@ -103,4 +103,6 @@ def get_transaction_query() -> str:
     }}
 }}
 {transaction_fragment}
-""".format(transaction_fragment=transaction_fragment)
+""".format(
+        transaction_fragment=transaction_fragment
+    )

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/gql/worker.py

@@ -18,7 +18,9 @@ def get_worker_query() -> str:
     }}
 }}
 {worker_fragment}
-""".format(worker_fragment=worker_fragment)
+""".format(
+        worker_fragment=worker_fragment
+    )
 
 
 def get_workers_query(filter: WorkerFilter) -> str:

packages/sdk/python/human-protocol-sdk/test/human_protocol_sdk/escrow/test_escrow_utils.py

@@ -381,6 +381,8 @@ def test_get_status_events(self):
                             "timestamp": 1620000000,
                             "escrowAddress": "0x123",
                             "status": "Pending",
+                            "block": "123456",
+                            "txHash": "0xabc",
                         }
                     ]
                 }
@@ -396,6 +398,8 @@ def test_get_status_events(self):
             self.assertEqual(result[0].escrow_address, "0x123")
             self.assertEqual(result[0].status, "Pending")
             self.assertEqual(result[0].chain_id, ChainId.POLYGON_AMOY)
+            self.assertEqual(result[0].block, 123456)
+            self.assertEqual(result[0].tx_hash, "0xabc")
 
     def test_get_status_events_with_date_range(self):
         with patch(
@@ -408,6 +412,8 @@ def test_get_status_events_with_date_range(self):
                             "timestamp": 1620000000,
                             "escrowAddress": "0x123",
                             "status": "Pending",
+                            "block": "123456",
+                            "txHash": "0xabc",
                         }
                     ]
                 }
@@ -429,6 +435,8 @@ def test_get_status_events_with_date_range(self):
             self.assertEqual(result[0].escrow_address, "0x123")
             self.assertEqual(result[0].status, "Pending")
             self.assertEqual(result[0].chain_id, ChainId.POLYGON_AMOY)
+            self.assertEqual(result[0].block, 123456)
+            self.assertEqual(result[0].tx_hash, "0xabc")
 
     def test_get_status_events_no_data(self):
         with patch(
@@ -454,6 +462,8 @@ def test_get_status_events_with_launcher(self):
                             "timestamp": 1620000000,
                             "escrowAddress": "0x123",
                             "status": "Pending",
+                            "block": "123456",
+                            "txHash": "0xabc",
                         }
                     ]
                 }
@@ -471,6 +481,8 @@ def test_get_status_events_with_launcher(self):
             self.assertEqual(result[0].escrow_address, "0x123")
             self.assertEqual(result[0].status, "Pending")
             self.assertEqual(result[0].chain_id, ChainId.POLYGON_AMOY)
+            self.assertEqual(result[0].block, 123456)
+            self.assertEqual(result[0].tx_hash, "0xabc")
 
     def test_get_payouts_unsupported_chain_id(self):
         filter = PayoutFilter(chain_id=9999)

packages/sdk/typescript/human-protocol-sdk/src/escrow/escrow_utils.ts

@@ -212,6 +212,7 @@ export class EscrowUtils {
       from,
       to,
       launcher,
+      escrowAddress,
       first = 10,
       skip = 0,
       orderDirection = OrderDirection.DESC,
@@ -221,6 +222,10 @@ export class EscrowUtils {
       throw ErrorInvalidAddress;
     }
 
+    if (escrowAddress && !ethers.isAddress(escrowAddress)) {
+      throw ErrorInvalidAddress;
+    }
+
     const networkData = NETWORKS[chainId];
     if (!networkData) {
       throw ErrorUnsupportedChainID;
@@ -242,12 +247,13 @@ export class EscrowUtils {
       escrowStatusEvents: StatusEvent[];
     }>(
       getSubgraphUrl(networkData),
-      GET_STATUS_UPDATES_QUERY(from, to, launcher),
+      GET_STATUS_UPDATES_QUERY(from, to, launcher, escrowAddress),
       {
         status: statusNames,
         from: from ? getUnixTimestamp(from) : undefined,
         to: to ? getUnixTimestamp(to) : undefined,
         launcher: launcher || undefined,
+        escrowAddress: escrowAddress || undefined,
         orderDirection,
         first: Math.min(first, 1000),
         skip,
@@ -262,8 +268,10 @@ export class EscrowUtils {
     return data['escrowStatusEvents'].map((event) => ({
       timestamp: Number(event.timestamp) * 1000,
       escrowAddress: event.escrowAddress,
-      status: EscrowStatus[event.status as keyof typeof EscrowStatus],
+      status: event.status as keyof typeof EscrowStatus,
       chainId,
+      block: BigInt(event.block),
+      txHash: event.txHash,
     }));
   }
 

packages/sdk/typescript/human-protocol-sdk/src/graphql/queries/escrow.ts

@@ -107,14 +107,16 @@ export const GET_ESCROWS_QUERY = (filter: IEscrowsFilter) => {
 export const GET_STATUS_UPDATES_QUERY = (
   from?: Date,
   to?: Date,
-  launcher?: string
+  launcher?: string,
+  escrowAddress?: string
 ) => {
   const WHERE_CLAUSE = `
     where: {
       status_in: $status
       ${from ? `timestamp_gte: $from` : ''}
       ${to ? `timestamp_lte: $to` : ''}
       ${launcher ? `launcher: $launcher` : ''}
+      ${escrowAddress ? `escrowAddress: $escrowAddress` : ''}
     }
   `;
   return gql`
@@ -123,6 +125,7 @@ export const GET_STATUS_UPDATES_QUERY = (
       $from: Int
       $to: Int
       $launcher: String
+      $escrowAddress: String
       $orderDirection: String
       $first: Int
       $skip: Int
@@ -137,6 +140,8 @@ export const GET_STATUS_UPDATES_QUERY = (
         escrowAddress,
         timestamp,
         status,
+        block,
+        txHash,
       }
     }
   `;

packages/sdk/typescript/human-protocol-sdk/src/graphql/types.ts

@@ -121,6 +121,8 @@ export type StatusEvent = {
   timestamp: string;
   escrowAddress: string;
   status: string;
+  block: string;
+  txHash: string;
 };
 
 export type KVStoreData = {

packages/sdk/typescript/human-protocol-sdk/src/interfaces.ts

@@ -176,6 +176,7 @@ export interface IStatusEventFilter extends IPagination {
   from?: Date;
   to?: Date;
   launcher?: string;
+  escrowAddress?: string;
 }
 
 export interface IWorker {
@@ -280,8 +281,10 @@ export interface IDailyHMT {
 export interface IStatusEvent {
   timestamp: number;
   escrowAddress: string;
-  status: EscrowStatus;
+  status: keyof typeof EscrowStatus;
   chainId: ChainId;
+  block: bigint;
+  txHash: string;
 }
 
 export interface ICancellationRefund {