Exploring Web Wallet's Architecture

Web Wallet under the hood

Darlington Nnam
Aug 10, 2023

Last week, we launched Web Wallet, a product that harnesses the power of Account Abstraction to introduce the familiar and easy-to-use web2 experience in a self-custody wallet.

We know you’ve tried out Web Wallet, and you’ve got questions about its architecture running through your mind. How and where are keys stored? How are phishing attacks mitigated? What happens if I forget my password? All these and more will be answered in the article below.

What is Web Wallet?

Web Wallet is a self-custodial wallet in your browser. It takes advantage of Account Abstraction to bring you the best aspects of web2 and web3. You create a wallet with an email address and password, eliminating all of the friction that comes with traditional blockchain wallets.

It’s important to note that your Web Wallet is an Argent account: a highly secured and audited smart contract-based account implementing the Starknet Account Abstraction interface and deployed on Starknet.

The account is secured by 2 keys: the Signer Key and Guardian Key. The security model requires both signer and guardian signatures to submit a valid transaction.

Web Wallet also comes with social recovery, giving the guardian the ability, under strict time lock conditions, to replace the signer.

Web Wallet’s Architecture

Now we understand what a Web Wallet is, let’s take a better look at some related concepts and how it works under the hood:

The Signer Key

When a user creates a new Web Wallet account, a signer key is randomly generated, encrypted by the user’s password, and securely stored in Argent’s backend.

NB: At no point, does Argent have access to an unencrypted form of the signer key (thus making it a proper self-custodial wallet).

The Guardian Key

The Guardian Key has an important role to play in account recovery which we’ll look at in the coming sections. It is generated and stored in Argent’s key service, a keys management service developed and hosted by Argent responsible for storing keys and signing transactions.

Web Wallet Authentication

The user authenticates with Argent’s backend using a passwordless authentication flow:

  • The user is asked to input his email address
  • He receives an email with a 6-digit verification code
  • If the correct verification code is inputted, the user is successfully authenticated.

Once authenticated, the user can store/retrieve his password-encrypted signer key and ask for a guardian signature.

Signing a transaction

Before signing a transaction, Web Wallet will show the user a nice transaction review screen (dApp name, tx simulation, etc). In order to sign the transaction the user needs to be authenticated with the backend to retrieve his encrypted signer key, decrypt it locally with his password, sign the transaction, and request a guardian signature from the Argent Key Service.

If the user's wallet is already funded it will further ask the user to confirm the transaction. The dApp will get feedback if the user has confirmed or rejected the transaction request. If confirmed, the dApp will get a transaction hash.

No password for 5 minutes…

With the model we implemented in Web Wallet, the user has to authenticate with the backend by decrypting his signer key every time he tries to sign a transaction, owing to the fact that we do not possess an unencrypted form of the user’s signer key. And considering Web Wallet is not one-click accessible like you have with extensions and mobile applications, we needed to come up with a solution that prevents users from inputting their password every time they needed to decrypt their signer key.

To improve this UX, we introduced a concept of short-time periods which enables the user to carry out multiple transactions in the next 5 minutes after inputting his password the first time without needing to input the password for every transaction. Each time the user inputs his password and decrypts his signer key at login or to sign a transaction, the key will be re-encrypted with an ephemeral key and stored in the Argent backend. If the user needs to sign a transaction within the 5 minutes time frame, the encrypted key will be fetched from the backend and decrypted locally with the ephemeral key.

NB: Users' keys are never stored or left resting in the browser at any time.

Web Wallet Recovery Mechanisms

After many years of refining web2 UX, users have become accustomed to the easy "forgot your password" flow. Consequently, we must develop secure mechanisms for account recovery.

Web Wallet offers two different recovery mechanisms:

1. Off-chain recovery: Pioneering the popular web2 UX, Web Wallet offers users the ability to easily recover their passwords using their email addresses. The catch here is that this action must be performed with a device (a browser actually) that was already previously authenticated. 

In order to achieve that, the signer key is re-encrypted with a device key which is stored in the browser's local storage. The encrypted key is stored in Argent’s backend. If the user can authenticate with the backend using their email, he can request this encrypted key. And if the browser is known, i.e. holds the encryption key, the user can decrypt the signer key.

We are also looking forward to integrating other alternate off-chain recovery mechanisms such as using your Argent mobile wallet.

2. On-chain recovery: As stated earlier, the catch with the off-chain recovery mechanisms is that the actions are required to be performed from a device that was already previously authenticated. But what happens in a case where the user also lost access to all previously authenticated devices? In that case, the user’s last resort becomes on-chain recovery, but how does this work?

  • A user tries to access his Web Wallet account, enters the verification code, and faces the step to enter the password.
  • The user enters an incorrect password and is shown a clickable text to perform “Recovery”.
  • The user chooses on-chain recovery, sets a new password, and is shown a confirmation screen informing them about a 7-day wait period, after which the previous signer will be escaped.
  • The user receives emails at different times during the 7-day period notifying them about the recovery action, info from the device on which the process was initiated, and a link to cancel the action. 
  • During the 7-day period, if the user tries to access Web Wallet, it will show a message with a countdown until the password is reset.
  • After 7 days, the signer will be escaped, and the user will receive a confirmation email letting them know they can now use their account.

NB: The on-chain recovery is a process at the blockchain level, where the account’s guardian is allowed to replace the account’s signer. In reality, the user will generate a new signer key and encrypt it with a new password. It will request the Argent Key Service to trigger the signer replacement by providing the new signer public key.

Common FAQs

What makes Web Wallet non-custodial?

As stated earlier, Web wallet is non-custodial because Argent never has access to the user's unencrypted signer key.

Is Web Wallet censorship resistant?

Today, Web Wallet is not exactly censorship resistant because if the Argent backend is not available, the user can’t access his keys and can’t submit transactions. We are working on solutions to make it censorship resistant. The obvious one which will be available with upcoming updates, is the ability to export the signer key from the web wallet interface. Another solution could be to allow advanced users to add a guardian backup at the smart account contract level. This is already implemented within the account contract so we just need to update the UI to support it too.

What happens if a user tries to sign a transaction with an undeployed Wallet?

If the user has funded their wallet, they are ready for their first transaction. The wallet deployment will be done along the first transaction and is almost invisible to the user. Just note that a connected wallet may not be deployed yet.

What happens if a user is trying to sign a transaction with an unfunded Wallet?

In a case where the user has no funds, the user is guided through the “Add funds” screens where they can go to on-ramps and more. We tried to make the funding process of new wallets as easy as possible with regard to KYC. Once this process is completed, the user's wallet will be funded and now ready to be deployed.

Can I recover my account if I lose access to my Email?

At the moment, No, as there would be no means to verify the user’s ownership. 


Hopefully, you now have a better understanding of Web Wallet.

We are constantly iterating on Web Wallet to ensure we give you a secure, safe, and easy-to-use user experience with self-custody wallets, and as such definitely open to feedback and constructive criticisms.

If you have any questions regarding this, reach out to me @0xdarlington, I’d love to help you build on Starknet with Argent.

For more developer resources, follow us across our socials:

Argent Twitter — @argentHq

Argent Engineering Twitter — @argentDeveloper

LinkedIn — @argentHq

Youtube — @argentHQ

Own It

We use 🍪 cookies to personalise your experience on Argent. Privacy Policy


HQ London, made with ❤️ across Europe