eep-sdk

Official TypeScript SDK for the Ethereum Escrow Protocol.

Thin ethers.js v6 wrapper around the EEPEscrow contract — full type coverage, zero config.

Install

npm install eep-sdk ethers

Quick start

import { ethers } from "ethers";
import { EEPClient, ethAsset, singleMilestone } from "eep-sdk";

const provider = new ethers.BrowserProvider(window.ethereum);
const signer   = await provider.getSigner();
const eep      = new EEPClient(signer, "0xYOUR_CONTRACT_ADDRESS");

// 1. Create
const id = await eep.createEscrow({
  recipient: "0xRecipient",
  asset: ethAsset(ethers.parseEther("1.0")),
  milestones: singleMilestone("On delivery"),
});

// 2. Fund
await eep.deposit(id, ethers.parseEther("1.0"));

// 3. Release
await eep.release(id);

API

new EEPClient(signerOrProvider, contractAddress)

| Parameter | Type | Description | |--------------------|------------------------|--------------------------------------| | signerOrProvider | Signer \| Provider | ethers Signer (writes) or Provider (reads) | | contractAddress | string | Deployed EEPEscrow address |

Read methods

| Method | Returns | Description | |---|---|---| | getEscrow(id) | EscrowData | Full escrow struct | | getMilestones(id) | Milestone[] | All milestones | | getState(id) | number | 0–5 state index | | totalEscrows() | bigint | Count of all escrows |

Write methods

| Method | Description | |---|---| | createEscrow(params) | Create escrow → returns bigint escrow ID | | deposit(id, ethAmount?) | Fund the escrow | | release(id) | Release all funds to recipient | | releaseMilestone(id, index) | Release one milestone | | dispute(id, reason) | Raise a dispute | | refund(id) | Refund to depositor | | executeDisputeOutcome(id) | Execute resolved dispute |

Event subscriptions

All return an unsubscribe function.

const unsub = eep.onEscrowCreated((id, depositor, recipient) => { ... });
const unsub = eep.onMilestoneReleased(id, (index, amount, recipient) => { ... });
const unsub = eep.onEscrowCompleted(id, (recipient, fee) => { ... });
const unsub = eep.onEscrowDisputed(id, (raisedBy) => { ... });

Asset helpers

import { ethAsset, erc20Asset, nftAsset } from "eep-sdk";

ethAsset(ethers.parseEther("1.0"))
erc20Asset("0xTokenAddress", 1000n * 10n ** 6n)  // 1 000 USDC
nftAsset("0xNFTAddress", 42n)

Milestone helpers

import { singleMilestone, milestonesFromPcts } from "eep-sdk";

singleMilestone("Full payment")

milestonesFromPcts([
  { pct: 30, description: "Upfront" },
  { pct: 70, description: "On delivery" },
])

Condition encoders

import { encodeTimeLock, encodeMultiSig, encodeOracleCondition, encodeNFTGated, daysFromNow } from "eep-sdk";

encodeTimeLock(daysFromNow(30))
encodeMultiSig(["0xAlice", "0xBob", "0xCarol"], 2)
encodeOracleCondition("0xPriceFeed", 200000000000n, true)  // price > $2 000
encodeNFTGated("0xNFT", 1n, false)

Utility functions

import { escrowStateName, daysFromNow, netAfterFee, allMilestonesReleased } from "eep-sdk";

escrowStateName(1)              // "ACTIVE"
daysFromNow(30)                 // bigint unix timestamp 30 days out
netAfterFee(ethers.parseEther("1.0"))  // after 0.25% fee
allMilestonesReleased(escrow)   // boolean

Escrow states

| Value | Label | |---|---| | 0 | PENDING | | 1 | ACTIVE | | 2 | DISPUTED | | 3 | COMPLETED | | 4 | REFUNDED | | 5 | EXPIRED |

License

MIT