Draft NEP for pending transaction queue. #611

robin-near · 2025-05-30T23:36:54Z

In the near future of the Near blockchain, we foresee that via the SPICE project, transaction and receipt execution will become decoupled from the blockchain itself; they will no longer run in lockstep. Instead, transactions will be included in the blocks first, and then execution will follow later.

This inherently introduces a problem that we must accept transactions before we know whether they are valid. Today, when a chunk producer produces a chunk containing a transaction, it can verify using the current shard state that the transaction has a valid signature, has enough balance, and a valid nonce. But as execution becomes asynchronous, we no longer have the current shard state to verify the
transactions against.

This NEP proposes a mechanism called the Pending Transaction Queue to solve this problem.

birchmd

Thanks for bringing this up! It is good to think about how to prevent possible DoS attacks under SPICE.

birchmd · 2025-06-02T13:23:05Z

neps/nep-0611.md

+#### Access Key Parallelism Restriction
+We now restrict the ability to send multiple parallel pending transactions with Access Keys.
+
+Specifically, for any given account $A$ with any number of access keys, the total number of access key transactions in the pending transaction queue whose sender is $A$ cannot exceed $P_{\mathrm {max}}$, a


Is this enough to prevent the attack described above? Instead of having one account they send many transactions to, it could be many accounts they send only a few transactions to each.

The idea is that the amount of block space the attacker consumes vs amount of gas the attacker has to pay, i.e. the "waste amplification factor", is unbounded in the attack mentioned in the NEP, but only O(1) with a maximum parallelism. It's then still possible to attack, but the attack would cost a proportional amount of gas - just cheaper than it is today - which isn't a very great incentive to mount the attack (given that the attack is only a DoS).

neps/nep-0611.md

…thout contract.

See near/NEPs#611 This PR adds the GasKey trie key. In subsequent PRs we will introduce a new transaction type to accept gas key transactions, and to implement the gas key actions.

gagdiez · 2025-07-16T13:10:17Z

Hi @robin-near (or anyone who is interested in championing this NEP forward) – we are cleaning the NEP backlog and noticed that this PR still has some incomplete sections: particularly, it has a "TODO: Other things". Therefore, we are labeling this PR as "Needs author revision."

Please ping the @near/nep-moderators once you are ready for us to review it. We typically close NEPs that are inactive for more than two months, so please let us know if you need more time.

garikbesson · 2025-09-22T11:29:18Z

Because there has been no activity from the author for more than 3 months, I'm marking the proposal as RETRACTED. Please feel free to open it again if you'd like to continue working on it.

jakmeier · 2026-01-14T14:03:42Z

As an SME, I have reviewed the proposal. Kudos to the team behind it, it is well designed thought through. Special thanks to @darioush for finalizing the NEP and being very responsive to any questions and suggestions I had.

Technical summary

The NEP builds the basis for a new concept, the pending transaction queue (PTQ). This queue is for transactions that are included for execution but have not been applied to the latest known blockchain state, yet.

The PTQ allows decoupling consensus on new chunks from transaction execution. Transactions to be included in a new chunk are verified against the state of an older block height, plus all pending transactions.

The challenge with this approach is that a transaction may look valid when it enters the PTQ but is no longer valid once it gets executed. This is especially problematic if the signer no longer has the balance to pay for the gas cost it owes for handling the transaction, or if the signing key got removed and it is no longer known whether it was a valid signature in the first place.

To address these concerns, a new type of access key is introduced, called gas key. Gas keys have a balance reserved for gas that cannot be removed without it being visible in the PTQ. Therefore, it is possible to verify ahead of time that a transactions signed with a gas key will have the balance to cover the gas cost once it executes.

For transactions signed by normal access keys, such a verification is not possible. Each account will be limited to a small number (4) of transactions per account in the PTQ to reduce the number of transactions that may go through the PTQ without being charged in the end.

Recommendation

I recommend accepting this proposal to move SPICE development forward.

See benefits and concerns below for the arguments in both directions.

Benefits

Enables decoupling of consensus from execution

Concerns

#	Concern	Resolution	Status
1	Existing signing workflows may be broken.	This would only become a problem later when SPICE is implemented. For now the PTQ is always empty. Even then, probably only a few users would be affected and they can easily migrate to gas keys.	Has a good solution with plenty of time.
2	NONCE handling may not be what developers want.	?	Still open. See #522 for what some developers wanted.
3	Normal access keys can still be used to submit transactions that fail and can't be charged.	By limiting the number of such transactions per account, such an attack would require creating many accounts. This itself is a cost, making the attack no longer free.	Addressed in the proposal.
4	This change is almost exclusively to enable SPICE, which itself is not fully designed, yet. Moving ahead with this implementation now has little benefit on its own. There is a risk we add features and change APIs that we need to revert later.	?	Still open.

