@rubric-protocol/sdk

@rubric-protocol/sdk

Post-quantum AI attestation for Node.js. Every AI decision your system makes — signed locally in microseconds, anchored to Hedera's public ledger in the background.

Built for EU AI Act Article 12 compliance and beyond.

⚠️ Critical: /v1/attest vs /v1/tiered-attest

Endpoint	Tier Required	Behavior	Cost
/v1/attest	Enterprise only	Writes directly to Hedera Consensus Service	HBAR per call
/v1/tiered-attest	Developer+	Merkle batching (1,000,000:1 compression)	Minimal

Use /v1/tiered-attest for all development and high-volume workloads. Hard rate limit: 60 req/min. If you are unsure which to use: use /v1/tiered-attest.

How it works

The SDK signs AI decisions locally using ML-DSA-65 (NIST FIPS 204, post-quantum) before any network call is made. Attestations are queued and flushed to Rubric's global federation in the background. Your AI pipeline sees zero added latency.

AI decision ‒ local sign (<1ms) → proof returned immediately
                                 ↓ background
                          Rubric anchor (5-10s) → HCS confirmed (~30s)

Each proof upgrades automatically as anchoring completes. You can fire-and-forget, or await full HCS confirmation for high-stakes decisions.

Install

npm install @rubric-protocol/sdk

Peer dependencies (install only what you use):

npm install openai              # for OpenAI plugin
npm install @langchain/core     # for LangChain plugin

Quickstart

import { createRubricClient } from '@rubric-protocol/sdk';

const rubric = createRubricClient({
  apiKey: process.env.RUBRIC_API_KEY!,
  localSigning: true,       // sign locally before network
  backgroundQueue: true,    // non-blocking flush
  node: 'auto',             // route to nearest healthy node
});

const proof = await rubric.attest({
  agentId: 'my-agent-v1',
  output: 'Loan application approved. Score: 742, DTI: 28%.',
  leafType: 'AGENT_OUTPUT',
  metadata: { model: 'gpt-4o', pipeline: 'credit-decisioning' },
});

console.log(proof.attestationId);  // immediate
console.log(proof.stage);          // 'local'

// Optional: wait for full HCS confirmation
proof.onUpgrade('confirmed', (confirmed) => {
  console.log(confirmed.hashScanUrl); // publicly verifiable on HashScan
});

LangChain

Add one handler and every LLM call, agent action, chain, and tool invocation is automatically attested.

import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor } from 'langchain/agents';
import { RubricLangChainHandler } from '@rubric-protocol/sdk';

const rubric = new RubricLangChainHandler({
  apiKey: process.env.RUBRIC_API_KEY!,
  localSigning: true,
  backgroundQueue: true,
  events: ['llm', 'agent', 'tool'],  // choose what to attest
  pipelineId: 'my-pipeline',
});

const executor = await AgentExecutor.fromAgentAndTools({
  agent,
  tools,
  callbacks: [rubric],  // that's it
});

await executor.invoke({ input: 'Analyze this transaction for fraud.' });
await rubric.shutdown(); // flush remaining queue on exit

OpenAI

Drop-in wrapper — your existing code is unchanged.

import OpenAI from 'openai';
import { withRubric } from '@rubric-protocol/sdk';

const openai = withRubric(new OpenAI(), {
  apiKey: process.env.RUBRIC_API_KEY!,
  agentId: 'my-openai-agent',
  localSigning: true,
  backgroundQueue: true,
});

// Use exactly as before — attestation happens automatically
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Should we approve this claim?' }],
});

High-stakes decisions

For decisions requiring immediate confirmation (medical triage, credit denial, hiring rejection), await full HCS anchoring:

const confirmed = await rubric.attestAndConfirm({
  agentId: 'triage-agent',
  output: 'Patient flagged for immediate review.',
  leafType: 'AGENT_OUTPUT',
  risk: 'high',
}, 90_000); // timeout ms

console.log(confirmed.hcsSequenceNumber);
console.log(confirmed.hashScanUrl); // immutable public record

Proof lifecycle

Every attestation returns a LiveProof that upgrades automatically:

Stage	When	What you have
local	<1ms	ML-DSA-65 signature + timestamp
anchored	5–10s	Merkle root committed to Rubric
confirmed	~30s	HCS sequence number, HashScan URL

proof.onUpgrade('anchored', (p) => console.log(p.merkleRoot));
proof.onUpgrade('confirmed', (p) => console.log(p.hashScanUrl));
proof.onUpgrade('any', (p) => console.log(p.stage)); // fires on each upgrade

Configuration

createRubricClient({
  apiKey: string,               // required — get one at rubric-protocol.com
  node?: 'us'|'sg'|'jp'|'ca'|'eu'|'auto',  // default: 'us'
  localSigning?: boolean,       // default: false
  keystorePath?: string,        // default: ~/.rubric/sdk-keypair.json
  keystorePassphrase?: string,  // AES-256-GCM encrypts the keystore
  backgroundQueue?: boolean,    // default: false
  enterprise?: boolean,         // uses /v1/tiered-attest (Merkle batching)
  proofUpgrade?: boolean,       // auto-poll for stage upgrades
  timeout?: number,             // HTTP timeout ms, default: 15000
})

Nodes

The SDK routes to Rubric's global federation automatically when node: 'auto'.

Region	Endpoint
US East	https://rubric-protocol.com/verify
Singapore	https://sg.rubric-protocol.com/verify
Japan	https://jp.rubric-protocol.com/verify
Canada	https://ca.rubric-protocol.com/verify
EU Central	https://eu.rubric-protocol.com/verify

Security

• ML-DSA-65 (NIST FIPS 204) — post-quantum signature scheme, same algorithm used server-side
• Keypairs stored at ~/.rubric/sdk-keypair.json with optional AES-256-GCM encryption via passphrase
• Canonical JSON serialization ensures deterministic, tamper-evident signing
• All attestations anchored to Hedera Consensus Service — public, immutable, independently verifiable

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (if using TypeScript)

Links

• Documentation
• API Reference
• HashScan — live attestation stream
• EU AI Act Article 12

License

MIT — Echelon Intelligence Systems LLC

Patent Pending