@cgentai/cgent-contracts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cgent.AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+## P2P Escrow SDK 文档
+
+本仓库提供一个用于点对点电商场景的资金托管合约 `P2PEscrow.sol` 以及与之配套的 TypeScript SDK，帮助买卖双方在交易过程中安全地锁定和释放资金。本文档覆盖以下内容：
+
+- 合约设计概览与角色职责
+- 订单生命周期及状态机
+- 合约公开方法与事件说明
+- 常量、费用与错误类型
+- SDK 安装、初始化及常用调用示例
+- 浏览器环境辅助方法
+
+> 合约源码位置：`contracts/P2PEscrow.sol`
+>
+> SDK 入口：`src/index.ts`（导出常量、类型与 `P2PEscrowClient`）
+
+---
+
+### 1. 合约概览
+
+`P2PEscrow` 合约主要面向买家（buyer）、卖家（seller）与仲裁者（arbitrator）三个角色：
+
+- **买家**：发起订单并预付代币；在没有争议时可以确认收货或撤回资金。
+- **卖家**：在确认收到款项后锁定订单；可在必要时退款或在锁定期后请求释放资金。
+- **仲裁者**：当订单进入争议流程时，负责裁定资金归属。
+- **合约拥有者（owner）**：配置手续费接收地址、仲裁者和可用代币列表。
+
+资金在订单创建时从买家转入合约，直至订单根据流程释放或退款。合约支持多个 ERC-20 代币，通过白名单管理支持的代币地址。
+
+手续费设定为 **1%**（`FEE_BPS = 100`，基础为 `10_000`）。手续费统一转入 `feeRecipient` 地址，其余金额发放给卖家。
+
+---
+
+### 2. 订单状态机
+
+合约使用 `OrderStatus` 枚举区分订单生命周期：
+
+| 数值 | 状态名 | 说明 |
+| --- | --- | --- |
+| 0 | `None` | 默认状态（订单不存在）。 |
+| 1 | `BuyerPaid` | 买家支付成功，订单已在合约中锁仓。 |
+| 2 | `SellerLocked` | 卖家确认并锁定订单，开始计算锁定期（30 天）。 |
+| 3 | `SellerRefunded` | 卖家将资金原路退回买家。 |
+| 4 | `SellerReleased` | 订单释放给卖家（扣除手续费）。 |
+| 5 | `BuyerWithdrawn` | 买家在卖家锁定前撤回资金。 |
+| 6 | `ArbitrationPending` | 仲裁者介入，等待裁决。 |
+| 7 | `ArbitrationBuyer` | 仲裁判定资金退回买家。 |
+| 8 | `ArbitrationSeller` | 仲裁判定资金释放给卖家（扣除手续费）。 |
+
+锁定期（`LOCK_DURATION = 30 days`）从卖家调用 `lockOrder` 时开始计算。锁定期届满后，卖家可调用 `sellerRelease` 将资金解锁给自己。
+
+---
+
+### 3. 合约方法
+
+#### 3.1 配置与查看
+
+- `feeRecipient() -> address`：查看手续费接收地址。
+- `arbitrator() -> address`：查看当前仲裁者地址。
+- `owner() -> address`：查看合约拥有者。
+- `supportedTokens(address token) -> bool`：查询代币是否在支持列表。
+- `getOrderId(address buyer, address seller, uint256 orderId) -> bytes32`：计算订单唯一 key。
+- `getOrder(address buyer, address seller, uint256 orderId) -> Order`：获取订单结构体。
+- `orders(bytes32 orderKey) -> Order`：通过订单 key 读取原始存储。
+
+#### 3.2 订单生命周期
+
+- `createOrder(address buyer, address seller, uint256 orderId, uint256 amount, address token)`
+  - 仅买家调用；检查代币是否支持、金额>0、卖家非零地址；将 `amount` 转入合约并创建订单。
+
+- `lockOrder(address buyer, uint256 orderId)`
+  - 仅卖家调用；要求状态为 `BuyerPaid`；锁定期开始计时，状态改为 `SellerLocked`。
+
+- `buyerWithdraw(address seller, uint256 orderId)`
+  - 买家在卖家锁定前随时撤回资金，状态变为 `BuyerWithdrawn`。
+
+- `sellerRefund(address buyer, uint256 orderId)`
+  - 卖家在 `BuyerPaid` 或 `SellerLocked` 状态下可主动退款给买家，状态为 `SellerRefunded`。
+
+- `buyerConfirmReceipt(address seller, uint256 orderId)`
+  - 买家在订单锁定后确认收货，触发 `_releaseToSeller`，将金额按费率拆分给卖家和手续费地址，状态变为 `SellerReleased`。
+
+- `sellerRelease(address buyer, uint256 orderId)`
+  - 卖家在锁定期已结束后自助释放资金给自己；状态要求 `SellerLocked` 且当前时间超过 `lockedUntil`。
+
+#### 3.3 仲裁流程
+
+- `setArbitrationPending(address buyer, address seller, uint256 orderId)`
+  - 仅仲裁者调用；在 `BuyerPaid` 或 `SellerLocked` 状态下进入仲裁，记录上一个状态。
+
+- `cancelArbitration(address buyer, address seller, uint256 orderId)`
+  - 仲裁者撤消仲裁，将状态还原至进入仲裁前的状态。
+
+- `arbitrate(address buyer, address seller, uint256 orderId, bool releaseToSeller)`
+  - 仲裁者最终裁决。`releaseToSeller = true` 时拆分手续费后转给卖家；否则原额退回买家。状态分别变更为 `ArbitrationSeller` 或 `ArbitrationBuyer`。
+
+#### 3.4 管理员操作
+
+- `setFeeRecipient(address newRecipient)`：合约拥有者更新手续费地址。
+- `setArbitrator(address newArbitrator)`：合约拥有者更新仲裁者。
+- `addSupportedToken(address token)` / `removeSupportedToken(address token)`：增删支持代币。
+- `transferOwnership(address newOwner)` / `renounceOwnership()`：标准 Ownable 权限管理。
+
+#### 3.5 内部逻辑
+
+- `_releaseToSeller(Order storage order, bytes32 orderKey)`：私有函数，用于统一执行释放逻辑，计算手续费并发放资金。
+
+---
+
+### 4. 事件
+
+合约定义的主要事件如下：
+
+- `OrderCreated(orderKey, buyer, seller, orderId, token, amount)`
+- `OrderLocked(orderKey, lockedUntil)`
+- `BuyerWithdrawn(orderKey)`
+- `SellerRefunded(orderKey)`
+- `SellerReleased(orderKey, sellerAmount, feeAmount)`
+- `ArbitrationPendingSet(orderKey)`
+- `ArbitrationResolved(orderKey, releasedToSeller, amount, feeAmount)`
+- `ArbitrationCancelled(orderKey, restoredStatus)`
+- `FeeRecipientUpdated(newRecipient)`
+- `ArbitratorUpdated(newArbitrator)`
+- `SupportedTokenAdded(token)` / `SupportedTokenRemoved(token)`
+
+SDK 提供的 `P2PEscrowClient` 支持通过 `on/once/off/removeAllListeners` 订阅这些事件。
+
+---
+
+### 5. 常量与错误
+
+- `LOCK_DURATION_SECONDS = 30 * 24 * 60 * 60`：卖家锁定后需等待的秒数。
+- `FEE_BPS = 100 (1%)`，`BPS_DENOMINATOR = 10_000`：手续费计算使用 `amount * FEE_BPS / BPS_DENOMINATOR`。
+- 关键错误：
+  - `InvalidToken(address)`：代币或地址无效。
+  - `InvalidAmount()`：金额为零。
+  - `OrderAlreadyExists()`：同一订单重复创建。
+  - `Unauthorized()`：调用方角色不匹配。
+  - `InvalidStatus()`：当前订单状态不允许执行操作。
+  - `LockPeriodActive(uint256)`：卖家释放时锁定期尚未到期。
+  - `NothingToRelease()`：订单金额为零。
+
+---
+
+### 6. SDK 使用指南
+
+SDK 基于 `ethers@^6`，在 Node.js、浏览器或任意支持 ESM/CJS 的环境中均可使用。
+
+#### 6.1 安装
+
+```bash
+npm install @cgentai/cgent-contracts ethers
+# 或者使用 pnpm / yarn
+```
+
+#### 6.2 初始化客户端
+
+```ts
+import { JsonRpcProvider } from "ethers";
+import { P2PEscrowClient } from "@cgentai/cgent-contracts";
+
+const provider = new JsonRpcProvider("https://rpc.sepolia.linea.build");
+const signer = await provider.getSigner(); // 也可以用 wallet.connect(provider)
+
+const escrow = new P2PEscrowClient({
+  address: "0xEscrowAddress",
+  runner: signer,
+});
+
+console.log(await escrow.getFeeRecipient());
+```
+
+`P2PEscrowClient.connect(address, runner)` 提供了便捷的静态初始化方法。
+
+#### 6.3 浏览器环境
+
+```ts
+import { createP2PEscrowClientFromBrowser } from "@cgentai/cgent-contracts";
+
+const escrow = await createP2PEscrowClientFromBrowser({
+  provider: window.ethereum,
+  address: "0xEscrowAddress",
+  accountIndex: 0, // 可选，默认 0
+});
+
+const account = await escrow.getRunnerAddress();
+```
+
+#### 6.4 创建订单
+
+```ts
+const buyerAddress = await escrow.getRunnerAddress();
+
+await escrow.createOrder({
+  buyer: buyerAddress!,
+  seller: "0xSellerAddress",
+  orderId: 1n,
+  amount: 1000n * 10n ** 6n, // 以最小单位传值
+  token: "0xUSDC",
+});
+```
+
+在调用前确保买家钱包已对合约执行 `ERC20.approve` 授权。
+
+#### 6.5 卖家操作
+
+```ts
+// 卖家确认锁定
+await escrow.withRunner(sellerSigner).lockOrder({
+  buyer: buyerAddress!,
+  orderId: 1n,
+});
+
+// 卖家等待锁定期结束后释放
+await escrow.withRunner(sellerSigner).sellerRelease({
+  buyer: buyerAddress!,
+  orderId: 1n,
+});
+
+// 或者在需要时退款
+await escrow.withRunner(sellerSigner).sellerRefund({
+  buyer: buyerAddress!,
+  orderId: 1n,
+});
+```
+
+#### 6.6 买家确认或撤回
+
+```ts
+// 买家确认收货
+await escrow.withRunner(buyerSigner).buyerConfirmReceipt({
+  seller: "0xSellerAddress",
+  orderId: 1n,
+});
+
+// 买家在卖家锁定前撤回
+await escrow.withRunner(buyerSigner).buyerWithdraw({
+  seller: "0xSellerAddress",
+  orderId: 1n,
+});
+```
+
+#### 6.7 仲裁流程
+
+```ts
+// 仲裁者设置仲裁中
+await escrow.withRunner(arbitratorSigner).setArbitrationPending({
+  buyer: buyerAddress!,
+  seller: "0xSellerAddress",
+  orderId: 1n,
+});
+
+// 最终裁决：true 释放给卖家（扣除手续费），false 退给买家
+await escrow.withRunner(arbitratorSigner).arbitrate({
+  buyer: buyerAddress!,
+  seller: "0xSellerAddress",
+  orderId: 1n,
+  releaseToSeller: true,
+});
+```
+
+#### 6.8 查询订单与辅助函数
+
+```ts
+const order = await escrow.getOrder({
+  buyer: buyerAddress!,
+  seller: "0xSellerAddress",
+  orderId: 1n,
+});
+
+console.log(order.status); // OrderStatus 枚举值
+
+const { feeAmount, sellerAmount } = P2PEscrowClient.calculateFee(order.amount);
+```
+
+SDK 返回的 `ResolvedOrder` 将合约中的 `uint256` 转换为 `bigint`，可直接参与 JS/TS 计算。
+
+---
+
+### 7. 事件监听
+
+`P2PEscrowClient` 继承了 TypeChain 的事件类型，可在 TypeScript 中获得强类型支持：
+
+```ts
+import type { P2PEscrow } from "@cgentai/cgent-contracts/typechain-types";
+
+escrow.on(escrow.contract.filters.OrderCreated(), (orderKey, buyer, seller, orderId) => {
+  console.log("New order", { orderKey, buyer, seller, orderId: orderId.toString() });
+});
+
+// 取消监听
+escrow.removeAllListeners(escrow.contract.filters.OrderCreated());
+```
+
+---
+
+### 8. 部署与网络
+
+`deployments/` 目录中存放了示例部署信息（例如 `P2PEscrow-84532.json` 对应于 Linea Sepolia 测试网）。使用 SDK 时请根据实际网络配置合约地址与 RPC 节点。
+
+---
+
+### 9. 开发与测试
+
+- 本仓库基于 Hardhat，测试脚本位于 `test/` 目录，可运行 `pnpm test` 或 `npx hardhat test`。
+- 若需自建环境，可使用 `pnpm deploy`（具体脚本请参考 `package.json`）。
+- 修改合约或 SDK 后，请重新编译生成 TypeChain 类型：`pnpm build`。
+
+---
+
+如需更多帮助或功能扩展，欢迎提交 Issue 或 PR。
+
+

