Escrow contract upgrades (#3482)

Co-authored-by: Francisco López <[email protected]>
Co-authored-by: Francisco López <[email protected]>
Co-authored-by: Dmitry Nechay <[email protected]>

Author: 3 people

.changeset/early-words-arrive.md

@@ -0,0 +1,8 @@
+---
+"@human-protocol/core": major
+---
+
+- Add new cancellation flow
+- Introduce admin role
+- Add the ability to create, fund and setup an escrow with only one transaction
+- Store intermediateResultsHash

.changeset/rich-kids-rush.md

@@ -0,0 +1,10 @@
+---
+"@human-protocol/sdk": major
+---
+
+### Changed
+
+- Created proper Subgraph types and cast values to the interfaces we have for SDK
+- Refactor EscrowUtils, TransactionUtils, OperatorUtils and WorkerUtils methods to fix mismatch types with Subgraph
+- Created some mappings to remove duplicated code
+- Add the ability to create, fund and setup an escrow with only one transaction

.github/workflows/cd-gitbook-sdk-docs.yaml

@@ -3,7 +3,7 @@ name: Publish SDK Docs to GitBook
 on:
   push:
     tags:
-      - "sdk@*"
+      - "js/sdk@*"
 
 permissions:
   contents: read

docs/sdk/python/human_protocol_sdk.constants.md

@@ -103,3 +103,5 @@ Enum for escrow statuses.
 #### Partial *= 2*
 
 #### Pending *= 1*
+
+#### ToCancel *= 6*

docs/sdk/python/human_protocol_sdk.escrow.escrow_client.md

@@ -74,25 +74,23 @@ Initializes a Escrow instance.
 * **Parameters:**
   **web3** (`Web3`) – The Web3 object
 
-#### add_trusted_handlers(\*args, \*\*kwargs)
-
 #### bulk_payout(\*args, \*\*kwargs)
 
 #### cancel(\*args, \*\*kwargs)
 
 #### complete(\*args, \*\*kwargs)
 
-#### create_bulk_payout_transaction(escrow_address, recipients, amounts, final_results_url, final_results_hash, txId, force_complete=False, tx_options=None)
+#### create_bulk_payout_transaction(escrow_address, recipients, amounts, final_results_url, final_results_hash, payoutId, force_complete=False, tx_options=None)
 
 Creates a prepared transaction for bulk payout without signing or sending it.
 
 * **Parameters:**
   * **escrow_address** (`str`) – Address of the escrow
   * **recipients** (`List`[`str`]) – Array of recipient addresses
-  * **amounts** (`List`[`Decimal`]) – Array of amounts the recipients will receive
+  * **amounts** (`List`[`int`]) – Array of amounts the recipients will receive
   * **final_results_url** (`str`) – Final results file URL
   * **final_results_hash** (`str`) – Final results file hash
-  * **txId** (`Decimal`) – Serial number of the bulks
+  * **payoutId** (`str`) – Unique identifier for the payout
   * **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
 * **Return type:**
   `TxParams`
@@ -159,14 +157,16 @@ Creates a prepared transaction for bulk payout without signing or sending it.
 
 #### create_escrow(\*args, \*\*kwargs)
 
+#### create_fund_and_setup_escrow(\*args, \*\*kwargs)
+
 #### ensure_correct_bulk_payout_input(escrow_address, recipients, amounts, final_results_url, final_results_hash)
 
 Validates input parameters for bulk payout operations.
 
 * **Parameters:**
   * **escrow_address** (`str`) – Address of the escrow
   * **recipients** (`List`[`str`]) – Array of recipient addresses
-  * **amounts** (`List`[`Decimal`]) – Array of amounts the recipients will receive
+  * **amounts** (`List`[`int`]) – Array of amounts the recipients will receive
   * **final_results_url** (`str`) – Final results file URL
   * **final_results_hash** (`str`) – Final results file hash
 * **Return type:**
@@ -185,7 +185,7 @@ Gets the balance for a specified escrow address.
 * **Parameters:**
   **escrow_address** (`str`) – Address of the escrow
 * **Return type:**
-  `Decimal`
+  `int`
 * **Returns:**
   Value of the balance
 * **Raises:**
@@ -262,6 +262,34 @@ Gets the escrow factory address of the escrow.
   )
   ```
 
+#### get_intermediate_results_hash(escrow_address)
+
+Gets the intermediate results file hash.
+
+* **Parameters:**
+  **escrow_address** (`str`) – Address of the escrow
+* **Return type:**
+  `str`
+* **Returns:**
+  Intermediate results file hash
+* **Raises:**
+  [**EscrowClientError**](#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an error occurs while checking the parameters
+* **Example:**
+  ```python
+  from eth_typing import URI
+  from web3 import Web3
+  from web3.providers.auto import load_provider_from_uri
+
+  from human_protocol_sdk.escrow import EscrowClient
+
+  w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
+  escrow_client = EscrowClient(w3)
+
+  hash = escrow_client.get_intermediate_results_hash(
+      "0x62dD51230A30401C455c8398d06F85e4EaB6309f"
+  )
+  ```
+
 #### get_intermediate_results_url(escrow_address)
 
 Gets the intermediate results file URL.
@@ -430,6 +458,34 @@ Gets the reputation oracle address of the escrow.
   )
   ```
 
