Book - Document nonceable CLI subcommands (#7656)

automerge

book/src/api-reference/cli.md

@@ -695,14 +695,20 @@ FLAGS:
     -v, --verbose                        Show extra information header
 
 OPTIONS:
-        --ask-seed-phrase <KEYPAIR NAME>    Securely recover a keypair using a seed phrase and optional passphrase
+        --ask-seed-phrase <KEYPAIR NAME>       Securely recover a keypair using a seed phrase and optional passphrase
-                                            [possible values: keypair]
+                                               [possible values: keypair]
-        --blockhash <BLOCKHASH>             Use the supplied blockhash
+        --blockhash <BLOCKHASH>                Use the supplied blockhash
-    -C, --config <PATH>                     Configuration file to use [default:
+    -C, --config <PATH>                        Configuration file to use [default:
-                                            ~/.config/solana/cli/config.yml]
+                                               ~/.config/solana/cli/config.yml]
-    -u, --url <URL>                         JSON RPC URL for the solana cluster
+    -u, --url <URL>                            JSON RPC URL for the solana cluster
-    -k, --keypair <PATH>                    /path/to/id.json
+    -k, --keypair <PATH>                       /path/to/id.json
-        --signer <PUBKEY=BASE58_SIG>...     Provide a public-key/signature pair for the transaction
+        --nonce <PUBKEY>                       Provide the nonce account to use when creating a nonced 
+                                               transaction. Nonced transactions are useful when a transaction 
+                                               requires a lengthy signing process. Learn more about nonced 
+                                               transactions at https://docs.solana.com/offline-signing/durable-nonce
+        --nonce-authority <nonce_authority>    Provide the nonce authority keypair to use when signing a nonced
+                                               transaction
+        --signer <PUBKEY=BASE58_SIG>...        Provide a public-key/signature pair for the transaction
 
 ARGS:
     <STAKE ACCOUNT>    Stake account to be deactivated.
@@ -725,14 +731,20 @@ FLAGS:
     -v, --verbose                        Show extra information header
 
 OPTIONS:
-        --ask-seed-phrase <KEYPAIR NAME>    Securely recover a keypair using a seed phrase and optional passphrase
+        --ask-seed-phrase <KEYPAIR NAME>       Securely recover a keypair using a seed phrase and optional passphrase
-                                            [possible values: keypair]
+                                               [possible values: keypair]
-        --blockhash <BLOCKHASH>             Use the supplied blockhash
+        --blockhash <BLOCKHASH>                Use the supplied blockhash
-    -C, --config <PATH>                     Configuration file to use [default:
+    -C, --config <PATH>                        Configuration file to use [default:
-                                            ~/.config/solana/cli/config.yml]
+                                               ~/.config/solana/cli/config.yml]
-    -u, --url <URL>                         JSON RPC URL for the solana cluster
+    -u, --url <URL>                            JSON RPC URL for the solana cluster
-    -k, --keypair <PATH>                    /path/to/id.json
+    -k, --keypair <PATH>                       /path/to/id.json
-        --signer <PUBKEY=BASE58_SIG>...     Provide a public-key/signature pair for the transaction
+        --nonce <PUBKEY>                       Provide the nonce account to use when creating a nonced 
+                                               transaction. Nonced transactions are useful when a transaction 
+                                               requires a lengthy signing process. Learn more about nonced 
+                                               transactions at https://docs.solana.com/offline-signing/durable-nonce
+        --nonce-authority <nonce_authority>    Provide the nonce authority keypair to use when signing a nonced
+                                               transaction
+        --signer <PUBKEY=BASE58_SIG>...        Provide a public-key/signature pair for the transaction
 
 ARGS:
     <STAKE ACCOUNT>    Stake account to delegate
@@ -1035,6 +1047,12 @@ OPTIONS:
                                                 ~/.config/solana/cli/config.yml]
     -u, --url <URL>                             JSON RPC URL for the solana cluster
     -k, --keypair <PATH>                        /path/to/id.json
+        --nonce <PUBKEY>                        Provide the nonce account to use when creating a nonced 
+                                                transaction. Nonced transactions are useful when a transaction 
+                                                requires a lengthy signing process. Learn more about nonced 
+                                                transactions at https://docs.solana.com/offline-signing/durable-nonce
+        --nonce-authority <nonce_authority>     Provide the nonce authority keypair to use when signing a nonced
+                                                transaction
         --signer <PUBKEY=BASE58_SIG>...         Provide a public-key/signature pair for the transaction
         --after <DATETIME>                      A timestamp after which transaction will execute
         --require-timestamp-from <PUBKEY>       Require timestamp from this third party

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

@@ -11,7 +11,7 @@ about in the [proposal](../implemented-proposals/durable-tx-nonces.md).
 
 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
+transaction fails with an instruction error, 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.
 
@@ -36,11 +36,15 @@ This issue is being actively addressed, progress can be followed on
 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.