neps/nep-0611.md

Co-authored-by: Matej Pavlovic <[email protected]>

matejpavlovic · 2026-01-14T17:09:13Z

neps/nep-0611.md

+
+`DeleteAccount` action will fail if the account has any associated gas keys.
+
+`DeleteKey` is not allowed to delete gas keys.


Would it make sense to not introduce a separate DeleteGasKey action and instead modify the DeleteKey action and define it as follows?

"If the key is an access key, <whatever the current definition of DeleteKey is>. If the key is a gas key, "

I imagine the separate action for deleting gas keys might be an artifact from the times where we considered gas keys and access keys to have different name spaces. Now that gas keys share the namespace with access keys, the two separate actions don't seem necessary. Moreover, I'd personally argue that a single DeleteKey is much more intuitive from a UX perspective.

Realizing that another difference between these two actions is nonce deletion, I see that the proposed simplification might not work. I guess this UX hiccup is something we'll have to live with.

~~The other (main) reason to keep it separate is that contracts can currently request DeleteKey via the promise_batch_action_delete_key host call.~~
^ This was not correct.

Actually, we can go with this approach based on this feedback and feedback from others.
The downside is we cannot charge gas for deletion accurately, but this seems not a practical issue.
We can use compute costs to prevent too much work in one chunk, and we could collect the gas ahead of time during addition if we really care about it.

As the design of the gas keys has diverged from the original, I think a revert can set a good baseline to review the new code carefully instead of trying to make a "migration" from the implementation to the new one (#14788) The up to date design can be found here: near/NEPs#611

…4891) Updates add/delete key actions to handle gas keys per near/NEPs#611 Note this also moves the code for add/delete keys to a new `access_keys` module. Additional changes: - Added a new `QueryRequest::ViewGasKeyNonces` variant and its handling in `NightshadeRuntime`, allowing clients to query the nonces associated with gas keys for a given `account_id` and `public_key`. The response is provided as a new `QueryResponseKind::GasKeyNonces` variant. - Implemented the `view_gas_key_nonces` method in the runtime adapter, which retrieves gas key nonces from the state trie. - Introduced new error variants for gas key operations in `ActionsValidationError`: `GasKeyTooManyNoncesRequested`, `AddGasKeyWithNonZeroBalance`, and `GasKeyFunctionCallAllowanceNotAllowed` - Removed the obsolete `KeyPermissionInvalid` error variant from both `ActionsValidationError` and `ActionErrorKind`, a

matejpavlovic

Nice!

All the comments I added are just nit picking.

neps/nep-0611.md

matejpavlovic · 2026-01-27T09:09:50Z

neps/nep-0611.md

+* Check that if the permission is a `FunctionCallPermission`, the allowance is `None` (unlimited
+  allowance).


Is this the case for access keys as well? If yes, I guess we require this for consistency - all good. If not, is there a specific reason we don't allow limiting the allowance for keys with FunctionCallPermission?

Ordinary access keys can use the allowances.

One reason is to avoid having to track them in the pending transaction queue (similar to balances).
I don't see a fundamental reason, so I guess we could add it later on if it was a request or requirement.

Do you mean that we'd need to track the allowance changes? Would the problematic case be wrongly accepting a transaction that exceeds the allowance because the allowance has only recently been decreased by some transaction in the pending queue? If that's the idea, then it makes sense to me - feel free to resolve this comment.

neps/nep-0611.md

matejpavlovic · 2026-01-27T10:42:48Z

neps/nep-0611.md

+To compute the pending transaction queues (one for each tracked shard) for a new block,
+
+* Start from the queue from the previous block;
+* Subtract the transactions that are included in each newly certified block;


The reader needs to know how SPICE works to understand this. Maybe we should mention that and repeat the remark that if this NEP is implemented on the current system, the pending transaction queue will always be empty anyway.

Co-authored-by: Matej Pavlovic <[email protected]>

gagdiez · 2026-01-29T08:52:34Z

Hi everyone! seems like SME @jakmeier and @matejpavlovic have completed their technical reviews. Based on their comments above, it seems like this proposal is ready for the working group members for review.

@near/wg-protocol – Can you please fully read this NEP and comment in the thread if you are leaning towards approving or rejecting it? Please make sure to include your rationale and any feedback that you have for the author.

Once we get 2/3 voting indications, we can start scheduling a public call for the author to present the NEP and for the working group members to formalize the voting.

cc @walnut-the-cat

birchmd

As a protocol working group member, I lean towards approving this proposal.

I have left some minor comments, but overall I think this proposal is well-motivated and technically sound. Rolling out SPICE-related changes as small, self-contained and backwards-compatible pieces will ease the transition for all participants in the Near ecosystem.

