popi-zxl/SDK_USAGE.md

ZXChain SDK 使用文档

初始化客户端

SDK 不主动读取 .env，需要自己管理配置，并把凭据传给 SDK。

import "git.yuanzoo.cn/zhangzhengqiang/popi-zxl"

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 访问密钥。
• ZXCHAIN_CERTIFICATE_FONT_PATH：可选。证书绘制使用的中文字体路径；Windows 可用 C:/Windows/Fonts/msyh.ttc。

存证和生成证书并一起返回

h4 对应 SDK 方法：

CreateSimpleHashAttestationCertificate(ctx, request)

它会完成以下流程：

从 WorkPreviewURL 下载作品预览图
计算作品预览图 EvidenceHash
生成证据包并计算 SM3 Hash
调用至信链 Hash 存证
生成 Popi 证书图片
上传证书图片到 COS
返回 evId、txId、区块高度、证书地址等结果

示例：

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",        //可选参数，可以不传
    FontPath:       "C:/Windows/Fonts/msyh.ttc", // 可选；Windows 推荐微软雅黑，或配置 ZXCHAIN_CERTIFICATE_FONT_PATH

    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值。
• FontPath：可选。中文字体路径；不传时 SDK 会自动查找 Windows/macOS/Linux 常见中文字体，也可以用 ZXCHAIN_CERTIFICATE_FONT_PATH 环境变量指定。Windows 常见可用路径：C:/Windows/Fonts/msyh.ttc、C:/Windows/Fonts/simhei.ttf、C:/Windows/Fonts/simsun.ttc。
• CertificateStorage：可选。COS 上传配置。

返回字段：

• ReceiptID：至信链 evId，后续给 h3 查询使用。
• RequestID：至信链 txId。
• BlockHeight：上链区块高度。
• TxTime：上链时间。
• SM3Hash：本次上链证据包的 SM3 Hash。
• EvidenceHash：作品预览图或业务传入证据的哈希。
• PopiCertificateCertNo：Popi 证书编号。
• PopiCertificateVerifyURL：Popi 证书二维码核验地址。
• PopiCertificateCertificateImageURL：Popi 证书图片公开地址。
• ZXChainCertURL：至信链官方证书地址。

h3：查询 Hash 取证记录

h3 对应 SDK 方法：

QueryHashAttestation(ctx, request)

Hash 存证成功后，可以用 ReceiptID 查询链上记录。

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：存证时写入的业务场景信息。