eddsa-wasm-ll

This crate exposes Silence Laboratories' threshold signing engines as a WebAssembly bundle. The bindings let JavaScript or TypeScript applications run multi-party key generation, signing, and key maintenance flows entirely in the browser, Node.js, or Deno.

The exported API mirrors the Rust implementation found in src/ and the Deno examples in tests/test-eddsa.ts, tests/test-redpallas.ts and tests/test-hard-derive.ts This document pulls the core usage patterns from those tests so you can bootstrap an integration quickly.

Installation

The repository ships six npm artefacts: three targets for each curve family.

• @silencelaboratories/eddsa-wasm-web
• @silencelaboratories/eddsa-wasm-node
• @silencelaboratories/eddsa-wasm-bundler
• @silencelaboratories/redpallas-wasm-web
• @silencelaboratories/redpallas-wasm-node
• @silencelaboratories/redpallas-wasm-bundler

Install the flavour that matches your environment:

npm install @silencelaboratories/eddsa-wasm-web

The package exposes an async default export that initialises the WASM module. Always await it before touching any other primitive.

import initEddsa, {
  KeygenSession,
  Keyshare,
  SignSession,
  Message,
  generateEncryptionKeypair,
} from "@silencelaboratories/eddsa-wasm-web";

await initEddsa();

Distributed Key Generation (DKG)

A DKG flow lets participants parties derive a shared key where any threshold subset can sign. The example below mirrors the helpers in tests/test-eddsa.ts and demonstrates the complete three-round protocol.

const participants = 3;
const threshold = 2;

// Generate the per-party key material used by the protocol.
const { secrets, publicKeys } = generateEncryptionMaterial(participants);

// Spin up a session per participant.
const sessions = secrets.map((secret, party_id) =>
  createKeygenSession(participants, threshold, party_id, secret, publicKeys),
);

// `queue` models the message transport between parties.
const queue = sessions.map((session) => session.createFirstMessage());
while (queue.length > 0) {
  const msg = queue.shift()!;
  const sender = msg.sender();
  const receiver = msg.receiver();

  if (receiver === undefined) {
    for (let partyId = 0; partyId < sessions.length; partyId++) {
      if (partyId === sender) continue;
      queue.push(...sessions[partyId].receiveMessage(msg.clone()));
    }
  } else {
    queue.push(...sessions[receiver].receiveMessage(msg.clone()));
  }
}

// and capture the resulting key shares.
const shares = sessions.map((session) => session.keyshare());

Supporting helpers lifted from the test suite:

type DkgMaterial = {
  secrets: Uint8Array[];
  publicKeys: Uint8Array;
};

type DkgResult = DkgMaterial & { shares: Keyshare[] };

function generateEncryptionMaterial(participants: number): DkgMaterial {
  const secrets: Uint8Array[] = [];
  const publicKeys: Uint8Array[] = [];

  for (let i = 0; i < participants; i++) {
    const pair = generateEncryptionKeypair();
    secrets.push(pair.secretKey);    // random 32 bytes
    publicKeys.push(pair.publicKey); // ed25519 public key
    pair.free();
  }

  return { secrets, publicKeys: concatBytes(publicKeys) };
}

function createKeygenSession(
  participants: number,
  threshold: number,
  partyId: number,
  secretKey: Uint8Array,
  aggregatedPublicKeys: Uint8Array,
): KeygenSession {
  const flattened = aggregatedPublicKeys.slice();
  return new KeygenSession(participants, threshold, partyId, secretKey, flattened);
}

function concatBytes(chunks: Uint8Array[]): Uint8Array {
  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
  const result = new Uint8Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    result.set(chunk, offset);
    offset += chunk.length;
  }
  return result;
}

The resulting shares carry metadata such as the party id, threshold, and public key. See tests/test-eddsa.ts for assertions that confirm the shape of the output.

For the RedPallas curve family (@silencelaboratories/redpallas-wasm-*), use the same DKG helpers as in tests/test-redpallas.ts.

Zcash Orchard derived keys (RedPallas)

When built with the redpallas feature (the default for this crate and the redpallas-wasm-* npm packages), DKG is followed by an additional distributed derivation round. Every participant runs the same message loop as in the DKG section above; once isFinished() is true, each party holds identical Orchard key material in addition to its threshold signing share.

