@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: Endpoint routing by tier

Endpoint	Tier Required	Behavior	Cost
/v1/attest	Enterprise only	Direct HCS write per call	HBAR per call
/v1/standard-attest	Standard+	Batched HCS writes (10s window, 1 HCS write per batch)	Minimal
/v1/tiered-attest	Developer+	Merkle batching (1,000,000:1 compression)	Minimal

Default for most workloads: /v1/tiered-attest (Developer) or /v1/standard-attest (Standard). Hard rate limit on /v1/attest: 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

Developer tier uses Merkle batching. For per-attestation HCS confirmation use Enterprise tier.

Developer tier — listen for batch confirmation:

const proof = await rubric.attest({
  agentId: 'triage-agent',
  output: 'Patient flagged for immediate review.',
  leafType: 'AGENT_OUTPUT',
});
proof.onUpgrade('confirmed', (p) => {
  console.log(p.hashScanUrl);
});

Enterprise tier — direct per-call HCS anchoring:

const confirmed = await rubric.attestAndConfirm({
  agentId: 'triage-agent',
  output: 'Patient flagged for immediate review.',
  leafType: 'AGENT_OUTPUT',
}, 90_000);
console.log(confirmed.hcsSequenceNumber);
console.log(confirmed.hashScanUrl);

Enterprise: rubric-protocol.com/pricing

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
  tier?: 'developer' | 'standard' | 'enterprise', // default: developer
  enterprise?: boolean,         // legacy alias for tier: 'enterprise'
  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
Singapore	https://sg.rubric-protocol.com
Japan	https://jp.rubric-protocol.com
Canada	https://ca.rubric-protocol.com
EU Central	https://eu.rubric-protocol.com

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

Agent Payment Attestation (attestBeforeSpend)

Wraps a payment tool call so the decision is attested and anchored before money moves. In enforce mode the payment does not execute unless Rubric acknowledges the record.

const { attestBeforeSpend, verifySpendCommitment } = require('@rubric-protocol/sdk');

const pay = attestBeforeSpend(myPaymentFn, {
  apiKey: process.env.RUBRIC_API_KEY,
  agentId: 'agent-01',
  mandateRef: 'mandate-abc',
  rail: 'x402',
  mode: 'enforce',
  attestReceipt: true,
});

const out = await pay(params, { intent: 'supplier invoice', amount: '25.00', currency: 'USDC' });

Retain out.decisionRecord and out.decisionPayloadKey. Rubric stores only a salted commitment and does not retain the key; without both, the anchored record cannot be opened.

verifySpendCommitment(out.decisionRecord, out.decisionPayloadKey, out.decisionCommitment);

See docs/apa-v1-binding-profile.md for the normative specification.