Using Crypto Conditions

The XRP Ledger currently supports PREIMAGE-SHA-256 conditions, a special case in the Cryptoconditions spec. Also called a "hashlock", this is the most basic kind of cryptocondition.

Generating a condition

To generate a PREIMAGE-SHA-256 condition, you start by creating the fulfillment (a type sign plus arbitrary bytes, usually random), then generate a condition which contains the hash of that fulfillment and some metadata like its size in bytes. You can use the five-bells-condition library to do this.

Verifying a fulfillment

Verifying a fulfillment for a condition means parsing the format of both, then calculating that the hash of the arbitrary data from the fulfillment is equal to the expected value in the condition. This is what the validateFulfillment(fulfillment, condition) method of the five-bells-condition library does. That function takes either strings (in the URI format) or Buffers (in the binary format). When working with the XRP Ledger, you should use the binary format, converting the Buffers to hex and back.

A code sample can be found here: https://github.com/ripple/ripple-dev-portal/blob/master/content/_code-samples/escrow/makecondition.js

const cc = require('five-bells-condition')
const crypto = require('crypto')
    
const preimageData = crypto.randomBytes(32)
const myFulfillment = new cc.PreimageSha256()
myFulfillment.setPreimage(preimageData)

const condition = myFulfillment.getConditionBinary().toString('hex').toUpperCase()
console.log('Condition:', condition)

const fulfillment = myFulfillment.serializeBinary().toString('hex').toUpperCase()
console.log('Fulfillment:', fulfillment)

const myCondition = cc.fulfillmentToCondition(myFulfillment)
console.log(cc.validateFulfillment(myFulfillment, myCondition)) // true

In your EscrowCreate transaction, set Condition to condition.

In the EscrowFinish transaction, set the matching Fulfillment and Condition. The Account is the sender of the EscrowFinish transaction. The Owner is the sender of the original EscrowCreate transaction. You can finish an escrow that someone else started (for example, if it pays you).

Use Case: Interledger Protocol

If you want to chain together several payments, including one going through the XRP Ledger:

The ultimate receiver generates the fulfillment and condition, then keeps the fulfillment secret and sends the condition back up the chain (or back to the initial sender).

The initial sender prepares a conditional payment with the condition they were given.

The next hop ("M") prepares a conditional payment with the same condition. So if the person receiving that one provides the fulfillment to receive money from M, then M can see that fulfillment and use it to unlock the conditional payment from the initial sender.

You can chain this indefinitely to create a chain that, as long as people manage their expiration times reasonably and no ledgers break, can prepare all the transfers and then unlock all of them only if the ultimate receiver on the end gets paid.