@entropyxyz/entropy-protocol-bundler

entropy-protocol

This contains wasm bindings to the entropy-protocol crate, for encrypting and decrypting messages to and from entropy TSS servers, and for executing the Entropy signing and DKG protocols on the client side when using private access mode.

Exposed to JS:

• Hpke - for signing and encrypting / decrypting
• X25519Keypair - for creating encryption keypairs
• runDkgProtocol - for registering in private access mode
• runSigningProtocol - for signing in private access mode
• ValidatorInfo - details of a TSS node
• KeyShare - a Synedrion ECDSA signing key-share

Helpers:

• toHex - convert a Uint8Array to hex-encoded string
• fromHex - convert a hex-encoded string to a Uint8Array, ignoring 0x prefix
• constantTimeEq - compare 2 Uint8Arrays in constant time

A note on using this on NodeJS

The private mode functions runDkgProtocol and runSigningProtocol expect to have access to the browser websockets API, which is not present on NodeJS. If you want to use these functions on NodeJS you must have the dependency ws as a property of the global object like so:

Object.assign(global, { WebSocket: require('ws') })

This is tested in CI with ws version ^8.14.2.

Hpke

This is used for communicating with TSS servers and uses Hybrid Public Key Encryption based on chacha20poly1305 with X25519 key agreement, as well as sr25519 signing.

Hpke.publicKeyFromSecret

Given an sr25519 secret key, derive an X25519 DH keypair and return the public key as a 32 bytes Uint8Array.

Hpke.encryptAndSign

Encrypt and sign a message. Takes an sr25519 secret key, a payload to encrypt, and the recipient's public x25519 key, all given as Uint8Arrays. Returns an EncryptedSignedMessage as a JSON serialized string.

Hpke.decryptAndVerify

Decrypt and verify an EncryptedSignedMessage. Takes an x25519 secret key given as a Uint8Array, and a JSON serialized SignedMessage containing the encrypted payload. On successful decryption and signature verification it will return the decrypted payload as a Uint8Array.

Hpke.generateSigningKey

Generates a secret sr25519 signing key and returns it as a Uint8Array. This is really only exposed for testing purposes, as you can also use Polkadot-JS to generate sr25519 keypairs.

X25519Keypair

X25519Keypair.generate

Constructor to randomly generate an X25519Keypair.

X25519Keypair.fromSecretKey

Constructor to create an X25519Keypair from a secret key given as a 32 byte Uint8Array.

X25519Keypair.secretKey

Returns the secret key as a Uint8Array. Note that this is a getter method, not a public property of the object.

X25519Keypair.publicKey

Returns the public key as a Uint8Array. Note that this is a getter method, not a public property of the object.

Registering in private access mode

To register in private access mode a register transaction must be submitted just as with other access modes.

Then we connect to the TSS servers in the DKG committee. The DKG committee consists of one TSS node from each signing sub-group, determined by the block number of the block containing the register transaction.

To find this, for each subgroup, we get the account IDs of all members using the staking pallet's signing_groups query with the signing group index number as the parameter.

Then we select a member of the subgroup by using the block number modulo the number of members of the subgroup. We check if that TSS server has fully a synced keyshare store using the staking pallet's is_validator_synced query with the account ID. If the server is not fully synced, we remove that TSS server from the list of servers, and repeat the selection process. If there are no fully synced validators in the subgroup, registration fails.

Once we have the account ID of the selected TSS server, we get their other details (IP address and x25519 public encryption key) by using the staking pallet's threshold_servers query with the account ID.

We create an array of ValidatorInfo objects containing these details, and pass this to the runDkgProtocol function, together with the user's secret sr25519 signing key.

runDkgProtocol returns a promise which if successful will resolve to a KeyShare. KeyShare has methods for serialization and de-serialization, to/from both JSON and binary (using bincode).

Signing in private access mode

The runSigningProtocol function also takes an array of ValidatorInfo objects. These should be selected using the message hash, exactly the same as the those used in a UserSignatureRequest.

runSigningProtocol needs to be run concurrently whilst making the user/sign_tx http requests, for example by using Promise.all. runSigningProtocol also takes the user's KeyShare as an argument, as well as the message hash, and the user's private sr25519 signing key and x25519 encryption key.

runSigningProtocol returns a promise which if successful will resolve to an ECDSA signature with recovery bit, encoded as a base64 string.

Changelog

0.2.0 - 2024-07-11

Breaking Changes

• In #853 the responsibility of generating a TSS mnemonic was shifted to operators, which can be done using the --mnemonic flag during process startup. This also allows operators to back up the mnemonic for their TSS.
• In #856 a new flag, --mnemonic-option, and environment variable DEPLOYER_MNEMONIC, were added to the entropy-test-cli as ways to indicate which account to use during registration. This replaces having an account name or mnemonic directly in the command invocation.
• In #866 timestamp was removed from UserSignatureRequest and replaced with block_number. Thus check_stale now uses block_number for stale checks
• In #881 the HashingAlgorithm enum is given an additional variant Blake2_256 and marked as non_exhaustive meaning we must handle the case that an unknown variant is added in the future.
• In #900 the subgroup signer selection was sorted to ensure a predicatble order across libraries, languages and clients.
• In #901 the network's currency units were changed. This resulted in a change to the existential deposit as well as balances of endowed accounts (e.g development accounts like //Alice).

Added

• Add a way to change program modification account (#843)
• Add support for --mnemonic-file and THRESHOLD_SERVER_MNEMONIC (#864)
• Add validator helpers to cli (#870)
• Add blake2 as built in hash function and make HashingAlgorithm non-exhaustive (#881)
• Add sort to subgroup signer selection (#900)
• Create four node Docker Compose chainspec (#902)
• Oracle data integration (#922)

Changed

• Move TSS mnemonic out of keystore (#853)
• Prepare test CLI for use in Programs repo (#856)
• Replace timestamp with block number (#866)
• Change currency units (#901)