@enc-protocol/client — API Reference

npm install @enc-protocol/client --registry https://npm-registry.ocrybit.workers.dev/

npm install @enc-protocol/core --registry https://npm-registry.ocrybit.workers.dev/

@enc-protocol/client
  index.js              Re-exports everything from all modules
  http.js               NodeClient — HTTP client for node communication
  ws.js                 NodeWebSocket — WebSocket client for real-time streaming
  session.js            SessionManager — auto-refreshing session tokens
  sdk.js                High-level SDK functions, factory exports, state management
  registry-client.js    RegistryClient — registry node lookups
  wallet.js             ENC pubkey to EVM address utilities

import { NodeClient } from '@enc-protocol/client/http.js'
import { NodeWebSocket } from '@enc-protocol/client/ws.js'

import { NodeClient, createIdentity, SessionManager } from '@enc-protocol/client'

import { NodeClient } from '@enc-protocol/client/http.js'
 
const client = new NodeClient(baseUrl, opts?)

const client = new NodeClient('https://enc-node.ocrybit.workers.dev')

import { SessionManager } from '@enc-protocol/client/session.js'
 
const sm = new SessionManager(myPrivateKey)
const client = new NodeClient('https://enc-node.ocrybit.workers.dev', {
  enclaveId: '...',
  identityPubHex: '...',
  seqPubHex: '...',
  sessionManager: sm,
})

client.encrypted → boolean

client.submitCommit(commit: Object) → Promise<Object>

{
  type: 'Receipt',
  seq: 0,
  id: '...',          // 64 hex event ID
  hash: '...',        // 64 hex commit hash
  timestamp: 1234567, // ms
  sig: '...',         // 128 hex author signature
  seq_sig: '...',     // 128 hex sequencer signature
  sequencer: '...',   // 64 hex sequencer pubkey
}

{
  type: 'Error',
  code: 'UNAUTHORIZED' | 'EXPIRED' | 'DUPLICATE' | ...,
  message: '...',
}

import { mkCommit, signCommit } from '@enc-protocol/core/event.js'
 
const commit = mkCommit(enclaveId, pubHex, 'post', '{"body":"hi"}', Date.now() + 300000, [])
const signed = signCommit(commit, privateKey)
const receipt = await client.submitCommit(signed)
console.log(receipt.id) // event ID

client.query(filter: Object, auth?: Object) → Promise<Object>

{ "type": "Query", "enclave": "...", "from": "...", "content": "session.ciphertext" }

const result = await client.query(
  { enclave: enclaveId, type: 'post', limit: 50 },
  { identity: pubHex, session: sessionToken }  // optional auth
)

client.pull(afterSeq: number, opts?: Object) → Promise<Object>

{
  type: 'Events',
  events: [...],     // array of event objects
}

// Pull all events from the beginning
const result = await client.pull(-1, { limit: 100 })
for (const event of result.events) {
  console.log(event.seq, event.type, event.content)
}

client.info() → Promise<Object>

client.getSTH(enclaveId?: string) → Promise<{ t: number, ts: number, r: string, sig: string }>

import { verifySTH, hexToBytes } from '@enc-protocol/core/crypto.js'
 
const sth = await client.getSTH()
const valid = verifySTH(sth.t, sth.ts, hexToBytes(sth.r), sth.sig, hexToBytes(seqPubHex))

client.getInclusion(leafIndex: number) → Promise<Object>

client.getState(key: string) → Promise<Object>

// Get RBAC state for an identity
const result = await client.getState(`rbac:${pubHex}`)

client.pingLiveness() → Promise<boolean>

import { NodeWebSocket } from '@enc-protocol/client/ws.js'
 
const ws = new NodeWebSocket(url)

ws.on(event: string, handler: Function) → NodeWebSocket

ws.connect() → NodeWebSocket

ws.close()

ws.connected → boolean

ws.subscribe(
  enclave: string,       // enclave ID (64 hex)
  from: string | null,   // identity pubkey for auth (or null)
  session: string | null, // session token (or null)
  filter?: Object        // { type?, from?, id?, seq?, timestamp?, limit? }
) → null

ws.unsubscribe(subId: string)

ws.commit(commit: Object)

import { NodeWebSocket } from '@enc-protocol/client/ws.js'
import { generateKeypair, bytesToHex, generateSession } from '@enc-protocol/core/crypto.js'
import { mkCommit, signCommit } from '@enc-protocol/core/event.js'
 
const kp = generateKeypair()
const pub = bytesToHex(kp.publicKey)
const { session } = generateSession(kp.privateKey)
 
