API reference

This page lists the public surface of openac-sdk 0.1.0 — class methods, top-level functions, and exported types — with the source files where each is defined. The auto-generated TypeDoc is built into static/api/openac-sdk/ whenever you run npm run build (which invokes npm run api:typedoc first) and is served from the same site under /api/openac-sdk/.

Experimental API

The 0.x surface is unstable. Names, parameters, and serialization formats may change without notice until the SDK reaches 1.0. See SDK overview for status.

OpenAC

src/index.ts — top-level facade. Construct with OpenAC.init(...); the constructor is private.

static init(config?): Promise<OpenAC>

Parameter	Type	Required	Description
config.wasmPath	string	No	URL or path to a wasm-bindgen JS shim. Omit to use the bundled module.
config.wasmModule	any	No	Pre-imported WASM module (overrides wasmPath). Useful for bundlers that handle WASM themselves.
config.assetsDir	string	No	Filesystem or URL directory holding prepare.r1cs, prepare_js/prepare.wasm, show.r1cs, show_js/show.wasm.
config.artifacts	CircuitArtifacts	No	Inline witness-calculator assets (overrides assetsDir).
config.memory	{ initial?: number; maximum?: number }	No	WebAssembly memory hints; otherwise defaults from wasm-bindgen.

If assetsDir / artifacts cannot be loaded, the WitnessCalculator is silently skipped — precompute will then require pre-built witnesses.

loadKeysFromUrl(baseUrl, vcSize): Promise<KeySet>

Fetches ${baseUrl}/${vcSize}_{prepare,show}_{proving,verifying}.key.

Parameter	Type	Description
baseUrl	string	Directory URL with no trailing slash.
vcSize	'1k' | '2k' | '4k' | '8k'	JWT-size bucket. See Installation – Proving keys.

Throws WasmError("KEY_LOAD_FAILED") on any non-200 response.

loadKeys(data): Promise<KeySet>

Wraps an already-fetched SerializedKeySet in a KeySet (adds verifyingKeys() and serialize() accessors).

precompute(request): Promise<PrecomputedCredential>

Runs the Prepare half: parses the SD-JWT, builds JWT circuit inputs, generates the witness, and produces prepareProof + prepareInstance + the reblindable witness. See Prepare phase.

PrecomputeRequest (types.ts):

Field	Type	Required	Description
jwt	string	Yes	Compact SD-JWT (header.payload.signature).
disclosures	string[]	Yes	Base64url disclosure strings.
issuerPublicKey	EcdsaPublicKey | PemPublicKey	Yes	P-256 JWK or PEM wrapper.
keys	KeySet	Yes	Output of loadKeysFromUrl / loadKeys.
jwtParams	JwtCircuitParams	No	Overrides DEFAULT_JWT_PARAMS.
birthdayClaimIndex	number	No	Index of a birthday claim in the disclosure array (resolves automatically when omitted).
decodeFlags	number[]	No	Per-match flag (0 = raw, 1 = URL-decoded). Defaults to zeros.
claimFormats	number[]	No	Per-claim format (0 = string, 1 = integer). Defaults to zeros.
additionalMatches	string[]	No	Extra substring patterns to extract.

present(request): Promise<PresentationProof>

Runs the Show half: signs the verifier nonce with the device key, builds Show circuit inputs, generates the witness, proves Show, and reblinds both halves through the single present WASM call. See Show phase.

PresentRequest (types.ts):

Field	Type	Required	Description
precomputed	PrecomputedCredential	Yes	Result of precompute.
verifierNonce	string	Yes	Fresh challenge from the verifier. Bound into the proof.
devicePrivateKey	string | Uint8Array	Yes	Holder's P-256 private key (hex string or bytes).
keys	KeySet	Yes	Same KeySet used in precompute.
showParams	ShowCircuitParams	No	Overrides DEFAULT_SHOW_PARAMS.
showInputOptions	ShowInputOptions	No	Predicate spec, claim values, postfix logic expression.

verify(proof, keys): Promise<VerificationResult>

