docs(utxo/aerospike): document the create-first transaction flow - #1679
Open
ordishs wants to merge 1 commit into
Open
docs(utxo/aerospike): document the create-first transaction flow#1679ordishs wants to merge 1 commit into
ordishs wants to merge 1 commit into
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Comment on lines
+116
to
+119
| 2. **Pruner Sweep**: | ||
| - The pruner identifies stale 'creating' transactions | ||
| - Instead of deleting them, the pruner rolls them forward through processing | ||
| - This prevents accumulation of incomplete transaction states |
Contributor
There was a problem hiding this comment.
[Major] Documentation appears correct but misleads — implementation differs.
This "Pruner Sweep" recovery path does not exist in the code. The pruner never inspects the creating flag:
stores/utxo/aerospike/pruner/pruner_service.goandpruner/prune_policies.gocontain zero references tocreating/Creating. The pruner selects records bydelete_at_height <= blockHeightand deletes them; it has no logic to detect stalecreatingrecords or "roll them forward."
The actual auto-recovery of stale creating records happens in subtree validation, not the pruner:
services/subtreevalidation/processTxMetaUsingStore.go:152-162— when a decorated tx hasCreating == true, it is treated as missing to trigger re-processing.services/subtreevalidation/processTxMetaUsingStore.go:224-225— the GetMeta path does the same (if !txMeta.Creatingbefore using the meta).
Suggest replacing this bullet with the subtree-validation re-processing path (or the create-side clearCreatingFlag retry at create.go:1228-1236), which is what the code actually does.
Comment on lines
+111
to
+114
| 1. **Validator Roll-Forward** (on ErrTxExists + Creating): | ||
| - When a transaction is detected in creating state during validation | ||
| - Validator performs roll-forward to complete the transaction | ||
| - This handles cases where the initial creation was interrupted |
Contributor
There was a problem hiding this comment.
[Minor] The attribution and trigger here are imprecise.
-
Trigger: the heading says "on ErrTxExists + Creating," but the two real triggers are different errors from different layers. The validator retry loop fires on
ErrTxCreating(parent still being written), notErrTxExists— seeservices/validator/Validator.go:498-525, which retriesvalidateInternalwith exponential backoff.ErrTxExistsis a create-side outcome (create.go:1232), unrelated to this retry. -
"Validator performs roll-forward to complete the transaction" overstates what the validator does: it simply retries the child with backoff and gives up after
maxRetries(Validator.go:520-524). It does not complete/roll forward the parent. The genuine roll-forward (re-processing the incomplete tx) lives in subtree validation, as noted in the comment on the Pruner Sweep bullet.
Consider reframing as: "Validator retry — on ErrTxCreating, the validator retries validation with backoff while the parent finishes; subtree validation re-processes txs still flagged creating."
Contributor
|
🤖 Claude Code Review Status: Complete Current Review: Docs-only PR adding a "Create-First Transaction Flow" section to the Aerospike UTXO store README. The Two accuracy issues remain in the Recovery Paths section (both flagged inline, still unresolved — the code confirms them):
Both build false confidence (docs read correctly but describe different logic), so they're worth addressing before merge. Everything else is accurate. |
Contributor
Benchmark Comparison ReportBaseline: Current: Summary
All benchmark results (sec/op)
Threshold: >10% with p < 0.05 | Generated: 2026-09-07 08:19 UTC |
Describe the create-first ordering that the Aerospike UTXO store now uses: the tentative 'creating' state, the three recovery paths (validator roll-forward on ErrTxExists, the pruner sweep that rolls forward instead of deleting, and setMined), and why the ordering prevents orphaned spends. Also add the creating bin to the record field list. The bin is set to true during creation and removed on finalisation, since absence means the transaction is not creating.
ordishs
force-pushed
the
docs/aerospike-utxo-create-first
branch
from
September 7, 2026 08:04
0156f4f to
99e5d7d
Compare
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the create-first ordering in the Aerospike UTXO store README. The behaviour landed in
8bba344cb(PR 1518); the README did not describe it.What changed
stores/utxo/aerospike/README.mdonly. No code changes.ErrTxExists+ creating, the pruner sweep that rolls stale records forward instead of deleting them, andsetMined), and why the ordering prevents orphaned spends.creatingbin to the normal-transaction field list.Accuracy notes
The
creatingbin description matchesteranode.lua:teranode.lua:23—local BIN_CREATING = "creating"teranode.lua:297— the spend guard tests== trueexplicitly, because nil or absent means not creatingteranode.lua:653-654—setMinedsets the bin tonil, deleting it, rather than setting it to falseThe doc therefore says the bin is deleted on commit, not set to
false.Testing
Documentation only, no build or runtime impact.