# EduVerseCredentials

**Repository Path**: lintsinghua/edu-verse-credentials

## Basic Information

- **Project Name**: EduVerseCredentials
- **Description**: EduVerse Credentials是一个基于区块链的去中心化学术和职业凭证系统原型，旨在利用Web3技术提供更安全、隐私保护的数字凭证管理解决方案。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-17
- **Last Updated**: 2025-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="client/src/assets/logo.svg" alt="EduVerse Credentials Logo" width="80" height="80"/>
  
  <h1>EduVerse Credentials</h1>
  <p><strong>🔐 去中心化学术和职业凭证系统</strong></p>
  
  <p>
    <img src="https://img.shields.io/badge/Node.js-%3E%3D%2016.x-brightgreen" alt="Node.js >= 16.x"/>
    <img src="https://img.shields.io/badge/npm-%3E%3D%208.x-blue" alt="npm >= 8.x"/>
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/>
  </p>
</div>

## 📋 项目概述

EduVerse Credentials 是一个基于区块链技术的去中心化学术和职业凭证系统，旨在为教育证书和职业资格提供可验证、安全且隐私保护的数字凭证解决方案。

## 🏗️ 项目结构

项目采用前后端分离的架构：

```
eduverse-credentials/
├── client/              # 前端应用
│   ├── public/          # 静态资源
│   ├── src/             # 前端源代码
│   │   ├── assets/      # 资源文件
│   │   ├── components/  # 组件
│   │   ├── contexts/    # 上下文
│   │   ├── pages/       # 页面
│   │   ├── services/    # 服务
│   │   └── utils/       # 工具函数
│   ├── build/           # 构建输出目录
│   ├── package.json     # 前端依赖配置
│   └── webpack.config.js# Webpack配置
├── server/              # 后端服务
│   ├── src/             # 后端源代码
│   │   ├── api.js       # API路由
│   │   ├── core/        # 核心逻辑
│   │   ├── issuer/      # 发行方模块
│   │   ├── models/      # 数据模型
│   │   ├── schemas/     # 验证模式
│   │   ├── services/    # 服务层
│   │   ├── utils/       # 工具函数
│   │   ├── verifier/    # 验证方模块
│   │   └── wallet/      # 钱包模块
│   ├── circuits/        # 零知识证明电路
│   ├── data/            # 数据存储目录
│   ├── index.js         # 后端入口点
│   └── package.json     # 后端依赖配置
├── docs/                # 项目文档
├── .env.example         # 环境变量示例
├── create-env.sh        # 开发环境配置脚本
├── create-prod-env.sh   # 生产环境配置脚本
└── package.json         # 根项目配置
```

## 🚀 快速开始

### 安装依赖

```bash
# 安装所有依赖（前端和后端）
npm run install:all
```

### 开发模式

```bash
# 同时启动前端和后端
npm run dev

# 仅启动前端
npm run client

# 仅启动后端
npm run server
```

### 生产构建

```bash
# 构建前端
npm run build

# 启动生产服务
npm start
```

## 📚 API文档

后端API可通过以下端点访问：

| 端点 | 描述 |
|------|------|
| `/api` | 主API端点 |
| `/wallet` | 钱包相关API |
| `/issuer` | 发行方相关API |
| `/verifier` | 验证方相关API |
| `/schemas` | 凭证Schema定义 |

## ⚖️ 许可证

MIT

## 💻 核心技术

- **🆔 去中心化身份 (DID)**: 实现符合W3C DID Core v1.0规范的DID方法
- **🔖 可验证凭证 (VC)**: 遵循W3C VC Data Model v2.0标准
- **🔍 零知识证明 (ZKP)**: 通过Polygon ID集成zk-SNARKs实现选择性披露
- **❌ 凭证撤销机制**: 支持W3C Bitstring Status List v1.0和Polygon ID原生撤销机制

## 🧩 系统组件

- **👛 EduVerse钱包**: 用户管理数字身份与凭证的应用
- **🏢 发行方门户**: 凭证发行与管理界面
- **🔍 验证方接口**: 凭证验证与查询API

## 📦 安装与使用

### 环境要求

- Node.js >= 16.x
- npm >= 8.x

### 安装步骤

1. **克隆仓库**
```bash
git clone https://github.com/yourusername/eduverse-credentials.git
cd eduverse-credentials
```

2. **安装所有依赖**
```bash
npm run install:all
```

3. **配置环境变量**
```bash
# 运行环境变量创建脚本
./create-env.sh
# 或手动创建server/.env文件并配置环境变量
```

4. **启动开发服务**
```bash
npm run dev
```

5. **单独启动服务**
```bash
# 仅启动后端
npm run server

# 仅启动前端
npm run client
```

6. **构建前端应用**
```bash
npm run build
```

7. **运行生产服务**
```bash
npm start
```

## 🤝 贡献指南

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建Pull Request

## 🔗 相关资源

