Smart contracts are self-executing agreements with the terms directly written into code on a blockchain. They automatically execute and enforce obligations when predefined conditions are met, enabling the transparent, traceable, and irreversible exchange of value without relying on traditional intermediaries like banks or legal entities.
The XRP Ledger supports a powerful form of smart contracts through its Escrow feature. You can create escrows that release XRP either after a specific time or once a cryptographic condition is fulfilled. This guide explains how to use a conditional escrow as a smart contract, providing a secure, trust-minimized way to handle agreements.
How a Smart Contract Escrow Works
Let’s consider a practical scenario:
A party host wants to pay a party band 2000 XRP once their performance is complete. A party planner acts as a neutral third party (an oracle) to verify that the band has performed satisfactorily.
In this setup:
- The party host is the sender who locks the XRP in the escrow.
- The party band is the receiver who gets paid upon fulfillment.
- The party planner is the oracle who confirms the real-world event (the performance) and provides the cryptographic proof to release the funds.
This structure ensures that the oracle never directly controls the funds, reducing risk and increasing transparency.
Prerequisites for Using an Escrow Smart Contract
For the Sender (Party Host)
- An XRP Ledger account with sufficient XRP to cover the escrow amount and transaction fees.
- Access to a
rippledserver to submit and sign transactions.
For the Receiver (Party Band)
- An XRP Ledger account to receive the escrowed XRP.
- Access to a
rippledserver to monitor transactions and submit the fulfillment.
For the Oracle (Party Planner)
- The ability to generate a cryptographic condition and fulfillment.
- A secure method to communicate the fulfillment to the receiver when conditions are met.
- The capability to verify that the receiver has met their obligations.
Defining the Smart Contract Terms
Before creating the escrow, all parties must agree on the terms:
- Expiration Time: The escrow should have a cancellation time (e.g., 12:00 PM the day after the party). This ensures that if the band doesn’t perform, the host can reclaim the XRP after the deadline.
- Amount: 2000 XRP, the agreed-upon fee for the band.
- Accounts: The escrow locks XRP from the host’s account and releases it to the band’s account upon successful fulfillment.
Time-based conditions are optional but recommended to prevent funds from being locked indefinitely.
Step-by-Step Process
1. Generate a Condition and Fulfillment
The oracle (party planner) generates a cryptographic condition and a corresponding fulfillment value. The condition is shared with both the sender and receiver, while the fulfillment is kept secret until the band has performed.
👉 Learn how to generate conditions and fulfillments
2. Calculate Time Values
The sender calculates the CancelAfter time value based on the agreed expiration time, using Unix timestamp format.
3. Create the Escrow
The sender submits an EscrowCreate transaction to the XRP Ledger, specifying:
- The amount to lock (2000 XRP).
- The receiver’s address.
- The cryptographic condition.
- The
CancelAftertime.
4. Confirm Escrow Creation
After the transaction is validated, the sender shares the transaction hash with the receiver. The receiver verifies that the escrow details match the agreed terms and that the condition is correct.
5. Fulfill the Condition
Once the band performs, the oracle provides the fulfillment to the receiver. The receiver submits an EscrowFinish transaction with the fulfillment before the expiration time.
6. Confirm Completion
After validation, the receiver confirms the XRP balance has increased by 2000 XRP. The sender can also verify the transaction using the provided hash.
If the fulfillment isn’t submitted before the expiration, the sender (or anyone) can cancel the escrow to reclaim the XRP.
Benefits of Using XRP Ledger Escrows
- No Middlemen: Escrows eliminate the need for trusted third parties to hold funds.
- Transparency: All transactions are publicly verifiable on the ledger.
- Security: Cryptographic conditions ensure that funds are only released when obligations are met.
- Flexibility: Supports both time-based and condition-based releases.
Frequently Asked Questions
What is a smart contract escrow?
A smart contract escrow is a self-executing agreement that locks funds until predefined conditions are met. On the XRP Ledger, this is implemented using conditional escrows.
Can the oracle access the locked funds?
No. The oracle only provides the cryptographic proof to release the funds but never controls them directly.
What happens if the fulfillment is not submitted on time?
If the receiver doesn’t submit the fulfillment before the CancelAfter time, the escrow expires, and the sender can reclaim the XRP.
Is it possible to modify an escrow after creation?
No. Once created, escrows are immutable. All terms must be agreed upon and set correctly during the EscrowCreate transaction.
Can I use escrows for assets other than XRP?
The native escrow feature on the XRP Ledger currently supports only XRP. However, other token types can be managed using higher-layer solutions.
How are transaction fees handled?
Each transaction (create, finish, cancel) requires a small fee in XRP, paid by the account submitting the transaction.
Conclusion
XRP Ledger escrows provide a robust, decentralized way to implement smart contracts for conditional payments. By combining cryptographic conditions with time-based expirations, users can create secure, transparent, and automated agreements without intermediaries.
Whether you’re managing payments between parties, releasing funds upon deliverables, or creating complex conditional logic, escrows on the XRP Ledger offer a flexible and efficient solution.