Skip to content

Use Escrow ​

Escrow lets two parties make an agreement and hold the payment in a smart contract until the agreement is settled.

These steps require an existing Escrow instance. Check the Gallery for a published instance, or get its network and CAM host address from a trusted publisher and open it in a viewer. For practice without a published instance, run the local demo, which requires a source checkout.

For example, a client hires a developer to build a website for $2,000. The client deposits the money on-chain, where the smart contract holds it until the agreement is settled.

The agreement identifies the parties, payment amount, deadlines and rules for releasing the money. These are recorded on-chain, while detailed contract documents are stored off-chain, with their references and cryptographic hashes recorded on-chain.

The developer accepts the agreement and later submits the completed work. The work itself remains off-chain, while its submission is recorded on-chain.

The client can approve the work or raise a dispute. If there is a dispute, a designated arbitrator decides whether the client or developer receives the money.

Approvals, disputes, decisions and settlement are recorded on-chain. Once the agreement is settled, the recipient can withdraw the funds from the smart contract.

Agree on the three parties first

PartyResponsibility
ClientCreates and funds; approves work or opens a dispute.
ContractorAccepts the agreement and submits work evidence.
ArbitratorAwards the whole disputed amount to either party before the arbitration deadline.

Addresses must be pairwise distinct. Contractor and arbitrator must be nonzero and not the escrow contract. The client chooses the arbitrator; there is no on-chain acknowledgement or fee for that role. Agree on participation and terms before committing money.

1. Create and fund as client

Open the selected app and connect the client wallet. Choose Create an agreement. Enter an exact reference unique to this client on this escrow contract; it cannot be reused after closure and is limited to 128 UTF-8 bytes.

Supply the contractor, arbitrator, positive payment and four phase durations. Durations are whole seconds from 1 to 31,536,000. Choose the immutable arbitration-timeout recipient: client or contractor. Supply the terms URI and nonzero SHA-256 digest using Prepare Escrow documents.

Choose Create agreement, review the destination and native value, then send with the wallet. Creation transfers exactly the specified payment into escrow; gas is separate. Save the successful receipt's agreement ID with the chain and escrow address. Reopen by ID or by the same client and exact reference, including case and spaces.

Result: the agreement is Funded, awaiting contractor acceptance. The ID identifies the client/reference pair; it is not a hash of every term. Creation and cancellation source.

2. Accept and submit as contractor

Connect the contractor wallet, reopen the agreement and check the terms, amount and deadlines. Choose Accept agreement before acceptance expires. The successful transaction starts the work clock.

When ready, prepare the work document's URI and digest and choose Submit work evidence before the work deadline. Wait for the receipt and the Submitted state; this starts the client's review clock. A document URL alone does not prove delivery or quality. Acceptance and submission source.

3. Approve or dispute as client

Inspect the submitted evidence. Before the review deadline, choose Approve work and credit contractor, or provide dispute evidence and choose Dispute submission.

For a dispute, the arbitrator can choose Award escrow to client or Award escrow to contractor before its deadline. There is no split award, appeal or second submission. If arbitration times out, anyone can finalize to the recipient fixed at creation. Review, arbitration and timeout source.

When a deadline passes

Before-deadline actions require the executing block's time to be strictly earlier than the deadline. At or after it, a timeout transaction becomes available. Time passing does not submit that transaction automatically.

State and clock startsNormal actionTimeout credits
Funded — creationContractor accepts; client can cancel.Client
Accepted — acceptanceContractor submits work.Client
Submitted — submissionClient approves or disputes.Contractor
Disputed — disputeArbitrator awards to one party.The recipient fixed at creation

Refresh to read the latest action availability. Disabled controls describe the last read, not a guarantee about a future transaction. The contract checks role, state and deadline again. Terminal states cannot reopen; there are no extensions, amendments or multiple milestones in this contract. Authoritative action conditions.

4. Withdraw the credited payment

Settlement closes the agreement and adds its whole amount to the beneficiary's credit. It does not send coins to that wallet. Connect the beneficiary account and choose View credit for viewed account.

Enter the recipient and choose Withdraw credit. This sends the account's complete aggregated unwithdrawn credit from this escrow contract and chain, not just this agreement's amount. The recipient can differ from the credit owner, but cannot be zero or the escrow contract and must accept the native payment.

Only the credit owner can authorize withdrawal. A failed transfer reverts it and preserves the credit. After an uncertain submission, inspect the receipt and refreshed credit before retrying. Withdrawal source.

Try with disposable local accounts

Complete source setup, then run:

make escrow/local/demo/gui/up \
  DOCKER_CONTEXT=your-local-context COMPOSE_PROJECT_NAME=cam-demo

Keep it running and open the complete printed URL, normally on loopback port 5174. Follow Attach a local test wallet with FIXTURE_WALLET_APP=escrow and the same context/project. The selector provides client, contractor and arbitrator; named roles do not bypass contract permissions.

Practice the steps above with a small amount in the wei input, a new reference and documents you control. After detaching the wallet, stop the launcher or explicitly remove the same demo:

make escrow/local/demo/gui/down \
  DOCKER_CONTEXT=your-local-context COMPOSE_PROJECT_NAME=cam-demo

For automated contract/viewer coverage, make escrow/local/scenario/run exercises nine terminal paths and full credit withdrawal on its own disposable chain. That is test evidence, not a public deployment.

Deploy and trust the right components

The core is immutable: no owner, pause, fee, sweep or upgrade path. Its read-only projection does not authorize payments. The separately owned CAM host can change published resources and bindings. Confirm the intended chain and contracts, not merely the app's label.

Use Escrow deployment settings with the shared deployment procedure. This guide follows source 04a18763; older deployments keep their original code and must use compatible publications.