- [W3C DID Core v1.0](https://www.w3.org/TR/did-core/)
- [W3C VC Data Model v2.0](https://www.w3.org/TR/vc-data-model-2.0/)
- [Polygon ID](https://polygon.technology/polygon-id)

## 📝 凭证流程使用说明

### 📤 凭证发行和导入流程

1. **发行凭证** 🔖
   - 在"发行方门户"中创建发行方DID (如果尚未创建)
   - 创建Schema (或选择已有Schema)
   - 在"凭证发行"选项卡中填写凭证信息，包括接收方DID和属性值
   - 点击"发行凭证"按钮
   - 凭证发行成功后，会出现凭证预览和复制选项

2. **导入凭证** 📥
   - **方法一**: 在凭证发行成功后，点击"复制凭证JSON"按钮，然后切换到"钱包">"导入凭证"页面，粘贴JSON数据并提交
   - **方法二**: 在凭证发行成功后，点击"打开导入页面"按钮，系统会自动打开导入页面并预填充凭证数据
   - **方法三**: 手动打开"钱包"应用，点击"导入凭证"按钮或使用菜单进入导入页面，粘贴凭证JSON数据

3. **使用凭证** 🔑
   - 成功导入凭证后，可在"凭证管理"页面查看所有凭证
   - 点击凭证可查看详情、生成证明或进行其他操作

## 🔍 凭证验证功能使用说明

EduVerse Credentials系统提供了丰富的凭证验证功能，支持多种验证方式和验证场景。

### 🧪 验证功能类型

1. **可验证演示(VP)验证** ✅
   - 验证带有签名或零知识证明的完整可验证演示
   - 可以验证与特定请求相关联的挑战，防止重放攻击
   - 支持多种零知识证明电路(如年龄证明、学位证明等)

2. **批量验证** 🔄
   - 一次性验证多个可验证演示
   - 适用于需要处理多个用户凭证的场景
   - 提供整体验证结果和单个凭证的详细验证状态

3. **直接凭证验证** 📋
   - 无需VP包装，直接验证单个可验证凭证(VC)
   - 验证凭证签名、撤销状态和过期时间
   - 对特殊类型凭证(如公钥凭证)进行专门验证

### 📋 使用步骤

#### 1. 创建验证请求 📝

系统支持三种不同类型的验证请求:

- **年龄证明请求** 🔞
  - 设置最小年龄要求
  - 可选择限定允许的发行方

- **学位证明请求** 🎓
  - 设置学位类型(如学士、硕士、博士)
  - 可选择指定专业和允许的发行方

- **MTP证明请求** 🔰
  - 通用验证请求，证明持有者拥有特定类型凭证且未被撤销
  - 设置凭证类型和Schema URL
  - 可选择限定允许的发行方

#### 2. 验证凭证 🔍

三种验证方式:

- **单个VP验证**:
  1. 切换到"验证凭证"标签页，选择"验证单个演示(VP)"
  2. 如有关联请求，选择对应的请求ID
  3. 粘贴VP JSON数据
  4. 点击"验证演示"按钮

- **批量验证**:
  1. 切换到"验证凭证"标签页，选择"批量验证"
  2. 粘贴VP数组JSON数据(格式见页面说明)
  3. 点击"批量验证"按钮

- **直接验证凭证**:
  1. 切换到"验证凭证"标签页，选择"直接验证凭证(VC)"
  2. 粘贴VC JSON数据
  3. 点击"验证凭证"按钮

#### 3. 查看验证结果 📊

所有验证结果会自动添加到"验证历史"标签页，包含:

- 验证ID
- 验证时间
- 持有者DID
- 验证结果(成功/失败)
- 详细验证信息(可点击查看)

点击"查看详情"按钮可查看完整验证报告，包括:
- 基本信息
- 验证检查项(VP签名、ZKP、凭证签名等)
- 包含的凭证验证状态
- 错误信息(如有)

## ⚙️ 开发环境配置

### 环境变量设置

为了正确运行EduVerse Credentials系统，需要设置以下环境变量（创建一个`.env`文件在项目根目录）：

```bash
# 基本配置
PORT=3000
NODE_ENV=development

# Polygon ID SDK配置
CIRCUITS_PATH=./circuits             # 零知识证明电路文件路径
DATA_STORAGE_PATH=./data             # 数据存储路径

# Polygon Amoy测试网配置
POLYGON_AMOY_RPC_URL=https://polygon-amoy.blockpi.network/v1/rpc/public  # Polygon测试网RPC
STATE_CONTRACT_ADDRESS=0x134B1BE34911E39A8397ec6289782989729807a4        # 状态合约地址

# 状态列表服务配置
STATUS_LIST_BASE_URL=http://localhost:3000/credentials/status             # 撤销状态列表访问URL前缀

# RHS (Reverse Hash Service) 配置
RHS_URL=https://rhs-staging.polygonid.me                                  # Polygon ID的RHS服务URL
```

### ⚠️ SDK初始化问题解决

在首次运行系统时，可能会出现SDK初始化失败的问题，主要表现为：

1. EthStateStorage初始化失败
2. 系统自动回退到使用模拟SDK

**解决方法**：

1. **检查RPC配置**：确保`POLYGON_AMOY_RPC_URL`指向有效的Polygon Amoy测试网RPC节点。
   可使用以下公共RPC节点替代：
   - `https://rpc-amoy.polygon.technology/`
   - `https://polygon-amoy.blockpi.network/v1/rpc/public`
   - `https://polygon-amoy.g.alchemy.com/v2/YOUR_API_KEY`（需使用自己的Alchemy API KEY）

2. **检查状态合约地址**：确保`STATE_CONTRACT_ADDRESS`设置正确。对于Amoy测试网，可以使用官方提供的合约地址。

3. **电路文件**：首次运行前，确保`circuits`目录存在并包含必要的电路文件。如果没有，系统将自动使用模拟实现。

4. **手动指定模拟模式**：如果只需要开发测试，可以注释掉真实SDK的加载代码，直接使用模拟SDK：
   ```javascript
   // 在src/utils/sdk-init.js中
   let polygonSDK = null; // 强制使用模拟SDK
   ```