Durable Transaction Nonces

Durable Transaction Nonces

Durable transaction nonces are a mechanism for getting around the typical short lifetime of a transaction's recent_blockhash.

Usage Examples

Full usage details for durable nonce CLI commands can be found in the CLI reference.

Nonce Authority

Authority over a nonce account can optionally be assigned to another account. In doing so the new authority inherits full control over the nonce account from the 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
  • 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, 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
Ethereal-keygen new -o nonce-keypair.json
Etherealcreate-nonce-account nonce-keypair.json 1
To keep the keypair entirely offline, use the Paper Wallet keypair generation instructions instead.
Full usage documentation

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
Etherealnonce nonce-keypair.json

Advancing the Stored Nonce Value

While not typically needed outside a more useful transaction, the stored nonce value can be advanced by
Etherealnew-nonce nonce-keypair.json
Full usage documentation

Display Nonce Account

Inspect a nonce account in a more human friendly format with
Etherealnonce-account nonce-keypair.json
balance: 0.5 Ethereal
minimum balance required: 0.00136416 Ethereal
nonce: DZar6t2EaCFQTbUP4DHKwZ1wT8gCPW2aRfkVWhydkBvS
Full usage documentation

Withdraw Funds from a Nonce Account

Withdraw funds from a nonce account with
Etherealwithdraw-from-nonce-account nonce-keypair.json ~/.config/Ethereal/id.json 0.5
Close a nonce account by withdrawing the full balance
Full usage documentation

Assign a New Authority to a Nonce Account

Reassign the authority of a nonce account after creation with
Etherealauthorize-nonce-account nonce-keypair.json nonce-authority.json
Full usage documentation

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
The following subcommands have received this treatment so far
  • pay
  • delegate-stake
  • deactivate-stake

Example Pay Using Durable Nonce

Here we demonstrate Alice paying Bob 1 Etherealusing 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
$ Ethereal-keygen new -o alice.json
$ Ethereal-keygen new -o nonce.json
$ Ethereal-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 Ethereal
$ Etherealairdrop -k alice.json 1
1 Ethereal
Create Alice's nonce account
Now Alice needs a nonce account. Create one
Here, no separate nonce authority is employed, so alice.json has full authority over the nonce account
$ Etherealcreate-nonce-account -k alice.json nonce.json 0.1
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
$ Etherealpay -k alice.json --blockhash expiredDTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7 bob.json 0.01
[2020-01-02T18:48:28.462911000Z ERROR Ethereal::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
Remember, alice.json is the nonce authority in this example
$ Etherealnonce-account nonce.json
balance: 0.1 Ethereal
minimum balance required: 0.00136416 Ethereal
nonce: F7vmkY3DTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7
$ Etherealpay -k alice.json --blockhash F7vmkY3DTaxfagttWjQweib42b6ZHADSx94Tw8gHx3W7 --nonce nonce.json bob.json 0.01
The transaction succeeds! Bob receives 0.01 Etherealfrom Alice and Alice's stored nonce advances to a new value
$ Etherealbalance -k bob.json
0.01 Ethereal
$ Etherealnonce-account nonce.json
balance: 0.1 Ethereal
minimum balance required: 0.00136416 Ethereal
nonce: 6bjroqDcZgTv6Vavhqf81oBHTv3aMnX19UTB51YhAZnN