Topics on accounts and wallets (#497)

* First draft of topics on accounts and wallets

* From the user's perspective

Co-authored-by: Germán Delbianco <[email protected]>

* key pairs

Co-authored-by: Germán Delbianco <[email protected]>

* on the test network

Co-authored-by: Germán Delbianco <[email protected]>

* kinds of tokens

Co-authored-by: Germán Delbianco <[email protected]>

* Style

* MetaMask supports Tezos

* depending on the cryptographic method used to create them

* is most likely a scam

Co-authored-by: Germán Delbianco <[email protected]>

* private key or secret key

Co-authored-by: Germán Delbianco <[email protected]>

* Also known as

* Recovery information

* Remove mention of time

* Airgap

* Clarify recovery info

* unique identifier on the blockchain

Co-authored-by: NicNomadic <[email protected]>

* Link to local accounts page

* Most wallets

Co-authored-by: NicNomadic <[email protected]>

* Change and to or

* Reuse page on popular wallets in these pages

* Fix link

* Semicolon should be colon

Co-authored-by: NicNomadic <[email protected]>

* Use staking app as example of dApp

* Connect wallets to tokens

* Reword introduction

---------

Co-authored-by: Germán Delbianco <[email protected]>
Co-authored-by: NicNomadic <[email protected]>

docs/conrefs/popular-wallets.md

@@ -0,0 +1,10 @@
+These are some wallets that you can use with Tezos:
+
+- [Temple](https://templewallet.com/) mobile application and browser extension
+- [Umami](https://umamiwallet.com/) standalone application for Windows, MacOS, and Linux
+- [Kukai](https://wallet.kukai.app/) federated identity application, which uses accounts linked to other accounts such as email or social media accounts
+- [Trust](https://trustwallet.com/tezos-wallet) mobile application and browser extension
+- [Airgap](https://airgap.it/) standalone and mobile applications
+- [Ledger](https://www.ledger.com/) hardware wallets
+
+The [MetaMask wallet](https://metamask.io/) supports Tezos, but only its browser extension, and only on Mainnet.

docs/developing/wallet-setup.md

@@ -2,23 +2,20 @@
 title: Installing and funding a wallet
 authors: Tim McMackin
 last_update:
-  date: 13 February 2024
+  date: 3 January 2025
 ---
 
+import PopularWallets from '@site/docs/conrefs/popular-wallets.md';
+
 To work with Tezos, you need a wallet, which is an application that maintains your accounts and signs Tezos transactions on your behalf.
 Wallets allow you to interact with dApps without exposing your account's private key.
 
 ## Choosing a wallet
 
-Which wallet you install is up to you and whether you want to install a wallet on your computer, in a browser extension, or as a mobile app.
-
-Mobile apps include [Temple](https://templewallet.com/), [Kukai](https://wallet.kukai.app/), and [Umami](https://umamiwallet.com/).
+Which wallet you install is up to you and whether you want to install a wallet on your computer, in a browser extension, as a mobile app, or as a piece of hardware.
 
-Browser extensions include the [Temple](https://templewallet.com/) browser extension.
+<PopularWallets />
 
-Desktop wallets for Tezos include [Kukai](https://wallet.kukai.app/) and [Umami](https://umamiwallet.com/).
-
-Tezos also supports the [MetaMask wallet](https://metamask.io/), but only its browser extension, and only on Mainnet.
 Follow these steps to enable Tezos in MetaMask:
 
 1. Install the MetaMask browser extension.
@@ -32,6 +29,8 @@ The page sends you to https://metamask.tezos.com to approve and manage the conne
 
 For more information about using MetaMask with Tezos, see [MetaMask Now Supports Tezos: An Explainer](https://spotlight.tezos.com/metamask-now-supports-tezos-an-explainer/).
 
+For a full list of Tezos wallets, see https://tezos.com/learn/store-and-use.
+
 ## Switching the wallet to a testnet
 
 If you're doing development work, you're probably using a testnet instead of Mainnet.

docs/using/staking.md

@@ -54,7 +54,8 @@ As with all decentralized applications, do not trust unknown sites asking you to
 
 :::
 
-1. Make sure you have tez tokens in a supported Tezos wallet, such as [Kukai](https://wallet.kukai.app/), [Temple](https://templewallet.com/), [Trust Wallet](https://trustwallet.com/), or [Umami Wallet](https://umamiwallet.com/).
+1. Make sure you have tez tokens in a supported Tezos wallet.
+For a list of popular wallets, see [Wallets](/using/wallets).
 
 1. Go to https://stake.tezos.com in a web browser.
 

docs/using/user-accounts.md

@@ -0,0 +1,81 @@
+---
+title: Accounts
+authors: "Tim McMackin"
+last_update:
+  date: 3 January 2025
+---
+
+From the user's perspective, a Tezos account is much like an account that you might have on a web application or computer system.
+You can use a Tezos account to do many things, including:
+
+- Store and work with tez, the native currency token of the Tezos system
+- Store and work with other [tokens](/architecture/tokens)
+- Uniquely identify yourself to online applications
+- Send transactions to Tezos, such as sending tokens to another account or calling a [smart contract](/smart-contracts)
+- Sign messages to prove that they came from your account
+
+From a technical standpoint, a Tezos account is a unique identifier on the blockchain that allows a user to encrypt transactions in a way that proves that those transactions came from them.
+In this way, using a Tezos account is how you prove your identity to the Tezos system and to applications that use Tezos.
+
+This page discusses user accounts.
+As described in [Accounts](/architecture/accounts), other types of Tezos accounts include [smart contracts](/smart-contracts) and [Smart Rollups](/architecture/smart-rollups).
+For technical information on user accounts, see [Accounts and addresses](https://tezos.gitlab.io/active/accounts.html) in the Octez documentation.
+
+Tezos users use wallets to manage their accounts; see [Wallets](/using/wallets).
+
+## Account addresses
+
+A Tezos account address uniquely identifies an account.
+Most Tezos user account addresses start with `tz1`, as in `tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx`, but they can also start with `tz2`, `tz3`, or `tz4`, depending on the cryptographic method used to create them.
+They consist of 26 characters and include only letters and numbers.
+
+:::note
+
+Tezos account addresses are case-sensitive.
+
+:::
+
+Technically, what users refer to as the "account address" is the hash of the public key of the account.
+
+## Public and private keys
+
+Cryptocurrency accounts rely on key pairs like other computer accounts rely on passwords.
+The keys secure the account and allow only the account owner to use the account.
+
+Keys come in pairs:
+
+- The account's **private key** allows a user to encrypt, or "sign," messages and transactions.
+- The account's **public key** allows Tezos and other users to verify that a message or transaction was signed by the account's private key.
+
+User generally don't deal with these keys directly.
+In most cases, their wallet application stores the keys and protects them with a password.
+
+## Account security
+
+:::warning
+
+You must keep your private key secret.
+
+The private key (also known as the secret key) is the only thing that another user needs to impersonate your account on Tezos and send transactions on your behalf.
+If another user gets your private key, they can access your account and send its tez and other tokens to another account.
+If your wallet provides a recovery phrase, you must keep it secret too, because malicious users can use it to recreate your private key.
+
+:::
+
+To keep their private keys safe, users use [wallets](/using/wallets), which are applications that store private keys and use them to sign transactions on your behalf.
+
+Of course the wallet application may also require a password, and therefore you must also keep this password secret.
+Many wallet applications provide a way to recover the account if you lose the wallet application or the device that it is on.
+Some wallets provide recovery codes in the form of a series of words, others recreate accounts from private keys, and others have proprietary recovery methods.
+You must also keep this recovery information secret.
+
+Malicious users and apps may try to get your private key, wallet password, or recovery information.
+For example, spam email and malicious apps may request this information or tell you that you need to "verify it" by entering it.
+
+The only time that you need to give anyone your private key or recovery information is when you set up or restore an account in a legitimate wallet application.
+Any other request for this information is most likely a scam.
+
+## Creating accounts
+
+Any wallet application can create, manage, and help you back up Tezos accounts.
+See [Wallets](/using/wallets).

docs/using/wallets.md

@@ -0,0 +1,77 @@
+---
+title: Wallets
+authors: "Tim McMackin"
+last_update:
+  date: 3 January 2025
+---
+
+import PopularWallets from '@site/docs/conrefs/popular-wallets.md';
+
+Wallets are tools that manage accounts on blockchains like Tezos.
+[Accounts](/using/user-accounts) hold and use tokens such as tez, the native token of Tezos.
+The primary purpose of wallets is to store an account's private key securely and encrypt (or "sign") transactions with that key without exposing the key.
+
+Most wallets can do other tasks, including:
+
+- Showing the token balances that an account holds, such as cryptocurrencies (DeFi tokens) and non-fungible tokens (NFTs)
+- Providing information on the value of tokens
+- Buying, selling, and exchanging tokens
+- Showing the transaction history of an account
+- Batching multiple transactions to save on transaction fees
+
+## Tezos wallets
+
+Many wallets are compatible with Tezos.
+They are available as standalone programs, as mobile applications, as web browser extensions, as online federated identity accounts, or as pieces of hardware.
+Which one you use depends on what platform you want to use your wallet on and what features you want.
+
+<PopularWallets />
+
+To set up MetaMask for Tezos, see [Choosing a wallet](/developing/wallet-setup#choosing-a-wallet).
+
+For a full list of Tezos wallets, see https://tezos.com/learn/store-and-use.
+For more information about using wallets with Tezos, see [Installing and funding a wallet](/developing/wallet-setup).
+
+## Setting up a wallet
+
+Each wallet application works differently, but in most cases setting up a wallet follows these general steps:
+
+1. You download and install the wallet application or browser extension.
+1. The wallet prompts you to set a password.
+1. The wallet generates a Tezos account.
+1. The wallet gives you a backup code, usually a series of words, which you can use to restore the account if there is a problem with the wallet or the hardware that runs it.
+1. The wallet shows the address of the new account.
+Most wallets can generate multiple accounts if you need more than one.
+
+Now you can use the wallet to work with tokens and dApps.
+
+## Transferring tokens
+
+Most wallets allow you to transfer tokens directly in the wallet application.
+In most cases, all you need to do is click **Send**, select the token and amount to send, and enter the address of the target account.
+
+For example, this is what a simple transfer of 10 tez looks like in the Temple wallet mobile application:
+
+<img src="/img/using/wallets-temple-transfer.png" alt="Transferring tez in Temple wallet" style={{width: 300}} />
+
+## Connecting a wallet to an application
+
+You can work within the wallet itself to see your tokens and account history.
+You can also use it to make transactions, including sending tokens to other accounts.
+
+Another primary use of a wallet is to connect to and use decentralized applications (dApps).
+These applications typically provide a web application user interface and use Tezos for background tasks such as user authentication, data storage, and payment processing.
+You must connect your wallet to the application, like logging in to a web site, before it can access your account information.
+Then, when the application wants to send a transaction to Tezos on your behalf, it sends the transaction to your wallet application for you to approve.
+If you approve the transaction, the wallet signs it with your private key and submits it to Tezos.
+
+For an example of a dApp and how you interact with it in your wallet, see [Staking](/using/staking).
+
+After you approve the transaction, you can see it in your wallet's history.
+
+:::warning
+
+Examine transactions thoroughly before approving them.
+Malicious dApps may send misleading transactions, and transactions cannot be reversed after you sign them.
+
+:::

sidebars.js

@@ -22,8 +22,8 @@ const sidebars = {
       //   type: 'doc',
       // },
       items: [
-        // 'using/user-accounts',
-        // 'using/wallets',
+        'using/user-accounts',
+        'using/wallets',
         // 'using/dapps',
         // 'using/transactions',
         'using/staking',