derivedKeys() returns a DerivedOrchardKeys object:

| Property | Role | | --- | --- | | ask | Authorizing key component of the Orchard full viewing key (FVK) | | nk | Nullifier-deriving key component of the FVK | | rivk | Incoming viewing key component of the FVK | | internalIvk | Incoming viewing key for the internal (change) address scope | | externalIvk | Incoming viewing key for the external (payment) address scope |

Together, ask, nk, and rivk are the serialized components needed to reconstruct the Orchard full viewing key in a Zcash wallet or indexer. The internalIvk and externalIvk fields are the scope-specific incoming viewing keys derived alongside the FVK; use them when your integration scans or decrypts notes on internal vs external Orchard addresses.

import initRedpallas, {
  KeygenSession,
  DerivedOrchardKeys,
  generateEncryptionKeypair,
} from "@silencelaboratories/redpallas-wasm-web";

await initRedpallas();

// ... run the same DKG message loop as above on KeygenSession instances ...

if (!sessions.every((s) => s.isFinished())) {
  throw new Error("dkg did not complete");
}

// All parties must agree on the derived Orchard material (see server_web_dkg.rs).
const keys: DerivedOrchardKeys = sessions[0].derivedKeys()!;
for (const session of sessions.slice(1)) {
  const peer = session.derivedKeys()!;
  const match =
    peer.ask.every((b, i) => b === keys.ask[i]) &&
    peer.nk.every((b, i) => b === keys.nk[i]) &&
    peer.rivk.every((b, i) => b === keys.rivk[i]);
  if (!match) {
    throw new Error("derived Orchard keys mismatch across parties");
  }
}

const fvk = { ask: keys.ask, nk: keys.nk, rivk: keys.rivk };
const internalIvk = keys.internalIvk;
const externalIvk = keys.externalIvk;

const shares = sessions.map((s) => s.keyshare());

The pattern above mirrors tests/server_web_dkg.rs, which mixes native zcash server sessions with WASM KeygenSession parties and asserts that ask, nk, and rivk match across every participant before extracting key shares. tests/test-redpallas.ts exercises the full RedPallas DKG and threshold-signing path end-to-end; wire derivedKeys() into your application the same way once the session reports finished.

Keyshare Rerandomization (RedPallas)

When built with redpallas, a threshold quorum can rerandomize existing keyshares via RerandomizeSession. The protocol runs three rounds (commit → open → tweak) and finishes by normalizing the new public key so Orchard ak has ỹ = 0. Use any threshold subset of shares from DKG; the resulting shares keep the same threshold but advertise a new group public key.

The flow mirrors tests/test-redpallas.ts (Rerand 2-of-3 then DSG):

import initRedpallas, {
  Keyshare,
  RerandomizeSession,
  SignSession,
  Message,
} from "@silencelaboratories/redpallas-wasm-web";

await initRedpallas();

// `shares` from a prior RedPallas DKG; pick any threshold-sized subset.
const subset: Keyshare[] = shares.slice(0, threshold);

const sessions = subset.map((share) => new RerandomizeSession(share));

const msg1: Message[] = sessions.map((s) => s.createFirstMessage());
const msg2: Message[] = sessions.flatMap((s) =>
  s.handleMessages(msg1.map((m) => m.clone())),
);

sessions.forEach((s) => {
  const out = s.handleMessages(msg2.map((m) => m.clone()));
  if (out.length !== 0 || !s.isFinished()) {
    throw new Error("rerandomize did not complete");
  }
});

const newShares = sessions.map((s) => s.keyshare());

// New PK differs from the pre-rerand key and has ỹ = 0.
const pk = newShares[0].publicKey;
if ((pk[31] & 0x80) !== 0) {
  throw new Error("rerandomized Orchard ak must have ỹ = 0");
}

// Sign with the rerandomized shares (same DSG loop as below).

Session state can be checkpointed mid-protocol with toBytes() / fromBytes() (see Rerand session toBytes/fromBytes roundtrip then DSG in tests/test-redpallas.ts and rerand_session_roundtrip in tests/keygen.rs). Treat thrown errors as fatal, the same as other sessions; inspect session.error() after a failure.

Threshold Signing (DSG)

Signing reuses the key shares produced during DKG. The snippet below follows the dsg helper from the test suite and shows the three interaction rounds between threshold parties.

