Welcome to the PadiPay Soroban Escrow Contracts repository!
PadiPay is a decentralized, Web2.5 escrow service designed specifically for informal markets. It bridges everyday traders to secure, transparent transactions without requiring them to understand the underlying blockchain technology.
This repository contains the core Soroban smart contracts that power the PadiPay escrow logic on the Stellar network.
The contract implements an Escrow Manager architecture, meaning a single deployed contract is capable of managing many independent escrow agreements concurrently.
The repository currently supports the v0.2.0 Contract Hardening milestone on the Stellar Testnet. For full release details, see the Changelog.
It supports:
- Basic escrow creation
- Locking funds
- Time-locks / Expirations (
execute_timeout) - Releasing funds to the seller
- Refunding the buyer
- Dispute resolution with an authenticated mediator
- Emergency circuit breakers (pause/unpause)
Note: Future milestone workflows like multi-mediator consensus and milestone payments are deferred to Phase C.
Below is the current lifecycle of an escrow. Note that the contract manages many escrows simultaneously, and this lifecycle applies independently to each unique escrow agreement:
stateDiagram-v2
[*] --> Created : Buyer Creates Escrow
Created --> Locked : Buyer Locks Funds
Locked --> Released : Released to Seller
Locked --> Refunded : Refunded to Buyer
Locked --> Refunded : execute_timeout()
Locked --> Released : resolve_dispute("pay_seller")
Locked --> Refunded : resolve_dispute("refund_buyer")
Released --> [*]
Refunded --> [*]
The contract follows a modular architecture organized into several logical layers:
- Escrow Manager & State: A single deployed contract manages multiple concurrent escrow agreements. Each agreement is tracked independently via a unique
EscrowId. - Storage Layer: Manages persistent contract state per escrow using the Soroban SDK.
- Authentication Layer: Ensures only authorized roles (Buyer, Seller, Mediator) can perform sensitive actions.
- Token Layer: Safely manages locking, releasing, and refunding Stellar assets.
- Event Layer: Publishes key lifecycle events (e.g.,
EscrowCreated,FundsLocked) for off-chain applications. - Admin Layer: Provides emergency controls (
pause,unpause) to mitigate zero-day risks.
For an in-depth look at the architecture, please see the Architecture Document.
To set up your environment for Soroban smart contract development:
Install Rust using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shAdd the WebAssembly target:
rustup target add wasm32v1-noneThe stellar CLI is required to build, test, and deploy contracts.
cargo install --locked stellar-cli --features optCompile the contract to WebAssembly:
stellar contract buildThis will generate a .wasm file in the target/wasm32v1-none/release/ directory.
For more details, see the Setup Guide.
The repository includes a comprehensive suite of unit and integration tests covering the happy path, failure scenarios, and authorization checks.
Execute the tests locally by running:
cargo testTo verify the code formatting:
cargo fmt --all -- --checkTo deploy the contract to the Stellar Testnet, please see the Deployment Guide for detailed commands and necessary environment variables.
PadiPay evolves incrementally. Here is a high-level view of our milestones:
- v0.1.0 — Happy Path MVP: Core escrow flow, tests, and basic CI [Completed]
- v0.2.0 — Contract Hardening: Security, expirations, dispute resolution, circuit breaker [Completed]
- v0.3.0 — Production Readiness (Phase C): Milestone payments, partial releases, protocol fees, decentralized mediator registry [Current]
Read the full plan in our Roadmap.