package/dist/src/browser.d.ts

@@ -0,0 +1,36 @@
+import type { P2PEscrowClientConfig } from "./types";
+export interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+    on?(event: string, listener: (...args: unknown[]) => void): void;
+    removeListener?(event: string, listener: (...args: unknown[]) => void): void;
+}
+export interface BrowserWalletClientConfig extends Omit<P2PEscrowClientConfig, "runner"> {
+    provider: Eip1193Provider;
+    accountIndex?: number;
+}
+/**
+ * Convenience helper for browser apps where the wallet (EIP-1193 provider)
+ * is injected by the host environment (e.g. MetaMask, Coinbase Wallet).
+ *
+ * ```ts
+ * import { createP2PEscrowClientFromBrowser } from "@cgent/contracts";
+ *
+ * const client = await createP2PEscrowClientFromBrowser({
+ *   provider: window.ethereum,
+ *   address: "0xEscrowAddress",
+ * });
+ *
+ * await client.createOrder({
+ *   buyer: await client.getRunnerAddress(),
+ *   seller: "0xSeller",
+ *   orderId: 1n,
+ *   amount: 100n * 10n ** 6n,
+ *   token: "0xUSDC",
+ * });
+ * ```
+ */
+export declare const createP2PEscrowClientFromBrowser: (config: BrowserWalletClientConfig) => Promise<import("./contracts/p2pEscrowClient").P2PEscrowClient>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/src/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAGrD,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACjE,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAC9E;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC;IACtF,QAAQ,EAAE,eAAe,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gCAAgC,GAC3C,QAAQ,yBAAyB,mEASlC,CAAC"}

