Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes for typos and minor formatting improvements across the repository #29

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fixes for typos and minor formatting improvements across the repository #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e0f51d
Fix typos in key-generation.md
Miska05 Dec 25, 2024
cbd888b
Fix typos and improve clarity in wallet-connect.md
Miska05 Dec 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/key-generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ An account is created adding in the Spending Private Key and registering an Alia

In order to store the keys securely so they can be used by the wallet to decrypt data and sign transactions, we use the browsers password manager. This can either be the browsers built in password manager or a third party like 1Passsword.

Most password managers store passwords encrypted, however for additional security we further encrypt the password with a symetric encryption key derived from the users password and a random salt.
Most password managers store passwords encrypted, however for additional security we further encrypt the password with a symmetric encryption key derived from the users password and a random salt.

### Step 1. Derive an encryption key.

Expand All @@ -57,7 +57,7 @@ Password Manager Entry = concact(Cipher, Random Salt)

## Account recovery

To ensure the user can still access their account under the above assumptions, a recovery kit is required. This kit contains infromation needed to recover the Account Private Key and regain spending access on the account.
To ensure the user can still access their account under the above assumptions, a recovery kit is required. This kit contains information needed to recover the Account Private Key and regain spending access on the account.

## Recovering the Spending Private Key

Expand Down Expand Up @@ -117,7 +117,7 @@ Important this information can be used to recover you Aztec Account.

## Scenarios

### Lost device / no access to password manager / can’t remeber user password.
### Lost device / no access to password manager / can’t remember user password.

Here the user must posses their recovery kit and have access to their Ethereum Private Key. If they posses this, they can do the following.