const ws = new NodeWebSocket('wss://enc-node.ocrybit.workers.dev/ws')
 
ws.on('open', () => {
  console.log('Connected')
 
  // Subscribe to all events
  ws.subscribe(enclaveId, pub, session, {})
})
 
ws.on('event', (event, subId) => {
  console.log(`[${subId}] Event ${event.seq}: ${event.type}`)
  console.log('Content:', event.content)
})
 
ws.on('eose', (subId) => {
  console.log(`[${subId}] End of stored events — now streaming live`)
})
 
ws.on('receipt', (receipt) => {
  console.log('Commit accepted, event ID:', receipt.id)
})
 
ws.on('error', (err) => {
  console.error('Error:', err.code, err.message)
})
 
ws.on('close', (code, reason) => {
  console.log('Disconnected:', code, reason)
})
 
ws.connect()
 
// Submit a commit after connection
setTimeout(() => {
  const commit = mkCommit(enclaveId, pub, 'post', '{"body":"via ws"}', Date.now() + 300000, [])
  const signed = signCommit(commit, kp.privateKey)
  ws.commit(signed)
}, 1000)

import { SessionManager } from '@enc-protocol/client/session.js'
 
const sm = new SessionManager(identityPriv, opts?)

sm.getSession() → {
  session: string,         // 136 hex char session token
  sessionPriv: Uint8Array, // 32-byte session private key
  expires: number          // Unix timestamp (seconds)
}

sm.token → string  // 136 hex chars

sm.valid → boolean

sm.refresh()

import { SessionManager } from '@enc-protocol/client/session.js'
import { generateKeypair } from '@enc-protocol/core/crypto.js'
 
const kp = generateKeypair()
const sm = new SessionManager(kp.privateKey, {
  duration: 3600,      // 1 hour sessions
  refreshBefore: 300,  // refresh 5 min before expiry
})
 
// First call generates a session
const { session, sessionPriv, expires } = sm.getSession()
console.log(sm.valid) // true
 
// Subsequent calls return cached session (until refresh needed)
const same = sm.getSession()
console.log(same.session === session) // true (same token)
 
// Force refresh
sm.refresh()
const fresh = sm.getSession()
console.log(fresh.session === session) // false (new token)

createIdentity(seed?: Uint8Array) → {
  privateKey: Uint8Array,
  publicKey: Uint8Array,
  publicKeyHex: string
}

import { createIdentity } from '@enc-protocol/client/sdk.js'
 
// Random identity
const alice = createIdentity()
 
// Deterministic identity from seed
const bob = createIdentity(new TextEncoder().encode('bob-seed-phrase'))
console.log(bob.publicKeyHex) // always the same for same seed

loadIdentity(privateKey: Uint8Array) → {
  privateKey: Uint8Array,
  publicKey: Uint8Array,
  publicKeyHex: string
}

signWithIdentity(identity: Object, data: Uint8Array) → Uint8Array(64)

import { ConnectionStatus } from '@enc-protocol/client/sdk.js'
 
ConnectionStatus.disconnected  // 'disconnected'
ConnectionStatus.connecting    // 'connecting'
ConnectionStatus.connected     // 'connected'
ConnectionStatus.error         // 'error'

createConnection(host: string, port: number, nodePubHex: string) → {
  host: string,
  port: number,
  nodePubHex: string,
  status: 'disconnected'
}

connect(conn: Object) → Object     // { ...conn, status: 'connected' }
disconnect(conn: Object) → Object  // { ...conn, status: 'disconnected' }

isConnected(conn: Object) → boolean

createCommit(
  identity: Object,    // { privateKey, publicKey, publicKeyHex }
  enclave: string,     // enclave ID (64 hex)
  type: string,        // event type
  content: string,     // JSON string content
  exp?: number,        // expiration ms (default: now + 5 min)
  tags?: string[][]    // tags (default: [])
) → Object            // signed commit (has sig field)

import { createIdentity, createCommit } from '@enc-protocol/client/sdk.js'
 
const id = createIdentity()
const signed = createCommit(id, enclaveId, 'post', '{"body":"hi"}')
// signed is ready to submit to a node

createManifestCommit(
  identity: Object,          // { privateKey, publicKey, publicKeyHex }
  manifestContent: string,   // manifest JSON string
  exp?: number,              // expiration (default: now + 5 min)
  tags?: string[][]          // tags (default: [])
) → Object                  // signed commit with derived enclave