package/dist/src/browser.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createP2PEscrowClientFromBrowser = void 0;
+const ethers_1 = require("ethers");
+const p2pEscrowClient_1 = require("./contracts/p2pEscrowClient");
+/**
+ * Convenience helper for browser apps where the wallet (EIP-1193 provider)
+ * is injected by the host environment (e.g. MetaMask, Coinbase Wallet).
+ *
+ * ```ts
+ * import { createP2PEscrowClientFromBrowser } from "@cgent/contracts";
+ *
+ * const client = await createP2PEscrowClientFromBrowser({
+ *   provider: window.ethereum,
+ *   address: "0xEscrowAddress",
+ * });
+ *
+ * await client.createOrder({
+ *   buyer: await client.getRunnerAddress(),
+ *   seller: "0xSeller",
+ *   orderId: 1n,
+ *   amount: 100n * 10n ** 6n,
+ *   token: "0xUSDC",
+ * });
+ * ```
+ */
+const createP2PEscrowClientFromBrowser = async (config) => {
+    const browserProvider = new ethers_1.BrowserProvider(config.provider);
+    const signer = await browserProvider.getSigner(config.accountIndex ?? 0);
+    return (0, p2pEscrowClient_1.createP2PEscrowClient)({
+        address: config.address,
+        runner: signer,
+    });
+};
+exports.createP2PEscrowClientFromBrowser = createP2PEscrowClientFromBrowser;
+//# sourceMappingURL=browser.js.map

