Module dao::bid_escrow::contract

source ·
Expand description

Contains Bid Escrow Contract definition and related abstractions.

§Definitions

  • Job Offer - A description of a Job posted by JobPoster
  • Bid - on offer that can be accepted by the Job Poster
  • JobPoster - user of the system that posts a Job Offer; it has to be KYC’d
  • Worker - the user who does a job
  • Internal Worker - a Worker who completed the KYC and was voted to be a VotingAssociate
  • External Worker - a Worker who completed the KYC and is not a Voting Associate
  • Voting Associate (or VA) - users of the system with Reputation and permissions to vote
  • KYC - Know Your Customer, a process that validates that the user can be the user of the system
  • Bid Escrow Voting - Mints reputation

§Posting

The first step of the Bid Escrow process is Posting a Job Offer. It is done by JobPoster by sending a query to a BidEscrow contract containing:

  • Expected timeframe for completing a Job
  • Maximum budget for a Job With the query, the JobPoster sends a DOS fee in CSPR. The minimum amount of a DOS fee is defined in Variable Repository Contract under the keyPostJobDOSFee. This action creates a new object in the contract called Job Offer and starts the Bidding process.

§Bidding

The Bidding process allows Workers to post Bids with the offer of completing a job. It is divided into two main parts.

§Internal Auction

During this part of the Bidding process only the VAs can bid. As the VAs have Reputation, they are bidding using Reputation as a stake. The Bid query to the contract consists of:

  • Proposed timeframe for completing the Job.
  • Proposed payment for the Job.
  • The amount of Reputation the Internal Worker stakes on this Job.

The Bid is then added to a list of available bids in the contract storage and is available for picking by the Job Poster. The time of an Internal Auction is defined in a Governance Variable InternalAuctionTime. The bidding process can already be completed here, if the JobPoster decides to chose one of the posted Bids before Internal Auction ends. However, if no Bid is picked during this time, the process becomes a Public Auction.

§Public Auction

If no Internal Worker decides to post a Bid on a Job Offer, or the Job Poster did not pick any bid during Internal Auction, the External Workers have a chance of submitting their bids during Public Auction time. As External Workers do not have any Reputation to stake, they are staking CSPR.

A query to the contract in case of External Workers consists of:

  • Proposed timeframe for completing the Job.
  • Proposed payment for the Job.
  • Decision if the Worker wants to become a Voting Associate if the Job is completed.
  • CSPR stake sent alongside the query Internal Workers by default cannot to submit their bids during Public Auction, however this behavior is configurable using VACanBidOnPublicAuction Governance Variable.

The time of a Public Auction is defined in a Governance Variable PublicAuctionTime.

§Picking a Bid

During the Auction process the Job Poster can pick a Bid. When no Bid is posted or selected by Job Poster during both auctions, the Job is cancelled, DOS Fee is returned to the Job Poster and stakes sent by the Bidders are returned to them.

§Submitting a Job Proof

Now the Worker has the time to complete the Job and submit its proof to the contract. After the works have been completed, the Worker sends a query to the contract containing the cryptographic hash of a document being a proof of Work done for a Job Poster.

When no Bid is posted or selected by the Job Poster during both auctions, the Job is cancelled, DOS Fee is returned to the Job Poster and stakes sent by the Bidders are returned to them.

§Voting

The Voting process is managed by VotingEngine.

§Voting passed

Besides yielding a positive result, the Voting passed means that the Reputation staked by the losing side is redistributed between the winning side, depending on the type of Worker.

§External Worker who wanted to become VA

  • The External Worker becomes VA.
  • The CSPR that were sent by the External Worker as a stake is returned to the External Worker.
  • Reputation of the voters who voted yes is returned to them.
  • Reputation of the voters who voted no is redistributed between the voters who voted yes proportional to the amount of reputation staked in the voting.
  • Reputation minted for the External Worker and used in the voting process is burned.

§Internal Worker

  • Reputation of the voters who voted yes is returned to them.
  • Reputation of the voters who voted no is redistributed between the voters who voted yes proportional to the amount of reputation staked in the voting.

