# Escrow System

The KayakNet Escrow System provides trustless cryptocurrency transactions for the marketplace.

## How It Works

```
┌─────────┐         ┌─────────┐         ┌─────────┐
│  Buyer  │         │ Escrow  │         │ Seller  │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │  1. Create Order  │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │  2. Pay to Escrow │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │                   │  3. Notify Seller │
     │                   │──────────────────▶│
     │                   │                   │
     │                   │  4. Ship Item     │
     │                   │◀──────────────────│
     │                   │                   │
     │  5. Receive Item  │                   │
     │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─│                   │
     │                   │                   │
     │  6. Confirm       │                   │
     │──────────────────▶│                   │
     │                   │                   │
     │                   │  7. Release Funds │
     │                   │──────────────────▶│
     │                   │                   │
```

## Supported Cryptocurrencies

| Currency | Symbol | Privacy Level             |
| -------- | ------ | ------------------------- |
| Monero   | XMR    | Maximum (default private) |
| Zcash    | ZEC    | High (shielded addresses) |

### Why These Currencies?

* **Bitcoin** - Not supported (transparent blockchain)
* **Monero** - Ring signatures, stealth addresses
* **Zcash** - Zero-knowledge proofs

## Order States

| State       | Description                       | Duration       |
| ----------- | --------------------------------- | -------------- |
| `created`   | Order initiated, awaiting payment | 24 hours       |
| `funded`    | Payment received, held in escrow  | Until shipped  |
| `shipped`   | Seller marked as shipped          | 14 days        |
| `completed` | Buyer confirmed receipt           | Final          |
| `disputed`  | Dispute opened                    | Until resolved |
| `refunded`  | Funds returned to buyer           | Final          |
| `expired`   | Order timed out                   | Final          |

## Creating an Escrow

### For Buyers

1. **Click "BUY"** on a listing
2. **Select currency** (XMR or ZEC)
3. **Enter delivery info** (encrypted)
4. **Review order details**
5. **Click "CREATE ORDER"**

You'll receive:

* **Escrow Address** - Where to send payment
* **Amount** - Exact crypto amount
* **Expiry** - Time limit for payment

### Payment

Send the **exact** amount to the escrow address:

```
Amount: 0.00123456 XMR
Address: 44zFk33yjuwLLWSkj1i2JMiiNX9HifKinA8v...
Fee: 2.5% (included)
Expires: 24 hours
```

**Important:**

* Send the EXACT amount shown
* Include enough for network fees
* Use correct currency network

### Confirmation

After payment:

1. Transaction broadcasts to network
2. KayakNet monitors for confirmations
3. Required confirmations: 10 (XMR), 6 (ZEC)
4. State changes to "funded"
5. Seller notified automatically

## For Sellers

### When Order is Funded

1. Check **SALES** tab in marketplace
2. Order shows "FUNDED" state
3. Delivery info is decrypted

### Fulfilling Order

1. Ship the item
2. Click **"MARK AS SHIPPED"**
3. Enter tracking info (optional)
4. State changes to "shipped"

### Receiving Payment

* Buyer confirms → Funds released instantly
* 14 days pass → Funds auto-release
* Dispute → Wait for resolution

## Disputes

### Opening a Dispute

As a buyer, if something's wrong:

1. Go to order details
2. Click **"OPEN DISPUTE"**
3. Select reason:
   * Item not received
   * Item not as described
   * Wrong item
   * Damaged item
   * Other
4. Describe the issue
5. Upload evidence (photos, screenshots)

### Dispute Resolution

1. **Seller Response** - 48 hours to respond
2. **Evidence Review** - Both parties submit proof
3. **Mediation** - Network mediators review
4. **Decision** - Funds released or refunded

### Auto-Resolution

If no response:

* Buyer dispute → Refunded after 7 days
* Seller dispute → Released after 7 days

## Fees

| Fee Type     | Amount   | When                |
| ------------ | -------- | ------------------- |
| Platform Fee | 2.5%     | On completion       |
| Network Fee  | Variable | On each transaction |
| Dispute Fee  | 1%       | If dispute filed    |

Platform fees fund network operations and development.

## Security

### Key Protection

* Escrow wallets on bootstrap node
* Multi-signature for large amounts (coming)
* Cold storage for reserves

### Address Generation

Each order gets a unique address:

```
Order: #1234
├── XMR subaddress: unique per order
└── ZEC z-address: unique per order
```

### No Custodial Risk

* Funds held minimum time
* Released immediately on confirmation
* No pooling of buyer funds

## Manual Confirmation

If automatic payment detection fails:

1. Go to order details
2. Click **"MANUAL CONFIRM"**
3. Enter transaction ID (TXID)
4. Submit

This is useful when:

* Wallet sync is behind
* Network congestion
* Unusual transaction

## API Reference

### Create Escrow

```
POST /api/escrow/create
{
  "listing_id": "abc123",
  "currency": "XMR",
  "buyer_address": "44zFk...",
  "delivery_info": "encrypted..."
}
```

### Check Status

```
GET /api/escrow/status?id=abc123
```

### Mark Shipped

```
POST /api/escrow/ship
{
  "escrow_id": "abc123",
  "tracking_info": "optional"
}
```

### Confirm Receipt

```
POST /api/escrow/release
{
  "escrow_id": "abc123"
}
```

## Best Practices

### For Buyers

* Verify seller reputation first
* Pay exact amount shown
* Check address carefully
* Confirm receipt promptly
* Keep transaction records

### For Sellers

* Ship promptly when funded
* Provide tracking when possible
* Communicate with buyers
* Keep shipping receipts
* Respond to disputes quickly

## Troubleshooting

### Payment Not Detected

1. Verify you sent correct amount
2. Check transaction confirmed
3. Use manual confirmation
4. Wait for wallet sync

### Funds Not Released

1. Check if buyer confirmed
2. Wait for auto-release (14 days)
3. Contact support if stuck

### Order Expired

* Payment wasn't received in time
* Create new order
* Use faster confirmation next time