package/dist/src/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":";;;AAAA,mCAAyC;AAGzC,iEAAoE;AAapE;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,MAAM,gCAAgC,GAAG,KAAK,EACnD,MAAiC,EACjC,EAAE;IACF,MAAM,eAAe,GAAG,IAAI,wBAAe,CAAC,MAAM,CAAC,QAAe,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IAEzE,OAAO,IAAA,uCAAqB,EAAC;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;AACL,CAAC,CAAC;AAVW,QAAA,gCAAgC,oCAU3C"}

package/dist/src/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const LOCK_DURATION_SECONDS: number;
+export declare const FEE_BPS = 100n;
+export declare const BPS_DENOMINATOR = 10000n;
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AACvD,eAAO,MAAM,OAAO,OAAO,CAAC;AAC5B,eAAO,MAAM,eAAe,SAAU,CAAC;AAEvC,eAAO,MAAM,YAAY,+CAA+C,CAAC"}

package/dist/src/constants.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZERO_ADDRESS = exports.BPS_DENOMINATOR = exports.FEE_BPS = exports.LOCK_DURATION_SECONDS = void 0;
+exports.LOCK_DURATION_SECONDS = 30 * 24 * 60 * 60; // 30 days
+exports.FEE_BPS = 100n; // 1%
+exports.BPS_DENOMINATOR = 10000n;
+exports.ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+//# sourceMappingURL=constants.js.map

