Escrow

The EscrowVault module manages USDC funds during the transaction lifecycle.

---

Overview

EscrowVault provides:

• USDC approval helpers
• Escrow balance queries
• Fund status tracking

Important: Escrow creation happens atomically inside ACTPKernel.linkEscrow(). This module provides helper methods for approvals and read-only access to escrow state.

---

Workflow

Per AIP-3, the escrow workflow is:

1. Approve: Consumer approves USDC to EscrowVault address
2. Link: Consumer calls ACTPKernel.linkEscrow()
3. Lock: Kernel creates escrow, pulls USDC from consumer
4. Release: After delivery + dispute window, funds release to provider

---

Methods

approveToken()

Approve USDC for escrow creation. Must be called before linkEscrow().

TypeScript

// Level 2: Advanced API - Direct protocol control
import { parseUnits } from 'ethers';

// Approve 100 USDC for escrow
const amount = parseUnits('100', 6); // USDC has 6 decimals
await client.escrow.approveToken(USDC_ADDRESS, amount);

// Now link escrow via advanced API
await client.advanced.linkEscrow(txId);

Python

# Level 2: Advanced API - Direct protocol control
# Approve 100 USDC for escrow
amount = 100 * 10**6  # USDC has 6 decimals
await client.escrow.approve_token(USDC_ADDRESS, amount)

# Now link escrow via advanced API
await client.advanced.link_escrow(tx_id)

Parameters:

Parameter	Type	Description
tokenAddress	string	USDC contract address
amount	bigint	Amount to approve (wei)

---

getEscrow()

Get escrow details by ID.

TypeScript

// Level 2: Advanced API - Direct protocol control
const escrow = await client.escrow.getEscrow(escrowId);

console.log('Requester:', escrow.requester);
console.log('Provider:', escrow.provider);
console.log('Amount:', escrow.amount);
console.log('Remaining:', escrow.remaining);
console.log('Released:', escrow.released);

Python

# Level 2: Advanced API - Direct protocol control
escrow = await client.escrow.get_escrow(escrow_id)

print(f'Requester: {escrow.requester}')
print(f'Provider: {escrow.provider}')
print(f'Amount: {escrow.amount}')
print(f'Remaining: {escrow.remaining}')
print(f'Released: {escrow.released}')

Returns:

TypeScript

// Level 2: Advanced API - Direct protocol control
interface Escrow {
  escrowId: string;
  requester: string;
  provider: string;
  amount: bigint;
  remaining: bigint;
  released: boolean;
  createdAt: number;
}

Python

# Level 2: Advanced API - Direct protocol control
class Escrow(TypedDict):
    escrow_id: str
    requester: str
    provider: str
    amount: int
    remaining: int
    released: bool
    created_at: int

---

getRemaining()

Get remaining balance in escrow.

TypeScript

// Level 2: Advanced API - Direct protocol control
const remaining = await client.escrow.getRemaining(escrowId);
console.log('Remaining in escrow:', remaining, 'wei');

Python

# Level 2: Advanced API - Direct protocol control
remaining = await client.escrow.get_remaining(escrow_id)
print(f'Remaining in escrow: {remaining} wei')

---

getAddress()

Get the EscrowVault contract address.

TypeScript

// Level 2: Advanced API - Direct protocol control
const vaultAddress = client.escrow.getAddress();
console.log('EscrowVault:', vaultAddress);

Python

# Level 2: Advanced API - Direct protocol control
vault_address = client.escrow.get_address()
print(f'EscrowVault: {vault_address}')

---

USDC Addresses

SDK Auto-Configuration

Contract addresses are automatically configured by the SDK based on your network parameter. You never need to hardcode addresses. The links below are for verification and auditing only.

Network	Basescan
Base Sepolia	View on Basescan
Base Mainnet	View on Basescan
Mock Mode	Auto-deployed mock token

---

Example: Complete Escrow Flow

TypeScript

// Level 2: Advanced API - Direct protocol control
import { ACTPClient, parseUnits } from '@agirails/sdk';
import { BASE_SEPOLIA } from '@agirails/sdk/config';

async function completeEscrowFlow() {
  const client = await ACTPClient.create({
    mode: 'mock',
    requesterAddress: '0x1111111111111111111111111111111111111111',
  });

  // 1. Create transaction
  const txId = await client.advanced.createTransaction({
    provider: '0x2222222222222222222222222222222222222222',
    requester: '0x1111111111111111111111111111111111111111',
    amount: parseUnits('100', 6), // $100 USDC
    deadline: Math.floor(Date.now() / 1000) + 86400,
    disputeWindow: 172800,
  });

  // 2. Approve USDC
  const amount = parseUnits('100', 6);
  await client.escrow.approveToken(BASE_SEPOLIA.contracts.usdc, amount);

  // 3. Link escrow (auto-transitions to COMMITTED)
  const escrowId = await client.advanced.linkEscrow(txId);
  console.log('Escrow linked:', escrowId);

  // 4. Check escrow balance
  const remaining = await client.escrow.getRemaining(escrowId);
  console.log('Funds locked:', remaining);

  // 5. After delivery and dispute window...
  await client.advanced.releaseEscrow(escrowId);
  console.log('Funds released to provider');
}

Python

# Level 2: Advanced API - Direct protocol control
import time
from agirails import ACTPClient

async def complete_escrow_flow():
    client = await ACTPClient.create(
        mode='mock',
        requester_address='0x1111111111111111111111111111111111111111',
    )

    # 1. Create transaction
    tx_id = await client.advanced.create_transaction({
        'provider': '0x2222222222222222222222222222222222222222',
        'requester': '0x1111111111111111111111111111111111111111',
        'amount': '100000000',  # $100 USDC in wei
        'deadline': int(time.time()) + 86400,
        'dispute_window': 172800,
    })

    # 2. Approve USDC
    amount = 100 * 10**6
    await client.escrow.approve_token(USDC_ADDRESS, amount)

    # 3. Link escrow
    escrow_id = await client.advanced.link_escrow(tx_id)
    print(f'Escrow linked: {escrow_id}')

    # 4. Check balance
    remaining = await client.escrow.get_remaining(escrow_id)
    print(f'Funds locked: {remaining}')

    # 5. Release after dispute window
    await client.advanced.release_escrow(escrow_id)
    print('Funds released to provider')

---

Security Notes

• Non-custodial: Funds are held by smart contract, not by AGIRAILS
• 2-of-3 pattern: Release requires either:
  • Requester approval (explicit release)
  • Dispute window expiry (automatic release)
  • Mediator decision (dispute resolution)
• Emergency withdrawal: 7-day timelock for admin access

---

Next Steps

• Kernel - Transaction lifecycle
• Events - Monitor escrow events
• EAS - Delivery attestations