@perkos/contracts-escrow

TypeScript ABI and types for the DeferredPaymentEscrowUpgradeable smart contract used in the x402 deferred payment scheme.

Installation

npm install @perkos/contracts-escrow

Usage

import {
  DEFERRED_ESCROW_ABI,
  ESCROW_ADDRESSES,
  getEscrowAddress,
  type Voucher,
  type DepositAuthorization,
  type FlushRequest,
  type ThawInfo
} from '@perkos/contracts-escrow';
import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';

// Create client
const client = createPublicClient({
  chain: base,
  transport: http()
});

// Get escrow address for network
const escrowAddress = getEscrowAddress('base-sepolia');

// Read deposit amount
const depositAmount = await client.readContract({
  address: escrowAddress,
  abi: DEFERRED_ESCROW_ABI,
  functionName: 'getDepositAmount',
  args: [buyerAddress, sellerAddress, assetAddress]
});

// Check if voucher was claimed
const isClaimed = await client.readContract({
  address: escrowAddress,
  abi: DEFERRED_ESCROW_ABI,
  functionName: 'voucherClaimed',
  args: [voucherId, nonce]
});

Contract Functions

Deposit Functions

| Function | Description | |----------|-------------| | deposit(seller, asset, amount) | Deposit tokens for a seller | | depositWithAuthorization(auth, signature) | Deposit with EIP-3009 authorization | | depositWithPermit(seller, asset, amount, deadline, v, r, s) | Deposit with EIP-2612 permit |

Claim Functions

| Function | Description | |----------|-------------| | claimVoucher(voucher, signature) | Claim payment using signed voucher | | claimVoucherBatch(vouchers, signatures) | Batch claim multiple vouchers |

Withdrawal Functions

| Function | Description | |----------|-------------| | thaw(seller, asset, amount) | Initiate withdrawal cooling period | | withdraw(seller, asset) | Complete withdrawal after thaw period | | flush(request, signature) | Emergency flush with seller signature |

View Functions

| Function | Description | |----------|-------------| | getDepositAmount(buyer, seller, asset) | Check deposit balance | | getClaimedAmount(buyer, seller, asset) | Check claimed balance | | getAvailableBalance(buyer, seller, asset) | Check available (unclaimed) balance | | authorizationUsed(address, nonce) | Check if authorization nonce was used | | voucherClaimed(voucherId, nonce) | Check if voucher was already claimed |

Types

Voucher

interface Voucher {
  id: `0x${string}`;
  buyer: `0x${string}`;
  seller: `0x${string}`;
  valueAggregate: bigint;
  asset: `0x${string}`;
  timestamp: bigint;
  nonce: bigint;
  escrow: `0x${string}`;
  chainId: bigint;
}

DepositAuthorization

interface DepositAuthorization {
  buyer: `0x${string}`;
  seller: `0x${string}`;
  asset: `0x${string}`;
  amount: bigint;
  validAfter: bigint;
  validBefore: bigint;
  nonce: `0x${string}`;
}

FlushRequest

interface FlushRequest {
  buyer: `0x${string}`;
  seller: `0x${string}`;
  asset: `0x${string}`;
  validAfter: bigint;
  validBefore: bigint;
  nonce: `0x${string}`;
}

Events

• Deposited(buyer, seller, asset, amount)
• VoucherClaimed(voucherId, nonce, buyer, seller, amount)
• ThawStarted(buyer, seller, asset, amount)
• Withdrawn(buyer, seller, asset, amount)

Contract Architecture

The contract uses the UUPS (Universal Upgradeable Proxy Standard) pattern from OpenZeppelin, allowing for bug fixes and feature additions without redeployment.

Related Packages

• @perkos/scheme-deferred - Deferred payment verification
• @perkos/types-x402 - Core x402 types
• @perkos/service-x402 - x402 service orchestrator

License

MIT