@syeedalireza/auction-escrow-web3

A clean TypeScript wrapper around blockchain smart contracts to handle escrow flows in decentralized e-commerce reverse auctions.

Features

• Web3 Integration: Uses ethers.js to interact with EVM-compatible blockchains.
• Hexagonal Architecture: Clean separation of concerns using the Ports and Adapters pattern.
• Type Safety: Fully typed interactions with the smart contract.

Installation

npm install @syeedalireza/auction-escrow-web3 ethers

Usage

import { EscrowAdapter, EscrowState } from '@syeedalireza/auction-escrow-web3';

// Initialize the adapter
const escrow = new EscrowAdapter({
  contractAddress: '0xYourContractAddress',
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_PROJECT_ID',
  privateKey: '0xYourPrivateKey' // Optional: Only required for write operations
});

async function run() {
  const auctionId = 'auction-123';
  const sellerAddress = '0xSellerAddress';

  // 1. Create an escrow (Buyer locks funds)
  const createTx = await escrow.createEscrow(auctionId, sellerAddress);
  console.log('Escrow created:', createTx);

  // 2. Deposit funds
  const depositTx = await escrow.depositFunds(auctionId, '1000000000000000000'); // 1 ETH in Wei
  console.log('Funds deposited:', depositTx);

  // 3. Check status
  const details = await escrow.getEscrowDetails(auctionId);
  console.log('Escrow State:', EscrowState[details.state]);

  // 4. Release funds to seller (after service delivery)
  const releaseTx = await escrow.releaseFunds(auctionId);
  console.log('Funds released:', releaseTx);
}

API

EscrowAdapter

Constructor

new EscrowAdapter(config: EscrowConfig)

• config.contractAddress: The deployed smart contract address.
• config.rpcUrl: The RPC endpoint (e.g., Infura, Alchemy).
• config.privateKey: (Optional) Private key for signing transactions. Required for state-changing methods.

Methods

• createEscrow(auctionId: string, seller: string): Promise<string>: Initializes the escrow. Returns transaction hash.
• depositFunds(auctionId: string, amountInWei: string): Promise<string>: Locks funds in the contract.
• releaseFunds(auctionId: string): Promise<string>: Releases funds to the seller.
• refundBuyer(auctionId: string): Promise<string>: Refunds the buyer (if conditions aren't met).
• getEscrowDetails(auctionId: string): Promise<EscrowDetails>: Fetches current state of the escrow.

Types

enum EscrowState {
  AWAITING_DEPOSIT = 0,
  FUNDED = 1,
  RELEASED = 2,
  REFUNDED = 3
}

interface EscrowDetails {
  buyer: string;
  seller: string;
  amount: string;
  state: EscrowState;
}