Welcome to DealVault

Every deal on DealVault follows one simple rule: funds are locked before work begins, and released only when conditions are met. No trust required. No intermediary. Just code.

This documentation covers everything — from how the escrow system works, to how contributors earn USDC, to how the Soroban smart contracts are deployed and function.

The Core Problem

Online work has always had a trust problem. Contributors fear they won't get paid. Maintainers fear they won't get the work. DealVault removes both fears by making payment guaranteed before work starts.

How It Solves It

Step 1 — Sign in with GitHub

Visit DealVault and click Get Started. Authenticate with your GitHub account. Your profile, repositories, and avatar are pulled automatically.

Step 2 — Choose your role

Select Contributor if you want to earn USDC by completing issues. Select Maintainer if you want to fund issues and attract contributors to your project. You can switch roles at any time from your profile.

Step 3 — Complete KYC & connect wallet

Before applying or creating issues, you must verify your identity (KYC) and connect a Stellar wallet — Freighter, Lobstr, or xBull. This takes about 2 minutes.

Step 4 — Start earning or funding

Contributors browse Explore Issues to find funded bounties. Maintainers submit their repo for review, then create funded issues once approved.

What is escrow?

Escrow is a financial arrangement where a third party holds funds until a transaction is complete. In DealVault, the "third party" is a Soroban smart contract — code running on the Stellar blockchain that no one controls except the rules written into it.

How funds are held

When a maintainer funds an issue, USDC is transferred from their Stellar wallet into the escrow contract address. The contract holds the funds trustlessly. Neither the maintainer, contributor, nor DealVault can access the funds unilaterally.

// Maintainer calls this to lock funds
pub fn fund_escrow(
    env: Env,
    deal_id: Symbol,
    maintainer: Address,
    contributor: Address,
    usdc_token: Address,
    amount: i128,
) {
    maintainer.require_auth();
    token::Client::new(&env, &usdc_token)
        .transfer(&maintainer, &env.current_contract_address(), &amount);
    // Store deal on-chain
    env.storage().instance().set(&deal_id, &(contributor, amount, usdc_token));
}

When funds are released

Funds are released in exactly three scenarios:

• Maintainer approves submitted work → funds go to contributor (minus 2% fee)
• Admin rules in favour of contributor during a dispute → same outcome
• Admin rules in favour of maintainer during a dispute → full refund to maintainer

What is Stellar?

Stellar is an open-source, decentralized blockchain network designed for fast and cheap cross-border payments. Transactions settle in 3–5 seconds and cost less than $0.000003.

What is Soroban?

Soroban is Stellar's smart contract platform. It uses Rust-based WebAssembly contracts that are deployed on-chain and execute deterministically. DealVault's escrow logic lives entirely in a Soroban contract.

Why USDC and not XLM?

XLM is Stellar's native token, but its value fluctuates with the market. A bounty worth 100 XLM today might be worth $30 tomorrow. Contributors can't plan their income around volatile rewards.

USDC is a stablecoin pegged 1:1 to the US Dollar. 100 USDC is always approximately $100 — regardless of crypto market conditions. This makes DealVault rewards predictable and professional.

Getting started as a Contributor

1. Sign in with GitHub
2. Select Contributor role
3. Complete KYC verification
4. Connect your Stellar wallet (Freighter / Lobstr / xBull)
5. Browse funded issues on Explore Issues
6. Apply to issues that match your skills

Applying to an issue

Every issue on DealVault shows a ✓ FUNDED badge — meaning the reward is already locked in escrow. Click Apply, and your application is sent to the maintainer.

Submitting work

Once assigned, complete the work and submit via the DealVault platform. Include a link to your pull request, repository, or deliverable. The maintainer will review and approve or request revisions.

Getting paid

When the maintainer approves, the Soroban contract automatically releases 98% of the escrow amount to your connected Stellar wallet. The remaining 2% is the DealVault platform fee. Settlement takes 3–5 seconds.

Getting started as a Maintainer

1. Sign in with GitHub
2. Select Maintainer role
3. Submit your repository for review
4. Wait for DealVault team approval (24–48 hours)
5. Create funded issues once approved

Submitting your repository

Every maintainer must submit their GitHub repo for review before creating issues. The DealVault team evaluates whether the project is active, has suitable open issues, and benefits the broader ecosystem.

