Metadata-Version: 2.4
Name: deepseek-pow
Version: 0.0.1
Summary: DeepSeek PoW challenge solver.
Author-email: Jerry <wujr24@m.fudan.edu.cn>
License: MIT
Project-URL: Homepage, https://github.com/Jerry-Wu-GitHub/deepseek-pow
Project-URL: Repository, https://github.com/Jerry-Wu-GitHub/deepseek-pow.git
Keywords: deepseek,proof-of-work,pow,wasm,wasmtime
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic
Requires-Dist: wasmtime
Dynamic: license-file

# deepseek-pow

[![PyPI](https://img.shields.io/pypi/v/deepseek-pow.svg)](https://pypi.org/project/deepseek-pow/)
[![Python](https://img.shields.io/pypi/pyversions/deepseek-pow.svg)](https://pypi.org/project/deepseek-pow/)
[![License](https://img.shields.io/pypi/l/deepseek-pow.svg)](LICENSE)

一个用于求解 DeepSeek Proof-of-Work challenge 的非官方 Python 库。

`deepseek-pow` 使用 Wasmtime 执行随包提供的 WebAssembly 求解器，并根据服务端返回的算法名称自动选择对应的算法实现。项目采用可扩展的求解器注册机制，以便将来支持 `DeepSeekHashV2` 等新版本。

> [!IMPORTANT]
> 本项目是非官方项目，与 DeepSeek 没有隶属、授权或合作关系。使用本项目时，请遵守相关服务条款及适用法律。

## 功能

- 支持 `DeepSeekHashV1`
- 使用 Wasmtime 执行 WASM 求解逻辑
- 根据算法名称自动选择求解器
- 提供结构化的 `Challenge` 和 `Solution` 数据模型
- 支持将求解结果转换为接近浏览器 Worker 输出的字典
- 提供统一的异常类型
- 支持注册自定义算法求解器
- 为未来的 `DeepSeekHashV2` 等算法预留扩展机制
- 提供类型注解

## 环境要求

- Python 3.10 或更高版本
- Wasmtime
- Pydantic

## 安装

从 PyPI 安装：

```bash
pip install deepseek-pow
```

从源代码安装：

```bash
git clone https://github.com/Jerry-Wu-GitHub/deepseek-pow.git
cd deepseek-pow
pip install .
```

开发模式安装：

```bash
pip install -e .
```

## 快速开始

创建 `Challenge`，根据算法名称取得求解器，然后调用 `solve()`：

```python
from deepseek_pow import Challenge, registry

challenge = Challenge(
    algorithm="DeepSeekHashV1",
    challenge=(
        "137790920b51f1247ee5defbdafc37a69bfaead6ace853587"
        "15592965396c943"
    ),
    salt="c3c3df94a0a803586dab",
    difficulty=144000,
    expire_at=1783681627181,
    signature="signature-from-server",
)

solver = registry.get(challenge.algorithm)
solution = solver.solve(challenge)

print(solution.answer)
```

处理多个 challenge 时，建议复用同一个求解器实例。

## 生成答案载荷

`Solution.to_answer_payload()` 会返回与浏览器 PoW Worker 输出结构接近的字典：

```python
payload = solution.to_answer_payload()

print(payload)
```

结果结构如下：

```python
{
    "algorithm": "DeepSeekHashV1",
    "challenge": "137790920b51f1247ee5defbdafc37a69bfaead6ace85358715592965396c943",
    "salt": "c3c3df94a0a803586dab",
    "answer": 123456.0,
    "signature": "signature-from-server",
}
```

## 直接使用 V1 求解器

除了全局注册表，也可以直接创建 `DeepSeekHashV1Solver`：

```python
from deepseek_pow.models import Challenge
from deepseek_pow.solvers import DeepSeekHashV1Solver

challenge = Challenge(
    algorithm="DeepSeekHashV1",
    challenge="your-challenge",
    salt="your-salt",
    difficulty=144000,
    expire_at=1783681627181,
)

solver = DeepSeekHashV1Solver()
solution = solver.solve(challenge)

print(solution.answer)
```

## 异常处理

库的公开异常都继承自 `DeepSeekPowError`：

```python
from deepseek_pow import Challenge, registry
from deepseek_pow.exceptions import (
    DeepSeekPowError,
    NoSolutionError,
    UnsupportedAlgorithmError,
    WasmLoadError,
)

try:
    challenge = Challenge(
        algorithm="DeepSeekHashV1",
        challenge="your-challenge",
        salt="your-salt",
        difficulty=144000,
        expire_at=1783681627181,
    )

    solver = registry.get(challenge.algorithm)
    solution = solver.solve(challenge)
except UnsupportedAlgorithmError as exc:
    print(f"不支持的算法: {exc}")
except WasmLoadError as exc:
    print(f"WASM 加载失败: {exc}")
except NoSolutionError as exc:
    print(f"没有找到有效答案: {exc}")
except DeepSeekPowError as exc:
    print(f"PoW 求解失败: {exc}")
```

异常类型如下：

| 异常                        | 说明                                   |
| --------------------------- | -------------------------------------- |
| `DeepSeekPowError`          | 所有公开库异常的基类                   |
| `InvalidChallengeError`     | challenge 字段缺失、类型错误或取值无效 |
| `UnsupportedAlgorithmError` | 算法尚未得到支持                       |
| `WasmLoadError`             | WASM 文件加载、实例化或导出解析失败    |
| `NoSolutionError`           | 求解器没有找到有效答案                 |
| `SolverRuntimeError`        | 求解期间发生内存访问或运行时错误       |

Pydantic 的数据验证异常不继承 `DeepSeekPowError`。创建无效 `Challenge` 时，如需单独处理验证错误，可以捕获 `pydantic.ValidationError`：

```python
from pydantic import ValidationError

try:
    challenge = Challenge(
        algorithm="DeepSeekHashV1",
        challenge=123,
        salt="salt",
        difficulty=144000,
        expire_at=1783681627181,
    )
except ValidationError as exc:
    print(exc)
```

## 支持的算法

| 算法标识         | 求解器                 | 状态 |
| ---------------- | ---------------------- | ---- |
| `DeepSeekHashV1` | `DeepSeekHashV1Solver` | 支持 |

遇到尚未注册的算法时：

```python
solver = registry.get("UnsupportedDeepSeekHash")
```

将抛出：

```text
UnsupportedAlgorithmError: 不支持的 PoW 算法: UnsupportedDeepSeekHash
```

## 注册自定义算法

自定义求解器需要继承 `BaseSolver`，设置唯一的 `name`，并实现 `solve()`：

```python
from typing import override

from deepseek_pow import BaseSolver, Challenge, Solution, registry


class CustomSolver(BaseSolver):
    """自定义 PoW 算法求解器。"""

    name = "CustomHashV1"

    @override
    def solve(self, challenge: Challenge) -> Solution:
        """求解自定义算法的 challenge。

        Parameters:
            challenge:
                待求解的 challenge。

        Returns:
            自定义算法的求解结果。
        """
        answer = 0.0

        return Solution(
            algorithm=self.name,
            challenge=challenge.challenge,
            salt=challenge.salt,
            answer=answer,
            signature=challenge.signature,
        )


registry.register(CustomSolver())

challenge = Challenge(
    algorithm="CustomHashV1",
    challenge="custom-challenge",
    salt="custom-salt",
    difficulty=1,
    expire_at=1783681627181,
)

solution = registry.get(challenge.algorithm).solve(challenge)
print(solution.answer)
```

注册相同名称的新求解器会替换现有实现。

也可以使用独立注册表，避免修改全局 `registry`：

```python
from deepseek_pow import AlgorithmRegistry

custom_registry = AlgorithmRegistry()
custom_registry.register(CustomSolver())

solver = custom_registry.get("CustomHashV1")
```

## 性能建议

### 复用求解器

创建 `DeepSeekHashV1Solver` 时需要加载并实例化 WASM。对于多个 challenge，请复用求解器：

```python
solver = registry.get("DeepSeekHashV1")

for challenge in challenges:
    solution = solver.solve(challenge)
```

全局 `registry` 在导入时已经创建并注册内置求解器，因此通过它获取同一算法时会复用对应实例。

### 线程安全

一个 `DeepSeekHashV1Solver` 实例包含可变的 Wasmtime Store、WASM 线性内存和栈指针，**不应被多个线程同时调用**。

多线程程序应为每个线程创建独立求解器：

```python
def worker(challenge: Challenge) -> Solution:
    solver = DeepSeekHashV1Solver()
    return solver.solve(challenge)
```

### 冷启动和稳态性能

首次创建求解器时需要读取并编译 WASM。后续调用会复用已经实例化的模块，因此稳态性能通常明显优于每次重新创建求解器。

## 安全与使用范围

本项目只负责对调用方提供的 PoW challenge 进行本地计算，不负责：

- 获取或绕过访问权限
- 绕过账户、身份验证或访问控制
- 规避服务端限制
- 自动化滥用第三方服务
- 保证服务端协议长期兼容

请确保你的使用方式获得授权，并遵守相关服务条款。

## 许可证

本项目基于 [MIT License](LICENSE) 发布。

## 免责声明

DeepSeek 是其各自权利人的商标。本项目是独立开发的非官方工具，不受 DeepSeek 认可、赞助或维护。

服务端的 PoW 协议和算法可能随时变化。本项目不保证对未来协议保持兼容，也不对因使用本项目造成的服务中断、数据损失或其他后果承担责任。
