From ce1d36cacb2129be1f54dbe34af43e1b5564b2df Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Mon, 30 Dec 2019 13:13:56 -0500 Subject: [PATCH] Book: Document CLI durable nonce account management (#7595) * Book: Document CLI durable nonce account management * Fix rent link * review --- book/src/SUMMARY.md | 1 + book/src/api-reference/cli.md | 30 ++++ book/src/offline-signing/README.md | 8 + book/src/offline-signing/durable-nonce.md | 188 ++++++++++++++++++++++ 4 files changed, 227 insertions(+) create mode 100644 book/src/offline-signing/durable-nonce.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index c65f45c910..161114872c 100644 --- a/book/src/SUMMARY.md +++ b/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) diff --git a/book/src/api-reference/cli.md b/book/src/api-reference/cli.md index 2e528fbd80..e2e1b6c11b 100644 --- a/book/src/api-reference/cli.md +++ b/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: 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] + +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 Securely recover a keypair using a seed phrase and optional passphrase + [possible values: keypair] + -C, --config Configuration file to use [default: + ~/.config/solana/cli/config.yml] + -u, --url JSON RPC URL for the solana cluster + -k, --keypair /path/to/id.json + --nonce-authority Specify nonce authority if different from account + +ARGS: + Address of the nonce account + Account to be granted authority of the nonce account +``` + #### solana-balance ```text solana-balance diff --git a/book/src/offline-signing/README.md b/book/src/offline-signing/README.md index e80827634f..9f6445c4fe 100644 --- a/book/src/offline-signing/README.md +++ b/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. diff --git a/book/src/offline-signing/durable-nonce.md b/book/src/offline-signing/durable-nonce.md new file mode 100644 index 0000000000..ad46e2e76f --- /dev/null +++ b/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 ` 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 %} +