SDK
官方 SDK
官方 SDK 封装了常用的 ClaimAnchor、GrantAnchor、事件锚创建、查询、验证和追溯流程,适合直接嵌入业务系统、审计平台或自动化任务。
V4.2 锁定代码兼容性:Python SDK 0.1.0(Python ≥ 3.9)、TypeScript SDK 0.2.0(Node.js ≥ 18)和 Rust SDK 0.1.0(Rust 2021)。生产接入请先从目标节点的 /healthz 读取 origin_fingerprint,再写入请求。
SDK 公开包仍在发布筹备中;官网仅在包实际发布后提供 pip、npm 或 crates.io 安装命令。当前可查阅 OpenAPI 4.2 合约 进行接口评估。
python.py
import asyncio
from gnomon_sdk import GnomonClient
async def main():
async with GnomonClient(
"https://<your-node-base-url>",
api_key="<访问密钥>",
origin_fingerprint="<从 /healthz 读取的来源指纹>",
) as client:
health = await client.healthz()
# 先调用 prepare_claim_anchor / prepare_grant_anchor,使用返回的 payload 在本地或 HSM 签名。
deployer_claim = await client.create_claim_anchor(
entity_fingerprint=bytes.fromhex("11" * 32),
attribute_type=0x0201,
attribute_hash=bytes.fromhex("22" * 32),
subject_public_key=bytes.fromhex("33" * 32),
subject_signature=subject_signature,
issuer_public_key=bytes.fromhex("55" * 32),
issuer_signature=issuer_signature,
)
agent_claim = await client.create_claim_anchor(
entity_fingerprint=bytes.fromhex("77" * 32),
attribute_type=0x0301,
attribute_hash=bytes.fromhex("88" * 32),
subject_public_key=bytes.fromhex("99" * 32),
subject_signature=agent_subject_signature,
issuer_public_key=bytes.fromhex("bb" * 32),
issuer_signature=agent_issuer_signature,
)
grant = await client.create_grant_anchor(
grantor_claim_ref=deployer_claim.anchor.anchor_id,
grantee_claim_ref=agent_claim.anchor.anchor_id,
scope_hash=bytes.fromhex("dd" * 32),
delegation_depth=0,
grantor_public_key=bytes.fromhex("ee" * 32),
grantor_signature=grantor_signature,
witness_public_key=bytes.fromhex("10" * 32),
witness_signature=witness_signature,
)
event_hash = bytes.fromhex("aa" * 32)
created = await client.create_event_anchor(
event_hash,
semantic_anchor={
"iris_ref": agent_claim.anchor.anchor_id,
"grant_ref": grant.anchor.anchor_id,
"event_data_hash": event_hash,
},
client_event_id="evt-001",
)
Python SDK 0.1.0 · 公开发布筹备中typescript.ts
import { GnomonClient, fromHex } from '@gnomon/sdk';
const client = new GnomonClient({
endpoint: 'https://<your-node-base-url>',
apiKey: '<访问密钥>',
originFingerprint: '<从 /healthz 读取的来源指纹>',
});
const health = await client.healthz();
const deployerClaim = await client.createClaimAnchor({
entityFingerprint: '11'.repeat(32),
attributeType: 0x0201,
attributeHash: '22'.repeat(32),
subjectPublicKey: new Uint8Array(32).fill(0x33),
subjectPrivateKey: new Uint8Array(32).fill(0x44),
issuerPublicKey: new Uint8Array(32).fill(0x55),
issuerPrivateKey: new Uint8Array(32).fill(0x66),
});
const agentClaim = await client.createClaimAnchor({
entityFingerprint: '77'.repeat(32),
attributeType: 0x0301,
attributeHash: '88'.repeat(32),
subjectPublicKey: new Uint8Array(32).fill(0x99),
subjectPrivateKey: new Uint8Array(32).fill(0xaa),
issuerPublicKey: new Uint8Array(32).fill(0xbb),
issuerPrivateKey: new Uint8Array(32).fill(0xcc),
});
const grant = await client.createGrantAnchor({
grantorClaimRef: deployerClaim.anchor.anchorId,
granteeClaimRef: agentClaim.anchor.anchorId,
scopeHash: 'dd'.repeat(32),
delegationDepth: 0,
grantorPublicKey: new Uint8Array(32).fill(0xee),
grantorPrivateKey: new Uint8Array(32).fill(0xff),
witnessPublicKey: new Uint8Array(32).fill(0x10),
witnessPrivateKey: new Uint8Array(32).fill(0x20),
});
const hash = new Uint8Array(32).fill(0xaa);
const created = await client.createEventAnchor(hash, {
semanticAnchor: {
irisRef: agentClaim.anchor.anchorId,
grantRef: grant.anchor.anchorId,
eventDataHash: hash,
},
clientEventId: 'evt-001',
});
TypeScript SDK 0.2.0 · 公开发布筹备中main.rs
use gnomon_sdk::GnomonClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = GnomonClient::builder()
.endpoint("https://<your-node-base-url>")
.api_key("<访问密钥>")
.origin_fingerprint([0x01u8; 32])
.build()?;
let health = client.healthz().await?;
println!("{} {:?}", health.status, health.origin_fingerprint);
let deployer_claim = client.create_claim_anchor(
&gnomon_types::EntityFingerprint([0x11; 32]),
0x0201,
[0x22; 32],
&[0x33; 32],
&[0x44; 32],
&[0x55; 32],
&[0x66; 32],
gnomon_sdk::CreateClaimAnchorOptions::default(),
).await?;
let agent_claim = client.create_claim_anchor(
&gnomon_types::EntityFingerprint([0x77; 32]),
0x0301,
[0x88; 32],
&[0x99; 32],
&[0xaa; 32],
&[0xbb; 32],
&[0xcc; 32],
gnomon_sdk::CreateClaimAnchorOptions::default(),
).await?;
let grant = client.create_grant_anchor(
&deployer_claim.anchor.anchor_id,
&agent_claim.anchor.anchor_id,
[0xdd; 32],
0,
&[0xee; 32],
&[0xff; 32],
&[0x10; 32],
&[0x20; 32],
gnomon_sdk::CreateGrantAnchorOptions::default(),
).await?;
let hash = [0xAAu8; 32];
let created = client.create_event_anchor_with_options(
hash,
gnomon_sdk::CreateAnchorOptions {
semantic_anchor_refs: Some(gnomon_core::SemanticAnchorRefs {
iris_ref: agent_claim.anchor.anchor_id,
scroll_ref: gnomon_types::AnchorId::default(),
grant_ref: grant.anchor.anchor_id,
bond_ref: gnomon_types::AnchorId::default(),
yield_ref: gnomon_types::AnchorId::default(),
event_data_hash: hash,
}),
..gnomon_sdk::CreateAnchorOptions::default()
}
).await?;
Rust SDK 0.1.0 · 公开发布筹备中主体与授权
ClaimAnchor / GrantAnchor 的推荐接入顺序
当业务系统需要证明“谁在执行、谁授权、授权边界是什么”时,推荐先固定主体身份和授权链,再写入操作事件锚。这样同一条操作既能做事件真实性验证,也能做责任链验证。
| 阶段 | 接口 | 用途 |
|---|---|---|
| 主体登记 | POST /v1/claim-anchors | 为部署方、Agent、组织主体或其他实体创建 ClaimAnchor。 |
| 当前主体状态 | GET /v1/claim-anchors | 按 entity_fingerprint + attribute_type 查询当前有效 ClaimAnchor。 |
| 主体校验 | POST /v1/claim-anchors:verify | 验证嵌套签名、事件锚有效性和撤销状态。 |
| 授权登记 | POST /v1/grant-anchors | 把授权范围、委托深度和授权关系写成独立 GrantAnchor。 |
| 当前授权状态 | GET /v1/grant-anchors | 按 grantor_fingerprint + grantee_fingerprint 查询当前有效授权。 |
| 授权校验 | POST /v1/grant-anchors:verify | 验证嵌套签名、授权链和关联 ClaimAnchor 的有效性。 |
| 撤销 | POST /v1/claim-anchors/{anchor_id}/revoke | 为主体写入撤销记录,并作为后续追责的失效证据。 |
| 操作事件 | POST /v1/event-anchors | 在 semantic_anchor 中引用 Agent ClaimAnchor 与 GrantAnchor,形成完整责任链。 |
健康与监控
先用 healthz 接入,再用私有 metrics 做运维观测
当前生产 VPS 将开发者接入面和运维监控面分开:公开入口提供节点健康和来源标识,Prometheus 监控面仅保留在宿主机和私网抓取链路。
| 接口 | 可见范围 | 用途 |
|---|---|---|
GET /healthz | 公开接入面 | 读取节点状态、origin_fingerprint 和 Prime RootTHK 同步摘要。 |
GET /readyz | 公开接入面 | 确认节点已经完成启动、存储和依赖初始化。 |
GET /metrics | 宿主机 / 私网 | 供 Prometheus 抓取指标文本;当前公网入口不暴露该路径。 |
当前 VPS 监控面
公网
GET /healthz
GET /readyz
私网抓取
127.0.0.1:15051/metrics
127.0.0.1:18110/metrics
127.0.0.1:18090/metrics
告警
gnomon_prime_root_thk_sync_error == 1
time() - gnomon_prime_root_thk_last_sync_success_timestamp_seconds > 30
公开 API
核心 API
开发者接入通常先走健康检查和事件锚主路径;涉及主体、授权、AI Agent 或多方责任链时,再补 ClaimAnchor / GrantAnchor 两层。
集群复制与 quorum 签名属于私有控制面,不是浏览器 SDK 的公开接入面;它们需要节点级 mTLS 和 Cluster-auth。
| 方法 | 接口 | 用途 |
|---|---|---|
| GET | /healthz | 检查节点健康,读取接入所需的来源标识和 Prime 同步摘要 |
| POST | /v1/event-anchors | 创建天璇协议事件锚 |
| GET | /v1/event-anchors/latest | 查询某个来源的当前 EEA,用于审计和链路观测 |
| POST | /v1/event-anchors:verify | 验证锚点完整性与深度 |
| GET | /v1/event-anchors/{anchor_id}/trace | 追溯链路 |
| POST | /v1/claim-anchors | 创建主体身份锚,常用于部署方、Agent 和组织主体登记 |
| POST | /v1/claim-anchors:verify | 验证 ClaimAnchor 的嵌套签名和撤销状态 |
| POST | /v1/grant-anchors | 创建授权锚,固定授权范围和委托边界 |
| POST | /v1/grant-anchors:verify | 验证授权链、ClaimAnchor 引用和签名完整性 |
| POST | /v1/event-anchors/batch | 批量创建事件锚 |
| POST | /v1/event-anchors:batchVerify | 批量验证事件锚 |