Detailed Instructions

Escrow contract deployment is the foundational step. The seller, often the NFT owner, initiates the process by calling a function like createEscrow on a pre-deployed, audited contract, passing the NFT's contract address and token ID as parameters. This action locks the NFT into the escrow contract's custody, transferring it from the seller's wallet. The contract emits an event (e.g., EscrowCreated) containing a unique escrow ID for tracking. It's critical to verify the contract's address on a block explorer like Etherscan to ensure it's the legitimate, non-malicious version.

• Sub-step 1: Approve the escrow contract to transfer your NFT using ERC721.approve(escrowAddress, tokenId)
• Sub-step 2: Call createEscrow(nftAddress, tokenId, buyerAddress, price) specifying terms
• Sub-step 3: Verify the EscrowCreated event and save the returned escrowId

solidityCopy
// Example function signature for initiation
function createEscrow(
    address _nftContract,
    uint256 _tokenId,
    address _buyer,
    uint256 _price
) external returns (uint256 escrowId);

Tip: Always check the contract's verification status and recent transactions to avoid interacting with a phishing copy.

Detailed Instructions

Conditional fund locking occurs when the buyer deposits the cryptocurrency (e.g., ETH) specified in the escrow terms. The buyer calls a payable function like depositPayment(uint256 escrowId) and sends the exact msg.value. The contract logic validates that the sent amount matches the agreed price and that the caller is the designated buyer. The funds are held securely within the contract's balance, creating a state where both the NFT and the payment are locked. The contract state updates to reflect the fundsDeposited status. Buyers must account for gas fees on top of the purchase price and ensure they are interacting with the correct escrowId.

• Sub-step 1: Review the escrow terms from the contract's public escrows mapping using the escrowId
• Sub-step 2: Execute the deposit transaction, sending the exact Wei amount
• Sub-step 3: Confirm the transaction success and check for a PaymentDeposited event

solidityCopy
// The buyer's deposit call
function depositPayment(uint256 _escrowId) external payable {
    require(msg.sender == escrows[_escrowId].buyer, "Not buyer");
    require(msg.value == escrows[_escrowId].price, "Incorrect amount");
    escrows[_escrowId].fundsDeposited = true;
    emit PaymentDeposited(_escrowId, msg.value);
}

Tip: Use a block explorer to confirm the contract's balance increased by the correct amount, proving the funds are locked.

Detailed Instructions

Atomic settlement is the core function that executes the swap. Once funds are confirmed, either the buyer or seller can call completeEscrow(escrowId). The contract performs critical checks: verifying the NFT is still held, the funds are deposited, and the caller is an authorized party. If all conditions pass, it executes two transfers in a single, atomic transaction: it sends the NFT to the buyer via ERC721.safeTransferFrom(contract, buyer, tokenId) and sends the locked funds to the seller via payable(seller).transfer(price). This eliminates counterparty risk. The contract state is then marked as completed or fulfilled, and the escrow is closed. Failed conditions will revert the entire transaction.

• Sub-step 1: Verify pre-conditions: fundsDeposited == true and NFT owner == escrow contract
• Sub-step 2: Call the completeEscrow function with the correct ID
• Sub-step 3: Monitor transaction logs for EscrowCompleted and Transfer events

solidityCopy
function completeEscrow(uint256 _escrowId) external {
    Escrow storage e = escrows[_escrowId];
    require(e.fundsDeposited, "Funds not sent");
    require(msg.sender == e.buyer || msg.sender == e.seller, "Unauthorized");
    // Transfer NFT to buyer
    IERC721(e.nftContract).safeTransferFrom(address(this), e.buyer, e.tokenId);
    // Transfer funds to seller
    payable(e.seller).transfer(e.price);
    e.completed = true;
    emit EscrowCompleted(_escrowId);
}

Tip: The atomic nature means the transaction will revert if the NFT was withdrawn or the contract lacks funds, protecting both sides.

Detailed Instructions

Contingency execution is handled by predefined functions for aborting the trade. A cancelEscrow(escrowId) function allows the seller to reclaim the NFT if the buyer hasn't deposited funds within a timeout period (e.g., 7 days), checked via block.timestamp > creationTime + timeout. Conversely, a refundBuyer(escrowId) function lets the buyer reclaim their payment if the seller fails to finalize or the terms are violated. These functions include access controls, often allowing only the rightful party to call them after specific conditions are met. Dispute resolution in more complex escrows may involve a multi-signature release or a trusted third-party arbitrator address authorized to call completeEscrow or refund.

