Skip to main content
Version: 1.9

EdBls12377

@sodot/sodot-node-sdk • Docs

@sodot/sodot-node-sdk / EdBls12377

Class: EdBls12377

Class providing the functionality for threshold Aleo signing with frost-ed-bls12-377.

Example​

const N = 3;
const T = 2;
const edBls12377 = new EdBls12377();
const API_KEY = 'MY_API_KEY';
const bytes32 = (value: number) => Uint8Array.from([value, ...new Uint8Array(31)]);

// Your backend creates a room for key generation.
const keygenRoomUuid = await edBls12377.createRoom(N, API_KEY);

// All parties initialize keygen and exchange keygen IDs through an authenticated channel.
const keygenInitResult = await edBls12377.initKeygen();
const keygenIds = [otherParty1KeygenId, otherParty2KeygenId];

// Each party joins keygen.
const keygenResult = await edBls12377.keygen(keygenRoomUuid, N, T, keygenInitResult, keygenIds);

// Sign Aleo request fields.
const signingRoomUuid = await edBls12377.createRoom(T, API_KEY);
const payload = {
  function_id: bytes32(0x29),
  is_root: false,
  program_checksum: bytes32(0x0b),
  inputs: [{ type: 'constant', index: bytes32(0x00), fields: [bytes32(0x01)] }],
};
const signedRequest = await edBls12377.signRequest(signingRoomUuid, keygenResult, payload);

Extends​

  • EdBls12377

Constructors​

new EdBls12377()​

new EdBls12377(hostUrl?): EdBls12377

Parameters​

• hostUrl?: string

Returns​

EdBls12377

Overrides​

EdBls12377Internal.constructor

Methods​

createRoom()​

createRoom(numParties, apiKey): Promise<string>

Creates a room for the given number of parties. A room is a one-time instance used to perform a single MPC operation (keygen/signing/refresh/reshare/export/import).

This function should be called in the backend so to not embed the API key in code that is distributed to users.

Parameters​

• numParties: number

The number of parties that will join the room. (an integer in range 1..65_535)

• apiKey: string

An API key required to create a room.

Returns​

Promise<string>

The UUID of the created room.

Inherited from​

EdBls12377Internal.createRoom

exportFullPrivateKey()​

exportFullPrivateKey(roomUuid, keygenResult, toExportID): Promise<undefined | string>

Extracts a full private key to a single designated party. Requires a threshold amount of parties in the export room.

Parameters​

• roomUuid: string

The UUID of the full-key export room.

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult participating in export, or the secret share as a string.

• toExportID: string

The export ID returned by EdBls12377.exportID of the party receiving the key.

Returns​

Promise<undefined | string>

The receiving party gets a private key string, other participants get undefined.

Inherited from​

EdBls12377Internal.exportFullPrivateKey

exportID()​

exportID(keygenResult): Promise<string>

Returns this party's export ID used in key extraction protocols.

The party that expects to receive the extracted key needs to call this function before EdBls12377.exportFullPrivateKey or EdBls12377.exportViewKey, and then share the returned ID with the threshold participants.

Parameters​

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult that contains the secret share to be used for key extraction, or the secret share as a string.

Returns​

Promise<string>

A base58 export ID string.

Inherited from​

EdBls12377Internal.exportID

exportViewKey()​

exportViewKey(roomUuid, keygenResult, toExportID): Promise<undefined | string>

Extracts a view key to a single designated party. Requires a threshold amount of parties in the export room.

Parameters​

• roomUuid: string

The UUID of the view-key export room.

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult participating in export, or the secret share as a string.

• toExportID: string

The export ID returned by EdBls12377.exportID of the party receiving the view key.

Returns​

Promise<undefined | string>

The receiving party gets a view key string, other participants get undefined.

Inherited from​

EdBls12377Internal.exportViewKey

importPrivateKeyImporter()​

importPrivateKeyImporter(roomUuid, threshold, privateKey, keygenInit, keygenIds, isPrivateKeyRaw): Promise<EdBls12377KeygenResult>

WARNING: Private key import is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it, due to a full private key being imported from a different system. Secret shares generated from imported private keys will always have the risk of the private key having been compromised in the past or in the future in case the private key is not deleted after the import operation.

This method is for the importing party that provides the full private key material.

Parameters​

• roomUuid: string

The UUID of the import room.

• threshold: number

The threshold of the new quorum. (an integer in range 1..65_535)

• privateKey: string

