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 and tests/test-redpallas.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.

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 both KeygenSession and SignSession.

Testing Locally

The repository includes complementary test suites:

• Rust-side harnesses (wasm-pack test --node -r and cargo test --all).

• Deno integration tests for the generated bindings:

  # Ed25519 (eddsa feature)
  deno test -A tests/test-eddsa.ts
  
  # RedPallas DKG + DSG (requires a redpallas web build first)
  wasm-pack build -t web . --features redpallas --no-default-features
  deno test -A tests/test-redpallas.ts

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

  cargo test -r -p eddsa-wasm-ll \
    --features redpallas,zcash-dkg --no-default-features \
    --test server_web_dkg test_server_web_dkg_derivation_interop

Licensing

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