diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ff8bb7..33cc292 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,57 +1,11 @@ -# Contributing +# Contributing to OpenProof -Thanks for helping improve OpenProof. The project is intentionally small, privacy-first, and zero-backend for the MVP. +Please see [docs/Contributing.md](docs/Contributing.md) for the full contributing guide. -## Development Setup +## Quick Links +- [Development Setup](docs/Development.md) +- [Architecture](docs/Architecture.md) +- [Deployment](docs/Deployment.md) +- [Testing](docs/Testing.md) -```bash -npm install -cp .env.example .env.local -npm run dev -``` - -Before opening a pull request, run: - -```bash -npm run lint -npm run typecheck -npm run build -npm run test:contracts -``` - -## Product Boundaries - -Keep contributions aligned with the core model: - -- Hash files locally in the browser. -- Register only hashes on Base Sepolia. -- Avoid server-side file uploads. -- Avoid mandatory databases, storage buckets, accounts, or IPFS. -- Do not add tokens, NFTs, staking, DeFi, social feeds, or ownership/legal overclaims. -- Do not commit private keys, wallet secrets, RPC secrets, or deployment credentials. - -## Pull Requests - -Good pull requests include: - -- A short description of the change. -- The commands used to validate it. -- Screenshots or recordings for UI changes. -- Updated documentation for behavior, setup, or security changes. -- Focused scope; unrelated refactors should be separate. - -Security-sensitive changes should also update [`SECURITY.md`](SECURITY.md) or [`docs/threat-model.md`](docs/threat-model.md) when relevant. - -## Commit Style - -Use clear, practical commit messages. Prefer: - -```text -Improve receipt import validation -Add proof explorer empty state -Harden Base Sepolia network handling -``` - -## License - -By contributing, you agree that your contribution is licensed under AGPL-3.0-only. +By contributing, you agree that your contributions will be licensed under AGPLv3. diff --git a/README.md b/README.md index d81e1bd..efbbc43 100644 --- a/README.md +++ b/README.md @@ -1,279 +1,99 @@ -# OpenProof - -OpenProof is a privacy-first, open-source proof-of-existence app for files, built on Base Sepolia. - -**Maturity:** Prototype. Core workflows are functional but breaking changes are expected. See [docs/SYSTEMS_DOCTRINE.md](docs/SYSTEMS_DOCTRINE.md) and [rfcs/](rfcs/) for the governance and specification layer. - -It lets users create timestamped blockchain proofs for file fingerprints without uploading or storing the files themselves. Files are hashed locally in the browser with SHA-256, and only the resulting `bytes32` hash is registered onchain through a minimal Solidity contract. - -[![Live app](https://img.shields.io/badge/live-proof.kovina.org-0052FF?style=for-the-badge)](https://proof.kovina.org) -[![CI](https://img.shields.io/github/actions/workflow/status/sparshsam/openproof/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/sparshsam/openproof/actions/workflows/ci.yml) -[![License: AGPL v3](https://img.shields.io/github/license/sparshsam/openproof?style=for-the-badge)](LICENSE) +
+ OpenProof +

OpenProof

+

Privacy-first proof-of-existence for files.
Timestamp file fingerprints on Base Sepolia without uploading a single byte.

