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
orPartial
.
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
orPartial
.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
orComplete
.
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.
Last updated
Was this helpful?