# Trail of Bits Audit Brief

## Intro to Entropy
- [High level docs](https://entropy-docs.vercel.app)
- [Entrosplainer](https://entropy-docs.vercel.app/Intro)
- [Terminology](https://entropy-docs.vercel.app/Terminology)

## Architecture of the system

### Repositories

The `entropy-core` repository encompases two major components: the Substrate code which makes up the `entropy` binary, and the off-chain webserver and threshold cryptography server known as the `entropy-tss`.


The `entropy-tss` pulls in from two other Entropy repositories: `programs` and `Synedrion`.

The Programs repository contains logic for executing Web Assembly code before producing signatures for users.

The Synedrion repository contains the logic for our threshold cryptography protocol.

### Coupled Binaries

While the `entropy-core` repository contains two seperate binaries, in practice they're coupled. Any validator that is part of the active set is required to run an instance of the `entropy-tss` server alongside their validator.


The binaries themselves may run on the same machine, or on seperate machines. It is up to the operator.

### Rough Network Layout

The Substrate nodes (`entropy` binary) run on their own peer-to-peer network exposed over port 30333. They communicate with the outside world over their RPC server exposed on port 9944.

The TSS servers (`entropy-tss` binary) also make up a pseudo-offchain network. It isn't a true peer-to-peer network, but they still end up needing to connect with other peers as part of protocol responsibilities. For example, when producing a signature for a user all TSS servers that make up the signing committee must establish connections with each other and perform the signing protocol.

The IP addresses of the TSS servers gets stored on-chain, and TSS servers query that before executing the protocol.


The `entropy.js` SDK is what would be coordinating and initiating interactions between users and the various actors on the network.

## Project Scope

This audit should focus on the code found in the [`entropy-core` repository](https://github.com/entropyxyz/entropy-core/).

For the audit you can use the [`hc/trail-of-bits-checkpoint`](https://github.com/entropyxyz/entropy-core/tree/hc/trail-of-bits-checkpoint) at commit `ae261ba`.

If you want some recently built images that work you can use the following images:
- [`docker pull entropyxyz/entropy:test-hc-release-ae261ba-tob-checkpoint`](https://hub.docker.com/layers/entropyxyz/entropy/test-hc-release-ae261ba-tob-checkpoint/images/sha256-199f1a21810c6dffeec5be1056175597558252540a5fa13235b8f353d6b404ec?context=explore)
- [`docker pull entropyxyz/entropy-tss:test-hc-release-ae261ba-tob-checkpoint`](https://hub.docker.com/layers/entropyxyz/entropy-tss/test-hc-release-ae261ba-tob-checkpoint/images/sha256-2381569180c6db7e8760e187b1dbcaac8ae931329db1ecf8ff42feec9b298822?context=explore)

The following are some suggestions for areas where we think it would be valuable to spend some time.

### Substrate

We want to get the following pallets reviewed:
- [Programs](https://github.com/entropyxyz/entropy-core/tree/master/pallets/programs)
- [Propagation](https://github.com/entropyxyz/entropy-core/tree/master/pallets/propagation)
- [Registry](https://github.com/entropyxyz/entropy-core/tree/master/pallets/registry)
- [Staking](https://github.com/entropyxyz/entropy-core/tree/master/pallets/staking)

We would also like to get the [runtime configuration parameters](https://github.com/entropyxyz/entropy-core/blob/master/runtime/src/lib.rs) reviewed. For example, looking for any pallets that are misconfigured or have erroneous values.

There are some pallets we do not plan to ship with our production network, and we will try and remove those before the review but there's a chance we won't get to it.

For a bit of context on where the configuration values come from, we usually take the values used by the currently deployed [Polkadot relay-chain runtime](https://github.com/polkadot-fellows/runtimes/tree/main/relay/polkadot).

Lastly, we'd also like a brief look through some of the [Service code](https://github.com/entropyxyz/entropy-core/tree/master/node/cli). We've modified a couple of things related to the CLI and the chainspec generation. There's no need to do a deep dive here though, a peek should be fine.

### Threshold Signature Scheme Server

The pieces that make up the TSS, as well as the TSS binary, can be found in the [`crates` folder](https://github.com/entropyxyz/entropy-core/tree/master/crates).

Here we'd like a focused look at:
- the registration and signing flows
- the interface with our cryptography library, Synedrion, to ensure that we're using the library correctly
- [`x25519-chacha20poly1305`](https://github.com/entropyxyz/entropy-core/blob/master/crates/protocol/src/sign_and_encrypt/mod.rs) implementation

If you have time, we'd also like a quick look at the [encrypted key-value store](https://github.com/entropyxyz/entropy-core/tree/master/crates/kvdb). We didn't write the initial code for this ourselves, instead taking the code form the Axelar project.

### Explicitly out of Scope
- Runtime Benchmarking
- [Slashing pallet](https://github.com/entropyxyz/entropy-core/tree/master/pallets/slashing)
- [Transaction Pause pallet](https://github.com/entropyxyz/entropy-core/tree/master/pallets/transaction-pause)
- [Entropy Test CLI](https://github.com/entropyxyz/entropy-core/tree/master/crates/test-cli)
- [Testing Utils crate](https://github.com/entropyxyz/entropy-core/tree/master/crates/testing-utils)
- Web Assembly bindings ([[1](https://github.com/entropyxyz/entropy-core/blob/master/crates/protocol/src/user/wasm.rs)], [[2](https://github.com/entropyxyz/entropy-core/blob/master/crates/protocol/src/sign_and_encrypt/wasm.rs)])

## Current Deployment(s)
We have an internal testnet running right now. There are no guarantees around this network, and it may get reset at any time.

If you want to get a general sense of what's going on on the network, you can check out our [status page](https://status.entropy.xyz).

We have three Substrate RPC nodes accessible at the following URLs:
- ws://54.175.228.156:9944
- ws://44.203.8.2:9944
- ws://52.91.103.118:9944

To view or interact with these from the Polkadot JS Apps UI you will need to run a [local version of the UI](https://github.com/polkadot-js/apps?tab=readme-ov-file#docker). This is because the nodes aren't running with TLS.

We also have four TSS servers deployed at the following URLs:
- http://100.26.207.49:3001/
- http://34.200.237.166:3001/
- http://184.72.189.154:3001/
- http://184.73.19.95:3001/

## Usage Tutorials

We have written [a short walkthrough](https://github.com/entropyxyz/meta/wiki/Getting-started-with-local-devnet-and-the-test-CLI) on how to deploy a network using our provided [Docker Compose](https://github.com/entropyxyz/entropy-core/blob/master/docker-compose.yaml) setup and interact with it using our [`entropy-test-cli`](https://github.com/entropyxyz/entropy-core/tree/master/crates/test-cli) tool.

We also have some overviews of the different flows:
- [Registration](https://entropy-docs.vercel.app/Register)
- [Signing](https://entropy-docs.vercel.app/Sign)
- [New validator syncing logic](https://entropy-docs.vercel.app/JoiningTheNetwork)

We've also got a bit of inline docs which you might find useful:
- [`entropy-core` API docs](https://docs-api-entropy-core.vercel.app/)
- The `entropy-tss` docs are very limited because only the public API is documented
- The Program docs are very out of date and cannot be updated because of [#53](https://github.com/entropyxyz/programs/issues/53)
- The [front page of the `entropy-tss` API docs](https://docs-api-entropy-core.vercel.app/entropy_tss) (partially) documents its HTTP endpoints.

## Known or Suspected Attack Vectors and Limitations
- Threshold for signing group saturation might be too low ([#638](https://github.com/entropyxyz/entropy-core/issues/638))
- This has been a big source of worry for the team recently due to the consequences
- There has been some debate about whether or not this is outside of the scope of the assumptions/threat model from an MPC point of view
- `/user/receive_key` endpoint can be misused by a malicious validator ([#652](https://github.com/entropyxyz/entropy-core/issues/652))
- Vulnerability in `pallet-staking-extension`'s `change_threshold_accounts` extrinsic([#654](https://github.com/entropyxyz/entropy-core/issues/654))
- The Proactive refresh feature
- The code is (mostly) all there, but it has not been well tested yet
- It's not running on our testnet either (we wanted to test core features first) ([#511](https://github.com/entropyxyz/entropy-core/issues/511)).
- See also [#547](https://github.com/entropyxyz/entropy-core/issues/547) - an easy fix but needs doing.
- See also [#510](https://github.com/entropyxyz/entropy-core/issues/510) - in process of fixing just time issues.
- Signatures are sent unencrypted to users (although the message itself never goes unencrypted over the wire).
- Also related to this is [#400](https://github.com/entropyxyz/entropy-core/issues/400).
- Keyshares and signature requests are encrypted over the wire, but with a static encryption key giving no forward secrecy. Messages could be recorded and decrypted later in the case a validator's secret x25519 key is compromised.
- Using a handshake involving ephemeral keys (eg: TLS or noise) would mitigate this.
- Shared randomness for protocol sessions ([#375](https://github.com/entropyxyz/entropy-core/issues/375))
- When getting a share from another validator when syncing, we should randomly select one to avoid the [first validator becoming the 'single source of truth'](https://github.com/entropyxyz/entropy-core/blob/fe96ae423dcf3e333833220dd1d97757c1450069/crates/threshold-signature-server/src/validator/api.rs#L199)
- See also [#546](https://github.com/entropyxyz/entropy-core/issues/546)
- We haven't tested the protocol execution logic with more than 2 parties (or 3 in private mode), so there is a high possibility of bugs.
- Validators dynamically joining or leaving a running network has not been tested - possibility of bugs relating to subgroups, syncing keyshares, etc.
- When picking a committee from the subgroups for distributed key generation or signature requests, it's pretty easy for a user to "pick" their committee ahead of time
- For DKG, the committee is picked based off the block number the registration request was included in
- For signing, the committee is picked based off the message which is to be signed [#392](https://github.com/entropyxyz/entropy-core/issues/392)
- At the moment there's no way to report or punish validators who misbehave in various ways (see [#333](https://github.com/entropyxyz/entropy-core/issues/333))
- A few things we may want to punish for are:
- A validator which does not participate in registration or signing protocols ([#639](https://github.com/entropyxyz/entropy-core/issues/639))
- A validator which does not share keyshares with other peers in their subgroup at the end of registration
- A validator which does not provide a keyshare to another peer in their subgroup during signing (i.e, when the peer is "syncing")
- A validator produces a signature without actually running a program
- At the moment there is no way to change the number of subgroups used by a running network without restarting the network ([#656](https://github.com/entropyxyz/entropy-core/issues/656))
- As part of the Staking pallet, we store the IP addresses of the [TSS servers on-chain](https://github.com/entropyxyz/entropy-core/blob/fe96ae423dcf3e333833220dd1d97757c1450069/pallets/staking/src/lib.rs#L126)
- This seems like an easy way to get people targetted for DoS attacks
- Couple of counterpoints here: operators should run this behind a load balancer, and we should considering implementing some sort of rate limiting/backoff as part of the TSS logic

## Expected Changes to Architecture

We've got a couple of upcoming features which may change the implementation or behaviour of the protocol in non-trivial ways.

We want to eventually run the network as a full threshold cryptography network. This means supporting t-of-N signatures, instead of just N-of-N (which is what's currently implemented). By making this change we will probably get rid of the idea of subgroups and how we form the signing committee.

We expect to add slashing flows over the next few months. This will also change the economics of the protocol a bit, but shouldn't change any core logic.

Lastly, we want to change the protocols used by the user to communicate with TSS servers. We want to make it possible to have browser-based clients without needing TLS certificates for each TSS server.

## Internal TODOs
- Remove runtime code that we don't need