From 495049cea6cfbf0fe09959d581a58c1a15eda598 Mon Sep 17 00:00:00 2001 From: m4sterbunny Date: Mon, 29 Dec 2025 11:14:51 +0000 Subject: [PATCH 1/3] reviews infrastructure section --- docusaurus.config.js | 8 ++ embedded-wallets/infrastructure/glossary.mdx | 60 ++++++------- .../infrastructure/mpc-architecture.mdx | 89 +++++++++---------- package-lock.json | 5 +- package.json | 1 + 5 files changed, 82 insertions(+), 81 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 53f1dafdf90..c596b01f5d5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -796,6 +796,14 @@ const config = { }, }, }), + stylesheets: [ + { + href: "https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css", + type: "text/css", + integrity: "sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi", + crossorigin: "anonymous", + }, + ], } module.exports = config diff --git a/embedded-wallets/infrastructure/glossary.mdx b/embedded-wallets/infrastructure/glossary.mdx index 83fb3c0d877..86c98548311 100644 --- a/embedded-wallets/infrastructure/glossary.mdx +++ b/embedded-wallets/infrastructure/glossary.mdx @@ -1,61 +1,51 @@ --- title: Important Terms and Definitions sidebar_label: Glossary - description: - "Important Terms and Definitions - Web3Auth Wallet Management Infrastructure | Documentation - - Web3Auth" + "Important Terms and Definitions - Embedded Wallets' Cryptographic Protocol | Web3Auth" --- -### Shamir Secret Sharing (SSS) +### Shamir Secret Sharing -Shamir’s secret sharing scheme is a polynomial threshold $[(t,n)]$ secret sharing scheme where a -dealer divides a secret into n multiple shares and each participant is given a share by evaluating a +[Shamir’s Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) (SSS) scheme is a polynomial threshold $(t,n)$ secret sharing scheme where the secret holder divides a secret into n multiple shares and each participant is given a share by evaluating a polynomial of order $t$ . To reconstruct the secret, $t + 1$ shares are required. -SSS is a base fundemental in a lot of MPC cryptography and in Web3Auth’s infrastucture. More can be -read [here](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing). +SSS is often applied in MPC cryptography and is fundemental to Embedded Wallet’s infrastucture. -### Verifiable Secret Sharing (VSS) +### Verifiable Secret Sharing -Verifiable secret sharing refers to Shamir secret sharing schemes where even in the presence of -malicious dealers, there is a well-defined secret that the participants can later reconstruct. +Verifiable secret sharing (VSS) refers to a class of secret-sharing schemes—often built on top of Shamir’s Secret Sharing—that ensure a well-defined secret can be reconstructed, even if the party distributing the shares behaves maliciously. -### Threshold Signature Schemes (TSS) +### Threshold Signature Schemes -Threshold signature schemes refer to signing schemes that allow a qualified set of parties involved +Threshold signature schemes (TSS) refer to signing schemes that allow a qualified set of parties involved in a secret sharing scheme to generate a signature on a message without reconstructing the private -key. The most well-known signature scheme is [GG19](https://eprint.iacr.org/2019/114.pdf) and an -implementation can be found [here](https://github.com/ZenGo-X/multi-party-ecdsa). In particular -Web3Auth supports and utilizes GG19, GG20, its EDDSA variants, and DKLS19. +key. The most well-known signature scheme is [GG19](https://eprint.iacr.org/2019/114.pdf) (with a reference implementation available in the [ZenGo-X repository](https://github.com/ZenGo-X/multi-party-ecdsa)). In particular +Embedded Wallets supports and utilizes GG19, GG20, its EDDSA variants, and DKLS19. -### Distributed Key Generation (DKG) +### Distributed Key Generation -Distributed key generation was introduced by Pedersen, and the key idea involves using n parallel -runs of SSS or VSS to ensure that there is no dealer who knows the secret. We generally use a -varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pdf) in our DKG. +Distributed Key Generation (DKG) was introduced by Pedersen, who demonstrated that using n parallel +runs of SSS or VSS ensures that there is no single party who knows the secret. Embedded wallets applies a +varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pdf) (AVSS) in our DKG.
Async Verifiable Secret Sharing
- The main advantage Async Verifiable Secret Sharing DKG has over the other well-known DKGs like - Pedersen DKG, Feldman's VSS and its variants is that it is fully asynchronous and thus does + The main advantage AVSS DKG has over the other well-known DKGs like + Pedersen DKG, Feldman's VSS, and its variants is that it is fully asynchronous. This means it does not require a complaint phase when we consider the allowance for a small zero-knowledge proof. This results in a simpler implementation (with constant communication rounds even during malicious scenarios), but at the expense of message size.

- In brief, this scheme generates a random bivariate polynomial (i.e. 2D surface) and creates - horizontal (X) and vertical (Y) slices at the appropriate indices as sharings. We then get - sub-sharings (points) on these horizontal and vertical sharings at the appropriate indices and - echo them to other nodes. As a node, the polynomial reconstructed from the sub-sharings - received from other nodes should match up with the initial sharing that the node received from - the dealer, and even if they do not, the node can always interpolate the correct sharing via - these echoed sub-sharings. This eliminates the dealer complaint phase. We then we restrict - ourselves to just the horizontal (X) domain such that our final sharings are still on that of - a univariate polynomial, which is what a typical DKG does.‌ + In brief, this scheme generates a random bivariate polynomial (a 2D surface) and creates horizontal (X) and vertical (Y) slices at the appropriate indices as shares. From these slices, nodes derive sub-shares (evaluation points) and exchange them with other nodes. + + Each node reconstructs a polynomial from the sub-shares received from other nodes and verifies that it is consistent with the initial share it received from the originating node. If inconsistencies are detected, the node can interpolate the correct share using the exchanged sub-shares, which eliminates the need for a separate complaint phase. + + Finally, the scheme restricts itself to the horizontal (X) domain so that the resulting shares lie on a univariate polynomial, which matches the structure used by standard DKG protocols.

