How do nonces work?

What is a nonce?

A nonce is a sequential ID number for transactions in a given wallet. You can think of a nonce as somewhat similar to a check number in a bank ledger, with the main difference being that nonces must always occur sequentially without skips.

Each transaction that you sign using your wallet will have an associated nonce. This value is automatically determined and passed along from your wallet when submitting a transaction, but there are some cases where nonces must be manually overridden.

Another important detail is that, if two transactions are signed from the same wallet with the same nonce, only the transaction with the higher fee will be accepted as a valid transaction. This principle, in effect, can be used to override or cancel transactions.

Why would you need to manually set a custom nonce?

There are three main reasons for setting a custom nonce:

1. To override or cancel a transaction: While transactions cannot be canceled with certainty, overriding a transaction can be achieved by submitting a new transaction with the same, manually assigned nonce, and a higher fee than the first transaction. When you "increase fee" on a transaction through a wallet, under the covers, what is really happening is a resubmission of a transaction with the same nonce, but at a higher fee.
2. To correct errors made by wallet software: Sometimes, a wallet will incorrectly assign a nonce so that it is not the immediate next sequential nonce. As we said previously, nonces must always occur sequentially without skips. If a nonce is submitted that is too high or too low, the transaction will never be able to be confirmed.
3. To get a series of transactions "unstuck" from an account: Similar to the first reason, a situation could arise in which a series of otherwise acceptable transactions are held up behind a "stuck" transaction. Since nonces must always occur sequentially without skips, a backlog can occur. Resubmitting a transaction in place of the transaction with a "stuck" nonce and a higher fee can resolve the issue.

How do you manually set a custom nonce to troubleshoot issues?

Setting a custom nonce is quite simple, and can be done usually within the "Edit nonce", "Advanced", or "Custom" menu when submitting a transaction within a wallet. A field will appear, typically with a preset nonce, and the option to manually type in a new nonce.

The main prerequisite is determining the current nonce for your account and re-submitting or otherwise addressing the issue at hand by submitting transactions with the correct nonce. Remember, there is a single acceptable nonce from a given account at all times. If you do not submit transactions with the single acceptable nonce, no future transactions can ever be accepted as valid transactions and they will all fail until the nonce is rectified and correct.

Troubleshooting issues with nonces

• Step One: Identify your account's current nonce using the Stacks Explorer. This is the single acceptable nonce from your given account. You can paste your STX address in the searchbar and your nonce will be listed as one of the main highlights of your address.

• Step Two: Identify the nonces of your pending transactions to see why they aren't being accepted as valid transactions. You can do this by clicking on the pending transaction or any other transaction in the ledger. The nonces on these transactions may be too high or too low (in other words, they may be duplicates or may have skipped nonces). In the screenshot below, you'll see the most recent transaction that successfully confirmed was 880, hence why in the prior screenshot in Step 1, the account's current nonce is 881. In this example, the single acceptable nonce for the next sequential transaction will be 881.

• Step Three: Create a new transaction (or re-create your original transaction), but manually typing in the single acceptable nonce as the custom nonce. You can usually do this by exposing the "Advanced" or "Custom" transaction menu before submitting your transaction. If you don't have a transaction you need to submit, you can send any amount of STX or any other token to another wallet. For example, you can "Create an Account" under the same Leather (formerly Hiro) wallet and then send 0.01 STX to the newly created address with the correct nonce assigned to the STX transfer. Any transaction will do as long as it is accepted as a valid transaction.

• Step Four: Submit the transaction and wait for it to confirm. If your goal is to render a transaction unstuck, you'll need to make sure your same-nonce-transaction has a higher fee than the previous one.

In conclusion

Nonces are a straightforward concept, but can be tricky in practice. If you're having trouble figuring out how to resolve a nonce-related issue with your account, please contact support and we can recommend a potential solution.