Funding types

Reviewing applicants

Once an issue is live, contributors can apply. You can view each applicant's profile, reputation score, completed bounties, and skills. Select the best fit and they'll be notified immediately.

Approving work

When a contributor submits work, review it carefully. If satisfied, click Approve & Release. The smart contract automatically releases funds to the contributor's Stellar wallet. If you need revisions, request them through the platform. If there's a serious disagreement, raise a dispute.

Admin responsibilities

• Review and approve or reject maintainer repo submissions
• Mediate disputes between contributors and maintainers
• Monitor all on-chain transactions via audit logs
• Manage KYC verification edge cases
• Enforce platform terms and community standards

Dispute resolution

When a dispute is raised, the admin reviews evidence submitted by both parties. Based on the review, the admin can either release funds to the contributor or refund to the maintainer. All dispute actions are recorded on-chain for full transparency.

What KYC involves

1. Personal information — name, email, date of birth, country (pre-filled from GitHub)
2. Government ID — passport, driver's licence, or national ID upload
3. Stellar wallet connection — connect Freighter, Lobstr, or xBull

Why we require KYC

• Prevents fake accounts and Sybil attacks
• Ensures contributors and maintainers are real, accountable people
• Builds trust for higher-value bounties
• Required for regulatory compliance with cross-border payments

How campaigns work

A campaign has a total USDC budget, a start and end date, and a set of approved repositories. Each approved repo gets a budget cap. Each issue within that repo gets a reward based on its label priority.

Anti-fraud protection

Each repo has a hard budget cap set by the admin. Maintainers cannot assign inflated rewards to specific people. Every payment is on-chain and publicly auditable. This makes the system transparent and tamper-proof.

When to raise a dispute

• Maintainer refuses to approve legitimately completed work
• Contributor submitted work that doesn't match the requirements
• Either party believes the other acted in bad faith

The process

How points work

The leaderboard resets per campaign period. Top contributors gain reputation, visibility, and priority placement in future applications.

What you'll find here

• All completed deal payouts with Stellar transaction hashes
• Current USDC balance locked in active escrows
• Platform fees deducted per deal
• Links to view each transaction on Stellar Explorer

Every transaction on DealVault is publicly verifiable on the Stellar blockchain. The transaction hash is always provided so you can independently verify any payment.

The contract is responsible for three things: locking funds, releasing funds, and refunding funds. No other logic. No complexity. Just three states, enforced by code.

The contract is non-upgradeable after deployment. The rules cannot be changed by DealVault, maintainers, or contributors. This is the basis of trustlessness.

┌─────────────────────────────────────┐
│  Frontend  (React + TypeScript)     │
│  Freighter wallet integration       │
│  Deployed on Vercel                 │
└──────────────┬──────────────────────┘
               │ REST API
┌──────────────▼──────────────────────┐
│  Backend  (Node.js + Express)       │
│  Deal metadata · Users · Notifs     │
│  MongoDB · Socket.io · JWT          │
│  Deployed on Render                 │
└──────────────┬──────────────────────┘
               │ Stellar SDK
┌──────────────▼──────────────────────┐
│  Soroban Smart Contract  (Rust)     │
│  fund_escrow · release · refund     │
│  Stellar Mainnet / Testnet          │
└─────────────────────────────────────┘

The backend never touches money. It only manages metadata (deal info, user profiles, notifications) and calls the Soroban contract when needed. All financial logic is in the contract.

Deal amount:          100.00 USDC
Platform fee (2%):      2.00 USDC  →  DealVault
Contributor receives:  98.00 USDC  →  Contributor wallet
Stellar gas:        ~0.000003 USD  →  Network only

The fee split is enforced inside the Soroban contract — it happens automatically on approval. DealVault cannot charge more than 2% and cannot take funds without approval.

Smart contract security

• All functions use require_auth() — only authorised parties can call critical functions
• Funds cannot be accessed by DealVault unilaterally
• Contract is open source and auditable by anyone
• Deployed as immutable — rules cannot be changed post-deployment

Platform security

• KYC verification for all participants — real identity behind every account
• JWT authentication with short expiry + refresh tokens
• All user data encrypted at rest and in transit
• Every action logged in a tamper-evident audit log
• GitHub OAuth — no passwords stored