kxco-pq-chain

HTTP client for the KXCO post-quantum identity relay.

Institutions sign ML-DSA-65 intents with their existing post-quantum key, POST them to the KXCO relay at https://relay.kxco.ai, and receive a transaction hash. KXCO validates the signature, pays gas in ARMR, and submits the EVM transaction on Armature L1. No wallets, no gas, no Ethereum node required.

When to use this

Any institution backend that needs on-chain credential management — registering identities, issuing and revoking credentials, anchoring audit roots, rotating keys — without running an Ethereum node or holding crypto. If you already have a KxcoIdentity from kxco-pq-sdk, this is the only client you need to write to the chain.

For reading chain state (querying registered identities, verifying credentials on-chain), use ethers.js directly against https://chain.kxco.ai/rpc.

Install

npm install kxco-pq-chain

Requires Node.js 20.19 or later. kxco-post-quantum is installed automatically as a dependency.

Quick start

import { KxcoChain } from 'kxco-pq-chain'

// identity is a KxcoIdentity from kxco-pq-sdk (must expose .kid and .sign())
const chain = new KxcoChain({
  relay:    'https://relay.kxco.ai',
  identity: institutionIdentity,
  timeout:  10_000,  // optional, ms, default 10 000
})

// Register the institution on-chain — called once during onboarding
const { txHash, blockNumber } = await chain.registerInstitution({
  publicKeyHex: Buffer.from(institutionIdentity.publicKey).toString('hex'),
  metadataUrl:  'https://example.com/institution.json',  // optional
})

// Record a user credential issuance on-chain
const result = await chain.issueCredential({
  userKid:          'aa29f37ab7f4b2cf',
  userPublicKeyHex: Buffer.from(userPublicKey).toString('hex'),
  role:             'verified-user',
  expiresAt:        1800000000,  // unix seconds; omit or 0 for no expiry
})

All methods return Promise<{ txHash: string, blockNumber: number }> and throw KxcoChainError on failure.

How it works

Your backend constructs an intent describing the operation (register, issue, revoke, anchor, rotate), signs the canonical signing message with your ML-DSA-65 private key, and POSTs the signed intent to https://relay.kxco.ai/intents. The relay verifies the signature against the institution public key registered on Armature L1, checks the nonce to prevent replays, and submits the corresponding EVM transaction. It returns the txHash and blockNumber once the transaction is included. Your institution never holds ARMR, never configures an RPC endpoint, and is billed monthly via invoice.

API

All methods are on a KxcoChain instance and return Promise<{ txHash: string, blockNumber: number }>.

new KxcoChain(opts)

| Parameter | Type | Required | Description | |---|---|---|---| | opts.relay | string | yes | Relay base URL — use 'https://relay.kxco.ai' | | opts.identity | { kid: string; sign(msg: Uint8Array): Promise<Uint8Array> } | yes | KxcoIdentity from kxco-pq-sdk or any object with .kid and .sign() | | opts.timeout | number | no | Request timeout in ms. Default: 10000 |

chain.registerInstitution({ publicKeyHex, metadataUrl? })

Register an institution on-chain. Called once during onboarding.

| Parameter | Type | Required | Description | |---|---|---|---| | publicKeyHex | string | yes | Hex-encoded 1952-byte ML-DSA-65 public key | | metadataUrl | string | no | URL of institution metadata JSON |

chain.issueCredential({ userKid, userPublicKeyHex, role, expiresAt? })

Record a user credential issuance on-chain.

| Parameter | Type | Required | Description | |---|---|---|---| | userKid | string | yes | 16-hex-char kid of the issued user | | userPublicKeyHex | string | yes | Hex-encoded user ML-DSA-65 public key | | role | string | yes | Role string, e.g. 'verified-user' | | expiresAt | number | no | Unix seconds. Omit or 0 for no expiry |

chain.revokeCredential({ userKid, reason? })

Revoke a user credential on-chain.

| Parameter | Type | Required | Description | |---|---|---|---| | userKid | string | yes | kid of the user whose credential is revoked | | reason | string | no | Human-readable revocation reason |

chain.anchorAuditRoot({ rootHash, entryCount })

Anchor an audit log checkpoint on-chain.