A hex string private key. Interpreted as seed (32 bytes) by default, or raw key material when isPrivateKeyRaw is true.

• keygenInit: EdBls12377InitKeygenResult

The local EdBls12377InitKeygenResult for this importing party.

• keygenIds: string[]

IDs of all other parties participating in the import ceremony.

• isPrivateKeyRaw: boolean = false

Optional, defaults to false. Set to true if privateKey is raw key material rather than a seed.

Returns​

Promise<EdBls12377KeygenResult>

A new EdBls12377KeygenResult derived from the imported key.

Inherited from​

EdBls12377Internal.importPrivateKeyImporter

importPrivateKeyRecipient()​

importPrivateKeyRecipient(roomUuid, threshold, keygenInit, keygenIds): Promise<EdBls12377KeygenResult>

WARNING: Private key import is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it, due to a full private key being imported from a different system. Secret shares generated from imported private keys will always have the risk of the private key having been compromised in the past or in the future in case the private key is not deleted after the import operation.

This method is for a recipient party that does not possess the full private key and receives a threshold share during import.

Parameters​

• roomUuid: string

The UUID of the import room.

• threshold: number

The threshold of the new quorum. (an integer in range 1..65_535)

• keygenInit: EdBls12377InitKeygenResult

The local EdBls12377InitKeygenResult for this recipient.

• keygenIds: string[]

IDs of all other parties participating in the import ceremony.

Returns​

Promise<EdBls12377KeygenResult>

A new EdBls12377KeygenResult derived from the imported key.

Inherited from​

EdBls12377Internal.importPrivateKeyRecipient

initKeygen()​

initKeygen(): Promise<EdBls12377InitKeygenResult>

All parties must call this function before calling EdBls12377.keygen. The resulting EdBls12377InitKeygenResult.keygenId must be sent through an authenticated communication channel to all other participating parties.

Returns​

Promise<EdBls12377InitKeygenResult>

An EdBls12377InitKeygenResult that contains a base58 keygenId and keygenSecret.

Inherited from​

EdBls12377Internal.initKeygen

keygen()​

keygen(roomUuid, numParties, threshold, keygenInit, keygenIds): Promise<EdBls12377KeygenResult>

Generates a threshold compute_key/address pair for the given number of parties and threshold.

notice

The keygenInit object should be discarded after successful completion of this call.

Parameters​

• roomUuid: string

The UUID of the keygen room.

• numParties: number

The number of parties in the keygen room. (an integer in range 1..65_535)

• threshold: number

The signing threshold. (an integer in range 1..65_535)

• keygenInit: EdBls12377InitKeygenResult

The same EdBls12377InitKeygenResult returned by this party's EdBls12377.initKeygen call.

• keygenIds: string[]

keygenId outputs from initKeygen() of all other parties in the keygen ceremony.

Returns​

Promise<EdBls12377KeygenResult>

An EdBls12377KeygenResult that contains computeKey, address, and secretShare.

Inherited from​

EdBls12377Internal.keygen

offlineExportFullPrivateKey()​

offlineExportFullPrivateKey(keygenResults): Promise<string>

Locally reconstructs the full private key from threshold key shares, without using the relay server.

Parameters​

• keygenResults: string[] | EdBls12377KeygenResult[]

A threshold-sized array of EdBls12377KeygenResult values, or secret-share strings.

Returns​

Promise<string>

The reconstructed full private key string.

Inherited from​

EdBls12377Internal.offlineExportFullPrivateKey

offlineExportViewKey()​

offlineExportViewKey(keygenResults): Promise<string>

Locally reconstructs the view key from threshold key shares, without using the relay server.

Parameters​

• keygenResults: string[] | EdBls12377KeygenResult[]

A threshold-sized array of EdBls12377KeygenResult values, or secret-share strings.

Returns​

Promise<string>

The reconstructed view key string.

Inherited from​

EdBls12377Internal.offlineExportViewKey

refresh()​

refresh(roomUuid, keygenResult): Promise<EdBls12377KeygenResult>

Refreshes the secret key material of all parties without changing the public identity (computeKey / address).

Parameters​

• roomUuid: string

The UUID of the refresh room.

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult to refresh, or the secret share as a string.

Returns​

Promise<EdBls12377KeygenResult>

A fresh EdBls12377KeygenResult with the same computeKey/address and new secretShare.

Inherited from​

EdBls12377Internal.refresh

reshareNewParty()​

