XRPL Escrow

A TypeScript helper library built on xrpl.js for creating and interacting with XRPL escrows.

Quick Start

import { Client, Wallet, xrpToDrops, unixTimeToRippleTime } from "xrpl";
import { XRPLEscrow } from "@yourcompany/xrpl-escrow";
import { Effect } from "effect";
import * as crypto from "crypto";

// Connect to XRPL
const client = new Client("wss://s.altnet.rippletest.net:51233/");
await client.connect();

// Setup wallets
const walletAlice = Wallet.fromSeed("your-seed");
const walletBob = Wallet.fromSeed("bob-seed");

// Create escrow instance
const escrow = new XRPLEscrow(client, walletAlice);

// Generate secret and hash
const preimage = crypto.randomBytes(32).toString("hex");
const hash = crypto.createHash("sha256").update(Buffer.from(preimage, "hex")).digest("hex");

// Create escrow (Alice → Bob, 10 XRP, expires in 1 hour)
const cancelAfter = unixTimeToRippleTime(Date.now() + 3600 * 1000);
const createResult = await Effect.runPromise(
    escrow.create(walletBob.address, xrpToDrops("10"), cancelAfter, hash)
);

const sequence = createResult.result.tx_json.Sequence;
console.log("Escrow created, sequence:", sequence);

// Wait for ledger validation
await new Promise(r => setTimeout(r, 6000));

// Finish escrow (Bob receives funds)
const escrowBob = new XRPLEscrow(client, walletBob);
const finishResult = await Effect.runPromise(
    escrowBob.finish(walletAlice.address, sequence, preimage)
);

console.log("Escrow finished!");

API

new XRPLEscrow(client, wallet)

Creates an escrow instance.

create(destination, amount, cancelAfter, secretHash)

Creates an escrow transaction.

const result = await Effect.runPromise(
    escrow.create(
        "rDestination...",     // Destination address
        xrpToDrops("10"),      // Amount in drops
        cancelAfter,           // Ripple epoch timestamp
        hash                   // SHA256 hash (64 hex chars)
    )
);

finish(owner, offerSequence, preimage)

Completes an escrow by providing the secret.

const result = await Effect.runPromise(
    escrow.finish(
        "rOwner...",           // Original escrow creator
        12345,                 // Sequence from create transaction
        preimage               // Secret (64 hex chars)
    )
);

cancel(owner, offerSequence)

Cancels an escrow after CancelAfter time passes.

const result = await Effect.runPromise(
    escrow.cancel(
        "rOwner...",           // Original escrow creator
        12345                  // Sequence from create transaction
    )
);

Examples

Cancel Escrow

// Create with short expiry (10 seconds)
const cancelAfter = unixTimeToRippleTime(Date.now() + 10 * 1000);
const createResult = await Effect.runPromise(
    escrow.create(walletBob.address, xrpToDrops("10"), cancelAfter, hash)
);

const sequence = createResult.result.tx_json.Sequence;

// Wait for expiry
await new Promise(r => setTimeout(r, 15000));

// Cancel and get funds back
await Effect.runPromise(escrow.cancel(walletAlice.address, sequence));

Third Party Finish

// Alice creates escrow to Bob
const createResult = await Effect.runPromise(
    escrow.create(walletBob.address, xrpToDrops("10"), cancelAfter, hash)
);

// Charlie finishes it (funds still go to Bob)
const escrowCharlie = new XRPLEscrow(client, walletCharlie);
await Effect.runPromise(
    escrowCharlie.finish(walletAlice.address, sequence, preimage)
);

Error Handling

const result = await Effect.runPromise(escrow.create(...))
    .catch(error => {
        console.error("Failed:", error.message);
    });

Networks

• Testnet: wss://s.altnet.rippletest.net:51233/
• Mainnet: wss://xrplcluster.com/

License

MIT