Escrow.sol

The Escrow contract is a core component of the HUMAN Protocol ecosystem. It securely manages ERC-20 token funds for transactions between job requesters (launchers) and workers, while paying protocol oracles and enforcing a clearly-defined life-cycle that guarantees transparency and trustlessness.

Key Features and Components

ERC20 Token Compatibility

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

Roles

Role	Capabilities
Launcher	Creates the escrow, can set it up, request cancellation, withdraw excess tokens, and receives leftover funds when the escrow is finished.
Admin	Privileged address that can perform all actions over the contract. It will be used to prevent abuses.
Exchange Oracle	Distributes tasks to workers, ensuring efficient task allocation and completion. Receives a fee.
Recording Oracle	Records intermediate results and may reserve funds for upcoming payouts. Receives a fee.
Reputation Oracle	Scores worker performance and triggers bulk payouts. Receives a fee.

Fees

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

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.
• ToCancel: Indicates that the launcher has started the cancellation process.
• 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 (admin or designated roles) 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 admin addresses.
• A duration (which, when added to the current block timestamp, sets the expiry time).
• 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. Anyone can deposit tokens at any time, but only the balance present before setup call is locked for payouts.
• Two events are emitted:
  • PendingV2:detailing the manifest and oracle addresses.
  • Fund:with the escrow’s balance.
• Can be called by:
  • Launcher.
  • Admin.
• Conditions:
  • Not expired.

Store Results

The contract allows for the storage of intermediate results. This ensures traceability of results throughout the escrow process and reserves funds for the next payout.

• Emits the IntermediateStorage event with the provided URL, hash and funds reserved.
• Can be called by:
  • Recording Oracle.
  • Admin.
• Conditions:
  • Not expired.
  • Status is Pending , Partial or ToCancel.

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 and reserved funds balance.
• Emits the BulkTransferV3 event including a payout 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. If status is ToCancel and remainingFunds is 0 the new status will be Cancelled.
• Can be called by:
  • Reputation Oracle.
  • Admin.
• Conditions:
  • Not expired.
  • Balance > 0.
  • Total amount <= reserved funds.
  • Payout id not used before.
  • Recipients and amounts lengths matching.

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.
  • Admin.
• Conditions:
  • Not expired.
  • Status is Paid or Partial.

Cancel

• Initiates cancellation process.
• Changes the status to ToCancel.
• Emits the CancellationRequested event.
• Can be called by:
  • Launcher.
  • Admin.
• Conditions:
  • Balance > 0; status is not 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).
• Emits the Withdraw event.
• Can be called by:
  • Launcher.
  • Admin.

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.