diff --git a/content/concepts/TDX.md b/content/concepts/TDX.md new file mode 100644 index 00000000..c65b69cb --- /dev/null +++ b/content/concepts/TDX.md @@ -0,0 +1,7 @@ +--- +title: "TDX" +lead: "" +draft: true +--- + +TODO \ No newline at end of file diff --git a/content/concepts/joining-the-network.md b/content/concepts/joining-the-network.md deleted file mode 100644 index a1a3dbf8..00000000 --- a/content/concepts/joining-the-network.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Joining the network" -lead: "This page covers the process of joining the Entropy network as a validator node, along with specific information that each node must provide." ---- - -{{< callout type="info" >}} -The network is not currently accepting public/user-ran validator nodes. We will [announce](https://github.com/entropyxyz/community/discussions/categories/announcements) ahead of time when we plan to start allowing new nodes to join the network. -{{< /callout >}} - -## Joining process - -The process works something like this: - -1. The new validator operates an Entropy chain node and a threshold server. -1. This new validator registers with the chain, and the chain then assigns it to a _signing subgroup_. -1. Once a new validator is aware of the subgroup it has joined, it requests the current validators in that group for a copy of the key-shares specific to that subgroup. To make this request, it sends a 'POST' request to 'validator/sync_kvdb' with the database keys of the shares it needs. -1. After the new validator has received all the shares, the node notifies the chain that it has successfully synchronized. - -```mermaid -sequenceDiagram - title Joining The Network - participant NV as New_Validator - participant CV as Current_Validator - participant C as Chain - - NV->>NV: Spins up chain instance - NV->>NV: Starts threshold server - C->>NV: Places validator in subgroup - NV->>CV: Contacts validator in subgroup asks for keys - CV->>NV: Validates validator's subgroup then encrypts and sends keys - NV->>C: Once all keys are received informs chain it has synced -``` - -## Required information - -Each individual validator node requires the following information before it can join the network: - -- **Endpoint**: The IP address of its threshold server. -- **X25519 Public Key**: Its public encryption key for encrypting messages to and from other validators. -- **Threshold Server Signing Account**: The account for the threshold server to submit transactions to the Entropy chain. diff --git a/content/concepts/key-management.md b/content/concepts/key-management.md new file mode 100644 index 00000000..b7e05d5d --- /dev/null +++ b/content/concepts/key-management.md @@ -0,0 +1,32 @@ +--- +title: "Key management" +lead: "This page explains the process for periodically substituting signers, swapping keyshares, and other processes the network uses to manage keys." +aliases: + - key-reshare +--- + +## Key reshare + +The idea here is that when validators join the network they may be selected to the signing comittee. A smaller randomly selected group of validators that is responsible for holding the parent network key. Every session, which consists of 2400 blocks (equivalent to 4 hours), the chain will notify the TSSs (Threshold Signature Servers) that a reshare is taking place. The chain will also reandomly select a validator to join the netowrk and remove the oldest signer from the comittee. + +The selected TSSs will connect to each other and execute the key reshare protocol on the parent network key, generating a new set of key shares. This protocol is similar to the distributed key generation protocol used during jump starting the network. Upon receiving a new key share, the recipients will hold the new key share in a secondary slot and rotate them to the current parent network key when everyone in the signing group has agreed that the rotation was succeful. All previous key shares will be incompatible with the refreshed key shares. However, the public validating key of the parent network key signing keypair never changes. This means all child keys will also remain the same. + +For information on chain randomness used see (here)[https://docs.substrate.io/build/randomness/] + +```mermaid +sequenceDiagram + Entropy Chain->>+Validator TSS: Tells selected validator to do Reshare (with new signer to add and old to remove). + Validator TSS->>+Validator TSS: Does Reshare with other selected validators stores new share in holding slot. + Validator TSS->>+Entropy Chain: Tells chain everything was A-OK + Entropy Chain->>+Validator TSS: When everyone is done tells all signers to rotate their holding key to the new parent key. +``` + +### Negative pathways + +- The above describes the happy pathway this part is for edge cases + +#### A failure of reshare protocol + +- There are multiple ways this process can fail, if that were to happen the offending party would be known as everyone in the new signing party needs to participate +- Since the process is two steps the current signing party would remain the offending party would be moved to slashing and the chain would initate a new reshare (not implemented yet) +- All parties are unable to unbond until leaving the singing party so their funds would be at risk and able to be slashed diff --git a/content/concepts/network-setup.md b/content/concepts/network-setup.md new file mode 100644 index 00000000..53923d31 --- /dev/null +++ b/content/concepts/network-setup.md @@ -0,0 +1,64 @@ +--- +title: "Network setup" +lead: "This page covers how the Entropy network functions from a conceptual standpoint. For techincal and actionable information on the various Entropy networks, check out the [Networks reference page](../reference/networks.md)." +aliases: + - joining-the-network +--- + +## Joining the network + +This section explains the process for validator nodes to join the network. The process works something like this: + +1. The new validator operates an Entropy chain node and a threshold server. +1. This new validator registers with the chain. +1. If the stake is enough and the node gets selected to be a validator, it will act as a relayer and be eligible to be added to the signer set. + +```mermaid +sequenceDiagram + title Joining The Network + participant NV as New_Validator + participant C as Chain + + NV->>NV: Spins up chain instance + NV->>NV: Starts threshold server + C->>NV: Places NV in validator set + CV->>NV: Validates validator's subgroup, then encrypts and sends keys +``` + +{{< callout type="info" >}} +The network is not currently accepting public/user-ran validator nodes. We will [announce](https://github.com/entropyxyz/community/discussions/categories/announcements) when we plan to start allowing new nodes to join the network. +{{< /callout >}} + +### Required information + +Each validator node requires the following information before it can join the network: + +- **Endpoint**: The IP address of its threshold server. +- **X25519 Public Key**: Its public encryption key for encrypting messages to and from other validators. +- **Threshold Server Signing Account**: The account for the threshold server to submit transactions to the Entropy chain. + +## Jumpstart + +The network needs a "jump start" to be in a usefull state. Pretty much this means we need to do a network wide DKG to create the network parent key. This is started through a blockchain call which informs the selected TSSs to do a dkg. These TSSs will create the network parent key and create the first signing comittee. + +Through reshares TSSs will get subbed in and out of the signing comittee. At registration user's are given a derivation off of the parent key and during signing we have a just in time key derivation to allow for singing for a given account. + +```mermaid +sequenceDiagram + participant Anyone + participant Chain + participant Validator Alice + participant Validator Bob + participant Validator Charlie + participant Validator David + + Anyone ->> Chain: Calls jumpstart_network(). + + Note over Chain: Selects validators for distributed-key-generation (DKG). + Chain ->> Validator Alice: do DKG message sent. + Chain ->> Validator Bob: do DKG message sent. + Note over Validator Alice, Validator Bob: Perform DKG. + Validator Alice ->> Chain: Confirms network is jumpstarted. + Validator Bob ->> Chain: Confirms network is jumpstarted. + Note over Chain: Network is jumpstarted, Alice and Bob are signers. +``` diff --git a/content/concepts/proactive-refresh.md b/content/concepts/proactive-refresh.md deleted file mode 100644 index 5a39b417..00000000 --- a/content/concepts/proactive-refresh.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Proactive refresh" -lead: "This page covers the process where key shares held by validators in a network are periodically updated to maintain the security of the network." ---- - -The idea here is that when validators join or leave the network, their key shares should become invalid. Every session, which consists of 2400 blocks (equivalent to 4 hours), the chain will notify the TSS (Threshold Signature Scheme) servers that a proactive refresh is taking place. The network's registered keys will be divided in parts to avoid refreshing the entire network and putting unnecessary strain on the validators. One TSS server from each sub-group is chosen based on a deterministic process involving the current block number modulo the number of TSS servers in that subgroup, similar to the selection process for DKG (Distributed Key Generation) during registration. - -The selected TSS servers (one from each subgroup) will connect to each other and execute the proactive refresh protocol, generating a new set of key shares. This protocol is similar to the distributed key generation protocol used during registration. The selected TSS servers will send the new key shares to the other members of their subgroup. Upon receiving a new key share, the recipients will replace their existing key share in their key-value store with the new one. All previous key shares will be incompatible with the refreshed key shares. However, the public validating key of the distributed signing keypair never changes. The private access mode will have an individual trigger initiated by the user, although this feature has not been implemented yet. - -```mermaid -sequenceDiagram - Entropy Chain->>+Validator TSS: Tells selected validator to do Proactive Refresh (one validator in each subgroup). - Validator TSS->>+Validator TSS: Get partition of registered keys. - Validator TSS->>+Validator TSS: Does Proactive Refresh with other selected validators. - Validator TSS->>+Validator TSS: Sends new key share to rest of members of subgroup and store it. -``` diff --git a/content/concepts/registering.md b/content/concepts/registering.md index 610f6037..e1a28e79 100644 --- a/content/concepts/registering.md +++ b/content/concepts/registering.md @@ -1,6 +1,6 @@ --- title: "Registering" -lead: "A user needs to register in order to be able to use the Entropy network to sign messages. This page covers that process." +lead: "This section explains the technical steps involved in registering a user account on the Entropy network, including the selection of programs and configurations, and the generation of a verifying key." --- The SDK method for registering is [`Entropy.register`](https://github.com/entropyxyz/sdk/blob/main/README.md#register). @@ -12,46 +12,11 @@ sequenceDiagram actor User participant Chain - participant Validator Alice - participant Validator Bob - participant Validator Charlie - participant Validator David - - box Subgroup 1 - participant Validator Alice - participant Validator Bob - end - - box Subgroup 2 - participant Validator Charlie - participant Validator David - end - - User ->> Chain: Informs chain of registration. - - Note over Chain: Selects validators for distributed-key-generation (DKG). - Chain ->> Validator Alice: Sends user information. - Chain ->> Validator Charlie: Sends user information. - - Note over Validator Alice, Validator Bob: Perform DKG. - Note over Validator Charlie, Validator David: Perform DKG. - Validator Alice ->> Validator Bob: Sends key-share to rest of subgroup. - Validator Charlie ->> Validator David: Sends key-share to rest of subgroup. - - Validator Alice ->> Chain: Confirms user is registered. - Validator Charlie ->> Chain: Confirms user is registered. - Note over Chain: User now in a registered state. + User ->> Chain: Informs chain of registration. And selects programs and configs associated with account + Chain ->> User: Selects user's derivation path and returns verifying key associated with that user ``` -1. The user registers with the Entropy chain by submitting a transaction from the 'signature request account' containing the 'Account Key', and initial 'ProgramsData'. +1. The user registers with the Entropy chain by submitting a transaction from any account containing the 'Account Key', and initial 'ProgramsData'. * ```ProgramsData``` - Is multiple Programs Instances. Which contain the ```program_pointer``` (the hash of the program you want to use) and the ```program_config``` for that program. On the evaluation of a signature request a threshold server will run all the programs and pass through the program config for that program. -1. The chain selects which nodes should perform a [distributed key generation (DKG)](https://docs.rs/synedrion/latest/synedrion/sessions/fn.make_key_gen_session.html) based on the current block number. -1. As each block is finalized, an off-chain worker makes an HTTP POST request to each selected threshold server with the signature request accounts of all users who have registered, as well as details of the other validator nodes in the signing subgroup. Specifically, the `/user/new` ([src](https://github.com/entropyxyz/entropy-core/blob/master/crypto/server/src/user/api.rs) [API](https://docs.rs/entropy-tss/latest/entropy_tss/#usernew---post)) endpoint is called with a [`OcwMessageDkg`](https://docs.rs/entropy-shared/latest/entropy_shared/types/struct.OcwMessageDkg.html). -1. All selected threshold servers: - 1. Connect to each other over websocket and make a [noise handshake](https://noiseprotocol.org/noise.html) to establish an encrypted channel for protocol messages. - 1. Perform a [DKG](https://docs.rs/synedrion/latest/synedrion/sessions/fn.make_key_gen_session.html) and store their [key-share](https://docs.rs/synedrion/latest/synedrion/struct.KeyShare.html) in their [encrypted key-value store](https://docs.rs/entropy-kvdb). - 1. Send the generated share to other members of their signing subgroup by POSTing to `/user/receive_key` ([src](https://github.com/entropyxyz/entropy-core/blob/master/crates/threshold-signature-server/src/user/api.rs) [API](https://docs.rs/entropy-tss/latest/entropy_tss/#for-other-instances-of-the-threshold-server)). - 1. They submit a transaction to the entropy chain to confirm the user has successfully registered. -1. On receiving a key-share via `receive_key`, the threshold server will check with the chain that the sender is in the correct subgroup, and if so store the key-share in their key-value store. -1. On receiving a confirmation transaction from all selected threshold server, the chain sets the user to a 'registered' state, making it possible to sign messages. +1. The chain selects a derivation path based on a running count and stores said user information in a mapping with the veryfying key for that user as the key in the mapping. The veryfying key will be the account that the edcsa signatures resolve to. diff --git a/content/concepts/node-encryption-and-authentication.md b/content/concepts/security.md similarity index 71% rename from content/concepts/node-encryption-and-authentication.md rename to content/concepts/security.md index 4a6eb26c..89a53c37 100644 --- a/content/concepts/node-encryption-and-authentication.md +++ b/content/concepts/security.md @@ -1,8 +1,14 @@ --- -title: "Node encryption and authentication" -lead: "When sending messages to threshold signature servers on the Entropy network, you must authenticate and encrypt the messages. This page covers that process." +title: "Security" +lead: "Entropy leverages cutting-edge cryptographic techniques and distributed systems principles to deliver a highly secure network. Learn more about our security architecture and protocols." +aliases: + - node-encryption-and-authentication --- +## Node encryption and authentication + +When sending messages to threshold signature servers on the Entropy network, you must authenticate and encrypt the messages. This section covers that process. + The authentication process is simple: each node has a substrate account stored on the chain, referred to as a TSS account. Messages are signed using SR25519. This encryption requires using an X25519 public key which gets used in [Hybrid Public Key Encryption](https://www.rfc-editor.org/rfc/rfc9180.html), using the [`hpke-rs`](https://docs.rs/hpke-rs) crate. diff --git a/content/concepts/signing.md b/content/concepts/signing.md index f9c85482..7f98d553 100644 --- a/content/concepts/signing.md +++ b/content/concepts/signing.md @@ -1,6 +1,6 @@ --- title: "Signing" -lead: "Getting a signature from the network is the main purpose of Entropy. Once you have this signature you can apply it onto whatever cryptographic process you need, like signing a PGP message or submitting an Ethereum transaction. This page covers how signing works." +lead: "This section delves into the technical details of the signing process, including the interaction between users, relayer nodes, and the signing committee, as well as the underlying threshold signature scheme." --- ## Signing process @@ -8,35 +8,30 @@ lead: "Getting a signature from the network is the main purpose of Entropy. Once ```mermaid sequenceDiagram Alice->>Alice: Creates transaction. - Alice->>Validator Bob: Sends transaction through private means. - Alice->>Validator Charlie: Sends transaction through private means. - Validator Bob->> Validator Bob: Determines whether they are a member of the signing committee. - Validator Charlie->> Validator Charlie: Determines whether they are a member of the signing committee. - Validator Bob->> Signing Committee: Requires constraints pass and the transaction matches the hash to sign. - Validator Charlie->> Signing Committee: Requires constraints pass and the transaction matches the hash to sign. - Signing Committee->> Signing Committee: Generates signature. - Signing Committee->> Alice: Sends completed signature. + Alice->>Relayer Validator: Sends transaction through private means. + Relayer Validator->>Signing Validator Bob: Sends transaction through private means (requires constraint pass). + Relayer Validator->>Signing Validator Charlie: Sends transaction through private means. + Signing Validator Bob->> Signing Committee: Requires constraints pass + Signing Validator Charlie->> Signing Committee: Requires constraints pass + Signing Committee->> Signing Committee: Derives user's key based on their derivation path, Generates signature. + Signing Committee->> Relayer Validator: Sends completed signature. + Relayer Validator->> Alice: Sends completed signature. ``` -1. The user computes the hash of the message they wish to sign and selects a signing committee by deterministically selecting a member of each signing group based on this hash. They can get the details of the signing groups as they were published on-chain when the user [registered]({{< relref "./registering" >}}). -1. The user contacts all threshold servers in the signing committee and makes a POST to `/user/sign_tx` with the message to be signed (encrypted for that node). -1. On receiving a message, each node checks that it is a member of the signing committee for that message using the hash. -1. The Threshold server retrieves the latest version of the associated program from the entropy chain, and executes it with the message to be signed as input. Only on getting successful program output do they continue to the next step. +1. The user computes the message they wish to sign and selects a Relayer node to send their message to `/user/relay_tx`. A relayer node is a validator that is not a signer +1. The relayer nodes does some checks, then randomly selects T of the signing commitee to pass the message to. +1. The Relayer contacts all threshold servers in the signing committee and makes a POST to `/user/sign_tx` with the message to be signed (encrypted for that node). +1. On receiving a message, each node checks that it is a member of the signing committee and is being contactacted by a validator. +1. The Threshold server retrieves the latest version of the associated program from the entropy chain, and executes it with the message to be signed as input. Only on getting successful program output do they continue to the next step (this is also done by the relayer before relaying a message). 1. The Threshold server sets up websocket connections to or from the rest of the committee to use for threshold signing protocol messages. They decide whether to make an outgoing connection, or accept an incoming one by comparing account IDs. These connections are secured using the [noise protocol](https://noiseprotocol.org/noise.html). Signing protocol messages can be either 'broadcast' to all of the committee or 'p2p' to a specific member. 1. Once all members of the signing committee have subscribed, nodes participate in the signing protocol to produce a signature using the key-shares retrieved from their key-value store. 1. If the signing process fails, nodes broadcast who the malicious/faulty signer was, which is included in the next block. Following that, the next block contains details of a new signing committee. The misbehaving signer will be 'slashed' (not yet implemented). -1. If the process is successful, the signature is returned to the user. Currently, this requires the user to repeatedly poll POST `signer/signature` with the signature hash until it successfully retrieves a signature. +1. If the process is successful, the signature is returned to the relayer then the user. -The signing process can only take place when a user is already registered on Entropy. The process involves the user and a committee of validators collectively performing the signing. The committee requires one Validator from each signing group as well as the user. The current version of the program will be executed here to determine whether or not to proceed with the signing protocol. +The signing process can only take place when a user is already registered on Entropy. The process involves the user and a committee of validators collectively performing the signing. The current version of the program will be executed here to determine whether or not to proceed with the signing protocol. For details on how signatures are actually created, see [Threshold Signature Scheme]({{< relref "./threshold-signature-scheme.md" >}}). -## Signing Group Selection - -Signing groups are chosen and held on-chain. Every time a new validator joins or gets removed, the chain will place or remove them from a subgroup such that: - - Subgroups do not shuffle current validators. - - Subgroups remain the same size or off by one. - ## Messages Currently the only restrictions for a message is that it's content is less than `1 MB` in size. diff --git a/content/concepts/threshold-signature-scheme.md b/content/concepts/threshold-signature-scheme.md index 4f3e2afd..0741d42b 100644 --- a/content/concepts/threshold-signature-scheme.md +++ b/content/concepts/threshold-signature-scheme.md @@ -1,6 +1,6 @@ --- title: "Threshold Signature Scheme" -lead: "This page covers what a threshold signature scheme is, and how they are used within the Entropy network." +lead: "This section provides a technical overview of the threshold signature scheme employed by Entropy, highlighting its key features, security properties, and the underlying cryptographic primitives." --- - The TSS Implementation used by Entropy is **Synedrion** [src](https://github.com/entropyxyz/synedrion) [API](https://docs.rs/synedrion) diff --git a/content/concepts/validators.md b/content/concepts/validators.md index 48e589cf..f531a5c5 100644 --- a/content/concepts/validators.md +++ b/content/concepts/validators.md @@ -1,11 +1,12 @@ --- title: "Validators" +lead: "This section provides a technical overview of the validator nodes that power the Entropy network, focusing on the roles of the Entropy blockchain and the threshold signature server." --- [`entropy-core`](https://github.com/entropyxyz/entropy-core) is run by validator nodes in the Entropy network. It has two different binaries, both of which are run by each validator node: -- The Entropy blockchain is built with [Substrate](https://docs.substrate.io/). This handles public data relating to who the users are and which programs they use, who the validators are and which 'signing subgroup' they belong to, and the bytecode of all available programs. -- The [Threshold signature server](https://github.com/entropyxyz/entropy-core/tree/master/crates/threshold-signature-server) which has an HTTP API based on [Axum](https://docs.rs/axum). This handles private data, such as a user's signing key shares, and runs the signing protocol. +- The Entropy blockchain is built with [Substrate](https://docs.substrate.io/). This handles public data relating to who the users are and which programs they use, who the validators are and which belong to the signing comittee, and the bytecode of all available programs. +- The [Threshold signature server](https://github.com/entropyxyz/entropy-core/tree/master/crates/threshold-signature-server) which has an HTTP API based on [Axum](https://docs.rs/axum). This handles private data, such as parent network key share, and runs the signing protocol. ```mermaid flowchart TD @@ -23,7 +24,7 @@ flowchart TD ## The Entropy chain [src](https://github.com/entropyxyz/entropy-core/tree/master/node/cli) -The purpose of the Entropy blockchain is to have a 'single source of truth' for the information which needs to be public and which the threshold signature servers need to have consensus on. For example, we need to have agreement of which validators belong to which signing subgroups, and which subgroups will participate in signing a particular message. +The purpose of the Entropy blockchain is to have a 'single source of truth' for the information which needs to be public and which the threshold signature servers need to have consensus on. For example, we need to have agreement of which validators belong to the singing comittee ### General functionality from Substrate @@ -38,7 +39,7 @@ The purpose of the Entropy blockchain is to have a 'single source of truth' for ### Custom functionality specific to Entropy: -- **Staking extension pallet** [src](https://github.com/entropyxyz/entropy-core/blob/master/pallets/staking/src/lib.rs) - staking is extended to assign a particular Threshold Signature Servers account to a particular chain node, and tracks which signing subgroup they belong to. +- **Staking extension pallet** [src](https://github.com/entropyxyz/entropy-core/blob/master/pallets/staking/src/lib.rs) - staking is extended to assign a particular Threshold Signature Servers account to a particular chain node, and tracks which ones are in the signing comittee. - **Registry pallet** [src](https://github.com/entropyxyz/entropy-core/blob/master/pallets/registry/src/lib.rs) - This provides a registry of Entropy users and which programs are currently associated with their account. This uses Substrate [events](https://docs.substrate.io/build/events-and-errors). - **Programs pallet** [src](https://github.com/entropyxyz/entropy-core/blob/master/pallets/programs/src/lib.rs) - This stores program bytecode as well as metadata associated with the program, such as a description of its interface and how many times it is used.