EarnProof Contracts

EarnProof is an open-source, privacy-focused income and payment verification protocol built on Stellar.

This repository contains the Soroban contracts that support issuer trust, proof commitments, revocation status, and protocol configuration for EarnProof.

Product Role

The contracts provide public status and trust primitives without storing private income data on-chain.

Contracts should answer questions such as:

• Is this issuer active?
• Was this proof commitment registered?
• Has this proof been revoked?
• Is this schema version approved?
• Are sensitive protocol operations paused?

Contracts must not calculate income, store salaries, store raw payment history, or custody user funds.

Current Scope

Implemented:

• Rust workspace
• Shared on-chain record types
• protocol-config contract
• issuer-registry contract with issuer registration, status transitions, address rotation, and lookup helpers
• proof-registry contract with proof registration, expiration validation, revocation state, issuer checks, protocol pause checks, schema approval checks, and lookup helpers
• Typed protocol configuration events
• Storage TTL extension policy for durable and temporary entries
• Testnet deployment scripts using stellar contract build, issuer registration, and manifest validation
• Contract tests exercise authorization through Soroban mocked auth instead of compiling out require_auth
• Buildable contract crates against soroban-sdk
• Code-linked lifecycle invariants in docs/invariants/
• Deterministic ledger-time boundary tests and backend encoding vectors
• Generated API reference in docs/reference/

The protocol-config contract currently supports:

• initialize
• get_admin
• set_admin
• pause
• unpause
• is_paused
• approve_schema_version
• deprecate_schema_version
• is_schema_version_approved
• get_config_version

Next:

• Run backend contract anchoring against deployed contract IDs
• Publish explorer links for deployment and proof lifecycle transactions

Tech Stack

• Rust
• Soroban SDK
• Stellar testnet

Repository Structure

contracts/
  issuer-registry/
  proof-registry/
  protocol-config/
packages/
  shared/
scripts/
tests/
docs/

Local Setup

cargo build
cargo test

Formatting:

cargo fmt --all --check
cargo clippy --workspace --all-targets

Executable Documentation Examples

This repository includes comprehensive, runnable documentation examples that demonstrate how to invoke each contract method. All examples use synthetic identifiers and run in a local Soroban sandbox environment.

Running Documentation Examples

To run all documentation examples:

cargo test --doc --workspace

To run examples for a specific contract:

cargo test --doc protocol_config
cargo test --doc issuer_registry
cargo test --doc proof_registry
cargo test --doc integration

Documentation Example Coverage

Examples are organized by contract and demonstrate:

• Protocol Config — Initialization, schema approval/deprecation, pause operations, admin changes
• Issuer Registry — Issuer registration, lifecycle transitions (suspend/reactivate/revoke), metadata updates, address rotation
• Proof Registry — Proof registration, issuer-initiated and admin revocation, validity checks
• Integration — End-to-end workflows and cross-contract validation (paused protocol blocks registration, suspended issuers block registration, unapproved schemas block registration)

Key Patterns in Examples

Hashing Requirements: All public identifiers must be hashed before passing to contracts:

• proof_id_hash = sha256(proof_id)
• issuer_id_hash = sha256(issuer_id)
• commitment_hash = sha256(canonical_credential_payload)
• metadata_hash = sha256(canonical_public_issuer_metadata)

In examples, we use synthetic BytesN<32> values to represent hashes.

Authorization Patterns:

• Protocol-Config writes require admin authorization
• Issuer-Registry writes require admin authorization
• Proof-Registry writes require issuer authorization (revoke_proof) or admin authorization (admin_revoke_proof)

Lifecycle Patterns:

• Issuer: register (Active) → suspend (Suspended) → reactivate (Active) → revoke (Revoked, terminal)
• Proof: register (Active) → revoke (Revoked, terminal); expiration is implicit

See tests/doc-examples/mod.rs for complete documentation and usage patterns.

Current Validation Status

The repository now pins a stable Rust toolchain in rust-toolchain.toml and CI runs formatting, clippy, tests, and build.

The current test suite covers protocol configuration defaults and schema changes, issuer registration/status transitions/duplicate prevention, proof registration/expiration/revocation/duplicate prevention, cross-contract dependency checks, storage TTL behavior, and authorization paths through mocked Soroban auth.

The current testnet deployment manifest is checked in at scripts/deployment-manifest.testnet.json.

Live testnet contract IDs:

• protocol-config: CC3OREX5QBIKJ5JOW36JFJJW7TLAKJOVT5WJXEITGALO7MU32KHICS2A
• issuer-registry: CB73TVWVJIIVNTKLWSHZB5NL2UIF3B3EUL4YH4MUD6EYX6SFIHE77D2F
• proof-registry: CCMTAXBWN2ZGEDVKGHT6GQENZSTBSLQAGYGGKJWNMDSTVRT2QNMMNWRK

The remaining readiness blocker is live backend anchoring against the deployed proof registry.

The protocol-config contract uses typed #[contractevent] events. Deployment automation is available under scripts/.

On-Chain Privacy Boundary

Contracts must not store:

• Exact salary
• Exact payment amount
• Full wallet history
• Personal name
• Email address
• Employment documents
• Raw transaction lists
• Unencrypted personal information

Contracts may store:

• Proof ID hash
• Commitment hash
• Issuer address
• Status
• Expiration
• Schema version
• Timestamp
• Public metadata hash

Security Requirements

• Authorization checks on every state mutation.
• Duplicate registration prevention.
• Status transitions must be explicit.
• Proof validity must respect expiration and revocation.
• Issuer-backed proof operations must reject inactive issuers.
• Sensitive operations should respect protocol pause state.
• Mainnet deployment should wait for independent review.

Documentation

• Storage Model — every DataKey variant, TTL policy, lifecycle events, and privacy boundaries
• Storage TTL, Expiration, and Restoration — extension triggers, expiry boundaries, restoration behavior, and operator responsibilities
• Storage Namespaces and Key Safety — namespace ownership, key-collision guarantees, durability rules, and the compatibility gate for new keys
• Contract Error Catalog — every error code with its cause, retry classification, and remediation
• Backend Integration — contract calls and hashing rules for the EarnProof API
• Testing — the test suites, and the ledger snapshot regression fixtures with their update procedure
• Threat Model and Security Review Checklist — comprehensive security analysis, threat enumeration, controls, and mainnet release gates

Related Repositories

• earnproof-frontend: Public app, worker dashboard, issuer UI, verifier UI, and admin UI.
• earnproof-backend: API, payment indexing, proof generation, credential signing, and verification.
• earnproof-sdk: Future TypeScript SDK for integrations.
• earnproof-specification: Future credential and verification standard.