+#### get_reserved_funds(escrow_address)
+
+Gets the reserved funds for a specified escrow address.
+
+* **Parameters:**
+  **escrow_address** (`str`) – Address of the escrow
+* **Return type:**
+  `int`
+* **Returns:**
+  Value of the reserved funds
+* **Raises:**
+  [**EscrowClientError**](#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an error occurs while checking the parameters
+* **Example:**
+  ```python
+  from eth_typing import URI
+  from web3 import Web3
+  from web3.providers.auto import load_provider_from_uri
+
+  from human_protocol_sdk.escrow import EscrowClient
+
+  w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
+  escrow_client = EscrowClient(w3)
+
+  reserved_funds = escrow_client.get_reserved_funds(
+      "0x62dD51230A30401C455c8398d06F85e4EaB6309f"
+  )
+  ```
+
 #### get_results_url(escrow_address)
 
 Gets the results file URL.
@@ -514,6 +570,8 @@ Gets the address of the token used to fund the escrow.
   )
   ```
 
+#### request_cancellation(\*args, \*\*kwargs)
+
 #### setup(\*args, \*\*kwargs)
 
 #### store_results(\*args, \*\*kwargs)
@@ -539,20 +597,20 @@ Initializes a Escrow instance.
 * **Parameters:**
   * **recording_oracle_address** (`str`) – Address of the Recording Oracle
   * **reputation_oracle_address** (`str`) – Address of the Reputation Oracle
-  * **recording_oracle_fee** (`Decimal`) – Fee percentage of the Recording Oracle
-  * **reputation_oracle_fee** (`Decimal`) – Fee percentage of the Reputation Oracle
+  * **recording_oracle_fee** (`int`) – Fee percentage of the Recording Oracle
+  * **reputation_oracle_fee** (`int`) – Fee percentage of the Reputation Oracle
   * **manifest** (`str`) – Manifest data (can be a URL or JSON string)
   * **hash** (`str`) – Manifest file hash
 
-### *class* human_protocol_sdk.escrow.escrow_client.EscrowWithdraw(tx_hash, token_address, amount_withdrawn)
+### *class* human_protocol_sdk.escrow.escrow_client.EscrowWithdraw(tx_hash, token_address, withdrawn_amount)
 
 Bases: `object`
 
-#### \_\_init_\_(tx_hash, token_address, amount_withdrawn)
+#### \_\_init_\_(tx_hash, token_address, withdrawn_amount)
 
 Represents the result of an escrow cancellation transaction.
 
 * **Parameters:**
   * **tx_hash** (`str`) – The hash of the transaction associated with the escrow withdrawal.
   * **token_address** (`str`) – The address of the token used for the withdrawal.
-  * **amount_withdrawn** (`any`) – The amount withdrawn from the escrow.
+  * **withdrawn_amount** (`any`) – The amount withdrawn from the escrow.

docs/sdk/python/human_protocol_sdk.escrow.escrow_utils.md

@@ -22,41 +22,101 @@ print(
 
 ## Module
 
-### *class* human_protocol_sdk.escrow.escrow_utils.EscrowData(chain_id, id, address, amount_paid, balance, count, factory_address, launcher, status, token, total_funded_amount, created_at, final_results_url=None, intermediate_results_url=None, manifest_hash=None, manifest=None, recording_oracle=None, reputation_oracle=None, exchange_oracle=None)
+### *class* human_protocol_sdk.escrow.escrow_utils.CancellationRefund(id, escrow_address, receiver, amount, block, timestamp, tx_hash)
 
 Bases: `object`
 
-#### \_\_init_\_(chain_id, id, address, amount_paid, balance, count, factory_address, launcher, status, token, total_funded_amount, created_at, final_results_url=None, intermediate_results_url=None, manifest_hash=None, manifest=None, recording_oracle=None, reputation_oracle=None, exchange_oracle=None)
+Represents a cancellation refund event.
+
+* **Parameters:**
+  * **id** (`str`) – The unique identifier for the cancellation refund event.
+  * **escrow_address** (`str`) – The address of the escrow associated with the refund.
+  * **receiver** (`str`) – The address of the recipient receiving the refund.
+  * **amount** (`str`) – The amount being refunded.
+  * **block** (`str`) – The block number in which the refund was processed.
+  * **timestamp** (`str`) – The timestamp of the refund event in milliseconds.
+  * **tx_hash** (`str`) – The transaction hash of the refund event.
+
+#### \_\_init_\_(id, escrow_address, receiver, amount, block, timestamp, tx_hash)
+
+### *class* human_protocol_sdk.escrow.escrow_utils.EscrowData(chain_id, id, address, amount_paid, balance, count, factory_address, launcher, job_requester_id, status, token, total_funded_amount, created_at, final_results_url=None, final_results_hash=None, intermediate_results_url=None, intermediate_results_hash=None, manifest_hash=None, manifest=None, recording_oracle=None, reputation_oracle=None, exchange_oracle=None, recording_oracle_fee=None, reputation_oracle_fee=None, exchange_oracle_fee=None)
+
+Bases: `object`
+
+#### \_\_init_\_(chain_id, id, address, amount_paid, balance, count, factory_address, launcher, job_requester_id, status, token, total_funded_amount, created_at, final_results_url=None, final_results_hash=None, intermediate_results_url=None, intermediate_results_hash=None, manifest_hash=None, manifest=None, recording_oracle=None, reputation_oracle=None, exchange_oracle=None, recording_oracle_fee=None, reputation_oracle_fee=None, exchange_oracle_fee=None)
 
 Initializes an EscrowData instance.
 
 * **Parameters:**
   * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – Chain identifier
   * **id** (`str`) – Identifier
   * **address** (`str`) – Address
-  * **amount_paid** (`int`) – Amount paid
-  * **balance** (`int`) – Balance
-  * **count** (`int`) – Count
+  * **amount_paid** (`str`) – Amount paid
+  * **balance** (`str`) – Balance
+  * **count** (`str`) – Count
   * **factory_address** (`str`) – Factory address
   * **launcher** (`str`) – Launcher
+  * **job_requester_id** (`Optional`[`str`]) – Job requester identifier
   * **status** (`str`) – Status
   * **token** (`str`) – Token
-  * **total_funded_amount** (`int`) – Total funded amount
-  * **created_at** (`datetime`) – Creation date
+  * **total_funded_amount** (`str`) – Total funded amount
+  * **created_at** (`str`) – Creation timestamp in milliseconds
   * **final_results_url** (`Optional`[`str`]) – URL for final results.
+  * **final_results_hash** (`Optional`[`str`]) – Hash for final results.
   * **intermediate_results_url** (`Optional`[`str`]) – URL for intermediate results.
+  * **intermediate_results_hash** (`Optional`[`str`]) – Hash for intermediate results.
   * **manifest_hash** (`Optional`[`str`]) – Manifest hash.
   * **manifest** (`Optional`[`str`]) – Manifest data (JSON/URL).
   * **recording_oracle** (`Optional`[`str`]) – Recording Oracle address.
   * **reputation_oracle** (`Optional`[`str`]) – Reputation Oracle address.
   * **exchange_oracle** (`Optional`[`str`]) – Exchange Oracle address.
+  * **recording_oracle_fee** (`Optional`[`str`]) – Fee for the Recording Oracle.
+  * **reputation_oracle_fee** (`Optional`[`str`]) – Fee for the Reputation Oracle.
+  * **exchange_oracle_fee** (`Optional`[`str`]) – Fee for the Exchange Oracle.
 
 ### *class* human_protocol_sdk.escrow.escrow_utils.EscrowUtils
 
 Bases: `object`
 
 A utility class that provides additional escrow-related functionalities.
 
+#### *static* get_cancellation_refund(chain_id, escrow_address)
+
+Returns the cancellation refund for a given escrow address.
+
+* **Parameters:**
+  * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – Network in which the escrow has been deployed
+  * **escrow_address** (`str`) – Address of the escrow
+* **Return type:**
+  [`CancellationRefund`](#human_protocol_sdk.escrow.escrow_utils.CancellationRefund)
+* **Returns:**
+  CancellationRefund data or None
+* **Raises:**
+  [**EscrowClientError**](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an unsupported chain ID or invalid address is provided.
+* **Example:**
+  ```python
+  from human_protocol_sdk.constants import ChainId
+  from human_protocol_sdk.escrow import EscrowUtils
+
+  refund = EscrowUtils.get_cancellation_refund(
+      ChainId.POLYGON_AMOY,
+      "0x1234567890123456789012345678901234567890"
+  )
+  ```
+
+#### *static* get_cancellation_refunds(filter)
+
+Fetch cancellation refunds from the subgraph based on the provided filter.
+
+* **Parameters:**
+  **filter** ([`CancellationRefundFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.CancellationRefundFilter)) – Object containing all the necessary parameters to filter cancellation refunds.
+* **Return List[CancellationRefund]:**
+  List of cancellation refunds matching the query parameters.
+* **Raises:**
+  [**EscrowClientError**](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an unsupported chain ID or invalid addresses are provided.
+* **Return type:**
+  `List`[[`CancellationRefund`](#human_protocol_sdk.escrow.escrow_utils.CancellationRefund)]
+
 #### *static* get_escrow(chain_id, escrow_address)
 
 Returns the escrow for a given address.
@@ -145,8 +205,8 @@ Initializes a Payout instance.
   * **chain_id** – The chain identifier where the payout occurred.
   * **escrow_address** (`str`) – The address of the escrow that executed the payout.
   * **recipient** (`str`) – The address of the recipient.
-  * **amount** (`int`) – The amount of the payout.
-  * **created_at** (`int`) – The time of creation of the payout.
+  * **amount** (`str`) – The amount of the payout.
+  * **created_at** (`str`) – The time of creation of the payout in milliseconds.
 
 #### \_\_init_\_(id, escrow_address, recipient, amount, created_at)
 
@@ -157,7 +217,7 @@ Bases: `object`
 Initializes a StatusEvent instance.
 
 * **Parameters:**
-  * **timestamp** (`int`) – The timestamp of the event.
+  * **timestamp** (`int`) – The timestamp of the event in milliseconds.
   * **status** (`str`) – The status of the escrow.
   * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – The chain identifier where the event occurred.
   * **escrow_address** (`str`) – The address of the escrow.