Book: Document CLI durable nonce account management (#7595)

* Book: Document CLI durable nonce account management

* Fix rent link

* review

book/src/SUMMARY.md

@@ -39,6 +39,7 @@
   * [Installation](paper-wallet/installation.md)
   * [Paper Wallet Usage](paper-wallet/usage.md)
 * [Offline Signing](offline-signing/README.md)
+  * [Durable Transaction Nonces](offline-signing/durable-nonce.md)
 * [API Reference](api-reference/README.md)
   * [Transaction](api-reference/transaction-api.md)
   * [Instruction](api-reference/instruction-api.md)

book/src/api-reference/cli.md

@@ -201,6 +201,7 @@ OPTIONS:
 SUBCOMMANDS:
     address                             Get your public key
     airdrop                             Request lamports
+    authorize-nonce-account             Assign account authority to a new entity
     balance                             Get your balance
     cancel                              Cancel a transfer
     catchup                             Wait for a validator to catch up to the cluster
@@ -305,6 +306,35 @@ ARGS:
     <UNIT>      Specify unit to use for request and balance display [possible values: SOL, lamports]
 ```
 
+#### solana-authorize-nonce-account
+```text
+solana-authorize-nonce-account 
+Assign account authority to a new entity
+
+USAGE:
+    solana authorize-nonce-account [FLAGS] [OPTIONS] <NONCE_ACCOUNT> <NEW_AUTHORITY_PUBKEY>
+
+FLAGS:
+    -h, --help                           Prints help information
+        --skip-seed-phrase-validation    Skip validation of seed phrases. Use this if your phrase does not use the BIP39
+                                         official English word list
+    -V, --version                        Prints version information
+    -v, --verbose                        Show extra information header
+
+OPTIONS:
+        --ask-seed-phrase <KEYPAIR NAME>    Securely recover a keypair using a seed phrase and optional passphrase
+                                            [possible values: keypair]
+    -C, --config <PATH>                     Configuration file to use [default:
+                                            ~/.config/solana/cli/config.yml]
+    -u, --url <URL>                         JSON RPC URL for the solana cluster
+    -k, --keypair <PATH>                    /path/to/id.json
+        --nonce-authority <KEYPAIR>         Specify nonce authority if different from account
+
+ARGS:
+    <NONCE_ACCOUNT>           Address of the nonce account
+    <NEW_AUTHORITY_PUBKEY>    Account to be granted authority of the nonce account
+```
+
 #### solana-balance
 ```text
 solana-balance 

book/src/offline-signing/README.md

@@ -75,3 +75,11 @@ Output
 ```text
 4vC38p4bz7XyiXrk6HtaooUqwxTWKocf45cstASGtmrD398biNJnmTcUCVEojE7wVQvgdYbjHJqRFZPpzfCQpmUN
 ```
+
+## Buying More Time to Sign
+
+Typically a Solana transaction must be signed and accepted by the network within
+a number of slots from the blockhash in its `recent_blockhash` field (~2min at
+the time of this writing). If your signing procedure takes longer than this, a
+[Durable Transaction Nonce](durable-nonce.md) can give you the extra time you
+need.

book/src/offline-signing/durable-nonce.md

@@ -0,0 +1,188 @@
+# Durable Transaction Nonces
+
+Durable transaction nonces are a mechanism for getting around the typical
+short lifetime of a transaction's [`recent_blockhash`](../transaction.md#recent-blockhash).
+They are implemented as a Solana Program, the mechanics of which can be read
+about in the [proposal](../implemented-proposals/durable-tx-nonces.md).
+
+## Known Issues
+
+### Fee Theft Opportunity
+
+The durable nonce implementation contains a vulernability which allows for fees
+to be stolen by a transaction using the feature under certain conditions. If the
+transaction fails with an instruction errror, the runtime rolls back the step
+that advanced the stored nonce, allowing it to be replayed and fees charged.
+This can be repeated until the stored nonce is successfully advanced.
+
+- Mitigation
+
+To minimize loss of funds, use a low-balance account to pay fees on a durable
+nonce transaction.
+
+If a transaction using the durable nonce feature fails with an instruction error,
+immediately submit a new transaction that advances the nonce and will certainly
+succeed. The simplest way to do this is with a single-instruction
+`NonceInstruction::Nonce` transaction, which can be sent using the CLI
+[`new-nonce`](#advancing-the-stored-nonce-value) command.
+
+- Issue Tracking
+
+This issue is being actively addressed, progress can be followed on
+[Github](https://github.com/solana-labs/solana/issues/7443).
+
+## Usage Examples
+
+Full usage details for durable nonce CLI commands can be found in the
+[CLI reference](../api-reference/cli.md).
+
+Additionally, authority over a nonce account can be assigned to another entity.
+This enables the creation of more complex account ownership arrangements and
+derived account addresses not associated with a keypair. The
+`--nonce-authority <AUTHORITY_KEYPAIR>` argument is used to specify this
+authority and is supported by the following commands
+* `create-nonce-account`
+* `new-nonce`
+* `withdraw-from-nonce-account`
+* `authorize-nonce-account`
+
+### Nonce Account Creation
+
+The durable transaction nonce feature uses an account to store the next nonce
+value.  Durable nonce accounts must be [rent-exempt](../implemented-proposals/rent.md#two-tiered-rent-regime),
+so need to carry the minimum balance to acheive this.
+
+A nonce account is created by first generating a new keypair, then create the account on chain
+
+- Command
+
+```bash
+solana-keygen new -o nonce-keypair.json
+solana create-nonce-account nonce-keypair.json 1 SOL
+```
+
+- Output
+
+```text
+2SymGjGV4ksPdpbaqWFiDoBz8okvtiik4KE9cnMQgRHrRLySSdZ6jrEcpPifW4xUpp4z66XM9d9wM48sA7peG2XL
+```
+
+{% hint style="info" %}
+To keep the keypair entirely offline, use the [Paper Wallet](../paper-wallet/README.md)
+keypair generation [instructions](../paper-wallet/usage.md#seed-phrase-generation.md)
+instead
+{% endhint %}
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-create-nonce-account)
+{% endhint %}
+
+### Querying the Stored Nonce Value
+
+Creating a durable nonce transaction requires passing the stored nonce value as
+the value to the `--blockhash` argument upon signing and submission. Obtain the
+presently stored nonce value with
+
+- Command
+
+```bash
+solana get-nonce nonce-keypair.json 
+```
+
+- Output
+
+```text
+8GRipryfxcsxN8mAGjy8zbFo9ezaUsh47TsPzmZbuytU
+```
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-get-nonce)
+{% endhint %}
+
+### Advancing the Stored Nonce Value
+
+While not typically needed outside a more useful transaction, the stored nonce
+value can be advanced by
+
+- Command
+
+```bash
+solana new-nonce nonce-keypair.json
+```
+
+- Output
+
+```text
+44jYe1yPKrjuYDmoFTdgPjg8LFpYyh1PFKJqm5SC1PiSyAL8iw1bhadcAX1SL7KDmREEkmHpYvreKoNv6fZgfvUK
+```
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-new-nonce)
+{% endhint %}
+
+### Display Nonce Account
+
+Inspect a nonce account in a more human friendly format with
+
+- Command
+
+```bash
+solana show-nonce-account nonce-keypair.json 
+```
+
+- Output
+
+```text
+balance: 0.5 SOL
+minimum balance required: 0.00136416 SOL
+nonce: DZar6t2EaCFQTbUP4DHKwZ1wT8gCPW2aRfkVWhydkBvS
+```
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-show-nonce-account)
+{% endhint %}
+
+### Withdraw Funds from a Nonce Account
+
+Withdraw funds from a nonce account with
+
+- Command
+
+```bash
+solana withdraw-from-nonce-account nonce-keypair.json ~/.config/solana/id.json 0.5 SOL
+```
+
+- Output
+
+```text
+3foNy1SBqwXSsfSfTdmYKDuhnVheRnKXpoPySiUDBVeDEs6iMVokgqm7AqfTjbk7QBE8mqomvMUMNQhtdMvFLide
+```
+
+{% hint style="info" %}
+Close a nonce account by withdrawing the full balance
+{% endhint %}
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-withdraw-from-nonce-account)
+{% endhint %}
+
+### Assign a New Authority to a Nonce Account
+
+Reassign the authority of a nonce account after creation with
+
+- Command
+
+```bash
+solana authorize-nonce-account nonce-keypair.json nonce-authority.json 
+```
+
+- Output
+
+```text
+3F9cg4zN9wHxLGx4c3cUKmqpej4oa67QbALmChsJbfxTgTffRiL3iUehVhR9wQmWgPua66jPuAYeL1K2pYYjbNoT
+```
+
+{% hint style="info" %}
+[Full usage documentation](../api-reference/cli.md#solana-authorize-nonce-account)
+{% endhint %}
+