const manifest = JSON.stringify({
  enc_v: 2, nonce: Date.now(),
  RBAC: {
    use_temp: 'none',
    schema: [{ event: '*', role: 'Public', ops: ['R', 'C'] }],
    states: [], traits: [],
    initial_state: {},
  },
})
 
const signed = createManifestCommit(id, manifest)
console.log(signed.enclave) // derived enclave ID

buildRegEnclaveContent(
  manifestEvent: Object,   // full finalized manifest event
  opts?: {
    app?: string,          // application name
    desc?: string,         // description
    meta?: Object,         // arbitrary metadata
    owner_proof?: string,  // ownership proof
  }
) → string               // JSON string for Reg_Enclave content

SubmitResult.success       // 'success'
SubmitResult.notConnected  // 'notConnected'
SubmitResult.error         // 'error'

initClient(identity: Object) → {
  identity: Object,
  connection: null,
  cachedSTH: null,
  pendingReceipts: []
}

connectClient(state, host, port, nodePubHex) → Object  // new state with connected connection

disconnectClient(state) → Object  // new state with disconnected connection

clientIsConnected(state) → boolean

getCachedSTH(state) → Object | null
cacheSTH(state, sth, timestamp) → Object  // new state with cached STH

verifyNodeReceipt(receipt: Object, nodePubHex: string) → boolean

import { verifyNodeReceipt } from '@enc-protocol/client/sdk.js'
 
const receipt = await client.submitCommit(signed)
const valid = verifyNodeReceipt(receipt, seqPubHex)

healthCheck(state) → { connected: true, latency: 0, version: '1.0.0' } | null

SDKInterface.node_api      // 'node_api'
SDKInterface.registry_api  // 'registry_api'
SDKInterface.local_api     // 'local_api'
 
SDKOperation.createIdentity       // 'createIdentity'
SDKOperation.loadIdentity         // 'loadIdentity'
SDKOperation.derivePublicKey      // 'derivePublicKey'
SDKOperation.generatePrivateKey   // 'generatePrivateKey'
SDKOperation.signWithIdentity     // 'signWithIdentity'
SDKOperation.createCommit         // 'createCommit'
SDKOperation.submitCommit         // 'submitCommit'
SDKOperation.queryEvents          // 'queryEvents'
SDKOperation.verifyNodeReceipt    // 'verifyNodeReceipt'
SDKOperation.verifyLogInclusion   // 'verifyLogInclusion'
SDKOperation.verifyLogConsistency // 'verifyLogConsistency'
SDKOperation.cacheSTH             // 'cacheSTH'
SDKOperation.healthCheck          // 'healthCheck'
SDKOperation.lookupNode           // 'lookupNode'
SDKOperation.lookupEnclave        // 'lookupEnclave'
SDKOperation.resolveEnclave       // 'resolveEnclave'

sdkOperationInterface(op: string) → string | null
// 'createIdentity' → 'local_api'
// 'submitCommit'   → 'node_api'
// 'lookupNode'     → 'registry_api'

allSDKOperations → string[]  // all 16 operation names

createNodeClient(url: string) → NodeClient

createRegistryClient(url: string) → RegistryClient

createWebSocket(url: string, opts?: Object) → NodeWebSocket

createSessionManager(identityPriv: Uint8Array, opts?: Object) → SessionManager

export {
  hexToBytes, bytesToHex, derivePublicKey, schnorrSign,
  generateSession, sha256Hash, taggedHash,
  computeContentHash, computeCommitHash, generateKeypair,
  ecdh, deriveKey, encrypt, decrypt,
} from '@enc-protocol/core/crypto.js'

export { NodeClient, NodeWebSocket, RegistryClient, SessionManager }

import { RegistryClient } from '@enc-protocol/client/registry-client.js'
 
const registry = new RegistryClient(registryUrl)

registry.lookupNode(seqPub: string) → Promise<Object | null>

registry.lookupEnclave(enclaveId: string) → Promise<Object | null>

registry.resolveEnclave(enclaveId: string) → Promise<{ enclave: Object, node: Object } | null>

registry.listNodes() → Promise<Object[]>

registry.lookupIdentity(pubkey: string) → Promise<Object | null>

registry.listIdentities() → Promise<Object[]>

registry.connectToEnclave(enclaveId: string) → Promise<NodeClient | null>

const client = await registry.connectToEnclave(enclaveId)
if (client) {
  const sth = await client.getSTH()
  console.log('Tree size:', sth.t)
}

registry.submitCommit(commit: Object) → Promise<Object>

registry.query(filter: Object) → Promise<Object>

registry.pingLiveness() → Promise<boolean>

