Skip to main content

EscrowManager

The EscrowManager class handles the full escrow lifecycle — creation, funding, delivery, dispute, and resolution.
import { EscrowManager } from '@x0-protocol/sdk';

const escrowManager = new EscrowManager(connection);
// or via client:
const escrowManager = client.escrow;

PDA Derivation

deriveEscrowAddress(buyer, seller, serviceMemo)

const escrowPda = escrowManager.deriveEscrowAddress(
  buyerPubkey,
  sellerPubkey,
  'Code review service'
);
Seeds: ["escrow", buyer.toBytes(), seller.toBytes(), sha256(memo)]

Full Lifecycle Example

import { EscrowState } from '@x0-protocol/sdk';

// 1. Create escrow
const { instruction: createIx, escrowAddress } = escrowManager.buildCreateEscrowInstruction({
  buyer: buyerPubkey,
  seller: sellerPubkey,
  amount: new BN(50_000_000), // 50 USDC
  memo: 'Smart contract audit',
  mint: x0UsdMint,
  timeoutSeconds: 259_200, // 72 hours
});

// 2. Fund escrow
const fundIx = escrowManager.buildFundEscrowInstruction(
  buyerPubkey, escrowAddress, x0UsdMint, new BN(50_000_000)
);

// 3. Seller delivers
const deliverIx = escrowManager.buildMarkDeliveredInstruction(
  sellerPubkey, escrowAddress
);

// 4. Buyer releases funds
const releaseIx = escrowManager.buildReleaseFundsInstruction(
  buyerPubkey, sellerPubkey, escrowAddress, x0UsdMint
);

Building Instructions

buildCreateEscrowInstruction(params)

ParameterTypeDescription
buyerPublicKeyBuyer’s wallet
sellerPublicKeySeller’s wallet
arbiter?PublicKeyOptional dispute arbiter
amountBNEscrow amount in micro-units
memostringService description (hashed on-chain)
mintPublicKeyToken mint for escrow
timeoutSeconds?numberCustom timeout (default: 72h)

buildFundEscrowInstruction(buyer, escrowAddress, mint, amount)

Transfer tokens into the escrow account. Only the buyer can call this.

buildMarkDeliveredInstruction(seller, escrowAddress)

Seller signals that the service has been delivered.

buildReleaseFundsInstruction(buyer, seller, escrowAddress, mint, reputationAccounts?)

Buyer confirms delivery and releases funds to seller. Optionally updates seller’s reputation via CPI.
const releaseIx = escrowManager.buildReleaseFundsInstruction(
  buyerPubkey,
  sellerPubkey,
  escrowAddress,
  x0UsdMint,
  {
    sellerReputation: reputationPda,
    sellerPolicy: sellerPolicyPda,
    reputationProgram: reputationProgramId,
  }
);

buildInitiateDisputeInstruction(disputeInitiator, escrowAddress, reason, reputationAccounts?)

Open a dispute with evidence.

buildResolveDisputeInstruction(arbiter, escrowAddress, buyer, seller, mint, favorSeller)

Arbiter resolves a dispute. Subject to 24-hour delay after dispute initiation.

buildClaimAutoReleaseInstruction(seller, escrowAddress, mint, reputationAccounts?)

Seller claims funds after timeout with no buyer action.

buildClaimTimeoutRefundInstruction(buyer, escrowAddress, mint)

Buyer claims refund after escrow timeout.

buildCancelEscrowInstruction(buyer, escrowAddress)

Cancel an unfunded escrow.

Querying Escrows

fetchEscrow(escrowAddress)

const escrow = await escrowManager.fetchEscrow(escrowPda);
Returns: EscrowAccount | null

getEscrowsForBuyer(buyer)

const escrows = await escrowManager.getEscrowsForBuyer(buyerPubkey);
// [{ address: PublicKey, account: EscrowAccount }]

getEscrowsForSeller(seller)

const escrows = await escrowManager.getEscrowsForSeller(sellerPubkey);

State Helpers

getStateLabel(state)

escrowManager.getStateLabel(EscrowState.Funded); // "Funded"

canAutoRelease(escrow)

Check if the escrow is eligible for auto-release (delivered + timeout passed).

canTimeoutRefund(escrow)

Check if the escrow is eligible for timeout refund.

getTimeUntilTimeout(escrow)

const seconds = escrowManager.getTimeUntilTimeout(escrow);
if (seconds !== null) {
  console.log(`Timeout in ${seconds / 3600} hours`);
}

EscrowAccount

FieldTypeDescription
versionnumberAccount version
buyerPublicKeyBuyer’s wallet
sellerPublicKeySeller’s wallet
arbiterPublicKey?Optional arbiter
amountBNEscrowed amount
memoHashUint8ArraySHA-256 of service memo
stateEscrowStateCurrent state
timeoutnumberTimeout timestamp
createdAtnumberCreation timestamp
deliveryProofUint8Array?Delivery proof hash
disputeEvidenceUint8Array?Dispute evidence hash
mintPublicKeyToken mint
tokenDecimalsnumberToken decimals
disputeInitiatedSlotnumber?Slot when dispute was opened
bumpnumberPDA bump

EscrowState Enum

ValueNameDescription
0CreatedEscrow initialized, awaiting funding
1FundedBuyer has funded the escrow
2DeliveredSeller has marked delivery
3DisputedDispute has been opened
4ReleasedFunds released to seller
5RefundedFunds refunded to buyer
6CancelledEscrow cancelled before funding
Last modified on February 8, 2026