Checks both proofs, the linking commitment, and the device signature in-circuit. Equivalent to verifyComponents(proof.prepareProof, proof.showProof, keys, proof.prepareInstance, proof.showInstance).

Field returned	Type	Notes
valid	boolean	False on any deserialization or check failure (see error).
expressionResult	boolean | null	Postfix expression output; null if valid is false.
deviceKey	{ x: string; y: string } | null	Hex-encoded public key extracted from public outputs.
verifyMs	number	Wall-clock verification time.
error	string | undefined	Diagnostic when valid is false.

createProof(request): Promise<ProofResult> (legacy one-shot)

Combines precompute + present in a single call. Retained for migration; prefer the split API for production wallets.

verifyProof(bytes, keys): Promise<VerificationResult> and verifyComponents(...)

Verify a serialized bundle (Uint8Array) or individual proof components. Use verify(proof, keys) unless you have a custom transport.

get isReady: boolean

True after init resolves. loadKeys* and the prove/verify methods require isReady === true.

Top-level functions

Symbol	Defined in	Purpose
Credential.parse(jwt, disclosures)	src/credential.ts	Parses an SD-JWT, validates the device binding key, exposes disclosedClaims, findBirthdayClaim().
buildJwtCircuitInputs(...)	src/inputs/jwt-input-builder.ts	Pre-flight inputs for the Prepare circuit.
buildShowCircuitInputs(params, nonce, sig, deviceKey, options)	src/inputs/show-input-builder.ts	Pre-flight inputs for the Show circuit. Verifies the device signature locally and throws INVALID_SIGNATURE on mismatch.
signDeviceNonce(nonce, privateKey)	src/inputs/show-input-builder.ts	ECDSA-P256 over sha256(nonce). Returns base64url-encoded compact signature.
PredicateOp / LogicToken	src/inputs/show-input-builder.ts	Numeric codes shared with eval-predicate.circom.
deserializePrecomputed(json)	src/prover.ts	Reconstructs a PrecomputedCredential from SerializedPrecomputedCredentialJSON.
WitnessCalculator	src/witness-calculator.ts	Low-level Circom witness runner; exposed for callers that want to manage R1CS / .wasm themselves.
NativeBackend	src/native-backend.ts	Node-only wrapper around the ecdsa-spartan2 Rust CLI. See Native backend.

Encoding / numeric helpers (base64Encode, base64urlEncode, bytesToBigInt, bigintToBytes, sha256Pad, sha256Hash, encodeClaims, modInverse, modScalarField, jwkPointToBigInt, P256_SCALAR_ORDER, …) are re-exported from src/utils.ts.

Constants

Constant	Value	Source
DEFAULT_JWT_PARAMS	See Prepare phase – DEFAULT_JWT_PARAMS.	src/types.ts
DEFAULT_SHOW_PARAMS	See Show phase – DEFAULT_SHOW_PARAMS.	src/types.ts
P256_SCALAR_ORDER	$2^{256} - 2^{224} + 2^{192} + 2^{96} - 1 \pmod{n_{\text{P-256}}}$ — the P-256 scalar field order $n$.	src/utils.ts

Errors

All errors extend OpenACError and expose a code: ErrorCode. See Errors for the cause / remediation table.

Types

The SDK re-exports the following types from src/types.ts:

OpenACConfig, ProofRequest, ProofResult, ProofTiming, ProofPublicValues, VerificationResult, VerifyingKeys, KeySet, SerializedKeySet, SerializedProof, SerializedProofJSON, DisclosedClaim, EcdsaPublicKey, EcdsaPrivateKey, IssuerPublicKey, PemPublicKey, JwtCircuitParams, ShowCircuitParams, JwtCircuitInputs, ShowCircuitInputs, CircuitArtifacts, ErrorCode, PrecomputeRequest, PrecomputedCredential, PrecomputeTiming, PresentRequest, PresentationProof, PresentationTiming, SerializedCredential, SerializedPrecomputedCredentialJSON. Each one is documented in the TypeDoc HTML linked at the top of this page.