Skip to content

reclaimprotocol/zkfetch-stellar-example

BranchesTags

Repository files navigation

zkFetch Stellar Example

A comprehensive demonstration of zero-knowledge proof generation and verification using the Reclaim Protocol integrated with the Stellar blockchain. This project showcases how to fetch data from various sources with cryptographic proofs and verify them on-chain using Soroban smart contracts.

Supported Data Sources

This project supports five different data sources for generating zero-knowledge proofs:

1. Stellar Price Data (CoinGecko)

  • Source: CoinGecko API
  • Data: Real-time Stellar (XLM) cryptocurrency price in USD
  • Use Case: Cryptocurrency price verification and trading applications

2. Economic Data (Trading Economics)

  • Source: Trading Economics website
  • Data: Countries GDP data and economic indicators
  • Use Case: Economic analysis and financial reporting

3. Billionaires Data (Forbes)

  • Source: Forbes Real-Time Billionaires API
  • Data: Live billionaire rankings, names, and net worth
  • Use Case: Wealth tracking and financial analytics

4. Weather Data (AccuWeather)

  • Source: AccuWeather NYC weather page
  • Data: Current temperature and city information for New York
  • Use Case: Weather verification and climate applications

5. Sports Data (Goal.com)

  • Source: Goal.com live scores page
  • Data: Live football match scores and team information
  • Use Case: Sports betting verification and match tracking

Features

  • Zero-Knowledge Proof Generation: Generate cryptographic proofs for external API data
  • Stellar Blockchain Integration: Verify proofs on Stellar testnet using Soroban contracts
  • Multi-Source Data Support: Five different data sources with unique extraction patterns
  • Comprehensive Testing: Full test suite with utility function validation
  • Modern Development Setup: ESLint, Prettier, and automated testing
  • CLI Interface: Easy-to-use command-line interface for all operations

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn package manager
  • Stellar testnet account with XLM for transaction fees
  • Basic understanding of blockchain and zero-knowledge proofs

Installation

  1. Clone the repository

    git clone https://github.com/your-username/zkfetch-stellar-example.git
cd zkfetch-stellar-example

  2. Install dependencies

    npm install

  3. Download required ZK files

    npm run download-zk-files

  4. Set up environment variables

    cp .env.example .env
# Edit .env file with your Stellar seedphrase

  5. Run setup script (optional)

    npm run setup

Configuration

Environment Variables

Create a .env file in the project root:

# Stellar Wallet Configuration
SEEDPHRASE=your twelve word seedphrase goes here for stellar wallet generation

# Optional: Override default network settings
# NETWORK_URL=https://horizon-testnet.stellar.org
# SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# CONTRACT_ID=CB5MLBRA5FOCU4ZE557UKHYIKA6ASE6U6ZNK4WVBMWZ7G6IOQMSSWCXQ

Application Configuration

The application uses a centralized configuration system in src/config.js:

  • Reclaim Protocol: APP_ID and APP_SECRET for proof generation
  • Stellar Network: Testnet configuration and contract details
  • API Endpoints: CoinGecko API for price data
  • File Paths: Default locations for proof files

Usage

Command Line Interface

# Generate a new Stellar price proof
npm run request-proof

# Generate a new Trading Economics countries GDP proof
npm run request-trading-economics

# Generate a new Forbes billionaires proof
npm run request-forbes

# Generate a new AccuWeather NYC proof
npm run request-accuweather

# Generate a new Goal.com live scores proof
npm run request-goal

# Verify existing proof on blockchain
npm run verify-proof

# Run complete workflow (request + verify)
npm start workflow

# Display application information
npm start info

Programmatic Usage

import { ZkFetchStellarApp } from './src/index.js';

const app = new ZkFetchStellarApp();

// Request a new Stellar price proof
const stellarProof = await app.requestStellarPriceProof();

// Request a new Trading Economics countries GDP proof
const tradingEconomicsProof = await app.requestTradingEconomicsProof();

// Request a new Forbes billionaires proof
const forbesProof = await app.requestForbesProof();

// Request a new AccuWeather NYC proof
const accuWeatherProof = await app.requestAccuWeatherProof();

// Request a new Goal.com live scores proof
const goalProof = await app.requestGoalProof();