package/dist/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;AACrD,QAAA,OAAO,GAAG,IAAI,CAAC,CAAC,KAAK;AACrB,QAAA,eAAe,GAAG,MAAO,CAAC;AAE1B,QAAA,YAAY,GAAG,4CAA4C,CAAC"}

package/dist/src/contracts/p2pEscrowClient.d.ts

@@ -0,0 +1,70 @@
+import type { AddressLike, ContractRunner, ContractTransactionResponse } from "ethers";
+import { type ArbitratorActionParams, type CreateOrderParams, type OrderIdentifier, type SellerActionParams, type BuyerWithdrawParams, type BuyerConfirmReceiptParams, type P2PEscrowClientConfig, type ResolvedOrder } from "../types";
+import type { TypedContractEvent, TypedDeferredTopicFilter, TypedListener } from "../../typechain-types/common";
+import type { P2PEscrow } from "../../typechain-types/contracts/P2PEscrow";
+/**
+ * High-level TypeScript wrapper around the `P2PEscrow` smart contract.
+ *
+ * Works with any ethers.js v6 `ContractRunner` (Signer, Provider or JsonRpcProvider).
+ * Designed to be framework-agnostic so it can run in browser or server runtimes.
+ */
+export declare class P2PEscrowClient {
+    private _contract;
+    constructor({ address, runner }: P2PEscrowClientConfig);
+    static connect(address: string, runner: ContractRunner): P2PEscrowClient;
+    get address(): string;
+    get runner(): ContractRunner | null;
+    get contract(): P2PEscrow;
+    getRunnerAddress(): Promise<string | null>;
+    withRunner(runner: ContractRunner): P2PEscrowClient;
+    /**
+     * Helpers
+     */
+    static calculateFee(amount: bigint): {
+        feeAmount: bigint;
+        sellerAmount: bigint;
+    };
+    static lockDurationSeconds(): number;
+    /**
+     * Reads
+     */
+    getFeeRecipient(): Promise<string>;
+    getArbitrator(): Promise<string>;
+    getOwner(): Promise<string>;
+    isSupportedToken(token: AddressLike): Promise<boolean>;
+    getOrderId(params: OrderIdentifier): Promise<string>;
+    getOrder(params: OrderIdentifier): Promise<ResolvedOrder>;
+    getRawOrder(params: OrderIdentifier): Promise<Awaited<ReturnType<P2PEscrow["orders"]>>>;
+    /**
+     * Transactions
+     */
+    createOrder(params: CreateOrderParams): Promise<ContractTransactionResponse>;
+    lockOrder(params: SellerActionParams): Promise<ContractTransactionResponse>;
+    buyerWithdraw(params: BuyerWithdrawParams): Promise<ContractTransactionResponse>;
+    buyerConfirmReceipt(params: BuyerConfirmReceiptParams): Promise<ContractTransactionResponse>;
+    sellerRefund(params: SellerActionParams): Promise<ContractTransactionResponse>;
+    sellerRelease(params: SellerActionParams): Promise<ContractTransactionResponse>;
+    setArbitrationPending(params: OrderIdentifier): Promise<ContractTransactionResponse>;
+    cancelArbitration(params: OrderIdentifier): Promise<ContractTransactionResponse>;
+    arbitrate(params: ArbitratorActionParams): Promise<ContractTransactionResponse>;
+    setFeeRecipient(newRecipient: AddressLike): Promise<ContractTransactionResponse>;
+    setArbitrator(newArbitrator: AddressLike): Promise<ContractTransactionResponse>;
+    addSupportedToken(token: AddressLike): Promise<ContractTransactionResponse>;
+    removeSupportedToken(token: AddressLike): Promise<ContractTransactionResponse>;
+    transferOwnership(newOwner: AddressLike): Promise<ContractTransactionResponse>;
+    renounceOwnership(): Promise<ContractTransactionResponse>;
+    /**
+     * Events
+     */
+    on<Event extends TypedContractEvent>(event: Event, listener: TypedListener<Event>): void;
+    on<Event extends TypedContractEvent>(filter: TypedDeferredTopicFilter<Event>, listener: TypedListener<Event>): void;
+    once<Event extends TypedContractEvent>(event: Event, listener: TypedListener<Event>): void;
+    once<Event extends TypedContractEvent>(filter: TypedDeferredTopicFilter<Event>, listener: TypedListener<Event>): void;
+    off<Event extends TypedContractEvent>(event: Event, listener: TypedListener<Event>): void;
+    off<Event extends TypedContractEvent>(filter: TypedDeferredTopicFilter<Event>, listener: TypedListener<Event>): void;
+    removeAllListeners<Event extends TypedContractEvent>(event?: Event): void;
+    private mapOrder;
+}
+export type { P2PEscrow };
+export declare const createP2PEscrowClient: (config: P2PEscrowClientConfig) => P2PEscrowClient;
+//# sourceMappingURL=p2pEscrowClient.d.ts.map

