@solidus-network/sdk

The main SDK package. The createSdk factory returns a client with three namespaces: did, credentials, and auth.


import { createSdk } from '@solidus-network/sdk'
 
const sdk = createSdk({
  mode: 'testnet',
  rpcUrl: 'https://rpc.solidus.network',
  signerPrivateKey: '0xabc...def',
})

Configuration


interface SolidusConfig {
  mode: 'stub' | 'testnet' | 'mainnet'
  rpcUrl?: string           // JSON-RPC endpoint URL (testnet/mainnet modes; default http://127.0.0.1:9944)
  signerPrivateKey?: string // Hex-encoded Ed25519 private key — only required by did.create()
}

mode: 'stub' runs against a local Postgres-backed stub with no network calls (local dev). mode: 'testnet' and 'mainnet' connect over JSON-RPC. signerPrivateKey is optional at the top level — every signing operation except did.create() takes its key as an explicit per-call argument instead (e.g. credentials.issue({issuerPrivateKey, ...}), credentials.revoke(id, issuerKey)).

Transaction signing uses Ed25519 over BLAKE3(publicKey || nonce_le || json(payload)).

Address derivation computes BLAKE3(publicKey), takes the first 20 bytes, and base58-encodes the result.

did.create

Registers a DID on-chain for the public key owned by the SDK’s configured signerPrivateKey. Throws if signerPrivateKey doesn’t own the supplied public key — use did.buildCreate() + did.submitCreate() instead to relay a DID that a different key signs (e.g. a frontend signs locally, a backend relays).


sdk.did.create(publicKey: string): Promise<DID>

Parameters

Name	Type	Description
`publicKey`	`string`	Hex-encoded Ed25519 public key (32 bytes) — must match the configured signer

Returns a DID descriptor — {id, controller, created, updated, network} — not a full DIDDocument. Use did.resolve() to fetch the full document.

Example


const did = await sdk.did.create(publicKeyHex)
 
console.log(did.id)
// "did:solidus:testnet:7Kf9xB2..."
 
const document = await sdk.did.resolve(did.id)
console.log(document.verificationMethod[0].type)
// "Ed25519VerificationKey2020"

did.resolve

Resolves an existing DID to its document.


sdk.did.resolve(did: string): Promise<DIDDocument | null>

Parameters

Name	Type	Description
`did`	`string`	The DID to resolve (e.g. `did:solidus:testnet:7Kf9...`)

Returns the DIDDocument if found, or null if the DID does not exist or has been deactivated.

Example


const doc = await sdk.did.resolve('did:solidus:testnet:7Kf9xB2...')
 
if (doc) {
  console.log(doc.authentication)
  // ["did:solidus:testnet:7Kf9xB2...#key-1"]
} else {
  console.log('DID not found')
}

did.deactivate

Permanently deactivates a DID. After deactivation, did.resolve returns null and any credentials issued to this DID can no longer be verified.


sdk.did.deactivate(did: string, signerKey: string): Promise<void>

Parameters

Name	Type	Description
`did`	`string`	The DID to deactivate
`signerKey`	`string`	Hex-encoded Ed25519 private key of the DID’s current controller

Example


await sdk.did.deactivate('did:solidus:testnet:7Kf9xB2...', signerPrivateKeyHex)
// DID is now permanently deactivated

credentials.issue

Issues a new verifiable credential on-chain.


sdk.credentials.issue(params: IssueCredentialParams): Promise<VerifiableCredential>

Parameters

Name	Type	Required	Description
`subjectDid`	`string`	Yes	DID of the credential subject
`issuerDid`	`string`	Yes	DID of the issuer
`issuerPrivateKey`	`string`	Yes	Hex-encoded Ed25519 private key of the issuer
`type`	`string[]`	Yes	Credential types (e.g. `['VerifiableCredential', 'KYCCredential']`)
`claims`	`Record<string, unknown>`	Yes	Claims to include in `credentialSubject`
`expiresInDays`	`number`	No	Days until expiration (omit for no expiry)
`network`	`string`	No	Network override (`'testnet'` or `'mainnet'`)

Returns a VerifiableCredential with a cryptographic proof attached.

Example