• Sub-step 1: Check the escrow's createdAt timestamp and timeoutDuration
• Sub-step 2: For cancellation, seller calls cancelEscrow before funds are deposited
• Sub-step 3: For a refund, buyer calls refundBuyer after deposit but before completion if terms are broken

solidityCopy
// Example cancellation logic for the seller
function cancelEscrow(uint256 _escrowId) external {
    Escrow storage e = escrows[_escrowId];
    require(msg.sender == e.seller, "Not seller");
    require(!e.fundsDeposited, "Funds already sent");
    require(block.timestamp > e.createdAt + 7 days, "Timeout not reached");
    IERC721(e.nftContract).safeTransferFrom(address(this), e.seller, e.tokenId);
    e.cancelled = true;
    emit EscrowCancelled(_escrowId);
}

Tip: Clearly agreed-upon timeout periods and cancellation terms in the initial agreement are crucial to avoid frozen assets.

Detailed Instructions

Begin by defining the core state variables and access control. Use OpenZeppelin's Ownable contract for administrative functions. The contract must track the escrow terms for each listing, including the NFT contract address, token ID, price, and involved parties. Store this data in a mapping, such as mapping(uint256 => EscrowListing) public listings;, where the key is a unique escrow ID. Declare the EscrowListing struct to hold the seller's address (seller), the buyer's address (buyer), the NFT contract address (nftContract), the token ID (tokenId), the agreed price in wei (price), and the current escrow state (e.g., State.Created).

solidityCopy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@openzeppelin/contracts/access/Ownable.sol";

contract NFTEscrow is Ownable {
    enum State { Created, Funded, Completed, Disputed, Cancelled }
    struct EscrowListing {
        address seller;
        address buyer;
        address nftContract;
        uint256 tokenId;
        uint256 price;
        State state;
    }
    mapping(uint256 => EscrowListing) public listings;
    uint256 public nextListingId;
}

Tip: Using an enum for the state ensures clear, validated transitions and prevents invalid contract states.

Detailed Instructions

Implement the primary functions that facilitate the escrow lifecycle. The createEscrow function should be called by the seller, taking parameters for the buyer, NFT contract, token ID, and price. It must verify the seller is the owner of the NFT, typically by checking IERC721(nftContract).ownerOf(tokenId) == msg.sender. Upon success, it creates a new entry in the listings mapping with the state set to State.Created. The fundEscrow function allows the buyer to deposit the agreed ETH. It must check that the msg.value equals the listing's price and that the state is Created. Upon receiving funds, the contract updates the state to State.Funded and holds the ETH in its balance.

solidityCopy
function createEscrow(address _buyer, address _nftContract, uint256 _tokenId, uint256 _price) external returns (uint256) {
    require(IERC721(_nftContract).ownerOf(_tokenId) == msg.sender, "Not NFT owner");
    uint256 listingId = nextListingId++;
    listings[listingId] = EscrowListing({
        seller: msg.sender,
        buyer: _buyer,
        nftContract: _nftContract,
        tokenId: _tokenId,
        price: _price,
        state: State.Created
    });
    emit EscrowCreated(listingId, msg.sender, _buyer, _price);
    return listingId;
}

function fundEscrow(uint256 _listingId) external payable {
    EscrowListing storage listing = listings[_listingId];
    require(listing.state == State.Created, "Invalid state");
    require(msg.sender == listing.buyer, "Not the buyer");
    require(msg.value == listing.price, "Incorrect payment");
    listing.state = State.Funded;
    emit EscrowFunded(_listingId, msg.value);
}

Tip: Always emit events for key state changes like EscrowCreated and EscrowFunded to allow off-chain applications to track contract activity.

Detailed Instructions

The completeEscrow function is the critical settlement mechanism. It should be callable by the buyer after funding. The function must verify the escrow is in the State.Funded state. It then executes two secure transfers atomically: first, it transfers the NFT from the seller to the buyer using IERC721(listing.nftContract).safeTransferFrom(listing.seller, listing.buyer, listing.tokenId);. Second, it transfers the held Ether from the contract to the seller using payable(listing.seller).transfer(listing.price);. After both operations succeed, update the listing state to State.Completed. This atomic execution is vital—if either transfer fails, the entire transaction reverts, preventing a scenario where one party receives an asset without the other.