@@ -73,13 +63,13 @@ varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pd ### Proactive Secret Sharing (PSS) Proactive secret sharing allows participants to “refresh” shares, so that all participants receive -new shares, but the secret remains unchanged. This allows the secret sharing to be secure against +new shares, while the secret remains unchanged. This allows the secret sharing to be secure against mobile adversaries who may be able to compromise all participants over the lifetime of the secret -(eg. adversary hacks a random participant’s server every month). +(for example, an adversary hacks a random participant’s server every month). Simply copying shares across epochs is a bad idea, since a single node operator operating in two -separate epochs would get access to two shares, and it also makes it not possible to increase or -decrease the number of operators in each epoch. Hence, we use PSS to migrate shares across epochs. +separate epochs would get access to two shares, and it also makes it impossible to increase or +decrease the number of operators in each epoch. This is why we use PSS to migrate shares across epochs. We refer the user to a [Proactive Secret Sharing Scheme](https://eprint.iacr.org/2002/134.pdf) that supports dynamic sets of participants, which we use for share refresh. In brief, the key idea is diff --git a/embedded-wallets/infrastructure/mpc-architecture.mdx b/embedded-wallets/infrastructure/mpc-architecture.mdx index 6358be2cfc6..edc01f6f3f9 100644 --- a/embedded-wallets/infrastructure/mpc-architecture.mdx +++ b/embedded-wallets/infrastructure/mpc-architecture.mdx @@ -1,8 +1,8 @@ --- -title: Web3Auth MPC Architecture +title: Embedded Wallets MPC Architecture sidebar_label: MPC Architecture -description: 'MPC Architecture - Web3Auth Wallet Infrastructure | Embedded Wallets' +description: 'MPC Architecture - Embedded Wallets Wallet Infrastructure | Web3Auth' --- import ExpandingSharesFlow from '@site/static/img/embedded-wallets/infrastructure/expanding-shares-tss-flow.png' @@ -11,43 +11,45 @@ import KeyUsageFlow from '@site/static/img/embedded-wallets/infrastructure/key-u import TkeyMpcFlowDark from '@site/static/img/embedded-wallets/flow-diagrams/tkey-mpc-flow-dark.png' import TkeyMpcFlowLight from '@site/static/img/embedded-wallets/flow-diagrams/tkey-mpc-flow-light.png' -This document provides an in-depth exploration of the technical architecture of the MPC-based SDKs, this includes the MPC Core Kit SDKs. +This document provides an in-depth exploration of the technical architecture of the MPC-based SDK, this includes the MPC Core Kit SDK. -The only difference between the SSS-based SDKs and MPC SDKs are that during usage/login MPC SDKs do not reconstruct user private keys. +The only difference between the [Shamir Secret Sharing-based](./glossary.mdx#shamir-secret-sharing) (SSS-based) SDKs and MPC SDKs are that during usage/login MPC SDKs do not reconstruct user private keys. -## Overview of Cryptographic and Blockchain Support (compatibility and implementations) +## Overview of cryptographic and blockchain support (compatibility and implementations) -Web3Auth supports most popular blockchains & elliptic curves out there. In particular, out of the box the infrastucture supports all chains on: +Embedded Wallets supports the most popular blockchains and elliptic curves: -- `secp256k1` | Ethereum (EVM) chains, Bitcoin, Polygon & other L2s, etc... +- `secp256k1` | Ethereum (EVM) chains (Base, Linea, Polygon, and other L2s), Bitcoin - `ed25519` | Solana, Polkadot, NEAR -For other elliptic curve/chain support, feel free to [ask/request](https://web3auth.io/contact-us.html) as we may already support them. +:::tip -### Distributed Key Generation & Pro-active Secret Sharing Schemes Used +For enquiries regarding additional elliptic curve/chain support, [ask/request](https://web3auth.io/contact-us.html) as we may already support them. -There are many schemes and variants for DKGs and PSSs out there, we in particular use an asynchronous variant, [Kate12](https://eprint.iacr.org/2012/377.pdf), derived from Asynchronous Verifiable Secret Sharing (AVSS), [Cachin02](https://eprint.iacr.org/2002/134.pdf). +::: + +### Distributed key generation and Pro-active Secret Sharing schemes + +There are many schemes and variants for [DKGs](./glossary.mdx#distributed-key-generation) and [PSSs](./glossary.mdx#proactive-secret-sharing-pss). Embedded wallets uses an asynchronous variant, [Kate12](https://eprint.iacr.org/2012/377.pdf), derived from Asynchronous Verifiable Secret Sharing (AVSS) [Cachin02](https://eprint.iacr.org/2002/134.pdf). -### TSS & Signature Schemes Used +### Threshold signature schemes -TSS schemes often vary in their approach to creating shared cryptographic material in a distributed manner. We support the popular EDDSA, and [DKLS19](https://eprint.iacr.org/2019/523.pdf). In result supporting the `ecdsa` signature standard on both elliptic curves. +[Threshold signature schemes](./glossary.mdx#threshold-signature-schemes) (TSS) vary in their approach to creating shared cryptographic material in a distributed manner. Embedded Wallets supports threshold EdDSA and threshold ECDSA using the [DKLS19](https://eprint.iacr.org/2019/523.pdf), covering both Ed25519 and secp256k1 elliptic curves. -It's worth noting that the TSS signing is largely decoupled from Web3Auth's infrastucture to allow us to be agnostic to TSS implementation. These include other signature schemes, which arguably are much more convienent. Notably, but non-exhaustively, Web3Auth supports: +Note that the TSS signing is largely decoupled from Embedded Wallets's infrastucture allowing the implementation to be agnostic to the underlying TSS protocol. This design enables support for multiple signature schemes, including: - [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) or its ElGamal variants - EDDSA or its [Schnorr variants](https://en.wikipedia.org/wiki/Schnorr_signature) -- BLS, Stark (coming soon) +- BLS +- Stark (coming soon) -| :memo: For other signature or elliptic curve or chain support, feel free to [ask or request](https://web3auth.io/contact-us.html) if we support them | -| ---------------------------------------------------------------------------------------------------------------------------------------------------- | +## User key overview -## User Key Overview +Embedded Wallets uses MPC to manage user wallets in a distributed fashion, leveraging various factors or shares managed by users, including their devices, private inputs, backup locations, and cloud service providers. As long as a user can access 2 out of n (2/n) of these shares, they can access their key. This distributedly secure key is called the $TSSKey$. -Web3Auth uses MPC to manage user wallets in a distributed fashion, leveraging various factors or shares managed by users, including their devices, private inputs, backup locations, and cloud service providers. As long as a user can access 2 out of n (2/n) of these shares, they can access their key. This distributedly secure key is called the $TSSKey$. +One of the lost functionalities of a distributedly secure key is the loss of efficient encryption/decryption capabilities. As such the $TSSKey$ is supported by another cryptographic key whose main purpose is to manage metadata pertaining to the user's account, the **metadataKey**. User metadata is strictly supplementary, helping to facilitate and govern user flows. Importantly, metadata does not leak information about the shares of the $TSSKey$ being used to sign transactions. -One of the lost functionalities of a distributedly secure key is the loss of efficient encryption/decryption capabilities. As such the **TSSKey** is supported by another cryptographic key that's main purpose is to manage metadata pertaining to the user's account, the **metadataKey**. User metadata is strictly supplementary and only helps to facilitate and govern user flows. In particular, metadata does not leak information about the shares of the **TSSKey** being used to sign transactions. - -### TSS Key +### Threshold signature scheme key @@ -55,47 +57,44 @@ One of the lost functionalities of a distributedly secure key is the loss of eff This diagram describes the relationship between the Web3Auth SDK and integrating application The user's setup starts by distributedly key generating (DKG) a 2 out of 3 (2/3) sharing, $f_0(x) = a_0 + a_1x$, with three shares: $f_0(1), f_0(z_1), f_0(z_2)$ where $z_1,z_2 \in \mathbb{Z}_q$. -1. **$f_0(z_1)$ "ShareA" is managed by Web3Auth infrastructure**: This share is kept and managed by OAuth authentication flows in a distributed security model. -2. **$f_0(1)$ "ShareB" is stored on the user's device**: Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics. -3. **$f_0(z_2)$ "ShareC" is a backup share**: An extra share to be kept by the user, possibly kept on a seperate device, downloaded or based on user input with enough entropy (eg. password, security questions, hardware device etc.). +1. $f_0(z_1)$ **ShareA** is managed by the Embedded Wallets infrastructure: This share is kept and managed by authentication flows (for example, OAuth login from an existing account) in a distributed security model. +2. **$f_0(1)$ **ShareB** is stored on the user's device: Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics. +3. **$f_0(z_2)$ **ShareC** is a backup share: An extra share to be kept by the user, possibly kept on a seperate device (such as a hardware device), downloaded, or based on user input with enough entropy (such as a password or security questions). -### The Metadata Key +### The metadata key -This key's storage process mirrors that of the TSSKey, with the primary difference being that the metadataKey is always reconstructed and used for encryption/decryption tasks. It's based on the fundamental Shamir’s Secret Sharing scheme and initially generated on the user's front-end. +This key's storage process mirrors that of the $TSSKey$, with the primary difference being that the metadataKey is always reconstructed and used for encryption/decryption tasks. It's based on the fundamental [SSS](./glossary.mdx#shamir-secret-sharing) scheme and initially generated on the user's frontend. ## Other components -### Factor Keys +### Factor keys -Factor keys enable refreshing, setting up multiple keys, deletion, and rotation capabilities on the TSSKey. They are randomly generated across various user-controlled locations or factors, such as their phone, chrome extension, cloud, or assisting third parties. Primarily used for data encryption/decryption, these keys provide a constant secret in different locations as shares to the TSSKey and/or metadataKey may rotate. They represent a storage point with a public address that we can encrypt data blobs for. +Factor keys enable refreshing, setting up multiple keys, deletion, and rotation capabilities on the $TSSKey$. They are randomly generated across various user-controlled locations or factors, such as their phone, chrome extension, cloud, or assisting third parties. Primarily used for data encryption/decryption, these keys provide a constant secret in different locations as shares to the $TSSKey$ and/or metadataKey may rotate. They represent a storage point with a public address that Embedded Wallets can encrypt data blobs for. -### User Metadata +### User metadata -User metadata is strictly supplementary and only helps to facilitate and govern user flows. In particular, metadata does not leak information about the shares of the private key being used to sign transactions. +User metadata is strictly supplementary and only helps to facilitate and govern user flows. As noted above, metadata does not leak information about the shares of the private key being used to sign transactions. -Metadata uses an encrypted storage layer that serves as a persistent data store for storing encrypted information about the user’s keys (eg. public key, preferences, device information, thresholds etc). This information is stored in a replicated fashion across the set of nodes that are involved in facilitating the user login. +Metadata uses an encrypted storage layer that serves as a persistent data store for storing encrypted information about the user’s keys (for example, public key, preferences, device information, and thresholds). This information is stored in a replicated fashion across the set of nodes that are involved in facilitating the user login. -During operation, when the user has threshold shares, they can read and write to metadata. Writing to metadata requires encrypting the data and signing it with the shares / private key. +During operation, when the user achieves threshold shares, they can read and write to metadata. Writing to metadata requires encrypting the data and signing it with the shares / private key. ## Flows -This segment goes through some of the interactions on a deeper level. - -:::note Components +Embedded Wallets flows manage how authentication, device storage, and backup factors work together during wallet creation, signing, and recovery. Three key elements are involved: -- **Web3Auth Infrastructure:** Web3Auth infrasturcture provides a user-specific share/factor based on some form of attestation from the user. This attestation could come in the form of an OAuth login from an existing account, a traditional email account login, or even biometrics. It also serves as a persistent data store for storing encrypted metadata, we also call this the metadata layer in following diagrams. +- **ShareA:** Embedded Wallets' infrasturcture provides a user-specific share/factor based on some form of attestation from the user. This attestation could come in the form of an OAuth login from an existing account, a traditional email account login, or even biometrics. It also serves as a persistent data store for storing encrypted metadata: the "metadata layer" in the following diagrams. -- **User device:** tKey is dependent on user devices to store shares. The base flow accomodates a single device, but users can use multiple devices to increase the threshold once they have an initial setup. Access to device storage on the user's device is implementation specific. For example, for native applications on mobile, they can make use of the device keychain. +- **ShareB:** $TSSKey$ relies on user devices to store shares. The base flow accomodates a single device, but users can use multiple devices to increase the threshold once they have an initial setup. Access to device storage on the user's device is implementation specific. For example, for native applications on mobile, they can make use of the device keychain. -- **Backup factor/share:** This is generally _not_ used during normal operation, and is intended for use in key recovery / share refresh if the user loses his/her device or shares. +- **ShareC**, the **Backup factor/share:** This is generally _not_ used during normal operation, and is intended for use in key recovery / share refresh if the user loses his/her device or shares. -::: ### Key initialization @@ -113,9 +112,9 @@ We select a polynomial $f(z)$ over $Z_q$ where: $$f(z) = a_1z + \sigma$$ src={KeyInitialisationFlow} /> -ShareA is stored on the user’s device, ShareB stored on Web3Auth Infrastructure, and ShareC dependent on user input or handled as a recovery share. +ShareA is stored on the user’s device, ShareB stored on Embedded Wallets Infrastructure, and ShareC dependent on user input or handled as a recovery share. -### Key Usage, Access and Signing +### Key usage, access and signing If a user has logged in previously, he/she access their key by accessing ShareB via a session token handshake and utilzing it with ShareA on the user’s current device using to sign Threshold Signaures. @@ -140,9 +139,9 @@ The offline signing phase consists of 6 rounds of interaction between the device This means that although the threshold signature generation takes a substantial amount of time, most of it can be precomputed via a background process, before the user even needs to sign a transaction. When the user decides to sign a message in the online phase, only one round of noninteractive communication is required, which is very fast (\<0.2 seconds). -### Expanding the Number of Shares (Adding a Device) +### Expanding the number of shares (adding a device) -In the case of a new device the user needs to conduct a Proactive Secret Sharing, a refresh scheme to generate a new factor in a distributed manner. This example goes through the setup on a new user’s device with an existing device in hand. This can also be conducted with a user’s backup factor, ie.e ShareC. +In the case of a new device the user needs to conduct a [PSS](./glossary.mdx#proactive-secret-sharing-pss), a refresh scheme to generate a new factor in a distributed manner. This example goes through the setup on a new user's device with an existing device in hand. This can also be conducted with a user's backup factor, such as ShareC. Expanding Shares Flow Date: Mon, 29 Dec 2025 16:29:15 +0000 Subject: [PATCH 2/3] reviews infrastructure section --- embedded-wallets/infrastructure/glossary.mdx | 27 +++-- .../infrastructure/mpc-architecture.mdx | 112 ++++++++++++------ .../infrastructure/nodes-and-dkg.mdx | 89 ++++++++------ 3 files changed, 140 insertions(+), 88 deletions(-) diff --git a/embedded-wallets/infrastructure/glossary.mdx b/embedded-wallets/infrastructure/glossary.mdx index 86c98548311..20bc25c446b 100644 --- a/embedded-wallets/infrastructure/glossary.mdx +++ b/embedded-wallets/infrastructure/glossary.mdx @@ -7,10 +7,11 @@ description: ### Shamir Secret Sharing -[Shamir’s Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) (SSS) scheme is a polynomial threshold $(t,n)$ secret sharing scheme where the secret holder divides a secret into n multiple shares and each participant is given a share by evaluating a +[Shamir’s Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) (SSS) scheme is a polynomial +threshold $(t,n)$ secret sharing scheme where the secret holder divides a secret into n multiple shares and each participant is given a share by evaluating a polynomial of order $t$ . To reconstruct the secret, $t + 1$ shares are required. -SSS is often applied in MPC cryptography and is fundemental to Embedded Wallet’s infrastucture. +SSS is often applied in MPC cryptography and is fundamental to Embedded Wallet’s infrastructure. ### Verifiable Secret Sharing @@ -20,7 +21,8 @@ Verifiable secret sharing (VSS) refers to a class of secret-sharing schemes—of Threshold signature schemes (TSS) refer to signing schemes that allow a qualified set of parties involved in a secret sharing scheme to generate a signature on a message without reconstructing the private -key. The most well-known signature scheme is [GG19](https://eprint.iacr.org/2019/114.pdf) (with a reference implementation available in the [ZenGo-X repository](https://github.com/ZenGo-X/multi-party-ecdsa)). In particular +key. The most well-known signature scheme is [GG19](https://eprint.iacr.org/2019/114.pdf) (with a reference +implementation available in the [ZenGo-X repository](https://github.com/ZenGo-X/multi-party-ecdsa)). In particular, Embedded Wallets supports and utilizes GG19, GG20, its EDDSA variants, and DKLS19. ### Distributed Key Generation @@ -33,7 +35,7 @@ varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pd Async Verifiable Secret Sharing
- The main advantage AVSS DKG has over the other well-known DKGs like + The main advantage Async Verifiable Secret Sharing (AVSS) DKG has over the other well-known DKGs like Pedersen DKG, Feldman's VSS, and its variants is that it is fully asynchronous. This means it does not require a complaint phase when we consider the allowance for a small zero-knowledge proof. This results in a simpler implementation (with constant communication rounds even during @@ -41,9 +43,12 @@ varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pd

