npm package: @perkos/contracts-escrow
Description: DeferredPaymentEscrow ABI for x402 deferred payment scheme
Author: PerkOS
Latest version: 1.0.1

# @perkos/contracts-escrow

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

## Installation

```bash
npm install @perkos/contracts-escrow
```

## Usage

```typescript
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

```typescript
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

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

### FlushRequest

```typescript
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](https://www.npmjs.com/package/@perkos/scheme-deferred) - Deferred payment verification
- [@perkos/types-x402](https://www.npmjs.com/package/@perkos/types-x402) - Core x402 types
- [@perkos/service-x402](https://www.npmjs.com/package/@perkos/service-x402) - x402 service orchestrator

## License

MIT