{"id":50970214,"url":"https://github.com/kobby-pentangeli/zescrow","last_synced_at":"2026-06-19T01:31:36.572Z","repository":{"id":304928036,"uuid":"957366818","full_name":"kobby-pentangeli/zescrow","owner":"kobby-pentangeli","description":"Execute and verify escrow transactions in zero-knowledge","archived":false,"fork":false,"pushed_at":"2026-06-09T12:22:11.000Z","size":9171,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-09T13:07:52.821Z","etag":null,"topics":["cross-chain","escrow-contract","ethereum","risc0","rust","smart-contracts","solana-program","zero-knowledge-proofs","zkvm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kobby-pentangeli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-30T07:21:35.000Z","updated_at":"2026-06-09T11:06:51.000Z","dependencies_parsed_at":"2025-07-17T12:10:28.975Z","dependency_job_id":"1350163d-984e-4998-aa2a-0b381599c5af","html_url":"https://github.com/kobby-pentangeli/zescrow","commit_stats":null,"previous_names":["maatlabs/zescrow","kobby-pentangeli/zescrow"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kobby-pentangeli/zescrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobby-pentangeli%2Fzescrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobby-pentangeli%2Fzescrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobby-pentangeli%2Fzescrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobby-pentangeli%2Fzescrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kobby-pentangeli","download_url":"https://codeload.github.com/kobby-pentangeli/zescrow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobby-pentangeli%2Fzescrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34514282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-chain","escrow-contract","ethereum","risc0","rust","smart-contracts","solana-program","zero-knowledge-proofs","zkvm"],"created_at":"2026-06-19T01:31:35.789Z","updated_at":"2026-06-19T01:31:36.556Z","avatar_url":"https://github.com/kobby-pentangeli.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zescrow\n\n[![Crates.io](https://img.shields.io/crates/v/zescrow-core.svg)](https://crates.io/crates/zescrow-core)\n[![Documentation](https://docs.rs/zescrow-core/badge.svg)](https://docs.rs/zescrow-core)\n[![CI](https://github.com/kobby-pentangeli/zescrow/workflows/CI/badge.svg)](https://github.com/kobby-pentangeli/zescrow/actions)\n[![License](https://img.shields.io/crates/l/zescrow.svg)](https://github.com/kobby-pentangeli/zescrow#license)\n\nZescrow (for zero-knowledge escrow) is a trust-minimized, chain-agnostic implementation of an escrow program using the RISC Zero zkVM as the zero-knowledge prover/verifier.\n\n\u003e [!WARNING]\n\u003e **This project is not audited and is under active development. Until `v1.0`, do not deploy in production.**\n\n## Features\n\n- **Privacy-Preserving**: Release conditions are proven in zero knowledge---the witness (hashlock preimages, signatures, public keys) never leaves the prover; only a binding commitment and the pass/fail result are revealed on-chain\n- **Chain-Agnostic**: Deploy the same escrow logic across L1s/L2s via lightweight on-chain agents (a Solana program or an EVM contract)\n- **Proof-Gated Settlement**: A conditioned escrow releases only against a RISC Zero receipt whose journal binds to that specific escrow, verified on-chain before funds move (hashlock, Ed25519, Secp256k1, threshold)\n\n## Project Structure\n\n```text\nzescrow/\n├── core/         # Chain-agnostic types, escrow state machine, conditions\n├── prover/       # RISC Zero zkVM prover/verifier (optional; guest in prover/methods/guest)\n├── client/       # CLI and the embeddable library of on-chain agents\n├── agent/        # On-chain programs (per chain)\n│   ├── solana/   #   Anchor program (+ litesvm harness, mock verifier)\n│   └── ethereum/ #   Foundry contract (Escrow.sol)\n├── e2e/          # End-to-end test suite (real client vs. ephemeral local chains)\n├── deploy/       # Deployment scripts, guides, and configuration templates\n├── docs/         # Developer documentation\n└── scripts/      # Toolchain setup and end-to-end proof helpers\n```\n\n## Quick Start\n\n### Prerequisites\n\nThe fastest path is the setup script, which idempotently installs and pins every toolchain the workspace targets---Rust (stable + nightly), the RISC Zero zkVM toolchain, the Agave (Solana) CLI, and Anchor:\n\n```bash\n./scripts/setup.sh            # install everything (same as --all)\n./scripts/setup.sh --verify   # print installed versions, install nothing\n```\n\nThe script also takes per-component flags (`--rust`, `--risc0`, `--solana`, `--anchor`) to install only what you need. Foundry (`forge`, `cast`, `anvil`), required for the Ethereum agent, is installed separately; see the [Development Guide](docs/development.md) for the full toolchain and version pins.\n\nFor a minimal build you need only:\n\n1. [Rust](https://rustup.rs/) (stable; the workspace uses the 2024 edition, which requires Rust 1.85 or newer)\n2. (Optional) the [RISC Zero toolchain](https://dev.risczero.com/api/zkvm/quickstart#1-install-the-risc-zero-toolchain)---only required for ZK conditions\n\n### Deploy\n\n```bash\n# Clone and enter the repository\ngit clone https://github.com/kobby-pentangeli/zescrow.git\ncd zescrow\n\n# Set up environment\ncp deploy/.env.template .env\n# Edit .env with your configuration\n\n# Deploy (choose network)\n./deploy/solana/run.sh --network local      # Local test validator\n./deploy/solana/run.sh --network devnet     # Solana devnet\n./deploy/ethereum/run.sh --network local    # Local node (anvil)\n./deploy/ethereum/run.sh --network sepolia  # Ethereum Sepolia\n\n# Create an escrow\ncp deploy/solana/escrow_params.json deploy/\ncargo run --release -p zescrow-client -- create\n```\n\n\u003e **Note**: For escrows with cryptographic conditions (ZK proofs), build with `--features prover`:\n\u003e\n\u003e ```bash\n\u003e cargo run --release -p zescrow-client --features prover -- create\n\u003e ```\n\nSee the [Deployment Guide](deploy/README.md) for detailed instructions on local development and devnet/testnet deployment.\n\n## How It Works\n\n1. **Deploy** a chain-specific agent (Solana program or EVM contract), pinned to the RISC Zero verifier and the guest image id\n2. **Configure** escrow parameters (parties, amount, timelocks, an optional condition)\n3. **Create** the escrow via the CLI; funds are locked and, for a conditioned escrow, the condition commitment is recorded on-chain\n4. **Finish** — for a conditioned escrow the client generates a zero-knowledge receipt and submits `(seal, journal)`, which the on-chain agent verifies and binds to this escrow before releasing to the recipient; an unconditioned escrow releases on the time-lock alone\n5. **Cancel** — refund to the sender after the cancellation deadline (which a conditioned escrow is always required to set)\n\n```text\nOFF-CHAIN  ·  prover host   —--   the witness never leaves this half\n──────────────────────────────────────────────────────────────────────────────\n\n   ┌──────────┐\n   │  Sender  │\n   └──────┬───┘\n          │ (1) create  (params, optional condition)\n          ▼\n   ┌──────┴────────────────────────┐\n   │  zescrow-client               │  (2) prove the witness   ┌───────────────────┐\n   │  CLI + library; the `prover`  │ ────────────────────────▶│  RISC Zero guest  │\n   │  feature runs the zkVM guest  │ ◀───── receipt ──────────│       (zkVM)      │\n   └──────┬────────────────────────┘                          └───────────────────┘\n          │\n          │  (1) create  →  lock funds + record the condition commitment\n          │  (3) finish  →  submit (seal, journal)\n\n══════════╪═══════════════════════════════════════════════════════════════════\n          │  only (seal, journal) cross —-- never the witness\n══════════╪═══════════════════  ON-CHAIN  ·  per chain  ══════════════════════\n          ▼\n   ┌──────┴──────────────────────────────────┐\n   │  On-chain agent                         │\n   │  Solana program / EVM contract          │  (3) verify       ┌─────────────────────────┐\n   │                                         │ ─────────────────▶│  RISC Zero verifier     │\n   │  - holds the escrow vault               │                   │  (Groth16; on Solana,   │\n   │  - reconstructs the journal from its    │ ◀────── valid ────│   a pinned router CPI)  │\n   │    own state, requires it to bind THIS  │                   └─────────────────────────┘\n   │    escrow, then checks the seal         │\n   │    against sha256(journal)              │\n   └──────┬──────────────────┬───────────────┘\n          │ release          │ refund   (after `cancel_after`,\n          ▼                  ▼   no valid proof was submitted)\n   ┌─────────────┐     ┌──────────┐\n   │  Recipient  │     │  Sender  │\n   └─────────────┘     └──────────┘\n```\n\n| Step            | What happens                                                                                                                                                                                | Path                             |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |\n| **(1) create**  | Lock the funds in the agent's vault and, for a conditioned escrow, record the condition commitment on-chain                                                                                 | Sender → client → agent          |\n| **(2) prove**   | Run the zkVM guest over the private witness, producing a receipt—--a `seal` and a binding `journal`                                                                                         | client → guest → client          |\n| **(3) finish**  | Submit `(seal, journal)`; the agent reconstructs the journal from its own state, requires it to bind this escrow, then verifies the seal against the pinned image id over `sha256(journal)` | client → agent → verifier        |\n| **(4) release** | Once the proof is valid and bound and the finish window is open, the vault pays the recipient                                                                                               | agent → Recipient                |\n| **cancel**      | After `cancel_after` with no valid proof, the vault refunds the sender in full                                                                                                              | Sender → client → agent → Sender |\n\nA few details about the diagram above are worth calling out:\n\n- **The witness never crosses the boundary.** Only the public receipt---the `seal` and the `journal`---goes on-chain; hashlock preimages, signatures, and public keys stay on the prover host. That OFF-CHAIN / ON-CHAIN divider is the privacy boundary.\n- **A valid proof is necessary but not sufficient.** The agent re-derives the journal from its own on-chain state and requires every binding field to match---agent, escrow id, sender, recipient, asset, amount, and condition---so a genuine proof of some other escrow yields a different `sha256(journal)` and is rejected.\n- **One shape, many chains.** Only the agent is per-chain---a Solana program or an EVM contract, and on Solana verification is a CPI to a pinned RISC Zero router. The client, the guest, and the receipt format are identical everywhere.\n- **Unconditioned escrows skip steps (2) and (3).** With no condition there is nothing to prove: release is gated on the finish time-lock alone, and a conditioned escrow is always required to set `cancel_after` so funds can never be stranded.\n\n## Development\n\n```bash\n# Format (requires nightly)\ncargo +nightly fmt\n\n# Lint\nRISC0_SKIP_BUILD=1 cargo clippy --all-features\n\n# Build\nRISC0_SKIP_BUILD=1 cargo build --release --all-features\n\n# Test\nRISC0_SKIP_BUILD=1 cargo test --all-features\n\n# Documentation\nRISC0_SKIP_BUILD=1 cargo doc --all-features --no-deps\n```\n\n\u003e **Note**: `RISC0_SKIP_BUILD=1` skips compiling the zkVM guest code, which requires the RISC Zero toolchain. If you have it installed (`rzup install`), you can omit this prefix.\n\nFor the full toolchain setup, the dev-mode proving environment, and how to run the end-to-end suite, see the [Development Guide](docs/development.md).\n\n## Security\n\nZescrow is **not audited** and is under active development. See [SECURITY.md](SECURITY.md) for the threat model, trust assumptions, and how to report a vulnerability.\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or \u003chttp://opensource.org/licenses/MIT\u003e)\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkobby-pentangeli%2Fzescrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkobby-pentangeli%2Fzescrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkobby-pentangeli%2Fzescrow/lists"}