// Verify proof on blockchain
const txHash = await app.verifyProofOnStellar();

// Run complete workflow
const result = await app.runCompleteWorkflow();

Individual Module Usage

import { requestProof } from './src/requestProof.js';
import { verifyProof } from './src/verifyProof.js';

// Request Stellar price proof with custom output path
const stellarProof = await requestProof('./stellar-proof.json', 'stellar');

// Request Trading Economics proof with custom output path
const tradingEconomicsProof = await requestProof('./trading-economics-proof.json', 'trading-economics');

// Request Forbes proof with custom output path
const forbesProof = await requestProof('./forbes-proof.json', 'forbes');

// Request AccuWeather proof with custom output path
const accuWeatherProof = await requestProof('./accuweather-proof.json', 'accuweather');

// Request Goal.com proof with custom output path
const goalProof = await requestProof('./goal-proof.json', 'goal');

// Verify proof with custom file path
const txHash = await verifyProof('./custom-proof.json');

Testing

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Categories

  • Proof Structure Validation: Validates proof format and required fields
  • Signature Verification: Ensures cryptographic signatures are valid
  • Utility Function Tests: Tests all helper functions with edge cases
  • Configuration Tests: Validates application configuration

Project Structure

zkfetch-stellar-example/
├── src/
│   ├── config.js          # Centralized configuration
│   ├── index.js           # Main application entry point
│   ├── requestProof.js     # Proof generation module
│   ├── verifyProof.js      # Blockchain verification module
│   ├── utils.js           # Utility functions
│   └── proof.json         # Generated proof file
├── tests/
│   └── proof.test.js      # Comprehensive test suite
├── scripts/
│   └── setup.js           # Setup automation script
├── .env.example           # Environment variables template
├── .eslintrc.json         # ESLint configuration
├── .prettierrc            # Prettier configuration
├── .gitignore             # Git ignore rules
└── package.json           # Project dependencies and scripts

Development

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Available Scripts

  • npm start - Run main application
  • npm run request-proof - Generate new proof
  • npm run verify-proof - Verify existing proof
  • npm test - Run test suite
  • npm run test:watch - Run tests in watch mode
  • npm run test:coverage - Run tests with coverage
  • npm run lint - Lint code
  • npm run lint:fix - Fix linting issues
  • npm run format - Format code
  • npm run setup - Run setup script

Network Configuration

Stellar Testnet

API Endpoints

How It Works

1. Proof Generation

The application uses the Reclaim Protocol to generate zero-knowledge proofs for multiple data sources:

  1. API Request: Fetches data from the selected source (CoinGecko, Trading Economics, Forbes, AccuWeather, or Goal.com)
  2. Data Extraction: Uses specialized regex patterns to extract relevant information from each source
  3. Proof Generation: Creates cryptographic proof of the extracted data
  4. File Storage: Saves proof to JSON file

2. Proof Verification

The verification process submits proofs to the Stellar blockchain:

  1. Proof Loading: Reads and validates proof file
  2. Data Preparation: Formats proof data for blockchain submission
  3. Transaction Creation: Builds Stellar transaction with Soroban contract call
  4. Blockchain Submission: Signs and submits transaction to testnet

3. Smart Contract Integration

The application interacts with a Soroban smart contract that:

  • Verifies cryptographic signatures
  • Validates proof structure
  • Stores verification results on-chain

Troubleshooting

Common Issues

  1. Missing .env file

    cp .env.example .env
# Edit with your seedphrase

  2. Insufficient XLM balance

    • Ensure your Stellar testnet account has XLM for transaction fees
    • Get testnet XLM from Stellar Friendbot

  3. ZK files not downloaded

    npm run download-zk-files

  4. Network connection issues

    • Check internet connection
    • Verify Stellar testnet is accessible

Error Messages

  • Missing required environment variables: Check your .env file
  • Proof file not found: Run npm run request-proof first
  • Failed to create Stellar wallet: Verify your seedphrase format
  • Transaction failed: Check account balance and network status

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the ISC License - see the LICENSE file for details.

Acknowledgments

Additional Resources

Links

About

No description, website, or topics provided.

Resources

Readme

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages