solana-docs 0.0.0

package/src/validator/gossip.md

@@ -0,0 +1,90 @@
+---
+title: Gossip Service
+---
+
+The Gossip Service acts as a gateway to nodes in the [control plane](terminology.md#control-plane). Validators use the service to ensure information is available to all other nodes in a cluster. The service broadcasts information using a [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol).
+
+## Gossip Overview
+
+Nodes continuously share signed data objects among themselves in order to manage a cluster. For example, they share their contact information, ledger height, and votes.
+
+Every tenth of a second, each node sends a "push" message and/or a "pull" message. Push and pull messages may elicit responses, and push messages may be forwarded on to others in the cluster.
+
+Gossip runs on a well-known UDP/IP port or a port in a well-known range. Once a cluster is bootstrapped, nodes advertise to each other where to find their gossip endpoint (a socket address).
+
+## Gossip Records
+
+Records shared over gossip are arbitrary, but signed and versioned (with a timestamp) as needed to make sense to the node receiving them. If a node receives two records from the same source, it updates its own copy with the record with the most recent timestamp.
+
+## Gossip Service Interface
+
+### Push Message
+
+A node sends a push message to tells the cluster it has information to share. Nodes send push messages to `PUSH_FANOUT` push peers.
+
+Upon receiving a push message, a node examines the message for:
+
+1. Duplication: if the message has been seen before, the node drops the message and may respond with `PushMessagePrune` if forwarded from a low staked node
+2. New data: if the message is new to the node
+
+   - Stores the new information with an updated version in its cluster info and purges any previous older value
+
+   - Stores the message in `pushed_once` (used for detecting duplicates, purged after `PUSH_MSG_TIMEOUT * 5` ms)
+
+   - Retransmits the messages to its own push peers
+
+3. Expiration: nodes drop push messages that are older than `PUSH_MSG_TIMEOUT`
+
+### Push Peers, Prune Message
+
+A nodes selects its push peers at random from the active set of known peers. The node keeps this selection for a relatively long time. When a prune message is received, the node drops the push peer that sent the prune. Prune is an indication that there is another, higher stake weighted path to that node than direct push.
+
+The set of push peers is kept fresh by rotating a new node into the set every `PUSH_MSG_TIMEOUT/2` milliseconds.
+
+### Pull Message
+
+A node sends a pull message to ask the cluster if there is any new information. A pull message is sent to a single peer at random and comprises a Bloom filter that represents things it already has. A node receiving a pull message iterates over its values and constructs a pull response of things that miss the filter and would fit in a message.
+
+A node constructs the pull Bloom filter by iterating over current values and recently purged values.
+
+A node handles items in a pull response the same way it handles new data in a push message.
+
+## Purging
+
+Nodes retain prior versions of values (those updated by a pull or push) and expired values (those older than `GOSSIP_PULL_CRDS_TIMEOUT_MS`) in `purged_values` (things I recently had). Nodes purge `purged_values` that are older than `5 * GOSSIP_PULL_CRDS_TIMEOUT_MS`.
+
+## Eclipse Attacks
+
+An eclipse attack is an attempt to take over the set of node connections with adversarial endpoints.
+
+This is relevant to our implementation in the following ways.
+
+- Pull messages select a random node from the network. An eclipse attack on _pull_ would require an attacker to influence the random selection in such a way that only adversarial nodes are selected for pull.
+- Push messages maintain an active set of nodes and select a random fanout for every push message. An eclipse attack on _push_ would influence the active set selection, or the random fanout selection.
+
+### Time and Stake based weights
+
+Weights are calculated based on `time since last picked` and the `natural log` of the `stake weight`.
+
+Taking the `ln` of the stake weight allows giving all nodes a fairer chance of network coverage in a reasonable amount of time. It helps normalize the large possible `stake weight` differences between nodes. This way a node with low `stake weight`, compared to a node with large `stake weight` will only have to wait a few multiples of ln(`stake`) seconds before it gets picked.
+
+There is no way for an adversary to influence these parameters.
+
+### Pull Message
+
+A node is selected as a pull target based on the weights described above.
+
+### Push Message
+
+A prune message can only remove an adversary from a potential connection.
+
+Just like _pull message_, nodes are selected into the active set based on weights.
+
+## Notable differences from PlumTree
+
+The active push protocol described here is based on
+[Plum Tree](https://haslab.uminho.pt/sites/default/files/jop/files/lpr07a.pdf).
+The main differences are:
+
+- Push messages have a wallclock that is signed by the originator. Once the wallclock expires the message is dropped. A hop limit is difficult to implement in an adversarial setting.
+- Lazy Push is not implemented because its not obvious how to prevent an adversary from forging the message fingerprint. A naive approach would allow an adversary to be prioritized for pull based on their input.

package/src/validator/runtime.md

@@ -0,0 +1,69 @@
+---
+title: The Runtime
+---
+
+## The Runtime
+
+The runtime is a concurrent transaction processor. Transactions specify their data dependencies upfront and dynamic memory allocation is explicit. By separating program code from the state it operates on, the runtime is able to choreograph concurrent access. Transactions accessing only read-only accounts are executed in parallel whereas transactions accessing writable accounts are serialized. The runtime interacts with the program through an entrypoint with a well-defined interface. The data stored in an account is an opaque type, an array of bytes. The program has full control over its contents.
+
+The transaction structure specifies a list of public keys and signatures for those keys and a sequential list of instructions that will operate over the states associated with the account keys. For the transaction to be committed all the instructions must execute successfully; if any abort the whole transaction fails to commit.
+
+#### Account Structure
+
+Accounts maintain a lamport balance and program-specific memory.
+
+## Transaction Engine
+
+The engine maps public keys to accounts and routes them to the program's entrypoint.
+
+### Execution
+
+Transactions are batched and processed in a pipeline. The TPU and TVU follow a slightly different path. The TPU runtime ensures that PoH record occurs before memory is committed.
+
+The TVU runtime ensures that PoH verification occurs before the runtime processes any transactions.
+
+![Runtime pipeline](/img/runtime.svg)
+
+At the _execute_ stage, the loaded accounts have no data dependencies, so all the programs can be executed in parallel.
+
+The runtime enforces the following rules:
+
+1. Only the _owner_ program may modify the contents of an account. This means that upon assignment data vector is guaranteed to be zero.
+2. Total balances on all the accounts is equal before and after execution of a transaction.
+3. After the transaction is executed, balances of read-only accounts must be equal to the balances before the transaction.
+4. All instructions in the transaction executed atomically. If one fails, all account modifications are discarded.
+
+Execution of the program involves mapping the program's public key to an entrypoint which takes a pointer to the transaction, and an array of loaded accounts.
+
+### SystemProgram Interface
+
+The interface is best described by the `Instruction::data` that the user encodes.
+
+- `CreateAccount` - This allows the user to create an account with an allocated data array and assign it to a Program.
+- `CreateAccountWithSeed` - Same as `CreateAccount`, but the new account's address is derived from
+  - the funding account's pubkey,
+  - a mnemonic string (seed), and
+  - the pubkey of the Program
+- `Assign` - Allows the user to assign an existing account to a program.
+- `Transfer` - Transfers lamports between accounts.
+
+### Program State Security
+
+For blockchain to function correctly, the program code must be resilient to user inputs. That is why in this design the program specific code is the only code that can change the state of the data byte array in the Accounts that are assigned to it. It is also the reason why `Assign` or `CreateAccount` must zero out the data. Otherwise there would be no possible way for the program to distinguish the recently assigned account data from a natively generated state transition without some additional metadata from the runtime to indicate that this memory is assigned instead of natively generated.
+
+To pass messages between programs, the receiving program must accept the message and copy the state over. But in practice a copy isn't needed and is undesirable. The receiving program can read the state belonging to other Accounts without copying it, and during the read it has a guarantee of the sender program's state.
+
+### Notes
+
+- There is no dynamic memory allocation. Client's need to use `CreateAccount` instructions to create memory before passing it to another program. This instruction can be composed into a single transaction with the call to the program itself.
+- `CreateAccount` and `Assign` guarantee that when account is assigned to the program, the Account's data is zero initialized.
+- Transactions that assign an account to a program or allocate space must be signed by the Account address' private key unless the Account is being created by `CreateAccountWithSeed`, in which case there is no corresponding private key for the account's address/pubkey.
+- Once assigned to program an Account cannot be reassigned.
+- Runtime guarantees that a program's code is the only code that can modify Account data that the Account is assigned to.
+- Runtime guarantees that the program can only spend lamports that are in accounts that are assigned to it.
+- Runtime guarantees the balances belonging to accounts are balanced before and after the transaction.
+- Runtime guarantees that instructions all executed successfully when a transaction is committed.
+
+## Future Work
+
+- [Continuations and Signals for long running Transactions](https://github.com/solana-labs/solana/issues/1485)

package/src/validator/tpu.md

@@ -0,0 +1,5 @@
+---
+title: TPU
+---
+
+![TPU Block Diagram](/img/tpu.svg)

package/src/validator/tvu.md

@@ -0,0 +1,9 @@
+---
+title: TVU
+---
+
+![TVU Block Diagram](/img/tvu.svg)
+
+## Retransmit Stage
+
+![Retransmit Block Diagram](/img/retransmit_stage.svg)

package/src/wallet-guide/apps.md

@@ -0,0 +1,74 @@
+---
+title: Mobile App Wallets
+---
+
+Solana is supported by multiple third-party apps which should provide a familiar
+experience for most people who are new or experienced with using crypto wallets.
+
+## Coin98
+
+[Coin98](https://coin98.app/) is an app available for iOS and Android and can
+be used to send and receive SOL tokens.
+
+_Note: Coin98 does not support stake accounts or staking operations_
+
+## Exodus
+
+Send, receive & exchange cryptocurrency with ease on the world's leading Desktop, Mobile and Hardware crypto wallets.
+
+Download [Exodus](https://exodus.com/) to easily and securely manage your Solana tokens.
+
+Exodus includes live charts, a built-in exchange, and 24/7 human support.
+
+## Solflare
+
+[Solflare Wallet](https://solflare.com/) has mobile applications available for both
+iOS and Android. These Mobile apps have support for sending Solana and SPL tokens,
+staking, and NFT management in a fully-featured NFT gallery.
+
+Security is a top priority for Solflare - the mobile wallet is non-custodial,
+meaning keys are managed by the user who retains total control of their own funds.
+The app supports biometric protection alongside passwords for maximum security.
+
+## Trust Wallet
+
+[Trust Wallet](https://trustwallet.com/) is an app available for iOS and Android
+and can be used to send and receive SOL tokens.
+
+_Note: Trust Wallet does not support stake accounts or staking operations_
+
+### Trust Wallet Security
+
+Tokens held in Trust Wallet are only as secure as the device on which the app is
+installed. Anyone who is able to unlock your phone or tablet may be able to
+use the Trust Wallet app and transfer your tokens. To improve security,
+you can add a passcode to the Trust Wallet application.
+To add a Trust Wallet passcode, open the app and go to
+Settings -> Security -> Passcode.
+
+If someone gains access to your Trust Wallet application, they can access your
+recovery seed phrase.
+Anyone who has access to your seed phrase will be able to recreate
+your Trust Wallet keys on a different device. From there, they could
+sign transactions from that device rather than on your own phone or tablet.
+The seed phrase is displayed when a new wallet is created and it can also be
+viewed at any later time in the app by following these steps:
+
+- Go to Setting -> Wallets
+- Under the Options menu for a particular wallet tap "Show Recovery Phrase"
+
+## Zelcore
+
+[Zelcore](https://zelcore.io) is a multi-currency wallet now supporting SOL and all Solana tokens (SPL). Each Zelcore account has 3 separate addresses for each asset.
+Store, transact, connect to dapps, and (soon) DEX trade in a single app and hold SOL tokens alongside BTC, ETH, and 270+ other cryptos.
+
+Zelcore is available for [Desktop](https://zelcore.io), [iOS](https://apps.apple.com/us/app/zelcore/id1436296839), and [Android](https://play.google.com/store/apps/details?id=com.zelcash.zelcore&hl=en_US&gl=US). One account for all your cryptos, all your devices.
+
+Zelcore also uses a custom Sollet-based wallet adapter solution so users can connect to all their dapps with a single browser tab to keep things tidy.
+
+__**DEVS**__: integrate Zelcore wallet into your products by implementing Sollet solution using "link.zelcore.io" as connection URL.
+
+### Zelcore Wallet Security
+Zelcore utilizes a username/password schema to derive private keys for all assets. Security layers include blockchain-based 2FA PIN, mobile device biometrics, and passphrases to allow users to set up as much or as little security as they like. All hashing functions done on-device, and no login/account info is stored nor transmitted off your device. The private keys only exist on-device while logged in, upon logging out there is no digital footprint left of your PKs.
+
+**Treat your username, password, d2FA PIN, passphrases, etc. with utmost care, just like your private keys. Never give these to anyone!**

package/src/wallet-guide/cli.md

@@ -0,0 +1,67 @@
+---
+title: Command Line Wallets
+---
+
+Solana supports several different types of wallets that can be used to interface
+directly with the Solana command-line tools.
+
+**If you are unfamiliar with using command line programs and just want to be able
+to send and receive SOL tokens, we recommend setting up a third-party
+[App Wallet](apps.md)**.
+
+To use a Command Line Wallet, you must first [install the Solana CLI tools](../cli/install-solana-cli-tools.md)
+
+## File System Wallet
+
+A _file system wallet_, aka an FS wallet, is a directory in your computer's
+file system. Each file in the directory holds a keypair.
+
+### File System Wallet Security
+
+A file system wallet is the most convenient and least secure form of wallet. It
+is convenient because the keypair is stored in a simple file. You can generate as
+many keys as you would like and trivially back them up by copying the files. It
+is insecure because the keypair files are **unencrypted**. If you are the only
+user of your computer and you are confident it is free of malware, an FS wallet
+is a fine solution for small amounts of cryptocurrency. If, however, your
+computer contains malware and is connected to the Internet, that malware may
+upload your keys and use them to take your tokens. Likewise, because the
+keypairs are stored on your computer as files, a skilled hacker with physical
+access to your computer may be able to access it. Using an encrypted hard
+drive, such as FileVault on MacOS, minimizes that risk.
+
+[File System Wallet](file-system-wallet.md)
+
+## Paper Wallet
+
+A _paper wallet_ is a collection of _seed phrases_ written on paper. A seed
+phrase is some number of words (typically 12 or 24) that can be used to
+regenerate a keypair on demand.
+
+### Paper Wallet Security
+
+In terms of convenience versus security, a paper wallet sits at the opposite
+side of the spectrum from an FS wallet. It is terribly inconvenient to use, but
+offers excellent security. That high security is further amplified when paper
+wallets are used in conjunction with
+[offline signing](../offline-signing.md). Custody services such as
+[Coinbase Custody](https://custody.coinbase.com/) use this combination.
+Paper wallets and custody services are an excellent way to secure a large number
+of tokens for a long period of time.
+
+[Paper Wallets](paper-wallet.md)
+
+## Hardware Wallet
+
+A hardware wallet is a small handheld device that stores keypairs and provides
+some interface for signing transactions.
+
+### Hardware Wallet Security
+
+A hardware wallet, such as the
+[Ledger hardware wallet](https://www.ledger.com/), offers a great blend of
+security and convenience for cryptocurrencies. It effectively automates the
+process of offline signing while retaining nearly all the convenience of a file
+system wallet.
+
+[Hardware Wallets](hardware-wallets.md)

package/src/wallet-guide/file-system-wallet.md

@@ -0,0 +1,65 @@
+---
+title: File System Wallet
+---
+
+This document describes how to create and use a file system wallet with the
+Solana CLI tools. A file system wallet exists as an unencrypted keypair file
+on your computer system's filesystem.
+
+> File system wallets are the **least secure** method of storing SOL tokens. Storing large amounts of tokens in a file system wallet is **not recommended**.
+
+## Before you Begin
+
+Make sure you have
+[installed the Solana Command Line Tools](../cli/install-solana-cli-tools.md)
+
+## Generate a File System Wallet Keypair
+
+Use Solana's command-line tool `solana-keygen` to generate keypair files. For
+example, run the following from a command-line shell:
+
+```bash
+mkdir ~/my-solana-wallet
+solana-keygen new --outfile ~/my-solana-wallet/my-keypair.json
+```
+
+This file contains your **unencrypted** keypair. In fact, even if you specify
+a password, that password applies to the recovery seed phrase, not the file. Do
+not share this file with others. Anyone with access to this file will have access
+to all tokens sent to its public key. Instead, you should share only its public
+key. To display its public key, run:
+
+```bash
+solana-keygen pubkey ~/my-solana-wallet/my-keypair.json
+```
+
+It will output a string of characters, such as:
+
+```text
+ErRr1caKzK8L8nn4xmEWtimYRiTCAZXjBtVphuZ5vMKy
+```
+
+This is the public key corresponding to the keypair in
+`~/my-solana-wallet/my-keypair.json`. The public key of the keypair file is
+your _wallet address_.
+
+## Verify your Address against your Keypair file
+
+To verify you hold the private key for a given address, use
+`solana-keygen verify`:
+
+```bash
+solana-keygen verify <PUBKEY> ~/my-solana-wallet/my-keypair.json
+```
+
+where `<PUBKEY>` is replaced with your wallet address.
+The command will output "Success" if the given address matches the
+the one in your keypair file, and "Failed" otherwise.
+
+## Creating Multiple File System Wallet Addresses
+
+You can create as many wallet addresses as you like. Simply re-run the
+steps in [Generate a File System Wallet](#generate-a-file-system-wallet-keypair)
+and make sure to use a new filename or path with the `--outfile` argument.
+Multiple wallet addresses can be useful if you want to transfer tokens between
+your own accounts for different purposes.

package/src/wallet-guide/hardware-wallets/ledger.md

@@ -0,0 +1,219 @@
+---
+title: Ledger Nano
+---
+
+This page describes how to use a Ledger Nano S or Nano X to interact with Solana
+using the command line tools. To see other solutions to interact with Solana with
+your Nano, [click here](../ledger-live.md#interact-with-the-solana-network).
+
+## Before You Begin
+
+- [Set up a Nano with the Solana App](../ledger-live.md)
+- [Install the Solana command-line tools](../../cli/install-solana-cli-tools.md)
+
+## Use Ledger Nano with Solana CLI
+
+1. Ensure the Ledger Live application is closed
+2. Plug your Nano into your computer's USB port
+3. Enter your pin and start the Solana app on the Nano
+4. Ensure the screen reads "Application is ready"
+
+### View your Wallet ID
+
+On your computer, run:
+
+```bash
+solana-keygen pubkey usb://ledger
+```
+
+This confirms your Ledger device is connected properly and in the correct state
+to interact with the Solana CLI. The command returns your Ledger's unique
+_wallet ID_. When you have multiple Nano devices connected to the same
+computer, you can use your wallet ID to specify which Ledger hardware wallet
+you want to use. If you only plan to use a single Nano on your computer
+at a time, you don't need to include the wallet ID. For information on
+using the wallet ID to use a specific Ledger, see
+[Manage Multiple Hardware Wallets](#manage-multiple-hardware-wallets).
+
+### View your Wallet Addresses
+
+Your Nano supports an arbitrary number of valid wallet addresses and signers.
+To view any address, use the `solana-keygen pubkey` command, as shown below,
+followed by a valid [keypair URL](../hardware-wallets.md#specify-a-keypair-url).
+
+Multiple wallet addresses can be useful if you want to transfer tokens between
+your own accounts for different purposes, or use different keypairs on the
+device as signing authorities for a stake account, for example.
+
+All of the following commands will display different addresses, associated with
+the keypair path given. Try them out!
+
+```bash
+solana-keygen pubkey usb://ledger
+solana-keygen pubkey usb://ledger?key=0
+solana-keygen pubkey usb://ledger?key=1
+solana-keygen pubkey usb://ledger?key=2
+```
+
+- NOTE: keypair url parameters are ignored in **zsh**
+   [see troubleshooting for more info](#troubleshooting)
+
+You can use other values for the number after `key=` as well.
+Any of the addresses displayed by these commands are valid Solana wallet
+addresses. The private portion associated with each address is stored securely
+on the Nano, and is used to sign transactions from this address.
+Just make a note of which keypair URL you used to derive any address you will be
+using to receive tokens.
+
+If you are only planning to use a single address/keypair on your device, a good
+easy-to-remember path might be to use the address at `key=0`. View this address
+with:
+
+```bash
+solana-keygen pubkey usb://ledger?key=0
+```
+
+Now you have a wallet address (or multiple addresses), you can share any of
+these addresses publicly to act as a receiving address, and you can use the
+associated keypair URL as the signer for transactions from that address.
+
+### View your Balance
+
+To view the balance of any account, regardless of which wallet it uses, use the
+`solana balance` command:
+
+```bash
+solana balance SOME_WALLET_ADDRESS
+```
+
+For example, if your address is `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`,
+then enter the following command to view the balance:
+
+```bash
+solana balance 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri
+```
+
+You can also view the balance of any account address on the Accounts tab in the
+[Explorer](https://explorer.solana.com/accounts)
+and paste the address in the box to view the balance in you web browser.
+
+Note: Any address with a balance of 0 SOL, such as a newly created one on your
+Ledger, will show as "Not Found" in the explorer. Empty accounts and non-existent
+accounts are treated the same in Solana. This will change when your account
+address has some SOL in it.
+
+### Send SOL from a Nano
+
+To send some tokens from an address controlled by your Nano, you will
+need to use the device to sign a transaction, using the same keypair URL you
+used to derive the address. To do this, make sure your Nano is plugged in,
+unlocked with the PIN, Ledger Live is not running, and the Solana App is open
+on the device, showing "Application is Ready".
+
+The `solana transfer` command is used to specify to which address to send tokens,
+how many tokens to send, and uses the `--keypair` argument to specify which
+keypair is sending the tokens, which will sign the transaction, and the balance
+from the associated address will decrease.
+
+```bash
+solana transfer RECIPIENT_ADDRESS AMOUNT --keypair KEYPAIR_URL_OF_SENDER
+```
+
+Below is a full example. First, an address is viewed at a certain keypair URL.
+Second, the balance of that address is checked. Lastly, a transfer transaction
+is entered to send `1` SOL to the recipient address `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`.
+When you hit Enter for a transfer command, you will be prompted to approve the
+transaction details on your Ledger device. On the device, use the right and
+left buttons to review the transaction details. If they look correct, click
+both buttons on the "Approve" screen, otherwise push both buttons on the "Reject"
+screen.
+
+```bash
+~$ solana-keygen pubkey usb://ledger?key=42
+CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
+
+~$ solana balance CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
+1.000005 SOL
+
+~$ solana transfer 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri 1 --keypair usb://ledger?key=42
+Waiting for your approval on Ledger hardware wallet usb://ledger/2JT2Xvy6T8hSmT8g6WdeDbHUgoeGdj6bE2VueCZUJmyN
+✅ Approved
+
+Signature: kemu9jDEuPirKNRKiHan7ycybYsZp7pFefAdvWZRq5VRHCLgXTXaFVw3pfh87MQcWX4kQY4TjSBmESrwMApom1V
+```
+
+After approving the transaction on your device, the program will display the
+transaction signature, and wait for the maximum number of confirmations (32)
+before returning. This only takes a few seconds, and then the transaction is
+finalized on the Solana network. You can view details of this or any other
+transaction by going to the Transaction tab in the
+[Explorer](https://explorer.solana.com/transactions)
+and paste in the transaction signature.
+
+## Advanced Operations
+
+### Manage Multiple Hardware Wallets
+
+It is sometimes useful to sign a transaction with keys from multiple hardware
+wallets. Signing with multiple wallets requires _fully qualified keypair URLs_.
+When the URL is not fully qualified, the Solana CLI will prompt you with
+the fully qualified URLs of all connected hardware wallets, and ask you to
+choose which wallet to use for each signature.
+
+Instead of using the interactive prompts, you can generate fully qualified
+URLs using the Solana CLI `resolve-signer` command. For example, try
+connecting a Nano to USB, unlock it with your pin, and running the
+following command:
+
+```text
+solana resolve-signer usb://ledger?key=0/0
+```
+
+You will see output similar to:
+
+```text
+usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
+```
+
+but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_ID`.
+
+With your fully qualified URL, you can connect multiple hardware wallets to
+the same computer and uniquely identify a keypair from any of them.
+Use the output from the `resolve-signer` command anywhere a `solana` command
+expects a `<KEYPAIR>` entry to use that resolved path as the signer for that
+part of the given transaction.
+
+## Troubleshooting
+
+### Keypair URL parameters are ignored in zsh
+
+The question mark character is a special character in zsh. If that's not a
+feature you use, add the following line to your `~/.zshrc` to treat it as a
+normal character:
+
+```bash
+unsetopt nomatch
+```
+
+Then either restart your shell window or run `~/.zshrc`:
+
+```bash
+source ~/.zshrc
+```
+
+If you would prefer not to disable zsh's special handling of the question mark
+character, you can disable it explictly with a backslash in your keypair URLs.
+For example:
+
+```bash
+solana-keygen pubkey usb://ledger\?key=0
+```
+
+## Support
+
+Check out our [Wallet Support Page](../support.md)
+for ways to get help.
+
+Read more about [sending and receiving tokens](../../cli/transfer-tokens.md) and
+[delegating stake](../../cli/delegate-stake.md). You can use your Ledger keypair URL
+anywhere you see an option or argument that accepts a `<KEYPAIR>`.

package/src/wallet-guide/hardware-wallets.md

@@ -0,0 +1,53 @@
+---
+title: Using Hardware Wallets on the Solana CLI
+---
+
+Signing a transaction requires a private key, but storing a private
+key on your personal computer or phone leaves it subject to theft.
+Adding a password to your key adds security, but many people prefer
+to take it a step further and move their private keys to a separate
+physical device called a _hardware wallet_. A hardware wallet is a
+small handheld device that stores private keys and provides some
+interface for signing transactions.
+
+The Solana CLI has first class support for hardware wallets. Anywhere
+you use a keypair filepath (denoted as `<KEYPAIR>` in usage docs), you
+can pass a _keypair URL_ that uniquely identifies a keypair in a
+hardware wallet.
+
+## Supported Hardware Wallets
+
+The Solana CLI supports the following hardware wallets:
+
+- [Ledger Nano S and Ledger Nano X](hardware-wallets/ledger.md)
+
+## Specify a Keypair URL
+
+Solana defines a keypair URL format to uniquely locate any Solana keypair on a
+hardware wallet connected to your computer.
+
+The keypair URL has the following form, where square brackets denote optional
+fields:
+
+```text
+usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]
+```
+
+`WALLET_ID` is a globally unique key used to disambiguate multiple devices.
+
+`DERVIATION_PATH` is used to navigate to Solana keys within your hardware wallet.
+The path has the form `<ACCOUNT>[/<CHANGE>]`, where each `ACCOUNT` and `CHANGE`
+are positive integers.
+
+For example, a fully qualified URL for a Ledger device might be:
+
+```text
+usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
+```
+
+All derivation paths implicitly include the prefix `44'/501'`, which indicates
+the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
+and that any derived keys are Solana keys (Coin type 501). The single quote
+indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
+derivations are hardened and therefore adding the quote is optional and
+unnecessary.