| Parameter | Type | Required | Description | |---|---|---|---| | rootHash | string | yes | Hex SHA-256 of the latest audit log entry hash (64 hex chars) | | entryCount | number | yes | Total entries in the log at checkpoint time |

chain.anchorAttestation({ payloadHash, purpose })

Anchor a high-value attestation envelope hash on-chain.

| Parameter | Type | Required | Description | |---|---|---|---| | payloadHash | string | yes | Hex SHA-256 of the signed attestation envelope (64 hex chars) | | purpose | string | yes | Purpose string, e.g. 'regulatory-report' |

chain.rotateKey({ newKid, newPublicKeyHex })

Record an institution key rotation on-chain.

| Parameter | Type | Required | Description | |---|---|---|---| | newKid | string | yes | New 16-hex-char kid after rotation | | newPublicKeyHex | string | yes | Hex-encoded new ML-DSA-65 public key |

chain.issueAgentCredential({ agentKid, agentPublicKeyHex, agentType, scopeHash, expiresAt })

Register an AI agent or machine identity on-chain. Called by the sponsoring institution.

| Parameter | Type | Required | Description | |---|---|---|---| | agentKid | string | yes | 16-hex-char kid of the agent | | agentPublicKeyHex | string | yes | Hex-encoded agent ML-DSA-65 public key | | agentType | 'llm' \| 'robot' \| 'iot' \| 'process' | yes | Agent category | | scopeHash | string | yes | Hex SHA-256 of the canonical scope JSON | | expiresAt | number | yes | Unix seconds — mandatory, must be greater than 0 |

chain.revokeAgentCredential({ agentKid, reason? })

Revoke an agent credential on-chain. The signing identity must be the sponsoring institution.

| Parameter | Type | Required | Description | |---|---|---|---| | agentKid | string | yes | kid of the agent to revoke | | reason | string | no | Human-readable revocation reason |

Error handling

All methods throw KxcoChainError on failure.

import { KxcoChain, KxcoChainError } from 'kxco-pq-chain'

try {
  await chain.issueCredential({ ... })
} catch (err) {
  if (err instanceof KxcoChainError) {
    console.error(err.code)    // 'TIMEOUT', 'NETWORK_ERROR', 'RELAY_ERROR', ...
    console.error(err.status)  // HTTP status or null
    console.error(err.body)    // raw relay response or null
  }
}

Common codes: BAD_CONFIG, TIMEOUT, NETWORK_ERROR, PARSE_ERROR, RELAY_ERROR, plus relay-specific codes such as CREDIT_EXHAUSTED.

Low-level helpers

Exported for integrations that need to construct or inspect intents directly.

import { buildIntent, buildSigningMessage, randomNonce, canonicalize } from 'kxco-pq-chain'

// Build the canonical UTF-8 signing message for a relay intent
const msg = buildSigningMessage(operation, institutionKid, nonce, timestamp, payload)

// Build and sign a complete relay intent object ready to POST
const intent = await buildIntent({ operation, institutionKid, payload, identity })

// Generate a cryptographically random 64-hex-char nonce
const nonce = randomNonce()

// RFC 8785 JSON Canonicalization Scheme
const canonical = canonicalize({ b: 2, a: 1 })  // '{"a":1,"b":2}'

What this does NOT do

• This is not a general-purpose Ethereum client. It does not wrap ethers.js or expose RPC calls.
• It does not read chain state. To query registered institutions, verify credentials, or inspect on-chain data, use ethers.js directly against https://chain.kxco.ai/rpc.
• It does not manage wallets, sign raw transactions, or interact with ARMR directly.

Part of the KXCO stack

| Package | Purpose | |---|---| | kxco-post-quantum | ML-DSA-65 key generation, signing, and verification (FIPS 204) | | kxco-pq-sdk | KxcoIdentity — issued and managed identity with on-device signing | | kxco-pq-chain | This package — HTTP client for the KXCO relay |

The relay is live at https://relay.kxco.ai. Armature L1 RPC is at https://chain.kxco.ai/rpc.

License

Apache-2.0 — Copyright 2026 KXCO by Knightsbridge

Authors: Shayne Heffernan and John Heffernan