# Agent Fees & Earnings Source: https://docs.zen.land/agents/agent-fees How agents earn money on Zenland. ## Fee Types Agents can earn through two fee mechanisms: Paid upfront when selected for an escrow Paid only when you resolve a dispute *** ## Assignment Fee ### How It Works * **When charged:** At escrow creation * **Who pays:** The buyer * **Typical range:** 0-2% * **Most common:** 0% (many agents don't charge this) ### Why Charge It? * Compensation for being "on call" * Reserves your capacity for this escrow * Income even if there's no dispute ### Why NOT Charge It? * Reduces your competitiveness * Disputed rarely, so opportunity cost is low * Entry barrier for your first clients New agents: consider 0% assignment fee to attract your first clients. *** ## Dispute Fee ### How It Works * **When charged:** Only when you resolve a dispute * **Deducted from:** The escrow amount (before split) * **Range:** 0.1% - 10% (set by DAO) * **Typical:** 2-5% ### Example Calculation ``` Escrow Amount: $5,000 Your Dispute Fee: 3% When you resolve: - Your fee: $5,000 × 3% = $150 - Remaining for split: $4,850 ``` *** ## Setting Your Fees When registering or updating your profile: | Parameter | Min | Max | Notes | | -------------- | ---- | --- | ----------- | | Assignment Fee | 0% | 2% | Can be 0 | | Dispute Fee | 0.1% | 10% | Must be > 0 | ### Strategy Considerations **Pros:** * More competitive * Attract more cases * Good for building reputation **Cons:** * Less income per case * May signal inexperience **Pros:** * More income per case * May signal expertise * Sustainable for serious agents **Cons:** * Fewer cases * Only works with reputation **0% assignment, 3-5% dispute:** * No barrier to selection * Fair compensation when you work * Competitive yet sustainable *** ## Earning Projections ### Conservative Estimates | Monthly Cases | Avg Escrow | Dispute Fee | Monthly Earnings | | ------------- | ---------- | ----------- | ---------------- | | 2 | \$1,000 | 3% | \$60 | | 5 | \$2,000 | 3% | \$300 | | 10 | \$5,000 | 3% | \$1,500 | | 20 | \$10,000 | 3% | \$6,000 | Actual earnings depend on your reputation, MAV, and the volume of disputes in the system. ### What Affects Your Volume? * **Reputation:** Higher = more selections * **MAV:** Higher = eligible for bigger escrows * **Fees:** Lower (to a point) = more competitive * **Response time:** Faster = better reputation *** ## Receiving Payment When you resolve a dispute: 1. You submit your decision 2. Smart contract calculates your fee 3. Fee is transferred to your wallet 4. Remaining funds split between parties 5. All in one atomic transaction No invoicing required. Fees are paid instantly on resolution. *** ## Gas Costs With your own wallet: * `agentResolve()` costs \~100,000-150,000 gas * At 20 gwei: \~\$2-3 per resolution With NYKNYC wallet: * **\$0** — Zenland sponsors all agent gas Register with zero gas costs → *** ## Tax Considerations Agent earnings may be taxable income. Consult a tax professional in your jurisdiction. You can export your earnings history from the agent dashboard for record-keeping. # Agent Staking Source: https://docs.zen.land/agents/agent-staking How agent staking works and why it matters. ## Dual Staking Model Zenland agents stake two types of assets: USDC or USDT that determines your Maximum Arbitratable Value. Zenland DAO tokens that show protocol alignment. *** ## Stablecoin Stake Your stablecoin stake has two purposes: ### 1. Determines MAV ``` MAV = Stablecoin Stake × MAV Multiplier Example: $1,000 × 20 = $20,000 MAV ``` You can only handle escrows up to your MAV. ### 2. Slashing Collateral If you're found to have acted in bad faith, the DAO can slash your stablecoin stake. Slashing is serious. Only stake what you're willing to risk. *** ## DAO Token Stake Token stake shows commitment to the Zenland ecosystem: * **Alignment:** You have a stake in the protocol's success * **Governance:** Your tokens give you voting power * **Reputation Signal:** Higher token stake signals commitment ### Minimum Requirements | Stake Type | Minimum | | ---------- | ------------------ | | Stablecoin | \~\$100 equivalent | | DAO Token | \~100 tokens | Minimums are set by DAO governance and can change. *** ## MAV Mechanics ### How MAV Protects Users If an agent has MAV of \$20,000: * They can't be selected for a \$25,000 escrow * Their stake is proportionally significant to the escrows they handle * Bad behavior risks meaningful financial loss ### MAV Multiplier The multiplier is set by the DAO: | Multiplier | Meaning | | ---------- | ------------------------------------------ | | 10x | Conservative, high agent skin in game | | 20x | Balanced approach (current setting) | | 50x | More permissive, favor agent accessibility | *** ## Staking More To increase your MAV: Go to your agent dashboard Choose stablecoins and/or DAO tokens Confirm the transaction Your new MAV is active immediately *** ## Withdrawing Stake Withdrawal has several safety mechanisms: ### Conditions for Withdrawal 1. **No active cases** — All invited disputes must be resolved 2. **Cooldown period** — 30 days since last case resolution 3. **Partial withdrawal okay** — As long as remaining stake meets minimums ### The `activeCases` Counter ``` When invited to dispute: activeCases++ When dispute resolves: activeCases-- Can withdraw only when: activeCases == 0 ``` ### Cooldown Period After your last case resolves, you must wait 30 days before withdrawing. **Why?** Prevents agents from: * Taking a bribe * Making a bad decision * Immediately unstaking to avoid consequences *** ## Slashing The DAO can slash agent stakes for misconduct: ### Slashable Offenses | Offense | Severity | Typical Slash | | ------------------------- | -------- | -------------- | | Accepting bribes | Critical | Up to 100% | | Clear bias/collusion | High | 25-75% | | Repeated unjust decisions | Medium | 10-50% | | Ignoring cases | Low | Warning to 10% | ### Slashing Process 1. Community member reports agent 2. DAO investigates through governance 3. Proposal to slash is voted on 4. If passed, stake is transferred to treasury or victim Slashing requires DAO vote. No individual can slash an agent. *** ## Economic Security The staking model creates these incentives: Build reputation → Get more cases → Earn more fees Accept bribe → Get slashed → Lose stake + reputation Can't handle escrows much larger than stake → Limited blast radius *** Learn about earning potential → # Becoming an Agent Source: https://docs.zen.land/agents/becoming-an-agent How to register as a Zenland dispute resolution agent. ## Requirements To become a Zenland agent, you need: Minimum \~\$100 worth of USDC or USDT Minimum \~100 Zenland DAO tokens Ethereum wallet (NYKNYC recommended for gas-free registration) Ability to respond to disputes within 7 days *** ## Registration Steps Go to the Zenland app and connect your wallet. Click on "Become an Agent" in your profile or navigation. Allow the AgentRegistry contract to use your stablecoins and DAO tokens. Configure your assignment fee and dispute fee (within DAO limits). Deposit your stablecoin and DAO token stakes. Sign the transaction to complete registration. *** ## Understanding Your MAV Your **Maximum Arbitratable Value (MAV)** determines the largest escrow you can handle: ``` Stablecoin Stake: $1,000 MAV Multiplier: 20x Your MAV: $20,000 ``` ### Increasing Your MAV Want to handle larger escrows? Increase your stake: | Stake | MAV (at 20x) | | -------- | ------------ | | \$100 | \$2,000 | | \$500 | \$10,000 | | \$1,000 | \$20,000 | | \$5,000 | \$100,000 | | \$10,000 | \$200,000 | *** ## Setting Your Fees You control your fee structure: ### Assignment Fee * **Range:** 0-2% (set by DAO) * **When charged:** Upfront when selected for an escrow * **Typical:** 0% (most agents don't charge this) ### Dispute Fee * **Range:** 0.1-10% (set by DAO) * **When charged:** Only when you resolve a dispute * **Typical:** 2-5% Start with lower fees to attract your first cases and build reputation. *** ## Managing Your Status ### Availability Toggle Set yourself as unavailable when: * You're on vacation * You have too many active cases * You need a break Unavailable agents can still handle their existing cases but won't appear in new escrow creation. ### View Your Cases Monitor your active cases: * Pending invitations * Cases awaiting your decision * Completed resolutions *** ## Withdrawal Rules You can withdraw your stake, but there are conditions: | Situation | Can Withdraw? | | ---------------------- | ------------------------------- | | No active cases | ✅ After 30-day cooldown | | Active cases exist | ❌ Must wait until resolved | | Recently resolved case | ⏳ 30 days after last resolution | The 30-day cooldown protects against agents "rage quitting" after controversial decisions. *** ## Best Practices Fast response times build reputation. Aim for 24-48 hours. Review all evidence carefully before deciding. Explain your reasoning when you decide. Never have personal or financial ties to either party. Keep records of your decision-making process. *** ## Common Questions Yes, you can update fees anytime. Changes only affect new escrows. Honest mistakes happen. The DAO only punishes clear misconduct, not difficult judgment calls. Yes, but you cannot be the agent for your own escrows. *** Understand the staking mechanics → # Resolving Disputes as an Agent Source: https://docs.zen.land/agents/resolving-disputes How to review and resolve disputes fairly. ## When You're Invited When someone invites you to resolve a dispute: 1. **Notification** — You'll see it in your agent dashboard 2. **7-Day Window** — You have 7 days to respond or you'll timeout 3. **Review Materials** — Examine the escrow terms and evidence *** ## The Review Process Read the PDF contract stored on-chain. What did both parties agree to? Look at what each party has submitted: * Delivered work/goods * Communication logs * Screenshots, files, etc. What is each party claiming? What evidence supports each claim? Determine a fair split based on the evidence. Enter the split percentages and confirm. *** ## Making Fair Decisions ### Common Scenarios **Decision:** 100% to seller (minus your fee) Buyer may be having buyer's remorse. Terms were met. **Decision:** 100% to buyer (minus your fee) Clear non-delivery = full refund. **Decision:** Proportional split If 60% of work was done, consider 60/40 split. **Decision:** Review original terms carefully What was actually promised? Refer to the PDF. **Decision:** Depends on specifications Were quality standards defined? Did work meet them? *** ## Decision Framework When unsure, consider: 1. **What was the agreement?** — Always start with the terms 2. **What can be proven?** — Evidence > claims 3. **Who is acting in good faith?** — Patterns matter 4. **What's proportional?** — Match compensation to delivery When in doubt, a 50/50 split acknowledges shared responsibility. Save 0/100 splits for clear-cut cases. *** ## Submitting Your Decision To resolve a dispute: Navigate to the dispute in your dashboard Specify buyer % and seller % Example: `buyerBps: 4000` (40%), `sellerBps: 6000` (60%) The transaction executes the split ### Fee Calculation ``` Escrow: $1,000 Your fee: 5% You enter: 40% buyer, 60% seller Calculation: 1. Your fee: $50 2. Remaining: $950 3. Buyer: $950 × 40% = $380 4. Seller: $950 × 60% = $570 ``` *** ## Best Practices Show you're attentive, even if you need more time to decide. Request clarification if evidence is unclear. Keep notes on why you decided what you did. Similar cases should have similar outcomes. *** ## What You Should NOT Do These actions can result in slashing: * ❌ Accept bribes from either party * ❌ Favor a party you have a relationship with * ❌ Decide without reviewing evidence * ❌ Take longer than 7 days without acting * ❌ Communicate privately with one party about the case *** ## Handling Difficult Cases Sometimes cases are genuinely hard: ### Insufficient Evidence If neither party provides clear evidence: * Ask for more documentation * Consider a 50/50 split if nothing helps ### Hostile Parties If parties are abusive: * Focus on the evidence, not the tone * Make your decision professionally ### Complex Technical Issues If you don't understand the work: * Focus on what was promised vs delivered * Ask for simplified explanations *** Learn about earning potential → # What is an Agent? Source: https://docs.zen.land/agents/what-is-an-agent How Zenland agents provide professional dispute resolution. ## The Role of Agents Agents are **professional arbitrators** who resolve disputes between buyers and sellers when they can't agree. An agent is like a judge for your escrow. When there's a disagreement, they review the evidence and make a fair decision. *** ## How Agents Work ```mermaid theme={null} graph TD A[Dispute Opened] --> B[Agent Invited] B --> C[Agent Reviews Case] C --> D[Buyer & Seller Present Evidence] D --> E[Agent Decides Split] E --> F[Funds Distributed] F --> G[Agent Receives Fee] ``` ### Key Responsibilities * 📋 **Review disputes** — Examine terms, evidence, and communications * ⚖️ **Make fair decisions** — Determine how to split escrowed funds * ⏰ **Respond promptly** — Act within 7 days of being invited * 🎯 **Stay neutral** — No relationship with either party *** ## Why Stake? Agents must **stake funds** to participate. This creates accountability: Agents risk their own money if they misbehave. Stake determines the maximum escrow size they can handle. DAO token stake shows commitment to the protocol. DAO can slash stakes for proven misconduct. *** ## What Agents Earn Agents earn fees for their services: | Fee Type | When Earned | Typical Range | | ------------------ | --------------------------- | ------------- | | **Assignment Fee** | When selected for an escrow | 0-2% | | **Dispute Fee** | When resolving a dispute | 1-10% | Most income comes from dispute fees. Assignment fees are optional upfront payments. ### Example Earnings ``` Escrow: $10,000 Dispute Fee: 5% Agent resolves dispute... Agent earns: $500 ``` *** ## Agent Selection Users choose agents when creating escrows. Selection criteria: Number of disputes resolved, time as agent, community feedback. Maximum escrow value the agent can handle (based on stake). Assignment and dispute fees set by the agent. Whether the agent is currently accepting new cases. *** ## Agent Validation Agents are validated at two points: ### At Escrow Creation * Is this agent registered? * Is their MAV ≥ escrow amount? * Are they active and available? ### At Agent Invite Same checks run again. This prevents: * Agents unstaking after being selected * Multiple high-value disputes draining MAV *** ## What If An Agent Misbehaves? The DAO provides oversight: | Issue | Response | | ------------------------- | ------------------------------------ | | Clearly biased decision | DAO investigation, possible slashing | | Accepting bribes | Heavy slashing, potential ban | | Repeatedly slow responses | Reputation damage, reduced selection | | Abandoning cases | Timeout mechanism, reputation hit | Agents cannot be punished for making difficult but fair decisions. The DAO only acts on clear misconduct. *** Learn how to register → # API Reference Source: https://docs.zen.land/developers/api-reference Complete function reference for Zenland smart contracts. ## EscrowFactory ### Write Functions #### createEscrow Creates and funds a new escrow atomically. ```solidity theme={null} function createEscrow( bytes32 userSalt, // User-provided entropy for address address seller, // Seller address address agent, // Agent (or address(0) for locked) address token, // ERC20 token address uint256 amount, // Escrow amount (in token decimals) uint256 buyerProtectionTime, // Time buyer has to review (seconds) bytes32 termsHash, // Hash of PDF terms uint256 version, // Contract version address expectedEscrow // Expected address (safety check) ) external returns (address escrow); ``` | Reverts If | | ----------------------------------- | | Token not whitelisted | | Amount below minimum | | Amount above maximum | | Agent not valid (if specified) | | Expected address mismatch | | Insufficient token balance/approval | ### View Functions #### quoteCreateEscrow ```solidity theme={null} function quoteCreateEscrow( bytes32 userSalt, address seller, address agent, address token, uint256 amount, uint256 buyerProtectionTime ) external view returns ( address predictedAddress, uint256 creationFee, uint256 assignmentFee ); ``` #### isEscrow ```solidity theme={null} function isEscrow(address addr) external view returns (bool); ``` *** ## EscrowImplementation ### State Variables (Read) ```solidity theme={null} function buyer() external view returns (address); function seller() external view returns (address); function agent() external view returns (address); function token() external view returns (address); function amount() external view returns (uint256); function state() external view returns (EscrowState); function termsHash() external view returns (bytes32); function buyerProtectionTime() external view returns (uint256); function sellerAcceptDeadline() external view returns (uint256); function fulfilledAt() external view returns (uint256); function agentInvitedAt() external view returns (uint256); ``` ### Write Functions #### accept Seller accepts the escrow terms. ```solidity theme={null} function accept() external; ``` | Constraint | | ------------------------------ | | Caller must be seller | | State must be PENDING | | Must be before accept deadline | #### decline Seller declines, refunding buyer. ```solidity theme={null} function decline() external; ``` #### cancelExpired Buyer cancels after acceptance window. ```solidity theme={null} function cancelExpired() external; ``` | Constraint | | -------------------------------- | | State must be PENDING | | Accept deadline must have passed | #### markFulfilled Seller marks work as complete. ```solidity theme={null} function markFulfilled() external; ``` | Constraint | | --------------------- | | Caller must be seller | | State must be ACTIVE | #### release Buyer releases funds to seller. ```solidity theme={null} function release() external; ``` | Constraint | | --------------------------------- | | Caller must be buyer | | State must be ACTIVE or FULFILLED | #### sellerRefund Seller refunds 100% to buyer. ```solidity theme={null} function sellerRefund() external; ``` | Constraint | | -------------------------- | | Caller must be seller | | State must not be terminal | #### claimExpired Seller claims after protection expires. ```solidity theme={null} function claimExpired() external; ``` | Constraint | | --------------------------------- | | Caller must be seller | | State must be FULFILLED | | Protection time must have expired | #### openDispute Buyer opens a dispute. ```solidity theme={null} function openDispute() external; ``` | Constraint | | --------------------------------- | | Caller must be buyer | | State must be ACTIVE or FULFILLED | #### inviteAgent Either party invites agent. ```solidity theme={null} function inviteAgent() external; ``` | Constraint | | ---------------------------- | | State must be DISPUTED | | Agent must not be address(0) | | Agent must still be valid | #### claimAgentTimeout Claim timeout after agent fails to act. ```solidity theme={null} function claimAgentTimeout() external; ``` | Constraint | | ------------------------------------ | | State must be AGENT\_INVITED | | 7 days must have passed since invite | #### agentResolve Agent resolves the dispute. ```solidity theme={null} function agentResolve( uint256 buyerBps, // 0-10000 uint256 sellerBps // 0-10000, must sum with buyerBps to 10000 ) external; ``` | Constraint | | ----------------------------- | | Caller must be agent | | State must be AGENT\_INVITED | | buyerBps + sellerBps == 10000 | #### proposeSplit Propose a mutual split. ```solidity theme={null} function proposeSplit( uint256 buyerBps, uint256 sellerBps ) external; ``` #### approveSplit Accept the other party's proposal. ```solidity theme={null} function approveSplit() external; ``` #### executeSplit Execute an approved split. ```solidity theme={null} function executeSplit() external; ``` *** ## AgentRegistry ### Write Functions #### register ```solidity theme={null} function register( uint256 stablecoinAmount, uint256 tokenAmount, uint256 assignmentFeeBps, uint256 disputeFeeBps ) external; ``` #### addStake ```solidity theme={null} function addStake( uint256 stablecoinAmount, uint256 tokenAmount ) external; ``` #### withdrawStake ```solidity theme={null} function withdrawStake( uint256 stablecoinAmount, uint256 tokenAmount ) external; ``` #### setFees ```solidity theme={null} function setFees( uint256 assignmentFeeBps, uint256 disputeFeeBps ) external; ``` #### setAvailable / setUnavailable ```solidity theme={null} function setAvailable() external; function setUnavailable() external; ``` ### View Functions #### getAgent ```solidity theme={null} function getAgent(address agent) external view returns ( bool registered, bool available, uint256 stablecoinStake, uint256 tokenStake, uint256 assignmentFeeBps, uint256 disputeFeeBps, uint256 activeCases, uint256 lastCaseTimestamp ); ``` #### validateAgentForContract ```solidity theme={null} function validateAgentForContract( address agent, uint256 contractValueWad // 18-decimal normalized ) external view returns (bool valid); ``` #### getMaxArbitratableValue ```solidity theme={null} function getMaxArbitratableValue( address agent ) external view returns (uint256 mavWad); ``` *** ## FeeManager ### View Functions #### quoteCreationFee ```solidity theme={null} function quoteCreationFee( address token, uint256 amount ) external view returns (uint256 fee); ``` #### isWhitelisted ```solidity theme={null} function isWhitelisted(address token) external view returns (bool); ``` # Architecture Overview Source: https://docs.zen.land/developers/architecture Technical architecture of the Zenland protocol. ## System Overview Zenland uses a modular smart contract architecture: ```mermaid theme={null} graph TB subgraph Core Contracts F[EscrowFactory] A[AgentRegistry] M[FeeManager] end subgraph Escrows E1[Escrow Clone 1] E2[Escrow Clone 2] E3[Escrow Clone N] end F -->|creates| E1 F -->|creates| E2 F -->|creates| E3 F -->|queries| A F -->|queries| M E1 -->|validates| A E2 -->|validates| A E3 -->|validates| A ``` *** ## Core Contracts ### EscrowFactory The main entry point for creating escrows. **Responsibilities:** * Deploy new escrow clones (EIP-1167) * Validate creation parameters * Collect protocol fees * Maintain `isEscrow` registry **Key Functions:** ```solidity theme={null} function createEscrow( bytes32 userSalt, address seller, address agent, address token, uint256 amount, uint256 buyerProtectionTime, bytes32 termsHash, uint256 version, address expectedEscrow ) external returns (address); ``` ### AgentRegistry Manages agent registration, staking, and validation. **Responsibilities:** * Agent registration and deregistration * Stake management (add/withdraw) * MAV calculations * Two-stage agent validation **Key Functions:** ```solidity theme={null} function register( uint256 stablecoinAmount, uint256 tokenAmount, uint256 assignmentFeeBps, uint256 disputeFeeBps ) external; function validateAgentForContract( address agent, uint256 contractValue ) external view returns (bool); ``` ### FeeManager Controls protocol fees and token whitelisting. **Responsibilities:** * Token whitelist management * Fee configuration per token * Fee quotation **Key Functions:** ```solidity theme={null} function quoteCreationFee( address token, uint256 amount ) external view returns (uint256); ``` ### EscrowImplementation The template contract cloned for each escrow. **Responsibilities:** * Hold escrowed funds * Enforce state machine * Process releases, refunds, splits * Handle dispute resolution *** ## Design Patterns ### Minimal Proxies (EIP-1167) Each escrow is a lightweight clone: ``` Implementation: 2500+ lines of logic Clone: Just 45 bytes pointing to implementation Gas savings: ~90% on deployment ``` ### CREATE2 Deterministic Addresses Escrow addresses are predictable: ```solidity theme={null} salt = keccak256(abi.encodePacked(userSalt, buyer)); address = CREATE2(salt, cloneCode); ``` **Benefits:** * PDF can include the address before creation * User can verify they're funding the right contract ### Two-Stage Agent Validation Agents are validated at: 1. **Creation:** Is agent valid for this escrow? 2. **Invite:** Is agent *still* valid when invited? **Why?** Prevents agents from unstaking after being selected. ### Checks-Effects-Interactions All state changes follow the pattern: 1. **Checks:** Validate inputs 2. **Effects:** Update state 3. **Interactions:** External calls last *** ## Trust Boundaries ### Factory-Escrow Trust ``` Factory maintains: isEscrow[address] = true Escrows can call: Factory for validation Other contracts: Untrusted ``` ### Agent-Escrow Trust ``` Agent can: Resolve disputes for their assigned escrow Agent cannot: Access other escrows Resolve without being invited ``` *** ## State Machine Escrow states and transitions: ```mermaid theme={null} stateDiagram-v2 [*] --> Pending: createEscrow Pending --> Active: accept Pending --> Refunded: decline/cancelExpired Active --> Fulfilled: markFulfilled Active --> Disputed: openDispute Active --> Released: release Active --> Refunded: sellerRefund Fulfilled --> Released: release/claimExpired Fulfilled --> Disputed: openDispute Disputed --> AgentInvited: inviteAgent Disputed --> Split: executeSplit AgentInvited --> Resolved: agentResolve AgentInvited --> Disputed: claimTimeout ``` *** ## Security Considerations All state-changing functions use ReentrancyGuard OpenZeppelin's SafeERC20 for all token operations Whitelist excludes tokens with hidden fees Escrow rules cannot change after deployment *** View detailed contract specs → # Integration Guide Source: https://docs.zen.land/developers/integration-guide How to integrate Zenland into your application. ## Overview Integrate Zenland escrows into your marketplace, platform, or dApp. Query escrow states and data Create/manage escrows (or use NYKNYC) Build real-time dashboards *** ## Installation ### NPM Package ```bash theme={null} npm install @zenland/contracts ``` ### Contract ABIs ```javascript theme={null} import { EscrowFactory__factory, EscrowImplementation__factory, AgentRegistry__factory, } from '@zenland/contracts'; ``` ### Direct Import ```javascript theme={null} // ABIs are also available at const factoryAbi = await fetch('https://zen.land/abi/EscrowFactory.json'); ``` *** ## Common Patterns ### 1. Predict Escrow Address Before creating, predict the escrow address: ```javascript theme={null} import { ethers } from 'ethers'; const factory = new ethers.Contract(FACTORY_ADDRESS, factoryAbi, provider); const { predictedAddress, creationFee, assignmentFee } = await factory.quoteCreateEscrow( userSalt, sellerAddress, agentAddress, tokenAddress, amount, buyerProtectionTime ); console.log(`Escrow will deploy to: ${predictedAddress}`); console.log(`Total fees: ${creationFee + assignmentFee}`); ``` ### 2. Create an Escrow ```javascript theme={null} // First: approve token spending const token = new ethers.Contract(tokenAddress, erc20Abi, signer); const totalAmount = amount + creationFee; await token.approve(FACTORY_ADDRESS, totalAmount); // Then: create escrow const tx = await factory.createEscrow( userSalt, sellerAddress, agentAddress, // or ethers.ZeroAddress for locked tokenAddress, amount, buyerProtectionTime, termsHash, 1, // version predictedAddress // safety check ); const receipt = await tx.wait(); console.log(`Escrow created: ${receipt.logs[0].args.escrow}`); ``` ### 3. Read Escrow State ```javascript theme={null} const escrow = new ethers.Contract( escrowAddress, escrowImplAbi, provider ); const state = await escrow.state(); const amount = await escrow.amount(); const buyer = await escrow.buyer(); const seller = await escrow.seller(); const states = ['PENDING', 'ACTIVE', 'FULFILLED', 'RELEASED', 'REFUNDED', 'DISPUTED', 'AGENT_INVITED', 'SPLIT', 'AGENT_RESOLVED']; console.log(`State: ${states[state]}`); ``` ### 4. Execute Actions ```javascript theme={null} // As buyer: release funds await escrow.connect(buyerSigner).release(); // As seller: mark fulfilled await escrow.connect(sellerSigner).markFulfilled(); // As seller: refund await escrow.connect(sellerSigner).sellerRefund(); ``` *** ## Indexing Events ### Using Ethers.js ```javascript theme={null} // Listen to all escrow creations factory.on('EscrowCreated', (escrow, buyer, seller, agent, token, amount, fee) => { console.log(`New escrow: ${escrow}`); }); // Listen to specific escrow events escrow.on('Released', (buyer, amount) => { console.log(`Released ${amount} to seller`); }); ``` ### Using The Graph We're working on a subgraph. Check back soon! ### Using Ponder ```typescript theme={null} // ponder.config.ts export default { contracts: { EscrowFactory: { abi: factoryAbi, address: FACTORY_ADDRESS, startBlock: START_BLOCK, }, }, }; // handlers/Factory.ts import { ponder } from '@ponder/core'; ponder.on('EscrowFactory:EscrowCreated', async ({ event, context }) => { await context.db.Escrow.create({ id: event.args.escrow, buyer: event.args.buyer, seller: event.args.seller, amount: event.args.amount, state: 'PENDING', }); }); ``` *** ## Gas Optimization ### For Your Users Combine approval + creation in one transaction. Use multicall for reading multiple escrows. ### For Your Backend ```javascript theme={null} // Use staticCall for simulations const wouldSucceed = await factory.createEscrow.staticCall(...args); // Estimate gas before sending const gasEstimate = await factory.createEscrow.estimateGas(...args); ``` *** ## Account Abstraction (ERC-4337) Want to sponsor gas for your users? ```javascript theme={null} // Using a paymaster (e.g., Pimlico, StackUp) const userOperation = await bundler.buildUserOp({ target: FACTORY_ADDRESS, data: factory.interface.encodeFunctionData('createEscrow', args), }); // Sponsor the operation userOperation.paymasterAndData = YOUR_PAYMASTER_DATA; await bundler.sendUserOperation(userOperation); ``` Want integration support? Reach out! *** ## API Reference See complete function signatures → # Smart Contracts Source: https://docs.zen.land/developers/smart-contracts Detailed smart contract specifications. ## Contract Overview | Contract | Type | Purpose | | -------------------- | ------------------ | -------------------------- | | EscrowFactory | Upgradeable (UUPS) | Creates and tracks escrows | | AgentRegistry | Upgradeable (UUPS) | Manages agent lifecycle | | FeeManager | Upgradeable (UUPS) | Fee configuration | | EscrowImplementation | Immutable | Template for escrow clones | *** ## EscrowFactory ### Storage ```solidity theme={null} address public implementation; address public agentRegistry; address public feeManager; address public treasury; mapping(address => bool) public isEscrow; ``` ### Key Functions #### createEscrow Creates and funds a new escrow atomically. ```solidity theme={null} function createEscrow( bytes32 userSalt, address seller, address agent, // address(0) for locked address token, uint256 amount, uint256 buyerProtectionTime, bytes32 termsHash, uint256 version, address expectedEscrow // Safety check ) external returns (address escrow); ``` **Flow:** 1. Calculate salt: `keccak256(userSalt, msg.sender)` 2. Predict escrow address via CREATE2 3. Validate: token whitelisted, amount valid, agent valid 4. Transfer protocol fee to treasury 5. Transfer escrow amount to predicted address 6. Deploy clone 7. Initialize escrow 8. Set `isEscrow[escrow] = true` #### quoteCreateEscrow Preview an escrow creation without executing. ```solidity theme={null} function quoteCreateEscrow( bytes32 userSalt, address seller, address agent, address token, uint256 amount, uint256 buyerProtectionTime ) external view returns ( address predictedAddress, uint256 creationFee, uint256 assignmentFee ); ``` *** ## AgentRegistry ### Storage ```solidity theme={null} struct Agent { bool registered; bool available; uint256 stablecoinStake; uint256 tokenStake; uint256 assignmentFeeBps; uint256 disputeFeeBps; uint256 activeCases; uint256 lastCaseTimestamp; } mapping(address => Agent) public agents; ``` ### Key Functions #### register ```solidity theme={null} function register( uint256 stablecoinAmount, uint256 tokenAmount, uint256 assignmentFeeBps, uint256 disputeFeeBps ) external; ``` #### addStake / withdrawStake ```solidity theme={null} function addStake(uint256 stablecoinAmount, uint256 tokenAmount) external; function withdrawStake(uint256 stablecoinAmount, uint256 tokenAmount) external; ``` #### validateAgentForContract ```solidity theme={null} function validateAgentForContract( address agent, uint256 contractValueWad // 18-decimal normalized ) external view returns (bool); ``` **Checks:** * Agent is registered * Agent is available * Agent's MAV ≥ contract value * Agent has minimum stakes *** ## FeeManager ### Storage ```solidity theme={null} struct TokenConfig { bool whitelisted; uint8 decimals; uint256 creationFeeBps; uint256 minCreationFee; uint256 maxCreationFee; } mapping(address => TokenConfig) public tokenConfigs; ``` ### Key Functions #### quoteCreationFee ```solidity theme={null} function quoteCreationFee( address token, uint256 amount ) external view returns (uint256 fee); ``` **Logic:** ``` rawFee = amount * feeBps / 10000 fee = clamp(rawFee, minFee, maxFee) ``` *** ## EscrowImplementation ### Storage ```solidity theme={null} // Core parties address public buyer; address public seller; address public agent; // Funds address public token; uint256 public amount; // Time parameters uint256 public buyerProtectionTime; uint256 public sellerAcceptDeadline; uint256 public fulfilledAt; // State EscrowState public state; bytes32 public termsHash; // Split negotiation uint256 public proposedBuyerBps; uint256 public proposedSellerBps; address public splitProposer; ``` ### State Enum ```solidity theme={null} enum EscrowState { PENDING, // 0 ACTIVE, // 1 FULFILLED, // 2 RELEASED, // 3 (terminal) REFUNDED, // 4 (terminal) DISPUTED, // 5 AGENT_INVITED, // 6 SPLIT, // 7 (terminal) AGENT_RESOLVED // 8 (terminal) } ``` ### Key Functions #### accept / decline ```solidity theme={null} function accept() external; // Seller only, PENDING -> ACTIVE function decline() external; // Seller only, PENDING -> REFUNDED ``` #### markFulfilled ```solidity theme={null} function markFulfilled() external; // Seller only, ACTIVE -> FULFILLED ``` #### release ```solidity theme={null} function release() external; // Buyer only, -> RELEASED ``` #### sellerRefund ```solidity theme={null} function sellerRefund() external; // Seller only, -> REFUNDED ``` #### openDispute ```solidity theme={null} function openDispute() external; // Buyer only, -> DISPUTED ``` #### inviteAgent ```solidity theme={null} function inviteAgent() external; // Either party, DISPUTED -> AGENT_INVITED ``` #### agentResolve ```solidity theme={null} function agentResolve( uint256 buyerBps, uint256 sellerBps ) external; // Agent only, -> AGENT_RESOLVED ``` #### proposeSplit / approveSplit / executeSplit ```solidity theme={null} function proposeSplit(uint256 buyerBps, uint256 sellerBps) external; function approveSplit() external; function executeSplit() external; ``` *** ## Events ### EscrowFactory Events ```solidity theme={null} event EscrowCreated( address indexed escrow, address indexed buyer, address indexed seller, address agent, address token, uint256 amount, uint256 fee ); ``` ### EscrowImplementation Events ```solidity theme={null} event Accepted(address indexed seller); event Declined(address indexed seller); event Fulfilled(address indexed seller, uint256 timestamp); event Released(address indexed buyer, uint256 amount); event Refunded(address indexed seller, uint256 amount); event DisputeOpened(address indexed buyer); event AgentInvited(address indexed inviter, address agent); event AgentResolved(address agent, uint256 buyerAmount, uint256 sellerAmount); event SplitProposed(address indexed proposer, uint256 buyerBps, uint256 sellerBps); event SplitExecuted(uint256 buyerAmount, uint256 sellerAmount); ``` *** Learn how to integrate → # Locked Escrow (2-of-2) Source: https://docs.zen.land/escrow-types/locked-escrow Satoshi's original escrow design — maximum trustlessness, but with permanent lock risk. **Advanced users only.** Locked escrows have NO dispute resolution. Funds can be locked FOREVER if parties disagree. ## What is a Locked Escrow? A **locked escrow** (also called "2-of-2 escrow") is created with **no agent selected**. This means: * ✅ **Maximum trustlessness** — no third party can touch your funds * ⚠️ **No dispute resolution** — if you disagree, there's no arbiter * 🔒 **Permanent lock risk** — funds can be locked forever if you can't agree This is Satoshi Nakamoto's original escrow design from 2010, based on pure game theory. *** ## How It Works ```mermaid theme={null} graph TD A[Buyer Creates Escrow] --> B[No Agent Selected] B --> C[Seller Accepts] C --> D{Both Agree?} D -->|Yes| E[Release or Refund] D -->|No| F[Propose Split] F --> G{Other Party Accepts?} G -->|Yes| H[Funds Split] G -->|No| I[🔒 Funds Locked Forever] ``` ### Available Actions | Action | Who Can Do It | Result | | ----------------- | ------------- | ---------------------- | | **Release** | Buyer | 100% to seller | | **Refund** | Seller | 100% to buyer | | **Propose Split** | Either | Suggest % distribution | | **Accept Split** | Other party | Execute the split | There is NO unilateral action for the buyer to get funds back. Only the seller can refund. *** ## The Game Theory Locked escrows work because of **mutually assured destruction**: ``` Seller delivers nothing ↓ Buyer refuses to release ↓ Money burns (locked forever) ↓ Seller gains $0 ``` ``` Buyer claims non-delivery ↓ Seller refuses to refund ↓ Money burns (locked forever) ↓ Buyer gains $0 ``` **The key insight:** Cheating has **zero expected value** because the other party can always burn the funds. This incentivizes honest behavior. *** ## When to Use Locked Escrow Trading large amounts with established partners you've worked with before. Business partners, friends, or repeat clients where trust is established. When you don't want any third party to see transaction details. When you philosophically prefer pure code over human arbitration. *** ## When NOT to Use Locked Escrow Avoid locked escrows in these situations: * ❌ **First-time transactions** with strangers * ❌ **Subjective deliverables** (design, writing, etc.) * ❌ **High-value transactions** you can't afford to lose * ❌ **Emotional counterparties** who might act out of spite * ❌ **Complex projects** with room for interpretation *** ## Real Risks to Understand ### Risk 1: Spite Burns Even if you delivered perfectly, a bitter buyer might refuse to release just to hurt you. ``` Seller: "But I delivered exactly what we agreed!" Buyer: "I don't care. I'd rather burn the money." Result: Funds locked forever. ``` ### Risk 2: Genuine Disagreement Good-faith parties can disagree on quality or completeness. ``` Seller: "The website is done." Buyer: "The contact form doesn't work." Seller: "It works fine on my machine." Result: Stalemate. No agent to decide who's right. ``` ### Risk 3: Abandonment Either party disappearing means funds are stuck. ``` Escrow funded → Seller accepts → Seller disappears Result: Buyer can never get funds back. ``` *** ## Stuck in a Locked Escrow? If you're in a locked escrow dispute, your options are: Reach out to the other party. Many deadlocks resolve with conversation. Split the difference. Getting 50% is better than 0%. If they won't respond, you may have to write it off. There is NO DAO escalation, NO support team, and NO way to recover funds from a locked escrow. This is by design. *** ## Creating a Locked Escrow If you understand the risks and want to proceed: Start creating an escrow normally When asked to select an agent, choose "No Agent" You'll see a warning. Confirm you understand the risks. Fund the escrow as normal *** ## Comparison: Standard vs Locked | Feature | Standard Escrow | Locked Escrow | | ----------------------- | ----------------- | --------------------- | | **Agent** | Yes, pre-selected | None | | **Dispute Resolution** | Agent decides | Mutual agreement only | | **Permanent Lock Risk** | No | Yes | | **Third-Party Trust** | Required | Not required | | **Best For** | Most users | Power users, OTC | | **Fees** | Protocol + Agent | Protocol only | *** Standard escrows are recommended for most transactions → # Standard Escrow Source: https://docs.zen.land/escrow-types/standard-escrow The recommended escrow type with professional dispute resolution. ## What is a Standard Escrow? A **standard escrow** is created with a pre-selected agent who can resolve disputes if buyer and seller disagree. Standard escrows offer the best balance of security and flexibility. Even if you trust your counterparty, having an agent as backup is wise. *** ## How It Works ```mermaid theme={null} graph TD A[Buyer Creates Escrow] --> B[Selects Agent] B --> C[Seller Accepts] C --> D{Work Completed?} D -->|Yes| E[Buyer Releases] D -->|Dispute| F[Agent Invited] F --> G[Agent Decides Split] G --> H[Funds Distributed] ``` ### Key Features If you disagree, a qualified agent reviews the case and decides a fair outcome. Agents stake funds to ensure they act fairly. Misconduct = slashing. Agents can only handle escrows up to their Maximum Arbitratable Value (based on stake). If the agent is unresponsive, you can claim timeout and settle mutually. *** ## Choosing a Good Agent When creating an escrow, you'll see a list of available agents. Here's what to look for: ### Reputation Metrics | Metric | What It Means | | --------------------- | ----------------------------------- | | **Total Resolved** | How many disputes they've handled | | **Registration Date** | How long they've been active | | **Availability** | Whether they're accepting new cases | ### Fees Agents charge two types of fees: | Fee Type | When Charged | Typical Range | | ------------------ | ---------------------------------- | ------------- | | **Assignment Fee** | When agent is selected at creation | 0-2% | | **Dispute Fee** | Only if agent resolves a dispute | 1-10% | Lower fees aren't always better. Experienced agents with higher fees may provide better resolution. ### Stake and MAV Agents must stake funds to participate: * **Stablecoin Stake:** Determines their MAV (Maximum Arbitratable Value) * **DAO Token Stake:** Shows alignment with the protocol ``` Example: - Agent stakes $1,000 in USDC - MAV multiplier is 20x - Agent can handle escrows up to $20,000 ``` Your escrow amount must be within the agent's MAV for them to be eligible. *** ## The Dispute Flow If something goes wrong: Signals that there's a problem with the delivery At invite time, the agent's eligibility is re-verified Both parties submit their case Decides what % goes to buyer vs seller Agent fee deducted first, then funds distributed *** ## Benefits of Standard Escrows If one party tries to cheat, the agent provides an impartial resolution. Don't need to negotiate endlessly. Agent decides within days. Funds can never be locked forever — there's always a path to resolution. Good behavior is recorded. Build a track record for future transactions. *** ## When NOT to Use Standard Escrow Consider a [locked escrow](/escrow-types/locked-escrow) instead if: * You have **absolute trust** in your counterparty * You're doing **OTC trades** with established partners * You want **maximum trustlessness** (no third party at all) * You understand and accept the risk of funds being locked forever Learn about locked escrows → # Agent Fees Source: https://docs.zen.land/fees/agent-fees How agents charge for assignment and dispute resolution. ## Agent Fee Types Agents can charge two types of fees: Charged when the agent is assigned to an escrow at creation. Charged only if the agent resolves a dispute. *** ## Assignment Fee Some agents charge an **upfront fee** when selected for an escrow: * **When charged:** At escrow creation * **Paid by:** Buyer (on top of escrow amount + protocol fee) * **Typical range:** 0-2% * **Purpose:** Reserves the agent's capacity Many agents charge 0% assignment fee. Check before selecting! *** ## Dispute Fee When an agent **resolves a dispute**, they earn a dispute fee: * **When charged:** Only when `agentResolve()` is called * **Deducted from:** The escrow funds (before split) * **Typical range:** 1-10% * **Capped at:** 10% maximum (enforced by DAO) ### How Dispute Fees Work ``` Escrow Amount: $1,000 Agent Dispute Fee: 5% Agent Decides: 60% buyer / 40% seller Calculation: 1. Agent fee: $1,000 × 5% = $50 2. Remaining: $1,000 - $50 = $950 3. Buyer: $950 × 60% = $570 4. Seller: $950 × 40% = $380 Distribution: - Agent: $50 - Buyer: $570 - Seller: $380 - Total: $1,000 ✓ ``` *** ## No Agent Fee If... If the buyer releases funds without a dispute, no agent fee is charged. Seller-initiated refunds don't involve the agent. If parties agree on a split without agent intervention, no fee is charged. If the agent doesn't respond within 7 days and you claim timeout, no fee is charged. *** ## Fee Bounds The DAO sets minimum and maximum fee limits: | Parameter | Value | Purpose | | ----------- | -------------- | ----------------------------------------------- | | **Min Fee** | 0.1% (10 bps) | Prevents "free" agents with no skin in the game | | **Max Fee** | 10% (1000 bps) | Protects users from excessive charges | Agents must set their fees within these bounds when registering. *** ## Choosing an Agent by Fees When selecting an agent, consider: **Pros:** Cheaper disputes **Cons:** May indicate less experience **Pros:** May signal quality/expertise **Cons:** More expensive if disputes occur The best strategy: choose based on reputation first, fees second. A skilled agent at 5% beats an inexperienced one at 1%. *** ## Viewing Agent Fees When creating an escrow, you can see each agent's fees: 1. Click on an agent's profile 2. View their **Assignment Fee** and **Dispute Fee** 3. Consider their reputation alongside fees 4. Select the best fit for your needs *** ## FAQs Agents can update their fees anytime, but changes only affect new escrows. Your escrow uses the fees at creation time. The agent fee is still deducted first. So "100% to buyer" means the buyer gets (100% - agent fee). Yes. Protocol fee (1%) is paid at creation. Agent fees (if any) are paid from the escrowed funds. # Fee Structure Source: https://docs.zen.land/fees/fee-structure Simple, transparent pricing with a $50 maximum cap. ## How Fees Work Zenland charges a simple **1% protocol fee** on every escrow created. One percent of the escrow amount Never pay less than 50 cents Never pay more than \$50 *** ## Fee Calculation Examples | Escrow Amount | 1% Would Be | Min/Max Applied | **You Pay** | | ------------- | ----------- | --------------- | ----------- | | \$25 | \$0.25 | Below minimum | **\$0.50** | | \$100 | \$1.00 | Within range | **\$1.00** | | \$500 | \$5.00 | Within range | **\$5.00** | | \$2,500 | \$25.00 | Within range | **\$25.00** | | \$10,000 | \$100.00 | Above maximum | **\$50.00** | | \$1,000,000 | \$10,000.00 | Above maximum | **\$50.00** | The \$50 cap makes Zenland extremely cost-effective for high-value transactions! *** ## Who Pays the Fee? The **buyer** pays the protocol fee when creating the escrow. ``` Escrow Amount: $1,000 Protocol Fee: $10 (1%) ━━━━━━━━━━━━━━━━━━━━ Total Paid by Buyer: $1,010 Seller Receives (on release): $1,000 ``` The fee is charged **on top** of the escrow amount. Sellers always receive the full agreed amount (minus any agent fees in disputes). *** ## When is the Fee Charged? The fee is charged **once**, at escrow creation: * ✅ Charged when escrow is created and funded * ❌ NOT charged on release, refund, or split * ❌ NOT charged on dispute resolution This is intentionally different from platforms that charge on both ends. You know your total cost upfront. *** ## Locked Escrows Locked escrows (no agent) pay the **same fee** as standard escrows. Why? Even without an agent, you're using: * Zenland's audited smart contracts * Deterministic addresses for PDF verification * Event indexing and UI infrastructure * Gas-optimized minimal proxies *** ## Fee Breakdown by Token Fees are calculated per-token to handle different decimal places: | Token | Fee % | Min Fee | Max Fee | | ----- | ------------ | ----------------------------- | ----------------- | | USDC | 1% (100 bps) | 500,000 (6 decimals) = \$0.50 | 50,000,000 = \$50 | | USDT | 1% (100 bps) | 500,000 (6 decimals) = \$0.50 | 50,000,000 = \$50 | Additional tokens may be added through DAO governance with their own fee configurations. *** ## Where Do Fees Go? All protocol fees are sent directly to the **DAO Treasury**: ``` Buyer creates escrow ↓ Fee transferred to Treasury (in same transaction) ↓ DAO governs treasury spending ``` The treasury funds: * Protocol development * Security audits * Community initiatives * Agent incentives *** ## Fee Changes Fees are controlled by the DAO: * **Current fees** are locked in when you create an escrow * **Future changes** only affect new escrows * **Your escrow** is never affected by fee updates after creation Learn how fees are governed → # Gas Fees Source: https://docs.zen.land/fees/gas-fees Understanding Ethereum gas costs and the zero-gas NYKNYC option. ## What Are Gas Fees? Gas fees are payments to Ethereum validators for processing your transactions: * **Every action** on Ethereum costs gas * **Gas prices fluctuate** based on network demand * **You pay in ETH** (even for USDC transactions) *** ## Zenland Gas Costs Typical gas costs for Zenland actions: | Action | Gas Used | Cost @ 20 gwei | Cost @ 100 gwei | | ------------- | --------- | -------------- | --------------- | | Create Escrow | \~200,000 | \~\$1.50 | \~\$7.50 | | Accept Escrow | \~100,000 | \~\$0.75 | \~\$3.75 | | Release Funds | \~80,000 | \~\$0.60 | \~\$3.00 | | Open Dispute | \~60,000 | \~\$0.45 | \~\$2.25 | | Agent Resolve | \~120,000 | \~\$0.90 | \~\$4.50 | Costs vary with ETH price and network congestion. Check [etherscan.io/gastracker](https://etherscan.io/gastracker) for current prices. *** ## Zero Gas with NYKNYC **Zenland sponsors all gas fees** when you use the NYKNYC smart wallet. ### What's Free with NYKNYC? Create, accept, release, refund — all free Open disputes, invite agents — all free Register as an agent — free Resolve disputes as an agent — free ### How It Works NYKNYC uses **ERC-4337 Account Abstraction**: ``` Traditional Wallet: You → Pay Gas → Transaction NYKNYC: You → Transaction → Zenland Pays Gas ``` 1. You sign the transaction 2. Zenland's paymaster covers the gas 3. You pay nothing in ETH *** ## Using Standard Wallets If you use MetaMask, Coinbase Wallet, or other wallets: ### You'll Need ETH Keep ETH in your wallet for gas. Recommended: * **Small transactions:** 0.01 ETH (\$15-30) * **Multiple transactions:** 0.05 ETH (\$80-150) * **Active trading:** 0.1+ ETH ### Tips to Save on Gas Gas is cheaper at night (US time) and on weekends. Avoid peak hours. Most wallets let you set a max gas price. Be patient for off-peak execution. Using permit (EIP-2612) for tokens can save one transaction. *** ## Gas vs Protocol Fees Don't confuse gas fees with protocol fees: | Type | What It Is | Who Gets It | | ---------------- | ------------------------------ | -------------------- | | **Gas Fee** | Payment to Ethereum validators | Ethereum network | | **Protocol Fee** | 1% of escrow amount | Zenland DAO Treasury | Both are separate costs. Protocol fee is fixed (1%), gas varies with network. *** ## Which Wallet Should You Use? * You want zero gas costs * You're new to crypto * You don't have ETH * You want the simplest experience * You already have a wallet with ETH * You prefer full self-custody * You want to use hardware wallets * You're comfortable with gas management *** Setup takes 2 minutes → # How It Works Source: https://docs.zen.land/getting-started/how-it-works The complete escrow lifecycle from creation to settlement. ## The Escrow Lifecycle Every Zenland escrow follows a clear lifecycle. Here's what happens at each stage: ```mermaid theme={null} graph LR A[Create] --> B[Pending] B --> C[Active] C --> D[Fulfilled] D --> E[Released] C --> F[Disputed] F --> G[Resolved] ``` *** ## Step 1: Create the Escrow Buyer and seller discuss and agree on the work, price, and timeline off-chain (chat, email, etc.) The Zenland app generates a PDF containing all terms. This gets hashed and stored on-chain. Select a professional dispute resolver, or go "locked" for pure 2-of-2 escrow. Buyer deposits funds + pays the 1% protocol fee. Funds are now locked in the smart contract. The escrow address is **deterministic** — it's known before you even create it! This address is embedded in your PDF for verification. *** ## Step 2: Seller Accepts Once the escrow is funded, the seller must **accept** the contract to activate it: * **Accept** — Seller agrees to the terms, escrow becomes `ACTIVE` * **Decline** — Seller rejects, buyer is refunded immediately * **No Response** — After the acceptance window, buyer can cancel and get refunded If you're a seller, always review the terms carefully before accepting. Once active, you're committed to delivering. *** ## Step 3: Do the Work With the escrow active: 1. **Seller** delivers the goods or completes the service 2. **Seller** marks the escrow as `Fulfilled` when done 3. **Buyer** reviews the delivery Communication is key! Use your preferred channel (Telegram, email, etc.) to stay in sync with the other party. *** ## Step 4: Settlement The escrow can settle in several ways: ### Happy Path: Release The buyer is satisfied and releases 100% of funds to the seller. Instant, no fees beyond the creation fee. ### Seller-Initiated Refund The seller can **always** refund 100% to the buyer at any time. No approval needed. Use this for "no questions asked" returns. ### Auto-Release (Buyer Protection Expiry) If the buyer doesn't respond after the protection period ends (and seller marked fulfilled), the seller can claim the funds. ### Mutual Split Both parties agree to divide the funds. Propose a split (e.g., 60/40), the other party approves, funds are distributed. *** ## When Things Go Wrong: Disputes If there's a disagreement: The buyer opens a dispute, pausing normal settlement. Either party invites the pre-selected agent to review the case. The agent reviews evidence and decides the split. Agent fee is deducted. See the full dispute resolution process → *** ## Summary: State Transitions | State | Description | Next States | | ----------------- | ---------------------------------- | --------------------------------------- | | **Pending** | Escrow created, waiting for seller | Active, Refunded | | **Active** | Seller accepted, work in progress | Fulfilled, Disputed, Released, Refunded | | **Fulfilled** | Seller marked as complete | Released, Disputed | | **Disputed** | Buyer raised an issue | Agent Invited, Split, Refunded | | **Agent Invited** | Waiting for agent decision | Resolved, Split, Refunded | | **Released** | Funds sent to seller ✓ | *Terminal* | | **Refunded** | Funds returned to buyer ✓ | *Terminal* | | **Split** | Funds divided between parties ✓ | *Terminal* | # Supported Networks Source: https://docs.zen.land/getting-started/supported-networks Where Zenland is deployed and how to connect. ## Ethereum Mainnet **Production Network** — Real assets, real transactions Zenland is deployed on **Ethereum mainnet**, the most secure and decentralized blockchain network. * **Battle-tested security** since 2015 * **Largest DeFi ecosystem** with deep liquidity * **Supported tokens:** USDC, USDT ### Contract Addresses (Mainnet) | Contract | Address | | ------------- | -------------------------------------------- | | EscrowFactory | `0x0000000000000000000000000000000000000000` | | AgentRegistry | `0x0000000000000000000000000000000000000000` | | FeeManager | `0x0000000000000000000000000000000000000000` | Contract addresses will be updated after mainnet deployment. *** ## Sepolia Testnet **Test Network** — Practice with fake assets Use Sepolia to test Zenland without risking real funds: * **Free test tokens** available from faucets * **Same functionality** as mainnet * **Perfect for developers** building integrations ### Contract Addresses (Sepolia) | Contract | Address | | ------------- | -------------------------------------------- | | EscrowFactory | `0x0000000000000000000000000000000000000000` | | AgentRegistry | `0x0000000000000000000000000000000000000000` | | FeeManager | `0x0000000000000000000000000000000000000000` | ### Getting Sepolia Test Tokens 1. Get Sepolia ETH from a [faucet](https://sepoliafaucet.com) 2. Get test USDC/USDT from the Zenland app (we provide test tokens) *** ## Supported Tokens Zenland V1 supports stablecoin escrows: | Token | Symbol | Decimals | Status | | -------- | ------ | -------- | ----------- | | USD Coin | USDC | 6 | ✅ Supported | | Tether | USDT | 6 | ✅ Supported | More tokens can be added through DAO governance. Vote on proposals to expand token support! *** ## Network Configuration Add Zenland-supported networks to your wallet: ### Ethereum Mainnet ``` Network Name: Ethereum Mainnet RPC URL: https://eth.llamarpc.com Chain ID: 1 Currency: ETH Block Explorer: https://etherscan.io ``` ### Sepolia Testnet ``` Network Name: Sepolia RPC URL: https://rpc.sepolia.org Chain ID: 11155111 Currency: SepoliaETH Block Explorer: https://sepolia.etherscan.io ``` Most wallets (MetaMask, Coinbase Wallet, etc.) have Ethereum Mainnet pre-configured. # Connecting Your Wallet Source: https://docs.zen.land/getting-started/wallets How to connect your wallet and get started with Zenland. ## Supported Wallets Zenland supports all popular Web3 wallets. Connect with whatever you're comfortable using: The most popular browser wallet Easy for Coinbase users Connect any mobile wallet *** ## Recommended: NYKNYC Wallet The smart wallet built for Zenland **NYKNYC** (Not Your Keys, Not Your... Crypto? 😉) is our recommended wallet powered by **ERC-4337 account abstraction**. ### Why NYKNYC? Zenland sponsors all your transactions. Create escrows, resolve disputes — all free. You don't need to hold ETH for gas. Just have USDC/USDT for your escrow. Agents pay nothing for registration or dispute resolution. Modern ERC-4337 technology with enhanced security features. ### Getting NYKNYC Go to [zen.land/app](https://zen.land/app) Select "NYKNYC" from the wallet options Follow the prompts to set up your smart wallet Transfer USDC or USDT to your NYKNYC address *** ## Using Other Wallets If you prefer your existing wallet, that's totally fine! Here's what to know: ### Gas Requirements With standard wallets, you'll need ETH for gas fees: | Action | Estimated Gas Cost | | ------------- | ------------------ | | Create Escrow | \~200,000 gas | | Release Funds | \~80,000 gas | | Open Dispute | \~60,000 gas | Gas costs vary with network congestion. Check [etherscan.io/gastracker](https://etherscan.io/gastracker) for current prices. ### Connecting Your Wallet Find the "Connect Wallet" button in the Zenland app Choose MetaMask, Coinbase Wallet, or WalletConnect Confirm the connection in your wallet Make sure you're on Ethereum Mainnet (or Sepolia for testing) *** ## Security Best Practices Your wallet is your identity on Zenland. Keep it safe! Your 12/24 word recovery phrase gives full access to your wallet. Never share it with anyone, including "support" staff. Always check the contract address and amounts before signing transactions. For high-value escrows, consider using a Ledger or Trezor for extra security. Always access Zenland from [zen.land](https://zen.land) to avoid phishing sites. # What is Zenland? Source: https://docs.zen.land/getting-started/what-is-zenland A trustless, on-chain escrow platform where smart contracts protect both buyers and sellers. ## The Problem with Traditional Escrow When two strangers transact online, trust is the biggest barrier: * **Buyers** worry about sending money and never receiving the goods * **Sellers** worry about delivering work and never getting paid * **Traditional escrow services** charge high fees and require you to trust a company **Zenland solves this** by putting funds in a smart contract that neither party controls — until both agree on the outcome. *** ## How Zenland Works Escrow Flow Diagram At its core, Zenland is simple: 1. **Funds are locked** in a smart contract when the escrow is created 2. **Both parties work** according to their agreement 3. **Funds are released** when the work is complete — or a dispute is resolved The magic is that **no single party can steal the funds**. The smart contract enforces the rules automatically. *** ## Key Features All escrow logic lives on Ethereum. Every transaction is transparent and verifiable by anyone. Zenland never holds your funds. They're secured in smart contracts that only respond to the rules. Professional agents can intervene when parties disagree, providing fair and efficient resolution. The protocol is owned by its community. Token holders vote on fees, upgrades, and parameters. *** ## Who Uses Zenland? Zenland is perfect for: * **Freelancers & Clients** — Secure milestone-based payments * **NFT/Crypto OTC Trades** — Safe peer-to-peer exchanges * **Service Providers** — Get paid after delivering quality work * **High-Value Transactions** — When you can't afford to trust blindly *** ## What Makes Us Different? | Feature | Traditional Escrow | Zenland | | ---------------- | ---------------------- | ----------------------------- | | **Trust Model** | Trust the company | Trust the code | | **Fees** | 3-10% + hidden costs | 1% (max \$50) | | **Availability** | Business hours | 24/7/365 | | **Transparency** | Opaque | Fully on-chain | | **Control** | Company controls funds | Smart contract controls funds | *** Learn how escrows work step by step → # DAO Token Source: https://docs.zen.land/governance/dao-token The Zenland DAO governance token. ## Overview The Zenland DAO token is the governance token of the protocol. ZEN \* Ethereum ERC-20 + Votes * Token symbol is illustrative. Confirm official symbol before launch. *** ## Token Utility The token serves three purposes: Vote on proposals to control protocol parameters, treasury, and upgrades. Agents must stake DAO tokens alongside stablecoins to participate. Token holdings signal commitment to the Zenland ecosystem. *** ## Voting Power ### Delegation Required Your tokens only grant voting power if **delegated**: ```javascript theme={null} // Delegate to yourself token.delegate(yourAddress); // Or delegate to someone else token.delegate(delegateAddress); ``` Undelegated tokens have zero voting power! Always delegate after acquiring tokens. ### Snapshot Voting When a proposal is created, a **snapshot block** is recorded. Your voting power equals your balance at that block. This prevents: * Flash loan attacks * Last-minute token purchases to influence votes *** ## Token Distribution Distribution details will be announced before token launch. ### Typical DAO Distribution | Allocation | Purpose | | ---------- | ------------------------------ | | Community | Airdrop, rewards, grants | | Team | Long-term alignment (vested) | | Treasury | Future development, incentives | | Ecosystem | Partnerships, integrations | *** ## Getting Tokens Tokens can be acquired through: Earn tokens by using Zenland (details TBA) Grants for valuable contributions Potential rewards for active agents DEX trading (after token launch) *** ## Contract Address Token contract address will be published after deployment. | Network | Address | | ---------------- | -------------------------------------------- | | Ethereum Mainnet | `0x0000000000000000000000000000000000000000` | | Sepolia Testnet | `0x0000000000000000000000000000000000000000` | *** Learn about proposals → # Proposals Source: https://docs.zen.land/governance/proposals How to create and vote on governance proposals. ## Proposal Lifecycle Share your idea on the DAO forum. Gather feedback and refine. If you have enough tokens, submit on-chain. 7 days for token holders to vote. If passed, 2-day delay before execution. Changes are applied automatically. *** ## Proposal Thresholds | Action | Requirement | | --------------- | ------------------ | | Create Proposal | 1% of total supply | | Quorum to Pass | 4% of total supply | | Voting Period | 7 days | | Timelock Delay | 2 days | Thresholds may be adjusted via governance. *** ## How to Vote ### Using the DAO Interface Connect with tokens delegated to yourself Browse proposals in the governance section Choose For, Against, or Abstain Sign the vote transaction ### Vote Options | Option | Effect | | ----------- | -------------------------------- | | **For** | Supports the proposal | | **Against** | Opposes the proposal | | **Abstain** | Counts toward quorum but neutral | *** ## What Makes a Good Proposal? What issue are you solving? Exact changes proposed Expected effects on the protocol What could go wrong? ### Example Proposal ```markdown theme={null} ## Title: Reduce Protocol Fee to 0.75% ### Summary Reduce the protocol fee from 1% to 0.75% to increase competitiveness. ### Motivation Competitor platforms charge 0.5%. Reducing fees will attract more users. ### Specification - Call `FeeManager.setCreationFeeBps(USDC, 75)` - Call `FeeManager.setCreationFeeBps(USDT, 75)` ### Impact - Treasury revenue: -25% per transaction - Expected volume increase: +50% - Net effect: +12.5% total revenue ### Risks - Revenue decrease if volume doesn't increase - Perception of instability from frequent changes ``` *** ## Creating a Proposal Requirements: * Own ≥1% of token supply (or have delegation) * Tokens delegated to yourself Define target contracts, function calls, and parameters Use the DAO interface or call Governor directly Post in forum and community channels Explain why the community should support it *** ## After Voting ### If Passed 1. **Queued in Timelock** — 2-day waiting period 2. **Community Can React** — Emergency pause if malicious 3. **Executed** — Changes go live ### If Failed 1. **No Changes** — Protocol continues as is 2. **Iterate** — Refine proposal based on feedback 3. **Re-propose** — Submit improved version *** Learn about the DAO treasury → # Treasury Source: https://docs.zen.land/governance/treasury How the DAO treasury is funded and managed. ## What is the Treasury? The **Zenland DAO Treasury** is a smart contract that: * Receives all protocol fees * Holds DAO assets * Disperses funds via governance Every protocol fee goes directly to the treasury. No company takes a cut. *** ## How It's Funded ### Protocol Fees | Source | Flow | | ------------------------ | ---------- | | Escrow creation fee (1%) | → Treasury | | Agent assignment fees | → Treasury | ### Other Sources * Token sale proceeds (if any) * Grants and partnerships * Yield from assets (if deployed) *** ## Treasury Management ### Controlled by DAO Only governance proposals can move treasury funds: 1. **Discussion** — Community agrees on use of funds 2. **Proposal** — Formal on-chain request 3. **Vote** — Token holders approve/reject 4. **Timelock** — 2-day safety delay 5. **Execution** — Funds transfer No individual can access treasury funds. Only passed proposals can trigger transfers. ### Timelock Contract The treasury is actually a **Timelock** contract: * Acts as the **owner** of protocol contracts * Executes proposals after delay * Can be paused in emergencies *** ## Treasury Uses Fund developers to build new features, fix bugs, improve UX. Pay for professional security reviews before upgrades. Support community projects, integrations, educational content. Reward security researchers who find vulnerabilities. Fund awareness campaigns and growth initiatives. Infrastructure, legal, compliance costs. *** ## Transparency Everything is on-chain: | Data | Where | | ----------------- | ----------------- | | Treasury balance | Etherscan | | All transactions | Block explorer | | Pending proposals | Governor contract | Check treasury balance on Etherscan → *** ## Requesting Funds Want to request funds for a project? Describe what you want to do and how much you need Gather community feedback Create on-chain proposal (or ask a delegate to help) Explain why your project benefits Zenland ### Good Grant Proposals Include What exactly will you produce? How will funds be spent? When will milestones be delivered? What have you built before? # Zenland DAO Source: https://docs.zen.land/governance/zenland-dao How Zenland is governed by its community. ## Community Owned Zenland is a **Decentralized Autonomous Organization (DAO)**. This means: No company controls Zenland. The protocol is governed by token holders. All proposals and votes happen on-chain, visible to everyone. *** ## How Governance Works ```mermaid theme={null} graph LR A[Idea] --> B[Forum Discussion] B --> C[Proposal Created] C --> D[Voting Period] D --> E{Pass?} E -->|Yes| F[Timelock Queue] F --> G[Execution] E -->|No| H[Rejected] ``` ### Governance Flow 1. **Discussion:** Ideas are discussed in the DAO forum 2. **Proposal:** Token holder creates on-chain proposal 3. **Voting:** 7-day voting period 4. **Timelock:** 2-day delay before execution (safety period) 5. **Execution:** Changes are applied automatically *** ## What Can the DAO Control? ### Protocol Parameters | Parameter | Example | | ------------------ | --------------------------- | | Protocol fee | Change from 1% to 0.75% | | Fee min/max | Adjust $0.50 min or $50 max | | Token whitelist | Add new supported tokens | | Agent requirements | Modify minimum stakes | ### Treasury | Action | Example | | ------------------ | --------------------------- | | Fund development | Grant to build features | | Security audits | Pay for professional review | | Community programs | Rewards, incentives, events | ### Agent Oversight | Action | Example | | --------------------- | -------------------------- | | Slash bad actors | Penalize proven misconduct | | Update MAV multiplier | Change 20x to 15x | | Fee bounds | Adjust agent fee limits | ### Upgrades | Action | Example | | ---------------------- | ------------------------ | | Factory upgrade | Deploy improved factory | | Implementation upgrade | New escrow features | | New contracts | Add new protocol modules | *** ## Key Roles Anyone holding Zenland DAO tokens can vote on proposals proportional to their holdings. Token holders can delegate their voting power to trusted community members. Anyone with enough tokens (proposal threshold) can create on-chain proposals. The timelock contract executes passed proposals after the delay period. *** ## Voting Power Your voting power = your token balance at the snapshot block. Remember to delegate your tokens to yourself or someone else to activate voting power! ``` Self-delegate: You vote directly Delegate to X: X votes on your behalf ``` *** ## Safety Mechanisms 2-day delay between vote passing and execution. Gives time to react. Minimum participation required for votes to be valid. 7 days to vote ensures broad participation. Minimum tokens needed to create proposals prevents spam. *** ## Get Involved Acquire Zenland DAO tokens Delegate to yourself to activate voting power Participate in governance discussions Cast your vote on active proposals Learn about the token → # Welcome to Zenland Source: https://docs.zen.land/index Trustless escrow for the decentralized age. Secure your transactions with on-chain smart contracts — no intermediaries required. Zenland Hero ## Secure. Trustless. Decentralized. Zenland is a **peer-to-peer escrow platform** built on Ethereum. Whether you're buying, selling, or resolving disputes — everything happens on-chain, transparently and securely. Simple pricing with a **\$50 max cap**. No hidden costs. All escrow logic lives on the blockchain. Fully verifiable. No business hours. Smart contracts work around the clock. *** ## Quick Start Learn how to safely purchase goods or services using Zenland escrow. Get paid securely while protecting your work with smart contracts. Become a dispute resolver and earn fees for your arbitration services. Integrate Zenland into your platform or build on top of our contracts. *** ## How It Works Creating an escrow takes just 3 simple steps: Define your terms, choose an agent (optional), and deposit funds into the smart contract. Complete the work or deliver the product. Both parties can track the escrow status. Once satisfied, the buyer releases funds instantly. Or resolve disputes with an agent. Dive deeper into the escrow lifecycle *** ## Why Zenland? Funds are held by smart contracts, not a company. No one — not even Zenland — can access your funds without your approval. The protocol is owned and managed by the Zenland DAO. Token holders vote on fees, parameters, and upgrades. When things go wrong, professional agents step in to resolve disputes fairly. Or use our locked escrow for pure 2-of-2 game theory. Just 1% per transaction, capped at \$50 maximum. No monthly subscriptions, no hidden costs. *** ## Supported Networks Production-ready for real transactions. Battle-tested security since 2015. Test your integrations with fake ETH before going live. *** ## Join Our Community Join our community chat for support and discussions. Participate in governance and shape the future of Zenland. # Community Source: https://docs.zen.land/resources/community Join the Zenland community and get involved. ## Official Channels **Join the Chat** Real-time discussions, announcements, and community support. **Join Discord** Community hub for discussions, support, and updates. **DAO Forum** Governance discussions, proposals, and long-form content. *** ## Get Help ### For Users Most questions are answered in this documentation. Our [FAQ](/resources/faq) covers common questions. Community members and team are active daily. ### For Developers * **Technical Docs:** [Developer Documentation](/developers/architecture) * **GitHub:** Coming soon * **API Reference:** [Smart Contract Reference](/developers/api-reference) ### For Agents * **Onboarding Guide:** [Becoming an Agent](/agents/becoming-an-agent) * **Best Practices:** Discuss in the forum *** ## Participate in Governance The Zenland DAO controls the protocol. Here's how to get involved: Acquire Zenland DAO tokens through participation or trading. Discuss proposals and ideas before they go on-chain. Use your tokens to vote on active proposals. If you hold enough tokens, create your own proposals. Learn about governance → *** ## Stay Updated ### Announcements * Major updates are posted in Telegram * Protocol changes are announced via DAO proposals ### Social Media * Twitter/X: Coming soon * Discord: [Join Discord](https://discord.gg/tMeUMvt6e3) *** ## Report Issues **[security@zen.land](mailto:security@zen.land)** Report vulnerabilities privately. Do not disclose publicly. **Via Telegram or Forum** Non-security bugs can be reported in community channels. *** ## Values Zenland is built on: * 🔓 **Openness** — Open source code, transparent governance * 🤝 **Fairness** — Equal treatment, neutral dispute resolution * 💪 **Decentralization** — No single point of control * 🛡️ **Security** — User funds are sacrosanct # Contract Addresses Source: https://docs.zen.land/resources/contract-addresses Deployed contract addresses on all networks. ## Ethereum Mainnet | Contract | Address | Etherscan | | ------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- | | **EscrowFactory** | `0xba2c6322fd59e2703a28d82db572950297600129` | [View](https://etherscan.io/address/0xba2c6322fd59e2703a28d82db572950297600129) | | **AgentRegistry** | `0x3406c744958b182d6edd2615ff9e53f0fbc60802` | [View](https://etherscan.io/address/0x3406c744958b182d6edd2615ff9e53f0fbc60802) | | **FeeManager** | `0x14f582bd5ddbc3e8416b9d3a9e5f0d3b6ce4206f` | [View](https://etherscan.io/address/0x14f582bd5ddbc3e8416b9d3a9e5f0d3b6ce4206f) | | **EscrowImplementation** | `0xcd982ee65c573aa45a4a41c57b3f60b68be3d9aa` | [View](https://etherscan.io/address/0xcd982ee65c573aa45a4a41c57b3f60b68be3d9aa) | ### Supported Tokens (Mainnet) | Token | Address | | ----- | -------------------------------------------- | | USDC | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | | USDT | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | *** ## Sepolia Testnet | Contract | Address | Etherscan | | ------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------- | | **EscrowFactory** | `0x9f5b706288ce48ae26a161664cd6b15b9c9ebc5e` | [View](https://sepolia.etherscan.io/address/0x9f5b706288ce48ae26a161664cd6b15b9c9ebc5e) | | **AgentRegistry** | `0x50cdb07a74a1898308eb2331940dd6b9263cce56` | [View](https://sepolia.etherscan.io/address/0x50cdb07a74a1898308eb2331940dd6b9263cce56) | | **FeeManager** | `0x412c2dcdcd4d1de95c37246d0fb54f1a0b9a1f2f` | [View](https://sepolia.etherscan.io/address/0x412c2dcdcd4d1de95c37246d0fb54f1a0b9a1f2f) | | **EscrowImplementation** | `0xa28bb288425a8b82523a064a8fad7337a550a9d1` | [View](https://sepolia.etherscan.io/address/0xa28bb288425a8b82523a064a8fad7337a550a9d1) | ### Test Tokens (Sepolia) | Token | Address | | --------- | -------------------------------------------- | | Test USDC | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` | | Test USDT | `0x7169D38820dfd117C3FA1f22a697dBA58d90BA06` | Need test tokens? Visit [faucet.daoforum.org](https://faucet.daoforum.org) to get test USDC and USDT for Sepolia. *** ## DAO Contracts | Contract | Network | Address | | --------------------------- | ------- | -------------------------------------------- | | **DAO Token** | Mainnet | `0xa6be5ae3bc634cf44439845365a01c2cd705f32d` | | **DAO Token** | Sepolia | `0xe4b758C752DD784FFA1f3D402e4401F4dD52F1ee` | | **DAO Timelock (Treasury)** | Mainnet | `0xA9790aC657BD38C8Ef2568c1642b02d2B96F20dD` | | **DAO Timelock (Treasury)** | Sepolia | `0xFEa9A7879118BD78247b40C6301B29043E4E8051` | *** ## Verifying Contracts All contracts are verified on Etherscan: 1. Click the Etherscan link above 2. Go to "Contract" tab 3. Click "Read Contract" or "Write Contract" 4. View source code and ABI *** ## NPM Package For developers, contract ABIs are available via npm: ```bash theme={null} npm install @zenland/contracts ``` ```javascript theme={null} import { EscrowFactory__factory } from '@zenland/contracts'; ``` Learn how to integrate → # FAQ Source: https://docs.zen.land/resources/faq Frequently asked questions about Zenland. ## General Questions Zenland is a decentralized escrow platform built on Ethereum. It allows two parties to transact safely using smart contracts instead of trusting a company. Yes. Funds are held in smart contracts, not by Zenland. The code is audited and open source. No one can access your funds without following the escrow rules. Zenland is deployed on **Ethereum mainnet** and **Sepolia testnet**. More chains may be added through DAO governance. Currently USDC and USDT. More tokens can be added via DAO proposals. *** ## Fees & Costs **1% of the escrow amount**, with a minimum of $0.50 and maximum of $50. Plus Ethereum gas fees (or free with NYKNYC wallet). The buyer pays the protocol fee when creating the escrow. The seller receives the full escrow amount. No. The 1% protocol fee is the only cost. Agent fees (if disputes occur) are transparent and shown upfront. Yes! Use the NYKNYC smart wallet. Zenland sponsors all gas fees for NYKNYC users. *** ## Using Escrows About 15-30 seconds once you submit the transaction (one Ethereum block confirmation). Depends on the state: * **Pending:** Yes — ask the seller to decline, or cancel yourself after the 1-hour acceptance window expires * **Active:** No unilateral cancel, but the seller can refund or you can negotiate a split See the full guide: [Cancelling an Escrow](/user-guides/cancelling-escrow) If they never accepted the escrow, you can cancel after the acceptance window. If they accepted and marked fulfilled, you can dispute or wait for protection to expire. Mark the escrow as fulfilled. After the protection period expires, you can claim the funds. *** ## Disputes The buyer opens a dispute → either party invites the agent → agent reviews and decides the split → funds are distributed. Typically 1-3 days once an agent is invited. Maximum 7 days before timeout can be claimed. After 7 days, either party can claim timeout. The escrow returns to disputed state with no agent, where you'll need to settle mutually. Agent decisions are final for that escrow. You can report misconduct to the DAO for future action against the agent. *** ## Agents [Register as an agent](/agents/becoming-an-agent) by staking stablecoins and DAO tokens. You'll need to meet minimum requirements. You set your own fees (within DAO limits). Earnings depend on the number of disputes you resolve. The DAO can slash their stake as punishment. Repeated misconduct leads to larger slashes. *** ## Technical Yes. Smart contracts are verified on Etherscan and available on GitHub. Yes! See our [developer documentation](/developers/integration-guide). An escrow with no agent. Funds can only move if both parties agree. See [Locked Escrow](/escrow-types/locked-escrow). *** ## Didn't find your answer? Join our Telegram for help # Glossary Source: https://docs.zen.land/resources/glossary Key terms and definitions used in Zenland. ## A ### Agent A professional dispute resolver who reviews cases and decides how to split escrowed funds. Agents stake funds to participate and earn fees for resolutions. ### Assignment Fee An optional upfront fee charged by an agent when they are selected for an escrow. *** ## B ### BPS (Basis Points) A unit for measuring percentages. 100 bps = 1%. Used for fee calculations. ### Buyer The party who creates and funds the escrow. Typically the one paying for goods or services. ### Buyer Protection Time The period after a seller marks as fulfilled during which the buyer can review before the seller can claim funds. *** ## D ### DAO (Decentralized Autonomous Organization) The community governance structure that owns and controls Zenland. Token holders vote on proposals. ### Dispute A formal disagreement raised by the buyer, indicating an issue with the delivery. ### Dispute Fee A fee charged by an agent only when they resolve a dispute. *** ## E ### EIP-1167 (Minimal Proxy) A standard for deploying lightweight clone contracts. Zenland uses this for gas-efficient escrow creation. ### Escrow A smart contract that holds funds until both parties agree on the outcome. ### ERC-4337 (Account Abstraction) A standard for smart contract wallets. Powers NYKNYC's gasless transactions. *** ## F ### Factory (EscrowFactory) The main contract that creates new escrow instances. All escrows are deployed through the factory. ### Fulfilled An escrow state indicating the seller has marked the work as complete. *** ## G ### Gas The fee paid to Ethereum validators to process transactions. *** ## L ### Locked Escrow An escrow created without an agent. Only mutual agreement (or seller refund) can move funds. Based on Satoshi's 2-of-2 escrow design. *** ## M ### MAV (Maximum Arbitratable Value) The maximum escrow value an agent can handle, based on their stake. Calculated as stake × multiplier. ### Minimal Proxy See EIP-1167. *** ## N ### NYKNYC Zenland's recommended smart wallet. "Not Your Keys, Not Your... Crypto?" Uses account abstraction for gasless transactions. *** ## P ### Pending An escrow state where the seller hasn't yet accepted the terms. ### Permit (EIP-2612) A gasless token approval standard. Allows approving + transferring in one transaction. ### Protocol Fee The 1% fee charged by Zenland on escrow creation. *** ## R ### Release The action of sending escrowed funds to the seller, typically when the buyer is satisfied. ### Refund Returning escrowed funds to the buyer. Sellers can do this unilaterally anytime. *** ## S ### Seller The party receiving payment in exchange for goods or services. ### Split A mutual agreement to divide escrowed funds between buyer and seller, often used to settle disputes. ### Stake Funds locked by agents as collateral. Determines their MAV and provides economic security. *** ## T ### Terminal State A final escrow state (Released, Refunded, Split, Agent Resolved) from which no further actions are possible. ### Timelock A smart contract that delays execution of DAO proposals, giving the community time to react. ### Treasury The DAO-controlled wallet that receives protocol fees. *** ## W ### WAD An 18-decimal fixed-point number format used for internal calculations. Normalizes tokens with different decimals. ### Whitelist The list of tokens approved by the DAO for use in escrows. Currently USDC and USDT. # Audit Status Source: https://docs.zen.land/security/audit-status Security audits and vulnerability disclosure. ## Current Audit Status Zenland V2 smart contracts are undergoing security review. | Item | Status | | ---------------------------------- | -------------- | | Internal Security Review | ✅ Complete | | Automated Analysis (Slither, etc.) | ✅ Complete | | External Audit | 🔄 In Progress | | Bug Bounty Program | 📋 Planned | *** ## Security Practices ### Code Quality * **Solidity 0.8+** — Built-in overflow protection * **OpenZeppelin contracts** — Battle-tested libraries * **Comprehensive tests** — Unit, integration, fuzz, invariant * **No floating pragma** — Exact compiler versions ### Review Process Before deployment: 1. ✅ 100% test coverage target 2. ✅ Internal security review 3. ✅ Automated vulnerability scanning 4. 🔄 External audit by reputable firm 5. 📋 Testnet deployment and testing 6. 📋 Mainnet deployment *** ## Audit Reports Once complete, audit reports will be published here: | Auditor | Scope | Date | Report | | ------- | ---------------------------------------------------- | --------- | --------- | | *TBD* | EscrowFactory, EscrowImpl, AgentRegistry, FeeManager | *Pending* | *Pending* | *** ## Known Limitations The following are **known behaviors**, not bugs: Tokens that charge fees on transfer will cause escrow amount mismatches. Only use whitelisted stablecoins. Tokens that change balance over time (like stETH) are not supported. This is intentional behavior for 2-of-2 escrows, not a vulnerability. Once created, escrow rules cannot change. This is a security feature. *** ## Vulnerability Disclosure Found a security issue? Please report responsibly. **Do NOT** disclose vulnerabilities publicly before they are fixed. ### How to Report 1. **Email:** [security@zen.land](mailto:security@zen.land) 2. **Include:** * Description of the vulnerability * Steps to reproduce * Potential impact assessment * Your suggested fix (optional) ### What to Expect | Timeframe | Action | | --------- | -------------------------------------- | | 24 hours | Acknowledgment of your report | | 72 hours | Initial assessment and severity rating | | 7-14 days | Fix development (for critical issues) | | After fix | Coordinated disclosure and credit | ### Bug Bounty (Coming Soon) We're planning a bug bounty program with rewards based on severity: | Severity | Potential Reward | | ----------------------- | ---------------- | | Critical (fund loss) | Up to \$50,000 | | High (frozen funds) | Up to \$10,000 | | Medium (DoS, griefing) | Up to \$2,000 | | Low (UI, informational) | Up to \$500 | *Exact amounts TBD. Check back for official program launch.* *** ## Security Contacts [security@zen.land](mailto:security@zen.land) Ask in Telegram # Dispute Resolution Security Source: https://docs.zen.land/security/dispute-resolution How the agent system protects against bad actors. ## Multi-Layer Protection Dispute resolution in Zenland has multiple security layers: ```mermaid theme={null} graph TD A[Disagreement Occurs] --> B{Try Mutual Split?} B -->|Yes, Agreed| C[Split Executed] B -->|No Agreement| D[Invite Agent] D --> E{Agent Valid?} E -->|Yes| F[Agent Reviews] E -->|No| G[Return to Disputed] F --> H[Agent Decides] H --> I[Funds Distributed] D --> J{Agent Timeout?} J -->|7 days| K[Claim Timeout] K --> G ``` *** ## Agent Staking Agents must **stake funds** to participate: ### Dual Staking Model | Stake Type | Purpose | Amount | | -------------------- | ----------------------------------------- | ---------------------- | | **Stablecoin Stake** | Determines MAV (max value they can judge) | Min \~\$100 equivalent | | **DAO Token Stake** | Shows protocol alignment | Min \~100 tokens | ### How MAV Works ``` Agent stakes: $1,000 USDC MAV multiplier: 20x Max escrow they can handle: $20,000 Your escrow: $15,000 → Agent is eligible ✓ Your escrow: $25,000 → Agent cannot be selected ✗ ``` *** ## Protection Against Agent Attacks ### Attack: Agent Unstakes After Selection **Scenario:** Agent is selected, then unstakes before dispute, then colludes for a bribe. **Protection:** 1. Agent eligibility is re-checked at *invite time* (not just creation) 2. `activeCases` counter prevents unstaking during disputes 3. 30-day cooldown after last case before unstaking allowed ### Attack: Agent Colludes with One Party **Scenario:** Agent takes a bribe to rule unfairly. **Protection:** 1. Economic: Bribe must exceed stake value (at risk of slashing) 2. Reputation: Bad decisions visible on-chain, affect future selection 3. DAO: Token holders can vote to slash bad agents ### Attack: Agent Goes Inactive **Scenario:** Agent stops responding to requests. **Protection:** 1. 7-day timeout after invite 2. Either party can claim timeout 3. Escrow returns to disputed with no agent 4. Parties settle via mutual split *** ## Two-Stage Agent Validation Agents are validated at two checkpoints: * Is this agent registered? * Is their MAV sufficient? * Are they active and available? *If fails: Cannot create escrow with this agent* * Is agent still registered? * Is MAV still sufficient? * Are they still active and available? *If fails: inviteAgent() reverts* This two-stage validation prevents "nothing to lose" attacks where agents unstake between creation and dispute. *** ## Seller Refund Escape Hatch Even in disputes, the seller can always refund: Seller can return 100% to buyer at any time — no approval needed. This provides an ultimate escape: * Agent is unresponsive? Seller can refund. * Dispute is taking too long? Seller can refund. * Seller made a mistake? Seller can refund. *** ## Locked Escrow Considerations For locked escrows (no agent): There is NO third-party intervention. Security comes purely from game theory. | Protection | Standard Escrow | Locked Escrow | | ------------------- | --------------- | ------------- | | Agent arbitration | ✓ | ✗ | | Seller refund | ✓ | ✓ | | Mutual split | ✓ | ✓ | | Timeout protection | ✓ | ✗ | | Permanent lock risk | ✗ | ✓ | *** ## DAO Oversight The DAO provides backstop governance: * **Slash bad agents** for proven misconduct * **Adjust parameters** (fees, timeouts, minimums) * **Blacklist tokens** that behave maliciously * **Upgrade factory** for future escrows The DAO cannot intervene in individual disputes or override agent decisions. This is by design for decentralization. *** Understand the agent system → # How Funds Are Protected Source: https://docs.zen.land/security/how-funds-are-protected Smart contract security that keeps your escrow funds safe. ## Non-Custodial by Design When you create an escrow, funds go directly to a smart contract — not to Zenland. This means: * ✅ **No company** can access your funds * ✅ **No employee** can steal or freeze your money * ✅ **No server hack** can compromise your escrow * ✅ **No government** can seize funds without your keys *** ## How It Works ```mermaid theme={null} graph LR A[Your Wallet] -->|Deposit| B[Escrow Smart Contract] B -->|Release| C[Seller's Wallet] B -->|Refund| A B -->|Split| D[Both Parties] ``` The smart contract: * **Holds funds** according to programmed rules * **Only releases** when conditions are met * **Cannot be changed** after deployment * **Is fully auditable** by anyone *** ## Security Layers ### Layer 1: Smart Contract Safety Each escrow is a lightweight clone of the audited implementation. Protection against reentrancy attacks on all state-changing functions. OpenZeppelin's safe transfer library prevents token-related exploits. State changes happen before external calls to prevent manipulation. ### Layer 2: Protocol Safety Escrow addresses are deterministic — you know where funds go before sending. Escrow creation and funding happen in one transaction. No front-running. Clear state transitions prevent invalid operations. Only DAO-approved tokens are supported. No weird token exploits. ### Layer 3: Trust Boundaries Only escrows created by the official factory are recognized. Agents are re-validated when invited to prevent stake manipulation. *** ## What Could Go Wrong (And How We Handle It) **Risk:** Tokens with hooks, fees, or rebasing could exploit escrows. **Mitigation:** Only whitelisted stablecoins (USDC, USDT) are supported. Fee-on-transfer and rebasing tokens are explicitly blocked. **Risk:** Someone could front-run your escrow creation. **Mitigation:** CREATE2 salt includes your address, so only you can deploy to your predicted address. **Risk:** Agent could collude with one party. **Mitigation:** Agents stake funds (5% of MAV minimum). Misbehavior = slashing by DAO. **Risk:** Bugs could lock or drain funds. **Mitigation:** Contracts are thoroughly tested and audited. Immutable escrows can't be "patched" after deployment. *** ## Immutability Once your escrow is created: * **The rules can't change** — your escrow follows the version it was created with * **No admin backdoor** — there's no function to drain funds * **DAO upgrades don't affect you** — only new escrows use new code This is intentional. Immutability is a feature, not a bug. It means you can trust the code. *** ## Best Practices for Users Check that the escrow address matches what's in your PDF contract. Always use zen.land. Bookmark it to avoid phishing sites. Your wallet is your escrow access. Protect your seed phrase. Read the escrow terms before funding. The smart contract enforces them exactly. *** Learn about our security audits → # Cancelling an Escrow Source: https://docs.zen.land/user-guides/cancelling-escrow How to cancel an escrow and get your funds back at every stage. **Quick answer:** If the seller hasn't accepted yet, ask them to **decline** the escrow — or wait **1 hour** for the acceptance window to expire and cancel it yourself. Either way, you get a full refund. ## How Cancellation Works There is no single "Cancel" button. How you get your funds back depends on the **current state** of the escrow. Here's every scenario: *** ## By Escrow State ### Pending — Seller Hasn't Accepted This is the most common cancellation scenario. The escrow is created and funded, but the seller hasn't accepted yet. The seller logs in and clicks **Decline**. The full escrow amount is refunded to the buyer instantly. If the seller doesn't respond within **1 hour**, the buyer can cancel the escrow and receive a full refund. The buyer **cannot** cancel unilaterally while the 1-hour acceptance window is still active. This protects the seller's right to review and accept. *** ### Active — Seller Accepted, Work In Progress Once the seller accepts, the buyer can no longer cancel alone. But there are two ways to return the funds: | Method | Who | How | | ----------------- | ------ | --------------------------------------------------------------------------------------------------- | | **Seller Refund** | Seller | The seller can refund 100% to the buyer at any time — no approval needed | | **Mutual Split** | Both | Either party proposes a split (can be 100% to buyer), the other approves, and funds are distributed | If you both agree the deal should be cancelled, a **split of 100% to buyer / 0% to seller** works exactly like a cancellation. *** ### Fulfilled — Seller Marked Complete Same options as Active: * **Seller** can still refund 100% to the buyer * **Both parties** can agree on a split **Buyers:** If you don't release, dispute, or negotiate before the protection period expires, the seller can claim the funds. *** ### Disputed — Dispute Opened Even during a dispute, funds can still be returned: * **Seller refund** — seller can refund 100% at any time * **Mutual split** — both parties agree on a split * **Invite the agent** — the agent decides how to split the funds *** ### Agent Invited — Waiting for Resolution While the agent is reviewing the case: * **Seller** can still refund 100% * **Both parties** can still agree on a split * **Agent** resolves and distributes funds (minus their fee) * If the agent doesn't respond within **7 days**, either party can **claim timeout** — the escrow returns to Disputed state with no agent, and you settle via split or seller refund *** ### Terminal States — It's Over Once an escrow reaches **Released**, **Refunded**, **Split**, or **Agent Resolved**, no further actions are possible. The funds have already been distributed. *** ## What About the Protocol Fee? The protocol fee (paid by the buyer at creation) is **not refunded** regardless of how the escrow ends. This fee covers the cost of deploying and maintaining the smart contract infrastructure. *** ## Summary Table | State | Buyer Can Cancel? | Seller Can Cancel? | How | | --------------------------- | :---------------: | :----------------: | ------------------------------------------------- | | **Pending** (within 1 hour) | ❌ | ✅ Decline | Seller clicks Decline | | **Pending** (after 1 hour) | ✅ Cancel Expired | ✅ Decline | Either party acts | | **Active** | ❌ | ✅ Refund | Seller refunds or both agree on split | | **Fulfilled** | ❌ | ✅ Refund | Seller refunds or both agree on split | | **Disputed** | ❌ | ✅ Refund | Seller refunds, split, or agent resolves | | **Agent Invited** | ❌ | ✅ Refund | Seller refunds, split, agent resolves, or timeout | | **Terminal** | ❌ | ❌ | Already finalized | *** ## Frequently Asked Questions You have two options: ask the seller to log in and decline the escrow (instant refund), or wait for the 1-hour acceptance window to expire and cancel it yourself. No. Once the seller accepts, the buyer cannot unilaterally cancel. The seller can refund, or both parties can agree on a split. No. The protocol fee is non-refundable regardless of the outcome. After 7 days, either party can claim agent timeout. The escrow returns to disputed state with no agent. From there, settle via mutual split or seller refund. *** Ask the community on Telegram # Creating an Escrow Source: https://docs.zen.land/user-guides/creating-escrow Step-by-step guide to creating your first escrow contract. ## Before You Start Make sure you have: Your wallet connected to the Zenland app Enough stablecoins to cover the escrow amount + 1% fee The seller's Ethereum wallet address Agreement on terms with your counterparty *** ## Step 1: Navigate to Create Escrow 1. Open [zen.land/app](https://zen.land/app) 2. Connect your wallet 3. Click **"Create Escrow"** in the navigation or dashboard *** ## Step 2: Enter Escrow Details Fill in the following fields: ### Seller Address Enter the Ethereum address of the person you're paying: ``` 0x1234567890abcdef1234567890abcdef12345678 ``` Double-check this address! Funds sent to the wrong address cannot be recovered. ### Amount Enter how much you want to escrow: * **Minimum:** \$1 (or equivalent in stablecoin) * **Token:** Choose USDC or USDT * **Fee:** 1% added on top (min $0.50, max $50) ### Description Write what this escrow is for. Be specific: "Website development: 5-page portfolio site with responsive design, contact form, and CMS integration. Delivery in 2 weeks." "Website" ### Buyer Protection Time How long you have to review the delivery after the seller marks it complete: | Timeframe | Good For | | --------- | -------------------------- | | 1 day | Simple, small transactions | | 3-7 days | Services requiring testing | | 14+ days | Complex projects | After this time expires, the seller can claim funds even if you haven't released them. Choose wisely! *** ## Step 3: Choose an Agent This is one of the most important decisions: ### Option A: Select an Agent (Recommended) Browse available agents and check: * **Reputation** — resolution history, success rate * **Fee** — what % they charge for disputes * **Specialization** — some agents focus on specific industries If you and the seller disagree, the agent decides how funds are split. Choose someone trustworthy and qualified. ### Option B: No Agent (Locked Escrow) **Advanced users only!** Locked escrows have no dispute resolution. With no agent: * You and the seller must agree on everything * If you disagree, funds can be locked **forever** * Only use with highly trusted counterparties [Learn more about Locked Escrows →](/escrow-types/locked-escrow) *** ## Step 4: Review the Contract Before funding, you'll see: 1. **PDF Preview** — A contract summarizing all terms 2. **Escrow Address** — The deterministic address where funds will go 3. **Fee Breakdown** — Amount + protocol fee The PDF is hashed and stored on-chain. This proves what you both agreed to. ### What to Verify * [ ] Seller address is correct * [ ] Amount matches your agreement * [ ] Description covers all deliverables * [ ] Protection time is adequate * [ ] Agent is acceptable (if applicable) *** ## Step 5: Fund the Escrow Click **"Create & Fund"** and approve the transaction: Your wallet asks to approve USDC/USDT spending Sign the transaction to create and fund the escrow Transaction is mined on Ethereum (\~15 seconds) You'll see confirmation and can share the link with your seller *** ## After Creation Your escrow is now in `PENDING` state, waiting for the seller to accept. ### What Happens Next? 1. **Notify your seller** — Share the escrow link or let them check their dashboard 2. **Seller reviews** — They verify the terms match your agreement 3. **Seller accepts** — Escrow becomes `ACTIVE`, work begins 4. **Or seller declines** — You receive an immediate refund ### If Seller Doesn't Respond If the seller doesn't accept within the acceptance window: * You can call **"Cancel Expired"** to get a full refund * No penalties, you just get your money back *** ## Common Issues Check that you have: * Enough stablecoins for amount + fee * Enough ETH for gas (unless using NYKNYC) * Token approval wasn't revoked Make sure: * They're connected to the right wallet address * They're on the correct network (Mainnet vs Sepolia) * They refresh their dashboard Unfortunately, escrows are created atomically. If you used the wrong address, wait for the acceptance window to expire, then cancel for a refund. Double-check next time! # Guide for Buyers Source: https://docs.zen.land/user-guides/for-buyers How to safely purchase goods or services using Zenland escrow. ## Why Use Escrow as a Buyer? When you're paying someone you don't fully trust, escrow protects you: * ✅ **Your money is safe** until you receive what was promised * ✅ **The seller is motivated** to deliver quality work * ✅ **Disputes get resolved** fairly by professional agents *** ## Step-by-Step: Creating Your First Escrow Go to [zen.land/app](https://zen.land/app) and connect your wallet. We recommend NYKNYC for zero gas fees. Start a new escrow from your dashboard. Fill in: * **Seller's wallet address** — get this from your seller * **Amount** — how much you're paying (in USDC or USDT) * **Description** — what you're buying * **Protection time** — how long you have to review the delivery Select a professional agent to resolve any potential disputes. Or choose "No Agent" for a locked escrow. Without an agent, disputes can only be resolved through mutual agreement. Funds may be locked forever if you disagree. Review the generated PDF contract, then sign and fund the escrow. The 1% fee is added on top of your amount. The seller must accept the escrow before work begins. If they don't accept in time, you can cancel and get a refund. *** ## Managing Your Escrow Once the seller accepts, here's what you can do: ### Communicate with Your Seller Stay in touch! Use Telegram, email, or your preferred channel to: * Track progress * Answer questions * Receive updates Good communication prevents most disputes. Check in regularly with your seller. ### Review the Delivery When the seller marks the escrow as `Fulfilled`: 1. **Check the work** carefully against your agreement 2. **Test everything** you paid for 3. **Take your time** — you have the full protection period ### Release the Funds If you're satisfied: Find your escrow and click the Release button Approve the transaction in your wallet Funds are instantly transferred to the seller *** ## What If Something's Wrong? ### Option 1: Negotiate with the Seller Before opening a dispute, try to resolve things directly: * **Clearly explain** what's not meeting expectations * **Give the seller** a chance to fix it * **Many issues** can be resolved with good communication ### Option 2: Open a Dispute If negotiation fails: Open a dispute from your escrow page The pre-selected agent will review the case Share evidence (screenshots, messages, deliverables) with the agent The agent determines a fair split of the funds. Their fee is deducted first. ### Option 3: Propose a Split Would you settle for a partial refund? Propose a split: * You suggest: "I keep 40%, seller keeps 60%" * Seller approves or counter-proposes * Funds are distributed when you both agree *** ## Important Buyer Tips Give yourself enough time to properly test the delivery. Minimum is 1 day. Check agent reputation and resolution history before choosing. Save conversations, screenshots, and specs. They help in disputes. If the work is good, release promptly! Great sellers deserve quick payment. *** ## FAQs for Buyers If the seller doesn't accept within the acceptance window, you can cancel the escrow and receive a full refund. You can't unilaterally cancel, but you can: * Ask the seller to refund you (they can do this anytime) * Open a dispute and let the agent decide * Propose a mutual split If the seller marked `Fulfilled` and your protection time expires, the seller can claim the funds. Review deliveries promptly! Just 1% of the escrow amount (min $0.50, max $50). This is paid when you create the escrow. # Guide for Sellers Source: https://docs.zen.land/user-guides/for-sellers How to get paid securely while protecting your work with Zenland escrow. ## Why Use Escrow as a Seller? Escrow protects you just as much as the buyer: * ✅ **Funds are locked upfront** — buyer can't ghost after you deliver * ✅ **You're protected** from chargebacks and "I changed my mind" * ✅ **You can always refund** if something goes wrong on your end *** ## Getting Started as a Seller ### 1. Share Your Wallet Address Give your **Ethereum wallet address** to the buyer. They'll use it to create the escrow. Use an ENS name (like `yourname.eth`) to make it easier for buyers to find you and verify your identity. ### 2. Review the Escrow Invitation When a buyer creates an escrow with you, you'll see it in your dashboard: * Is the amount correct? * Do the terms match your agreement? * Is the protection time reasonable? * Who is the selected agent? * Amount doesn't match discussion * Vague or missing terms * Very short protection time * No agent selected (understand the risks) ### 3. Accept or Decline If everything looks good, accept the escrow. You're now committed to delivering. If something's wrong, decline. The buyer gets an immediate refund. Once you accept, you're expected to deliver. Only accept escrows you're confident you can complete. *** ## Doing the Work Once the escrow is active: ### Stay in Communication * **Update the buyer** on your progress * **Ask questions** if anything is unclear * **Set expectations** for delivery timeline ### When You're Done Make sure you've delivered everything in the agreement This signals to the buyer that you're done The buyer reviews and releases funds. The protection timer starts. *** ## Getting Paid ### Best Case: Buyer Releases The buyer reviews your work, loves it, and hits Release. Funds arrive instantly! ### Buyer is Unresponsive If the buyer doesn't respond after marking fulfilled: 1. **Wait for protection time to expire** 2. **Claim the funds yourself** — you've earned them! This is your safety net against buyers who ghost after receiving good work. ### Buyer Opens a Dispute Don't panic. Here's what happens: You'll see the dispute in your dashboard The pre-selected agent reviews the case Share delivery proof, messages, and anything showing you delivered The agent determines a fair split. Their fee is deducted from the total. *** ## Your Secret Weapon: Seller Refund As a seller, you have a powerful option others don't: **unilateral refund**. At any time before the escrow is finalized, you can return 100% to the buyer — no approval needed. Use this when: * 😅 You realize you can't complete the work * 🤝 You want to end things on good terms * ⚠️ The project scope changed unexpectedly Refunding protects your reputation. It's better to refund early than get a bad resolution. *** ## Proposing a Split Sometimes partial payment is fair. You can propose a split: Choose how to divide the funds (e.g., 70% to you, 30% to buyer) They can accept, reject, or counter-propose When you both agree, funds are distributed automatically *** ## Important Seller Tips Save all communications, specs, and work files. They're crucial in disputes. When you're done, mark it. This starts the protection timer. If you need more time, tell the buyer early. Most are understanding. Understand who will resolve disputes before you accept. *** ## FAQs for Sellers Present your evidence to the agent. If you delivered what was agreed, you'll likely win the dispute. Agents are trained to identify bad-faith buyers. The current escrow amount is fixed. For additional work, create a new escrow with the new scope. Mark as fulfilled, wait for protection time to expire, then claim the funds. The smart contract enforces your right to payment. No! The buyer pays the 1% creation fee. You receive the full escrow amount (minus agent fees only if there's a dispute resolution). # Managing Your Escrow Source: https://docs.zen.land/user-guides/managing-escrow Actions available during an active escrow. ## Escrow States Overview Your escrow will pass through different states. Here's what you can do at each: ```mermaid theme={null} stateDiagram-v2 [*] --> Pending: Create Pending --> Active: Seller Accepts Pending --> Refunded: Seller Declines Pending --> Refunded: Cancel Expired Active --> Fulfilled: Mark Fulfilled Active --> Disputed: Open Dispute Active --> Released: Buyer Releases Active --> Refunded: Seller Refunds Fulfilled --> Released: Release or Claim Fulfilled --> Disputed: Open Dispute Disputed --> Resolved: Agent Decides Disputed --> Split: Mutual Agreement ``` *** ## Actions by State ### Pending State The escrow has been created but the seller hasn't accepted yet. * Wait for seller to accept * Cancel if seller doesn't respond (after expiry) * Review the terms carefully * Accept to start working * Decline if terms are wrong *** ### Active State Seller accepted. Work is in progress! | Action | Description | | ----------------- | ----------------------------- | | **Release** | Send 100% to seller (anytime) | | **Open Dispute** | Raise an issue with the work | | **Propose Split** | Suggest dividing the funds | | Action | Description | | ------------------ | ----------------------------------------- | | **Mark Fulfilled** | Signal that work is complete | | **Refund** | Return 100% to buyer (no approval needed) | | **Propose Split** | Suggest dividing the funds | *** ### Fulfilled State Seller has marked the work as complete. The clock is ticking! **Buyers:** Review promptly! After the protection time expires, the seller can claim the funds. | Action | Description | | ----------------- | --------------------------------------- | | **Release** | Send funds to seller (you're satisfied) | | **Open Dispute** | Something is wrong with delivery | | **Propose Split** | Negotiate a partial refund | | Action | Description | | ------------------------ | ----------------------------------- | | **Claim** (after expiry) | Take funds if buyer is unresponsive | | **Refund** | Return 100% to buyer | | **Propose Split** | Negotiate a resolution | *** ### Disputed State A dispute has been opened. Normal settlement is paused. Either party can invite the pre-selected agent to resolve the dispute. Or try to settle mutually without involving the agent. Even during a dispute, the seller can still refund 100% or both parties can agree to a split. *** ### Agent Invited State The agent is reviewing the case. * **Present your case** — Share evidence with the agent * **Respond promptly** — Agents may have questions * **Be honest** — Agents can detect bad-faith behavior * Agent reviews evidence from both parties * Agent decides the split (e.g., 60% buyer, 40% seller) * Agent fee is deducted from the total * Funds are distributed automatically **Agent Timeout:** If the agent doesn't respond within 7 days, either party can claim timeout. The escrow returns to disputed state with no agent (locked mode). *** ## The Split Negotiation Flow Splits are a powerful way to settle without agent involvement: Either party proposes a split (e.g., "70% to me, 30% to you") The other party sees the proposal in their dashboard They can: * **Accept** — Funds are distributed immediately * **Counter** — Propose different percentages * **Ignore** — Proposal stays pending When both parties agree on the same split, it executes automatically Proposing a split is free! It doesn't commit you to anything until the other party accepts. *** ## Terminal States These are the final states — the escrow is complete: | State | Meaning | | ------------------ | ------------------------------ | | **Released** | Full amount sent to seller | | **Refunded** | Full amount returned to buyer | | **Split** | Amount divided between parties | | **Agent Resolved** | Agent determined the split | Once in a terminal state, no further actions are possible. *** ## Tips for Smooth Escrows * Review deliveries promptly to keep the seller happy * Communicate clearly about what's missing before disputing * Release funds quickly when satisfied — it builds trust * Mark fulfilled only when everything is truly complete * Communicate any delays before they become problems * Don't be afraid to refund if you can't deliver * Document everything in writing * Use the protection time wisely * Try mutual settlement before invoking agents # Resolving Disputes Source: https://docs.zen.land/user-guides/resolving-disputes What happens when buyer and seller disagree, and how disputes are resolved. ## When to Open a Dispute Not every issue needs a formal dispute. Consider these first: Most issues stem from miscommunication. Talk to the other party before escalating. Would you accept a partial refund? Splits are faster and cheaper than disputes. Open a dispute when: * The other party is unresponsive * You fundamentally disagree on what was agreed * You believe the other party is acting in bad faith *** ## The Dispute Process The **buyer** clicks "Open Dispute" on the escrow page. This pauses normal settlement. Either party invites the pre-selected agent to review the case. The agent examines: * The escrow terms (PDF contract) * Evidence from both parties * Communication history (if provided) The agent sets a split: * `80% buyer / 20% seller` (buyer mostly right) * `50% / 50%` (shared fault) * `10% buyer / 90% seller` (seller mostly right) Agent fee is deducted first, then remaining funds are split as decided. *** ## Presenting Your Case When an agent is invited, you'll need to make your case clearly: ### What to Include What was promised? Reference the escrow terms and any off-chain discussions. Screenshots, files, links — proof of what was (or wasn't) delivered. Relevant messages showing the timeline and commitments. Clearly state what resolution you want and why it's fair. ### Tips for a Strong Case "The website doesn't work" is weak. "The contact form throws a 500 error when submitted" is strong. Agents can smell exaggeration. Acknowledge any mistakes on your side. Respond to agent questions quickly. Delays hurt your credibility. *** ## Agent Fees When an agent resolves a dispute, they earn a fee: ``` Total Funds: $1,000 Agent Fee: 5% = $50 Remaining: $950 Agent Decision: 60% buyer / 40% seller - Buyer receives: $570 - Seller receives: $380 ``` Agent fees vary. Check the agent's fee before selecting them when creating the escrow. ### Fee Caps Agents must set fees within DAO-defined limits: * **Minimum:** 0.1% (10 basis points) * **Maximum:** 10% (1000 basis points) *** ## Agent Timeout What if the agent doesn't respond? If an agent doesn't act within **7 days** of being invited, either party can claim timeout. Give the agent time to respond Either party can trigger this But now with NO agent (locked mode) Propose a split, or seller can refund Agent timeouts affect the agent's reputation and may result in DAO action. *** ## Disputes in Locked Escrows If you created an escrow without an agent: There is no agent to invite. You must reach agreement with the other party. Your options: 1. **Propose a Split** — Negotiate percentages until you agree 2. **Seller Refunds** — Seller can always return 100% to buyer 3. **Accept Stalemate** — Funds remain locked forever (neither party gets them) This is why we recommend always selecting an agent. Locked escrows are for advanced users who accept this risk. *** ## Escalation to DAO (Future) **Coming in V2:** For extreme cases where agents misbehave, disputes may be escalated to the DAO for community resolution. Currently, the DAO can: * Slash agent stakes for misconduct * Blacklist bad-faith agents * Adjust protocol parameters But individual dispute resolution is handled by agents, not DAO voting. *** ## FAQs Yes, but only if the escrow is still in Fulfilled state (seller hasn't claimed yet). No, only buyers can open disputes. But sellers can always refund or propose splits. Agent decisions are final for that escrow. You can report agent misconduct to the DAO for future action. Depends on the agent, but typically 1-3 days. The 7-day timeout is a safety net.