# NEAR Proposal Final - Draft

For Web3Auth integration in the NEAR wallet adapter, we originally devised five potential flows and, the NEAR team handpicked one out of them. This document is a detailed overview of that flow.

## High-level Overview

We aim to modify wallet-selector SDK so that the users can create an implicit account on their preferred wallet without writing down the seed phrase. Users can reconstruct their keys via social login and access on any compatible NEAR wallet (web/extension/native). The entry point to wallet-selector UI will always be a DApp, and once connected, DApps can directly invoke the wallet application to approve transactions.

### Definition
**Dapp** - Decentralise Near Application with wallet-selector.
**Wallet-Selector** - SDK that powers the UX flow in DApp.
**Wallet** - Web wallet or App wallet.
**Web3Auth** - Web3Auth site that reconstructs private key.
**Broadcast Server** - Server that relays the message on the respective channel

### Abbreviations

**FCK** - Function call key(Key with limited access assigned to DApps with a preset allowance).
**FAK** - Full Access Key(A key with full access assigned to Wallets).
**SDK** - Standard development kit.

## Wallet-Selector

NEAR already has a wallet selector node SDK available for DApps to integrate; right now, it is only responsible for wallet discovery. At present, it supports the below-listed wallets :
- NEAR Wallet - Browser wallet.
- My NEAR Wallet - Browser wallet.
- Sender - Injected wallet.
- Math Wallet - Injected wallet.
- Nightly - Injected wallet.
- Meteor Wallet - Injected wallet.
- Welldone Wallet - Injected wallet.
- Coin98 Wallet - Injected wallet.
- Neth - Injected wallet.
- Ledger - Hardware wallet.
- WalletConnect - Bridge wallet.
- Nightly Connect - Bridge wallet.
- Here Wallet - Mobile wallet.
- NearFi Wallet - Mobile wallet.
- Opto Wallet - Mobile wallet & Browser wallet.

### Specification for Wallet-Selector

Functions:
- Control the end-to-end UX.
- Initialize Wallet-selector.web3auth.io context with details like login provider, wallet details, connection details, etc.
- Discover and list all supported wallets (This can be crowdsourced).
- List social login providers.
- Facilitate DApp to wallet connection.

Limitations:
- Wallet-selector cannot handle key management.
- Agnostic about wallet priority.

## Signup Flow


### Extension: DApp to wallet connection


1. User clicks connect button on DApp page.
2. Wallet selector window opens up and user select social provider and wallet app from list.
3. SDK generates a random sessionID for connection and proceed to next step.
4. Request to generate FCK is attached to the connection
5. (Optional) DApp generates a connection URL if a native wallet is selected.
6. Connection is established

## Web3Auth Site

Once the user selects the social provider and the wallet, Wallet-selector will redirect the user to the Web3Auth site. Web3Auth site is fully responsible for the key generation and management.

### Specification

Functions:
- Manage and secure the implicit account’s private key with web3auth.
- Manage Full Access Keys (wallet) on implicit account
- Communicate with wallet.
- Dapp could have a separate client-id (different account for same OAuth login) capability.

Limitations:
- Signing transactions (except adding or removing FAK)

Assumptions:
- Wallets are trusted entities. They have full access to account.
- Needs a NEAR funding source.

## Key Deliverables

### Wallet-Selector
- Updated and stable wallet-selector-SDK for DApps in browser.
- Wallet selector can list wallets and do wallet discovery in user’s device.
- Documentation for DApps developers to integrate the wallet-selector.
- Documentation for wallets to attain compatibility with wallet-selector.
- A reference implementation sample for DApps.
- A reference implementation sample for Wallets.
- Update near provider to invoke injected wallets.

<!-- - Api for redirect to web3auth with dapp details -->
### Web3Auth Site
- Inject Full Access Key to the Wallet
- Send dapp's details and account ID to Wallet. This step is dependant on where the wallet context live
- Web + Mobile
- send dapp details via bridging server or qrcode
- Web + Web
- send dapp details via redirect flow
- Web + Chrome Extension
- send dapp details via `near provider`
- get public key via `near provider` and add it as FAK

<br/>

### Multichain Wallet App (Edge Case)

#### Problem statement
Wallets which support multiple chains would like to keep that functionality intact when integrating the new `@web3auth/near-provider` SDK. There could be a discrepency with the existing web3auth SDK which can also be used directly (Check appendix for legacy flow).

#### Strategy
Below are some proposal strategy for multichain wallet app :

- Suggested: ***Wallet will use the FAK to generate keys for other chains***
- Web3auth will return 2 keys. One is FAK for interacting with Near and another secp256k1 key for other chains.

## Appendix

### Bridging Server
Server can relay messages in respective channels

<!--  -->

1) ECDH connection can be establised between web3auth and the wallet.
2) Wallet in scan the web3auth epmeral public key (g.a).
3) Wallet is will derive g.a.b.
4) Wallet will post a message (connections request and g.b) for g.a.
5) Web3auth will send the implicit key on g.b.a.

<br/>

### Explorations for Step 7, 8 in Sign In Flow
To asign new wallet to implict account we have options below

- Default
- Web3auth generates a unique ID and pass the ID to wallet via new browser window's query param / qrcode or etc.
- Wallet generates private key pair
- Wallet post send public key, wallet name, wallet/app url via bridging server
- Web3auth got the request and add public key as FAK of the implicit account
- Return( or redirect) to dapp with the wallet details

- Pass Private Key via ECDH / Qrcode
- Web3auth generates a unique ID and pass the link to wallet via new browser window's query param / qrcode or etc.
- Wallet generates private key pair
- Setup ECDH between wallet and web3auth
- Web3auth generates key-pair
- Web3auth add private-key as Full Access Key
- Web3auth send private-key to wallet via ECDH (encrypted)
- Return to dapp with the wallet details

<br/>

### Sign Transaction Flow
- Sign Transaction is redirect to respected wallet
- For app wallet, deeplink or web with qrcode (bridging server is an option like wallet connect)

<br/>

### Legacy Signup
The flow below changes the entry point from DApp and wallet selector and move it to wallets. Here the user installs the wallet application and generates the key with Web3Auth from wallet's UI.
<!--  -->

<!--  -->

<br/>

Flow :
1) Redirect to Web3Auth
2) Complete Oauth
4) Open Broadcast Channel with generated `unique id`
5) Open new window to wallet site with `unique id` -or- show qrcode of `unique id` for app wallet to scan
6) Open Broadcast Channel with `unique id`
7) Send public key to web3auth via broadcast channel
8) Send Account Id and wallet details

<br />

### Wallet integration spec
Wallet responsible to generate key pair and send the public key to the
bridging server endpoint
- redirect flow params
- `query params` - `?web3auth_channel=<channel id>&account_id=<account_id>&<dapp forwarded data>`
- qrcode scan
- `data` - `?web3auth_channel=<channel id>&account_id=<account_id>&<dapp forwarded data>`

### Bridge Server API Spec
- POST `/channel/<unique-id>/register`
body :
- publicKey - string (hex)

<br/>

Description : API to register public key from wallet as Full Access Key on new Wallet flow.

- GET `/channel/<unique-id>/transaction`

Description: poll api to get pending `transaction`

- POST `/channel/<unique-id>/hash`
Body:
- hash - string

Description : Send transaction hash to web3auth which will redirect back to dapp ( for native app flow )

- POST `/channel/<unique-id>/ssr`
Description: subscribe to ssr or websocket