143 lines
4.2 KiB
Markdown
143 lines
4.2 KiB
Markdown
# ZXChain SDK 使用文档
|
||
|
||
## 初始化客户端
|
||
|
||
SDK 不主动读取 `.env`，需要自己管理配置，并把凭据传给 SDK。
|
||
|
||
```go
|
||
client, err := zxchainsdk.NewSDKClient(
|
||
os.Getenv("ZXCHAIN_SECRET_ID"),
|
||
os.Getenv("ZXCHAIN_SECRET_KEY"),
|
||
os.Getenv("ZXCHAIN_PRIVATE_KEY"),
|
||
)
|
||
if err != nil {
|
||
log.Fatalf("初始化至信链客户端失败: %v", err)
|
||
}
|
||
```
|
||
|
||
需要的环境变量：
|
||
|
||
- `ZXCHAIN_SECRET_ID`：至信链访问密钥 ID。
|
||
- `ZXCHAIN_SECRET_KEY`：至信链访问密钥。
|
||
- `ZXCHAIN_PRIVATE_KEY`：至信链私钥，用于签名存证请求。
|
||
- `COS_BUCKET_URL`：证书上传 COS 桶地址。
|
||
- `COS_PUBLIC_BASE_URL`：证书公开访问基础地址。
|
||
- `COS_SECRET_ID`：COS 访问密钥 ID。
|
||
- `COS_SECRET_KEY`：COS 访问密钥。
|
||
|
||
## 存证和生成证书并一起返回
|
||
|
||
`h4` 对应 SDK 方法：
|
||
|
||
```go
|
||
CreateSimpleHashAttestationCertificate(ctx, request)
|
||
```
|
||
|
||
它会完成以下流程：
|
||
|
||
```text
|
||
从 WorkPreviewURL 下载作品预览图
|
||
计算作品预览图 EvidenceHash
|
||
生成证据包并计算 SM3 Hash
|
||
调用至信链 Hash 存证
|
||
生成 Popi 证书图片
|
||
上传证书图片到 COS
|
||
返回 evId、txId、区块高度、证书地址等结果
|
||
```
|
||
|
||
示例：
|
||
|
||
```go
|
||
result, err := client.CreateSimpleHashAttestationCertificate(context.Background(), zxchainsdk.SimpleHashAttestationCertificateRequest{
|
||
UserName: "zzzzzq",
|
||
UserID: "56142321",
|
||
WorkName: "测试作品",
|
||
TaskID: "9999999",
|
||
CompletedAt: "2026.5.11 15:20:01",
|
||
WorkPreviewURL: "https://your-cdn/path/work-preview.jpg",
|
||
EvidenceHash: "作品hash", //可选参数，可以不传
|
||
|
||
CertificateStorage: &zxchainsdk.COSCertificateStorage{ //可选参数，可以不传
|
||
BucketURL: os.Getenv("COS_BUCKET_URL"),
|
||
PublicBaseURL: os.Getenv("COS_PUBLIC_BASE_URL"),
|
||
SecretID: os.Getenv("COS_SECRET_ID"),
|
||
SecretKey: os.Getenv("COS_SECRET_KEY"),
|
||
},
|
||
})
|
||
if err != nil {
|
||
log.Fatalf("简化证书生成失败: %v", err)
|
||
}
|
||
|
||
fmt.Println("evId:", result.ReceiptID)
|
||
fmt.Println("txId:", result.RequestID)
|
||
fmt.Println("blockHeight:", result.BlockHeight)
|
||
fmt.Println("txTime:", result.TxTime)
|
||
fmt.Println("sm3Hash:", result.SM3Hash)
|
||
fmt.Println("certificateURL:", result.PopiCertificateCertificateImageURL)
|
||
fmt.Println("zxChainCertURL:", result.ZXChainCertURL)
|
||
```
|
||
|
||
请求参数：
|
||
|
||
- `UserName`：申请用户名称。
|
||
- `UserID`：申请用户 ID。
|
||
- `WorkName`：作品名称。
|
||
- `TaskID`：生成任务 ID。
|
||
- `CompletedAt`：作品完成时间。
|
||
- `WorkPreviewURL`：作品图片 URL。
|
||
- `EvidenceHash`：可选。作品文件哈希；不传时 SDK 会从 `WorkPreviewURL` 下载内容并自行计算hash值。
|
||
- `CertificateStorage`：可选。COS 上传配置。
|
||
|
||
返回字段：
|
||
|
||
- `ReceiptID`：至信链 `evId`，后续给 `h3` 查询使用。
|
||
- `RequestID`：至信链 `txId`。
|
||
- `BlockHeight`：上链区块高度。
|
||
- `TxTime`：上链时间。
|
||
- `SM3Hash`：本次上链证据包的 SM3 Hash。
|
||
- `EvidenceHash`：作品预览图或业务传入证据的哈希。
|
||
- `PopiCertificateCertNo`：Popi 证书编号。
|
||
- `PopiCertificateVerifyURL`：Popi 证书二维码核验地址。
|
||
- `PopiCertificateCertificateImageURL`：Popi 证书图片公开地址。
|
||
- `ZXChainCertURL`：至信链官方证书地址。
|
||
|
||
## h3：查询 Hash 取证记录
|
||
|
||
`h3` 对应 SDK 方法：
|
||
|
||
```go
|
||
QueryHashAttestation(ctx, request)
|
||
```
|
||
|
||
Hash 存证成功后，可以用 `ReceiptID` 查询链上记录。
|
||
|
||
```go
|
||
result, err := client.QueryHashAttestation(context.Background(), zxchainsdk.HashAttestationQueryRequest{
|
||
EvID: receiptID,
|
||
})
|
||
if err != nil {
|
||
log.Fatalf("Hash 取证查询失败: %v", err)
|
||
}
|
||
|
||
fmt.Println("evId:", result.EvID)
|
||
fmt.Println("txId:", result.TxID)
|
||
fmt.Println("blockHeight:", result.BlockHeight)
|
||
fmt.Println("txTime:", result.TxTime)
|
||
fmt.Println("extendInfo:", result.ExtendInfo)
|
||
```
|
||
|
||
查询条件至少传一个：
|
||
|
||
- `EvID`：`h4` 返回的 `ReceiptID`。
|
||
- `Hash`：存证内容的 SM3 Hash。
|
||
- `TxID`：`h4` 返回的 `RequestID`。
|
||
|
||
返回字段：
|
||
|
||
- `EvID`：Hash 存证回执中的 `evId`。
|
||
- `TxID`：Hash 存证回执中的 `txId`。
|
||
- `BlockHeight`：上链区块高度。
|
||
- `TxTime`：官方返回的上链时间。
|
||
- `ExtendInfo`：存证时写入的业务场景信息。
|
||
|