@neuraiproject/neurai-connect-core

The protocol core of Neurai Connect: everything the wallet SDK, the dApp SDK, the backend verifier and the relay share. It runs in browsers, Node and React Native and never touches a private key — signing is the application's job.

Specification: spec/ (uri.md, crypto.md, relay-rpc.md, session.md, auth.md).

Most applications do not use this package directly:

• a website installs @neuraiproject/neurai-connect and its backend @neuraiproject/neurai-auth;
• a wallet installs @neuraiproject/neurai-connect-wallet, which re-exports the pieces a wallet needs from here.

What is inside

| Module | Contents | | --- | --- | | uri | nc:<topic>@1?relay=…&symKey=… pairing URIs (formatNcUri, parsePairingUri, isPairingUri); wc: v2 URIs are accepted too. | | crypto | X25519 key agreement + HKDF-SHA256 → ChaCha20-Poly1305 (generateKeyPair, deriveSymKey, hashKey, generateRandomBytes32). | | envelope | The two envelope types on the wire (encrypt, decrypt, serialize, deserialize). | | relay-auth | Ed25519 did:key JWTs that authenticate a client to the relay (generateRelayKeyPair, signJWT, verifyJWT). | | relay-client | The WebSocket client with reconnection, at-least-once delivery and persisted deduplication (RelayClient). | | messenger | Encrypted JSON-RPC over topics (Messenger): requests, responses, notifications, timeouts. | | protocol | Method names, tags and TTLs of the session protocol, the CAIP-2 chain ids (NEURAI_CHAIN_MAINNET, NEURAI_CHAIN_TESTNET), namespaces and error codes. | | caip122 | Sign in with Neurai: the canonical message (formatAuthMessage), CACAO building and checks (buildCacaoPayload, buildCacao, assertCacaoShape), did:pkh helpers and the per-domain identity path (identityPathForDomain). | | storage / browser-storage / record-store | The KeyValueStorage interface the SDKs persist through, a localStorage adapter and an in-memory one. | | jsonrpc / bytes / dedup | Small utilities the modules above share. |

import { formatNcUri, generateRandomBytes32, pairingTopic, RelayClient, MemoryStorage } from "@neuraiproject/neurai-connect-core";

const symKey = generateRandomBytes32();
const uri = formatNcUri({ topic: pairingTopic(symKey), symKey, relayUrl: "wss://relay.neurai.org/v1" });

const relay = new RelayClient({ relayUrl: "wss://relay.neurai.org/v1", storage: new MemoryStorage() });
await relay.connect();

Builds and environments

The package ships ESM and CommonJS builds with type declarations for both. Its cryptography comes from @noble/* 2.x, which is ESM-only: the CommonJS build therefore needs Node 20.19+ or 22.12+, where require() of ES modules is available (React Native's Metro and every bundler handle it natively). In a browser, use BrowserStorage as the storage adapter.

Compatibility

The wire format follows the WalletConnect v2 protocol as implemented by @walletconnect/* 2.21.8, the last Apache-2.0 release; the vectors in spec/vectors were generated with it and this package is tested against them. See spec/compat.md for what is and is not interoperable.

License

MIT.