birchmd · 2026-01-29T15:21:43Z

neps/nep-0611.md

+
+#### Modifications to existing actions
+
+`AddKey` action will fail if the public key is already registered as a gas key (unless adding a gas key with that public key).


Is the statement in paratheses here meant to imply that the action to add a gas key is idempotent? I think it makes sense to fail a duplicate add transaction instead of having it silently do nothing.

The duplicate add transaction is intended to fail. The writing here is confusing, I updated the paragraph.

birchmd · 2026-01-29T15:26:30Z

neps/nep-0611.md

+* To apply this action, all relevant trie nodes are deleted,
+* Decreases storage usage of associated account,
+* The remaining balance left in the key is **burned**. This prevents an attack where an adversary floods the chain with transactions, then deletes the key to reclaim the balance before the transactions execute.
+  * For user's benefit we may consider failing this action if the balance exceeds a certain threshold. The implementation may include a `force` flag that overrides this check.


I think having this threshold is a good idea and should be included officially in the NEP rather than being left as an ambiguous maybe.

Good call, we will discuss in the SPICE implementation group on Monday and update the NEP with a suitable value.

Please let me know if you have an opinion about the force flag as well.

We suggested 1 NEAR as this threshold.

Additionally the force option is a leftover from a previous revision where we introduced separate actions to delete gas keys. To keep the same action, we can't add such option, so I removed its mention here.

birchmd · 2026-01-29T15:58:26Z

neps/nep-0611.md