Expand All @@ -140,10 +140,10 @@ It may be worth considering encrypting the Spending `Private Key` and `Account P

Without the `Recovery Kit`, the attacker can’t use this in any attack. However there is a phising attack here that the attacker could trick the user into “recovering” on an insecure website.

To combat this, the recovery kit should explictly detail the correct URL to recover via e.g `wallet.aztec.network/recovery`.
To combat this, the recovery kit should explicitly detail the correct URL to recover via e.g `wallet.aztec.network/recovery`.

### User loses access to their Ethereum Private Key.

If the user does not have access to their Ethereum Private Key, their recovery kit is usless. The UI can encourage them to periodical prove they have access to this key to mitigate against this. Should they fail that test, a new recovery kit can be generated.
If the user does not have access to their Ethereum Private Key, their recovery kit is useless. The UI can encourage them to periodical prove they have access to this key to mitigate against this. Should they fail that test, a new recovery kit can be generated.

So long as an attacker does not have access to the `Old Ethereum Private Key` this should be secure. If their is a chance an attacker has access to the `Old Ethereum Private Key` and the old recovery kit can’t be guranteed to be destroyed, security concious users should migrate to a new account.
So long as an attacker does not have access to the `Old Ethereum Private Key` this should be secure. If their is a chance an attacker has access to the `Old Ethereum Private Key` and the old recovery kit can’t be guranteed to be destroyed, security conscious users should migrate to a new account.
22 changes: 11 additions & 11 deletions docs/wallet-connect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## The objective

We want to create a walletconnect compatible web wallet that allows the dapps to, once a session is established, to create an iframe of the web wallet to have a long running instance of the wallet.
We want to create a walletconnect compatible web wallet that allows the dApps to, once a session is established, to create an iframe of the web wallet to have a long running instance of the wallet.

It's necessary to handover the walletconnect connection from the fully-fledged website wallet to the newly created iframe specifically for that dapp.
It's necessary to handover the walletconnect connection from the fully-fledged website wallet to the newly created iframe specifically for that dApp.

## But what's exactly a session?

Expand All @@ -26,7 +26,7 @@ When a walletconnect instance is initiated, all the controllers are created and

This causes that a new instance of a website that uses walletconnect is going to take ownership of all sessions and pairings, since its subscription module will subscribe to all these topics.

This can be problematic for our objective, since we want the iframed instances of the wallet to take hold of the connection with the specific dapp only.
This can be problematic for our objective, since we want the iframed instances of the wallet to take hold of the connection with the specific dApp only.

## A solution

Expand All @@ -39,19 +39,19 @@ We also need to avoid the iframe getting visibility of the pairings/sessions/sub

### Pairing establishment

When the dapp considers that a session needs to be established, it will create a new SignClient, get a pairing uri and open Web3Modal with the Uri. The Aztec wallet will be present in the list and on click by the user, a new tab/window for the wallet will be opened with the uri as param.
When the dApp considers that a session needs to be established, it will create a new SignClient, get a pairing uri and open Web3Modal with the Uri. The Aztec wallet will be present in the list and on click by the user, a new tab/window for the wallet will be opened with the uri as param.

The wallet tab will open and detect that is running in standalone (non-iframe) mode. It'll create a regular SignClient with real localStorage and accept the pairing using the URI passed as parameter. A new session will be created and persisted. Here is when all the wallet-specific checks (the keystore for the account is opened, user accepts the connection) happen.

The response of the pairing creation will include metadata that signals that the wallet is iframable. Due to anti tracking features of multiple browsers, direct connection between the standalone instance and an iframe is not possible. This standalone instance can be closed.

### Iframe creation and handover via popup

When the dapp receives the response to the pairing/session from the SignClient, the metadata will inform it that the wallet is iframable and will contain the url of the wallet. The dapp will then open an iframe for the aztec wallet, passing the session topic.
When the dApp receives the response to the pairing/session from the SignClient, the metadata will inform it that the wallet is iframable and will contain the url of the wallet. The dApp will then open an iframe for the aztec wallet, passing the session topic.

The wallet will recognize itself as running in an iframe and will find no active wc session for that topic in its storage, so it will request the parent dapp to become visible to show a "Connect" button.
The wallet will recognize itself as running in an iframe and will find no active wc session for that topic in its storage, so it will request the parent dApp to become visible to show a "Connect" button.

When the connect button is clicked, the iframe will open a popup instance of the wallet via window.open(). This newly created instance of the wallet will be able to access unpartitioned local storage and is able to send it back to the iframe via `window.parent.postMessage`.
When the connect button is clicked, the iframe will open a popup instance of the wallet via window.open(). This newly created instance of the wallet will be able to access non-partitioned local storage and is able to send it back to the iframe via `window.parent.postMessage`.

The popup instance of the wallet will receive the message and will find the session created for that topic. It will send the iframe over BroadcastChannel all the data necessary to recreate the session on the iframe side:

Expand All @@ -67,7 +67,7 @@ The iframe wallet will receive the session data and:
- Add the session data structure to the client
- Subscribe to the session topic to start receiving messages

With this steps, the connection handover is complete. The iframe will start receiving all the messages of the session topic and only that session topic.
With these steps, the connection handover is complete. The iframe will start receiving all the messages of the session topic and only that session topic.

### Implementation

Expand All @@ -77,7 +77,7 @@ The wallet needs to implement the following features for iframable walletconnect

- Should be openable in the /wc path for [walletconnect universal linking](https://github.com/WalletConnect/web3modal/blob/V2/packages/core/src/utils/CoreUtil.ts#L60)
- Will have the WC uri as query parameter
- Should accept/deny the session request providing a list of method, events and addresses for the session
- Should accept/deny the session request providing a list of methods, events and addresses for the session
- Should signal in the metadata that can be run in an iframe
- Should be openable in popup mode (window.opener is the iframe)
- Should hand over the encrypted keystore and password to the opener (same origin)
Expand All @@ -86,11 +86,11 @@ The wallet needs to implement the following features for iframable walletconnect
- It should read the session topic from query params
- Should have a visible button to trigger the popup
- Should we use a protocol with the app to open/close the iframe viewport?
- Should receive the keystore and the session from the popup and start handling the dapp requests
- Should receive the keystore and the session from the popup and start handling the dApp requests
- Should try to remember the session details in localstorage
- Should it also try to remember the keystore? that way the popup click wouldn't be necessary on every tab / page refresh

The dapp only needs to add, on session creation or when reusing a cached session, code to open an iframe to the wallet if the metadata says it's iframable:
The dApp only needs to add, on session creation or when reusing a cached session, code to open an iframe to the wallet if the metadata says it's iframable:

```typescript
const {
Expand Down