+### Nonce Authority
-This enables the creation of more complex account ownership arrangements and
+
-derived account addresses not associated with a keypair. The
+Authority over a nonce account can optionally be assigned to another account. In
-`--nonce-authority <AUTHORITY_KEYPAIR>` argument is used to specify this
+doing so the new authority inherits full control over the nonce account from the
-authority and is supported by the following commands
+previous authority, including the account creator. This feature 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 account and is supported by the following
+commands
 * `create-nonce-account`
 * `new-nonce`
 * `withdraw-from-nonce-account`
@@ -50,7 +54,7 @@ authority and is supported by the following commands
 
 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.
+so need to carry the minimum balance to achieve this.
 
 A nonce account is created by first generating a new keypair, then create the account on chain
 
@@ -186,3 +190,100 @@ solana authorize-nonce-account nonce-keypair.json nonce-authority.json
 [Full usage documentation](../api-reference/cli.md#solana-authorize-nonce-account)
 {% endhint %}
 
+## Other Commands Supporting Durable Nonces
+
+To make use of durable nonces with other CLI subcommands, two arguments must be
+supported.
+* `--nonce`, specifies the account storing the nonce value
+* `--nonce-authority`, specifies an optional [nonce authority](#nonce-authority)
+
+The following subcommands have received this treatment so far
+* [`pay`](../api-reference/cli.md#solana-pay)
+* [`delegate-stake`](../api-reference/cli.md#solana-delegate-stake)
+* [`deactivate-stake`](../api-reference/cli.md#solana-deactivate-stake)
+
+### Example Pay Using Durable Nonce
+
+Here we demonstrate Alice paying Bob 1 SOL using a durable nonce. The procedure
+is the same for all subcommands supporting durable nonces
+
+#### - Create accounts
+
+First we need some accounts for Alice, Alice's nonce and Bob
+
+```bash
+$ solana-keygen new -o alice.json
+$ solana-keygen new -o nonce.json
+$ solana-keygen new -o bob.json
+```
+
+#### - Fund Alice's account
+
+Alice will need some funds to create a nonce account and send to Bob. Airdrop
+her some SOL
+
+```bash
+$ solana airdrop -k alice.json 10 SOL
+10 SOL
+```
+
+#### - Create Alice's nonce account
+
+Now Alice needs a nonce account. Create one
+
+{% hint style="info" %}
+Here, no separate [nonce authority](#nonce-authority) is employed, so `alice.json`
+has full authority over the nonce account
+{% endhint %}
+
+```bash
+$ solana create-nonce-account -k alice.json nonce.json 1 SOL
+3KPZr96BTsL3hqera9up82KAU462Gz31xjqJ6eHUAjF935Yf8i1kmfEbo6SVbNaACKE5z6gySrNjVRvmS8DcPuwV
+```
+
+#### - A failed first attempt to pay Bob
+
+Alice attempts to pay Bob, but takes too long to sign. The specified blockhash
+expires and the transaction fails
+
+```bash
+$ solana pay -k alice.json --blockhash expiredDTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7 bob.json 1 SOL
+[2020-01-02T18:48:28.462911000Z ERROR solana_cli::cli] Io(Custom { kind: Other, error: "Transaction \"33gQQaoPc9jWePMvDAeyJpcnSPiGUAdtVg8zREWv4GiKjkcGNufgpcbFyRKRrA25NkgjZySEeKue5rawyeH5TzsV\" failed: None" })
+Error: Io(Custom { kind: Other, error: "Transaction \"33gQQaoPc9jWePMvDAeyJpcnSPiGUAdtVg8zREWv4GiKjkcGNufgpcbFyRKRrA25NkgjZySEeKue5rawyeH5TzsV\" failed: None" })
+```
+
+#### - Nonce to the rescue!
+
+Alice retries the transaction, this time specifying her nonce account and the
+blockhash stored there
+
+{% hint style="info" %}
+Remember, `alice.json` is the [nonce authority](#nonce-authority) in this example
+{% endhint %}
+
+```bash
+$ solana show-nonce-account nonce.json 
+balance: 1 SOL
+minimum balance required: 0.00136416 SOL
+nonce: F7vmkY3DTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7
+```
+```bash
+$ solana pay -k alice.json --blockhash F7vmkY3DTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7 --nonce nonce.json bob.json 1 SOL
+HR1368UKHVZyenmH7yVz5sBAijV6XAPeWbEiXEGVYQorRMcoijeNAbzZqEZiH8cDB8tk65ckqeegFjK8dHwNFgQ
+```
+
+#### - Success!
+
+The transaction succeeds!  Bob receives 1 SOL from Alice and Alice's stored
+nonce advances to a new value
+
+```bash
+$ solana balance -k bob.json
+1 SOL
+```
+```bash
+$ solana show-nonce-account nonce.json 
+balance: 1 SOL
+minimum balance required: 0.00136416 SOL
+nonce: 6bjroqDcZgTv6Vavhqf81oBHTv3aMnX19UTB51YhAZnN
+```