const message = crypto.getRandomValues(new Uint8Array(32));
const sharesToUse = shares.slice(0, threshold);

const sessions = sharesToUse.map((share) => new SignSession(share, message, "m"));

const msg1 = sessions.map((session) => session.createFirstMessage());
const msg2 = sessions.flatMap((session) =>
  session.handleMessages(msg1.map((m) => m.clone()))
);
const msg3 = sessions.flatMap((session) =>
  session.handleMessages(msg2.map((m) => m.clone()))
);

sessions.forEach((session) => {
  session.handleMessages(msg3.map((m) => m.clone()));
});

const signatures = sessions.map((session) => session.signature());

The final signatures are raw encodings for the active curve (Ed25519 for the eddsa-wasm-* packages, RedPallas for redpallas-wasm-*). Each SignSession is single-use; discard it after calling signature().

Key Rotation and Share Recovery

The library exposes additional helpers that allow rotating key shares or recovering lost participants:

• KeygenSession.initKeyRotation(share, secretKey, aggregatedPublicKeys)
• KeygenSession.initKeyRecovery(share, lostPartyIds, secretKey, aggregatedPublicKeys)
• KeygenSession.initLostShareRecovery(participants, threshold, partyId, expectedPublicKey, lostPartyIds, secretKey, aggregatedPublicKeys)

The Deno test suite demonstrates a full rotation flow (Key rotation) and a lost-share recovery path (key share recovery) that feed into the session-based DKG helper again to reach steady state. Those tests are excellent references when wiring up similar logic on the application side.

Error Handling

Session methods throw JavaScript exceptions when progress is impossible. Examples from the test suite include:

• Re-playing a round method, e.g. calling createFirstMessage() twice.
• Passing a party its own outgoing message.

Treat these errors as fatal: the protocol state is no longer usable once a method throws. If you need structured errors, inspect the optional session.error() accessor on KeygenSession, SignSession, and RerandomizeSession.

Testing Locally

Run these from wrapper/wasm-ll/. This crate’s Cargo defaults are console_error_panic_hook + redpallas (which pulls the private zcash crate). Ed25519 lives behind eddsa; VRF types (VrfKeygenSession, HardDeriveSession, …) behind vrf. Pass explicit features for each suite:

| Suite | Features | | --- | --- | | Ed25519 DKG / DSG | console_error_panic_hook,eddsa | | VRF DKG + hard derive | console_error_panic_hook,eddsa,vrf | | RedPallas DKG / DSG | console_error_panic_hook,redpallas | | Orchard server/web interop | redpallas,zcash-dkg |

Always pass --no-default-features when building a non-RedPallas flavour locally.

• Deno integration tests (build WASM first, then test):

  # Ed25519
  wasm-pack build -t web . -- --no-default-features --features console_error_panic_hook,eddsa
  deno test -A tests/test-eddsa.ts
  
  # VRF hard derivation
  wasm-pack build -t web . -- --no-default-features --features console_error_panic_hook,eddsa,vrf
  deno test -A tests/test-hard-derive.ts
  
  # RedPallas (requires a Kellnr registry token for the optional zcash dependency)
  wasm-pack build -t web . -- --no-default-features --features console_error_panic_hook,redpallas
  deno test -A tests/test-redpallas.ts

• Rust / WASM harnesses:

  # Ed25519
  cargo test --no-default-features --features eddsa
  wasm-pack test --node --no-default-features --features eddsa
  
  # VRF (integration tests in tests/vrf.rs + wasm_bindgen tests)
  cargo test --no-default-features --features eddsa,vrf
  wasm-pack test --node --no-default-features --features eddsa,vrf

• Orchard derivation interop between native server sessions and WASM web parties (tests/server_web_dkg.rs):

  cargo test -r --no-default-features --features redpallas,zcash-dkg \
    --test server_web_dkg test_server_web_dkg_derivation_interop

• VRF DKG + hard-derive interop between native server sessions and WASM web parties (tests/server_web_vrf.rs):

  cargo test -r --no-default-features --features eddsa,vrf --test server_web_vrf

From the repo root, add -p eddsa-wasm-ll to cargo test commands.

Licensing

This wrapper is released under the Silence Laboratories License Agreement. See LICENSE for the full text.