Time locks and conditions

An escrow is always in one of a few states.

Held. The finish time has not come. Nothing can be done.

Ready. The finish time has passed and there is no password. Anyone can finish it, and the recipient gets paid.

Conditionally ready. There is a password. The escrow can be finished only by someone who shows it. If there is also a finish time, that time must pass first.

Expired. The expiration time passed before anyone finished it. It can no longer pay the recipient. Anyone can cancel it, and the sender gets the funds back.

The password is called a fulfillment. The escrow stores only a fingerprint of it, called the condition. Showing the condition tells nobody the password. Whoever knows the password can finish the escrow, so it stays secret until it is time to release.

A common pattern: the sender makes the password, locks funds with its fingerprint and sets an expiration. When the other side delivers what was agreed, the sender hands over the password. If that never happens, the escrow expires and the sender cancels it.

A conditional escrow always needs an expiration. Otherwise a lost password would lock the funds for good.

Times. FinishAfter and CancelAfter are seconds since the Ripple Epoch, January 1, 2000 (00:00 UTC). That is 946684800 seconds after the Unix epoch. Both are compared with the close time of the previous ledger, not a wall clock.

EscrowFinish takes Owner, OfferSequence and, for conditional escrows, Condition and Fulfillment. Any account may send it.

• It fails before FinishAfter.
• It fails without a matching Fulfillment when the escrow has a Condition.
• It fails after CancelAfter.

EscrowCancel takes Owner and OfferSequence. Any account may send it.

• It fails if the escrow has no CancelAfter.
• It fails until CancelAfter has passed.

An expired escrow stays in the ledger, and keeps the sender's reserve locked, until someone cancels it.

Crypto-conditions. The only supported type is PREIMAGE-SHA-256. Condition and fulfillment are hex strings in the crypto-conditions format. Use a crypto-conditions library to build them from random bytes. Anyone holding the fulfillment can finish the escrow, and a fulfillment becomes public once it is used in a transaction.

Cost of a conditional finish. Verifying a fulfillment costs more than a normal transaction:

reference_fee * (signer_count + 33 + (fulfillment_bytes / 16))

With a reference cost of 10 drops, that is a minimum of 330 drops plus 10 drops per 16 bytes of fulfillment. A finish with no fulfillment pays the normal cost.

States by field combination

Deposit Authorization. EscrowFinish accepts CredentialIDs, a set of credentials that authorize the deposit when the recipient restricts incoming payments.

Related: Locking funds on the ledger, Fees and burn, Smart Escrows.