encPubToEvmAddress(encPubHex: string) → [string, string]
// Returns [evenYAddress, oddYAddress]

import { encPubToEvmAddress } from '@enc-protocol/client/wallet.js'
 
const [even, odd] = encPubToEvmAddress('abcd1234...')
console.log(even)  // '0x...' — address assuming even y-coordinate
console.log(odd)   // '0x...' — address assuming odd y-coordinate

resolveEvmAddress(encPubHex: string, rpcUrl: string) → Promise<string>

import { resolveEvmAddress } from '@enc-protocol/client/wallet.js'
 
const addr = await resolveEvmAddress(pubHex, 'https://eth.llamarpc.com')
console.log(addr) // '0x...' — the address with higher balance

import {
  createIdentity, createManifestCommit, createCommit,
  createNodeClient, createSessionManager, verifyNodeReceipt,
} from '@enc-protocol/client'
import { verifySTH, hexToBytes, verifySession } from '@enc-protocol/core/crypto.js'
import { verifyEvent } from '@enc-protocol/core/event.js'
import { verify, wireToProof, buildRBACKey, decodeRoleBitmask } from '@enc-protocol/core/smt.js'
import { verifyInclusionProof } from '@enc-protocol/core/ct.js'
import { isOwner } from '@enc-protocol/core/rbac.js'
 
const NODE = 'https://enc-node.ocrybit.workers.dev'
 
// ── 1. Create identity ──
const id = createIdentity()
console.log('Public key:', id.publicKeyHex)
 
// ── 2. Create enclave ──
const manifest = JSON.stringify({
  enc_v: 2,
  nonce: Date.now(),
  RBAC: {
    use_temp: 'none',
    schema: [
      { event: 'post', role: 'owner', ops: ['C', 'U', 'D'] },
      { event: '*', role: 'Public', ops: ['R'] },
    ],
    states: [],
    traits: ['owner(0)'],
    initial_state: { owner: [id.publicKeyHex] },
  },
})
 
const manifestCommit = createManifestCommit(id, manifest)
const client = createNodeClient(NODE)
const createResult = await client.submitCommit(manifestCommit)
 
const enclaveId = manifestCommit.enclave
const seqPubHex = createResult.sequencer
console.log('Enclave:', enclaveId)
 
// ── 3. Submit a post ──
const postCommit = createCommit(id, enclaveId, 'post', JSON.stringify({ body: 'hello world' }))
const receipt = await client.submitCommit(postCommit)
 
// Verify the receipt
const receiptValid = verifyNodeReceipt(receipt, seqPubHex)
console.log('Receipt valid:', receiptValid)
 
// ── 4. Set up encrypted client ──
const sm = createSessionManager(id.privateKey, { duration: 3600 })
const encClient = new (await import('@enc-protocol/client/http.js')).NodeClient(NODE, {
  enclaveId,
  identityPubHex: id.publicKeyHex,
  seqPubHex,
  sessionManager: sm,
})
console.log('Encrypted mode:', encClient.encrypted) // true
 
// ── 5. Verify Signed Tree Head ──
const sth = await client.getSTH(enclaveId)
const sthValid = verifySTH(sth.t, sth.ts, hexToBytes(sth.r), sth.sig, hexToBytes(seqPubHex))
console.log('STH valid:', sthValid, '| Tree size:', sth.t)
 
// ── 6. Pull events and verify each ──
const pullResult = await client.pull(-1, { enclave: enclaveId, limit: 100 })
for (const event of pullResult.events) {
  const ok = verifyEvent(event)
  console.log(`  seq=${event.seq} type=${event.type} verified=${ok}`)
}
 
// ── 7. Verify inclusion proof ──
const inclResult = await encClient.getInclusion(0)
if (inclResult.ct_proof) {
  const path = inclResult.ct_proof.p.map(h => hexToBytes(h))
  const leafHash = hexToBytes(inclResult.leaf_hash)
  const inclValid = verifyInclusionProof(leafHash, 0, sth.t, path, hexToBytes(sth.r))
  console.log('Inclusion proof valid:', inclValid)
}
 
// ── 8. Verify RBAC state proof ──
const stateResult = await encClient.getState(`rbac:${id.publicKeyHex}`)
if (stateResult.proof) {
  const proof = wireToProof(stateResult.proof)
  const smtRoot = hexToBytes(stateResult.smt_root)
  const proofValid = verify(proof, smtRoot)
  console.log('State proof valid:', proofValid)
 
  if (proof.value) {
    const bitmask = decodeRoleBitmask(proof.value)
    console.log('Is owner:', isOwner(bitmask))
  }
}