Escrow.sol

The Escrow contract is a core component of the HUMAN Protocol ecosystem. It securely manages token funds (using any ERC20 token) for transactions between job requesters and workers. The contract provides a transparent, trustless mechanism for task-related payments and fee distributions. upon the successful completion of tasks.

Key Features and Components

ERC20 Token Compatibility

The contract supports transactions with any ERC20 compliant token, allowing for flexible payment options within the ecosystem.

Trusted Handlers

Designated addresses have privileged access to perform critical operations within the contract, enhancing security and control over the escrow process.

Oracle Integration

Three types of oracles interact with the contract:

• Reputation Oracle: Evaluates worker performance and determines the distribution of rewards based on worker reputation.

• Recording Oracle: Records task completion and worker performance.

• Exchange Oracle: Facilitates the distribution of tasks to workers, ensuring efficient task allocation and completion.

Each oracle is assigned a fee percentage that is deducted from payouts.

Dynamic Fee Structure

Oracle fees are predetermined and automatically deducted from payouts, ensuring fair compensation for oracle services. The sum of these fees must not exceed 100%, ensuring that payouts are correctly adjusted.

Bulk Payment Functionality

The contract supports bulk payout operations. This allows for the distribution of payments to multiple recipients in a single transaction while deducting the respective oracle fees.

Contract Status Management

The contract's lifecycle is managed through various statuses, ensuring that operations are executed in a logical sequence.

• Launched: Initial state after deployment.

• Pending: Set during setup after specifying oracle addresses, fees, and job manifest details.

• Partial / Paid: Determined by the state of funds after bulk payouts.

• Complete: Indicates that the escrow has fully processed payouts and final settlements.

• Cancelled: Indicates that the escrow was terminated, returning the remaining funds to the canceler.

Security Measures

The contract uses several modifiers to ensure that:

• Only authorized addresses (trusted handlers or designated oracles) can call sensitive functions.

• Operations are executed only if the contract is in the correct state (e.g., not expired, not already complete).

• The contract’s funds are protected against reentrancy attacks.

Workflow/Functions

Initialization

Upon deployment, the contract is initialized with:

• The ERC20 token address.

• The launcher and canceler addresses.

• A duration (which, when added to the current block timestamp, sets the expiry time).

• An array of additional trusted handler addresses.

• The contract is initially set to the Launched status.

Funding

Funds can be deposited into the contract at any stage, but only funds sent before setup call will be used for payouts.

Setup

• Sets the addresses of the reputation, recording, and exchange oracles.

• Defines each oracle’s fee percentage (ensuring the total does not exceed 100%).

• Stores the job manifest details (a URL and hash).

• Transitions the contract to the Pending status.

• Captures the current token balance as the remaining funds.

• Two events are emitted:

  • PendingV2:detailing the manifest and oracle addresses.

  • Fund:with the escrow’s balance.

• Can be called by:

  • Trusted handlers.

• Conditions:

  • Not expired.

Store Results

The contract allows for the storage of intermediate results. This ensures traceability of results throughout the escrow process.

• Emits the IntermediateStorage event with the provided URL and hash.

• Can be called by:

  • Recording Oracle

  • Trusted handlers.

• Conditions:

  • Not expired.

  • Status is Pending or Partial.

Bulk Payouts

This function is used to distribute funds to multiple recipients in one call. It:

• Verifies that recipient and amount arrays match and meet limits (including a maximum count and aggregate value).

• Deducts the appropriate fees (based on the combined oracle fee percentages) from each recipient’s amount.

• Transfers fees directly to each oracle.

• Updates the remaining funds balance.

• Emits the BulkTransferV2 event including a transaction ID and final results URL.

• If either the escrow’s balance is zero or forceComplete is set, Complete status is set to finalize the contract status and remaining funds are sent to the requester; otherwise, it sets the status to Partial.

• Can be called by:

  • Reputation Oracle

  • Trusted handlers.

• Conditions:

  • Not expired.

  • Balance > 0.

  • Status is Pending or Partial.

  • Status is not Paid.

Complete

• This function transfers any remaining funds back to the launcher and finalizes the contract with a Complete status.

• Emits the Completed event.

• Can be called by:

  • Reputation Oracle

  • Trusted handlers.

• Conditions:

  • Not expired.

  • Status is Paid.

Cancel

• Returns all remaining funds to the canceler.

• Changes the status to Cancelled.

• Emits the Cancelled event.

• Can be called by:

  • Trusted handlers.

• Conditions:

  • Balance > 0.

  • Status is not Paid or Complete.

Withdraw

This function was implemented to avoid the lock of funds in the contract.

• Lets trusted handlers withdraw excess tokens from the contract (tokens that exceed the escrow’s remaining funds for the designated token or any other token).

• Can be called by:

  • Trusted handlers.

Security and Trust

The contract employs multiple security measures, including reentrancy guards and modifiers, to ensure operations are executed by authorized parties and under appropriate conditions. It also emits events for key operations, allowing external monitoring and interaction with the contract's activities.