+
+ +[![Live app](https://img.shields.io/badge/website-proof.kovina.org-0052FF?style=for-the-badge)](https://proof.kovina.org) +[![License](https://img.shields.io/github/license/sparshsam/openproof?style=for-the-badge)](LICENSE) [![Built on Base Sepolia](https://img.shields.io/badge/Built%20on-Base%20Sepolia-0052FF?style=for-the-badge)](https://sepolia.basescan.org/address/0x60d3DD631E6e4F6D76f761689d6FA229945a874a) +[![Source Code](https://img.shields.io/badge/Source%20Code-GitHub-181717?style=for-the-badge&logo=github)](https://github.com/sparshsam/openproof) -![OpenProof landing page](assets/screenshot-main.png) +## Hero -## Quick Links +![OpenProof landing page](assets/hero/hero.png) -- [Live app](https://proof.kovina.org) -- [BaseScan contract](https://sepolia.basescan.org/address/0x60d3DD631E6e4F6D76f761689d6FA229945a874a) -- [Architecture](docs/ARCHITECTURE.md) -- [Receipt specification](docs/spec/receipt-specification.md) -- [JSON Schema](docs/spec/openproof-receipt-schema.json) -- [Test vectors](docs/spec/openproof-test-vectors.md) -- [Threat model](docs/threat-model.md) -- [Security policy](SECURITY.md) -- [Contributing](CONTRIBUTING.md) -- [Privacy policy](docs/PRIVACY.md) -- [Terms of service](docs/TERMS.md) -- [Platform readiness](docs/PLATFORM_READINESS.md) -- [Changelog](CHANGELOG.md) - -## What OpenProof Does - -OpenProof creates a verifiable timestamp for a file hash: - -1. Select a file in the browser. -2. OpenProof hashes the file locally using SHA-256. -3. Connect a wallet on Base Sepolia. -4. Register only the hash in `OpenProofRegistry`. -5. Download a local JSON receipt or share the proof page. -6. Verify later by hashing the exact same file again. - -No file uploads. No server-side storage. No database. No IPFS dependency for the MVP. - -## Screenshots +## Gallery | Create proof | Verify proof | -| --- | --- | -| ![Create proof screen](assets/screenshot-create.png) | ![Verify proof screen](assets/screenshot-verify.png) | - -Additional screenshots are available in [`public/screenshots`](public/screenshots). - -## Features - -| Feature | Status | Notes | -| --- | --- | --- | -| Local SHA-256 hashing | Available | Uses the browser Web Crypto API. File bytes stay local. | -| Proof registration | Available | Registers `bytes32` hashes on Base Sepolia. | -| Proof verification | Available | Re-hashes local files and checks the registry. | -| JSON proof receipts | Available | Generated and downloaded locally; never uploaded by OpenProof. | -| Receipt import | Available | Validates OpenProof receipt JSON and checks the hash onchain. | -| Local proof history | Available | Stored only in browser local storage. | -| Public proof pages | Available | `/proof/[hash]` reads public registry state. | -| QR verification | Available | Encodes the proof page URL, not the file. | -| Bundle proofs | Available | Deterministic combined hash for multiple local files. | -| Base mainnet | Roadmap | Current MVP is Base Sepolia testnet only. | - -## Built on Base Sepolia - -OpenProof v0 uses Base Sepolia so contributors and users can test the proof flow without real funds. - -- Chain: Base Sepolia -- Chain ID: `84532` -- Explorer: [BaseScan Sepolia](https://sepolia.basescan.org) -- Registry contract: [`0x60d3DD631E6e4F6D76f761689d6FA229945a874a`](https://sepolia.basescan.org/address/0x60d3DD631E6e4F6D76f761689d6FA229945a874a) - -The current public app is a testnet proof-of-existence utility. Base mainnet deployment is a roadmap item, not a current production claim. - -## Privacy Model - -OpenProof is designed around local-first proof creation: - -- Files are read through the browser File API. -- Hashing happens locally with the Web Crypto API. -- Only the SHA-256 hash is sent to the smart contract. -- Receipts are local JSON downloads. -- Recent proof history stays in browser local storage. -- There is no backend upload endpoint, database, storage bucket, or account system. - -Important caveat: public hashes can leak information if the original file is already known, small, or easy to guess. Do not register hashes for sensitive guessable content without understanding that risk. - -## Security Notes - -OpenProof proves that a matching hash was registered by a wallet at a recorded chain timestamp. It does not prove authorship, ownership, lawful possession, legal validity, or the truth of a file's contents. - -If the original file is lost, OpenProof cannot recover it. The chain stores only the hash. - -Do not use OpenProof for legal, financial, medical, compliance, or regulated claims without professional advice. See [`docs/threat-model.md`](docs/threat-model.md) and [`SECURITY.md`](SECURITY.md). - -## Install and Run - -Requirements: - -- Node.js 22 or newer -- npm -- A WalletConnect project ID from Reown Cloud -- Base Sepolia test ETH for contract deployment or proof registration - -```bash -git clone https://github.com/sparshsam/openproof.git -cd openproof -npm install -cp .env.example .env.local -npm run dev -``` +|---|---| +| ![Create proof screen](assets/gallery/screenshot-create.png) | ![Verify proof screen](assets/gallery/screenshot-verify.png) | -Open `http://localhost:3000`. +## Why OpenProof -Fill these values in `.env.local`: +OpenProof creates verifiable timestamps for file hashes. No uploads. No accounts. No database. Select a file, hash it locally with SHA-256, register only the hash on Base Sepolia, and download a portable JSON receipt. Verify later by hashing the exact same file again — no original file ever leaves your device. -```bash -NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID= -NEXT_PUBLIC_CHAIN_ID=84532 -NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS=0x60d3DD631E6e4F6D76f761689d6FA229945a874a -BASE_SEPOLIA_RPC_URL=https://sepolia.base.org -DEPLOYER_PRIVATE_KEY= -``` - -Never commit private keys. `.env` and `.env.local` are ignored by git. - -## Build From Source - -```bash -npm run lint -npm run typecheck -npm run build -npm run test:contracts -``` - -## Tech Stack - -- Next.js 16 -- TypeScript -- Tailwind CSS -- wagmi, viem, RainbowKit -- Solidity and Hardhat -- Base Sepolia -- Vercel - -Contract commands: - -```bash -npm run compile -npm run test:contracts -npm run deploy:base-sepolia -``` - -Deployment requires `BASE_SEPOLIA_RPC_URL` and `DEPLOYER_PRIVATE_KEY` in `.env`. - -## Deploy to Vercel - -OpenProof deploys as a static Next.js app with no backend services required. - -1. Fork or clone this repository. -2. Import it into Vercel. -3. Add the public environment variables: - - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` - - `NEXT_PUBLIC_CHAIN_ID=84532` - - `NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS` -4. Deploy with the default Next.js settings. - -No paid domain, database, storage bucket, file uploads, or IPFS pinning service is required for the MVP. - -## Project Structure - -```text -contracts/ Solidity registry contract -docs/ Architecture, threat model, deployment notes -docs/spec/ Canonical receipt specification, JSON Schema, test vectors -public/screenshots/ App screenshots used by docs and social previews -scripts/ Contract deployment script -src/app/ Next.js App Router pages -src/components/ Reusable UI and wallet components -src/lib/ Hashing, receipts, contracts, history, proof utilities -test/ Hardhat contract tests -``` - -## Roadmap - -OpenProof should remain a small, trustworthy proof utility first. The roadmap expands the proof layer without turning the app into a storage product, marketplace, token system, or legal-tech overclaim. - -### Near-Term - -- **Detached signature support** — let users sign a file hash or receipt with a wallet without necessarily registering a new proof onchain. -- **~~Stronger receipt format~~** ✅ *Delivered in v0.2* — versioned, canonical JSON receipts with deterministic serialization, Ed25519 signatures, and portable verification. See [`docs/spec/receipt-specification.md`](docs/spec/receipt-specification.md). -- **Receipt verification polish** — clearer success, mismatch, unsupported-chain, and malformed-receipt states. -- **~~Better bundle proofs~~** ✅ *Delivered in v0.2* — canonical bundle receipt type with sorted commitments array, deterministically-derived subject hash, and inclusion verification. See [Bundle Proofs §7](docs/spec/receipt-specification.md#7-bundle-proofs). -- **Self-hosting documentation** — clearer deployment notes for Vercel, static hosting, custom RPCs, and self-deployed contracts. -- **Threat-model expansion** — document hash-guessing risks, known-file attacks, metadata leakage, wallet privacy, and timestamp limitations in more accessible language. - -### Mid-Term - -- **Base mainnet deployment** — production registry deployment on Base mainnet after testnet UX and contract assumptions are stable. -- **Reproducible deployment metadata** — publish compiler version, source verification notes, deployment scripts, and deterministic contract metadata. -- **Event indexing options** — provide lightweight indexing paths for larger deployments without making a backend mandatory for the core app. -- **Proof collections** — allow users to group related proofs locally, such as a project folder, evidence bundle, release archive, or creative work package. -- **Portable proof pages** — static, shareable proof pages that can be saved or mirrored without depending on OpenProof hosting forever. -- **Multilingual documentation** — translate core usage, privacy, and risk explanations for broader accessibility. - -### Long-Term Vision - -- **~~Open proof standard~~** ✅ *Initial specification delivered* — the [canonical receipt specification](docs/spec/receipt-specification.md) defines the interoperable proof receipt format. Cross-app adoption and implementation guides are the next layer. -- **Cross-app verification layer** — let tools like local PDF readers, research notebooks, archives, and creator tools anchor proofs through the same receipt model. -- **Organization and project attestations** — optional signing flows for teams, open-source maintainers, journalists, researchers, and creators to prove who anchored a file hash. -- **Proof timelines** — build local timelines showing how a document, folder, release, or bundle changed over time through successive hashes. -- **Public-interest archives** — support verifiable public datasets, civic documents, open research artifacts, and community records without requiring OpenProof to host the underlying files. -- **Offline-first verifier** — a downloadable verifier that can validate receipts and re-hash files without using the hosted web app. - -### What OpenProof Will Not Become - -- No file hosting platform. -- No NFT marketplace. -- No token, rewards, staking, or DeFi layer. -- No claim that a hash proves authorship, ownership, truth, legality, or copyright. -- No mandatory backend, account system, analytics, or file upload pipeline. - -OpenProof uses Base as calm verification infrastructure: public enough to be durable, minimal enough to stay out of the user's way. - -## Future Philosophy - -OpenProof is part of a broader direction: software that helps people prove things without surrendering the thing itself. - -The long-term ecosystem idea is: +## Features -- **Proof before platform** — let users verify existence and integrity without depending on a company database. -- **Privacy before convenience theatre** — never upload files just to make verification feel magical. -- **Local-first by default** — hash, inspect, and verify as much as possible on the user's own device. -- **Permanence without exposure** — use public infrastructure for small fingerprints, not private contents. -- **Interoperable calm tools** — receipts, hashes, and verification flows should work across projects instead of becoming another silo. -- **Base as infrastructure, not speculation** — low-cost public settlement for proofs, not a reason to invent a token. +| Feature | Description | +|---|---| +| **Local SHA-256 hashing** | Files are hashed in-browser via the Web Crypto API. File bytes stay local. | +| **Proof registration** | Register `bytes32` hashes on the Base Sepolia blockchain. | +| **Proof verification** | Re-hash local files and check against the onchain registry. | +| **JSON receipts** | Portable, versioned proof receipts downloaded locally. | +| **Receipt import** | Validate existing receipts and verify hashes onchain. | +| **Local proof history** | Recent proofs stored in browser local storage only. | +| **Public proof pages** | `/proof/[hash]` reads public registry state for sharing. | +| **QR verification** | QR-encode the proof page URL for quick mobile verification. | +| **Bundle proofs** | Deterministic combined hash for multiple local files. | -The immediate goal is simple: create and verify trustworthy file fingerprints. The ambitious goal is an open proof layer that other quiet, privacy-minded tools can rely on. +## Designed For -## Contributing +- **Researchers** — timestamp research data and preprints. +- **Creators** — prove ownership of digital works without uploading. +- **Archivists** — anchor file fingerprints to an immutable chain. +- **Anyone** — who needs to prove a file existed at a certain time. -Contributions are welcome when they preserve the core architecture: local hashing, no file uploads, no mandatory backend, and no speculative token or DeFi features. +## Design Philosophy -Before opening a pull request: +> "Proof before platform — let users verify existence without surrendering the file itself." -```bash -npm run lint -npm run typecheck -npm run build -npm run test:contracts -``` +OpenProof is part of a broader direction: software that helps people prove things without surrendering the thing itself. Local-first by default. Privacy before convenience theatre. Permanence without exposure. -For UI changes, include screenshots. For security-sensitive changes, update the threat model or security policy where relevant. See [`CONTRIBUTING.md`](CONTRIBUTING.md). +## Built With -## Repository Metadata +- [Next.js 16](https://nextjs.org/) +- [TypeScript](https://www.typescriptlang.org/) +- [Tailwind CSS](https://tailwindcss.com/) +- [wagmi](https://wagmi.sh/) / [viem](https://viem.sh/) / [RainbowKit](https://www.rainbowkit.com/) +- [Solidity](https://soliditylang.org/) / [Hardhat](https://hardhat.org/) +- [Base Sepolia](https://base.org/) +- [Vercel](https://vercel.com/) -Recommended GitHub topics: +## Version Journey -```text -base, base-sepolia, built-on-base, onchain, proof-of-existence, ethereum, -solidity, viem, wagmi, rainbowkit, web3, cryptography, privacy-first, -nextjs, typescript, tailwindcss, vercel, agplv3, pwa -``` +| Version | Date | Highlights | +|---|---|---| +| v0.4.0 | 2026-06 | Receipt specification — canonical JSON receipt format with deterministic serialization | +| v0.3.0 | 2026-05 | Bundle proofs — combined hash for multiple files with sorted commitments | +| v0.2.0 | 2026-04 | QR verification — encode proof page URL for mobile verification | +| v0.1.0 | 2026-03 | MVP — basic proof creation, verification, and local history | -## Support +## Quick Links -For bug reports, feature requests, and general support, [open a GitHub issue](https://github.com/sparshsam/openproof/issues). For security vulnerabilities, see the [security policy](SECURITY.md). +- [Live app](https://proof.kovina.org) +- [BaseScan contract](https://sepolia.basescan.org/address/0x60d3DD631E6e4F6D76f761689d6FA229945a874a) +- [Development setup](docs/Development.md) +- [Architecture](docs/Architecture.md) +- [Deployment](docs/Deployment.md) +- [Testing](docs/Testing.md) +- [Contributing](CONTRIBUTING.md) +- [Receipt specification](docs/spec/receipt-specification.md) +- [Threat model](docs/threat-model.md) +- [Privacy policy](docs/PRIVACY.md) +- [Terms of service](docs/TERMS.md) +- [Changelog](CHANGELOG.md) ## License -OpenProof is licensed under AGPL-3.0-only. See [`LICENSE`](LICENSE). +AGPL-3.0-only. See [`LICENSE`](LICENSE). ---- +### Open Collection -*Last updated: 2026-06-21* +| Project | Description | +|---|---| +| [OpenPalette](https://github.com/sparshsam/openpalette) | Accessibility-first color system | +| [OpenSend](https://github.com/sparshsam/opensend) | Encrypted file sharing | +| [OpenSprout](https://github.com/sparshsam/opensprout) | Lightweight project scaffold | +| [OpenTone](https://github.com/sparshsam/opentone) | Minimal audio tools | +| **OpenProof (you are here)** | Privacy-first proof-of-existence | diff --git a/assets/branding/icon.svg b/assets/branding/icon.svg new file mode 100644 index 0000000..fc9aa95 --- /dev/null +++ b/assets/branding/icon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/branding/og.png b/assets/branding/og.png new file mode 100644 index 0000000..8911c16 Binary files /dev/null and b/assets/branding/og.png differ diff --git a/assets/gallery/create-desktop.png b/assets/gallery/create-desktop.png new file mode 100644 index 0000000..6ea6d68 Binary files /dev/null and b/assets/gallery/create-desktop.png differ diff --git a/assets/gallery/create-mobile.png b/assets/gallery/create-mobile.png new file mode 100644 index 0000000..6aaa2fa Binary files /dev/null and b/assets/gallery/create-mobile.png differ diff --git a/assets/gallery/home-desktop.png b/assets/gallery/home-desktop.png new file mode 100644 index 0000000..bcaa2cd Binary files /dev/null and b/assets/gallery/home-desktop.png differ diff --git a/assets/gallery/proof-desktop.png b/assets/gallery/proof-desktop.png new file mode 100644 index 0000000..a9bd05e Binary files /dev/null and b/assets/gallery/proof-desktop.png differ diff --git a/assets/gallery/screenshot-create.png b/assets/gallery/screenshot-create.png new file mode 100644 index 0000000..6ea6d68 Binary files /dev/null and b/assets/gallery/screenshot-create.png differ diff --git a/assets/gallery/screenshot-verify.png b/assets/gallery/screenshot-verify.png new file mode 100644 index 0000000..4139fe0 Binary files /dev/null and b/assets/gallery/screenshot-verify.png differ diff --git a/assets/gallery/verify-desktop.png b/assets/gallery/verify-desktop.png new file mode 100644 index 0000000..4139fe0 Binary files /dev/null and b/assets/gallery/verify-desktop.png differ diff --git a/assets/hero/hero.png b/assets/hero/hero.png new file mode 100644 index 0000000..bcaa2cd Binary files /dev/null and b/assets/hero/hero.png differ diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 0000000..0a656ef --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,13 @@ +# Architecture + +The canonical architecture document is at [`docs/ARCHITECTURE.md`](ARCHITECTURE.md). + +For additional architectural context, see: + +- [Architectural Invariants](ARCHITECTURAL_INVARIANTS.md) +- [Data Flow](DATA_FLOW.md) +- [Trust Model](TRUST_MODEL.md) +- [Trust Boundaries](TRUST_BOUNDARIES.md) +- [Failure Modes](FAILURE_MODES.md) +- [Design Restraints](DESIGN_RESTRAINTS.md) +- [Systems Doctrine](SYSTEMS_DOCTRINE.md) diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 0000000..f0c4a79 --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,52 @@ +# Contributing to OpenProof + +Thank you for your interest in OpenProof. The project is intentionally small, privacy-first, and zero-backend for the MVP. + +## Quick Start + +See [`docs/Development.md`](Development.md) for full setup instructions. + +## Before Submitting a Pull Request + +```bash +npm run lint +npm run typecheck +npm run build +npm run test:contracts +``` + +For UI changes, include screenshots. For security-sensitive changes, update the threat model or security policy. + +## Product Boundaries + +- Hash files locally in the browser. +- Register only hashes on Base Sepolia. +- Avoid server-side file uploads, databases, storage buckets, accounts, or IPFS. +- Do not add tokens, NFTs, staking, DeFi, social feeds, or ownership/legal overclaims. +- Do not commit private keys, wallet secrets, or deployment credentials. + +## Pull Request Guidelines + +- Short description of the change. +- Commands used to validate it. +- Screenshots for UI changes. +- Updated documentation for behavior, setup, or security changes. +- Focused scope; unrelated refactors in separate PRs. + +## Commit Style + +Use clear, practical commit messages: + +```text +Improve receipt import validation +Add proof explorer empty state +Harden Base Sepolia network handling +``` + +## License + +By contributing, you agree that your contributions are licensed under AGPL-3.0-only. + +--- + +*For the full contributing guide, see [`CONTRIBUTING.md`](../CONTRIBUTING.md) at the repository root.* diff --git a/docs/Deployment.md b/docs/Deployment.md new file mode 100644 index 0000000..bbce60d --- /dev/null +++ b/docs/Deployment.md @@ -0,0 +1,27 @@ +# Deployment + +OpenProof deploys as a static Next.js app with no backend services required. + +## Deploy to Vercel + +1. Fork or clone this repository. +2. Import it into [Vercel](https://vercel.com). +3. Add the public environment variables: + - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` + - `NEXT_PUBLIC_CHAIN_ID=84532` + - `NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS` +4. Deploy with the default Next.js settings. + +No paid domain, database, storage bucket, file uploads, or IPFS pinning service is required for the MVP. + +## Contract Deployment + +```bash +npm run compile +npm run test:contracts +npm run deploy:base-sepolia +``` + +Contract deployment requires `BASE_SEPOLIA_RPC_URL` and `DEPLOYER_PRIVATE_KEY` in `.env`. + +For additional deployment notes, see [`docs/deployment-notes.md`](deployment-notes.md). diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..e760da3 --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,56 @@ +# Development + +## Prerequisites + +- Node.js 22 or newer +- npm +- A WalletConnect project ID from [Reown Cloud](https://cloud.reown.com/) +- Base Sepolia test ETH for contract deployment or proof registration + +## Setup + +```bash +git clone https://github.com/sparshsam/openproof.git +cd openproof +npm install +cp .env.example .env.local +npm run dev +``` + +Open `http://localhost:3000`. + +## Environment Variables + +Fill these values in `.env.local`: + +| Variable | Description | +|---|---| +| `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` | WalletConnect project ID (required) | +| `NEXT_PUBLIC_CHAIN_ID` | Chain ID — set to `84532` for Base Sepolia | +| `NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS` | Deployed registry contract address | +| `BASE_SEPOLIA_RPC_URL` | RPC URL for Base Sepolia (`https://sepolia.base.org`) | +| `DEPLOYER_PRIVATE_KEY` | Private key for contract deployment (never commit) | + +Never commit private keys. `.env` and `.env.local` are ignored by git. + +## Useful Commands + +```bash +npm run dev # Start development server +npm run lint # Run ESLint +npm run typecheck # Run TypeScript type checking +npm run build # Production build +npm run compile # Compile Solidity contracts +npm run test:contracts # Run Hardhat contract tests +npm run deploy:base-sepolia # Deploy registry contract +``` + +## Contract Commands + +```bash +npm run compile # Compile Solidity contracts +npm run test:contracts # Run contract tests +npm run deploy:base-sepolia # Deploy to Base Sepolia +``` + +Deployment requires `BASE_SEPOLIA_RPC_URL` and `DEPLOYER_PRIVATE_KEY` in `.env`. diff --git a/docs/Testing.md b/docs/Testing.md new file mode 100644 index 0000000..193c9dd --- /dev/null +++ b/docs/Testing.md @@ -0,0 +1,41 @@ +# Testing + +Run these checks before submitting a pull request: + +## Lint + +```bash +npm run lint +``` + +Runs ESLint across the codebase. + +## TypeScript Type Checking + +```bash +npm run typecheck +``` + +Ensures all TypeScript types are correct. + +## Production Build + +```bash +npm run build +``` + +Verifies the Next.js app builds without errors. + +## Contract Tests + +```bash +npm run test:contracts +``` + +Runs Hardhat tests for the Solidity registry contract. + +## All Checks in One Command + +```bash +npm run lint && npm run typecheck && npm run build && npm run test:contracts +```