reshareNewParty(roomUuid, oldThreshold, newThreshold, keygenInit, keygenIds): Promise<EdBls12377KeygenResult>

WARNING: Key resharing is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it, as incorrect usage might lead to the detriment of the private key security. To use the feature correctly, developers using this feature must make sure that at least n - t + 1 parties of the t-of-n signing quorum delete their current shares before using the resharing of the private key. Also, after resharing, the resharing operation must not be considered complete until such deletion has occurred. Since deleting a share cannot be guaranteed cryptographically, it must be guaranteed by the software architecture (hence, by the developers using the SDK).

This method is for a new party (one that does not currently hold a share) joining a resharing ceremony.

Parameters​

• roomUuid: string

The UUID of the reshare room.

• oldThreshold: number

The old threshold of the existing quorum. (an integer in range 1..65_535)

• newThreshold: number

The new threshold after resharing. (an integer in range 1..65_535)

• keygenInit: EdBls12377InitKeygenResult

The local EdBls12377InitKeygenResult for the new party.

• keygenIds: string[]

IDs of parties in the new quorum (initKeygen() for new parties, exportID() for remaining parties).

Returns​

Promise<EdBls12377KeygenResult>

A new EdBls12377KeygenResult for the reshared quorum.

Inherited from​

EdBls12377Internal.reshareNewParty

reshareRemainingParty()​

reshareRemainingParty(roomUuid, newThreshold, keygenResult, keygenIds): Promise<EdBls12377KeygenResult>

WARNING: Key resharing is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it, as incorrect usage might lead to the detriment of the private key security. To use the feature correctly, developers using this feature must make sure that at least n - t + 1 parties of the t-of-n signing quorum delete their current shares before using the resharing of the private key. Also, after resharing, the resharing operation must not be considered complete until such deletion has occurred. Since deleting a share cannot be guaranteed cryptographically, it must be guaranteed by the software architecture (hence, by the developers using the SDK).

This method is for a remaining party (one that already holds a share) joining a resharing ceremony.

Parameters​

• roomUuid: string

The UUID of the reshare room.

• newThreshold: number

The new threshold after resharing. (an integer in range 1..65_535)

• keygenResult: string | EdBls12377KeygenResult

The existing EdBls12377KeygenResult, or the secret share as a string.

• keygenIds: string[]

IDs of parties in the new quorum (initKeygen() for new parties, exportID() for remaining parties).

Returns​

Promise<EdBls12377KeygenResult>

A new EdBls12377KeygenResult for the reshared quorum.

Inherited from​

EdBls12377Internal.reshareRemainingParty

signBytes()​

signBytes(roomUuid, keygenResult, message): Promise<string>

Signs an arbitrary byte message using a threshold subset of parties.

Produces an Aleo Schnorr signature matching snarkVM's Signature::sign_bytes / Signature::verify_bytes. The signature is returned as a bech32 sign1... string suitable for the snarkVM Signature::from_str parser, and verifies against the threshold key's address (returned in EdBls12377KeygenResult.address).

The native side bit-packs message into 252-bit field-element chunks before signing; messages up to ~128 KiB are supported. Signing fails before any MPC traffic if the message is too large, or if its packed form structurally matches an Aleo request preimage (a cross-protocol confusion guard — see SigningError::MessageLooksLikeRequest).

Parameters​

• roomUuid: string

The UUID of the signing room.

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult that contains the secret share used for signing, or the secret share as a string.

• message: Uint8Array

The raw bytes to sign.

Returns​

Promise<string>

The bech32-encoded Aleo Signature string.

Inherited from​

EdBls12377Internal.signBytes

signRequest()​

signRequest(roomUuid, keygenResult, requestPayload): Promise<EdBls12377SignedRequest>

Signs Aleo request fields using a threshold subset of parties. Non-record inputs use { type, index, fields }. Record inputs use { type: 'record', h, tag }. All request fields are exposed as Uint8Array; the SDK hex-encodes them when calling the native bindings.

Parameters​

• roomUuid: string

The UUID of the signing room.

• keygenResult: string | EdBls12377KeygenResult

The EdBls12377KeygenResult that contains the secret share used for signing, or the secret share as a string.

• requestPayload: EdBls12377RequestSignPayload

The Aleo request payload fields to sign.

Returns​

Promise<EdBls12377SignedRequest>

The signed Aleo request as EdBls12377SignedRequest, containing byte-encoded signer, signature, tvk, and gammas.

Inherited from​

EdBls12377Internal.signRequest