const credential = await sdk.credentials.issue({
  subjectDid: 'did:solidus:testnet:subject123',
  issuerDid: 'did:solidus:testnet:issuer456',
  issuerPrivateKey: '0xabc...def',
  type: ['VerifiableCredential', 'KYCCredential'],
  claims: {
    level: 2,
    country: 'DE',
    documentType: 'passport',
    verifiedAt: '2026-05-07T12:00:00Z',
  },
  expiresInDays: 365,
})
 
console.log(credential.id)
// "urn:uuid:a1b2c3d4-..."
 
console.log(credential.proof.type)
// "Ed25519Signature2020"

credentials.verify

Looks up a credential by ID on-chain and checks its signature, expiry, and revocation status. Takes the credential’s ID, not the credential object.


sdk.credentials.verify(vcId: string): Promise<VerificationResult>

Parameters

Name	Type	Description
`vcId`	`string`	The credential ID to verify (e.g. `credential.id`)

Returns a VerificationResult with the overall validity and individual check results. The chain validates signatures at submission time and Solidus credentials don’t expire on-chain, so signature and expiry report true for any credential found; revocation reflects the current on-chain revocation state.


interface VerificationResult {
  valid: boolean
  credentialId?: string
  error?: string
  checks: {
    signature: boolean
    expiry: boolean
    revocation: boolean
  }
}

Example


const result = await sdk.credentials.verify(credential.id)
 
if (result.valid) {
  console.log('Credential is valid')
  console.log('Credential ID:', result.credentialId)
} else {
  console.log('Verification failed:', result.error)
  console.log('Not revoked:', result.checks.revocation)
}

credentials.revoke

Revokes a credential by its ID. Once revoked, credentials.verify will return checks.revocation: false.


sdk.credentials.revoke(credentialId: string, issuerKey: string): Promise<void>

Parameters

Name	Type	Description
`credentialId`	`string`	The credential ID (e.g. `urn:solidus:credential:...`)
`issuerKey`	`string`	Hex-encoded Ed25519 private key of the issuer

Example


await sdk.credentials.revoke('urn:solidus:credential:...', issuerPrivateKeyHex)
// Credential is now revoked on-chain

credentials.query

Queries all credentials issued to a given DID.


sdk.credentials.query(subjectDid: string): Promise<VerifiableCredential[]>

Parameters

Name	Type	Description
`subjectDid`	`string`	The DID to query credentials for

Returns an array of VerifiableCredential objects.

Example


const credentials = await sdk.credentials.query(
  'did:solidus:testnet:subject123'
)
 
for (const cred of credentials) {
  console.log(cred.type, cred.validFrom)
}
// ["VerifiableCredential", "KYCCredential"] "2026-05-07T12:00:00Z"

auth.createChallenge

Creates an authentication challenge scoped to a domain and returns its ID as a plain string (in testnet/mainnet mode the SDK tracks the challenge server-side, keyed by this ID).


sdk.auth.createChallenge(domain: string): Promise<string>

Parameters

Name	Type	Description
`domain`	`string`	The relying-party domain the challenge is scoped to

Returns the challenge ID as a string.

Example


const challengeId = await sdk.auth.createChallenge('myapp.example.com')

sdk.auth is a different, higher-level surface than the standalone @solidus-network/auth package’s createChallenge/verifyPresentation functions (which return a full Challenge object and take an explicit public-key resolver). If you need the DID-bound challenge/nonce details, see the @solidus-network/auth reference.

auth.verifyPresentation

Verifies a signed verifiable presentation (as a JSON string) against a previously issued challenge ID, resolving the holder’s DID document from the chain to check the signature.


sdk.auth.verifyPresentation(
  vp: string,
  challenge: string,
  domain: string,
): Promise<AuthResult>

Parameters

Name	Type	Description
`vp`	`string`	The signed `VerifiablePresentation`, JSON-stringified
`challenge`	`string`	The challenge ID returned by `auth.createChallenge`
`domain`	`string`	The relying-party domain

Returns an AuthResult:


interface AuthResult {
  valid: boolean
  did?: string
  claims?: Record<string, unknown>
  error?: string
}

Example


const result = await sdk.auth.verifyPresentation(
  JSON.stringify(signedPresentation),
  challengeId,
  'myapp.example.com',
)
 
if (result.valid) {
  console.log('Authenticated as:', result.did)
} else {
  console.log('Auth failed:', result.error)
}