SipHeron-VDR/vdr-core
GitHub: SipHeron-VDR/vdr-core
基于 Solana 区块链的文档公证与验证 SDK，支持直接链上锚定文档哈希并提供永久不可篡改的真实性验证能力。
Stars: 2 | Forks: 1
@sipheron/vdr-core
The Cryptographic Engine of SipHeron VDR.
SipHeron VDR 是一种将文档永久公证到 Solana 区块链的协议。
`@sipheron/vdr-core` 是独立的基础 SDK，允许开发者与 Solana 上的 SipHeron 智能合约进行交互 —— 可以完全独立进行（无需 API 密钥），也可以通过托管的 SipHeron 平台进行。
## 架构可视化
```
@sipheron/vdr-core
│
├── DIRECT (no SipHeron account needed)
│ ├── hashDocument() — SHA-256 client-side
│ ├── anchorToSolana() — Direct blockchain write
│ ├── verifyOnChain() — Direct blockchain read
│ ├── deriveAnchorAddress() — PDA derivation
│ └── verifyWebhookSignature() — HMAC verification
│
└── HOSTED (SipHeron API key required)
└── SipHeron (Client)
├── anchors.create()
├── anchors.get()
├── verify.check()
```
DIRECT（直连）与 HOSTED（托管）之间的区分是经过深思熟虑的。任何精明的买家或外部审计员都可以查看 `vdr-core` 中的开源实现，并确认我们提供的是**真正的、自主的加密独立性**。`anchorToSolana()` 和 `verifyOnChain()` 纯粹通过 RPC 节点工作。通过利用我们的托管功能，您只会获得便利 —— 元数据、证书、仪表板和合规性功能 —— 而无需放弃区块链的基本承诺。
## 安装
```
npm install @sipheron/vdr-core
# 以及使用 Direct On-Chain functions 时的 peer dependency
npm install @solana/web3.js
```
## 1. 直接链上使用（开源）
无需 API 密钥，无需月费（除 Solana gas 费用外），无需仪表板。您直接与不可变的智能合约进行交互。
### A. 文档哈希处理（客户端）
所有内容均在客户端生成，以确保文档在未哈希处理的情况下永远不会触及外部服务器。
```
import { hashDocument, hashFile, hashStream, hashBase64 } from '@sipheron/vdr-core'
// Browser: File / Blob
const hash1 = await hashDocument(fileBuffer)
// Node.js: Disc files
const hash2 = await hashFile('/path/to/contract.pdf')
// Streams (Node or Web Streams)
const hash3 = await hashStream(readableStream)
// APIs: Base64
const hash4 = await hashBase64('JVBERi0xLjQKJcOkw...')
```
### B. 直接锚定到 Solana
您需要提供自己的 Solana Keypair。该库通过 JSON RPC 直接链上调用 SipHeron 合约。
```
import { anchorToSolana } from '@sipheron/vdr-core'
import { Keypair } from '@solana/web3.js'
const issuerKeypair = Keypair.fromSecretKey(...) // Your wallet
const result = await anchorToSolana({
buffer: fileBuffer,
keypair: issuerKeypair,
network: 'mainnet',
metadata: 'My Private Contract v1.2'
})
console.log('Record PDA Address:', result.pda)
console.log('Solana Transaction:', result.explorerUrl)
```
### C. 直接链上验证
通过显式解析程序数据账户来查找您的锚点。
```
import { verifyOnChain, deriveAnchorAddress } from '@sipheron/vdr-core'
const check = await verifyOnChain({
hash: documentHash,
network: 'mainnet',
ownerPublicKey: issuerKeypair.publicKey
})
console.log(check.authentic) // true if hash matches and not revoked
```
### D. Webhook 验证
如果您的服务器接收到 SipHeron Webhooks（在使用托管平台时），请使用恒定时间比较法以加密方式手动验证签名。
```
import { parseWebhookEvent } from '@sipheron/vdr-core'
const event = parseWebhookEvent({
body: rawRequestBody,
signature: req.headers['x-sipheron-signature'],
secret: process.env.SIPHERON_WEBHOOK_SECRET
})
console.log(event.type) // 'anchor.confirmed'
```
## 2. 托管平台使用（SipHeron Client）
对于希望集成 SaaS 功能（生成 PDF 证书、维护托管分析仪表板、获取托管合规日志）的开发者，SDK 通过我们的便捷包装器 API 暴露了完全相同的逻辑。
```
import { SipHeron } from '@sipheron/vdr-core'
// 1. Initialize client
const sipheron = new SipHeron({
apiKey: process.env.SIPHERON_API_KEY,
network: 'devnet' // or 'mainnet'
})
// 2. Wrap and anchor via Platform
const record = await sipheron.anchors.create({
file: documentBuffer,
name: 'Employment Verification'
})
console.log('Certificate URL:', record.verificationUrl)
// 3. Batch Verification API
const verification = await sipheron.verify.check({ file: documentBuffer })
```
## 错误处理
简洁、一致且程序化的错误类。
```
import {
SipHeronError,
SolanaConnectionError,
TransactionError,
HashMismatchError
} from '@sipheron/vdr-core'
try {
await anchorToSolana(...)
} catch (err) {
if (err instanceof TransactionError) {
console.log('Wallet rejected or Tx dropped')
}
}
```
## 交互式工作室示例
如果您希望在视觉上完全测试直接引擎，我们在 `examples` 目录中内置了一个精美的交互式工作室：
```
cd examples/vdr-studio
npm install
node server.js
```
导航到 `http://localhost:3050`，即可拖放安全文档、生成 PDA、完全在客户端进行哈希处理，并直接在 Solana 上进行验证/锚定。
## 构建
```
npm run build
```
## 许可证与安全
开源 SDK 根据标准的 Apache-2.0 授权。如需报告与哈希/Webhook 签名相关的安全漏洞或计时攻击 bug，请通过 `security@sipheron.com` 进行协调。
标签：DNS 反向解析, HMAC, HTTP工具, PDA, Rust, SHA-256, Solana, Web3, Zenmap, 不可抵赖性, 公证服务, 区块链, 去中心化, 密码学, 手动系统调用, 数字指纹, 数据可视化, 数据完整性, 文档验证, 智能合约, 电子取证, 网络流量审计, 自动化攻击, 防篡改