How Crypto Escrow Disputes Work

Crypto escrow disputes on DeFiEscrow are a freeze. Any party can raise one while the escrow is Funded or Approved. Release stops being available. The wallet that raised the dispute is the only wallet that can remove it. If the freeze is still in place 30 days later, anyone can terminate the escrow and the people who deposited are refunded. Nobody is appointed to hear evidence, award a percentage, or pay the person who "should have won."

If you need that kind of hearing, you need a person or a forum outside this contract, and you need the off-chain agreement to say what the parties will do after the hearing. The contract will not carry it out. This page is the mechanism you actually have. The refund arithmetic is continued in dispute timeouts and refunds.

When a dispute can be raised

The function is raiseDispute. The caller must be a party. The state must be Funded or Approved. You cannot dispute an escrow that is still waiting for deposits in the Created state. You cannot dispute one that is already Released or Terminated. There is no reason field the contract stores as text. The transaction itself is the objection.

Raising the dispute saves the previous state, records who raised it, and records the time. The state becomes Disputed. release requires Approved, so it fails. Approvals and the ordinary timeout cancellation also do not proceed through the dispute. cancelAfterTimeout explicitly refuses while the escrow is disputed. The dispute clock replaces the deadline clock until the dispute ends.

Any party includes a depositor, a withdrawer, and an acknowledger. It does not include a random address that heard about the deal. If your lawyer needs the power to freeze the escrow, the lawyer's wallet has to be a party from the start.

Removing it, and the deadline you do not get back

removeDispute succeeds only for the address stored as the raiser, and only while the state is still Disputed. It puts the escrow back to Funded or Approved, whichever it was, and clears the dispute metadata. It does not add time to the funding deadline or the approval deadline.

That interaction matters. Suppose the approval deadline is tomorrow, the escrow is Funded, and you raise a dispute. You leave it in place for a week. You then remove it. The escrow returns to Funded, the approval deadline is already past, and cancelAfterTimeout can terminate it. You did not buy a week of extra negotiation inside the approval window. You stepped out of that window. If your goal was to pause and then continue toward release, only do this while there is still time, or while the state you will return to is already Approved, where the approval deadline no longer cancels the deal.

If you are not the raiser, you cannot clear someone else's dispute. You wait, or you wait out the 30 days and refund. There is no vote of the other parties that overrides the raiser.

What the freeze is for

Use it when release would be wrong and you need it to stop now. The important case is Approved. Every required person has approved, deadlines will not unwind the escrow, and someone is about to call release. A party who believes the off-chain conditions failed can dispute before that release. After release, the payouts are credited and a dispute is no longer available. Do not wait for a phone call if a release transaction is the thing you are trying to stop.

Use it less casually when the escrow is merely Funded and the approval deadline is already your exit. Refusing to approve, then letting the deadline refund deposits, is the ordinary "I do not accept this" path. A dispute is the path that installs a 30-day timer and takes the deadline timer offline. Those are different lengths. Pick the one you mean.

Do not use a dispute as a threat to extract a new price. The contract cannot pay a new price. The best a dispute can do, if it is not removed, is return deposits. A renegotiated price is a new escrow, created after this one is over.

The recommendation field is not a ruling

While the escrow is Disputed, submitDAORecommendation can store a 32-byte value. The function does not check that the caller is a party, an arbitrator, or anyone in particular. The stored value does not change approvals, fees, or balances. A later reader can see that some address wrote some hash at some time. They cannot pull tokens out with it. Ignore any explanation that says a DAO, a mediator, or a support team will "rule on the dispute" inside this contract. They can talk. They can even write that field. The tokens move only on remove-and-continue, or on the timeout refund, or not at all until one of those happens.

Deadlines remain the right tool for "we might not agree, and the deposit should come home on a date we chose." Disputes are the right tool for "stop release." Using each one for the other's job is how people end up waiting 30 days for an outcome a deadline would have produced sooner, or watching a release land because they thought a deadline still applied after approval.