+```rust
+enum TransactionNonce {
+    Nonce { nonce: Nonce },
+    GasKeyNonce { nonce: Nonce, nonce_index: u32 }


Nit: if we the limit on parallel nonces will be 1024 then we could use u16 here for the nonce index instead of u32 just to save a few bytes of space in the serialized form.

Good point, with u16 we can still increase the max to ~65k nonces.
I will also discuss this on Monday with the implementation group.

Changed to u16.

birchmd · 2026-01-29T16:03:44Z

neps/nep-0611.md

+
+Transaction processing is extended with a new failure case: `InvalidTxError::NotEnoughBalanceForDeposit`. In case the account programmatically sends away its balance we need to be able to charge the user a fee, otherwise we will have the spam issue this NEP intends to prevent. With honest chunk producers, this case only happens when using a gas key. 
+
+*Note*: As of the current date, `nearcore` ignores failed transactions in processing. After `ProtocolFeature::InvalidTxGenerateOutcomes`, invalid transactions impact the outcome but not the state. Therefore, this NEP also introduces the change that failed transactions may update the state (to charge for gas).


Do I understand correctly that this statement means the gas key balance will be reduced even in the case of a failed transfer due to insufficient balance? I think that does make sense for DoS prevention, I am just double checking because it's not fully clear to me in the text as written.

Yes, that's correct. In this scenario, the gas key balance is reduced to charge for gas even though the transaction fails.

I'll clarify this in the text.

birchmd · 2026-01-29T16:07:39Z

neps/nep-0611.md

+This constraint should be good enough to cover cases of adding, funding, removing, or withdrawing from gas
+keys as well. For adding and funding, we do need the execution to catch up before the newly available
+balance can be used for pending transactions, which is suboptimal but correct. 
+Note that contract execution cannot create receipts that withdraw from gas keys; only gas key


This is because we are intentionally not updating the promise-creating host functions in the VM to include the new action? I'm not sure where it is appropriate to do so, but it would be good to document that these actions are intentionally excludes as opposed to missed by an oversight so that it is not accidentally added in the future.

That's correct. Updating to capture this comment.

Draft NEP for pending transaction queue.

31d207a

github-project-automation bot added this to NEPs May 30, 2025

github-project-automation bot moved this to NEW in NEPs May 30, 2025

trechriron deployed to robin/611 - nomicon PR #611 May 30, 2025 23:36 — with Render View deployment

thisisjoshford added this to DevRel May 30, 2025

github-project-automation bot moved this to NEW❗ in DevRel May 30, 2025

birchmd reviewed Jun 2, 2025

View reviewed changes

Revise the NEP so that access keys are not restricted for accounts wi…

4abd9a3

…thout contract.

trechriron deployed to robin/611 - nomicon PR #611 June 6, 2025 21:01 — with Render View deployment

robin-near mentioned this pull request Jun 9, 2025

Introduce GasKey to the trie. near/nearcore#13687

Merged

Merge branch 'master' into robin/611

2d8c2db

trechriron temporarily deployed to robin/611 - nomicon PR #611 July 16, 2025 13:06 — with Render Destroyed

gagdiez added S-draft/needs-author-revision A NEP in the DRAFT stage that needs an author revision. WG-protocol Protocol Standards Work Group should be accountable labels Jul 16, 2025

gagdiez moved this from NEW to DRAFT in NEPs Jul 16, 2025

garikbesson closed this Sep 22, 2025

github-project-automation bot moved this from NEW❗ to Shipped 🚀 in DevRel Sep 22, 2025

garikbesson added the S-retracted A NEP that was retracted by the author or had no activity for over two months. label Sep 22, 2025

garikbesson moved this from DRAFT to RETRACTED in NEPs Sep 22, 2025

This was referenced Oct 27, 2025

spice: Implement pending transaction queue near/nearcore#13586

Open

spice: Pending transaction queue NEP near/nearcore#14499

Open

spice: Implement gas keys near/nearcore#14500

Open

revision and completing incomplete sections

1139911

darioush reopened this Nov 21, 2025

github-project-automation bot moved this from Shipped 🚀 to NEW❗ in DevRel Nov 21, 2025

md lint

99f068c

darioush added 8 commits January 13, 2026 16:34

update framing as access keys

4ee1736

describe RPC modifications

55360f7

update existing actions section

2c9b6d2

remove non-relevant section about transfer in alternatives

787e6d3

clarify deleting keys problem

83ed9d2

extra transfer costs

251f31d

rewording

7eb55b4

metadata

3eddaa4

walnut-the-cat removed the S-draft/needs-author-revision A NEP in the DRAFT stage that needs an author revision. label Jan 14, 2026

matejpavlovic reviewed Jan 14, 2026

View reviewed changes

neps/nep-0611.md Outdated Show resolved Hide resolved

Update neps/nep-0611.md

ec8c3b5

Co-authored-by: Matej Pavlovic <[email protected]>

matejpavlovic reviewed Jan 14, 2026

View reviewed changes

darioush added 2 commits January 16, 2026 09:00

update NEP for merged actions

9fe5ecd

Merge branch 'robin/611' of github.com:near/NEPs into robin/611

3df5adc

darioush mentioned this pull request Jan 16, 2026

chore(gas-keys): revert changes for updated design near/nearcore#14851

Merged

darioush mentioned this pull request Jan 17, 2026

feat(gas-keys): 3/n Add gas keys as part of Add/DeleteKey actions near/nearcore#14891

Merged

gessellericauerta145-star approved these changes Jan 22, 2026

View reviewed changes

rename TransferFromGasKey -> WithdrawFromGasKey

8b6d8bb

matejpavlovic approved these changes Jan 27, 2026

View reviewed changes

darioush and others added 2 commits January 27, 2026 05:32

Apply suggestions from code review

1b2ad0b

Co-authored-by: Matej Pavlovic <[email protected]>

clarify pending transaction queue is empty without SPICE

20f8b8e

birchmd reviewed Jan 29, 2026

View reviewed changes

darioush added 3 commits January 30, 2026 08:53

reviewer feedback

ea061c6

clarify action fail threshold

e9c8296

make nonce_index u16

279d8c8


		`DeleteAccount` action will fail if the account has any associated gas keys.

		`DeleteKey` is not allowed to delete gas keys.

		* Check that if the permission is a `FunctionCallPermission`, the allowance is `None` (unlimited
		allowance).


		#### Modifications to existing actions

		`AddKey` action will fail if the public key is already registered as a gas key (unless adding a gas key with that public key).


		Transaction processing is extended with a new failure case: `InvalidTxError::NotEnoughBalanceForDeposit`. In case the account programmatically sends away its balance we need to be able to charge the user a fee, otherwise we will have the spam issue this NEP intends to prevent. With honest chunk producers, this case only happens when using a gas key.

		Note: As of the current date, `nearcore` ignores failed transactions in processing. After `ProtocolFeature::InvalidTxGenerateOutcomes`, invalid transactions impact the outcome but not the state. Therefore, this NEP also introduces the change that failed transactions may update the state (to charge for gas).

Draft NEP for pending transaction queue. #611

Are you sure you want to change the base?

Draft NEP for pending transaction queue. #611

Conversation

robin-near commented May 30, 2025 • edited by gagdiez Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

birchmd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gagdiez commented Jul 16, 2025

Uh oh!

garikbesson commented Sep 22, 2025

Uh oh!

jakmeier commented Jan 14, 2026

Technical summary

Recommendation

Benefits

Concerns

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matejpavlovic Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

darioush Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matejpavlovic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gagdiez commented Jan 29, 2026

Uh oh!

birchmd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

robin-near commented May 30, 2025 •

edited by gagdiez

Loading

matejpavlovic Jan 14, 2026 •

edited

Loading

darioush Jan 14, 2026 •

edited

Loading