§External Worker

  • The CSPR that were sent by the External Worker as a stake is returned to the External Worker.
  • Reputation minted for the External Worker and used in the voting process is burned.
  • Reputation of the voters who voted yes is returned to them, except for the Reputation minted for the Worker using CSPR stake.
  • Reputation of the voters who voted no is redistributed between the voters who voted yes proportional to the amount of reputation staked in the voting (External Worker does not receive Reputation in this step).

§Payment CSPR Redistribution

Reputation used for the Voting and minted after a successful Job has been redistributed during the above process, but there is CSPR to redistribute that was allocated to the Job. How much resources is redistributed and to whom depends on the type of Worker and whether it wanted to become a VA.

§Payment pool

The CSPR to redistribute is calculated using a formula: payment pool = job price

§External Worker who wants to become VA

As the External Worker now is the VA, it is considered to be an Internal Worker in this scenario.

§Internal Worker

Firstly the Governance Payment is calculated using a formula:

governance payment = payment pool * BidEscrowPaymentRatio Read more.

The Governance Payment is then transferred to a multisig wallet, which address is held in the Variable Repository Contract called BidEscrowWalletAddress. The rest of the payment is redistributed between all of the VAs'.

remaining amount = payment pool - governance payment

§External Worker

If the Job was done by an External Worker who didn’t want to become a VA, the first step is the same as in the case of Internal Worker - Governance Payment is being made. However the rest is then divided between the External Worker and the VAs’.

Firstly to get the amount that VA’s receive we use a formula:

VA payment amount = remaining amount * DefaultPolicingRate Read more

Then, the rest is transferred to the External Worker:

External Worker payment amount = payment pool- governance payment - VA payment amount

§Voting failed

Besides yielding a negative result, the Voting passed means that the Reputation staked by the losing side is redistributed between the winning side, depending on the type of Worker.

§External Worker who wanted to become VA

  • The External Worked DOES NOT become a VA.
  • The CSPR that were sent by the External Worker as a stake is redistributed between the VA’s.
  • The Reputation minted for the External Worker using CSPR stake is burned.
  • Reputation of the voters who voted no is returned to them.
  • Reputation of the voters who voted yes is redistributed between the voters who voted no proportional to the amount of reputation staked in the voting.

§Internal Worker

  • Reputation of the voters who voted no is returned to them.
  • Reputation of the voters who voted yes is redistributed between the voters who voted no proportional to the amount of reputation staked in the voting.

§External Worker

The CSPR that were sent by the External Worker as a stake is redistributed between the VA’s. The Reputation minted for the External Worker using CSPR stake is burned. Reputation of the voters who voted no is returned to them. Reputation of the voters who voted yes is redistributed between the voters who voted no proportional to the amount of reputation staked in the voting.

§CSPR

If the Voting fails, the CSPR sent to the contract as a payment for Job is returned to the Job Poster. If the work has been attempted to do by an External Worker the CSPR that the Worker staked during the Bid process is redistributed between all VA’s.

§Quorum not reached

When the Quorum is not reached during the Formal Voting, following things happen:

  • The process ends here.
  • VA’s stakes are returned to them.
  • Job Poster payment and `DOS fee is returned.
  • Internal Worker’s Reputation and External Worker’s CSPR stake is returned.
  • External Worker’s Reputation that was minted using CSPR stake is burned.

§Returning DOS Fee

The final step of the process is returning the CSPR DOS Fee to the Job Poster.

§Grace Period

However, if External Worker do not post a Job Proof in time, his CSPR stake is redistributed between all VA’s. In case of Internal Worker, his staked Reputation gets burned and it undergoes the Automated Reputation slashing see Slashing Voter. Then the process enters a Grace period (with the timeframe the same as the timeframe of the work for Worker). During this period, anyone (VA, External Worker, even the original Worker) can submit the Job Proof, becoming the new Worker and participating in the reward mechanism. Alongside the Job Proof, a Worker needs to send a stake in form of Reputation (or CSPR for External Worker). This stake will behave in the same manner as stake sent by the original Worker. If nobody submits the Job Proof during the grace period, the whole process ends. The CSPR paid by the Job Poster is returned along with the DOS Fee. This is a special implementation of [positional parameters].

Structs§