- In brief, this scheme generates a random bivariate polynomial (a 2D surface) and creates horizontal (X) and vertical (Y) slices at the appropriate indices as shares. From these slices, nodes derive sub-shares (evaluation points) and exchange them with other nodes. + In brief, this scheme generates a random bivariate polynomial (a 2D surface) and creates horizontal (X) and + vertical (Y) slices at the appropriate indices as shares. From these slices, nodes derive sub-shares (evaluation points) and exchange them with other nodes. - Each node reconstructs a polynomial from the sub-shares received from other nodes and verifies that it is consistent with the initial share it received from the originating node. If inconsistencies are detected, the node can interpolate the correct share using the exchanged sub-shares, which eliminates the need for a separate complaint phase. + Each node reconstructs a polynomial from the sub-shares received from other nodes and verifies that it is + consistent with the initial share it received from the originating node. If inconsistencies are detected, the node can interpolate the correct share using the exchanged sub-shares, which eliminates the need for a separate + complaint phase. Finally, the scheme restricts itself to the horizontal (X) domain so that the resulting shares lie on a univariate polynomial, which matches the structure used by standard DKG protocols.
@@ -60,9 +65,9 @@ varient of [Async Verifiable Secret Sharing](https://eprint.iacr.org/2002/134.pd
-### Proactive Secret Sharing (PSS) +### Proactive Secret Sharing -Proactive secret sharing allows participants to “refresh” shares, so that all participants receive +Proactive Secret Sharing (PSS) allows participants to “refresh” shares, so that all participants receive new shares, while the secret remains unchanged. This allows the secret sharing to be secure against mobile adversaries who may be able to compromise all participants over the lifetime of the secret (for example, an adversary hacks a random participant’s server every month). @@ -73,7 +78,7 @@ decrease the number of operators in each epoch. This is why we use PSS to migrat We refer the user to a [Proactive Secret Sharing Scheme](https://eprint.iacr.org/2002/134.pdf) that supports dynamic sets of participants, which we use for share refresh. In brief, the key idea is -that we create polynomial sharings of the existing key shares and add these polynomials in a +that we create polynomial sharing of the existing key shares and add these polynomials in a specific way such that the coefficient of the master polynomial is the Lagrange interpolation of the existing key shares. Much like how DKGs are the sum of several secret sharings, where the master secret is the sum of all of the secrets from each of the N-parallel secret sharing protocols, we can @@ -83,8 +88,8 @@ nodes, with their "secret" as their share. The resulting shares of shares, if ad ### Epochs -Torus nodes operate within a certain time period, called an epoch. Nodes within the same epoch are -part of the same BFT (Byzantine Fault Tolerance) network and hold key shares that are compatible +The underlying node network operates within chunks of time, called an epoch. Nodes within the same epoch are +part of the same BFT (Byzantine Fault Tolerant) network and hold key shares that are compatible with each others' key shares. Nodes within different epochs do not. The main purpose of epochs is to ensure that node operators can be removed and added, and to minimize the impact of loss of key shares or node failures over time. diff --git a/embedded-wallets/infrastructure/mpc-architecture.mdx b/embedded-wallets/infrastructure/mpc-architecture.mdx index edc01f6f3f9..c2305ce4bc0 100644 --- a/embedded-wallets/infrastructure/mpc-architecture.mdx +++ b/embedded-wallets/infrastructure/mpc-architecture.mdx @@ -19,24 +19,27 @@ The only difference between the [Shamir Secret Sharing-based](./glossary.mdx#sha Embedded Wallets supports the most popular blockchains and elliptic curves: -- `secp256k1` | Ethereum (EVM) chains (Base, Linea, Polygon, and other L2s), Bitcoin +- `secp256k1` | Ethereum (EVM) chains (including Base, Linea, Polygon, and other L2s), Bitcoin - `ed25519` | Solana, Polkadot, NEAR :::tip -For enquiries regarding additional elliptic curve/chain support, [ask/request](https://web3auth.io/contact-us.html) as we may already support them. +For enquiries regarding additional elliptic curve/chain support, [ask/request](https://web3auth.io/contact-us.html) as +we may already support them. ::: -### Distributed key generation and Pro-active Secret Sharing schemes +### Distributed key generation and Proactive Secret Sharing schemes -There are many schemes and variants for [DKGs](./glossary.mdx#distributed-key-generation) and [PSSs](./glossary.mdx#proactive-secret-sharing-pss). Embedded wallets uses an asynchronous variant, [Kate12](https://eprint.iacr.org/2012/377.pdf), derived from Asynchronous Verifiable Secret Sharing (AVSS) [Cachin02](https://eprint.iacr.org/2002/134.pdf). +There are many schemes and variants for [Distributed Key Generation](./glossary.mdx#distributed-key-generation) (DKG) +and [Proactive Secret Sharing](./glossary.mdx#proactive-secret-sharing) schemes (PSSs). Embedded wallets uses an asynchronous variant, [Kate12](https://eprint.iacr.org/2012/377.pdf), derived from Asynchronous Verifiable Secret +Sharing (AVSS) [Cachin02](https://eprint.iacr.org/2002/134.pdf). ### Threshold signature schemes [Threshold signature schemes](./glossary.mdx#threshold-signature-schemes) (TSS) vary in their approach to creating shared cryptographic material in a distributed manner. Embedded Wallets supports threshold EdDSA and threshold ECDSA using the [DKLS19](https://eprint.iacr.org/2019/523.pdf), covering both Ed25519 and secp256k1 elliptic curves. -Note that the TSS signing is largely decoupled from Embedded Wallets's infrastucture allowing the implementation to be agnostic to the underlying TSS protocol. This design enables support for multiple signature schemes, including: +Note that the TSS signing is largely decoupled from Embedded Wallets' infrastructure allowing the implementation to be agnostic to the underlying TSS protocol. This design enables support for multiple signature schemes, including: - [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) or its ElGamal variants - EDDSA or its [Schnorr variants](https://en.wikipedia.org/wiki/Schnorr_signature) @@ -45,9 +48,13 @@ Note that the TSS signing is largely decoupled from Embedded Wallets's infrastuc ## User key overview -Embedded Wallets uses MPC to manage user wallets in a distributed fashion, leveraging various factors or shares managed by users, including their devices, private inputs, backup locations, and cloud service providers. As long as a user can access 2 out of n (2/n) of these shares, they can access their key. This distributedly secure key is called the $TSSKey$. +Embedded Wallets uses MPC to manage user wallets in a distributed fashion, leveraging various factors or shares +managed by users, including their devices, private inputs, backup locations, and cloud service providers. As long +as a user can access 2 out of n (2/n) of these shares, they can access their key. This secure key, generated using +DKG is called the $TSSKey$. -One of the lost functionalities of a distributedly secure key is the loss of efficient encryption/decryption capabilities. As such the $TSSKey$ is supported by another cryptographic key whose main purpose is to manage metadata pertaining to the user's account, the **metadataKey**. User metadata is strictly supplementary, helping to facilitate and govern user flows. Importantly, metadata does not leak information about the shares of the $TSSKey$ being used to sign transactions. +One of disadvantages of a DKG-generated keys is the loss of efficient encryption/decryption capabilities. As such, +the $TSSKey$ is supported by another cryptographic key whose main purpose is to manage metadata pertaining to the user's account, the **metadataKey**. User metadata is strictly supplementary, helping to facilitate and govern user flows. Importantly, metadata does not leak information about the shares of the $TSSKey$ being used to sign transactions. ### Threshold signature scheme key @@ -61,15 +68,19 @@ One of the lost functionalities of a distributedly secure key is the loss of eff /> -The user's setup starts by distributedly key generating (DKG) a 2 out of 3 (2/3) sharing, $f_0(x) = a_0 + a_1x$, with three shares: $f_0(1), f_0(z_1), f_0(z_2)$ where $z_1,z_2 \in \mathbb{Z}_q$. +The user's setup uses DKG to instantiate 2 out of 3 (2/3) sharing, $f_0(x) = a_0 + a_1x$, with three +shares: $f_0(1), f_0(z_1), f_0(z_2)$ where $z_1,z_2 \in \mathbb{Z}_q$. 1. $f_0(z_1)$ **ShareA** is managed by the Embedded Wallets infrastructure: This share is kept and managed by authentication flows (for example, OAuth login from an existing account) in a distributed security model. 2. **$f_0(1)$ **ShareB** is stored on the user's device: Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics. -3. **$f_0(z_2)$ **ShareC** is a backup share: An extra share to be kept by the user, possibly kept on a seperate device (such as a hardware device), downloaded, or based on user input with enough entropy (such as a password or security questions). +3. **$f_0(z_2)$ **ShareC** is a backup share: An extra share to be kept by the user, possibly kept on a separate +device (such as a hardware device), downloaded, or based on user input with enough entropy (such as a password or +security questions). ### The metadata key -This key's storage process mirrors that of the $TSSKey$, with the primary difference being that the metadataKey is always reconstructed and used for encryption/decryption tasks. It's based on the fundamental [SSS](./glossary.mdx#shamir-secret-sharing) scheme and initially generated on the user's frontend. +This key's storage process mirrors that of the $TSSKey$, with the primary difference being that the metadataKey is +always reconstructed and used for encryption/decryption tasks. It's based on the fundamental [SSS](./glossary.mdx#shamir-secret-sharing) scheme and initially generated on the user's frontend. ## Other components @@ -79,32 +90,42 @@ Factor keys enable refreshing, setting up multiple keys, deletion, and rotation ### User metadata -User metadata is strictly supplementary and only helps to facilitate and govern user flows. As noted above, metadata does not leak information about the shares of the private key being used to sign transactions. +User metadata is strictly supplementary and only helps to facilitate and govern user flows. As noted above, metadata +does not leak information about the shares of the private key being used to sign transactions. -Metadata uses an encrypted storage layer that serves as a persistent data store for storing encrypted information about the user’s keys (for example, public key, preferences, device information, and thresholds). This information is stored in a replicated fashion across the set of nodes that are involved in facilitating the user login. +Metadata uses an encrypted storage layer that serves as a persistent data store for storing encrypted information +about the user’s keys (for example, public key, preferences, device information, and thresholds). This information is stored in a replicated fashion across the set of nodes that are involved in facilitating the user login. During operation, when the user achieves threshold shares, they can read and write to metadata. Writing to metadata requires encrypting the data and signing it with the shares / private key. ## Flows -Embedded Wallets flows manage how authentication, device storage, and backup factors work together during wallet creation, signing, and recovery. Three key elements are involved: +Embedded Wallets flows manage how authentication, device storage, and backup factors work together during wallet +creation, signing, and recovery. Three key elements are involved: -- **ShareA:** Embedded Wallets' infrasturcture provides a user-specific share/factor based on some form of attestation from the user. This attestation could come in the form of an OAuth login from an existing account, a traditional email account login, or even biometrics. It also serves as a persistent data store for storing encrypted metadata: the "metadata layer" in the following diagrams. +- **ShareA:** Embedded Wallets' infrastructure provides a user-specific share/factor based on some form of attestation +from the user. This attestation could come in the form of an OAuth login from an existing account, a traditional email account login, or even biometrics. It also serves as a persistent data store for storing encrypted metadata: the +"metadata layer" in the following diagrams. -- **ShareB:** $TSSKey$ relies on user devices to store shares. The base flow accomodates a single device, but users can use multiple devices to increase the threshold once they have an initial setup. Access to device storage on the user's device is implementation specific. For example, for native applications on mobile, they can make use of the device keychain. +- **ShareB:** $TSSKey$ relies on user devices to store shares. The base flow accommodates a single device, but users can use multiple devices to increase the threshold once they have an initial setup. Access to device storage on the user's device is implementation specific. For example, for native applications on mobile, they can make use of the device +keychain. -- **ShareC**, the **Backup factor/share:** This is generally _not_ used during normal operation, and is intended for use in key recovery / share refresh if the user loses his/her device or shares. +- **ShareC**, the **Backup factor/share:** This is generally _not_ used during normal operation, and is intended for +use in key recovery / share refresh if the user loses his/her device or shares. +### Key handling on user login -### Key initialization +Key handling begins in response to a user-triggered action, such as logging in. At this stage, the system attempts to retrieve any existing encrypted metadata associated with the user. -A key is initialized upon a user-triggered action (eg. login to nodes). We then attempt to retrieve associated metadata for the user. If none exists, the user is a new one and we generate a corresponding SSS 2/3 polynomial with its respective key and shares. If it exists, we decrypt the metadata using the nodes $encKey$ and read the metadata to verify user information and associated secret sharing parameters. +If metadata is found, the user is an existing user. The metadata is decrypted using the nodes’ $encKey$ , and the stored information is used to validate the user and load the existing secret-sharing parameters. No new key material is generated in this path. + +If no metadata is found, the user is treated as a new user, and a new key is initialized. In this case, a 2-of-3 Shamir’s Secret Sharing (SSS) polynomial is generated, producing a private key and its corresponding shares. We select a polynomial $f(z)$ over $Z_q$ where: $$f(z) = a_1z + \sigma$$ - $f(0) = \sigma$ denotes the private key scalar to be used by the user -- $a_1$ is a coefficient to $z$ -- $f(z_1),f(z_2)$ and $f(z_3)$ are ShareA, ShareB and ShareC respectively +- $a_1$ is a polynomial coefficient to $z$ +- $f(z_1),f(z_2)$ and $f(z_3)$ are ShareA, ShareB, and ShareC respectively Key Initialisation Flow -ShareA is stored on the user’s device, ShareB stored on Embedded Wallets Infrastructure, and ShareC dependent on user input or handled as a recovery share. - ### Key usage, access and signing -If a user has logged in previously, he/she access their key by accessing ShareB via a session token handshake and utilzing it with ShareA on the user’s current device using to sign Threshold Signaures. +For returning users, key access is established by retrieving ShareB via a session token handshake and combining it +with the locally stored ShareA on the user’s device to produce threshold signatures. Key Usage Flow -#### Threshold Signature Scheme (TSS) +#### Threshold Signature Scheme -The TSS signing requires information from two sections: +The [TSS](./glossary.mdx#threshold-signature-schemes) signing requires information from two sections: -- shared information (eg. public key, share commitments, theeshold, unique identifiers) -- local information (eg. TSS key share). +- shared information (such as public key, share commitments, threshold, unique identifiers) +- local information (such as TSS key share) -The shared information is stored on metadata and replicated, whereas the local information is kept locally on the user's device. This ensures that metadata for shared operations can be easily replicated and accessed without computationally expensive calls, while for local operations the TSS key shares never leave the local context. +The shared information is stored as metadata and replicated, whereas the local information is kept on the user's device. This ensures that metadata for shared operations can be easily replicated and accessed without computationally expensive calls, while for local operations the TSS key shares never leave the local context. -Constructing a threshold signature requires a session token which we can get via the session request. This then allows us to set up a threshold signature session. The threshold signature session consists of an offline signing phase and an online signing phase (GG20, GG19, Doerner19). +Constructing a threshold signature requires a session token which we can get via the session request. This then allows us to set up a threshold signature session. The threshold signature session consists of an offline signing phase and an +online signing phase (GG20, GG19, Doerner19). -The offline signing phase consists of 6 rounds of interaction between the device and nodes and can be pre-computed before the transaction signing request is received. The online signing phase requires the transaction to be present and is non-interactive. +The offline signing phase consists of 6 rounds of interaction between the device and nodes and can be precomputed before the transaction signing request is received. The online signing phase requires the transaction to be present and is non-interactive. -This means that although the threshold signature generation takes a substantial amount of time, most of it can be precomputed via a background process, before the user even needs to sign a transaction. When the user decides to sign a message in the online phase, only one round of noninteractive communication is required, which is very fast (\<0.2 seconds). +This means that although the threshold signature generation takes a substantial amount of time, most of it can be precomputed via a background process, before the user even needs to sign a transaction. When the user decides to sign +a message in the online phase, only one round of noninteractive communication is required, which is very fast +(\<0.2 seconds). ### Expanding the number of shares (adding a device) -In the case of a new device the user needs to conduct a [PSS](./glossary.mdx#proactive-secret-sharing-pss), a refresh scheme to generate a new factor in a distributed manner. This example goes through the setup on a new user's device with an existing device in hand. This can also be conducted with a user's backup factor, such as ShareC. +In the case of adding a new device, the user needs to conduct a [PSS](./glossary.mdx#proactive-secret-sharing) to +trigger a refresh protocol that derives an additional share in a distributed manner, without changing the +underlying secret. The following example goes through the setup on a user's device with an existing device in hand. +This can also be conducted with a user's backup factor, such as ShareC. Expanding Shares Flow ## Lifecycle ### Initialization -When a Web3Auth Network Node is started, it tries to register its connection details on an Ethereum smart contract. Once all nodes have been registered for that epoch, they try to connect with each other to set up the BFT network, and start generating distributed keys. They also listen for incoming information from nodes in the previous epoch. +When an Embedded Wallets Network node is started, it tries to register its connection details on an Ethereum smart contract. Nodes that successfully register for that epoch try to connect with each other to set up the BFT network, and start generating distributed keys. They also listen for incoming information from nodes in the previous epoch. ### Operation During operation, a node runs three separate parallel process: -1. Mapping user IDs to keys -2. Generating distributed key shares +1. Mapping user IDs to keys. +2. Generating distributed key shares. 3. Allowing users to retrieve their shares. #### Mapping user IDs to keys -The mapping process primarily interacts with the BFT layer, which allows nodes to share state on which keys belong to which users. When a new user requests for a key, the node submits a BFT transaction that modifies this state. Existing users who have logged in are compared against this shared state to ensure that they retrieve the correct key share. +The mapping process primarily interacts with the BFT layer, which allows nodes to share state on which keys belong to which users. When a new user requests a key, the node submits a BFT transaction that modifies this state. Existing users who have logged in are compared against this shared state to ensure that they retrieve the correct key share. #### Generating distributed key shares -The distributed key generation process primarily uses libp2p for communication between nodes, and generates a buffer of shared keys, in order to reduce the average response time for key assignments for new users. +The DKG process primarily uses libp2p for communication between nodes, and generates a buffer of shared keys in order to reduce the average response time for key assignments for new users. -#### Allowing users to retrieve their shares. +#### Allowing users to retrieve their shares -The share retrieval process starts when a user wishes to retrieve their keys. They individually submit their OAuth token via a commit-reveal scheme to the nodes, and once this OAuth token is checked for uniqueness and validity, each node returns the user's \(encrypted\) key share. This does not require communication between the nodes. +The share retrieval process starts when a user wishes to retrieve their keys. They individually submit their authentication token via a commit-reveal scheme to the nodes, and once this authentication token is checked for uniqueness and validity, each node returns the user's \(encrypted\) key share. This does not require communication between the nodes. Assignments of keys to new users only require interaction with the mapping process, assuming that there is at least one unassigned key in the buffer. As such, we are able to assign keys to accounts ahead of time, before that accounts' owner decides to login and reconstruct the key. This forms the basis for our account resolver APIs. ### Migration -When an epoch comes to an end, the current node operators agree on the next epoch, and send information about the current mapping state and the existing keys to the next set of nodes in the next epoch. This is done via typical reliable broadcast methods for the mapping, and PSS \(proactive secret sharing\) for the key shares. +When an epoch comes to an end, the current node operators agree on the next epoch, and send information about the current mapping state and the existing keys to the next set of nodes in the next epoch. This is done via typical reliable broadcast methods for the mapping, and [Proactive Secret Sharing](./glossary.mdx#proactive-secret-sharing) (PSS) for the key shares. -### Trust Assumptions +### Trust assumptions -The Torus Network operates on two main threshold assumptions: a key generation threshold \(>¼\)and a key retrieval threshold \(>½\). Generating keys for new users requires more than ¾ of the nodes to be operating honestly, and reconstructing keys for existing users requires >½ of the nodes to be operating honestly. For more information, refer to the dual-threshold construction in [AVSS](https://eprint.iacr.org/2002/134.pdf). +The Torus Network operates on two main threshold assumptions: a key generation threshold \(>¼\) and a key retrieval threshold \(>½\). Generating keys for new users requires more than ¾ of the nodes to be operating honestly, and reconstructing keys for existing users requires >½ of the nodes to be operating honestly. For more information, refer to the dual-threshold construction in [Async Verifiable Secret Sharing](./glossary.mdx#distributed-key-generation) (AVSS). -While most other secret sharing schemes use ⅔ honest majority with a >⅓ reconstruction threshold, our preference for total system failure over key theft favors the former thresholds.‌ +While most other secret sharing schemes use ⅔ honest majority with a >⅓ reconstruction threshold, our preference for total system failure over key theft favors the former thresholds. -## Key Assignments +## Key assignments -The keys are assigned to a combination of `verifier` \(e.g., Google, Reddit, Discord\) and `verifier_id` \(e.g., email, username\), which is a unique identifier respective to and provided by the `verifier`.‌ This assignment can be triggered by any node and is decided through the nodes consensus layer. +The keys are assigned to a combination of `verifier` (for example, an authentication provider configuration, such as OAuth-based logins via Google) and `verifier_id` (such as, email, username), which is a unique identifier respective to and provided by the `verifier`. This assignment can be triggered by any node and is decided through the nodes consensus layer. -### Verifiers and Key Retrieval +### Verifiers and key retrieval -The fundamental flow for Torus sign-in is as follows: +The key retrieval flow for an Embedded Wallets sign-in uses the Torus Node Network as described below: ![Standard login with OAuth2 (Google, Facebook, Apple, Reddit, Discord, Twitch)](/img/tutorials/login-key-assignments.png) -1. Your application gets the user to sign-in via their preferred method \(OAuth / email password / passwordless / verification code\). -2. After the user gives consent/verifies his/her email, Torus SDK will receive an ID token and assign a key to the user depending on User Verifier ID from ID Token. -3. The key is retrieved from the Torus network and exposed to Web3 provider \(DApp\) to complete user sign-in request. -4. Torus uses this ID Token to check if the user's profile information exists in the DApp. - 1. If it does, the user will be signed in to the DApp with their preferred login. - 2. If it doesn't, the user can create a new account on the DApp with their preferred login. +1. Your application prompts the user to sign in using their preferred authentication method (for example, OAuth/OIDC). + +2. After the user successfully authenticates, the Embedded Wallets SDK (client-side) receives a verifiable authentication token. From this token, the SDK derives the user’s `verifier_id` (or retrieves it from the authentication provider’s user profile) and uses the (`verifier`, `verifier_id`) pair to identify or assign the user’s key. + +3. The SDK communicates with the Embedded Wallets network (Torus Network) to retrieve the user’s corresponding key share from the Torus network and makes it available to the application to complete the sign-in flow, without exposing the full private key. + +4. Using the authentication context, the application determines whether the user already has profile data associated with the dapp: + 1. If it does, the user is signed in. + 2. If it does not, the user can create a new account using the same login method. -In order to allow for general verifiers to be used instead of only allowing OAuth, we typically need at least two of these APIs to be implemented by the external verifier:‌ +In order to allow for general verifiers to be used instead of only allowing OAuth, we typically need at least two of these APIs to be implemented by the external verifier: -1. an API that issues unique tokens when a user is logged in. -2. an API that consumes these tokens and returns user information as well as when the token was issued. +1. An API that issues unique tokens when a user is logged in. +2. An API that consumes these tokens and returns user information as well as when the token was issued. -The first API must be accessible from the browser \(e.g. CORS-enabled, restricted headers\), in order to ensure that the Torus servers are not able to intercept the user's token \(front-running\). +The first API must be accessible from the browser (must be CORS-enabled and restrict headers), in order to ensure that the Torus servers are not able to intercept the user's token (perform front-running). -Typically any entity that fulfills these two APIs and provides signatures on unique ID strings and timestamp can be a verifier. This is extendable to several authentication schemes, including existing authentication standards like OAuth Token flow and OpenID Connect.‌ +Typically any entity that fulfills these two APIs and provides signatures on unique ID strings and timestamp can be a verifier. This is extendable to several authentication schemes, including existing authentication standards like OAuth Token flow and OpenID Connect. -## Front-Running Protection +## Front-running protection -In order to prevent a rogue node, or the Torus servers, from front-running you by taking your token, impersonating your login, and thereby stealing your key, we use a commitment scheme on our token similar to Bracha's Reliable Broadcast, to ensure that all nodes can be sure that a threshold number of other nodes are aware of the commitment, before it is finally revealed.‌ +To prevent token front-running and user impersonation by a rogue node or the Torus servers, the system uses a token commitment scheme inspired by Bracha’s Reliable Broadcast. This ensures that a token is revealed, and key shares are released, only after a threshold of nodes have acknowledged the token commitment. -The general approach is as follows: we ensure that the front-end gets access to the token first, creates a commitment to the token and a temporary public-private keypair, and reveals the token only if a threshold number of nodes accept this commitment. The nodes will then use this keypair to encrypt the shares before sending it to the user. +The general approach is as follows: the frontend obtains an authentication token, creates a commitment to the token (hashes the token), and generates a temporary public–private key pair. It sends the token commitment and temporary public key to the nodes. If nodes have not seen the token before, they acknowledge the commitment by returning a signature. -This is done by generating a temporary public-private keypair in the front-end. The front-end calls the first API and receives an authentication token. This token is hashed, and the front-end sends the token hash and the temporary public key to each node, and each node returns a signature on this message, if this is the first time they have seen this token commitment. A bundle of these signatures is the proof, and submitting the proof together with the plain \(unhashed token\) to each node results in the node responding with a key share that is encrypted with the temporary public key. +Once a threshold of acknowledgements/signatures is collected, the frontend reveals the authentication token along with the signatures. After verification, each node encrypts its key share using the temporary public key and returns it to the frontend. ### Attack 1: Front-runner intercepts the original commitment request and sends a modified public key From 13e7748b8805291154bec2a78809e548081f13ea Mon Sep 17 00:00:00 2001 From: m4sterbunny Date: Tue, 30 Dec 2025 12:19:13 +0000 Subject: [PATCH 3/3] completes first pass of review, several items wip, see inline comments --- .../_partials/_sdk-key-model-table.mdx | 14 +++++ embedded-wallets/infrastructure/README.mdx | 61 +++++++++++------- embedded-wallets/infrastructure/glossary.mdx | 3 +- .../infrastructure/mpc-architecture.mdx | 12 ++-- .../infrastructure/nodes-and-dkg.mdx | 28 +++++---- .../infrastructure/sss-architecture.mdx | 63 +++++++++++-------- ew-sidebar.js | 4 +- 7 files changed, 114 insertions(+), 71 deletions(-) create mode 100644 embedded-wallets/_partials/_sdk-key-model-table.mdx diff --git a/embedded-wallets/_partials/_sdk-key-model-table.mdx b/embedded-wallets/_partials/_sdk-key-model-table.mdx new file mode 100644 index 00000000000..026cdd623f0 --- /dev/null +++ b/embedded-wallets/_partials/_sdk-key-model-table.mdx @@ -0,0 +1,14 @@ +--- +description: Single sourced table +imported: /embedded-wallets/infrastructure/README.mdx +suggest_import1: embedded-wallets/how-it-works.mdx +suggest_import2: embedded-wallets/sdk/README.mdx +suggest_import3&4: sss-architecture.mdx and mpc-architecture.mdx +update: IF the MPC signing supports all, platforms column can go +--- + +| SDK Family | Platforms | Key Model | Available from | +| ---------- | --------- | --------- | -------------- | +| **Plug and Play Embedded Wallets SDK**
| **Web:** [React](/embedded-wallets/sdk/react), [Vue](/embedded-wallets/sdk/vue), [JavaScript](/embedded-wallets/sdk/js)
**Mobile:** [Android](/embedded-wallets/sdk/android), [iOS](/embedded-wallets/sdk/ios), [React Native](/embedded-wallets/sdk/react-native), [Flutter](/embedded-wallets/sdk/flutter)
**Gaming:** [Unity](/embedded-wallets/sdk/unity), [Unreal Engine](/embedded-wallets/sdk/unreal)
**Backend:** [Node.js](/embedded-wallets/sdk/node) | [SSS](/embedded-wallets/infrastructure/sss-architecture)
(key reconstruction) | [Base, Growth, and Scale plans](https://web3auth.io/pricing.html) | +| **MPC Core Kit SDK** | TBD are the same platforms supported? | [TSS/MPC](/embedded-wallets/infrastructure/mpc-architecture)
(no key reconstruction) | [Enterprise plan](https://web3auth.io/pricing.html) | + diff --git a/embedded-wallets/infrastructure/README.mdx b/embedded-wallets/infrastructure/README.mdx index 78d3da92c93..367098d8c7a 100644 --- a/embedded-wallets/infrastructure/README.mdx +++ b/embedded-wallets/infrastructure/README.mdx @@ -9,10 +9,11 @@ import KeyManagementDark from '@site/static/img/embedded-wallets/flow-diagrams/k import KeyManagementLight from '@site/static/img/embedded-wallets/flow-diagrams/key-management-light.png' import NodeArchitecture from '@site/static/img/embedded-wallets/infrastructure/node-architecture.png' import ShareSplitting from '@site/static/img/embedded-wallets/infrastructure/share-splitting.png' +import SDKKeyModelTable from '../_partials/_sdk-key-model-table.mdx' -Embedded Wallets infrastructure (formerly Web3Auth) is designed to make managing cryptographic wallets intuitive, reducing onboarding times, increasing conversion and improving security. It achieves this by distributing a user's private key across multiple key shares, forming a 'web of trust' that enables multi-factor account handling. The system leverages Threshold Cryptography principles or MPC(Multi-Party Computation), where a user needs a threshold of 2 out of n key shares to access their private key or generate transaction signatures. +Embedded Wallets infrastructure (formerly Web3Auth) is designed to make managing cryptographic wallets intuitive, reducing onboarding times, increasing conversion and improving security. It achieves this by distributing a user's private key across multiple key shares, forming a 'web of trust' that enables multi-factor account handling. The system leverages threshold cryptography principles or MPC (Multi-Party Computation), where a user needs a threshold of 2 out of n key shares to access their private key or generate transaction signatures. -One of the key advantages of this infrastructure is that it eliminates the need to store complete private keys anywhere, including databases, devices and participating nodes. Instead, the private key is distributed across the system in a non-custodial manner, reducing the risk of a single point of failure and preventing potential losses due to device theft or loss. +One of the primary advantages of this infrastructure is that it eliminates the need to store complete private keys anywhere, including databases, devices and participating nodes. Instead, the private key is distributed across the system in a non-custodial manner, reducing the risk of a single point of failure and preventing potential losses due to device theft or loss. The design goals of the wallet infrastructure include: @@ -22,9 +23,16 @@ The design goals of the wallet infrastructure include: ## Overview -As we proceed further into the inner workings of Embedded Wallets, it's essential to take a step back and understand the infrastructure that underpins our entire system. Before moving forward, you may want to revisit the [How it works](/embedded-wallets/how-it-works) section if you need a refresher on the product and implementations. This section provides an overview of how our wallet management infrastructure operates, diving deeper into our implementation of Shamir Secret Sharing (SSS) and Threshold Signature Scheme (TSS) based Multi-Party Computation (MPC) systems. +This section provides an overview of how our wallet management infrastructure operates, diving deeper into our implementation of [Shamir Secret Sharing](./glossary.mdx#shamir-secret-sharing) (SSS) and [Threshold Signature Scheme](./glossary.mdx#threshold-signature-schemes) (TSS) based Multi-Party Computation (MPC) systems. -Here's a video explaining our SSS based Wallet Management Infrastructure. + + +:::tip +Consider reviewing [How it Works](/embedded-wallets/how-it-works) for a refresher on the product and implementations. + +::: + +The following video explains our [SSS-based](./glossary.mdx#shamir-secret-sharing) Wallet Management Infrastructure.