Skip to main content

Escrow

escrw.worlds

This contract is responsible for holding the secured funds for worker proposals until the elected custodians or an agreed arbitrator releases the funds to the receiver or the escrow time limit expires which would allow returning of funds to the sender. It is designed to be used in close connection with the worker proposal contract but it could be used in isolation or with other contracts that need an escrow function.

Actions:​

Initialise an escrow transaction escrw.worlds::init​

An escrow transaction must be initialised specifying all the required fields including the sender, intended receiver, expiry time, arbitrator, memo for the eventual transfer action. There is also an optional external key which can be used as a cross-contract reference key rather than only relying on the internal auto-incrementing key which would otherwise lead to key collisions in time.

Transfer funds for an escrow escrw.worlds::transfer​

Funds for an escrow would need to be transferred to escrow contract using the usual transfer action as seen and replicated by most EOS based token contracts. This contract’s code relies on the built-in notifications that the transfer action directs to both the sender and receiver of accounts of the transfer. When a transfer notification is received by the escrow contract the transfer action implementation will verify the sender has an empty escrow record and assigns the amount transferred into that escrow record for later processing by the other actions in the escrow contract code. An initialised escrow record may be cancelled with the cancel action provided it is called before the transfer action has populated the escrow.

Cancel a new escrow escrw.worlds::cancel​

Once an escrow has been initialised but not yet funded with a transfer, this action will be able to cancel the escrow. Once the escrow has been funded then it can no longer be cancelled and needs to play through the other actions.

Approval or un-approval of an escrow​

escrw.worlds::approve escrw.worlds::disapprove

Once an escrow has been initialised and populated with a transfer action the next step would be to approve the escrow either by the sender, the nominated arbitrator or receiver. Two approvals are required from any of these three accounts to allow the claim action to be performed. disapprove may be subsequently called to remove an existing approval by the relevant actor.

Claim an approved escrow payment escrw.worlds::claim​

The claim action can only be executed by the intended receiver for an escrow payment and will only succeed with the correct approval state for the escrow record. At this point, the escrowed amount will be transferred to the nominated service company account so that payments can be processed to the intended receiver.

Dispute before expiry escrw.worlds::dispute​

If a related proposal is not getting the required approvals to authorise payment to the worker and the worker believes that is not fair then they can dispute the propsal/escrow which will put the escrow into a state of dispute. Once in this state the nominated arbitrator is authorised to step in and make a judgement eaither way and can then direct if the payment should be sent to the worker or back to the DAO.

Refund after expiry escrw.worlds::refund​

While the funds in the escrow account must be locked up for a certain duration they must also be available after expiry time has passed if there has not been sufficient approval from the sender or the arbitrator otherwise there could be funds locked in the account permanently. The refund action provides this mechanism and can only be called by the sender if the expiry time has passed. Then the escrowed amount will be transferred back the sender and the escrow record will be removed from the table on chain.

Tables​

Escrow records escrw.worlds::escrows​

  • key - (name) Primary identifier key for the escrow record
  • sender - (name) account paying for the escrow amount
  • receiver - (name) account intended to receive the escrow amount
  • arb - (name) account of an agreed arbitrator who can resolve disputes
  • receiver_pay - (extended_asset) the amount due to be paid
  • arbitrator_pay - (extended_asset) the amount to pay the arbitrator if required
  • memo - (string) The memo string to insert in the token transfer
  • expires - (time_point_sec) The timestamp when the escrow expires and can be refunded back to the sender
  • disputed - (bool) a state flag to indicate if it's in dispute and allows the arbitrator to step in.