solidityCopy
function completeEscrow(uint256 _listingId) external {
    EscrowListing storage listing = listings[_listingId];
    require(listing.state == State.Funded, "Escrow not funded");
    require(msg.sender == listing.buyer, "Not the buyer");

    // Transfer NFT from seller to buyer
    IERC721(listing.nftContract).safeTransferFrom(listing.seller, listing.buyer, listing.tokenId);

    // Transfer funds from contract to seller
    payable(listing.seller).transfer(listing.price);

    listing.state = State.Completed;
    emit EscrowCompleted(_listingId);
}

Tip: Use safeTransferFrom for NFTs to ensure the receiver is an ERC721-compliant contract or EOA, providing an extra layer of safety over transferFrom.

Detailed Instructions

A robust escrow must handle edge cases. Implement a cancelEscrow function that allows the seller to cancel an unfunded listing (State.Created). This protects sellers if a buyer does not deposit funds. More importantly, add a dispute resolution mechanism. Create an openDispute function that either party can call to change the state to State.Disputed, freezing the assets. The actual resolution should be handled by the contract owner (or a designated arbitrator) via a resolveDispute function. This function takes the listing ID and a bool indicating whether to award funds to the seller or refund the buyer. It must check the state is Disputed, then execute the appropriate asset transfer (NFT or ETH) based on the ruling before setting a final state.

solidityCopy
function openDispute(uint256 _listingId) external {
    EscrowListing storage listing = listings[_listingId];
    require(msg.sender == listing.seller || msg.sender == listing.buyer, "Not a party");
    require(listing.state == State.Funded, "Cannot dispute");
    listing.state = State.Disputed;
    emit DisputeOpened(_listingId, msg.sender);
}

function resolveDispute(uint256 _listingId, bool _awardToSeller) external onlyOwner {
    EscrowListing storage listing = listings[_listingId];
    require(listing.state == State.Disputed, "Not in dispute");
    
    if (_awardToSeller) {
        // Seller gets ETH, buyer gets NFT (already held by contract logic)
        payable(listing.seller).transfer(listing.price);
    } else {
        // Buyer gets ETH back, seller keeps NFT
        payable(listing.buyer).transfer(listing.price);
        // Optionally return NFT to seller if it was held in escrow
    }
    listing.state = State.Completed;
    emit DisputeResolved(_listingId, _awardToSeller);
}

Tip: In a production system, consider a more decentralized dispute layer, but a simple owner-controlled resolution is a standard starting point for a basic contract.

Detailed Instructions

Use Hardhat or Foundry to compile and test the contract. Write unit tests that simulate the entire escrow flow. First, deploy mock ERC721 tokens for testing. Key test cases must verify: the seller can create an escrow, the buyer can fund it with the exact ETH amount, and the completeEscrow function successfully transfers both assets. Test security invariants: a non-buyer cannot fund the escrow, the escrow cannot be completed unless funded, and the contract correctly reverts on under/over payments. Use Foundry's forge test or Hardhat's test runner with Chai assertions. For example, a test should check that after funding, the contract's ETH balance increases by the listing price. Simulate a dispute scenario to ensure the owner can resolve it and funds are sent to the correct party.

javascriptCopy
// Example Hardhat test snippet
describe("NFTEscrow", function () {
  it("Should create, fund, and complete an escrow", async function () {
    await nft.mint(seller.address, tokenId);
    await nft.connect(seller).approve(escrow.address, tokenId);
    
    await escrow.connect(seller).createEscrow(buyer.address, nft.address, tokenId, price);
    await escrow.connect(buyer).fundEscrow(0, { value: price });
    
    expect(await ethers.provider.getBalance(escrow.address)).to.equal(price);
    
    await escrow.connect(buyer).completeEscrow(0);
    expect(await nft.ownerOf(tokenId)).to.equal(buyer.address);
  });
});

Tip: Include tests for reentrancy attacks by ensuring state updates happen before external calls (Checks-Effects-Interactions pattern) or using ReentrancyGuard.