Release 2025-01-16

.github/workflows/ci-test-dashboard.yaml

@@ -0,0 +1,23 @@
+name: Dashboard Check
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    paths:
+      - 'packages/core/**'
+      - 'packages/sdk/typescript/human-protocol-sdk/**'
+      - 'packages/apps/dashboard/**'
+  workflow_dispatch:
+
+jobs:
+  dashboard-server-test:
+    name: Dashboard Server Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm install --global yarn && yarn
+        name: Install dependencies
+      - run: yarn workspace @human-protocol/dashboard-server test
+        name: Run dashboard Server test

README.md

@@ -4,7 +4,7 @@
 | | | | |
 | --- | --- | --- | --- |
 | [![Lint Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-lint.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-lint.yaml) | [![Protocol Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-core.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-core.yaml) | [![Python SDK Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-python-sdk.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-python-sdk.yaml) | [![Node.js SDK Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-node-sdk.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-node-sdk.yaml) |
-| [![Subgraph Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-subgraph.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-subgraph.yaml) | [![Dashboard UI Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-dashboard-ui.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-dashboard-ui.yaml) | [![Faucet Server Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-faucet-server.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-faucet-server.yaml) | [![Contract Deploy](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-deploy-contracts.yaml/badge.svg?event=workflow_dispatch)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-deploy-contracts.yaml) |
+| [![Subgraph Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-subgraph.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-subgraph.yaml) | [![Dashboard Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-dashboard.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-dashboard.yaml) | [![Faucet Server Check](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-faucet-server.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/ci-test-faucet-server.yaml) | [![Contract Deploy](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-deploy-contracts.yaml/badge.svg?event=workflow_dispatch)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-deploy-contracts.yaml) |
 | [![Core NPM Publish](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-core.yaml/badge.svg?event=release)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-core.yaml) | [![Python SDK Publish](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-python-sdk.yaml/badge.svg?event=release)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-python-sdk.yaml) | [![Node.js SDK Publish](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-node-sdk.yaml/badge.svg?event=release)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-node-sdk.yaml) | [![Subgraph Deploy](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-subgraph.yaml/badge.svg?branch=main)](https://github.com/humanprotocol/human-protocol/actions/workflows/cd-subgraph.yaml) |
 
 
@@ -92,4 +92,4 @@ git config blame.markUnblamableLines true
 ## LEGAL NOTICE
 
 The Protocol is an open-source, blockchain-based network that organizes, evaluates, and compensates human labor (the “Protocol”).  Your use of the Protocol is entirely at your own risk. The Protocol is available on an “as is” basis without warranties of any kind, either express or implied, including, but not limited to, warranties of merchantability, title, fitness for a particular purpose and non-infringement. You assume all risks associated with using the Protocol, and digital assets   and   decentralized   systems   generally,   including   but   not
-limited to, that: (a) digital assets are highly volatile; (b) using digital assets is inherently risky due to both features of such assets and the potential unauthorized acts of third parties; (c) you may not have ready access to digital assets; and (d) you may lose some or all of your tokens or other digital assets. You agree that you will have no recourse against anyone else for any losses due to the use of the Protocol. For example, these losses may arise from or relate to: (i) incorrect   information;   (ii)   software   or   network   failures;  (iii) corrupted digital wallet files; (iv) unauthorized access; (v) errors, mistakes, or inaccuracies; or (vi) third-party activities. The Protocol does not collect any personal data, and your interaction with the Protocol will solely be through your public digital wallet address. Any personal or other data that you may make available in connection with the Protocol may not be private or secure.
+limited to, that: (a) digital assets are highly volatile; (b) using digital assets is inherently risky due to both features of such assets and the potential unauthorized acts of third parties; (c) you may not have ready access to digital assets; and (d) you may lose some or all of your tokens or other digital assets. You agree that you will have no recourse against anyone else for any losses due to the use of the Protocol. For example, these losses may arise from or relate to: (i) incorrect   information;   (ii)   software   or   network   failures;  (iii) corrupted digital wallet files; (iv) unauthorized access; (v) errors, mistakes, or inaccuracies; or (vi) third-party activities. The Protocol does not collect any personal data, and your interaction with the Protocol will solely be through your public digital wallet address. Any personal or other data that you may make available in connection with the Protocol may not be private or secure.

docs/sdk/python/human_protocol_sdk.encryption.encryption.md

@@ -1,11 +1,11 @@
 # human_protocol_sdk.encryption.encryption module
 
-This class allows to sign, verify, encrypt and
-decrypt messages at all levels of escrow processing.
+This class allows signing, verifying, encrypting, and
+decrypting messages at all levels of escrow processing.
 
 The algorithm includes the implementation of the
 [PGP encryption algorithm]([https://github.com/openpgpjs/openpgpjs](https://github.com/openpgpjs/openpgpjs))
-multi-public key encryption on python.
+multi-public key encryption in Python.
 Using the vanilla [ed25519]([https://en.wikipedia.org/wiki/EdDSA#Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519))
 implementation Schnorr signatures for signature and
 [curve25519]([https://en.wikipedia.org/wiki/Curve25519](https://en.wikipedia.org/wiki/Curve25519)) for encryption.

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

@@ -64,7 +64,7 @@ Represents the result of an escrow cancellation transaction.
 
 Bases: `object`
 
-A class used to manage escrow on the HUMAN network.
+A client class to interact with the escrow smart contract.
 
 #### \_\_init_\_(web3)
 
@@ -127,7 +127,7 @@ Pays out the amounts specified to the workers and sets the URL of the final resu
   * **escrow_address** (`str`) – Address of the escrow
   * **recipients** (`List`[`str`]) – Array of recipient addresses
   * **amounts** (`List`[`Decimal`]) – Array of amounts the recipients will receive
-  * **final_results_url** (`str`) – Final results file url
+  * **final_results_url** (`str`) – Final results file URL
   * **final_results_hash** (`str`) – Final results file hash
   * **txId** (`Decimal`) – Serial number of the bulks
   * **force_complete** (`Optional`[`bool`]) – (Optional) Indicates if remaining balance should be transferred to the escrow creator
@@ -263,19 +263,22 @@ Sets the status of an escrow to completed.
   escrow_client.complete("0x62dD51230A30401C455c8398d06F85e4EaB6309f")
   ```
 
-#### create_escrow(token_address, trusted_handlers, job_requester_id, tx_options=None)
+#### create_bulk_payout_transaction(escrow_address, recipients, amounts, final_results_url, final_results_hash, txId, force_complete=False, tx_options=None)
 
-Creates an escrow contract that uses the token passed to pay oracle fees and reward workers.
+Creates a prepared transaction for bulk payout without signing or sending it.
 
 * **Parameters:**
-  * **tokenAddress** – The address of the token to use for payouts
-  * **trusted_handlers** (`List`[`str`]) – Array of addresses that can perform actions on the contract
-  * **job_requester_id** (`str`) – The id of the job requester
+  * **escrow_address** (`str`) – Address of the escrow
+  * **recipients** (`List`[`str`]) – Array of recipient addresses
+  * **amounts** (`List`[`Decimal`]) – 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
   * **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
 * **Return type:**
-  `str`
+  `TxParams`
 * **Returns:**
-  The address of the escrow created
+  A dictionary containing the prepared transaction
 * **Raises:**
   [**EscrowClientError**](#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an error occurs while checking the parameters
 * **Example:**
@@ -300,10 +303,80 @@ Creates an escrow contract that uses the token passed to pay oracle fees and rew
   (w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
   escrow_client = EscrowClient(w3)
 
-  token_address = '0x0376D26246Eb35FF4F9924cF13E6C05fd0bD7Fb4'
-  trusted_handlers = [
+  recipients = [
       '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
-      '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+      '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92267'
+  ]
+  amounts = [
+      Web3.to_wei(5, 'ether'),
+      Web3.to_wei(10, 'ether')
+  ]
+  results_url = 'http://localhost/results.json'
+  results_hash = 'b5dad76bf6772c0f07fd5e048f6e75a5f86ee079'
+
+  transaction = escrow_client.create_bulk_payout_transaction(
+      "0x62dD51230A30401C455c8398d06F85e4EaB6309f",
+      recipients,
+      amounts,
+      results_url,
+      results_hash,
+      1,
+      false
+  )
+
+  print(f"Transaction: {transaction}")
+
+  signed_transaction = w3.eth.account.sign_transaction(
+      transaction, private_key
+  )
+  tx_hash = w3.eth.send_raw_transaction(
+      signed_transaction.raw_transaction
+  )
+  tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
+  print(f"Transaction sent with hash: {tx_hash.hex()}")
+  print(f"Transaction receipt: {tx_receipt}")
+  ```
+
+#### create_escrow(token_address, trusted_handlers, job_requester_id, tx_options=None)
+
+Creates a new escrow contract.
+
+* **Parameters:**
+  * **token_address** (`str`) – Address of the token to be used in the escrow
+  * **trusted_handlers** (`List`[`str`]) – List of trusted handler addresses
+  * **job_requester_id** (`str`) – ID of the job requester
+  * **tx_options** (`Optional`[`TxParams`]) – (Optional) Transaction options
+* **Return type:**
+  `str`
+* **Returns:**
+  Address of the created escrow contract
+* **Example:**
+  ```python
+  from eth_typing import URI
+  from web3 import Web3
+  from web3.middleware import construct_sign_and_send_raw_middleware
+  from web3.providers.auto import load_provider_from_uri
+
+  from human_protocol_sdk.escrow import EscrowClient
+
+  def get_w3_with_priv_key(priv_key: str):
+      w3 = Web3(load_provider_from_uri(
+          URI("http://localhost:8545")))
+      gas_payer = w3.eth.account.from_key(priv_key)
+      w3.eth.default_account = gas_payer.address
+      w3.middleware_onion.add(
+          construct_sign_and_send_raw_middleware(gas_payer),
+          "construct_sign_and_send_raw_middleware",
+      )
+      return (w3, gas_payer)
+
+  (w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
+  escrow_client = EscrowClient(w3)
+
+  token_address = '0x1234567890abcdef1234567890abcdef12345678'
+  trusted_handlers = [
+      '0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef',
+      '0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef'
   ]
   job_requester_id = 'job-requester'
   escrow_address = escrow_client.create_escrow(
@@ -313,12 +386,29 @@ Creates an escrow contract that uses the token passed to pay oracle fees and rew
   )
   ```
 
+#### 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
+  * **final_results_url** (`str`) – Final results file URL
+  * **final_results_hash** (`str`) – Final results file hash
+* **Return type:**
+  `None`
+* **Returns:**
+  None
+* **Raises:**
+  [**EscrowClientError**](#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If validation fails
+
 #### fund(escrow_address, amount, tx_options=None)
 
 Adds funds to the escrow.
 
 * **Parameters:**
-  * **escrow_address** (`str`) – Address of the escrow to setup
+  * **escrow_address** (`str`) – Address of the escrow to fund
   * **amount** (`Decimal`) – Amount to be added as funds
   * **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
 * **Return type:**
@@ -349,8 +439,10 @@ Adds funds to the escrow.
   (w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
   escrow_client = EscrowClient(w3)
 
-  amount = Web3.to_wei(5, 'ether') # convert from ETH to WEI
-  escrow_client.fund("0x62dD51230A30401C455c8398d06F85e4EaB6309f", amount)
+  amount = Web3.to_wei(5, 'ether')  # convert from ETH to WEI
+  escrow_client.fund(
+      "0x62dD51230A30401C455c8398d06F85e4EaB6309f", amount
+  )
   ```
 
 #### get_balance(escrow_address)
@@ -694,15 +786,9 @@ Gets the address of the token used to fund the escrow.
 Sets up the parameters of the escrow.
 
 * **Parameters:**
-  * **escrow_address** (`str`) – Address of the escrow to setup
-  * **escrow_config** ([`EscrowConfig`](#human_protocol_sdk.escrow.escrow_client.EscrowConfig)) – Object containing all the necessary information to setup an escrow
-  * **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
-* **Return type:**
-  `None`
-* **Returns:**
-  None
-* **Raises:**
-  [**EscrowClientError**](#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an error occurs while checking the parameters
+  * **escrow_address** (`str`) – Address of the escrow contract
+  * **escrow_config** ([`EscrowConfig`](#human_protocol_sdk.escrow.escrow_client.EscrowConfig)) – Configuration parameters for the escrow
+  * **tx_options** (`Optional`[`TxParams`]) – (Optional) Transaction options
 * **Example:**
   ```python
   from eth_typing import URI
@@ -713,7 +799,8 @@ Sets up the parameters of the escrow.
   from human_protocol_sdk.escrow import EscrowClient
 
   def get_w3_with_priv_key(priv_key: str):
-      w3 = Web3(load_provider_from_uri(URI("http://localhost:8545")))
+      w3 = Web3(load_provider_from_uri(
+          URI("http://localhost:8545")))
       gas_payer = w3.eth.account.from_key(priv_key)
       w3.eth.default_account = gas_payer.address
       w3.middleware_onion.add(
@@ -725,27 +812,35 @@ Sets up the parameters of the escrow.
   (w3, gas_payer) = get_w3_with_priv_key('YOUR_PRIVATE_KEY')
   escrow_client = EscrowClient(w3)
 
-  escrow_address = "0x62dD51230A30401C455c8398d06F85e4EaB6309f"
+  escrow_address = "0x1234567890abcdef1234567890abcdef12345678"
   escrow_config = EscrowConfig(
-      "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-      "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-      "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-      10,
-      10,
-      10,
-      "htttp://localhost/manifest.json",
-      "b5dad76bf6772c0f07fd5e048f6e75a5f86ee079",
+      recording_oracle_address='0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef',
+      reputation_oracle_address='0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef',
+      exchange_oracle_address='0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef',
+      recording_oracle_fee=100,
+      reputation_oracle_fee=100,
+      exchange_oracle_fee=100,
+      recording_oracle_url='https://example.com/recording',
+      reputation_oracle_url='https://example.com/reputation',
+      exchange_oracle_url='https://example.com/exchange',
+      manifest_url='https://example.com/manifest',
+      manifest_hash='0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef'
+  )
+  escrow_client.setup(
+      escrow_address,
+      escrow_config
   )
-  escrow_client.setup(escrow_address, escrow_config)
   ```
+* **Return type:**
+  `None`
 
 #### store_results(escrow_address, url, hash, tx_options=None)
 
-Stores the results url.
+Stores the results URL.
 
 * **Parameters:**
   * **escrow_address** (`str`) – Address of the escrow
-  * **url** (`str`) – Results file url
+  * **url** (`str`) – Results file URL
   * **hash** (`str`) – Results file hash
   * **tx_options** (`Optional`[`TxParams`]) – (Optional) Additional transaction parameters
 * **Return type:**

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

@@ -6,7 +6,7 @@ Utility class for escrow-related operations.
 
 ```python
 from human_protocol_sdk.constants import ChainId
-from human_protocol_sdk.escrow import EscrowUtils, EscorwFilter, Status
+from human_protocol_sdk.escrow import EscrowUtils, EscrowFilter, Status
 
 print(
     EscrowUtils.get_escrows(
@@ -133,7 +133,7 @@ Retrieve status events for specified networks and statuses within a date range.
 
   print(
       EscrowUtils.get_status_events(
-          networks=[ChainId.POLYGON_AMOY, ChainId.ETHEREUM],
+          chain_id=ChainId.POLYGON_AMOY,
           statuses=[Status.Pending, Status.Paid],
           date_from=datetime(2023, 1, 1),
           date_to=datetime(2023, 12, 31),

docs/sdk/python/human_protocol_sdk.escrow.md

@@ -16,7 +16,9 @@ obtain information from both the contracts and subgraph.
     * [`EscrowClient.bulk_payout()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.bulk_payout)
     * [`EscrowClient.cancel()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.cancel)
     * [`EscrowClient.complete()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.complete)
+    * [`EscrowClient.create_bulk_payout_transaction()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.create_bulk_payout_transaction)
     * [`EscrowClient.create_escrow()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.create_escrow)
+    * [`EscrowClient.ensure_correct_bulk_payout_input()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.ensure_correct_bulk_payout_input)
     * [`EscrowClient.fund()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.fund)
     * [`EscrowClient.get_balance()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.get_balance)
     * [`EscrowClient.get_exchange_oracle_address()`](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClient.get_exchange_oracle_address)