开发者

从事件摘要到可验证凭据,
用接口和 SDK 快速接入 Gnomon

开发者既可以直接写入事件锚,也可以先登记主体 ClaimAnchor、建立 GrantAnchor 授权链,再把操作事件锚串到同一条可验证责任链上。

官方 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-anchorsentity_fingerprint + attribute_type 查询当前有效 ClaimAnchor。
主体校验POST /v1/claim-anchors:verify验证嵌套签名、事件锚有效性和撤销状态。
授权登记POST /v1/grant-anchors把授权范围、委托深度和授权关系写成独立 GrantAnchor。
当前授权状态GET /v1/grant-anchorsgrantor_fingerprint + grantee_fingerprint 查询当前有效授权。
授权校验POST /v1/grant-anchors:verify验证嵌套签名、授权链和关联 ClaimAnchor 的有效性。
撤销POST /v1/claim-anchors/{anchor_id}/revoke为主体写入撤销记录,并作为后续追责的失效证据。
操作事件POST /v1/event-anchorssemantic_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

开发者接入通常先走健康检查和事件锚主路径;涉及主体、授权、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批量验证事件锚
Gnomon 接口试验场

在浏览器中测试节点健康、ClaimAnchor、GrantAnchor、事件锚创建、验证、追溯和批量处理流程。

打开接口试验场