package/dist/src/contracts/p2pEscrowClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"p2pEscrowClient.d.ts","sourceRoot":"","sources":["../../../src/contracts/p2pEscrowClient.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/p2pEscrowClient.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createP2PEscrowClient = exports.P2PEscrowClient = void 0;
+const constants_1 = require("../constants");
+const P2PEscrow__factory_1 = require("../../typechain-types/factories/contracts/P2PEscrow__factory");
+/**
+ * High-level TypeScript wrapper around the `P2PEscrow` smart contract.
+ *
+ * Works with any ethers.js v6 `ContractRunner` (Signer, Provider or JsonRpcProvider).
+ * Designed to be framework-agnostic so it can run in browser or server runtimes.
+ */
+class P2PEscrowClient {
+    _contract;
+    constructor({ address, runner }) {
+        if (!address) {
+            throw new Error("P2PEscrowClient: contract address is required");
+        }
+        if (!runner) {
+            throw new Error("P2PEscrowClient: runner (signer or provider) is required");
+        }
+        this._contract = P2PEscrow__factory_1.P2PEscrow__factory.connect(address, runner);
+    }
+    static connect(address, runner) {
+        return new P2PEscrowClient({ address, runner });
+    }
+    get address() {
+        return this._contract.target.toString();
+    }
+    get runner() {
+        return this._contract.runner ?? null;
+    }
+    get contract() {
+        return this._contract;
+    }
+    async getRunnerAddress() {
+        const currentRunner = this._contract.runner;
+        if (currentRunner?.getAddress) {
+            return currentRunner.getAddress();
+        }
+        return null;
+    }
+    withRunner(runner) {
+        this._contract = this._contract.connect(runner);
+        return this;
+    }
+    /**
+     * Helpers
+     */
+    static calculateFee(amount) {
+        const feeAmount = (amount * constants_1.FEE_BPS) / constants_1.BPS_DENOMINATOR;
+        return {
+            feeAmount,
+            sellerAmount: amount - feeAmount,
+        };
+    }
+    static lockDurationSeconds() {
+        return constants_1.LOCK_DURATION_SECONDS;
+    }
+    /**
+     * Reads
+     */
+    async getFeeRecipient() {
+        return this._contract.feeRecipient();
+    }
+    async getArbitrator() {
+        return this._contract.arbitrator();
+    }
+    async getOwner() {
+        return this._contract.owner();
+    }
+    async isSupportedToken(token) {
+        return this._contract.supportedTokens(token);
+    }
+    async getOrderId(params) {
+        return this._contract.getOrderId(params.buyer, params.seller, params.orderId);
+    }
+    async getOrder(params) {
+        const order = await this._contract.getOrder(params.buyer, params.seller, params.orderId);
+        return this.mapOrder(order);
+    }
+    async getRawOrder(params) {
+        const orderKey = await this.getOrderId(params);
+        return this._contract.orders(orderKey);
+    }
+    /**
+     * Transactions
+     */
+    async createOrder(params) {
+        return this._contract.createOrder(params.buyer, params.seller, params.orderId, params.amount, params.token);
+    }
+    async lockOrder(params) {
+        return this._contract.lockOrder(params.buyer, params.orderId);
+    }
+    async buyerWithdraw(params) {
+        return this._contract.buyerWithdraw(params.seller, params.orderId);
+    }
+    async buyerConfirmReceipt(params) {
+        return this._contract.buyerConfirmReceipt(params.seller, params.orderId);
+    }
+    async sellerRefund(params) {
+        return this._contract.sellerRefund(params.buyer, params.orderId);
+    }
+    async sellerRelease(params) {
+        return this._contract.sellerRelease(params.buyer, params.orderId);
+    }
+    async setArbitrationPending(params) {
+        return this._contract.setArbitrationPending(params.buyer, params.seller, params.orderId);
+    }
+    async cancelArbitration(params) {
+        return this._contract.cancelArbitration(params.buyer, params.seller, params.orderId);
+    }
+    async arbitrate(params) {
+        return this._contract.arbitrate(params.buyer, params.seller, params.orderId, params.releaseToSeller ?? false);
+    }
+    async setFeeRecipient(newRecipient) {
+        return this._contract.setFeeRecipient(newRecipient);
+    }
+    async setArbitrator(newArbitrator) {
+        return this._contract.setArbitrator(newArbitrator);
+    }
+    async addSupportedToken(token) {
+        return this._contract.addSupportedToken(token);
+    }
+    async removeSupportedToken(token) {
+        return this._contract.removeSupportedToken(token);
+    }
+    async transferOwnership(newOwner) {
+        return this._contract.transferOwnership(newOwner);
+    }
+    async renounceOwnership() {
+        return this._contract.renounceOwnership();
+    }
+    on(eventOrFilter, listener) {
+        void this._contract.on(eventOrFilter, listener);
+    }
+    once(eventOrFilter, listener) {
+        void this._contract.once(eventOrFilter, listener);
+    }
+    off(eventOrFilter, listener) {
+        void this._contract.off(eventOrFilter, listener);
+    }
+    removeAllListeners(event) {
+        void this._contract.removeAllListeners(event);
+    }
+    mapOrder(order) {
+        return {
+            buyer: order.buyer,
+            seller: order.seller,
+            amount: order.amount,
+            lockedUntil: order.lockedUntil,
+            token: order.token,
+            status: Number(order.status),
+            previousStatus: Number(order.previousStatus),
+        };
+    }
+}
+exports.P2PEscrowClient = P2PEscrowClient;
+const createP2PEscrowClient = (config) => new P2PEscrowClient(config);
+exports.createP2PEscrowClient = createP2PEscrowClient;
+//# sourceMappingURL=p2pEscrowClient.js.map