@solidus-network/sdk

The client SDK for the Solidus Network identity protocol — DID create/resolve/recovery, verifiable-credential issuance and verification (W3C VC 2.0 + SD-JWT VC), BBS+ selective-disclosure credential envelopes, and direct JSON-RPC access to the Solidus chain, behind one client.

Status: Solidus runs on testnet only — there is no mainnet and no $SLDS token distribution yet. did:solidus is registered in the W3C DID Method Registry (a listing of DID methods, not a standards-track endorsement). BBS+ credential primitives are testnet-grade with an external audit pending — see @solidus-network/bbs.

Install

npm install @solidus-network/sdk
# or
pnpm add @solidus-network/sdk

Quick start

import { createSdk, generateKeypair } from '@solidus-network/sdk'

// testnet/mainnet mode requires a signer key at construction time, even for
// read-only calls — generate a throwaway one if you don't have one yet.
const { privateKey } = await generateKeypair()

const solidus = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network', // or set SOLIDUS_RPC_URL
  signerPrivateKey: privateKey,          // or set SOLIDUS_SIGNER_KEY
})

// Resolve a DID
const doc = await solidus.did.resolve('did:solidus:testnet:<abc123>')

To verify a credential you already hold, call credentials.verify with its id (not the credential object itself):

const result = await solidus.credentials.verify(myCredential.id)
if (result.valid) {
  console.log(result.checks) // { signature, expiry, revocation }
}

Modes

import { createSdk } from '@solidus-network/sdk'

// stub mode reads its Postgres connection from SOLIDUS_STUB_DB_URL
const dev = createSdk({ mode: 'stub' })

const live = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network',
  signerPrivateKey: process.env.SOLIDUS_SIGNER_KEY,
})

• stub — local Postgres-backed mock for development; no chain interaction, same interface as chain mode. Requires SOLIDUS_STUB_DB_URL in the environment.
• testnet — talks to a Solidus chain node over JSON-RPC. The public endpoint is rpc.solidus.network; the SDK's built-in default is http://127.0.0.1:9944 (a local dev node), so pass rpcUrl or set SOLIDUS_RPC_URL to reach the public chain.
• mainnet — reserved. Solidus has not launched mainnet — don't use this mode in production today.

Features

Tied to what's actually exported from the package:

• DIDs — did.create / did.buildCreate + did.submitCreate (split sign-then-relay, for holder-signs / backend-relays flows) / did.resolve / did.deactivate.
• DID social recovery — recoverySigningMessage, signAsGuardian, buildRecover / submitRecover, buildSetRecoveryPolicy — byte-compatible with the on-chain Rust primitive.
• Verifiable credentials — credentials.issue / verify / revoke / query, W3C VC Data Model 2.0 shape (validFrom / validUntil).
• SD-JWT VC — issueSdJwtVc, verifySdJwtVc, presentSdJwtVc (holder presentation + Key-Binding JWT), createStatusListJwt. Built for EUDI-Wallet-style interop.
• BBS+ credential envelopes (on-chain) — sdk.bbs.issueCredential / verifyProof / verifyCredentialProof, chain mode only. For client-side BBS+ signing and selective-disclosure proof generation, pair this with @solidus-network/bbs.
• Privacy: one-seed key hierarchy — deriveValueKeyFromSeed, derivePairwiseKeyFromSeed, derivePodWrapKey, derivePidFromSeed, pairwiseDid, scanValueAccounts — one seed, deterministically separated into identity / value / pairwise / pod-wrap keys so DID resolution never links to payment activity.
• Pod credential storage — sealCredentialBundle / openCredentialBundle (AES-256-GCM at rest) and multi-device sync (syncBundleToPod, restoreBundleFromPod, createHttpPodBundleClient).
• Chain client — getChainInfo, chain.transfer, chain.getBalance, chain.sendTransaction, chain.getNonce, chain.getRecoveryInfo.
• DID auth — auth.createChallenge / verifyPresentation; see @solidus-network/auth for the full DID challenge/response and unlinkable-presentation flow.
• Drop-in stub mode for local development against Postgres, with the same interface as chain mode.

Related packages

• @solidus-network/auth — DID challenge/response authentication and DID-less BBS+ unlinkable-presentation verification
• @solidus-network/bbs — BBS+ selective-disclosure primitives (client-side signing and proof generation)
• @solidus-network/types — shared TypeScript types (DIDs, verifiable credentials, auth results)

Documentation

Full docs: docs.solidus.network · SDK reference · Whitepaper · Protocol spec

See CHANGELOG.md for release history.

License

Apache-2.0 — see LICENSE.